@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
package/dist/types.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
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
|
+
/** Thrown for malformed engine configuration (a strict rule without a reason, an unknown preset, ...). */
|
|
10
|
+
export class PathscopeConfigError extends Error {
|
|
11
|
+
constructor(message) {
|
|
12
|
+
super(`[pathscope] ${message}`);
|
|
13
|
+
this.name = 'PathscopeConfigError';
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Thrown when the git universe cannot be asked: the git binary is missing,
|
|
18
|
+
* the root is not inside a repository, or a git command failed. The message
|
|
19
|
+
* always names the command that failed (fail loud, never scan
|
|
20
|
+
* the filesystem as a silent fallback).
|
|
21
|
+
*/
|
|
22
|
+
export class PathscopeGitError extends Error {
|
|
23
|
+
constructor(message) {
|
|
24
|
+
super(`[pathscope] ${message}`);
|
|
25
|
+
this.name = 'PathscopeGitError';
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
//# sourceMappingURL=types.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8JH,0GAA0G;AAC1G,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}
|
|
@@ -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>;
|
package/dist/universe.js
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* gitUniverse — the ask-git mode (self-written spawn).
|
|
3
|
+
*
|
|
4
|
+
* No filesystem traversal: the universe is whatever git says it is.
|
|
5
|
+
* `--exclude-standard` lets git itself consume the whole ignore chain
|
|
6
|
+
* (gitignore / info/exclude / core.excludesFile); tracked content stays in
|
|
7
|
+
* by design — the walk-mode exclusion stack does NOT participate here
|
|
8
|
+
* ("git as truth": a tracked node_modules belongs in the universe). Consumers
|
|
9
|
+
* who want it out mount the opt-in post-filter, which reuses the preset
|
|
10
|
+
* groups and the node-ignore kernel with policy-layer semantics but none of
|
|
11
|
+
* the full walk stack (no stones, no strict channel, no dot category, no
|
|
12
|
+
* budget).
|
|
13
|
+
*
|
|
14
|
+
* Spawn discipline: `node:child_process` directly (execa/tinyexec stay out);
|
|
15
|
+
* every failure mode — git missing, root outside any repository, a non-zero
|
|
16
|
+
* git exit — throws {@link PathscopeGitError} naming the failed command.
|
|
17
|
+
*
|
|
18
|
+
* Mode filtering (lint-staged is the isomorphic reference):
|
|
19
|
+
* gitlink submodules (mode 160000) and symlinks (mode 120000) are not files
|
|
20
|
+
* and never enter the universe. `ls-files --stage` carries the mode; records
|
|
21
|
+
* from `--others` (untracked) carry none and are regular files by
|
|
22
|
+
* construction — an untracked symlink only gains mode 120000 when git
|
|
23
|
+
* starts tracking it.
|
|
24
|
+
*
|
|
25
|
+
* Path pipeline: both `ls-files --full-name` and `diff --cached --raw`
|
|
26
|
+
* emit repo-root-relative paths, so every path is rebased onto the PASSED
|
|
27
|
+
* root with one conversion. Note the asymmetry git itself has: `ls-files`
|
|
28
|
+
* run from a subdirectory is limited to that subtree, while
|
|
29
|
+
* `diff --cached --raw` reports the whole repository — the rebase drops
|
|
30
|
+
* entries outside the root so all three variants agree on "the universe of
|
|
31
|
+
* this root".
|
|
32
|
+
*/
|
|
33
|
+
import { spawnSync } from 'node:child_process';
|
|
34
|
+
import { isAbsolute, join, relative, resolve } from 'node:path';
|
|
35
|
+
import ignore from 'ignore';
|
|
36
|
+
import { compilePresetPatterns, isPresetName } from './presets.js';
|
|
37
|
+
import { toPosix } from './paths.js';
|
|
38
|
+
import { PathscopeConfigError, PathscopeGitError, } from './types.js';
|
|
39
|
+
/** Repository-root cache, keyed by resolved root (case-folded on win32 so
|
|
40
|
+
* drive-letter case cannot split an entry). Tests that create and destroy
|
|
41
|
+
* repositories reset it via {@link clearUniverseCache}. */
|
|
42
|
+
const repoRootCache = new Map();
|
|
43
|
+
/** Empty the repository-root memoization (test seam; production callers never need it). */
|
|
44
|
+
export function clearUniverseCache() {
|
|
45
|
+
repoRootCache.clear();
|
|
46
|
+
}
|
|
47
|
+
/** Run git in cwd; any failure is loud and names the command. */
|
|
48
|
+
function runGit(cwd, args) {
|
|
49
|
+
const run = spawnSync('git', args, { cwd, encoding: 'utf8' });
|
|
50
|
+
if (run.error) {
|
|
51
|
+
const code = run.error.code;
|
|
52
|
+
if (code === 'ENOENT') {
|
|
53
|
+
throw new PathscopeGitError('git binary not found on PATH — the universe is "ask git" and cannot be computed without it');
|
|
54
|
+
}
|
|
55
|
+
throw new PathscopeGitError(`git ${args.join(' ')} could not be spawned: ${String(run.error)}`);
|
|
56
|
+
}
|
|
57
|
+
if (run.status !== 0) {
|
|
58
|
+
const stderr = String(run.stderr).trim();
|
|
59
|
+
if (/not a git repository/i.test(stderr)) {
|
|
60
|
+
throw new PathscopeGitError(`root is not inside a git repository: ${cwd} (git ${args.join(' ')} failed: ${stderr})`);
|
|
61
|
+
}
|
|
62
|
+
throw new PathscopeGitError(`git ${args.join(' ')} failed (exit ${String(run.status)}): ${stderr}`);
|
|
63
|
+
}
|
|
64
|
+
return run.stdout;
|
|
65
|
+
}
|
|
66
|
+
/** Repository root for a resolved root, memoized. Only successes are cached. */
|
|
67
|
+
function repoRootOf(rootAbs) {
|
|
68
|
+
const key = process.platform === 'win32' ? rootAbs.toLowerCase() : rootAbs;
|
|
69
|
+
const hit = repoRootCache.get(key);
|
|
70
|
+
if (hit !== undefined)
|
|
71
|
+
return hit;
|
|
72
|
+
const top = runGit(rootAbs, ['rev-parse', '--show-toplevel']).split('\n')[0]?.trim() ?? '';
|
|
73
|
+
if (top === '') {
|
|
74
|
+
throw new PathscopeGitError(`git rev-parse --show-toplevel returned no repository root for ${rootAbs}`);
|
|
75
|
+
}
|
|
76
|
+
repoRootCache.set(key, top);
|
|
77
|
+
return top;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Parse `ls-files -z --stage` records into paths, dropping gitlink submodules
|
|
81
|
+
* (160000) and symlinks (120000). Records from `--others` carry no stage
|
|
82
|
+
* prefix (no tab) and are kept as-is. Conflicted paths appear once per stage;
|
|
83
|
+
* the Set deduplicates. Input paths are repo-root-relative.
|
|
84
|
+
*/
|
|
85
|
+
export function filterLsFilesStageRecords(stdout) {
|
|
86
|
+
const kept = new Set();
|
|
87
|
+
for (const record of stdout.split('\0')) {
|
|
88
|
+
if (record === '')
|
|
89
|
+
continue;
|
|
90
|
+
const tab = record.indexOf('\t');
|
|
91
|
+
if (tab === -1) {
|
|
92
|
+
kept.add(record); // untracked (--others): regular file, no mode line
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
const mode = record.slice(0, tab).split(' ')[0];
|
|
96
|
+
if (mode === '160000' || mode === '120000')
|
|
97
|
+
continue; // gitlink / symlink
|
|
98
|
+
kept.add(record.slice(tab + 1));
|
|
99
|
+
}
|
|
100
|
+
return [...kept];
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Parse `diff --cached -z --raw` records, dropping entries whose destination
|
|
104
|
+
* mode is a gitlink (160000) or symlink (120000). `--no-renames` is always
|
|
105
|
+
* passed by the caller, so every record is header + exactly one path; the
|
|
106
|
+
* defensive R/C branch keeps the parser honest if that ever changes.
|
|
107
|
+
*/
|
|
108
|
+
export function filterDiffRawRecords(stdout) {
|
|
109
|
+
const kept = new Set();
|
|
110
|
+
const tokens = stdout.split('\0');
|
|
111
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
112
|
+
const token = tokens[i];
|
|
113
|
+
if (token === '' || !token.startsWith(':'))
|
|
114
|
+
continue;
|
|
115
|
+
const [, dstMode, , , status] = token.split(' ');
|
|
116
|
+
const path = tokens[i + 1] ?? '';
|
|
117
|
+
// Rename/copy records carry a second path (source); the destination —
|
|
118
|
+
// the only side this diff-filtered universe cares about — is the second.
|
|
119
|
+
const destination = status === 'R' || status === 'C' ? (tokens[i + 2] ?? '') : path;
|
|
120
|
+
if (dstMode !== '160000' && dstMode !== '120000')
|
|
121
|
+
kept.add(destination);
|
|
122
|
+
i += status === 'R' || status === 'C' ? 2 : 1;
|
|
123
|
+
}
|
|
124
|
+
return [...kept];
|
|
125
|
+
}
|
|
126
|
+
/** Rebase a repo-root-relative git path onto the passed root; null when it
|
|
127
|
+
* lands outside the root (the diff variant reports the whole repository). */
|
|
128
|
+
function rebaseToRoot(repoRootNative, rootAbs, repoRelPosix) {
|
|
129
|
+
const rel = relative(rootAbs, join(repoRootNative, repoRelPosix));
|
|
130
|
+
if (rel === '' || isAbsolute(rel) || rel.startsWith('..'))
|
|
131
|
+
return null;
|
|
132
|
+
return toPosix(rel);
|
|
133
|
+
}
|
|
134
|
+
/** Validate the filter table; same fail-loud rules as the walk option face. */
|
|
135
|
+
function validateFilter(filter) {
|
|
136
|
+
for (const name of filter.mountPresets ?? []) {
|
|
137
|
+
if (!isPresetName(name)) {
|
|
138
|
+
throw new PathscopeConfigError(`unknown preset "${String(name)}" in universe filter — the five groups are vcs | deps | build | caches | agentDocs`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
for (const entry of filter.exclude ?? []) {
|
|
142
|
+
if (typeof entry !== 'string' || entry.trim() === '') {
|
|
143
|
+
throw new PathscopeConfigError('filter.exclude entries must be non-empty gitignore-style pattern strings');
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* Adjudicate one POSIX-relative file against the combined filter table,
|
|
149
|
+
* replaying the walk's per-level semantics over a flat list: each ancestor
|
|
150
|
+
* directory (with its trailing slash) and finally the file itself are tested
|
|
151
|
+
* in order; a level the combined table excludes cuts the whole subtree
|
|
152
|
+
* (structural — a deeper file-level `!` cannot revive out of an excluded
|
|
153
|
+
* directory, git's own rule), while a dir-level `!` rescue (e.g.
|
|
154
|
+
* `!node_modules/`) restores the subtree, exactly as git's last-match-wins
|
|
155
|
+
* answers it.
|
|
156
|
+
*/
|
|
157
|
+
function survivesFilter(file, table) {
|
|
158
|
+
const parts = file.split('/');
|
|
159
|
+
for (let i = 1; i <= parts.length; i++) {
|
|
160
|
+
const isDir = i < parts.length;
|
|
161
|
+
const probe = parts.slice(0, i).join('/') + (isDir ? '/' : '');
|
|
162
|
+
if (table.test(probe).ignored)
|
|
163
|
+
return false; // subtree out
|
|
164
|
+
}
|
|
165
|
+
return true;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Ask git for the file universe of `root`. Variants:
|
|
169
|
+
* `'all'` (default) tracked + untracked-but-not-ignored; `'tree'` the index
|
|
170
|
+
* contents only; `'staged'` the A/C/M/R changes staged vs HEAD (publish
|
|
171
|
+
* semantics). The exclusion stack does not participate — mount
|
|
172
|
+
* `options.filter` to post-filter with preset + policy patterns. Throws
|
|
173
|
+
* {@link PathscopeGitError} when git is missing or the root is outside any
|
|
174
|
+
* repository, and {@link PathscopeConfigError} for a malformed filter.
|
|
175
|
+
*/
|
|
176
|
+
export async function gitUniverse(root, options = {}) {
|
|
177
|
+
const variant = options.variant ?? 'all';
|
|
178
|
+
if (variant !== 'all' && variant !== 'tree' && variant !== 'staged') {
|
|
179
|
+
throw new PathscopeConfigError(`unknown variant "${String(variant)}" — the universe is all | tree | staged`);
|
|
180
|
+
}
|
|
181
|
+
if (options.filter !== undefined)
|
|
182
|
+
validateFilter(options.filter);
|
|
183
|
+
const rootAbs = resolve(root);
|
|
184
|
+
const repoRoot = repoRootOf(rootAbs);
|
|
185
|
+
let repoRelative;
|
|
186
|
+
if (variant === 'staged') {
|
|
187
|
+
// Publish semantics: only Added/Copied/Modified/Renamed staged
|
|
188
|
+
// entries; deletions cannot be published. --no-renames pins the raw
|
|
189
|
+
// record shape (one path per record; a rename shows as A on the new side).
|
|
190
|
+
repoRelative = filterDiffRawRecords(runGit(rootAbs, ['diff', '--cached', '-z', '--raw', '--no-renames', '--diff-filter=ACMR']));
|
|
191
|
+
}
|
|
192
|
+
else {
|
|
193
|
+
// --stage carries the mode line for filtering; --others adds the
|
|
194
|
+
// untracked (bare records); --exclude-standard is the whole point —
|
|
195
|
+
// git eats its own ignore chain, pathscope does not re-implement it.
|
|
196
|
+
const args = ['ls-files', '-z', '--full-name', '--stage'];
|
|
197
|
+
if (variant === 'all')
|
|
198
|
+
args.push('--cached', '--others', '--exclude-standard');
|
|
199
|
+
repoRelative = filterLsFilesStageRecords(runGit(rootAbs, args));
|
|
200
|
+
}
|
|
201
|
+
let files = repoRelative
|
|
202
|
+
.map((p) => rebaseToRoot(repoRoot, rootAbs, p))
|
|
203
|
+
.filter((p) => p !== null)
|
|
204
|
+
.sort();
|
|
205
|
+
if (options.filter !== undefined) {
|
|
206
|
+
// One combined table, git last-match-wins: preset patterns at the front,
|
|
207
|
+
// consumer patterns at the rear (they may override presets and negate).
|
|
208
|
+
const table = ignore();
|
|
209
|
+
const patterns = [
|
|
210
|
+
...compilePresetPatterns(options.filter.mountPresets ?? []),
|
|
211
|
+
...(options.filter.exclude ?? []),
|
|
212
|
+
];
|
|
213
|
+
if (patterns.length > 0)
|
|
214
|
+
table.add(patterns);
|
|
215
|
+
files = files.filter((file) => survivesFilter(file, table));
|
|
216
|
+
}
|
|
217
|
+
return { files, repoRoot, diagnostics: [] };
|
|
218
|
+
}
|
|
219
|
+
//# sourceMappingURL=universe.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"universe.js","sourceRoot":"","sources":["../src/universe.ts"],"names":[],"mappings":"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"}
|
package/docs/glossary.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Consumer glossary of the pathscope vocabulary — the two resolution modes, the exclusion stack layers, boundary markers, alignment and the fail-loud reliability nouns
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Glossary
|
|
6
|
+
|
|
7
|
+
The vocabulary pathscope uses, in one place. Terms are sorted from the top down: read the first six and every README example parses; the rest matter when you tune the stack.
|
|
8
|
+
|
|
9
|
+
## The core nouns
|
|
10
|
+
|
|
11
|
+
**Path scope** — the set of files a tool should see for a given root and a given set of rules. This is the package's one output shape: an array of POSIX-style paths relative to the scan root, sorted.
|
|
12
|
+
|
|
13
|
+
**Scan root** — the directory a scope request starts from. All output paths are relative to it, not to the repository root (which may be higher).
|
|
14
|
+
|
|
15
|
+
**Walk mode** — resolving the path scope by traversing the filesystem, with the exclusion stack and gitignore cascade applied on the way down. Rides `walkScope`.
|
|
16
|
+
|
|
17
|
+
**Ask-git mode** — resolving the path scope by asking git instead of walking (`git ls-files` under the hood). Git is the truth: the exclusion stack does not participate by default. Rides `gitUniverse`. Mutually exclusive with walk mode — one scope request goes through one of the two, never a blend.
|
|
18
|
+
|
|
19
|
+
**Composable exclusion engine** — the exclusion stack + gitignore cascade as a standalone engine (`createExclusionEngine`). For consumers that own their own traversal — watchers, incremental snapshots, virtual filesystems — and cannot use the built-in walker.
|
|
20
|
+
|
|
21
|
+
**Nearest config file** — a configuration file located on the way up from a starting directory; the nearest one wins (`locateNearest`). pathscope only locates it, never reads or parses it.
|
|
22
|
+
|
|
23
|
+
## The exclusion stack
|
|
24
|
+
|
|
25
|
+
**Default ignore preset** — a named group of default exclusions (VCS internals, dependencies, build outputs, caches, agent docs). Mounting is append-only and presets sit at the FRONT of the rule table: any named negation (`!vendor/`) in a gitignore layer or in your `exclude` option can walk an entry back out. There is no wholesale-replacement channel.
|
|
26
|
+
|
|
27
|
+
**Your own ignore rules (the policy layer)** — the `exclude` patterns you pass, appended at the END of the rule table. They may override presets and gitignore rules, and may negate.
|
|
28
|
+
|
|
29
|
+
**Override whitelist** — final say: an include that outranks everything except the strict channel. Naming a directory (`cache/`) itself restores descent into it.
|
|
30
|
+
|
|
31
|
+
**Strict rule** — an exclusion that not even the override whitelist can rescind. Every entry must carry a written `reason`; a reason-less entry is rejected as a configuration error. This is the outbound-artifact-boundary channel (npm-packlist / cargo precedent) — index and retrieval consumers should not use it.
|
|
32
|
+
|
|
33
|
+
**Last-match-wins** — git's own rule for conflicting gitignore patterns: within the combined rule table, the last matching pattern decides. The cascade appends shallower `.gitignore` files before deeper ones, so deeper rules win within their subtree.
|
|
34
|
+
|
|
35
|
+
**Whole-tree pruning** — when a directory is excluded with no rescue, its entire subtree disappears from the scope, and its own `.gitignore` is never applied — its `!` rules cannot leak onto the rest of the walk.
|
|
36
|
+
|
|
37
|
+
## Boundary markers
|
|
38
|
+
|
|
39
|
+
The API names this option `boundaryStones`; markers is the plain word for what they are.
|
|
40
|
+
|
|
41
|
+
**Boundary marker** — an existence signal in a directory that truncates the whole subtree. Content is never interpreted; only presence matters.
|
|
42
|
+
|
|
43
|
+
**Core marker (`.git`)** — always on. An unregistered nested repository — an *embedded repository*, in git's own terminology — truncates the walk, exactly as git never descends into one.
|
|
44
|
+
|
|
45
|
+
**Config-home marker** — a marker name you declare (may be nested, e.g. `.toolkit/collect.config.toml`); a directory directly containing one marks a separate sub-project and truncates. Never exemptible — you declared it yourself.
|
|
46
|
+
|
|
47
|
+
**`.gitignore` boundary marker** — the opt-in variant (`gitignoreProxy`) that treats a nested `.gitignore` as a boundary signal instead of more rules. Off by default: mainstream treats a nested `.gitignore` as rules, not territory.
|
|
48
|
+
|
|
49
|
+
**Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
|
|
50
|
+
|
|
51
|
+
## Alignment
|
|
52
|
+
|
|
53
|
+
**Alignment** — which family's nested-repository semantics the core marker follows. `'git'` (default): an embedded repository truncates whole. `'scanner'` (ripgrep-style): nested repositories never truncate, at any depth, and a nested `.gitignore` is rules — the marker hit is still reported, as metadata ("this subtree is a nested repository"), but the cut never executes.
|
|
54
|
+
|
|
55
|
+
## Reliability nouns
|
|
56
|
+
|
|
57
|
+
**Loud budget** — a file-count limit on walk mode (default 2000). When a scan would exceed it, traversal is cut and a `budget-exceeded` diagnostic is emitted. Never a silent cut.
|
|
58
|
+
|
|
59
|
+
**Fail-loud** — the error policy: malformed configuration throws `PathscopeConfigError`; git absence or failure throws `PathscopeGitError` naming the command. Nothing is silently re-scanned "some other way", and a failed git query never falls back to a filesystem walk.
|