@any-nav/core 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.2.0 — 2026-10-31
+
+- fast-bm25 loads lazily on first engine construction: importing the
+  package no longer touches the search engine at module-load time, so
+  every non-search path (CLI `list` / `list --json`, dsh nav) skips it.
+  Public API and search results are unchanged.
+- Routing and curated rows take a folder's `markdown` locator from the
+  scan's representative-README field on `NavNode`; the view-level README
+  pairing is retired.
+- The re-exported scan face tracks `@any-nav/scan` 0.2.0: the walk engine
+  delegates to `@catheadowl/pathscope`, folder descriptions read the
+  directory's `package.json` / `manifest.yml` carriers, and the former
+  traversal-boundary export family is removed with the in-package engine
+  it belonged to — see the scan changelog for the full face.
+
+## 0.1.0 — 2026-10-21
+
+First registry release.
+
+- Public SDK surface: the `createAnyNav` / `listFolder` facade, config
+  (`loadConfigFile` / `parseConfig` / `ConfigError`), the budget-guard
+  engine, render / `materialize` with built-in `agents-md` and
+  `generic-markdown` formats, and the query faces (`routingView`,
+  `curatedView`, `candidateFeed`, the search kernel, `readSource`).
+- `routingViewJson` — the routing projection serialized as pure JSON, the
+  machine face for CLI `--json` and library consumers.
+- Scanning now composes the split-out zero-dependency `@any-nav/scan`
+  package and re-exports its full face; embedders who only need the engine
+  can depend on `@any-nav/scan` directly.
+- Listings compose the structure-only walk — depth-bounded views hydrate
+  only the rows they render, not every file under the root.
+- Budget cuts surface as lower bounds: the routing face carries
+  `countIncompletePaths`; rendered rows show ≥N floors with the
+  `count-truncated-at-limit` diagnostic.

package/LICENSE

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

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @any-nav/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> The Any-Nav SDK: scan a Markdown folder, guard it against a context budget, render navigation fragments, and answer list / search / read.
+
+`@any-nav/core` is the read-only SDK behind Any-Nav. It composes the
+zero-dependency scan engine (`@any-nav/scan` — its full face is re-exported
+here) with: strict `any-nav.toml` config parsing, curation of default
+expansion via the config's `local` list, the budget-guard engine, rendering
+of the canonical navigation fragment for registered formats, and the query
+faces — `list(path)` with its rows / markdown renderings and JSON
+serialization, the search kernel, `read`, and the candidate feed.
+
+## Install
+
+```sh
+npm install @any-nav/core
+```
+
+## Usage
+
+The one-call face — list a folder under its nearest governing config (pure
+defaults when there is none):
+
+```ts
+import { listFolder, routingViewJson } from '@any-nav/core';
+
+const listing = await listFolder('docs'); // optional query: { configPath, depth, commandRunner }
+const machine = routingViewJson(listing);  // the routing projection as a pure JSON string
+```
+
+The full facade:
+
+```ts
+import { createAnyNav } from '@any-nav/core';
+
+const app = await createAnyNav({ configPath: 'any-nav.toml' }); // or { config, cwd }
+
+const sources = app.sources();                  // the config root as the single implicit source
+const exposure = app.decideExposure(sources[0]); // budget-guard reading — warns, never collapses
+const fragment = app.render(exposure, 'agents-md');
+const next = app.materialize(current, fragment); // pure splice — the caller writes the file
+```
+
+## Config
+
+`any-nav.toml` states only exceptions; every key defaults:
+
+- `local` — curation list: paths expanded into the default listing.
+- `budget` — the context-budget guard (over budget warns, never silently
+  collapses).
+- `scan` — scan boundary policy (`excludeDirs` / `excludeFiles` /
+  `excludeDotEntries` / `respectGitignore` / `maxFiles`), additive over the
+  engine's built-in floor.
+
+## Boundaries this SDK keeps
+
+- Read-only over the filesystem: no writes, no processes, no network, no
+  transport or LLM-client imports. `materialize()` returns new text — every
+  write belongs to the adapter.
+- The unified list model: `list(path)` is the product face; governance and
+  expansion live here, adapters only transport.
+- `NavItem { name, description, locator }` (from `@any-nav/scan`) is the only
+  knowledge model.
+- Embedders that only need the scan engine can depend on `@any-nav/scan`
+  directly and carry no SDK dependencies (smol-toml, fast-bm25 live on this
+  package's config and search paths, not the engine's).
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import type { ScanConfig } from '@any-nav/scan';
+export interface BudgetConfig {
+    /** Share of the context budget navigation may occupy, 0 < share ≤ 1. */
+    share?: number;
+    /** Hard cap in estimated tokens. */
+    maxTokens?: number;
+}
+export interface AnyNavConfig {
+    /**
+     * Curated default-expansion list (the `local` kind family; external /
+     * command members are parked in a trigger unit). Entries are
+     * config-root-relative folder paths; a listed folder's row expands to
+     * its direct children. Membership says expansion, not existence —
+     * folders off the list stay addressable by path. Optional; default = no
+     * expansion (depth-0 everywhere).
+     */
+    local?: string[];
+    budget?: BudgetConfig;
+    scan?: ScanConfig;
+    /**
+     * Declared entry commands (2026-10-16): full CLI command lines an agent
+     * runs once when starting here, e.g. "mytool instructions". Pure
+     * declarations — any-nav never executes them and never reads their
+     * output; the list faces render one leading procedure line. Optional;
+     * default = none.
+     */
+    commands?: string[];
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function parseConfig(text: string): AnyNavConfig;
+export declare function loadConfigFile(configPath: string): Promise<AnyNavConfig>;
+/**
+ * Normalize one local entry to a clean config-root-relative POSIX path.
+ * The unit is the path — no globs, no numeric depths (Any principle: an
+ * entry states "expand this folder", containment merges trees for free).
+ */
+export declare function normalizeLocalPath(entry: string, where: string): string;

package/dist/config.js

@@ -0,0 +1,186 @@
+/**
+ * Config: parse and strictly validate any-nav.toml.
+ *
+ * The file only states exceptions — scan / local / budget / commands are
+ * the whole key set (framework decision 9, unified list model; commands
+ * joined 2026-10-16, entry-procedures argumentation): scan bounds the
+ * subtree, local curates default expansion, budget guards size, commands
+ * declares entry procedure. Unknown keys are rejected rather than ignored.
+ */
+import { readFile } from 'node:fs/promises';
+import { parse } from 'smol-toml';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+export function parseConfig(text) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(`TOML syntax error: ${err.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('config must be a TOML table');
+    }
+    const obj = raw;
+    const unknownTop = Object.keys(obj).filter((k) => k !== 'local' && k !== 'budget' && k !== 'scan' && k !== 'commands');
+    if (unknownTop.length > 0) {
+        throw new ConfigError(`unknown top-level keys: ${unknownTop.join(', ')}`);
+    }
+    const local = obj.local === undefined ? undefined : parseLocal(obj.local);
+    const budget = obj.budget === undefined ? undefined : parseBudget(obj.budget);
+    const scan = obj.scan === undefined ? undefined : parseScan(obj.scan);
+    const commands = obj.commands === undefined ? undefined : parseCommands(obj.commands);
+    const config = {};
+    if (local !== undefined)
+        config.local = local;
+    if (budget !== undefined)
+        config.budget = budget;
+    if (scan !== undefined)
+        config.scan = scan;
+    if (commands !== undefined)
+        config.commands = commands;
+    return config;
+}
+export async function loadConfigFile(configPath) {
+    const text = await readFile(configPath, 'utf8');
+    return parseConfig(text);
+}
+/**
+ * Normalize one local entry to a clean config-root-relative POSIX path.
+ * The unit is the path — no globs, no numeric depths (Any principle: an
+ * entry states "expand this folder", containment merges trees for free).
+ */
+export function normalizeLocalPath(entry, where) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+        throw new ConfigError(`${where} must be a non-empty path string`);
+    }
+    if (/[*?[\]]/.test(entry)) {
+        throw new ConfigError(`${where} must be a plain path, not a glob: ${entry}`);
+    }
+    const normalized = entry.replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+    if (normalized === '' || normalized === '.') {
+        throw new ConfigError(`${where} must name a folder under the config root, not the root itself: ${entry}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.some((s) => s === '' || s === '.')) {
+        throw new ConfigError(`${where} is not a clean relative path: ${entry}`);
+    }
+    if (segments.includes('..')) {
+        throw new ConfigError(`${where} must stay under the config root: ${entry}`);
+    }
+    if (/^[a-zA-Z]:/.test(normalized) || normalized.startsWith('/')) {
+        throw new ConfigError(`${where} must be config-root-relative, not absolute: ${entry}`);
+    }
+    return segments.join('/');
+}
+function parseLocal(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ConfigError('local must be a non-empty array of folder paths (omit the key for no expansion)');
+    }
+    const seen = new Set();
+    const out = [];
+    raw.forEach((entry, i) => {
+        const normalized = normalizeLocalPath(entry, `local[${i}]`);
+        if (seen.has(normalized)) {
+            throw new ConfigError(`local lists the same path twice: ${normalized}`);
+        }
+        seen.add(normalized);
+        out.push(normalized);
+    });
+    return out;
+}
+function parseScan(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('scan must be a table');
+    }
+    const obj = raw;
+    const known = [
+        'excludeDirs',
+        'excludeFiles',
+        'excludeDotEntries',
+        'respectGitignore',
+        'boundaryExempt',
+        'maxFiles',
+    ];
+    const unknown = Object.keys(obj).filter((k) => !known.includes(k));
+    if (unknown.length > 0) {
+        throw new ConfigError(`unknown keys in scan: ${unknown.join(', ')}`);
+    }
+    const scan = {};
+    for (const key of ['excludeDirs', 'excludeFiles', 'boundaryExempt']) {
+        const value = obj[key];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value) || !value.every((s) => typeof s === 'string' && s.trim() !== '')) {
+            throw new ConfigError(`scan.${key} must be an array of non-empty strings`);
+        }
+        if (value.length === 0) {
+            throw new ConfigError(key === 'boundaryExempt'
+                ? 'scan.boundaryExempt must not be empty — omit the key for no exemptions (an empty list states nothing)'
+                : `scan.${key} must not be empty — omit the key to keep just the built-in defaults (it appends, never replaces)`);
+        }
+        scan[key] = value;
+    }
+    for (const key of ['excludeDotEntries', 'respectGitignore']) {
+        const value = obj[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'boolean') {
+            throw new ConfigError(`scan.${key} must be a boolean`);
+        }
+        scan[key] = value;
+    }
+    if (obj.maxFiles !== undefined) {
+        if (typeof obj.maxFiles !== 'number' || !Number.isInteger(obj.maxFiles) || obj.maxFiles <= 0) {
+            throw new ConfigError('scan.maxFiles must be a positive integer');
+        }
+        scan.maxFiles = obj.maxFiles;
+    }
+    return scan;
+}
+function parseCommands(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ConfigError('commands must be a non-empty array of CLI command lines (omit the key for none)');
+    }
+    const seen = new Set();
+    raw.forEach((entry, i) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            throw new ConfigError(`commands[${i}] must be a non-empty command line string`);
+        }
+        if (seen.has(entry)) {
+            throw new ConfigError(`commands lists the same command twice: ${entry}`);
+        }
+        seen.add(entry);
+    });
+    return raw;
+}
+function parseBudget(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new ConfigError('budget must be a table');
+    }
+    const obj = raw;
+    const unknown = Object.keys(obj).filter((k) => k !== 'share' && k !== 'maxTokens');
+    if (unknown.length > 0) {
+        throw new ConfigError(`unknown keys in budget: ${unknown.join(', ')}`);
+    }
+    const budget = {};
+    if (obj.share !== undefined) {
+        if (typeof obj.share !== 'number' || !(obj.share > 0 && obj.share <= 1)) {
+            throw new ConfigError('budget.share must be a number in (0, 1]');
+        }
+        budget.share = obj.share;
+    }
+    if (obj.maxTokens !== undefined) {
+        if (typeof obj.maxTokens !== 'number' || !Number.isInteger(obj.maxTokens) || obj.maxTokens <= 0) {
+            throw new ConfigError('budget.maxTokens must be a positive integer');
+        }
+        budget.maxTokens = obj.maxTokens;
+    }
+    return budget;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Engine: token estimation and the budget guard.
+ *
+ * Mode forms are retired (framework decision 9, unified list model): the
+ * fragment's shape is the curated `local` view, and budget is a fuse —
+ * over budget warns loudly, never silently. The write-face guard that
+ * acts on it (collapse marker branches, then trim lines) lives in
+ * render's fragmentBodyGuarded; this module only sizes and warns.
+ */
+import type { BudgetConfig } from './config.ts';
+import type { FragmentNode } from './types.ts';
+export interface Exposure {
+    source: {
+        path: string;
+    };
+    estimatedTokens: number;
+    budgetTokens: number;
+    /** True when the fragment exceeds the budget — warned, never silently altered. */
+    overBudget: boolean;
+    /** Human-readable guard reading (declarer-facing; the fragment itself carries no aggregate note). */
+    reason: string;
+}
+export declare const NON_CJK_CHARS_PER_TOKEN = 4;
+export declare const FORMAT_OVERHEAD = 1.25;
+export declare const DEFAULT_SHARE = 0.02;
+export declare const DEFAULT_CONTEXT_TOKENS = 100000;
+export declare function estimateTokens(text: string): number;
+export declare function resolveBudget(budget?: BudgetConfig): number;
+/** Format-agnostic listing used for size estimation: the curated view walked as rows. */
+export declare function canonicalListing(nodes: FragmentNode[]): string;
+export declare function decideExposure(source: {
+    path: string;
+}, nodes: FragmentNode[], budgetTokens: number): Exposure;

package/dist/engine.js

@@ -0,0 +1,43 @@
+// Heuristic constants — thresholds are engineering means, the constraint
+// is the context budget. Calibrate with measurements during M1 usage.
+export const NON_CJK_CHARS_PER_TOKEN = 4;
+export const FORMAT_OVERHEAD = 1.25;
+export const DEFAULT_SHARE = 0.02;
+export const DEFAULT_CONTEXT_TOKENS = 100_000;
+const CJK = /[\u{4E00}-\u{9FFF}\u{3040}-\u{30FF}\u{AC00}-\u{D7AF}]/gu;
+export function estimateTokens(text) {
+    const cjk = [...text.matchAll(CJK)].length;
+    const rest = text.length - cjk;
+    return Math.ceil(cjk + rest / NON_CJK_CHARS_PER_TOKEN);
+}
+export function resolveBudget(budget) {
+    if (budget?.maxTokens !== undefined)
+        return budget.maxTokens;
+    const share = budget?.share ?? DEFAULT_SHARE;
+    return Math.max(1, Math.round(share * DEFAULT_CONTEXT_TOKENS));
+}
+/** Format-agnostic listing used for size estimation: the curated view walked as rows. */
+export function canonicalListing(nodes) {
+    const lines = [];
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            lines.push(`${node.name}${node.kind === 'folder' ? '/' : ''} — ${node.description ?? ''}  (${node.path})`);
+            if (node.children !== undefined)
+                visit(node.children);
+        }
+    };
+    visit(nodes);
+    return lines.join('\n');
+}
+function sized(text) {
+    return Math.ceil(estimateTokens(text) * FORMAT_OVERHEAD);
+}
+export function decideExposure(source, nodes, budgetTokens) {
+    const estimatedTokens = sized(canonicalListing(nodes));
+    const overBudget = estimatedTokens > budgetTokens;
+    const reason = overBudget
+        ? `fragment exceeds the budget (${estimatedTokens} > ${budgetTokens} tokens) — the rows answer stays whole; see 'any-nav help config'`
+        : `fragment fits the budget (${estimatedTokens} ≤ ${budgetTokens} tokens)`;
+    return { source, estimatedTokens, budgetTokens, overBudget, reason };
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAsBA,yEAAyE;AACzE,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAClC,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE9C,MAAM,GAAG,GAAG,yDAAyD,CAAC;AAEtE,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;IAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,uBAAuB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,IAAI,MAAM,EAAE,SAAS,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IAC7D,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,aAAa,CAAC;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,sBAAsB,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,CAAC,KAAqB,EAAQ,EAAE;QAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,WAAW,IAAI,EAAE,MAAM,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;YAC3G,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,CAAC;IACF,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,MAAwB,EACxB,KAAqB,EACrB,YAAoB;IAEpB,MAAM,eAAe,GAAG,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,eAAe,GAAG,YAAY,CAAC;IAClD,MAAM,MAAM,GAAG,UAAU;QACvB,CAAC,CAAC,gCAAgC,eAAe,MAAM,YAAY,mEAAmE;QACtI,CAAC,CAAC,6BAA6B,eAAe,MAAM,YAAY,UAAU,CAAC;IAC7E,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACvE,CAAC"}

package/dist/expand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Expand markers: resolve the config's `local` list into the member set
+ * for the config's OWN view (framework decision 9; strict locality
+ * 2026-10-07: a toml serves only its own folder's direct listing —
+ * re-rooting into a descendant's view is abolished).
+ *
+ * Membership says expansion, not existence: a folder on the list expands
+ * to its direct children wherever its row is rendered within this view;
+ * every folder stays path-addressable regardless. Entries are
+ * config-root-relative and apply only when the toml's own folder is the
+ * listed folder. Deep entries stand alone (transparent corridors,
+ * 2026-10-08): an ancestor that is not itself a member passes only the
+ * member path through — see hasMemberDescendant.
+ */
+import type { NavNode, ScanDiagnostic } from './types.ts';
+/** Member paths for the config's own view — the list as written. */
+export declare function expandMemberSet(local: readonly string[] | undefined): ReadonlySet<string>;
+/**
+ * Whether a non-member folder carries a member descendant — the corridor
+ * test (transparent-corridor ruling, 2026-10-08): such a folder renders
+ * nothing of its own; only the member path passes through it, so a deep
+ * entry never needs its ancestors on the list.
+ */
+export declare function hasMemberDescendant(node: NavNode, members: ReadonlySet<string>): boolean;
+/**
+ * Guard diagnostics for the whole local list, checked once per instance
+ * against the governing config-root scan: a marker naming a path with no
+ * folder in the scanned tree fires a warning — never silent. Scan policy
+ * (excluded subtrees) counts as absent: such a marker can never fire.
+ */
+export declare function expandDiagnostics(local: readonly string[] | undefined, tree: NavNode): ScanDiagnostic[];
+/** Folder lookup by source-relative path; null when absent or not a directory. */
+export declare function findDir(root: NavNode, path: string): NavNode | null;

package/dist/expand.js

@@ -0,0 +1,61 @@
+/** Member paths for the config's own view — the list as written. */
+export function expandMemberSet(local) {
+    const members = new Set();
+    if (local === undefined)
+        return members;
+    for (const entry of local)
+        members.add(entry);
+    return members;
+}
+/**
+ * Whether a non-member folder carries a member descendant — the corridor
+ * test (transparent-corridor ruling, 2026-10-08): such a folder renders
+ * nothing of its own; only the member path passes through it, so a deep
+ * entry never needs its ancestors on the list.
+ */
+export function hasMemberDescendant(node, members) {
+    for (const child of node.children ?? []) {
+        if (child.kind !== 'dir')
+            continue;
+        if (members.has(child.path) || hasMemberDescendant(child, members))
+            return true;
+    }
+    return false;
+}
+/**
+ * Guard diagnostics for the whole local list, checked once per instance
+ * against the governing config-root scan: a marker naming a path with no
+ * folder in the scanned tree fires a warning — never silent. Scan policy
+ * (excluded subtrees) counts as absent: such a marker can never fire.
+ */
+export function expandDiagnostics(local, tree) {
+    if (local === undefined)
+        return [];
+    const diagnostics = [];
+    for (const entry of local) {
+        if (findDir(tree, entry) === null) {
+            diagnostics.push({
+                code: 'expand-path-missing',
+                severity: 'warning',
+                message: `local entry '${entry}' has no folder in the scanned tree (missing or excluded by scan policy); it will never expand.`,
+                path: entry,
+                audience: 'maintainer',
+            });
+        }
+    }
+    return diagnostics;
+}
+/** Folder lookup by source-relative path; null when absent or not a directory. */
+export function findDir(root, path) {
+    if (path === '')
+        return root;
+    let node = root;
+    for (const segment of path.split('/')) {
+        const next = node.children?.find((c) => c.kind === 'dir' && c.name === segment);
+        if (!next)
+            return null;
+        node = next;
+    }
+    return node;
+}
+//# sourceMappingURL=expand.js.map

package/dist/expand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.js","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,KAAoC;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,KAAK;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,OAA4B;IAC7E,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;YAAE,SAAS;QACnC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;IAClF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAoC,EAAE,IAAa;IACnF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,qBAAqB;gBAC3B,QAAQ,EAAE,SAAS;gBACnB,OAAO,EAAE,gBAAgB,KAAK,iGAAiG;gBAC/H,IAAI,EAAE,KAAK;gBACX,QAAQ,EAAE,YAAY;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,OAAO,CAAC,IAAa,EAAE,IAAY;IACjD,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,IAAI,GAAY,IAAI,CAAC;IACzB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/facade.d.ts

@@ -0,0 +1,93 @@
+import type { AnyNavConfig } from './config.ts';
+import type { DescriptionProvider } from '@any-nav/scan';
+import { type Exposure } from './engine.ts';
+import { type NavFormat } from './render.ts';
+import type { ListView, NavCandidateFeed, NavLocator, NavSource, RenderedFragment, SearchHit } from './types.ts';
+/** Reserved (v1.x) so index/description caches never make core write. */
+export interface CacheStore {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+}
+/**
+ * Entry-command execution port (commands key, full-render ruling
+ * 2026-10-16): core never spawns — the adapter injects the runner, core
+ * consumes the captured stdout and renders it canonically. cwd is the
+ * governing toml's directory (the tool's project context).
+ */
+export type CommandRunner = (command: string, ctx: {
+    cwd: string;
+}) => Promise<{
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export interface CreateAnyNavInput {
+    /** Config object, or a path to any-nav.toml (adapters decide discovery). */
+    config: AnyNavConfig | {
+        configPath: string;
+    };
+    /** Base directory for resolving relative source paths when passing an
+     *  object; a config file resolves against its own directory. */
+    cwd: string;
+    /** Extra axis-B formats; built-ins are always registered. */
+    formats?: NavFormat[];
+    descriptionProvider?: DescriptionProvider;
+    cache?: CacheStore;
+}
+export interface AnyNav {
+    /** The scanned sources — the config root itself (implicit single source). */
+    sources(): NavSource[];
+    /** The budget-guard reading for one source (warns, never collapses here). */
+    decideExposure(source: NavSource): Exposure;
+    render(exposure: Exposure, formatId: string): RenderedFragment;
+    /** Pure splice of a fragment into existing content; the adapter writes it. */
+    materialize(currentContent: string, fragment: RenderedFragment): string;
+    /**
+     * The product face, pinned form: `dir` defaults to '.', any folder
+     * under this instance's config root (the boundary survives for
+     * --config-style pinning). The discovery form — nearest toml at or
+     * above the listed folder, pure defaults when none — is `listFolder`;
+     * adapters that don't pin should call that instead.
+     */
+    list(dir?: string, query?: {
+        depth?: number;
+        commandRunner?: CommandRunner;
+    }): Promise<ListView>;
+    search(query: {
+        text: string;
+        limit?: number;
+    }): SearchHit[];
+    read(locator: NavLocator): Promise<{
+        content: string;
+        mediaType: 'text/markdown';
+    }>;
+    /**
+     * Candidate feed (mode ④ supply face): the curated tree
+     * flattened into word-picker candidates, every path re-rooted onto
+     * baseDir. Snapshot semantics — freshness is the consumer's rebuild
+     * policy. maxFiles caps the feed loudly (truncated + omittedCount).
+     */
+    candidates(query: {
+        baseDir: string;
+        maxFiles?: number;
+    }): NavCandidateFeed;
+}
+export declare function createAnyNav(input: CreateAnyNavInput): Promise<AnyNav>;
+/** A listing plus the config that actually governed it (null = defaults). */
+export interface FolderListing extends ListView {
+    governingConfig: string | null;
+}
+/**
+ * The product face, discovery form (2026-10-07 optionality ruling):
+ * governance = the nearest any-nav.toml at or above `dir` — the folder's
+ * own toml if it carries one, else the closest ancestor's, else pure
+ * defaults. `configPath` pins a specific config instead (paths outside
+ * its root then error — the pinned boundary). cwd never participates.
+ */
+export declare function listFolder(dir: string, query?: {
+    configPath?: string;
+    depth?: number;
+    commandRunner?: CommandRunner;
+}): Promise<FolderListing>;