@catheadowl/pathscope 0.1.1 → 0.3.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 +72 -0
- package/README.md +51 -3
- package/dist/cascade.d.ts +6 -0
- package/dist/cascade.js +21 -11
- package/dist/cascade.js.map +1 -1
- package/dist/cjs/cascade.d.ts +6 -0
- package/dist/cjs/engine.d.ts +4 -0
- package/dist/cjs/exclusion-engine.d.ts +71 -1
- package/dist/cjs/explain.d.ts +109 -0
- package/dist/cjs/index.d.ts +10 -6
- package/dist/cjs/index.js +324 -80
- package/dist/cjs/presets.d.ts +11 -3
- package/dist/cjs/types.d.ts +43 -2
- package/dist/engine.d.ts +4 -0
- package/dist/engine.js +24 -2
- package/dist/engine.js.map +1 -1
- package/dist/exclusion-engine.d.ts +71 -1
- package/dist/exclusion-engine.js +234 -93
- package/dist/exclusion-engine.js.map +1 -1
- package/dist/explain.d.ts +109 -0
- package/dist/explain.js +193 -0
- package/dist/explain.js.map +1 -0
- package/dist/index.d.ts +10 -6
- package/dist/index.js +8 -5
- package/dist/index.js.map +1 -1
- package/dist/presets.d.ts +11 -3
- package/dist/presets.js +17 -7
- package/dist/presets.js.map +1 -1
- package/dist/types.d.ts +43 -2
- package/dist/types.js.map +1 -1
- package/docs/glossary.md +29 -3
- package/docs/semantics.md +20 -4
- package/package.json +4 -2
package/docs/glossary.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Consumer glossary of the pathscope vocabulary — the
|
|
2
|
+
description: Consumer glossary of the pathscope vocabulary — the three resolution faces (walk, ask-git, point query), the exclusion stack layers, boundary markers, alignment, the probe nouns and the fail-loud reliability nouns
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Glossary
|
|
6
6
|
|
|
7
|
-
The vocabulary pathscope uses, in one place. Terms are sorted from the top down: read the
|
|
7
|
+
The vocabulary pathscope uses, in one place. Terms are sorted from the top down: read the core nouns plus the probe face and every README example parses; the rest matters when you tune the stack.
|
|
8
8
|
|
|
9
9
|
## The core nouns
|
|
10
10
|
|
|
@@ -16,10 +16,30 @@ The vocabulary pathscope uses, in one place. Terms are sorted from the top down:
|
|
|
16
16
|
|
|
17
17
|
**Ask-git mode** — resolving the path scope by asking git instead of walking (`git ls-files` under the hood). Git is the truth: the exclusion stack does not participate by default. Rides `gitUniverse`. Mutually exclusive with walk mode — one scope request goes through one of the two, never a blend.
|
|
18
18
|
|
|
19
|
+
**Point query** — resolving ONE path instead of the whole set: `explainScopePath(root, relPath, options?)` answers whether the path is in scope and exactly which layer decided. The read-only third face over the same scope request (walk mode enumerates, ask-git lists, the point query adjudicates); nonexistent paths answer hypothetically over the rule space.
|
|
20
|
+
|
|
21
|
+
**Rule space** — the full set of adjudicating rules for one scope request: mounted presets, every gitignore layer (root, nested, inherited), the policy layer, plus the non-rule layers (stones, strict, override, dot). A point query's `excluded` is the rule-space verdict — it equals walkScope membership for paths on disk under an un-cut budget; the budget is a walk-chassis concern outside the rule space, and walkScope membership is undefined for paths that do not exist.
|
|
22
|
+
|
|
19
23
|
**Composable exclusion engine** — the exclusion stack + gitignore cascade as a standalone engine (`createExclusionEngine`). For consumers that own their own traversal — watchers, incremental snapshots, virtual filesystems — and cannot use the built-in walker.
|
|
20
24
|
|
|
25
|
+
**Walk chassis** — the traversal wrapper that owns the loud budget and symlink following (`walkScope`); the decision core (exclusion stack + cascade) is shared by every face. The point query and the composable engine are chassis-free: they accept the chassis options and ignore them.
|
|
26
|
+
|
|
21
27
|
**Nearest config file** — a configuration file located on the way up from a starting directory; the nearest one wins (`locateNearest`). pathscope only locates it, never reads or parses it.
|
|
22
28
|
|
|
29
|
+
## The probe face
|
|
30
|
+
|
|
31
|
+
The vocabulary a point query's answer is made of.
|
|
32
|
+
|
|
33
|
+
**Hit chain** — the ordered adjudication record a point query returns: every layer that matched, in stack-priority order (stones → strict → override → the combined rule table → dot entries); within the combined table, stream order (presets → cascade → your excludes), so the last table entry is the last-match-wins winner. The chain is not empty only on exclusions — a rescued path tells its story too (the preset hit, then the override that saved it).
|
|
34
|
+
|
|
35
|
+
**Hit entry** — one link of the chain: the source layer plus its attribution — the preset name, or the gitignore layer anchor with the rule as written, or the stone name, or the strict/override/policy pattern — and `path`, the path the hit adjudicated: the queried path for rule answers, the excluded ancestor for structural ones.
|
|
36
|
+
|
|
37
|
+
**Structural answer** — a point-query verdict that came from a directory-level prune: an excluded ancestor (the whole subtree rides the prune and the pruned layer's own rules never participate) or the queried directory itself being cut (a trailing-slash query). `structural: true` means the verdict is a place, not a rule.
|
|
38
|
+
|
|
39
|
+
**Layer anchor** — where a gitignore hit's rule lives: `''` is the scan root's own `.gitignore`, a relative directory (e.g. `sub`) is a nested layer inside the scan, and `inherited:..` names a layer above the scan root (one `..` per level up). The rule space is **repository-local**: git's global excludes (`core.excludesFile`) and `.git/info/exclude` do not participate — reconcile against `git check-ignore` accordingly.
|
|
40
|
+
|
|
41
|
+
**Explicit projection** — the point query's built-in answer to "what if I name this path explicitly": `pierceable` is false only when an enforced stone or a strict rule blocks; every other layer yields to explicit naming (naming a path is override-channel semantics). A mechanism, not a policy — whether to report, warn, or refuse a pierceable path is the consumer's call.
|
|
42
|
+
|
|
23
43
|
## The exclusion stack
|
|
24
44
|
|
|
25
45
|
**Default ignore preset** — a named group of default exclusions (VCS internals, dependencies, build outputs, caches, agent docs). Mounting is append-only and presets sit at the FRONT of the rule table: any named negation (`!vendor/`) in a gitignore layer or in your `exclude` option can walk an entry back out. There is no wholesale-replacement channel.
|
|
@@ -34,6 +54,10 @@ The vocabulary pathscope uses, in one place. Terms are sorted from the top down:
|
|
|
34
54
|
|
|
35
55
|
**Whole-tree pruning** — when a directory is excluded with no rescue, its entire subtree disappears from the scope, and its own `.gitignore` is never applied — its `!` rules cannot leak onto the rest of the walk.
|
|
36
56
|
|
|
57
|
+
**Dot entries** — names starting with a dot (`.env`, `.gitignore` itself). A walk-layer category, not a gitignore rule: excluded by default (`excludeDotEntries`, the ripgrep `hidden` semantics), and rescuable by the override whitelist. A point query reports the category as its own chain source (`'dot'`).
|
|
58
|
+
|
|
59
|
+
**Exemption** — the named-subtree registration of boundary markers (`boundaryStones.exempt`, e.g. `'embedded-toolkit/'`): naming a subtree neutralizes its OWN core/`.gitignore` marker hits, so it descends as a native subtree — the submodule-registration analogue. A neutralized hit still reports in the chain, as `enforced: false`. Registration, not rescue: deeper markers inside it are still markers, and config-home markers are never exemptible.
|
|
60
|
+
|
|
37
61
|
## Boundary markers
|
|
38
62
|
|
|
39
63
|
The API names this option `boundaryStones`; markers is the plain word for what they are.
|
|
@@ -46,7 +70,9 @@ The API names this option `boundaryStones`; markers is the plain word for what t
|
|
|
46
70
|
|
|
47
71
|
**`.gitignore` boundary marker** — the opt-in variant (`gitignoreProxy`) that treats a nested `.gitignore` as a boundary signal instead of more rules. Off by default: mainstream treats a nested `.gitignore` as rules, not territory.
|
|
48
72
|
|
|
49
|
-
**Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
|
|
73
|
+
**Marker hit** — the report that a marker's name exists in a directory (`stoneHit` in the API). A hit is either **enforced** (the cut executes) or report-only (`enforced: false` — the scanner alignment's report-not-cut: metadata, no cut). On the composable engine this rides the array form of `excludeDirectory` (the names of the markers that hit), because per-name decisions need to know which marker fired.
|
|
74
|
+
|
|
75
|
+
**Walk stone report** — the walk face's marker-hit report: `stoneHits` on the `walkScope` result, every hit the walk discovered as `{ stoneName, path, enforced }` — pure metadata, the file set is untouched. Only directories the walk visits report, so pruned subtrees and the area below a budget cut stay silent (see the walk stone report section in `docs/semantics.md`).
|
|
50
76
|
|
|
51
77
|
## Alignment
|
|
52
78
|
|
package/docs/semantics.md
CHANGED
|
@@ -19,14 +19,14 @@ The full-stack priority over one engine, strongest first:
|
|
|
19
19
|
|
|
20
20
|
## Presets
|
|
21
21
|
|
|
22
|
-
Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table:
|
|
22
|
+
Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table. A `dirs` entry with a leading slash is **scan-root-anchored** (plain gitignore anchoring): it matches only at the scan root itself (re-anchored accordingly when the scan root sits below a repo root), and the named-negation exit key un-excludes it like any other entry.
|
|
23
23
|
|
|
24
24
|
| Group | Covers |
|
|
25
25
|
| --- | --- |
|
|
26
26
|
| `vcs` | `.git/`, `.hg/`, `.svn/` |
|
|
27
27
|
| `deps` | `node_modules/`, `.pnpm/`, `vendor/` |
|
|
28
|
-
| `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage
|
|
29
|
-
| `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
|
|
28
|
+
| `build` | `dist/`, `build/`, `lib/`, `out/`, `coverage/`, `/target` (root-anchored — the cargo/maven build tree; nested same-named directories are untouched) |
|
|
29
|
+
| `caches` | `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `.venv/`, `venv/`, `.gradle/`, `.nox/`, `.cache/`, `.next/`, `.nuxt/`, `.turbo/`, `.vite/`, `.parcel-cache/`, `.svelte-kit/`, `.vscode-test/` |
|
|
30
30
|
| `agentDocs` | `AGENTS.md`, `CLAUDE.md` (files — agent self-loading instructions, not project content) |
|
|
31
31
|
|
|
32
32
|
## Boundary markers
|
|
@@ -49,6 +49,12 @@ Opt-in via `boundaryStones.gitignoreProxy`: treat a nested `.gitignore` as a bou
|
|
|
49
49
|
|
|
50
50
|
`boundaryStones.exempt` names subtrees whose own core/`.gitignore` marker hits are neutralized — the submodule-registration analogue (git does not descend into an unregistered embedded repository; naming a subtree is the walk-mode way to register it). Entries are gitignore-style patterns anchored at the scan root (e.g. `'embedded-toolkit/'`). A matched directory descends as a native subtree: its nested `.gitignore` files apply by the ordinary nesting rules (re-anchored, never leaking outside the subtree), while deeper markers inside it still cut — the exemption reaches only the named directory's own hits. Config homes are never exemptible.
|
|
51
51
|
|
|
52
|
+
### The walk stone report
|
|
53
|
+
|
|
54
|
+
`walkScope` results carry `stoneHits`: every marker hit the walk discovered, as `{ stoneName, path, enforced }` — the stone that hit, the scan-root-relative directory directly containing it, and whether the hit executed its cut under the active alignment face and exemption. Pure metadata: the report never changes the file set. On the default git face `enforced: true` names where truncations happened; under `alignment: 'scanner'` core-stone hits report `enforced: false` (report-not-cut — "this subtree is a nested repository"), and exemption-neutralized hits report `enforced: false` the same way (registration, not rescue). Config-home hits always report `enforced: true` — they are your own declarations and keep their verdict under every face. The scan root's own markers are not reported (the root is the universe boundary and never adjudicates against itself); only directories the walk visits as descent candidates appear. Sorted by path, then stone name.
|
|
55
|
+
|
|
56
|
+
The report's completeness is the walk's: only visited descent candidates are probed, so subtrees removed by the rule stack (preset, `exclude`, the dot category) and everything below a budget cut leave no hits — a silent absence is not negative evidence; check `diagnostics` for the budget case. The core `.git` marker matches both of git's own forms (a `.git` directory, or the `gitdir` pointer file a worktree or submodule carries), and `.gitmodules` registration is invisible to the walk — a registered submodule hits exactly like an embedded repository, with `boundaryStones.exempt` as the walk-mode registration for both.
|
|
57
|
+
|
|
52
58
|
## Scanner semantics
|
|
53
59
|
|
|
54
60
|
With `alignment: 'scanner'` (ripgrep-style):
|
|
@@ -64,10 +70,20 @@ With `alignment: 'scanner'` (ripgrep-style):
|
|
|
64
70
|
|
|
65
71
|
Presets are un-excludable by design: a named negation (`!vendor/`) in any gitignore layer or in your `exclude` option un-excludes a preset entry. There is no wholesale-replacement channel — `mountPresets` is append-only.
|
|
66
72
|
|
|
73
|
+
## Point queries (the read-only probe)
|
|
74
|
+
|
|
75
|
+
`explainScopePath(root, relPath, options?)` is the third way to resolve one scope request: instead of enumerating the set (`walkScope`) or asking git (`gitUniverse`), it answers a membership point query — **is this path excluded, and exactly which layer decided?** Read-only: no exclusion source is added, no matching behavior changes, `walkScope` output is untouched.
|
|
76
|
+
|
|
77
|
+
- **Consistency**: the probe replays the ancestor chain over a dedicated engine instance (the same construction inputs), adjudicating every ancestor directory exactly as the walk would — stones probed, gitignores folded only for descended directories. A corpus-wide equivalence gate pins probe verdicts against the same fixture expectations `walkScope` answers. `excluded` is the rule-space verdict — it equals "absent from a walkScope result" for paths on disk under an un-cut budget; the loud budget is a walk-chassis concern the probe never reflects, and for a nonexistent path `excluded: false` means "nothing in the rule space excludes it" (walkScope membership is undefined for paths that do not exist).
|
|
78
|
+
- **Structural answers**: an ancestor excluded with no directory-level rescue makes the answer structural — `excluded: true, structural: true`, the chain attributes to that ancestor, and the pruned subtree's `.gitignore` never participates. A directory-shaped query (trailing slash) cut at its own adjudication is structural the same way: the prune is the answer. For a structural answer the chain is exactly the excluded ancestor's adjudication record — adjudication does not continue below the prune, so the query path's own rule hits are absent by construction; what still matters below it (enforced stones, strict hits) surfaces in the explicit projection's blockers.
|
|
79
|
+
- **The hit chain**: the adjudication record, in full-stack priority order (stones → strict → override → combined table → dot); within the combined table, stream order (presets → cascade → policy rear seat) so the last table entry is the last-match-wins winner. The chain reports every layer that matched — an **included** path can carry hits (the preset hit, then the override that rescued it), and a stone entry with `enforced: false` is report-only (it did not produce the verdict; an exemption-neutralized hit reports this way too). Each entry carries its attribution — `presetName`, the gitignore layer anchor (`''` = the scan root's own layer, a relative directory without trailing slash (e.g. `sub`) = a nested layer, `inherited:..` = a layer above the root, one `..` per level) plus the rule text **as written** (re-anchoring stays internal), or the stone name with `enforced` (under `alignment: 'scanner'` the core stone is reported `enforced: false` — report-not-cut). The rule space is **repository-local**: git's global excludes (`core.excludesFile`) and `.git/info/exclude` never participate — `git check-ignore` may therefore flag paths the probe includes.
|
|
80
|
+
- **Explicit projection**: `explicit.pierceable` is false only when an enforced stone cut or a strict hit blocks the path — those two channels outrank even the override whitelist, and explicit naming is override-channel semantics. Everything else (presets, cascade, policy, dot) is pierceable. The projection is a mechanism, not a policy: what to do with a pierceable path (report, warn, refuse) is the consumer's call.
|
|
81
|
+
- **Input domain**: scan-root-relative POSIX paths; a leading `./` is stripped (`''`, `'.'`, `'./'` all name the scan root itself, which returns the boundary fact: `excluded: false`, empty chain); the trailing slash is the **operator** that selects directory-order adjudication — a slash-less query always adjudicates file-order, even for an existing directory. Nonexistent paths adjudicate hypothetically over the rule space — the status-query shape. Absolute paths, backslashes, `..` escapes, and empty inner segments are rejected as configuration errors (`PathscopeConfigError`); the `root` argument takes any form `path.resolve` accepts, exactly like walkScope. Each call is self-contained over a dedicated engine instance — calls are independent and safe to run in parallel; symlinks are not resolved (`followSymlinks` / `maxFiles` are walk-chassis options, accepted and ignored). The probe covers the walk face only; the ask-git face has no point query — git itself answers those questions. The inherited anchor's reach: the construction phase reads `.gitignore` files from the scan root up to the enclosing repository's root (or the disk root outside a repository), shallow first.
|
|
82
|
+
|
|
67
83
|
## Walk defaults
|
|
68
84
|
|
|
69
85
|
- Output: POSIX relative paths, sorted.
|
|
70
86
|
- `excludeDotEntries` (default `true`): rg `hidden` semantics — a walk-layer option, not a gitignore rule; `override` can rescue dot entries.
|
|
71
87
|
- `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before (rg `--no-ignore`).
|
|
72
88
|
- Symlinks are not resolved by default (git/ripgrep default).
|
|
73
|
-
- `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination.
|
|
89
|
+
- `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination. `explainScopePath` is the read-only third face over the same request: it adjudicates, it never enumerates.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@catheadowl/pathscope",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Cross-repo shared engine resolving the in-scope file set: walk, gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Cross-repo shared engine resolving the in-scope file set: walk or per-path point queries (excluded + why), gitignore cascade, mounted exclusion presets, loud budget, git universe, boundary stones — under a git-native alignment skeleton with conformance fixtures adjudicated by a git oracle.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -25,9 +25,11 @@
|
|
|
25
25
|
"scripts": {
|
|
26
26
|
"build": "tsc -p tsconfig.build.json && node scripts/build-cjs.mjs",
|
|
27
27
|
"typecheck": "tsc --noEmit",
|
|
28
|
+
"lint:face": "node scripts/published-face-lint.mjs",
|
|
28
29
|
"test": "node --test \"test/*.test.ts\"",
|
|
29
30
|
"oracle": "node scripts/git-oracle.mjs",
|
|
30
31
|
"oracle:fix": "node scripts/git-oracle.mjs --update",
|
|
32
|
+
"oracle:crate": "node scripts/ignore-crate-oracle.mjs",
|
|
31
33
|
"prepack": "pnpm run build && pnpm run test"
|
|
32
34
|
},
|
|
33
35
|
"dependencies": {
|