@any-nav/scan 0.0.0-stage → 0.2.0

package/dist/scan.js

@@ -0,0 +1,154 @@
+/**
+ * Scan: walk a Markdown folder into a NavTree under the routes traversal
+ * semantics (absorption — port, don't rewrite). Since the pathscope
+ * delegation (facade transition: the public API and
+ * behavior stand, the walk engine is swapped) the scan is two layers:
+ *
+ *   - engine — @catheadowl/pathscope `walkScope` answers "which files are in
+ *     scope": the gitignore cascade (nested, plus inheritance above the scan
+ *     root), mounted exclusion presets
+ *     (vcs/deps/build = the old nine-entry floor plus vendor/ and coverage/,
+ *     an accepted increment; agentDocs = the built-in AGENTS.md/CLAUDE.md
+ *     exclusion), the policy layer carrying the resolved excludeDirs (rear
+ *     seat: gitignore negations cannot resurrect a floor entry, as before),
+ *     the dot category, and boundary stones. respectGitignore and
+ *     excludeDotEntries pass straight through.
+ *   - consumer replay (this package) — the Markdown-only post-filter, the
+ *     case-insensitive excludeFiles check, the sorted (localeCompare) DFS
+ *     assembly with empty-directory pruning, the maxFiles budget (its unit
+ *     is a TREE ENTRY — a Markdown file surviving the filters — so the
+ *     engine query runs unbounded and the replay owns the fact-safe cut and
+ *     its diagnostics), NavNode/markdown-locator assembly, and the
+ *     description chains: folder descriptions from the directory's
+ *     standardized carriers in order — its `package.json` `description`,
+ *     then its `manifest.yml` `metadata.description` — else from
+ *     the folder's own README.md; dir nodes also carry
+ *     `markdown` — the representative README child's path, present iff the
+ *     tree contains it, known from enumeration alone in both
+ *     walks. 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.
+ *
+ * File split 2026-10-24: this module keeps the two entry points and their
+ * output faces; the four blocks they share live beside it — engine-mapping
+ * (options/preset mapping + the walkScope bridge), tree-replay (the sorted
+ * DFS replay), budget (the maxFiles state + cut diagnostics), hydration
+ * (the read pipeline + provider face).
+ */
+import { stat } from 'node:fs/promises';
+import { fileLimitDiagnostic } from './budget.js';
+import { resolveScanOptions } from './engine-mapping.js';
+import { builtinDescriptionProvider, settleDescription } from './hydration.js';
+import { assignFolderDescriptions, performWalk, rootNode } from './tree-replay.js';
+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 () => [],
+    };
+}
+function rootDiagnostic(code, message) {
+    return { code, severity: 'warning', message, path: '.', audience: 'consumer' };
+}
+//# sourceMappingURL=scan.js.map

package/dist/scan.js.map

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

package/dist/tree-replay.d.ts

@@ -0,0 +1,61 @@
+import { type ResolvedScanOptions } from './engine-mapping.ts';
+import { BoundedReads, type DiagnosticEvent, type FileRecord } from './hydration.ts';
+import type { NavNode } from './types.ts';
+export declare function isExcludedFileName(name: string, excludeFiles: readonly string[]): boolean;
+/**
+ * Directory description carriers: standardized files a folder
+ * may already carry, in descending order of standardization — the npm
+ * `package.json` description, then the manifest-authoring `manifest.yml`
+ * `metadata.description` gloss. Priority order, per stage: present with a
+ * usable value wins; present but empty or key-less falls through to the
+ * next stage (never fabricates); unreadable or invalid fires a loud
+ * maintainer diagnostic and falls through the same way. The README chain
+ * remains the tail after the last carrier. The files are never Markdown so
+ * they never enter the tree, and they never consume the maxFiles budget.
+ */
+export declare const DIR_DESCRIPTION_CARRIERS: readonly string[];
+export declare function isDirDescriptionCarrier(name: string): boolean;
+/** Shared mutable walk state (the budget stays out: its arithmetic is
+ * synchronous exactly as in the serial walk, which is what keeps the
+ * maxFiles cut point identical). */
+export interface WalkContext {
+    /** Scan root as given — replay paths join against it. */
+    root: string;
+    opts: ResolvedScanOptions;
+    events: DiagnosticEvent[];
+    /** Walked md files by source-relative path, in walk order — the structure
+     * walk's describe() index (the eager walk kicks reads inline instead). */
+    files: Map<string, FileRecord>;
+    /** Directory carrier descriptions captured during the walk; the folder
+     * pass folds them with README chains into node descriptions. */
+    carrierDescriptions: Map<NavNode, string | undefined>;
+    reads: BoundedReads;
+    /** Eager walks kick reads at walk positions; structure walks record files
+     * only, deferring every content read to describe(). */
+    eager: boolean;
+    /** Dir paths (walk order) whose descent the maxFiles budget cut short —
+     * the floor-count chain; the per-row diagnostics ride the
+     * walk events alongside. */
+    countIncompletePaths: string[];
+}
+/** The shared walk's result (either entry point assembles its output from
+ * this): assembled tree (carrier descriptions captured), budget, and
+ * walk-order events (diag events for directory findings; file events in
+ * eager mode). */
+export interface WalkOutcome {
+    ctx: WalkContext;
+    tree: NavNode;
+    itemCount: number;
+    events: DiagnosticEvent[];
+    limitHit: boolean;
+}
+export declare function performWalk(root: string, options: ResolvedScanOptions | undefined, eager: boolean): Promise<WalkOutcome>;
+/**
+ * Post-walk folder descriptions, bottom-up over the assembled tree — the
+ * same chain the serial walk computed inline: carrier description first
+ * (package.json, then manifest.yml), 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.
+ */
+export declare function assignFolderDescriptions(node: NavNode, ctx: WalkContext): void;
+export declare function rootNode(root: string): NavNode;

package/dist/tree-replay.js

@@ -0,0 +1,256 @@
+/**
+ * Tree replay — the Markdown layer over the engine's in-scope set (file
+ * split 2026-10-24), in the pre-facade walk's exact order and shape: the
+ * md-only post-filter with the case-insensitive excludeFiles check and the
+ * regular-file gate, the name-sorted (localeCompare) DFS with
+ * empty-directory pruning, the budget's fact-safe cut and its floor-count
+ * chain, NavNode/markdown-locator assembly, and the folder description
+ * chains (carrier read at entry, README fold after the settle). The engine
+ * bridge lives in engine-mapping.ts, the budget state and diagnostics in
+ * budget.ts, the read pipeline in hydration.ts; the two entry points that
+ * assemble their outputs from this walk live in scan.ts.
+ */
+import { lstat, readFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { extractManifestDescription, extractPackageJsonDescription } from './description.js';
+import { countTruncatedDiagnostic } from './budget.js';
+import { resolveScanOptions, scopeLevels } from './engine-mapping.js';
+import { BoundedReads } from './hydration.js';
+const MARKDOWN_EXT = '.md';
+export function isExcludedFileName(name, excludeFiles) {
+    if (excludeFiles.length === 0)
+        return false;
+    const lower = name.toLowerCase();
+    return excludeFiles.some((excluded) => excluded.toLowerCase() === lower);
+}
+/**
+ * Directory description carriers: standardized files a folder
+ * may already carry, in descending order of standardization — the npm
+ * `package.json` description, then the manifest-authoring `manifest.yml`
+ * `metadata.description` gloss. Priority order, per stage: present with a
+ * usable value wins; present but empty or key-less falls through to the
+ * next stage (never fabricates); unreadable or invalid fires a loud
+ * maintainer diagnostic and falls through the same way. The README chain
+ * remains the tail after the last carrier. The files are never Markdown so
+ * they never enter the tree, and they never consume the maxFiles budget.
+ */
+export const DIR_DESCRIPTION_CARRIERS = ['package.json', 'manifest.yml'];
+export function isDirDescriptionCarrier(name) {
+    const lower = name.toLowerCase();
+    return DIR_DESCRIPTION_CARRIERS.some((carrier) => carrier === lower);
+}
+/**
+ * Read the directory's carrier description from the engine's in-scope set,
+ * carrier by carrier in DIR_DESCRIPTION_CARRIERS order (case-insensitive on
+ * the on-disk name) — scope membership IS the gitignore verdict the engine
+ * computed with its accumulated rules (a gitignored carrier falls through),
+ * and respectGitignore: false leaves the carrier in scope the same way.
+ * Returns undefined when no carrier yields a description — the README chain
+ * then fills in.
+ */
+async function carrierDescription(relDir, level, ctx) {
+    for (const carrierName of DIR_DESCRIPTION_CARRIERS) {
+        const name = [...level.files].find((candidate) => candidate.toLowerCase() === carrierName);
+        if (name === undefined)
+            continue;
+        const rel = relDir === '' ? name : `${relDir}/${name}`;
+        let content;
+        try {
+            content = await readFile(join(ctx.root, rel), 'utf8');
+        }
+        catch {
+            ctx.events.push({
+                kind: 'diag',
+                diagnostic: {
+                    code: 'description-carrier-unreadable',
+                    severity: 'warning',
+                    message: `Unable to read directory description carrier ${rel}.`,
+                    path: rel,
+                    audience: 'maintainer',
+                },
+            });
+            continue;
+        }
+        const read = carrierName === 'package.json'
+            ? extractPackageJsonDescription(content)
+            : extractManifestDescription(content);
+        if ('error' in read) {
+            ctx.events.push({
+                kind: 'diag',
+                diagnostic: {
+                    code: 'description-carrier-unreadable',
+                    severity: 'warning',
+                    message: `Directory description carrier ${rel}: ${read.error}.`,
+                    path: rel,
+                    audience: 'maintainer',
+                },
+            });
+            continue;
+        }
+        if (read.description !== null && read.description.trim() !== '')
+            return read.description;
+    }
+    return undefined;
+}
+export async function performWalk(root, options, eager) {
+    const opts = options ?? resolveScanOptions();
+    const budget = { files: 0, limitHit: opts.maxFiles <= 0 };
+    const ctx = {
+        root,
+        opts,
+        events: [],
+        files: new Map(),
+        carrierDescriptions: new Map(),
+        reads: new BoundedReads(),
+        eager,
+        countIncompletePaths: [],
+    };
+    const level = await scopeLevels(root, opts);
+    const excludeDirNames = new Set(opts.excludeDirs);
+    const rootOutcome = await scanLevel('', level, ctx, budget, excludeDirNames);
+    const tree = rootNode(root);
+    if (rootOutcome.children.length > 0) {
+        tree.children = rootOutcome.children;
+        const markdown = readmeChildPath(tree);
+        if (markdown !== undefined)
+            tree.markdown = markdown;
+    }
+    ctx.carrierDescriptions.set(tree, rootOutcome.carrierDescription);
+    return { ctx, tree, itemCount: budget.files, events: ctx.events, limitHit: budget.limitHit };
+}
+/**
+ * Replay one directory level in the pre-facade walk's exact order and shape:
+ * entries name-sorted (localeCompare, directories and files together), the
+ * budget checked at every entry start (an entry past the cut is never
+ * examined), directories descending recursively and pruning when nothing
+ * Markdown survives beneath, the fact-safe-cut chain recorded on the way
+ * out. Markdown files additionally pass the case-insensitive excludeFiles
+ * check and a regular-file gate: symlinks never entered the old walk (the
+ * readdir dirent types said so) while the unresolved link IS an in-scope
+ * entry for the engine, so the lstat gate restores the old shape. Eager
+ * walks kick reads at walk positions; structure walks record files for
+ * describe().
+ */
+async function scanLevel(relDir, level, ctx, budget, excludeDirNames) {
+    const { opts } = ctx;
+    const carrier = await carrierDescription(relDir, level, ctx);
+    const children = [];
+    const names = [...level.dirs.keys(), ...level.files].sort((a, b) => a.localeCompare(b));
+    for (const name of names) {
+        if (budget.files >= opts.maxFiles) {
+            budget.limitHit = true;
+            continue;
+        }
+        const rel = relDir === '' ? name : `${relDir}/${name}`;
+        const dirLevel = level.dirs.get(name);
+        if (dirLevel !== undefined) {
+            // Literal-name floor semantics: the old engine compared directory names
+            // by equality. Plain names already rode the engine's policy channel;
+            // this check also carries any non-plain entry verbatim.
+            if (excludeDirNames.has(name))
+                continue;
+            const outcome = await scanLevel(rel, dirLevel, ctx, budget, excludeDirNames);
+            if (outcome.children.length === 0)
+                continue; // empty-directory pruning (root exempt)
+            const node = { name, path: rel, kind: 'dir', children: outcome.children };
+            // Enumeration-known locator: set when the README child is in
+            // the tree — a budget cut past the README or an exclusion leaves it
+            // absent (the field mirrors the tree, never the filesystem).
+            const markdown = readmeChildPath(node);
+            if (markdown !== undefined)
+                node.markdown = markdown;
+            ctx.carrierDescriptions.set(node, outcome.carrierDescription);
+            // Fact-safe cut: 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) });
+            }
+            children.push(node);
+            continue;
+        }
+        if (extname(name).toLowerCase() !== MARKDOWN_EXT)
+            continue;
+        if (isExcludedFileName(name, opts.excludeFiles))
+            continue;
+        const abs = join(ctx.root, rel);
+        let regular = true;
+        try {
+            regular = (await lstat(abs)).isFile();
+        }
+        catch {
+            // Vanished between the engine walk and the replay: keep the node — the
+            // read settles through the unreadable-file path, as the old walk did.
+        }
+        if (!regular)
+            continue;
+        const node = { name: stem(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;
+        children.push(node);
+    }
+    return { children, carrierDescription: carrier };
+}
+/**
+ * The representative README child's path — the folder-description chain's
+ * own name rule (file node names are stems, so the stem 'readme',
+ * case-insensitive; children are name-sorted, the first match represents).
+ * Mirrors the tree, not the filesystem: the walk sets it at assembly, so
+ * an excluded README leaves it absent.
+ */
+function readmeChildPath(node) {
+    for (const child of node.children ?? []) {
+        if (child.kind === 'file' && child.name.toLowerCase() === 'readme')
+            return child.path;
+    }
+    return undefined;
+}
+/**
+ * Post-walk folder descriptions, bottom-up over the assembled tree — the
+ * same chain the serial walk computed inline: carrier description first
+ * (package.json, then manifest.yml), 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.
+ */
+export 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.carrierDescriptions.get(node) ?? readmeDescription;
+    if (description !== undefined)
+        node.description = description;
+}
+export 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);
+}
+//# sourceMappingURL=tree-replay.js.map

package/dist/tree-replay.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Scan-domain types: the knowledge model and the scan policy inputs.
+ *
+ * This is the lean consumption face's type system: NavItem { name,
+ * description, locator } is the ONLY knowledge model in Any-Nav (the SDK's
+ * view DTOs build on it, never beside it), and ScanConfig is the scan
+ * boundary policy the TOML layer maps onto. Both live here — with the
+ * scanner — so embedders of the engine never pull the SDK's view types.
+ */
+/** v1 locates markdown files only. Kinds beyond 'file' are out of v1 scope. */
+export type NavLocatorKind = 'file';
+export interface NavLocator {
+    kind: NavLocatorKind;
+    /** Path relative to the nav source root, POSIX separators. */
+    path: string;
+}
+export interface NavItem {
+    /** Stable name; defaults to the file stem. */
+    name: string;
+    /** One line, from the description source chain. */
+    description: string;
+    locator: NavLocator;
+}
+/** Tree used for drill-down. Directories are nodes, not items. */
+export interface NavNode {
+    name: string;
+    /** Path relative to the source root, POSIX separators; '' for the root. */
+    path: string;
+    kind: 'dir' | 'file';
+    /** Present when kind === 'file'. */
+    item?: NavItem;
+    /** Present when kind === 'dir'. */
+    children?: NavNode[];
+    /**
+     * Dir nodes only (the root included): description from the directory's
+     * standardized carriers in order — its `package.json` `description`, then
+     * its `manifest.yml` `metadata.description` — else the
+     * extraction from the directory's own README.md (routes
+     * folder-representative semantics). Absent when none carries one.
+     */
+    description?: string;
+    /** Dir nodes only (root included): the representative README child's POSIX-relative path; present iff it is in the tree. */
+    markdown?: string;
+}
+/**
+ * Global scan boundary policy (routes traversal semantics; exclude
+ * lists are additive). All keys default — the config
+ * states only exceptions, and stating one never drops the built-in floor.
+ */
+export interface ScanConfig {
+    /** Directory names additionally skipped during traversal; appends to the always-on built-in list. */
+    excludeDirs?: string[];
+    /** Markdown file names (case-insensitive) additionally excluded from navigation, e.g. AGENTS.md; appends to the built-in list. */
+    excludeFiles?: string[];
+    /** Skip entries whose name starts with '.', e.g. .github. */
+    excludeDotEntries?: boolean;
+    /** Whether traversal respects .gitignore files. */
+    respectGitignore?: boolean;
+    /**
+     * Subtrees whose own nested `.git` does not cut them from this view — the
+     * engine's named-subtree core-stone exemption (git's
+     * submodule-registration face: an unregistered embedded repo is foreign
+     * territory, a registered one participates). Entries are gitignore-style
+     * patterns anchored at the view's scan root (e.g. 'deepseek-harness/');
+     * registration is not rescue — the subtree still passes every exclusion
+     * floor, and deeper embedded repos inside it still cut.
+     */
+    boundaryExempt?: string[];
+    /** Maximum Markdown files examined per source walk; past the cap entries go unexamined — diagnostics fire and folders whose descent was cut disclose floor (≥) counts (never a silent cut). */
+    maxFiles?: number;
+}
+export type DiagnosticAudience = 'consumer' | 'maintainer';
+export interface ScanDiagnostic {
+    code: string;
+    severity: 'info' | 'warning';
+    message: string;
+    path?: string;
+    audience: DiagnosticAudience;
+    /** Present only on write-artifact diagnostics (section-trimmed-to-budget):
+     *  the rows answer is never touched by the budget guard, so rows packaging
+     *  and agent faces stay silent — the report belongs where the artifact is
+     *  produced (the CLI --write flow; the section's own tail note is the
+     *  canonical text). */
+    face?: 'write';
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Scan-domain types: the knowledge model and the scan policy inputs.
+ *
+ * This is the lean consumption face's type system: NavItem { name,
+ * description, locator } is the ONLY knowledge model in Any-Nav (the SDK's
+ * view DTOs build on it, never beside it), and ScanConfig is the scan
+ * boundary policy the TOML layer maps onto. Both live here — with the
+ * scanner — so embedders of the engine never pull the SDK's view types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@any-nav/scan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Any-Nav scan core: the engine facade that walks a Markdown folder into a nav tree under the routes traversal semantics (exclusions, gitignore inheritance, a loud maxFiles budget, folder descriptions) with the walk delegated to @catheadowl/pathscope. Embedders consume this directly; @any-nav/core composes it with curation, render, and search.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CatheadOwl/any-nav.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@catheadowl/pathscope": "^0.1.1"
+  },
+  "keywords": [
+    "agent",
+    "navigation",
+    "markdown",
+    "scan"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.ts\""
+  }
 }