@any-nav/scan 0.0.0-stage → 0.1.0

package/dist/scan.d.ts

@@ -0,0 +1,82 @@
+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>;
+}
+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
+     * 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;
+    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, U11/U12).
+     */
+    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
+     * 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>;

package/dist/scan.js

@@ -0,0 +1,603 @@
+/**
+ * Scan: walk a Markdown folder into a NavTree under the routes traversal
+ * semantics (ADR-0010 absorption — port, don't rewrite): exclusion policies,
+ * gitignore inheritance, a loud maxFiles budget, empty-directory pruning, and
+ * folder descriptions — from a `_category_` sidecar when the folder carries
+ * one (the exception channel for release-face READMEs), else from the
+ * folder's own README.md. Description extraction is the ported routes chain
+ * (description.ts); null falls to core's placeholder + diagnostic, which
+ * routes does not have and core keeps (stricter).
+ *
+ * Read-only by contract: scanning must never modify source files
+ * (map is not territory).
+ *
+ * Two entry points share one walk (2026-10-20): scanSource reads and
+ * extracts every Markdown file (snapshot semantics — the search/candidates
+ * anchor); scanStructure walks structure-only and hydrates descriptions on
+ * demand via describe(), so a depth-0 view pays reads for the rows it
+ * renders, not the whole tree. Reads overlap behind a bounded in-flight
+ * window — budget cut, tree shape, and diagnostic order stay byte-identical
+ * to the serial walk this replaced — and fetch a bounded head that provably
+ * covers the extraction chain's input (frontmatter + the body-head window),
+ * extended adaptively, never more bytes than the chain can consume.
+ */
+import { open, readdir, readFile, stat } from 'node:fs/promises';
+import { basename, extname, join, relative, sep } from 'node:path';
+import { BODY_HEAD_LINE_LIMIT, extractDescription, extractSidecarDescription } from './description.js';
+import { isGitignored, readGitignoreRules } from './gitignore.js';
+const MARKDOWN_EXT = '.md';
+/**
+ * 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 (ADR-0010 update 2026-10-07): 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.
+    return {
+        excludeDirs: [...DEFAULT_EXCLUDE_DIRS, ...(config?.excludeDirs ?? [])],
+        excludeFiles: [...DEFAULT_EXCLUDE_FILES, ...(config?.excludeFiles ?? [])],
+        excludeDotEntries: config?.excludeDotEntries ?? true,
+        respectGitignore: config?.respectGitignore ?? true,
+        maxFiles: config?.maxFiles ?? 2000,
+    };
+}
+export const builtinDescriptionProvider = {
+    extract: (file) => Promise.resolve(extractDescription(file.content)),
+};
+export function isExcludedFileName(name, excludeFiles) {
+    if (excludeFiles.length === 0)
+        return false;
+    const lower = name.toLowerCase();
+    return excludeFiles.some((excluded) => excluded.toLowerCase() === lower);
+}
+/**
+ * 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 const DIR_SIDECAR_NAMES = ['_category_.yml', '_category_.yaml', '_category_.json'];
+export function isDirSidecarName(name) {
+    const lower = name.toLowerCase();
+    return DIR_SIDECAR_NAMES.some((sidecar) => sidecar === lower);
+}
+/**
+ * Whether a directory's already-listed entries carry a .gitignore — the
+ * walk opens the file only when readdir saw it, skipping the failing
+ * probe open per gitignore-less directory that dominated large-tree scan
+ * latency (case-insensitive: a case-insensitive filesystem would have
+ * resolved the probe open the same way).
+ */
+function carriesGitignore(entries) {
+    return entries.some((entry) => entry.isFile() && entry.name.toLowerCase() === '.gitignore');
+}
+/**
+ * Read the directory's sidecar description from its already-listed entries.
+ * Returns undefined when no sidecar exists, when the authoritative one is
+ * gitignored (traversal honors the same rules as content), or when it carries
+ * no description key — the README chain then fills in. Unreadable or invalid
+ * sidecars fire a loud diagnostic and fall through the same way.
+ */
+async function sidecarDescription(absDir, relDir, entries, ctx, gitignoreRules) {
+    for (const sidecarName of DIR_SIDECAR_NAMES) {
+        const entry = entries.find((candidate) => candidate.name.toLowerCase() === sidecarName && candidate.isFile());
+        if (entry === undefined)
+            continue;
+        const abs = join(absDir, entry.name);
+        if (ctx.opts.respectGitignore && isGitignored(abs, false, gitignoreRules))
+            return undefined;
+        const rel = relDir === '' ? entry.name : `${relDir}/${entry.name}`;
+        let content;
+        try {
+            content = await readFile(abs, 'utf8');
+        }
+        catch {
+            ctx.events.push({
+                kind: 'diag',
+                diagnostic: {
+                    code: 'sidecar-unreadable',
+                    severity: 'warning',
+                    message: `Unable to read directory description sidecar ${rel}.`,
+                    path: rel,
+                    audience: 'maintainer',
+                },
+            });
+            return undefined;
+        }
+        const read = extractSidecarDescription(entry.name, content);
+        if ('error' in read) {
+            ctx.events.push({
+                kind: 'diag',
+                diagnostic: {
+                    code: 'sidecar-unreadable',
+                    severity: 'warning',
+                    message: `Directory description sidecar ${rel}: ${read.error}.`,
+                    path: rel,
+                    audience: 'maintainer',
+                },
+            });
+            return undefined;
+        }
+        return read.description !== null && read.description.trim() !== '' ? read.description : undefined;
+    }
+    return undefined;
+}
+/** 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. */
+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. */
+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);
+}
+/**
+ * Post-walk folder descriptions, bottom-up over the assembled tree — the
+ * same chain the serial walk computed inline: sidecar first, else the
+ * folder's own first README child (children are name-sorted) carrying a
+ * real description. Runs after the settle, so file descriptions are final.
+ */
+function assignFolderDescriptions(node, ctx) {
+    let readmeDescription;
+    for (const child of node.children ?? []) {
+        if (child.kind === 'dir')
+            assignFolderDescriptions(child, ctx);
+        if (readmeDescription === undefined &&
+            child.kind === 'file' &&
+            child.name.toLowerCase() === 'readme' &&
+            child.item !== undefined &&
+            !child.item.description.startsWith('Undocumented')) {
+            readmeDescription = child.item.description;
+        }
+    }
+    const description = ctx.sidecars.get(node) ?? readmeDescription;
+    if (description !== undefined)
+        node.description = description;
+}
+async function performWalk(root, options, eager) {
+    const opts = options ?? resolveScanOptions();
+    const budget = { files: 0, limitHit: opts.maxFiles <= 0 };
+    const ctx = {
+        opts,
+        events: [],
+        files: new Map(),
+        sidecars: new Map(),
+        reads: new BoundedReads(),
+        eager,
+        countIncompletePaths: [],
+    };
+    const rootEntries = await sortedEntries(root, ctx);
+    // The readdir already says whether the root carries a .gitignore — probe
+    // opens for the (common) absent case are pure walk-thread latency, so
+    // only real files are opened (the same gate applies per directory below).
+    const rootRules = opts.respectGitignore && carriesGitignore(rootEntries)
+        ? await readGitignoreRules(root)
+        : [];
+    // Root description: the same chain as any directory — sidecar first, else
+    // the root README's own extraction (uniform semantics, no root special case).
+    const rootSidecar = await sidecarDescription(root, '', rootEntries, ctx, rootRules);
+    const children = [];
+    for (const entry of rootEntries) {
+        if (isDirSidecarName(entry.name))
+            continue; // consumed by rootSidecar above
+        const node = await scanEntry(root, root, entry, ctx, rootRules, budget);
+        if (node === null)
+            continue;
+        children.push(node);
+    }
+    const tree = rootNode(root);
+    if (children.length > 0)
+        tree.children = children;
+    ctx.sidecars.set(tree, rootSidecar);
+    return { ctx, tree, itemCount: budget.files, events: ctx.events, limitHit: budget.limitHit };
+}
+function fileLimitDiagnostic(maxFiles) {
+    return {
+        code: 'file-limit-reached',
+        severity: 'warning',
+        message: `Markdown file limit (${maxFiles}) reached while scanning; entries past the limit were not examined — folders whose descent was cut carry ≥ counts (a floor, not the total) and later folders are absent. Raise scan.maxFiles for the full tree.`,
+        path: '.',
+        audience: 'consumer',
+    };
+}
+/**
+ * Per-row disclosure for one floor-count folder (ADR-0010 U12): the budget
+ * cut this folder's descent mid-way, so the count a view renders for it is
+ * a floor. Consumer audience — it is view fidelity, same class as
+ * file-limit-reached.
+ */
+function countTruncatedDiagnostic(rel) {
+    return {
+        code: 'count-truncated-at-limit',
+        severity: 'warning',
+        message: `The maxFiles budget cut this folder's descent short; its shown count is a floor (at least that many), and entries past the cut point are absent.`,
+        path: rel,
+        audience: 'consumer',
+    };
+}
+export async function scanSource(root, provider = builtinDescriptionProvider, options) {
+    let rootStat;
+    try {
+        rootStat = await stat(root);
+    }
+    catch {
+        return { tree: rootNode(root), itemCount: 0, diagnostics: [rootDiagnostic('scan-root-not-found', `Scan root does not exist or is unreadable.`)], countIncompletePaths: [] };
+    }
+    if (rootStat.isFile()) {
+        return { tree: rootNode(root), itemCount: 0, diagnostics: [rootDiagnostic('scan-root-is-file', `Scan root is a file. Navigation scans start from folders.`)], countIncompletePaths: [] };
+    }
+    if (!rootStat.isDirectory()) {
+        return { tree: rootNode(root), itemCount: 0, diagnostics: [rootDiagnostic('scan-root-unsupported', `Scan root is neither a directory nor a Markdown file.`)], countIncompletePaths: [] };
+    }
+    const walk = await performWalk(root, options, true);
+    const diagnostics = [];
+    // Drain: settle the started reads in walk order (they overlapped during
+    // the walk) — descriptions and per-file diagnostics land exactly where
+    // the serial walk would have put them.
+    for (const event of walk.events) {
+        if (event.kind === 'diag') {
+            diagnostics.push(event.diagnostic);
+            continue;
+        }
+        await settleDescription(event.read, provider, diagnostics);
+    }
+    if (walk.limitHit)
+        diagnostics.push(fileLimitDiagnostic(walk.ctx.opts.maxFiles));
+    assignFolderDescriptions(walk.tree, walk.ctx);
+    return { tree: walk.tree, itemCount: walk.itemCount, diagnostics, countIncompletePaths: walk.ctx.countIncompletePaths };
+}
+/**
+ * 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 async function scanStructure(root, provider = builtinDescriptionProvider, options) {
+    let rootStat;
+    try {
+        rootStat = await stat(root);
+    }
+    catch {
+        return structureError(root, 'scan-root-not-found', `Scan root does not exist or is unreadable.`);
+    }
+    if (rootStat.isFile()) {
+        return structureError(root, 'scan-root-is-file', `Scan root is a file. Navigation scans start from folders.`);
+    }
+    if (!rootStat.isDirectory()) {
+        return structureError(root, 'scan-root-unsupported', `Scan root is neither a directory nor a Markdown file.`);
+    }
+    const walk = await performWalk(root, options, false);
+    const diagnostics = [];
+    for (const event of walk.events) {
+        if (event.kind === 'diag')
+            diagnostics.push(event.diagnostic);
+    }
+    if (walk.limitHit)
+        diagnostics.push(fileLimitDiagnostic(walk.ctx.opts.maxFiles));
+    return {
+        tree: walk.tree,
+        itemCount: walk.itemCount,
+        diagnostics,
+        countIncompletePaths: walk.ctx.countIncompletePaths,
+        describe: async (paths) => {
+            const targeted = paths instanceof Set ? paths : new Set(paths);
+            const records = [...walk.ctx.files.values()].filter((record) => targeted.has(record.rel) && record.node.item === undefined);
+            if (records.length === 0) {
+                assignFolderDescriptions(walk.tree, walk.ctx);
+                return [];
+            }
+            const reads = [];
+            for (const record of records) {
+                await walk.ctx.reads.gate();
+                const item = { name: record.node.name, description: '', locator: { kind: 'file', path: record.rel } };
+                record.node.item = item;
+                reads.push({ rel: record.rel, content: walk.ctx.reads.start(record.abs), item });
+            }
+            const sink = [];
+            for (const read of reads)
+                await settleDescription(read, provider, sink);
+            assignFolderDescriptions(walk.tree, walk.ctx);
+            return sink;
+        },
+    };
+}
+function structureError(root, code, message) {
+    return {
+        tree: rootNode(root),
+        itemCount: 0,
+        diagnostics: [rootDiagnostic(code, message)],
+        countIncompletePaths: [],
+        describe: async () => [],
+    };
+}
+/**
+ * Scan one directory entry into a tree node, or null when it carries no
+ * Markdown descendant (empty-directory pruning, ADR-0010; a dir with only
+ * pruned subdirs prunes too — a directory with a README is never empty).
+ * Eager walks kick reads here and settle at the drain; structure walks
+ * record the file for describe(). Either way descriptions finalize before
+ * the caller's output contract completes.
+ */
+async function scanEntry(root, absDir, entry, ctx, gitignoreRules, budget) {
+    const { opts } = ctx;
+    if (budget.files >= opts.maxFiles) {
+        budget.limitHit = true;
+        return null;
+    }
+    if (opts.excludeDotEntries && entry.name.startsWith('.'))
+        return null;
+    const abs = join(absDir, entry.name);
+    const rel = relPath(root, abs);
+    if (opts.respectGitignore && isGitignored(abs, entry.isDirectory(), gitignoreRules))
+        return null;
+    if (entry.isDirectory()) {
+        if (opts.excludeDirs.includes(entry.name))
+            return null;
+        const dirEntries = await sortedEntries(abs, ctx);
+        // The readdir above already says whether this dir carries a .gitignore
+        // — opening the file only then skips the failing probe per
+        // gitignore-less directory (the walk-thread latency that dominated
+        // large-tree scans; same gate as the root).
+        const nestedRules = opts.respectGitignore && carriesGitignore(dirEntries)
+            ? [...gitignoreRules, ...(await readGitignoreRules(abs))]
+            : gitignoreRules;
+        const sidecar = await sidecarDescription(abs, rel, dirEntries, ctx, nestedRules);
+        const children = [];
+        for (const child of dirEntries) {
+            if (isDirSidecarName(child.name))
+                continue; // consumed by sidecar above
+            const node = await scanEntry(root, abs, child, ctx, nestedRules, budget);
+            if (node === null)
+                continue;
+            children.push(node);
+        }
+        if (children.length === 0)
+            return null;
+        const node = { name: entry.name, path: rel, kind: 'dir', children };
+        ctx.sidecars.set(node, sidecar);
+        // Fact-safe cut (ADR-0010 U12): the budget flipped inside this folder's
+        // span, so it survives with partial children — as does every surviving
+        // ancestor, which marks itself the same way at its own loop's end (the
+        // chain of folders whose counts are floors). A partial count must never
+        // present as the total: the path joins the floor-count set and the
+        // per-row diagnostic fires (consumer audience). Folders never entered
+        // after the flip vanish instead — the global file-limit-reached covers
+        // those, unchanged.
+        if (budget.limitHit) {
+            ctx.countIncompletePaths.push(rel);
+            ctx.events.push({ kind: 'diag', diagnostic: countTruncatedDiagnostic(rel) });
+        }
+        return node;
+    }
+    if (entry.isFile() && extname(entry.name).toLowerCase() === MARKDOWN_EXT) {
+        if (isExcludedFileName(entry.name, opts.excludeFiles))
+            return null;
+        const node = { name: stem(entry.name), path: rel, kind: 'file' };
+        // Eager start, deferred settle: the read overlaps the rest of the walk
+        // while the budget counts synchronously at kick-off — the cut point
+        // (first maxFiles in sorted DFS order) is the serial walk's.
+        if (ctx.eager) {
+            await ctx.reads.gate();
+            const item = { name: node.name, description: '', locator: { kind: 'file', path: rel } };
+            node.item = item;
+            ctx.events.push({ kind: 'file', read: { rel, content: ctx.reads.start(abs), item } });
+        }
+        else {
+            ctx.files.set(rel, { rel, abs, node });
+        }
+        budget.files += 1;
+        return node;
+    }
+    return null;
+}
+async function sortedEntries(dir, ctx) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        ctx.events.push({
+            kind: 'diag',
+            diagnostic: {
+                code: 'unreadable-directory',
+                severity: 'warning',
+                message: `Unable to read directory.`,
+                path: dir,
+                audience: 'maintainer',
+            },
+        });
+        return [];
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+function rootDiagnostic(code, message) {
+    return { code, severity: 'warning', message, path: '.', audience: 'consumer' };
+}
+function placeholder(relPath, diagnostics) {
+    diagnostics.push({
+        code: 'no-description',
+        severity: 'warning',
+        // The code states the condition; the message carries only the datum
+        // (coggit's WARN | code | source=... convention — no restating sentence).
+        message: relPath,
+        path: relPath,
+        audience: 'maintainer',
+    });
+    return `Undocumented — add a description to ${relPath}`;
+}
+function rootNode(root) {
+    const name = basename(root);
+    return { name: name === '' || name === '.' || name === '/' ? 'root' : name, path: '', kind: 'dir' };
+}
+function stem(fileName) {
+    return fileName.slice(0, fileName.length - extname(fileName).length);
+}
+function relPath(root, abs) {
+    return relative(root, abs).split(sep).join('/');
+}
+//# sourceMappingURL=scan.js.map