@pugi/cli 0.1.0-beta.23 → 0.1.0-beta.25

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

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

@@ -0,0 +1,145 @@
+/**
+ * Default byte cap for the engine system-prompt injection. The L28
+ * spec calls for 2000 tokens; conservatively that is ~8 KB of UTF-8
+ * (rough Claude tokeniser ratio: ~4 chars per token). We cap at 8 KB
+ * so the formatted block stays under the token budget across every
+ * supported model family without per-model accounting.
+ */
+export const DEFAULT_FORMAT_BYTES_CAP = 8 * 1024;
+/**
+ * Maximum symbols per row. The engine row format is:
+ *
+ *   `- path/to/file.ts — summary line — exports: Foo(class), bar(fn)`
+ *
+ * Beyond 6 symbols the row grows past the readable column budget and
+ * the additional names rarely move the needle for the model — the
+ * exports tail is signal-bearing only for the first few entries
+ * anyway (`index.ts` re-exports tend к pile up).
+ */
+export const MAX_SYMBOLS_PER_ROW = 6;
+/**
+ * Render the repo-map text. The implementation is intentionally split
+ * into:
+ *
+ *   - `prioritise(...)` — pure sort + filter, fully testable in
+ *     isolation, no I/O of any kind.
+ *   - `renderRow(...)`  — one file's row, byte-counted.
+ *   - main loop — assembles header + rows + footer, respecting cap.
+ *
+ * The split lets the spec assert each stage in isolation (priority
+ * order, single-row shape, truncation arithmetic).
+ */
+export function formatRepoMap(extracts, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_FORMAT_BYTES_CAP;
+    const omitHeader = options.omitHeader === true;
+    const prioritised = prioritise(extracts);
+    const header = omitHeader
+        ? ''
+        : `## Repo map\n\n${prioritised.length} source files indexed.\n\n`;
+    const headerBytes = byteLength(header);
+    if (headerBytes >= maxBytes) {
+        // Cap is smaller than even the header — emit nothing rather than
+        // a truncated header that the engine cannot parse.
+        return {
+            text: '',
+            filesIncluded: 0,
+            filesTotal: extracts.length,
+            bytes: 0,
+            truncated: extracts.length > 0,
+        };
+    }
+    const rows = [];
+    let bytesUsed = headerBytes;
+    let filesIncluded = 0;
+    let truncated = false;
+    for (let i = 0; i < prioritised.length; i += 1) {
+        const row = renderRow(prioritised[i]);
+        const rowBytes = byteLength(row);
+        // Reserve space for the footer (`\n... N more files\n`). We
+        // overestimate at 64 bytes — the exact number depends on the
+        // file count digits but 64 covers any realistic case.
+        const footerReserve = i + 1 < prioritised.length ? 64 : 0;
+        if (bytesUsed + rowBytes + footerReserve > maxBytes) {
+            truncated = true;
+            break;
+        }
+        rows.push(row);
+        bytesUsed += rowBytes;
+        filesIncluded += 1;
+    }
+    let text = header + rows.join('');
+    if (truncated) {
+        const omitted = prioritised.length - filesIncluded;
+        text += `\n... ${omitted} more file${omitted === 1 ? '' : 's'}\n`;
+    }
+    return {
+        text,
+        filesIncluded,
+        filesTotal: extracts.length,
+        bytes: byteLength(text),
+        truncated,
+    };
+}
+/* ----------------------------- helpers ----------------------------- */
+/**
+ * Sort the extracts by (exported-symbol count desc, path asc). The
+ * engine cares about the public surface; a file with 12 exported
+ * symbols carries more signal than 50 private helpers.
+ */
+export function prioritise(extracts) {
+    return [...extracts].sort((a, b) => {
+        const expA = countExports(a);
+        const expB = countExports(b);
+        if (expA !== expB)
+            return expB - expA;
+        return a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0;
+    });
+}
+function countExports(extract) {
+    let n = 0;
+    for (const sym of extract.symbols)
+        if (sym.exported)
+            n += 1;
+    return n;
+}
+/**
+ * Render a single file row. Format:
+ *
+ *   `- path/to/file.ts — summary — exports: Foo(class), bar(fn), Baz(type)`
+ *
+ * When there are no exported symbols, the `exports:` tail is dropped.
+ * When there is no summary, the dash separator is dropped.
+ */
+export function renderRow(extract) {
+    const exported = extract.symbols.filter((s) => s.exported);
+    const symbolsTail = exported.length > 0
+        ? ` — exports: ${formatSymbolList(exported.slice(0, MAX_SYMBOLS_PER_ROW))}`
+        : '';
+    const summaryTail = extract.summary ? ` — ${extract.summary}` : '';
+    return `- ${extract.relPath}${summaryTail}${symbolsTail}\n`;
+}
+function formatSymbolList(symbols) {
+    return symbols.map((s) => `${s.name}(${shortKind(s.kind)})`).join(', ');
+}
+function shortKind(kind) {
+    switch (kind) {
+        case 'function':
+            return 'fn';
+        case 'class':
+            return 'class';
+        case 'interface':
+            return 'iface';
+        case 'type':
+            return 'type';
+        case 'enum':
+            return 'enum';
+        case 'const':
+            return 'const';
+        case 'heading':
+            return 'h';
+    }
+}
+function byteLength(s) {
+    return Buffer.byteLength(s, 'utf8');
+}
+//# sourceMappingURL=formatter.js.map