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

@any-nav/scan

v0.2.0

Published

Any-Nav scan core: the engine facade that walks a Markdown folder into a nav tree under the routes traversal semantics (exclusions, gitignore inheritance, a loud maxFiles budget, folder descriptions) with the walk delegated to @catheadowl/pathscope. Embed

Readme

@any-nav/scan

Walk any Markdown folder into a navigation tree.

@any-nav/scan is the lean scan engine behind Any-Nav: it reads a folder of Markdown files and produces a navigation tree — names, one-line descriptions, and file locators — ready for listings, indexes, and agent navigation surfaces. The walk's scope resolution — gitignore cascade, exclusion floors, the dot category, boundary stones — is delegated to @catheadowl/pathscope (one runtime dependency); everything Markdown-shaped — the tree, the budget, pruning, description chains — lives here. The full SDK (config, budget guard, rendering, query) lives in @any-nav/core, which composes and re-exports this package's full face.

Install

npm install @any-nav/scan

Usage

import { builtinDescriptionProvider, resolveScanOptions, scanSource } from '@any-nav/scan';

const output = await scanSource(
  'docs',                            // the folder to walk (absolute or relative)
  builtinDescriptionProvider,        // description chain; this is the default, shown for clarity
  resolveScanOptions({ maxFiles: 2000, respectGitignore: true }),
);

output.tree;        // NavNode tree — directories are nodes, files carry a NavItem
output.itemCount;   // number of Markdown items read
output.diagnostics; // loud notes (budget hit, no-description files, …) — never a silent cut

The knowledge model is one shape: NavItem { name, description, locator } (name defaults to the file stem; locator.path is POSIX-relative to the scan root). There is no second model — the SDK's view types build on it, never beside it.

Structure-only walks (lazy descriptions)

When a consumer renders a slice of the tree (a depth-0 listing shows only its own rows), reading every file up front is wasted work. scanStructure runs the identical walk — exclusions, gitignore, budget, pruning — with zero content reads; file nodes carry no NavItem until describe(paths) hydrates exactly the ones a view renders, in place:

import { resolveScanOptions, scanStructure } from '@any-nav/scan';

const structure = await scanStructure('docs', undefined, resolveScanOptions());
structure.tree;        // same shape a full scan produces; file items absent
structure.itemCount;   // identical to a full scan (the budget counts entries)
structure.diagnostics; // walk findings; per-file diagnostics ride describe()
const perFile = await structure.describe(new Set(['README.md', 'guides/README.md']));

Reads fetch a bounded head that provably covers the description chain's input (frontmatter plus the body-head window, extended adaptively when a head cannot prove stability) — extraction results are identical to a full read, at a fraction of the bytes.

Scan semantics

  • Additive exclusions — excludeDirs / excludeFiles append to an always-on built-in floor (e.g. AGENTS.md, CLAUDE.md, node_modules, dist, and — with the engine delegation — vendor and coverage); stating one never drops the defaults. Dot entries are skipped by default. Empty directories are pruned from the tree.
  • gitignore inheritance — respectGitignore (default on): traversal honors the .gitignore cascade, nested files and the chain above the scan root alike (git-native; the exit key for a floor entry is naming it in a .gitignore negation, e.g. !vendor/).
  • Registered subtrees — boundaryExempt: gitignore-style patterns anchored at the scan root (e.g. deepseek-harness/) naming subtrees whose own nested .git no longer cuts them from this view — git's submodule-registration face (an unregistered embedded repo is foreign territory; a registered one participates). Registration is not rescue: the subtree still passes every exclusion floor, and deeper embedded repositories inside it still cut. Default: none.
  • A loud budget — maxFiles (default 2000) caps markdown entries per source walk; hitting the cap fires diagnostics, never a silent truncation: folders whose descent was cut carry floor counts (countIncompletePaths on the output; views render ≥N with a per-row count-truncated-at-limit diagnostic) and later folders are absent. The budget counts tree entries (identical cut for full and structure walks).
  • Description source chain — per file, in priority order: frontmatter description:, else an explicit description: line in the document head, else the first substantive body line; none matching falls to a placeholder plus a no-description diagnostic (full scans emit one per file; structure walks emit them per hydrated file, so a lazy view warns about the rows it renders).
  • Folder descriptions — a directory describes itself via its standardized carriers in order: its package.json description, else its manifest.yml metadata.description, else the same extraction over its own README.md; an unreadable or invalid carrier fires a description-carrier-unreadable diagnostic and falls through.
  • Representative README locator — dir nodes carry markdown, the POSIX-relative path of the folder's representative README.md; present iff that README is a node in the tree (file nodes never carry it).
  • Read-only — scanning never modifies source files. The map is not the territory.

Boundaries this package keeps

  • One runtime dependency by ruling — @catheadowl/pathscope, the shared file-scope engine the walk delegates to; nothing else may join it.
  • ResolvedScanOptions is terminal: callers hand the scanner final values; resolveScanOptions is an additive default floor, not an obligation.
  • DescriptionProvider is a port — the built-in chain is the default; a custom provider (e.g. an LLM-backed one) plugs into the same interface.
  • API shell policy: the public surface exports what real consumption forms need — someone importing today, a local fork being the unwired equivalent — and never speculative breadth; each future export passes a light ruling first. The former traversal-boundary family (GitignoreRule, readInheritedGitignoreRules, readGitignoreRules, isGitignored) was removed with the in-package engine it belonged to: it had no importing consumer, and reading boundary rules without a scan is engine territory — the right home is a future @catheadowl/pathscope API, not this package.

License

MIT