weavatrix 1.9.1 → 1.10.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 44 read-only operations over one
 revision-bound evidence graph: impact, architecture, APIs, Git history,
 duplicates, dead code, search, semantic links, and temporal memory.
 
@@ -91,9 +93,83 @@ 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 44 read-only operations
 
 | Workflow | Operations |
 | --- | --- |
@@ -103,7 +179,7 @@ Build the smallest source bundle needed to edit this symbol safely.
 | Health and quality | `find_duplicates`, `find_dead_code`, `run_audit`, `coverage_map`, `hot_path_review` |
 | 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.1
+weavatrix 1.10.0
     profile catalog · refresh · watcher · MCP framing
     |
     v
-weavatrix-rust 2.7.3
-    typed graph · analysis · 43 read-only operations
+weavatrix-rust 2.9.0
+    typed graph · analysis · 44 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.1",
-  "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.10.0",
+  "weavatrixEngineVersion": "2.9.0",
+  "description": "Native repository intelligence for coding agents: 44 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",
@@ -13,7 +13,7 @@
   "bugs": {
     "url": "https://github.com/Weavatrix/weavatrix/issues"
   },
-  "mcpName": "io.github.weavatrix/weavatrix",
+  "mcpName": "io.github.Weavatrix/weavatrix",
   "type": "module",
   "engines": {
     "node": ">=18"

package/server.json

@@ -1,20 +1,20 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.weavatrix/weavatrix",
+  "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: 44 read-only repository tools across 24 code and configuration surfaces.",
   "repository": {
     "url": "https://github.com/Weavatrix/weavatrix",
     "source": "github"
   },
-  "version": "1.9.1",
+  "version": "1.10.0",
   "websiteUrl": "https://weavatrix.com",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "weavatrix",
-      "version": "1.9.1",
+      "version": "1.10.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

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,9 +14,9 @@ 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.
@@ -28,7 +30,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 +41,7 @@ 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.
 - [`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 +51,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/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/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