@catheadowl/pathscope 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,40 @@ description: pathscope changelog — user-visible changes per release, newest fi
7
7
  All notable changes to this project are documented here. The format follows
8
8
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
9
9
 
10
+ ## 0.3.0 — 2026-11-13
11
+
12
+ ### Added
13
+
14
+ - **walk stone report** (2026-11-13 owner ruling — the report-not-cut
15
+ principle carried onto the walk result): `walkScope` results carry
16
+ `stoneHits` — every boundary-stone hit the walk discovered, as
17
+ `{ stoneName, path, enforced }`. One walk now tells you which subtrees are
18
+ independent repositories (or declared config-home sub-domains) and where:
19
+ `enforced: true` on the default git face names the truncation locations;
20
+ under `alignment: 'scanner'` core-stone hits report `enforced: false`
21
+ (report-not-cut metadata) and the walk descends; exemption-neutralized hits
22
+ report `enforced: false` (registration, not rescue); config-home hits stay
23
+ `enforced: true` under every face. Pure metadata — the file set is untouched,
24
+ output is sorted (path, then stone name), the scan root's own markers are
25
+ not reported, and conformance fixture 38 pins the membership invariants.
26
+
27
+ ### Changed
28
+
29
+ - **preset vocabulary additions** (adopted 2026-11-13): `venv` and
30
+ `.gradle` join the opt-in `caches` group (both in repomix's defaultIgnore;
31
+ `venv` also in github's Python template — watchfiles carries `.venv` only);
32
+ the `build` group gains the **root-anchored** `/target` — the cargo/maven
33
+ build tree, anchored exactly because `target` is collision-grade (the Rust
34
+ toolchain's own adjudication: cargo#3158 → `cargo new` generates `/target`).
35
+ The anchored entry matches only a `target` directory AT the scan root
36
+ (re-anchored accordingly when the scan root sits below a repo root) —
37
+ nested same-named directories are untouched, and `!target/` un-excludes it
38
+ like every preset entry. `caches` is not default-mounted (no default
39
+ change); `build` is, so default scans now skip a scan-root `target/` —
40
+ projects whose scan root legitimately holds content in `target/` name their
41
+ way out with `!target/`. A `dirs` entry may now carry a leading slash
42
+ (scan-root anchor) — plain gitignore anchoring, no new matching semantics.
43
+
10
44
  ## 0.2.0 — 2026-11-01
11
45
 
12
46
  ### Added
package/README.md CHANGED
@@ -7,6 +7,7 @@ pathscope answers one question three ways: **which files are in scope?** Walk th
7
7
  ## Features
8
8
 
9
9
  - **Git-native semantics** — an unregistered nested repository (an *embedded repository*, in git's own terminology) truncates the walk, exactly as git never descends into one; `.gitignore` cascades with last-match-wins, symlinks are not followed, hidden (dot) entries are skipped by default.
10
+ - **Stone report** — every boundary-stone hit the walk discovers surfaces as structured metadata (`stoneHits`: stone name + directory + whether it enforced its cut). One walk tells you which subtrees are independent repositories and where: under the default git face the report names the truncation locations; under `alignment: 'scanner'` it is report-not-cut metadata. The file set is untouched by the report.
10
11
  - **Default ignore presets** — opt-in groups for VCS internals, dependencies, build outputs, caches, and agent docs; every entry can be un-excluded with a named `!` negation.
11
12
  - **Per-path point queries** — `explainScopePath` answers "is this path in scope, and exactly which layer decided" with a full attribution chain (preset / gitignore layer / boundary stone / strict-override-policy / dot), structural-prune answers, and an explicit-pierce projection. Read-only over the same scope request.
12
13
  - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
@@ -26,12 +27,20 @@ import { walkScope } from '@catheadowl/pathscope';
26
27
 
27
28
  // Default stack: gitignore cascade + vcs/deps/build presets + dot entries
28
29
  // excluded + loud budget (2000).
29
- const { files, diagnostics } = await walkScope('/repo');
30
+ const { files, diagnostics, stoneHits } = await walkScope('/repo');
30
31
  console.log(files);
31
32
  //=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
32
33
 
33
34
  console.log(diagnostics);
34
35
  //=> [] — non-empty means the budget cut the scan (code: 'budget-exceeded')
36
+
37
+ console.log(stoneHits);
38
+ //=> [{ stoneName: '.git', path: 'embedded-toolkit', enforced: true }]
39
+ // — every stone hit the walk discovered: which subtrees are independent
40
+ // repositories (or declared sub-domains) and where. `enforced: true` on the
41
+ // default git face names where the truncation happened; under
42
+ // alignment: 'scanner' the core stone reports enforced: false and the
43
+ // walk descends. Pure metadata — the file set never changes because of it.
35
44
  ```
36
45
 
37
46
  All output paths are POSIX-style relative to the scanned root, sorted.
@@ -139,7 +148,7 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
139
148
 
140
149
  | Export | One-line |
141
150
  | --- | --- |
142
- | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics }` |
151
+ | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics, stoneHits }` |
143
152
  | `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
144
153
  | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
145
154
  | `locateNearest(names, options?)` | Nearest config file, no parsing |
@@ -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/cjs/index.js CHANGED
@@ -1474,16 +1474,23 @@ var PRESETS = {
1474
1474
  // Build outputs and coverage. These are collision-grade names (a project's
1475
1475
  // source can legitimately live in `lib/`) — that is exactly why they ride
1476
1476
  // the un-excludable preset channel (`!lib/` names its way out) instead of
1477
- // a separate immune layer.
1478
- dirs: ["dist", "build", "lib", "out", "coverage"]
1477
+ // a separate immune layer. `/target` is the ROOT-ANCHORED cargo/maven
1478
+ // build tree: anchored exactly because `target` is collision-grade — the
1479
+ // Rust toolchain's own adjudication (cargo#3158: a bare `target` hits
1480
+ // same-named directories at any depth; `cargo new` generates `/target`),
1481
+ // so the entry binds only when the scan root itself is the project.
1482
+ dirs: ["dist", "build", "lib", "out", "coverage", "/target"]
1479
1483
  },
1480
1484
  caches: {
1481
- // Python & front-end cache/generated trees. Vendor lineage of the entries:
1485
+ // Cache/generated trees (Python, front-end, build tools). Vendor lineage
1486
+ // of the entries:
1482
1487
  // - repomix `defaultIgnore.ts` (MIT): __pycache__, .mypy_cache,
1483
- // .pytest_cache, .tox, .venv, .cache, .next, .nuxt, .turbo, .vite,
1484
- // .parcel-cache, .svelte-kit
1488
+ // .pytest_cache, .tox, .venv, venv, .gradle, .cache, .next, .nuxt,
1489
+ // .turbo, .vite, .parcel-cache, .svelte-kit
1485
1490
  // - watchfiles `DefaultFilter` (Python-side alignment): __pycache__,
1486
1491
  // .mypy_cache, .pytest_cache, .ruff_cache, .tox, .nox, .venv
1492
+ // (non-dot `venv` and `.gradle` are repomix-only — watchfiles carries
1493
+ // neither; github's Python/Gradle templates carry both)
1487
1494
  // This group is NOT in the default mount set.
1488
1495
  dirs: [
1489
1496
  "__pycache__",
@@ -1492,6 +1499,8 @@ var PRESETS = {
1492
1499
  ".ruff_cache",
1493
1500
  ".tox",
1494
1501
  ".venv",
1502
+ "venv",
1503
+ ".gradle",
1495
1504
  ".cache",
1496
1505
  ".next",
1497
1506
  ".nuxt",
@@ -1897,13 +1906,23 @@ async function walkScope(root, options = {}) {
1897
1906
  return hits;
1898
1907
  };
1899
1908
  const diagnostics = [];
1909
+ const stoneReport = [];
1900
1910
  const controller = new AbortController();
1901
1911
  const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
1902
1912
  let included = 0;
1903
1913
  let budgetCut = false;
1904
1914
  const excludeDirectory = (dirName, dirPath) => {
1905
1915
  const key = dirPath.replace(/\/+$/, "");
1906
- if (engine.excludeDirectory(dirName, key, stoneHits(key))) return true;
1916
+ const hits = stoneHits(key);
1917
+ if (key !== scanKey && hits.length > 0) {
1918
+ const relDir = key.slice(scanKey.length + 1);
1919
+ for (const hit of engine.attributeStones(relDir, hits)) {
1920
+ if (hit.stoneName !== void 0) {
1921
+ stoneReport.push({ stoneName: hit.stoneName, path: relDir, enforced: hit.enforced === true });
1922
+ }
1923
+ }
1924
+ }
1925
+ if (engine.excludeDirectory(dirName, key, hits)) return true;
1907
1926
  engine.foldGitignore(key, readGitignoreText(key));
1908
1927
  return false;
1909
1928
  };
@@ -1935,7 +1954,10 @@ async function walkScope(root, options = {}) {
1935
1954
  // the budget, not per-directory I/O errors.
1936
1955
  suppressErrors: true
1937
1956
  }).withRelativePaths().filter((path3) => keepFile(path3)).crawl(rootNative).withPromise();
1938
- return { files: [...files].sort(), diagnostics };
1957
+ stoneReport.sort(
1958
+ (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.stoneName < b.stoneName ? -1 : a.stoneName > b.stoneName ? 1 : 0
1959
+ );
1960
+ return { files: [...files].sort(), diagnostics, stoneHits: stoneReport };
1939
1961
  }
1940
1962
 
1941
1963
  // src/explain.ts
@@ -11,15 +11,23 @@
11
11
  import type { PresetName } from './types.ts';
12
12
  /** Type guard used by option validation — unknown preset names fail loudly. */
13
13
  export declare function isPresetName(value: unknown): value is PresetName;
14
- /** Preset content: directory names (matched as dir-only `name/` patterns at any depth) and file names. */
14
+ /**
15
+ * Preset content: directory names (matched as dir-only `name/` patterns at any
16
+ * depth) and file names. A `dirs` entry MAY carry a leading slash (`/target`)
17
+ * — it then compiles to a scan-root-anchored pattern (`/target/`, plain
18
+ * gitignore anchoring) that matches only a same-named directory at the scan
19
+ * root itself, never nested ones; the named-negation exit key (`!target/`)
20
+ * un-excludes it like any other entry.
21
+ */
15
22
  export type Preset = {
16
23
  dirs: string[];
17
24
  files?: string[];
18
25
  };
19
26
  /**
20
27
  * The five preset groups. `dirs` entries compile to dir-only gitignore
21
- * patterns (`name/` — a plain file with the same name stays in scope);
22
- * `files` entries compile to bare names.
28
+ * patterns (`name/` — a plain file with the same name stays in scope; a
29
+ * leading-slash entry anchors to the scan root); `files` entries compile to
30
+ * bare names.
23
31
  */
24
32
  export declare const PRESETS: Record<PresetName, Preset>;
25
33
  /** The default mount set. */
@@ -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 {
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":"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"}
package/dist/presets.d.ts CHANGED
@@ -11,15 +11,23 @@
11
11
  import type { PresetName } from './types.ts';
12
12
  /** Type guard used by option validation — unknown preset names fail loudly. */
13
13
  export declare function isPresetName(value: unknown): value is PresetName;
14
- /** Preset content: directory names (matched as dir-only `name/` patterns at any depth) and file names. */
14
+ /**
15
+ * Preset content: directory names (matched as dir-only `name/` patterns at any
16
+ * depth) and file names. A `dirs` entry MAY carry a leading slash (`/target`)
17
+ * — it then compiles to a scan-root-anchored pattern (`/target/`, plain
18
+ * gitignore anchoring) that matches only a same-named directory at the scan
19
+ * root itself, never nested ones; the named-negation exit key (`!target/`)
20
+ * un-excludes it like any other entry.
21
+ */
15
22
  export type Preset = {
16
23
  dirs: string[];
17
24
  files?: string[];
18
25
  };
19
26
  /**
20
27
  * The five preset groups. `dirs` entries compile to dir-only gitignore
21
- * patterns (`name/` — a plain file with the same name stays in scope);
22
- * `files` entries compile to bare names.
28
+ * patterns (`name/` — a plain file with the same name stays in scope; a
29
+ * leading-slash entry anchors to the scan root); `files` entries compile to
30
+ * bare names.
23
31
  */
24
32
  export declare const PRESETS: Record<PresetName, Preset>;
25
33
  /** The default mount set. */
package/dist/presets.js CHANGED
@@ -5,8 +5,9 @@ export function isPresetName(value) {
5
5
  }
6
6
  /**
7
7
  * The five preset groups. `dirs` entries compile to dir-only gitignore
8
- * patterns (`name/` — a plain file with the same name stays in scope);
9
- * `files` entries compile to bare names.
8
+ * patterns (`name/` — a plain file with the same name stays in scope; a
9
+ * leading-slash entry anchors to the scan root); `files` entries compile to
10
+ * bare names.
10
11
  */
11
12
  export const PRESETS = {
12
13
  vcs: {
@@ -24,16 +25,23 @@ export const PRESETS = {
24
25
  // Build outputs and coverage. These are collision-grade names (a project's
25
26
  // source can legitimately live in `lib/`) — that is exactly why they ride
26
27
  // the un-excludable preset channel (`!lib/` names its way out) instead of
27
- // a separate immune layer.
28
- dirs: ['dist', 'build', 'lib', 'out', 'coverage'],
28
+ // a separate immune layer. `/target` is the ROOT-ANCHORED cargo/maven
29
+ // build tree: anchored exactly because `target` is collision-grade — the
30
+ // Rust toolchain's own adjudication (cargo#3158: a bare `target` hits
31
+ // same-named directories at any depth; `cargo new` generates `/target`),
32
+ // so the entry binds only when the scan root itself is the project.
33
+ dirs: ['dist', 'build', 'lib', 'out', 'coverage', '/target'],
29
34
  },
30
35
  caches: {
31
- // Python & front-end cache/generated trees. Vendor lineage of the entries:
36
+ // Cache/generated trees (Python, front-end, build tools). Vendor lineage
37
+ // of the entries:
32
38
  // - repomix `defaultIgnore.ts` (MIT): __pycache__, .mypy_cache,
33
- // .pytest_cache, .tox, .venv, .cache, .next, .nuxt, .turbo, .vite,
34
- // .parcel-cache, .svelte-kit
39
+ // .pytest_cache, .tox, .venv, venv, .gradle, .cache, .next, .nuxt,
40
+ // .turbo, .vite, .parcel-cache, .svelte-kit
35
41
  // - watchfiles `DefaultFilter` (Python-side alignment): __pycache__,
36
42
  // .mypy_cache, .pytest_cache, .ruff_cache, .tox, .nox, .venv
43
+ // (non-dot `venv` and `.gradle` are repomix-only — watchfiles carries
44
+ // neither; github's Python/Gradle templates carry both)
37
45
  // This group is NOT in the default mount set.
38
46
  dirs: [
39
47
  '__pycache__',
@@ -42,6 +50,8 @@ export const PRESETS = {
42
50
  '.ruff_cache',
43
51
  '.tox',
44
52
  '.venv',
53
+ 'venv',
54
+ '.gradle',
45
55
  '.cache',
46
56
  '.next',
47
57
  '.nuxt',
@@ -1 +1 @@
1
- {"version":3,"file":"presets.js","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAYA,MAAM,YAAY,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE5F,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAKD;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAA+B;IACjD,GAAG,EAAE;QACH,yEAAyE;QACzE,0EAA0E;QAC1E,uCAAuC;QACvC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;KAC9B;IACD,IAAI,EAAE;QACJ,yEAAyE;QACzE,6DAA6D;QAC7D,IAAI,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC;KAC1C;IACD,KAAK,EAAE;QACL,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,2BAA2B;QAC3B,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC;KAClD;IACD,MAAM,EAAE;QACN,2EAA2E;QAC3E,kEAAkE;QAClE,uEAAuE;QACvE,iCAAiC;QACjC,uEAAuE;QACvE,iEAAiE;QACjE,8CAA8C;QAC9C,IAAI,EAAE;YACJ,aAAa;YACb,aAAa;YACb,eAAe;YACf,aAAa;YACb,MAAM;YACN,OAAO;YACP,QAAQ;YACR,OAAO;YACP,OAAO;YACP,QAAQ;YACR,OAAO;YACP,eAAe;YACf,aAAa;YACb,MAAM;YACN,cAAc;SACf;KACF;IACD,SAAS,EAAE;QACT,+DAA+D;QAC/D,mEAAmE;QACnE,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC;KAClC;CACF,CAAC;AAEF,6BAA6B;AAC7B,MAAM,CAAC,MAAM,uBAAuB,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvF,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
1
+ {"version":3,"file":"presets.js","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAYA,MAAM,YAAY,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE5F,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAYD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAA+B;IACjD,GAAG,EAAE;QACH,yEAAyE;QACzE,0EAA0E;QAC1E,uCAAuC;QACvC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;KAC9B;IACD,IAAI,EAAE;QACJ,yEAAyE;QACzE,6DAA6D;QAC7D,IAAI,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC;KAC1C;IACD,KAAK,EAAE;QACL,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,sEAAsE;QACtE,yEAAyE;QACzE,sEAAsE;QACtE,yEAAyE;QACzE,oEAAoE;QACpE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC;KAC7D;IACD,MAAM,EAAE;QACN,yEAAyE;QACzE,kBAAkB;QAClB,kEAAkE;QAClE,uEAAuE;QACvE,gDAAgD;QAChD,uEAAuE;QACvE,iEAAiE;QACjE,0EAA0E;QAC1E,4DAA4D;QAC5D,8CAA8C;QAC9C,IAAI,EAAE;YACJ,aAAa;YACb,aAAa;YACb,eAAe;YACf,aAAa;YACb,MAAM;YACN,OAAO;YACP,MAAM;YACN,SAAS;YACT,QAAQ;YACR,OAAO;YACP,OAAO;YACP,QAAQ;YACR,OAAO;YACP,eAAe;YACf,aAAa;YACb,MAAM;YACN,cAAc;SACf;KACF;IACD,SAAS,EAAE;QACT,+DAA+D;QAC/D,mEAAmE;QACnE,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC;KAClC;CACF,CAAC;AAEF,6BAA6B;AAC7B,MAAM,CAAC,MAAM,uBAAuB,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvF,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
package/dist/types.d.ts CHANGED
@@ -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 {
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8JH,0GAA0G;AAC1G,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwMH,0GAA0G;AAC1G,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}
package/docs/glossary.md CHANGED
@@ -72,6 +72,8 @@ The API names this option `boundaryStones`; markers is the plain word for what t
72
72
 
73
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.
74
74
 
75
+ **Walk stone report** — the walk face's marker-hit report: `stoneHits` on the `walkScope` result, every hit the walk discovered as `{ stoneName, path, enforced }` — pure metadata, the file set is untouched. Only directories the walk visits report, so pruned subtrees and the area below a budget cut stay silent (see the walk stone report section in `docs/semantics.md`).
76
+
75
77
  ## Alignment
76
78
 
77
79
  **Alignment** — which family's nested-repository semantics the core marker follows. `'git'` (default): an embedded repository truncates whole. `'scanner'` (ripgrep-style): nested repositories never truncate, at any depth, and a nested `.gitignore` is rules — the marker hit is still reported, as metadata ("this subtree is a nested repository"), but the cut never executes.
package/docs/semantics.md CHANGED
@@ -19,14 +19,14 @@ The full-stack priority over one engine, strongest first:
19
19
 
20
20
  ## Presets
21
21
 
22
- Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table:
22
+ Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table. A `dirs` entry with a leading slash is **scan-root-anchored** (plain gitignore anchoring): it matches only at the scan root itself (re-anchored accordingly when the scan root sits below a repo root), and the named-negation exit key un-excludes it like any other entry.
23
23
 
24
24
  | Group | Covers |
25
25
  | --- | --- |
26
26
  | `vcs` | `.git/`, `.hg/`, `.svn/` |
27
27
  | `deps` | `node_modules/`, `.pnpm/`, `vendor/` |
28
- | `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage/` |
29
- | `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
28
+ | `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage/`, `/target` (root-anchored — the cargo/maven build tree; nested same-named directories are untouched) |
29
+ | `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `venv/`, `.gradle/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
30
30
  | `agentDocs` | `AGENTS.md`, `CLAUDE.md` (files — agent self-loading instructions, not project content) |
31
31
 
32
32
  ## Boundary markers
@@ -49,6 +49,12 @@ Opt-in via `boundaryStones.gitignoreProxy`: treat a nested `.gitignore` as a bou
49
49
 
50
50
  `boundaryStones.exempt` names subtrees whose own core/`.gitignore` marker hits are neutralized — the submodule-registration analogue (git does not descend into an unregistered embedded repository; naming a subtree is the walk-mode way to register it). Entries are gitignore-style patterns anchored at the scan root (e.g. `'embedded-toolkit/'`). A matched directory descends as a native subtree: its nested `.gitignore` files apply by the ordinary nesting rules (re-anchored, never leaking outside the subtree), while deeper markers inside it still cut — the exemption reaches only the named directory's own hits. Config homes are never exemptible.
51
51
 
52
+ ### The walk stone report
53
+
54
+ `walkScope` results carry `stoneHits`: every marker hit the walk discovered, as `{ stoneName, path, enforced }` — the stone that hit, the scan-root-relative directory directly containing it, and whether the hit executed its cut under the active alignment face and exemption. Pure metadata: the report never changes the file set. On the default git face `enforced: true` names where truncations happened; under `alignment: 'scanner'` core-stone hits report `enforced: false` (report-not-cut — "this subtree is a nested repository"), and exemption-neutralized hits report `enforced: false` the same way (registration, not rescue). Config-home hits always report `enforced: true` — they are your own declarations and keep their verdict under every face. The scan root's own markers are not reported (the root is the universe boundary and never adjudicates against itself); only directories the walk visits as descent candidates appear. Sorted by path, then stone name.
55
+
56
+ The report's completeness is the walk's: only visited descent candidates are probed, so subtrees removed by the rule stack (preset, `exclude`, the dot category) and everything below a budget cut leave no hits — a silent absence is not negative evidence; check `diagnostics` for the budget case. The core `.git` marker matches both of git's own forms (a `.git` directory, or the `gitdir` pointer file a worktree or submodule carries), and `.gitmodules` registration is invisible to the walk — a registered submodule hits exactly like an embedded repository, with `boundaryStones.exempt` as the walk-mode registration for both.
57
+
52
58
  ## Scanner semantics
53
59
 
54
60
  With `alignment: 'scanner'` (ripgrep-style):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@catheadowl/pathscope",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
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": {