@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

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

package/dist/core/repo-map/page-rank.js

@@ -0,0 +1,105 @@
+/**
+ * PageRank scorer для repo-map (#60 Phase 2).
+ *
+ * Thin wrapper around `graphology` + `graphology-metrics` PageRank
+ * implementation. We do NOT roll our own power-iteration loop —
+ * graphology's centrality module is the maintained, well-tested
+ * standard в the JS ecosystem (Yomguithereal, MIT, 2k+ stars).
+ *
+ * What this module adds on top of the library:
+ *  - Pugi domain types (PageRankNode / PageRankEdge with optional weight)
+ *  - File-level aggregation (aggregateByFile) — sums symbol scores per file
+ *  - Output normalization (normalizeScores) к [0, 100] range для prompt
+ *    table rendering per docs/features/feat-pugi-ranked-repo-map.md §4
+ *
+ * No I/O, no globals. Safe to call from worker threads.
+ */
+import * as graphologyModule from 'graphology';
+import * as pagerankModule from 'graphology-metrics/centrality/pagerank.js';
+const graphologyAny = graphologyModule;
+const Graph = graphologyAny.default ?? graphologyModule;
+const pagerankAny = pagerankModule;
+const pagerankCentrality = pagerankAny.default ?? pagerankModule;
+const DEFAULT_DAMPING = 0.85;
+const DEFAULT_MAX_ITERATIONS = 100;
+const DEFAULT_TOLERANCE = 1e-6;
+export function pageRank(nodes, edges, options = {}) {
+    const damping = options.damping ?? DEFAULT_DAMPING;
+    const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const tolerance = options.tolerance ?? DEFAULT_TOLERANCE;
+    if (damping < 0 || damping >= 1) {
+        throw new RangeError(`damping must be в [0, 1), got ${damping}`);
+    }
+    if (maxIterations < 1) {
+        throw new RangeError(`maxIterations must be >= 1, got ${maxIterations}`);
+    }
+    if (tolerance <= 0) {
+        throw new RangeError(`tolerance must be > 0, got ${tolerance}`);
+    }
+    const scores = new Map();
+    if (nodes.length === 0) {
+        return { scores };
+    }
+    const seen = new Set();
+    for (const node of nodes) {
+        if (seen.has(node.id)) {
+            throw new Error('duplicate node ids — pageRank requires unique node.id');
+        }
+        seen.add(node.id);
+    }
+    const graph = new Graph({ type: 'directed', multi: true, allowSelfLoops: true });
+    for (const node of nodes) {
+        graph.addNode(node.id);
+    }
+    for (const edge of edges) {
+        if (!seen.has(edge.from) || !seen.has(edge.to)) {
+            continue;
+        }
+        const weight = edge.weight ?? 1;
+        if (weight <= 0)
+            continue;
+        graph.addEdge(edge.from, edge.to, { weight });
+    }
+    pagerankCentrality.assign(graph, {
+        alpha: damping,
+        maxIterations,
+        tolerance,
+        getEdgeWeight: 'weight',
+        nodePageRankAttribute: 'pagerank',
+    });
+    for (const id of graph.nodes()) {
+        const score = graph.getNodeAttribute(id, 'pagerank');
+        scores.set(id, typeof score === 'number' ? score : 0);
+    }
+    return { scores };
+}
+export function aggregateByFile(symbolScores, symbolToFile) {
+    const fileScores = new Map();
+    for (const [symbolId, score] of symbolScores) {
+        const file = symbolToFile.get(symbolId);
+        if (file === undefined)
+            continue;
+        fileScores.set(file, (fileScores.get(file) ?? 0) + score);
+    }
+    return fileScores;
+}
+export function normalizeScores(scores) {
+    const normalized = new Map();
+    if (scores.size === 0)
+        return normalized;
+    let max = 0;
+    for (const score of scores.values()) {
+        if (score > max)
+            max = score;
+    }
+    if (max === 0) {
+        for (const id of scores.keys())
+            normalized.set(id, 0);
+        return normalized;
+    }
+    for (const [id, score] of scores) {
+        normalized.set(id, (score / max) * 100);
+    }
+    return normalized;
+}
+//# sourceMappingURL=page-rank.js.map

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

@@ -0,0 +1,211 @@
+/**
+ * Repo-map scanner — .
+ *
+ * Walks the workspace via `fs.readdirSync` (sync, depth-first), filters
+ * to a recognised set of source-language extensions, and applies the
+ * shared `PugiIgnore` matcher so the same exclusion rules used by the
+ * three-tier context skeleton also gate the repo-map.
+ *
+ * Why a stand-alone scanner (vs. reusing the skeleton walker):
+ *
+ *  1. The skeleton walker emits a flat `IndexArtifact[]` of every
+ *     ignore-respecting file (markdown, configs, schemas, etc.) for
+ *     the working-set heuristic. The repo-map ONLY needs source
+ *     files — markdown headings and JSON keys are not "definitions"
+ *     in the L28 sense. Filtering downstream is cheap, but the
+ *     scanner gets to short-circuit on extension before stat'ing
+ *     the file, which matters for monorepos with thousands of
+ *     non-source artefacts (lockfiles, schemas, fixtures).
+ *
+ *  2. We need mtime + size per file so `cache.ts` can invalidate
+ *     stale entries without re-parsing. The skeleton walker
+ *     surfaces only paths.
+ *
+ *  3. The L28 contract caps the walk at `MAX_SRC_FILES` (5000) and
+ *     individual files at `MAX_FILE_BYTES` (200 KiB). When the cap
+ *     trips the scanner returns a `{ skipped: 'too-large' }`
+ *     verdict rather than partial data — the consumer must decide
+ *     whether to fall back to a no-op map or surface a hint к the
+ *     operator. Surfacing partial data would silently bias the
+ *     injected summary toward whichever subtree the walker happened
+ *     to traverse first.
+ *
+ * The output is sorted (POSIX path string compare) so two runs over
+ * the same workspace produce byte-identical `repo-map.json` caches —
+ * `cache.ts` relies on stable ordering for its hash-free freshness
+ * check. POSIX-style separators are used in `relPath` regardless of
+ * platform so the cache file stays portable.
+ *
+ * Pure module surface: no logging, no network. Errors during readdir
+ * on a single subtree (permission denied, symlink loop) are swallowed
+ * and the walker continues — repo-map is a best-effort context
+ * enrichment, never a gate.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, posix, relative, resolve, sep } from 'node:path';
+/**
+ * Hard ceiling on total source files surfaced by a single scan. The
+ * engine context budget is the binding constraint — a 5K-file repo
+ * already overflows the 2K-token injection cap so going higher buys
+ * nothing but walker latency. Repos above the cap fall back к the
+ * `{ skipped: 'too-large' }` verdict.
+ */
+export const MAX_SRC_FILES = 5000;
+/**
+ * Per-file size cap. Files larger than this are skipped — they are
+ * almost always generated (compiled JS, vendored libs, encoded blobs)
+ * and add noise without signal. The 200 KiB threshold mirrors the
+ * skeleton walker's own `MAX_FILE_BYTES` so the two scans agree
+ * on "what counts as a source file".
+ */
+export const MAX_FILE_BYTES = 200 * 1024;
+/**
+ * Source-language extensions the extractor knows how to parse. Adding
+ * a language here without a matching extractor branch is a silent
+ * no-op (the file shows up в the scan but extracts zero symbols);
+ * the spec asserts the symmetry so a future PR cannot drift the two
+ * lists out of sync.
+ */
+export const SUPPORTED_EXTENSIONS = Object.freeze([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.md',
+    '.mdx',
+]);
+const defaultReaddir = (path) => readdirSync(path, { withFileTypes: true });
+const defaultStat = (path) => {
+    const s = statSync(path);
+    return { size: s.size, mtimeMs: s.mtimeMs };
+};
+/**
+ * Walk the workspace once and return every source file the extractor
+ * is willing to parse. The function is deliberately synchronous —
+ * the underlying walks are CPU-bound, не I/O-bound, and the sync
+ * call avoids the promise overhead that dominates for thousands of
+ * small files. The L28 engine boot path runs this on a Node `setImmediate`
+ * so the main thread is not blocked.
+ */
+export function scanRepoForMap(options) {
+    const root = resolve(options.root);
+    const readdir = options.readdir ?? defaultReaddir;
+    const stat = options.stat ?? defaultStat;
+    const maxFiles = options.maxFiles ?? MAX_SRC_FILES;
+    const maxFileBytes = options.maxFileBytes ?? MAX_FILE_BYTES;
+    const ignore = options.ignore;
+    const files = [];
+    let walked = 0;
+    let skippedLarge = 0;
+    let skippedIgnored = 0;
+    let tooLarge = false;
+    /**
+     * Depth-first recursion. We push dirs into a manual stack instead of
+     * recursing in JS because deep monorepos (Nx with 100+ packages)
+     * have approached the v8 default stack limit on Windows runners
+     * before; an explicit stack is one less thing to debug.
+     */
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdir(dir);
+        }
+        catch {
+            // Permission denied / symlink loop / mid-flight delete — keep
+            // walking. Repo-map is best-effort context, never a gate.
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            const isDir = entry.isDirectory();
+            if (ignore.isIgnored(abs, isDir)) {
+                skippedIgnored += 1;
+                continue;
+            }
+            if (isDir) {
+                stack.push(abs);
+                continue;
+            }
+            if (!entry.isFile()) {
+                // Symlinks, sockets, FIFOs etc. Skip silently — they are not
+                // source code and stat'ing them can throw on broken links.
+                continue;
+            }
+            walked += 1;
+            const ext = extOf(entry.name);
+            if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+                continue;
+            }
+            let statResult;
+            try {
+                statResult = stat(abs);
+            }
+            catch {
+                // File vanished between readdir and stat — skip.
+                continue;
+            }
+            if (statResult.size > maxFileBytes) {
+                skippedLarge += 1;
+                continue;
+            }
+            // Workspace-relative POSIX path. `relative` returns the host
+            // separator on Windows; normalise to forward slashes so the
+            // cache file is portable.
+            const rel = relative(root, abs).split(sep).join(posix.sep);
+            files.push({
+                relPath: rel,
+                absPath: abs,
+                ext,
+                sizeBytes: statResult.size,
+                mtimeMs: statResult.mtimeMs,
+            });
+            if (files.length > maxFiles) {
+                tooLarge = true;
+                break;
+            }
+        }
+        if (tooLarge)
+            break;
+    }
+    if (tooLarge) {
+        return {
+            ok: false,
+            root,
+            skipped: {
+                reason: 'too-large',
+                walked,
+            },
+        };
+    }
+    // Sort by POSIX path for stable cache output. Two runs over the
+    // same workspace yield byte-identical JSON so the cache hash check
+    // is a simple `mtime + size` per entry without a content digest.
+    files.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+    return {
+        ok: true,
+        root,
+        files,
+        stats: {
+            walked,
+            kept: files.length,
+            skippedLarge,
+            skippedIgnored,
+        },
+    };
+}
+/**
+ * Lowercase extension including the leading dot, or '' when the
+ * filename has no extension. Mirrors `node:path.extname` semantics —
+ * inlined so the scanner has zero per-iteration call overhead.
+ */
+function extOf(name) {
+    const dot = name.lastIndexOf('.');
+    if (dot < 0 || dot === 0)
+        return '';
+    return name.slice(dot).toLowerCase();
+}
+//# sourceMappingURL=scanner.js.map