@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
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,96 @@ description: pathscope changelog — user-visible changes per release, newest fi
|
|
|
7
7
|
All notable changes to this project are documented here. The format follows
|
|
8
8
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
9
9
|
|
|
10
|
+
## 0.4.0 — 2026-11-20
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **ignore family (`.ignore` / `.rgignore`) as first-class rule sources**
|
|
15
|
+
(2026-11-20 owner ruling — completing ignore-crate WalkBuilder parity):
|
|
16
|
+
the walk root's own `.ignore`/`.rgignore` and every descended directory's
|
|
17
|
+
are folded into the cascade with the same gitignore(5) syntax and
|
|
18
|
+
re-anchoring, after that directory's `.gitignore` and with `.rgignore`
|
|
19
|
+
beating `.ignore` (the ignore crate's own precedence, empirically backed
|
|
20
|
+
by the crate-judge lane, which gained a family-order conformance entry). Distinct
|
|
21
|
+
attribution on the probe face (`source: 'ignore'` + `ignoreFile`), a
|
|
22
|
+
dedicated layered escape hatch (`respectIgnoreFamily`, default `true` —
|
|
23
|
+
both family switches off = rg `--no-ignore`'s file face), face-orthogonal
|
|
24
|
+
under every `alignment` face, and **no inherited phase**: files above the
|
|
25
|
+
walk root are never read (rg's own behavior when the root is a
|
|
26
|
+
subdirectory; the global excludes file stays out for the same locality
|
|
27
|
+
reason). Trees without family files are byte-identical, always. New
|
|
28
|
+
composable-engine step `foldIgnoreFamily` (additive; not folding = the
|
|
29
|
+
family simply does not apply), `ExclusionIO.readIgnoreFamily?` optional
|
|
30
|
+
reader, and `HitSource` gains the `'ignore'` member.
|
|
31
|
+
- **Windows hidden-attribute face** (2026-11-20 owner ruling — completing rg
|
|
32
|
+
`hidden` semantics on the platform where the contract was half-kept): on
|
|
33
|
+
Windows, `excludeDotEntries` now also excludes entries carrying
|
|
34
|
+
`FILE_ATTRIBUTE_HIDDEN` — attribute-hidden, dot-less trees (AppData-class)
|
|
35
|
+
no longer enter walks uninvited; rg and fd (v7.4.0+) check exactly this
|
|
36
|
+
attribute, and the override whitelist rescues either face (exclusion is not
|
|
37
|
+
access control; naming a hidden entry reaches it, same as rg `--hidden`).
|
|
38
|
+
The capability is a win-only native piece shipped inside the package —
|
|
39
|
+
enumeration itself carries the attributes, so the walk pays zero extra
|
|
40
|
+
syscalls; no optional dependencies, no install-time toolchain, and pure
|
|
41
|
+
metadata queries throughout (OneDrive placeholders stay placeholders). The
|
|
42
|
+
dot hit's attribution now says which face fired (`LayerHit.via`:
|
|
43
|
+
`'name' | 'attribute'`), the probe face reads the same attribute through
|
|
44
|
+
the optional `ExclusionIO.hidden` method (walk and point queries agree),
|
|
45
|
+
and adjudication accepts an optional metadata argument
|
|
46
|
+
(`excludeDirectory`/`admitFile` and the `adjudicate*` variants — additive).
|
|
47
|
+
When the native piece cannot load on win32 the attribute face goes inert
|
|
48
|
+
and the scan says so loudly exactly once
|
|
49
|
+
(`windows-hidden-attributes-unavailable` diagnostic) — never a silent
|
|
50
|
+
behavioral gap.
|
|
51
|
+
- **walk link report** (2026-11-19 owner ruling — the second entry-kind report
|
|
52
|
+
face): `walkScope` results carry `links` — the unresolved link entries
|
|
53
|
+
(junctions / symlinks) named exactly as they appear in `files`, so
|
|
54
|
+
link-aware consumers stop re-deriving link-ness with per-entry lstat (the
|
|
55
|
+
any-nav replay layer was the cost evidence). Pure report increment:
|
|
56
|
+
identical options produce the identical `files`, and `links` is always a
|
|
57
|
+
subset of `files` — the same exclusion stack, dot category, and budget cut
|
|
58
|
+
govern both faces, so an excluded link (a dot-named one, a rule-excluded
|
|
59
|
+
one, one below a budget cut) leaves no record.
|
|
60
|
+
`followSymlinks: true` retires the face — followed links are not
|
|
61
|
+
unresolved entries; `links` is always `[]` under following. A dirent whose
|
|
62
|
+
type predicates are all false — DT_UNKNOWN filesystems (pre-ftype XFS,
|
|
63
|
+
some network filesystems), unrecognized Windows reparse tags (e.g.
|
|
64
|
+
OneDrive placeholders), special files (FIFOs, sockets, devices) on any
|
|
65
|
+
filesystem — costs one lstat and the true type governs: links close on
|
|
66
|
+
every filesystem, and entries whose true type re-enters the walk's
|
|
67
|
+
three-way dispatch (DT_UNKNOWN and placeholder dirents) enumerate where
|
|
68
|
+
the traversal silently dropped them before; wherever every dirent lands
|
|
69
|
+
inside the dispatch the walk is byte-identical and pays nothing.
|
|
70
|
+
|
|
71
|
+
### Changed
|
|
72
|
+
|
|
73
|
+
- **`excludeDotEntries` widens on Windows** (the feature side of the face
|
|
74
|
+
above): the default face now also prunes attribute-hidden, dot-less
|
|
75
|
+
entries and their subtrees. Unix behavior is byte-identical (the attribute
|
|
76
|
+
face does not exist there — ignore-crate precedent: unix hidden is
|
|
77
|
+
dot-name only). Consumers pinning default walks on Windows will see the
|
|
78
|
+
file set shrink by exactly the attribute-hidden entries; turning the
|
|
79
|
+
option off opens both faces together, and the override whitelist rescues
|
|
80
|
+
either face.
|
|
81
|
+
|
|
82
|
+
### Fixed
|
|
83
|
+
|
|
84
|
+
- **walk hot-path memory wall and attribution cost** (2026-11-20):
|
|
85
|
+
`walkScope` memory no longer grows O(files × rules). The attribution
|
|
86
|
+
enumeration ran inside the walk verdict path — a single-rule matcher
|
|
87
|
+
instance per rule, each memoizing every tested path unconditionally
|
|
88
|
+
(node-ignore 7.0.13's per-instance test cache) — so big curated trees
|
|
89
|
+
retained GB-scale memory (measured 4.9GB at 54k files × ~719 folded rules;
|
|
90
|
+
OOM past a 12GB heap at 109k × ~1,253). The walk verdict now pays only the
|
|
91
|
+
four channel instances' combined tests; per-rule attribution stays on the
|
|
92
|
+
probe/explain slow path with byte-identical hit chains. Measured: the same
|
|
93
|
+
half-tree reads 5.47s at 132MB (was 49.8s at 4.9GB) and the full tree
|
|
94
|
+
completes at 16.7s at 185MB (was unable to finish). Outputs are
|
|
95
|
+
byte-identical — the conformance corpus (28 fixtures / 152 cases, both
|
|
96
|
+
provenance kinds plus the crate judge) is green and per-file counts
|
|
97
|
+
reconcile exactly. A bounded-memory regression test pins the working set
|
|
98
|
+
(measured 18MB vs 443MB for the pre-fix shape on the test corpus).
|
|
99
|
+
|
|
10
100
|
## 0.3.0 — 2026-11-13
|
|
11
101
|
|
|
12
102
|
### Added
|
package/README.md
CHANGED
|
@@ -6,9 +6,11 @@ pathscope answers one question three ways: **which files are in scope?** Walk th
|
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
|
-
- **Git-native semantics** — an unregistered nested repository (an *embedded repository*, in git's own terminology) truncates the walk, exactly as git never descends into one; `.gitignore` cascades with last-match-wins, symlinks are not followed, hidden
|
|
9
|
+
- **Git-native semantics** — an unregistered nested repository (an *embedded repository*, in git's own terminology) truncates the walk, exactly as git never descends into one; `.gitignore` cascades with last-match-wins, symlinks are not followed, hidden entries are skipped by default with rg `hidden` semantics complete: dot-named everywhere, plus the Windows `FILE_ATTRIBUTE_HIDDEN` face (AppData-class attribute-hidden trees stay out of walks; the win-only native piece ships inside the package and says so loudly — never silently — if it cannot load).
|
|
10
10
|
- **Stone report** — every boundary-stone hit the walk discovers surfaces as structured metadata (`stoneHits`: stone name + directory + whether it enforced its cut). One walk tells you which subtrees are independent repositories and where: under the default git face the report names the truncation locations; under `alignment: 'scanner'` it is report-not-cut metadata. The file set is untouched by the report.
|
|
11
|
+
- **Link report** — the unresolved link entries (junctions / symlinks) surface as structured metadata (`links`), named exactly as they appear in `files`: the same exclusion stack, dot category, and budget cut govern both faces, so an excluded link leaves no record. `followSymlinks: true` retires the face. The file set is untouched by the report.
|
|
11
12
|
- **Default ignore presets** — opt-in groups for VCS internals, dependencies, build outputs, caches, and agent docs; every entry can be un-excluded with a named `!` negation.
|
|
13
|
+
- **The ignore family** — `.ignore` and `.rgignore` are first-class rule sources alongside `.gitignore` (ignore-crate WalkBuilder parity): rg users' curated ignore files govern the walk, same syntax, same cascade, distinct attribution, with `respectIgnoreFamily` as their own escape hatch. Files above the walk root are never read (rg's own locality).
|
|
12
14
|
- **Per-path point queries** — `explainScopePath` answers "is this path in scope, and exactly which layer decided" with a full attribution chain (preset / gitignore layer / boundary stone / strict-override-policy / dot), structural-prune answers, and an explicit-pierce projection. Read-only over the same scope request.
|
|
13
15
|
- **Loud budget** — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
|
|
14
16
|
- **Fail-loud everywhere** — malformed configuration throws `PathscopeConfigError`; missing git or a failed git command throws `PathscopeGitError`. Nothing is silently re-scanned a different way.
|
|
@@ -27,7 +29,7 @@ import { walkScope } from '@catheadowl/pathscope';
|
|
|
27
29
|
|
|
28
30
|
// Default stack: gitignore cascade + vcs/deps/build presets + dot entries
|
|
29
31
|
// excluded + loud budget (2000).
|
|
30
|
-
const { files, diagnostics, stoneHits } = await walkScope('/repo');
|
|
32
|
+
const { files, links, diagnostics, stoneHits } = await walkScope('/repo');
|
|
31
33
|
console.log(files);
|
|
32
34
|
//=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
|
|
33
35
|
|
|
@@ -41,6 +43,10 @@ console.log(stoneHits);
|
|
|
41
43
|
// default git face names where the truncation happened; under
|
|
42
44
|
// alignment: 'scanner' the core stone reports enforced: false and the
|
|
43
45
|
// walk descends. Pure metadata — the file set never changes because of it.
|
|
46
|
+
|
|
47
|
+
console.log(links);
|
|
48
|
+
//=> ['dir-link'] — the unresolved link entries, named as they appear in
|
|
49
|
+
// files (always a subset of it; followSymlinks: true retires the face).
|
|
44
50
|
```
|
|
45
51
|
|
|
46
52
|
All output paths are POSIX-style relative to the scanned root, sorted.
|
|
@@ -148,7 +154,7 @@ Files are only located, never read or parsed — TOML/YAML handling stays with y
|
|
|
148
154
|
|
|
149
155
|
| Export | One-line |
|
|
150
156
|
| --- | --- |
|
|
151
|
-
| `walkScope(root, options?)` | Walk + exclude → `{ files, diagnostics, stoneHits }` |
|
|
157
|
+
| `walkScope(root, options?)` | Walk + exclude → `{ files, links, diagnostics, stoneHits }` |
|
|
152
158
|
| `explainScopePath(root, relPath, options?)` | Point query → `{ excluded, structural, hitChain, explicit }` |
|
|
153
159
|
| `gitUniverse(root, options?)` | Ask git → `{ files, repoRoot, diagnostics }` |
|
|
154
160
|
| `locateNearest(names, options?)` | Nearest config file, no parsing |
|
package/dist/cascade.d.ts
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
/** The ignore-file family the walk reads — same gitignore(5) syntax, different governance residence. */
|
|
2
|
+
export type IgnoreFileName = '.gitignore' | '.ignore' | '.rgignore';
|
|
3
|
+
/** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
|
|
4
|
+
export declare function readIgnoreFileText(dirPath: string, filename: IgnoreFileName): string | null;
|
|
1
5
|
/** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
|
|
2
6
|
export declare function readGitignoreText(dirPath: string): string | null;
|
|
3
7
|
/** Split gitignore text into lines, tolerating CRLF. */
|
package/dist/cascade.js
CHANGED
|
@@ -25,15 +25,19 @@
|
|
|
25
25
|
* same logic.
|
|
26
26
|
*/
|
|
27
27
|
import { readFileSync } from 'node:fs';
|
|
28
|
-
/** Read `<dir
|
|
29
|
-
export function
|
|
28
|
+
/** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
|
|
29
|
+
export function readIgnoreFileText(dirPath, filename) {
|
|
30
30
|
try {
|
|
31
|
-
return readFileSync(`${dirPath.replace(/\/+$/, '')}
|
|
31
|
+
return readFileSync(`${dirPath.replace(/\/+$/, '')}/${filename}`, 'utf8');
|
|
32
32
|
}
|
|
33
33
|
catch {
|
|
34
34
|
return null;
|
|
35
35
|
}
|
|
36
36
|
}
|
|
37
|
+
/** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
|
|
38
|
+
export function readGitignoreText(dirPath) {
|
|
39
|
+
return readIgnoreFileText(dirPath, '.gitignore');
|
|
40
|
+
}
|
|
37
41
|
/** Split gitignore text into lines, tolerating CRLF. */
|
|
38
42
|
export function splitLines(text) {
|
|
39
43
|
return text.split(/\r?\n/);
|
package/dist/cascade.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cascade.js","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"cascade.js","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAKvC,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,QAAwB;IAC1E,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,kBAAkB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,MAAc;IAC3D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,UAAU,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAc;IACvD,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,uCAAuC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,QAAQ;QACzB,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAC5D,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC;IAC3B,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAClD,CAAC"}
|
package/dist/cjs/cascade.d.ts
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
/** The ignore-file family the walk reads — same gitignore(5) syntax, different governance residence. */
|
|
2
|
+
export type IgnoreFileName = '.gitignore' | '.ignore' | '.rgignore';
|
|
3
|
+
/** Read `<dir>/<filename>` (UTF-8); null when absent or unreadable. */
|
|
4
|
+
export declare function readIgnoreFileText(dirPath: string, filename: IgnoreFileName): string | null;
|
|
1
5
|
/** Read `<dir>/.gitignore` (UTF-8); null when absent or unreadable. */
|
|
2
6
|
export declare function readGitignoreText(dirPath: string): string | null;
|
|
3
7
|
/** Split gitignore text into lines, tolerating CRLF. */
|
|
@@ -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
|