@any-nav/scan 0.1.0 → 0.2.0

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

@@ -33,16 +33,18 @@ export interface NavNode {
     children?: NavNode[];
     /**
      * Dir nodes only (the root included): description from the directory's
-     * `_category_.yml/.yaml/.json` sidecar when it carries a `description` key
-     * (the exception channel for release-face READMEs), else the extraction
-     * from the directory's own README.md (routes folder-representative
-     * semantics). Absent when neither carries one.
+     * 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 (ADR-0010: routes traversal semantics; update
- * 2026-10-07: exclude lists are additive). All keys default — the config
+ * 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 {
@@ -54,6 +56,16 @@ export interface ScanConfig {
     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;
 }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@any-nav/scan",
-  "version": "0.1.0",
-  "description": "Any-Nav scan core: the zero-dependency engine that walks a Markdown folder into a nav tree under the routes traversal semantics (exclusions, gitignore inheritance, a loud maxFiles budget, folder descriptions). Embedders consume this directly; @any-nav/core composes it with curation, render, and search.",
+  "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",
@@ -11,7 +15,11 @@
     "CHANGELOG.md"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@catheadowl/pathscope": "^0.1.1"
   },
   "keywords": [
     "agent",

package/dist/gitignore.d.ts

@@ -1,9 +0,0 @@
-export interface GitignoreRule {
-    baseDir: string;
-    pattern: string;
-    negated: boolean;
-    directoryOnly: boolean;
-}
-export declare function readInheritedGitignoreRules(root: string, scanRoot: string): Promise<GitignoreRule[]>;
-export declare function readGitignoreRules(dir: string): Promise<GitignoreRule[]>;
-export declare function isGitignored(filePath: string, isDirectory: boolean, rules: readonly GitignoreRule[]): boolean;

package/dist/gitignore.js

@@ -1,128 +0,0 @@
-/**
- * gitignore-aware traversal support, ported verbatim from the routes module
- * (dsh-plugin-dev/extras/modules/routes/src/gitignore.ts, ADR-0010: port,
- * don't rewrite). Known subset boundary (routes-documented): `!` re-includes
- * inside one file are honored; cross-file re-include of an ignored path is
- * not — revisit via a port if real corpora hit it (ADR-0010 reversal).
- */
-import { readFile } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
-export async function readInheritedGitignoreRules(root, scanRoot) {
-    const rootPath = resolve(root);
-    const scanRootPath = resolve(scanRoot);
-    const relativeScanRoot = normalizeSlash(relative(rootPath, scanRootPath));
-    const segments = relativeScanRoot && !relativeScanRoot.startsWith('..')
-        ? relativeScanRoot.split('/').filter(Boolean)
-        : [];
-    const dirs = [rootPath];
-    for (let index = 0; index < segments.length; index += 1) {
-        dirs.push(join(rootPath, ...segments.slice(0, index + 1)));
-    }
-    const rules = await Promise.all(dirs.map((dir) => readGitignoreRules(dir)));
-    return rules.flat();
-}
-export async function readGitignoreRules(dir) {
-    let content;
-    try {
-        content = await readFile(join(dir, '.gitignore'), 'utf8');
-    }
-    catch {
-        return [];
-    }
-    return content
-        .split(/\r?\n/u)
-        .map((line) => parseGitignoreLine(dir, line))
-        .filter((rule) => rule !== null);
-}
-export function isGitignored(filePath, isDirectory, rules) {
-    let ignored = false;
-    // Perf (2026-10-20, semantics identical): one relative() per distinct
-    // baseDir per call — a typical tree carries many rules from the same
-    // ancestor .gitignore, and the path result is rule-invariant.
-    const relativeByBaseDir = new Map();
-    for (const rule of rules) {
-        if (rule.directoryOnly && !isDirectory)
-            continue;
-        if (!matchesRule(filePath, rule, relativeByBaseDir))
-            continue;
-        ignored = !rule.negated;
-    }
-    return ignored;
-}
-function parseGitignoreLine(baseDir, rawLine) {
-    let line = rawLine.trim();
-    if (!line || line.startsWith('#'))
-        return null;
-    let negated = false;
-    if (line.startsWith('!')) {
-        negated = true;
-        line = line.slice(1).trim();
-    }
-    if (!line)
-        return null;
-    const directoryOnly = line.endsWith('/');
-    line = line.replace(/^\/+/u, '').replace(/\/+$/u, '');
-    if (!line)
-        return null;
-    return {
-        baseDir,
-        pattern: normalizeSlash(line),
-        negated,
-        directoryOnly,
-    };
-}
-function matchesRule(filePath, rule, relativeByBaseDir) {
-    let relativePath = relativeByBaseDir.get(rule.baseDir);
-    if (relativePath === undefined) {
-        relativePath = normalizeSlash(relative(rule.baseDir, filePath));
-        relativeByBaseDir.set(rule.baseDir, relativePath);
-    }
-    if (!relativePath || relativePath.startsWith('..'))
-        return false;
-    if (!rule.pattern.includes('/')) {
-        return relativePath.split('/').some((part) => matchesGlob(part, rule.pattern));
-    }
-    return matchesGlob(relativePath, rule.pattern);
-}
-/** Compiled-glob memo (perf 2026-10-20, semantics identical): the regex
- * depends only on the pattern, and a scan checks the same handful of
- * patterns once per entry — compiling per check was ~70% of large-tree
- * scan CPU. Patterns are few and bounded by the corpus's .gitignore lines. */
-const globRegexCache = new Map();
-function matchesGlob(value, pattern) {
-    let regex = globRegexCache.get(pattern);
-    if (regex === undefined) {
-        regex = new RegExp(`^${globToRegex(pattern)}$`, 'u');
-        globRegexCache.set(pattern, regex);
-    }
-    return regex.test(value);
-}
-function globToRegex(pattern) {
-    let regex = '';
-    for (let index = 0; index < pattern.length; index += 1) {
-        const char = pattern[index];
-        const next = pattern[index + 1];
-        if (char === '*' && next === '*') {
-            regex += '.*';
-            index += 1;
-            continue;
-        }
-        if (char === '*') {
-            regex += '[^/]*';
-            continue;
-        }
-        if (char === '?') {
-            regex += '[^/]';
-            continue;
-        }
-        regex += escapeRegex(char);
-    }
-    return regex;
-}
-function escapeRegex(value) {
-    return value.replace(/[|\\{}()[\]^$+*?.]/gu, '\\$&');
-}
-function normalizeSlash(value) {
-    return value.replace(/\\/gu, '/');
-}
-//# sourceMappingURL=gitignore.js.map

package/dist/gitignore.js.map

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