@catheadowl/pathscope 0.2.0 → 0.4.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 +124 -0
- package/README.md +18 -3
- package/dist/cascade.d.ts +4 -0
- package/dist/cascade.js +7 -3
- package/dist/cascade.js.map +1 -1
- package/dist/cjs/cascade.d.ts +4 -0
- package/dist/cjs/engine.d.ts +4 -0
- package/dist/cjs/exclusion-engine.d.ts +67 -10
- package/dist/cjs/index.js +2128 -88
- package/dist/cjs/presets.d.ts +11 -3
- package/dist/cjs/types.d.ts +99 -8
- package/dist/cjs/walk-hidden.d.ts +41 -0
- package/dist/cjs/walk-links.d.ts +63 -0
- package/dist/cjs/win-attr.d.ts +27 -0
- package/dist/engine.d.ts +4 -0
- package/dist/engine.js +91 -7
- package/dist/engine.js.map +1 -1
- package/dist/exclusion-engine.d.ts +67 -10
- package/dist/exclusion-engine.js +156 -71
- package/dist/exclusion-engine.js.map +1 -1
- package/dist/explain.js +18 -3
- package/dist/explain.js.map +1 -1
- package/dist/presets.d.ts +11 -3
- package/dist/presets.js +17 -7
- package/dist/presets.js.map +1 -1
- package/dist/types.d.ts +99 -8
- package/dist/types.js.map +1 -1
- package/dist/walk-hidden.d.ts +41 -0
- package/dist/walk-hidden.js +96 -0
- package/dist/walk-hidden.js.map +1 -0
- package/dist/walk-links.d.ts +63 -0
- package/dist/walk-links.js +124 -0
- package/dist/walk-links.js.map +1 -0
- package/dist/win-attr.d.ts +27 -0
- package/dist/win-attr.js +81 -0
- package/dist/win-attr.js.map +1 -0
- package/docs/glossary.md +4 -0
- package/docs/semantics.md +25 -5
- package/package.json +4 -1
- package/prebuilds/win32-x64/pathscope_win_attr.node +0 -0
package/dist/types.d.ts
CHANGED
|
@@ -118,19 +118,37 @@ export interface ScopeOptions {
|
|
|
118
118
|
/** Opt-in boundary stones — see {@link BoundaryStonesOptions}. */
|
|
119
119
|
boundaryStones?: BoundaryStonesOptions;
|
|
120
120
|
/**
|
|
121
|
-
* Exclude
|
|
122
|
-
*
|
|
123
|
-
*
|
|
121
|
+
* Exclude hidden entries — rg `hidden` semantics, platform-twin-faced
|
|
122
|
+
* (2026-11-20 owner ruling): the dot-name face every platform has, plus
|
|
123
|
+
* on Windows the FILE_ATTRIBUTE_HIDDEN face (AppData-class attribute-
|
|
124
|
+
* hidden, dot-less trees). A walk-layer option, not a gitignore rule.
|
|
125
|
+
* Default `true`. The override whitelist can rescue hidden entries on
|
|
126
|
+
* either face — exclusion is not access control. On win32 with the native
|
|
127
|
+
* attribute piece unavailable the attribute face goes inert and the scan
|
|
128
|
+
* reports it loudly (`windows-hidden-attributes-unavailable`); on unix
|
|
129
|
+
* the attribute face does not exist by design (ignore-crate precedent:
|
|
130
|
+
* unix hidden = dot-name only) and no diagnostic fires.
|
|
124
131
|
*/
|
|
125
132
|
excludeDotEntries?: boolean;
|
|
126
133
|
/**
|
|
127
134
|
* Respect `.gitignore` rules (inherited phase + walk-time folding). Default
|
|
128
|
-
* `true`. `false` is the layered escape hatch (rg `--no-ignore`
|
|
129
|
-
* only the
|
|
130
|
-
*
|
|
131
|
-
* boundary stones adjudicate exactly as before.
|
|
135
|
+
* `true`. `false` is the layered escape hatch (rg `--no-ignore-vcs`
|
|
136
|
+
* granularity): only the vcs ignore sources are skipped — the `.ignore`
|
|
137
|
+
* family keeps its own switch, and mounted presets, the policy layer, the
|
|
138
|
+
* override whitelist, and boundary stones adjudicate exactly as before.
|
|
139
|
+
* Turning BOTH this and {@link ScopeOptions.respectIgnoreFamily} off is the
|
|
140
|
+
* file-face equivalent of rg `--no-ignore`.
|
|
132
141
|
*/
|
|
133
142
|
respectGitignore?: boolean;
|
|
143
|
+
/**
|
|
144
|
+
* Respect the `.ignore` / `.rgignore` family (rg's non-vcs ignore files,
|
|
145
|
+
* same gitignore(5) syntax, read on the walk root itself and in every
|
|
146
|
+
* descended directory — never above the root: the family has no inherited
|
|
147
|
+
* phase, unlike `.gitignore`). Default `true`. `false` skips only these two
|
|
148
|
+
* sources; `.gitignore` keeps its own switch. Face-orthogonal: the family
|
|
149
|
+
* is read under every `alignment` face, exactly like `.gitignore`.
|
|
150
|
+
*/
|
|
151
|
+
respectIgnoreFamily?: boolean;
|
|
134
152
|
/**
|
|
135
153
|
* Loud file budget: when the scan would include more than this many files,
|
|
136
154
|
* traversal is cut and a diagnostic is emitted — never a silent cut.
|
|
@@ -140,20 +158,93 @@ export interface ScopeOptions {
|
|
|
140
158
|
/** Follow symlinks during traversal. Default `false` (git/ripgrep default). */
|
|
141
159
|
followSymlinks?: boolean;
|
|
142
160
|
}
|
|
143
|
-
/**
|
|
161
|
+
/**
|
|
162
|
+
* A loud diagnostic emitted by a scan. The budget cut is the canonical
|
|
163
|
+
* case; the degradation notice is the Windows hidden-attribute face saying
|
|
164
|
+
* it went inert instead of silently changing what the walk returns.
|
|
165
|
+
*/
|
|
144
166
|
export type ScanDiagnostic = {
|
|
145
167
|
code: 'budget-exceeded';
|
|
146
168
|
/** Human-readable statement of the cut. */
|
|
147
169
|
message: string;
|
|
148
170
|
/** The budget limit that was hit. */
|
|
149
171
|
limit: number;
|
|
172
|
+
} | {
|
|
173
|
+
/** The win32 native attribute piece failed to load: the dot category's attribute face is inert this run. */
|
|
174
|
+
code: 'windows-hidden-attributes-unavailable';
|
|
175
|
+
/** Human-readable statement of the degradation — never a silent cut. */
|
|
176
|
+
message: string;
|
|
150
177
|
};
|
|
178
|
+
/**
|
|
179
|
+
* One boundary-stone hit discovered during a walk — the walk face's share of
|
|
180
|
+
* the report-not-cut principle: which subtrees carry an existence signal
|
|
181
|
+
* (an embedded repository, a declared config home) and where. Pure metadata:
|
|
182
|
+
* the report never changes the file set.
|
|
183
|
+
*
|
|
184
|
+
* - `stoneName` — the stone that hit (the core `.git` — a `.git` directory
|
|
185
|
+
* or one of git's own pointer-file forms, such as a worktree/submodule
|
|
186
|
+
* `gitdir` file; a declared config home; the `.gitignore` proxy when
|
|
187
|
+
* mounted);
|
|
188
|
+
* - `path` — the scan-root-relative POSIX directory directly containing the
|
|
189
|
+
* stone (the nested repository's own directory, not the stone file);
|
|
190
|
+
* - `enforced` — whether the hit executed its cut under the active alignment
|
|
191
|
+
* face and exemption: `true` on the default git face (the entry names where
|
|
192
|
+
* the truncation happened), `false` for scanner-face core-stone hits
|
|
193
|
+
* (report-not-cut) and exemption-neutralized hits (registration, not
|
|
194
|
+
* rescue), and `true` always for config-home hits (your own declarations
|
|
195
|
+
* keep their verdict under every face).
|
|
196
|
+
*
|
|
197
|
+
* The scan root's own stones are not reported — the root is the universe
|
|
198
|
+
* boundary and never adjudicates against itself; only directories the walk
|
|
199
|
+
* visits as descent candidates appear here. Completeness is therefore the
|
|
200
|
+
* walk's: rule-pruned subtrees (preset, `exclude`, dot category) and
|
|
201
|
+
* everything below a budget cut (check `diagnostics`) leave no hits — a
|
|
202
|
+
* silent absence is not negative evidence. `.gitmodules` registration is
|
|
203
|
+
* invisible to the walk: a registered submodule's `.git` file hits exactly
|
|
204
|
+
* like an embedded repository's; `boundaryStones.exempt` is the walk-mode
|
|
205
|
+
* registration for both.
|
|
206
|
+
*/
|
|
207
|
+
export interface WalkStoneHit {
|
|
208
|
+
stoneName: string;
|
|
209
|
+
path: string;
|
|
210
|
+
enforced: boolean;
|
|
211
|
+
}
|
|
151
212
|
/** Result of a {@link walkScope} run. */
|
|
152
213
|
export interface WalkResult {
|
|
153
214
|
/** Included files as POSIX relative paths (forward slashes), sorted. */
|
|
154
215
|
files: string[];
|
|
216
|
+
/**
|
|
217
|
+
* Unresolved link entries (junctions / symlinks) named as they appear in
|
|
218
|
+
* {@link WalkResult.files} — scan-root-relative POSIX paths, sorted, and
|
|
219
|
+
* always a SUBSET of `files`: the same exclusion stack, dot category, and
|
|
220
|
+
* budget cut adjudicate both faces, so an excluded link (a dot-named one,
|
|
221
|
+
* a rule-excluded one, one below a budget cut) leaves no record. Pure
|
|
222
|
+
* report increment (2026-11-19 owner ruling): wherever every dirent lands
|
|
223
|
+
* inside the walk's three-way type dispatch, identical options produce the
|
|
224
|
+
* identical `files`. `followSymlinks: true` retires the face — followed
|
|
225
|
+
* links are not unresolved entries (dir-link bodies retire, file links
|
|
226
|
+
* resolve), so `links` is always `[]` under following.
|
|
227
|
+
*
|
|
228
|
+
* A dirent whose type predicates are all false — DT_UNKNOWN filesystems
|
|
229
|
+
* (pre-ftype XFS, some network filesystems), unrecognized Windows reparse
|
|
230
|
+
* tags (e.g. OneDrive placeholders), special files (FIFOs, sockets,
|
|
231
|
+
* devices) on any filesystem — costs one lstat and the true type governs:
|
|
232
|
+
* entries whose true type re-enters the dispatch enumerate where the
|
|
233
|
+
* traversal silently dropped them before; entries still outside it pay
|
|
234
|
+
* one lstat that changes nothing. Completeness is the walk's, as for
|
|
235
|
+
* {@link WalkStoneHit}: rule-pruned subtrees and everything below a
|
|
236
|
+
* budget cut leave no records — a silent absence is not negative evidence.
|
|
237
|
+
*/
|
|
238
|
+
links: string[];
|
|
155
239
|
/** Diagnostics; empty when the scan completed without a cut. */
|
|
156
240
|
diagnostics: ScanDiagnostic[];
|
|
241
|
+
/**
|
|
242
|
+
* Boundary-stone hits discovered during the walk, sorted by path then
|
|
243
|
+
* stone name — see {@link WalkStoneHit}. Empty when no directory on the
|
|
244
|
+
* walked tree carried a stone. Report-only: identical options without
|
|
245
|
+
* this field produce the identical `files`.
|
|
246
|
+
*/
|
|
247
|
+
stoneHits: WalkStoneHit[];
|
|
157
248
|
}
|
|
158
249
|
/** Thrown for malformed engine configuration (a strict rule without a reason, an unknown preset, ...). */
|
|
159
250
|
export declare class PathscopeConfigError extends Error {
|
package/dist/types.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA4PH,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,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hidden-attribute stash fs — the walk-side seam of the Windows
|
|
3
|
+
* hidden-attribute face (dot-name OR platform-hidden completion of
|
|
4
|
+
* `excludeDotEntries`, 2026-11-20 owner ruling).
|
|
5
|
+
*
|
|
6
|
+
* Rides the same fdir fs-injection seam as the link recorder, layered
|
|
7
|
+
* INNERMOST (closest to the OS): readdir goes to the native win32
|
|
8
|
+
* enumeration (FindFirstFileW — the dwFileAttributes ride along with the
|
|
9
|
+
* enumeration itself, zero extra syscalls, the same data libuv fetches and
|
|
10
|
+
* drops), returns duck-Dirents for the chassis three-way dispatch (the same
|
|
11
|
+
* structural-facade contract as the link recorder's direntFacade — the
|
|
12
|
+
* chassis consults exactly isFile/isDirectory/isSymbolicLink), and records
|
|
13
|
+
* the hidden bit SPARSELY (only true entries) keyed by the normalized
|
|
14
|
+
* directory key — the same keys the engine glue looks up.
|
|
15
|
+
*
|
|
16
|
+
* The chassis glue consults the stash at its two adjudication sites
|
|
17
|
+
* (excludeDirectory / keepFile) as a pure Map hit and passes the fact into
|
|
18
|
+
* the engine as adjudication metadata: the engine itself stays a pure
|
|
19
|
+
* string adjudicator and never touches the filesystem.
|
|
20
|
+
*/
|
|
21
|
+
import * as nativeFs from 'node:fs';
|
|
22
|
+
import type { WinAttrModule } from './win-attr.ts';
|
|
23
|
+
/** The fs surface fdir may touch — the link recorder's chassis contract verbatim. */
|
|
24
|
+
export type ChassisFs = Pick<typeof nativeFs, 'readdir' | 'readdirSync' | 'realpath' | 'realpathSync' | 'stat' | 'statSync'>;
|
|
25
|
+
/** A hidden-attribute stash ready to inject as the traversal's innermost fs. */
|
|
26
|
+
export interface HiddenStashFs {
|
|
27
|
+
/** Inject below the link recorder (or directly as the chassis `fs`). */
|
|
28
|
+
readonly fs: ChassisFs;
|
|
29
|
+
/**
|
|
30
|
+
* Whether `name` inside `dirKey` carried FILE_ATTRIBUTE_HIDDEN in the
|
|
31
|
+
* enumeration. Undefined = not hidden or never observed — both mean the
|
|
32
|
+
* attribute face does not fire (the stash records true entries only).
|
|
33
|
+
*/
|
|
34
|
+
hiddenFor(dirKey: string, name: string): boolean | undefined;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Create the stashing fs over the native module. The readdir call shape is
|
|
38
|
+
* exactly the one fdir's async walk uses (withFileTypes + callback); the
|
|
39
|
+
* sync twin mirrors the link recorder's coverage.
|
|
40
|
+
*/
|
|
41
|
+
export declare function createHiddenStashFs(winAttr: WinAttrModule): HiddenStashFs;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hidden-attribute stash fs — the walk-side seam of the Windows
|
|
3
|
+
* hidden-attribute face (dot-name OR platform-hidden completion of
|
|
4
|
+
* `excludeDotEntries`, 2026-11-20 owner ruling).
|
|
5
|
+
*
|
|
6
|
+
* Rides the same fdir fs-injection seam as the link recorder, layered
|
|
7
|
+
* INNERMOST (closest to the OS): readdir goes to the native win32
|
|
8
|
+
* enumeration (FindFirstFileW — the dwFileAttributes ride along with the
|
|
9
|
+
* enumeration itself, zero extra syscalls, the same data libuv fetches and
|
|
10
|
+
* drops), returns duck-Dirents for the chassis three-way dispatch (the same
|
|
11
|
+
* structural-facade contract as the link recorder's direntFacade — the
|
|
12
|
+
* chassis consults exactly isFile/isDirectory/isSymbolicLink), and records
|
|
13
|
+
* the hidden bit SPARSELY (only true entries) keyed by the normalized
|
|
14
|
+
* directory key — the same keys the engine glue looks up.
|
|
15
|
+
*
|
|
16
|
+
* The chassis glue consults the stash at its two adjudication sites
|
|
17
|
+
* (excludeDirectory / keepFile) as a pure Map hit and passes the fact into
|
|
18
|
+
* the engine as adjudication metadata: the engine itself stays a pure
|
|
19
|
+
* string adjudicator and never touches the filesystem.
|
|
20
|
+
*/
|
|
21
|
+
import * as nativeFs from 'node:fs';
|
|
22
|
+
/** dwFileAttributes bits this face dispatches on. */
|
|
23
|
+
const ATTR_HIDDEN = 0x2;
|
|
24
|
+
const ATTR_DIRECTORY = 0x10;
|
|
25
|
+
const ATTR_REPARSE_POINT = 0x400;
|
|
26
|
+
/**
|
|
27
|
+
* Create the stashing fs over the native module. The readdir call shape is
|
|
28
|
+
* exactly the one fdir's async walk uses (withFileTypes + callback); the
|
|
29
|
+
* sync twin mirrors the link recorder's coverage.
|
|
30
|
+
*/
|
|
31
|
+
export function createHiddenStashFs(winAttr) {
|
|
32
|
+
// Sparse by design: only hidden=true entries are recorded.
|
|
33
|
+
const hiddenByDir = new Map();
|
|
34
|
+
/** readdir keys arrive with fdir's trailing separator; the engine glue keys slashless. */
|
|
35
|
+
const dirKeyOf = (crawlPath) => crawlPath.replace(/\/+$/, '');
|
|
36
|
+
/**
|
|
37
|
+
* The duck-Dirent: exactly the three predicates the chassis dispatch
|
|
38
|
+
* consults. A reparse point is a link (junctions and symlinks are the
|
|
39
|
+
* same class here — the libuv dirent mapping's own equivalence); a
|
|
40
|
+
* directory bit without a reparse bit is a directory; everything else is
|
|
41
|
+
* a file. No all-false shape is producible, so the link recorder's
|
|
42
|
+
* DT_UNKNOWN rescue never fires on these entries.
|
|
43
|
+
*/
|
|
44
|
+
const facade = (name, attrs) => {
|
|
45
|
+
const isLink = (attrs & ATTR_REPARSE_POINT) !== 0;
|
|
46
|
+
const isDir = !isLink && (attrs & ATTR_DIRECTORY) !== 0;
|
|
47
|
+
return {
|
|
48
|
+
name,
|
|
49
|
+
isFile: () => !isDir && !isLink,
|
|
50
|
+
isDirectory: () => isDir,
|
|
51
|
+
isSymbolicLink: () => isLink,
|
|
52
|
+
};
|
|
53
|
+
};
|
|
54
|
+
const observe = (crawlPath, names, attrs) => {
|
|
55
|
+
const key = dirKeyOf(crawlPath);
|
|
56
|
+
const out = [];
|
|
57
|
+
for (let i = 0; i < names.length; i++) {
|
|
58
|
+
if ((attrs[i] & ATTR_HIDDEN) !== 0) {
|
|
59
|
+
let set = hiddenByDir.get(key);
|
|
60
|
+
if (set === undefined) {
|
|
61
|
+
set = new Set();
|
|
62
|
+
hiddenByDir.set(key, set);
|
|
63
|
+
}
|
|
64
|
+
set.add(names[i]);
|
|
65
|
+
}
|
|
66
|
+
out.push(facade(names[i], attrs[i]));
|
|
67
|
+
}
|
|
68
|
+
return out;
|
|
69
|
+
};
|
|
70
|
+
const readdir = ((crawlPath, opts, cb) => {
|
|
71
|
+
winAttr.readdirWithAttrs(crawlPath, (err, names, attrs) => {
|
|
72
|
+
if (err !== null) {
|
|
73
|
+
// Preserve the ErrnoException call shape fdir's error path expects.
|
|
74
|
+
cb(err);
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
cb(null, observe(crawlPath, names ?? [], attrs ?? []));
|
|
78
|
+
});
|
|
79
|
+
});
|
|
80
|
+
const readdirSync = ((crawlPath, opts) => {
|
|
81
|
+
const { names, attrs } = winAttr.readdirWithAttrsSync(crawlPath);
|
|
82
|
+
return observe(crawlPath, names, attrs);
|
|
83
|
+
});
|
|
84
|
+
return {
|
|
85
|
+
fs: {
|
|
86
|
+
readdir,
|
|
87
|
+
readdirSync,
|
|
88
|
+
realpath: nativeFs.realpath,
|
|
89
|
+
realpathSync: nativeFs.realpathSync,
|
|
90
|
+
stat: nativeFs.stat,
|
|
91
|
+
statSync: nativeFs.statSync,
|
|
92
|
+
},
|
|
93
|
+
hiddenFor: (dirKey, name) => (hiddenByDir.get(dirKey)?.has(name) === true ? true : undefined),
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
//# sourceMappingURL=walk-hidden.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"walk-hidden.js","sourceRoot":"","sources":["../src/walk-hidden.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Link face (2026-11-19 owner ruling) — the walk's second entry-kind report:
|
|
3
|
+
* unresolved link entries (junctions / symlinks) named as they appear in
|
|
4
|
+
* `files`. Pure report increment over the traversal the chassis already
|
|
5
|
+
* performs: the injected fs wrapper observes the Dirents fdir reads anyway
|
|
6
|
+
* (readdir withFileTypes — zero extra syscalls), records symlink entries
|
|
7
|
+
* into a side table keyed exactly like the walk's relative output paths,
|
|
8
|
+
* and the final `links` is the intersection with the admitted `files` —
|
|
9
|
+
* the same exclusion stack, dot category, and budget cut govern both faces.
|
|
10
|
+
*
|
|
11
|
+
* DT_UNKNOWN rescue (ruling point 2): a dirent whose type predicates are all
|
|
12
|
+
* false — DT_UNKNOWN filesystems (pre-ftype XFS, some network filesystems),
|
|
13
|
+
* unrecognized Windows reparse tags (e.g. OneDrive placeholders), special
|
|
14
|
+
* files (FIFOs, sockets, devices) on any filesystem — falls through every
|
|
15
|
+
* branch of the chassis dispatch and is silently dropped today. The wrapper
|
|
16
|
+
* pays one lstat per such entry and forwards a facade carrying the true
|
|
17
|
+
* type: entries whose true type re-enters the walk's three-way dispatch
|
|
18
|
+
* (file / directory / symlink — DT_UNKNOWN and placeholder dirents) now
|
|
19
|
+
* enumerate where they were silently dropped before, closing links on every
|
|
20
|
+
* filesystem; entries still outside the dispatch pay one lstat that changes
|
|
21
|
+
* nothing. Where every dirent lands inside the dispatch, the walk is
|
|
22
|
+
* byte-identical and pays nothing.
|
|
23
|
+
*
|
|
24
|
+
* `followSymlinks: true` retires the face (ruling point 3): followed links
|
|
25
|
+
* are not unresolved entries (dir-link bodies retire from the output, file
|
|
26
|
+
* links resolve), so no recorder is mounted at all under following.
|
|
27
|
+
*/
|
|
28
|
+
import { type Dirent } from 'node:fs';
|
|
29
|
+
import * as nativeFs from 'node:fs';
|
|
30
|
+
/** The fs surface fdir may touch — its `fs` option swaps the whole object. */
|
|
31
|
+
export type FsSix = Pick<typeof nativeFs, 'readdir' | 'readdirSync' | 'realpath' | 'realpathSync' | 'stat' | 'statSync'>;
|
|
32
|
+
/** A link recorder ready to inject as the chassis `fs` (see {@link createLinkRecorder}). */
|
|
33
|
+
export interface LinkRecorder {
|
|
34
|
+
/** Inject into fdir's `fs` option; the chassis consumes readdir/readdirSync only. */
|
|
35
|
+
readonly fs: FsSix;
|
|
36
|
+
/** Unresolved-link scan-root-relative paths observed during the crawl (a superset of the final face — intersection with the admitted files governs). */
|
|
37
|
+
readonly links: ReadonlySet<string>;
|
|
38
|
+
/** Record + rescue one dirent batch, returning the possibly rewritten batch. Exposed for the unit tests — the all-false dirent shape is not creatable through a real readdir on mainstream trees. */
|
|
39
|
+
readonly observeDirents: (crawlPath: string, entries: Dirent[]) => Dirent[];
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Create the recording fs. The first readdir call fixes the root's walk form
|
|
43
|
+
* (the crawl path fdir hands us — trailing separator, configured '/'), which
|
|
44
|
+
* every later crawl path extends by plain concatenation, so slicing by it
|
|
45
|
+
* reproduces the walk's relative output strings byte for byte.
|
|
46
|
+
*
|
|
47
|
+
* `base` swaps the enumeration layer below the recorder (default: node fs).
|
|
48
|
+
* The Windows hidden-attribute face mounts its stashing fs there — the
|
|
49
|
+
* recorder then observes the attribute-carrying duck-Dirents and both faces
|
|
50
|
+
* ride the same readdir batches with zero extra syscalls.
|
|
51
|
+
*/
|
|
52
|
+
export declare function createLinkRecorder(base?: FsSix): LinkRecorder;
|
|
53
|
+
/**
|
|
54
|
+
* One lstat for a dirent whose type predicates are all false (DT_UNKNOWN
|
|
55
|
+
* filesystems): the facade carries the true type so the chassis dispatches
|
|
56
|
+
* on it. Anything lstat cannot reach (races, permissions) or whose true type
|
|
57
|
+
* is still outside the walk's three-way dispatch (FIFOs, sockets, devices)
|
|
58
|
+
* returns the original dirent — exactly today's behavior. Exported for the
|
|
59
|
+
* unit tests (synthetic unknown dirents over a real tree).
|
|
60
|
+
*/
|
|
61
|
+
export declare function rescueUnknownType(walkPath: string, entry: Dirent): Dirent;
|
|
62
|
+
/** `links = files ∩ recorded` — the admitted set governs the face; filtering the sorted files preserves the sort. */
|
|
63
|
+
export declare function selectLinks(files: readonly string[], recorded: ReadonlySet<string>): string[];
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Link face (2026-11-19 owner ruling) — the walk's second entry-kind report:
|
|
3
|
+
* unresolved link entries (junctions / symlinks) named as they appear in
|
|
4
|
+
* `files`. Pure report increment over the traversal the chassis already
|
|
5
|
+
* performs: the injected fs wrapper observes the Dirents fdir reads anyway
|
|
6
|
+
* (readdir withFileTypes — zero extra syscalls), records symlink entries
|
|
7
|
+
* into a side table keyed exactly like the walk's relative output paths,
|
|
8
|
+
* and the final `links` is the intersection with the admitted `files` —
|
|
9
|
+
* the same exclusion stack, dot category, and budget cut govern both faces.
|
|
10
|
+
*
|
|
11
|
+
* DT_UNKNOWN rescue (ruling point 2): a dirent whose type predicates are all
|
|
12
|
+
* false — DT_UNKNOWN filesystems (pre-ftype XFS, some network filesystems),
|
|
13
|
+
* unrecognized Windows reparse tags (e.g. OneDrive placeholders), special
|
|
14
|
+
* files (FIFOs, sockets, devices) on any filesystem — falls through every
|
|
15
|
+
* branch of the chassis dispatch and is silently dropped today. The wrapper
|
|
16
|
+
* pays one lstat per such entry and forwards a facade carrying the true
|
|
17
|
+
* type: entries whose true type re-enters the walk's three-way dispatch
|
|
18
|
+
* (file / directory / symlink — DT_UNKNOWN and placeholder dirents) now
|
|
19
|
+
* enumerate where they were silently dropped before, closing links on every
|
|
20
|
+
* filesystem; entries still outside the dispatch pay one lstat that changes
|
|
21
|
+
* nothing. Where every dirent lands inside the dispatch, the walk is
|
|
22
|
+
* byte-identical and pays nothing.
|
|
23
|
+
*
|
|
24
|
+
* `followSymlinks: true` retires the face (ruling point 3): followed links
|
|
25
|
+
* are not unresolved entries (dir-link bodies retire from the output, file
|
|
26
|
+
* links resolve), so no recorder is mounted at all under following.
|
|
27
|
+
*/
|
|
28
|
+
import { lstatSync } from 'node:fs';
|
|
29
|
+
import * as nativeFs from 'node:fs';
|
|
30
|
+
/**
|
|
31
|
+
* Create the recording fs. The first readdir call fixes the root's walk form
|
|
32
|
+
* (the crawl path fdir hands us — trailing separator, configured '/'), which
|
|
33
|
+
* every later crawl path extends by plain concatenation, so slicing by it
|
|
34
|
+
* reproduces the walk's relative output strings byte for byte.
|
|
35
|
+
*
|
|
36
|
+
* `base` swaps the enumeration layer below the recorder (default: node fs).
|
|
37
|
+
* The Windows hidden-attribute face mounts its stashing fs there — the
|
|
38
|
+
* recorder then observes the attribute-carrying duck-Dirents and both faces
|
|
39
|
+
* ride the same readdir batches with zero extra syscalls.
|
|
40
|
+
*/
|
|
41
|
+
export function createLinkRecorder(base = nativeFs) {
|
|
42
|
+
const recorded = new Set();
|
|
43
|
+
// The first readdir argument is the root's walk form. Invariant: the engine
|
|
44
|
+
// always passes an ABSOLUTE root (resolve()d), so the root form is absolute
|
|
45
|
+
// and every later crawl path extends it by plain concatenation — the
|
|
46
|
+
// degenerate fdir root forms ('.'/'') would break the slice keying below
|
|
47
|
+
// and are never produced through walkScope.
|
|
48
|
+
let rootForm = null;
|
|
49
|
+
/** Record + rescue one dirent batch; returns the possibly rewritten batch. */
|
|
50
|
+
const observe = (crawlPath, entries) => {
|
|
51
|
+
if (rootForm === null)
|
|
52
|
+
rootForm = crawlPath;
|
|
53
|
+
const out = [];
|
|
54
|
+
for (const entry of entries) {
|
|
55
|
+
let observed = entry;
|
|
56
|
+
if (entry.isSymbolicLink()) {
|
|
57
|
+
recorded.add(crawlPath.slice(rootForm.length) + entry.name);
|
|
58
|
+
}
|
|
59
|
+
else if (!entry.isFile() && !entry.isDirectory()) {
|
|
60
|
+
observed = rescueUnknownType(crawlPath + entry.name, entry);
|
|
61
|
+
if (observed !== entry && observed.isSymbolicLink()) {
|
|
62
|
+
recorded.add(crawlPath.slice(rootForm.length) + entry.name);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
out.push(observed);
|
|
66
|
+
}
|
|
67
|
+
return out;
|
|
68
|
+
};
|
|
69
|
+
// fdir's async walk uses exactly this call shape (readdir with withFileTypes
|
|
70
|
+
// plus a callback); no other overload is ever taken through this object.
|
|
71
|
+
const readdir = ((crawlPath, opts, cb) => {
|
|
72
|
+
base.readdir(crawlPath, opts, (err, entries) => {
|
|
73
|
+
if (err)
|
|
74
|
+
return cb(err);
|
|
75
|
+
cb(null, observe(crawlPath, entries));
|
|
76
|
+
});
|
|
77
|
+
});
|
|
78
|
+
const readdirSync = ((crawlPath, opts) => observe(crawlPath, base.readdirSync(crawlPath, opts)));
|
|
79
|
+
return {
|
|
80
|
+
fs: {
|
|
81
|
+
readdir,
|
|
82
|
+
readdirSync,
|
|
83
|
+
realpath: base.realpath,
|
|
84
|
+
realpathSync: base.realpathSync,
|
|
85
|
+
stat: base.stat,
|
|
86
|
+
statSync: base.statSync,
|
|
87
|
+
},
|
|
88
|
+
links: recorded,
|
|
89
|
+
observeDirents: observe,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* One lstat for a dirent whose type predicates are all false (DT_UNKNOWN
|
|
94
|
+
* filesystems): the facade carries the true type so the chassis dispatches
|
|
95
|
+
* on it. Anything lstat cannot reach (races, permissions) or whose true type
|
|
96
|
+
* is still outside the walk's three-way dispatch (FIFOs, sockets, devices)
|
|
97
|
+
* returns the original dirent — exactly today's behavior. Exported for the
|
|
98
|
+
* unit tests (synthetic unknown dirents over a real tree).
|
|
99
|
+
*/
|
|
100
|
+
export function rescueUnknownType(walkPath, entry) {
|
|
101
|
+
let stats;
|
|
102
|
+
try {
|
|
103
|
+
stats = lstatSync(walkPath);
|
|
104
|
+
}
|
|
105
|
+
catch {
|
|
106
|
+
return entry;
|
|
107
|
+
}
|
|
108
|
+
if (stats.isSymbolicLink())
|
|
109
|
+
return direntFacade(entry.name, false, false, true);
|
|
110
|
+
if (stats.isFile())
|
|
111
|
+
return direntFacade(entry.name, true, false, false);
|
|
112
|
+
if (stats.isDirectory())
|
|
113
|
+
return direntFacade(entry.name, false, true, false);
|
|
114
|
+
return entry;
|
|
115
|
+
}
|
|
116
|
+
/** The chassis consults exactly these three predicates (its walk dispatch) — a structural facade is sound for that consumer. */
|
|
117
|
+
function direntFacade(name, file, dir, link) {
|
|
118
|
+
return { name, isFile: () => file, isDirectory: () => dir, isSymbolicLink: () => link };
|
|
119
|
+
}
|
|
120
|
+
/** `links = files ∩ recorded` — the admitted set governs the face; filtering the sorted files preserves the sort. */
|
|
121
|
+
export function selectLinks(files, recorded) {
|
|
122
|
+
return files.filter((rel) => recorded.has(rel));
|
|
123
|
+
}
|
|
124
|
+
//# sourceMappingURL=walk-links.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"walk-links.js","sourceRoot":"","sources":["../src/walk-links.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The native surface. `readdirWithAttrs*` returns the raw `dwFileAttributes`
|
|
3
|
+
* values per entry (libuv's dirent surface discards them — this is the whole
|
|
4
|
+
* point); `getHidden` is the per-path probe for the IO/probe face.
|
|
5
|
+
*/
|
|
6
|
+
export interface WinAttrModule {
|
|
7
|
+
/** 1 = hidden, 0 = not hidden, -1 = attribute unreadable. */
|
|
8
|
+
getHidden(path: string): number;
|
|
9
|
+
readdirWithAttrsSync(path: string): {
|
|
10
|
+
names: string[];
|
|
11
|
+
attrs: number[];
|
|
12
|
+
};
|
|
13
|
+
readdirWithAttrs(path: string, cb: (err: Error | null, names?: string[], attrs?: number[]) => void): void;
|
|
14
|
+
}
|
|
15
|
+
/** Load the prebuilt addon on win32; null everywhere the face cannot fire. */
|
|
16
|
+
export declare function loadWinAttr(): WinAttrModule | null;
|
|
17
|
+
/**
|
|
18
|
+
* The degradation diagnostic as a pure decision (unit-testable on every
|
|
19
|
+
* platform): on win32, with the dot category on and the native piece not
|
|
20
|
+
* loadable, the attribute face is inert and the walk must say so — never a
|
|
21
|
+
* silent behavioral gap. On unix there is no diagnostic: the attribute face
|
|
22
|
+
* is semantically vacuous there, nothing was lost.
|
|
23
|
+
*/
|
|
24
|
+
export declare function hiddenFaceDiagnostic(excludeDotEntriesOn: boolean, addonAvailable: boolean, isWin: boolean): {
|
|
25
|
+
code: 'windows-hidden-attributes-unavailable';
|
|
26
|
+
message: string;
|
|
27
|
+
} | null;
|
package/dist/win-attr.js
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Win-only native attribute reader — the capability piece of the Windows
|
|
3
|
+
* hidden-attribute face (the dot-name OR platform-hidden completion of
|
|
4
|
+
* `excludeDotEntries`, 2026-11-20 owner ruling).
|
|
5
|
+
*
|
|
6
|
+
* The prebuilt addon ships inside the package (prebuilds/win32-x64/) — no
|
|
7
|
+
* optionalDependencies, no consumer-side toolchain, no install-time failure
|
|
8
|
+
* modes. The loader never throws: on non-win platforms the module does not
|
|
9
|
+
* exist by design (unix hidden = dot-name only, ignore-crate precedent —
|
|
10
|
+
* the face is semantically vacuous there, not degraded), and a failed load
|
|
11
|
+
* on win32 means the DEGRADATION CONTRACT applies — the attribute face goes
|
|
12
|
+
* inert and walkScope says so loudly exactly once (see
|
|
13
|
+
* {@link hiddenFaceDiagnostic}).
|
|
14
|
+
*/
|
|
15
|
+
import { createRequire } from 'node:module';
|
|
16
|
+
import { platform } from 'node:process';
|
|
17
|
+
let cached;
|
|
18
|
+
/**
|
|
19
|
+
* A require anchored to THIS file, both projections. The CJS bundle stubs
|
|
20
|
+
* `import.meta` as an empty object (esbuild: import.meta is not available
|
|
21
|
+
* with format=cjs), so `createRequire(import.meta.url)` would throw there —
|
|
22
|
+
* the CJS projection rides `__filename` instead; the ESM projection has no
|
|
23
|
+
* `__filename` and uses `import.meta.url`.
|
|
24
|
+
*/
|
|
25
|
+
function requireForThisFile() {
|
|
26
|
+
if (typeof __filename !== 'undefined')
|
|
27
|
+
return createRequire(__filename);
|
|
28
|
+
return createRequire(import.meta.url);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* The prebuild's location relative to this file, per projection layout:
|
|
32
|
+
* one level up from src/ and from the tsc ESM output (dist/), two levels up
|
|
33
|
+
* from the esbuild CJS bundle (dist/cjs/). The first candidate that loads
|
|
34
|
+
* and passes the export-shape check wins.
|
|
35
|
+
*/
|
|
36
|
+
const PREBUILD_CANDIDATES = [
|
|
37
|
+
'../prebuilds/win32-x64/pathscope_win_attr.node',
|
|
38
|
+
'../../prebuilds/win32-x64/pathscope_win_attr.node',
|
|
39
|
+
];
|
|
40
|
+
/** Load the prebuilt addon on win32; null everywhere the face cannot fire. */
|
|
41
|
+
export function loadWinAttr() {
|
|
42
|
+
if (cached !== undefined)
|
|
43
|
+
return cached;
|
|
44
|
+
cached = null;
|
|
45
|
+
if (platform === 'win32') {
|
|
46
|
+
const require = requireForThisFile();
|
|
47
|
+
for (const candidate of PREBUILD_CANDIDATES) {
|
|
48
|
+
try {
|
|
49
|
+
const mod = require(candidate);
|
|
50
|
+
if (typeof mod.getHidden === 'function' && typeof mod.readdirWithAttrs === 'function' &&
|
|
51
|
+
typeof mod.readdirWithAttrsSync === 'function') {
|
|
52
|
+
cached = mod;
|
|
53
|
+
break;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
// Wrong-depth candidate or a genuinely missing/broken prebuild —
|
|
58
|
+
// degradation, not an error; the diagnostic in walkScope is the loud channel.
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return cached;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The degradation diagnostic as a pure decision (unit-testable on every
|
|
66
|
+
* platform): on win32, with the dot category on and the native piece not
|
|
67
|
+
* loadable, the attribute face is inert and the walk must say so — never a
|
|
68
|
+
* silent behavioral gap. On unix there is no diagnostic: the attribute face
|
|
69
|
+
* is semantically vacuous there, nothing was lost.
|
|
70
|
+
*/
|
|
71
|
+
export function hiddenFaceDiagnostic(excludeDotEntriesOn, addonAvailable, isWin) {
|
|
72
|
+
if (!isWin || !excludeDotEntriesOn || addonAvailable)
|
|
73
|
+
return null;
|
|
74
|
+
return {
|
|
75
|
+
code: 'windows-hidden-attributes-unavailable',
|
|
76
|
+
message: 'the Windows hidden-attribute face of the dot category is inert this run ' +
|
|
77
|
+
'(native prebuild not loaded): attribute-hidden, dot-less entries are NOT pruned — ' +
|
|
78
|
+
'never a silent cut; install integrity or the package tarball is the first suspect',
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
//# sourceMappingURL=win-attr.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"win-attr.js","sourceRoot":"","sources":["../src/win-attr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAcxC,IAAI,MAAwC,CAAC;AAE7C;;;;;;GAMG;AACH,SAAS,kBAAkB;IACzB,IAAI,OAAO,UAAU,KAAK,WAAW;QAAE,OAAO,aAAa,CAAC,UAAU,CAAC,CAAC;IACxE,OAAO,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG;IAC1B,gDAAgD;IAChD,mDAAmD;CAC3C,CAAC;AAEX,8EAA8E;AAC9E,MAAM,UAAU,WAAW;IACzB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,GAAG,IAAI,CAAC;IACd,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAA2B,CAAC;gBACzD,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU;oBACjF,OAAO,GAAG,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;oBACnD,MAAM,GAAG,GAAoB,CAAC;oBAC9B,MAAM;gBACR,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,8EAA8E;YAChF,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,mBAA4B,EAC5B,cAAuB,EACvB,KAAc;IAEd,IAAI,CAAC,KAAK,IAAI,CAAC,mBAAmB,IAAI,cAAc;QAAE,OAAO,IAAI,CAAC;IAClE,OAAO;QACL,IAAI,EAAE,uCAAuC;QAC7C,OAAO,EACL,0EAA0E;YAC1E,oFAAoF;YACpF,mFAAmF;KACtF,CAAC;AACJ,CAAC"}
|
package/docs/glossary.md
CHANGED
|
@@ -72,6 +72,10 @@ The API names this option `boundaryStones`; markers is the plain word for what t
|
|
|
72
72
|
|
|
73
73
|
**Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). A hit is either **enforced** (the cut executes) or report-only (`enforced: false` — the scanner alignment's report-not-cut: metadata, no cut). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
|
|
74
74
|
|
|
75
|
+
**Walk stone report** — the walk face's marker-hit report: `stoneHits` on the `walkScope` result, every hit the walk discovered as `{ stoneName, path, enforced }` — pure metadata, the file set is untouched. Only directories the walk visits report, so pruned subtrees and the area below a budget cut stay silent (see the walk stone report section in `docs/semantics.md`).
|
|
76
|
+
|
|
77
|
+
**Walk link report** — the walk face's entry-kind report: `links` on the `walkScope` result, the unresolved link entries (junctions / symlinks) named exactly as they appear in `files` — always a subset of it (the same exclusion stack governs both faces), `[]` under `followSymlinks: true` (see the walk link report section in `docs/semantics.md`).
|
|
78
|
+
|
|
75
79
|
## Alignment
|
|
76
80
|
|
|
77
81
|
**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.
|