@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.
@@ -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,13 +158,22 @@ 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
  };
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
- if (engine.excludeDirectory(dirName, key, hits))
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
- if (!engine.admitFile(rel))
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: options.followSymlinks === true,
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
- return { files: [...files].sort(), diagnostics, stoneHits: stoneReport };
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
@@ -1 +1 @@
1
- {"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
@@ -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); `dot` →
13
- * nothing beyond the source.
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. No budget — the loud file
96
- * budget is a chassis concern owned by walkScope.
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