@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/core/repo-map/build.js

@@ -0,0 +1,125 @@
+/**
+ * Repo-map build orchestrator — Leak L28 (2026-05-27).
+ *
+ * Single entry point that the CLI command + the engine boot path both
+ * call. Wires the scanner → extractor → cache → formatter pipeline
+ * together and surfaces a structured result the caller can render or
+ * inject without knowing the inner module shapes.
+ *
+ * The orchestrator is split out от cache.ts and the command handler
+ * so:
+ *
+ *   1. The CLI command + the engine system-prompt injector share one
+ *      code path. Drift between the two would silently change what
+ *      the model sees vs. what the operator sees.
+ *
+ *   2. The spec can exercise the full pipeline against a temp dir
+ *      without mounting Ink or the engine.
+ *
+ * Pure-ish: reads from disk (the source files + the cache), but never
+ * mutates anything outside `.pugi/repo-map.json` and never logs. The
+ * caller decides whether к persist the cache (`writeCache: true`) or
+ * к compute the map в-memory (`writeCache: false` — useful for
+ * non-interactive `--json` invocations on read-only fs).
+ */
+import { readFileSync } from 'node:fs';
+import { loadPugiIgnore } from '../context/pugiignore.js';
+import { defaultCachePath, diffCacheAgainstScan, mergeCache, readRepoMapCache, writeRepoMapCache, } from './cache.js';
+import { extractFromFile } from './extractor.js';
+import { scanRepoForMap } from './scanner.js';
+import { formatRepoMap } from './formatter.js';
+/**
+ * Run the full pipeline. Returns a structured verdict; never throws.
+ * The 'too-large' branch fires when the workspace exceeds the file
+ * cap — callers surface a hint к the operator ("repo too large for
+ * inline map — try .pugiignore") and skip injection.
+ */
+export function buildRepoMap(options) {
+    const root = options.root;
+    const refresh = options.refresh === true;
+    const writeCache = options.writeCache !== false;
+    const cachePath = options.cachePath ?? defaultCachePath(root);
+    const readFile = options.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const ignore = loadPugiIgnore(root);
+    const scan = scanRepoForMap({ root, ignore });
+    if (!scan.ok) {
+        return {
+            ok: false,
+            root,
+            reason: scan.skipped.reason,
+            walked: scan.skipped.walked,
+        };
+    }
+    const prior = refresh ? null : readCacheOrNull(cachePath);
+    const diff = diffCacheAgainstScan(prior, scan.files);
+    const freshExtracts = new Map();
+    for (const file of diff.toRebuild) {
+        let source;
+        try {
+            source = readFile(file.absPath);
+        }
+        catch {
+            // File vanished или became unreadable mid-build — skip. The
+            // cache layer will just not have an entry for it; next refresh
+            // picks it up if it reappears.
+            continue;
+        }
+        freshExtracts.set(file.relPath, extractFromFile(file, source));
+    }
+    const cache = mergeCache({
+        root,
+        prior,
+        scanned: scan.files,
+        freshExtracts,
+    });
+    let cacheWritten = false;
+    if (writeCache) {
+        const writeResult = writeRepoMapCache(cachePath, cache);
+        cacheWritten = writeResult.ok;
+    }
+    // Surface the extracts в the same order the scanner produced (sorted
+    // by POSIX path) so callers iterating the result render deterministic
+    // output. The formatter does its own priority sort, so a different
+    // order here would only affect callers that iterate manually.
+    const extracts = [];
+    for (const file of scan.files) {
+        const entry = cache.entries[file.relPath];
+        if (entry)
+            extracts.push(entry.extract);
+    }
+    return {
+        ok: true,
+        root,
+        cache,
+        extracts,
+        scanStats: scan.stats,
+        diffStats: {
+            rebuilt: diff.toRebuild.length,
+            reused: diff.reuse.length,
+            dropped: diff.toDrop.length,
+        },
+        cachePath,
+        cacheWritten,
+    };
+}
+/**
+ * Convenience wrapper: build + format в one call. The engine boot
+ * path uses this so it does not have к know the formatter shape.
+ */
+export function buildAndFormatRepoMap(options) {
+    const build = buildRepoMap(options);
+    if (!build.ok)
+        return { build };
+    const format = formatRepoMap(build.extracts, {
+        maxBytes: options.formatBytesCap,
+        omitHeader: options.omitHeader,
+    });
+    return { build, format };
+}
+function readCacheOrNull(path) {
+    const verdict = readRepoMapCache(path);
+    if (verdict.ok)
+        return verdict.cache;
+    return null;
+}
+//# sourceMappingURL=build.js.map

package/dist/core/repo-map/cache.js

@@ -0,0 +1,185 @@
+/**
+ * Repo-map cache — Leak L28 (2026-05-27).
+ *
+ * Persists the result of the scan + extract passes к
+ * `.pugi/repo-map.json` so subsequent boots reuse the symbol table
+ * without re-walking the workspace. The cache key is `(mtimeMs, size)`
+ * per file, matching the heuristic used by Node's own native
+ * `node:fs.statSync` cache and Git's index format. A file whose mtime
+ * AND size match the cached entry is presumed unchanged; otherwise the
+ * extractor re-runs against the fresh contents.
+ *
+ * Why not a content hash:
+ *
+ *   The α6.5 file-cache module already hashes by content for the
+ *   working-set heuristic, and the L28 use case is different — repo-
+ *   map invalidation is "should we re-parse" not "is this content
+ *   identical to the last cached version". A content-hash sweep would
+ *   re-read every source file on every boot, defeating the purpose of
+ *   a cache. mtime + size matches the cost profile (one stat call per
+ *   file, no read) while catching every realistic edit pattern
+ *   (editors universally update mtime; even `truncate` updates size).
+ *
+ * Why JSON not SQLite:
+ *
+ *   The α6.5 index-store ships as a flat JSON blob and parses в <50 ms
+ *   for typical repos (~2000 files); we match the format так the
+ *   doctor probe + cabinet sync tools can read repo-map.json without
+ *   spinning up a SQLite driver. The blob is gzip-friendly if a future
+ *   sprint wants к ship it across the wire.
+ *
+ * Schema versioning: every cache entry carries `schemaVersion`. When
+ * the extractor surface changes (new symbol kinds, new summary
+ * format), bump the constant and existing caches are dropped on the
+ * next boot — same pattern as the migration runner.
+ *
+ * Pure-ish surface: reads / writes use `node:fs` sync, no logging.
+ * Errors are converted к structured results so the caller can decide
+ * whether к surface them or fall back к a cold rebuild.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Cache format version. Bump when:
+ *   - `RepoMapSymbol` adds / renames a field
+ *   - `RepoMapFileExtract` adds / renames a field
+ *   - The mtime + size invalidation contract changes
+ *
+ * Old caches with a mismatched version are dropped on read.
+ */
+export const REPO_MAP_CACHE_VERSION = 1;
+/**
+ * Default location for the workspace cache file. Mirrors the rest of
+ * the `.pugi/` convention: `<workspace>/.pugi/repo-map.json`.
+ */
+export function defaultCachePath(workspaceRoot) {
+    return join(workspaceRoot, '.pugi', 'repo-map.json');
+}
+/**
+ * Read the cache file from disk. Returns a structured verdict; never
+ * throws. The 'missing' branch is the cold-boot happy path. The
+ * 'parse-error' branch signals corruption — the caller drops the
+ * cache and rebuilds. The 'version-mismatch' branch fires after an
+ * extractor schema bump.
+ */
+export function readRepoMapCache(path) {
+    if (!existsSync(path)) {
+        return { ok: false, reason: 'missing' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return { ok: false, reason: 'parse-error' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'parse-error' };
+    }
+    if (!isCacheShape(parsed)) {
+        return { ok: false, reason: 'parse-error' };
+    }
+    if (parsed.schemaVersion !== REPO_MAP_CACHE_VERSION) {
+        return { ok: false, reason: 'version-mismatch' };
+    }
+    return { ok: true, cache: parsed };
+}
+/**
+ * Write the cache atomically (write-then-rename) so a concurrent
+ * reader never sees a half-flushed JSON blob. Errors are surfaced as
+ * a structured boolean so the caller can decide whether к escalate —
+ * the engine boot path silently swallows write failures because
+ * repo-map is a best-effort enrichment.
+ */
+export function writeRepoMapCache(path, cache) {
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const body = JSON.stringify(cache, null, 2) + '\n';
+        const tmp = path + '.tmp';
+        writeFileSync(tmp, body, { encoding: 'utf8' });
+        // Atomic rename. `fs.renameSync` is atomic on POSIX + on NTFS when
+        // src + dst live on the same volume, which is always true for
+        // `.pugi/`-local writes.
+        renameSync(tmp, path);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function diffCacheAgainstScan(prior, scanned) {
+    const toRebuild = [];
+    const reuse = [];
+    const seen = new Set();
+    for (const file of scanned) {
+        seen.add(file.relPath);
+        const entry = prior?.entries[file.relPath];
+        if (!entry
+            || entry.mtimeMs !== file.mtimeMs
+            || entry.sizeBytes !== file.sizeBytes) {
+            toRebuild.push(file);
+        }
+        else {
+            reuse.push(file.relPath);
+        }
+    }
+    const toDrop = [];
+    if (prior) {
+        for (const key of Object.keys(prior.entries)) {
+            if (!seen.has(key))
+                toDrop.push(key);
+        }
+    }
+    return { toRebuild, toDrop, reuse };
+}
+/**
+ * Stitch a fresh cache object together from the prior surviving
+ * entries + the newly-extracted ones. Pure helper — the caller is
+ * responsible for actually writing the result.
+ */
+export function mergeCache(args) {
+    const { root, prior, scanned, freshExtracts } = args;
+    const entries = {};
+    for (const file of scanned) {
+        const fresh = freshExtracts.get(file.relPath);
+        if (fresh) {
+            entries[file.relPath] = {
+                mtimeMs: file.mtimeMs,
+                sizeBytes: file.sizeBytes,
+                extract: fresh,
+            };
+            continue;
+        }
+        const priorEntry = prior?.entries[file.relPath];
+        if (priorEntry) {
+            entries[file.relPath] = priorEntry;
+        }
+    }
+    return {
+        schemaVersion: REPO_MAP_CACHE_VERSION,
+        root,
+        builtAtMs: args.nowMs ?? Date.now(),
+        entries,
+    };
+}
+function isCacheShape(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.schemaVersion === 'number'
+        && typeof v.root === 'string'
+        && typeof v.builtAtMs === 'number'
+        && typeof v.entries === 'object'
+        && v.entries !== null);
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/repo-map/extractor.js

@@ -0,0 +1,254 @@
+/**
+ * Maximum symbols carried per file. The formatter further truncates к
+ * the 2 KB injection budget, but capping per-file here keeps a single
+ * giant `index.ts` from monopolising the map.
+ */
+export const MAX_SYMBOLS_PER_FILE = 50;
+/**
+ * Extract symbols + summary from a single file. `kind` is dispatched
+ * on the lowercased extension. Files with an unrecognised extension
+ * return an empty symbol list with `summary: null` — the scanner
+ * already filtered by `SUPPORTED_EXTENSIONS` so this branch is mostly
+ * defensive (test fixtures sometimes pass `.txt`).
+ */
+export function extractFromFile(file, source) {
+    switch (file.ext) {
+        case '.ts':
+        case '.tsx':
+        case '.js':
+        case '.jsx':
+        case '.mjs':
+        case '.cjs':
+            return extractFromTsLike(file, source);
+        case '.md':
+        case '.mdx':
+            return extractFromMarkdown(file, source);
+        default:
+            return {
+                relPath: file.relPath,
+                ext: file.ext,
+                summary: null,
+                symbols: [],
+            };
+    }
+}
+/* ------------------------- TS / JS extraction ------------------------- */
+/**
+ * Identifier pattern. We use the ASCII subset (letters/digits/`$`/`_`)
+ * rather than the full unicode ID start/continue range because the
+ * unicode tables would inflate the bundle by ~50 KB for zero benefit
+ * — Pugi's customers are typing English identifiers. Unicode names
+ * in source still PARSE (they just do not surface в the repo-map);
+ * the formatter degrades gracefully.
+ */
+const IDENT = '[A-Za-z_$][A-Za-z0-9_$]*';
+/**
+ * Top-level declaration shapes:
+ *
+ *   export? (default)? class Foo { ... }
+ *   export? (default)? function foo() { ... }
+ *   export? (default)? async function foo() { ... }
+ *   export? (const|let|var) foo = (args) => { ... }
+ *   export? (const|let|var) foo = async (args) => { ... }
+ *   export? (const|let|var) foo = function (args) { ... }
+ *   export? interface Foo { ... }
+ *   export? type Foo = ...
+ *   export? enum Foo { ... }
+ *
+ * The patterns anchor on start-of-line (`^` with the `m` flag) so they
+ * never match nested declarations inside a class body or a closure.
+ * That intentionally loses precision for module-level IIFEs (e.g.
+ * `;(function init() {})()`), but the L28 budget already drops nested
+ * symbols, so the loss is invisible to the operator.
+ */
+const TS_CLASS_RE = new RegExp(`^(export\\s+(?:default\\s+)?(?:abstract\\s+)?)?class\\s+(${IDENT})`, 'gm');
+const TS_FUNCTION_RE = new RegExp(`^(export\\s+(?:default\\s+)?)?(?:async\\s+)?function\\s*\\*?\\s+(${IDENT})`, 'gm');
+/**
+ * Arrow / function-expression `const|let|var foo = (...) => ...` shape.
+ * The optional type annotation between the identifier and the `=` is
+ * non-trivial because TS allows `(...) => ...` IN the annotation
+ * itself ("export const x: () => number = () => 1"). We allow `=>`
+ * as a unit inside the annotation by matching the char class
+ * `(?:=>|[^=\\n])*?` which consumes either an arrow token OR a
+ * non-`=` char; the trailing assignment `=` is then the first
+ * standalone `=` (`(?!>)`) on the line. The match tail (`=>` arrow,
+ * parenthesised arg list, generic, or `function` keyword) anchors
+ * the RHS so plain `const x = 1` does not surface as a function.
+ */
+const TS_ARROW_RE = new RegExp(`^(export\\s+)?(?:const|let|var)\\s+(${IDENT})\\b(?:=>|[^=\\n])*?=(?!>)\\s*(?:async\\s*)?(?:\\(|<|function\\b)`, 'gm');
+const TS_INTERFACE_RE = new RegExp(`^(export\\s+)?interface\\s+(${IDENT})`, 'gm');
+const TS_TYPE_RE = new RegExp(`^(export\\s+)?type\\s+(${IDENT})\\s*[=<]`, 'gm');
+const TS_ENUM_RE = new RegExp(`^(export\\s+)?(?:const\\s+)?enum\\s+(${IDENT})`, 'gm');
+/**
+ * Lead JSDoc / TSDoc block: `/** ... *​/` at the start of the file or
+ * preceded only by whitespace + import statements. We pick the first
+ * non-empty narrative line — the convention across Pugi's own codebase
+ * is that the headline sentence sits at the top of the block.
+ */
+const LEAD_DOC_RE = /\/\*\*([\s\S]*?)\*\//;
+function extractFromTsLike(file, source) {
+    const symbols = [];
+    // We compute line numbers lazily by counting newlines в `source`
+    // up к each match's `.index`. Building a single prefix-newline
+    // array once is cheaper than calling `source.slice(0, idx).split`
+    // per match.
+    const lineStarts = computeLineStarts(source);
+    const lineFor = (offset) => binarySearchLine(lineStarts, offset);
+    const pushMatches = (regex, kind, exportIndex, nameIndex) => {
+        regex.lastIndex = 0;
+        let match;
+        while ((match = regex.exec(source)) !== null) {
+            if (symbols.length >= MAX_SYMBOLS_PER_FILE)
+                return;
+            const name = match[nameIndex];
+            if (!name)
+                continue;
+            const exported = Boolean(match[exportIndex]);
+            symbols.push({
+                name,
+                kind,
+                exported,
+                line: lineFor(match.index),
+            });
+        }
+    };
+    pushMatches(TS_CLASS_RE, 'class', 1, 2);
+    pushMatches(TS_FUNCTION_RE, 'function', 1, 2);
+    pushMatches(TS_ARROW_RE, 'const', 1, 2);
+    pushMatches(TS_INTERFACE_RE, 'interface', 1, 2);
+    pushMatches(TS_TYPE_RE, 'type', 1, 2);
+    pushMatches(TS_ENUM_RE, 'enum', 1, 2);
+    // Dedupe by `name + kind` — `export const x = function x() {}` would
+    // otherwise show up twice (arrow regex + function regex). Keep the
+    // earlier one (lowest line) and the exported flag if either match
+    // saw it.
+    const dedup = new Map();
+    for (const sym of symbols) {
+        const key = `${sym.kind}::${sym.name}`;
+        const prior = dedup.get(key);
+        if (!prior) {
+            dedup.set(key, sym);
+        }
+        else if (sym.line < prior.line) {
+            dedup.set(key, { ...sym, exported: prior.exported || sym.exported });
+        }
+        else if (sym.exported && !prior.exported) {
+            dedup.set(key, { ...prior, exported: true });
+        }
+    }
+    const deduped = Array.from(dedup.values()).sort((a, b) => a.line - b.line);
+    return {
+        relPath: file.relPath,
+        ext: file.ext,
+        summary: extractLeadDocSummary(source),
+        symbols: deduped.slice(0, MAX_SYMBOLS_PER_FILE),
+    };
+}
+/**
+ * Extract the first narrative sentence from a leading JSDoc block.
+ * Returns null when no block is present in the first 4 KB of the
+ * file (cap protects against huge generated headers).
+ */
+export function extractLeadDocSummary(source) {
+    const window = source.slice(0, 4096);
+    const match = LEAD_DOC_RE.exec(window);
+    if (!match)
+        return null;
+    const body = match[1] ?? '';
+    for (const rawLine of body.split('\n')) {
+        const line = rawLine.replace(/^\s*\*\s?/u, '').trim();
+        if (line.length === 0)
+            continue;
+        // Skip the `@param` / `@returns` / `@deprecated` block prefixes —
+        // the summary is the prose lead, not the tag soup.
+        if (line.startsWith('@'))
+            continue;
+        // Truncate at 120 chars so a 5-line philosophical preamble does
+        // not blow the formatter's column budget.
+        return line.length > 120 ? line.slice(0, 117) + '...' : line;
+    }
+    return null;
+}
+/* -------------------------- Markdown extraction -------------------------- */
+const MD_HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/gm;
+function extractFromMarkdown(file, source) {
+    const symbols = [];
+    const lineStarts = computeLineStarts(source);
+    MD_HEADING_RE.lastIndex = 0;
+    let match;
+    while ((match = MD_HEADING_RE.exec(source)) !== null) {
+        if (symbols.length >= MAX_SYMBOLS_PER_FILE)
+            break;
+        const level = match[1]?.length ?? 0;
+        // Only H1 + H2 surface — the L28 budget cannot afford H3+ depth
+        // and the operator-readable map is meant к answer "what is в
+        // this file" not "what is the full TOC".
+        if (level > 2)
+            continue;
+        const name = (match[2] ?? '').trim();
+        if (!name)
+            continue;
+        symbols.push({
+            name,
+            kind: 'heading',
+            exported: true,
+            line: binarySearchLine(lineStarts, match.index),
+        });
+    }
+    return {
+        relPath: file.relPath,
+        ext: file.ext,
+        summary: extractMarkdownSummary(source),
+        symbols,
+    };
+}
+/**
+ * First non-heading paragraph in the markdown file. Truncated к 120
+ * chars like the JSDoc summary so the formatter stays single-line.
+ */
+export function extractMarkdownSummary(source) {
+    const lines = source.split('\n').slice(0, 200);
+    let sawHeading = false;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#')) {
+            sawHeading = true;
+            continue;
+        }
+        // Skip front-matter delimiters and HTML/markdown directives.
+        if (line === '---' || line.startsWith('<!--'))
+            continue;
+        if (!sawHeading) {
+            // Pre-heading body — usually front-matter content. Skip it; the
+            // first POST-heading paragraph is the operator-facing summary.
+            continue;
+        }
+        return line.length > 120 ? line.slice(0, 117) + '...' : line;
+    }
+    return null;
+}
+/* ----------------------------- helpers ----------------------------- */
+function computeLineStarts(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i += 1) {
+        if (source.charCodeAt(i) === 10 /* \n */)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function binarySearchLine(starts, offset) {
+    // Returns 1-based line number.
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+//# sourceMappingURL=extractor.js.map