weavatrix 0.1.3 → 0.2.0

package/src/graph/internal-builder.build.js

@@ -8,10 +8,20 @@ import { specToPkg } from "./builder/spec-pkg.js";
 import { analyzeSyntaxComplexity } from "../analysis/source-complexity.js";
 import { Parser, Query, GRAMMARS, LANGS, EXT_LANG, FAMILY, isDataFile, isDocFile, MAX_PARSE_BYTES, ensureParser, walk } from "./internal-builder.langs.js";
 import { buildResolvers } from "./internal-builder.resolvers.js";
+import { addJavaReferences } from "./internal-builder.java.js";
+import { assignDeterministicCommunities } from "./community.js";
+import { resolveJsBarrels } from "./internal-builder.barrels.js";
+import { snapshotRepository } from "./incremental-refresh.js";
 
 // Parse a repo directory into a graph-builder-compatible { nodes, links } graph.
 export async function buildInternalGraph(repoDir, opts = {}) {
-  const files = walk(repoDir);
+  const rel = (p) => relative(repoDir, p).replace(/\\/g, "/");
+  const allFiles = walk(repoDir);
+  const snapshot = snapshotRepository(repoDir, allFiles);
+  const requestedFiles = Array.isArray(opts.includeFiles)
+    ? new Set(opts.includeFiles.map((file) => String(file).replace(/\\/g, "/").replace(/^\.\//, "")))
+    : null;
+  const files = requestedFiles ? allFiles.filter((file) => requestedFiles.has(rel(file))) : allFiles;
   // Lazy grammar loading: compile only the WASMs for languages this repo actually contains.
   const wanted = new Set();
   for (const f of files) { const g = EXT_LANG[extname(f)]; if (g) wanted.add(g); }
@@ -21,13 +31,31 @@ export async function buildInternalGraph(repoDir, opts = {}) {
   const caps = (grammar, src, root) => { const query = src && q(grammar, src); return query ? query.captures(root) : []; };
   const field = (n, f) => (n && n.childForFieldName ? n.childForFieldName(f) : null);
 
-  const rel = (p) => relative(repoDir, p).replace(/\\/g, "/");
-  const fileSet = new Set(files.map(rel));
+  const fileSet = new Set(allFiles.map(rel));
   const nodes = []; const links = []; const nodeIds = new Set(); const nodeById = new Map();
   const addNode = (n) => { if (!nodeIds.has(n.id)) { nodeIds.add(n.id); nodes.push(n); nodeById.set(n.id, n); } };
   const perFileSymbols = new Map();
   const symByFileName = new Map();
   const importedLocals = new Map();
+  const jsExports = new Map();
+  if (requestedFiles && opts.baseGraph?.jsExportRecords) {
+    for (const [file, records] of Object.entries(opts.baseGraph.jsExportRecords)) {
+      if (!requestedFiles.has(file) && Array.isArray(records)) jsExports.set(file, records.map((record) => ({ ...record })));
+    }
+  }
+  if (requestedFiles && Array.isArray(opts.baseGraph?.nodes)) {
+    for (const node of opts.baseGraph.nodes) {
+      const id = String(node?.id || "");
+      const file = String(node?.source_file || (id.includes("#") ? id.slice(0, id.indexOf("#")) : id)).replace(/\\/g, "/");
+      if (!id.includes("#") || requestedFiles.has(file) || !fileSet.has(file)) continue;
+      const match = id.match(/#([A-Za-z_$][\w$]*)@\d+/);
+      if (!match) continue;
+      let names = symByFileName.get(file);
+      if (!names) symByFileName.set(file, (names = new Map()));
+      if (!names.has(match[1])) names.set(match[1], id);
+      nodeById.set(id, node);
+    }
+  }
   // Bare-package imports (axios, node:fs, @scope/x) — the graph can't resolve them to a repo file, but
   // dependency analysis NEEDS them (unused/missing deps). Additive top-level array; nodes/links untouched.
   const externalImports = [];
@@ -50,13 +78,15 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     // giant / generated / minified file → keep the file NODE but don't parse symbols (avoids a wedged parse)
     if (code.length > MAX_PARSE_BYTES) { perFileSymbols.set(fileRel, []); symByFileName.set(fileRel, new Map()); continue; }
     if ((++_parsed % 24) === 0) await new Promise((r) => setImmediate(r)); // breathe: let the UI paint between chunks
+    if (typeof opts.onParseFile === "function") opts.onParseFile(fileRel);
     const parser = new Parser(); parser.setLanguage(langs[grammar]);
     let tree; try { tree = parser.parse(code); } catch { continue; }
 
     const syms = []; const nameToId = new Map(); const moduleNameToId = new Map();
     const addSym = (name, line, callable, extra) => {
       if (!name || !/^[A-Za-z_$][\w$]*$/.test(name)) return;
-      const id = `${fileRel}#${name}@${line}`; if (nodeIds.has(id)) return;
+      const suffix = /^:[A-Za-z0-9_-]+$/.test(extra?.idSuffix || "") ? extra.idSuffix : "";
+      const id = `${fileRel}#${name}@${line}${suffix}`; if (nodeIds.has(id)) return;
       const sourceNode = extra && extra.sourceNode;
       const endLine = sourceNode?.endPosition ? sourceNode.endPosition.row + 1 : 0;
       let complexity = null;
@@ -82,8 +112,15 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       syms.push({ id, name, start: line, end: endLine >= line ? endLine : 0 });
       if (!nameToId.has(name)) nameToId.set(name, id);
       if (extra?.moduleDeclaration && !moduleNameToId.has(name)) moduleNameToId.set(name, id);
+      return id;
     };
     const imports = new Map(); importedLocals.set(fileRel, imports);
+    const recordJsExport = (record) => {
+      if (!record) return;
+      const records = jsExports.get(fileRel) || [];
+      records.push(record);
+      jsExports.set(fileRel, records);
+    };
     const addImportEdge = (tgt, meta = {}) => {
       if (!tgt || tgt === fileRel) return;
       links.push({
@@ -92,6 +129,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         relation: meta.relation || "imports",
         confidence: "EXTRACTED",
         ...(typeof meta.typeOnly === "boolean" ? { typeOnly: meta.typeOnly } : {}),
+        ...(meta.compileOnly === true ? { compileOnly: true } : {}),
         ...(meta.line ? { line: meta.line } : {}),
         ...(meta.specifier ? { specifier: meta.specifier } : {}),
       });
@@ -112,7 +150,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     // Post-hoc export flag (export {a}, export default X, CJS module.exports) — declarations are flagged at addSym time.
     const markExported = (name) => { const id = moduleNameToId.get(name); const n = id && nodeById.get(id); if (n) n.exported = true; };
 
-    try { lang.pass1({ grammar, tree, fileRel, code, caps, field, addSym, addNode, links, nodeIds, syms, nameToId, imports, addImportEdge, addExternalImport, markExported, fileSet, ...resolvers }); }
+    try { lang.pass1({ grammar, tree, fileRel, code, caps, field, addSym, addNode, links, nodeIds, syms, nameToId, imports, addImportEdge, addExternalImport, markExported, recordJsExport, fileSet, ...resolvers }); }
     catch (e) { /* one bad file never sinks the whole build */ void e; }
 
     syms.sort((a, b) => a.start - b.start);
@@ -135,6 +173,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     let dm = goDirSymbols.get(d); if (!dm) goDirSymbols.set(d, (dm = new Map()));
     for (const [n, id] of m) if (!dm.has(n)) dm.set(n, id);
   }
+  const { resolveNamespaceMember } = resolveJsBarrels({ jsExports, importedLocals, links });
   // Exact source ranges can overlap (a named function nested inside another function). Attribute a call
   // to the innermost matching symbol, not whichever outer declaration happened to be added first.
   const enclosing = (fileRel, line) => {
@@ -149,9 +188,24 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     const local = symByFileName.get(fileRel); if (local && local.has(name)) return local.get(name);
     if (sharesDirScope(fileRel)) { const d = fileRel.includes("/") ? fileRel.slice(0, fileRel.lastIndexOf("/")) : ""; const dm = goDirSymbols.get(d); if (dm && dm.has(name)) return dm.get(name); }
     const imp = importedLocals.get(fileRel) && importedLocals.get(fileRel).get(name);
-    if (imp && imp.targetFile) { const tf = symByFileName.get(imp.targetFile); if (tf && tf.has(imp.imported)) return tf.get(imp.imported); }
+    if (imp && imp.targetFile) {
+      const targetFile = imp.originFile || imp.targetFile;
+      const importedName = imp.originName || imp.imported;
+      const tf = symByFileName.get(targetFile); if (tf && tf.has(importedName)) return tf.get(importedName);
+    }
     return null;
   };
+  const javaTypeKinds = new Set(["class", "interface", "enum", "record", "annotation"]);
+  const resolveJavaType = (name, fileRel) => {
+    const imp = importedLocals.get(fileRel)?.get(name);
+    if (imp?.targetFile) {
+      const symbols = symByFileName.get(imp.targetFile);
+      const target = symbols?.get(imp.imported) || symbols?.get(name);
+      if (target && javaTypeKinds.has(nodeById.get(target)?.symbol_kind)) return target;
+    }
+    const target = symByFileName.get(fileRel)?.get(name);
+    return target && javaTypeKinds.has(nodeById.get(target)?.symbol_kind) ? target : null;
+  };
   for (const abs of files) {
     const fileRel = rel(abs); const grammar = EXT_LANG[extname(abs)]; if (!grammar) continue;
     const lang = LANGS[FAMILY[grammar]]; if (!lang || lang.isWeb || !langs[grammar]) continue;
@@ -175,14 +229,30 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       const target = dm && dm.get(fld.text);
       if (target && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED" });
     }
-    for (const heritageSrc of lang.heritage || []) for (const cap of caps(grammar, heritageSrc, tree.rootNode)) {
-      const cls = enclosing(fileRel, cap.node.startPosition.row + 1); if (!cls) continue;
-      const target = resolveCall(cap.node.text, fileRel);
-      if (target && target !== cls.id) links.push({ source: cls.id, target, relation: "inherits", confidence: "INFERRED" });
+    for (const heritageSpec of lang.heritage || []) {
+      const query = typeof heritageSpec === "string" ? heritageSpec : heritageSpec.query;
+      const relation = typeof heritageSpec === "string" ? "inherits" : (heritageSpec.relation || "inherits");
+      for (const cap of caps(grammar, query, tree.rootNode)) {
+        const cls = enclosing(fileRel, cap.node.startPosition.row + 1); if (!cls) continue;
+        const target = FAMILY[grammar] === "java" ? resolveJavaType(cap.node.text, fileRel) : resolveCall(cap.node.text, fileRel);
+        if (target && target !== cls.id) links.push({ source: cls.id, target, relation, confidence: "INFERRED" });
+      }
     }
     // JSX is a real symbol use even though it is not a call_expression. Resolve imported components to their
     // declaration so component fan-in and unused-export checks do not claim `<SettingsView />` is unreferenced.
     if (FAMILY[grammar] === "js") {
+      // Namespace calls (`ui.run()`) need the member name before an export-star facade can be resolved.
+      for (const cap of caps(grammar, `(call_expression function: (member_expression) @memberCall)`, tree.rootNode)) {
+        const object = field(cap.node, "object"), property = field(cap.node, "property");
+        if (!object || object.type !== "identifier" || !property) continue;
+        const imp = importedLocals.get(fileRel)?.get(object.text);
+        if (!imp || imp.imported !== "*" || imp.typeOnly) continue;
+        const origin = resolveNamespaceMember(fileRel, imp, property.text, "call");
+        if (origin.status !== "resolved") continue;
+        const target = symByFileName.get(origin.origin.file)?.get(origin.origin.name);
+        const caller = enclosing(fileRel, cap.node.startPosition.row + 1);
+        if (target && caller && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED" });
+      }
       for (const cap of caps(grammar, `[
         (jsx_opening_element name: (_) @jsx)
         (jsx_self_closing_element name: (_) @jsx)
@@ -193,9 +263,14 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         if (parts.length === 1 && !/^[A-Z_$]/.test(localName)) continue; // undotted lowercase tags are platform/intrinsic elements
         const imp = importedLocals.get(fileRel)?.get(localName);
         if (!imp || !imp.targetFile || imp.typeOnly) continue;
-        const targetSymbols = symByFileName.get(imp.targetFile);
+        let targetFile = imp.originFile || imp.targetFile;
+        let importedName = imp.originName || imp.imported;
+        if (imp.imported === "*" && parts.length > 1) {
+          const origin = resolveNamespaceMember(fileRel, imp, parts[parts.length - 1], "jsx");
+          if (origin.status === "resolved") { targetFile = origin.origin.file; importedName = origin.origin.name; }
+        }
+        const targetSymbols = symByFileName.get(targetFile);
         if (!targetSymbols) continue;
-        const importedName = imp.imported === "*" && parts.length > 1 ? parts[parts.length - 1] : imp.imported;
         const target = targetSymbols.get(importedName) || targetSymbols.get(localName);
         if (!target) continue;
         const owner = enclosing(fileRel, cap.node.startPosition.row + 1);
@@ -222,6 +297,9 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         const caller = enclosing(fileRel, sel.startPosition.row + 1); emitRef(caller ? caller.id : fileRel, target);
       }
     }
+    if (FAMILY[grammar] === "java") {
+      addJavaReferences({ grammar, tree, fileRel, caps, resolveJavaType, enclosing, links });
+    }
     tree.delete();
   }
 
@@ -238,17 +316,34 @@ export async function buildInternalGraph(repoDir, opts = {}) {
 
   // community = folder bucket (top 2 path parts) — deterministic, mirrors the folder-based module grouping the
   // app already uses (graph-builder-analysis.js). Populates Modules/community cards without a heavy clustering pass.
-  const folderOf = (f) => { const d = String(f || "").split("/").filter(Boolean).slice(0, -1); return d.length ? d.slice(0, 2).join("/") : "(root)"; };
-  const commOf = new Map(); let commSeq = 0;
-  for (const n of nodes) { const fo = folderOf(n.source_file); if (!commOf.has(fo)) commOf.set(fo, commSeq++); n.community = commOf.get(fo); }
+  assignDeterministicCommunities(nodes);
 
   // extImportsV: bump when the externalImports schema/coverage changes (v2 = go/python ecosystems) —
   // deps-engine rebuilds in memory when a saved graph is older than this.
-  return { nodes, links, externalImports, extImportsV: 2, edgeTypesV: 1, complexityV: 1, repoBoundaryV: 1 };
+  // edgeTypesV 2 adds language-neutral compile-only edges (currently Rust mod/use/re-export) on top
+  // of v1's TypeScript typeOnly classification.
+  return {
+    nodes,
+    links,
+    externalImports,
+    extImportsV: 2,
+    edgeTypesV: 2,
+    complexityV: 1,
+    repoBoundaryV: 1,
+    barrelResolutionV: 1,
+    extractorSchemaV: 1,
+    jsExportRecords: Object.fromEntries([...jsExports.entries()].sort(([a], [b]) => a.localeCompare(b))),
+    fileHashes: snapshot.fileHashes,
+    fileExportSignatures: snapshot.fileExportSignatures,
+    controlHashes: snapshot.controlHashes,
+    graphRevision: snapshot.revision,
+    ...(requestedFiles ? { incrementalScope: true } : {}),
+  };
 }
 
 // Build + write graph.json to outPath (creating the dir). Returns { ok, nodes, links, graphJson }.
 export async function writeInternalGraph(repoDir, outPath, opts = {}) {
+  if (Array.isArray(opts.includeFiles)) throw new Error("refusing to write a scoped incremental graph as a complete graph");
   const graph = await buildInternalGraph(repoDir, opts);
   mkdirSync(dirname(outPath), { recursive: true });
   writeFileSync(outPath, JSON.stringify(graph), "utf8");

package/src/graph/internal-builder.java.js

@@ -0,0 +1,33 @@
+// Resolve Java type usages only when they land on declarations that exist in the graph. Synthetic nodes for
+// String/List/annotations inflate metrics without adding navigation value, so unresolved/external types vanish.
+export function addJavaReferences({ grammar, tree, fileRel, caps, resolveJavaType, enclosing, links }) {
+  const refSeen = new Set();
+  const isHeritage = (node) => {
+    let current = node?.parent;
+    for (let hops = 0; current && hops < 8; hops++, current = current.parent) {
+      if (["superclass", "super_interfaces", "extends_interfaces"].includes(current.type)) return true;
+      if (["class_declaration", "interface_declaration", "enum_declaration", "record_declaration"].includes(current.type)) return false;
+    }
+    return false;
+  };
+  const emitTypeRef = (name, node) => {
+    if (!name || isHeritage(node)) return;
+    const target = resolveJavaType(name, fileRel);
+    if (!target) return;
+    const owner = enclosing(fileRel, node.startPosition.row + 1);
+    const source = owner?.id || fileRel;
+    if (source === target) return;
+    const key = `${source}>${target}`;
+    if (refSeen.has(key)) return;
+    refSeen.add(key);
+    links.push({ source, target, relation: "references", confidence: "INFERRED", usage: "type", line: node.startPosition.row + 1 });
+  };
+  for (const cap of caps(grammar, `(type_identifier) @type`, tree.rootNode)) {
+    // A qualified type is handled once by its outer scoped_type_identifier. Inner package segments could
+    // otherwise bind to unrelated same-named project types.
+    if (cap.node.parent?.type !== "scoped_type_identifier") emitTypeRef(cap.node.text, cap.node);
+  }
+  for (const cap of caps(grammar, `(scoped_type_identifier) @type`, tree.rootNode)) {
+    if (cap.node.parent?.type !== "scoped_type_identifier") emitTypeRef(cap.node.text.split(".").pop(), cap.node);
+  }
+}

package/src/graph/internal-builder.langs.js

@@ -9,6 +9,7 @@ import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { isPathInside } from "../repo-path.js";
 import { childProcessEnv } from "../child-env.js";
+import { filterWeavatrixIgnored } from "../path-ignore.js";
 import LANG_JS from "./builder/lang-js.js";
 import LANG_PY from "./builder/lang-python.js";
 import LANG_GO from "./builder/lang-go.js";
@@ -132,7 +133,7 @@ function gitFileUniverse(dir) {
 }
 
 function walk(dir) {
-  return gitFileUniverse(dir) ?? walkFallback(dir);
+  return filterWeavatrixIgnored(dir, gitFileUniverse(dir) ?? walkFallback(dir));
 }
 
 export { Parser, Query, GRAMMARS, LANGS, EXT_LANG, FAMILY, isDataFile, isDocFile, MAX_PARSE_BYTES, ensureParser, walk };

package/src/graph/internal-builder.resolvers.js

@@ -1,5 +1,6 @@
 // Per-repo resolution context shared by the language modules: JS/TS path-aliases + relative imports, Python
-// dotted/relative modules, Go package dirs, Java class files, and web hrefs / the CSS selector index.
+// dotted/relative modules, Go package dirs, Rust crate/module paths, Java class files, and web hrefs /
+// the CSS selector index.
 // (Split from internal-builder.js — see its doc comment for the overall architecture.)
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -47,6 +48,112 @@ export function buildResolvers(repoDir, fileSet) {
     return cands.find((f) => f === full || f.endsWith("/" + full)) || cands[0] || null;
   };
 
+  // Rust modules are files, but their paths are logical rather than simple source-relative imports:
+  // `foo.rs` owns children below `foo/`, while lib.rs/main.rs/mod.rs own siblings. Keep the resolver
+  // filesystem-only and crate-local: Cargo/external dependencies belong to dependency analysis, not to
+  // the internal module graph.
+  const cleanRustRel = (p) => String(p || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/").replace(/\/$/, "").replace(/^\.$/, "");
+  const rustDir = (p) => { p = cleanRustRel(p); const i = p.lastIndexOf("/"); return i < 0 ? "" : p.slice(0, i); };
+  const rustBase = (p) => { p = cleanRustRel(p); const i = p.lastIndexOf("/"); return i < 0 ? p : p.slice(i + 1); };
+  const rustJoin = (...parts) => cleanRustRel(join(...parts.filter((x) => x != null && x !== "")));
+  const rustFiles = new Set([...fileSet].filter((fr) => fr.endsWith(".rs")));
+  const rustRoots = new Map();
+  for (const fr of rustFiles) {
+    const base = rustBase(fr);
+    if (base !== "lib.rs" && base !== "main.rs") continue;
+    const dir = rustDir(fr);
+    let root = rustRoots.get(dir);
+    if (!root) rustRoots.set(dir, (root = { base: dir, lib: null, main: null }));
+    root[base === "lib.rs" ? "lib" : "main"] = fr;
+  }
+  const rustRootList = [...rustRoots.values()].sort((a, b) => b.base.length - a.base.length);
+  const rustContext = (fromRel) => {
+    fromRel = cleanRustRel(fromRel);
+    const base = rustBase(fromRel);
+    const dir = rustDir(fromRel);
+    if (base === "lib.rs" || base === "main.rs") return { base: dir, rootFile: fromRel };
+
+    // Cargo treats direct files in these conventional folders as independent crate roots. This only
+    // affects paths originating in the root file itself; nested module ownership still comes from mod/use.
+    if (/^(?:bin|examples|tests|benches)$/.test(rustBase(dir))) return { base: dir, rootFile: fromRel };
+    for (const root of rustRootList) {
+      if (!root.base || fromRel.startsWith(root.base + "/")) return { base: root.base, rootFile: root.lib || root.main };
+    }
+    return { base: dir, rootFile: fromRel };
+  };
+  const rustModuleBase = (fromRel) => {
+    const ctx = rustContext(fromRel);
+    if (ctx.rootFile === cleanRustRel(fromRel)) return rustDir(fromRel);
+    const name = rustBase(fromRel);
+    if (name === "lib.rs" || name === "main.rs" || name === "mod.rs") return rustDir(fromRel);
+    return rustJoin(rustDir(fromRel), name.replace(/\.rs$/, ""));
+  };
+  const rustInlineBase = (fromRel, inlineModules = []) => {
+    let base = rustModuleBase(fromRel);
+    for (let i = 0; i < inlineModules.length; i++) {
+      const mod = inlineModules[i] || {};
+      if (mod.path) {
+        // Rust Reference: a path attribute on the first inline module is relative to the source file's
+        // directory; nested attributes are relative to their containing module's search directory.
+        const parent = i === 0 ? rustDir(fromRel) : base;
+        base = rustJoin(parent, mod.path);
+      } else base = rustJoin(base, mod.name);
+    }
+    return base;
+  };
+  const rustModuleFile = (moduleBase, ctx) => {
+    moduleBase = cleanRustRel(moduleBase);
+    if (moduleBase === cleanRustRel(ctx.base) && ctx.rootFile && rustFiles.has(ctx.rootFile)) return ctx.rootFile;
+    const flat = moduleBase + ".rs";
+    if (rustFiles.has(flat)) return flat;
+    const legacy = rustJoin(moduleBase, "mod.rs");
+    return rustFiles.has(legacy) ? legacy : null;
+  };
+  const resolveRustMod = (fromRel, name, { inlineModules = [], explicitPath = "" } = {}) => {
+    fromRel = cleanRustRel(fromRel);
+    if (explicitPath) {
+      const parent = inlineModules.length ? rustInlineBase(fromRel, inlineModules) : rustDir(fromRel);
+      const target = rustJoin(parent, explicitPath);
+      return rustFiles.has(target) ? target : null;
+    }
+    const targetBase = rustJoin(rustInlineBase(fromRel, inlineModules), String(name || "").replace(/^r#/, ""));
+    return rustModuleFile(targetBase, rustContext(fromRel));
+  };
+  const resolveRustPath = (fromRel, rawSegments, { inlineModules = [], unqualified = true } = {}) => {
+    fromRel = cleanRustRel(fromRel);
+    const segments = (Array.isArray(rawSegments) ? rawSegments : String(rawSegments || "").split("::"))
+      .map((s) => String(s).trim().replace(/^r#/, "")).filter(Boolean);
+    if (!segments.length) return null;
+    const ctx = rustContext(fromRel);
+    const current = rustInlineBase(fromRel, inlineModules);
+    let rest = [...segments];
+    const starts = [];
+    let anchored = false;
+    if (rest[0] === "crate") { anchored = true; rest.shift(); starts.push(ctx.base); }
+    else if (rest[0] === "self") { anchored = true; rest.shift(); starts.push(current); }
+    else if (rest[0] === "super") {
+      anchored = true;
+      let base = current;
+      while (rest[0] === "super") { rest.shift(); base = rustDir(base); }
+      if (ctx.base && base !== ctx.base && !base.startsWith(ctx.base + "/")) return null;
+      starts.push(base);
+    } else if (unqualified) {
+      // Rust 2018 resolves a bare use path from the crate root/external prelude. Prefer an internal root
+      // module, then allow a lexically-local module for qualified expressions in nested modules.
+      starts.push(ctx.base);
+      if (current !== ctx.base) starts.push(current);
+    } else return null;
+
+    for (const start of starts) {
+      const min = anchored ? 0 : 1; // never reinterpret an unresolved external `serde::X` as the crate root
+      for (let used = rest.length; used >= min; used--) {
+        const target = rustModuleFile(rustJoin(start, ...rest.slice(0, used)), ctx);
+        if (target) return { targetFile: target, consumed: segments.length - rest.length + used, remaining: rest.slice(used), anchored };
+      }
+    }
+    return null;
+  };
+
   // Path aliases (tsconfig compilerOptions.paths + vite/webpack alias) are scoped to their config folder.
   // Without nearest-config resolution, a monorepo's root `@/*` can hijack the same alias in web/.
   const aliasContexts = new Map();
@@ -188,5 +295,5 @@ export function buildResolvers(repoDir, fileSet) {
     return fileSet.has(cand) ? cand : null;
   };
 
-  return { resolveJsImport, resolveAlias, resolvePyPath, pyBaseDir, pyTopDirs, resolveGoImport, dirFiles, resolveJavaImport, resolveHref, selectorIndex, htmlUsages, goModule, goRequires };
+  return { resolveJsImport, resolveAlias, resolvePyPath, pyBaseDir, pyTopDirs, resolveGoImport, dirFiles, resolveRustMod, resolveRustPath, resolveJavaImport, resolveHref, selectorIndex, htmlUsages, goModule, goRequires };
 }

package/src/graph/layout.js

@@ -2,9 +2,11 @@
 // pure filter/analysis helpers so callers get everything from one import:
 //   graph-filter.js   — pure graph filters (test-mode, path-scope)
 //   graph-analysis.js — parse graph.json → file/module/symbol view, hotspots, communities
-import { readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { repoBaseName } from "../scan/discover.js";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import process from "node:process";
+import { readdirSync, realpathSync } from "node:fs";
 
 export * from "./graph-filter.js";
 export * from "../analysis/graph-analysis.js";
@@ -12,14 +14,28 @@ export * from "../analysis/graph-analysis.js";
 // Graphs live in a `weavatrix-graphs/` folder NEXT to the repo (inside the repo's parent folder),
 // never inside the repo itself — the graph is derived data, not source. One folder per repo holds
 // graph.json plus graph.prev.json (saved by rebuild_graph for graph_diff).
+export function graphHomeDir() {
+  return resolve(process.env.WEAVATRIX_GRAPH_HOME || join(homedir(), ".weavatrix", "graphs"));
+}
+
+export function graphStorageKey(repoPath) {
+  let absolute;
+  try { absolute = realpathSync.native(repoPath); }
+  catch { absolute = resolve(repoPath); }
+  const normalized = process.platform === "win32" ? absolute.toLowerCase() : absolute;
+  const slug = (basename(absolute) || "repo").replace(/[^A-Za-z0-9_.-]/g, "_");
+  const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+  return `${slug}-${digest}`;
+}
+
 export function graphOutDirForRepo(repoPath) {
-  return join(dirname(repoPath), "weavatrix-graphs", repoBaseName(repoPath));
+  return join(graphHomeDir(), graphStorageKey(repoPath));
 }
 
 // A separate dir for a single module's scoped graph, so it never clobbers the repo's graph.
 export function graphOutDirForModule(repoPath, moduleName) {
   const safe = String(moduleName).replace(/[^A-Za-z0-9_.-]/g, "_");
-  return join(dirname(repoPath), "weavatrix-graphs", repoBaseName(repoPath), "modules", safe);
+  return join(graphOutDirForRepo(repoPath), "modules", safe);
 }
 
 // Top-level source folders of a repo (for path-scoped builds).

package/src/graph/relations.js

@@ -0,0 +1,4 @@
+// Ownership/nesting edges are useful for navigation, but are not evidence of code usage.
+const STRUCTURAL_RELATIONS = new Set(["contains", "method"]);
+
+export const isStructuralRelation = (relation) => STRUCTURAL_RELATIONS.has(String(relation || ""));

package/src/graph/repo-registry.js

@@ -0,0 +1,124 @@
+// Global local registry for repository graphs. Absolute paths never leave the machine; hosted sync
+// uses the opaque UUID. Identity is anchored in each canonical graph folder so simultaneous MCP
+// processes cannot mint different IDs for the same repository.
+import {randomUUID} from 'node:crypto'
+import {existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync} from 'node:fs'
+import {basename, join, relative, resolve} from 'node:path'
+import process from 'node:process'
+import {graphStorageKey} from './layout.js'
+import {atomicWriteFileSync, withFileLockSync} from './file-lock.js'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const MARKER = '.repository-id'
+
+const normalized = (value) => {
+    const path = String(value || '').replace(/\\/g, '/').replace(/\/+$/, '')
+    return process.platform === 'win32' ? path.toLowerCase() : path
+}
+
+const realOrResolved = (value) => {
+    try { return realpathSync.native(value) } catch { return resolve(value) }
+}
+
+const canonicalGraphDir = (repoPath, graphHome) => join(resolve(graphHome), graphStorageKey(repoPath))
+const markerPath = (graphDir) => join(graphDir, MARKER)
+
+export function registryPath(graphHome) { return join(graphHome, 'repositories.json') }
+
+export function readRepositoryRegistry(graphHome) {
+    try {
+        const parsed = JSON.parse(readFileSync(registryPath(graphHome), 'utf8'))
+        return parsed?.repositoryRegistryV === 1 && Array.isArray(parsed.repositories)
+            ? parsed.repositories.filter((item) => item && typeof item === 'object')
+            : []
+    } catch { return [] }
+}
+
+function writeRegistry(graphHome, repositories) {
+    atomicWriteFileSync(registryPath(graphHome), JSON.stringify({repositoryRegistryV: 1, repositories}, null, 2), 'utf8')
+}
+
+function readMarker(graphDir) {
+    try {
+        const id = readFileSync(markerPath(graphDir), 'utf8').trim()
+        return UUID.test(id) ? id : null
+    } catch { return null }
+}
+
+function createOrReadMarker(graphDir, preferredId) {
+    mkdirSync(graphDir, {recursive: true})
+    const path = markerPath(graphDir)
+    const existing = readMarker(graphDir)
+    if (existing) return existing
+    if (existsSync(path)) throw new Error(`invalid repository identity marker: ${path}`)
+    const candidate = UUID.test(String(preferredId || '')) ? preferredId : randomUUID()
+    try { writeFileSync(path, `${candidate}\n`, {encoding: 'utf8', flag: 'wx'}) }
+    catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        const raced = readMarker(graphDir)
+        if (!raced) throw new Error(`invalid repository identity marker after concurrent registration: ${path}`)
+        return raced
+    }
+    return candidate
+}
+
+export function registerRepository({repoPath, graphDir, graphHome}) {
+    mkdirSync(graphHome, {recursive: true})
+    const real = realOrResolved(repoPath)
+    const canonical = canonicalGraphDir(real, graphHome)
+    if (normalized(realOrResolved(graphDir)) !== normalized(realOrResolved(canonical))) {
+        throw new Error(`repository graphs must be registered from the canonical graph directory: ${canonical}`)
+    }
+    return withFileLockSync(join(graphHome, '.repositories.lock'), () => {
+        const key = normalized(real)
+        const repositories = readRepositoryRegistry(graphHome)
+        let record = repositories.find((item) => normalized(item.repoPath) === key)
+        const now = new Date().toISOString()
+        const repositoryId = createOrReadMarker(canonical, record?.repositoryId)
+        if (!record) {
+            record = {repositoryId, repoPath: real, label: basename(real) || 'repo', graphDir: canonical, firstSeenAt: now, lastSeenAt: now}
+            repositories.push(record)
+        } else {
+            record.repositoryId = repositoryId
+            record.repoPath = real
+            record.graphDir = canonical
+            record.label = basename(real) || record.label || 'repo'
+            record.lastSeenAt = now
+        }
+        const deduped = repositories.filter((item, index, all) =>
+            normalized(item.repoPath) !== key || all.findIndex((candidate) => normalized(candidate.repoPath) === key) === index)
+        deduped.sort((a, b) => String(a.label).localeCompare(String(b.label)) || String(a.repositoryId).localeCompare(String(b.repositoryId)))
+        writeRegistry(graphHome, deduped)
+        return {...record}
+    })
+}
+
+export function repositoryRecord(repoPath, graphHome) {
+    const real = realOrResolved(repoPath)
+    const key = normalized(real)
+    return liveRepositoryRecords(graphHome).find((item) => normalized(item.repoPath) === key) || null
+}
+
+function validLiveRecord(item, graphHome) {
+    if (!UUID.test(String(item?.repositoryId || '')) || typeof item?.repoPath !== 'string' || typeof item?.graphDir !== 'string') return null
+    let repoReal
+    let graphHomeReal
+    let graphReal
+    try {
+        repoReal = realpathSync.native(item.repoPath)
+        graphHomeReal = realpathSync.native(graphHome)
+        graphReal = realpathSync.native(item.graphDir)
+        if (!statSync(repoReal).isDirectory() || !existsSync(join(repoReal, '.git'))) return null
+        if (!statSync(graphReal).isDirectory() || !statSync(join(graphReal, 'graph.json')).isFile()) return null
+    } catch { return null }
+    if (normalized(graphReal) !== normalized(realOrResolved(canonicalGraphDir(repoReal, graphHomeReal)))) return null
+    const rel = relative(graphHomeReal, graphReal)
+    if (!rel || rel.startsWith('..') || resolve(graphHomeReal, rel) !== resolve(graphReal)) return null
+    if (readMarker(graphReal) !== item.repositoryId) return null
+    return {...item, repoPath: repoReal, graphDir: graphReal}
+}
+
+export function liveRepositoryRecords(graphHome) {
+    if (!existsSync(graphHome)) return []
+    return readRepositoryRegistry(graphHome).map((item) => validLiveRecord(item, graphHome)).filter(Boolean)
+}