filefilter 0.2.2__tar.gz → 0.2.4__tar.gz

{filefilter-0.2.2/src/filefilter.egg-info → filefilter-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filefilter
-Version: 0.2.2
+Version: 0.2.4
 Summary: Filter files in a directory tree based on configurable glob rules.
 Author-email: "Ioannis D (devcoons)" <support@devcoons.com>
 License-Expression: MIT
@@ -161,11 +161,10 @@ When scanning files, the library applies filters in this exact sequence:
    - If the file extension matches `exclude.extensions` → **excluded immediately**.  
    - This step is not overridden by include patterns.
 
-2️⃣ **Path excludes vs. includes (specificity wins)**  
+2️⃣ **Path excludes vs. override patterns (`include.odirs`, `include.ofiles`)**  
    - If the file path matches `exclude.files`, or its parent directory matches `exclude.dirs`, the file is a candidate for exclusion.  
-   - At the same time, the library checks all matching patterns in `include.dirs` and `include.files`.  
-   - Each pattern receives a **specificity score** (more literal segments = higher score; more wildcards = lower score).  
-   - If the **best matching include pattern is more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
+   - **`include.dirs` and `include.files` do not override excludes** — they only gate inclusion later.  
+   - If a matching pattern in `include.odirs` or `include.ofiles` is **more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
    - Otherwise → **excluded**.
 
    | Pattern | Relative specificity |
@@ -173,8 +172,11 @@ When scanning files, the library applies filters in this exact sequence:
    | `**` | very low (broad) |
    | `**/KLM/**` | higher |
    | `**/KLM/ABC/**` | highest |
+   | `**/test_*.py` vs `**/test_keep.py` | ofile wins (more specific) |
 
-   > Put both the broad include and the exception in the same `include.dirs` list — no separate override section is needed.
+   > Use `include.dirs` for normal scoping (e.g. `**`, `src/**`).  
+   > Use `include.odirs` for directory carve-outs under `exclude.dirs` / `exclude.files`.  
+   > Use `include.ofiles` for file carve-outs under `exclude.files` / `exclude.dirs`.
 
 3️⃣ **Include-file fast path**  
    - If the file matches any `include.files` pattern → **included immediately**,  
@@ -201,6 +203,8 @@ When scanning files, the library applies filters in this exact sequence:
   "filters": {
     "include": {
       "dirs": [],
+      "odirs": [],
+      "ofiles": [],
       "files": [],
       "extensions": []
     },
@@ -216,8 +220,10 @@ When scanning files, the library applies filters in this exact sequence:
 | Field | Description |
 |-------|--------------|
 | `root_dir` | Base directory (absolute or relative). |
-| `filters.include.dirs` | Directory inclusion patterns. Broader and narrower patterns can coexist; a more specific include dir beats a broader exclude dir (see decision order). |
-| `filters.include.files` | File inclusion patterns (glob-like). Also participates in specificity comparisons against excludes. |
+| `filters.include.dirs` | Directory inclusion patterns for gating (must match when any include filters are set). Never overrides excludes. |
+| `filters.include.odirs` | Optional. Override directory patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies dir gating. |
+| `filters.include.ofiles` | Optional. Override file patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies file gating (does not skip extension whitelist). |
+| `filters.include.files` | File inclusion patterns (glob-like). Forces inclusion (skips extension whitelist) once path excludes are resolved. Does not override excludes. |
 | `filters.include.extensions` | Extension whitelist. |
 | `filters.exclude.*` | Same structure, but acts as exclusion filters. |
 
@@ -435,14 +441,15 @@ When scanning files, the library applies filters in this exact sequence:
 ###  Example 7 — Exclude a subtree, except an explicit include path
 
 Exclude everything under `KLM`, but still collect files under `KLM/ABC`.  
-List the exception alongside the broad include in normal `include.dirs`:
+Use `include.dirs` for the broad scope and `include.odirs` for the exception:
 
 ```json
 {
   "root_dir": ".",
   "filters": {
     "include": {
-      "dirs": ["**", "**/KLM/ABC/**"],
+      "dirs": ["**"],
+      "odirs": ["**/KLM/ABC/**"],
       "files": [],
       "extensions": ["c"]
     },
@@ -458,20 +465,52 @@ List the exception alongside the broad include in normal `include.dirs`:
 | File Path | Result | Reason |
 |------------|---------|--------|
 | `src/foo.c` | ✅ | broad `**` include + `.c` extension |
-| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude beats broad `**` |
-| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` include beats `**/KLM/**` exclude |
-| `src/x/KLM/ABC/deep/keep.c` | ✅ | exception works at any depth |
+| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude; no matching `odirs` |
+| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` odir beats `**/KLM/**` exclude |
+| `src/x/KLM/ABC/deep/keep.c` | ✅ | odir exception works at any depth |
 | `src/KLM/ABC/keep.txt` | ❌ | wrong extension (still inside the allowed dir) |
 
-The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` by adding both `src/**` (or `**`) and `**/ABC/KLM/**` to `include.dirs`.
+The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` via `include.odirs: ["**/ABC/KLM/**"]` alongside `include.dirs: ["src/**"]`.
+
+---
+
+###  Example 8 — Exclude file patterns, except specific files
+
+Exclude all `test_*.py` files, but keep `test_keep.py`:
+
+```json
+{
+  "root_dir": ".",
+  "filters": {
+    "include": {
+      "dirs": ["**"],
+      "ofiles": ["**/test_keep.py"],
+      "files": [],
+      "extensions": ["py"]
+    },
+    "exclude": {
+      "dirs": [],
+      "files": ["**/test_*.py"],
+      "extensions": []
+    }
+  }
+}
+```
+
+| File Path | Result | Reason |
+|------------|---------|--------|
+| `src/app.py` | ✅ | broad include + `.py` extension |
+| `src/test_foo.py` | ❌ | `**/test_*.py` exclude; no matching `ofiles` |
+| `src/test_keep.py` | ✅ | `**/test_keep.py` ofile beats `**/test_*.py` exclude |
+| `nested/test_keep.py` | ✅ | ofile exception works at any depth |
 
 ---
 
 ## Summary of Behavior
 
 - `exclude.extensions` are always applied first (hard exclude).  
-- For path rules, **the most specific matching pattern wins** — a narrow `include.dirs` entry can beat a broader `exclude.dirs` entry in the same config.  
-- Broad includes such as `**` do **not** cancel excludes; only a **more specific** include does.  
+- `include.dirs` and `include.files` **never** override path excludes — they only gate inclusion.  
+- Only `include.odirs` and `include.ofiles` can override a matching exclude, and only when the override pattern is **more specific**.  
 - A matching `include.files` pattern forces inclusion (skips extension whitelist), once path excludes are resolved.  
 - If any include filters exist, at least one must match (inclusion gating).  
 - Extensions act as a **final whitelist** when not bypassed by `include.files`.  

{filefilter-0.2.2 → filefilter-0.2.4}/README.md

@@ -128,11 +128,10 @@ When scanning files, the library applies filters in this exact sequence:
    - If the file extension matches `exclude.extensions` → **excluded immediately**.  
    - This step is not overridden by include patterns.
 
-2️⃣ **Path excludes vs. includes (specificity wins)**  
+2️⃣ **Path excludes vs. override patterns (`include.odirs`, `include.ofiles`)**  
    - If the file path matches `exclude.files`, or its parent directory matches `exclude.dirs`, the file is a candidate for exclusion.  
-   - At the same time, the library checks all matching patterns in `include.dirs` and `include.files`.  
-   - Each pattern receives a **specificity score** (more literal segments = higher score; more wildcards = lower score).  
-   - If the **best matching include pattern is more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
+   - **`include.dirs` and `include.files` do not override excludes** — they only gate inclusion later.  
+   - If a matching pattern in `include.odirs` or `include.ofiles` is **more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
    - Otherwise → **excluded**.
 
    | Pattern | Relative specificity |
@@ -140,8 +139,11 @@ When scanning files, the library applies filters in this exact sequence:
    | `**` | very low (broad) |
    | `**/KLM/**` | higher |
    | `**/KLM/ABC/**` | highest |
+   | `**/test_*.py` vs `**/test_keep.py` | ofile wins (more specific) |
 
-   > Put both the broad include and the exception in the same `include.dirs` list — no separate override section is needed.
+   > Use `include.dirs` for normal scoping (e.g. `**`, `src/**`).  
+   > Use `include.odirs` for directory carve-outs under `exclude.dirs` / `exclude.files`.  
+   > Use `include.ofiles` for file carve-outs under `exclude.files` / `exclude.dirs`.
 
 3️⃣ **Include-file fast path**  
    - If the file matches any `include.files` pattern → **included immediately**,  
@@ -168,6 +170,8 @@ When scanning files, the library applies filters in this exact sequence:
   "filters": {
     "include": {
       "dirs": [],
+      "odirs": [],
+      "ofiles": [],
       "files": [],
       "extensions": []
     },
@@ -183,8 +187,10 @@ When scanning files, the library applies filters in this exact sequence:
 | Field | Description |
 |-------|--------------|
 | `root_dir` | Base directory (absolute or relative). |
-| `filters.include.dirs` | Directory inclusion patterns. Broader and narrower patterns can coexist; a more specific include dir beats a broader exclude dir (see decision order). |
-| `filters.include.files` | File inclusion patterns (glob-like). Also participates in specificity comparisons against excludes. |
+| `filters.include.dirs` | Directory inclusion patterns for gating (must match when any include filters are set). Never overrides excludes. |
+| `filters.include.odirs` | Optional. Override directory patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies dir gating. |
+| `filters.include.ofiles` | Optional. Override file patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies file gating (does not skip extension whitelist). |
+| `filters.include.files` | File inclusion patterns (glob-like). Forces inclusion (skips extension whitelist) once path excludes are resolved. Does not override excludes. |
 | `filters.include.extensions` | Extension whitelist. |
 | `filters.exclude.*` | Same structure, but acts as exclusion filters. |
 
@@ -402,14 +408,15 @@ When scanning files, the library applies filters in this exact sequence:
 ###  Example 7 — Exclude a subtree, except an explicit include path
 
 Exclude everything under `KLM`, but still collect files under `KLM/ABC`.  
-List the exception alongside the broad include in normal `include.dirs`:
+Use `include.dirs` for the broad scope and `include.odirs` for the exception:
 
 ```json
 {
   "root_dir": ".",
   "filters": {
     "include": {
-      "dirs": ["**", "**/KLM/ABC/**"],
+      "dirs": ["**"],
+      "odirs": ["**/KLM/ABC/**"],
       "files": [],
       "extensions": ["c"]
     },
@@ -425,20 +432,52 @@ List the exception alongside the broad include in normal `include.dirs`:
 | File Path | Result | Reason |
 |------------|---------|--------|
 | `src/foo.c` | ✅ | broad `**` include + `.c` extension |
-| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude beats broad `**` |
-| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` include beats `**/KLM/**` exclude |
-| `src/x/KLM/ABC/deep/keep.c` | ✅ | exception works at any depth |
+| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude; no matching `odirs` |
+| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` odir beats `**/KLM/**` exclude |
+| `src/x/KLM/ABC/deep/keep.c` | ✅ | odir exception works at any depth |
 | `src/KLM/ABC/keep.txt` | ❌ | wrong extension (still inside the allowed dir) |
 
-The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` by adding both `src/**` (or `**`) and `**/ABC/KLM/**` to `include.dirs`.
+The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` via `include.odirs: ["**/ABC/KLM/**"]` alongside `include.dirs: ["src/**"]`.
+
+---
+
+###  Example 8 — Exclude file patterns, except specific files
+
+Exclude all `test_*.py` files, but keep `test_keep.py`:
+
+```json
+{
+  "root_dir": ".",
+  "filters": {
+    "include": {
+      "dirs": ["**"],
+      "ofiles": ["**/test_keep.py"],
+      "files": [],
+      "extensions": ["py"]
+    },
+    "exclude": {
+      "dirs": [],
+      "files": ["**/test_*.py"],
+      "extensions": []
+    }
+  }
+}
+```
+
+| File Path | Result | Reason |
+|------------|---------|--------|
+| `src/app.py` | ✅ | broad include + `.py` extension |
+| `src/test_foo.py` | ❌ | `**/test_*.py` exclude; no matching `ofiles` |
+| `src/test_keep.py` | ✅ | `**/test_keep.py` ofile beats `**/test_*.py` exclude |
+| `nested/test_keep.py` | ✅ | ofile exception works at any depth |
 
 ---
 
 ## Summary of Behavior
 
 - `exclude.extensions` are always applied first (hard exclude).  
-- For path rules, **the most specific matching pattern wins** — a narrow `include.dirs` entry can beat a broader `exclude.dirs` entry in the same config.  
-- Broad includes such as `**` do **not** cancel excludes; only a **more specific** include does.  
+- `include.dirs` and `include.files` **never** override path excludes — they only gate inclusion.  
+- Only `include.odirs` and `include.ofiles` can override a matching exclude, and only when the override pattern is **more specific**.  
 - A matching `include.files` pattern forces inclusion (skips extension whitelist), once path excludes are resolved.  
 - If any include filters exist, at least one must match (inclusion gating).  
 - Extensions act as a **final whitelist** when not bypassed by `include.files`.  

{filefilter-0.2.2 → filefilter-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "filefilter"
-version = "0.2.2"
+version = "0.2.4"
 description = "Filter files in a directory tree based on configurable glob rules."
 readme = "README.md"
 authors = [{ name = "Ioannis D (devcoons)", email = "support@devcoons.com" }]

{filefilter-0.2.2 → filefilter-0.2.4}/src/filefilter/__init__.py

@@ -24,7 +24,7 @@
 #                                                                                       #
 #########################################################################################
 
-__version__ = '0.2.2'
+__version__ = '0.2.4'
 
 #########################################################################################
 # IMPORTS                                                                               #

{filefilter-0.2.2 → filefilter-0.2.4}/src/filefilter/collector.py

@@ -164,12 +164,13 @@ def should_include(full_path: str, cfg: Ruleset) -> bool:
         return False
 
     inc_dirs = _merge(cfg.inc_dirs_root, cfg.inc_dirs_one, cfg.inc_dirs_any)
-    inc_path_spec = best_matching_specificity(inc_dirs, match_dir, dir_rel)
-    if cfg.include_files:
-        inc_path_spec = max(
-            inc_path_spec,
-            best_matching_specificity(cfg.include_files, match_file, rel),
-        )
+    odirs = _merge(cfg.inc_odirs_root, cfg.inc_odirs_one, cfg.inc_odirs_any)
+    gate_dirs = _merge(inc_dirs, odirs)
+
+    odir_spec = best_matching_specificity(odirs, match_dir, dir_rel)
+    ofiles = cfg.include_ofiles or []
+    ofile_spec = best_matching_specificity(ofiles, match_file, rel)
+    override_spec = max(odir_spec, ofile_spec)
 
     exc_dirs = _merge(cfg.exc_dirs_root, cfg.exc_dirs_one, cfg.exc_dirs_any)
     exc_path_spec = -1
@@ -186,15 +187,16 @@ def should_include(full_path: str, cfg: Ruleset) -> bool:
             exc_path_spec,
             best_matching_specificity(exc_dirs, match_dir, dir_rel),
         )
-    if exclude_path_hit and inc_path_spec <= exc_path_spec:
+    if exclude_path_hit and override_spec <= exc_path_spec:
         return False
 
-    files_present = bool(cfg.include_files)
-    files_match = files_present and match_file(rel, cfg.include_files)
-    if files_match:
+    gate_files = _merge(cfg.include_files, ofiles)
+    if cfg.include_files and match_file(rel, cfg.include_files):
         return True
-    dirs_present = bool(inc_dirs)
-    dirs_match = dirs_present and match_dir(dir_rel, inc_dirs)
+    files_present = bool(gate_files)
+    files_match = files_present and match_file(rel, gate_files)
+    dirs_present = bool(gate_dirs)
+    dirs_match = dirs_present and match_dir(dir_rel, gate_dirs)
     if (files_present or dirs_present) and not (files_match or dirs_match):
         return False
     if cfg.inc_exts and not ext_matches(ext, cfg.inc_exts, name):

{filefilter-0.2.2 → filefilter-0.2.4}/src/filefilter/ruleset.py

@@ -54,9 +54,11 @@ class Ruleset:
         exc = data['filters']['exclude']
 
         self.inc_dirs_root, self.inc_dirs_one, self.inc_dirs_any = parse_dir_patterns(inc.get('dirs', []))
+        self.inc_odirs_root, self.inc_odirs_one, self.inc_odirs_any = parse_dir_patterns(inc.get('odirs', []))
         self.exc_dirs_root, self.exc_dirs_one, self.exc_dirs_any = parse_dir_patterns(exc.get('dirs', []))
 
         self.include_files = parse_file_patterns(inc.get('files', []))
+        self.include_ofiles = parse_file_patterns(inc.get('ofiles', []))
         self.exclude_files = parse_file_patterns(exc.get('files', []))
 
         self.inc_exts = parse_extensions(inc.get('extensions', []))

{filefilter-0.2.2 → filefilter-0.2.4/src/filefilter.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filefilter
-Version: 0.2.2
+Version: 0.2.4
 Summary: Filter files in a directory tree based on configurable glob rules.
 Author-email: "Ioannis D (devcoons)" <support@devcoons.com>
 License-Expression: MIT
@@ -161,11 +161,10 @@ When scanning files, the library applies filters in this exact sequence:
    - If the file extension matches `exclude.extensions` → **excluded immediately**.  
    - This step is not overridden by include patterns.
 
-2️⃣ **Path excludes vs. includes (specificity wins)**  
+2️⃣ **Path excludes vs. override patterns (`include.odirs`, `include.ofiles`)**  
    - If the file path matches `exclude.files`, or its parent directory matches `exclude.dirs`, the file is a candidate for exclusion.  
-   - At the same time, the library checks all matching patterns in `include.dirs` and `include.files`.  
-   - Each pattern receives a **specificity score** (more literal segments = higher score; more wildcards = lower score).  
-   - If the **best matching include pattern is more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
+   - **`include.dirs` and `include.files` do not override excludes** — they only gate inclusion later.  
+   - If a matching pattern in `include.odirs` or `include.ofiles` is **more specific** than the best matching exclude pattern → the exclude is **ignored** for this file.  
    - Otherwise → **excluded**.
 
    | Pattern | Relative specificity |
@@ -173,8 +172,11 @@ When scanning files, the library applies filters in this exact sequence:
    | `**` | very low (broad) |
    | `**/KLM/**` | higher |
    | `**/KLM/ABC/**` | highest |
+   | `**/test_*.py` vs `**/test_keep.py` | ofile wins (more specific) |
 
-   > Put both the broad include and the exception in the same `include.dirs` list — no separate override section is needed.
+   > Use `include.dirs` for normal scoping (e.g. `**`, `src/**`).  
+   > Use `include.odirs` for directory carve-outs under `exclude.dirs` / `exclude.files`.  
+   > Use `include.ofiles` for file carve-outs under `exclude.files` / `exclude.dirs`.
 
 3️⃣ **Include-file fast path**  
    - If the file matches any `include.files` pattern → **included immediately**,  
@@ -201,6 +203,8 @@ When scanning files, the library applies filters in this exact sequence:
   "filters": {
     "include": {
       "dirs": [],
+      "odirs": [],
+      "ofiles": [],
       "files": [],
       "extensions": []
     },
@@ -216,8 +220,10 @@ When scanning files, the library applies filters in this exact sequence:
 | Field | Description |
 |-------|--------------|
 | `root_dir` | Base directory (absolute or relative). |
-| `filters.include.dirs` | Directory inclusion patterns. Broader and narrower patterns can coexist; a more specific include dir beats a broader exclude dir (see decision order). |
-| `filters.include.files` | File inclusion patterns (glob-like). Also participates in specificity comparisons against excludes. |
+| `filters.include.dirs` | Directory inclusion patterns for gating (must match when any include filters are set). Never overrides excludes. |
+| `filters.include.odirs` | Optional. Override directory patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies dir gating. |
+| `filters.include.ofiles` | Optional. Override file patterns (defaults to `[]` when omitted). When more specific than a matching exclude, the exclude is ignored for that path. Also satisfies file gating (does not skip extension whitelist). |
+| `filters.include.files` | File inclusion patterns (glob-like). Forces inclusion (skips extension whitelist) once path excludes are resolved. Does not override excludes. |
 | `filters.include.extensions` | Extension whitelist. |
 | `filters.exclude.*` | Same structure, but acts as exclusion filters. |
 
@@ -435,14 +441,15 @@ When scanning files, the library applies filters in this exact sequence:
 ###  Example 7 — Exclude a subtree, except an explicit include path
 
 Exclude everything under `KLM`, but still collect files under `KLM/ABC`.  
-List the exception alongside the broad include in normal `include.dirs`:
+Use `include.dirs` for the broad scope and `include.odirs` for the exception:
 
 ```json
 {
   "root_dir": ".",
   "filters": {
     "include": {
-      "dirs": ["**", "**/KLM/ABC/**"],
+      "dirs": ["**"],
+      "odirs": ["**/KLM/ABC/**"],
       "files": [],
       "extensions": ["c"]
     },
@@ -458,20 +465,52 @@ List the exception alongside the broad include in normal `include.dirs`:
 | File Path | Result | Reason |
 |------------|---------|--------|
 | `src/foo.c` | ✅ | broad `**` include + `.c` extension |
-| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude beats broad `**` |
-| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` include beats `**/KLM/**` exclude |
-| `src/x/KLM/ABC/deep/keep.c` | ✅ | exception works at any depth |
+| `src/KLM/skip.c` | ❌ | `**/KLM/**` exclude; no matching `odirs` |
+| `src/KLM/ABC/keep.c` | ✅ | `**/KLM/ABC/**` odir beats `**/KLM/**` exclude |
+| `src/x/KLM/ABC/deep/keep.c` | ✅ | odir exception works at any depth |
 | `src/KLM/ABC/keep.txt` | ❌ | wrong extension (still inside the allowed dir) |
 
-The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` by adding both `src/**` (or `**`) and `**/ABC/KLM/**` to `include.dirs`.
+The same technique applies to other “exclude a path part, except one branch” cases — for example, exclude `**/ABC/**` but keep `**/ABC/KLM/**` via `include.odirs: ["**/ABC/KLM/**"]` alongside `include.dirs: ["src/**"]`.
+
+---
+
+###  Example 8 — Exclude file patterns, except specific files
+
+Exclude all `test_*.py` files, but keep `test_keep.py`:
+
+```json
+{
+  "root_dir": ".",
+  "filters": {
+    "include": {
+      "dirs": ["**"],
+      "ofiles": ["**/test_keep.py"],
+      "files": [],
+      "extensions": ["py"]
+    },
+    "exclude": {
+      "dirs": [],
+      "files": ["**/test_*.py"],
+      "extensions": []
+    }
+  }
+}
+```
+
+| File Path | Result | Reason |
+|------------|---------|--------|
+| `src/app.py` | ✅ | broad include + `.py` extension |
+| `src/test_foo.py` | ❌ | `**/test_*.py` exclude; no matching `ofiles` |
+| `src/test_keep.py` | ✅ | `**/test_keep.py` ofile beats `**/test_*.py` exclude |
+| `nested/test_keep.py` | ✅ | ofile exception works at any depth |
 
 ---
 
 ## Summary of Behavior
 
 - `exclude.extensions` are always applied first (hard exclude).  
-- For path rules, **the most specific matching pattern wins** — a narrow `include.dirs` entry can beat a broader `exclude.dirs` entry in the same config.  
-- Broad includes such as `**` do **not** cancel excludes; only a **more specific** include does.  
+- `include.dirs` and `include.files` **never** override path excludes — they only gate inclusion.  
+- Only `include.odirs` and `include.ofiles` can override a matching exclude, and only when the override pattern is **more specific**.  
 - A matching `include.files` pattern forces inclusion (skips extension whitelist), once path excludes are resolved.  
 - If any include filters exist, at least one must match (inclusion gating).  
 - Extensions act as a **final whitelist** when not bypassed by `include.files`.  

{filefilter-0.2.2 → filefilter-0.2.4}/tests/test_comprehensive.py

@@ -262,7 +262,8 @@ def test_regression_file_matching(path: str, patterns: list[str], expected: bool
 
 SPECIFICITY_SCENARIOS = [
     pytest.param(
-        ["**", "**/KLM/ABC/**"],
+        ["**"],
+        ["**/KLM/ABC/**"],
         ["**/KLM/**"],
         {
             "src/foo.py": True,
@@ -273,7 +274,8 @@ SPECIFICITY_SCENARIOS = [
         id="klm-abc-exception",
     ),
     pytest.param(
-        ["src/**", "**/ABC/KLM/**"],
+        ["src/**"],
+        ["**/ABC/KLM/**"],
         ["**/ABC/**"],
         {
             "src/foo.py": True,
@@ -286,6 +288,7 @@ SPECIFICITY_SCENARIOS = [
     ),
     pytest.param(
         ["**"],
+        [],
         ["**/__pycache__/**"],
         {
             "src/app.py": True,
@@ -294,7 +297,8 @@ SPECIFICITY_SCENARIOS = [
         id="pycache-broad-exclude-wins",
     ),
     pytest.param(
-        ["**", "**/keep/**"],
+        ["**"],
+        [],
         ["**/skip/**"],
         {
             "skip/only.py": False,
@@ -306,10 +310,11 @@ SPECIFICITY_SCENARIOS = [
 ]
 
 
-@pytest.mark.parametrize("inc_dirs,exc_dirs,files", SPECIFICITY_SCENARIOS)
+@pytest.mark.parametrize("inc_dirs,inc_odirs,exc_dirs,files", SPECIFICITY_SCENARIOS)
 def test_specificity_integration(
     tmp_path: Path,
     inc_dirs: list[str],
+    inc_odirs: list[str],
     exc_dirs: list[str],
     files: dict[str, bool],
 ):
@@ -317,6 +322,7 @@ def test_specificity_integration(
         touch(tmp_path / rel)
     cfg = make_config(
         include_dirs=inc_dirs,
+        include_odirs=inc_odirs,
         include_extensions=["py"],
         exclude_dirs=exc_dirs,
     )

{filefilter-0.2.2 → filefilter-0.2.4}/tests/test_inclusion_logic.py

@@ -179,8 +179,8 @@ def test_dotfile_file_pattern_not_extension_filter(tree: Path):
     assert str(tree / "main.py") not in paths
 
 
-def test_specific_include_dir_beats_broader_exclude(tmp_path: Path):
-    """More specific include.dirs in the same list override broader exclude.dirs."""
+def test_specific_odir_beats_broader_exclude(tmp_path: Path):
+    """Only include.odirs override excludes; include.dirs do not."""
     touch(tmp_path / "src" / "foo.c")
     touch(tmp_path / "src" / "KLM" / "skip.c")
     touch(tmp_path / "src" / "KLM" / "ABC" / "keep.c")
@@ -188,7 +188,8 @@ def test_specific_include_dir_beats_broader_exclude(tmp_path: Path):
     touch(tmp_path / "src" / "x" / "KLM" / "ABC" / "keep.c")
 
     cfg = make_config(
-        include_dirs=["**", "**/KLM/ABC/**"],
+        include_dirs=["**"],
+        include_odirs=["**/KLM/ABC/**"],
         include_extensions=["c"],
         exclude_dirs=["**/KLM/**"],
     )
@@ -201,6 +202,17 @@ def test_specific_include_dir_beats_broader_exclude(tmp_path: Path):
     assert str(tmp_path / "src" / "x" / "KLM" / "ABC" / "keep.c") in paths
 
 
+def test_include_dirs_do_not_override_exclude(tmp_path: Path):
+    touch(tmp_path / "src" / "KLM" / "ABC" / "keep.c")
+    cfg = make_config(
+        include_dirs=["**", "**/KLM/ABC/**"],
+        include_extensions=["c"],
+        exclude_dirs=["**/KLM/**"],
+    )
+    paths = select_paths(tmp_path, cfg)
+    assert str(tmp_path / "src" / "KLM" / "ABC" / "keep.c") not in paths
+
+
 def test_broad_include_dir_does_not_beat_specific_exclude(tree: Path):
     cfg = make_config(
         include_dirs=["**"],
@@ -213,8 +225,8 @@ def test_broad_include_dir_does_not_beat_specific_exclude(tree: Path):
     assert str(tree / "src" / "__pycache__" / "cached.py") not in paths
 
 
-def test_abc_klm_exception_via_include_dirs_only(tmp_path: Path):
-    """Earlier ABC/KLM scenario using only include.dirs + exclude.dirs."""
+def test_abc_klm_exception_via_include_odirs(tmp_path: Path):
+    """ABC/KLM carve-out uses include.odirs, not include.dirs."""
     touch(tmp_path / "src" / "foo.c")
     touch(tmp_path / "src" / "ABC" / "only.c")
     touch(tmp_path / "src" / "ABC" / "other" / "skip.c")
@@ -224,7 +236,8 @@ def test_abc_klm_exception_via_include_dirs_only(tmp_path: Path):
     touch(tmp_path / "src" / "x" / "ABC" / "KLM" / "keep.c")
 
     cfg = make_config(
-        include_dirs=["src/**", "**/ABC/KLM/**"],
+        include_dirs=["src/**"],
+        include_odirs=["**/ABC/KLM/**"],
         include_extensions=["c"],
         exclude_dirs=["**/ABC/**"],
     )
@@ -237,3 +250,65 @@ def test_abc_klm_exception_via_include_dirs_only(tmp_path: Path):
     assert str(tmp_path / "src" / "ABC" / "KLM" / "nested" / "keep.c") in paths
     assert str(tmp_path / "src" / "x" / "ABC" / "other" / "skip.c") not in paths
     assert str(tmp_path / "src" / "x" / "ABC" / "KLM" / "keep.c") in paths
+
+
+def test_specific_ofile_beats_broader_exclude_file(tmp_path: Path):
+    """Only include.ofiles override excludes; include.files do not."""
+    touch(tmp_path / "src" / "app.py")
+    touch(tmp_path / "src" / "test_foo.py")
+    touch(tmp_path / "src" / "test_keep.py")
+    touch(tmp_path / "src" / "nested" / "test_keep.py")
+
+    cfg = make_config(
+        include_dirs=["**"],
+        include_ofiles=["**/test_keep.py"],
+        include_extensions=["py"],
+        exclude_files=["**/test_*.py"],
+    )
+    paths = select_paths(tmp_path, cfg)
+
+    assert str(tmp_path / "src" / "app.py") in paths
+    assert str(tmp_path / "src" / "test_foo.py") not in paths
+    assert str(tmp_path / "src" / "test_keep.py") in paths
+    assert str(tmp_path / "src" / "nested" / "test_keep.py") in paths
+
+
+def test_include_files_do_not_override_exclude_file(tmp_path: Path):
+    touch(tmp_path / "src" / "test_keep.py")
+    cfg = make_config(
+        include_dirs=["**"],
+        include_files=["**/test_keep.py", "**/test_*.py"],
+        include_extensions=["py"],
+        exclude_files=["**/test_*.py"],
+    )
+    paths = select_paths(tmp_path, cfg)
+    assert str(tmp_path / "src" / "test_keep.py") not in paths
+
+
+def test_ofile_overrides_exclude_dir_for_single_file(tmp_path: Path):
+    touch(tmp_path / "build" / "app.py")
+    touch(tmp_path / "build" / "keep.py")
+    cfg = make_config(
+        include_dirs=["**"],
+        include_ofiles=["**/build/keep.py"],
+        include_extensions=["py"],
+        exclude_dirs=["**/build/**"],
+    )
+    paths = select_paths(tmp_path, cfg)
+    assert str(tmp_path / "build" / "app.py") not in paths
+    assert str(tmp_path / "build" / "keep.py") in paths
+
+
+def test_ofile_satisfies_file_gating_without_fast_path(tmp_path: Path):
+    """ofiles satisfy gating but do not skip extension whitelist."""
+    touch(tmp_path / "src" / "keep.txt")
+    touch(tmp_path / "src" / "skip.txt")
+    cfg = make_config(
+        include_files=["**/only.py"],
+        include_ofiles=["**/keep.txt"],
+        include_extensions=["py"],
+        exclude_files=["**/*.txt"],
+    )
+    paths = select_paths(tmp_path, cfg)
+    assert str(tmp_path / "src" / "keep.txt") not in paths
+    assert str(tmp_path / "src" / "skip.txt") not in paths

{filefilter-0.2.2 → filefilter-0.2.4}/tests/test_readme_verification.py

@@ -123,7 +123,12 @@ README_EXAMPLES = [
         {
             "root_dir": ".",
             "filters": {
-                "include": {"dirs": ["**", "**/KLM/ABC/**"], "files": [], "extensions": ["c"]},
+                "include": {
+                    "dirs": ["**"],
+                    "odirs": ["**/KLM/ABC/**"],
+                    "files": [],
+                    "extensions": ["c"],
+                },
                 "exclude": {"dirs": ["**/KLM/**"], "files": [], "extensions": []},
             },
         },
@@ -191,7 +196,12 @@ def test_readme_abc_klm_branch_exception(tmp_path: Path):
     cfg = {
         "root_dir": ".",
         "filters": {
-            "include": {"dirs": ["src/**", "**/ABC/KLM/**"], "files": [], "extensions": ["c"]},
+            "include": {
+                "dirs": ["src/**"],
+                "odirs": ["**/ABC/KLM/**"],
+                "files": [],
+                "extensions": ["c"],
+            },
             "exclude": {"dirs": ["**/ABC/**"], "files": [], "extensions": []},
         },
     }

{filefilter-0.2.2 → filefilter-0.2.4}/tests/test_ruleset.py

@@ -6,7 +6,8 @@ from pathlib import Path
 
 import pytest
 
-from filefilter import Ruleset, load
+from filefilter import Ruleset, load, matches
+from conftest import touch
 
 
 def test_ruleset_resolves_relative_root_against_base(tmp_path: Path):
@@ -53,6 +54,67 @@ def test_parse_extensions_normalizes_values():
     assert rules.exc_exts == [".log"]
 
 
+def test_missing_odirs_defaults_to_empty(tmp_path: Path):
+    cfg = {
+        "root_dir": ".",
+        "filters": {
+            "include": {"dirs": ["**"], "extensions": ["py"]},
+            "exclude": {"dirs": ["**/build/**"]},
+        },
+    }
+    touch(tmp_path / "src" / "app.py")
+    touch(tmp_path / "build" / "app.py")
+    rules = load(json.dumps(cfg), base=str(tmp_path))
+    assert rules.inc_odirs_root == []
+    assert rules.inc_odirs_one == []
+    assert rules.inc_odirs_any == []
+    assert matches(str(tmp_path / "src" / "app.py"), rules) is True
+    assert matches(str(tmp_path / "build" / "app.py"), rules) is False
+
+
+def test_parse_odirs_buckets_like_dirs():
+    cfg = {
+        "root_dir": ".",
+        "filters": {
+            "include": {"dirs": ["src"], "odirs": ["**/keep/**", "*/pkg"]},
+            "exclude": {},
+        },
+    }
+    rules = Ruleset(cfg, resolve_base=".")
+    assert rules.inc_dirs_root == ["src"]
+    assert rules.inc_odirs_any == ["**/keep/**"]
+    assert rules.inc_odirs_one == ["*/pkg"]
+
+
+def test_missing_ofiles_defaults_to_empty(tmp_path: Path):
+    cfg = {
+        "root_dir": ".",
+        "filters": {
+            "include": {"dirs": ["**"], "extensions": ["py"]},
+            "exclude": {"files": ["**/skip.py"]},
+        },
+    }
+    touch(tmp_path / "app.py")
+    touch(tmp_path / "skip.py")
+    rules = load(json.dumps(cfg), base=str(tmp_path))
+    assert rules.include_ofiles == []
+    assert matches(str(tmp_path / "app.py"), rules) is True
+    assert matches(str(tmp_path / "skip.py"), rules) is False
+
+
+def test_parse_ofiles_like_files():
+    cfg = {
+        "root_dir": ".",
+        "filters": {
+            "include": {"files": ["*.py"], "ofiles": ["**/keep.txt", "README.*"]},
+            "exclude": {},
+        },
+    }
+    rules = Ruleset(cfg, resolve_base=".")
+    assert rules.include_files == ["*.py"]
+    assert rules.include_ofiles == ["**/keep.txt", "readme.*"]
+
+
 def test_empty_dir_patterns_are_ignored(tmp_path: Path):
     cfg = {
         "root_dir": ".",