@catheadowl/pathscope 0.1.1 → 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 +38 -0
- package/README.md +40 -1
- package/dist/cascade.d.ts +6 -0
- package/dist/cascade.js +21 -11
- package/dist/cascade.js.map +1 -1
- package/dist/cjs/cascade.d.ts +6 -0
- package/dist/cjs/exclusion-engine.d.ts +71 -1
- package/dist/cjs/explain.d.ts +109 -0
- package/dist/cjs/index.d.ts +10 -6
- package/dist/cjs/index.js +295 -73
- package/dist/cjs/types.d.ts +2 -2
- package/dist/exclusion-engine.d.ts +71 -1
- package/dist/exclusion-engine.js +234 -93
- package/dist/exclusion-engine.js.map +1 -1
- package/dist/explain.d.ts +109 -0
- package/dist/explain.js +193 -0
- package/dist/explain.js.map +1 -0
- package/dist/index.d.ts +10 -6
- package/dist/index.js +8 -5
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +2 -2
- package/docs/glossary.md +27 -3
- package/docs/semantics.md +11 -1
- package/package.json +4 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,44 @@ 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.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
|
+
|
|
10
48
|
## 0.1.1 — 2026-10-31
|
|
11
49
|
|
|
12
50
|
Maintenance release — no library changes. CI publishing switched to npm
|
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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
package/dist/cascade.js.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/cjs/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;
|
|
@@ -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>;
|
package/dist/cjs/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).
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
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';
|