@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

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

@@ -1,254 +0,0 @@
-/**
- * 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

@@ -1,145 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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