@getfoyer/review-core 0.2.0 → 0.2.1

package/dist/fileReader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * FileReader port — the seam between "where do source files come from?"
+ * and the semantic-context builder / repair-instruction renderer.
+ *
+ * Two real implementations live outside this package:
+ *  - api/ ships an Octokit-backed reader that fetches by SHA from GitHub
+ *    (used during PR verification, where no workspace exists yet).
+ *  - packages/cli ships a disk-backed reader that reads from the working
+ *    tree (used during pre-PR `foyer review`).
+ *
+ * Both share the same contract: returns the file's UTF-8 contents or
+ * null. Never throws — callers degrade silently.
+ */
+export interface FileReader {
+    read(path: string): Promise<string | null>;
+}
+//# sourceMappingURL=fileReader.d.ts.map

package/dist/fileReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileReader.d.ts","sourceRoot":"","sources":["../src/fileReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5C"}

package/dist/fileReader.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fileReader.js.map

package/dist/fileReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileReader.js","sourceRoot":"","sources":["../src/fileReader.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -6,4 +6,7 @@
  * without specifying the subpath.
  */
 export * from './types.js';
+export type { FileReader } from './fileReader.js';
+export { buildSemanticContext, buildSemanticContextCached, getSharedSemanticBlockCache, _resetSharedCacheForTests, } from './semantic/index.js';
+export type { BuildSemanticContextOptions, SemanticBlock, TouchedSymbol, ImportedSymbol, SemanticBlockCache, } from './semantic/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,2BAA2B,EAC3B,aAAa,EACb,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -6,4 +6,5 @@
  * without specifying the subpath.
  */
 export * from './types.js';
+export { buildSemanticContext, buildSemanticContextCached, getSharedSemanticBlockCache, _resetSharedCacheForTests, } from './semantic/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC"}

package/dist/semantic/cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Process-local LRU cache for rendered semantic blocks.
+ *
+ * Same PR head SHA → same touched files → same `<semantic_context>` block.
+ * `code_review` and `intent_fidelity` both want it; cache lets us build once.
+ *
+ * Out of scope: cross-process / cross-deploy persistence. Railway redeploys
+ * flush the map and the next request rebuilds on demand. The cache is a hot-
+ * path optimization, not a correctness primitive — every miss is harmless.
+ */
+import type { SemanticBlock } from './types.js';
+export interface SemanticBlockCache {
+    get(key: string): SemanticBlock | undefined;
+    set(key: string, block: SemanticBlock): void;
+    /** For tests only — drops every entry. */
+    clear(): void;
+    /** For metrics. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        capacity: number;
+    };
+}
+export declare function createSemanticBlockCache(capacity?: number): SemanticBlockCache;
+/** Canonical key. `repoFullName` is `owner/name`; head SHA is the post-image. */
+export declare function cacheKey(repoFullName: string, headSha: string): string;
+export declare function getSharedSemanticBlockCache(): SemanticBlockCache;
+/** Test seam. */
+export declare function _resetSharedCacheForTests(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/semantic/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/semantic/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C,0CAA0C;IAC1C,KAAK,IAAI,IAAI,CAAC;IACd,mBAAmB;IACnB,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,GAAE,MAAyB,GAAG,kBAAkB,CA4BhG;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAID,wBAAgB,2BAA2B,IAAI,kBAAkB,CAGhE;AAED,iBAAiB;AACjB,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/semantic/cache.js

@@ -0,0 +1,50 @@
+const DEFAULT_CAPACITY = 64;
+export function createSemanticBlockCache(capacity = DEFAULT_CAPACITY) {
+    // Map preserves insertion order; deleting and re-setting on read pushes a
+    // key to the most-recently-used end. Evict from the iterator's first entry
+    // when over capacity. Standard LRU dance, no extra deps.
+    const map = new Map();
+    let hits = 0;
+    let misses = 0;
+    return {
+        get(key) {
+            const v = map.get(key);
+            if (v === undefined) {
+                misses += 1;
+                return undefined;
+            }
+            map.delete(key);
+            map.set(key, v);
+            hits += 1;
+            return v;
+        },
+        set(key, block) {
+            if (map.has(key))
+                map.delete(key);
+            map.set(key, block);
+            if (map.size > capacity) {
+                const oldest = map.keys().next().value;
+                if (oldest !== undefined)
+                    map.delete(oldest);
+            }
+        },
+        clear() { map.clear(); hits = 0; misses = 0; },
+        stats() { return { hits, misses, size: map.size, capacity }; },
+    };
+}
+/** Canonical key. `repoFullName` is `owner/name`; head SHA is the post-image. */
+export function cacheKey(repoFullName, headSha) {
+    return `${repoFullName}@${headSha}`;
+}
+/** Process singleton — one cache for the whole verification worker. */
+let _singleton = null;
+export function getSharedSemanticBlockCache() {
+    if (!_singleton)
+        _singleton = createSemanticBlockCache();
+    return _singleton;
+}
+/** Test seam. */
+export function _resetSharedCacheForTests() {
+    _singleton = null;
+}
+//# sourceMappingURL=cache.js.map

package/dist/semantic/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/semantic/cache.ts"],"names":[],"mappings":"AAYA,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAW5B,MAAM,UAAU,wBAAwB,CAAC,WAAmB,gBAAgB;IAC1E,0EAA0E;IAC1E,2EAA2E;IAC3E,yDAAyD;IACzD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,OAAO;QACL,GAAG,CAAC,GAAG;YACL,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;gBAAC,MAAM,IAAI,CAAC,CAAC;gBAAC,OAAO,SAAS,CAAC;YAAC,CAAC;YACvD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAChB,IAAI,IAAI,CAAC,CAAC;YACV,OAAO,CAAC,CAAC;QACX,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACpB,IAAI,GAAG,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;gBACvC,IAAI,MAAM,KAAK,SAAS;oBAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QACD,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9C,KAAK,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,YAAoB,EAAE,OAAe;IAC5D,OAAO,GAAG,YAAY,IAAI,OAAO,EAAE,CAAC;AACtC,CAAC;AAED,uEAAuE;AACvE,IAAI,UAAU,GAA8B,IAAI,CAAC;AACjD,MAAM,UAAU,2BAA2B;IACzC,IAAI,CAAC,UAAU;QAAE,UAAU,GAAG,wBAAwB,EAAE,CAAC;IACzD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,yBAAyB;IACvC,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC"}

package/dist/semantic/contextBuilder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Render the touched-symbol + imported-symbol data into the markdown block
+ * that ships inside the LLM user message.
+ *
+ * Hard cap: `maxBytes` (default 30KB) on the final rendered string. We drop
+ * the lowest-priority items first (imported symbols before touched symbols;
+ * trailing items before earlier ones) and emit a truncation footer when we
+ * had to drop anything.
+ */
+import type { ImportedSymbol, SemanticBlock, TouchedSymbol } from './types.js';
+export interface BuildContextInput {
+    touched: TouchedSymbol[];
+    imported: ImportedSymbol[];
+    maxBytes: number;
+}
+export declare function renderSemanticBlock(input: BuildContextInput): SemanticBlock;
+//# sourceMappingURL=contextBuilder.d.ts.map

package/dist/semantic/contextBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBuilder.d.ts","sourceRoot":"","sources":["../../src/semantic/contextBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,aAAa,CAyD3E"}

package/dist/semantic/contextBuilder.js

@@ -0,0 +1,92 @@
+export function renderSemanticBlock(input) {
+    const { touched, imported, maxBytes } = input;
+    if (touched.length === 0 && imported.length === 0) {
+        return { rendered: '', stats: emptyStats() };
+    }
+    // Priority order: touched symbols first (most useful), then imports.
+    // Inside touched, preserve the order we collected (file order).
+    const renderedTouched = touched.map(renderTouchedSymbol);
+    const renderedImported = imported.map(renderImportedSymbol);
+    let droppedTouched = 0;
+    let droppedImported = 0;
+    let body = composeBody(renderedTouched, renderedImported);
+    let block = wrapBlock(body, droppedTouched, droppedImported);
+    // Trim imports first, then touched-symbol entries from the tail.
+    while (block.length > maxBytes && renderedImported.length > 0) {
+        renderedImported.pop();
+        droppedImported += 1;
+        body = composeBody(renderedTouched, renderedImported);
+        block = wrapBlock(body, droppedTouched, droppedImported);
+    }
+    while (block.length > maxBytes && renderedTouched.length > 1) {
+        renderedTouched.pop();
+        droppedTouched += 1;
+        body = composeBody(renderedTouched, renderedImported);
+        block = wrapBlock(body, droppedTouched, droppedImported);
+    }
+    // Last-resort hard slice if a single symbol body still exceeds the cap.
+    // The block remains well-formed (tag stays closed) so the LLM doesn't see
+    // a dangling fence.
+    if (block.length > maxBytes) {
+        const sliced = block.slice(0, Math.max(0, maxBytes - CLOSE_TAG.length)) + CLOSE_TAG;
+        return {
+            rendered: sliced,
+            stats: {
+                touchedFiles: countFiles(touched),
+                touchedSymbols: touched.length - droppedTouched,
+                importedSymbols: imported.length - droppedImported,
+                bytes: sliced.length,
+                truncated: true,
+            },
+        };
+    }
+    return {
+        rendered: block,
+        stats: {
+            touchedFiles: countFiles(touched),
+            touchedSymbols: touched.length - droppedTouched,
+            importedSymbols: imported.length - droppedImported,
+            bytes: block.length,
+            truncated: droppedTouched > 0 || droppedImported > 0,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal renderers
+// ---------------------------------------------------------------------------
+const OPEN_TAG = '<semantic_context>';
+const CLOSE_TAG = '</semantic_context>';
+function emptyStats() {
+    return { touchedFiles: 0, touchedSymbols: 0, importedSymbols: 0, bytes: 0, truncated: false };
+}
+function countFiles(touched) {
+    return new Set(touched.map((s) => s.file)).size;
+}
+function renderTouchedSymbol(sym) {
+    return `### ${sym.kind} \`${sym.name}\` — ${sym.file}:${sym.line}\n\`\`\`\n${sym.body}\n\`\`\``;
+}
+function renderImportedSymbol(sym) {
+    return `- \`${sym.name}\` from \`${sym.fromFile}\` — \`${sym.signature}\``;
+}
+function composeBody(touched, imported) {
+    const parts = [];
+    if (touched.length > 0) {
+        parts.push('## Touched symbols (full definitions, not just diff hunks)');
+        parts.push(touched.join('\n\n'));
+    }
+    if (imported.length > 0) {
+        parts.push('## Imported symbols referenced by touched files (1-hop)');
+        parts.push(imported.join('\n'));
+    }
+    return parts.join('\n\n');
+}
+function wrapBlock(body, droppedTouched, droppedImported) {
+    const footerParts = [];
+    if (droppedTouched > 0)
+        footerParts.push(`${droppedTouched} touched symbol(s) omitted`);
+    if (droppedImported > 0)
+        footerParts.push(`${droppedImported} imported signature(s) omitted`);
+    const footer = footerParts.length > 0 ? `\n\n[truncated: ${footerParts.join(', ')}]` : '';
+    return `${OPEN_TAG}\n${body}${footer}\n${CLOSE_TAG}`;
+}
+//# sourceMappingURL=contextBuilder.js.map

package/dist/semantic/contextBuilder.js.map

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

package/dist/semantic/diffParse.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal unified-diff parser.
+ *
+ * Extracts, per touched file, the line ranges in the post-image that the diff
+ * actually changes (added or context-surrounded). Pure data — no AST work
+ * here. The downstream module maps those line ranges onto symbols.
+ *
+ * Why not a library: unified diff is small enough that a focused parser
+ * (5KB, no deps) beats pulling in `parse-diff` for one consumer.
+ */
+export interface DiffHunk {
+    /** 1-based starting line in the post-image (the `+` side). */
+    newStart: number;
+    /** Number of post-image lines covered by this hunk. */
+    newLines: number;
+}
+export interface DiffFile {
+    /** Repo-relative path from the `+++ b/<path>` header. `null` for /dev/null
+     *  (file deleted) — callers should skip these. */
+    newPath: string | null;
+    hunks: DiffHunk[];
+}
+export declare function parseUnifiedDiff(diff: string): DiffFile[];
+/** Touched files in the post-image. Drops deletions (no `+++ b/` path) and
+ *  files with zero hunks (rename headers, mode changes). */
+export declare function touchedFiles(diff: string): {
+    path: string;
+    hunks: DiffHunk[];
+}[];
+//# sourceMappingURL=diffParse.d.ts.map

package/dist/semantic/diffParse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffParse.d.ts","sourceRoot":"","sources":["../../src/semantic/diffParse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB;sDACkD;IAClD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6BzD;AAED;4DAC4D;AAC5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,EAAE,CAIhF"}

package/dist/semantic/diffParse.js

@@ -0,0 +1,48 @@
+/**
+ * Minimal unified-diff parser.
+ *
+ * Extracts, per touched file, the line ranges in the post-image that the diff
+ * actually changes (added or context-surrounded). Pure data — no AST work
+ * here. The downstream module maps those line ranges onto symbols.
+ *
+ * Why not a library: unified diff is small enough that a focused parser
+ * (5KB, no deps) beats pulling in `parse-diff` for one consumer.
+ */
+export function parseUnifiedDiff(diff) {
+    const lines = diff.split('\n');
+    const files = [];
+    let current = null;
+    for (const line of lines) {
+        if (line.startsWith('+++ ')) {
+            // `+++ b/path` or `+++ /dev/null`. Strip the `b/` prefix when present.
+            const raw = line.slice(4).trim();
+            const newPath = raw === '/dev/null' ? null : raw.replace(/^b\//, '');
+            current = { newPath, hunks: [] };
+            files.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('@@')) {
+            // Form: `@@ -<oldStart>,<oldLines> +<newStart>,<newLines> @@ ...`.
+            // Defensive: line counts default to 1 when omitted, per spec.
+            const m = /\+(\d+)(?:,(\d+))?/.exec(line);
+            if (!m)
+                continue;
+            const newStart = parseInt(m[1], 10);
+            const newLines = m[2] ? parseInt(m[2], 10) : 1;
+            if (Number.isFinite(newStart) && Number.isFinite(newLines)) {
+                current.hunks.push({ newStart, newLines });
+            }
+        }
+    }
+    return files;
+}
+/** Touched files in the post-image. Drops deletions (no `+++ b/` path) and
+ *  files with zero hunks (rename headers, mode changes). */
+export function touchedFiles(diff) {
+    return parseUnifiedDiff(diff)
+        .filter((f) => f.newPath !== null && f.hunks.length > 0)
+        .map((f) => ({ path: f.newPath, hunks: f.hunks }));
+}
+//# sourceMappingURL=diffParse.js.map

package/dist/semantic/diffParse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffParse.js","sourceRoot":"","sources":["../../src/semantic/diffParse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAoB,IAAI,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,uEAAuE;YACvE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACjC,MAAM,OAAO,GAAG,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACrE,OAAO,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,mEAAmE;YACnE,8DAA8D;YAC9D,MAAM,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC3D,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,gBAAgB,CAAC,IAAI,CAAC;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;SAC5F,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/semantic/imports.d.ts

@@ -0,0 +1,16 @@
+import type { FileReader } from '../fileReader.js';
+import type { ImportedSymbol } from './types.js';
+export interface ImportResolutionInput {
+    /** The importing file (a touched file). */
+    fromFile: string;
+    /** Edges produced by `findImports` for that file. */
+    edges: {
+        source: string;
+        names: string[];
+    }[];
+    reader: FileReader;
+    /** Soft cap on total imported-symbol entries collected across all edges. */
+    cap: number;
+}
+export declare function resolveImports(input: ImportResolutionInput): Promise<ImportedSymbol[]>;
+//# sourceMappingURL=imports.d.ts.map

package/dist/semantic/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../../src/semantic/imports.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA4CjD,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC7C,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA6B5F"}

package/dist/semantic/imports.js

@@ -0,0 +1,102 @@
+/**
+ * Import-edge resolution.
+ *
+ * Given an import like `import { foo, bar } from './utils'` in
+ * `src/services/billing.ts`, resolve `./utils` to a real repo path, fetch
+ * that file via the FileReader, parse it, and extract the signatures of
+ * `foo` and `bar`.
+ *
+ * Resolution rules (intentionally cheap):
+ *   - Relative paths only (`.` or `..`). Bare-module specifiers (`react`,
+ *     `lodash`) are skipped — we'd need package.json + node_modules walking
+ *     to handle those, and signatures of third-party deps rarely catch bugs
+ *     the diff alone misses.
+ *   - Try the literal path, then `<path>.ts`, `.tsx`, `.js`, `.jsx`,
+ *     `.py`, then `<path>/index.ts` / `.js`. Skip the rest. The plan calls
+ *     this "1-hop"; we explicitly do NOT recurse.
+ *
+ * Returns at most `cap` imported symbols total across the call to keep the
+ * rendered block bounded.
+ */
+import { dirname, posix } from 'node:path';
+import { languageForPath } from './languages.js';
+import { parse } from './parser.js';
+import { topLevelDefinitions, symbolName } from './symbols.js';
+const RELATIVE_CANDIDATE_SUFFIXES = ['', '.ts', '.tsx', '.js', '.jsx', '.py', '.rb'];
+const INDEX_SUFFIXES = ['/index.ts', '/index.tsx', '/index.js', '/index.jsx', '/__init__.py'];
+function isRelative(spec) {
+    return spec.startsWith('./') || spec.startsWith('../') || spec === '.' || spec === '..';
+}
+function candidatePaths(fromFile, spec) {
+    const baseDir = dirname(fromFile);
+    const joined = posix.normalize(posix.join(baseDir, spec));
+    const out = [];
+    // TS/ESM convention: source imports `./foo.js` but the actual file on disk
+    // is `./foo.ts`. Try the TS-equivalent before the literal so common cases
+    // resolve on the first hit. Also handles `.jsx → .tsx`, `.mjs → .mts`, etc.
+    const jsToTs = {
+        '.js': '.ts',
+        '.jsx': '.tsx',
+        '.mjs': '.mts',
+        '.cjs': '.cts',
+    };
+    const extMatch = /(\.[a-z]+)$/i.exec(joined);
+    if (extMatch && jsToTs[extMatch[1]]) {
+        out.push(joined.slice(0, -extMatch[1].length) + jsToTs[extMatch[1]]);
+    }
+    for (const sfx of RELATIVE_CANDIDATE_SUFFIXES) {
+        out.push(joined + sfx);
+    }
+    for (const sfx of INDEX_SUFFIXES) {
+        out.push(joined + sfx);
+    }
+    return out;
+}
+async function resolveImport(reader, fromFile, spec) {
+    if (!isRelative(spec))
+        return null;
+    for (const candidate of candidatePaths(fromFile, spec)) {
+        const content = await reader.read(candidate);
+        if (content !== null)
+            return { path: candidate, content };
+    }
+    return null;
+}
+export async function resolveImports(input) {
+    const collected = [];
+    for (const edge of input.edges) {
+        if (collected.length >= input.cap)
+            break;
+        if (!isRelative(edge.source))
+            continue;
+        const resolved = await resolveImport(input.reader, input.fromFile, edge.source);
+        if (!resolved)
+            continue;
+        const lang = languageForPath(resolved.path);
+        if (!lang)
+            continue;
+        const parsed = await parse(resolved.content, lang);
+        if (!parsed)
+            continue;
+        const defs = topLevelDefinitions(parsed, lang);
+        const wanted = new Set(edge.names);
+        const wantsAll = wanted.has('*');
+        for (const def of defs) {
+            if (collected.length >= input.cap)
+                break;
+            const nm = symbolName(def);
+            if (!wantsAll && !wanted.has(nm))
+                continue;
+            // Signature = first line of the body. For TS interfaces / type aliases
+            // the "first line" is the only meaningful part anyway.
+            const firstLine = def.text.split('\n', 1)[0].trim();
+            collected.push({
+                name: nm,
+                fromFile: resolved.path,
+                signature: firstLine,
+            });
+        }
+    }
+    return collected;
+}
+//# sourceMappingURL=imports.js.map

package/dist/semantic/imports.js.map

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

package/dist/semantic/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Public entry point: build a `<semantic_context>` block to inline next to
+ * the diff in the code-review LLM user message.
+ *
+ * Never throws. Any failure (grammar load, file fetch, parse) returns an
+ * empty `SemanticBlock` and the caller proceeds with diff-only — same as
+ * Foyer behaves today.
+ *
+ * Timing: this runs in the pre-sandbox static pass alongside `code_review`.
+ * It uses `FileReader` (Octokit-backed) rather than a `SandboxHandle`,
+ * because at this point in the orchestrator no workspace exists yet.
+ * Cross-file caller search would require a workspace and is deferred —
+ * see `~/.claude/plans/implement-ast-parsing-for-scalable-charm.md`.
+ */
+import type { FileReader } from '../fileReader.js';
+import { type SemanticBlockCache } from './cache.js';
+import type { SemanticBlock } from './types.js';
+export interface BuildSemanticContextOptions {
+    /** Hard cap on the rendered block (bytes). Default: 30_000. */
+    maxBytes?: number;
+    /** Cap on bytes per individual symbol body before slicing. Default: 4_000. */
+    bodyCapBytes?: number;
+    /** Cap on imported-symbol entries across the whole block. Default: 30. */
+    importedCap?: number;
+    /** Cap on files we'll parse in one call. Default: 20. Protects against
+     *  mega-PRs that touch hundreds of files. */
+    fileCap?: number;
+}
+export declare function buildSemanticContext(diff: string, reader: FileReader, options?: BuildSemanticContextOptions): Promise<SemanticBlock>;
+/**
+ * Cached variant: same `(repoFullName, headSha)` resolves through a shared
+ * LRU. The two consumers (`code_review`, `intent_fidelity`) hit the same key
+ * and the second one returns instantly. Falls through to a fresh build on
+ * miss, then stores. Pass `cache` to override the shared singleton in tests.
+ */
+export declare function buildSemanticContextCached(input: {
+    diff: string;
+    reader: FileReader;
+    repoFullName: string;
+    headSha: string;
+}, options?: BuildSemanticContextOptions, cache?: SemanticBlockCache): Promise<SemanticBlock>;
+export type { SemanticBlock, TouchedSymbol, ImportedSymbol } from './types.js';
+export { getSharedSemanticBlockCache, _resetSharedCacheForTests } from './cache.js';
+export type { SemanticBlockCache } from './cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/semantic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/semantic/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOnD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,YAAY,CAAC;AAE/E,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;iDAC6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,aAAa,CAAC,CA8CxB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,EACD,OAAO,GAAE,2BAAgC,EACzC,KAAK,GAAE,kBAAkD,GACxD,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/semantic/index.js

@@ -0,0 +1,78 @@
+import { touchedFiles } from './diffParse.js';
+import { languageForPath } from './languages.js';
+import { parse } from './parser.js';
+import { findTouchedSymbols, findImports } from './symbols.js';
+import { resolveImports } from './imports.js';
+import { renderSemanticBlock } from './contextBuilder.js';
+import { cacheKey, getSharedSemanticBlockCache, } from './cache.js';
+const DEFAULT_OPTS = {
+    maxBytes: 30_000,
+    bodyCapBytes: 4_000,
+    importedCap: 30,
+    fileCap: 20,
+};
+export async function buildSemanticContext(diff, reader, options = {}) {
+    const opts = { ...DEFAULT_OPTS, ...options };
+    if (!diff || diff.trim().length === 0) {
+        return { rendered: '', stats: { touchedFiles: 0, touchedSymbols: 0, importedSymbols: 0, bytes: 0, truncated: false } };
+    }
+    try {
+        const files = touchedFiles(diff).slice(0, opts.fileCap);
+        if (files.length === 0) {
+            return { rendered: '', stats: { touchedFiles: 0, touchedSymbols: 0, importedSymbols: 0, bytes: 0, truncated: false } };
+        }
+        const touched = [];
+        const imported = [];
+        const remainingImportBudget = () => opts.importedCap - imported.length;
+        for (const file of files) {
+            const lang = languageForPath(file.path);
+            if (!lang)
+                continue;
+            const source = await reader.read(file.path);
+            if (source === null)
+                continue;
+            const parsed = await parse(source, lang);
+            if (!parsed)
+                continue;
+            const fileSymbols = findTouchedSymbols(parsed, lang, file.path, file.hunks, opts.bodyCapBytes);
+            touched.push(...fileSymbols);
+            // Only bother resolving imports for files that actually have touched
+            // symbols — if the diff is a config edit, the imports aren't useful.
+            if (fileSymbols.length > 0 && remainingImportBudget() > 0) {
+                const edges = findImports(parsed, lang);
+                const resolved = await resolveImports({
+                    fromFile: file.path,
+                    edges,
+                    reader,
+                    cap: remainingImportBudget(),
+                });
+                imported.push(...resolved);
+            }
+        }
+        return renderSemanticBlock({ touched, imported, maxBytes: opts.maxBytes });
+    }
+    catch {
+        // Never block a review on enrichment failure.
+        return { rendered: '', stats: { touchedFiles: 0, touchedSymbols: 0, importedSymbols: 0, bytes: 0, truncated: false } };
+    }
+}
+/**
+ * Cached variant: same `(repoFullName, headSha)` resolves through a shared
+ * LRU. The two consumers (`code_review`, `intent_fidelity`) hit the same key
+ * and the second one returns instantly. Falls through to a fresh build on
+ * miss, then stores. Pass `cache` to override the shared singleton in tests.
+ */
+export async function buildSemanticContextCached(input, options = {}, cache = getSharedSemanticBlockCache()) {
+    const key = cacheKey(input.repoFullName, input.headSha);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const fresh = await buildSemanticContext(input.diff, input.reader, options);
+    // Only cache non-empty blocks. Empty results from a transient failure
+    // (e.g. parser cold-start race) should be retryable on the next consumer.
+    if (fresh.rendered.length > 0)
+        cache.set(key, fresh);
+    return fresh;
+}
+export { getSharedSemanticBlockCache, _resetSharedCacheForTests } from './cache.js';
+//# sourceMappingURL=index.js.map

package/dist/semantic/index.js.map

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