@any-nav/scan 0.0.0-stage → 0.2.0

package/dist/engine-mapping.d.ts

@@ -0,0 +1,48 @@
+import type { ScanConfig } from './types.ts';
+/**
+ * Agent-instruction files harnesses load on their own; they carry no
+ * navigation value (the agent already has them) so they never appear in
+ * navigation (routes DEFAULT_EXCLUDE_FILES, ported).
+ */
+export declare const DEFAULT_EXCLUDE_FILES: readonly string[];
+/** routes DEFAULT_EXCLUDE_DIRS, ported verbatim. Always on (the safety
+ * floor); user excludeDirs entries append to it, never replace it — a
+ * generate-era 'any-nav' entry was retired with `list --write` (the
+ * materialization target is now any file the caller names). */
+export declare const DEFAULT_EXCLUDE_DIRS: readonly string[];
+export interface ResolvedScanOptions {
+    excludeDirs: readonly string[];
+    excludeFiles: readonly string[];
+    excludeDotEntries: boolean;
+    respectGitignore: boolean;
+    /**
+     * Named-subtree core-stone exemptions, passed verbatim to the
+     * engine's `boundaryStones.exempt`: gitignore-style patterns anchored at
+     * the scan root. Optional — absent means no exemptions (every embedded
+     * repo stays foreign territory, exactly as before the key existed); the
+     * field stays optional so pre-existing terminal callers keep compiling.
+     */
+    boundaryExempt?: readonly string[];
+    maxFiles: number;
+}
+export declare function resolveScanOptions(config?: ScanConfig): ResolvedScanOptions;
+/** One trie level over the engine's in-scope set: files sit at their direct
+ * parent, directory segments carry the levels beneath them. Only levels with
+ * in-scope content exist — an empty directory (or one whose content is all
+ * out of scope) never enters the trie, which is the empty-directory pruning
+ * the old walk computed by hand. */
+export interface ScopeLevel {
+    files: Set<string>;
+    dirs: Map<string, ScopeLevel>;
+}
+/**
+ * The one engine query — "which files are in scope". Unbounded on purpose: the
+ * budget's unit is a TREE ENTRY (a Markdown file surviving the consumer
+ * filters), so the engine's raw-file budget never fires here and the
+ * replay below owns the fact-safe cut, its ordering, and its diagnostics.
+ * (Engine diagnostics beyond the budget do not exist in 0.1.0.)
+ * boundaryExempt rides boundaryStones.exempt verbatim: naming a
+ * subtree registers its participation — its own .git no longer cuts it,
+ * while deeper embedded repos inside it and un-named siblings keep the cut.
+ */
+export declare function scopeLevels(root: string, opts: ResolvedScanOptions): Promise<ScopeLevel>;

package/dist/engine-mapping.js

@@ -0,0 +1,127 @@
+/**
+ * Engine mapping face — everything crossing the boundary into
+ * @catheadowl/pathscope (the facade face): the
+ * resolved-options face (the additive default floor), the preset mounts, the
+ * policy-channel patterns, the walkScope query itself, and the scope trie the
+ * replay descends. "Which files are in scope" is the engine's question; the
+ * Markdown layer that turns the scope into a tree lives in tree-replay.ts.
+ */
+import { walkScope } from '@catheadowl/pathscope';
+/**
+ * Agent-instruction files harnesses load on their own; they carry no
+ * navigation value (the agent already has them) so they never appear in
+ * navigation (routes DEFAULT_EXCLUDE_FILES, ported).
+ */
+export const DEFAULT_EXCLUDE_FILES = ['AGENTS.md', 'CLAUDE.md'];
+/** routes DEFAULT_EXCLUDE_DIRS, ported verbatim. Always on (the safety
+ * floor); user excludeDirs entries append to it, never replace it — a
+ * generate-era 'any-nav' entry was retired with `list --write` (the
+ * materialization target is now any file the caller names). */
+export const DEFAULT_EXCLUDE_DIRS = [
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    '.pnpm',
+    'dist',
+    'build',
+    'lib',
+    'out',
+];
+export function resolveScanOptions(config) {
+    // Additive ruling: the built-in tables are the
+    // always-on floor, user entries append — "the file states only exceptions"
+    // must not mean restating the defaults to add one. Duplicates are harmless
+    // (membership checks only), so a plain concat stays honest. boundaryExempt
+    // has no floor to append to — an absent key means no exemptions.
+    return {
+        excludeDirs: [...DEFAULT_EXCLUDE_DIRS, ...(config?.excludeDirs ?? [])],
+        excludeFiles: [...DEFAULT_EXCLUDE_FILES, ...(config?.excludeFiles ?? [])],
+        excludeDotEntries: config?.excludeDotEntries ?? true,
+        respectGitignore: config?.respectGitignore ?? true,
+        boundaryExempt: config?.boundaryExempt ?? [],
+        maxFiles: config?.maxFiles ?? 2000,
+    };
+}
+/**
+ * The engine-mounted exclusion floor: when the caller resolved
+ * the built-in floor (resolveScanOptions output, or an equivalent terminal
+ * list), its dir table rides the engine's preset form — vcs/deps/build carry
+ * the old nine-entry DEFAULT_EXCLUDE_DIRS table plus vendor/ and coverage/
+ * (the accepted preset increment) — and agentDocs carries the built-in
+ * AGENTS.md/CLAUDE.md file exclusion. A terminal caller that narrowed the
+ * floor (BASE_SCAN-style excludeDirs: []) keeps exact name semantics via
+ * the policy channel and the replay's literal check: nothing is
+ * force-mounted. (The preset increment is negatable by a repo's .gitignore
+ * — engine front-seat semantics; the floor names on the policy channel are
+ * not, exactly as before.)
+ */
+function engineMounts(opts) {
+    const mounts = [];
+    if (DEFAULT_EXCLUDE_DIRS.every((name) => opts.excludeDirs.includes(name))) {
+        mounts.push('vcs', 'deps', 'build');
+    }
+    if (DEFAULT_EXCLUDE_FILES.every((name) => opts.excludeFiles.includes(name))) {
+        mounts.push('agentDocs');
+    }
+    return mounts;
+}
+/**
+ * The resolved excludeDirs ride the engine's policy channel as dir-only
+ * patterns at the rear seat of the rule table — exactly the old floor's
+ * independence from gitignore (a repo's `!node_modules/` cannot resurrect a
+ * floor entry). Entries that are not plain names (separators, globs, a
+ * leading '!') stay out of the channel: the old engine compared directory
+ * names by literal equality, and those entries keep that semantics in the
+ * replay instead of acquiring pattern meaning.
+ */
+function excludeChannelPatterns(excludeDirs) {
+    return excludeDirs
+        .filter((name) => /^[^/\\!*?[\]!#]+$/u.test(name))
+        .map((name) => `${name}/`);
+}
+function buildScopeLevel(paths) {
+    const root = { files: new Set(), dirs: new Map() };
+    for (const path of paths) {
+        const segments = path.split('/');
+        let level = root;
+        for (let index = 0; index < segments.length - 1; index += 1) {
+            const segment = segments[index];
+            if (segment === undefined)
+                continue;
+            let child = level.dirs.get(segment);
+            if (child === undefined) {
+                child = { files: new Set(), dirs: new Map() };
+                level.dirs.set(segment, child);
+            }
+            level = child;
+        }
+        const file = segments[segments.length - 1];
+        if (file !== undefined && file !== '')
+            level.files.add(file);
+    }
+    return root;
+}
+/**
+ * The one engine query — "which files are in scope". Unbounded on purpose: the
+ * budget's unit is a TREE ENTRY (a Markdown file surviving the consumer
+ * filters), so the engine's raw-file budget never fires here and the
+ * replay below owns the fact-safe cut, its ordering, and its diagnostics.
+ * (Engine diagnostics beyond the budget do not exist in 0.1.0.)
+ * boundaryExempt rides boundaryStones.exempt verbatim: naming a
+ * subtree registers its participation — its own .git no longer cuts it,
+ * while deeper embedded repos inside it and un-named siblings keep the cut.
+ */
+export async function scopeLevels(root, opts) {
+    const boundaryExempt = opts.boundaryExempt ?? [];
+    const scope = await walkScope(root, {
+        mountPresets: engineMounts(opts),
+        exclude: excludeChannelPatterns(opts.excludeDirs),
+        excludeDotEntries: opts.excludeDotEntries,
+        respectGitignore: opts.respectGitignore,
+        ...(boundaryExempt.length > 0 ? { boundaryStones: { exempt: [...boundaryExempt] } } : {}),
+        maxFiles: Number.MAX_SAFE_INTEGER,
+    });
+    return buildScopeLevel(scope.files);
+}
+//# sourceMappingURL=engine-mapping.js.map

package/dist/engine-mapping.js.map

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

package/dist/hydration.d.ts

@@ -0,0 +1,49 @@
+import type { NavItem, NavNode, ScanDiagnostic } from './types.ts';
+export interface ScannedFile {
+    path: string;
+    content: string;
+}
+/** Port: built-in chain is the ported routes extraction; LLM providers arrive in v1.x. */
+export interface DescriptionProvider {
+    extract(file: ScannedFile): Promise<string | null>;
+}
+export declare const builtinDescriptionProvider: DescriptionProvider;
+/** One started read awaiting its settle: item attaches blank at kick-off,
+ * the description lands at the settle. */
+export interface PendingRead {
+    rel: string;
+    content: Promise<string | null>;
+    item: NavItem;
+}
+/** Walk-order diagnostic events: directory diagnostics record where they
+ * fired; file events settle at the drain — the flattened order equals the
+ * serial walk's emission order. Structure walks emit diag events only. */
+export type DiagnosticEvent = {
+    kind: 'diag';
+    diagnostic: ScanDiagnostic;
+} | {
+    kind: 'file';
+    read: PendingRead;
+};
+/** Structure-walk file record: the node exists without an item; describe()
+ * attaches the item after extraction. */
+export interface FileRecord {
+    rel: string;
+    abs: string;
+    node: NavNode;
+}
+/** Bounded in-flight read window: kicks never reject (read errors resolve
+ * null — the unreadable-file path), and the gate waits for the next settle
+ * before kicking past the ceiling. gate() then start() keeps the started
+ * promise unwrapped for fire-and-continue callers. */
+export declare class BoundedReads {
+    private readonly pending;
+    /** Wait for a window slot (no-op while under the ceiling). */
+    gate(): Promise<void>;
+    /** Start one read and return its still-running promise. */
+    start(abs: string): Promise<string | null>;
+}
+/** Settle one started read: the description lands on the item and any
+ * per-file diagnostic (unreadable-file / no-description placeholder) goes
+ * to the sink at the caller's position. */
+export declare function settleDescription(read: PendingRead, provider: DescriptionProvider, sink: ScanDiagnostic[]): Promise<void>;

package/dist/hydration.js

@@ -0,0 +1,181 @@
+/**
+ * Read pipeline for descriptions — the machinery both entry points share
+ * (file split 2026-10-24): the bounded in-flight read window, the bounded
+ * head ladder that provably covers the extraction chain's input (frontmatter
+ * plus the body-head window, extended adaptively, never more bytes than the
+ * chain can consume), the walk-order read events, and the settle that lands
+ * a description — or the unreadable-file / no-description paths — on an
+ * item. The extraction chain itself lives in description.ts.
+ */
+import { open } from 'node:fs/promises';
+import { extractDescription, BODY_HEAD_LINE_LIMIT } from './description.js';
+export const builtinDescriptionProvider = {
+    extract: (file) => Promise.resolve(extractDescription(file.content)),
+};
+/** Read fan-out ceiling: the 2026-10-20 probe saturated at 8 lanes (~4.3x,
+ * 39→9ms over 177 files) with nothing at 16 — the window keeps stragglers
+ * from stalling the pipeline and bounds transient memory to the window's
+ * in-flight file heads. */
+const MAX_INFLIGHT_READS = 16;
+/** Bounded in-flight read window: kicks never reject (read errors resolve
+ * null — the unreadable-file path), and the gate waits for the next settle
+ * before kicking past the ceiling. gate() then start() keeps the started
+ * promise unwrapped for fire-and-continue callers. */
+export class BoundedReads {
+    pending = [];
+    /** Wait for a window slot (no-op while under the ceiling). */
+    async gate() {
+        if (this.pending.length >= MAX_INFLIGHT_READS) {
+            await Promise.race(this.pending);
+        }
+    }
+    /** Start one read and return its still-running promise. */
+    start(abs) {
+        const content = readDescriptionInput(abs);
+        this.pending.push(content);
+        void content.then(() => {
+            const index = this.pending.indexOf(content);
+            if (index !== -1)
+                this.pending.splice(index, 1);
+        });
+        return content;
+    }
+}
+/** First head rung and the extension factor: extraction reads frontmatter
+ * plus a 15-line body-head window (fences/HTML comments stripped inside
+ * it), so a head closing the frontmatter and showing 16+ open body lines
+ * with nothing dangling at the cut is provably equivalent to the full file
+ * for the chain — the ladder only climbs for long frontmatter or
+ * fence/comment-heavy heads. */
+const DESC_HEAD_BYTES = 16 * 1024;
+const DESC_HEAD_LADDER = 4;
+/**
+ * Read the file head the description chain consumes — never more bytes than
+ * the chain can read, provably equivalent input or the ladder climbs (the
+ * whole file is the terminal rung). Any I/O error resolves null (the
+ * unreadable-file path); the full readFile this replaced had the same
+ * contract with far more bytes.
+ */
+async function readDescriptionInput(abs) {
+    let handle;
+    try {
+        handle = await open(abs);
+    }
+    catch {
+        return null;
+    }
+    try {
+        let capacity = DESC_HEAD_BYTES;
+        for (;;) {
+            const bytes = await readUpTo(handle, capacity);
+            const text = bytes.toString('utf8');
+            if (bytes.length < capacity || headCoversExtraction(text))
+                return text;
+            capacity *= DESC_HEAD_LADDER;
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+async function readUpTo(handle, capacity) {
+    const buffer = Buffer.alloc(capacity);
+    let filled = 0;
+    while (filled < capacity) {
+        const { bytesRead } = await handle.read(buffer, filled, capacity - filled, filled);
+        if (bytesRead === 0)
+            break;
+        filled += bytesRead;
+    }
+    return filled === capacity ? buffer : buffer.subarray(0, filled);
+}
+/**
+ * Whether a head provably covers every byte extractDescription reads:
+ * frontmatter closed when opened; past it, at least BODY_HEAD_LINE_LIMIT + 1
+ * open lines (the chain slices 15 — the +1 guarantees the 15th ended with a
+ * newline and is complete) with no code fence or HTML comment left dangling
+ * at the cut (mirrors stripCodeFences / stripHtmlComments state shapes; a
+ * dangling marker means later content could still change the strip).
+ */
+function headCoversExtraction(text) {
+    const lines = text.split(/\r?\n/u);
+    let start = 0;
+    if (lines[0]?.trim() === '---') {
+        const end = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+        if (end === -1)
+            return false;
+        start = end + 1;
+    }
+    let inFence = false;
+    let inComment = false;
+    let openLines = 0;
+    for (let index = start; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/^\s*(`{3,}|~{3,})/u.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        let rest = line;
+        while (rest.length > 0) {
+            if (!inComment) {
+                const opens = rest.indexOf('<!--');
+                if (opens === -1)
+                    break;
+                rest = rest.slice(opens + 4);
+                inComment = true;
+            }
+            else {
+                const closes = rest.indexOf('-->');
+                if (closes === -1) {
+                    rest = '';
+                    break;
+                }
+                rest = rest.slice(closes + 3);
+                inComment = false;
+            }
+        }
+        openLines += 1;
+    }
+    return !inFence && !inComment && openLines >= BODY_HEAD_LINE_LIMIT + 1;
+}
+/** Settle one started read: the description lands on the item and any
+ * per-file diagnostic (unreadable-file / no-description placeholder) goes
+ * to the sink at the caller's position. */
+export async function settleDescription(read, provider, sink) {
+    const content = await read.content;
+    if (content === null) {
+        // routes port: an unreadable Markdown file still becomes a bare-path
+        // route (diagnostic fires, the entry survives) — it must not silently
+        // vanish from navigation, and it still consumes the maxFiles budget.
+        sink.push({
+            code: 'unreadable-file',
+            severity: 'warning',
+            message: `Unable to read Markdown file ${read.rel}.`,
+            path: read.rel,
+            audience: 'maintainer',
+        });
+        read.item.description = `Undocumented — unreadable file ${read.rel}`;
+        return;
+    }
+    const extracted = await provider.extract({ path: read.rel, content });
+    read.item.description =
+        extracted !== null && extracted.trim() !== '' ? extracted : placeholder(read.rel, sink);
+}
+function placeholder(relPath, diagnostics) {
+    diagnostics.push({
+        code: 'no-description',
+        severity: 'warning',
+        // The code states the condition; the message carries only the datum
+        // (the WARN | code | source=... convention — no restating sentence).
+        message: relPath,
+        path: relPath,
+        audience: 'maintainer',
+    });
+    return `Undocumented — add a description to ${relPath}`;
+}
+//# sourceMappingURL=hydration.js.map

package/dist/hydration.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @any-nav/scan public API — the lean engine face.
+ *
+ * Boundary rules this surface must preserve:
+ *   1. one runtime dependency by ruling — @catheadowl/pathscope, the shared
+ *      file-scope engine the walk delegates to. That delegation replaced the
+ *      zero-dependency premise: embedders carry pathscope
+ *      and its three deps (ignore/fdir/find-up) in the install closure, and
+ *      no other dependency may join them;
+ *   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;
+ *   4. API shell policy: export what real consumption forms
+ *      need — a consumption form is someone importing today, a local
+ *      fork being the unwired equivalent — never speculative breadth;
+ *      each future export passes a light ruling first.
+ */
+export type { DiagnosticAudience, NavItem, NavLocator, NavLocatorKind, NavNode, ScanConfig, ScanDiagnostic, } from './types.ts';
+export type { ResolvedScanOptions } from './engine-mapping.ts';
+export type { DescriptionProvider, ScannedFile, } from './hydration.ts';
+export type { ScanOutput, StructureScanOutput, } from './scan.ts';
+export { builtinDescriptionProvider, } from './hydration.ts';
+export { DEFAULT_EXCLUDE_DIRS, DEFAULT_EXCLUDE_FILES, resolveScanOptions, } from './engine-mapping.ts';
+export { DIR_DESCRIPTION_CARRIERS, isDirDescriptionCarrier, isExcludedFileName, } from './tree-replay.ts';
+export { scanSource, scanStructure, } from './scan.ts';
+export { extractDescription } from './description.ts';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { builtinDescriptionProvider, } from './hydration.js';
+export { DEFAULT_EXCLUDE_DIRS, DEFAULT_EXCLUDE_FILES, resolveScanOptions, } from './engine-mapping.js';
+export { DIR_DESCRIPTION_CARRIERS, isDirDescriptionCarrier, isExcludedFileName, } from './tree-replay.js';
+export { 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":"AAqCA,OAAO,EACL,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,UAAU,EACV,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/scan.d.ts

@@ -0,0 +1,46 @@
+import { type ResolvedScanOptions } from './engine-mapping.ts';
+import { type DescriptionProvider } from './hydration.ts';
+import type { NavNode, ScanDiagnostic } from './types.ts';
+export interface ScanOutput {
+    tree: NavNode;
+    itemCount: number;
+    diagnostics: ScanDiagnostic[];
+    /**
+     * Dir paths (walk order) whose descent the maxFiles budget cut short —
+     * the cut chain (fact-safe cut): the folder where the
+     * budget flipped plus every surviving ancestor. Their recursive counts
+     * are floors, never totals; views render ≥N and the walk events carry a
+     * per-row diagnostic. Identical for the structure walk.
+     */
+    countIncompletePaths: string[];
+}
+export declare function scanSource(root: string, provider?: DescriptionProvider, options?: ResolvedScanOptions): Promise<ScanOutput>;
+export interface StructureScanOutput {
+    tree: NavNode;
+    itemCount: number;
+    /** Walk diagnostics (directory findings + file-limit); per-file
+     * diagnostics (no-description / unreadable-file) ride describe(). */
+    diagnostics: ScanDiagnostic[];
+    /**
+     * Dir paths whose descent the maxFiles budget cut short — counts are
+     * floors (≥ rows, per-row diagnostics already in `diagnostics`);
+     * identical to scanSource's list (same cut point).
+     */
+    countIncompletePaths: string[];
+    /**
+     * Hydrate descriptions for the given source-relative Markdown paths, in
+     * place: file nodes gain their NavItem, and folders fold descriptions
+     * (carrier ?? own README chain, identical to a full scan) once their
+     * README hydrates. Returns the per-file diagnostics in walk order.
+     * Idempotent — already-hydrated paths are skipped; unknown paths are
+     * ignored. Reads fetch bounded heads under the same in-flight window.
+     */
+    describe(paths: Iterable<string>): Promise<ScanDiagnostic[]>;
+}
+/**
+ * Structure-only walk: every exclusion, gitignore, budget, and pruning rule
+ * of scanSource with zero content reads — file nodes carry no item until
+ * describe() hydrates the ones a view actually renders. The tree shape and
+ * itemCount are exactly scanSource's (the budget counts entries, not reads).
+ */
+export declare function scanStructure(root: string, provider?: DescriptionProvider, options?: ResolvedScanOptions): Promise<StructureScanOutput>;