@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/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 dot entries (rg `hidden` semantics: a walk-layer option, not a
122
- * gitignore rule). Default `true`. The override
123
- * whitelist can rescue dot entries.
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` 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.
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
- /** A loud diagnostic emitted by a scan. The budget cut is the canonical case. */
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;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"}
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;
@@ -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.