From 3885f499c5c7142c60c0d21eb898c061a0afa649 Mon Sep 17 00:00:00 2001
From: kite <lizhengfeng.lzf@alibaba-inc.com>
Date: Sun, 7 Jun 2026 20:22:39 +0800
Subject: [PATCH] docs: add path filtering documentation to all README files

Document the include/exclude configuration in rule.json files, explaining
the filter decision priority, how layers interact, and listing built-in
default exclude patterns.
---
 README.ja-JP.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 README.md       | 42 ++++++++++++++++++++++++++++++++++++++++++
 README.zh-CN.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 126 insertions(+)

diff --git a/README.ja-JP.md b/README.ja-JP.md
index effa4e7..97bcd4b 100644
--- a/README.ja-JP.md
+++ b/README.ja-JP.md
@@ -327,6 +327,48 @@ OCRは4層の優先度チェーンを使ってレビュールールを解決し
 - 各層の中では、ルールは宣言順に評価されます — 最初にマッチしたものが採用されます。
 - ルールファイルが存在しない場合は、何も出力せずスキップされます。
 
+### パスフィルタリング
+
+ルールファイルでは `include` と `exclude` フィールドも使用でき、どのファイルをレビュー対象にするかを制御できます：
+
+```json
+{
+  "rules": [
+    {"path": "**/*.java", "rule": "null安全性をチェック"}
+  ],
+  "include": ["src/main/**/*.java", "lib/**/*.kt"],
+  "exclude": ["**/generated/**", "vendor/**"]
+}
+```
+
+**フィルタ判定の優先度（高い順）：**
+
+| ステップ | 条件 | 結果 |
+|------|-----------|--------|
+| 1 | ファイルがバイナリ | 除外 |
+| 2 | パスがユーザーの`exclude`パターンにマッチ | 除外 |
+| 3 | ファイル拡張子がサポートリストにない | 除外 |
+| 4 | `include`が設定されており、パスがマッチ | **レビュー対象**（ステップ5をスキップ） |
+| 5 | パスが組み込みデフォルト除外パターン（テストファイル等）にマッチ | 除外 |
+| 6 | 上記のいずれにも該当しない | レビュー対象 |
+
+**動作ロジック：**
+
+- `include`と`exclude`はレビュールールと同じ優先度チェーン（`--rule` > プロジェクト設定 > グローバル設定）に従います。**include/excludeが設定されている最も高い優先度の層**が一括で適用され、層を跨いだマージは行われません。
+- `exclude`は常に`include`より優先されます — 両方にマッチするファイルは除外されます。
+- `include`は**組み込みデフォルト除外パターンをバイパスする**ためのものであり（例：テストファイル）、排他的な許可リストではありません — `include`パターンにマッチしないファイルも通常通りデフォルトフィルタチェックに進みます。
+- パターン構文：`**`再帰マッチ、`*`単一セグメントマッチ、`{a,b}`ブレース展開をサポート。マッチングは大文字小文字を区別しません。
+
+**組み込みデフォルト除外パターン**（テストファイル等をフィルタ — `include`でオーバーライド可能）：
+
+```
+**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
+**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
+**/src/test/java/**/*.java, **/src/test/**/*.kt,
+**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
+**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
+```
+
 ## 設定リファレンス
 
 設定ファイル：`~/.opencodereview/config.json`
diff --git a/README.md b/README.md
index 913dcb0..5b8e416 100644
--- a/README.md
+++ b/README.md
@@ -327,6 +327,48 @@ Layers 1–3 share the same JSON format:
 - Within each layer, rules are evaluated in declaration order — the first match wins.
 - If a rule file does not exist, it is silently skipped.
 
+### Path Filtering
+
+Rule files also support `include` and `exclude` fields to control which files enter the review scope:
+
+```json
+{
+  "rules": [
+    {"path": "**/*.java", "rule": "Check for null safety"}
+  ],
+  "include": ["src/main/**/*.java", "lib/**/*.kt"],
+  "exclude": ["**/generated/**", "vendor/**"]
+}
+```
+
+**Filter decision priority (highest to lowest):**
+
+| Step | Condition | Result |
+|------|-----------|--------|
+| 1 | File is binary | Excluded |
+| 2 | Path matches user `exclude` pattern | Excluded |
+| 3 | File extension not in supported list | Excluded |
+| 4 | `include` is configured and path matches | **Reviewed** (skips step 5) |
+| 5 | Path matches built-in default exclude pattern (test files, etc.) | Excluded |
+| 6 | None of the above | Reviewed |
+
+**How it works:**
+
+- `include` and `exclude` follow the same priority chain as review rules (`--rule` > project config > global config). The **highest-priority layer that has include/exclude configured** takes effect as a whole — patterns are not merged across layers.
+- `exclude` always wins over `include` — a file matching both is excluded.
+- `include` acts as a **bypass for built-in default exclude patterns** (e.g., test files), not as an exclusive allowlist — files not matching any `include` pattern still proceed through the default filter checks normally.
+- Pattern syntax: supports `**` recursive matching, `*` single-segment matching, and `{a,b}` brace expansion. Matching is case-insensitive.
+
+**Built-in default exclude patterns** (filters test files, etc. — can be overridden with `include`):
+
+```
+**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
+**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
+**/src/test/java/**/*.java, **/src/test/**/*.kt,
+**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
+**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
+```
+
 ## Configuration Reference
 
 Config file: `~/.opencodereview/config.json`
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 324ee9a..c32957c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -317,6 +317,48 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
 - 在每一层内，规则按声明顺序评估 —— 首次匹配生效。
 - 如果规则文件不存在，将被静默跳过。
 
+### 路径过滤
+
+规则文件同时支持 `include` 和 `exclude` 字段，用于控制哪些文件进入审查范围：
+
+```json
+{
+  "rules": [
+    {"path": "**/*.java", "rule": "检查空值安全"}
+  ],
+  "include": ["src/main/**/*.java", "lib/**/*.kt"],
+  "exclude": ["**/generated/**", "vendor/**"]
+}
+```
+
+**过滤决策优先级（从高到低）：**
+
+| 步骤 | 条件 | 结果 |
+|------|------|------|
+| 1 | 文件为二进制文件 | 排除 |
+| 2 | 路径匹配用户 `exclude` 模式 | 排除 |
+| 3 | 文件扩展名不在支持列表中 | 排除 |
+| 4 | 配置了 `include` 且路径匹配 | **纳入审查**（跳过步骤 5） |
+| 5 | 路径匹配内置默认排除模式（测试文件等） | 排除 |
+| 6 | 以上均不满足 | 纳入审查 |
+
+**生效逻辑：**
+
+- `include` 和 `exclude` 遵循与评审规则相同的优先级链（`--rule` > 项目配置 > 全局配置），取**最高优先级中配置了 include/exclude 的那一层**整体生效，不会跨层合并。
+- `exclude` 始终优先于 `include` —— 同时匹配两者的文件会被排除。
+- `include` 的作用是**绕过内置默认排除模式**（如测试文件），而非限制审查范围 —— 未匹配 `include` 的文件仍会正常进入后续的默认过滤判断。
+- 模式语法：支持 `**` 递归匹配、`*` 单级匹配和 `{a,b}` 大括号展开，匹配时不区分大小写。
+
+**内置默认排除模式**（用于过滤测试文件等，可通过 `include` 覆盖）：
+
+```
+**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
+**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
+**/src/test/java/**/*.java, **/src/test/**/*.kt,
+**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
+**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
+```
+
 ## 配置参考
 
 配置文件：`~/.opencodereview/config.json`