@catheadowl/pathscope 0.1.1 → 0.3.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,78 @@ 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.3.0 — 2026-11-13
11
+
12
+ ### Added
13
+
14
+ - **walk stone report** (2026-11-13 owner ruling — the report-not-cut
15
+ principle carried onto the walk result): `walkScope` results carry
16
+ `stoneHits` — every boundary-stone hit the walk discovered, as
17
+ `{ stoneName, path, enforced }`. One walk now tells you which subtrees are
18
+ independent repositories (or declared config-home sub-domains) and where:
19
+ `enforced: true` on the default git face names the truncation locations;
20
+ under `alignment: 'scanner'` core-stone hits report `enforced: false`
21
+ (report-not-cut metadata) and the walk descends; exemption-neutralized hits
22
+ report `enforced: false` (registration, not rescue); config-home hits stay
23
+ `enforced: true` under every face. Pure metadata — the file set is untouched,
24
+ output is sorted (path, then stone name), the scan root's own markers are
25
+ not reported, and conformance fixture 38 pins the membership invariants.
26
+
27
+ ### Changed
28
+
29
+ - **preset vocabulary additions** (adopted 2026-11-13): `venv` and
30
+ `.gradle` join the opt-in `caches` group (both in repomix's defaultIgnore;
31
+ `venv` also in github's Python template — watchfiles carries `.venv` only);
32
+ the `build` group gains the **root-anchored** `/target` — the cargo/maven
33
+ build tree, anchored exactly because `target` is collision-grade (the Rust
34
+ toolchain's own adjudication: cargo#3158 → `cargo new` generates `/target`).
35
+ The anchored entry matches only a `target` directory AT the scan root
36
+ (re-anchored accordingly when the scan root sits below a repo root) —
37
+ nested same-named directories are untouched, and `!target/` un-excludes it
38
+ like every preset entry. `caches` is not default-mounted (no default
39
+ change); `build` is, so default scans now skip a scan-root `target/` —
40
+ projects whose scan root legitimately holds content in `target/` name their
41
+ way out with `!target/`. A `dirs` entry may now carry a leading slash
42
+ (scan-root anchor) — plain gitignore anchoring, no new matching semantics.
43
+
44
+ ## 0.2.0 — 2026-11-01
45
+
46
+ ### Added
47
+
48
+ - **per-path probe** — `explainScopePath(root, relPath, options?)`: the
49
+ read-only point-query face over the same scope request. Returns
50
+ `{ excluded, structural, hitChain, explicit }` — the membership verdict,
51
+ whether it came from a directory-level prune (an excluded ancestor, or the
52
+ queried directory itself), the ordered hit chain attributing every
53
+ matching layer (preset name / gitignore layer anchor + the rule as
54
+ written / stone name with the scanner face's report-not-cut fact /
55
+ strict, override, policy, dot), and the explicit-pierce projection
56
+ (`pierceable` = no enforced stone and no strict hit; the policy of what
57
+ to do with a pierceable path stays consumer-side). Nonexistent paths
58
+ adjudicate hypothetically; the scan root returns the boundary fact;
59
+ out-of-domain inputs (`..`, absolute, backslash) fail loudly. Verdict
60
+ equivalence with `walkScope` membership is pinned by the whole conformance
61
+ corpus (37 fixtures, both provenance kinds) through the same
62
+ fixture→options mapping.
63
+ - **engine attribution faces** — `createExclusionEngine` gains
64
+ `adjudicateDirectory` / `adjudicateFile` (the boolean faces delegate to
65
+ them — identical verdicts by construction) plus the narrow projection
66
+ faces `attributeStones` / `adjudicateStrict`. The combined rule table is
67
+ now maintained per-rule with provenance alongside the verdict instances;
68
+ the verdict path is byte-identical (the unchanged-green corpus is the
69
+ zero-matching-deviation evidence).
70
+ - **ignore-crate conformance judge** — `scripts/ignore-crate-oracle.mjs`
71
+ (+ cargo-gated test, `npm run oracle:crate`): a second reference anchor
72
+ that re-adjudicates every git-oracle fixture against ripgrep's library
73
+ core (`ignore` crate) over its public walk face. First run registered two
74
+ acknowledged anchor-limit divergences (char-class edges where the crate's
75
+ globset parts from git wildmatch while pathscope's kernel agrees with
76
+ git) — git remains the sole expectation generator; unexpected drift
77
+ fails the gate.
78
+ - conformance fixtures 36 (structural ancestor: a pruned subtree's own
79
+ rules never participate) and 37 (mixed attribution chain: preset front →
80
+ cascade shallow→deep → policy rear).
81
+
10
82
  ## 0.1.1 — 2026-10-31
11
83
 
12
84
  Maintenance release — no library changes. CI publishing switched to npm
package/README.md CHANGED
@@ -2,12 +2,14 @@
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
+ - **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.
10
11
  - **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.
12
+ - **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
13
  - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
12
14
  - **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
15
  - **ESM + CommonJS** — dual build, Node.js >= 20.
@@ -25,12 +27,20 @@ import { walkScope } from '@catheadowl/pathscope';
25
27
 
26
28
  // Default stack: gitignore cascade + vcs/deps/build presets + dot entries
27
29
  // excluded + loud budget (2000).
28
- const { files, diagnostics } = await walkScope('/repo');
30
+ const { files, diagnostics, stoneHits } = await walkScope('/repo');
29
31
  console.log(files);
30
32
  //=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
31
33
 
32
34
  console.log(diagnostics);
33
35
  //=> [] — non-empty means the budget cut the scan (code: 'budget-exceeded')
36
+
37
+ console.log(stoneHits);
38
+ //=> [{ stoneName: '.git', path: 'embedded-toolkit', enforced: true }]
39
+ // — every stone hit the walk discovered: which subtrees are independent
40
+ // repositories (or declared sub-domains) and where. `enforced: true` on the
41
+ // default git face names where the truncation happened; under
42
+ // alignment: 'scanner' the core stone reports enforced: false and the
43
+ // walk descends. Pure metadata — the file set never changes because of it.
34
44
  ```
35
45
 
36
46
  All output paths are POSIX-style relative to the scanned root, sorted.
@@ -46,6 +56,41 @@ const { files } = await walkScope('/repo', {
46
56
  });
47
57
  ```
48
58
 
59
+ ### Ask one path: excluded, and why
60
+
61
+ `explainScopePath` is the read-only probe over the same scope request — the diagnostic face for "why is this file not in scope":
62
+
63
+ ```js
64
+ import { explainScopePath } from '@catheadowl/pathscope';
65
+
66
+ const answer = await explainScopePath('/repo', 'node_modules/pkg/index.js');
67
+ // {
68
+ // excluded: true,
69
+ // structural: true, // a directory-level prune carries the subtree
70
+ // hitChain: [
71
+ // { source: 'preset', presetName: 'deps', ruleText: 'node_modules/',
72
+ // path: 'node_modules' }, // the hit adjudicated the ANCESTOR
73
+ // ],
74
+ // explicit: { pierceable: true, blockers: [] }, // naming it would pierce
75
+ // }
76
+
77
+ // Same scope request as a walk — pass the SAME options you pass walkScope:
78
+ const same = await explainScopePath('/repo', 'sandbox/x.snapshot.md', {
79
+ mountPresets: ['vcs', 'deps', 'build', 'caches'],
80
+ exclude: ['sandbox/'],
81
+ });
82
+ ```
83
+
84
+ 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.
85
+
86
+ Fine print worth knowing before your first call:
87
+
88
+ - `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).
89
+ - 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`.
90
+ - `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.
91
+ - 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.
92
+ - 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.
93
+
49
94
  ### Ask git instead of walking
50
95
 
51
96
  ```js
@@ -103,10 +148,13 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
103
148
 
104
149
  | Export | One-line |
105
150
  | --- | --- |
106
- | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics }` |
151
+ | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics, stoneHits }` |
152
+ | `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
107
153
  | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
108
154
  | `locateNearest(names, options?)` | Nearest config file, no parsing |
109
155
  | `createExclusionEngine(root, options?, io?)` | The exclusion engine for your own traversal |
156
+ | `nodeExclusionIO` | The node-filesystem default `ExclusionIO` for the engine |
157
+ | `clearUniverseCache()` | Reset `gitUniverse`'s repo-root memoization (test seam) |
110
158
  | `PRESETS` / `DEFAULT_MOUNTED_PRESETS` | Preset contents |
111
159
  | `PathscopeConfigError` / `PathscopeGitError` | Fail-loud error classes |
112
160
 
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;
@@ -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,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';