@karajan-family/code 4.21.0

package/src/infrastructure/command-runner.js

@@ -0,0 +1,44 @@
+/**
+ * CommandRunner — DI-friendly adapter over execa / runCommand.
+ *
+ * Why: agent adapters (claude, codex, gemini, ...) all end up invoking
+ * src/utils/process.js -> runCommand. That makes unit-testing the agent layer
+ * slow and flaky — every test either spins up a real child process or stubs
+ * execa deep inside Vitest's module graph.
+ *
+ * This adapter preserves the runCommand API exactly, so current consumers
+ * can opt-in to DI without behavioural changes. A matching MockCommandRunner
+ * lives in src/infrastructure/mocks.js and lets tests script outputs per
+ * invocation.
+ *
+ * @typedef {Object} CommandRunResult
+ * @property {number} exitCode
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {boolean} [timedOut]
+ * @property {string|null} [signal]
+ *
+ * @typedef {Object} CommandRunOptions
+ * @property {number} [timeout]
+ * @property {(evt: {stream: string, line: string}) => void} [onOutput]
+ * @property {number} [silenceTimeoutMs]
+ * @property {number} [partialOutputFlushMs]
+ * @property {string|Buffer} [input]
+ * @property {string} [cwd]
+ * @property {Record<string,string>} [env]
+ *
+ * @typedef {Object} CommandRunner
+ * @property {(command: string, args?: string[], options?: CommandRunOptions) => Promise<CommandRunResult>} run
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Default implementation — delegates to runCommand.
+ * @type {CommandRunner}
+ */
+export const defaultCommandRunner = {
+  async run(command, args = [], options = {}) {
+    return runCommand(command, args, options);
+  }
+};

package/src/infrastructure/environment.js

@@ -0,0 +1,38 @@
+/**
+ * Environment — the DI bundle passed to services that need filesystem + command
+ * execution. Grouping them keeps call sites small: `new BaseAgent(..., env)`
+ * instead of `new BaseAgent(..., fs, runner)`.
+ *
+ * @typedef {import("./file-system-service.js").FileSystemService} FileSystemService
+ * @typedef {import("./command-runner.js").CommandRunner} CommandRunner
+ *
+ * @typedef {Object} Environment
+ * @property {FileSystemService} fs
+ * @property {CommandRunner} runner
+ */
+
+import { defaultFileSystem } from "./file-system-service.js";
+import { defaultCommandRunner } from "./command-runner.js";
+
+/**
+ * Default environment uses native fs + real execa-based runner.
+ * Tests should inject a custom environment via buildEnvironment() below.
+ * @type {Environment}
+ */
+export const defaultEnvironment = Object.freeze({
+  fs: defaultFileSystem,
+  runner: defaultCommandRunner
+});
+
+/**
+ * Merge overrides on top of the default environment. Missing properties fall
+ * back to defaults, so callers can replace only the pieces they care about.
+ * @param {Partial<Environment>} [overrides]
+ * @returns {Environment}
+ */
+export function buildEnvironment(overrides = {}) {
+  return Object.freeze({
+    fs: overrides.fs ?? defaultFileSystem,
+    runner: overrides.runner ?? defaultCommandRunner
+  });
+}

package/src/infrastructure/file-system-service.js

@@ -0,0 +1,63 @@
+/**
+ * FileSystemService — thin DI-friendly adapter over node:fs/promises.
+ *
+ * Why: existing code uses node:fs directly (see src/utils/fs.js and consumers),
+ * which makes unit-testing orchestrator/agent paths slow and flaky — every test
+ * that exercises a code path touching fs has to stage real files on disk.
+ *
+ * This adapter preserves the exact native API shapes for the handful of
+ * operations actually used in the codebase, so consumers can opt-in to DI
+ * without rewriting call sites. A matching MockFileSystem lives in
+ * src/infrastructure/mocks.js.
+ *
+ * Scope for TSK-0316: intentionally minimal. Only the operations already used
+ * by orchestrator + agents. Additional methods added on demand.
+ *
+ * @typedef {Object} FileSystemService
+ * @property {(path: string, encoding?: string) => Promise<string|Buffer>} readFile
+ * @property {(path: string, data: string|Buffer, encoding?: string) => Promise<void>} writeFile
+ * @property {(path: string, data: string|Buffer, encoding?: string) => Promise<void>} appendFile
+ * @property {(path: string) => Promise<boolean>} exists
+ * @property {(path: string) => Promise<void>} ensureDir
+ * @property {(path: string) => Promise<string[]>} readdir
+ * @property {(src: string, dest: string) => Promise<void>} copyFile
+ * @property {(path: string) => Promise<{size: number, isDirectory: () => boolean, isFile: () => boolean}>} stat
+ */
+
+import fs from "node:fs/promises";
+
+/**
+ * Default implementation backed by node:fs/promises.
+ * @type {FileSystemService}
+ */
+export const defaultFileSystem = {
+  async readFile(path, encoding = "utf8") {
+    return fs.readFile(path, encoding);
+  },
+  async writeFile(path, data, encoding = "utf8") {
+    await fs.writeFile(path, data, encoding);
+  },
+  async appendFile(path, data, encoding = "utf8") {
+    await fs.appendFile(path, data, encoding);
+  },
+  async exists(path) {
+    try {
+      await fs.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async ensureDir(path) {
+    await fs.mkdir(path, { recursive: true });
+  },
+  async readdir(path) {
+    return fs.readdir(path);
+  },
+  async copyFile(src, dest) {
+    await fs.copyFile(src, dest);
+  },
+  async stat(path) {
+    return fs.stat(path);
+  }
+};

package/src/infrastructure/mocks.js

@@ -0,0 +1,182 @@
+/**
+ * Test doubles for the DI surfaces. Intentionally dumb — tests stage inputs
+ * through simple setters and assert on recorded calls.
+ *
+ * @typedef {import("./file-system-service.js").FileSystemService} FileSystemService
+ * @typedef {import("./command-runner.js").CommandRunner} CommandRunner
+ * @typedef {import("./command-runner.js").CommandRunResult} CommandRunResult
+ * @typedef {import("./command-runner.js").CommandRunOptions} CommandRunOptions
+ */
+
+/**
+ * In-memory file system. Paths are stored as-is (no normalization) to keep
+ * behaviour predictable in tests.
+ */
+export class MockFileSystem {
+  constructor(initial = {}) {
+    /** @type {Map<string, string|Buffer>} */
+    this.files = new Map(Object.entries(initial));
+    /** @type {Set<string>} */
+    this.directories = new Set();
+    /** @type {Array<{op: string, path: string, args?: unknown}>} */
+    this.calls = [];
+  }
+
+  _record(op, path, args) {
+    this.calls.push({ op, path, args });
+  }
+
+  async readFile(path, encoding = "utf8") {
+    this._record("readFile", path, { encoding });
+    if (!this.files.has(path)) {
+      const err = new Error(`ENOENT: no such file or directory, open '${path}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    const data = this.files.get(path);
+    if (Buffer.isBuffer(data) && encoding) return data.toString(encoding);
+    return data;
+  }
+
+  async writeFile(path, data, encoding = "utf8") {
+    this._record("writeFile", path, { encoding });
+    this.files.set(path, data);
+  }
+
+  async appendFile(path, data, encoding = "utf8") {
+    this._record("appendFile", path, { encoding });
+    const prev = this.files.get(path) ?? "";
+    this.files.set(path, String(prev) + String(data));
+  }
+
+  async exists(path) {
+    this._record("exists", path);
+    return this.files.has(path) || this.directories.has(path);
+  }
+
+  async ensureDir(path) {
+    this._record("ensureDir", path);
+    this.directories.add(path);
+  }
+
+  async readdir(path) {
+    this._record("readdir", path);
+    const prefix = path.endsWith("/") ? path : path + "/";
+    const entries = new Set();
+    for (const p of this.files.keys()) {
+      if (p.startsWith(prefix)) {
+        const tail = p.slice(prefix.length).split("/")[0];
+        if (tail) entries.add(tail);
+      }
+    }
+    if (!entries.size && !this.directories.has(path)) {
+      const err = new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    return [...entries];
+  }
+
+  async copyFile(src, dest) {
+    this._record("copyFile", src, { dest });
+    if (!this.files.has(src)) {
+      const err = new Error(`ENOENT: no such file or directory, copyfile '${src}' -> '${dest}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    this.files.set(dest, this.files.get(src));
+  }
+
+  async stat(path) {
+    this._record("stat", path);
+    if (this.files.has(path)) {
+      const data = this.files.get(path);
+      const size = Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data));
+      return {
+        size,
+        isDirectory: () => false,
+        isFile: () => true
+      };
+    }
+    if (this.directories.has(path)) {
+      return {
+        size: 0,
+        isDirectory: () => true,
+        isFile: () => false
+      };
+    }
+    const err = new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    err.code = "ENOENT";
+    throw err;
+  }
+}
+
+/**
+ * Scripted command runner. Tests call enqueue() to stage responses in order,
+ * or setResponder() for a per-invocation decision. Every run() is recorded.
+ */
+export class MockCommandRunner {
+  constructor() {
+    /** @type {Array<CommandRunResult>} */
+    this.queue = [];
+    /** @type {Array<{command: string, args: string[], options: CommandRunOptions}>} */
+    this.calls = [];
+    /** @type {null | ((args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>)} */
+    this.responder = null;
+    /** @type {CommandRunResult} */
+    this.defaultResponse = { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  /**
+   * Queue a response. FIFO — first enqueued is returned on the first run().
+   * @param {Partial<CommandRunResult>} response
+   */
+  enqueue(response) {
+    this.queue.push({ exitCode: 0, stdout: "", stderr: "", ...response });
+    return this;
+  }
+
+  /**
+   * Replace FIFO queue with a function that decides per-call.
+   * @param {(args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>} fn
+   */
+  setResponder(fn) {
+    this.responder = fn;
+    return this;
+  }
+
+  /**
+   * @param {string} command
+   * @param {string[]} args
+   * @param {CommandRunOptions} options
+   * @returns {Promise<CommandRunResult>}
+   */
+  async run(command, args = [], options = {}) {
+    this.calls.push({ command, args: [...args], options: { ...options } });
+    if (this.responder) return this.responder({ command, args, options });
+    if (this.queue.length > 0) return this.queue.shift();
+    return { ...this.defaultResponse };
+  }
+
+  /**
+   * Convenience: last recorded invocation, or null.
+   */
+  get lastCall() {
+    return this.calls.at(-1) ?? null;
+  }
+}
+
+/**
+ * Build an Environment backed by the mocks above. Useful shorthand in tests:
+ *
+ *   const { env, fs, runner } = buildMockEnvironment();
+ *   const agent = new BaseAgent(..., env);
+ *
+ * @param {{files?: Record<string, string|Buffer>}} [opts]
+ */
+export function buildMockEnvironment({ files } = {}) {
+  const fs = new MockFileSystem(files);
+  const runner = new MockCommandRunner();
+  const env = Object.freeze({ fs, runner });
+  return { env, fs, runner };
+}

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;
+}