@catheadowl/pathscope 0.0.0-stage → 0.1.1
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 +97 -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 +54 -4
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"commonjs"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path normalization helpers (the matching kernel is fed
|
|
3
|
+
* POSIX forward-slash paths relative to each rule base; win32 native paths
|
|
4
|
+
* are normalized here before they reach node-ignore).
|
|
5
|
+
*/
|
|
6
|
+
/** Native → POSIX separators (win32 backslashes become forward slashes). */
|
|
7
|
+
export declare function toPosix(p: string): string;
|
|
8
|
+
/** POSIX join where '' absorbs on either side ('' + 'x' = 'x'; 'a' + '' = 'a'). */
|
|
9
|
+
export declare function joinPosix(a: string, b: string): string;
|
|
10
|
+
/** Final path segment ('a/b.md' → 'b.md'; 'x' → 'x'). */
|
|
11
|
+
export declare function baseNamePosix(rel: string): string;
|
|
12
|
+
/** Directory portion of a POSIX relative path ('' when at the top level). */
|
|
13
|
+
export declare function dirNamePosix(rel: string): string;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The five mounted exclusion presets.
|
|
3
|
+
*
|
|
4
|
+
* Mounting is append-only and presets sit at the FRONT of the combined rule
|
|
5
|
+
* table: a named negation in any gitignore layer or in the policy layer can
|
|
6
|
+
* walk an entry back out (ESLint globalIgnores precedent — user `!` and
|
|
7
|
+
* deeper rules un-exclude preset defaults); no wholesale-replacement channel
|
|
8
|
+
* exists. Entry additions/removals are deliberate, versioned changes — the
|
|
9
|
+
* test suite pins the content snapshot as an anti-drift gate.
|
|
10
|
+
*/
|
|
11
|
+
import type { PresetName } from './types.ts';
|
|
12
|
+
/** Type guard used by option validation — unknown preset names fail loudly. */
|
|
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. */
|
|
15
|
+
export type Preset = {
|
|
16
|
+
dirs: string[];
|
|
17
|
+
files?: string[];
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* 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.
|
|
23
|
+
*/
|
|
24
|
+
export declare const PRESETS: Record<PresetName, Preset>;
|
|
25
|
+
/** The default mount set. */
|
|
26
|
+
export declare const DEFAULT_MOUNTED_PRESETS: readonly PresetName[];
|
|
27
|
+
/** Compile mounted presets (in mount order) into gitignore-style patterns. */
|
|
28
|
+
export declare function compilePresetPatterns(names: readonly PresetName[]): string[];
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public type surface for the pathscope engine: walk mode (ScopeOptions /
|
|
3
|
+
* WalkResult), git universe (UniverseOptions / UniverseResult), and config
|
|
4
|
+
* discovery (LocateNearestOptions / DiscoveryResult).
|
|
5
|
+
*
|
|
6
|
+
* The walk option face maps 1:1 onto the conformance fixtures' `extension`
|
|
7
|
+
* field: `mountPresets`, `override`, and the boundary stone declarations.
|
|
8
|
+
*/
|
|
9
|
+
/** The five mounted preset groups. */
|
|
10
|
+
export type PresetName = 'vcs' | 'deps' | 'build' | 'caches' | 'agentDocs';
|
|
11
|
+
/**
|
|
12
|
+
* A strict (immune) exclusion — the outbound-artifact-boundary channel
|
|
13
|
+
* (npm-packlist / cargo precedent). Index/retrieval consumers
|
|
14
|
+
* must not use it; every entry carries a written credential/integrity-level
|
|
15
|
+
* reason, and a reason-less entry is rejected as a configuration error.
|
|
16
|
+
*/
|
|
17
|
+
export interface StrictRule {
|
|
18
|
+
/** gitignore-style pattern, relative to the scan root. */
|
|
19
|
+
pattern: string;
|
|
20
|
+
/** Written reason why this boundary is immune rather than overridable. */
|
|
21
|
+
reason: string;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Opt-in boundary stones beyond the always-on core `.git` stone.
|
|
25
|
+
* Stones are existence signals only — content is never interpreted; a hit
|
|
26
|
+
* truncates the whole subtree (one-way cut).
|
|
27
|
+
*/
|
|
28
|
+
export interface BoundaryStonesOptions {
|
|
29
|
+
/**
|
|
30
|
+
* Config-home stone names (may be nested, e.g. `.specs/collect.config.toml`):
|
|
31
|
+
* a directory directly containing one of these is a declared sub-domain and
|
|
32
|
+
* its subtree is truncated. The consumer declares the name set.
|
|
33
|
+
*/
|
|
34
|
+
configHomes?: string[];
|
|
35
|
+
/**
|
|
36
|
+
* Treat a nested `.gitignore` as a boundary signal instead of more rules.
|
|
37
|
+
* Off by default because mainstream treats a nested .gitignore as rules,
|
|
38
|
+
* not territory.
|
|
39
|
+
*/
|
|
40
|
+
gitignoreProxy?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Named-subtree exemption of the boundary stones. Two exemptible kinds
|
|
43
|
+
* with different anchors: the core `.git` — the submodule registration isomorphism
|
|
44
|
+
* (git does not descend into an embedded repository it has not
|
|
45
|
+
* registered; naming a subtree here is the walk-mode face of that
|
|
46
|
+
* registration) — and, when {@link BoundaryStonesOptions.gitignoreProxy}
|
|
47
|
+
* is mounted, the `.gitignore` proxy stone itself: naming a subtree is
|
|
48
|
+
* the named revocation of that registration deviation, restoring the
|
|
49
|
+
* git-native default where a nested `.gitignore` is rules, not
|
|
50
|
+
* territory. Config homes are never exemptible (no registered need;
|
|
51
|
+
* dissolving a consumer's declared governance sub-domain by pattern is a
|
|
52
|
+
* different safety flavor). Entries are gitignore-style patterns
|
|
53
|
+
* anchored at the scan root (e.g. `'embedded-toolkit/'`); a matched
|
|
54
|
+
* directory descends as a native subtree — its nested `.gitignore` files
|
|
55
|
+
* fold by the ordinary nesting rules (re-anchored, never leaking outside
|
|
56
|
+
* the subtree), while deeper embedded stones inside it (a nested `.git`,
|
|
57
|
+
* a nested proxy hit) are still stones: the exemption reaches only the
|
|
58
|
+
* named directory's own hits of the exemptible kinds. A co-hit of the
|
|
59
|
+
* exemptible kinds in one directory is neutralized by the single naming
|
|
60
|
+
* (symmetric), and the stone keeps its verdict over every subtree the
|
|
61
|
+
* patterns do not name.
|
|
62
|
+
*/
|
|
63
|
+
exempt?: string[];
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The alignment faces over one decision core: named presets, not a new
|
|
67
|
+
* semantic axis. The face governs the git-native pair (the core `.git`
|
|
68
|
+
* stone and the `.gitignore` proxy stone) only.
|
|
69
|
+
*/
|
|
70
|
+
export type AlignmentFace = 'git' | 'scanner';
|
|
71
|
+
/** Options for {@link walkScope}. All fields optional; defaults are the product defaults. */
|
|
72
|
+
export interface ScopeOptions {
|
|
73
|
+
/**
|
|
74
|
+
* Preset groups to mount (append-only). Default
|
|
75
|
+
* `['vcs', 'deps', 'build']`. Pass `[]`
|
|
76
|
+
* to mount none. There is no wholesale-replacement channel: un-excluding a
|
|
77
|
+
* preset entry is done by a named negation (`!vendor/`) in a gitignore
|
|
78
|
+
* layer or the policy layer.
|
|
79
|
+
*/
|
|
80
|
+
mountPresets?: PresetName[];
|
|
81
|
+
/**
|
|
82
|
+
* Policy layer: consumer-declared exclusion rules (gitignore-style patterns
|
|
83
|
+
* relative to the scan root), appended at the END of the combined rule
|
|
84
|
+
* table — they may override presets and gitignore rules, and may negate.
|
|
85
|
+
*/
|
|
86
|
+
exclude?: string[];
|
|
87
|
+
/**
|
|
88
|
+
* Override whitelist — the terminal include, highest precedence. Rescues
|
|
89
|
+
* everything below it, including preset defaults
|
|
90
|
+
* and the dot category; naming a directory itself (`cache/`) restores
|
|
91
|
+
* descent into it. Only the strict immune channel outranks it.
|
|
92
|
+
*/
|
|
93
|
+
override?: string[];
|
|
94
|
+
/** Strict immune exclusions — see {@link StrictRule}. */
|
|
95
|
+
strict?: StrictRule[];
|
|
96
|
+
/**
|
|
97
|
+
* Alignment face — which family's native semantics the core-stone channel
|
|
98
|
+
* aligns to. `'git'` (default): the
|
|
99
|
+
* git-VCS family — an unregistered nested repository truncates whole (the
|
|
100
|
+
* core `.git` stone), and `boundaryStones.exempt` is the registration face
|
|
101
|
+
* (the submodule-registration isomorphism). `'scanner'`: the scanner family
|
|
102
|
+
* (rg/fd; ignore-crate/WalkBuilder parity) — nested repositories do not
|
|
103
|
+
* truncate, at any depth, and a nested `.gitignore` is rules, not
|
|
104
|
+
* territory. Under the scanner face the core stone is reported but not
|
|
105
|
+
* enforced: it stays in the probe contract and the per-stone `stoneHit`
|
|
106
|
+
* report keeps naming `.git` (consumer-visible "this subtree is a nested
|
|
107
|
+
* repository" metadata) while the cut never executes; `exempt` entries
|
|
108
|
+
* targeting the core stone are inert. Config-home stones are consumer
|
|
109
|
+
* self-declared governance and keep their verdict under every face;
|
|
110
|
+
* mounting `gitignoreProxy` under the scanner face is rejected as a
|
|
111
|
+
* configuration error (the two intentions contradict). On the composable
|
|
112
|
+
* face (`createExclusionEngine`) the scanner semantics ride the ARRAY
|
|
113
|
+
* `stoneHit` form of `excludeDirectory` — the boolean form keeps its
|
|
114
|
+
* unconditional cut (an unspecified hit cannot be attributed to the
|
|
115
|
+
* unenforced core stone).
|
|
116
|
+
*/
|
|
117
|
+
alignment?: AlignmentFace;
|
|
118
|
+
/** Opt-in boundary stones — see {@link BoundaryStonesOptions}. */
|
|
119
|
+
boundaryStones?: BoundaryStonesOptions;
|
|
120
|
+
/**
|
|
121
|
+
* Exclude dot entries (rg `hidden` semantics: a walk-layer option, not a
|
|
122
|
+
* gitignore rule). Default `true`. The override
|
|
123
|
+
* whitelist can rescue dot entries.
|
|
124
|
+
*/
|
|
125
|
+
excludeDotEntries?: boolean;
|
|
126
|
+
/**
|
|
127
|
+
* Respect `.gitignore` rules (inherited phase + walk-time folding). Default
|
|
128
|
+
* `true`. `false` is the layered escape hatch (rg `--no-ignore` precedent):
|
|
129
|
+
* only the gitignore sources are
|
|
130
|
+
* skipped — mounted presets, the policy layer, the override whitelist, and
|
|
131
|
+
* boundary stones adjudicate exactly as before.
|
|
132
|
+
*/
|
|
133
|
+
respectGitignore?: boolean;
|
|
134
|
+
/**
|
|
135
|
+
* Loud file budget: when the scan would include more than this many files,
|
|
136
|
+
* traversal is cut and a diagnostic is emitted — never a silent cut.
|
|
137
|
+
* Default `2000`.
|
|
138
|
+
*/
|
|
139
|
+
maxFiles?: number;
|
|
140
|
+
/** Follow symlinks during traversal. Default `false` (git/ripgrep default). */
|
|
141
|
+
followSymlinks?: boolean;
|
|
142
|
+
}
|
|
143
|
+
/** A loud diagnostic emitted by a scan. The budget cut is the canonical case. */
|
|
144
|
+
export type ScanDiagnostic = {
|
|
145
|
+
code: 'budget-exceeded';
|
|
146
|
+
/** Human-readable statement of the cut. */
|
|
147
|
+
message: string;
|
|
148
|
+
/** The budget limit that was hit. */
|
|
149
|
+
limit: number;
|
|
150
|
+
};
|
|
151
|
+
/** Result of a {@link walkScope} run. */
|
|
152
|
+
export interface WalkResult {
|
|
153
|
+
/** Included files as POSIX relative paths (forward slashes), sorted. */
|
|
154
|
+
files: string[];
|
|
155
|
+
/** Diagnostics; empty when the scan completed without a cut. */
|
|
156
|
+
diagnostics: ScanDiagnostic[];
|
|
157
|
+
}
|
|
158
|
+
/** Thrown for malformed engine configuration (a strict rule without a reason, an unknown preset, ...). */
|
|
159
|
+
export declare class PathscopeConfigError extends Error {
|
|
160
|
+
constructor(message: string);
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Thrown when the git universe cannot be asked: the git binary is missing,
|
|
164
|
+
* the root is not inside a repository, or a git command failed. The message
|
|
165
|
+
* always names the command that failed (fail loud, never scan
|
|
166
|
+
* the filesystem as a silent fallback).
|
|
167
|
+
*/
|
|
168
|
+
export declare class PathscopeGitError extends Error {
|
|
169
|
+
constructor(message: string);
|
|
170
|
+
}
|
|
171
|
+
/** The git-universe variants. */
|
|
172
|
+
export type UniverseVariant = 'all' | 'tree' | 'staged';
|
|
173
|
+
/**
|
|
174
|
+
* Opt-in post-filter over the raw git universe ("git as truth" —
|
|
175
|
+
* the exclusion stack does NOT participate by default; a tracked
|
|
176
|
+
* node_modules belongs in the universe). Policy-layer semantics on the
|
|
177
|
+
* node-ignore kernel: preset patterns sit at the FRONT of a combined rule
|
|
178
|
+
* table, `exclude` patterns at the REAR (they may override presets and may
|
|
179
|
+
* negate). This is not the full walk stack — no boundary stones, no strict
|
|
180
|
+
* channel, no dot category, no budget.
|
|
181
|
+
*/
|
|
182
|
+
export interface UniverseFilter {
|
|
183
|
+
/** Preset groups to mount at the front of the filter table. Default: none. */
|
|
184
|
+
mountPresets?: PresetName[];
|
|
185
|
+
/**
|
|
186
|
+
* Consumer-declared gitignore-style patterns relative to the passed root,
|
|
187
|
+
* appended after the presets (rear seat — they win, and may negate).
|
|
188
|
+
*/
|
|
189
|
+
exclude?: string[];
|
|
190
|
+
}
|
|
191
|
+
/** Options for {@link gitUniverse}. */
|
|
192
|
+
export interface UniverseOptions {
|
|
193
|
+
/** Which universe to ask git for. Default `'all'`. */
|
|
194
|
+
variant?: UniverseVariant;
|
|
195
|
+
/** Opt-in post-filter — see {@link UniverseFilter}. Default: none (raw git truth). */
|
|
196
|
+
filter?: UniverseFilter;
|
|
197
|
+
}
|
|
198
|
+
/** Result of a {@link gitUniverse} run. */
|
|
199
|
+
export interface UniverseResult {
|
|
200
|
+
/**
|
|
201
|
+
* The universe as POSIX relative paths from the PASSED root (not the repo
|
|
202
|
+
* root), sorted. When the root is a subdirectory, the universe is that
|
|
203
|
+
* subtree only — git's own cwd limiting, mirrored verbatim.
|
|
204
|
+
*/
|
|
205
|
+
files: string[];
|
|
206
|
+
/** Repository root as git reports it (`rev-parse --show-toplevel`). */
|
|
207
|
+
repoRoot: string;
|
|
208
|
+
/**
|
|
209
|
+
* Diagnostics; always empty in 0.1.0 (the universe has no budget — git is
|
|
210
|
+
* the authority, not a traversal that could be cut). The field exists for
|
|
211
|
+
* shape parity with {@link WalkResult}.
|
|
212
|
+
*/
|
|
213
|
+
diagnostics: ScanDiagnostic[];
|
|
214
|
+
}
|
|
215
|
+
/** Options for {@link locateNearest}. */
|
|
216
|
+
export interface LocateNearestOptions {
|
|
217
|
+
/** Directory the upward walk starts from. Default: `process.cwd()`. */
|
|
218
|
+
cwd?: string;
|
|
219
|
+
/**
|
|
220
|
+
* Directory at which the upward walk stops, inclusive — the stop directory
|
|
221
|
+
* itself is the last one examined. Beyond it, a nearer-looking residence is
|
|
222
|
+
* a different governance boundary.
|
|
223
|
+
*/
|
|
224
|
+
stopAt?: string;
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* A located config residence. `name` is the matched entry of
|
|
228
|
+
* the declared name set (multi-segment names stay whole, e.g.
|
|
229
|
+
* `.specs/collect.config.toml`); `path` is its absolute location.
|
|
230
|
+
* Parsing stays consumer-side — pathscope is format-neutral.
|
|
231
|
+
*/
|
|
232
|
+
export interface DiscoveryResult {
|
|
233
|
+
name: string;
|
|
234
|
+
path: string;
|
|
235
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { type UniverseOptions, type UniverseResult } from './types.ts';
|
|
2
|
+
/** Empty the repository-root memoization (test seam; production callers never need it). */
|
|
3
|
+
export declare function clearUniverseCache(): void;
|
|
4
|
+
/**
|
|
5
|
+
* Parse `ls-files -z --stage` records into paths, dropping gitlink submodules
|
|
6
|
+
* (160000) and symlinks (120000). Records from `--others` carry no stage
|
|
7
|
+
* prefix (no tab) and are kept as-is. Conflicted paths appear once per stage;
|
|
8
|
+
* the Set deduplicates. Input paths are repo-root-relative.
|
|
9
|
+
*/
|
|
10
|
+
export declare function filterLsFilesStageRecords(stdout: string): string[];
|
|
11
|
+
/**
|
|
12
|
+
* Parse `diff --cached -z --raw` records, dropping entries whose destination
|
|
13
|
+
* mode is a gitlink (160000) or symlink (120000). `--no-renames` is always
|
|
14
|
+
* passed by the caller, so every record is header + exactly one path; the
|
|
15
|
+
* defensive R/C branch keeps the parser honest if that ever changes.
|
|
16
|
+
*/
|
|
17
|
+
export declare function filterDiffRawRecords(stdout: string): string[];
|
|
18
|
+
/**
|
|
19
|
+
* Ask git for the file universe of `root`. Variants:
|
|
20
|
+
* `'all'` (default) tracked + untracked-but-not-ignored; `'tree'` the index
|
|
21
|
+
* contents only; `'staged'` the A/C/M/R changes staged vs HEAD (publish
|
|
22
|
+
* semantics). The exclusion stack does not participate — mount
|
|
23
|
+
* `options.filter` to post-filter with preset + policy patterns. Throws
|
|
24
|
+
* {@link PathscopeGitError} when git is missing or the root is outside any
|
|
25
|
+
* repository, and {@link PathscopeConfigError} for a malformed filter.
|
|
26
|
+
*/
|
|
27
|
+
export declare function gitUniverse(root: string, options?: UniverseOptions): Promise<UniverseResult>;
|
|
@@ -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;
|
package/dist/discover.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Config discovery (find-up + a thin self-written wrapper).
|
|
3
|
+
*
|
|
4
|
+
* Nearest-wins is the semantics: a nested config file is
|
|
5
|
+
* a governance boundary — the subtree below it has its own geometry, and the
|
|
6
|
+
* closest residence above any starting directory is THE residence. That
|
|
7
|
+
* semantics never spills into the exclusion axis: discovery only locates,
|
|
8
|
+
* never interprets. Parsing stays consumer-side (core takes resolved
|
|
9
|
+
* options; toml/yaml do not enter pathscope).
|
|
10
|
+
*
|
|
11
|
+
* find-up v8 semantics, verified against its source: the upward walk checks
|
|
12
|
+
* each directory shallow→deep, testing every declared name per directory, so
|
|
13
|
+
* the NEAREST directory wins and only within one directory does declaration
|
|
14
|
+
* order break ties; `stopAt` is inclusive (the stop directory itself is the
|
|
15
|
+
* last one examined). Both match this module's contract, which is why the
|
|
16
|
+
* wrapper delegates instead of hand-rolling the walk.
|
|
17
|
+
*/
|
|
18
|
+
import { basename } from 'node:path';
|
|
19
|
+
import { findUpSync } from 'find-up';
|
|
20
|
+
import { toPosix } from './paths.js';
|
|
21
|
+
import { PathscopeConfigError } from './types.js';
|
|
22
|
+
/** Validate declared residence names: non-empty, relative, no `..` climbs —
|
|
23
|
+
* the same fail-loud shape the boundary-stone config homes use. */
|
|
24
|
+
function validateNames(names) {
|
|
25
|
+
if (!Array.isArray(names) || names.length === 0) {
|
|
26
|
+
throw new PathscopeConfigError('locateNearest needs a non-empty set of residence names');
|
|
27
|
+
}
|
|
28
|
+
for (const name of names) {
|
|
29
|
+
if (typeof name !== 'string' || name.trim() === '' || name.startsWith('/')) {
|
|
30
|
+
throw new PathscopeConfigError(`residence name "${String(name)}" must be a non-empty relative name (e.g. ".specs/collect.config.toml")`);
|
|
31
|
+
}
|
|
32
|
+
if (name.split('/').includes('..')) {
|
|
33
|
+
throw new PathscopeConfigError(`residence name "${name}" must not climb with ".."`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Locate the nearest config residence at or above `options.cwd` (default
|
|
39
|
+
* `process.cwd()`): the first directory on the way up that directly contains
|
|
40
|
+
* one of `names` wins; within one directory, earlier-declared names win.
|
|
41
|
+
* The walk stops after examining `options.stopAt` (inclusive) — beyond that
|
|
42
|
+
* boundary a residence belongs to a different governance domain. Returns
|
|
43
|
+
* `{name, path}` or `null` when no residence exists in bounds. No file is
|
|
44
|
+
* ever read or parsed.
|
|
45
|
+
*/
|
|
46
|
+
export function locateNearest(names, options = {}) {
|
|
47
|
+
validateNames(names);
|
|
48
|
+
const found = findUpSync(names, { cwd: options.cwd, stopAt: options.stopAt });
|
|
49
|
+
if (found === undefined)
|
|
50
|
+
return null;
|
|
51
|
+
// Recover WHICH declared name hit: the found path ends with the name
|
|
52
|
+
// segment-for-segment (multi-segment names stay whole; win32 resolve
|
|
53
|
+
// rewrites separators, so compare in POSIX form, case-insensitively there).
|
|
54
|
+
const foundPosix = toPosix(found);
|
|
55
|
+
const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
|
|
56
|
+
const suffixOf = (name) => `/${name}`;
|
|
57
|
+
const hit = names.find((name) => foundPosix.length >= suffixOf(name).length &&
|
|
58
|
+
fold(foundPosix.slice(foundPosix.length - suffixOf(name).length)) === fold(suffixOf(name)));
|
|
59
|
+
if (hit === undefined) {
|
|
60
|
+
// Unreachable in practice; basename keeps the contract non-lying if a
|
|
61
|
+
// future find-up changes its return shape.
|
|
62
|
+
return { name: basename(found), path: found };
|
|
63
|
+
}
|
|
64
|
+
return { name: hit, path: found };
|
|
65
|
+
}
|
|
66
|
+
//# sourceMappingURL=discover.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAmD,MAAM,YAAY,CAAC;AAEnG;mEACmE;AACnE,SAAS,aAAa,CAAC,KAAe;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,oBAAoB,CAAC,wDAAwD,CAAC,CAAC;IAC3F,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,oBAAoB,CAC5B,mBAAmB,MAAM,CAAC,IAAI,CAAC,yEAAyE,CACzG,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,oBAAoB,CAAC,mBAAmB,IAAI,4BAA4B,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,OAAO,GAAyB,EAAE;IAC/E,aAAa,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9E,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,qEAAqE;IACrE,qEAAqE;IACrE,4EAA4E;IAC5E,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9F,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;IACtD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CACpB,CAAC,IAAI,EAAE,EAAE,CACP,UAAU,CAAC,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM;QAC1C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAC7F,CAAC;IACF,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,sEAAsE;QACtE,2CAA2C;QAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC"}
|
package/dist/engine.d.ts
ADDED
|
@@ -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>;
|
package/dist/engine.js
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* walkScope — the walk-mode engine.
|
|
3
|
+
*
|
|
4
|
+
* Chassis: fdir (exclude predicate = per-directory adjudication with
|
|
5
|
+
* whole-tree pruning; AbortSignal = budget interrupt; symlinks unresolved by
|
|
6
|
+
* default). Decision core: createExclusionEngine (exclusion-engine.ts) —
|
|
7
|
+
* the exclusion stack + gitignore cascade as a composable module; walkScope
|
|
8
|
+
* wires it to the chassis and owns the loud budget, the only piece of the
|
|
9
|
+
* stack that is chassis-concern (orthogonal).
|
|
10
|
+
*
|
|
11
|
+
* Full-stack priority (implemented verbatim in
|
|
12
|
+
* the decision core):
|
|
13
|
+
* 0. boundary stones — structural terminal, before override and every
|
|
14
|
+
* exclusion judgment
|
|
15
|
+
* 1. strict channel — immune exclusion, outbound artifact boundaries only;
|
|
16
|
+
* even the override whitelist cannot rescue it
|
|
17
|
+
* 2. override — terminal include, rescues everything else; naming a
|
|
18
|
+
* directory itself restores descent
|
|
19
|
+
* 3. combined table — git last-match-wins: presets (front) → gitignore
|
|
20
|
+
* cascade (shallow→deep) → policy layer (rear seat,
|
|
21
|
+
* evaluated last); directory excluded with no
|
|
22
|
+
* directory-level rescue → whole-tree pruning, the
|
|
23
|
+
* only structural non-revivable
|
|
24
|
+
* 4. dot category — walk-layer option (default on), whitelist can rescue
|
|
25
|
+
* 5. budget — orthogonal and LOUD: a cut always emits a diagnostic
|
|
26
|
+
*/
|
|
27
|
+
import { existsSync } from 'node:fs';
|
|
28
|
+
import { join, resolve } from 'node:path';
|
|
29
|
+
import { fdir } from 'fdir';
|
|
30
|
+
import { readGitignoreText } from './cascade.js';
|
|
31
|
+
import { createExclusionEngine, validateOptions } from './exclusion-engine.js';
|
|
32
|
+
import { PathscopeConfigError } from './types.js';
|
|
33
|
+
/** Loud default budget. */
|
|
34
|
+
const DEFAULT_MAX_FILES = 2000;
|
|
35
|
+
/**
|
|
36
|
+
* Walk `root` and produce the in-scope file set: POSIX relative paths, sorted,
|
|
37
|
+
* plus loud diagnostics. See {@link ScopeOptions} for the exclusion stack.
|
|
38
|
+
*/
|
|
39
|
+
export async function walkScope(root, options = {}) {
|
|
40
|
+
validateOptions(options);
|
|
41
|
+
const rootNative = resolve(root);
|
|
42
|
+
if (!existsSync(rootNative)) {
|
|
43
|
+
throw new PathscopeConfigError(`scan root does not exist: ${rootNative}`);
|
|
44
|
+
}
|
|
45
|
+
// Canonical walk key — fdir is configured with pathSeparator '/', so every
|
|
46
|
+
// directory path the exclude predicate sees is POSIX-separator absolute.
|
|
47
|
+
const scanKey = rootNative.replace(/\\/g, '/');
|
|
48
|
+
// Decision core (inherited phase + full exclusion stack). The chassis-side
|
|
49
|
+
// glue below drives it exactly as the core's contract prescribes: probe the
|
|
50
|
+
// stones first, adjudicate, and only fold a descended directory's rules.
|
|
51
|
+
const engine = await createExclusionEngine(scanKey, options);
|
|
52
|
+
// Per-stone hit report (not a bare boolean): the boundaryStones.exempt key
|
|
53
|
+
// adjudicates on which stones hit — the named subtree's own hits of the
|
|
54
|
+
// exemptible kinds (core `.git`, and `.gitignore` when the proxy stone is
|
|
55
|
+
// mounted) are neutralized; config homes are never exemptible.
|
|
56
|
+
const stoneHits = (key) => {
|
|
57
|
+
const hits = [];
|
|
58
|
+
for (const name of engine.stoneNames) {
|
|
59
|
+
if (existsSync(join(key, ...name.split('/'))))
|
|
60
|
+
hits.push(name);
|
|
61
|
+
}
|
|
62
|
+
return hits;
|
|
63
|
+
};
|
|
64
|
+
const diagnostics = [];
|
|
65
|
+
const controller = new AbortController();
|
|
66
|
+
const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
|
|
67
|
+
let included = 0;
|
|
68
|
+
let budgetCut = false;
|
|
69
|
+
/** Per-directory adjudication — fdir prunes the whole subtree when this returns true. */
|
|
70
|
+
const excludeDirectory = (dirName, dirPath) => {
|
|
71
|
+
const key = dirPath.replace(/\/+$/, '');
|
|
72
|
+
if (engine.excludeDirectory(dirName, key, stoneHits(key)))
|
|
73
|
+
return true;
|
|
74
|
+
// Descending: fold this layer's .gitignore in after the parent's rules
|
|
75
|
+
// (shallow first, deep later; the subtree is pruned above
|
|
76
|
+
// before this point when the layer is excluded, so its `!` never applies).
|
|
77
|
+
engine.foldGitignore(key, readGitignoreText(key));
|
|
78
|
+
return false;
|
|
79
|
+
};
|
|
80
|
+
/** Per-file adjudication, then the loud budget gate. */
|
|
81
|
+
const keepFile = (rel) => {
|
|
82
|
+
if (budgetCut)
|
|
83
|
+
return false;
|
|
84
|
+
if (!engine.admitFile(rel))
|
|
85
|
+
return false;
|
|
86
|
+
if (included >= maxFiles) {
|
|
87
|
+
budgetCut = true;
|
|
88
|
+
controller.abort();
|
|
89
|
+
diagnostics.push({
|
|
90
|
+
code: 'budget-exceeded',
|
|
91
|
+
limit: maxFiles,
|
|
92
|
+
message: `file budget of ${maxFiles} reached — traversal was cut here (never a silent cut)`,
|
|
93
|
+
});
|
|
94
|
+
return false;
|
|
95
|
+
}
|
|
96
|
+
included += 1;
|
|
97
|
+
return true;
|
|
98
|
+
};
|
|
99
|
+
const files = await new fdir({
|
|
100
|
+
pathSeparator: '/',
|
|
101
|
+
exclude: excludeDirectory,
|
|
102
|
+
signal: controller.signal,
|
|
103
|
+
resolveSymlinks: options.followSymlinks === true,
|
|
104
|
+
// Keep descended-through-symlink paths in the scan-root universe instead
|
|
105
|
+
// of emitting real (possibly outside-root) paths.
|
|
106
|
+
useRealPaths: false,
|
|
107
|
+
// Unreadable directories are skipped, ripgrep-style; the loud channel is
|
|
108
|
+
// the budget, not per-directory I/O errors.
|
|
109
|
+
suppressErrors: true,
|
|
110
|
+
})
|
|
111
|
+
.withRelativePaths()
|
|
112
|
+
.filter((path) => keepFile(path))
|
|
113
|
+
.crawl(rootNative)
|
|
114
|
+
.withPromise();
|
|
115
|
+
return { files: [...files].sort(), diagnostics };
|
|
116
|
+
}
|
|
117
|
+
//# sourceMappingURL=engine.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
|
|
@@ -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>;
|