@catheadowl/pathscope 0.2.0 → 0.4.0

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,130 @@ 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.0 — 2026-11-20
11
+
12
+ ### Added
13
+
14
+ - **ignore family (`.ignore` / `.rgignore`) as first-class rule sources**
15
+ (2026-11-20 owner ruling — completing ignore-crate WalkBuilder parity):
16
+ the walk root's own `.ignore`/`.rgignore` and every descended directory's
17
+ are folded into the cascade with the same gitignore(5) syntax and
18
+ re-anchoring, after that directory's `.gitignore` and with `.rgignore`
19
+ beating `.ignore` (the ignore crate's own precedence, empirically backed
20
+ by the crate-judge lane, which gained a family-order conformance entry). Distinct
21
+ attribution on the probe face (`source: 'ignore'` + `ignoreFile`), a
22
+ dedicated layered escape hatch (`respectIgnoreFamily`, default `true` —
23
+ both family switches off = rg `--no-ignore`'s file face), face-orthogonal
24
+ under every `alignment` face, and **no inherited phase**: files above the
25
+ walk root are never read (rg's own behavior when the root is a
26
+ subdirectory; the global excludes file stays out for the same locality
27
+ reason). Trees without family files are byte-identical, always. New
28
+ composable-engine step `foldIgnoreFamily` (additive; not folding = the
29
+ family simply does not apply), `ExclusionIO.readIgnoreFamily?` optional
30
+ reader, and `HitSource` gains the `'ignore'` member.
31
+ - **Windows hidden-attribute face** (2026-11-20 owner ruling — completing rg
32
+ `hidden` semantics on the platform where the contract was half-kept): on
33
+ Windows, `excludeDotEntries` now also excludes entries carrying
34
+ `FILE_ATTRIBUTE_HIDDEN` — attribute-hidden, dot-less trees (AppData-class)
35
+ no longer enter walks uninvited; rg and fd (v7.4.0+) check exactly this
36
+ attribute, and the override whitelist rescues either face (exclusion is not
37
+ access control; naming a hidden entry reaches it, same as rg `--hidden`).
38
+ The capability is a win-only native piece shipped inside the package —
39
+ enumeration itself carries the attributes, so the walk pays zero extra
40
+ syscalls; no optional dependencies, no install-time toolchain, and pure
41
+ metadata queries throughout (OneDrive placeholders stay placeholders). The
42
+ dot hit's attribution now says which face fired (`LayerHit.via`:
43
+ `'name' | 'attribute'`), the probe face reads the same attribute through
44
+ the optional `ExclusionIO.hidden` method (walk and point queries agree),
45
+ and adjudication accepts an optional metadata argument
46
+ (`excludeDirectory`/`admitFile` and the `adjudicate*` variants — additive).
47
+ When the native piece cannot load on win32 the attribute face goes inert
48
+ and the scan says so loudly exactly once
49
+ (`windows-hidden-attributes-unavailable` diagnostic) — never a silent
50
+ behavioral gap.
51
+ - **walk link report** (2026-11-19 owner ruling — the second entry-kind report
52
+ face): `walkScope` results carry `links` — the unresolved link entries
53
+ (junctions / symlinks) named exactly as they appear in `files`, so
54
+ link-aware consumers stop re-deriving link-ness with per-entry lstat (the
55
+ any-nav replay layer was the cost evidence). Pure report increment:
56
+ identical options produce the identical `files`, and `links` is always a
57
+ subset of `files` — the same exclusion stack, dot category, and budget cut
58
+ govern both faces, so an excluded link (a dot-named one, a rule-excluded
59
+ one, one below a budget cut) leaves no record.
60
+ `followSymlinks: true` retires the face — followed links are not
61
+ unresolved entries; `links` is always `[]` under following. A dirent whose
62
+ type predicates are all false — DT_UNKNOWN filesystems (pre-ftype XFS,
63
+ some network filesystems), unrecognized Windows reparse tags (e.g.
64
+ OneDrive placeholders), special files (FIFOs, sockets, devices) on any
65
+ filesystem — costs one lstat and the true type governs: links close on
66
+ every filesystem, and entries whose true type re-enters the walk's
67
+ three-way dispatch (DT_UNKNOWN and placeholder dirents) enumerate where
68
+ the traversal silently dropped them before; wherever every dirent lands
69
+ inside the dispatch the walk is byte-identical and pays nothing.
70
+
71
+ ### Changed
72
+
73
+ - **`excludeDotEntries` widens on Windows** (the feature side of the face
74
+ above): the default face now also prunes attribute-hidden, dot-less
75
+ entries and their subtrees. Unix behavior is byte-identical (the attribute
76
+ face does not exist there — ignore-crate precedent: unix hidden is
77
+ dot-name only). Consumers pinning default walks on Windows will see the
78
+ file set shrink by exactly the attribute-hidden entries; turning the
79
+ option off opens both faces together, and the override whitelist rescues
80
+ either face.
81
+
82
+ ### Fixed
83
+
84
+ - **walk hot-path memory wall and attribution cost** (2026-11-20):
85
+ `walkScope` memory no longer grows O(files × rules). The attribution
86
+ enumeration ran inside the walk verdict path — a single-rule matcher
87
+ instance per rule, each memoizing every tested path unconditionally
88
+ (node-ignore 7.0.13's per-instance test cache) — so big curated trees
89
+ retained GB-scale memory (measured 4.9GB at 54k files × ~719 folded rules;
90
+ OOM past a 12GB heap at 109k × ~1,253). The walk verdict now pays only the
91
+ four channel instances' combined tests; per-rule attribution stays on the
92
+ probe/explain slow path with byte-identical hit chains. Measured: the same
93
+ half-tree reads 5.47s at 132MB (was 49.8s at 4.9GB) and the full tree
94
+ completes at 16.7s at 185MB (was unable to finish). Outputs are
95
+ byte-identical — the conformance corpus (28 fixtures / 152 cases, both
96
+ provenance kinds plus the crate judge) is green and per-file counts
97
+ reconcile exactly. A bounded-memory regression test pins the working set
98
+ (measured 18MB vs 443MB for the pre-fix shape on the test corpus).
99
+
100
+ ## 0.3.0 — 2026-11-13
101
+
102
+ ### Added
103
+
104
+ - **walk stone report** (2026-11-13 owner ruling — the report-not-cut
105
+ principle carried onto the walk result): `walkScope` results carry
106
+ `stoneHits` — every boundary-stone hit the walk discovered, as
107
+ `{ stoneName, path, enforced }`. One walk now tells you which subtrees are
108
+ independent repositories (or declared config-home sub-domains) and where:
109
+ `enforced: true` on the default git face names the truncation locations;
110
+ under `alignment: 'scanner'` core-stone hits report `enforced: false`
111
+ (report-not-cut metadata) and the walk descends; exemption-neutralized hits
112
+ report `enforced: false` (registration, not rescue); config-home hits stay
113
+ `enforced: true` under every face. Pure metadata — the file set is untouched,
114
+ output is sorted (path, then stone name), the scan root's own markers are
115
+ not reported, and conformance fixture 38 pins the membership invariants.
116
+
117
+ ### Changed
118
+
119
+ - **preset vocabulary additions** (adopted 2026-11-13): `venv` and
120
+ `.gradle` join the opt-in `caches` group (both in repomix's defaultIgnore;
121
+ `venv` also in github's Python template — watchfiles carries `.venv` only);
122
+ the `build` group gains the **root-anchored** `/target` — the cargo/maven
123
+ build tree, anchored exactly because `target` is collision-grade (the Rust
124
+ toolchain's own adjudication: cargo#3158 → `cargo new` generates `/target`).
125
+ The anchored entry matches only a `target` directory AT the scan root
126
+ (re-anchored accordingly when the scan root sits below a repo root) —
127
+ nested same-named directories are untouched, and `!target/` un-excludes it
128
+ like every preset entry. `caches` is not default-mounted (no default
129
+ change); `build` is, so default scans now skip a scan-root `target/` —
130
+ projects whose scan root legitimately holds content in `target/` name their
131
+ way out with `!target/`. A `dirs` entry may now carry a leading slash
132
+ (scan-root anchor) — plain gitignore anchoring, no new matching semantics.
133
+
10
134
  ## 0.2.0 — 2026-11-01
11
135
 
12
136
  ### Added
package/README.md CHANGED
@@ -6,8 +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
+ - **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.
10
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).
11
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.
12
15
  - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
13
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.
@@ -26,12 +29,24 @@ import { walkScope } from '@catheadowl/pathscope';
26
29
 
27
30
  // Default stack: gitignore cascade + vcs/deps/build presets + dot entries
28
31
  // excluded + loud budget (2000).
29
- const { files, diagnostics } = await walkScope('/repo');
32
+ const { files, links, diagnostics, stoneHits } = await walkScope('/repo');
30
33
  console.log(files);
31
34
  //=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
32
35
 
33
36
  console.log(diagnostics);
34
37
  //=> [] — non-empty means the budget cut the scan (code: 'budget-exceeded')
38
+
39
+ console.log(stoneHits);
40
+ //=> [{ stoneName: '.git', path: 'embedded-toolkit', enforced: true }]
41
+ // — every stone hit the walk discovered: which subtrees are independent
42
+ // repositories (or declared sub-domains) and where. `enforced: true` on the
43
+ // default git face names where the truncation happened; under
44
+ // alignment: 'scanner' the core stone reports enforced: false and the
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).
35
50
  ```
36
51
 
37
52
  All output paths are POSIX-style relative to the scanned root, sorted.
@@ -139,7 +154,7 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
139
154
 
140
155
  | Export | One-line |
141
156
  | --- | --- |
142
- | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics }` |
157
+ | `walkScope(root, options?)` | Walk + exclude → `{ files, links, diagnostics, stoneHits }` |
143
158
  | `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
144
159
  | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
145
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. */
@@ -2,5 +2,9 @@ import { type ScopeOptions, type WalkResult } from './types.ts';
2
2
  /**
3
3
  * Walk `root` and produce the in-scope file set: POSIX relative paths, sorted,
4
4
  * plus loud diagnostics. See {@link ScopeOptions} for the exclusion stack.
5
+ *
6
+ * @throws {@link PathscopeConfigError} when `root` does not exist — the same
7
+ * fail-loud family as every face; a missing scan root is a configuration
8
+ * error, never a silent empty result.
5
9
  */
6
10
  export declare function walkScope(root: string, options?: ScopeOptions): Promise<WalkResult>;
@@ -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