@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.
@@ -0,0 +1,193 @@
1
+ /**
2
+ * explainScopePath — the read-only per-path probe face (06 seam extension,
3
+ * 2026-10-31 frozen contract). One scope request, a third resolution:
4
+ * walkScope enumerates the set, gitUniverse lists it, the probe answers a
5
+ * membership POINT QUERY — `excluded` plus the hit chain that produced it.
6
+ *
7
+ * Consistency mechanism: a DEDICATED engine instance replaying the ancestor
8
+ * chain — every ancestor directory is adjudicated exactly as the walk would
9
+ * (stone probes over the same IO face, gitignore folded only for descended
10
+ * directories), then the final segment adjudicates by file order (or
11
+ * directory order for a trailing-slash query). The equivalence argument is
12
+ * the subtree-anchoring invariant: folded rules are re-anchored under their
13
+ * directory's prefix, so folds from non-ancestor directories cannot match
14
+ * the queried path — the replay state equals the walk's state at the moment
15
+ * it reaches the path. The corpus-wide equivalence fixture gate pins this.
16
+ *
17
+ * Structural answers: an ancestor excluded with no directory-level rescue
18
+ * makes the answer structural — the chain attributes to that ancestor and
19
+ * the pruned subtree's .gitignore never folds (deep rules do not
20
+ * participate, mirroring the walk's prune). The explicit projection still
21
+ * walks the remaining chain in projection mode (stone probes + strict
22
+ * only): those are the two channels explicit naming can never pierce.
23
+ */
24
+ import { existsSync } from 'node:fs';
25
+ import { resolve } from 'node:path';
26
+ import { createExclusionEngine, nodeExclusionIO } from './exclusion-engine.js';
27
+ import { PathscopeConfigError } from './types.js';
28
+ /**
29
+ * Validate the query path: scan-root-relative POSIX form. Absolute paths,
30
+ * backslash separators, `..` escapes, and double slashes are rejected as
31
+ * configuration errors — one canonical input form. Returns the normalized
32
+ * segments plus whether the query named a directory (trailing slash).
33
+ */
34
+ function parseRelPath(relPath) {
35
+ if (typeof relPath !== 'string') {
36
+ throw new PathscopeConfigError('relPath must be a scan-root-relative POSIX path string');
37
+ }
38
+ if (relPath.includes('\\')) {
39
+ throw new PathscopeConfigError(`relPath "${relPath}" contains a backslash — pass POSIX-separator form`);
40
+ }
41
+ if (relPath.startsWith('/')) {
42
+ throw new PathscopeConfigError(`relPath "${relPath}" is absolute — pass a scan-root-RELATIVE path`);
43
+ }
44
+ const isDir = relPath.endsWith('/');
45
+ let core = relPath;
46
+ while (core.startsWith('./'))
47
+ core = core.slice(2);
48
+ if (core === '.' || core === '')
49
+ return { segments: [], isDir: true, isRoot: true };
50
+ const segments = core.replace(/\/+$/, '').split('/');
51
+ for (const seg of segments) {
52
+ if (seg === '') {
53
+ throw new PathscopeConfigError(`relPath "${relPath}" has an empty segment (double slash)`);
54
+ }
55
+ if (seg === '.' || seg === '..') {
56
+ throw new PathscopeConfigError(`relPath "${relPath}" escapes the scan root (".", ".." segments)`);
57
+ }
58
+ }
59
+ return { segments, isDir, isRoot: false };
60
+ }
61
+ /**
62
+ * Point-query one path against the same scope request a walk would resolve:
63
+ * `explainScopePath(root, 'pkg/lib.ts', options)` answers whether that path
64
+ * is in scope and exactly which layer decided it. Nonexistent paths
65
+ * adjudicate hypothetically over the rule space (the stone probes report
66
+ * the IO facts as they are) — a status query asks precisely about on-disk
67
+ * paths that never entered an index. The scan root itself returns the
68
+ * universe-boundary fact (`excluded: false`, empty chain). Read-only: no
69
+ * exclusion source is added, no matching behavior changes, walkScope output
70
+ * is untouched.
71
+ *
72
+ * Input form: `relPath` is scan-root-relative POSIX; a leading `./` is
73
+ * stripped (so `''`, `'.'`, and `'./'` all name the scan root itself); a
74
+ * trailing slash is the OPERATOR selecting directory-order adjudication (a
75
+ * slash-less query always adjudicates file-order, even for an existing
76
+ * directory); an empty segment INSIDE the path (`a//b`) is rejected. The
77
+ * `root` argument takes any form `path.resolve` accepts — relative or
78
+ * absolute, native separators included — exactly like walkScope. Each call
79
+ * is self-contained over a dedicated engine instance — calls are
80
+ * independent and safe to run in parallel. Symlinks are not resolved;
81
+ * `followSymlinks` and `maxFiles` are walk-chassis options, accepted and
82
+ * ignored. A symlinked FINAL segment adjudicates by its own name (never
83
+ * resolved); intermediate reads (stone probes, `.gitignore`) follow the
84
+ * filesystem as any read does. Many-paths workloads: there is no batch
85
+ * face yet (deferred) — each call is self-contained, so run concurrent
86
+ * queries concurrently.
87
+ *
88
+ * The probe covers the WALK face only; the ask-git face (gitUniverse) has
89
+ * no point query — git itself answers those questions. IO rides the node
90
+ * filesystem — an injectable-IO probe face (URI/remote filesystems, the
91
+ * composable engine's ExclusionIO route) is deferred, not provided.
92
+ *
93
+ * @throws PathscopeConfigError when `relPath` is out of domain (absolute
94
+ * path, backslash separator, `..` escape, empty inner segment) or the scan
95
+ * root does not exist — the same fail-loud family as every other malformed
96
+ * input.
97
+ */
98
+ export async function explainScopePath(root, relPath, options = {}) {
99
+ const { segments, isDir, isRoot } = parseRelPath(relPath);
100
+ // Root resolution mirrors walkScope verbatim (resolve → existence → POSIX key).
101
+ const rootNative = resolve(root);
102
+ if (!existsSync(rootNative)) {
103
+ throw new PathscopeConfigError(`scan root does not exist: ${rootNative}`);
104
+ }
105
+ const baseKey = rootNative.replace(/\\/g, '/').replace(/\/+$/, '');
106
+ const engine = await createExclusionEngine(baseKey, options);
107
+ const io = nodeExclusionIO;
108
+ /** Stone probe for one directory key — the same per-name probes the walk glue performs. */
109
+ const probeStones = async (dirKey) => {
110
+ const hits = [];
111
+ for (const name of engine.stoneNames) {
112
+ if (await io.exists(dirKey, name))
113
+ hits.push(name);
114
+ }
115
+ return hits;
116
+ };
117
+ const withPath = (hits, path) => hits.map((h) => ({ ...h, path }));
118
+ if (isRoot) {
119
+ // The scan root is the universe boundary: never excluded, nothing
120
+ // adjudicates it, nothing blocks explicit naming.
121
+ return { excluded: false, structural: false, hitChain: [], explicit: { pierceable: true, blockers: [] } };
122
+ }
123
+ const hitChain = [];
124
+ const blockers = [];
125
+ const keys = [];
126
+ let key = baseKey;
127
+ for (const seg of segments) {
128
+ key = `${key}/${seg}`;
129
+ keys.push(key);
130
+ }
131
+ // ---- verdict replay: ancestors first, then the final segment -------------
132
+ let excluded;
133
+ let structural = false;
134
+ let stoppedDepth = -1;
135
+ for (let i = 0; i < segments.length; i++) {
136
+ const name = segments[i];
137
+ const relHere = segments.slice(0, i + 1).join('/');
138
+ const isLeaf = i === segments.length - 1;
139
+ const adjudicateAsDir = isLeaf ? isDir : true;
140
+ if (adjudicateAsDir) {
141
+ const stoneHit = await probeStones(keys[i]);
142
+ const adj = engine.adjudicateDirectory(name, keys[i], stoneHit);
143
+ hitChain.push(...withPath(adj.hits, relHere));
144
+ if (adj.excluded) {
145
+ // Structural: the prune at this directory carries the whole subtree.
146
+ excluded = true;
147
+ structural = true;
148
+ stoppedDepth = i;
149
+ break;
150
+ }
151
+ // Descending: fold this layer's .gitignore, exactly as the walk glue does.
152
+ engine.foldGitignore(keys[i], await io.readGitignore(keys[i]));
153
+ if (isLeaf)
154
+ excluded = false;
155
+ }
156
+ else {
157
+ const adj = engine.adjudicateFile(relHere);
158
+ hitChain.push(...withPath(adj.hits, relHere));
159
+ excluded = !adj.admitted;
160
+ }
161
+ }
162
+ // ---- explicit projection --------------------------------------------------
163
+ // Blockers from the adjudicated chain: enforced stones and strict hits.
164
+ for (const hit of hitChain) {
165
+ if (hit.source === 'strict' || (hit.source === 'stone' && hit.enforced !== false)) {
166
+ blockers.push(hit);
167
+ }
168
+ }
169
+ // Under a structural stop the rule adjudication must NOT continue (pruned
170
+ // rules never participate), but stone facts and strict are exactly the
171
+ // projection's questions — keep probing the remaining chain.
172
+ if (stoppedDepth >= 0 && stoppedDepth < segments.length - 1) {
173
+ for (let j = stoppedDepth + 1; j < segments.length; j++) {
174
+ const relHere = segments.slice(0, j + 1).join('/');
175
+ const isLeaf = j === segments.length - 1;
176
+ const asDir = isLeaf ? isDir : true;
177
+ if (asDir) {
178
+ blockers.push(...withPath(engine.attributeStones(relHere, await probeStones(keys[j])), relHere));
179
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, true).hits, relHere));
180
+ }
181
+ else {
182
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, false).hits, relHere));
183
+ }
184
+ }
185
+ }
186
+ return {
187
+ excluded: excluded ?? false,
188
+ structural,
189
+ hitChain,
190
+ explicit: { pierceable: blockers.length === 0, blockers },
191
+ };
192
+ }
193
+ //# sourceMappingURL=explain.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -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';
package/dist/index.js CHANGED
@@ -6,14 +6,17 @@
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.js';
16
18
  export { createExclusionEngine, nodeExclusionIO } from './exclusion-engine.js';
19
+ export { explainScopePath } from './explain.js';
17
20
  export { clearUniverseCache, gitUniverse } from './universe.js';
18
21
  export { locateNearest } from './discover.js';
19
22
  export { PRESETS, DEFAULT_MOUNTED_PRESETS } from './presets.js';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
package/dist/types.d.ts CHANGED
@@ -206,8 +206,8 @@ export interface UniverseResult {
206
206
  /** Repository root as git reports it (`rev-parse --show-toplevel`). */
207
207
  repoRoot: string;
208
208
  /**
209
- * Diagnostics; always empty in 0.1.0 (the universe has no budget — git is
210
- * the authority, not a traversal that could be cut). The field exists for
209
+ * Diagnostics; always empty (the universe has no budget — git is the
210
+ * authority, not a traversal that could be cut). The field exists for
211
211
  * shape parity with {@link WalkResult}.
212
212
  */
213
213
  diagnostics: ScanDiagnostic[];
package/docs/glossary.md CHANGED
@@ -1,10 +1,10 @@
1
1
  ---
2
- description: Consumer glossary of the pathscope vocabulary — the two resolution modes, the exclusion stack layers, boundary markers, alignment and the fail-loud reliability nouns
2
+ description: Consumer glossary of the pathscope vocabulary — the three resolution faces (walk, ask-git, point query), the exclusion stack layers, boundary markers, alignment, the probe nouns and the fail-loud reliability nouns
3
3
  ---
4
4
 
5
5
  # Glossary
6
6
 
7
- The vocabulary pathscope uses, in one place. Terms are sorted from the top down: read the first six and every README example parses; the rest matter when you tune the stack.
7
+ The vocabulary pathscope uses, in one place. Terms are sorted from the top down: read the core nouns plus the probe face and every README example parses; the rest matters when you tune the stack.
8
8
 
9
9
  ## The core nouns
10
10
 
@@ -16,10 +16,30 @@ The vocabulary pathscope uses, in one place. Terms are sorted from the top down:
16
16
 
17
17
  **Ask-git mode** — resolving the path scope by asking git instead of walking (`git ls-files` under the hood). Git is the truth: the exclusion stack does not participate by default. Rides `gitUniverse`. Mutually exclusive with walk mode — one scope request goes through one of the two, never a blend.
18
18
 
19
+ **Point query** — resolving ONE path instead of the whole set: `explainScopePath(root, relPath, options?)` answers whether the path is in scope and exactly which layer decided. The read-only third face over the same scope request (walk mode enumerates, ask-git lists, the point query adjudicates); nonexistent paths answer hypothetically over the rule space.
20
+
21
+ **Rule space** — the full set of adjudicating rules for one scope request: mounted presets, every gitignore layer (root, nested, inherited), the policy layer, plus the non-rule layers (stones, strict, override, dot). A point query's `excluded` is the rule-space verdict — it equals walkScope membership for paths on disk under an un-cut budget; the budget is a walk-chassis concern outside the rule space, and walkScope membership is undefined for paths that do not exist.
22
+
19
23
  **Composable exclusion engine** — the exclusion stack + gitignore cascade as a standalone engine (`createExclusionEngine`). For consumers that own their own traversal — watchers, incremental snapshots, virtual filesystems — and cannot use the built-in walker.
20
24
 
25
+ **Walk chassis** — the traversal wrapper that owns the loud budget and symlink following (`walkScope`); the decision core (exclusion stack + cascade) is shared by every face. The point query and the composable engine are chassis-free: they accept the chassis options and ignore them.
26
+
21
27
  **Nearest config file** — a configuration file located on the way up from a starting directory; the nearest one wins (`locateNearest`). pathscope only locates it, never reads or parses it.
22
28
 
29
+ ## The probe face
30
+
31
+ The vocabulary a point query's answer is made of.
32
+
33
+ **Hit chain** — the ordered adjudication record a point query returns: every layer that matched, in stack-priority order (stones → strict → override → the combined rule table → dot entries); within the combined table, stream order (presets → cascade → your excludes), so the last table entry is the last-match-wins winner. The chain is not empty only on exclusions — a rescued path tells its story too (the preset hit, then the override that saved it).
34
+
35
+ **Hit entry** — one link of the chain: the source layer plus its attribution — the preset name, or the gitignore layer anchor with the rule as written, or the stone name, or the strict/override/policy pattern — and `path`, the path the hit adjudicated: the queried path for rule answers, the excluded ancestor for structural ones.
36
+
37
+ **Structural answer** — a point-query verdict that came from a directory-level prune: an excluded ancestor (the whole subtree rides the prune and the pruned layer's own rules never participate) or the queried directory itself being cut (a trailing-slash query). `structural: true` means the verdict is a place, not a rule.
38
+
39
+ **Layer anchor** — where a gitignore hit's rule lives: `''` is the scan root's own `.gitignore`, a relative directory (e.g. `sub`) is a nested layer inside the scan, and `inherited:..` names a layer above the scan root (one `..` per level up). The rule space is **repository-local**: git's global excludes (`core.excludesFile`) and `.git/info/exclude` do not participate — reconcile against `git check-ignore` accordingly.
40
+
41
+ **Explicit projection** — the point query's built-in answer to "what if I name this path explicitly": `pierceable` is false only when an enforced stone or a strict rule blocks; every other layer yields to explicit naming (naming a path is override-channel semantics). A mechanism, not a policy — whether to report, warn, or refuse a pierceable path is the consumer's call.
42
+
23
43
  ## The exclusion stack
24
44
 
25
45
  **Default ignore preset** — a named group of default exclusions (VCS internals, dependencies, build outputs, caches, agent docs). Mounting is append-only and presets sit at the FRONT of the rule table: any named negation (`!vendor/`) in a gitignore layer or in your `exclude` option can walk an entry back out. There is no wholesale-replacement channel.
@@ -34,6 +54,10 @@ The vocabulary pathscope uses, in one place. Terms are sorted from the top down:
34
54
 
35
55
  **Whole-tree pruning** — when a directory is excluded with no rescue, its entire subtree disappears from the scope, and its own `.gitignore` is never applied — its `!` rules cannot leak onto the rest of the walk.
36
56
 
57
+ **Dot entries** — names starting with a dot (`.env`, `.gitignore` itself). A walk-layer category, not a gitignore rule: excluded by default (`excludeDotEntries`, the ripgrep `hidden` semantics), and rescuable by the override whitelist. A point query reports the category as its own chain source (`'dot'`).
58
+
59
+ **Exemption** — the named-subtree registration of boundary markers (`boundaryStones.exempt`, e.g. `'embedded-toolkit/'`): naming a subtree neutralizes its OWN core/`.gitignore` marker hits, so it descends as a native subtree — the submodule-registration analogue. A neutralized hit still reports in the chain, as `enforced: false`. Registration, not rescue: deeper markers inside it are still markers, and config-home markers are never exemptible.
60
+
37
61
  ## Boundary markers
38
62
 
39
63
  The API names this option `boundaryStones`; markers is the plain word for what they are.
@@ -46,7 +70,7 @@ The API names this option `boundaryStones`; markers is the plain word for what t
46
70
 
47
71
  **`.gitignore` boundary marker** — the opt-in variant (`gitignoreProxy`) that treats a nested `.gitignore` as a boundary signal instead of more rules. Off by default: mainstream treats a nested `.gitignore` as rules, not territory.
48
72
 
49
- **Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
73
+ **Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). A hit is either **enforced** (the cut executes) or report-only (`enforced: false` — the scanner alignment's report-not-cut: metadata, no cut). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
50
74
 
51
75
  ## Alignment
52
76
 
package/docs/semantics.md CHANGED
@@ -64,10 +64,20 @@ With `alignment: 'scanner'` (ripgrep-style):
64
64
 
65
65
  Presets are un-excludable by design: a named negation (`!vendor/`) in any gitignore layer or in your `exclude` option un-excludes a preset entry. There is no wholesale-replacement channel — `mountPresets` is append-only.
66
66
 
67
+ ## Point queries (the read-only probe)
68
+
69
+ `explainScopePath(root, relPath, options?)` is the third way to resolve one scope request: instead of enumerating the set (`walkScope`) or asking git (`gitUniverse`), it answers a membership point query — **is this path excluded, and exactly which layer decided?** Read-only: no exclusion source is added, no matching behavior changes, `walkScope` output is untouched.
70
+
71
+ - **Consistency**: the probe replays the ancestor chain over a dedicated engine instance (the same construction inputs), adjudicating every ancestor directory exactly as the walk would — stones probed, gitignores folded only for descended directories. A corpus-wide equivalence gate pins probe verdicts against the same fixture expectations `walkScope` answers. `excluded` is the rule-space verdict — it equals "absent from a walkScope result" for paths on disk under an un-cut budget; the loud budget is a walk-chassis concern the probe never reflects, 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).
72
+ - **Structural answers**: an ancestor excluded with no directory-level rescue makes the answer structural — `excluded: true, structural: true`, the chain attributes to that ancestor, and the pruned subtree's `.gitignore` never participates. A directory-shaped query (trailing slash) cut at its own adjudication is structural the same way: the prune is the answer. 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 by construction; what still matters below it (enforced stones, strict hits) surfaces in the explicit projection's blockers.
73
+ - **The hit chain**: the adjudication record, in full-stack priority order (stones → strict → override → combined table → dot); within the combined table, stream order (presets → cascade → policy rear seat) so the last table entry is the last-match-wins winner. The chain reports every layer that matched — 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 (it did not produce the verdict; an exemption-neutralized hit reports this way too). Each entry carries its attribution — `presetName`, the gitignore layer anchor (`''` = the scan root's own layer, a relative directory without trailing slash (e.g. `sub`) = a nested layer, `inherited:..` = a layer above the root, one `..` per level) plus the rule text **as written** (re-anchoring stays internal), or the stone name with `enforced` (under `alignment: 'scanner'` the core stone is reported `enforced: false` — report-not-cut). The rule space is **repository-local**: git's global excludes (`core.excludesFile`) and `.git/info/exclude` never participate — `git check-ignore` may therefore flag paths the probe includes.
74
+ - **Explicit projection**: `explicit.pierceable` is false only when an enforced stone cut or a strict hit blocks the path — those two channels outrank even the override whitelist, and explicit naming is override-channel semantics. Everything else (presets, cascade, policy, dot) is pierceable. The projection is a mechanism, not a policy: what to do with a pierceable path (report, warn, refuse) is the consumer's call.
75
+ - **Input domain**: scan-root-relative POSIX paths; a leading `./` is stripped (`''`, `'.'`, `'./'` all name the scan root itself, which returns the boundary fact: `excluded: false`, empty chain); the trailing slash is the **operator** that selects directory-order adjudication — a slash-less query always adjudicates file-order, even for an existing directory. Nonexistent paths adjudicate hypothetically over the rule space — the status-query shape. Absolute paths, backslashes, `..` escapes, and empty inner segments are rejected as configuration errors (`PathscopeConfigError`); the `root` argument takes any form `path.resolve` accepts, exactly like walkScope. Each call is self-contained over a dedicated engine instance — calls are independent and safe to run in parallel; symlinks are not resolved (`followSymlinks` / `maxFiles` are walk-chassis options, accepted and ignored). The probe covers the walk face only; the ask-git face has no point query — git itself answers those questions. The inherited anchor's reach: the construction phase reads `.gitignore` files from the scan root up to the enclosing repository's root (or the disk root outside a repository), shallow first.
76
+
67
77
  ## Walk defaults
68
78
 
69
79
  - Output: POSIX relative paths, sorted.
70
80
  - `excludeDotEntries` (default `true`): rg `hidden` semantics — a walk-layer option, not a gitignore rule; `override` can rescue dot entries.
71
81
  - `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before (rg `--no-ignore`).
72
82
  - Symlinks are not resolved by default (git/ripgrep default).
73
- - `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination.
83
+ - `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination. `explainScopePath` is the read-only third face over the same request: it adjudicates, it never enumerates.
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@catheadowl/pathscope",
3
- "version": "0.1.0",
4
- "description": "Cross-repo shared engine resolving the in-scope file set: walk, gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
3
+ "version": "0.2.0",
4
+ "description": "Cross-repo shared engine resolving the in-scope file set: walk or per-path point queries (excluded + why), gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
8
- "url": "git+https://github.com/catheadowl/pathscope.git"
8
+ "url": "git+https://github.com/CatheadOwl/pathscope.git"
9
9
  },
10
10
  "type": "module",
11
11
  "engines": {
@@ -19,14 +19,17 @@
19
19
  "CHANGELOG.md"
20
20
  ],
21
21
  "publishConfig": {
22
- "access": "public"
22
+ "access": "public",
23
+ "provenance": false
23
24
  },
24
25
  "scripts": {
25
26
  "build": "tsc -p tsconfig.build.json && node scripts/build-cjs.mjs",
26
27
  "typecheck": "tsc --noEmit",
28
+ "lint:face": "node scripts/published-face-lint.mjs",
27
29
  "test": "node --test \"test/*.test.ts\"",
28
30
  "oracle": "node scripts/git-oracle.mjs",
29
31
  "oracle:fix": "node scripts/git-oracle.mjs --update",
32
+ "oracle:crate": "node scripts/ignore-crate-oracle.mjs",
30
33
  "prepack": "pnpm run build && pnpm run test"
31
34
  },
32
35
  "dependencies": {