@catheadowl/pathscope 0.1.0 → 0.2.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
@@ -1,90 +1,135 @@
1
- ---
2
- description: pathscope changelog — user-visible changes per release, newest first
3
- ---
4
-
5
- # Changelog
6
-
7
- All notable changes to this project are documented here. The format follows
8
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
9
-
10
- ## 0.1.0 — 2026-10-24
11
-
12
- First public cut.
13
-
14
- ### Added
15
-
16
- - **walk mode** — `walkScope(root, options)`: whole-tree pruning, gitignore
17
- cascade (inherited + nested, one ordered rule stream, last-match-wins),
18
- five mounted exclusion presets (vcs / deps / build / caches / agentDocs —
19
- un-excludable via named `!`), policy layer, override whitelist (terminal
20
- include), strict immune channel (outbound artifact boundaries, written
21
- reason mandatory), boundary stones (always-on `.git` core stone, opt-in
22
- config homes and `.gitignore` proxy), dot-entry walk option, symlinks
23
- unresolved by default, and a loud file budget (default 2000 — never a
24
- silent cut). `respectGitignore: false` skips the gitignore sources only —
25
- presets, the policy layer, the override whitelist, and boundary stones
26
- are unaffected.
27
- - **named-subtree core-stone exemption** — `boundaryStones.exempt`:
28
- gitignore-style patterns anchored at the scan root (e.g.
29
- `'embedded-toolkit/'`) naming subtrees whose own `.git` no longer
30
- truncates them — the submodule-registration isomorphism. A matched
31
- directory descends as a native subtree (nested `.gitignore` files fold by
32
- the ordinary nesting rules), while a deeper embedded `.git` inside it is
33
- still a stone and un-named siblings keep the cut. The exemption reaches
34
- only the core stone (config homes and the `.gitignore` proxy are never
35
- exemptible) and is registration, not rescue. On the composable engine
36
- face, `excludeDirectory`'s `stoneHit` parameter additionally accepts
37
- per-stone hit names (`boolean | readonly string[]`); the boolean form
38
- still truncates unconditionally.
39
- - **proxy-stone exemption** — `boundaryStones.exempt` reaches the
40
- `.gitignore` proxy stone under the same rules: naming a subtree revokes
41
- its proxy registration — the named subtree returns to the git-native
42
- default where a nested `.gitignore` is rules, not territory. Config homes
43
- stay never-exemptible; a co-hit of the exemptible kinds in one directory
44
- is neutralized by the single naming; deeper proxy stones inside the named
45
- subtree are still stones. A degenerate `.gitignore` config-home
46
- declaration under a mounted proxy stone is rejected as a configuration
47
- error.
48
- - **alignment faces** — `alignment?: 'git' | 'scanner'` (default `'git'`):
49
- two named faces over one decision core. The git face is the standing
50
- semantics (core-stone truncation). The scanner face (rg/fd family parity)
51
- suspends core-stone enforcement — report-not-cut: the `.git` stone stays
52
- in the probe contract and the per-stone `stoneHit` report keeps naming it
53
- ("this subtree is a nested repository" metadata) while the truncation
54
- never executes, at any depth. Config-home stones keep their verdict under
55
- every face; mounting `gitignoreProxy` under the scanner face is rejected
56
- as a configuration error. On the composable face the scanner semantics
57
- ride the array `stoneHit` form of `excludeDirectory`; the boolean form
58
- keeps its unconditional cut.
59
- - **git universe** — `gitUniverse(root, options)`: ask git instead of
60
- walking. Variants `all` (tracked + untracked-but-not-ignored), `tree`
61
- (index contents), `staged` (A/C/M/R vs HEAD). Gitlink submodules
62
- (mode 160000) and symlinks (mode 120000) never enter the universe;
63
- repository root memoized per root (`clearUniverseCache` resets); opt-in
64
- `filter` post-filter (a tracked `node_modules` belongs in the universe).
65
- - **config discovery** — `locateNearest(names, {cwd, stopAt})`:
66
- nearest-wins residence lookup (nested config = governance boundary;
67
- `stopAt` inclusive). Locates only — parsing stays consumer-side.
68
- - **composable decision core** — `createExclusionEngine(rootKey, options?,
69
- io?)`: the exclusion stack + gitignore cascade behind walkScope as a
70
- standalone engine for consumers that own their own traversal (incremental
71
- snapshots, watcher feeds, URI/remote filesystems). Construction runs the
72
- inherited phase through an injectable async `ExclusionIO`
73
- (`nodeExclusionIO` is the node default); adjudication is pure and
74
- synchronous — `excludeDirectory(name, dirPath, stoneHit?)` → (descend) →
75
- `foldGitignore(dirPath, text)` → `admitFile(relPath)` mirrors walkScope's
76
- per-directory sequence, no budget (the loud budget stays with walkScope).
77
- - **conformance corpus** — self-contained fixtures of two provenance kinds
78
- (git-oracle-adjudicated and registered extensions), language-neutral for
79
- cross-language ports.
80
- - `PathscopeConfigError` (malformed options fail loudly) and
81
- `PathscopeGitError` (git missing / not a repository / git failed — the
82
- message names the command).
83
- - **dual-format package** — a CommonJS require condition
84
- (`dist/cjs/index.js`, an esbuild bundle that inlines the ESM-only find-up
85
- so the CJS artifact runs on the same Node range as the ESM face) alongside
86
- the ESM default (`esbuild` is a devDependency, build-time only).
87
-
88
- ### Changed
89
-
90
- - Nothing yet — this is the first release.
1
+ ---
2
+ description: pathscope changelog — user-visible changes per release, newest first
3
+ ---
4
+
5
+ # Changelog
6
+
7
+ All notable changes to this project are documented here. The format follows
8
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
9
+
10
+ ## 0.2.0 — 2026-11-01
11
+
12
+ ### Added
13
+
14
+ - **per-path probe** — `explainScopePath(root, relPath, options?)`: the
15
+ read-only point-query face over the same scope request. Returns
16
+ `{ excluded, structural, hitChain, explicit }` — the membership verdict,
17
+ whether it came from a directory-level prune (an excluded ancestor, or the
18
+ queried directory itself), the ordered hit chain attributing every
19
+ matching layer (preset name / gitignore layer anchor + the rule as
20
+ written / stone name with the scanner face's report-not-cut fact /
21
+ strict, override, policy, dot), and the explicit-pierce projection
22
+ (`pierceable` = no enforced stone and no strict hit; the policy of what
23
+ to do with a pierceable path stays consumer-side). Nonexistent paths
24
+ adjudicate hypothetically; the scan root returns the boundary fact;
25
+ out-of-domain inputs (`..`, absolute, backslash) fail loudly. Verdict
26
+ equivalence with `walkScope` membership is pinned by the whole conformance
27
+ corpus (37 fixtures, both provenance kinds) through the same
28
+ fixture→options mapping.
29
+ - **engine attribution faces** — `createExclusionEngine` gains
30
+ `adjudicateDirectory` / `adjudicateFile` (the boolean faces delegate to
31
+ them — identical verdicts by construction) plus the narrow projection
32
+ faces `attributeStones` / `adjudicateStrict`. The combined rule table is
33
+ now maintained per-rule with provenance alongside the verdict instances;
34
+ the verdict path is byte-identical (the unchanged-green corpus is the
35
+ zero-matching-deviation evidence).
36
+ - **ignore-crate conformance judge** — `scripts/ignore-crate-oracle.mjs`
37
+ (+ cargo-gated test, `npm run oracle:crate`): a second reference anchor
38
+ that re-adjudicates every git-oracle fixture against ripgrep's library
39
+ core (`ignore` crate) over its public walk face. First run registered two
40
+ acknowledged anchor-limit divergences (char-class edges where the crate's
41
+ globset parts from git wildmatch while pathscope's kernel agrees with
42
+ git) — git remains the sole expectation generator; unexpected drift
43
+ fails the gate.
44
+ - conformance fixtures 36 (structural ancestor: a pruned subtree's own
45
+ rules never participate) and 37 (mixed attribution chain: preset front →
46
+ cascade shallow→deep → policy rear).
47
+
48
+ ## 0.1.1 — 2026-10-31
49
+
50
+ Maintenance release — no library changes. CI publishing switched to npm
51
+ trusted publishing (OIDC); provenance attestations stay off while the
52
+ source repository is private (`publishConfig.provenance: false`, to be
53
+ dropped when the repository goes public).
54
+
55
+ ## 0.1.0 — 2026-10-24
56
+
57
+ First public cut.
58
+
59
+ ### Added
60
+
61
+ - **walk mode** — `walkScope(root, options)`: whole-tree pruning, gitignore
62
+ cascade (inherited + nested, one ordered rule stream, last-match-wins),
63
+ five mounted exclusion presets (vcs / deps / build / caches / agentDocs —
64
+ un-excludable via named `!`), policy layer, override whitelist (terminal
65
+ include), strict immune channel (outbound artifact boundaries, written
66
+ reason mandatory), boundary stones (always-on `.git` core stone, opt-in
67
+ config homes and `.gitignore` proxy), dot-entry walk option, symlinks
68
+ unresolved by default, and a loud file budget (default 2000 — never a
69
+ silent cut). `respectGitignore: false` skips the gitignore sources only —
70
+ presets, the policy layer, the override whitelist, and boundary stones
71
+ are unaffected.
72
+ - **named-subtree core-stone exemption** — `boundaryStones.exempt`:
73
+ gitignore-style patterns anchored at the scan root (e.g.
74
+ `'embedded-toolkit/'`) naming subtrees whose own `.git` no longer
75
+ truncates them — the submodule-registration isomorphism. A matched
76
+ directory descends as a native subtree (nested `.gitignore` files fold by
77
+ the ordinary nesting rules), while a deeper embedded `.git` inside it is
78
+ still a stone and un-named siblings keep the cut. The exemption reaches
79
+ only the core stone (config homes and the `.gitignore` proxy are never
80
+ exemptible) and is registration, not rescue. On the composable engine
81
+ face, `excludeDirectory`'s `stoneHit` parameter additionally accepts
82
+ per-stone hit names (`boolean | readonly string[]`); the boolean form
83
+ still truncates unconditionally.
84
+ - **proxy-stone exemption** — `boundaryStones.exempt` reaches the
85
+ `.gitignore` proxy stone under the same rules: naming a subtree revokes
86
+ its proxy registration — the named subtree returns to the git-native
87
+ default where a nested `.gitignore` is rules, not territory. Config homes
88
+ stay never-exemptible; a co-hit of the exemptible kinds in one directory
89
+ is neutralized by the single naming; deeper proxy stones inside the named
90
+ subtree are still stones. A degenerate `.gitignore` config-home
91
+ declaration under a mounted proxy stone is rejected as a configuration
92
+ error.
93
+ - **alignment faces** — `alignment?: 'git' | 'scanner'` (default `'git'`):
94
+ two named faces over one decision core. The git face is the standing
95
+ semantics (core-stone truncation). The scanner face (rg/fd family parity)
96
+ suspends core-stone enforcement — report-not-cut: the `.git` stone stays
97
+ in the probe contract and the per-stone `stoneHit` report keeps naming it
98
+ ("this subtree is a nested repository" metadata) while the truncation
99
+ never executes, at any depth. Config-home stones keep their verdict under
100
+ every face; mounting `gitignoreProxy` under the scanner face is rejected
101
+ as a configuration error. On the composable face the scanner semantics
102
+ ride the array `stoneHit` form of `excludeDirectory`; the boolean form
103
+ keeps its unconditional cut.
104
+ - **git universe** — `gitUniverse(root, options)`: ask git instead of
105
+ walking. Variants `all` (tracked + untracked-but-not-ignored), `tree`
106
+ (index contents), `staged` (A/C/M/R vs HEAD). Gitlink submodules
107
+ (mode 160000) and symlinks (mode 120000) never enter the universe;
108
+ repository root memoized per root (`clearUniverseCache` resets); opt-in
109
+ `filter` post-filter (a tracked `node_modules` belongs in the universe).
110
+ - **config discovery** — `locateNearest(names, {cwd, stopAt})`:
111
+ nearest-wins residence lookup (nested config = governance boundary;
112
+ `stopAt` inclusive). Locates only — parsing stays consumer-side.
113
+ - **composable decision core** — `createExclusionEngine(rootKey, options?,
114
+ io?)`: the exclusion stack + gitignore cascade behind walkScope as a
115
+ standalone engine for consumers that own their own traversal (incremental
116
+ snapshots, watcher feeds, URI/remote filesystems). Construction runs the
117
+ inherited phase through an injectable async `ExclusionIO`
118
+ (`nodeExclusionIO` is the node default); adjudication is pure and
119
+ synchronous — `excludeDirectory(name, dirPath, stoneHit?)` → (descend) →
120
+ `foldGitignore(dirPath, text)` → `admitFile(relPath)` mirrors walkScope's
121
+ per-directory sequence, no budget (the loud budget stays with walkScope).
122
+ - **conformance corpus** — self-contained fixtures of two provenance kinds
123
+ (git-oracle-adjudicated and registered extensions), language-neutral for
124
+ cross-language ports.
125
+ - `PathscopeConfigError` (malformed options fail loudly) and
126
+ `PathscopeGitError` (git missing / not a repository / git failed — the
127
+ message names the command).
128
+ - **dual-format package** — a CommonJS require condition
129
+ (`dist/cjs/index.js`, an esbuild bundle that inlines the ESM-only find-up
130
+ so the CJS artifact runs on the same Node range as the ESM face) alongside
131
+ the ESM default (`esbuild` is a devDependency, build-time only).
132
+
133
+ ### Changed
134
+
135
+ - Nothing yet — this is the first release.
package/README.md CHANGED
@@ -2,12 +2,13 @@
2
2
 
3
3
  > Resolve the set of files a tool should see in a repository — git-native by default.
4
4
 
5
- pathscope answers one question three ways: **which files are in scope?** Walk the filesystem with a gitignore cascade and default ignore presets (`walkScope`), ask git directly instead of walking (`gitUniverse`), or compose the same exclusion engine into your own traversal (`createExclusionEngine`). It also locates the nearest config file on the way up without parsing it (`locateNearest`).
5
+ pathscope answers one question three ways: **which files are in scope?** Walk the filesystem with a gitignore cascade and default ignore presets (`walkScope`), ask git directly instead of walking (`gitUniverse`), or point-query one path — is it excluded, and exactly which layer decided (`explainScopePath`)? You can also compose the same exclusion engine into your own traversal (`createExclusionEngine`). It also locates the nearest config file on the way up without parsing it (`locateNearest`).
6
6
 
7
7
  ## Features
8
8
 
9
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.
10
10
  - **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.
11
+ - **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.
11
12
  - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
12
13
  - **Fail-loud everywhere** — malformed configuration throws `PathscopeConfigError`; missing git or a failed git command throws `PathscopeGitError`. Nothing is silently re-scanned a different way.
13
14
  - **ESM + CommonJS** — dual build, Node.js >= 20.
@@ -46,6 +47,41 @@ const { files } = await walkScope('/repo', {
46
47
  });
47
48
  ```
48
49
 
50
+ ### Ask one path: excluded, and why
51
+
52
+ `explainScopePath` is the read-only probe over the same scope request — the diagnostic face for "why is this file not in scope":
53
+
54
+ ```js
55
+ import { explainScopePath } from '@catheadowl/pathscope';
56
+
57
+ const answer = await explainScopePath('/repo', 'node_modules/pkg/index.js');
58
+ // {
59
+ // excluded: true,
60
+ // structural: true, // a directory-level prune carries the subtree
61
+ // hitChain: [
62
+ // { source: 'preset', presetName: 'deps', ruleText: 'node_modules/',
63
+ // path: 'node_modules' }, // the hit adjudicated the ANCESTOR
64
+ // ],
65
+ // explicit: { pierceable: true, blockers: [] }, // naming it would pierce
66
+ // }
67
+
68
+ // Same scope request as a walk — pass the SAME options you pass walkScope:
69
+ const same = await explainScopePath('/repo', 'sandbox/x.snapshot.md', {
70
+ mountPresets: ['vcs', 'deps', 'build', 'caches'],
71
+ exclude: ['sandbox/'],
72
+ });
73
+ ```
74
+
75
+ Every matching layer reports with its attribution — which preset, which `.gitignore` layer (anchor + the line as written), which stone (with the scanner face's report-not-cut fact), strict/override/policy patterns. Nonexistent paths adjudicate hypothetically (the status-query shape). Explicit piercing policy (report / warn / refuse) stays with you — the engine supplies the facts.
76
+
77
+ Fine print worth knowing before your first call:
78
+
79
+ - `excluded` is the **rule-space verdict**. For a path on disk under an un-cut budget it equals "absent from a walkScope result"; the two caveats are by design — the loud budget is a walk-chassis concern this API never reflects (a budget-cut walk omits files the probe rightly reports as included), and for a nonexistent path `excluded: false` means "nothing in the rule space excludes it" (walkScope membership is undefined for paths that do not exist — your status branch owns existence separately).
80
+ - The chain is an **adjudication record, not just the verdict's cause** — an included path can carry hits (the preset hit, then the override that rescued it), and a stone entry with `enforced: false` is report-only metadata (the scanner face's report-not-cut). For a structural answer the chain is exactly the excluded ancestor's adjudication record: adjudication does not continue below the prune, so the query path's own rule hits are absent — what still matters below it (enforced stones, strict hits) surfaces in `explicit.blockers`.
81
+ - `relPath` is scan-root-relative POSIX; a leading `./` is stripped (`''`, `'.'`, `'./'` all name the scan root itself); the trailing slash is the **operator** that selects directory-order adjudication, not a statement about disk — a slash-less query always adjudicates file-order, even for an existing directory. `root` takes any form `path.resolve` accepts, native separators included, exactly like walkScope.
82
+ - Out-of-domain inputs (`..` escapes, absolute paths, backslashes, empty inner segments, a nonexistent scan root) throw `PathscopeConfigError` — same fail-loud family as every other malformed input.
83
+ - Each call is self-contained over a dedicated engine instance: calls are independent and safe to run in parallel — many-paths workloads have no batch face yet (deferred), so run concurrent queries concurrently. Symlinks are not resolved (like the walk default): a symlinked final segment adjudicates by its own name, intermediate reads follow the filesystem as any read does; `followSymlinks` and `maxFiles` are walk-chassis options — accepted and ignored here. The probe covers the walk face only; the ask-git face has no point query — git itself answers those questions.
84
+
49
85
  ### Ask git instead of walking
50
86
 
51
87
  ```js
@@ -104,9 +140,12 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
104
140
  | Export | One-line |
105
141
  | --- | --- |
106
142
  | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics }` |
143
+ | `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
107
144
  | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
108
145
  | `locateNearest(names, options?)` | Nearest config file, no parsing |
109
146
  | `createExclusionEngine(root, options?, io?)` | The exclusion engine for your own traversal |
147
+ | `nodeExclusionIO` | The node-filesystem default `ExclusionIO` for the engine |
148
+ | `clearUniverseCache()` | Reset `gitUniverse`'s repo-root memoization (test seam) |
110
149
  | `PRESETS` / `DEFAULT_MOUNTED_PRESETS` | Preset contents |
111
150
  | `PathscopeConfigError` / `PathscopeGitError` | Fail-loud error classes |
112
151
 
package/dist/cascade.d.ts CHANGED
@@ -14,3 +14,9 @@ export declare function splitLines(text: string): string[];
14
14
  * Negation prefixes and backslash escapes pass through untouched.
15
15
  */
16
16
  export declare function reanchorLines(lines: string[], prefix: string): string[];
17
+ /**
18
+ * The per-line form of {@link reanchorLines} — the provenance pairing the
19
+ * read-only probe face needs: one raw line in, its mounted (re-anchored)
20
+ * form out, null for non-rule lines (blank / comment / bare `!`).
21
+ */
22
+ export declare function reanchorLine(line: string, prefix: string): string | null;
package/dist/cascade.js CHANGED
@@ -52,18 +52,28 @@ export function splitLines(text) {
52
52
  export function reanchorLines(lines, prefix) {
53
53
  const out = [];
54
54
  for (const line of lines) {
55
- if (line === '' || line.startsWith('#'))
56
- continue;
57
- const negative = line.startsWith('!');
58
- const body = negative ? line.slice(1) : line;
59
- if (body === '')
60
- continue; // a bare '!' is discarded, as git does
61
- const anchored = body.startsWith('/') || body.slice(0, -1).includes('/');
62
- const reanchored = anchored
63
- ? `${prefix}/${body.startsWith('/') ? body.slice(1) : body}`
64
- : `${prefix}/**/${body}`;
65
- out.push(negative ? `!${reanchored}` : reanchored);
55
+ const reanchored = reanchorLine(line, prefix);
56
+ if (reanchored !== null)
57
+ out.push(reanchored);
66
58
  }
67
59
  return out;
68
60
  }
61
+ /**
62
+ * The per-line form of {@link reanchorLines} — the provenance pairing the
63
+ * read-only probe face needs: one raw line in, its mounted (re-anchored)
64
+ * form out, null for non-rule lines (blank / comment / bare `!`).
65
+ */
66
+ export function reanchorLine(line, prefix) {
67
+ if (line === '' || line.startsWith('#'))
68
+ return null;
69
+ const negative = line.startsWith('!');
70
+ const body = negative ? line.slice(1) : line;
71
+ if (body === '')
72
+ return null; // a bare '!' is discarded, as git does
73
+ const anchored = body.startsWith('/') || body.slice(0, -1).includes('/');
74
+ const reanchored = anchored
75
+ ? `${prefix}/${body.startsWith('/') ? body.slice(1) : body}`
76
+ : `${prefix}/**/${body}`;
77
+ return negative ? `!${reanchored}` : reanchored;
78
+ }
69
79
  //# sourceMappingURL=cascade.js.map
@@ -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,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7C,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS,CAAC,uCAAuC;QAClE,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;QACzE,MAAM,UAAU,GAAG,QAAQ;YACzB,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;YAC5D,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC;QAC3B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
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"}
@@ -14,3 +14,9 @@ export declare function splitLines(text: string): string[];
14
14
  * Negation prefixes and backslash escapes pass through untouched.
15
15
  */
16
16
  export declare function reanchorLines(lines: string[], prefix: string): string[];
17
+ /**
18
+ * The per-line form of {@link reanchorLines} — the provenance pairing the
19
+ * read-only probe face needs: one raw line in, its mounted (re-anchored)
20
+ * form out, null for non-rule lines (blank / comment / bare `!`).
21
+ */
22
+ export declare function reanchorLine(line: string, prefix: string): string | null;
@@ -1,4 +1,35 @@
1
- import { type ScopeOptions } from './types.ts';
1
+ import { type PresetName, type ScopeOptions } from './types.ts';
2
+ /** The provenance layers of the exclusion stack, in full-stack priority order. */
3
+ export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'policy' | 'dot';
4
+ /**
5
+ * One attribution entry of a layer adjudication (the read-only probe face's
6
+ * unit). Field payload by source: `stone` → stoneName + enforced
7
+ * (report-not-cut facts — a hit that does not execute its cut carries
8
+ * `enforced: false`); `strict`/`override`/`policy` → ruleText (the pattern
9
+ * as supplied); `preset` → presetName + ruleText (the entry as mounted);
10
+ * `gitignore` → gitignoreAnchor ('' = the scan root's own layer, a relative
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.
14
+ */
15
+ export interface LayerHit {
16
+ source: HitSource;
17
+ presetName?: PresetName;
18
+ gitignoreAnchor?: string;
19
+ ruleText?: string;
20
+ stoneName?: string;
21
+ enforced?: boolean;
22
+ }
23
+ /** Directory adjudication with attribution — `excluded` is the walk verdict verbatim. */
24
+ export interface DirectoryAdjudication {
25
+ excluded: boolean;
26
+ hits: LayerHit[];
27
+ }
28
+ /** File adjudication with attribution — `admitted` is the walk verdict verbatim. */
29
+ export interface FileAdjudication {
30
+ admitted: boolean;
31
+ hits: LayerHit[];
32
+ }
2
33
  /**
3
34
  * Filesystem access for the engine's construction-time inherited phase.
4
35
  * Methods receive POSIX-separator absolute directory keys —
@@ -65,6 +96,45 @@ export interface ExclusionEngine {
65
96
  * budget is a chassis concern owned by walkScope.
66
97
  */
67
98
  admitFile(relPath: string): boolean;
99
+ /**
100
+ * {@link ExclusionEngine.excludeDirectory} with attribution: the same
101
+ * verdict (and the same policy-negation restatement side effect), plus the
102
+ * per-layer hit list in full-stack priority order — the read-only probe
103
+ * face's engine side. Every layer that MATCHED reports an entry
104
+ * (non-matching layers stay silent); within the combined table the entries
105
+ * follow the rule stream (presets → cascade → folds → policy rear seat),
106
+ * so the last table entry is the last-match-wins winner. The verdict comes
107
+ * from the same rule instances the walk uses — identical by construction.
108
+ */
109
+ adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): DirectoryAdjudication;
110
+ /**
111
+ * {@link ExclusionEngine.admitFile} with attribution — same file-order
112
+ * verdict plus the per-layer hit list (see
113
+ * {@link ExclusionEngine.adjudicateDirectory}).
114
+ */
115
+ adjudicateFile(relPath: string): FileAdjudication;
116
+ /**
117
+ * Stone attribution only (pure): per-stone hit entries with `enforced`
118
+ * flags for one scan-root-relative directory — the exemption (named
119
+ * subtree) and the alignment face (report-not-cut) are applied exactly as
120
+ * the truncation adjudication applies them. The scan root itself never
121
+ * truncates, so `relDir: ''` reports nothing (the universe-boundary
122
+ * guard). The probe's explicit projection uses this under pruned
123
+ * subtrees, where rule adjudication must NOT run but stone facts remain
124
+ * consumer-relevant.
125
+ */
126
+ attributeStones(relDir: string, stoneHit: readonly string[]): LayerHit[];
127
+ /**
128
+ * Strict-channel adjudication only (pure): whether the strict immune
129
+ * channel hits a scan-root-relative path, with per-rule attribution.
130
+ * `isDir` selects the directory form (trailing-slash canonical space) of
131
+ * the path. The projection face for pruned-subtree walks — strict is the
132
+ * one rule channel explicit naming can never pierce.
133
+ */
134
+ adjudicateStrict(relPath: string, isDir: boolean): {
135
+ hit: boolean;
136
+ hits: LayerHit[];
137
+ };
68
138
  }
69
139
  /** Validate options; malformed configuration fails loudly instead of scanning differently. */
70
140
  export declare function validateOptions(options: ScopeOptions): void;
@@ -0,0 +1,109 @@
1
+ import { type LayerHit } from './exclusion-engine.ts';
2
+ import { type ScopeOptions } from './types.ts';
3
+ /** One hit in the explanation chain: a layer adjudication entry plus the path it adjudicated. */
4
+ export interface HitEntry extends LayerHit {
5
+ /**
6
+ * The scan-root-relative POSIX path this hit adjudicated — the queried
7
+ * path itself for rule answers, the EXCLUDED ANCESTOR for structural
8
+ * answers (the pruned directory is where the verdict was made).
9
+ */
10
+ path: string;
11
+ }
12
+ /** The explicit-pierce projection: what would happen if the consumer named this path explicitly. */
13
+ export interface ExplicitProjection {
14
+ /**
15
+ * False only when an enforced stone cut or a strict-channel hit blocks the
16
+ * path (the stone is a structural terminal, strict is immune even to the
17
+ * override whitelist — explicit naming is override-channel semantics and
18
+ * cannot pierce either). Every other layer (presets, cascade, policy, dot)
19
+ * is pierceable: naming a path is the terminal include.
20
+ */
21
+ pierceable: boolean;
22
+ /**
23
+ * The blocking hits (enforced stones / strict rules), in chain order.
24
+ * A stone blocker carries `enforced: true` by definition (only enforced
25
+ * stones block) — the field is load-bearing in `hitChain` (where it
26
+ * separates report-not-cut metadata) and tautological here; renderers may
27
+ * omit it.
28
+ */
29
+ blockers: HitEntry[];
30
+ }
31
+ /** Result of {@link explainScopePath}. */
32
+ export interface ExplanationResult {
33
+ /**
34
+ * The rule-space verdict: true = the exclusion stack excludes this path.
35
+ * For a path on disk under an un-cut budget this equals "absent from a
36
+ * walkScope result"; the two caveats are both by design — the loud budget
37
+ * is a walk-chassis concern the probe never reflects (a budget-cut walk
38
+ * omits files this API rightly reports as included), and for a
39
+ * nonexistent path `excluded: false` means "nothing in the rule space
40
+ * excludes it" (walkScope membership is undefined for paths that do not
41
+ * exist — the consumer's status branch owns existence separately).
42
+ */
43
+ excluded: boolean;
44
+ /**
45
+ * True when the verdict comes from a directory-level adjudication — an
46
+ * excluded ancestor (the whole subtree rides the prune) or the queried
47
+ * directory itself being cut. Rule answers on the queried path are
48
+ * non-structural.
49
+ */
50
+ structural: boolean;
51
+ /**
52
+ * The adjudication record: every layer that matched, in full-stack
53
+ * priority order (stone → strict → override → combined table → dot);
54
+ * within the combined table entries follow the rule stream (presets →
55
+ * cascade → folds → policy rear seat), so the last table entry is the
56
+ * last-match-wins winner. The chain is not only the verdict's cause — an
57
+ * included path can carry hits (the preset hit, then the override that
58
+ * rescued it), and a stone entry with `enforced: false` is report-only
59
+ * metadata (the scanner face's report-not-cut: it did not produce the
60
+ * verdict).
61
+ *
62
+ * For a structural answer the chain is EXACTLY the excluded ancestor's
63
+ * adjudication record: adjudication does not continue below the prune,
64
+ * so the query path's own rule hits are absent by construction (the
65
+ * pruned subtree's `.gitignore` is never folded). What still matters
66
+ * below the prune — enforced stones and strict hits — surfaces in
67
+ * {@link ExplicitProjection.blockers} instead.
68
+ */
69
+ hitChain: HitEntry[];
70
+ explicit: ExplicitProjection;
71
+ }
72
+ /**
73
+ * Point-query one path against the same scope request a walk would resolve:
74
+ * `explainScopePath(root, 'pkg/lib.ts', options)` answers whether that path
75
+ * is in scope and exactly which layer decided it. Nonexistent paths
76
+ * adjudicate hypothetically over the rule space (the stone probes report
77
+ * the IO facts as they are) — a status query asks precisely about on-disk
78
+ * paths that never entered an index. The scan root itself returns the
79
+ * universe-boundary fact (`excluded: false`, empty chain). Read-only: no
80
+ * exclusion source is added, no matching behavior changes, walkScope output
81
+ * is untouched.
82
+ *
83
+ * Input form: `relPath` is scan-root-relative POSIX; a leading `./` is
84
+ * stripped (so `''`, `'.'`, and `'./'` all name the scan root itself); a
85
+ * trailing slash is the OPERATOR selecting directory-order adjudication (a
86
+ * slash-less query always adjudicates file-order, even for an existing
87
+ * directory); an empty segment INSIDE the path (`a//b`) is rejected. The
88
+ * `root` argument takes any form `path.resolve` accepts — relative or
89
+ * absolute, native separators included — exactly like walkScope. Each call
90
+ * is self-contained over a dedicated engine instance — calls are
91
+ * independent and safe to run in parallel. Symlinks are not resolved;
92
+ * `followSymlinks` and `maxFiles` are walk-chassis options, accepted and
93
+ * ignored. A symlinked FINAL segment adjudicates by its own name (never
94
+ * resolved); intermediate reads (stone probes, `.gitignore`) follow the
95
+ * filesystem as any read does. Many-paths workloads: there is no batch
96
+ * face yet (deferred) — each call is self-contained, so run concurrent
97
+ * queries concurrently.
98
+ *
99
+ * The probe covers the WALK face only; the ask-git face (gitUniverse) has
100
+ * no point query — git itself answers those questions. IO rides the node
101
+ * filesystem — an injectable-IO probe face (URI/remote filesystems, the
102
+ * composable engine's ExclusionIO route) is deferred, not provided.
103
+ *
104
+ * @throws PathscopeConfigError when `relPath` is out of domain (absolute
105
+ * path, backslash separator, `..` escape, empty inner segment) or the scan
106
+ * root does not exist — the same fail-loud family as every other malformed
107
+ * input.
108
+ */
109
+ export declare function explainScopePath(root: string, relPath: string, options?: ScopeOptions): Promise<ExplanationResult>;
@@ -6,15 +6,19 @@
6
6
  * cascade on the node-ignore kernel, mounted exclusion presets, override
7
7
  * whitelist, strict immune channel, boundary stones, and a loud budget) or
8
8
  * ask-git mode (gitUniverse — git is the truth, the exclusion stack does not
9
- * participate). Config discovery (locateNearest) locates the nearest config
10
- * residence and never parses it. Consumers that own their own traversal
11
- * (incremental snapshots, watcher feeds, URI/remote filesystems) compose the
12
- * same exclusion stack + cascade as a standalone decision core:
13
- * createExclusionEngine.
9
+ * participate). The read-only probe face (explainScopePath) answers a
10
+ * membership point query over the same scope request — excluded plus the
11
+ * hit chain that decided it. Config discovery (locateNearest) locates the
12
+ * nearest config residence and never parses it. Consumers that own their
13
+ * own traversal (incremental snapshots, watcher feeds, URI/remote
14
+ * filesystems) compose the same exclusion stack + cascade as a standalone
15
+ * decision core: createExclusionEngine.
14
16
  */
15
17
  export { walkScope } from './engine.ts';
16
18
  export { createExclusionEngine, nodeExclusionIO } from './exclusion-engine.ts';
17
- export type { ExclusionEngine, ExclusionIO } from './exclusion-engine.ts';
19
+ export type { DirectoryAdjudication, ExclusionEngine, ExclusionIO, FileAdjudication, HitSource, LayerHit } from './exclusion-engine.ts';
20
+ export { explainScopePath } from './explain.ts';
21
+ export type { ExplicitProjection, ExplanationResult, HitEntry } from './explain.ts';
18
22
  export { clearUniverseCache, gitUniverse } from './universe.ts';
19
23
  export { locateNearest } from './discover.ts';
20
24
  export { PRESETS, DEFAULT_MOUNTED_PRESETS } from './presets.ts';