@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.
@@ -148,12 +148,53 @@ export type ScanDiagnostic = {
148
148
  /** The budget limit that was hit. */
149
149
  limit: number;
150
150
  };
151
+ /**
152
+ * One boundary-stone hit discovered during a walk — the walk face's share of
153
+ * the report-not-cut principle: which subtrees carry an existence signal
154
+ * (an embedded repository, a declared config home) and where. Pure metadata:
155
+ * the report never changes the file set.
156
+ *
157
+ * - `stoneName` — the stone that hit (the core `.git` — a `.git` directory
158
+ * or one of git's own pointer-file forms, such as a worktree/submodule
159
+ * `gitdir` file; a declared config home; the `.gitignore` proxy when
160
+ * mounted);
161
+ * - `path` — the scan-root-relative POSIX directory directly containing the
162
+ * stone (the nested repository's own directory, not the stone file);
163
+ * - `enforced` — whether the hit executed its cut under the active alignment
164
+ * face and exemption: `true` on the default git face (the entry names where
165
+ * the truncation happened), `false` for scanner-face core-stone hits
166
+ * (report-not-cut) and exemption-neutralized hits (registration, not
167
+ * rescue), and `true` always for config-home hits (your own declarations
168
+ * keep their verdict under every face).
169
+ *
170
+ * The scan root's own stones are not reported — the root is the universe
171
+ * boundary and never adjudicates against itself; only directories the walk
172
+ * visits as descent candidates appear here. Completeness is therefore the
173
+ * walk's: rule-pruned subtrees (preset, `exclude`, dot category) and
174
+ * everything below a budget cut (check `diagnostics`) leave no hits — a
175
+ * silent absence is not negative evidence. `.gitmodules` registration is
176
+ * invisible to the walk: a registered submodule's `.git` file hits exactly
177
+ * like an embedded repository's; `boundaryStones.exempt` is the walk-mode
178
+ * registration for both.
179
+ */
180
+ export interface WalkStoneHit {
181
+ stoneName: string;
182
+ path: string;
183
+ enforced: boolean;
184
+ }
151
185
  /** Result of a {@link walkScope} run. */
152
186
  export interface WalkResult {
153
187
  /** Included files as POSIX relative paths (forward slashes), sorted. */
154
188
  files: string[];
155
189
  /** Diagnostics; empty when the scan completed without a cut. */
156
190
  diagnostics: ScanDiagnostic[];
191
+ /**
192
+ * Boundary-stone hits discovered during the walk, sorted by path then
193
+ * stone name — see {@link WalkStoneHit}. Empty when no directory on the
194
+ * walked tree carried a stone. Report-only: identical options without
195
+ * this field produce the identical `files`.
196
+ */
197
+ stoneHits: WalkStoneHit[];
157
198
  }
158
199
  /** Thrown for malformed engine configuration (a strict rule without a reason, an unknown preset, ...). */
159
200
  export declare class PathscopeConfigError extends Error {
@@ -206,8 +247,8 @@ export interface UniverseResult {
206
247
  /** Repository root as git reports it (`rev-parse --show-toplevel`). */
207
248
  repoRoot: string;
208
249
  /**
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
250
+ * Diagnostics; always empty (the universe has no budget — git is the
251
+ * authority, not a traversal that could be cut). The field exists for
211
252
  * shape parity with {@link WalkResult}.
212
253
  */
213
254
  diagnostics: ScanDiagnostic[];
package/dist/engine.d.ts CHANGED
@@ -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>;
package/dist/engine.js CHANGED
@@ -35,6 +35,10 @@ const DEFAULT_MAX_FILES = 2000;
35
35
  /**
36
36
  * Walk `root` and produce the in-scope file set: POSIX relative paths, sorted,
37
37
  * plus loud diagnostics. See {@link ScopeOptions} for the exclusion stack.
38
+ *
39
+ * @throws {@link PathscopeConfigError} when `root` does not exist — the same
40
+ * fail-loud family as every face; a missing scan root is a configuration
41
+ * error, never a silent empty result.
38
42
  */
39
43
  export async function walkScope(root, options = {}) {
40
44
  validateOptions(options);
@@ -62,6 +66,14 @@ export async function walkScope(root, options = {}) {
62
66
  return hits;
63
67
  };
64
68
  const diagnostics = [];
69
+ // Walk-face stone report (shape B, 2026-11-13 owner ruling): every stone hit
70
+ // the walk discovers surfaces as metadata — the composable face's
71
+ // report-not-cut principle carried onto the walk result. Collected at probe
72
+ // time via the engine's stone attribution (exemption and alignment face
73
+ // applied exactly as the truncation adjudication applies them), sorted for a
74
+ // stable output contract. The scan root itself never reports (universe
75
+ // boundary — attributeStones guards it too).
76
+ const stoneReport = [];
65
77
  const controller = new AbortController();
66
78
  const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
67
79
  let included = 0;
@@ -69,7 +81,16 @@ export async function walkScope(root, options = {}) {
69
81
  /** Per-directory adjudication — fdir prunes the whole subtree when this returns true. */
70
82
  const excludeDirectory = (dirName, dirPath) => {
71
83
  const key = dirPath.replace(/\/+$/, '');
72
- if (engine.excludeDirectory(dirName, key, stoneHits(key)))
84
+ const hits = stoneHits(key);
85
+ if (key !== scanKey && hits.length > 0) {
86
+ const relDir = key.slice(scanKey.length + 1);
87
+ for (const hit of engine.attributeStones(relDir, hits)) {
88
+ if (hit.stoneName !== undefined) {
89
+ stoneReport.push({ stoneName: hit.stoneName, path: relDir, enforced: hit.enforced === true });
90
+ }
91
+ }
92
+ }
93
+ if (engine.excludeDirectory(dirName, key, hits))
73
94
  return true;
74
95
  // Descending: fold this layer's .gitignore in after the parent's rules
75
96
  // (shallow first, deep later; the subtree is pruned above
@@ -112,6 +133,7 @@ export async function walkScope(root, options = {}) {
112
133
  .filter((path) => keepFile(path))
113
134
  .crawl(rootNative)
114
135
  .withPromise();
115
- return { files: [...files].sort(), diagnostics };
136
+ stoneReport.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.stoneName < b.stoneName ? -1 : a.stoneName > b.stoneName ? 1 : 0);
137
+ return { files: [...files].sort(), diagnostics, stoneHits: stoneReport };
116
138
  }
117
139
  //# sourceMappingURL=engine.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAA2D,MAAM,YAAY,CAAC;AAE3G,2BAA2B;AAC3B,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,OAAO,GAAiB,EAAE;IACtE,eAAe,CAAC,OAAO,CAAC,CAAC;IAEzB,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAAC,6BAA6B,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,2EAA2E;IAC3E,yEAAyE;IACzE,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE/C,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,2EAA2E;IAC3E,wEAAwE;IACxE,0EAA0E;IAC1E,+DAA+D;IAC/D,MAAM,SAAS,GAAG,CAAC,GAAW,EAAqB,EAAE;QACnD,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,6EAA6E;IAC7E,kEAAkE;IAClE,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,uEAAuE;IACvE,6CAA6C;IAC7C,MAAM,WAAW,GAA4B,EAAE,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,yFAAyF;IACzF,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAE,OAAe,EAAW,EAAE;QACrE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;gBACvD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;oBAChC,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC,CAAC;gBAChG,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7D,uEAAuE;QACvE,0DAA0D;QAC1D,2EAA2E;QAC3E,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,wDAAwD;IACxD,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAW,EAAE;QACxC,IAAI,SAAS;YAAE,OAAO,KAAK,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAAC;YACzB,SAAS,GAAG,IAAI,CAAC;YACjB,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,iBAAiB;gBACvB,KAAK,EAAE,QAAQ;gBACf,OAAO,EAAE,kBAAkB,QAAQ,wDAAwD;aAC5F,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC;QAC3B,aAAa,EAAE,GAAG;QAClB,OAAO,EAAE,gBAAgB;QACzB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,eAAe,EAAE,OAAO,CAAC,cAAc,KAAK,IAAI;QAChD,yEAAyE;QACzE,kDAAkD;QAClD,YAAY,EAAE,KAAK;QACnB,yEAAyE;QACzE,4CAA4C;QAC5C,cAAc,EAAE,IAAI;KACrB,CAAC;SACC,iBAAiB,EAAE;SACnB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;SAChC,KAAK,CAAC,UAAU,CAAC;SACjB,WAAW,EAAE,CAAC;IAEjB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACxB,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAChH,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAC3E,CAAC"}
@@ -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;
@@ -26,12 +26,20 @@
26
26
  * combined table (presets front → gitignore cascade shallow→deep → policy
27
27
  * layer rear seat, git last-match-wins) → dot category. The budget stays
28
28
  * chassis-side: an engine has no file limit and emits no diagnostics.
29
+ *
30
+ * Attribution face (2026-10-31 06 seam extension): every rule the verdict
31
+ * instances consume is ALSO recorded per-rule with its provenance, and the
32
+ * `adjudicate*` variants return the per-layer hit list next to the identical
33
+ * verdict — the read-only probe face (explainScopePath) replays the
34
+ * ancestor chain over these. The verdict path is unchanged: same instances,
35
+ * same line order (the corpus-green gate is the zero-matching-deviation
36
+ * evidence).
29
37
  */
30
38
  import { existsSync } from 'node:fs';
31
39
  import { join } from 'node:path';
32
- import ignore from 'ignore';
33
- import { readGitignoreText, reanchorLines, splitLines } from './cascade.js';
34
- import { compilePresetPatterns, DEFAULT_MOUNTED_PRESETS, isPresetName } from './presets.js';
40
+ import ignore, {} from 'ignore';
41
+ import { readGitignoreText, reanchorLine, splitLines } from './cascade.js';
42
+ import { DEFAULT_MOUNTED_PRESETS, isPresetName, PRESETS } from './presets.js';
35
43
  import { baseNamePosix, joinPosix } from './paths.js';
36
44
  import { PathscopeConfigError } from './types.js';
37
45
  /** Default IO over the node filesystem (existsSync / readFileSync). */
@@ -117,6 +125,40 @@ function parentDirKey(key) {
117
125
  export async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO) {
118
126
  validateOptions(options);
119
127
  const respectGitignore = options.respectGitignore !== false;
128
+ /** A raw line is a rule unless blank / comment / bare '!'. */
129
+ const asRule = (raw) => (raw === '' || raw.startsWith('#') || raw === '!' ? null : raw);
130
+ const ruleIg = (mounted) => {
131
+ const ig = ignore();
132
+ ig.add([mounted]);
133
+ return ig;
134
+ };
135
+ /** gitignore-layer rules from raw `.gitignore` lines under one anchor ('' = scan root, relDir = nested layer, 'inherited:..' = above root). */
136
+ const gitignoreRules = (lines, anchor, prefix) => {
137
+ const out = [];
138
+ for (const raw of lines) {
139
+ const mounted = prefix === '' ? asRule(raw) : reanchorLine(raw, prefix);
140
+ if (mounted === null)
141
+ continue;
142
+ out.push({ mounted, original: raw, source: 'gitignore', gitignoreAnchor: anchor, ig: ruleIg(mounted) });
143
+ }
144
+ return out;
145
+ };
146
+ /** Enumerate per-rule hits for one channel: a rule reports when its single-rule instance matches the path with either polarity. */
147
+ const channelHits = (rules, canonical) => {
148
+ const hits = [];
149
+ for (const r of rules) {
150
+ const t = r.ig.test(canonical);
151
+ if (!t.ignored && !t.unignored)
152
+ continue;
153
+ const hit = { source: r.source, ruleText: r.original };
154
+ if (r.presetName !== undefined)
155
+ hit.presetName = r.presetName;
156
+ if (r.gitignoreAnchor !== undefined)
157
+ hit.gitignoreAnchor = r.gitignoreAnchor;
158
+ hits.push(hit);
159
+ }
160
+ return hits;
161
+ };
120
162
  // ---- inherited phase ----------------------------------------------------
121
163
  // Locate the enclosing git root by probing `.git` upward (dual file|dir
122
164
  // form), the scan root itself included; without a hit the inheritance top
@@ -138,7 +180,11 @@ export async function createExclusionEngine(rootKey, options = {}, io = nodeExcl
138
180
  dir = parent;
139
181
  }
140
182
  }
141
- const inheritedLines = [];
183
+ // Inherited rules ride verbatim in the canonical space (the inheritance
184
+ // top is that space's anchor); each ancestor's lines carry its anchor for
185
+ // the probe's attribution ('inherited:..' form — above the scan root,
186
+ // report-only, never part of the matching space).
187
+ const inheritedRules = [];
142
188
  if (top !== undefined && top !== rootKey) {
143
189
  const ancestors = [];
144
190
  let cur = parentDirKey(rootKey);
@@ -149,49 +195,85 @@ export async function createExclusionEngine(rootKey, options = {}, io = nodeExcl
149
195
  cur = parentDirKey(cur);
150
196
  }
151
197
  ancestors.reverse(); // git reads the cascade shallow first
152
- for (const ancestor of ancestors) {
198
+ for (const [idx, ancestor] of ancestors.entries()) {
199
+ // After the reverse the nearest ancestor sits LAST: hops from the scan
200
+ // root = length - idx ('..' for the parent, '../..' for the grandparent).
201
+ const hops = ancestors.length - idx;
202
+ const anchor = `inherited:${Array.from({ length: hops }, () => '..').join('/')}`;
153
203
  const text = await io.readGitignore(ancestor);
154
- if (text !== null)
155
- inheritedLines.push(...splitLines(text));
204
+ if (text === null)
205
+ continue;
206
+ for (const raw of splitLines(text)) {
207
+ const mounted = asRule(raw);
208
+ if (mounted === null)
209
+ continue;
210
+ inheritedRules.push({
211
+ mounted,
212
+ original: raw,
213
+ source: 'gitignore',
214
+ gitignoreAnchor: anchor,
215
+ ig: ruleIg(mounted),
216
+ });
217
+ }
156
218
  }
157
219
  }
158
220
  const rootPrefix = top !== undefined && rootKey.startsWith(top) ? top : rootKey;
159
221
  const offRel = rootKey.slice(rootPrefix.length).replace(/^\//, '');
160
222
  // ---- canonical rule space ------------------------------------------------
161
223
  const toCanonical = (rel) => (offRel === '' ? rel : `${offRel}/${rel}`);
162
- /** Re-anchor scan-root-based patterns (relDir '' = the scan root itself) into the canonical space. */
163
- const mount = (patterns, relDir = '') => {
164
- const prefix = joinPosix(offRel, relDir);
165
- return prefix === '' ? patterns : reanchorLines(patterns, prefix);
166
- };
224
+ /** Mount one scan-root-relative pattern into the canonical space (re-anchored iff off-root). */
225
+ const mountOne = (pattern) => (offRel === '' ? pattern : reanchorLine(pattern, offRel));
167
226
  // Combined table, front segment first: presets → inherited gitignores
168
227
  // (verbatim — natively expressed in canonical space) → scan root's own
169
228
  // .gitignore. Nested layers are appended by foldGitignore mid-walk.
170
229
  const core = ignore();
171
- const presetPatterns = compilePresetPatterns(options.mountPresets ?? DEFAULT_MOUNTED_PRESETS);
172
- if (presetPatterns.length > 0)
173
- core.add(mount(presetPatterns));
174
- if (inheritedLines.length > 0)
175
- core.add(inheritedLines);
230
+ const coreRules = [];
231
+ for (const pName of options.mountPresets ?? DEFAULT_MOUNTED_PRESETS) {
232
+ const preset = PRESETS[pName];
233
+ for (const dir of preset.dirs) {
234
+ const mounted = mountOne(`${dir}/`);
235
+ coreRules.push({ mounted, original: `${dir}/`, source: 'preset', presetName: pName, ig: ruleIg(mounted) });
236
+ }
237
+ for (const file of preset.files ?? []) {
238
+ const mounted = mountOne(file);
239
+ coreRules.push({ mounted, original: file, source: 'preset', presetName: pName, ig: ruleIg(mounted) });
240
+ }
241
+ }
242
+ coreRules.push(...inheritedRules);
176
243
  const rootIgnoreText = respectGitignore ? await io.readGitignore(rootKey) : null;
177
244
  if (rootIgnoreText !== null) {
178
- const lines = mount(splitLines(rootIgnoreText));
179
- if (lines.length > 0)
180
- core.add(lines);
245
+ coreRules.push(...gitignoreRules(splitLines(rootIgnoreText), '', offRel));
181
246
  }
247
+ if (coreRules.length > 0)
248
+ core.add(coreRules.map((r) => r.mounted));
182
249
  // Policy layer holds the rear seat of the combined table: after the whole
183
250
  // gitignore cascade, so its match (either polarity) wins over the cascade.
184
251
  const policy = ignore();
252
+ const policyRules = [];
185
253
  if (options.exclude !== undefined && options.exclude.length > 0) {
186
- policy.add(mount(options.exclude));
254
+ for (const pattern of options.exclude) {
255
+ const mounted = mountOne(pattern);
256
+ policyRules.push({ mounted, original: pattern, source: 'policy', ig: ruleIg(mounted) });
257
+ }
258
+ policy.add(policyRules.map((r) => r.mounted));
187
259
  }
188
260
  const overrideIg = ignore();
261
+ const overrideRules = [];
189
262
  if (options.override !== undefined && options.override.length > 0) {
190
- overrideIg.add(mount(options.override));
263
+ for (const pattern of options.override) {
264
+ const mounted = mountOne(pattern);
265
+ overrideRules.push({ mounted, original: pattern, source: 'override', ig: ruleIg(mounted) });
266
+ }
267
+ overrideIg.add(overrideRules.map((r) => r.mounted));
191
268
  }
192
269
  const strictIg = ignore();
270
+ const strictRules = [];
193
271
  if (options.strict !== undefined && options.strict.length > 0) {
194
- strictIg.add(mount(options.strict.map((rule) => rule.pattern)));
272
+ for (const rule of options.strict) {
273
+ const mounted = mountOne(rule.pattern);
274
+ strictRules.push({ mounted, original: rule.pattern, source: 'strict', ig: ruleIg(mounted) });
275
+ }
276
+ strictIg.add(strictRules.map((r) => r.mounted));
195
277
  }
196
278
  const configHomes = options.boundaryStones?.configHomes ?? [];
197
279
  const gitignoreProxy = options.boundaryStones?.gitignoreProxy === true;
@@ -244,28 +326,37 @@ export async function createExclusionEngine(rootKey, options = {}, io = nodeExcl
244
326
  // self-declared governance and keep their verdict under every face.
245
327
  const unenforcedNames = options.alignment === 'scanner' ? new Set(['.git']) : null;
246
328
  /**
247
- * Stone verdict over one directory (the scan root itself never truncates).
248
- * The exemption neutralizes the named directory's own hits of the
249
- * exemptible stone kinds (the core `.git`; `.gitignore` too when the proxy
250
- * stone is mounted); the alignment face then drops the unenforced kinds
251
- * (the core `.git` under the scanner face — reported, never enforced); any
252
- * remaining hit (a config home) still truncates. The boolean form reports
253
- * an unspecified hit and truncates unconditionally.
329
+ * Stone adjudication detail over one directory (the scan root itself never
330
+ * truncates — the caller guards). Every probed hit reports an entry with
331
+ * its `enforced` flag: the exemption neutralizes the named directory's own
332
+ * hits of the exemptible stone kinds (the core `.git`; `.gitignore` too
333
+ * when the proxy stone is mounted); the alignment face drops the unenforced
334
+ * kinds (the core `.git` under the scanner face — reported, never
335
+ * enforced). Any hit left enforced (a config home, an un-named `.git`)
336
+ * still truncates. The boolean form reports an unspecified hit and
337
+ * truncates unconditionally (no name to attribute).
254
338
  */
255
- const stoneTruncates = (hit, key) => {
339
+ const stoneDetail = (hit, relDir) => {
340
+ if (hit == null || hit === false)
341
+ return [];
256
342
  if (hit === true)
257
- return true;
258
- if (hit == null || !Array.isArray(hit) || hit.length === 0)
259
- return false;
343
+ return [{ enforced: true }];
260
344
  let names = hit;
261
- if (isExemptDir(key.slice(rootKey.length + 1))) {
345
+ if (isExemptDir(relDir)) {
262
346
  names = names.filter((name) => !exemptibleNames.has(name));
263
347
  }
264
348
  if (unenforcedNames !== null) {
265
349
  names = names.filter((name) => !unenforcedNames.has(name));
266
350
  }
267
- return names.length > 0;
351
+ const enforcedSet = new Set(names);
352
+ return hit.map((name) => ({ stoneName: name, enforced: enforcedSet.has(name) }));
268
353
  };
354
+ const stoneHitEntries = (detail) => detail.map((d) => {
355
+ const hit = { source: 'stone', enforced: d.enforced };
356
+ if (d.stoneName !== undefined)
357
+ hit.stoneName = d.stoneName;
358
+ return hit;
359
+ });
269
360
  /** Combined-table verdict for a canonical path: policy after the cascade. */
270
361
  const combinedExcludes = (canonical) => {
271
362
  const policyResult = policy.test(canonical);
@@ -275,54 +366,93 @@ export async function createExclusionEngine(rootKey, options = {}, io = nodeExcl
275
366
  return false;
276
367
  return core.test(canonical).ignored;
277
368
  };
369
+ // ---- attribution adjudications (the verdict faces delegate to these) -----
370
+ // Same order, same instances, same side effects as the boolean faces —
371
+ // `excluded`/`admitted` are the walk verdicts by construction, `hits` the
372
+ // per-layer attribution the read-only probe face reports.
373
+ const adjudicateDirectoryImpl = (name, dirPath, stoneHit) => {
374
+ const key = dirPath.replace(/\/+$/, '');
375
+ const relDir = key === rootKey ? '' : key.slice(rootKey.length + 1);
376
+ const hits = [];
377
+ // 0. boundary stones — structural terminal; the scan
378
+ // root itself is the universe boundary and never truncates. The
379
+ // named-subtree exemption (boundaryStones.exempt) adjudicates
380
+ // inside this verdict: the named directory's own hits of the
381
+ // exemptible stone kinds are neutralized (reported enforced:false),
382
+ // everything else keeps its cut.
383
+ if (key !== rootKey) {
384
+ const stones = stoneHitEntries(stoneDetail(stoneHit, relDir));
385
+ hits.push(...stones);
386
+ if (stones.some((h) => h.enforced))
387
+ return { excluded: true, hits };
388
+ }
389
+ const canonicalDir = toCanonical(`${relDir}/`);
390
+ // 1. strict immune channel — not rescuable, not even by the override whitelist.
391
+ hits.push(...channelHits(strictRules, canonicalDir));
392
+ if (strictIg.test(canonicalDir).ignored)
393
+ return { excluded: true, hits };
394
+ // 2. override whitelist — terminal include; naming the directory itself
395
+ // rescues descent into it.
396
+ if (overrideIg.test(canonicalDir).ignored) {
397
+ hits.push(...channelHits(overrideRules, canonicalDir));
398
+ return { excluded: false, hits };
399
+ }
400
+ // 3. combined rule table — the policy layer holds the rear seat. A
401
+ // directory excluded with no directory-level rescue prunes the
402
+ // subtree (structural, the only non-revivable). When the rescue
403
+ // comes from a policy NEGATION, the negation is restated into the
404
+ // core stream at its cascade-equivalent position as an anchored,
405
+ // exactly-subtree-scoped rule: node-ignore reports a negation as a
406
+ // match only when it hits the pathname itself, so without the
407
+ // restatement files beneath the rescued directory would fall back
408
+ // to the core stream's component match (e.g. the mounted preset)
409
+ // and be re-excluded — diverging from the same rule pair written
410
+ // in one .gitignore file.
411
+ hits.push(...channelHits(coreRules, canonicalDir));
412
+ hits.push(...channelHits(policyRules, canonicalDir));
413
+ const policyResult = policy.test(canonicalDir);
414
+ if (policyResult.ignored)
415
+ return { excluded: true, hits };
416
+ if (policyResult.unignored) {
417
+ if (core.test(canonicalDir).ignored) {
418
+ core.add(`!/${canonicalDir}`);
419
+ }
420
+ }
421
+ else if (core.test(canonicalDir).ignored) {
422
+ return { excluded: true, hits };
423
+ }
424
+ // 4. dot category — walk-layer option; the whitelist had its chance at 2.
425
+ if (excludeDotEntries && name.startsWith('.')) {
426
+ hits.push({ source: 'dot' });
427
+ return { excluded: true, hits };
428
+ }
429
+ return { excluded: false, hits };
430
+ };
431
+ const adjudicateFileImpl = (relPath) => {
432
+ const canonical = toCanonical(relPath);
433
+ const hits = [];
434
+ hits.push(...channelHits(strictRules, canonical));
435
+ if (strictIg.test(canonical).ignored)
436
+ return { admitted: false, hits };
437
+ if (overrideIg.test(canonical).ignored) {
438
+ hits.push(...channelHits(overrideRules, canonical));
439
+ return { admitted: true, hits };
440
+ }
441
+ hits.push(...channelHits(coreRules, canonical));
442
+ hits.push(...channelHits(policyRules, canonical));
443
+ if (combinedExcludes(canonical))
444
+ return { admitted: false, hits };
445
+ if (excludeDotEntries && baseNamePosix(relPath).startsWith('.')) {
446
+ hits.push({ source: 'dot' });
447
+ return { admitted: false, hits };
448
+ }
449
+ return { admitted: true, hits };
450
+ };
278
451
  return {
279
452
  rootKey,
280
453
  stoneNames,
281
454
  excludeDirectory(name, dirPath, stoneHit) {
282
- const key = dirPath.replace(/\/+$/, '');
283
- // 0. boundary stones — structural terminal; the scan
284
- // root itself is the universe boundary and never truncates. The
285
- // named-subtree exemption (boundaryStones.exempt) adjudicates
286
- // inside this verdict: the named directory's own hits of the
287
- // exemptible stone kinds are neutralized, everything else keeps
288
- // its cut.
289
- if (key !== rootKey && stoneTruncates(stoneHit, key))
290
- return true;
291
- const relDir = key.slice(rootKey.length + 1);
292
- const canonicalDir = toCanonical(`${relDir}/`);
293
- // 1. strict immune channel — not rescuable, not even by the override whitelist.
294
- if (strictIg.test(canonicalDir).ignored)
295
- return true;
296
- // 2. override whitelist — terminal include; naming the directory itself
297
- // rescues descent into it.
298
- if (overrideIg.test(canonicalDir).ignored)
299
- return false;
300
- // 3. combined rule table — the policy layer holds the rear seat. A
301
- // directory excluded with no directory-level rescue prunes the
302
- // subtree (structural, the only non-revivable). When the rescue
303
- // comes from a policy NEGATION, the negation is restated into the
304
- // core stream at its cascade-equivalent position as an anchored,
305
- // exactly-subtree-scoped rule: node-ignore reports a negation as a
306
- // match only when it hits the pathname itself, so without the
307
- // restatement files beneath the rescued directory would fall back
308
- // to the core stream's component match (e.g. the mounted preset)
309
- // and be re-excluded — diverging from the same rule pair written
310
- // in one .gitignore file.
311
- const policyResult = policy.test(canonicalDir);
312
- if (policyResult.ignored)
313
- return true;
314
- if (policyResult.unignored) {
315
- if (core.test(canonicalDir).ignored) {
316
- core.add(`!/${canonicalDir}`);
317
- }
318
- }
319
- else if (core.test(canonicalDir).ignored) {
320
- return true;
321
- }
322
- // 4. dot category — walk-layer option; the whitelist had its chance at 2.
323
- if (excludeDotEntries && name.startsWith('.'))
324
- return true;
325
- return false;
455
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit).excluded;
326
456
  },
327
457
  foldGitignore(dirPath, text) {
328
458
  if (text == null || !respectGitignore)
@@ -331,21 +461,32 @@ export async function createExclusionEngine(rootKey, options = {}, io = nodeExcl
331
461
  if (key === rootKey)
332
462
  return; // consumed at construction
333
463
  const relDir = key.slice(rootKey.length + 1);
334
- const lines = mount(splitLines(text), relDir);
335
- if (lines.length > 0)
336
- core.add(lines);
464
+ const rules = gitignoreRules(splitLines(text), relDir, joinPosix(offRel, relDir));
465
+ if (rules.length > 0) {
466
+ core.add(rules.map((r) => r.mounted));
467
+ coreRules.push(...rules);
468
+ }
337
469
  },
338
470
  admitFile(relPath) {
339
- const canonical = toCanonical(relPath);
340
- if (strictIg.test(canonical).ignored)
341
- return false;
342
- if (overrideIg.test(canonical).ignored)
343
- return true;
344
- if (combinedExcludes(canonical))
345
- return false;
346
- if (excludeDotEntries && baseNamePosix(relPath).startsWith('.'))
347
- return false;
348
- return true;
471
+ return adjudicateFileImpl(relPath).admitted;
472
+ },
473
+ adjudicateDirectory(name, dirPath, stoneHit) {
474
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit);
475
+ },
476
+ adjudicateFile(relPath) {
477
+ return adjudicateFileImpl(relPath);
478
+ },
479
+ attributeStones(relDir, stoneHit) {
480
+ // The scan root is the universe boundary and never truncates — its own
481
+ // stone facts are not adjudication (nothing they could cut above them).
482
+ if (relDir === '')
483
+ return [];
484
+ return stoneHitEntries(stoneDetail(stoneHit, relDir));
485
+ },
486
+ adjudicateStrict(relPath, isDir) {
487
+ const trimmed = relPath.replace(/\/+$/, '');
488
+ const canonical = toCanonical(isDir ? `${trimmed}/` : trimmed);
489
+ return { hit: strictIg.test(canonical).ignored, hits: channelHits(strictRules, canonical) };
349
490
  },
350
491
  };
351
492
  }