@catheadowl/pathscope 0.3.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 +90 -0
- package/README.md +9 -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/exclusion-engine.d.ts +67 -10
- package/dist/cjs/index.js +2101 -83
- package/dist/cjs/types.d.ts +58 -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.js +69 -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/types.d.ts +58 -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 +2 -0
- package/docs/semantics.md +16 -2
- package/package.json +4 -1
- package/prebuilds/win32-x64/pathscope_win_attr.node +0 -0
|
@@ -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
|
@@ -74,6 +74,8 @@ The API names this option `boundaryStones`; markers is the plain word for what t
|
|
|
74
74
|
|
|
75
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
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
|
+
|
|
77
79
|
## Alignment
|
|
78
80
|
|
|
79
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.
|
package/docs/semantics.md
CHANGED
|
@@ -55,6 +55,20 @@ Opt-in via `boundaryStones.gitignoreProxy`: treat a nested `.gitignore` as a bou
|
|
|
55
55
|
|
|
56
56
|
The report's completeness is the walk's: only visited descent candidates are probed, so subtrees removed by the rule stack (preset, `exclude`, the dot category) and everything below a budget cut leave no hits — a silent absence is not negative evidence; check `diagnostics` for the budget case. The core `.git` marker matches both of git's own forms (a `.git` directory, or the `gitdir` pointer file a worktree or submodule carries), and `.gitmodules` registration is invisible to the walk — a registered submodule hits exactly like an embedded repository, with `boundaryStones.exempt` as the walk-mode registration for both.
|
|
57
57
|
|
|
58
|
+
### The walk link report
|
|
59
|
+
|
|
60
|
+
`walkScope` results carry `links`: the unresolved link entries (junctions / symlinks), named exactly as they appear in `files` — scan-root-relative, sorted, and always a **subset** of `files`. The same exclusion stack, dot category, and budget cut govern both faces, so an excluded link (a dot-named one, a rule-excluded one, one below a budget cut) leaves no record; link-aware consumers read `links` instead of re-deriving link-ness with per-entry lstat. `followSymlinks: true` retires the face — followed links are not unresolved entries (directory-link bodies retire from the output, file links resolve), so `links` is always `[]` under following.
|
|
61
|
+
|
|
62
|
+
A dirent whose type predicates are all false — DT_UNKNOWN filesystems (pre-ftype XFS, some network filesystems), unrecognized Windows reparse tags (e.g. OneDrive placeholders), special files (FIFOs, sockets, devices) on any filesystem — costs one lstat and the true type governs: links close on every filesystem, and entries the traversal silently dropped on such trees before (DT_UNKNOWN and placeholder dirents) now enumerate. Where every dirent lands inside the walk's three-way type dispatch (file / directory / symlink), the walk is byte-identical and pays nothing. The report's completeness is the walk's, as for `stoneHits`: rule-pruned subtrees and everything below a budget cut leave no records — a silent absence is not negative evidence.
|
|
63
|
+
|
|
64
|
+
### The Windows hidden-attribute face
|
|
65
|
+
|
|
66
|
+
On Windows the dot category has a second detection face (2026-11-20 owner ruling, completing rg `hidden` semantics): an entry carrying `FILE_ATTRIBUTE_HIDDEN` is excluded by `excludeDotEntries` exactly like a dot-named one — AppData-class attribute-hidden, dot-less trees no longer enter walks uninvited. rg and fd (v7.4.0+) both check the attribute on Windows and the dot-name everywhere; the override whitelist rescues either face, and the dot hit's attribution says which face fired (`via: 'name' | 'attribute'`). The capability is a win-only native piece shipped inside the package (no optional dependencies, no install-time toolchain): enumeration itself carries the attributes, so the walk pays zero extra syscalls; the probe face reads the same attribute through its IO layer, so point queries and walks agree. When the native piece fails to load on win32 the attribute face goes inert and the scan says so loudly once (`windows-hidden-attributes-unavailable`) — never a silent behavioral gap; on unix the attribute face does not exist by design (ignore-crate precedent: unix hidden is dot-name only) and no diagnostic fires. Exclusion is not access control: naming a hidden entry through the override whitelist reaches it, same as rg `--hidden`.
|
|
67
|
+
|
|
68
|
+
### The ignore family (`.ignore` / `.rgignore`)
|
|
69
|
+
|
|
70
|
+
The ignore family's non-vcs members are first-class rule sources (completing ignore-crate WalkBuilder parity, 2026-11-20 owner ruling): `.ignore` and `.rgignore` are read with the same gitignore(5) syntax, on the walk root itself and in every descended directory, with `respectIgnoreFamily` (default `true`) as their own layered escape hatch — turning both it and `respectGitignore` off is the file-face equivalent of rg `--no-ignore`, either one alone matching rg's `--no-ignore-vcs`-style granularity. Per directory the family folds in after that directory's `.gitignore` and `.rgignore` beats `.ignore` (the ignore crate's own precedence, empirically backed by the crate-judge lane); deeper layers beat shallower ones like every cascade member; the policy layer stays rear (explicit channels beat files, rg `-g` isomorphism) and the override whitelist stays terminal. Attribution is distinct: family hits carry `source: 'ignore'` plus `ignoreFile`, so probe chains never misattribute a family cut to gitignore. Unlike `.gitignore`, the family has **no inherited phase** — files above the walk root are never read (rg's own behavior when the root is a subdirectory, and the repository-local rule space); the global excludes file stays out for the same reason. Face-orthogonal: the family is read under every `alignment` face, exactly like `.gitignore`. Trees without family files are byte-identical, always.
|
|
71
|
+
|
|
58
72
|
## Scanner semantics
|
|
59
73
|
|
|
60
74
|
With `alignment: 'scanner'` (ripgrep-style):
|
|
@@ -83,7 +97,7 @@ Presets are un-excludable by design: a named negation (`!vendor/`) in any gitign
|
|
|
83
97
|
## Walk defaults
|
|
84
98
|
|
|
85
99
|
- Output: POSIX relative paths, sorted.
|
|
86
|
-
- `excludeDotEntries` (default `true`): rg `hidden` semantics — a walk-layer option, not a gitignore rule; `override` can rescue
|
|
87
|
-
- `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before (rg `--no-ignore`).
|
|
100
|
+
- `excludeDotEntries` (default `true`): rg `hidden` semantics, platform-twin-faced — the dot-name face everywhere plus the Windows `FILE_ATTRIBUTE_HIDDEN` face (see above) — a walk-layer option, not a gitignore rule; `override` can rescue hidden entries on either face.
|
|
101
|
+
- `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before; the `.ignore` family keeps its own switch (`respectIgnoreFamily`), and both off is rg `--no-ignore`'s file face (rg `--no-ignore-vcs` granularity for either alone).
|
|
88
102
|
- Symlinks are not resolved by default (git/ripgrep default).
|
|
89
103
|
- `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination. `explainScopePath` is the read-only third face over the same request: it adjudicates, it never enumerates.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@catheadowl/pathscope",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Cross-repo shared engine resolving the in-scope file set: walk or per-path point queries (excluded + why), gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
"files": [
|
|
17
17
|
"dist",
|
|
18
18
|
"docs",
|
|
19
|
+
"prebuilds",
|
|
19
20
|
"CHANGELOG.md"
|
|
20
21
|
],
|
|
21
22
|
"publishConfig": {
|
|
@@ -24,6 +25,7 @@
|
|
|
24
25
|
},
|
|
25
26
|
"scripts": {
|
|
26
27
|
"build": "tsc -p tsconfig.build.json && node scripts/build-cjs.mjs",
|
|
28
|
+
"build:native": "node scripts/build-native.mjs",
|
|
27
29
|
"typecheck": "tsc --noEmit",
|
|
28
30
|
"lint:face": "node scripts/published-face-lint.mjs",
|
|
29
31
|
"test": "node --test \"test/*.test.ts\"",
|
|
@@ -40,6 +42,7 @@
|
|
|
40
42
|
"devDependencies": {
|
|
41
43
|
"@types/node": "^26.6.5",
|
|
42
44
|
"esbuild": "^0.28.2",
|
|
45
|
+
"node-gyp": "^13.1.0",
|
|
43
46
|
"typescript": "^7.0.2"
|
|
44
47
|
},
|
|
45
48
|
"exports": {
|
|
Binary file
|