karajan-code 2.33.0 → 2.34.0

package/README.md

@@ -345,6 +345,24 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.34.0 released** — Minor. Two epics in one window. **KJC-PCS-0052 "Multi-language RAG"** — Python, Rust, Go and Java join JS/TS as first-class citizens of the local RAG index (AST chunkers via `web-tree-sitter` + multi-lang watcher + audit/onboarder multi-stack manifest sniffer), so a polyglot repo gets the same semantic retrieval surface as a single-language one. **KJC-PCS-0053 "RAG Quality & Observability"** — `kj rag eval` ships a frozen golden-query harness with `recall@k + MRR` (CI-gated via `--min-recall`), content-hash dedup skips redundant embeddings, optional MMR diversification returns *different* chunks instead of five near-duplicates, and `docs/RAG.md` gains a six-questions deep-dive documenting the system end-to-end. `kj rag index --since <ref>` + a post-merge git hook keep the index in sync with `git pull` / merge without manual intervention.
+>
+> - **`vec_store_meta` + `kj rag index --since`** (PR #882, KJC-TSK-0455 PR1): per-project last-indexed-commit stamp; `--since auto` resolves it; explicit refs honoured; missing baseline falls back to a full index with a friendly warning. Idempotent.
+> - **Post-merge hook + pre-run drift check** (PR #883, KJC-TSK-0455 PR2): new `kj rag install-hooks` writes `.git/hooks/post-merge` so `git pull` auto-triggers a delta re-index. Pre-run drift check emits a one-line hint when `HEAD` is ahead of the last indexed SHA by more than N files.
+> - **Language registry + Python canary** (PR #884, KJC-TSK-0474): new `src/lang/registry.js` with `adapterForPath(file)`; the indexer + watcher both route through it. Python lands as the first non-JS adapter to exercise the registry shape from day one.
+> - **Python AST chunker** (PR #886, KJC-TSK-0478) and **Rust AST chunker** (PR #888, KJC-TSK-0479): web-tree-sitter walkers + regex fallbacks, grammars vendored under `vendor/tree-sitter-grammars/*.wasm` so SEA binaries stay self-contained.
+> - **Indexer prepares Python / Rust grammars** (PR #889, KJC-TSK-0480): `prepareAdapters()` awaits the grammar loads before walking so the first file doesn't pay the cold-load tax mid-batch.
+> - **Go AST chunker** (PR #890, KJC-TSK-0481): tree-sitter walker + regex fallback. Method receivers rendered explicitly so retrieval surfaces method-vs-function disambiguation without re-parsing.
+> - **Multi-stack manifest sniffer for `basal-cost`** (PR #891, KJC-TSK-0476): `kj audit` now reads Python (`pyproject.toml`, `requirements*.txt`), Rust (`Cargo.toml`), Go (`go.mod`) and Java (`pom.xml`, `build.gradle*`) manifests alongside `package.json`. Cost estimates no longer assume JS/TS.
+> - **Multi-stack frameworks in audit bundle** (PR #892, KJC-TSK-0477): the audit bundle JSON gains a `stacks` field listing detected language stacks + framework hints (Django, Flask, Actix, Tokio, Gin, Echo, Spring, Quarkus...). Onboarder + audit role render polyglot reality.
+> - **Java AST chunker** (PR #893, KJC-TSK-0486): two-level walker (class / interface / enum / record → method / constructor) + regex fallback. Inner classes flattened with `Outer$Inner` symbols.
+> - **`docs/RAG.md` six-questions deep-dive** (PR #894, KJC-TSK-0485): per-language chunker table, six-provider embedder matrix, hybrid + rerank + metadata filter, update strategy table, validation tiers. Excluded from the shrink-budget gate.
+> - **Watcher derived from language registry** (PR #895, KJC-TSK-0482): `kj watch` matcher no longer hard-codes JS/TS. Python / Rust / Go / Java sources trigger live re-index.
+> - **Content-hash skip-on-match** (PR #896, KJC-TSK-0484 PR-A): each chunk gains a `sha256` column; identical bodies skip the Ollama call. Re-indexing identical files now costs zero embeddings.
+> - **MMR diversification in retriever** (PR #898, KJC-TSK-0484 PR-B): optional `rag.search.mmr` over the top-N candidates; lambda (`rag.search.mmrLambda`, default 0.5) trades pure cosine relevance for diversity. Off by default.
+> - **Retrieval-quality harness** (PR #899, KJC-TSK-0483 PR-A): pure `runEval(queries, runQuery, { topK, ks })` scoring recall@k (binary) + MRR. `tests/rag/golden-queries.json` ships 20 entries covering the public surface of `src/rag/`.
+> - **`kj rag eval` CLI + baseline docs** (PR #900, KJC-TSK-0483 PR-B): subcommand wires the harness to the indexed corpus, emits aggregate + per-query report (human or `--json`), and sets `process.exitCode = 1` when `--min-recall <n>` is set and aggregate falls below — drop-in CI gate after `kj rag index`.
+
 > **v2.33.0 released** — Minor. **AI Harness Scorecard golden metric (KJC-PCS-0051, Plan B)** — every `kj audit` now boots a Docker one-shot of `addyosmani/ai-harness-scorecard`, gets a deterministic 0–100 score + A–F grade, persists it to a per-project `audit-history.db`, and on the next run renders the delta vs the previous baseline plus an optional Unicode-bar trend sparkline. One golden number for "how AI-friendly is this repo today vs last week," zero LLM tokens spent.
 >
 > - **Harness Docker one-shot** (PR #877, KJC-TSK-0470): `src/audit/harness-runner.js` runs `docker run --rm -v <repo>:/repo addyosmani/ai-harness-scorecard analyze`, parses the verdict, auto-skips on missing Docker. `--no-harness` opts out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -37,6 +37,7 @@
     "bin/",
     "templates/",
     "scripts/",
+    "vendor/tree-sitter-grammars/",
     "packages/hu-board/src/",
     "packages/hu-board/public/",
     "packages/hu-board/package.json",
@@ -85,7 +86,8 @@
     "knip": "^6.14.1",
     "madge": "^8.0.0",
     "sqlite-vec": "^0.1.9",
-    "valibot": "^1.3.1"
+    "valibot": "^1.3.1",
+    "web-tree-sitter": "^0.26.9"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/scripts/git-hooks/post-merge

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# KJC-TSK-0455 — Auto-refresh the local RAG index after a merge so retrieval
+# never serves stale code. Installed by `kj rag install-hooks`. The marker
+# in this comment is how the installer tells kj-managed hooks from user hooks.
+set -euo pipefail
+if ! command -v kj >/dev/null 2>&1; then exit 0; fi
+kj rag index --since auto >/dev/null 2>&1 || true

package/src/audit/basal-cost.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { getKarajanHome } from "../utils/paths.js";
+import { sniffManifests, summariseStack } from "../utils/manifest-sniff.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -59,16 +60,16 @@ async function countLines(filePath) {
   }
 }
 
-async function countDependencies(projectDir) {
-  const pkgPath = path.join(projectDir, "package.json");
-  try {
-    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
-    const deps = Object.keys(pkg.dependencies || {});
-    const devDeps = Object.keys(pkg.devDependencies || {});
-    return { dependencies: deps.length, devDependencies: devDeps.length, total: deps.length + devDeps.length };
-  } catch {
-    return { dependencies: 0, devDependencies: 0, total: 0 };
+function countDependenciesFromStack(stack) {
+  // Suma deps + devDeps de TODOS los manifests detectados (multi-stack).
+  // Si no hay manifests, devuelve ceros — coherente con repos sin paquete.
+  let deps = 0;
+  let devDeps = 0;
+  for (const m of stack.manifests) {
+    deps += m.deps;
+    devDeps += m.devDeps;
   }
+  return { dependencies: deps, devDependencies: devDeps, total: deps + devDeps };
 }
 
 function runDepcheck(projectDir) {
@@ -231,8 +232,11 @@ export async function measureBasalCost(projectDir) {
     totalLines += await countLines(f);
   }
 
-  const depInfo = await countDependencies(projectDir);
-  const depcheck = await runDepcheck(projectDir);
+  const stack = summariseStack(await sniffManifests(projectDir));
+  const depInfo = countDependenciesFromStack(stack);
+  // depcheck solo aplica a Node; en stacks puros no-Node lo saltamos.
+  const hasNode = stack.manifests.some((m) => m.stack === "node");
+  const depcheck = hasNode ? await runDepcheck(projectDir) : { unused: [], note: "depcheck skipped (no package.json)" };
   const deadExports = await findDeadExports(sourceFiles);
 
   return {
@@ -240,7 +244,8 @@ export async function measureBasalCost(projectDir) {
     totalFiles: sourceFiles.length,
     dependencies: depInfo,
     unusedDependencies: depcheck,
-    deadExports
+    deadExports,
+    stack
   };
 }
 

package/src/cli/register-meta.js

@@ -3,7 +3,7 @@ import { triageCommand } from "../commands/triage.js";
 import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
-import { ragIndexCommand, ragQueryCommand } from "../commands/rag.js";
+import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
@@ -104,12 +104,21 @@ export function registerMeta(program, { pkgVersion }) {
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
     .option("--with-sources", "Also index the projectDir's JS/TS files")
+    .option("--since <ref>", "Only re-index files changed since <ref> ('auto' uses the last indexed commit; falls back to full index if unset). KJC-TSK-0455.")
     .option("--json", "Output the totals as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-index", flags, async ({ config, logger }) => {
         await ragIndexCommand({ config, logger, flags });
       });
     });
+  rag.command("install-hooks")
+    .description("Install the post-merge git hook so the RAG index auto-refreshes after pulls/merges (KJC-TSK-0455)")
+    .option("--json", "Output the result as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-install-hooks", flags, async ({ config, logger }) => {
+        await ragInstallHooksCommand({ config, logger, flags });
+      });
+    });
   rag.command("query <text>")
     .description("Run a semantic query against the indexed RAG corpus")
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
@@ -136,6 +145,20 @@ export function registerMeta(program, { pkgVersion }) {
         await ragQueryCommand({ text, config, logger, flags: { ...flags, mode: ragMode } });
       });
     });
+  // KJC-TSK-0483 — `kj rag eval` runs the golden-query harness and reports
+  // recall@5/recall@10/MRR. `--min-recall` turns it into a CI gate.
+  rag.command("eval")
+    .description("Score the retriever against a golden query set (recall@k + MRR)")
+    .option("--golden <path>", "Path to golden queries JSON (default: tests/rag/golden-queries.json)")
+    .option("--top-k <n>", "Number of hits to retrieve per query (default: 10)", "10")
+    .option("--min-recall <n>", "Fail (exit 1) if aggregated recall@5 falls below this threshold")
+    .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project.")
+    .option("--json", "Emit the full report as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-eval", flags, async ({ config, logger }) => {
+        await ragEvalCommand({ config, logger, flags });
+      });
+    });
 
   // KJC-TSK-0441 — `kj watch [start|stop|status]` for live RAG re-index.
   const watch = program.command("watch").description("Live RAG re-index daemon");

package/src/cli/register-pipeline.js

@@ -110,6 +110,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
     .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
+    .option("--no-rag-update", "Skip the pre-run RAG drift check (KJC-TSK-0455). Same as config.rag.autoUpdate.onRun=false.")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")

package/src/commands/rag.js

@@ -2,10 +2,12 @@
 //   kj rag index [--project <slug>] [--with-sources]
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
-import { openVecStore, countChunks, projectSlug } from "../rag/vec-store.js";
+import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeEmbedder } from "../rag/embedders/factory.js";
-import { indexProject } from "../rag/indexer.js";
+import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
+import { installPostMergeHook } from "../rag/auto-update.js";
+import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function openDb(config) {
@@ -16,15 +18,39 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const db = openDb(config);
   try {
-    const totals = await indexProject(projectDir, {
-      db, embedder: makeEmbedder(config),
-      karajanHome: getKarajanHome(), logger,
-      withSources: Boolean(flags.withSources),
-    });
+    const slug = projectSlug(projectDir);
+    const embedder = makeEmbedder(config);
+    const sinceFlag = flags.since;
+    // KJC-TSK-0455 — `--since auto` resolves to the last commit we indexed;
+    // an explicit ref is honoured as-is. Without a baseline (first-time
+    // index) we fall back to a full reindex with a friendly warning so the
+    // hook in PR2 stays a no-op-friendly entrypoint.
+    let since = null;
+    if (sinceFlag) {
+      since = sinceFlag === "auto" ? getLastIndexedCommit(db, slug) : sinceFlag;
+      if (!since) logger.warn?.("[rag] --since auto: no previous index recorded; running full index");
+    }
+    let totals;
+    if (since) {
+      try {
+        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger });
+      } catch (err) {
+        logger.warn?.(`[rag] delta index failed (${err.message}); falling back to full index`);
+        totals = null;
+      }
+    }
+    if (!totals) {
+      totals = await indexProject(projectDir, {
+        db, embedder,
+        karajanHome: getKarajanHome(), logger,
+        withSources: Boolean(flags.withSources),
+      });
+    }
+    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(totals)}\n`);
     } else {
-      logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed)`);
+      logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed${totals.deleted ? `, ${totals.deleted} chunks deleted` : ""})`);
     }
     return totals;
   } finally {
@@ -32,6 +58,18 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   }
 }
 
+// KJC-TSK-0455 — `kj rag install-hooks` wires the post-merge hook so the
+// local index keeps up after `git pull` / merges. Opt-in to keep us from
+// silently writing under `.git/hooks/`; pre-run drift check covers users
+// who never run it.
+export async function ragInstallHooksCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const res = installPostMergeHook({ projectDir, logger });
+  if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+  else if (res.installed) logger.info(`[rag] installed post-merge hook at ${res.target}`);
+  return res;
+}
+
 export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   if (!text) throw new Error("kj rag query: text argument required");
   const db = openDb(config);
@@ -75,3 +113,39 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     db.close();
   }
 }
+
+// KJC-TSK-0483 — `kj rag eval`. Runs the retriever against a golden query
+// set and reports recall@5, recall@10 and MRR per query and aggregated.
+// Exit code != 0 when `--min-recall` is set and the aggregated recall@5
+// falls below the threshold — lets CI fail noisily on retrieval regressions.
+const DEFAULT_GOLDEN = "tests/rag/golden-queries.json";
+export async function ragEvalCommand({ config, logger, flags = {} }) {
+  const db = openDb(config);
+  try {
+    const goldenPath = flags.golden || DEFAULT_GOLDEN;
+    const queries = loadGoldenQueries(goldenPath);
+    const topK = Math.max(1, Number(flags.topK) || 10);
+    const detected = projectSlug(config?.projectDir || process.cwd());
+    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    const embedder = makeEmbedder(config);
+    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project });
+    const report = await runEval(queries, runQuery, { topK, ks: [5, 10] });
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(report)}\n`);
+    } else {
+      logger.info(`[rag-eval] ${report.aggregate.n} queries · recall@5=${report.aggregate.recall["@5"].toFixed(3)} · recall@10=${report.aggregate.recall["@10"].toFixed(3)} · MRR=${report.aggregate.mrr.toFixed(3)}`);
+      for (const r of report.results) {
+        const rank = r.firstRank == null ? "—" : `#${r.firstRank}`;
+        logger.info(`  [${rank}] ${r.query}`);
+      }
+    }
+    const minRecall = Number(flags.minRecall);
+    if (Number.isFinite(minRecall) && report.aggregate.recall["@5"] < minRecall) {
+      logger.error?.(`[rag-eval] recall@5=${report.aggregate.recall["@5"].toFixed(3)} below --min-recall=${minRecall}`);
+      process.exitCode = 1;
+    }
+    return report;
+  } finally {
+    db.close();
+  }
+}

package/src/commands/run.js

@@ -12,6 +12,7 @@ import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
+import { maybeAutoUpdate } from "../rag/auto-update.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -84,6 +85,13 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
   }
 
+  // KJC-TSK-0455 — Pre-run drift check. Default ON; opt out with
+  // --no-rag-update (flag) or config.rag.autoUpdate.onRun=false. If the
+  // local index is behind HEAD we re-embed the delta before the agents
+  // start reading from the RAG store; on any failure we log and move on
+  // so a broken vector store never blocks a run.
+  await maybeAutoUpdate({ projectDir, config, logger, flags });
+
   // Best-effort session cleanup before starting
   try {
     const { cleanupExpiredSessions } = await import("../session-cleanup.js");

package/src/config/defaults.js

@@ -189,6 +189,13 @@ const DEFAULTS = {
     devtools_mcp: false,
     thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
   },
+  rag: {
+    // KJC-TSK-0455 — Auto-refresh the local RAG index. `onRun` runs a
+    // delta re-index before every `kj run`; `onCommit` is consulted by
+    // `kj rag install-hooks` to decide whether to install the post-merge
+    // hook. Both default ON; flip to false to opt out without uninstalling.
+    autoUpdate: { onCommit: true, onRun: true }
+  },
   telemetry: true,
   guards: {
     output: {

package/src/lang/chunk-go.js

@@ -0,0 +1,94 @@
+// KJC-PCS-0052 PR-B.2.3 — Go source chunker (tree-sitter + regex fallback).
+// Mismo contrato síncrono que chunk-rust: AST si el caller awaited
+// `prepareGo()` antes, regex si no. Top-level: func / method / type.
+//
+// `method_declaration` (con receiver) y `function_declaration` se tratan
+// igual — symbol es el nombre, sin componer "Recv.Method" (coherente con
+// Python: del scope se ocupa la búsqueda semántica, no el chunk).
+// `type_declaration` contiene type_spec(s); usamos el primero como symbol.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const NAMED_KINDS = new Set([
+  "function_declaration",
+  "method_declaration",
+]);
+const TOP_RE = /^(?:func(?:\s+\([^)]+\))?|type)\s+([A-Za-z_]\w*)/gm;
+
+export async function prepareGo() {
+  return loadLanguage("go");
+}
+
+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 symbolForType(node) {
+  for (const spec of node.namedChildren) {
+    if (spec.type === "type_spec" || spec.type === "type_alias") {
+      const nameNode = spec.childForFieldName("name");
+      if (nameNode) return nameNode.text;
+    }
+  }
+  return null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("go");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    let symbol = null;
+    if (NAMED_KINDS.has(child.type)) {
+      const nameNode = child.childForFieldName("name");
+      if (nameNode) symbol = nameNode.text;
+    } else if (child.type === "type_declaration") {
+      symbol = symbolForType(child);
+    }
+    if (symbol) marks.push({ idx: child.startIndex, symbol });
+  }
+  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 chunkGo(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: "go" },
+    }));
+  }
+  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: "go" } });
+    }
+  }
+  return out;
+}

package/src/lang/chunk-java.js

@@ -0,0 +1,90 @@
+// KJC-PCS-0052 PR-B.2.5 — Java chunker (tree-sitter + regex fallback).
+// Walker 2 niveles: top-level emite class/interface/enum/record; segundo pase
+// desciende al body por method_declaration / constructor_declaration. Symbol
+// sin prefijar (coherente con chunk-go), el RAG ya lleva contexto del fichero.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const CONTAINER_KINDS = new Set([
+  "class_declaration",
+  "interface_declaration",
+  "enum_declaration",
+  "record_declaration",
+]);
+const MEMBER_KINDS = new Set([
+  "method_declaration",
+  "constructor_declaration",
+]);
+const TOP_RE = /^[ \t]*(?:public\s+|private\s+|protected\s+|static\s+|final\s+|abstract\s+|sealed\s+|non-sealed\s+)*(class|interface|enum|record)\s+([A-Za-z_]\w*)/gm;
+
+export async function prepareJava() {
+  return loadLanguage("java");
+}
+
+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 nameOf(node) {
+  const n = node.childForFieldName("name");
+  return n ? n.text : null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("java");
+  if (!entry) return null;
+  let tree;
+  try { tree = entry.parser.parse(text); } catch { return null; }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    if (!CONTAINER_KINDS.has(child.type)) continue;
+    const s = nameOf(child);
+    if (s) marks.push({ idx: child.startIndex, symbol: s });
+    const body = child.childForFieldName("body");
+    if (!body) continue;
+    for (const m of body.namedChildren) {
+      if (!MEMBER_KINDS.has(m.type)) continue;
+      const ms = nameOf(m);
+      if (ms) marks.push({ idx: m.startIndex, symbol: ms });
+    }
+  }
+  marks.sort((a, b) => a.idx - b.idx);
+  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[2] });
+  return marks;
+}
+
+export function chunkJava(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: "java" },
+    }));
+  }
+  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: "java" } });
+    }
+  }
+  return out;
+}

package/src/lang/chunk-python.js

@@ -0,0 +1,88 @@
+// KJC-PCS-0052 PR-B.2.1 — Python source chunker (tree-sitter + regex fallback).
+// Top-level `def`/`async def`/`class` siguen siendo la frontera de chunk, pero
+// ahora con dos caminos:
+//   1. AST (web-tree-sitter): si el caller hizo `await preparePython()` antes
+//      del indexado, leemos el árbol y capturamos solo nodos cuyo `parent.type`
+//      es `module` — eso excluye métodos anidados sin depender de la
+//      indentación visual y captura decoradores (`decorated_definition`)
+//      apuntando al def/class real subyacente.
+//   2. Regex: fallback síncrono para entornos sin tree-sitter listo (tests
+//      legacy, primera invocación antes de `preparePython`). Misma semántica
+//      que PR-B.
+//
+// El contrato externo no cambia: `chunkPython(text, opts)` es síncrono y
+// devuelve `[{ text, metadata: { source, kind, symbol, language } }]`.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const TOP_RE = /^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm;
+
+export async function preparePython() {
+  return loadLanguage("python");
+}
+
+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 marksViaAST(text) {
+  const entry = getLoaded("python");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    let defNode = null;
+    if (child.type === "function_definition" || child.type === "class_definition") {
+      defNode = child;
+    } else if (child.type === "decorated_definition") {
+      defNode = child.childForFieldName("definition");
+    }
+    if (!defNode) continue;
+    const nameNode = defNode.childForFieldName("name");
+    if (!nameNode) continue;
+    marks.push({ idx: child.startIndex, symbol: nameNode.text });
+  }
+  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 chunkPython(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: "python" },
+    }));
+  }
+  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: "python" } });
+    }
+  }
+  return out;
+}