@any-nav/scan 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.0 — 2026-10-21
+
+First registry release: the zero-dependency scan engine, split out of
+`@any-nav/core` (2026-10-19) as the lean consumption face for embedders.
+
+- `scanSource()` walks a Markdown folder into a `NavNode` tree under the
+  routes traversal semantics: additive exclusion lists over an always-on
+  built-in floor, `.gitignore` inheritance, a loud `maxFiles` budget
+  (diagnostic, never a silent cut), empty-directory pruning, and folder
+  descriptions via the `_category_` sidecar → README chain.
+- Budget cuts are disclosed as lower bounds: folders cut by the cap carry
+  floor counts (`countIncompletePaths` on the output; views render ≥N
+  with a per-row `count-truncated-at-limit` diagnostic) — surviving rows
+  never overstate completeness.
+- `scanStructure()` runs the identical walk with zero content reads: file
+  nodes carry no `NavItem` until `describe(paths)` hydrates exactly the
+  rendered rows in place; bounded-head reads keep extraction identical to
+  a full read.
+- Walk throughput: overlapped directory reads and memoized `.gitignore`
+  matching.
+- Description extraction: frontmatter `description:` → document-head
+  `description:` line → first substantive body line → placeholder +
+  `no-description` diagnostic.
+- Terminal `ResolvedScanOptions` with `resolveScanOptions` as the additive
+  default floor; `builtinDescriptionProvider` as the default
+  `DescriptionProvider` port implementation.
+- The knowledge model: `NavItem { name, description, locator }` plus
+  `NavNode`, `ScanConfig`, and audience-tagged `ScanDiagnostic`s.
+- Zero npm dependencies — the isolated install closure is this package alone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatheadOwl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @any-nav/scan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Walk any Markdown folder into a navigation tree. Zero npm dependencies.
+
+`@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. This package exists so embedders who only need the engine carry
+nothing else: no TOML parser, no search index, no SDK. The full SDK (config,
+budget guard, rendering, query) lives in `@any-nav/core`, which composes and
+re-exports this package's full face.
+
+## Install
+
+```sh
+npm install @any-nav/scan
+```
+
+## Usage
+
+```ts
+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:
+
+```ts
+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`); 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 `.gitignore` rules from the scan root down.
+- **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
+  `_category_.yml` / `.yaml` / `.json` sidecar's `description` key, else via
+  the same extraction over its own `README.md`.
+- **Read-only** — scanning never modifies source files. The map is not the
+  territory.
+
+## Boundaries this package keeps
+
+- Zero runtime dependencies beyond Node builtins — the install closure is
+  this package alone.
+- `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.
+
+## License
+
+MIT

package/dist/description.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One-line description extraction, ported verbatim from the routes module
+ * (dsh-plugin-dev/extras/modules/routes/src/description.ts, ADR-0010:
+ * absorption is porting — every boundary handling here is tuition already
+ * paid on production corpora; do not "simplify" it).
+ *
+ * Priority: ① frontmatter `description:`, ② an explicit `description:` line
+ * in the document head, ③ the first substantive body line as a fallback.
+ * Returns null when none match.
+ */
+/** Body-line description lookup only trusts the document head, so a `description:` inside a code block or deep in the prose cannot hijack the route. Exported for the scan-side head-read sufficiency check (scan.ts), which must stay in lockstep with this window. */
+export declare const BODY_HEAD_LINE_LIMIT = 15;
+/**
+ * Extracts a one-line route description from Markdown, in priority order:
+ * ① frontmatter `description:`, ② an explicit `description:` line in the document
+ * head, ③ the first substantive body line as a fallback. Returns `null` when none match.
+ */
+export declare function extractDescription(content: string): string | null;
+/**
+ * Directory sidecar read (2026-10-07): `_category_.yml/.yaml/.json` carry a
+ * folder's description so release-face READMEs stay untouched. YAML reuses
+ * the frontmatter ① key reader — the sidecar is frontmatter without the
+ * document (an indented `link.description:` therefore reads too, covering
+ * Docusaurus-shaped files for free); JSON parses properly and accepts the
+ * top-level `description` or the Docusaurus `link.description` shape.
+ * `{ description: null }` means the file carries no description key.
+ */
+export type SidecarRead = {
+    description: string | null;
+} | {
+    error: string;
+};
+export declare function extractSidecarDescription(fileName: string, content: string): SidecarRead;

package/dist/description.js

@@ -0,0 +1,273 @@
+/**
+ * One-line description extraction, ported verbatim from the routes module
+ * (dsh-plugin-dev/extras/modules/routes/src/description.ts, ADR-0010:
+ * absorption is porting — every boundary handling here is tuition already
+ * paid on production corpora; do not "simplify" it).
+ *
+ * Priority: ① frontmatter `description:`, ② an explicit `description:` line
+ * in the document head, ③ the first substantive body line as a fallback.
+ * Returns null when none match.
+ */
+/** Body-line description lookup only trusts the document head, so a `description:` inside a code block or deep in the prose cannot hijack the route. Exported for the scan-side head-read sufficiency check (scan.ts), which must stay in lockstep with this window. */
+export const BODY_HEAD_LINE_LIMIT = 15;
+/** Minimum code-point length for a body line to count as a substantive first sentence (fallback ③). Word count is avoided because CJK text has no space tokenization. */
+const MIN_SUBSTANTIVE_LENGTH = 20;
+/** Approximate cap (code points) for a fallback description; longer lines are cut at the last sentence boundary inside the cap. */
+const MAX_DESCRIPTION_CHARS = 120;
+const SENTENCE_ENDERS = ['.', '。', '!', '！', '?', '？', ';', '；'];
+/** Link or image, tolerating one level of nesting so a badge (`[![alt](img)](href)`) counts as a single token. */
+const LINK_OR_IMAGE = /!?\[(?:[^[\]]|\[[^\]]*\])*\]\([^)]*\)/gu;
+/**
+ * Extracts a one-line route description from Markdown, in priority order:
+ * ① frontmatter `description:`, ② an explicit `description:` line in the document
+ * head, ③ the first substantive body line as a fallback. Returns `null` when none match.
+ */
+export function extractDescription(content) {
+    const frontmatter = parseYamlLikeFrontmatter(content);
+    const frontmatterDescription = frontmatter
+        ? readDescriptionKey(frontmatter.split(/\r?\n/u))
+        : null;
+    if (frontmatterDescription)
+        return frontmatterDescription;
+    const body = frontmatter ? contentAfterFrontmatter(content) : content;
+    const openBodyLines = stripHtmlComments(stripCodeFences(body.split(/\r?\n/u))).slice(0, BODY_HEAD_LINE_LIMIT);
+    const bodyDescription = readDescriptionKey(openBodyLines);
+    if (bodyDescription)
+        return bodyDescription;
+    return firstSubstantiveLine(openBodyLines);
+}
+/** Fallback ③: the first body line that is prose (not Markdown structure) and long enough, cleaned of inline Markdown and capped. */
+function firstSubstantiveLine(lines) {
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (isStructuralLine(line) || isSetextTitle(lines, index))
+            continue;
+        const cleaned = cleanInlineMarkdown(line);
+        if (codePointLength(cleaned) < MIN_SUBSTANTIVE_LENGTH)
+            continue;
+        return truncateDescription(cleaned);
+    }
+    return null;
+}
+/** A setext heading's title line sits directly above its `===`/`---` underline; skip the title, not just the underline. */
+function isSetextTitle(lines, index) {
+    if (index + 1 >= lines.length)
+        return false;
+    const trimmed = lines[index + 1].trim();
+    return trimmed.length > 0 && /^(={3,}|-{3,})\s*$/u.test(trimmed);
+}
+/** Structural Markdown lines never carry a description; they are skipped before the length test. */
+function isStructuralLine(line) {
+    const text = line.trim();
+    if (text.length === 0)
+        return true;
+    if (/^#{1,6}(\s|$)/u.test(text))
+        return true; // ATX heading
+    if (/^(={3,}|-{3,}|\*{3,}|_{3,})$/u.test(text))
+        return true; // setext underline / horizontal rule
+    if (/^>/u.test(text))
+        return true;
+    if (/^[-+*](\s|$)/u.test(text))
+        return true; // unordered list
+    if (/^\d{1,3}\.\s/u.test(text))
+        return true; // ordered list
+    // table row / language-switch ("English | [中文]"); inline code spans are
+    // masked first — marked-up code is never table structure (ADR-0010 U8)
+    const outsideCodeSpans = text.replace(/`[^`]*`/gu, '');
+    if (outsideCodeSpans.startsWith('|') || /\s\|\s/u.test(outsideCodeSpans))
+        return true;
+    if (/^</u.test(text))
+        return true;
+    if (isLinkOnlyLine(text))
+        return true; // badge row / nav chrome
+    return false;
+}
+/** A line whose visible text is only links/images (badges, nav) carries no prose description. */
+function isLinkOnlyLine(text) {
+    return text.length > 0 && text.replace(LINK_OR_IMAGE, '').trim().length === 0;
+}
+/** Light inline-Markdown cleanup so a fallback line reads as plain prose. */
+function cleanInlineMarkdown(line) {
+    return line
+        .trim()
+        .replace(/!\[([^\]]*)\]\([^)]*\)/gu, '$1')
+        .replace(/\[([^\]]*)\]\([^)]*\)/gu, '$1')
+        .replace(/`([^`]*)`/gu, '$1')
+        .replace(/\*\*([^*]+)\*\*/gu, '$1')
+        .replace(/__([^_]+)__/gu, '$1')
+        .replace(/\s+/g, ' ')
+        .replace(/[：:]\s*$/u, '')
+        .trim();
+}
+/** Cut long fallback text at the last sentence boundary inside the cap; hard-cut (with a trailing `...`) when no boundary is deep enough. */
+function truncateDescription(text) {
+    if (codePointLength(text) <= MAX_DESCRIPTION_CHARS)
+        return text;
+    const head = [...text].slice(0, MAX_DESCRIPTION_CHARS).join('');
+    const boundary = lastSentenceBoundary(head);
+    if (boundary >= 0) {
+        const cut = head.slice(0, boundary + 1).trimEnd();
+        if (codePointLength(cut) >= MIN_SUBSTANTIVE_LENGTH)
+            return cut;
+    }
+    return head.trimEnd() + '...';
+}
+/** Last sentence ender inside `text`, skipping abbreviation dots (`ctx.`, `e.g.`). */
+function lastSentenceBoundary(text) {
+    for (let index = text.length - 1; index >= 0; index--) {
+        const char = text[index];
+        if (char === '.') {
+            if (isAbbreviationDot(text, index))
+                continue;
+            return index;
+        }
+        if (SENTENCE_ENDERS.includes(char))
+            return index;
+    }
+    return -1;
+}
+function isAbbreviationDot(text, index) {
+    let letters = 0;
+    for (let prev = index - 1; prev >= 0 && prev >= index - 3; prev--) {
+        if (/[a-z]/u.test(text[prev]))
+            letters++;
+        else
+            break;
+    }
+    if (letters === 0)
+        return false;
+    const next = index + 1 < text.length ? text[index + 1] : '';
+    return /[a-z,;):]/u.test(next);
+}
+function codePointLength(text) {
+    return [...text].length;
+}
+/** Drops fenced code blocks (```…``` and ~~~…~~~) so tool/program examples cannot leak `description:` matches. */
+function stripCodeFences(lines) {
+    const openLines = [];
+    let insideFence = false;
+    for (const line of lines) {
+        if (isFenceLine(line)) {
+            insideFence = !insideFence;
+            continue;
+        }
+        if (!insideFence)
+            openLines.push(line);
+    }
+    return openLines;
+}
+function isFenceLine(line) {
+    return /^\s*(`{3,}|~{3,})/u.test(line);
+}
+/** Drops HTML comments (`<!--`…`-->`, possibly multi-line) so generated/boilerplate comment text cannot become the description. */
+function stripHtmlComments(lines) {
+    const openLines = [];
+    let insideComment = false;
+    for (const line of lines) {
+        let rest = line;
+        let openPart = '';
+        while (rest.length > 0) {
+            if (!insideComment) {
+                const start = rest.indexOf('<!--');
+                if (start === -1) {
+                    openPart += rest;
+                    break;
+                }
+                openPart += rest.slice(0, start);
+                rest = rest.slice(start + 4);
+                insideComment = true;
+            }
+            else {
+                const end = rest.indexOf('-->');
+                if (end === -1) {
+                    rest = '';
+                    break;
+                }
+                rest = rest.slice(end + 3);
+                insideComment = false;
+            }
+        }
+        openLines.push(openPart);
+    }
+    return openLines;
+}
+export function extractSidecarDescription(fileName, content) {
+    if (fileName.toLowerCase().endsWith('.json')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            return { error: `invalid JSON: ${err.message}` };
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return { error: 'sidecar JSON must be an object' };
+        }
+        const obj = parsed;
+        const fromKey = (value) => typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+        const top = fromKey(obj.description);
+        if (top !== null)
+            return { description: top };
+        const link = typeof obj.link === 'object' && obj.link !== null && !Array.isArray(obj.link)
+            ? obj.link
+            : undefined;
+        const nested = link === undefined ? null : fromKey(link.description);
+        return { description: nested };
+    }
+    return { description: readDescriptionKey(content.split(/\r?\n/u)) };
+}
+function parseYamlLikeFrontmatter(content) {
+    const lines = content.split(/\r?\n/u);
+    if (lines[0]?.trim() !== '---')
+        return null;
+    const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (endIndex === -1)
+        return null;
+    return lines.slice(1, endIndex).join('\n');
+}
+function contentAfterFrontmatter(content) {
+    const lines = content.split(/\r?\n/u);
+    const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    return endIndex === -1 ? content : lines.slice(endIndex + 1).join('\n');
+}
+function readDescriptionKey(lines) {
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const match = line.match(/^\s*(description|decription)\s*:\s*(.*)$/iu);
+        if (!match)
+            continue;
+        const inline = stripYamlString(match[2].trim());
+        if (inline)
+            return inline;
+        const block = readIndentedBlock(lines, index + 1);
+        if (block)
+            return block;
+    }
+    return null;
+}
+function readIndentedBlock(lines, start) {
+    const collected = [];
+    for (let index = start; index < lines.length; index++) {
+        const line = lines[index];
+        if (line.trim().length === 0) {
+            if (collected.length > 0)
+                break;
+            continue;
+        }
+        if (!/^\s+/.test(line))
+            break;
+        collected.push(line.trim());
+    }
+    return collected.length > 0 ? collected.join(' ') : null;
+}
+function stripYamlString(value) {
+    const stripped = value
+        .replace(/^\|[+-]?$/u, '')
+        .replace(/^>[+-]?$/u, '')
+        .trim();
+    if (!stripped)
+        return null;
+    const quoted = stripped.match(/^(['"])(.*)\1$/u);
+    return (quoted ? quoted[2] : stripped).trim() || null;
+}
+//# sourceMappingURL=description.js.map

package/dist/description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"description.js","sourceRoot":"","sources":["../src/description.ts"],"names":[],"mappings":"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"}

package/dist/gitignore.d.ts

@@ -0,0 +1,9 @@
+export interface GitignoreRule {
+    baseDir: string;
+    pattern: string;
+    negated: boolean;
+    directoryOnly: boolean;
+}
+export declare function readInheritedGitignoreRules(root: string, scanRoot: string): Promise<GitignoreRule[]>;
+export declare function readGitignoreRules(dir: string): Promise<GitignoreRule[]>;
+export declare function isGitignored(filePath: string, isDirectory: boolean, rules: readonly GitignoreRule[]): boolean;

package/dist/gitignore.js

@@ -0,0 +1,128 @@
+/**
+ * gitignore-aware traversal support, ported verbatim from the routes module
+ * (dsh-plugin-dev/extras/modules/routes/src/gitignore.ts, ADR-0010: port,
+ * don't rewrite). Known subset boundary (routes-documented): `!` re-includes
+ * inside one file are honored; cross-file re-include of an ignored path is
+ * not — revisit via a port if real corpora hit it (ADR-0010 reversal).
+ */
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+export async function readInheritedGitignoreRules(root, scanRoot) {
+    const rootPath = resolve(root);
+    const scanRootPath = resolve(scanRoot);
+    const relativeScanRoot = normalizeSlash(relative(rootPath, scanRootPath));
+    const segments = relativeScanRoot && !relativeScanRoot.startsWith('..')
+        ? relativeScanRoot.split('/').filter(Boolean)
+        : [];
+    const dirs = [rootPath];
+    for (let index = 0; index < segments.length; index += 1) {
+        dirs.push(join(rootPath, ...segments.slice(0, index + 1)));
+    }
+    const rules = await Promise.all(dirs.map((dir) => readGitignoreRules(dir)));
+    return rules.flat();
+}
+export async function readGitignoreRules(dir) {
+    let content;
+    try {
+        content = await readFile(join(dir, '.gitignore'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return content
+        .split(/\r?\n/u)
+        .map((line) => parseGitignoreLine(dir, line))
+        .filter((rule) => rule !== null);
+}
+export function isGitignored(filePath, isDirectory, rules) {
+    let ignored = false;
+    // Perf (2026-10-20, semantics identical): one relative() per distinct
+    // baseDir per call — a typical tree carries many rules from the same
+    // ancestor .gitignore, and the path result is rule-invariant.
+    const relativeByBaseDir = new Map();
+    for (const rule of rules) {
+        if (rule.directoryOnly && !isDirectory)
+            continue;
+        if (!matchesRule(filePath, rule, relativeByBaseDir))
+            continue;
+        ignored = !rule.negated;
+    }
+    return ignored;
+}
+function parseGitignoreLine(baseDir, rawLine) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#'))
+        return null;
+    let negated = false;
+    if (line.startsWith('!')) {
+        negated = true;
+        line = line.slice(1).trim();
+    }
+    if (!line)
+        return null;
+    const directoryOnly = line.endsWith('/');
+    line = line.replace(/^\/+/u, '').replace(/\/+$/u, '');
+    if (!line)
+        return null;
+    return {
+        baseDir,
+        pattern: normalizeSlash(line),
+        negated,
+        directoryOnly,
+    };
+}
+function matchesRule(filePath, rule, relativeByBaseDir) {
+    let relativePath = relativeByBaseDir.get(rule.baseDir);
+    if (relativePath === undefined) {
+        relativePath = normalizeSlash(relative(rule.baseDir, filePath));
+        relativeByBaseDir.set(rule.baseDir, relativePath);
+    }
+    if (!relativePath || relativePath.startsWith('..'))
+        return false;
+    if (!rule.pattern.includes('/')) {
+        return relativePath.split('/').some((part) => matchesGlob(part, rule.pattern));
+    }
+    return matchesGlob(relativePath, rule.pattern);
+}
+/** Compiled-glob memo (perf 2026-10-20, semantics identical): the regex
+ * depends only on the pattern, and a scan checks the same handful of
+ * patterns once per entry — compiling per check was ~70% of large-tree
+ * scan CPU. Patterns are few and bounded by the corpus's .gitignore lines. */
+const globRegexCache = new Map();
+function matchesGlob(value, pattern) {
+    let regex = globRegexCache.get(pattern);
+    if (regex === undefined) {
+        regex = new RegExp(`^${globToRegex(pattern)}$`, 'u');
+        globRegexCache.set(pattern, regex);
+    }
+    return regex.test(value);
+}
+function globToRegex(pattern) {
+    let regex = '';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const next = pattern[index + 1];
+        if (char === '*' && next === '*') {
+            regex += '.*';
+            index += 1;
+            continue;
+        }
+        if (char === '*') {
+            regex += '[^/]*';
+            continue;
+        }
+        if (char === '?') {
+            regex += '[^/]';
+            continue;
+        }
+        regex += escapeRegex(char);
+    }
+    return regex;
+}
+function escapeRegex(value) {
+    return value.replace(/[|\\{}()[\]^$+*?.]/gu, '\\$&');
+}
+function normalizeSlash(value) {
+    return value.replace(/\\/gu, '/');
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../src/gitignore.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @any-nav/scan public API — the lean engine face.
+ *
+ * Boundary rules this surface must preserve:
+ *   1. zero runtime dependencies beyond node builtins — embedders install
+ *      nothing else (this package exists so they never carry the SDK's
+ *      smol-toml / fast-bm25);
+ *   2. read-only over the filesystem — scanning never modifies sources
+ *      (map is not territory);
+ *   3. terminal options: ResolvedScanOptions is what it says — callers
+ *      hand the scanner final values; the additive default floor is a
+ *      convenience (resolveScanOptions), not an obligation.
+ */
+export type { DiagnosticAudience, NavItem, NavLocator, NavLocatorKind, NavNode, ScanConfig, ScanDiagnostic, } from './types.ts';
+export type { DescriptionProvider, ResolvedScanOptions, ScanOutput, ScannedFile, StructureScanOutput, } from './scan.ts';
+export { builtinDescriptionProvider, DEFAULT_EXCLUDE_DIRS, DEFAULT_EXCLUDE_FILES, DIR_SIDECAR_NAMES, isDirSidecarName, isExcludedFileName, resolveScanOptions, scanSource, scanStructure, } from './scan.ts';
+export { extractDescription } from './description.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { builtinDescriptionProvider, DEFAULT_EXCLUDE_DIRS, DEFAULT_EXCLUDE_FILES, DIR_SIDECAR_NAMES, isDirSidecarName, isExcludedFileName, resolveScanOptions, scanSource, scanStructure, } from './scan.js';
+export { extractDescription } from './description.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}