Chisel CLAUDE.md

Chisel — CLAUDE.md

Test impact analysis and code intelligence for LLM agents. Zero external dependencies.

Audience (how to read this project)

• Primary user: autonomous and semi-autonomous coding agents (MCP, CLI invoked by agents), not a stand-alone dashboard for engineering managers.
• Typical human: solo developer orchestrating multiple agent sessions, parallel tasks, or long-running analyses — not “hand off to another engineer” workflows. Tools like ownership / who_reviews expose git-derived context (blame, commit activity) for debugging and risk heuristics; they are not org-chart features.
• Multi-agent safety (see project.py, ProcessLock, RWLock) exists so several processes (agents, terminals, CI) can share one .chisel/ database without corrupting reads/writes — treat this as a first-class product requirement, not an edge case.

When editing behavior or docs, prefer: structured tool results, explicit statuses (no_data, no_changes, git_error), import-graph + test edges over relying on git co-change alone, and clear hints when MCP would otherwise time out or mis-resolve project_dir.

Architecture

chisel/
  engine.py         — Orchestrator. Owns Storage, GitAnalyzer, TestMapper, ImpactAnalyzer, RWLock, ProcessLock. Shard routing (_with_shard, _shard_for_path) and auto-update (_try_auto_update).
  project.py        — Multi-agent safety: project root detection, path normalization, storage resolution (incl. per-shard dirs), cross-process file lock.
  bootstrap.py      — CHISEL_BOOTSTRAP user-module loader (custom extractor registration at engine startup).
  storage.py        — SQLite persistence (WAL mode, 30s busy timeout, write retry). 17 tables (incl. meta, import_edges, branch_co_changes, file_locks, bg_jobs, job_events, static_test_imports).
  ast_utils.py      — Multi-lang AST extraction (12 languages). CodeUnit dataclass. _extract_brace_lang() shared by brace-delimited langs.
  git_analyzer.py   — Parses git log/blame via subprocess. Branch/diff queries.
  metrics.py        — Pure computation: churn scoring, ownership aggregation, co-change detection, coupling_threshold(). _parse_iso_date shared utility.
  import_graph.py   — Static import_edges between source files (structural coupling).
  test_mapper.py    — Test file discovery, framework detection, dependency extraction, edge building.
  impact.py         — Impact analysis, risk scoring, stale test detection, reviewer suggestions.
  static_test_imports.py — StaticImportIndex: maps code paths → covering tests via DB static imports + disk overlay. Powers working-tree fallbacks in suggest_tests/diff_impact.
  risk_meta.py      — Risk-map _meta diagnostics and dynamic reweighting when components are uniform.
  cli.py            — argparse CLI (28 subcommands). _run_tool() shared handler. Entry point: chisel.cli:main
  schemas.py        — JSON Schema definitions + dispatch table for all 26 tools (parity enforced by test). Shared by HTTP and stdio servers.
  mcp_server.py     — HTTP MCP server (GET /tools, /health, POST /call). ThreadedHTTPServer. dispatch_tool() shared by both servers.
  mcp_stdio.py      — stdio MCP server (requires optional 'mcp' package). _configure_server() for engine lifecycle mgmt.
  next_steps.py     — Contextual next-step suggestions for MCP tool responses. compute_next_steps() dispatched per tool.
  llm_contract.py   — Agent vocabulary: trust note, status/source constants; MCP tool descriptions reference this (see docs/LLM_CONTRACT.md).
  rwlock.py         — Read-write lock for in-process concurrent access.