error-trace-debugger 0.1.0

package/src/core/Orchestrator.js

@@ -0,0 +1,190 @@
+import { create_initial_state, is_budget_exceeded } from "./state.js";
+
+export class Orchestrator {
+  #tools;
+  #repo_path;
+  #max_iterations;
+  #budget_ms;
+  #run_tests;
+  #test_command;
+
+  constructor({
+    repo_path,
+    tools,
+    max_iterations = 5,
+    budget_ms,
+    run_tests = false,
+    test_command
+  }) {
+    this.#repo_path = repo_path;
+    this.#tools = tools;
+    this.#max_iterations = max_iterations;
+    this.#budget_ms = budget_ms;
+    this.#run_tests = run_tests;
+    this.#test_command = test_command;
+  }
+
+  async run({ raw_logs }) {
+    const state = create_initial_state({
+      repo_path: this.#repo_path,
+      raw_logs,
+      max_iterations: this.#max_iterations,
+      budget_ms: this.#budget_ms,
+      run_tests: this.#run_tests,
+      test_command: this.#test_command
+    });
+
+    state.log_artifact = await this.#tools.log_analyzer.run({
+      raw_logs: state.raw_logs,
+      repo_path: state.repo_path
+    });
+    state.investigation_steps.push({
+      tool_name: "log_analyzer",
+      summary: "Parsed logs into frames and signals.",
+      output: summarize_log_artifact(state.log_artifact)
+    });
+
+    while (state.iteration_index < state.max_iterations) {
+      if (is_budget_exceeded(state)) break;
+
+      const hypothesis = build_hypothesis_from_artifact(state.log_artifact, {
+        iteration_index: state.iteration_index
+      });
+      state.hypotheses.push(hypothesis);
+
+      const search_queries = build_search_queries(state.log_artifact, hypothesis);
+      const search_result = await this.#tools.code_search.run({
+        repo_path: state.repo_path,
+        queries: search_queries
+      });
+
+      state.investigation_steps.push({
+        tool_name: "code_search",
+        summary: "Searched the codebase for likely relevant symbols/strings.",
+        output: {
+          queries: search_queries,
+          match_count: search_result.matches.length,
+          top_matches: search_result.matches.slice(0, 10)
+        }
+      });
+
+      const patch_plan = await this.#tools.diff_generator.run({
+        repo_path: state.repo_path,
+        log_artifact: state.log_artifact,
+        hypothesis,
+        search_matches: search_result.matches
+      });
+
+      state.fix_plan = patch_plan.fix_plan;
+      state.patch_text = patch_plan.patch_text || "";
+      state.investigation_steps.push({
+        tool_name: "diff_generator",
+        summary: "Proposed a fix plan and generated a patch (if possible).",
+        output: {
+          has_patch: Boolean(state.patch_text && state.patch_text.trim().length > 0),
+          edit_count: state.fix_plan?.edits?.length ?? 0
+        }
+      });
+
+      if (state.run_tests) {
+        state.validation_result = await this.#tools.test_runner.run({
+          repo_path: state.repo_path,
+          test_command: state.test_command
+        });
+        state.investigation_steps.push({
+          tool_name: "test_runner",
+          summary: "Executed tests and summarized results.",
+          output: {
+            ok: state.validation_result.ok,
+            exit_code: state.validation_result.exit_code,
+            detected_command: state.validation_result.detected_command
+          }
+        });
+
+        if (state.validation_result.ok) break;
+      }
+
+      if (state.patch_text && state.patch_text.trim().length > 0) break;
+      state.iteration_index += 1;
+    }
+
+    if (state.run_tests && state.validation_result) {
+      state.has_error = !state.validation_result.ok;
+    }
+
+    return {
+      repo_path: state.repo_path,
+      raw_logs: state.raw_logs,
+      log_artifact: state.log_artifact,
+      hypotheses: state.hypotheses,
+      investigation_steps: state.investigation_steps,
+      fix_plan: state.fix_plan,
+      patch_text: state.patch_text,
+      validation_result: state.validation_result,
+      has_error: state.has_error
+    };
+  }
+}
+
+function summarize_log_artifact(log_artifact) {
+  return {
+    error_name: log_artifact.error_name,
+    error_message: log_artifact.error_message,
+    frame_count: log_artifact.frames.length,
+    top_frames: log_artifact.frames.slice(0, 5)
+  };
+}
+
+function build_hypothesis_from_artifact(log_artifact, { iteration_index }) {
+  const top_frame = log_artifact.frames.find((frame) => frame.is_repo_frame) || null;
+  const claim = top_frame
+    ? `Likely failing near ${top_frame.file_path}:${top_frame.line_number}.`
+    : "Likely failing in application code referenced by the stack trace.";
+
+  return {
+    iteration_index,
+    claim,
+    confidence: top_frame ? 0.6 : 0.3,
+    predicted_locations: top_frame
+      ? [{ file_path: top_frame.file_path, line_number: top_frame.line_number }]
+      : [],
+    evidence: {
+      error_name: log_artifact.error_name,
+      error_message: log_artifact.error_message,
+      top_frame
+    }
+  };
+}
+
+function build_search_queries(log_artifact, hypothesis) {
+  const queries = new Set();
+
+  if (log_artifact.error_name) queries.add(log_artifact.error_name);
+  if (log_artifact.error_message) {
+    for (const token of tokenize(log_artifact.error_message)) queries.add(token);
+  }
+
+  for (const location of hypothesis.predicted_locations) {
+    const basename = location.file_path.split("/").pop();
+    if (basename) queries.add(basename);
+  }
+
+  for (const frame of log_artifact.frames.slice(0, 10)) {
+    if (frame.function_name) queries.add(frame.function_name);
+    if (frame.file_path) {
+      const basename = frame.file_path.split("/").pop();
+      if (basename) queries.add(basename);
+    }
+  }
+
+  return [...queries].filter((q) => q && q.trim().length >= 3).slice(0, 25);
+}
+
+function tokenize(text) {
+  return text
+    .split(/[^a-zA-Z0-9_./-]+/g)
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .slice(0, 20);
+}
+

package/src/core/report_writer.js

@@ -0,0 +1,161 @@
+export function write_report(final_report, { format = "md" } = {}) {
+  if (format === "json") {
+    return `${JSON.stringify(final_report, null, 2)}\n`;
+  }
+
+  if (format === "text") {
+    return write_text_report(final_report);
+  }
+
+  return write_markdown_report(final_report);
+}
+
+function write_text_report(final_report) {
+  const lines = [];
+  lines.push(`repo: ${final_report.repo_path}`);
+  if (final_report.log_artifact?.error_name) {
+    lines.push(`error: ${final_report.log_artifact.error_name}`);
+  }
+  if (final_report.log_artifact?.error_message) {
+    lines.push(`message: ${final_report.log_artifact.error_message}`);
+  }
+  if (final_report.log_artifact?.frames?.length) {
+    const top_frame = final_report.log_artifact.frames.find((f) => f.is_repo_frame)
+      || final_report.log_artifact.frames[0];
+    if (top_frame) {
+      lines.push(`top_frame: ${top_frame.file_path}:${top_frame.line_number ?? "?"}`);
+    }
+  }
+  lines.push("");
+
+  const top_hypothesis = final_report.hypotheses?.[0];
+  if (top_hypothesis) {
+    lines.push(`hypothesis: ${top_hypothesis.claim}`);
+    lines.push(`confidence: ${top_hypothesis.confidence}`);
+    lines.push("");
+  }
+
+  if (final_report.investigation_steps?.length) {
+    lines.push("investigation_steps:");
+    for (const step of final_report.investigation_steps) {
+      lines.push(`- ${step.tool_name}: ${step.summary}`);
+    }
+    lines.push("");
+  }
+
+  if (final_report.fix_plan?.summary) {
+    lines.push("suggested fix:");
+    lines.push(final_report.fix_plan.summary);
+    lines.push("");
+  }
+
+  if (final_report.patch_text && final_report.patch_text.trim().length > 0) {
+    lines.push("patch:");
+    lines.push(final_report.patch_text);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function write_markdown_report(final_report) {
+  const lines = [];
+  lines.push("## Deep Agent report");
+  lines.push("");
+  lines.push(`- **repo**: \`${final_report.repo_path}\``);
+
+  const artifact = final_report.log_artifact;
+  if (artifact?.error_name) lines.push(`- **error**: \`${artifact.error_name}\``);
+  if (artifact?.error_message) lines.push(`- **message**: ${escape_md(artifact.error_message)}`);
+
+  lines.push("");
+
+  if (artifact?.frames?.length) {
+    lines.push("## Stack (top frames)");
+    lines.push("");
+    lines.push("```");
+    for (const frame of artifact.frames.slice(0, 8)) {
+      const fn_part = frame.function_name ? `${frame.function_name} ` : "";
+      const loc = `${frame.file_path}:${frame.line_number ?? "?"}:${frame.column_number ?? "?"}`;
+      lines.push(`${fn_part}${loc}${frame.is_repo_frame ? " [repo]" : ""}`);
+    }
+    lines.push("```");
+    lines.push("");
+  }
+
+  if (final_report.hypotheses?.length) {
+    const hypothesis = final_report.hypotheses[0];
+    lines.push("## Hypothesis");
+    lines.push("");
+    lines.push(`- **claim**: ${escape_md(hypothesis.claim)}`);
+    lines.push(`- **confidence**: ${hypothesis.confidence}`);
+    if (hypothesis.predicted_locations?.length) {
+      lines.push("");
+      lines.push("Likely locations:");
+      for (const location of hypothesis.predicted_locations) {
+        lines.push(
+          `- \`${location.file_path}:${location.line_number ?? "?"}\``
+        );
+      }
+    }
+    lines.push("");
+  }
+
+  if (final_report.investigation_steps?.length) {
+    lines.push("## Investigation timeline");
+    lines.push("");
+    for (const step of final_report.investigation_steps) {
+      lines.push(`- **${step.tool_name}**: ${escape_md(step.summary)}`);
+    }
+    lines.push("");
+  }
+
+  if (final_report.fix_plan) {
+    lines.push("## Suggested fix");
+    lines.push("");
+    if (final_report.fix_plan.summary) lines.push(escape_md(final_report.fix_plan.summary));
+    if (final_report.fix_plan.edits?.length) {
+      lines.push("");
+      lines.push("Edits:");
+      for (const edit of final_report.fix_plan.edits) {
+        lines.push(`- \`${edit.file_path}\` (${edit.reason || "reason omitted"})`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (final_report.validation_result) {
+    lines.push("## Tests");
+    lines.push("");
+    lines.push(`- **ok**: ${final_report.validation_result.ok}`);
+    if (final_report.validation_result.detected_command) {
+      lines.push(
+        `- **command**: \`${final_report.validation_result.detected_command}\``
+      );
+    }
+    if (final_report.validation_result.summary) {
+      lines.push("");
+      lines.push("Output summary:");
+      lines.push("");
+      lines.push("```");
+      lines.push(final_report.validation_result.summary);
+      lines.push("```");
+    }
+    lines.push("");
+  }
+
+  if (final_report.patch_text && final_report.patch_text.trim().length > 0) {
+    lines.push("## Patch");
+    lines.push("");
+    lines.push("```diff");
+    lines.push(final_report.patch_text.trimEnd());
+    lines.push("```");
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function escape_md(text) {
+  return String(text).replaceAll("\r", "");
+}
+

package/src/core/state.js

@@ -0,0 +1,33 @@
+export function create_initial_state({
+  repo_path,
+  raw_logs,
+  max_iterations,
+  budget_ms,
+  run_tests,
+  test_command
+}) {
+  return {
+    repo_path,
+    raw_logs,
+    max_iterations,
+    budget_ms,
+    run_tests,
+    test_command,
+    started_at_ms: Date.now(),
+    iteration_index: 0,
+    investigation_steps: [],
+    hypotheses: [],
+    log_artifact: null,
+    fix_plan: null,
+    patch_text: "",
+    validation_result: null,
+    has_error: false
+  };
+}
+
+export function is_budget_exceeded(state) {
+  if (!Number.isFinite(state.budget_ms)) return false;
+  const elapsed_ms = Date.now() - state.started_at_ms;
+  return elapsed_ms >= state.budget_ms;
+}
+

package/src/core/write_text_file.js

@@ -0,0 +1,8 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function write_text_file(target_path, contents) {
+  await fs.mkdir(path.dirname(target_path), { recursive: true });
+  await fs.writeFile(target_path, contents, "utf8");
+}
+

package/src/tools/CodeSearchTool.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { execa } from "execa";
+import fg from "fast-glob";
+import ignore from "ignore";
+
+const DEFAULT_MAX_MATCHES = 300;
+const DEFAULT_MAX_LINES_PER_QUERY = 200;
+const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 5 * 1024 * 1024;
+
+export class CodeSearchTool {
+  #repo_path;
+  #has_ripgrep_promise;
+
+  constructor({ repo_path }) {
+    this.#repo_path = repo_path;
+    this.#has_ripgrep_promise = null;
+  }
+
+  async run({ repo_path, queries }) {
+    const resolved_repo_path = repo_path || this.#repo_path;
+    const normalized_queries = (queries || []).map((q) => String(q)).filter(Boolean);
+
+    const has_ripgrep = await this.#has_ripgrep();
+    if (has_ripgrep) {
+      return await this.#run_with_ripgrep(resolved_repo_path, normalized_queries);
+    }
+
+    return await this.#run_with_fallback_scan(resolved_repo_path, normalized_queries);
+  }
+
+  async #has_ripgrep() {
+    if (this.#has_ripgrep_promise) return this.#has_ripgrep_promise;
+    this.#has_ripgrep_promise = (async () => {
+      try {
+        await execa("rg", ["--version"], { reject: true });
+        return true;
+      } catch {
+        return false;
+      }
+    })();
+    return this.#has_ripgrep_promise;
+  }
+
+  async #run_with_ripgrep(repo_path, queries) {
+    const matches = [];
+    const unique_queries = [...new Set(queries)].slice(0, 25);
+
+    for (const query of unique_queries) {
+      const result = await execa(
+        "rg",
+        [
+          "--no-heading",
+          "--line-number",
+          "--color",
+          "never",
+          "--fixed-strings",
+          "--smart-case",
+          "--glob",
+          "!**/node_modules/**",
+          "--glob",
+          "!**/dist/**",
+          "--glob",
+          "!**/build/**",
+          query
+        ],
+        { cwd: repo_path, reject: false }
+      );
+
+      if (result.exitCode !== 0 && result.exitCode !== 1) continue;
+      const lines = String(result.stdout || "").split(/\r?\n/g).filter(Boolean);
+      for (const line of lines.slice(0, DEFAULT_MAX_LINES_PER_QUERY)) {
+        const parsed = parse_ripgrep_line(line);
+        if (parsed) matches.push({ query, ...parsed });
+      }
+    }
+
+    return { matches: matches.slice(0, DEFAULT_MAX_MATCHES) };
+  }
+
+  async #run_with_fallback_scan(repo_path, queries) {
+    const ig = await load_ignore(repo_path);
+    const candidates = await fg(["**/*.*"], {
+      cwd: repo_path,
+      dot: false,
+      onlyFiles: true,
+      followSymbolicLinks: false
+    });
+
+    const matches = [];
+    const unique_queries = [...new Set(queries)].slice(0, 25);
+    let total_bytes_read = 0;
+
+    for (const rel_path of candidates) {
+      if (!should_scan_file(rel_path)) continue;
+      if (ig.ignores(rel_path)) continue;
+
+      const absolute_path = path.join(repo_path, rel_path);
+      let contents = "";
+      try {
+        const stat = await fs.stat(absolute_path);
+        if (!stat.isFile()) continue;
+        if (stat.size > DEFAULT_MAX_FILE_BYTES) continue;
+        if (total_bytes_read + stat.size > DEFAULT_MAX_TOTAL_BYTES) break;
+
+        contents = await fs.readFile(absolute_path, "utf8");
+        total_bytes_read += Buffer.byteLength(contents, "utf8");
+      } catch {
+        continue;
+      }
+
+      for (const query of unique_queries) {
+        const index = contents.indexOf(query);
+        if (index < 0) continue;
+        matches.push({
+          query,
+          file_path: rel_path,
+          line_number: guess_line_number(contents, index),
+          snippet: extract_snippet(contents, index, query.length)
+        });
+      }
+
+      if (matches.length >= DEFAULT_MAX_MATCHES) break;
+    }
+
+    return { matches };
+  }
+}
+
+function parse_ripgrep_line(line) {
+  const match = line.match(/^(?<file_path>.*?):(?<line_number>\d+):(?<snippet>.*)$/);
+  if (!match?.groups) return null;
+  return {
+    file_path: match.groups.file_path,
+    line_number: Number(match.groups.line_number),
+    snippet: match.groups.snippet
+  };
+}
+
+function should_scan_file(rel_path) {
+  if (rel_path.startsWith("node_modules/")) return false;
+  if (rel_path.startsWith("dist/")) return false;
+  if (rel_path.startsWith("build/")) return false;
+  if (rel_path.includes("/.git/")) return false;
+  return true;
+}
+
+async function load_ignore(repo_path) {
+  const ig = ignore();
+  ig.add(["node_modules/", "dist/", "build/", ".git/"]);
+  try {
+    const gitignore = await fs.readFile(path.join(repo_path, ".gitignore"), "utf8");
+    ig.add(gitignore.split(/\r?\n/g));
+  } catch {
+    // ignore
+  }
+  return ig;
+}
+
+function guess_line_number(contents, index) {
+  return contents.slice(0, index).split("\n").length;
+}
+
+function extract_snippet(contents, index, length) {
+  const start_index = Math.max(0, index - 60);
+  const end_index = Math.min(contents.length, index + length + 60);
+  return contents.slice(start_index, end_index).replaceAll("\n", "\\n");
+}
+

package/src/tools/GitDiffTool.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { createTwoFilesPatch } from "diff";
+
+export class GitDiffTool {
+  #repo_path;
+
+  constructor({ repo_path }) {
+    this.#repo_path = repo_path;
+  }
+
+  async run({
+    repo_path,
+    log_artifact,
+    hypothesis,
+    search_matches,
+    fix_plan_overrides
+  }) {
+    const resolved_repo_path = repo_path || this.#repo_path;
+    const top_repo_frame = log_artifact.frames.find((f) => f.is_repo_frame) || null;
+
+    const base_plan = build_minimal_fix_plan({
+      hypothesis,
+      top_repo_frame,
+      search_matches
+    });
+
+    const fix_plan = merge_fix_plans(base_plan, fix_plan_overrides);
+
+    const patch_text = await generate_patch_from_edits(resolved_repo_path, fix_plan.edits);
+    return { fix_plan, patch_text };
+  }
+}
+
+function build_minimal_fix_plan({ hypothesis, top_repo_frame, search_matches }) {
+  const location_hint = top_repo_frame
+    ? `${top_repo_frame.file_path}:${top_repo_frame.line_number}`
+    : "unknown location";
+
+  const top_matches = (search_matches || []).slice(0, 3);
+  const summary_lines = [
+    `Start from ${location_hint} and verify the failing assumptions.`,
+    "If this is a null/undefined access, add validation or adjust the upstream contract.",
+    "If this is a missing import/export, ensure the symbol is defined and exported correctly."
+  ];
+  if (top_matches.length) {
+    summary_lines.push("");
+    summary_lines.push("Relevant search hits:");
+    for (const match of top_matches) {
+      summary_lines.push(`- ${match.file_path}:${match.line_number} (${match.query})`);
+    }
+  }
+
+  return {
+    summary: summary_lines.join("\n"),
+    edits: []
+  };
+}
+
+function merge_fix_plans(base_plan, overrides) {
+  if (!overrides) return base_plan;
+  const merged_summary =
+    typeof overrides.summary === "string" && overrides.summary.trim().length > 0
+      ? overrides.summary
+      : base_plan.summary;
+
+  const merged_edits = Array.isArray(overrides.edits) && overrides.edits.length > 0
+    ? overrides.edits
+    : base_plan.edits;
+
+  return {
+    summary: merged_summary,
+    edits: merged_edits
+  };
+}
+
+async function safe_read_text(absolute_path) {
+  try {
+    return await fs.readFile(absolute_path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function generate_patch_from_edits(repo_path, edits) {
+  const normalized_edits = Array.isArray(edits) ? edits : [];
+  if (!normalized_edits.length) return "";
+
+  const patches = [];
+  for (const edit of normalized_edits) {
+    const rel_path = edit.file_path;
+    if (!rel_path || typeof edit.new_text !== "string") continue;
+
+    const absolute_path = path.join(repo_path, rel_path);
+    const before_text = await safe_read_text(absolute_path);
+    const after_text = edit.new_text;
+
+    if (before_text === after_text) continue;
+
+    patches.push(
+      createTwoFilesPatch(
+        `a/${rel_path}`,
+        `b/${rel_path}`,
+        before_text,
+        after_text,
+        "",
+        "",
+        { context: 3 }
+      )
+    );
+  }
+
+  return patches.join("\n").trimEnd();
+}
+