@catheadowl/pathscope 0.0.0-stage → 0.1.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.
Files changed (44) hide show
  1. package/CHANGELOG.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +127 -2
  4. package/dist/cascade.d.ts +16 -0
  5. package/dist/cascade.js +69 -0
  6. package/dist/cascade.js.map +1 -0
  7. package/dist/cjs/cascade.d.ts +16 -0
  8. package/dist/cjs/discover.d.ts +11 -0
  9. package/dist/cjs/engine.d.ts +6 -0
  10. package/dist/cjs/exclusion-engine.d.ts +79 -0
  11. package/dist/cjs/index.d.ts +22 -0
  12. package/dist/cjs/index.js +2102 -0
  13. package/dist/cjs/package.json +1 -0
  14. package/dist/cjs/paths.d.ts +13 -0
  15. package/dist/cjs/presets.d.ts +28 -0
  16. package/dist/cjs/types.d.ts +235 -0
  17. package/dist/cjs/universe.d.ts +27 -0
  18. package/dist/discover.d.ts +11 -0
  19. package/dist/discover.js +66 -0
  20. package/dist/discover.js.map +1 -0
  21. package/dist/engine.d.ts +6 -0
  22. package/dist/engine.js +117 -0
  23. package/dist/engine.js.map +1 -0
  24. package/dist/exclusion-engine.d.ts +79 -0
  25. package/dist/exclusion-engine.js +352 -0
  26. package/dist/exclusion-engine.js.map +1 -0
  27. package/dist/index.d.ts +22 -0
  28. package/dist/index.js +21 -0
  29. package/dist/index.js.map +1 -0
  30. package/dist/paths.d.ts +13 -0
  31. package/dist/paths.js +28 -0
  32. package/dist/paths.js.map +1 -0
  33. package/dist/presets.d.ts +28 -0
  34. package/dist/presets.js +77 -0
  35. package/dist/presets.js.map +1 -0
  36. package/dist/types.d.ts +235 -0
  37. package/dist/types.js +28 -0
  38. package/dist/types.js.map +1 -0
  39. package/dist/universe.d.ts +27 -0
  40. package/dist/universe.js +219 -0
  41. package/dist/universe.js.map +1 -0
  42. package/docs/glossary.md +59 -0
  43. package/docs/semantics.md +73 -0
  44. package/package.json +53 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,90 @@
1
+ ---
2
+ description: pathscope changelog — user-visible changes per release, newest first
3
+ ---
4
+
5
+ # Changelog
6
+
7
+ All notable changes to this project are documented here. The format follows
8
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
9
+
10
+ ## 0.1.0 — 2026-10-24
11
+
12
+ First public cut.
13
+
14
+ ### Added
15
+
16
+ - **walk mode** — `walkScope(root, options)`: whole-tree pruning, gitignore
17
+ cascade (inherited + nested, one ordered rule stream, last-match-wins),
18
+ five mounted exclusion presets (vcs / deps / build / caches / agentDocs —
19
+ un-excludable via named `!`), policy layer, override whitelist (terminal
20
+ include), strict immune channel (outbound artifact boundaries, written
21
+ reason mandatory), boundary stones (always-on `.git` core stone, opt-in
22
+ config homes and `.gitignore` proxy), dot-entry walk option, symlinks
23
+ unresolved by default, and a loud file budget (default 2000 — never a
24
+ silent cut). `respectGitignore: false` skips the gitignore sources only —
25
+ presets, the policy layer, the override whitelist, and boundary stones
26
+ are unaffected.
27
+ - **named-subtree core-stone exemption** — `boundaryStones.exempt`:
28
+ gitignore-style patterns anchored at the scan root (e.g.
29
+ `'embedded-toolkit/'`) naming subtrees whose own `.git` no longer
30
+ truncates them — the submodule-registration isomorphism. A matched
31
+ directory descends as a native subtree (nested `.gitignore` files fold by
32
+ the ordinary nesting rules), while a deeper embedded `.git` inside it is
33
+ still a stone and un-named siblings keep the cut. The exemption reaches
34
+ only the core stone (config homes and the `.gitignore` proxy are never
35
+ exemptible) and is registration, not rescue. On the composable engine
36
+ face, `excludeDirectory`'s `stoneHit` parameter additionally accepts
37
+ per-stone hit names (`boolean | readonly string[]`); the boolean form
38
+ still truncates unconditionally.
39
+ - **proxy-stone exemption** — `boundaryStones.exempt` reaches the
40
+ `.gitignore` proxy stone under the same rules: naming a subtree revokes
41
+ its proxy registration — the named subtree returns to the git-native
42
+ default where a nested `.gitignore` is rules, not territory. Config homes
43
+ stay never-exemptible; a co-hit of the exemptible kinds in one directory
44
+ is neutralized by the single naming; deeper proxy stones inside the named
45
+ subtree are still stones. A degenerate `.gitignore` config-home
46
+ declaration under a mounted proxy stone is rejected as a configuration
47
+ error.
48
+ - **alignment faces** — `alignment?: 'git' | 'scanner'` (default `'git'`):
49
+ two named faces over one decision core. The git face is the standing
50
+ semantics (core-stone truncation). The scanner face (rg/fd family parity)
51
+ suspends core-stone enforcement — report-not-cut: the `.git` stone stays
52
+ in the probe contract and the per-stone `stoneHit` report keeps naming it
53
+ ("this subtree is a nested repository" metadata) while the truncation
54
+ never executes, at any depth. Config-home stones keep their verdict under
55
+ every face; mounting `gitignoreProxy` under the scanner face is rejected
56
+ as a configuration error. On the composable face the scanner semantics
57
+ ride the array `stoneHit` form of `excludeDirectory`; the boolean form
58
+ keeps its unconditional cut.
59
+ - **git universe** — `gitUniverse(root, options)`: ask git instead of
60
+ walking. Variants `all` (tracked + untracked-but-not-ignored), `tree`
61
+ (index contents), `staged` (A/C/M/R vs HEAD). Gitlink submodules
62
+ (mode 160000) and symlinks (mode 120000) never enter the universe;
63
+ repository root memoized per root (`clearUniverseCache` resets); opt-in
64
+ `filter` post-filter (a tracked `node_modules` belongs in the universe).
65
+ - **config discovery** — `locateNearest(names, {cwd, stopAt})`:
66
+ nearest-wins residence lookup (nested config = governance boundary;
67
+ `stopAt` inclusive). Locates only — parsing stays consumer-side.
68
+ - **composable decision core** — `createExclusionEngine(rootKey, options?,
69
+ io?)`: the exclusion stack + gitignore cascade behind walkScope as a
70
+ standalone engine for consumers that own their own traversal (incremental
71
+ snapshots, watcher feeds, URI/remote filesystems). Construction runs the
72
+ inherited phase through an injectable async `ExclusionIO`
73
+ (`nodeExclusionIO` is the node default); adjudication is pure and
74
+ synchronous — `excludeDirectory(name, dirPath, stoneHit?)` → (descend) →
75
+ `foldGitignore(dirPath, text)` → `admitFile(relPath)` mirrors walkScope's
76
+ per-directory sequence, no budget (the loud budget stays with walkScope).
77
+ - **conformance corpus** — self-contained fixtures of two provenance kinds
78
+ (git-oracle-adjudicated and registered extensions), language-neutral for
79
+ cross-language ports.
80
+ - `PathscopeConfigError` (malformed options fail loudly) and
81
+ `PathscopeGitError` (git missing / not a repository / git failed — the
82
+ message names the command).
83
+ - **dual-format package** — a CommonJS require condition
84
+ (`dist/cjs/index.js`, an esbuild bundle that inlines the ESM-only find-up
85
+ so the CJS artifact runs on the same Node range as the ESM face) alongside
86
+ the ESM default (`esbuild` is a devDependency, build-time only).
87
+
88
+ ### Changed
89
+
90
+ - Nothing yet — this is the first release.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CatheadOwl
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,128 @@
1
- # Temporary Holding Version
1
+ # pathscope
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Resolve the set of files a tool should see in a repository — git-native by default.
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`).
6
+
7
+ ## Features
8
+
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
+ - **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
+ - **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
12
+ - **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
+ - **ESM + CommonJS** — dual build, Node.js >= 20.
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ npm install @catheadowl/pathscope
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ ```js
24
+ import { walkScope } from '@catheadowl/pathscope';
25
+
26
+ // Default stack: gitignore cascade + vcs/deps/build presets + dot entries
27
+ // excluded + loud budget (2000).
28
+ const { files, diagnostics } = await walkScope('/repo');
29
+ console.log(files);
30
+ //=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
31
+
32
+ console.log(diagnostics);
33
+ //=> [] — non-empty means the budget cut the scan (code: 'budget-exceeded')
34
+ ```
35
+
36
+ All output paths are POSIX-style relative to the scanned root, sorted.
37
+
38
+ ```js
39
+ // Mount more presets, add your own ignore rules, and rescue paths with
40
+ // the override whitelist (final say — it outranks presets, gitignore
41
+ // rules, and the dot category).
42
+ const { files } = await walkScope('/repo', {
43
+ mountPresets: ['vcs', 'deps', 'build', 'caches'],
44
+ exclude: ['sandbox/', '*.snapshot.md'],
45
+ override: ['vendor/generated/api.md'],
46
+ });
47
+ ```
48
+
49
+ ### Ask git instead of walking
50
+
51
+ ```js
52
+ import { gitUniverse } from '@catheadowl/pathscope';
53
+
54
+ // Tracked + untracked-but-not-ignored files, straight from git. No
55
+ // filesystem walk — git is the truth, the exclusion stack does not
56
+ // participate (a tracked node_modules belongs in the result).
57
+ const { files, repoRoot } = await gitUniverse('/repo');
58
+
59
+ // Staged changes (A/C/M/R vs HEAD) with an opt-in post-filter.
60
+ const publishable = await gitUniverse('/repo', {
61
+ variant: 'staged',
62
+ filter: { mountPresets: ['deps', 'caches'] },
63
+ });
64
+ ```
65
+
66
+ ### Compose the exclusion engine into your own traversal
67
+
68
+ Watchers, incremental snapshots, and virtual filesystems cannot use the built-in walker. `createExclusionEngine` gives them the same exclusion stack + gitignore cascade as a standalone engine:
69
+
70
+ ```js
71
+ import { createExclusionEngine } from '@catheadowl/pathscope';
72
+
73
+ const engine = await createExclusionEngine('/repo/src');
74
+ for (const entry of await myReadDir('/repo/src')) {
75
+ if (entry.isDirectory) {
76
+ const stoneHit = await probeStones(engine.stoneNames, entry.path); // your own existence probes
77
+ if (engine.excludeDirectory(entry.name, entry.path, stoneHit)) continue; // prune the subtree
78
+ engine.foldGitignore(entry.path, await myReadGitignore(entry.path)); // fold on descent
79
+ await descend(entry.path);
80
+ } else if (engine.admitFile(relativePosix(entry.path))) {
81
+ keep(entry.path);
82
+ }
83
+ }
84
+ ```
85
+
86
+ The file budget belongs to `walkScope` — the engine has none.
87
+
88
+ ### Locate the nearest config file
89
+
90
+ ```js
91
+ import { locateNearest } from '@catheadowl/pathscope';
92
+
93
+ const home = locateNearest(['toolkit.toml', '.specs/collect.config.toml'], {
94
+ cwd: '/repo/src',
95
+ stopAt: '/repo', // inclusive — beyond it, a config file belongs to a different project
96
+ });
97
+ //=> { name: 'toolkit.toml', path: '/repo/toolkit.toml' } | null
98
+ ```
99
+
100
+ Files are only located, never read or parsed — TOML/YAML handling stays with you.
101
+
102
+ ## API
103
+
104
+ | Export | One-line |
105
+ | --- | --- |
106
+ | `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics }` |
107
+ | `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
108
+ | `locateNearest(names, options?)` | Nearest config file, no parsing |
109
+ | `createExclusionEngine(root, options?, io?)` | The exclusion engine for your own traversal |
110
+ | `PRESETS` / `DEFAULT_MOUNTED_PRESETS` | Preset contents |
111
+ | `PathscopeConfigError` / `PathscopeGitError` | Fail-loud error classes |
112
+
113
+ Full signatures, option tables, and return shapes live in the `.d.ts` files shipped in this package — every export carries complete doc comments (the same comments your editor renders as IntelliSense).
114
+
115
+ ## Documentation
116
+
117
+ - [docs/glossary.md](docs/glossary.md) — the domain vocabulary
118
+ - [docs/semantics.md](docs/semantics.md) — presets, boundary markers, precedence order
119
+
120
+ ## Related
121
+
122
+ - [ignore](https://github.com/kaelzhang/node-ignore) — the gitignore kernel pathscope rides
123
+ - [fast-glob](https://github.com/mrmlnc/fast-glob) / [globby](https://github.com/sindresorhus/globby) — pattern-matching walkers
124
+ - [find-up](https://github.com/sindresorhus/find-up) — the config-discovery kernel
125
+
126
+ ## License
127
+
128
+ MIT
@@ -0,0 +1,16 @@
1
+ /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
2
+ export declare function readGitignoreText(dirPath: string): string | null;
3
+ /** Split gitignore text into lines, tolerating CRLF. */
4
+ export declare function splitLines(text: string): string[];
5
+ /**
6
+ * Re-anchor a base's rule lines into the canonical space by prefixing
7
+ * `prefix` (the base's POSIX path in that space; never ''). Anchoring rules
8
+ * (gitignore(5)):
9
+ * - a pattern with a leading `/` or a middle separator is anchored at its
10
+ * base → `prefix/<pattern>`;
11
+ * - a bare name matches at any depth below its base → the same name under
12
+ * a `**` bridge (`**` spans zero levels too, so the base level still
13
+ * matches).
14
+ * Negation prefixes and backslash escapes pass through untouched.
15
+ */
16
+ export declare function reanchorLines(lines: string[], prefix: string): string[];
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Cascade rule plumbing (self-written over the node-ignore kernel).
3
+ *
4
+ * git's nested-.gitignore semantics = one ordered rule stream, shallow rules
5
+ * first and deep rules later, last-match-wins over the whole stream (so a
6
+ * deeper `!` defeats a shallower exclusion).
7
+ * The stream lives in ONE canonical rule space anchored at the inheritance
8
+ * top (the git root found during engine construction, or the disk root for
9
+ * non-repo scans):
10
+ *
11
+ * - rules from `.gitignore` files at/above the scan root are already
12
+ * natively expressed in that space and are added VERBATIM;
13
+ * - rules from the scan root's own `.gitignore`, from nested `.gitignore`
14
+ * files discovered during the walk, and from the engine's scan-root-based
15
+ * layers (presets, policy, override, strict) are re-anchored into the
16
+ * space by prefixing their base's canonical path.
17
+ *
18
+ * Every re-anchored rule is subtree-scoped (anchored patterns get the base
19
+ * prefix; bare names get a `**` bridge under the base), so appending a deeper
20
+ * layer's rules mid-walk can never leak onto sibling branches — the
21
+ * append-only stream is "parent rules first, this layer after".
22
+ * The inherited phase itself (the upward
23
+ * `.git` probe and the read-down) lives in exclusion-engine.ts construction
24
+ * over the injectable ExclusionIO, so URI-filesystem consumers ride the
25
+ * same logic.
26
+ */
27
+ import { readFileSync } from 'node:fs';
28
+ /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
29
+ export function readGitignoreText(dirPath) {
30
+ try {
31
+ return readFileSync(`${dirPath.replace(/\/+$/, '')}/.gitignore`, 'utf8');
32
+ }
33
+ catch {
34
+ return null;
35
+ }
36
+ }
37
+ /** Split gitignore text into lines, tolerating CRLF. */
38
+ export function splitLines(text) {
39
+ return text.split(/\r?\n/);
40
+ }
41
+ /**
42
+ * Re-anchor a base's rule lines into the canonical space by prefixing
43
+ * `prefix` (the base's POSIX path in that space; never ''). Anchoring rules
44
+ * (gitignore(5)):
45
+ * - a pattern with a leading `/` or a middle separator is anchored at its
46
+ * base → `prefix/<pattern>`;
47
+ * - a bare name matches at any depth below its base → the same name under
48
+ * a `**` bridge (`**` spans zero levels too, so the base level still
49
+ * matches).
50
+ * Negation prefixes and backslash escapes pass through untouched.
51
+ */
52
+ export function reanchorLines(lines, prefix) {
53
+ const out = [];
54
+ for (const line of lines) {
55
+ if (line === '' || line.startsWith('#'))
56
+ continue;
57
+ const negative = line.startsWith('!');
58
+ const body = negative ? line.slice(1) : line;
59
+ if (body === '')
60
+ continue; // a bare '!' is discarded, as git does
61
+ const anchored = body.startsWith('/') || body.slice(0, -1).includes('/');
62
+ const reanchored = anchored
63
+ ? `${prefix}/${body.startsWith('/') ? body.slice(1) : body}`
64
+ : `${prefix}/**/${body}`;
65
+ out.push(negative ? `!${reanchored}` : reanchored);
66
+ }
67
+ return out;
68
+ }
69
+ //# sourceMappingURL=cascade.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cascade.js","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,MAAc;IAC3D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7C,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS,CAAC,uCAAuC;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACzE,MAAM,UAAU,GAAG,QAAQ;YACzB,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YAC5D,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC;QAC3B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
@@ -0,0 +1,16 @@
1
+ /** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
2
+ export declare function readGitignoreText(dirPath: string): string | null;
3
+ /** Split gitignore text into lines, tolerating CRLF. */
4
+ export declare function splitLines(text: string): string[];
5
+ /**
6
+ * Re-anchor a base's rule lines into the canonical space by prefixing
7
+ * `prefix` (the base's POSIX path in that space; never ''). Anchoring rules
8
+ * (gitignore(5)):
9
+ * - a pattern with a leading `/` or a middle separator is anchored at its
10
+ * base → `prefix/<pattern>`;
11
+ * - a bare name matches at any depth below its base → the same name under
12
+ * a `**` bridge (`**` spans zero levels too, so the base level still
13
+ * matches).
14
+ * Negation prefixes and backslash escapes pass through untouched.
15
+ */
16
+ export declare function reanchorLines(lines: string[], prefix: string): string[];
@@ -0,0 +1,11 @@
1
+ import { type DiscoveryResult, type LocateNearestOptions } from './types.ts';
2
+ /**
3
+ * Locate the nearest config residence at or above `options.cwd` (default
4
+ * `process.cwd()`): the first directory on the way up that directly contains
5
+ * one of `names` wins; within one directory, earlier-declared names win.
6
+ * The walk stops after examining `options.stopAt` (inclusive) — beyond that
7
+ * boundary a residence belongs to a different governance domain. Returns
8
+ * `{name, path}` or `null` when no residence exists in bounds. No file is
9
+ * ever read or parsed.
10
+ */
11
+ export declare function locateNearest(names: string[], options?: LocateNearestOptions): DiscoveryResult | null;
@@ -0,0 +1,6 @@
1
+ import { type ScopeOptions, type WalkResult } from './types.ts';
2
+ /**
3
+ * Walk `root` and produce the in-scope file set: POSIX relative paths, sorted,
4
+ * plus loud diagnostics. See {@link ScopeOptions} for the exclusion stack.
5
+ */
6
+ export declare function walkScope(root: string, options?: ScopeOptions): Promise<WalkResult>;
@@ -0,0 +1,79 @@
1
+ import { type ScopeOptions } from './types.ts';
2
+ /**
3
+ * Filesystem access for the engine's construction-time inherited phase.
4
+ * Methods receive POSIX-separator absolute directory keys —
5
+ * consumers on URI/remote filesystems map the keys back to their own handles.
6
+ */
7
+ export interface ExclusionIO {
8
+ /**
9
+ * Probe whether `name` (a relative POSIX name, possibly multi-segment like
10
+ * `.specs/collect.config.toml`) exists inside `dirKey`. File and
11
+ * directory both count (the dual-form `.git` contract).
12
+ */
13
+ exists(dirKey: string, name: string): Promise<boolean>;
14
+ /** Read `<dirKey>/.gitignore` (UTF-8); null when absent or unreadable. */
15
+ readGitignore(dirKey: string): Promise<string | null>;
16
+ }
17
+ /** Default IO over the node filesystem (existsSync / readFileSync). */
18
+ export declare const nodeExclusionIO: ExclusionIO;
19
+ /** A composable exclusion engine over one scan root. Not concurrent-safe: one engine per traversal run. */
20
+ export interface ExclusionEngine {
21
+ /** The scan root key as passed at construction (POSIX-separator absolute). */
22
+ readonly rootKey: string;
23
+ /**
24
+ * Stone names the caller must existence-probe in every candidate directory
25
+ * before adjudication (always starts with the core `.git`; then declared
26
+ * config homes; then `.gitignore` when the proxy stone is opted into).
27
+ * Under the scanner alignment face the core `.git` stays in this probe set
28
+ * (its hit is still reportable metadata in the array form) but never
29
+ * truncates — report, not enforce.
30
+ */
31
+ readonly stoneNames: readonly string[];
32
+ /**
33
+ * Per-directory adjudication (pure): stones (via `stoneHit` — the caller's
34
+ * probe of {@link ExclusionEngine.stoneNames} in the directory, the scan
35
+ * root itself never truncates) → strict → override → combined table → dot
36
+ * category. True = exclude the directory (the caller prunes the subtree and
37
+ * does NOT fold). False = descend: the caller reads the directory's
38
+ * `.gitignore` and passes it to {@link ExclusionEngine.foldGitignore}.
39
+ *
40
+ * `stoneHit` takes two forms. The boolean form (a hit is a hit) is the
41
+ * original contract; the array form reports the NAMES of the stones that
42
+ * hit (any subset of {@link ExclusionEngine.stoneNames}) and is required
43
+ * for BOTH per-name adjudications: the `boundaryStones.exempt` key (the
44
+ * exemption neutralizes the exemptible stone kinds — the core `.git`
45
+ * and, when the proxy stone is mounted, `.gitignore` itself; config
46
+ * homes are never exemptible) and the `alignment: 'scanner'` face (the
47
+ * report-not-cut policy drops the core-stone kind BY NAME). The engine
48
+ * must see which stones hit; on an unspecified boolean hit neither
49
+ * applies and the directory truncates unconditionally — a consumer
50
+ * mounting the scanner face that drives the boolean form silently loses
51
+ * the face. Report names, not booleans.
52
+ */
53
+ excludeDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): boolean;
54
+ /**
55
+ * Fold a descended directory's `.gitignore` text into the cascade (shallow
56
+ * first, deep later — appended at the rear of the rule stream, subtree-
57
+ * scoped by re-anchoring). No-op when `text` is null/undefined, when the
58
+ * walk skipped gitignore respect, or when `dirPath` is the scan root (the
59
+ * root's own `.gitignore` is consumed at construction).
60
+ */
61
+ foldGitignore(dirPath: string, text: string | null | undefined): void;
62
+ /**
63
+ * Per-file adjudication (pure) for a scan-root-relative POSIX path: strict
64
+ * → override → combined table → dot category. No budget — the loud file
65
+ * budget is a chassis concern owned by walkScope.
66
+ */
67
+ admitFile(relPath: string): boolean;
68
+ }
69
+ /** Validate options; malformed configuration fails loudly instead of scanning differently. */
70
+ export declare function validateOptions(options: ScopeOptions): void;
71
+ /**
72
+ * Build the composable exclusion engine for `rootKey` (a POSIX-separator
73
+ * absolute path key — native roots must be resolved and separator-normalized
74
+ * by the caller first, as walkScope does). Options are the shared
75
+ * {@link ScopeOptions} face; the chassis fields (`maxFiles`,
76
+ * `followSymlinks`) are accepted and ignored — the engine has no budget and
77
+ * never touches symlinks.
78
+ */
79
+ export declare function createExclusionEngine(rootKey: string, options?: ScopeOptions, io?: ExclusionIO): Promise<ExclusionEngine>;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * pathscope — cross-repo file-scope engine, public surface.
3
+ *
4
+ * Two mutually exclusive ways to resolve the in-scope set (the "circle"
5
+ * axis): walk mode (walkScope over the fdir chassis with the gitignore
6
+ * cascade on the node-ignore kernel, mounted exclusion presets, override
7
+ * whitelist, strict immune channel, boundary stones, and a loud budget) or
8
+ * ask-git mode (gitUniverse — git is the truth, the exclusion stack does not
9
+ * participate). Config discovery (locateNearest) locates the nearest config
10
+ * residence and never parses it. Consumers that own their own traversal
11
+ * (incremental snapshots, watcher feeds, URI/remote filesystems) compose the
12
+ * same exclusion stack + cascade as a standalone decision core:
13
+ * createExclusionEngine.
14
+ */
15
+ export { walkScope } from './engine.ts';
16
+ export { createExclusionEngine, nodeExclusionIO } from './exclusion-engine.ts';
17
+ export type { ExclusionEngine, ExclusionIO } from './exclusion-engine.ts';
18
+ export { clearUniverseCache, gitUniverse } from './universe.ts';
19
+ export { locateNearest } from './discover.ts';
20
+ export { PRESETS, DEFAULT_MOUNTED_PRESETS } from './presets.ts';
21
+ export { PathscopeConfigError, PathscopeGitError } from './types.ts';
22
+ export type { AlignmentFace, BoundaryStonesOptions, DiscoveryResult, LocateNearestOptions, PresetName, ScanDiagnostic, ScopeOptions, StrictRule, UniverseFilter, UniverseOptions, UniverseResult, UniverseVariant, WalkResult, } from './types.ts';