@catheadowl/pathscope 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,115 @@ description: pathscope changelog — user-visible changes per release, newest fi
7
7
  All notable changes to this project are documented here. The format follows
8
8
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
9
9
 
10
+ ## 0.4.1 — 2026-11-20
11
+
12
+ ### Fixed
13
+
14
+ - **loader never-throws restored under the require(esm) hybrid** (2026-11-20,
15
+ consumer-found during the 0.4.0 registry-install verification): requiring
16
+ this package by absolute path from an eval entry
17
+ (`node -e "require('<abs pkg dir>')"`) made Node's require(esm) define
18
+ `__filename` as the eval main's `'[eval]'`, and the CJS-projection anchor
19
+ branch fed that sentinel straight into `createRequire` — an uncaught
20
+ ERR_INVALID_ARG_VALUE at the first walkScope, past the loader's
21
+ never-throws contract. The anchor now trusts `__filename` only when it is
22
+ an absolute path and falls through to `import.meta.url` (which
23
+ require(esm) forms as this file's real URL), and the load call site
24
+ hardens the contract with its own guard. Narrow edge: exports-map
25
+ require, import, and real-file parents were always clean, and 0.3.0 was
26
+ unaffected. A regression pin drives the exact eval-entry shape (abs-path
27
+ require + a real walk with a family file) against the built dist.
28
+
29
+ ## 0.4.0 — 2026-11-20
30
+
31
+ ### Added
32
+
33
+ - **ignore family (`.ignore` / `.rgignore`) as first-class rule sources**
34
+ (2026-11-20 owner ruling — completing ignore-crate WalkBuilder parity):
35
+ the walk root's own `.ignore`/`.rgignore` and every descended directory's
36
+ are folded into the cascade with the same gitignore(5) syntax and
37
+ re-anchoring, after that directory's `.gitignore` and with `.rgignore`
38
+ beating `.ignore` (the ignore crate's own precedence, empirically backed
39
+ by the crate-judge lane, which gained a family-order conformance entry). Distinct
40
+ attribution on the probe face (`source: 'ignore'` + `ignoreFile`), a
41
+ dedicated layered escape hatch (`respectIgnoreFamily`, default `true` —
42
+ both family switches off = rg `--no-ignore`'s file face), face-orthogonal
43
+ under every `alignment` face, and **no inherited phase**: files above the
44
+ walk root are never read (rg's own behavior when the root is a
45
+ subdirectory; the global excludes file stays out for the same locality
46
+ reason). Trees without family files are byte-identical, always. New
47
+ composable-engine step `foldIgnoreFamily` (additive; not folding = the
48
+ family simply does not apply), `ExclusionIO.readIgnoreFamily?` optional
49
+ reader, and `HitSource` gains the `'ignore'` member.
50
+ - **Windows hidden-attribute face** (2026-11-20 owner ruling — completing rg
51
+ `hidden` semantics on the platform where the contract was half-kept): on
52
+ Windows, `excludeDotEntries` now also excludes entries carrying
53
+ `FILE_ATTRIBUTE_HIDDEN` — attribute-hidden, dot-less trees (AppData-class)
54
+ no longer enter walks uninvited; rg and fd (v7.4.0+) check exactly this
55
+ attribute, and the override whitelist rescues either face (exclusion is not
56
+ access control; naming a hidden entry reaches it, same as rg `--hidden`).
57
+ The capability is a win-only native piece shipped inside the package —
58
+ enumeration itself carries the attributes, so the walk pays zero extra
59
+ syscalls; no optional dependencies, no install-time toolchain, and pure
60
+ metadata queries throughout (OneDrive placeholders stay placeholders). The
61
+ dot hit's attribution now says which face fired (`LayerHit.via`:
62
+ `'name' | 'attribute'`), the probe face reads the same attribute through
63
+ the optional `ExclusionIO.hidden` method (walk and point queries agree),
64
+ and adjudication accepts an optional metadata argument
65
+ (`excludeDirectory`/`admitFile` and the `adjudicate*` variants — additive).
66
+ When the native piece cannot load on win32 the attribute face goes inert
67
+ and the scan says so loudly exactly once
68
+ (`windows-hidden-attributes-unavailable` diagnostic) — never a silent
69
+ behavioral gap.
70
+ - **walk link report** (2026-11-19 owner ruling — the second entry-kind report
71
+ face): `walkScope` results carry `links` — the unresolved link entries
72
+ (junctions / symlinks) named exactly as they appear in `files`, so
73
+ link-aware consumers stop re-deriving link-ness with per-entry lstat (the
74
+ any-nav replay layer was the cost evidence). Pure report increment:
75
+ identical options produce the identical `files`, and `links` is always a
76
+ subset of `files` — the same exclusion stack, dot category, and budget cut
77
+ govern both faces, so an excluded link (a dot-named one, a rule-excluded
78
+ one, one below a budget cut) leaves no record.
79
+ `followSymlinks: true` retires the face — followed links are not
80
+ unresolved entries; `links` is always `[]` under following. A dirent whose
81
+ type predicates are all false — DT_UNKNOWN filesystems (pre-ftype XFS,
82
+ some network filesystems), unrecognized Windows reparse tags (e.g.
83
+ OneDrive placeholders), special files (FIFOs, sockets, devices) on any
84
+ filesystem — costs one lstat and the true type governs: links close on
85
+ every filesystem, and entries whose true type re-enters the walk's
86
+ three-way dispatch (DT_UNKNOWN and placeholder dirents) enumerate where
87
+ the traversal silently dropped them before; wherever every dirent lands
88
+ inside the dispatch the walk is byte-identical and pays nothing.
89
+
90
+ ### Changed
91
+
92
+ - **`excludeDotEntries` widens on Windows** (the feature side of the face
93
+ above): the default face now also prunes attribute-hidden, dot-less
94
+ entries and their subtrees. Unix behavior is byte-identical (the attribute
95
+ face does not exist there — ignore-crate precedent: unix hidden is
96
+ dot-name only). Consumers pinning default walks on Windows will see the
97
+ file set shrink by exactly the attribute-hidden entries; turning the
98
+ option off opens both faces together, and the override whitelist rescues
99
+ either face.
100
+
101
+ ### Fixed
102
+
103
+ - **walk hot-path memory wall and attribution cost** (2026-11-20):
104
+ `walkScope` memory no longer grows O(files × rules). The attribution
105
+ enumeration ran inside the walk verdict path — a single-rule matcher
106
+ instance per rule, each memoizing every tested path unconditionally
107
+ (node-ignore 7.0.13's per-instance test cache) — so big curated trees
108
+ retained GB-scale memory (measured 4.9GB at 54k files × ~719 folded rules;
109
+ OOM past a 12GB heap at 109k × ~1,253). The walk verdict now pays only the
110
+ four channel instances' combined tests; per-rule attribution stays on the
111
+ probe/explain slow path with byte-identical hit chains. Measured: the same
112
+ half-tree reads 5.47s at 132MB (was 49.8s at 4.9GB) and the full tree
113
+ completes at 16.7s at 185MB (was unable to finish). Outputs are
114
+ byte-identical — the conformance corpus (28 fixtures / 152 cases, both
115
+ provenance kinds plus the crate judge) is green and per-file counts
116
+ reconcile exactly. A bounded-memory regression test pins the working set
117
+ (measured 18MB vs 443MB for the pre-fix shape on the test corpus).
118
+
10
119
  ## 0.3.0 — 2026-11-13
11
120
 
12
121
  ### Added
package/README.md CHANGED
@@ -6,9 +6,11 @@ pathscope answers one question three ways: **which files are in scope?** Walk th
6
6
 
7
7
  ## Features
8
8
 
9
- - **Git-native semantics** — an unregistered nested repository (an *embedded repository*, in git's own terminology) truncates the walk, exactly as git never descends into one; `.gitignore` cascades with last-match-wins, symlinks are not followed, hidden (dot) entries are skipped by default.
9
+ - **Git-native semantics** — an unregistered nested repository (an *embedded repository*, in git's own terminology) truncates the walk, exactly as git never descends into one; `.gitignore` cascades with last-match-wins, symlinks are not followed, hidden entries are skipped by default with rg `hidden` semantics complete: dot-named everywhere, plus the Windows `FILE_ATTRIBUTE_HIDDEN` face (AppData-class attribute-hidden trees stay out of walks; the win-only native piece ships inside the package and says so loudly — never silently — if it cannot load).
10
10
  - **Stone report** — every boundary-stone hit the walk discovers surfaces as structured metadata (`stoneHits`: stone name + directory + whether it enforced its cut). One walk tells you which subtrees are independent repositories and where: under the default git face the report names the truncation locations; under `alignment: 'scanner'` it is report-not-cut metadata. The file set is untouched by the report.
11
+ - **Link report** — the unresolved link entries (junctions / symlinks) surface as structured metadata (`links`), named exactly as they appear in `files`: the same exclusion stack, dot category, and budget cut govern both faces, so an excluded link leaves no record. `followSymlinks: true` retires the face. The file set is untouched by the report.
11
12
  - **Default ignore presets** — opt-in groups for VCS internals, dependencies, build outputs, caches, and agent docs; every entry can be un-excluded with a named `!` negation.
13
+ - **The ignore family** — `.ignore` and `.rgignore` are first-class rule sources alongside `.gitignore` (ignore-crate WalkBuilder parity): rg users' curated ignore files govern the walk, same syntax, same cascade, distinct attribution, with `respectIgnoreFamily` as their own escape hatch. Files above the walk root are never read (rg's own locality).
12
14
  - **Per-path point queries** — `explainScopePath` answers "is this path in scope, and exactly which layer decided" with a full attribution chain (preset / gitignore layer / boundary stone / strict-override-policy / dot), structural-prune answers, and an explicit-pierce projection. Read-only over the same scope request.
13
15
  - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
14
16
  - **Fail-loud everywhere** — malformed configuration throws `PathscopeConfigError`; missing git or a failed git command throws `PathscopeGitError`. Nothing is silently re-scanned a different way.
@@ -27,7 +29,7 @@ import { walkScope } from '@catheadowl/pathscope';
27
29
 
28
30
  // Default stack: gitignore cascade + vcs/deps/build presets + dot entries
29
31
  // excluded + loud budget (2000).
30
- const { files, diagnostics, stoneHits } = await walkScope('/repo');
32
+ const { files, links, diagnostics, stoneHits } = await walkScope('/repo');
31
33
  console.log(files);
32
34
  //=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
33
35
 
@@ -41,6 +43,10 @@ console.log(stoneHits);
41
43
  // default git face names where the truncation happened; under
42
44
  // alignment: 'scanner' the core stone reports enforced: false and the
43
45
  // walk descends. Pure metadata — the file set never changes because of it.
46
+
47
+ console.log(links);
48
+ //=> ['dir-link'] — the unresolved link entries, named as they appear in
49
+ // files (always a subset of it; followSymlinks: true retires the face).
44
50
  ```
45
51
 
46
52
  All output paths are POSIX-style relative to the scanned root, sorted.
@@ -148,7 +154,7 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
148
154
 
149
155
  | Export | One-line |
150
156
  | --- | --- |
151
- | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics, stoneHits }` |
157
+ | `walkScope(root, options?)` | Walk + exclude → `{ files, links, diagnostics, stoneHits }` |
152
158
  | `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
153
159
  | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
154
160
  | `locateNearest(names, options?)` | Nearest config file, no parsing |
package/dist/cascade.d.ts CHANGED
@@ -1,3 +1,7 @@
1
+ /** The ignore-file family the walk reads — same gitignore(5) syntax, different governance residence. */
2
+ export type IgnoreFileName = '.gitignore' | '.ignore' | '.rgignore';
3
+ /** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
4
+ export declare function readIgnoreFileText(dirPath: string, filename: IgnoreFileName): string | null;
1
5
  /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
2
6
  export declare function readGitignoreText(dirPath: string): string | null;
3
7
  /** Split gitignore text into lines, tolerating CRLF. */
package/dist/cascade.js CHANGED
@@ -25,15 +25,19 @@
25
25
  * same logic.
26
26
  */
27
27
  import { readFileSync } from 'node:fs';
28
- /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
29
- export function readGitignoreText(dirPath) {
28
+ /** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
29
+ export function readIgnoreFileText(dirPath, filename) {
30
30
  try {
31
- return readFileSync(`${dirPath.replace(/\/+$/, '')}/.gitignore`, 'utf8');
31
+ return readFileSync(`${dirPath.replace(/\/+$/, '')}/${filename}`, 'utf8');
32
32
  }
33
33
  catch {
34
34
  return null;
35
35
  }
36
36
  }
37
+ /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
38
+ export function readGitignoreText(dirPath) {
39
+ return readIgnoreFileText(dirPath, '.gitignore');
40
+ }
37
41
  /** Split gitignore text into lines, tolerating CRLF. */
38
42
  export function splitLines(text) {
39
43
  return text.split(/\r?\n/);
@@ -1 +1 @@
1
- {"version":3,"file":"cascade.js","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,MAAc;IAC3D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,UAAU,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAc;IACvD,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,uCAAuC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,QAAQ;QACzB,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAC5D,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC;IAC3B,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAClD,CAAC"}
1
+ {"version":3,"file":"cascade.js","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAKvC,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,QAAwB;IAC1E,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,kBAAkB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,MAAc;IAC3D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,UAAU,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAc;IACvD,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,uCAAuC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,QAAQ;QACzB,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAC5D,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC;IAC3B,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAClD,CAAC"}
@@ -1,3 +1,7 @@
1
+ /** The ignore-file family the walk reads — same gitignore(5) syntax, different governance residence. */
2
+ export type IgnoreFileName = '.gitignore' | '.ignore' | '.rgignore';
3
+ /** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
4
+ export declare function readIgnoreFileText(dirPath: string, filename: IgnoreFileName): string | null;
1
5
  /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
2
6
  export declare function readGitignoreText(dirPath: string): string | null;
3
7
  /** Split gitignore text into lines, tolerating CRLF. */
@@ -1,6 +1,6 @@
1
1
  import { type PresetName, type ScopeOptions } from './types.ts';
2
2
  /** The provenance layers of the exclusion stack, in full-stack priority order. */
3
- export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'policy' | 'dot';
3
+ export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'ignore' | 'policy' | 'dot';
4
4
  /**
5
5
  * One attribution entry of a layer adjudication (the read-only probe face's
6
6
  * unit). Field payload by source: `stone` → stoneName + enforced
@@ -9,8 +9,12 @@ export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore'
9
9
  * as supplied); `preset` → presetName + ruleText (the entry as mounted);
10
10
  * `gitignore` → gitignoreAnchor ('' = the scan root's own layer, a relative
11
11
  * dir = a nested layer, 'inherited:..' = a layer above the scan root) +
12
- * ruleText (the line as written — re-anchoring stays internal); `dot` →
13
- * nothing beyond the source.
12
+ * ruleText (the line as written — re-anchoring stays internal); `ignore`
13
+ * (the .ignore/.rgignore family) → the same depth anchor plus `ignoreFile`
14
+ * naming which family member fired; `dot` →
15
+ * `via`, always present: which face of the rg `hidden` concept fired —
16
+ * 'name' = the dot-name face every platform has, 'attribute' = the Windows
17
+ * FILE_ATTRIBUTE_HIDDEN face.
14
18
  */
15
19
  export interface LayerHit {
16
20
  source: HitSource;
@@ -19,6 +23,22 @@ export interface LayerHit {
19
23
  ruleText?: string;
20
24
  stoneName?: string;
21
25
  enforced?: boolean;
26
+ /** `ignore` only: which family member produced the hit ('.ignore' | '.rgignore'). */
27
+ ignoreFile?: '.ignore' | '.rgignore';
28
+ /** `dot` only, always present there: which face of the rg hidden concept fired. */
29
+ via?: 'name' | 'attribute';
30
+ }
31
+ /**
32
+ * Adjudication metadata the caller pre-fetches per entry — the platform
33
+ * facts a pure string adjudicator cannot see. The walk glue fills it from
34
+ * the enumeration stash (zero extra syscalls); the probe face fills it from
35
+ * `ExclusionIO.hidden`. Absent/undefined metadata = the face does not fire
36
+ * (a non-win platform, a degraded native piece, or a custom IO without the
37
+ * capability) — exactly the walk's degradation contract.
38
+ */
39
+ export interface EntryMeta {
40
+ /** The entry carries the platform's hidden bit (Windows FILE_ATTRIBUTE_HIDDEN). */
41
+ hidden?: boolean;
22
42
  }
23
43
  /** Directory adjudication with attribution — `excluded` is the walk verdict verbatim. */
24
44
  export interface DirectoryAdjudication {
@@ -44,8 +64,29 @@ export interface ExclusionIO {
44
64
  exists(dirKey: string, name: string): Promise<boolean>;
45
65
  /** Read `<dirKey>/.gitignore` (UTF-8); null when absent or unreadable. */
46
66
  readGitignore(dirKey: string): Promise<string | null>;
67
+ /**
68
+ * Read `<dirKey>/.ignore` and `<dirKey>/.rgignore` (UTF-8); null per file
69
+ * when absent or unreadable. The ignore family's read face — optional so
70
+ * existing custom IO implementations keep compiling; absent method = the
71
+ * family stays inert for that consumer's construction and probe phases
72
+ * (the walk reads the files itself through the node fs, unaffected).
73
+ */
74
+ readIgnoreFamily?(dirKey: string): Promise<{
75
+ ignore: string | null;
76
+ rgignore: string | null;
77
+ }>;
78
+ /**
79
+ * Probe whether `name` inside `dirKey` carries the platform's hidden bit
80
+ * (Windows FILE_ATTRIBUTE_HIDDEN). Null = unknown — a non-win platform,
81
+ * a custom IO without the capability, or an unreadable attribute: the
82
+ * caller passes no hidden metadata and the attribute face stays inert,
83
+ * exactly like the walk's degradation contract. Optional so existing
84
+ * custom IO implementations keep compiling; the dot-name face needs
85
+ * nothing from this method.
86
+ */
87
+ hidden?(dirKey: string, name: string): Promise<boolean | null>;
47
88
  }
48
- /** Default IO over the node filesystem (existsSync / readFileSync). */
89
+ /** Default IO over the node filesystem (existsSync / readFileSync + the win32 native attribute probe). */
49
90
  export declare const nodeExclusionIO: ExclusionIO;
50
91
  /** A composable exclusion engine over one scan root. Not concurrent-safe: one engine per traversal run. */
51
92
  export interface ExclusionEngine {
@@ -81,7 +122,7 @@ export interface ExclusionEngine {
81
122
  * mounting the scanner face that drives the boolean form silently loses
82
123
  * the face. Report names, not booleans.
83
124
  */
84
- excludeDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): boolean;
125
+ excludeDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[], meta?: EntryMeta): boolean;
85
126
  /**
86
127
  * Fold a descended directory's `.gitignore` text into the cascade (shallow
87
128
  * first, deep later — appended at the rear of the rule stream, subtree-
@@ -90,12 +131,28 @@ export interface ExclusionEngine {
90
131
  * root's own `.gitignore` is consumed at construction).
91
132
  */
92
133
  foldGitignore(dirPath: string, text: string | null | undefined): void;
134
+ /**
135
+ * Fold a descended directory's `.ignore` and `.rgignore` into the
136
+ * cascade — appended after that directory's `.gitignore` layer (family
137
+ * beats vcs at the same depth; within the family `.rgignore` beats
138
+ * `.ignore`, the ignore crate's own per-directory order). No-op for null
139
+ * texts, when `respectIgnoreFamily` is false, or when `dirPath` is the
140
+ * scan root (the root's own family files are consumed at construction).
141
+ * The family has NO inherited phase: files above the scan root are never
142
+ * read — unlike `.gitignore`, deliberately (rg's own behavior when the
143
+ * root is a subdirectory, and the repository-local rule space).
144
+ */
145
+ foldIgnoreFamily(dirPath: string, texts: {
146
+ ignore?: string | null;
147
+ rgignore?: string | null;
148
+ }): void;
93
149
  /**
94
150
  * Per-file adjudication (pure) for a scan-root-relative POSIX path: strict
95
- * → override → combined table → dot category. No budget — the loud file
96
- * budget is a chassis concern owned by walkScope.
151
+ * → override → combined table → dot category. `meta` carries the
152
+ * pre-fetched platform-hidden bit for the dot category's attribute face.
153
+ * No budget — the loud file budget is a chassis concern owned by walkScope.
97
154
  */
98
- admitFile(relPath: string): boolean;
155
+ admitFile(relPath: string, meta?: EntryMeta): boolean;
99
156
  /**
100
157
  * {@link ExclusionEngine.excludeDirectory} with attribution: the same
101
158
  * verdict (and the same policy-negation restatement side effect), plus the
@@ -106,13 +163,13 @@ export interface ExclusionEngine {
106
163
  * so the last table entry is the last-match-wins winner. The verdict comes
107
164
  * from the same rule instances the walk uses — identical by construction.
108
165
  */
109
- adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): DirectoryAdjudication;
166
+ adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[], meta?: EntryMeta): DirectoryAdjudication;
110
167
  /**
111
168
  * {@link ExclusionEngine.admitFile} with attribution — same file-order
112
169
  * verdict plus the per-layer hit list (see
113
170
  * {@link ExclusionEngine.adjudicateDirectory}).
114
171
  */
115
- adjudicateFile(relPath: string): FileAdjudication;
172
+ adjudicateFile(relPath: string, meta?: EntryMeta): FileAdjudication;
116
173
  /**
117
174
  * Stone attribution only (pure): per-stone hit entries with `enforced`
118
175
  * flags for one scan-root-relative directory — the exemption (named