sergii-ziborov/weavatrix

# Weavatrix **Local repository intelligence for AI coding agents — understand the application quickly, then change it with evidence.** Weavatrix builds a reusable living graph of any local repository: files, symbols, imports, calls, inheritance, health findings, clone families and Git-history coupling. It gives Claude Code, Codex, or any MCP client a bounded map for fast application understanding and lower repeated context, then reuses the same graph for change impact, Health, dead-code review, duplicates, history and intended- architecture safeguards. Text search is included as a supporting source check, not the product core. **38 tools available; 34 enabled by the default offline profile. Local-first: with the defaults, no repository data leaves your machine.** - Website: [weavatrix.com](https://weavatrix.com) - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix) - npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix ` ## One graph, many views The 38 MCP methods are not one linear workflow. They project the same reusable graph into the smallest view needed for a task: repository and build state; modules, communities, hubs, neighbors and paths; exact symbols and bounded source context; endpoint and cross-repository API flow; symbol and change-set blast radius; graph revision and behavioral Git history; Health, dependencies, vulnerabilities, dead code, clones, coverage and hot paths; proof-carrying change verification; intended-architecture contracts and ratchets; local multi-repository work; and explicit, preview-confirmed Hosted exchange. ## Why An AI agent editing code without architecture, health and history evidence is refactoring blind. Weavatrix answers questions a text index cannot: - *"What breaks if I change this?"* → `change_impact` diffs your branch (staged, unstaged and untracked included), maps the changed files and symbols onto the graph, and lists everything that depends on them — with test coverage attached, so the **untested part of the blast radius** stands out before you ship. - *"Who calls this function?"* → `inspect_symbol` returns exact bounded TS/JS occurrences plus source context; `context_bundle` adds production-first graph relations, exact re-export sites, diverse call-site excerpts, and a smaller source workset. `get_dependents` walks the symbol-level reverse graph transitively. Opt into `include_container_importers:true` only when a broader module-import radius is intended. - *"Did my refactor actually decouple anything?"* → `graph_diff base_ref=HEAD~1` builds an immutable baseline graph without checking it out, then reports the structural delta: new module dependencies, broken or introduced import cycles, and symbols that lost their last caller. - *"Where is the repo rotting or repeating itself?"* → `run_audit`, `find_dead_code`, `find_duplicates`, `hot_path_review` and `git_history` combine deterministic findings, graph connectivity and co-change evidence instead of treating a matching string as an architecture fact. - *"Is this change actually safe?"* -> `verified_change` accepts the task plus current diff/files and returns one proof-carrying `PASS`, `BLOCKED`, or `UNKNOWN`: compact edit contexts, exact-symbol impact, bounded call-argument flow, Git graph drift, architecture/duplicate/API ratchets, and affected-test evidence. ## Worked examples These are representative sequences from local dogfooding, not fabricated chat transcripts. Counts describe the observed repository snapshots and will move with the code. ### Understand an unfamiliar backend without reading it linearly Question: Where does an attack-mitigation request go? module_map -> production territories and strongest module dependencies list_endpoints -> 462 routes observed in a 1,076-file backend snapshot trace_endpoint -> composed router mount -> controller -> service -> task/messaging -> bounded call-site excerpts around decisive edges Use `module_map` for the initial application shape, then switch to the exact endpoint or symbol. Do not lead with a broad natural-language `query_graph` when the route or identifier is already known. ### Check whether a backend handler is used by another repository Question: Can this handler be removed? list_known_repos -> trace_api_contract backend endpoints observed: 163 client callsites joined: 267 across two registered clients handler liveness: NOT_DEAD_EXTERNAL_USE unresolved dynamic URLs: POSSIBLE_EXTERNAL_USE / UNKNOWN This joins separately cached local graphs; it does not upload source. Medium/high-confidence external use can keep a handler out of the dead-code queue, while dynamic or ambiguous calls remain explicitly incomplete evidence. ### Change one method with an evidence trail inspect_symbol -> context_bundle -> get_dependents -> coverage_map -> edit the bounded workset -> verified_change phase=verify base_ref= On an observed BranchPilot diff, `change_impact` separated removed methods/signatures from additive exports and ranked a 98-node radius without collapsing runtime and type-only coupling. If measured coverage, the architecture contract, or requested tests are missing, the final state is `UNKNOWN`, not a cosmetic pass. ### Review Health and clone debt without auto-deleting code run_audit category=dependencies debt=all -> missing direct dependency (observed: mongodb) -> lockfile drift and unresolved imports run_audit debt=all -> runtime cycles separated from compile/type-only coupling find_duplicates -> clone families and same-name divergence -> homogeneous router boilerplate suppressed by default Every dead-code, orphan, dependency and duplicate item remains review evidence. Confirm framework conventions and source use before editing; Weavatrix does not auto-delete or merge findings. `run_audit` also returns an explicit capability matrix. `STRUCTURE CHECKED` and a supported package ecosystem do not imply `RUNTIME_CORRECTNESS` or `CONCURRENCY` is complete. Maven/Gradle manifests are reported `NOT_SUPPORTED`/`PARTIAL` for import-to-artifact verification rather than as a false clean `0 declared / 0 external`; bounded Go/Java correctness checks disclose that they are neither compiler proof nor a race detector. ### Trace an event, queue, worker, cron or CLI flow query_graph seed_symbols=["handleAttackEvents"] relation_filter=["calls", "references"] flow_direction="both" -> exact listener plus bounded producers and consumers context_bundle label="handleAttackEvents" -> production callers first and diverse excerpts around decisive call sites Exact symbol seeds avoid fuzzy routing noise and work for non-HTTP entry points without adding a special-purpose tool for every framework. A narrow `search_code` registration check is still useful when the handler name is not known; it is a discovery aid, not the graph. ### Establish an architecture contract without silently changing policy get_architecture_contract action=preview baseline_mode=none -> adaptive Maven/Gradle/monorepo territories -> observed dependency directions labelled OBSERVED_NOT_ENFORCED -> exact proposed file, verification, hash and short-lived token get_architecture_contract action=approve confirm_token= -> creates only a missing .weavatrix/architecture.json prepare_change -> edit -> verify_architecture Use `baseline_mode=accept-current` only when the owner explicitly accepts current deterministic debt. Approval rechecks the graph and never overwrites an existing local or Hosted policy. ## Benchmarks Two different gates ship in the repository: - `npm run benchmark` is a reproducible golden suite for TypeScript, JavaScript, Python, Go, Java and Rust, plus cross-repository HTTP matching, framework conventions and the MCP graph lifecycle. - `npm run benchmark:real` compares revision-pinned local application snapshots with the checked-in 0.2.1 relation baseline. It fails on unexplained signal loss; `MISSING`, `STALE` and `UNBASELINED` remain incomplete, not green. Representative local regression run (Windows x64, Node 24.15.0, July 18, 2026): | Gate | Result | Selected evidence | |---|---:|---| | Six language fixtures | 6/6 PASS | exact symbols/edges and complete edge provenance | | Cross-repo fixture | PASS, 431.79 ms cold | endpoint match, typed wrapper, external use, affected screen | | Lifecycle | PASS | `full -> incremental -> none -> reconnect/none`; 1,376-byte text response | | Total fixture cold build | 1.31 s | all six language graphs; 6.4 KB bounded report | | Real-repository baseline | 6/6 PASS | TS, JS, Python, Go, Java and Rust snapshots | Real snapshots ranged from 473 nodes / 1,165 edges in 0.22 s (Go) to 8,192 nodes / 21,814 edges in 9.44 s (TypeScript). The Java snapshot built 7,143 nodes / 23,708 edges in 2.61 s, including receiver-aware cross-file calls. These are regression measurements on one machine, not competitor benchmarks or universal latency claims. See [benchmark/cases.mjs](benchmark/cases.mjs), [benchmark/real-repositories.json](benchmark/real-repositories.json), and run the commands above to reproduce them on your own repositories. ## Quick start Requires Node ≥ 18. One command: # Claude Code — offline default; local repository switching is available explicitly: claude mcp add -s user weavatrix -- npx -y weavatrix Codex CLI: codex mcp add weavatrix -- npx -y weavatrix # or in ~/.codex/config.toml [mcp_servers.weavatrix] command = "npx" args = ["-y", "weavatrix", "C:/path/to/repo"] startup_timeout_sec = 20 tool_timeout_sec = 60 The package has one binary and several explicit security profiles. The omitted profile is `offline`: all local analysis plus `open_repo`, with every HTTP tool absent. Pass one profile as the final argument when a stricter repository boundary or a network feature is wanted: | Profile | Local repository switching | Cross-repo graph reads | OSV requests | Hosted sync / contract pull | |---|---:|---:|---:|---:| | `offline` (default) | Yes, only through `open_repo` | Yes, only through `trace_api_contract` | No | No | | `pinned` | No | No | No | No | | `osv` | Yes | Yes, only when called | Only when `refresh_advisories` is called | No | | `hosted` / `full` | Yes | Yes, only when called | Only when called | `preview_sync` is local; only `sync_graph` or `pull_architecture_contract` can make a request | # Hard-pin one repository and expose no network tools: claude mcp add -s user weavatrix -- npx -y weavatrix pinned # Add only explicit OSV refresh: claude mcp add -s user weavatrix -- npx -y weavatrix osv # Enable the owner-authenticated hosted workflow: claude mcp add -s user weavatrix -- npx -y weavatrix hosted Advanced registrations may still pass an exact comma-separated capability set: `graph,search,source,health,build,retarget,crossrepo,advisories,hosted`. The former `online` capability remains a compatibility alias for `advisories,hosted`; new registrations should use the named profiles or the narrower capability names. After an upgrade, reconnect the MCP server or start a new agent task before checking its tool list: many clients snapshot `tools/list` and input schemas for the lifetime of one connection. The expected counts are 31 for `pinned`, 34 for `offline`, 35 for `osv`, and all 38 for `hosted` / `full`. A custom capability list must include `crossrepo` to expose `trace_api_contract`; `online` alone adds only the legacy advisory/Hosted groups. `graph_stats` reports the running package version, enabled capabilities and registered-tool count so a cached process can be distinguished from the installed package. Or clone it: git clone https://github.com/sergii-ziborov/weavatrix cd weavatrix && npm install claude mcp add -s user weavatrix -- node /weavatrix/bin/weavatrix-mcp.mjs - `` — the repository to start with; the graph location is derived automatically in the per-user registry (`~/.weavatrix/graphs//graph.json`; its stable UUID is stored beside it in `.repository-id`). Pass an explicit ` ` pair instead if you keep graphs elsewhere. No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph locally. With the default `offline` profile (or an explicit capability set containing `retarget`), `open_repo` can change the active repository and builds a missing graph automatically. A normal `open_repo` also upgrades graphs that predate current typed-edge/provenance/physical-LOC metadata; `build:false` probes without building and refuses a legacy graph. Retargeting is offline but intentionally changes the filesystem boundary for subsequent tools; select `pinned` when that boundary must not move. An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install as `~/.claude/skills/weavatrix/SKILL.md`. ## Tools **graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`, `get_community`, `list_communities`, `module_map`, `get_dependents`, `change_impact`, `verified_change`, `git_history`, `graph_diff`, `get_architecture_contract`, `prepare_change`. Runtime dependencies, TypeScript type-only coupling and language compile-only edges (Rust module/use, Java imports) are reported separately where that distinction changes the result. TypeScript type-space and value-space declarations keep distinct identities; classes and enums that inhabit both spaces are labelled `both`. Every current edge carries versioned provenance. The parser emits `EXTRACTED`, `RESOLVED`, and `INFERRED`; the built-in bounded TypeScript/JavaScript precision overlay upgrades only references confirmed by its bundled `typescript-language-server` + TypeScript runtime to `EXACT_LSP`. `CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly disabled and only static evidence is active. Java and Rust language-server providers are not bundled: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete TypeScript/JavaScript overlay. The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off` before starting the MCP server for parser-only operation from the first build, or pass `precision:"off"` to `rebuild_graph` / `open_repo`. The MCPB installer exposes the same `lsp` / `off` choice as **TypeScript/JavaScript semantic precision**. **search / source** — `search_code` (ripgrep-backed, pure-Node fallback, with repository-relative path globs on Windows/macOS/Linux), `read_source` (a symbol's actual code in one hop), `context_bundle` (definition plus grouped inbound/outbound containers ranked production-first, exact re-export sites, call-site/target provenance and diverse bounded excerpts around decisive edges), `inspect_symbol` (one exact bounded TS/JS reference query, logical containers, impact and source excerpts), `list_endpoints` (HTTP route inventory: Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web, including nested Express `router.use(...)` mount composition, declaration/reachability counts, mount provenance, and Spring conditional/default-active state), `trace_endpoint` (one exact composed route → handler → bounded production call graph with call-site excerpts) **health** — `find_dead_code` (bounded review queue for statically unreferenced and test-only files, functions, methods, and symbols, with evidence tiers, completed/remaining verification and explicit public/framework/dynamic caveats), `run_audit` (an explicit capability matrix plus unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification; `category:dependencies` isolates missing/unused/duplicate declarations, unresolved imports and lockfile drift, missing npm/Go/Python deps, honest Maven/Gradle `NOT_SUPPORTED`/`PARTIAL` import verification, bounded Go/Java correctness candidates, runtime cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat + lockfile drift; accepts an immutable `base_ref`, `changed_files`, and `debt: new|existing|all` for review-scoped results; production paths are the default and `include_classified:true` opts into test/generated/docs evidence), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even after renames and can inspect strict small clones down to 12 tokens; homogeneous router boilerplate is suppressed unless `include_boilerplate:true`), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots ranked by connectivity — tests are never executed), `hot_path_review` (bounded local-cost evidence with separate graph/test risk), `verify_architecture`, `explain_architecture_violation`, `propose_architecture_exception` `hot_path_review` ranks production symbols using parser-derived local time, memory, cyclomatic and call-site facts plus exact inside-loop allocation, copy, scan, sort and recursion evidence. Graph fan-in/fan-out and measured coverage (or explicitly labelled static test reachability) remain separate from local syntax cost. Its focused default uses `min_score:85` plus a narrow strong-local fallback; pass `min_score:0` only when the full diagnostic queue is wanted. The ranking is not profiler data or interprocedural Big-O. **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as `graph.prev.json`) For dead functions/methods/symbols, call `find_dead_code` first. Its default production-only queue shows high/medium-confidence candidates and excludes tests, generated code, mocks, stories and docs; use `kinds:["method"]` or a `path` prefix to narrow it. `min_confidence:"low"` explicitly includes public APIs and framework/dynamic/reflection-sensitive candidates with their warnings. For repository maintenance or branch debt, pair it with `run_audit category=unused debt=all` (or add an immutable `base_ref` with `debt=new`) to cover unused files, exports and dependencies. Neither tool authorizes deletion: `STRONG_STATIC_EVIDENCE` means an exact zero-reference result, not permission to remove; follow each candidate's `remainingChecks`, then inspect source/dependents/configuration and run tests. `graph_diff` accepts `base_ref` (`HEAD~1`, `main`, `origin/main`, or another local Git ref) for a fresh baseline comparison. Without it, the tool compares against `graph.prev.json` saved by the last full rebuild. Either mode can be narrowed with `path`. Graph and health calls reconcile the working graph before answering. Safe JS/TS body-only changes reparse only the changed files plus bounded reverse importers; add/delete, export-surface, barrel, manifest, alias, ignore/config, non-JS/TS, or unsafe merge cases deliberately fall back to a full rebuild. The result says whether freshness was `none`, `incremental`, or `full`. Graph artifacts stay in the per-user cache and never need to be committed to Git. `verified_change` is read-only by default. It may run only explicitly requested `package.json` scripts whose names are allowlisted as test/check/verify scripts, and only when both `run_tests:true` and `WEAVATRIX_ALLOW_TEST_RUNS=1` are present. It never accepts an arbitrary shell command. Cross-repository API proof is used only when the active profile includes `crossrepo`; without a configured architecture contract or complete evidence, the result is `UNKNOWN`, not a cosmetic pass. Its data-flow section maps bounded JS/TS call arguments to callee parameters; it is not CFG, value-propagation, or taint analysis. **retarget** *(included in `offline`; absent from `pinned`; every switch is an explicit local call)* — `open_repo`, `list_known_repos`; changes the active repository boundary **crossrepo** *(included in `offline`; absent from `pinned`; reads only registered local graphs)* — `trace_api_contract`; reconciles the selected backend/client graphs and joins routes to client callsites `query_graph` accepts optional `seed_files` and exact `seed_symbols` when an architectural or event-driven question must start from known entry points. `relation_filter` limits edge kinds and `flow_direction:forward|backward|both` turns the same graph into a bounded producer/consumer view. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when question-derived seeds are also wanted. A code-shaped identifier such as `startMitigate` is treated as a stronger bounded seed than surrounding words such as controller/service/flow; all exact same-name declarations are retained instead of adding unrelated concept seeds. Broad bootstrap/tool-execution/routing questions rank conventional executables and graph-declared production entry points ahead of site, documentation, benchmark and fixture matches. Production-first classification also applies during traversal, so unrelated tests/generated/docs/benchmarks do not leak back from a production seed; name a class in the question or set `include_classified:true` to include it. Unreferenced unmatched constant/field leaves are hidden unless `include_low_signal:true`. Broad ranking remains orientation evidence; use `seed_files`, `seed_symbols`, an exact endpoint, or `inspect_symbol` when the intended entry point is already known. Instruction words such as “REST”, “path”, and “inspect” do not become fuzzy code seeds. **advisories** *(network, explicit opt-in)* — `refresh_advisories` **hosted** *(explicit opt-in; preview is local, send/pull are networked)* — `preview_sync`, `pull_architecture_contract`, `sync_graph`. `preview_sync` performs no request and returns the destination, repository UUID, exact payload fields/sections/size/hash and a short-lived confirmation token for the cached payload. `sync_graph` sends only with both that token and `dry_run:false`; its legacy dry-run form remains a no-network compatibility alias. Quality of life: graph/health reads auto-reconcile and expose `none` / `incremental` / `full` freshness, with a short clean-read debounce to avoid rescanning the repository for every tool call; ambiguous name lookups are disclosed instead of silently guessed; and the server **hot-reloads its watched MCP tool entry modules and catalog** when those files change — other MCP helpers and analysis engines require a reconnect. Every MCP response also carries local, transient `_meta["weavatrix/metrics"]` with elapsed time, output bytes/token estimate, graph freshness/revision/update and graph-cache status. These metrics are not persisted or transmitted by Weavatrix. If a source checkout's package version moves while an old daemon remains alive, `initialize`, `tools/list`, and tool calls fail loudly with `STALE_RUNTIME` until the client reconnects; the opt-out is reserved for deliberate development. ### 0.2.14 typed flows, honest Health, and architecture bootstrap - Go call resolution now follows receiver types through parameters, locals, constructor returns, imported types and struct fields. It links calls such as `bgpSpeaker.RemoveMitigator(update)` to `(*Speaker).RemoveMitigator` without guessing across ambiguous same-name receivers. - `query_graph` adds exact `seed_symbols`, `relation_filter`, and directed traversal for generic event/queue/worker/cron/CLI flows. `context_bundle` ranks production callers before tests and uses diverse edge-centered excerpts. `FlowSpec` no longer accidentally requests test traversal. - Health exposes per-capability completeness. Maven/Gradle support is honest instead of returning a clean zero, and bounded Go/Java correctness findings never claim compiler, runtime, race, or concurrency proof. Spring endpoints expose conditional/default-inactive controllers. - Architecture bootstrap adapts to Maven/Gradle/monorepo source roots and uses a reviewable preview/approve handshake. A stale daemon now refuses analysis when its runtime version differs from the package on disk. - The MCP implementation and static site are split into owner-focused modules/assets. A release test enforces a physical 300-line maximum for JavaScript/TypeScript under `src`, `bin`, `scripts`, and `test`, plus maintained HTML/CSS/JavaScript under `site`. Full patch notes: [docs/releases/v0.2.14.md](docs/releases/v0.2.14.md). ### 0.2.9 correctness, signal, and consent patch - Express endpoint inventory composes nested imported `router.use(...)` mounts, so a local route such as `/:attackId/startMitigate` is reported with its reachable `/warRoom/attack` prefix, declared vs reachable counts and the exact static mount chain. `trace_endpoint` continues from that route into the bounded call graph and call-site excerpts. - `context_bundle` keeps the call-site file/line separate from the target definition and adds bounded excerpts around decisive edges instead of stopping inside a long leading comment. - `search_code` applies documented repository-relative path globs correctly when ripgrep runs on Windows. Broad `query_graph` prompts no longer turn generic REST/instruction words into noisy configuration-file seeds, and code-shaped identifiers outrank generic controller/service/flow concepts. - `run_audit` is production-first by default while retaining explicit access to classified evidence; `category:dependencies` provides a focused dependency-health slice; duplicate review suppresses homogeneous Express router boilerplate unless requested. - the separate no-network `preview_sync` produces the exact payload approval artifact; `sync_graph` requires that preview followed by an exact short-lived confirmation token, validates the configured destination, requires HTTPS outside loopback, and never networks during preview. Contract-pull HTTP failures expose actionable auth/not-found/not-ready states. - Every MCP call exposes transient local execution/output/freshness metrics without collection or egress. The public site, privacy/security pages, package metadata and license presentation now describe the same 38-tool/34-offline surface and the same network boundary. Full patch notes: [docs/releases/v0.2.9.md](docs/releases/v0.2.9.md). ### 0.2.8 trust and precision patch - Dead-code review no longer labels a declaration `test-only` when it has a same-file production use. Revision-bound positive evidence from an exact `inspect_symbol` point query also removes that declaration from later dead-code candidates instead of remaining isolated in its cache. - Python dependency checks discover nested `requirements*.txt`, `requirements/*.txt`, `pyproject.toml`, and `Pipfile` manifests and assign imports to their nearest manifest scope. A root `test.py` is classified consistently as test code. - Endpoint extraction masks commented-out routes without shifting source offsets and rejects primitive path-to-name maps such as `{'/.codex': 'claude'}` while retaining real route tables. - Rust symbols now expose concrete kinds, owner types, visibility/export state, selection ranges and structural owner/member edges. This is parser evidence; Rust semantic/LSP precision remains explicitly unavailable. - Natural-language retrieval honors explicit Rust, Python, TypeScript, JavaScript, Go, Java, and C# intent in mixed repositories. Compact `verified_change` text now includes decisive exact reference counts and bounded inbound caller names for every selected edit symbol. Full patch notes: [docs/releases/v0.2.8.md](docs/releases/v0.2.8.md). ### 0.2.7 verified-change workflow - New `verified_change` composes task retrieval, exact symbol context, change impact, immutable Git graph comparison, architecture/duplicate/API ratchets, and targeted-test evidence behind one `PASS` / `BLOCKED` / `UNKNOWN` contract. - Intent-expanded graph retrieval is combined with exact changed-symbol seeds. A bounded JS/TS interprocedural layer records call arguments and their callee parameters without claiming CFG or taint completeness. - Test execution is a double opt-in and limited to existing test/check/verify package scripts; default operation remains read-only. - Malware scanning now sweeps installed npm package roots instead of package-manager caches or hosted release snapshots. Static heuristic findings are capped at `high`, expose unverified execution/origin/lockfile/exposure state, and no longer prescribe secret rotation unless execution or credential exposure has actually been confirmed. - `query_graph` and `verified_change` task retrieval now enforce production-first classification through traversal/selection while retaining exact changed or pinned non-product symbols; query output also suppresses unmatched constant/field leaves. `hot_path_review` defaults to a focused 85-point queue, while `min_score:0` remains the explicit full-diagnostic mode. - Dead-code candidates now carry evidence tiers and remaining checks; dependency findings carry per-finding manifest plus indexed-source/script/config verification without authorizing removal. - `npm run benchmark:agent` reports routing success, false positives, token estimate and latency. Codebase Memory and Serena results stay explicitly `MISSING` until independently collected data is supplied under the [blind agent-change protocol](docs/agent-task-benchmark.md); `benchmark:agent:release` fails closed without same-task change success, FP, token, and time results. Full patch notes: [docs/releases/v0.2.7.md](docs/releases/v0.2.7.md). ### 0.2.6 compact-context and TypeScript identity patch - New `context_bundle` turns a symbol into a bounded workset: definition, grouped inbound/outbound containers, reference evidence, exact re-export locations and a small number of source excerpts. - Re-export records retain their concrete file, line, alias, specifier, type-only flag and resolved origin. Barrel propagation through `export *` stays exact and private declarations are not exposed. - TypeScript interfaces and type aliases are first-class type-space nodes. Same-named runtime values keep separate identities, while classes and enums are explicitly marked as inhabiting both spaces. - Graph schema v5 and freshness gates rebuild older caches before these precision-sensitive results are used. The changes remain local-only and add no runtime dependency. Full patch notes: [docs/releases/v0.2.6.md](docs/releases/v0.2.6.md). ### 0.2.5 exact-symbol and graph-fidelity patch - New `inspect_symbol` spends a bounded LSP query on one requested TS/JS declaration, groups exact occurrences by logical container, and returns definition/caller source context. Its separate LRU cache is revision/config fingerprinted and never replaces the broad precision overlay. - Default-object service facades resolve to their underlying helpers, while `get_dependents` no longer silently expands every symbol query to all importers of its file. - Python receiver-aware method dispatch and unambiguous wildcard imports distinguish same-named methods across classes without promoting ambiguous dynamic evidence. - `run_audit` makes unused-dependency checking visible even when clean; dead-code review identifies production symbols referenced only by tests; small-clone scanning can be lowered to 12 tokens with stricter evidence rules. - `hot_path_review` adds a bounded offline performance-review queue with line-addressable local cost evidence, separate graph risk, and honest measured/unavailable coverage states. Full patch notes: [docs/releases/v0.2.5.md](docs/releases/v0.2.5.md). ### 0.2.4 graph-mode correctness and semantic precision patch - `graph_diff base_ref=...` builds the immutable baseline in the current graph mode, so a `no-tests` graph is never compared with a hidden `full` universe. Previous-rebuild snapshots with mismatched modes are rejected instead of reporting false removals or cycle drift. - `trace_api_contract` preserves each registered repository's build mode during refresh and exposes that mode in `graphReconciliation`. - `graph_stats` and `open_repo` expose the canonical graph path and build mode; an explicit mode mismatch with `build:false` fails closed instead of silently retargeting. - `module_map` is production-only by default and can opt back into classified tests, fixtures, benchmarks, generated output and docs with `include_non_product:true`. - A bundled, read-only TypeScript/JavaScript language server validates a bounded set of semantic references after graph reconciliation. Confirmed edges become `EXACT_LSP`; zero-reference evidence can strengthen an internal dead-code candidate only after a successful exact query. Partial, unavailable and revision-mismatched overlays stay visible and never become cosmetic exactness. The provider is Weavatrix's pinned `typescript-language-server` + TypeScript runtime, never a repository binary or `npx` download. Automatic type acquisition is disabled. Its child environment is reduced to OS/temp/locale basics with a Node/System path; registry, proxy, cloud, token and `NODE_OPTIONS` values are not inherited. TypeScript may still read locally declared project configuration, dependencies and type declarations; Weavatrix accepts returned evidence only after repository realpath containment. Applicable config chains are audited before provider startup; configured language-service plugins and unresolved/outside config are refused, while semantic inputs are fingerprinted before cache reuse and rechecked after each run. No source or evidence is transmitted, and the provider performs no Weavatrix HTTP request. MCP EOF/SIGTERM drains or tree-terminates TLS and tsserver before the stdio process exits. - Broad `query_graph` bootstrap and tool-execution ranking now prefers production executables and graph-declared entry points over site, docs, benchmark and fixture surfaces. Exact `seed_files` remain the deterministic option when the caller already knows the entry point. - The bundled skill routes orientation, diff review, cross-repository API tracing and exact-symbol work through Weavatrix's own evidence states. Java/Rust exact providers remain `UNAVAILABLE` in this release instead of being presented as compiler-confirmed. Full patch notes: [docs/releases/v0.2.4.md](docs/releases/v0.2.4.md). ### 0.2.3 real-wrapper patch - Auto-discovery recognizes wrappers that pass a fixed HTTP client method and argument array to a shared transport helper, such as `api(axios.get, [url, options])`. - Ambiguous handler names can resolve to the unique matching symbol in a module directly imported by the route file, allowing proven external frontend calls to suppress only that exact backend dead-code candidate. - Missing, ambiguous, low-confidence and capped evidence remains review-only; the patch does not turn absence of a client match into a dead-code verdict. Full patch notes: [docs/releases/v0.2.3.md](docs/releases/v0.2.3.md). ### 0.2.2 regression and cross-repository evidence - Permanent TS/JS/Python/Go/Java/Rust regression fixtures now gate graph correctness, output size, latency, freshness, reconnect behavior and repository-target stability. - Every current graph edge carries versioned `EXTRACTED`, `RESOLVED`, or `INFERRED` provenance; `EXACT_LSP` and `CONFLICT` are reserved for the optional precision overlay. - `trace_api_contract` recognizes configured and conservatively auto-discovered HTTP wrappers, resolves bounded dynamic URL prefixes and can mark an unambiguous backend handler `NOT_DEAD_EXTERNAL_USE` when another registered repository supplies medium/high-confidence use. - Real-repository verification records explicit `MISSING`, `UNBASELINED`, and `STALE` gaps instead of converting absent Java/Rust or source-checkout evidence into a green result. - No mandatory runtime dependency was added. Full release notes: [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md). ### 0.2.1 bounded-output patch - `git_history top_n=N` is a hard per-collection MCP cap, including churn, hotspots and every coupling list. JSON output reports `total`, `returned` and `truncated` for each collection. - `god_nodes` ranks production code by default, excluding classified tests and generated/build artifacts; pass `include_classified:true` only when those surfaces are intentionally in scope. - `output_format:"text"` returns concise TextContent only. Use `output_format:"json"` when a workflow needs the full stable `weavatrix.tool.v1` structured envelope. - `trace_api_contract` resolves bounded constant prefixes in template URLs and accepts segment-aligned path fragments such as `/query` for `/edgeAnalytics/query/...`. - `change_impact` labels test/e2e edits as `test-only` and does not seed product blast radius from them. - Without a saved architecture contract, `prepare_change` returns concise provisional budgets and clearly labels them as non-enforceable; request `get_architecture_contract output_format:"json"` only when the inferred starter contract is actually needed. Full patch notes: [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md). ## Signal quality and repository configuration Weavatrix `0.2.0` reduces the most common sources of static-analysis noise while deepening Rust and Java graphs: - In Git repositories, graph and clone scans use tracked plus non-ignored untracked files, so `.gitignore`-excluded build outputs such as packaged applications do not dominate findings. - Add a repository-root `.weavatrixignore` for analysis-only exclusions that should remain tracked in Git. It supports `*`, `**`, `?`, root-anchored `/patterns`, directory suffixes and ordered `!` re-includes. The same file universe is used by graph building, audits and clone scanning. - `mode: "no-tests"` and `find_duplicates(include_tests:false)` classify `test-e2e`, Cypress, Playwright, acceptance and integration roots as tests, not only `*.test`/`*.spec` filenames. - `benchmarks/**` and any `**/__temp/**` root are classified as non-production review surfaces and suppressed from dead-code/clone/audit queues by default. If a benchmark is deliberate production source, opt its narrow path back in with `.weavatrix.json` `classify.product` patterns. - TypeScript `import type` and type-only re-exports remain visible as compile-time coupling but do not inflate runtime-cycle severity. `module_map`, `change_impact` and structural diffs preserve that distinction. `god_nodes` ranks unique neighbors with runtime connectivity first and reports repeated occurrences separately. - Rust `mod`, `use` and `pub use` paths now resolve between files and modules. They are marked compile-only, so they enrich `module_map` and compile-time coupling without inventing runtime initialization cycles or promoting compile-time coupling to runtime impact. Axum and actix-web routes are included in `list_endpoints`. - Java class/interface/enum/record/annotation declarations retain their symbol kind; methods and constructors are linked to their declaring type with visibility metadata. Internal `extends`/`implements` relationships and resolvable type references link to real declarations. Field, parameter, local and static receiver types resolve project-internal cross-file calls; overloads are selected by arity and ambiguous/external targets fail closed. Imports are compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java trees use package-aware communities instead of one giant `src` bucket. External or synthetic placeholder types are not created merely to inflate graph counts. - Dependency checks resolve the nearest workspace manifest and `tsconfig`/`jsconfig` aliases, account for framework-owned runtime peers such as Next.js + `react-dom`, and recognize Next.js App Router route exports as endpoints. - Generated NAPI-RS platform loaders and declared template/example catalogs no longer create phantom runtime dependency, orphan or unused-export findings. Conventional template roots are inferred conservatively; custom roots can be declared explicitly. - `coverage_map` reports coverage as **unavailable** when no supported report exists. That means “no data”, not zero coverage. - Duplicate output is a review queue, not a verdict: near-identical bodies are clone candidates; same-name/different-body pairs are divergence candidates. Read both sources and confirm the shared contract before consolidating code. - `run_audit base_ref=... debt=new` compares stable finding fingerprints against a graph rebuilt from that immutable commit. Existing debt and fixed findings are counted separately. Supplying only `changed_files` is honestly labeled changed scope—it is never presented as proof that a finding is new. - `find_dead_code` exposes the symbol-level liveness evidence already used by the audit as a bounded agent review queue. Public/exported methods, framework entries, decorators, dynamic loading and reflection lower confidence; the result always says `REVIEW_REQUIRED` and `autoDelete:false`. ### HTTP clients and wrappers `trace_api_contract` recognizes built-in object clients such as `axios.get(...)`, explicit bare or object/member wrappers, and simple auto-discovered functions that forward a URL parameter directly to a known HTTP client. Auto-discovered wrappers are restricted to their bounded reverse-import scope; ambiguous same-name definitions are skipped and reported as incomplete evidence. Persistent per-client-repository configuration lives in `.weavatrix.json`: { "httpContracts": { "clientNames": ["internalHttp"], "wrappers": [ { "call": "get", "method": "GET", "urlArgument": 0 }, { "object": "transport", "member": "send", "method": "POST", "urlArgument": 1 } ], "autoDiscoverWrappers": true } } The MCP call exposes the same ad-hoc controls as `client_names`, `client_wrappers` and `auto_discover_wrappers`. A medium/high-confidence client match marks the backend endpoint/handler `NOT_DEAD_EXTERNAL_USE`; a low-confidence match is `POSSIBLE_EXTERNAL_USE`; no match is `UNKNOWN`. Only an unambiguously resolved handler node can suppress a method-level dead-code candidate. The tool never turns missing static evidence into a `DEAD` verdict. `run_audit` makes incomplete security coverage explicit. OSV state is `OK` only after every supported pinned package/version for this repository was queried successfully. `PARTIAL` means some queries failed, the response was incomplete, the dependency fingerprint changed, or the cache uses a legacy stamp; `NOT_CHECKED` means there is no per-repository refresh; `ERROR` means the local check itself failed. None of the latter three states is a clean vulnerability result. The cache stores a fingerprint of the supported dependency set so a lockfile change cannot silently reuse a stale `OK`. For conventions that cannot be inferred safely, add an optional `.weavatrix-deps.json` at the repository root: { "entrypoints": ["scripts/publish-release.mjs"], "nonRuntimeRoots": ["library", "catalogs/examples"], "python": { "managedDependencies": ["numpy", "openvino-genai"], "ignoreDependencies": ["vendor-sdk"] } } `entrypoints` protects framework/script entry files from dead-code classification. `nonRuntimeRoots` (alias: `templateRoots`) marks reusable examples/templates that are not deployed as one application. It suppresses orphan/dead/unused-export noise and missing/unresolved dependency findings when every use is inside those roots. Import edges, cycles and boundary checks remain visible. `managedDependencies` declares Python modules supplied by an external runtime; `ignoreDependencies` suppresses intentionally unresolved Python packages. Keep the lists narrow: they change audit interpretation, not the repository or its dependency installation. ## Privacy: local-first, offline by design Graph queries, audits, clone scans and repository switching run locally. The default capability set is `graph,search,source,health,build,retarget,crossrepo`: no Weavatrix HTTP requests. `open_repo` changes the active local boundary only when called. Select `pinned` to remove repository switching, global repository listing, and cross-repository graph tracing too. Weavatrix itself initiates outbound HTTP only from three tools; all are absent from `offline` and `pinned`, and none runs merely because a profile is enabled: - `refresh_advisories` — queries [OSV.dev](https://osv.dev) with your lockfile's package **names + versions** (that is what an OSV query is; never source code) and caches the advisories in `~/.weavatrix/advisories.json`. `run_audit` then matches against that store fully offline. - `pull_architecture_contract` — sends the active repository's opaque stable UUID with bearer authentication, downloads the owner-approved target-architecture contract, validates it, and stores the contract in the local graph cache. It sends no source, symbol, or repository path. - `preview_sync` — builds a bounded evidence snapshot locally without sending anything. The preview shows the destination host/path, normalized repository name, opaque UUID, payload version, exact top-level fields, included sections, node/link/byte counts and canonical SHA-256 hash. A `sync_graph` call with `dry_run:false` and its exact short-lived `confirm_token` sends the cached payload to the same destination. A token alone does not send while the default dry-run remains active. It sends payload v3: the v2 graph allowlist plus module dependencies, runtime/compile-time cycles, declared boundary violations, health findings, complexity-threshold breaches, stack identifiers, a bounded direct/transitive dependency graph, direct package usage, and bounded clone/divergence review candidates. Local analyzers may read repository source and manifests to derive those facts. The wire contract has no fields for file bodies, snippets, absolute host paths, environment values or Git remotes; unknown fields are discarded and unsafe optional path metadata is omitted. The confirmed request also carries the normalized repository display name used by the hosted list. The endpoint is **yours**, configured through `WEAVATRIX_SYNC_URL` and the optional `WEAVATRIX_SYNC_TOKEN`; the feature is off by default. Pass `payload_version: 2` only for an intentional graph-only compatibility sync—there is no silent downgrade that discards evidence. Graphs that predate current typed-edge/provenance metadata must be rebuilt once before V3 sync; V3 also refuses a stale graph so source-derived evidence cannot be mixed with old topology. HTTPS is required except for an explicitly configured loopback endpoint; embedded URL credentials and fragments are rejected. Evidence sections carry independent `state` (`COMPLETE`, `PARTIAL`, `NOT_CHECKED`, `NOT_APPLICABLE`, `ERROR`) and `verdict` (`PASS`, `FAIL`, `UNKNOWN`) fields plus exact `total/returned/truncated` counts. An incomplete check is never converted into a clean zero. V3 is deterministic: volatile timestamps are excluded and the allowlisted snapshot has a canonical SHA-256 fingerprint, so identical evidence does not manufacture a hosted revision. The client mirrors the hosted 8 MiB / 25,000-node / 100,000-edge / 50,000-external-import safety limits before networking. If a network tool is not listed by the MCP client, that is the expected offline default. With the user's approval, select `osv` for advisory refresh only or `hosted` for the hosted workflow, restart/reconnect the MCP server, and then invoke the intended tool. Enabling a profile does not trigger a request by itself. Profiles (`offline`, `pinned`, `osv`, `hosted`, `full`) or exact capability groups (`graph`, `search`, `source`, `health`, `build`, `retarget`, `crossrepo`, `advisories`, `hosted`) are selectable through the final positional argument. Omitted caps use `offline`; an explicit capability list exposes exactly the named groups. Legacy `online` expands to `advisories,hosted` for compatibility. ## Security model Socket capability alerts describe expected powers of a local code-analysis tool; they are not vulnerability findings. This is where each capability comes from and how it is controlled: | Capability alert | Why it exists | Activation and boundary | |---|---|---| | Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; confirmed `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three. Sync defaults to a no-network dry-run and then requires both `dry_run:false` and its exact short-lived token; hosted calls require `WEAVATRIX_SYNC_URL`, and non-loopback hosted endpoints require HTTPS | | Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; the bundled TLS/tsserver process supplies bounded JS/TS semantic evidence; timed-out Windows child trees may be terminated; `verified_change` can optionally run an existing package test/check/verify script | The semantic provider never invokes repository code. Test execution separately requires `run_tests:true` plus `WEAVATRIX_ALLOW_TEST_RUNS=1`, rejects arbitrary commands and shell-sensitive arguments, and should be enabled only for trusted repository scripts | | Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` | | Environment access | Reads `WEAVATRIX_*` configuration; ordinary local helpers inherit a credential-stripped environment, while TLS/tsserver receives only allowlisted OS/temp/locale values and a constrained executable path | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment. TLS/tsserver also receives no registry/proxy/cloud credentials or `NODE_OPTIONS` | | Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory/architecture caches | Realpath containment blocks traversal and symlink/junction escapes. The `pinned` profile removes `open_repo`; the default `offline` profile permits only explicit local switching. The optional malware dependency scan may inspect installed dependency caches such as GOPATH | | URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the three network-profile tools perform requests | `read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or realpath escapes. Graph-derived paths pass through the same boundary before analysis tools read them. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md). ## Languages JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · HTML · CSS — parsed with [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) WASM grammars; no Python install, no native compilation. ## On-disk layout Graphs are derived data and never live inside your repo: the global per-user registry stores them at `~/.weavatrix/graphs//` (including `.repository-id`, `graph.json`, and `graph.prev.json`). ## Development npm install npm test # unit/integration tests plus the quick golden benchmark npm run benchmark # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate npm run benchmark:real # locally available real repos vs source-free 0.2.1 baselines The benchmark checks representative graph correctness, complete edge provenance, cross-repository HTTP tracing, output bytes, latency, freshness, reconnect and active-target stability. Its budgets, semantics and intentionally limited claims are documented in [docs/benchmarking.md](docs/benchmarking.md). Maintained JavaScript/TypeScript files under `src`, `bin`, `scripts`, and `test`, plus HTML/CSS/JavaScript under `site`, have a hard physical 300-line ceiling enforced by the release suite. Larger concerns are split into owner-focused modules behind slim stable facades (`foo.js` re-exports `foo.parse.js`, `foo.report.js`, …). The MCP layer lives in `src/mcp/` (graph context, tool entry modules, focused helpers, and the catalog/hot-reload loader) behind the thin stdio entry `src/mcp-server.mjs`. ## Roadmap - **Public 0.2.2 regression foundation** now has the permanent six-language golden corpus, cross-repository wrapper/liveness fixture, framework/convention fixture, full MCP lifecycle gate and a portable real-repository runner. Six source-free 0.2.1 real-repository baselines are recorded; edge provenance is gated end-to-end and the strict six-repository release command passes. - **Wrapper-aware API contracts** shipped in 0.2.2: persistent/ad-hoc configuration, conservative discovery, cross-repository handler liveness and explicit unknown states. The next hosted increment joins privacy-safe contract identities across separately synced services. - **Hosted architecture workbench** at [app.weavatrix.com](https://app.weavatrix.com) is an access-controlled preview for owner-authenticated source-free evidence and revision history. Its UI and backend evolve independently from the public MCP release; local use remains fully optional. - **Semantic precision bridge** shipped for TypeScript/JavaScript in 0.2.4: a bounded, revision-bound local overlay validates references with the bundled language server while the parser graph remains the fallback. Java and Rust providers are not bundled yet and stay explicitly `UNAVAILABLE`. - **Git-native architecture history** — bounded tag/ref timelines and branch reports built outside the worktree; graph artifacts stay out of Git. - **Cross-repository company evidence** — endpoints, events and internal packages joined to affected consumers and ownership without uploading source. - **CI blast radius** — bounded `change_impact` and architecture-ratchet evidence as a PR check/comment. The public alignment note for the fixed cross-product release sequence is in [docs/product-roadmap.md](docs/product-roadmap.md). ## License The Weavatrix source in this repository is [MIT licensed](LICENSE) © 2026 Sergii Ziborov. Third-party dependencies retain their own licenses. See the public [license page](https://weavatrix.com/license) for the same notice.

标签：AI编程辅助, JS文件枚举, MCP服务, MITM代理, 云安全监控, 代码图谱, 代码质量审计, 变更影响分析, 可视化界面, 弱口令爆破, 数据可视化, 日志审计, 本地优先, 自定义脚本, 逆向工具, 静态分析