weavatrix 0.1.0

package/src/infra/infra.js

@@ -0,0 +1,38 @@
+// Infrastructure / backing-service detection. graph-builder's graph.json only contains code FILES and
+// symbols, so the GUI board's external-service towers were inferred purely from FILE PATHS
+// (relIsDb + a name-regex). That misses any datastore whose connector file isn't literally named
+// after it — e.g. a service that `import`s @clickhouse/client from services/metrics.js, or wires
+// Influx through a logging helper. This module reads the REAL high-signal sources instead:
+//   1. dependency manifests   (package.json / go.mod / requirements.txt / pom.xml / build.gradle /
+//                              Cargo.toml / *.csproj / Gemfile / composer.json)  — most reliable
+//   2. container/orchestration (docker-compose / Dockerfile / k8s manifests) — image names
+//   3. env / config            (.env*, k8s env:) — variable-NAME conventions (KEYS ONLY, never values)
+//   4. source imports          — to attribute each service to its connector file(s) for the io edges
+// and matches them against a curated signature registry → a structured list of services the repo
+// talks to, each with kind/name/colour + the files that connect to it.
+//
+// PRIVACY: env files are read for KEY NAMES only (the part before `=`); values are never parsed,
+// stored, logged, or returned. Secrets in .env stay in .env.
+//
+// This file is now a facade — the implementation lives in the sibling modules below; every public
+// export is re-exported here so existing import paths keep working unchanged:
+//   infra.match.js  — deterministic matchers (deps / images / env keys) + manifest dep extraction
+//   infra.scan.js   — the single filesystem walk (manifests, compose/k8s images, env KEY names)
+//   infra.detect.js — signature matching, connector-file attribution, cached public API
+
+// ---- signature registry ----
+// One row per backing service, loaded from infra-registry.js (generated + adversarially verified by the
+// infra-signature-registry workflow). Matching is DETERMINISTIC token comparison (no free-form regex over
+// arbitrary text), so false positives stay near zero:
+//   deps        — exact manifest dependency names; token T matches dep D when D===T or D starts with T/ T: T@.
+//   images      — docker image repo names, matched by path-segment SUFFIX ("redis" hits "bitnami/redis";
+//                 "mongo" misses "mongo-express").
+//   envPrefixes — UPPERCASE env-var KEY prefixes; token P matches key K when K===P or K starts with P_.
+//                 Prefixes listed in envWeak only count when the key ALSO ends in an infra suffix
+//                 (HOST/URL/DSN/PORT/BROKER/…), so DATABASE_URL-style keys can't over-fire.
+//   imports     — quoted substrings in source import/require lines; used to attribute connector files.
+// kind ∈ db|ts|cache|queue|cloud|api|fs|logs — drives the GUI board tower glyph/colour (GUI core KCFG).
+export { INFRA_SERVICES } from "./infra-registry.js";
+
+export { depMatches, normImageRepo, imageMatches, envMatches, depsFromManifest } from "./infra.match.js";
+export { detectInfraFromScan, detectInfra } from "./infra.detect.js";

package/src/infra/infra.match.js

@@ -0,0 +1,102 @@
+// Deterministic matchers + manifest dependency extraction for infrastructure detection.
+// Split out of infra.js (which remains the public facade); see that file's header for the full
+// detection pipeline and the registry/matching contract.
+import { lc } from "./infra-items.js";
+
+// env-var name suffixes that, when a generic prefix carries one, confirm it really configures a
+// backing service (so PG_/DATABASE_/S3_/ES_ only fire on PG_HOST, DATABASE_URL, S3_BUCKET, …).
+const ENV_SUFFIX = /_(HOSTS?|URLS?|URI|DSN|PORTS?|ADDR|ADDRESS(ES)?|BROKERS?|SERVERS?|ENDPOINTS?|CONN|CONNECTION(S)?|DB|DATABASE|PASS(WORD)?|USER(NAME)?|SECRET|TOPICS?|BUCKETS?|REGION|GROUP|CLUSTER|NAMESPACE|REPLICA(SET)?|MEASUREMENT|TLS|SSL|KEY|TOKEN)$/;
+
+// ---- matchers (exported for unit tests) ---------------------------------------------------------
+export function depMatches(manifestDep, token) {
+  const m = lc(manifestDep), d = lc(token);
+  if (!m || !d) return false;
+  return m === d || m.startsWith(d + "/") || m.startsWith(d + ":") || m.startsWith(d + "@");
+}
+
+// strip registry host + tag + digest → bare repo path (lowercased)
+export function normImageRepo(ref) {
+  let s = String(ref || "").trim().replace(/^['"]|['"]$/g, "");
+  if (!s) return "";
+  const at = s.indexOf("@");
+  if (at >= 0) s = s.slice(0, at); // strip @sha256:...
+  const slash = s.lastIndexOf("/");
+  const lastSeg = s.slice(slash + 1);
+  const colon = lastSeg.indexOf(":"); // tag lives only in the last path segment (host may have :port)
+  if (colon >= 0) s = s.slice(0, slash + 1) + lastSeg.slice(0, colon);
+  return lc(s);
+}
+// repo path-segments end with the token's segments (so "redis" hits "bitnami/redis", "mongo" misses "mongo-express")
+export function imageMatches(repoSegs, token) {
+  const t = lc(token).split("/").filter(Boolean);
+  if (!t.length || t.length > repoSegs.length) return false;
+  for (let i = 1; i <= t.length; i++) if (repoSegs[repoSegs.length - i] !== t[t.length - i]) return false;
+  return true;
+}
+
+export function envMatches(key, token, weak) {
+  const K = String(key || "").toUpperCase(), P = String(token || "").toUpperCase();
+  if (!K || !P) return false;
+  if (K !== P && !K.startsWith(P + "_")) return false;
+  if (weak) {
+    if (K === P) return false; // a bare generic prefix alone proves nothing
+    if (!ENV_SUFFIX.test(K.slice(P.length))) return false; // require an infra-ish suffix
+  }
+  return true;
+}
+
+// ---- manifest dependency extraction -------------------------------------------------------------
+
+// Returns a Set of dependency token strings pulled from one manifest file. PROD deps only where the
+// format distinguishes them (package.json/composer.json), so test-only clients (ioredis-mock,
+// mongodb-memory-server, testcontainers) don't manufacture a phantom service.
+// test doubles / in-memory fakes / emulators — these pull in a client name but mean "this is tested
+// against a fake", not "depends on the live service". Never let them register a backing service.
+const DEV_DOUBLE = /(-mock|_mock|mock-|fake|memory-server|inmemory|testcontainers|-local$|localstack|azurite)/i;
+
+export function depsFromManifest(name, text) {
+  const out = new Set();
+  const add = (v) => { const s = String(v || "").trim(); if (s && !DEV_DOUBLE.test(s)) out.add(s); };
+  const low = name.toLowerCase();
+  try {
+    if (low === "package.json") {
+      const j = JSON.parse(text);
+      for (const sect of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+        if (j[sect] && typeof j[sect] === "object") for (const k of Object.keys(j[sect])) add(k);
+      }
+    } else if (low === "composer.json") {
+      const j = JSON.parse(text);
+      if (j.require && typeof j.require === "object") for (const k of Object.keys(j.require)) add(k);
+    } else if (low === "go.mod") {
+      // `require x.y/z v1` and `require ( … )` blocks
+      for (const m of text.matchAll(/^\s*(?:require\s+)?([a-z0-9.-]+\.[a-z]{2,}\/[^\s]+)\s+v[0-9]/gim)) add(m[1]);
+    } else if (low === "go.sum") {
+      for (const m of text.matchAll(/^([a-z0-9.-]+\.[a-z]{2,}\/[^\s]+)\s+v[0-9]/gim)) add(m[1]);
+    } else if (low === "requirements.txt" || low === "constraints.txt") {
+      for (const line of text.split(/\r?\n/)) {
+        const m = line.match(/^\s*([A-Za-z0-9._-]+)/);
+        if (m && !line.trim().startsWith("#")) add(m[1]);
+      }
+    } else if (low === "pipfile" || low === "pyproject.toml" || low === "cargo.toml") {
+      // TOML dependency tables — pull bare `name = ...` keys and array-of-strings `"name>=x"`.
+      for (const m of text.matchAll(/^\s*["']?([A-Za-z0-9._-]+)["']?\s*=/gm)) add(m[1]);
+      for (const m of text.matchAll(/["']([A-Za-z0-9._-]+)\s*[<>=~!^*]/g)) add(m[1]);
+    } else if (low === "pom.xml") {
+      // pair each <artifactId> with the nearest preceding <groupId> → group:artifact AND bare artifact
+      const re = /<groupId>\s*([^<]+?)\s*<\/groupId>\s*<artifactId>\s*([^<]+?)\s*<\/artifactId>/g;
+      let m;
+      while ((m = re.exec(text))) { add(`${m[1]}:${m[2]}`); add(m[2]); }
+      for (const a of text.matchAll(/<artifactId>\s*([^<]+?)\s*<\/artifactId>/g)) add(a[1]);
+    } else if (low.endsWith(".gradle") || low.endsWith(".gradle.kts")) {
+      // implementation('group:artifact:ver') / "group:artifact:ver"
+      for (const m of text.matchAll(/["']([A-Za-z0-9._-]+:[A-Za-z0-9._-]+)(?::[^"']*)?["']/g)) { add(m[1]); add(m[1].split(":")[1]); }
+    } else if (low.endsWith(".csproj") || low === "packages.config" || low.endsWith(".fsproj")) {
+      for (const m of text.matchAll(/(?:PackageReference|package)\s+(?:Include|id)\s*=\s*"([^"]+)"/gi)) add(m[1]);
+    } else if (low === "gemfile") {
+      for (const m of text.matchAll(/^\s*gem\s+["']([^"']+)["']/gim)) add(m[1]);
+    }
+  } catch {
+    /* malformed manifest — skip */
+  }
+  return out;
+}

package/src/infra/infra.scan.js

@@ -0,0 +1,93 @@
+// Repo filesystem scan for infrastructure detection: one walk collects manifest dependency tokens,
+// container image refs, env-var KEY names (never values — see the privacy note in infra.js), and
+// code files for the import-attribution pass. Split out of infra.js (which remains the public facade).
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { safeRead } from "./infra-items.js";
+import { depsFromManifest, normImageRepo } from "./infra.match.js";
+
+// ---- scanning bounds (mirror apimap.js) ---------------------------------------------------------
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out", ".next", "coverage", "vendor",
+  ".venv", "venv", "env", "target", "__pycache__", ".idea", ".vscode", ".cache", "bin", "obj",
+]);
+const CODE_EXT = new Set([
+  ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".vue", ".svelte",
+  ".py", ".go", ".java", ".kt", ".rb", ".php", ".cs", ".scala", ".rs",
+]);
+const MAX_FILES = 60000;
+// graph-analysis IPC stays responsive on large repos — detection itself (manifests/images/env) is unaffected
+
+const MANIFEST_NAMES = new Set([
+  "package.json", "composer.json", "go.mod", "go.sum", "requirements.txt", "constraints.txt",
+  "pipfile", "pyproject.toml", "cargo.toml", "pom.xml", "packages.config", "gemfile",
+]);
+const isManifest = (name) => {
+  const n = name.toLowerCase();
+  return MANIFEST_NAMES.has(n) || n.endsWith(".gradle") || n.endsWith(".gradle.kts") || n.endsWith(".csproj") || n.endsWith(".fsproj");
+};
+const isComposeFile = (name) => /^(docker-)?compose([.-].*)?\.ya?ml$/i.test(name);
+const isDockerfile = (name) => /^dockerfile(\..+)?$/i.test(name) || /\.dockerfile$/i.test(name);
+const isYaml = (name) => /\.ya?ml$/i.test(name);
+
+// ---- the scan -----------------------------------------------------------------------------------
+export function scanRepo(repoPath) {
+  const deps = new Set();         // manifest dependency tokens
+  const imageRefs = [];           // normalized image repo paths
+  const envKeys = new Set();      // UPPERCASE env-var names (keys only)
+  const codeFiles = [];           // { path(rel, fwd-slash), full } for the import pass
+  const manifests = new Set();    // which manifest kinds were seen (for diagnostics)
+
+  let count = 0;
+  const stack = [repoPath];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) stack.push(join(cur, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (++count > MAX_FILES) break;
+      const name = entry.name;
+      const full = join(cur, name);
+      const rel = full.slice(repoPath.length).replace(/^[\\/]/, "").replace(/\\/g, "/");
+
+      if (isManifest(name)) {
+        manifests.add(name.toLowerCase());
+        for (const d of depsFromManifest(name, safeRead(full))) deps.add(d);
+        continue;
+      }
+      if (/^\.env(\..+)?$/i.test(name)) {
+        const text = safeRead(full);
+        // KEYS ONLY — split on the first '=' and keep the left side; never read the value.
+        for (const line of text.split(/\r?\n/)) {
+          const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+          if (m) envKeys.add(m[1].toUpperCase());
+        }
+        continue;
+      }
+      const dockery = isComposeFile(name) || isDockerfile(name);
+      if (dockery || isYaml(name)) {
+        const text = safeRead(full);
+        if (!text) continue;
+        const k8sLike = /(^|\n)\s*kind:\s*\S/.test(text) && /(^|\n)\s*(image|env):/.test(text);
+        if (!dockery && !k8sLike) continue; // a random *.yaml that isn't a manifest — skip
+        for (const m of text.matchAll(/(?:^|\n)\s*(?:-\s*)?image:\s*["']?([^\s"']+)/gi)) imageRefs.push(normImageRepo(m[1]));
+        for (const m of text.matchAll(/(?:^|\n)\s*FROM\s+(?:--platform=\S+\s+)?([^\s]+)/gi)) imageRefs.push(normImageRepo(m[1]));
+        // env var NAMES: k8s `- name: KEY`, compose `KEY: value` / `- KEY=value`, Dockerfile `ENV KEY`
+        for (const m of text.matchAll(/\bname:\s*["']?([A-Z_][A-Z0-9_]{2,})\b/g)) envKeys.add(m[1].toUpperCase());
+        for (const m of text.matchAll(/(?:^|\n)\s*(?:-\s*)?([A-Z_][A-Z0-9_]{2,})\s*[:=]/g)) envKeys.add(m[1].toUpperCase());
+        continue;
+      }
+      const dot = name.lastIndexOf(".");
+      const ext = dot >= 0 ? name.slice(dot).toLowerCase() : "";
+      if (CODE_EXT.has(ext)) codeFiles.push({ path: rel, full });
+    }
+    if (count > MAX_FILES) break;
+  }
+  const imageSegs = imageRefs.filter(Boolean).map((r) => ({ raw: r, segs: r.split("/").filter(Boolean) }));
+  return { deps, imageSegs, envKeys, codeFiles, manifests: [...manifests] };
+}

package/src/mcp/catalog.mjs

@@ -0,0 +1,68 @@
+// Tool catalog + hot-reload loader. Every tool declares a capability GROUP; the stdio shell exposes
+// only the groups enabled for this registration (argv[4]). loadHotApi() re-imports the tool modules
+// with a cache-busting version so edits to src/mcp/tools-*.mjs (or this file) go live without an MCP
+// reconnect. graph-context.mjs is imported STATICALLY everywhere — it holds process-lifetime caches
+// and does not hot-reload (nor do the ../analysis engines; changing those needs a reconnect).
+import {dirname} from 'node:path'
+import {fileURLToPath} from 'node:url'
+import {resolveNode, isSymbol, stalenessLine, resetStalenessCache} from './graph-context.mjs'
+import {createRgResolver} from '../mcp-rg.mjs'
+import {readSource, searchCode} from '../mcp-source-tools.mjs'
+
+const SELF_DIR = dirname(fileURLToPath(import.meta.url))
+const resolveRg = createRgResolver(SELF_DIR)
+
+// The files whose mtime the stdio shell watches for hot reload — keep in sync with the imports in
+// loadHotApi below (catalog.mjs itself is last: a change here re-derives the whole table).
+export const HOT_FILES = ['tools-graph.mjs', 'tools-impact.mjs', 'tools-health.mjs', 'tools-actions.mjs', 'catalog.mjs']
+
+function buildTools({tg, ti, th, ta}) {
+    return [
+        {cap: 'graph', name: 'graph_stats', description: 'Return summary statistics: node count, edge count, communities, confidence breakdown, and graph build time vs repo HEAD (staleness).', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tg.tGraphStats(g, ctx)},
+        {cap: 'graph', name: 'get_node', description: 'Get full details for a specific node by label or ID.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID to look up'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNode(g, a, ctx)},
+        {cap: 'graph', name: 'get_neighbors', description: 'Get all direct neighbors of a node with edge details (1 hop, call sites deduped). For transitive impact use get_dependents; for the impact of your current branch changes use change_impact.', inputSchema: {type: 'object', properties: {label: {type: 'string'}, relation_filter: {type: 'string', description: 'Optional: filter by relation type'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNeighbors(g, a, ctx)},
+        {cap: 'graph', name: 'query_graph', description: 'Explore the graph around a concept (BFS/DFS). Returns a focused, ranked subgraph — the closest, most-connected nodes near the matched seeds, with edges among them — not the full flood; states how many nodes were reached vs shown.', inputSchema: {type: 'object', properties: {question: {type: 'string', description: 'Natural language question or keyword search'}, mode: {type: 'string', enum: ['bfs', 'dfs'], default: 'bfs'}, depth: {type: 'integer', default: 3}, context_filter: {type: 'array', items: {type: 'string'}}, token_budget: {type: 'integer', description: 'Higher budget shows more nodes/edges', default: 2000}}, required: ['question']}, run: (g, a) => tg.tQueryGraph(g, a)},
+        {cap: 'graph', name: 'god_nodes', description: 'Return the most connected nodes - the core abstractions of the knowledge graph.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}}}, run: (g, a) => tg.tGodNodes(g, a)},
+        {cap: 'graph', name: 'shortest_path', description: 'Find the shortest path between two concepts in the knowledge graph.', inputSchema: {type: 'object', properties: {source: {type: 'string'}, target: {type: 'string'}, max_hops: {type: 'integer', default: 8}}, required: ['source', 'target']}, run: (g, a) => tg.tShortestPath(g, a)},
+        {cap: 'graph', name: 'get_dependents', description: 'Transitive blast-radius of ONE node: everything that calls/imports/inherits it, directly or through intermediaries (reverse edges, ranked by proximity then connectivity). For a symbol, also follows importers of its containing file. Use before refactoring; get_neighbors shows only 1 hop, change_impact covers your whole current diff at once.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID'}, depth: {type: 'integer', description: 'Max reverse hops, default 3', default: 3}, max_nodes: {type: 'integer', description: 'Max dependents to list, default 40', default: 40}}, required: ['label']}, run: (g, a) => ti.tGetDependents(g, a)},
+        {cap: 'graph', name: 'change_impact', description: 'Blast radius of a change: by default diffs branch commits + staged/unstaged/untracked work against a base ref (auto merge-base with origin/main|master), OR takes an explicit `files` list (e.g. a PR\'s changed files — assesses a NOT-checked-out PR). Maps changed files/symbols onto the graph and lists everything depending on them (reverse edges, ranked by proximity + connectivity) with test coverage attached — untested hotspots called out. Run before opening or reviewing a PR; drill down with get_dependents, coverage detail via coverage_map.', inputSchema: {type: 'object', properties: {base: {type: 'string', description: 'Base ref, e.g. origin/main or HEAD~1 (default: first existing of origin/HEAD, origin/main, origin/master, main, master)'}, files: {type: 'array', items: {type: 'string'}, description: 'Explicit repo-relative changed-file list — skips the local git diff; use for PRs that are not checked out'}, depth: {type: 'integer', description: 'Max reverse hops, default 2'}, max_nodes: {type: 'integer', description: 'Max impacted nodes to list, default 40'}}}, run: (g, a, ctx) => ti.tChangeImpact(g, a, ctx)},
+        {cap: 'graph', name: 'get_community', description: 'Get all nodes in a community by community ID (0-indexed by size).', inputSchema: {type: 'object', properties: {community_id: {type: 'integer', description: 'Community ID (0-indexed by size)'}}, required: ['community_id']}, run: (g, a) => tg.tGetCommunity(g, a)},
+        {cap: 'search', name: 'search_code', description: 'Full-text or regex search across the repo source (ripgrep-backed, Node fallback). The graph only stores structure — use this to find literal text/patterns, then get_node/get_neighbors for structure.', inputSchema: {type: 'object', properties: {query: {type: 'string', description: 'text or regex to search for'}, is_regex: {type: 'boolean', default: false}, glob: {type: 'string', description: 'optional path glob, e.g. "*.js" or "src/**"'}, max_results: {type: 'integer', default: 40}}, required: ['query']}, run: (g, a, ctx) => searchCode({repoRoot: ctx.repoRoot, resolveRg}, a)},
+        {cap: 'source', name: 'read_source', description: "Read the actual source of a node (by label/ID) or a repo-relative file path — the symbol's lines with context. The graph stores only locations, not source text. For a path read, pass start_line to anchor the window anywhere in the file (otherwise it shows the head).", inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'node label or ID'}, path: {type: 'string', description: 'or a repo-relative file path'}, start_line: {type: 'integer', description: 'anchor line: window = start_line-before .. start_line+after'}, before: {type: 'integer', default: 3}, after: {type: 'integer', default: 40}}}, run: (g, a, ctx) => readSource({repoRoot: ctx.repoRoot, resolveNode, isSymbol}, g, a)},
+        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over the repo (MOSS winnowing over method bodies — finds copy-paste even with renamed variables, not just matching names). Returns clone groups with file:line sites. Use to guide de-duplication refactors. mode 'semantic' flips the lens: same-name symbols across files ranked by size, where LOW similarity marks divergent copies (same name, drifted behavior) — min_similarity is ignored there.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', description: 'min fragment size, default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals (embedded C#/SQL/PowerShell templates) — the code pass strips string bodies, so these are otherwise invisible', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
+        {cap: 'health', name: 'run_audit', description: 'Full internal health audit of the repo: dead code (unused files/exports), dependency health (missing/undeclared and unused npm/Go/Python deps), structure (import cycles, orphan files, boundary-rule violations), and offline supply-chain checks (known OSV vulnerabilities, typosquats, lockfile drift). Filter by category/severity. Malware heuristics are opt-in (slow).', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
+        {cap: 'health', name: 'coverage_map', description: 'Map an existing test-coverage report (istanbul/lcov/coverage.py/Go cover.out — read offline, never runs tests) onto the code graph: per-module coverage plus refactor-risk hotspots — well-connected symbols with low coverage, ranked by degree × uncovered. Pair with get_dependents: many dependents + low coverage ⇒ write tests before changing.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
+        {cap: 'graph', name: 'list_communities', description: 'List graph communities named by their dominant folder (largest first) with sample files — a readable module overview; feed the list position into get_community.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max communities to list, default 20'}}}, run: (g, a, ctx) => th.tListCommunities(g, a, ctx)},
+        {cap: 'graph', name: 'module_map', description: 'Folder-level architecture map: modules with file/symbol counts plus the strongest module→module dependency edges. Fast orientation before diving into files.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
+        {cap: 'source', name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux …): method, path, handler, and file:line, deduped across code and OpenAPI docs.', inputSchema: {type: 'object', properties: {max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
+        {cap: 'build', name: 'rebuild_graph', description: "Rebuild this repo's code graph from current source (weavatrix's own web-tree-sitter builder), reload it in-memory, and report the STRUCTURAL DELTA vs the previous state — new/removed module dependencies, cycle changes, newly orphaned symbols. The prior state is saved as graph.prev.json for graph_diff. Call after significant edits.", inputSchema: {type: 'object', properties: {mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}, scope: {type: 'string', description: 'optional path prefix to limit the graph'}}}, run: (g, a, ctx) => ta.tRebuildGraph(g, a, ctx)},
+        {cap: 'graph', name: 'graph_diff', description: 'Structural diff of the last rebuild: previous graph state (graph.prev.json, saved by rebuild_graph) vs current — architecture drift (new module dependencies), broken or introduced import cycles, symbols that lost their last caller. The semantic complement to the textual git diff for validating a refactor.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Optional node-id/path prefix to scope the diff, e.g. src/query'}}}, run: (g, a, ctx) => ti.tGraphDiff(g, a, ctx)},
+        {cap: 'build', name: 'open_repo', description: 'Retarget this server at another local repository: loads its graph from the central weavatrix-graphs layout next to the repo, building it first when missing (large repos can take minutes; pass build:false to probe without building). Afterwards every tool answers for the new repo.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Absolute path to the repository folder'}, build: {type: 'boolean', description: 'Build the graph when missing (default true)', default: true}, mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}}, required: ['path']}, run: (g, a, ctx) => ta.tOpenRepo(g, a, ctx)},
+        {cap: 'graph', name: 'list_known_repos', description: 'List sibling repositories that already have a built graph in the central weavatrix-graphs folder next to the current repo — ready targets for open_repo.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tListKnownRepos(g, a, ctx)},
+        {cap: 'online', name: 'refresh_advisories', description: "ONLINE, explicit opt-in: refresh the local OSV advisory store for this repo's lockfile-pinned packages (npm/PyPI/Go). Sends package names + versions to OSV.dev — never automatic, never source code. Afterwards run_audit reads the refreshed store fully offline (~/.weavatrix/advisories.json).", inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', description: 'Per-request timeout, default 20000'}}}, run: (g, a, ctx) => ta.tRefreshAdvisories(g, a, ctx)},
+        {cap: 'online', name: 'sync_graph', description: 'ONLINE, explicit opt-in, off until configured: push the current graph.json to your weavatrix site or self-hosted endpoint (env WEAVATRIX_SYNC_URL, optional WEAVATRIX_SYNC_TOKEN bearer auth) for a hosted graph view. Payload is the graph only — file paths, symbol names, edges — never file contents.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
+    ]
+}
+
+// Import the tool modules (cache-busted when version > 0), build the catalog, apply the caps filter.
+// capsArg semantics: undefined/null = no per-repo config → ALL tools; a present string (even '') is an
+// explicit selection → expose exactly those groups, so "select nothing" really exposes nothing.
+export async function loadHotApi(version, capsArg) {
+    const v = version ? `?v=${version}` : ''
+    const [tg, ti, th, ta] = await Promise.all([
+        import(new URL(`./tools-graph.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-impact.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-health.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-actions.mjs${v}`, import.meta.url).href),
+    ])
+    const all = buildTools({tg, ti, th, ta})
+    const caps = capsArg == null ? null : new Set(String(capsArg).split(',').map((s) => s.trim()).filter(Boolean))
+    const tools = caps ? all.filter((t) => caps.has(t.cap)) : all
+    return {
+        tools,
+        byName: new Map(tools.map((t) => [t.name, t])),
+        caps,
+        stalenessLine,
+        resetStalenessCache,
+    }
+}

package/src/mcp/graph-context.mjs

@@ -0,0 +1,276 @@
+// Shared graph core for the MCP tool modules: graph loading + indexes, node resolution, staleness,
+// the raw-graph cache, and the structural diff helpers. This module holds process-lifetime CACHES
+// (staleness, raw graph), so every tool module imports it STATICALLY — it is the one part of src/mcp
+// that does NOT hot-reload (editing it needs an MCP reconnect, same as the analysis engines).
+import {readFileSync, statSync} from 'node:fs'
+import {join} from 'node:path'
+import {spawnSync} from 'node:child_process'
+import {buildFileImportGraph, findSccs} from '../analysis/dep-rules.js'
+
+// ---- graph load + indexes -----------------------------------------------------------------------
+export function loadGraph(path) {
+    const raw = JSON.parse(readFileSync(path, 'utf8'))
+    const nodes = Array.isArray(raw.nodes) ? raw.nodes : []
+    const links = Array.isArray(raw.links) ? raw.links : []
+    const byId = new Map()
+    const byLabel = new Map()
+    for (const n of nodes) {
+        if (!n || n.id == null) continue
+        byId.set(String(n.id), n)
+        const key = String(n.label ?? n.id).toLowerCase()
+        if (!byLabel.has(key)) byLabel.set(key, [])
+        byLabel.get(key).push(n)
+    }
+    const out = new Map() // id -> [{id, relation, confidence}]
+    const inn = new Map()
+    const push = (map, k, v) => {
+        if (!map.has(k)) map.set(k, [])
+        map.get(k).push(v)
+    }
+    for (const e of links) {
+        if (!e || e.source == null || e.target == null) continue
+        const s = String(e.source)
+        const t = String(e.target)
+        push(out, s, {id: t, relation: e.relation, confidence: e.confidence})
+        push(inn, t, {id: s, relation: e.relation, confidence: e.confidence})
+    }
+    return {nodes, links, byId, byLabel, out, inn}
+}
+
+export const isSymbol = (id) => String(id).includes('#')
+export const degreeOf = (g, id) => (g.out.get(id)?.length || 0) + (g.inn.get(id)?.length || 0)
+export const labelOf = (g, id) => {
+    const n = g.byId.get(String(id))
+    return n ? String(n.label ?? n.id) : String(id)
+}
+
+// "connectivity" degree ignores structural `contains` (parent→symbol nesting) so god_nodes surfaces real
+// call/import/reference hubs, not just files that hold many symbols.
+export const connList = (list) => (list || []).filter((e) => e.relation !== 'contains')
+
+// Resolve a user-supplied "label" to a node: exact id → exact label → ci label → substring (best degree).
+// Returns {node, matches, alternates} so callers can disclose ambiguity instead of silently picking one.
+export function resolveNodeInfo(g, query) {
+    const q = String(query ?? '').trim()
+    if (!q) return {node: null, matches: 0, alternates: []}
+    if (g.byId.has(q)) return {node: g.byId.get(q), matches: 1, alternates: []}
+    const lc = q.toLowerCase()
+    const exactLabel = g.byLabel.get(lc)
+    if (exactLabel?.length) return pickBest(g, exactLabel)
+    // substring over id + label
+    const hits = []
+    for (const n of g.nodes) {
+        const id = String(n.id).toLowerCase()
+        const lbl = String(n.label ?? '').toLowerCase()
+        if (id.includes(lc) || lbl.includes(lc)) hits.push(n)
+        if (hits.length > 500) break
+    }
+    return hits.length ? pickBest(g, hits) : {node: null, matches: 0, alternates: []}
+}
+export const resolveNode = (g, query) => resolveNodeInfo(g, query).node
+function pickBest(g, list) {
+    const node = bestByDegree(g, list)
+    const alternates = list
+        .filter((n) => n !== node)
+        .sort((a, b) => degreeOf(g, b.id) - degreeOf(g, a.id))
+        .slice(0, 4)
+        .map((n) => `${n.label ?? n.id} [${n.id}]`)
+    return {node, matches: list.length, alternates}
+}
+// One-line disclosure when a fuzzy label matched several nodes — silently picking one hides wrong-node errors.
+export function ambiguityNote(query, info) {
+    if (!info.node || info.matches <= 1) return null
+    const more = info.matches - 1 - info.alternates.length
+    return `Note: "${query}" matched ${info.matches} nodes; using the best-connected. Others: ${info.alternates.join(', ')}${more > 0 ? ` (+${more} more)` : ''}`
+}
+const bestByDegree = (g, list) =>
+    list.reduce((best, n) => (degreeOf(g, n.id) > degreeOf(g, best.id) ? n : best), list[0])
+
+// seeds for traversal/search: rank substring/token matches by degree
+export function findSeeds(g, query, limit = 8) {
+    const q = String(query ?? '').trim().toLowerCase()
+    if (!q) return []
+    const tokens = q.split(/[^a-z0-9_]+/i).filter((t) => t.length > 1)
+    const scored = []
+    for (const n of g.nodes) {
+        const hay = `${String(n.id)} ${String(n.label ?? '')} ${String(n.source_file ?? '')}`.toLowerCase()
+        let score = 0
+        if (hay.includes(q)) score += 5
+        for (const t of tokens) if (hay.includes(t)) score += 1
+        if (score > 0) scored.push({n, score: score + Math.min(3, degreeOf(g, n.id) / 20)})
+    }
+    scored.sort((a, b) => b.score - a.score)
+    return scored.slice(0, limit).map((s) => s.n)
+}
+
+// undirected adjacency for reachability (query/shortest path)
+export function undirectedNeighbors(g, id) {
+    const seen = new Map()
+    for (const e of g.out.get(id) || []) seen.set(e.id, e.relation)
+    for (const e of g.inn.get(id) || []) if (!seen.has(e.id)) seen.set(e.id, e.relation)
+    return seen
+}
+
+// ---- staleness ----------------------------------------------------------------------------------
+// The graph is a point-in-time build of graph.json; without a freshness signal an agent cannot tell
+// whether answers reflect the current code. Compare graph.json mtime with the repo's latest commit
+// (cheap `git log -1`), cached for 60s so per-tool warnings don't spawn git on every call.
+let stalenessCache = {key: '', checkedAt: 0, info: null}
+export function graphStaleness(ctx) {
+    const now = Date.now()
+    if (stalenessCache.info && stalenessCache.key === ctx.graphPath && now - stalenessCache.checkedAt < 60_000) return stalenessCache.info
+    const info = {builtAt: null, headAt: null, stale: false, behind: null}
+    try { info.builtAt = statSync(ctx.graphPath).mtime } catch { /* no graph file — nothing to report */ }
+    if (ctx.repoRoot && info.builtAt) {
+        try {
+            const head = spawnSync('git', ['-C', ctx.repoRoot, 'log', '-1', '--format=%cI'], {encoding: 'utf8', timeout: 4000})
+            const iso = (head.stdout || '').trim()
+            if (head.status === 0 && iso) {
+                info.headAt = new Date(iso)
+                if (info.headAt > info.builtAt) {
+                    info.stale = true
+                    const cnt = spawnSync('git', ['-C', ctx.repoRoot, 'rev-list', '--count', `--since=${info.builtAt.toISOString()}`, 'HEAD'], {encoding: 'utf8', timeout: 4000})
+                    if (cnt.status === 0) info.behind = Number(cnt.stdout.trim()) || null
+                }
+            }
+        } catch { /* git unavailable — degrade to builtAt only */ }
+        // Uncommitted work drifts line numbers just as hard as commits do (that is how agents get bitten:
+        // they edit, then re-query). Count dirty files actually TOUCHED after the build — a dirty file
+        // older than the graph was already part of it.
+        try {
+            const st = spawnSync('git', ['-C', ctx.repoRoot, 'status', '--porcelain'], {encoding: 'utf8', timeout: 4000})
+            if (st.status === 0) {
+                let newer = 0
+                for (const ln of String(st.stdout || '').split(/\r?\n/).filter(Boolean).slice(0, 200)) {
+                    const p = ln.slice(3).trim().replace(/^"|"$/g, '')
+                    try { if (statSync(join(ctx.repoRoot, p)).mtime > info.builtAt) newer++ } catch { newer++ } // deleted counts as drift
+                }
+                info.dirtyNewer = newer
+                if (newer > 0) info.stale = true
+            }
+        } catch { /* git unavailable */ }
+    }
+    stalenessCache = {key: ctx.graphPath, checkedAt: now, info}
+    return info
+}
+export const resetStalenessCache = () => { stalenessCache = {key: '', checkedAt: 0, info: null} }
+export function stalenessLine(ctx) {
+    const s = graphStaleness(ctx)
+    if (!s.stale) return null
+    const bits = []
+    if (s.headAt && s.headAt > s.builtAt) bits.push(`${s.behind != null ? `${s.behind} commit${s.behind === 1 ? '' : 's'}` : 'commits'} newer than the graph`)
+    if (s.dirtyNewer) bits.push(`${s.dirtyNewer} uncommitted file(s) edited after the build`)
+    return `Warning: graph may be stale — the repo has ${bits.join(' and ')} (built ${s.builtAt.toISOString()}). Line numbers may have drifted; call rebuild_graph.`
+}
+
+// Per-file drift check for tools that print exact line numbers: the global warning says the REPO
+// moved; this says THIS file moved — the difference between "be careful" and "these numbers are off".
+export function fileStalenessNote(ctx, sourceFile) {
+    if (!ctx?.repoRoot || !sourceFile) return null
+    const s = graphStaleness(ctx)
+    if (!s.builtAt) return null
+    try {
+        if (statSync(join(ctx.repoRoot, String(sourceFile))).mtime > s.builtAt) {
+            return `Note: ${sourceFile} changed after the graph was built — line numbers above may have drifted (rebuild_graph refreshes them).`
+        }
+    } catch { /* file gone — the read tools will surface that themselves */ }
+    return null
+}
+
+// Raw graph.json (with externalImports, file_type, source_end …) for the analysis modules — the MCP's
+// own loadGraph struct strips those fields. Cached by mtime; rebuild_graph changes the mtime → refresh.
+let rawGraphCache = {path: '', mtimeMs: 0, data: null}
+export function rawGraph(ctx) {
+    const mtimeMs = statSync(ctx.graphPath).mtimeMs
+    if (!rawGraphCache.data || rawGraphCache.path !== ctx.graphPath || rawGraphCache.mtimeMs !== mtimeMs) {
+        rawGraphCache = {path: ctx.graphPath, mtimeMs, data: JSON.parse(readFileSync(ctx.graphPath, 'utf8'))}
+    }
+    return rawGraphCache.data
+}
+
+// ---- graph diff ----------------------------------------------------------------------------------
+// One previous state is enough (4-13 MB per repo — cheap): rebuild_graph snapshots the outgoing
+// graph.json as graph.prev.json and reports the structural delta inline, at the exact moment the fix
+// is being verified. graph_diff re-queries the same pair later. Raw node/edge dumps would be noise —
+// the signal is aggregated: module-dependency drift, cycle count changes, newly orphaned symbols.
+export const prevGraphPathFor = (graphPath) => String(graphPath).replace(/\.json$/, '.prev.json')
+export const edgeEndpoint = (v) => String(v && typeof v === 'object' ? v.id : v)
+export const fileOfId = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
+const folderOfFile = (file) => {
+    const dirs = String(file || '').split(/[\\/]/).filter(Boolean).slice(0, -1)
+    return dirs.length ? dirs.slice(0, 2).join('/') : '(root)'
+}
+
+// Works on anything with {nodes, links}: the raw graph.json shape and the loadGraph struct alike.
+export function diffGraphs(oldG, newG) {
+    const nodeIds = (graph) => new Set((graph.nodes || []).map((n) => String(n.id)))
+    const oldNodes = nodeIds(oldG)
+    const newNodes = nodeIds(newG)
+
+    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${edgeEndpoint(l.target)}`
+    const edgeSet = (graph) => new Set((graph.links || []).map(edgeKey))
+    const oldEdges = edgeSet(oldG)
+    const newEdges = edgeSet(newG)
+
+    const moduleEdges = (graph) => {
+        const set = new Set()
+        for (const l of graph.links || []) {
+            if (l.relation === 'contains') continue
+            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
+            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
+            if (a !== b) set.add(`${a} → ${b}`)
+        }
+        return set
+    }
+    const oldMods = moduleEdges(oldG)
+    const newMods = moduleEdges(newG)
+
+    const incoming = (graph) => {
+        const m = new Map()
+        for (const l of graph.links || []) {
+            if (l.relation === 'contains') continue
+            const t = edgeEndpoint(l.target)
+            m.set(t, (m.get(t) || 0) + 1)
+        }
+        return m
+    }
+    const oldIn = incoming(oldG)
+    const newIn = incoming(newG)
+
+    const cycles = (graph) => { try { return findSccs(buildFileImportGraph(graph).adj).length } catch { return null } }
+
+    return {
+        nodes: {
+            added: [...newNodes].filter((id) => !oldNodes.has(id)),
+            removed: [...oldNodes].filter((id) => !newNodes.has(id))
+        },
+        edges: {
+            added: [...newEdges].filter((k) => !oldEdges.has(k)).length,
+            removed: [...oldEdges].filter((k) => !newEdges.has(k)).length
+        },
+        moduleEdges: {
+            added: [...newMods].filter((k) => !oldMods.has(k)),
+            removed: [...oldMods].filter((k) => !newMods.has(k))
+        },
+        // survived the rebuild but lost every caller/importer — likely made dead by the change
+        orphaned: [...oldIn.keys()].filter((id) => newNodes.has(id) && !newIn.has(id)),
+        cycles: {before: cycles(oldG), after: cycles(newG)}
+    }
+}
+
+export function formatGraphDiff(d) {
+    if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
+        return 'No structural change between the two graph states.'
+    }
+    const cap = (list, n) => list.slice(0, n).map((x) => `  ${x}`).concat(list.length > n ? [`  … +${list.length - n} more`] : [])
+    const lines = [`Structural delta: nodes +${d.nodes.added.length}/−${d.nodes.removed.length}, edges +${d.edges.added}/−${d.edges.removed}.`]
+    if (d.cycles.before != null && d.cycles.after != null && d.cycles.before !== d.cycles.after) {
+        lines.push(`Import cycles: ${d.cycles.before} → ${d.cycles.after}${d.cycles.after < d.cycles.before ? '  (cycle broken — fix confirmed)' : '  (NEW cycle introduced — see run_audit)'}`)
+    }
+    if (d.moduleEdges.added.length) lines.push('NEW module dependencies (architecture drift — review):', ...cap(d.moduleEdges.added, 12))
+    if (d.moduleEdges.removed.length) lines.push('Removed module dependencies (decoupling confirmed):', ...cap(d.moduleEdges.removed, 12))
+    if (d.orphaned.length) lines.push('Symbols that lost their last caller/importer (now dead?):', ...cap(d.orphaned, 10))
+    if (d.nodes.added.length) lines.push('Added nodes:', ...cap(d.nodes.added, 12))
+    if (d.nodes.removed.length) lines.push('Removed nodes:', ...cap(d.nodes.removed, 12))
+    return lines.join('\n')
+}