@catheadowl/pathscope 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +109 -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 +2126 -102
- 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 +97 -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
package/dist/cjs/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,13 +158,22 @@ 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
|
};
|
|
151
178
|
/**
|
|
152
179
|
* One boundary-stone hit discovered during a walk — the walk face's share of
|
|
@@ -186,6 +213,29 @@ export interface WalkStoneHit {
|
|
|
186
213
|
export interface WalkResult {
|
|
187
214
|
/** Included files as POSIX relative paths (forward slashes), sorted. */
|
|
188
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[];
|
|
189
239
|
/** Diagnostics; empty when the scan completed without a cut. */
|
|
190
240
|
diagnostics: ScanDiagnostic[];
|
|
191
241
|
/**
|
|
@@ -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,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,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/engine.js
CHANGED
|
@@ -21,14 +21,21 @@
|
|
|
21
21
|
* evaluated last); directory excluded with no
|
|
22
22
|
* directory-level rescue → whole-tree pruning, the
|
|
23
23
|
* only structural non-revivable
|
|
24
|
-
* 4. dot category — walk-layer option (default on), whitelist can rescue
|
|
24
|
+
* 4. dot category — walk-layer option (default on), whitelist can rescue;
|
|
25
|
+
* platform-twin-faced: dot-name everywhere, plus the
|
|
26
|
+
* Windows FILE_ATTRIBUTE_HIDDEN face (rg hidden
|
|
27
|
+
* semantics completed, 2026-11-20 owner ruling)
|
|
25
28
|
* 5. budget — orthogonal and LOUD: a cut always emits a diagnostic
|
|
26
29
|
*/
|
|
27
30
|
import { existsSync } from 'node:fs';
|
|
28
31
|
import { join, resolve } from 'node:path';
|
|
32
|
+
import { platform } from 'node:process';
|
|
29
33
|
import { fdir } from 'fdir';
|
|
30
|
-
import { readGitignoreText } from './cascade.js';
|
|
34
|
+
import { readGitignoreText, readIgnoreFileText } from './cascade.js';
|
|
31
35
|
import { createExclusionEngine, validateOptions } from './exclusion-engine.js';
|
|
36
|
+
import { createLinkRecorder, selectLinks } from './walk-links.js';
|
|
37
|
+
import { createHiddenStashFs } from './walk-hidden.js';
|
|
38
|
+
import { hiddenFaceDiagnostic, loadWinAttr } from './win-attr.js';
|
|
32
39
|
import { PathscopeConfigError } from './types.js';
|
|
33
40
|
/** Loud default budget. */
|
|
34
41
|
const DEFAULT_MAX_FILES = 2000;
|
|
@@ -66,6 +73,19 @@ export async function walkScope(root, options = {}) {
|
|
|
66
73
|
return hits;
|
|
67
74
|
};
|
|
68
75
|
const diagnostics = [];
|
|
76
|
+
// Hidden-attribute face (2026-11-20 owner ruling): win-only native
|
|
77
|
+
// enumeration carrying dwFileAttributes rides INNERMOST on the same
|
|
78
|
+
// fs-injection seam as the link recorder; absent metadata = the face does
|
|
79
|
+
// not fire. On win32 with the native piece missing the walk says so loudly
|
|
80
|
+
// exactly once — never a silent behavioral gap; on unix the face is
|
|
81
|
+
// semantically vacuous (rg's own unix behavior is dot-name only) and no
|
|
82
|
+
// diagnostic fires.
|
|
83
|
+
const winAttr = options.excludeDotEntries === false ? null : loadWinAttr();
|
|
84
|
+
const respectIgnoreFamily = options.respectIgnoreFamily !== false;
|
|
85
|
+
const attrStash = winAttr === null ? null : createHiddenStashFs(winAttr);
|
|
86
|
+
const degraded = hiddenFaceDiagnostic(options.excludeDotEntries !== false, attrStash !== null, platform === 'win32');
|
|
87
|
+
if (degraded !== null)
|
|
88
|
+
diagnostics.push(degraded);
|
|
69
89
|
// Walk-face stone report (shape B, 2026-11-13 owner ruling): every stone hit
|
|
70
90
|
// the walk discovers surfaces as metadata — the composable face's
|
|
71
91
|
// report-not-cut principle carried onto the walk result. Collected at probe
|
|
@@ -90,19 +110,41 @@ export async function walkScope(root, options = {}) {
|
|
|
90
110
|
}
|
|
91
111
|
}
|
|
92
112
|
}
|
|
93
|
-
|
|
113
|
+
// The directory's hidden bit lives in its PARENT's enumeration stash —
|
|
114
|
+
// a pure Map hit. Dot-named directories short-circuit: the name face
|
|
115
|
+
// already fires and the lookup is moot.
|
|
116
|
+
const meta = attrStash !== null && !dirName.startsWith('.') &&
|
|
117
|
+
attrStash.hiddenFor(key.slice(0, key.lastIndexOf('/')), dirName) === true
|
|
118
|
+
? { hidden: true }
|
|
119
|
+
: undefined;
|
|
120
|
+
if (engine.excludeDirectory(dirName, key, hits, meta))
|
|
94
121
|
return true;
|
|
95
122
|
// Descending: fold this layer's .gitignore in after the parent's rules
|
|
96
123
|
// (shallow first, deep later; the subtree is pruned above
|
|
97
|
-
// before this point when the layer is excluded, so its `!` never applies)
|
|
124
|
+
// before this point when the layer is excluded, so its `!` never applies),
|
|
125
|
+
// then the .ignore family behind it (.ignore before .rgignore — the
|
|
126
|
+
// per-directory order; both files absent = no-op, byte-identical walk).
|
|
98
127
|
engine.foldGitignore(key, readGitignoreText(key));
|
|
128
|
+
if (respectIgnoreFamily) {
|
|
129
|
+
engine.foldIgnoreFamily(key, {
|
|
130
|
+
ignore: readIgnoreFileText(key, '.ignore'),
|
|
131
|
+
rgignore: readIgnoreFileText(key, '.rgignore'),
|
|
132
|
+
});
|
|
133
|
+
}
|
|
99
134
|
return false;
|
|
100
135
|
};
|
|
101
136
|
/** Per-file adjudication, then the loud budget gate. */
|
|
102
137
|
const keepFile = (rel) => {
|
|
103
138
|
if (budgetCut)
|
|
104
139
|
return false;
|
|
105
|
-
|
|
140
|
+
// The file's hidden bit lives in its parent's stash — same pure Map hit.
|
|
141
|
+
const slash = rel.lastIndexOf('/');
|
|
142
|
+
const name = slash === -1 ? rel : rel.slice(slash + 1);
|
|
143
|
+
const fileMeta = attrStash !== null && !name.startsWith('.') &&
|
|
144
|
+
attrStash.hiddenFor(slash === -1 ? scanKey : `${scanKey}/${rel.slice(0, slash)}`, name) === true
|
|
145
|
+
? { hidden: true }
|
|
146
|
+
: undefined;
|
|
147
|
+
if (!engine.admitFile(rel, fileMeta))
|
|
106
148
|
return false;
|
|
107
149
|
if (included >= maxFiles) {
|
|
108
150
|
budgetCut = true;
|
|
@@ -117,23 +159,43 @@ export async function walkScope(root, options = {}) {
|
|
|
117
159
|
included += 1;
|
|
118
160
|
return true;
|
|
119
161
|
};
|
|
162
|
+
// Link face (2026-11-19 owner ruling, pure-additive partition): the
|
|
163
|
+
// unresolved-link entries the traversal already classifies surface as a
|
|
164
|
+
// second report face. The recorder rides the chassis's own readdir
|
|
165
|
+
// Dirents — entries inside the walk's three-way type dispatch pay nothing;
|
|
166
|
+
// a dirent outside it (DT_UNKNOWN filesystems, unrecognized reparse tags,
|
|
167
|
+
// special files) pays one lstat. followSymlinks retires the face: followed
|
|
168
|
+
// links are not unresolved entries, so no recorder is mounted at all and
|
|
169
|
+
// `links` is always [].
|
|
170
|
+
const follow = options.followSymlinks === true;
|
|
171
|
+
// Recorder OUTER, attribute enumeration INNER: the recorder observes the
|
|
172
|
+
// attribute-carrying duck-Dirents, so the links face and the hidden face
|
|
173
|
+
// ride the same readdir batches — zero extra syscalls for either.
|
|
174
|
+
const recorder = follow ? null : createLinkRecorder(attrStash?.fs);
|
|
120
175
|
const files = await new fdir({
|
|
121
176
|
pathSeparator: '/',
|
|
122
177
|
exclude: excludeDirectory,
|
|
123
178
|
signal: controller.signal,
|
|
124
|
-
resolveSymlinks:
|
|
179
|
+
resolveSymlinks: follow,
|
|
125
180
|
// Keep descended-through-symlink paths in the scan-root universe instead
|
|
126
181
|
// of emitting real (possibly outside-root) paths.
|
|
127
182
|
useRealPaths: false,
|
|
128
183
|
// Unreadable directories are skipped, ripgrep-style; the loud channel is
|
|
129
184
|
// the budget, not per-directory I/O errors.
|
|
130
185
|
suppressErrors: true,
|
|
186
|
+
fs: recorder?.fs ?? attrStash?.fs,
|
|
131
187
|
})
|
|
132
188
|
.withRelativePaths()
|
|
133
189
|
.filter((path) => keepFile(path))
|
|
134
190
|
.crawl(rootNative)
|
|
135
191
|
.withPromise();
|
|
136
192
|
stoneReport.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.stoneName < b.stoneName ? -1 : a.stoneName > b.stoneName ? 1 : 0);
|
|
137
|
-
|
|
193
|
+
const sortedFiles = [...files].sort();
|
|
194
|
+
return {
|
|
195
|
+
files: sortedFiles,
|
|
196
|
+
links: recorder ? selectLinks(sortedFiles, recorder.links) : [],
|
|
197
|
+
diagnostics,
|
|
198
|
+
stoneHits: stoneReport,
|
|
199
|
+
};
|
|
138
200
|
}
|
|
139
201
|
//# sourceMappingURL=engine.js.map
|
package/dist/engine.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAsB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAA2D,MAAM,YAAY,CAAC;AAE3G,2BAA2B;AAC3B,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,OAAO,GAAiB,EAAE;IACtE,eAAe,CAAC,OAAO,CAAC,CAAC;IAEzB,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAAC,6BAA6B,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,2EAA2E;IAC3E,yEAAyE;IACzE,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE/C,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,2EAA2E;IAC3E,wEAAwE;IACxE,0EAA0E;IAC1E,+DAA+D;IAC/D,MAAM,SAAS,GAAG,CAAC,GAAW,EAAqB,EAAE;QACnD,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,mEAAmE;IACnE,oEAAoE;IACpE,0EAA0E;IAC1E,2EAA2E;IAC3E,oEAAoE;IACpE,wEAAwE;IACxE,oBAAoB;IACpB,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3E,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,KAAK,KAAK,CAAC;IAClE,MAAM,SAAS,GAAyB,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,iBAAiB,KAAK,KAAK,EAAE,SAAS,KAAK,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC;IACrH,IAAI,QAAQ,KAAK,IAAI;QAAE,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClD,6EAA6E;IAC7E,kEAAkE;IAClE,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,uEAAuE;IACvE,6CAA6C;IAC7C,MAAM,WAAW,GAA4B,EAAE,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,yFAAyF;IACzF,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAE,OAAe,EAAW,EAAE;QACrE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;gBACvD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;oBAChC,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC,CAAC;gBAChG,CAAC;YACH,CAAC;QACH,CAAC;QACD,uEAAuE;QACvE,qEAAqE;QACrE,wCAAwC;QACxC,MAAM,IAAI,GACR,SAAS,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAC9C,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,IAAI;YACvE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE;YAClB,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnE,uEAAuE;QACvE,0DAA0D;QAC1D,2EAA2E;QAC3E,oEAAoE;QACpE,wEAAwE;QACxE,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,mBAAmB,EAAE,CAAC;YACxB,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,SAAS,CAAC;gBAC1C,QAAQ,EAAE,kBAAkB,CAAC,GAAG,EAAE,WAAW,CAAC;aAC/C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,wDAAwD;IACxD,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAW,EAAE;QACxC,IAAI,SAAS;YAAE,OAAO,KAAK,CAAC;QAC5B,yEAAyE;QACzE,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACvD,MAAM,QAAQ,GACZ,SAAS,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAC3C,SAAS,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,IAAI;YAC9F,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE;YAClB,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACnD,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAAC;YACzB,SAAS,GAAG,IAAI,CAAC;YACjB,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,iBAAiB;gBACvB,KAAK,EAAE,QAAQ;gBACf,OAAO,EAAE,kBAAkB,QAAQ,wDAAwD;aAC5F,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,oEAAoE;IACpE,wEAAwE;IACxE,mEAAmE;IACnE,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,wBAAwB;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAEnE,MAAM,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC;QAC3B,aAAa,EAAE,GAAG;QAClB,OAAO,EAAE,gBAAgB;QACzB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,eAAe,EAAE,MAAM;QACvB,yEAAyE;QACzE,kDAAkD;QAClD,YAAY,EAAE,KAAK;QACnB,yEAAyE;QACzE,4CAA4C;QAC5C,cAAc,EAAE,IAAI;QACpB,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,SAAS,EAAE,EAAE;KAClC,CAAC;SACC,iBAAiB,EAAE;SACnB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;SAChC,KAAK,CAAC,UAAU,CAAC;SACjB,WAAW,EAAE,CAAC;IAEjB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACxB,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAChH,CAAC;IACF,MAAM,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;QAC/D,WAAW;QACX,SAAS,EAAE,WAAW;KACvB,CAAC;AACJ,CAAC"}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type PresetName, type ScopeOptions } from './types.ts';
|
|
2
2
|
/** The provenance layers of the exclusion stack, in full-stack priority order. */
|
|
3
|
-
export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'policy' | 'dot';
|
|
3
|
+
export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'ignore' | 'policy' | 'dot';
|
|
4
4
|
/**
|
|
5
5
|
* One attribution entry of a layer adjudication (the read-only probe face's
|
|
6
6
|
* unit). Field payload by source: `stone` → stoneName + enforced
|
|
@@ -9,8 +9,12 @@ export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore'
|
|
|
9
9
|
* as supplied); `preset` → presetName + ruleText (the entry as mounted);
|
|
10
10
|
* `gitignore` → gitignoreAnchor ('' = the scan root's own layer, a relative
|
|
11
11
|
* dir = a nested layer, 'inherited:..' = a layer above the scan root) +
|
|
12
|
-
* ruleText (the line as written — re-anchoring stays internal); `
|
|
13
|
-
*
|
|
12
|
+
* ruleText (the line as written — re-anchoring stays internal); `ignore`
|
|
13
|
+
* (the .ignore/.rgignore family) → the same depth anchor plus `ignoreFile`
|
|
14
|
+
* naming which family member fired; `dot` →
|
|
15
|
+
* `via`, always present: which face of the rg `hidden` concept fired —
|
|
16
|
+
* 'name' = the dot-name face every platform has, 'attribute' = the Windows
|
|
17
|
+
* FILE_ATTRIBUTE_HIDDEN face.
|
|
14
18
|
*/
|
|
15
19
|
export interface LayerHit {
|
|
16
20
|
source: HitSource;
|
|
@@ -19,6 +23,22 @@ export interface LayerHit {
|
|
|
19
23
|
ruleText?: string;
|
|
20
24
|
stoneName?: string;
|
|
21
25
|
enforced?: boolean;
|
|
26
|
+
/** `ignore` only: which family member produced the hit ('.ignore' | '.rgignore'). */
|
|
27
|
+
ignoreFile?: '.ignore' | '.rgignore';
|
|
28
|
+
/** `dot` only, always present there: which face of the rg hidden concept fired. */
|
|
29
|
+
via?: 'name' | 'attribute';
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Adjudication metadata the caller pre-fetches per entry — the platform
|
|
33
|
+
* facts a pure string adjudicator cannot see. The walk glue fills it from
|
|
34
|
+
* the enumeration stash (zero extra syscalls); the probe face fills it from
|
|
35
|
+
* `ExclusionIO.hidden`. Absent/undefined metadata = the face does not fire
|
|
36
|
+
* (a non-win platform, a degraded native piece, or a custom IO without the
|
|
37
|
+
* capability) — exactly the walk's degradation contract.
|
|
38
|
+
*/
|
|
39
|
+
export interface EntryMeta {
|
|
40
|
+
/** The entry carries the platform's hidden bit (Windows FILE_ATTRIBUTE_HIDDEN). */
|
|
41
|
+
hidden?: boolean;
|
|
22
42
|
}
|
|
23
43
|
/** Directory adjudication with attribution — `excluded` is the walk verdict verbatim. */
|
|
24
44
|
export interface DirectoryAdjudication {
|
|
@@ -44,8 +64,29 @@ export interface ExclusionIO {
|
|
|
44
64
|
exists(dirKey: string, name: string): Promise<boolean>;
|
|
45
65
|
/** Read `<dirKey>/.gitignore` (UTF-8); null when absent or unreadable. */
|
|
46
66
|
readGitignore(dirKey: string): Promise<string | null>;
|
|
67
|
+
/**
|
|
68
|
+
* Read `<dirKey>/.ignore` and `<dirKey>/.rgignore` (UTF-8); null per file
|
|
69
|
+
* when absent or unreadable. The ignore family's read face — optional so
|
|
70
|
+
* existing custom IO implementations keep compiling; absent method = the
|
|
71
|
+
* family stays inert for that consumer's construction and probe phases
|
|
72
|
+
* (the walk reads the files itself through the node fs, unaffected).
|
|
73
|
+
*/
|
|
74
|
+
readIgnoreFamily?(dirKey: string): Promise<{
|
|
75
|
+
ignore: string | null;
|
|
76
|
+
rgignore: string | null;
|
|
77
|
+
}>;
|
|
78
|
+
/**
|
|
79
|
+
* Probe whether `name` inside `dirKey` carries the platform's hidden bit
|
|
80
|
+
* (Windows FILE_ATTRIBUTE_HIDDEN). Null = unknown — a non-win platform,
|
|
81
|
+
* a custom IO without the capability, or an unreadable attribute: the
|
|
82
|
+
* caller passes no hidden metadata and the attribute face stays inert,
|
|
83
|
+
* exactly like the walk's degradation contract. Optional so existing
|
|
84
|
+
* custom IO implementations keep compiling; the dot-name face needs
|
|
85
|
+
* nothing from this method.
|
|
86
|
+
*/
|
|
87
|
+
hidden?(dirKey: string, name: string): Promise<boolean | null>;
|
|
47
88
|
}
|
|
48
|
-
/** Default IO over the node filesystem (existsSync / readFileSync). */
|
|
89
|
+
/** Default IO over the node filesystem (existsSync / readFileSync + the win32 native attribute probe). */
|
|
49
90
|
export declare const nodeExclusionIO: ExclusionIO;
|
|
50
91
|
/** A composable exclusion engine over one scan root. Not concurrent-safe: one engine per traversal run. */
|
|
51
92
|
export interface ExclusionEngine {
|
|
@@ -81,7 +122,7 @@ export interface ExclusionEngine {
|
|
|
81
122
|
* mounting the scanner face that drives the boolean form silently loses
|
|
82
123
|
* the face. Report names, not booleans.
|
|
83
124
|
*/
|
|
84
|
-
excludeDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): boolean;
|
|
125
|
+
excludeDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[], meta?: EntryMeta): boolean;
|
|
85
126
|
/**
|
|
86
127
|
* Fold a descended directory's `.gitignore` text into the cascade (shallow
|
|
87
128
|
* first, deep later — appended at the rear of the rule stream, subtree-
|
|
@@ -90,12 +131,28 @@ export interface ExclusionEngine {
|
|
|
90
131
|
* root's own `.gitignore` is consumed at construction).
|
|
91
132
|
*/
|
|
92
133
|
foldGitignore(dirPath: string, text: string | null | undefined): void;
|
|
134
|
+
/**
|
|
135
|
+
* Fold a descended directory's `.ignore` and `.rgignore` into the
|
|
136
|
+
* cascade — appended after that directory's `.gitignore` layer (family
|
|
137
|
+
* beats vcs at the same depth; within the family `.rgignore` beats
|
|
138
|
+
* `.ignore`, the ignore crate's own per-directory order). No-op for null
|
|
139
|
+
* texts, when `respectIgnoreFamily` is false, or when `dirPath` is the
|
|
140
|
+
* scan root (the root's own family files are consumed at construction).
|
|
141
|
+
* The family has NO inherited phase: files above the scan root are never
|
|
142
|
+
* read — unlike `.gitignore`, deliberately (rg's own behavior when the
|
|
143
|
+
* root is a subdirectory, and the repository-local rule space).
|
|
144
|
+
*/
|
|
145
|
+
foldIgnoreFamily(dirPath: string, texts: {
|
|
146
|
+
ignore?: string | null;
|
|
147
|
+
rgignore?: string | null;
|
|
148
|
+
}): void;
|
|
93
149
|
/**
|
|
94
150
|
* Per-file adjudication (pure) for a scan-root-relative POSIX path: strict
|
|
95
|
-
* → override → combined table → dot category.
|
|
96
|
-
*
|
|
151
|
+
* → override → combined table → dot category. `meta` carries the
|
|
152
|
+
* pre-fetched platform-hidden bit for the dot category's attribute face.
|
|
153
|
+
* No budget — the loud file budget is a chassis concern owned by walkScope.
|
|
97
154
|
*/
|
|
98
|
-
admitFile(relPath: string): boolean;
|
|
155
|
+
admitFile(relPath: string, meta?: EntryMeta): boolean;
|
|
99
156
|
/**
|
|
100
157
|
* {@link ExclusionEngine.excludeDirectory} with attribution: the same
|
|
101
158
|
* verdict (and the same policy-negation restatement side effect), plus the
|
|
@@ -106,13 +163,13 @@ export interface ExclusionEngine {
|
|
|
106
163
|
* so the last table entry is the last-match-wins winner. The verdict comes
|
|
107
164
|
* from the same rule instances the walk uses — identical by construction.
|
|
108
165
|
*/
|
|
109
|
-
adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): DirectoryAdjudication;
|
|
166
|
+
adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[], meta?: EntryMeta): DirectoryAdjudication;
|
|
110
167
|
/**
|
|
111
168
|
* {@link ExclusionEngine.admitFile} with attribution — same file-order
|
|
112
169
|
* verdict plus the per-layer hit list (see
|
|
113
170
|
* {@link ExclusionEngine.adjudicateDirectory}).
|
|
114
171
|
*/
|
|
115
|
-
adjudicateFile(relPath: string): FileAdjudication;
|
|
172
|
+
adjudicateFile(relPath: string, meta?: EntryMeta): FileAdjudication;
|
|
116
173
|
/**
|
|
117
174
|
* Stone attribution only (pure): per-stone hit entries with `enforced`
|
|
118
175
|
* flags for one scan-root-relative directory — the exemption (named
|