@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.
- package/CHANGELOG.md +90 -0
- package/LICENSE +21 -0
- package/README.md +127 -2
- package/dist/cascade.d.ts +16 -0
- package/dist/cascade.js +69 -0
- package/dist/cascade.js.map +1 -0
- package/dist/cjs/cascade.d.ts +16 -0
- package/dist/cjs/discover.d.ts +11 -0
- package/dist/cjs/engine.d.ts +6 -0
- package/dist/cjs/exclusion-engine.d.ts +79 -0
- package/dist/cjs/index.d.ts +22 -0
- package/dist/cjs/index.js +2102 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/paths.d.ts +13 -0
- package/dist/cjs/presets.d.ts +28 -0
- package/dist/cjs/types.d.ts +235 -0
- package/dist/cjs/universe.d.ts +27 -0
- package/dist/discover.d.ts +11 -0
- package/dist/discover.js +66 -0
- package/dist/discover.js.map +1 -0
- package/dist/engine.d.ts +6 -0
- package/dist/engine.js +117 -0
- package/dist/engine.js.map +1 -0
- package/dist/exclusion-engine.d.ts +79 -0
- package/dist/exclusion-engine.js +352 -0
- package/dist/exclusion-engine.js.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/paths.d.ts +13 -0
- package/dist/paths.js +28 -0
- package/dist/paths.js.map +1 -0
- package/dist/presets.d.ts +28 -0
- package/dist/presets.js +77 -0
- package/dist/presets.js.map +1 -0
- package/dist/types.d.ts +235 -0
- package/dist/types.js +28 -0
- package/dist/types.js.map +1 -0
- package/dist/universe.d.ts +27 -0
- package/dist/universe.js +219 -0
- package/dist/universe.js.map +1 -0
- package/docs/glossary.md +59 -0
- package/docs/semantics.md +73 -0
- 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
|
-
#
|
|
1
|
+
# pathscope
|
|
2
2
|
|
|
3
|
-
|
|
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[];
|
package/dist/cascade.js
ADDED
|
@@ -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';
|