@catheadowl/pathscope
v0.3.0
Published
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 fi
Readme
pathscope
Resolve the set of files a tool should see in a repository — git-native by default.
pathscope answers one question three ways: which files are in scope? Walk the filesystem with a gitignore cascade and default ignore presets (walkScope), ask git directly instead of walking (gitUniverse), or point-query one path — is it excluded, and exactly which layer decided (explainScopePath)? You can also compose the same exclusion engine into your own traversal (createExclusionEngine). It also locates the nearest config file on the way up without parsing it (locateNearest).
Features
- 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;
.gitignorecascades with last-match-wins, symlinks are not followed, hidden (dot) entries are skipped by default. - 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; underalignment: 'scanner'it is report-not-cut metadata. The file set is untouched by the report. - 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. - Per-path point queries —
explainScopePathanswers "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. - Loud budget — when a scan would exceed the file budget, traversal is cut and a diagnostic is emitted. Never a silent cut.
- Fail-loud everywhere — malformed configuration throws
PathscopeConfigError; missing git or a failed git command throwsPathscopeGitError. Nothing is silently re-scanned a different way. - ESM + CommonJS — dual build, Node.js >= 20.
Install
npm install @catheadowl/pathscopeUsage
import { walkScope } from '@catheadowl/pathscope';
// Default stack: gitignore cascade + vcs/deps/build presets + dot entries
// excluded + loud budget (2000).
const { files, diagnostics, stoneHits } = await walkScope('/repo');
console.log(files);
//=> ['package.json', 'src/engine.ts', 'src/paths.ts', 'test/engine.test.ts']
console.log(diagnostics);
//=> [] — non-empty means the budget cut the scan (code: 'budget-exceeded')
console.log(stoneHits);
//=> [{ stoneName: '.git', path: 'embedded-toolkit', enforced: true }]
// — every stone hit the walk discovered: which subtrees are independent
// repositories (or declared sub-domains) and where. `enforced: true` on the
// default git face names where the truncation happened; under
// alignment: 'scanner' the core stone reports enforced: false and the
// walk descends. Pure metadata — the file set never changes because of it.All output paths are POSIX-style relative to the scanned root, sorted.
// Mount more presets, add your own ignore rules, and rescue paths with
// the override whitelist (final say — it outranks presets, gitignore
// rules, and the dot category).
const { files } = await walkScope('/repo', {
mountPresets: ['vcs', 'deps', 'build', 'caches'],
exclude: ['sandbox/', '*.snapshot.md'],
override: ['vendor/generated/api.md'],
});Ask one path: excluded, and why
explainScopePath is the read-only probe over the same scope request — the diagnostic face for "why is this file not in scope":
import { explainScopePath } from '@catheadowl/pathscope';
const answer = await explainScopePath('/repo', 'node_modules/pkg/index.js');
// {
// excluded: true,
// structural: true, // a directory-level prune carries the subtree
// hitChain: [
// { source: 'preset', presetName: 'deps', ruleText: 'node_modules/',
// path: 'node_modules' }, // the hit adjudicated the ANCESTOR
// ],
// explicit: { pierceable: true, blockers: [] }, // naming it would pierce
// }
// Same scope request as a walk — pass the SAME options you pass walkScope:
const same = await explainScopePath('/repo', 'sandbox/x.snapshot.md', {
mountPresets: ['vcs', 'deps', 'build', 'caches'],
exclude: ['sandbox/'],
});Every matching layer reports with its attribution — which preset, which .gitignore layer (anchor + the line as written), which stone (with the scanner face's report-not-cut fact), strict/override/policy patterns. Nonexistent paths adjudicate hypothetically (the status-query shape). Explicit piercing policy (report / warn / refuse) stays with you — the engine supplies the facts.
Fine print worth knowing before your first call:
excludedis the rule-space verdict. For a path on disk under an un-cut budget it equals "absent from a walkScope result"; the two caveats are by design — the loud budget is a walk-chassis concern this API never reflects (a budget-cut walk omits files the probe rightly reports as included), and for a nonexistent pathexcluded: falsemeans "nothing in the rule space excludes it" (walkScope membership is undefined for paths that do not exist — your status branch owns existence separately).- The chain is an adjudication record, not just the verdict's cause — an included path can carry hits (the preset hit, then the override that rescued it), and a stone entry with
enforced: falseis report-only metadata (the scanner face's report-not-cut). 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 — what still matters below it (enforced stones, strict hits) surfaces inexplicit.blockers. relPathis scan-root-relative POSIX; a leading./is stripped ('','.','./'all name the scan root itself); the trailing slash is the operator that selects directory-order adjudication, not a statement about disk — a slash-less query always adjudicates file-order, even for an existing directory.roottakes any formpath.resolveaccepts, native separators included, exactly like walkScope.- Out-of-domain inputs (
..escapes, absolute paths, backslashes, empty inner segments, a nonexistent scan root) throwPathscopeConfigError— same fail-loud family as every other malformed input. - Each call is self-contained over a dedicated engine instance: calls are independent and safe to run in parallel — many-paths workloads have no batch face yet (deferred), so run concurrent queries concurrently. Symlinks are not resolved (like the walk default): a symlinked final segment adjudicates by its own name, intermediate reads follow the filesystem as any read does;
followSymlinksandmaxFilesare walk-chassis options — accepted and ignored here. The probe covers the walk face only; the ask-git face has no point query — git itself answers those questions.
Ask git instead of walking
import { gitUniverse } from '@catheadowl/pathscope';
// Tracked + untracked-but-not-ignored files, straight from git. No
// filesystem walk — git is the truth, the exclusion stack does not
// participate (a tracked node_modules belongs in the result).
const { files, repoRoot } = await gitUniverse('/repo');
// Staged changes (A/C/M/R vs HEAD) with an opt-in post-filter.
const publishable = await gitUniverse('/repo', {
variant: 'staged',
filter: { mountPresets: ['deps', 'caches'] },
});Compose the exclusion engine into your own traversal
Watchers, incremental snapshots, and virtual filesystems cannot use the built-in walker. createExclusionEngine gives them the same exclusion stack + gitignore cascade as a standalone engine:
import { createExclusionEngine } from '@catheadowl/pathscope';
const engine = await createExclusionEngine('/repo/src');
for (const entry of await myReadDir('/repo/src')) {
if (entry.isDirectory) {
const stoneHit = await probeStones(engine.stoneNames, entry.path); // your own existence probes
if (engine.excludeDirectory(entry.name, entry.path, stoneHit)) continue; // prune the subtree
engine.foldGitignore(entry.path, await myReadGitignore(entry.path)); // fold on descent
await descend(entry.path);
} else if (engine.admitFile(relativePosix(entry.path))) {
keep(entry.path);
}
}The file budget belongs to walkScope — the engine has none.
Locate the nearest config file
import { locateNearest } from '@catheadowl/pathscope';
const home = locateNearest(['toolkit.toml', '.specs/collect.config.toml'], {
cwd: '/repo/src',
stopAt: '/repo', // inclusive — beyond it, a config file belongs to a different project
});
//=> { name: 'toolkit.toml', path: '/repo/toolkit.toml' } | nullFiles are only located, never read or parsed — TOML/YAML handling stays with you.
API
| Export | One-line |
| --- | --- |
| walkScope(root, options?) | Walk + exclude → { files, diagnostics, stoneHits } |
| explainScopePath(root, relPath, options?) | Point query → { excluded, structural, hitChain, explicit } |
| gitUniverse(root, options?) | Ask git → { files, repoRoot, diagnostics } |
| locateNearest(names, options?) | Nearest config file, no parsing |
| createExclusionEngine(root, options?, io?) | The exclusion engine for your own traversal |
| nodeExclusionIO | The node-filesystem default ExclusionIO for the engine |
| clearUniverseCache() | Reset gitUniverse's repo-root memoization (test seam) |
| PRESETS / DEFAULT_MOUNTED_PRESETS | Preset contents |
| PathscopeConfigError / PathscopeGitError | Fail-loud error classes |
Full signatures, option tables, and return shapes live in the .d.ts files shipped in this package — every export carries complete doc comments (the same comments your editor renders as IntelliSense).
Documentation
- docs/glossary.md — the domain vocabulary
- docs/semantics.md — presets, boundary markers, precedence order
Related
- ignore — the gitignore kernel pathscope rides
- fast-glob / globby — pattern-matching walkers
- find-up — the config-discovery kernel
License
MIT
