weavatrix 0.1.3 → 0.2.0

package/src/graph/freshness-probe.js

@@ -0,0 +1,141 @@
+// Fast repository freshness probe. Full graph snapshots hash every source file and are still the
+// authority when something changed; this exact Git/worktree token is safe to cache in-process and in
+// versioned graph metadata when HEAD + dirty/untracked/control-file content remain unchanged.
+import {createHash} from 'node:crypto'
+import {spawnSync} from 'node:child_process'
+import {readFileSync, statSync} from 'node:fs'
+import {createRequire} from 'node:module'
+import {childProcessEnv} from '../child-env.js'
+import {createRepoBoundary} from '../repo-path.js'
+
+export const REPOSITORY_FRESHNESS_PROBE_V = 1
+export const GRAPH_BUILDER_SCHEMA_V = 1
+export const GRAPH_BUILDER_VERSION = (() => {
+    try { return String(createRequire(import.meta.url)('../../package.json').version) }
+    catch { return '0.0.0' }
+})()
+
+// These are the graph capabilities whose meaning is owned by the current builder. The package
+// version invalidates stamps across releases; the explicit schema requirements also fail closed when
+// a saved graph is hand-edited or a development build bumps a structural schema without a version bump.
+const CURRENT_GRAPH_SCHEMA = Object.freeze({
+    extImportsV: 2,
+    edgeTypesV: 2,
+    complexityV: 1,
+    repoBoundaryV: 1,
+    barrelResolutionV: 1,
+    extractorSchemaV: 1,
+})
+const CONTROL_FILES = ['.gitignore', '.weavatrixignore', '.weavatrix.json']
+const MAX_CONTROL_BYTES = 1_000_000
+
+function git(repoRoot, args) {
+    const result = spawnSync('git', ['-C', repoRoot, ...args], {
+        encoding: 'buffer', timeout: 8000, windowsHide: true, env: childProcessEnv(), maxBuffer: 16 * 1024 * 1024,
+    })
+    return result.status === 0 ? Buffer.from(result.stdout || '') : null
+}
+
+function statusPaths(status) {
+    const records = status.toString('utf8').split('\0').filter(Boolean)
+    const paths = []
+    for (let index = 0; index < records.length; index++) {
+        const record = records[index]
+        if (record.length < 4) continue
+        paths.push(record.slice(3))
+        // In porcelain -z, rename/copy destinations are followed by the original path as a bare item.
+        if (/^[RC]/.test(record) || /^[RC]/.test(record.slice(1, 2))) {
+            if (records[index + 1]) paths.push(records[++index])
+        }
+    }
+    return [...new Set(paths)]
+}
+
+export function repositoryFreshnessProbe(repoRoot) {
+    const head = git(repoRoot, ['rev-parse', '--verify', 'HEAD'])
+    const status = git(repoRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignored=no'])
+    if (!head || !status) return null
+    const digest = createHash('sha256').update(head).update(status)
+    const boundary = createRepoBoundary(repoRoot)
+    for (const rel of statusPaths(status).sort()) {
+        digest.update(rel)
+        const resolved = boundary.resolve(rel)
+        if (!resolved.ok) { digest.update(`!${resolved.reason}`); continue }
+        try {
+            const stats = statSync(resolved.path)
+            if (!stats.isFile()) { digest.update('!not-file'); continue }
+            // Dirty sets are normally tiny. Hashing their content makes same-size rapid edits exact while
+            // still avoiding reads of every clean file in the repository.
+            digest.update(readFileSync(resolved.path))
+        } catch { digest.update('!unreadable') }
+    }
+    // Control files can intentionally be gitignored. Always include their bounded contents so a
+    // matching Git status can never hide a changed graph universe/classification policy.
+    for (const rel of CONTROL_FILES) {
+        digest.update(`control:${rel}\0`)
+        const resolved = boundary.resolve(rel)
+        if (!resolved.ok) { digest.update(`!${resolved.reason}`); continue }
+        try {
+            const stats = statSync(resolved.path)
+            if (!stats.isFile()) { digest.update('!not-file'); continue }
+            if (stats.size > MAX_CONTROL_BYTES) { digest.update('!oversized'); continue }
+            digest.update(readFileSync(resolved.path))
+        } catch { digest.update('!unreadable') }
+    }
+    return digest.digest('hex')
+}
+
+const isHash = (value) => /^[a-f0-9]{64}$/.test(String(value || ''))
+
+export function graphSchemaIsCurrent(graph) {
+    return Boolean(graph) && Object.entries(CURRENT_GRAPH_SCHEMA)
+        .every(([key, expected]) => Number(graph[key]) === expected)
+}
+
+// Returns true only when a graph stamp was produced by this exact builder contract for the active
+// complete build mode. Legacy, scoped, non-Git, malformed and schema-old graphs all fall through to
+// the authoritative repository snapshot path.
+export function persistedFreshnessMatches(graph, probe, mode = graph?.graphBuildMode || 'full') {
+    if (!graph || !isHash(probe) || !graphSchemaIsCurrent(graph)) return false
+    if (Number(graph.repositoryFreshnessProbeV) !== REPOSITORY_FRESHNESS_PROBE_V) return false
+    if (Number(graph.repositoryFreshnessBuilderSchemaV) !== GRAPH_BUILDER_SCHEMA_V) return false
+    if (String(graph.repositoryFreshnessBuilderVersion || '') !== GRAPH_BUILDER_VERSION) return false
+    if (String(graph.repositoryFreshnessProbe || '') !== probe) return false
+    if (String(graph.repositoryFreshnessMode || '') !== String(mode || 'full')) return false
+    if (String(graph.graphBuildMode || '') !== String(mode || 'full')) return false
+    if (String(graph.graphBuildScope || '') !== '') return false
+    return true
+}
+
+// Mutates the graph metadata and reports whether serialization is required. A null probe deliberately
+// removes an older stamp: non-Git repos and repositories that changed while parsing must never inherit
+// a stale fast-path token.
+export function stampRepositoryFreshness(graph, probe, mode = graph?.graphBuildMode || 'full') {
+    if (!graph || typeof graph !== 'object') return false
+    const next = isHash(probe) && graphSchemaIsCurrent(graph) && !graph.graphBuildScope
+        ? {
+            repositoryFreshnessProbeV: REPOSITORY_FRESHNESS_PROBE_V,
+            repositoryFreshnessBuilderSchemaV: GRAPH_BUILDER_SCHEMA_V,
+            repositoryFreshnessBuilderVersion: GRAPH_BUILDER_VERSION,
+            repositoryFreshnessProbe: probe,
+            repositoryFreshnessMode: String(mode || 'full'),
+        }
+        : null
+    const keys = [
+        'repositoryFreshnessProbeV',
+        'repositoryFreshnessBuilderSchemaV',
+        'repositoryFreshnessBuilderVersion',
+        'repositoryFreshnessProbe',
+        'repositoryFreshnessMode',
+    ]
+    let changed = false
+    for (const key of keys) {
+        if (next && Object.hasOwn(next, key)) {
+            if (graph[key] !== next[key]) { graph[key] = next[key]; changed = true }
+        } else if (Object.hasOwn(graph, key)) {
+            delete graph[key]
+            changed = true
+        }
+    }
+    return changed
+}

package/src/graph/graph-filter.js

@@ -1,44 +1,61 @@
-// Pure graph filters applied to a built graph.json (no I/O). graph-builder itself has no test/scope
-// filter, so we post-process the graph object: drop test nodes, keep only a subpath, etc.
+// Graph filters applied to a built graph.json. Test semantics come from the shared repository path
+// classifier, so no-tests agrees with duplicate/audit/coverage tools (including repo config).
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
 
 export function isTestPath(path) {
-  return /(^|[\\/])(__tests?__|tests?)([\\/]|$)|\.(test|itest|spec|e2e)\.|_test\.go$|(^|[\\/])test_[^\\/]*\.py$/i.test(String(path || ""));
+  return hasPathClass(createPathClassifier(null).explain(path), "test", "e2e");
+}
+
+const normalizedPath = (value) => String(value || "").replace(/\\/g, "/");
+
+function externalImportsForNodes(graph, nodes) {
+  if (!Array.isArray(graph.externalImports)) return undefined;
+  const files = new Set(nodes.map((node) => normalizedPath(node.source_file)).filter(Boolean));
+  return graph.externalImports.filter((item) => files.has(normalizedPath(item?.file)));
 }
 
 // Filter a built graph.json by test-mode: drop test nodes ("no-tests") or keep only tests + the
 // nodes they depend on ("tests-only"). graph-builder update has no test filter, so we do it post-build.
-export function filterGraphForMode(graph, mode) {
+export function filterGraphForMode(graph, mode, { repoRoot = null } = {}) {
   if (mode !== "no-tests" && mode !== "tests-only") return graph;
   const nodes = graph.nodes || [];
   const links = graph.links || [];
   const endpoint = (value) => (value && typeof value === "object" ? value.id : value);
+  const classifier = createPathClassifier(repoRoot);
+  const isTest = (path) => hasPathClass(classifier.explain(path), "test", "e2e");
   let keep;
   if (mode === "no-tests") {
-    keep = new Set(nodes.filter((node) => !isTestPath(node.source_file)).map((node) => node.id));
+    keep = new Set(nodes.filter((node) => !isTest(node.source_file)).map((node) => node.id));
   } else {
-    const testIds = new Set(nodes.filter((node) => isTestPath(node.source_file)).map((node) => node.id));
+    const testIds = new Set(nodes.filter((node) => isTest(node.source_file)).map((node) => node.id));
     keep = new Set(testIds);
     for (const link of links) {
       if (testIds.has(endpoint(link.source))) keep.add(endpoint(link.target)); // a test's dependency
     }
   }
+  const keptNodes = nodes.filter((node) => keep.has(node.id));
+  const externalImports = externalImportsForNodes(graph, keptNodes);
   return {
     ...graph,
-    nodes: nodes.filter((node) => keep.has(node.id)),
-    links: links.filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target)))
+    nodes: keptNodes,
+    links: links.filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target))),
+    ...(externalImports ? { externalImports } : {})
   };
 }
 
 // Keep only nodes under a subpath (path-scope), drop links touching removed nodes.
 export function filterGraphByScope(graph, scope) {
   if (!scope) return graph;
-  const norm = (p) => String(p || "").replace(/\\/g, "/");
+  const norm = normalizedPath;
   const prefix = norm(scope).replace(/\/+$/, "") + "/";
   const endpoint = (value) => (value && typeof value === "object" ? value.id : value);
   const keep = new Set((graph.nodes || []).filter((node) => (norm(node.source_file) + "/").startsWith(prefix)).map((node) => node.id));
+  const keptNodes = (graph.nodes || []).filter((node) => keep.has(node.id));
+  const externalImports = externalImportsForNodes(graph, keptNodes);
   return {
     ...graph,
-    nodes: (graph.nodes || []).filter((node) => keep.has(node.id)),
-    links: (graph.links || []).filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target)))
+    nodes: keptNodes,
+    links: (graph.links || []).filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target))),
+    ...(externalImports ? { externalImports } : {})
   };
 }

package/src/graph/incremental-refresh.js

@@ -0,0 +1,232 @@
+// Conservative incremental graph refresh. This module never writes graph.json: it either returns the
+// untouched complete graph, a fully rebuilt graph, or a complete merge of a bounded scoped parse into
+// the previous graph. Callers own serialization/locking.
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { extname, relative } from "node:path";
+import { walk } from "./internal-builder.langs.js";
+import { createRepoBoundary } from "../repo-path.js";
+import { assignDeterministicCommunities } from "./community.js";
+
+const JS_EXT = new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"]);
+const CONFIG_RISK = /(^|\/)(package(?:-lock)?\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|tsconfig(?:\.[^/]*)?\.json|jsconfig(?:\.[^/]*)?\.json|go\.(?:mod|sum)|Cargo\.(?:toml|lock)|pom\.xml|build\.gradle(?:\.kts)?|vite\.config\.[^/]+|webpack\.config\.[^/]+|babel\.config\.[^/]+)$/i;
+const CONTROL_FILES = [".gitignore", ".weavatrixignore", ".weavatrix.json"];
+const MAX_CONTROL_BYTES = 1_000_000;
+
+const norm = (value) => String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const endpoint = (value) => String(value && typeof value === "object" ? value.id : value);
+const fileOfEndpoint = (value, nodesById) => {
+  const id = endpoint(value);
+  const source = nodesById.get(id)?.source_file;
+  if (source) return norm(source);
+  const marker = id.indexOf("#");
+  return norm(marker < 0 ? id : id.slice(0, marker));
+};
+
+// We only need to know whether a module's public surface changed, not understand its implementation.
+// The full tree-sitter pass remains authoritative; this signature is deliberately conservative and
+// whitespace-insensitive. Any changed export statement forces a full rebuild.
+export function jsExportSignature(text, file = "") {
+  if (!JS_EXT.has(extname(file))) return "";
+  const source = String(text || "");
+  const exports = [];
+  const pattern = /\bexport\s+(?:declare\s+)?(?:type\s+)?(?:\*\s+(?:as\s+[A-Za-z_$][\w$]*\s+)?from\s*["'][^"']+["']|\{[\s\S]*?\}(?:\s+from\s*["'][^"']+["'])?|default\s+(?:(?:async\s+)?function\s*\*?|class)?\s*[A-Za-z_$]?[\w$]*|(?:async\s+)?function\s*\*?\s+[A-Za-z_$][\w$]*|class\s+[A-Za-z_$][\w$]*|(?:const|let|var|interface|type|enum)\s+[A-Za-z_$][\w$]*)/g;
+  for (const match of source.matchAll(pattern)) exports.push(match[0].replace(/\s+/g, " ").trim());
+  // The general matcher intentionally stops before implementation bodies. Preserve every binding name
+  // in multi-declarator exports (`export const a = 1, b = 2`) so adding/removing one cannot slip through.
+  for (const match of source.matchAll(/\bexport\s+(?:declare\s+)?(?:const|let|var)\s+([^;\n]+)/g)) {
+    const names = [];
+    for (const part of match[1].split(",")) {
+      const declared = part.trim().match(/^([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=/);
+      if (declared) names.push(declared[1]);
+    }
+    exports.push(`bindings:${names.join(",")}`);
+  }
+  return hash(exports.join("\n"));
+}
+
+export function snapshotRepository(repoDir, files = walk(repoDir)) {
+  const root = String(repoDir);
+  const fileHashes = {};
+  const fileExportSignatures = {};
+  const relativeFiles = [];
+  for (const abs of files) {
+    const rel = norm(relative(root, abs));
+    let body;
+    try { body = readFileSync(abs); } catch { continue; }
+    relativeFiles.push(rel);
+    fileHashes[rel] = hash(body);
+    if (JS_EXT.has(extname(rel))) fileExportSignatures[rel] = jsExportSignature(body.toString("utf8"), rel);
+  }
+  relativeFiles.sort();
+  const controlHashes = {};
+  const boundary = createRepoBoundary(root);
+  for (const rel of CONTROL_FILES) {
+    const resolved = boundary.resolve(rel);
+    if (!resolved.ok) {
+      controlHashes[rel] = resolved.reason === "not-found" ? null : `UNREADABLE:${resolved.reason}`;
+      continue;
+    }
+    try {
+      const stats = statSync(resolved.path);
+      controlHashes[rel] = stats.isFile() && stats.size <= MAX_CONTROL_BYTES
+        ? hash(readFileSync(resolved.path))
+        : stats.isFile() ? "UNREADABLE:oversized" : "UNREADABLE:not-file";
+    } catch {
+      controlHashes[rel] = "UNREADABLE:unreadable";
+    }
+  }
+  const revision = hash([
+    ...relativeFiles.map((file) => `${file}:${fileHashes[file]}`),
+    ...Object.keys(controlHashes).sort().map((file) => `${file}:${controlHashes[file] ?? "missing"}`),
+  ].join("\n"));
+  return { files, relativeFiles, fileHashes, fileExportSignatures, controlHashes, revision };
+}
+
+function sameRecord(left, right) {
+  const a = left && typeof left === "object" ? left : {};
+  const b = right && typeof right === "object" ? right : {};
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) if (a[key] !== b[key]) return false;
+  return true;
+}
+
+function changedPaths(previous, current) {
+  const keys = new Set([...Object.keys(previous || {}), ...Object.keys(current || {})]);
+  return [...keys].filter((file) => previous?.[file] !== current?.[file]).sort();
+}
+
+function isBarrelFile(graph, file) {
+  const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
+  return (graph.links || []).some((link) => {
+    const sourceFile = fileOfEndpoint(link.source, nodesById);
+    return sourceFile === file && (link.relation === "re_exports" || link.barrelProxy === true);
+  });
+}
+
+function reverseImporters(graph, changed) {
+  const changedSet = new Set(changed);
+  const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
+  const result = new Set();
+  for (const link of graph.links || []) {
+    const targetFile = fileOfEndpoint(link.target, nodesById);
+    if (!changedSet.has(targetFile)) continue;
+    const sourceFile = fileOfEndpoint(link.source, nodesById);
+    if (sourceFile && sourceFile !== targetFile) result.add(sourceFile);
+  }
+  return result;
+}
+
+function mergeScopedGraph(base, scoped, affected, snapshot) {
+  const affectedSet = new Set(affected);
+  const baseNodes = Array.isArray(base.nodes) ? base.nodes : [];
+  const scopedNodes = Array.isArray(scoped.nodes) ? scoped.nodes : [];
+  const baseNodesById = new Map(baseNodes.map((node) => [String(node.id), node]));
+  const nodeFile = (node) => norm(node?.source_file || fileOfEndpoint(node?.id, baseNodesById));
+  const nodes = [...baseNodes.filter((node) => !affectedSet.has(nodeFile(node))), ...scopedNodes];
+  assignDeterministicCommunities(nodes);
+  const nodesById = new Map(nodes.map((node) => [String(node.id), node]));
+  if (nodesById.size !== nodes.length) throw new Error("incremental merge produced duplicate node ids");
+
+  const baseLinkKept = (link) => {
+    const sourceFile = fileOfEndpoint(link.source, baseNodesById);
+    // A scoped rebuild owns every outgoing edge of an affected source. Incoming edges from an
+    // unaffected source still describe that source and must survive (A -> B -> changed C reparses
+    // B+C, but A -> B is not regenerated by the scoped builder). The node-id filter below safely
+    // removes an incoming edge when its affected target symbol no longer exists.
+    return !affectedSet.has(sourceFile);
+  };
+  // Base and scoped links are disjoint by source file: every scoped source was removed above. Keep
+  // repeated call/reference occurrences intact because occurrence hotspots intentionally use them.
+  const links = [...(base.links || []).filter(baseLinkKept), ...(scoped.links || [])]
+    .filter((link) => nodesById.has(endpoint(link.source)) && nodesById.has(endpoint(link.target)));
+
+  const externalImports = [
+    ...(base.externalImports || []).filter((record) => !affectedSet.has(norm(record?.file))),
+    ...(scoped.externalImports || []),
+  ];
+  const fileNodes = new Set(nodes.filter((node) => !String(node.id).includes("#")).map((node) => norm(node.source_file || node.id)));
+  if (fileNodes.size !== snapshot.relativeFiles.length || snapshot.relativeFiles.some((file) => !fileNodes.has(file))) {
+    throw new Error("incremental merge did not preserve the complete file universe");
+  }
+
+  const merged = {
+    ...base,
+    nodes,
+    links,
+    externalImports,
+    jsExportRecords: scoped.jsExportRecords || base.jsExportRecords || {},
+    fileHashes: snapshot.fileHashes,
+    fileExportSignatures: snapshot.fileExportSignatures,
+    controlHashes: snapshot.controlHashes,
+    graphRevision: snapshot.revision,
+  };
+  for (const key of ["extImportsV", "edgeTypesV", "complexityV", "repoBoundaryV", "barrelResolutionV", "extractorSchemaV"]) {
+    merged[key] = Math.max(Number(base[key]) || 0, Number(scoped[key]) || 0);
+  }
+  return merged;
+}
+
+export async function refreshGraphIncrementally(repoDir, existingGraph, {
+  buildGraph,
+  maxChangedFiles = 24,
+  maxParsedFiles = 80,
+  builderOptions = {},
+} = {}) {
+  const builder = buildGraph || (await import("./internal-builder.js")).buildInternalGraph;
+  const snapshot = snapshotRepository(repoDir);
+  const full = async (reason, changedFiles = []) => {
+    const graph = await builder(repoDir, builderOptions);
+    return { graph, kind: "full", changedFiles, reason, revision: graph.graphRevision || snapshot.revision, parsedFiles: snapshot.relativeFiles };
+  };
+
+  if (!existingGraph || !existingGraph.fileHashes || !existingGraph.fileExportSignatures
+    || !existingGraph.controlHashes || !existingGraph.jsExportRecords || Number(existingGraph.barrelResolutionV) < 1
+    || Number(existingGraph.extractorSchemaV) < 1) {
+    return full("incremental-baseline-unavailable");
+  }
+  if (!sameRecord(existingGraph.controlHashes, snapshot.controlHashes)) return full("ignore-or-control-config-changed");
+
+  const oldFiles = Object.keys(existingGraph.fileHashes).sort();
+  if (oldFiles.length !== snapshot.relativeFiles.length || oldFiles.some((file, index) => file !== snapshot.relativeFiles[index])) {
+    const changedFiles = changedPaths(existingGraph.fileHashes, snapshot.fileHashes);
+    return full("file-universe-changed", changedFiles);
+  }
+  const changedFiles = changedPaths(existingGraph.fileHashes, snapshot.fileHashes);
+  if (!changedFiles.length) {
+    return { graph: existingGraph, kind: "none", changedFiles: [], reason: "content-unchanged", revision: snapshot.revision, parsedFiles: [] };
+  }
+  if (changedFiles.length > maxChangedFiles) return full("changed-set-too-large", changedFiles);
+  if (changedFiles.some((file) => CONFIG_RISK.test(file))) return full("config-manifest-or-alias-changed", changedFiles);
+  if (changedFiles.some((file) => !JS_EXT.has(extname(file)))) return full("language-requires-full-context", changedFiles);
+  for (const file of changedFiles) {
+    if (isBarrelFile(existingGraph, file)) return full(`barrel-file-changed:${file}`, changedFiles);
+    if (existingGraph.fileExportSignatures[file] !== snapshot.fileExportSignatures[file]) {
+      return full(`export-surface-changed:${file}`, changedFiles);
+    }
+  }
+
+  const importers = reverseImporters(existingGraph, changedFiles);
+  const affected = [...new Set([...changedFiles, ...importers])].filter((file) => snapshot.fileHashes[file]).sort();
+  if (affected.length > maxParsedFiles) return full("reverse-importer-set-too-large", changedFiles);
+  try {
+    const scoped = await builder(repoDir, {
+      ...builderOptions,
+      includeFiles: affected,
+      baseGraph: existingGraph,
+    });
+    if (scoped.incrementalScope !== true) return full("builder-did-not-honor-incremental-scope", changedFiles);
+    const graph = mergeScopedGraph(existingGraph, scoped, affected, snapshot);
+    return {
+      graph,
+      kind: "incremental",
+      changedFiles,
+      reason: importers.size ? "changed-files-and-reverse-importers" : "changed-files-only",
+      revision: snapshot.revision,
+      parsedFiles: affected,
+    };
+  } catch {
+    return full("incremental-merge-safety-fallback", changedFiles);
+  }
+}

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

@@ -0,0 +1,169 @@
+// TypeScript/JavaScript barrel transparency. The parser keeps physical import/re-export edges for
+// execution-order and cycle analysis; this post-pass resolves public export names to their declaring
+// files, marks the physical facade hops as proxies, and adds direct semantic importer -> origin edges.
+// Resolution follows ESM rules that matter for a static graph: explicit exports shadow `export *`,
+// `default` never flows through a star, cycles terminate, and conflicting star origins stay ambiguous.
+
+const resolved = (file, name, typeOnly = false) => ({ status: "resolved", origin: { file, name, typeOnly } });
+const MISSING = Object.freeze({ status: "missing" });
+const AMBIGUOUS = Object.freeze({ status: "ambiguous" });
+
+function mergeCandidates(candidates) {
+  if (candidates.some((candidate) => candidate.status === "ambiguous")) return AMBIGUOUS;
+  const origins = new Map();
+  for (const candidate of candidates) {
+    if (candidate.status !== "resolved") continue;
+    const key = `${candidate.origin.file}\0${candidate.origin.name}`;
+    const current = origins.get(key);
+    if (!current) origins.set(key, { ...candidate.origin });
+    else current.typeOnly = current.typeOnly && candidate.origin.typeOnly;
+  }
+  if (!origins.size) return MISSING;
+  if (origins.size > 1) return AMBIGUOUS;
+  return { status: "resolved", origin: [...origins.values()][0] };
+}
+
+function withTypeOnly(result, typeOnly) {
+  if (result.status !== "resolved" || !typeOnly) return result;
+  return resolved(result.origin.file, result.origin.name, true);
+}
+
+export function resolveJsBarrels({ jsExports, importedLocals, links }) {
+  const tables = new Map();
+  for (const [file, records] of jsExports) {
+    const table = { explicit: new Map(), stars: [] };
+    for (const record of records || []) {
+      if (record.kind === "star") {
+        table.stars.push(record);
+        continue;
+      }
+      if (!record.exported) continue;
+      const list = table.explicit.get(record.exported) || [];
+      list.push(record);
+      table.explicit.set(record.exported, list);
+    }
+    tables.set(file, table);
+  }
+
+  const cache = new Map();
+  const resolveExport = (file, name, trail = new Set()) => {
+    const key = `${file}\0${name}`;
+    const rootResolution = trail.size === 0;
+    if (cache.has(key)) return cache.get(key);
+    if (trail.has(key)) return MISSING;
+    const table = tables.get(file);
+    if (!table) return MISSING;
+    const nextTrail = new Set(trail);
+    nextTrail.add(key);
+
+    const explicit = table.explicit.get(name) || [];
+    if (explicit.length) {
+      const candidates = explicit.map((record) => {
+        if (record.kind === "named") {
+          return withTypeOnly(resolveExport(record.targetFile, record.imported, nextTrail), record.typeOnly);
+        }
+        if (record.kind === "namespace") return resolved(record.targetFile, "*", record.typeOnly);
+        const local = record.local || name;
+        const binding = importedLocals.get(file)?.get(local);
+        if (binding?.targetFile && binding.imported && binding.imported !== "*") {
+          return withTypeOnly(resolveExport(binding.targetFile, binding.imported, nextTrail), record.typeOnly || binding.typeOnly);
+        }
+        // Type/interface declarations are intentionally not symbol nodes yet, but their declaring file is
+        // still the correct semantic origin for file/module dependency analysis.
+        return resolved(file, local, record.typeOnly);
+      });
+      const result = mergeCandidates(candidates);
+      if (rootResolution) cache.set(key, result);
+      return result;
+    }
+
+    if (name === "default") {
+      if (rootResolution) cache.set(key, MISSING);
+      return MISSING;
+    }
+    const candidates = table.stars.map((star) => withTypeOnly(resolveExport(star.targetFile, name, nextTrail), star.typeOnly));
+    const result = mergeCandidates(candidates);
+    if (rootResolution) cache.set(key, result);
+    return result;
+  };
+
+  // Every internal re-export is a physical facade hop. It remains in the graph for runtime cycle truth,
+  // but semantic consumers ignore it in favor of importer -> declaration edges below.
+  for (const link of links) {
+    if (link.relation !== "re_exports") continue;
+    const records = jsExports.get(String(link.source)) || [];
+    if (records.some((record) => record.targetFile === String(link.target))) link.barrelProxy = true;
+  }
+
+  const semanticEdges = new Map();
+  const addSemanticEdge = (source, imp, origin, usage = null, force = false) => {
+    if (!origin?.file || (!force && origin.file === imp.targetFile)) return;
+    const key = `${source}\0${origin.file}\0${imp.line || 0}`;
+    const effectiveTypeOnly = imp.typeOnly === true || origin.typeOnly === true;
+    const current = semanticEdges.get(key);
+    if (current) {
+      if (!effectiveTypeOnly) delete current.typeOnly;
+      return;
+    }
+    semanticEdges.set(key, {
+      source,
+      target: origin.file,
+      relation: "imports",
+      confidence: "EXTRACTED",
+      semanticOrigin: true,
+      viaBarrel: imp.targetFile,
+      ...(effectiveTypeOnly ? { typeOnly: true } : {}),
+      ...(imp.line ? { line: imp.line } : {}),
+      ...(imp.specifier ? { specifier: imp.specifier } : {}),
+      ...(usage ? { usage } : {}),
+    });
+  };
+
+  const proxiedImportGroups = new Set();
+  for (const [source, imports] of importedLocals) {
+    for (const imp of imports.values()) {
+      if (!imp?.targetFile || imp.imported === "*") continue;
+      const result = resolveExport(imp.targetFile, imp.imported);
+      if (result.status !== "resolved") continue;
+      imp.originFile = result.origin.file;
+      imp.originName = result.origin.name;
+      imp.originTypeOnly = result.origin.typeOnly === true;
+      if (result.origin.file === imp.targetFile) continue;
+      proxiedImportGroups.add(`${source}\0${imp.targetFile}\0${imp.line || 0}`);
+      for (const link of links) {
+        if (String(link.source) === source && String(link.target) === imp.targetFile && link.relation === "imports"
+          && (!imp.line || !link.line || link.line === imp.line)) link.barrelProxy = true;
+      }
+      addSemanticEdge(source, imp, result.origin);
+    }
+  }
+  // One import statement can mix a barrel-local export with re-exported bindings. Once its physical
+  // file edge becomes a proxy, preserve the local binding as its own semantic edge to the barrel file.
+  for (const [source, imports] of importedLocals) for (const imp of imports.values()) {
+    if (!imp?.originFile || imp.originFile !== imp.targetFile) continue;
+    if (!proxiedImportGroups.has(`${source}\0${imp.targetFile}\0${imp.line || 0}`)) continue;
+    addSemanticEdge(source, imp, { file: imp.originFile, name: imp.originName, typeOnly: imp.originTypeOnly }, null, true);
+  }
+  links.push(...semanticEdges.values());
+
+  // Namespace member usage is only knowable in pass 2 (`ui.Button`, `ui.run`). Expose a bounded helper
+  // that uses the same cache and emits the corresponding semantic file edge exactly once.
+  const resolveNamespaceMember = (source, imp, member, usage = null) => {
+    if (!imp?.targetFile || imp.imported !== "*") return MISSING;
+    const result = resolveExport(imp.targetFile, member);
+    if (result.status !== "resolved") return result;
+    if (result.origin.file !== imp.targetFile) {
+      for (const link of links) {
+        if (String(link.source) === source && String(link.target) === imp.targetFile && link.relation === "imports"
+          && (!imp.line || !link.line || link.line === imp.line)) link.barrelProxy = true;
+      }
+      addSemanticEdge(source, imp, result.origin, usage);
+      // addSemanticEdge may have created a new entry after the initial push.
+      const edge = semanticEdges.get(`${source}\0${result.origin.file}\0${imp.line || 0}`);
+      if (edge && !links.includes(edge)) links.push(edge);
+    }
+    return result;
+  };
+
+  return { resolveExport, resolveNamespaceMember };
+}