@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
Maintainers
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/scanUsage
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 cutThe 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/excludeFilesappend to an always-on built-in floor (e.g.AGENTS.md,CLAUDE.md,node_modules,dist, and — with the engine delegation —vendorandcoverage); 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.gitignorecascade, nested files and the chain above the scan root alike (git-native; the exit key for a floor entry is naming it in a.gitignorenegation, e.g.!vendor/). - Registered subtrees —
boundaryExempt: gitignore-style patterns anchored at the scan root (e.g.deepseek-harness/) naming subtrees whose own nested.gitno 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 (countIncompletePathson the output; views render ≥N with a per-rowcount-truncated-at-limitdiagnostic) 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 explicitdescription:line in the document head, else the first substantive body line; none matching falls to a placeholder plus ano-descriptiondiagnostic (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.jsondescription, else itsmanifest.ymlmetadata.description, else the same extraction over its ownREADME.md; an unreadable or invalid carrier fires adescription-carrier-unreadablediagnostic and falls through. - Representative README locator — dir nodes carry
markdown, the POSIX-relative path of the folder's representativeREADME.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. ResolvedScanOptionsis terminal: callers hand the scanner final values;resolveScanOptionsis an additive default floor, not an obligation.DescriptionProvideris 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/pathscopeAPI, not this package.
License
MIT
