weavatrix 1.9.2 → 1.11.0

package/README.md

@@ -1,5 +1,7 @@
 # Weavatrix — native MCP repository intelligence
 
+<img src="https://raw.githubusercontent.com/Weavatrix/weavatrix/main/plugins/weavatrix/assets/logo.svg" alt="Weavatrix logo" width="88" align="right">
+
 [![CI](https://github.com/Weavatrix/weavatrix/actions/workflows/ci.yml/badge.svg)](https://github.com/Weavatrix/weavatrix/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/weavatrix.svg)](https://www.npmjs.com/package/weavatrix)
 [![engine](https://img.shields.io/crates/v/weavatrix-rust.svg?label=engine)](https://crates.io/crates/weavatrix-rust)
@@ -8,7 +10,7 @@
 **Give your coding agent repository evidence before it starts guessing.**
 
 Weavatrix is the native MCP product for repository intelligence. It gives
-Codex, Claude Code, and other coding agents 43 read-only operations over one
+Codex, Claude Code, and other coding agents 47 read-only operations over one
 revision-bound evidence graph: impact, architecture, APIs, Git history,
 duplicates, dead code, search, semantic links, and temporal memory.
 
@@ -91,19 +93,93 @@ Which dependency violates .weavatrix/architecture.json?
 Find every GraphQL, gRPC, Kafka, RabbitMQ, NATS, JMS, SQS, or SNS
 contract affected by this branch.
 Build the smallest source bundle needed to edit this symbol safely.
+Show me this file as it was two commits ago, without a checkout.
+```
+
+## See it answer
+
+Real answers from Weavatrix analyzing its own repository at commit
+`ec8bf30`, abridged (`…`) and with the local root shortened. Reproduce any of
+them with `weavatrix tool <name> . '<arguments>'`.
+
+**Orient in one call** — and know exactly which repository and revision
+answered:
+
+```json
+{"name": "graph_stats", "arguments": {}}
 ```
 
-## The 43 read-only operations
+```json
+{
+  "nodes": 1294,
+  "edges": 2771,
+  "freshness": {"state": "CURRENT", "source_revision": "sha256:dd3d96d3…"},
+  "relations": {"calls": 651, "contains": 1271, "imports": 419, "references": 314, "…": "…"},
+  "repository_context": {
+    "root": "…/weavatrix",
+    "git_head": "ec8bf3041588623f23ec5e7ebbaff3a333da9ca7",
+    "scan_revision": "sha256:dd3d96d3…",
+    "graph_age_seconds": 0
+  }
+}
+```
+
+Every answer carries that `repository_context` block. Add
+`"expected_repository": "weavatrix"` to any call and a server that was
+retargeted elsewhere fails loudly instead of answering about the wrong
+repository.
+
+**Blast radius before you edit:**
+
+```json
+{"name": "get_dependents", "arguments": {"label": "file:src/mcp/server/mod.rs", "max_nodes": 6}}
+```
+
+```json
+{
+  "dependents": [
+    {"distance": 1, "node": {"id": "file:src/main.rs", "language": "rust"}},
+    {"distance": 1, "node": {"id": "file:src/mcp/mod.rs"}},
+    {"distance": 1, "node": {"id": "file:src/mcp/server/tests/catalog.rs"}},
+    {"…": "…"}
+  ]
+}
+```
+
+**The file as it was — no checkout** (`git_read_blob`):
+
+```json
+{"name": "git_read_blob", "arguments": {"path": "Cargo.toml", "revision": "HEAD~3", "max_bytes": 400}}
+```
+
+```json
+{
+  "path": "Cargo.toml",
+  "revision": "70b5bc788a10ec89ab28b9ecbc005e3b9c7f9829",
+  "oid": "f5f54bac00a4feb6e965c0d87c5c6d4d25782e91",
+  "kind": "utf8-text",
+  "lines": ["[package]", "name = \"weavatrix\"", "version = \"1.9.2\"", "…"],
+  "size_bytes": 1224,
+  "returned_bytes": 400,
+  "truncated": true
+}
+```
+
+Three commits before `ec8bf30` this package was 1.9.2; the agent reads that
+follow-up to a diff without touching the worktree. Binary blobs fail closed
+instead of being decoded into garbage.
+
+## The 47 read-only operations
 
 | Workflow | Operations |
 | --- | --- |
 | Graph orientation | `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`, `get_community`, `list_communities`, `module_map`, `build_graph` |
 | Change impact | `get_dependents`, `change_impact`, `select_tests`, `verified_change`, `prepare_change`, `graph_diff` |
-| Exact source context | `search_code`, `read_source`, `inspect_symbol`, `context_bundle`, `map_stacktrace` |
-| Health and quality | `find_duplicates`, `find_dead_code`, `run_audit`, `coverage_map`, `hot_path_review` |
+| Exact source context | `search_code`, `read_source`, `inspect_symbol`, `go_to_definition`, `find_references`, `context_bundle`, `map_stacktrace` |
+| Health and quality | `find_duplicates`, `find_dead_code`, `run_audit`, `coverage_map`, `hot_path_review`, `perf_attribution` |
 | APIs and transports | `list_endpoints`, `trace_endpoint`, `trace_api_contract` |
 | Architecture | `get_architecture_contract`, `verify_architecture`, `verify_capabilities`, `explain_architecture_violation`, `propose_architecture_exception` |
-| Git and repositories | `git_history`, `cross_repo_git`, `open_repo`, `list_known_repos`, `rebuild_graph` |
+| Git and repositories | `git_history`, `git_read_blob`, `cross_repo_git`, `open_repo`, `list_known_repos`, `rebuild_graph` |
 | Native extensions | `vector_search`, `semantic_link`, `seo_link_suggestions`, `memory_context` |
 
 Every operation is read-only with respect to the analyzed repository.
@@ -129,12 +205,12 @@ coding agent
     |
     | MCP over stdio
     v
-weavatrix 1.9.2
+weavatrix 1.11.0
     profile catalog · refresh · watcher · MCP framing
     |
     v
-weavatrix-rust 2.7.3
-    typed graph · analysis · 43 read-only operations
+weavatrix-rust 2.10.0
+    typed graph · analysis · 47 read-only operations
 ```
 
 This npm product owns MCP transport and native distribution. The
@@ -143,13 +219,27 @@ the reusable protocol-independent engine; it is not an MCP server.
 Its standalone diagnostic therefore reports `weavatrix-rust <engine-version>`,
 while this MCP product reports both its product and embedded-engine identities.
 
-Engine 2.2.1 makes three reports carry only what their evidence supports:
-`find_duplicates` reports the lines a clone covers completely and the byte
-range to check them by, `run_audit` runtime findings land on the line they
-matched, and `token_budget` is refused by the operations that cannot apply it
-rather than accepted and ignored. `find_duplicates` also gains
-`include_strings`, which compares the payloads of multi-line literals - inline
-SQL, embedded templates - that the code pass sees as a single token.
+### You do not need the server to use the engines
+
+The layers underneath are separately released npm packages with their own
+repositories, licenses, and TypeScript types. Each one is a native library you
+can `require` directly, with no MCP server, no agent, and no dependency on any
+other Weavatrix package:
+
+| Package | What it does on its own |
+| --- | --- |
+| [`weavatrix-scan`](https://www.npmjs.com/package/weavatrix-scan) | Deterministic repository manifests: normalized paths, sizes, hashes, one revision, typed skip evidence. |
+| [`weavatrix-parse`](https://www.npmjs.com/package/weavatrix-parse) | Lossless tokenization and structural facts for 25 languages, with exact spans. |
+| [`weavatrix-graph`](https://www.npmjs.com/package/weavatrix-graph) | A directed graph with provenance on every edge, plus BFS, SCC, topological sort, and PageRank. |
+| [`weavatrix-memory`](https://www.npmjs.com/package/weavatrix-memory) | Bitemporal, evidence-carrying agent memory with a hard token budget and an audit receipt. |
+| [`weavatrix-search`](https://www.npmjs.com/package/weavatrix-search) | Bounded ignore-aware content search, plus a persistent index updated from watcher events. |
+| [`weavatrix-search-vector`](https://www.npmjs.com/package/weavatrix-search-vector) | Persistent, mutable vector search with metadata filters and an exact oracle. |
+| [`weavatrix-clone`](https://www.npmjs.com/package/weavatrix-clone) | Type-1/2/3 clone detection with per-pair evidence and JSON, SARIF, and BigCloneEval output. |
+
+Their Node and Bun benchmarks against the JavaScript library each would
+otherwise replace live in one place, with the rules written down and the
+losing rows kept:
+[weavatrix-benchmarks](https://github.com/Weavatrix/weavatrix-benchmarks).
 
 ## Release evidence
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "weavatrix",
-  "version": "1.9.2",
-  "weavatrixEngineVersion": "2.7.3",
-  "description": "Native repository intelligence for coding agents: 43 read-only MCP operations backed by typed evidence graphs, impact, architecture, APIs, Git, search, semantics, and memory.",
+  "version": "1.11.0",
+  "weavatrixEngineVersion": "2.10.0",
+  "description": "Native repository intelligence for coding agents: 47 read-only MCP operations backed by typed evidence graphs, impact, architecture, APIs, Git, search, semantics, and memory.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
   "license": "MIT",
   "homepage": "https://weavatrix.com",

package/server.json

@@ -2,19 +2,19 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.Weavatrix/weavatrix",
   "title": "Weavatrix",
-  "description": "Native Weavatrix MCP: 43 read-only repository tools across 24 code and configuration surfaces.",
+  "description": "Native Weavatrix MCP: 47 read-only repository tools across 24 code and configuration surfaces.",
   "repository": {
     "url": "https://github.com/Weavatrix/weavatrix",
     "source": "github"
   },
-  "version": "1.9.2",
+  "version": "1.11.0",
   "websiteUrl": "https://weavatrix.com",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "weavatrix",
-      "version": "1.9.2",
+      "version": "1.11.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/skill/SKILL.md

@@ -19,8 +19,8 @@ contracts. Do not call it merely because the server is available.
 
 1. Call `graph_stats` to confirm the active repository and graph revision.
 2. Use `module_map` for orientation or `search_code` for a known literal.
-3. Pin decisive evidence with `inspect_symbol`, `context_bundle`, or
-   `read_source`.
+3. Pin decisive evidence with `inspect_symbol`, `go_to_definition`,
+   `find_references`, `context_bundle`, or `read_source`.
 4. Expand only when needed: `get_dependents` or `change_impact` for risk,
    `trace_endpoint` or `trace_api_contract` for runtime contracts,
    `verify_architecture` for policy, and `run_audit` for a broad health pass.

package/skill/references/tool-routing.md

@@ -2,7 +2,9 @@
 
 Open only the card for the method you are about to call. Each card explains
 when to use the method, its exact published inputs, and a minimal compact call.
-The live MCP `tools/list` schema is authoritative.
+The live MCP `tools/list` schema is authoritative. Every answer carries
+`repository_context` (root, scan revision, Git HEAD, graph age); pass
+`expected_repository` to fail fast when the active repository differs.
 
 ## Graph, source, and orientation
 
@@ -12,13 +14,15 @@ The live MCP `tools/list` schema is authoritative.
 - [`query_graph`](tools/query_graph.md) — Bounded BFS or DFS around exact or textual seeds.
 - [`god_nodes`](tools/god_nodes.md) — Rank high-connectivity production nodes.
 - [`shortest_path`](tools/shortest_path.md) — Shortest typed dependency path between two nodes.
-- [`get_community`](tools/get_community.md) — Return one weak graph component.
-- [`list_communities`](tools/list_communities.md) — List deterministic weak graph components.
-- [`module_map`](tools/module_map.md) — Production folder and dependency map.
+- [`get_community`](tools/get_community.md) — Return one coupling community (containment and package edges excluded).
+- [`list_communities`](tools/list_communities.md) — List deterministic coupling communities (containment and package edges excluded).
+- [`module_map`](tools/module_map.md) — Production folder map at a requested directory depth.
 - [`build_graph`](tools/build_graph.md) — Workspace, target and runner topology from manifest evidence.
 - [`search_code`](tools/search_code.md) — Literal or Rust-regex repository search without ripgrep.
 - [`read_source`](tools/read_source.md) — Bounded source context by node or repository path.
 - [`inspect_symbol`](tools/inspect_symbol.md) — Definition, direct relationships and source evidence.
+- [`go_to_definition`](tools/go_to_definition.md) — Resolve the symbol at a source position to its definition without guessing by name.
+- [`find_references`](tools/find_references.md) — Occurrences of the symbol at a position or label, from the graph and an on-disk SCIP index if present.
 - [`context_bundle`](tools/context_bundle.md) — Compact graph and source bundle for one symbol.
 - [`map_stacktrace`](tools/map_stacktrace.md) — Map stack-trace text onto repository files and symbols.
 
@@ -28,7 +32,8 @@ The live MCP `tools/list` schema is authoritative.
 - [`change_impact`](tools/change_impact.md) — Read-only Git change impact with graph evidence.
 - [`select_tests`](tools/select_tests.md) — Select the test suites a change most plausibly needs to run.
 - [`git_history`](tools/git_history.md) — Bounded direct Git history without launching git.
-- [`cross_repo_git`](tools/cross_repo_git.md) — Parallel histories, shared commits, or diffs across local repositories.
+- [`git_read_blob`](tools/git_read_blob.md) — Bounded UTF-8 file content at an immutable Git revision or blob OID; binary blobs are refused.
+- [`cross_repo_git`](tools/cross_repo_git.md) — Parallel histories, shared commits, or diffs across named local repositories.
 - [`verified_change`](tools/verified_change.md) — Composite pre-commit evidence and conservative verdict.
 - [`graph_diff`](tools/graph_diff.md) — Compare the current snapshot with an immutable Git revision.
 
@@ -38,7 +43,8 @@ The live MCP `tools/list` schema is authoritative.
 - [`find_dead_code`](tools/find_dead_code.md) — Conservative unreferenced-symbol review queue.
 - [`run_audit`](tools/run_audit.md) — Repository structure and evidence completeness audit.
 - [`coverage_map`](tools/coverage_map.md) — Measured coverage discovery or explicit static reachability.
-- [`hot_path_review`](tools/hot_path_review.md) — Rank high-connectivity and large source symbols.
+- [`hot_path_review`](tools/hot_path_review.md) — Rank functions by static complexity times resolved call fan-in.
+- [`perf_attribution`](tools/perf_attribution.md) — Correlate a measurement series with the declarations that changed between the revisions that produced it.
 - [`get_architecture_contract`](tools/get_architecture_contract.md) — Read or preview the local target-architecture contract.
 - [`prepare_change`](tools/prepare_change.md) — Select architecture rules for intended changed files.
 - [`verify_architecture`](tools/verify_architecture.md) — Verify graph dependencies against the active contract.
@@ -48,14 +54,14 @@ The live MCP `tools/list` schema is authoritative.
 
 ## APIs and transports
 
-- [`list_endpoints`](tools/list_endpoints.md) — Inventory statically extracted HTTP endpoints.
+- [`list_endpoints`](tools/list_endpoints.md) — Inventory statically extracted HTTP endpoints, including hand-rolled req.method/pathname conditions.
 - [`trace_endpoint`](tools/trace_endpoint.md) — Resolve an endpoint and its bounded call neighborhood.
-- [`trace_api_contract`](tools/trace_api_contract.md) — Cross-repository HTTP, GraphQL, gRPC and event-transport contract evidence.
+- [`trace_api_contract`](tools/trace_api_contract.md) — Cross-repository HTTP, GraphQL, gRPC and event-transport contract evidence for named backend and client roots.
 
 ## Repositories and refresh
 
-- [`open_repo`](tools/open_repo.md) — Retarget to another local repository.
-- [`list_known_repos`](tools/list_known_repos.md) — List repositories opened by this server process.
+- [`open_repo`](tools/open_repo.md) — Retarget to another local repository. Graphs unused for 20 minutes unload; asking for one again rescans that folder.
+- [`list_known_repos`](tools/list_known_repos.md) — List repositories with an in-process graph.
 - [`rebuild_graph`](tools/rebuild_graph.md) — Rebuild the derived in-memory graph without source writes.
 
 ## Optional supplied-data analysis

package/skill/references/tools/find_references.md

@@ -0,0 +1,36 @@
+# `find_references`
+
+Occurrences of the symbol at a position or label, from the graph and an on-disk SCIP index if present.
+
+## When to use
+
+List every recorded occurrence of one symbol after you have a label or a pinned
+`(path, line, column)` usage.
+
+## Inputs
+
+- `label` (string) — exact node label; mutually exclusive with a full position.
+- `path` (string) — repository-relative file when resolving by position.
+- `line` (integer, min 1) — 1-based line when resolving by position.
+- `column` (integer, min 1) — 1-based column when resolving by position.
+- `scip_path` (string) — optional on-disk SCIP index; never spawned.
+- `max_results` (integer, min 1).
+- `cursor` (string).
+- `output_format` ("text" | "json" | "structured", default "json") — text returns the concise text block only; json returns structured output and mirrors it into text for clients that read only content; structured drops that mirror, which is the larger copy, and is safe only where the client reads structuredContent.
+
+## Minimal call
+
+```json
+{
+  "name": "find_references",
+  "arguments": {
+    "path": "src/main.rs",
+    "line": 42,
+    "column": 12,
+    "output_format": "text"
+  }
+}
+```
+
+Requires `label` or a complete position. The live MCP `tools/list` schema
+remains authoritative for this installed version.

package/skill/references/tools/git_read_blob.md

@@ -0,0 +1,33 @@
+# `git_read_blob`
+
+Bounded UTF-8 file content at an immutable Git revision or blob OID; binary blobs are refused.
+
+## When to use
+
+After `graph_diff` or `git_history`, read a file "as it was" at a revision - or the exact blob an OID names - without checking anything out.
+
+## Inputs
+
+- `max_bytes` (integer, min 1) — cap on returned content bytes (default 262144); the true size and a truncation flag are always reported.
+- `oid` (string) — blob object id; mutually exclusive with `path`.
+- `output_format` ("text" | "json" | "structured", default "json") — text returns the concise text block only; json returns structured output and mirrors it into text for clients that read only content; structured drops that mirror, which is the larger copy, and is safe only where the client reads structuredContent.
+- `path` (string) — repository-relative file path looked up in the revision's tree.
+- `revision` (string) — any resolvable revision, `~N` first-parent steps supported; default `HEAD`.
+- `token_budget` (integer, min 1) — Approximate output ceiling in tokens (serialized bytes / 4); result arrays are trimmed from the tail to fit and the report states what was dropped.
+
+## Minimal call
+
+```json
+{
+  "name": "git_read_blob",
+  "arguments": {
+    "path": "src/app.js",
+    "revision": "HEAD~1",
+    "output_format": "text"
+  }
+}
+```
+
+Binary content fails closed with the blob's true size; the answer never
+fabricates text from bytes. The live MCP `tools/list` schema remains
+authoritative for this installed version.

package/skill/references/tools/go_to_definition.md

@@ -0,0 +1,34 @@
+# `go_to_definition`
+
+Resolve the symbol at a source position to its definition without guessing by name.
+
+## When to use
+
+You already have `(path, line, column)` for a usage and need the definition the
+graph recorded for that occurrence - not a same-named overload elsewhere.
+
+## Inputs
+
+- `path` (string, required) — repository-relative file.
+- `line` (integer, required, min 1) — 1-based line of the usage.
+- `column` (integer, required, min 1) — 1-based column of the usage.
+- `scip_path` (string) — optional on-disk SCIP index; never spawned.
+- `output_format` ("text" | "json" | "structured", default "json") — text returns the concise text block only; json returns structured output and mirrors it into text for clients that read only content; structured drops that mirror, which is the larger copy, and is safe only where the client reads structuredContent.
+
+## Minimal call
+
+```json
+{
+  "name": "go_to_definition",
+  "arguments": {
+    "path": "src/main.rs",
+    "line": 42,
+    "column": 12,
+    "output_format": "text"
+  }
+}
+```
+
+Unresolved positions stay `UNRESOLVED`; a unique repository name is not a
+definition. The live MCP `tools/list` schema remains authoritative for this
+installed version.

package/skill/references/tools/list_known_repos.md

@@ -1,10 +1,10 @@
 # `list_known_repos`
 
-List repositories opened by this server process.
+List repositories with an in-process graph.
 
 ## When to use
 
-List repositories previously opened by this server process.
+See which roots this process has already opened.
 
 ## Inputs
 

package/skill/references/tools/perf_attribution.md

@@ -0,0 +1,39 @@
+# `perf_attribution`
+
+Correlate a measurement series with the declarations that changed between the revisions that produced it.
+
+## When to use
+
+You already have a harness table of measurements per Git revision and want
+co-occurrence with structural change - not a profiler sample.
+
+## Inputs
+
+- `measurements_file` (string, required) — repository-relative TSV/CSV the harness wrote; `#` comment rows are ignored.
+- `metric` (string, required) — column with the measured number.
+- `revision_column` (string, default `"commit"`) — column with the Git revision.
+- `direction` ("lower_is_better" | "higher_is_better", default `"lower_is_better"`).
+- `max_revisions` (integer, min 2).
+- `min_delta_percent` (integer, min 0).
+- `top_n` (integer, min 0).
+- `path` (string).
+- `include_tests` (boolean).
+- `include_classified` (boolean).
+- `output_format` ("text" | "json" | "structured", default "json") — text returns the concise text block only; json returns structured output and mirrors it into text for clients that read only content; structured drops that mirror, which is the larger copy, and is safe only where the client reads structuredContent.
+
+## Minimal call
+
+```json
+{
+  "name": "perf_attribution",
+  "arguments": {
+    "measurements_file": "bench/results.tsv",
+    "metric": "ns_per_op",
+    "output_format": "text"
+  }
+}
+```
+
+This is co-occurrence between caller measurements and static change, not CPU
+profiler attribution. The live MCP `tools/list` schema remains authoritative
+for this installed version.