karajan-code 2.32.0 → 2.34.0

package/src/lang/chunk-rust.js

@@ -0,0 +1,102 @@
+// KJC-PCS-0052 PR-B.2.2 — Rust source chunker (tree-sitter + regex fallback).
+// Mismo contrato síncrono que chunk-python: AST si el caller awaited
+// `prepareRust()` antes, regex si no. Top-level items (fn / struct / enum /
+// trait / impl / mod) son la frontera de chunk.
+//
+// El nodo `impl_item` no tiene field `name`; usamos el campo `type` para
+// que metadata.symbol apunte al tipo implementado (útil para grep en RAG).
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const NAMED_KINDS = new Set([
+  "function_item",
+  "struct_item",
+  "enum_item",
+  "trait_item",
+  "mod_item",
+  "type_item",
+  "union_item",
+]);
+const TOP_RE = /^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+|unsafe\s+|extern\s+(?:"[^"]+"\s+)?)*(?:fn|struct|enum|trait|mod|type|union|impl)(?:\s+(?:<[^>]+>\s+)?)?([A-Za-z_][\w]*)/gm;
+
+export async function prepareRust() {
+  return loadLanguage("rust");
+}
+
+function windowText(text, limit, overlap) {
+  if (text.length <= limit) return [text];
+  const step = Math.max(1, limit - overlap);
+  const out = [];
+  for (let i = 0; i < text.length; i += step) {
+    out.push(text.slice(i, i + limit));
+    if (i + limit >= text.length) break;
+  }
+  return out;
+}
+
+function symbolForImpl(node) {
+  const typeNode = node.childForFieldName("type");
+  return typeNode ? typeNode.text : null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("rust");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  let pendingAttrStart = null;
+  for (const child of tree.rootNode.namedChildren) {
+    if (child.type === "attribute_item" || child.type === "inner_attribute_item") {
+      if (pendingAttrStart === null) pendingAttrStart = child.startIndex;
+      continue;
+    }
+    let symbol = null;
+    if (NAMED_KINDS.has(child.type)) {
+      const nameNode = child.childForFieldName("name");
+      if (nameNode) symbol = nameNode.text;
+    } else if (child.type === "impl_item") {
+      symbol = symbolForImpl(child);
+    }
+    if (symbol) {
+      const idx = pendingAttrStart ?? child.startIndex;
+      marks.push({ idx, symbol });
+    }
+    pendingAttrStart = null;
+  }
+  return marks;
+}
+
+function marksViaRegex(text) {
+  const marks = [];
+  TOP_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_RE.exec(text)) !== null) marks.push({ idx: m.index, symbol: m[1] });
+  return marks;
+}
+
+export function chunkRust(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const marks = marksViaAST(text) ?? marksViaRegex(text);
+  if (marks.length === 0) {
+    return windowText(text, limit, overlap).map((piece) => ({
+      text: piece,
+      metadata: { source: path, kind: "code", symbol: null, language: "rust" },
+    }));
+  }
+  const out = [];
+  for (let i = 0; i < marks.length; i += 1) {
+    const start = marks[i].idx;
+    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
+    const body = text.slice(start, end);
+    for (const piece of windowText(body, limit, overlap)) {
+      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "rust" } });
+    }
+  }
+  return out;
+}

package/src/lang/go.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-B.2.3 — Go adapter. Detección por go.mod/go.sum; vendor/
+// y bin/ no se recorren (vendor lo usa `go mod vendor`, bin son builds).
+// chunk-go usa AST (tree-sitter) cuando el caller hizo `await prepareGo()`
+// y cae a regex en otro caso (mismo patrón que PYTHON_ADAPTER / RUST_ADAPTER).
+import { chunkGo, prepareGo } from "./chunk-go.js";
+
+export const GO_ADAPTER = {
+  id: "go",
+  extensions: [".go"],
+  skipSegments: ["vendor", "bin"],
+  manifests: ["go.mod", "go.sum"],
+  chunkSource: chunkGo,
+  prepare: prepareGo,
+};

package/src/lang/java.js

@@ -0,0 +1,16 @@
+// KJC-PCS-0052 PR-B.2.5 — Java adapter. Detección por pom.xml / build.gradle
+// (Maven, Gradle Groovy y Kotlin DSL). target/ y build/ son outputs estándar
+// de ambos sistemas; .gradle/ es el cache del wrapper; out/ lo usan IDEs
+// (IntelliJ/Eclipse) para classes. chunk-java usa AST (tree-sitter) cuando
+// el caller hizo `await prepareJava()` y cae a regex en otro caso (mismo
+// patrón que GO_ADAPTER / RUST_ADAPTER / PYTHON_ADAPTER).
+import { chunkJava, prepareJava } from "./chunk-java.js";
+
+export const JAVA_ADAPTER = {
+  id: "java",
+  extensions: [".java"],
+  skipSegments: ["target", "build", ".gradle", "out"],
+  manifests: ["pom.xml", "build.gradle", "build.gradle.kts"],
+  chunkSource: chunkJava,
+  prepare: prepareJava,
+};

package/src/lang/js.js

@@ -0,0 +1,8 @@
+// KJC-PCS-0052 PR-A — JS/TS adapter. Codifica las constantes que vivían
+// hard-coded en src/rag/indexer.js antes del registry.
+export const JS_ADAPTER = {
+  id: "js",
+  extensions: [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"],
+  skipSegments: ["node_modules", ".next", ".nuxt", ".svelte-kit"],
+  manifests: ["package.json"],
+};

package/src/lang/python.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-A/PR-B — Python adapter. Detección por manifest activa
+// el adapter; virtualenvs y caches se excluyen del walk. PR-B añade
+// `chunkSource` regex top-level (def/async def/class) — tree-sitter real
+// queda para PR-B.2 (decisión WASM vs native).
+import { chunkPython, preparePython } from "./chunk-python.js";
+
+export const PYTHON_ADAPTER = {
+  id: "python",
+  extensions: [".py"],
+  skipSegments: ["__pycache__", ".venv", "venv", ".tox", ".pytest_cache", ".mypy_cache", ".ruff_cache"],
+  manifests: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"],
+  chunkSource: chunkPython,
+  prepare: preparePython,
+};

package/src/lang/registry.js

@@ -0,0 +1,79 @@
+// KJC-PCS-0052 PR-A — Language adapter registry. Antes vivían CODE_EXT_RE
+// y SKIP_SEGMENTS hardcoded en indexer.js (solo JS/TS); ahora cada adapter
+// declara extensiones, skipSegments y manifests. PR-B añadirá AST chunkers
+// (tree-sitter); PR-C/D usan el mismo registry para audit y onboarder.
+import { existsSync } from "node:fs";
+import { extname, join } from "node:path";
+
+import { GO_ADAPTER } from "./go.js";
+import { JAVA_ADAPTER } from "./java.js";
+import { JS_ADAPTER } from "./js.js";
+import { PYTHON_ADAPTER } from "./python.js";
+import { RUST_ADAPTER } from "./rust.js";
+
+// Segmentos siempre excluidos del walk, independientes de stack: VCS,
+// outputs de build, scratch de Karajan, sandbox del audit. Lo que viva
+// aquí jamás se indexa.
+const COMMON_SKIP_SEGMENTS = [".git", "dist", "build", "coverage", ".karajan", ".kj", "_diet"];
+
+const REGISTRY = [JS_ADAPTER, PYTHON_ADAPTER, RUST_ADAPTER, GO_ADAPTER, JAVA_ADAPTER];
+
+export function getAdapters() {
+  return REGISTRY.slice();
+}
+
+/**
+ * Detecta qué adapters aplican a un projectDir mirando los manifests
+ * declarados. Si ningún adapter coincide (proyecto sin manifest), cae
+ * a JS para no romper repos legacy o sandboxes de tests.
+ */
+export function detectAdaptersForProject(projectDir) {
+  if (!projectDir) return [JS_ADAPTER];
+  const matched = REGISTRY.filter((a) => a.manifests.some((m) => existsSync(join(projectDir, m))));
+  return matched.length ? matched : [JS_ADAPTER];
+}
+
+/**
+ * Construye los matchers que usa el indexer al recorrer el árbol:
+ * `isCodeFile(path)` decide si la extensión cuadra con algún adapter
+ * activo; `shouldSkip(path)` aplica la unión de skipSegments comunes +
+ * los del adapter. Devuelve también `extensions` por si el caller quiere
+ * inspeccionarlas (p.ej. tests).
+ */
+export function buildMatchers(adapters) {
+  const extSet = new Set();
+  const skipSet = new Set(COMMON_SKIP_SEGMENTS);
+  for (const a of adapters) {
+    for (const e of a.extensions) extSet.add(e.toLowerCase());
+    for (const s of a.skipSegments || []) skipSet.add(s);
+  }
+  return {
+    isCodeFile: (p) => extSet.has(extname(p).toLowerCase()),
+    shouldSkip: (p) => p.split("/").some((seg) => skipSet.has(seg)),
+    extensions: [...extSet],
+  };
+}
+
+/**
+ * Unión de extensiones de TODOS los adapters registrados. Útil para
+ * `detectKind` en el indexer, que recibe un path suelto sin saber el
+ * projectDir y necesita reconocer una extensión de código aunque venga
+ * de un adapter no detectado en el proyecto actual.
+ */
+export function getAllCodeExtensions() {
+  const out = new Set();
+  for (const a of REGISTRY) for (const e of a.extensions) out.add(e.toLowerCase());
+  return [...out];
+}
+
+/**
+ * KJC-PCS-0052 PR-B — devuelve el adapter cuya `extensions` cubre el
+ * path, o `null` si ninguno matchea. Lo consume el chunker para delegar
+ * a un chunker específico por lenguaje (p.ej. Python).
+ */
+export function adapterForPath(path) {
+  if (!path) return null;
+  const ext = extname(path).toLowerCase();
+  for (const a of REGISTRY) if (a.extensions.includes(ext)) return a;
+  return null;
+}

package/src/lang/rust.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-B.2.2 — Rust adapter. Detección por Cargo.toml; target/
+// y skip segments evitan que el indexer recorra builds. chunk-rust usa
+// AST (tree-sitter) cuando el caller hizo `await prepareRust()` y cae a
+// regex en otro caso (mismo patrón que PYTHON_ADAPTER).
+import { chunkRust, prepareRust } from "./chunk-rust.js";
+
+export const RUST_ADAPTER = {
+  id: "rust",
+  extensions: [".rs"],
+  skipSegments: ["target", ".cargo"],
+  manifests: ["Cargo.toml", "Cargo.lock"],
+  chunkSource: chunkRust,
+  prepare: prepareRust,
+};

package/src/lang/tree-sitter-loader.js

@@ -0,0 +1,49 @@
+// KJC-PCS-0052 PR-B.2.1 — Lazy loader for web-tree-sitter parsers.
+// Async init (Parser.init + Language.load) is paid once per language id
+// and cached. Callers that want AST chunking must `await loadLanguage(...)`
+// during pre-loop; the per-file chunker then reads the cached entry
+// synchronously via `getLoaded(id)` and falls back to regex if not ready.
+//
+// Pure WASM (web-tree-sitter) over native bindings: no node-gyp build, no
+// per-platform .node files — works inside the SEA binary because the
+// grammar `.wasm` files travel with the npm package under
+// `vendor/tree-sitter-grammars/` (see ../../vendor/.../README.md).
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { Language, Parser } from "web-tree-sitter";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const GRAMMAR_DIR = resolve(HERE, "../../vendor/tree-sitter-grammars");
+
+const cache = new Map();
+let runtimePromise = null;
+
+async function initRuntime() {
+  if (!runtimePromise) runtimePromise = Parser.init();
+  return runtimePromise;
+}
+
+export function grammarPath(id) {
+  return resolve(GRAMMAR_DIR, `${id}.wasm`);
+}
+
+export async function loadLanguage(id, wasmPath = grammarPath(id)) {
+  if (cache.has(id)) return cache.get(id);
+  await initRuntime();
+  const language = await Language.load(wasmPath);
+  const parser = new Parser();
+  parser.setLanguage(language);
+  const entry = { parser, language };
+  cache.set(id, entry);
+  return entry;
+}
+
+export function getLoaded(id) {
+  return cache.get(id) || null;
+}
+
+export function resetForTests() {
+  cache.clear();
+  runtimePromise = null;
+}

package/src/onboarder/collectors/framework-multilang.js

@@ -0,0 +1,64 @@
+// KJC-TSK-0477 — Detectores mínimos de framework por stack (Python/Rust/Go).
+// Consume el sniff de manifests (PR-C) para conocer deps + presencia de
+// archivos canónicos. Cero deps externas, fail-soft (devuelve null o lista
+// vacía). El brief markdown se sintetiza río abajo desde estos campos.
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const PY_FW = [
+  { name: "django", deps: ["django"], file: "manage.py" },
+  { name: "flask", deps: ["flask"], file: "app.py" },
+  { name: "fastapi", deps: ["fastapi"], file: "main.py" },
+];
+const RUST_FW = [
+  { name: "axum", deps: ["axum"] },
+  { name: "actix-web", deps: ["actix-web"] },
+  { name: "rocket", deps: ["rocket"] },
+];
+const GO_FW = [
+  { name: "gin", deps: ["github.com/gin-gonic/gin"] },
+  { name: "echo", deps: ["github.com/labstack/echo"] },
+  { name: "fiber", deps: ["github.com/gofiber/fiber"] },
+];
+
+function matchFw(manifestRaw, projectDir, table) {
+  const found = [];
+  for (const fw of table) {
+    const hasDep = fw.deps.some((d) => manifestRaw?.includes(d));
+    const hasFile = fw.file ? existsSync(path.join(projectDir, fw.file)) : false;
+    if (hasDep || hasFile) found.push({ name: fw.name, viaDep: hasDep, viaFile: hasFile });
+  }
+  return found;
+}
+
+function detectLayout(projectDir, expected) {
+  return expected.filter((d) => existsSync(path.join(projectDir, d)));
+}
+
+// Detect frameworks + canonical layout per stack. Returns one entry per
+// detected manifest stack (skips Node — the existing JS path already covers
+// that with detectProjectStack).
+export function detectFrameworksMultiLang(projectDir, manifests = [], { readManifest } = {}) {
+  const out = [];
+  for (const m of manifests) {
+    if (m.stack === "node") continue;
+    const raw = readManifest ? readManifest(m) : "";
+    if (m.stack === "python") {
+      out.push({ stack: "python", manifest: m.manifest,
+        frameworks: matchFw(raw, projectDir, PY_FW),
+        layout: detectLayout(projectDir, ["apps", "src", "tests"]) });
+    } else if (m.stack === "rust") {
+      const isBin = existsSync(path.join(projectDir, "src", "main.rs"));
+      const isLib = existsSync(path.join(projectDir, "src", "lib.rs"));
+      out.push({ stack: "rust", manifest: m.manifest,
+        crateType: isBin && isLib ? "mixed" : isBin ? "binary" : isLib ? "library" : null,
+        frameworks: matchFw(raw, projectDir, RUST_FW),
+        layout: detectLayout(projectDir, ["src", "tests", "examples", "benches"]) });
+    } else if (m.stack === "go") {
+      out.push({ stack: "go", manifest: m.manifest, modulePath: m.name || null,
+        frameworks: matchFw(raw, projectDir, GO_FW),
+        layout: detectLayout(projectDir, ["cmd", "internal", "pkg"]) });
+    }
+  }
+  return out;
+}

package/src/onboarder/collectors/index.js

@@ -7,6 +7,8 @@ import { readdir } from "node:fs/promises";
 import { join, relative } from "node:path";
 
 import { detectProjectStack } from "../../utils/stack-detect.js";
+import { sniffManifests } from "../../utils/manifest-sniff.js";
+import { detectFrameworksMultiLang } from "./framework-multilang.js";
 
 const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", "__pycache__"]);
 
@@ -100,16 +102,31 @@ export async function collectAdrs(projectDir) {
   return found;
 }
 
+// Read a manifest file as raw text (best-effort) for framework dep matching.
+function readManifestRaw(projectDir) {
+  return (m) => {
+    try { return readFileSync(join(projectDir, m.manifest), "utf8"); }
+    catch { return ""; }
+  };
+}
+
 // One-shot bundle: every slot is independent; missing slots → null/[].
+// KJC-TSK-0477: manifests (multi-stack) + frameworksMultiLang (Python/Rust/Go)
+// se añaden de forma aditiva para que el brief pueda incluir secciones
+// condicionales sin romper consumidores existentes.
 export async function collectAll(projectDir) {
-  const [stack, tree, adrs] = await Promise.all([
+  const [stack, tree, adrs, manifests] = await Promise.all([
     detectProjectStack(projectDir).catch(() => null),
     collectTree(projectDir).catch(() => []),
     collectAdrs(projectDir).catch(() => []),
+    sniffManifests(projectDir).catch(() => []),
   ]);
+  const frameworksMultiLang = detectFrameworksMultiLang(projectDir, manifests, { readManifest: readManifestRaw(projectDir) });
   return {
     projectDir,
     stack,
+    manifests,
+    frameworksMultiLang,
     tree,
     git: collectGitHistory(projectDir),
     configs: collectConfigs(projectDir),

package/src/rag/auto-update.js

@@ -0,0 +1,50 @@
+// KJC-TSK-0455 PR2 — Pre-run drift check + post-merge hook installer.
+// Keeps the local RAG index aligned with HEAD so retrieval never serves
+// stale code without the user having to run `kj rag index` by hand.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+
+import { openVecStore, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+import { indexProjectDelta } from "./indexer.js";
+import { makeEmbedder } from "./embedders/factory.js";
+
+const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-hooks/post-merge");
+
+export async function maybeAutoUpdate({ projectDir, config, logger = console, flags = {} } = {}) {
+  // commander turns `--no-rag-update` into flags.ragUpdate === false.
+  if (flags?.ragUpdate === false || config?.rag?.autoUpdate?.onRun === false) return { skipped: true };
+  if (!projectDir || !existsSync(join(projectDir, ".git"))) return { skipped: true };
+  let head;
+  try { const r = await execa("git", ["-C", projectDir, "rev-parse", "HEAD"]); head = r.stdout.trim(); }
+  catch { return { skipped: true }; }
+  const slug = projectSlug(projectDir);
+  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  try {
+    const since = getLastIndexedCommit(db, slug);
+    if (!since || since === head) return { skipped: true, head };
+    logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}); running delta update`);
+    const totals = await indexProjectDelta(projectDir, { db, embedder: makeEmbedder(config), since, logger });
+    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+    return { ran: true, totals };
+  } catch (err) {
+    logger.warn?.(`[rag] auto-update failed (${err.message}); continuing without refresh`);
+    return { failed: true, error: err.message };
+  } finally { db.close(); }
+}
+
+export function installPostMergeHook({ projectDir, logger = console } = {}) {
+  const hooksDir = join(projectDir, ".git", "hooks");
+  if (!existsSync(join(projectDir, ".git"))) throw new Error(`Not a git repository: ${projectDir}`);
+  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+  const target = join(hooksDir, "post-merge");
+  const src = readFileSync(HOOK_SRC, "utf8");
+  if (existsSync(target) && !readFileSync(target, "utf8").includes("KJC-TSK-0455")) {
+    logger.warn?.(`[rag] ${target} already exists and was not installed by kj; leaving untouched`);
+    return { skipped: true, target };
+  }
+  writeFileSync(target, src);
+  chmodSync(target, 0o755);
+  return { installed: true, target };
+}

package/src/rag/chunker.js

@@ -92,13 +92,17 @@ export function chunkPlan(plan, { path = "<plan>", limit = DEFAULT_CHUNK_LIMIT }
 // ---------- source chunker (export-symbol granularity) ------------
 
 import { chunkSourceAST } from "./chunker-ast.js";
+import { adapterForPath } from "../lang/registry.js";
 
 const EXPORT_RE = /^export\s+(?:async\s+)?(?:function|class|const|let)\s+(\w+)/gm;
 
-// KJC-TSK-0444 — try AST chunker first (top-level declarations as whole
-// units, JSDoc folded in); fall back to the export-regex if @babel/parser
-// can't parse the file (returns null).
+// KJC-TSK-0444 + KJC-PCS-0052 PR-B — dispatch por adapter cuando el path
+// coincide con un lenguaje registrado que aporta su propio `chunkSource`
+// (p.ej. Python regex top-level). Si no, mantiene el camino JS histórico:
+// AST de @babel/parser primero, fallback a export-regex.
 export function chunkSource(text, opts = {}) {
+  const ad = adapterForPath(opts.path);
+  if (ad?.chunkSource) return ad.chunkSource(text, opts);
   const ast = chunkSourceAST(text, opts);
   if (ast) return ast;
   return chunkSourceRegex(text, opts);

package/src/rag/eval.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0483 — Retrieval-quality harness. Loads a golden set of queries
+// (each with expected source paths and/or symbol names), runs the retriever
+// against each, and reports recall@k + MRR per query and aggregated. Pure:
+// the runner takes `runQuery` as a function so the CLI plugs in `query()`
+// while tests can use a stub.
+import { readFileSync } from "node:fs";
+
+const DEFAULT_KS = [5, 10];
+
+export function loadGoldenQueries(path) {
+  const data = JSON.parse(readFileSync(path, "utf8"));
+  if (!Array.isArray(data)) throw new Error(`golden queries: expected an array in ${path}`);
+  return data;
+}
+
+function hitMatchesExpected(hit, expected) {
+  if (!hit) return false;
+  const src = hit.source || "";
+  if (expected.sources?.some((s) => src.endsWith(s))) return true;
+  const sym = hit.metadata?.symbol;
+  if (sym && expected.symbols?.includes(sym)) return true;
+  return false;
+}
+
+// Per-query metrics. `recall@k` is binary — 1 if any expected match lands in
+// the top-k, else 0. `rr` is the reciprocal of the first relevant rank (1 if
+// the very first hit matches, 0 if none do). `firstRank` is null on miss so
+// callers can render "—" without re-checking.
+export function scoreQuery(hits, expected, ks = DEFAULT_KS) {
+  const recall = {};
+  for (const k of ks) {
+    recall[`@${k}`] = hits.slice(0, k).some((h) => hitMatchesExpected(h, expected)) ? 1 : 0;
+  }
+  let firstRank = null;
+  let rr = 0;
+  for (let i = 0; i < hits.length; i += 1) {
+    if (hitMatchesExpected(hits[i], expected)) { firstRank = i + 1; rr = 1 / firstRank; break; }
+  }
+  return { recall, rr, firstRank };
+}
+
+export function aggregate(results, ks = DEFAULT_KS) {
+  const n = results.length || 1;
+  const recall = {};
+  for (const k of ks) {
+    recall[`@${k}`] = results.reduce((acc, r) => acc + (r.recall[`@${k}`] || 0), 0) / n;
+  }
+  const mrr = results.reduce((acc, r) => acc + (r.rr || 0), 0) / n;
+  return { n: results.length, recall, mrr };
+}
+
+export async function runEval(queries, runQuery, { topK = 10, ks = DEFAULT_KS } = {}) {
+  const results = [];
+  for (const q of queries) {
+    const hits = (await runQuery(q.query, topK)) || [];
+    const expected = { sources: q.expected_sources || [], symbols: q.expected_symbols || [] };
+    const scored = scoreQuery(hits, expected, ks);
+    results.push({ query: q.query, hits, ...scored });
+  }
+  return { results, aggregate: aggregate(results, ks) };
+}