Startrust/trustcode

# trustcode [](https://github.com/Startrust/trustcode/actions/workflows/ci.yml) [](./LICENSE)  trustcode indexes a repository into a compact, evidence-backed knowledge graph of symbols, relationships, execution flows, and routes, then serves it to AI coding agents through a CLI and an MCP server. When an agent asks "how does login create a session?" or "what breaks if I change this function?", trustcode answers **with the source evidence and a confidence score** behind every claim — so the agent can act without re-reading files and without trusting guesses. It is local-first (no hosted service, no network calls by default) and ships as a single native Rust binary. ## Built with AI coding agents trustcode is developed primarily by **AI coding agents** — fitting, since it's a code-intelligence tool *for* agents, dogfooded by being built *with* them. **Contribution norm:** the vast majority of code changes are expected to be made by AI coding agents, with humans steering. Most source in this repository was authored by an agent and gated through CI before merging. Humans drive the project from a level up: - **Open issues** — report bugs, request features, propose direction. - **Review & discuss** — weigh in on pull requests and architecture. - **Direct an agent** — hand a task to a coding agent and review the result. ## The Trust Contract Every non-trivial relationship stored carries a `provenance`, a `confidence` (0–1), and an `evidence` record (the exact source span that justifies it). Weak guesses are recorded with low confidence and kept out of default answers. ## Install ### From npm (single static binary, no toolchain) Install globally so the `trustcode` command is on your PATH (recommended — the rest of this README uses the bare `trustcode` command): npm install -g @startrust/trustcode trustcode index Or run it without installing, via `npx` — but then **prefix every command** with `npx @startrust/trustcode` (e.g. `npx @startrust/trustcode status`): npx @startrust/trustcode index Either way, the launcher selects and runs the prebuilt binary for your platform (win32/linux/darwin × x64/arm64). ### From source cargo build --release # binary at target/release/trustcode Requires a Rust toolchain. SQLite is compiled in (bundled), so no external database is needed. ## Quick start These examples use the bare `trustcode` command (global install). If you're using `npx`, prefix each one with `npx @startrust/trustcode`. trustcode index # build .trustcode/trustcode.db for the current repo trustcode status # files / symbols / relationships / flows / clusters trustcode find createSession # locate symbols by name trustcode show SessionStore.create # signature + source slice trustcode trace loginHandler createSession # evidenced call path, one record per hop trustcode explain "how does login create a session" trustcode impact createSession # what depends on it, risk, affected flows/tests/clusters trustcode dataflow config # where a value flows to / from (--up for upstream) trustcode routes # API routes -> handlers -> consumers trustcode review # git-diff change impact: changed symbols + blast radius + risk trustcode rename createSession newName # dry-run rename plan with per-edit confidence (changes nothing) trustcode contract # producer response shape vs consumer access -> mismatches trustcode clusters # cohesive symbol groups (subsystems), derived by graph clustering trustcode doctor # index health: staleness, parse + resolution stats trustcode sync # incremental re-index (re-parses only changed files) trustcode init # install git hooks that auto-sync after commit/merge/checkout **Languages.** trustcode indexes **11 languages** — TypeScript, JavaScript, TSX, JSX, Rust, Go, Python, Java, C#, PHP, and Ruby. Six (Rust, Go, Java, C#, PHP, Ruby) resolve calls across files through their own import/package/namespace models; eight carry variable-level data-flow. ## Keeping the index fresh Three ways the graph stays current — mirroring how the index should never go stale: - **While serving**: `trustcode serve --mcp` runs a catch-up sync on start, then watches the source tree and incrementally re-syncs (debounced) on every change — no manual step. - **Git hooks**: `trustcode init` installs `post-commit` / `post-merge` (covers `git pull`) / `post-checkout` hooks that run `trustcode sync` in the background. - **Manual**: `trustcode sync` any time. `sync` is incremental — unchanged files are reloaded from stored per-file artifacts and only changed files are re-parsed, yet the result is always identical to a fresh `index`. ### Example: `trace` loginHandler [function] (src/auth.ts:3) ↓ calls [conf 0.90] line 4 createSession(validateCredentials(req)) createSession [function] (src/session.ts:1) ### Example: `explain` `explain` returns a single, self-contained Answer in eight sections — enough to act on without opening a file. For `trustcode explain "how does loginHandler create a session"`: ## summary loginHandler [function] src/auth.ts:2-4 (exported) Calls 2 symbol(s); called by 0 symbol(s). ## matched_flows loginHandler -> persist (3 steps, conf 0.90) ## primary_trace loginHandler [function] (src/auth.ts:2) ↓ calls [conf 0.90] createSession(validateCredentials(req)) createSession [function] (src/session.ts:1) ↓ calls [conf 0.90] persist(userId) persist [function] (src/session.ts:2) ## source_slices 2 | export function loginHandler(req) { 3 | return createSession(validateCredentials(req)); 4 | } ## evidence [import-resolved] conf 0.90 createSession(validateCredentials(req)) [same-file-call] conf 0.90 persist(userId) ## related_tests (none found) ## uncertain_steps (none) ## suggested_next_symbols createSession [function] validateCredentials [function] Every hop names the rule and confidence behind it — that's the Trust Contract in practice. ## MCP server trustcode speaks the Model Context Protocol over stdio, exposing fourteen tools: `trustcode_status`, `trustcode_files`, `trustcode_find`, `trustcode_show`, `trustcode_trace`, `trustcode_explain`, `trustcode_impact`, `trustcode_dataflow`, `trustcode_review`, `trustcode_rename`, `trustcode_contract`, `trustcode_routes`, `trustcode_clusters`, `trustcode_doctor`. trustcode serve --mcp ### Connecting a client **One-step project setup (Claude Code + Codex):** trustcode install # then run `trustcode index` once `install` writes project-local, committable config so the whole team gets trustcode after a clone: - **Claude Code** — `.mcp.json` (MCP server), and `.claude/settings.json` pre-approving the `mcp__trustcode__*` tools plus hooks that show index status on session start and re-sync after edits. - **Codex** — `.codex/config.toml` (MCP server). - **`AGENTS.md`** — a short guidance block (read by both tools) telling the agent to prefer the `trustcode_*` tools and to run `trustcode index` if the project isn't indexed yet. The commands use `npx @startrust/trustcode@latest`, so teammates don't need a global install and always launch the newest release; pass `--global-bin` to use a globally-installed `trustcode` instead. `trustcode uninstall` removes it all cleanly. (The local index under `.trustcode/` is git-ignored, so each clone runs `trustcode index` once.) **Manual / other clients** — register the server yourself: { "mcpServers": { "trustcode": { "command": "npx", "args": ["-y", "@startrust/trustcode@latest", "serve", "--mcp"] } } } Or `claude mcp add trustcode -- npx -y @startrust/trustcode@latest serve --mcp`. stdout carries only protocol traffic; logs go to stderr. While serving, the index incrementally syncs on file changes (see [Keeping the index fresh](#keeping-the-index-fresh)); an unindexed project is left untouched with a hint to run `trustcode index`. ### Staying up to date trustcode ships often. Config written by `trustcode install` pins `@latest`, so the MCP server and hooks always launch the newest release. If you run the binary directly, it checks the npm registry at most once a day — only in an interactive terminal — and prints a one-line hint when a newer version exists (`npm i -g @startrust/trustcode@latest` to update). Set `TRUSTCODE_NO_UPDATE_CHECK=1` to turn the check off; it never runs in pipes, hooks, or CI. ## What it understands today ### Languages Native tree-sitter parsing, driven by per-language `.scm` query files. | Language | Extensions | Export rule | Status | |---|---|---|---| | TypeScript / TSX | `.ts` `.tsx` `.mts` `.cts` | `export` | ✅ | | JavaScript / JSX | `.js` `.jsx` `.mjs` `.cjs` | `export` | ✅ | | Rust | `.rs` | `pub` | ✅ | | Go | `.go` | capitalization | ✅ | | Python | `.py` `.pyi` | non-underscore name | ✅ | Call resolution is same-file + import-resolved + unique-global; language-specific module/import resolution is partial. Exact, type-aware resolution via a language server is the planned precision layer. ### Graph - **Symbols:** functions, classes, interfaces, methods (`Class.method`), arrow consts, React components - **Relationships:** imports, calls (same-file / import-resolved / weak global), each with evidence + confidence - **Flows:** execution paths derived from the call graph - **Data-flow (symbol-level):** `flows_to` edges from nested calls (`outer(inner())` → inner flows to outer), surfaced by `show` as "flows into" / "fed by". Variable-level def-use is a planned deeper layer - **Frameworks:** Express routes, Next.js `route.ts` handlers, `fetch`/`axios` consumers (`route_to_handler` and `fetches_route` edges) - **Impact:** upstream blast radius with LOW/MEDIUM/HIGH/CRITICAL risk and affected flows/tests ## How it stores things A project-local `.trustcode/trustcode.db` (SQLite + FTS5), git-ignored. The schema keeps `nodes` (symbols) and `edges` (relationships); every edge carries provenance, confidence, and an evidence JSON record from the first migration. ## Architecture A Cargo workspace of focused crates. Data flows one way — `scan → extract → resolve → flow → db` — and both front-ends query through the shared `trustcode-db::query` layer, so the CLI and MCP server always return identical Answers. | crate | responsibility | |---|---| | `trustcode-core` | domain types, stable IDs, path normalization (no I/O deps) | | `trustcode-scan` | git-aware file discovery, ignore rules, content hashing, change detection | | `trustcode-extract` | tree-sitter symbol/import/call/route/data-flow extraction (`.scm` queries) | | `trustcode-resolve` | call / route / data-flow resolution into evidenced edges | | `trustcode-flow` | execution-flow detection | | `trustcode-db` | SQLite schema, migrations, and the shared query layer (Answers) | | `trustcode-mcp` | MCP stdio server (rmcp) | | `trustcode-cli` | the `trustcode` binary | ## Development cargo test # unit + integration + blind-answer recall eval cargo fmt --all --check cargo clippy --all-targets -- -D warnings bash benchmarks/run.sh # dogfood-index real repos and report numbers CI runs fmt + clippy (deny warnings) and the test suite across Linux/macOS/Windows; all must be green to merge. See [AGENTS.md](./AGENTS.md) for the full engineering playbook. ## Status Working today: index → symbols → evidenced call graph → flows → trace / explain / impact / routes over both CLI and MCP. **7 languages** (TypeScript, JavaScript, TSX, JSX, Rust, Go, Python), symbol-level data-flow, incremental sync, a file watcher and git hooks, npm packaging, and cross-platform CI. Planned next: a TypeScript language-server precision layer (exact, type-aware resolution at confidence 1.0) and variable-level data-flow. ## License [MIT](./LICENSE)

标签：通知系统