@any-nav/scan 0.1.0 → 0.2.0

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

@@ -2,16 +2,27 @@
  * @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);
+ *   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.
+ *      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 { 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 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

@@ -1,3 +1,6 @@
-export { builtinDescriptionProvider, DEFAULT_EXCLUDE_DIRS, DEFAULT_EXCLUDE_FILES, DIR_SIDECAR_NAMES, isDirSidecarName, isExcludedFileName, resolveScanOptions, scanSource, scanStructure, } from './scan.js';
+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

@@ -1 +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"}
+{"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

@@ -1,55 +1,19 @@
-import type { NavNode, ScanConfig, ScanDiagnostic } 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;
-    maxFiles: number;
-}
-export declare function resolveScanOptions(config?: ScanConfig): ResolvedScanOptions;
-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>;
-}
+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, ADR-0010 U12): the folder where the
+     * 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 const builtinDescriptionProvider: DescriptionProvider;
-export declare function isExcludedFileName(name: string, excludeFiles: readonly string[]): boolean;
-/**
- * Directory description sidecars (2026-10-07): the Docusaurus ecosystem
- * names — a folder may state its navigation description in one of these
- * instead of its README (release-face READMEs stay untouched). The first
- * existing name in this order is authoritative; the files are never Markdown
- * so they never enter the tree, and they never consume the maxFiles budget.
- */
-export declare const DIR_SIDECAR_NAMES: readonly string[];
-export declare function isDirSidecarName(name: string): boolean;
 export declare function scanSource(root: string, provider?: DescriptionProvider, options?: ResolvedScanOptions): Promise<ScanOutput>;
 export interface StructureScanOutput {
     tree: NavNode;
@@ -60,13 +24,13 @@ export interface StructureScanOutput {
     /**
      * 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, U11/U12).
+     * 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
-     * (sidecar ?? own README chain, identical to a full scan) once their
+     * (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.