npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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; .gitignore cascades 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; under alignment: '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 — 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.
  • 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 throws PathscopeGitError. Nothing is silently re-scanned a different way.
  • ESM + CommonJS — dual build, Node.js >= 20.

Install

npm install @catheadowl/pathscope

Usage

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:

  • excluded is 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 path excluded: false means "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: false is 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 in explicit.blockers.
  • relPath is 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. root takes any form path.resolve accepts, native separators included, exactly like walkScope.
  • Out-of-domain inputs (.. escapes, absolute paths, backslashes, empty inner segments, a nonexistent scan root) throw PathscopeConfigError — 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; followSymlinks and maxFiles are 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' } | null

Files 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

Related

License

MIT