weavatrix 0.2.0 → 0.2.2

package/src/analysis/http-contracts.js

@@ -8,11 +8,17 @@ import { createPathClassifier, hasPathClass } from "../path-classification.js";
 import { isWeavatrixIgnored, loadWeavatrixIgnore } from "../path-ignore.js";
 import { createRepoBoundary } from "../repo-path.js";
 import { safeRead } from "../util.js";
+import {
+  DEFAULT_HTTP_CLIENT_NAMES,
+  discoverHttpWrappers,
+  loadHttpContractConfig,
+  normalizeHttpClientNames,
+  normalizeHttpWrapperDescriptors,
+} from "./http-contract-wrappers.js";
 
-export const HTTP_CONTRACTS_V = 1;
+export const HTTP_CONTRACTS_V = 2;
 
 const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
-const DEFAULT_CLIENT_NAMES = Object.freeze(["axios", "http", "https", "$http", "httpClient", "apiClient", "restClient"]);
 const DEFAULTS = Object.freeze({
   maxBackendFiles: 3_000,
   maxClientFiles: 3_000,
@@ -148,7 +154,7 @@ function quotedArgument(text, start, quote) {
   return null;
 }
 
-function templateArgument(text, start) {
+function templateArgument(text, start, constants = null, requireStatic = false) {
   let value = "";
   let dynamicSegments = 0;
   let unknownPrefix = false;
@@ -182,6 +188,13 @@ function templateArgument(text, start) {
       cursor += 1;
     }
     if (depth !== 0) return null;
+    const expression = text.slice(index + 2, cursor - 1).trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(expression) && constants?.has(expression)) {
+      value += constants.get(expression);
+      index = cursor - 1;
+      continue;
+    }
+    if (requireStatic) return null;
     const next = text[cursor];
     const leftBoundary = value === "" || value.endsWith("/");
     const rightBoundary = !next || next === "/" || next === "?" || next === "#" || next === "`";
@@ -194,8 +207,71 @@ function templateArgument(text, start) {
   return null;
 }
 
-function parseUrlArgument(text, openParen) {
-  let start = openParen + 1;
+function extractStaticStringConstants(text) {
+  const source = String(text || "");
+  const mask = maskNonCode(source);
+  const declarations = [];
+  const declaration = /\bconst\s+([A-Za-z_$][\w$]*)\s*=/g;
+  let match;
+  while ((match = declaration.exec(mask)) && declarations.length < 500) {
+    let start = match.index + match[0].length;
+    while (/\s/.test(source[start] || "")) start += 1;
+    declarations.push({ name: match[1], start });
+  }
+
+  const constants = new Map();
+  for (const item of declarations) {
+    const quote = source[item.start];
+    if (quote !== "'" && quote !== '"') continue;
+    const parsed = quotedArgument(source, item.start, quote);
+    if (parsed && parsed.value.length <= 2_048) constants.set(item.name, parsed.value);
+  }
+  // Resolve bounded chains such as `const route = `${API_ROOT}/query`` without evaluating code.
+  for (let pass = 0; pass < Math.min(8, declarations.length); pass += 1) {
+    let changed = false;
+    for (const item of declarations) {
+      if (constants.has(item.name) || source[item.start] !== "`") continue;
+      const parsed = templateArgument(source, item.start, constants, true);
+      if (!parsed || parsed.value.length > 2_048) continue;
+      constants.set(item.name, parsed.value);
+      changed = true;
+    }
+    if (!changed) break;
+  }
+  return constants;
+}
+
+function argumentStart(text, openParen, target) {
+  let current = 0, round = 0, square = 0, curly = 0;
+  for (let index = openParen + 1; index < text.length; index += 1) {
+    const char = text[index];
+    if (current === target && !/\s|,/.test(char)) return index;
+    if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      index += 1;
+      while (index < text.length) {
+        if (text[index] === "\\") index += 2;
+        else if (text[index] === quote) break;
+        else index += 1;
+      }
+      continue;
+    }
+    if (char === "(" ) round += 1;
+    else if (char === "[" ) square += 1;
+    else if (char === "{" ) curly += 1;
+    else if (char === ")") {
+      if (round === 0 && square === 0 && curly === 0) return null;
+      round -= 1;
+    } else if (char === "]") square -= 1;
+    else if (char === "}") curly -= 1;
+    else if (char === "," && round === 0 && square === 0 && curly === 0) current += 1;
+  }
+  return null;
+}
+
+function parseUrlArgument(text, openParen, constants, argument = 0) {
+  let start = argumentStart(text, openParen, argument);
+  if (start == null) return { path: null, endIndex: openParen, kind: "dynamic", dynamic: true, unknownPrefix: false, partialDynamic: true, reason: `URL argument ${argument} is missing` };
   while (/\s/.test(text[start] || "")) start += 1;
   const quote = text[start];
   if (quote === "'" || quote === '"') {
@@ -204,7 +280,7 @@ function parseUrlArgument(text, openParen) {
     return { path: normalizeHttpContractPath(parsed.value), endIndex: parsed.endIndex, kind: "literal", dynamic: false, unknownPrefix: false, partialDynamic: false, reason: null };
   }
   if (quote === "`") {
-    const parsed = templateArgument(text, start);
+    const parsed = templateArgument(text, start, constants);
     if (!parsed) return { path: null, endIndex: start, kind: "dynamic", dynamic: true, reason: "unterminated URL template" };
     return {
       path: normalizeHttpContractPath(parsed.value),
@@ -231,21 +307,30 @@ function fetchMethod(text, argumentEnd) {
 }
 
 function normalizedClientNames(values) {
-  return new Set([...DEFAULT_CLIENT_NAMES, ...(Array.isArray(values) ? values : [])]
+  return new Set([...DEFAULT_HTTP_CLIENT_NAMES, ...normalizeHttpClientNames(values)]
     .map((value) => String(value || "").trim().toLowerCase())
     .filter((value) => /^[a-z_$][\w$]*$/i.test(value)));
 }
 
+const escapeRegex = (value) => String(value).replace(/[|\\{}()[\]^$+*?.-]/g, "\\$&");
+
 export function extractHttpClientCallsFromText(text, file, options = {}) {
   const source = String(text || "");
   const mask = maskNonCode(source);
+  const constants = extractStaticStringConstants(source);
   const allowed = normalizedClientNames(options.clientNames);
+  const wrappers = normalizeHttpWrapperDescriptors(options.wrappers, "input")
+    .concat((Array.isArray(options.normalizedWrappers) ? options.normalizedWrappers : []));
   const maxCalls = boundedInteger(options.maxCalls, DEFAULTS.maxCallsPerClient, 1, HARD.maxCallsPerClient);
   const calls = [];
+  const seen = new Set();
   let truncated = false;
-  const add = (clientName, method, openParen, fetch = false) => {
+  const add = (clientName, method, openParen, fetch = false, urlArgument = 0, detector = "builtin", wrapper = null) => {
+    const key = `${openParen}\0${method}\0${urlArgument}`;
+    if (seen.has(key)) return;
+    seen.add(key);
     if (calls.length >= maxCalls) { truncated = true; return; }
-    const parsed = parseUrlArgument(source, openParen);
+    const parsed = parseUrlArgument(source, openParen, constants, urlArgument);
     const fetchInfo = fetch ? fetchMethod(source, parsed.endIndex) : { method: method.toUpperCase(), uncertain: false };
     calls.push({
       file: normalizeFile(file),
@@ -258,10 +343,12 @@ export function extractHttpClientCallsFromText(text, file, options = {}) {
       unknownPrefix: Boolean(parsed.unknownPrefix),
       partialDynamic: Boolean(parsed.partialDynamic || fetchInfo.uncertain),
       reason: fetchInfo.uncertain ? "HTTP method is dynamic" : parsed.reason,
+      detector,
+      wrapper,
     });
   };
 
-  const member = /(^|[^\w$])([A-Za-z_$][\w$]*)\s*(?:\?\.|\.)\s*(get|post|put|patch|delete|head|options)\s*\(/gim;
+  const member = /(^|[^\w$])([A-Za-z_$][\w$]*)\s*(?:\?\.|\.)\s*(get|post|put|patch|delete|head|options)\s*(?:<[^>\n]{1,200}>)?\s*\(/gim;
   let match;
   while ((match = member.exec(mask))) {
     if (!allowed.has(match[2].toLowerCase())) continue;
@@ -269,6 +356,24 @@ export function extractHttpClientCallsFromText(text, file, options = {}) {
   }
   const fetchCall = /(^|[^\w$])fetch\s*\(/gim;
   while ((match = fetchCall.exec(mask))) add("fetch", "GET", fetchCall.lastIndex - 1, true);
+  for (const wrapper of wrappers) {
+    if (wrapper.allowedFiles instanceof Set && !wrapper.allowedFiles.has(normalizeFile(file))) continue;
+    if (wrapper.kind === "function") {
+      const bare = new RegExp(`(^|[^\\w$.?])${escapeRegex(wrapper.call)}\\s*(?:<[^>\\n]{1,200}>)?\\s*\\(`, "gim");
+      while ((match = bare.exec(mask))) {
+        const nameAt = bare.lastIndex - match[0].length + match[1].length;
+        if (/\bfunction\s*$/i.test(mask.slice(Math.max(0, nameAt - 30), nameAt))) continue;
+        add(wrapper.call, wrapper.method, bare.lastIndex - 1, false, wrapper.urlArgument, `${wrapper.source}-wrapper`, {
+          kind: wrapper.kind, call: wrapper.call, definitionFile: wrapper.definitionFile || null,
+        });
+      }
+    } else if (wrapper.kind === "member") {
+      const memberCall = new RegExp(`(^|[^\\w$])${escapeRegex(wrapper.object)}\\s*(?:\\?\\.|\\.)\\s*${escapeRegex(wrapper.member)}\\s*(?:<[^>\\n]{1,200}>)?\\s*\\(`, "gim");
+      while ((match = memberCall.exec(mask))) add(`${wrapper.object}.${wrapper.member}`, wrapper.method, memberCall.lastIndex - 1, false, wrapper.urlArgument, `${wrapper.source}-wrapper`, {
+        kind: wrapper.kind, object: wrapper.object, member: wrapper.member, definitionFile: wrapper.definitionFile || null,
+      });
+    }
+  }
   calls.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line || left.method.localeCompare(right.method) || String(left.path).localeCompare(String(right.path)));
   return { calls, truncated };
 }
@@ -279,7 +384,7 @@ function filesFromGraph(graph) {
 
 export function detectHttpClientCalls(repoRoot, codeFiles, options = {}) {
   const boundary = createRepoBoundary(repoRoot);
-  if (!boundary.root) return { calls: [], truncated: false, filesScanned: 0 };
+  if (!boundary.root) return { calls: [], truncated: false, filesScanned: 0, discovery: { enabled: false, configured: 0, discovered: 0, ambiguous: [] }, reasons: [] };
   const maxFiles = boundedInteger(options.maxFiles, DEFAULTS.maxClientFiles, 1, HARD.maxClientFiles);
   const maxCalls = boundedInteger(options.maxCalls, DEFAULTS.maxCallsPerClient, 1, HARD.maxCallsPerClient);
   const ignoreRules = loadWeavatrixIgnore(boundary.root);
@@ -287,6 +392,7 @@ export function detectHttpClientCalls(repoRoot, codeFiles, options = {}) {
   const candidates = [...new Set((codeFiles || []).map((entry) => normalizeFile(entry?.path || entry)).filter(Boolean))].sort();
   let truncated = candidates.length > maxFiles;
   let filesScanned = 0;
+  const sources = [];
   const calls = [];
   for (const file of candidates.slice(0, maxFiles)) {
     if (!/\.(?:[cm]?[jt]sx?|vue|svelte)$/i.test(file) || isWeavatrixIgnored(file, ignoreRules)) continue;
@@ -297,14 +403,53 @@ export function detectHttpClientCalls(repoRoot, codeFiles, options = {}) {
     const text = safeRead(resolved.path);
     if (!text) continue;
     filesScanned += 1;
+    sources.push({ file, text });
+  }
+  const config = loadHttpContractConfig(boundary.root);
+  const clientNames = [...new Set([
+    ...normalizeHttpClientNames(options.clientNames),
+    ...config.clientNames,
+  ])];
+  const configured = [
+    ...normalizeHttpWrapperDescriptors(options.wrappers, "input"),
+    ...config.wrappers,
+  ];
+  const discoveryEnabled = options.autoDiscoverWrappers !== false && config.autoDiscoverWrappers !== false;
+  const discovered = discoveryEnabled ? discoverHttpWrappers(sources, clientNames) : { wrappers: [], ambiguous: [], truncated: false };
+  const scopedDiscovered = discovered.wrappers.map((wrapper) => ({
+    ...wrapper,
+    allowedFiles: wrapperScopeFiles(wrapper.definitionFile, options.graph),
+  }));
+  for (const { file, text } of sources) {
     const remaining = maxCalls - calls.length;
     if (remaining <= 0) { truncated = true; break; }
-    const extracted = extractHttpClientCallsFromText(text, file, { clientNames: options.clientNames, maxCalls: remaining });
+    const extracted = extractHttpClientCallsFromText(text, file, {
+      clientNames,
+      normalizedWrappers: [...configured, ...scopedDiscovered],
+      maxCalls: remaining,
+    });
     calls.push(...extracted.calls);
     if (extracted.truncated) truncated = true;
   }
   calls.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line || left.method.localeCompare(right.method) || String(left.path).localeCompare(String(right.path)));
-  return { calls, truncated, filesScanned };
+  const reasons = [];
+  if (config.error) reasons.push(`HTTP contract config ${config.error}`);
+  reasons.push(...(config.warnings || []));
+  if (discovered.truncated) reasons.push("auto-discovered wrapper cap reached");
+  if (discovered.ambiguous.length) reasons.push(`${discovered.ambiguous.length} ambiguous auto-discovered wrapper name(s) skipped`);
+  return {
+    calls,
+    truncated,
+    filesScanned,
+    discovery: {
+      enabled: discoveryEnabled,
+      configured: configured.length,
+      discovered: scopedDiscovered.length,
+      ambiguous: discovered.ambiguous,
+      truncated: discovered.truncated,
+    },
+    reasons,
+  };
 }
 
 function pathSegments(path) {
@@ -334,6 +479,14 @@ function suffixShapeMatch(endpointSegments, callSegments) {
   return routeShapeMatches(endpointSegments.slice(endpointSegments.length - callSegments.length), callSegments);
 }
 
+function routeShapeContains(endpointSegments, requestedSegments) {
+  if (!requestedSegments.length || requestedSegments.length > endpointSegments.length) return false;
+  for (let start = 0; start <= endpointSegments.length - requestedSegments.length; start += 1) {
+    if (routeShapeMatches(endpointSegments.slice(start, start + requestedSegments.length), requestedSegments)) return true;
+  }
+  return false;
+}
+
 function methodMatches(endpointMethod, callMethod) {
   return endpointMethod === "ANY" || endpointMethod === "ALL" || endpointMethod === callMethod;
 }
@@ -384,6 +537,24 @@ function reverseImports(graph = {}) {
   return reverse;
 }
 
+function wrapperScopeFiles(sourceFile, graph) {
+  const source = normalizeFile(sourceFile);
+  if (!source || !Array.isArray(graph?.nodes)) return null;
+  const reverse = reverseImports(graph);
+  const allowed = new Set([source]);
+  const queue = [{ file: source, depth: 0 }];
+  while (queue.length && allowed.size < 2_000) {
+    const current = queue.shift();
+    if (current.depth >= 4) continue;
+    for (const importer of [...(reverse.get(current.file) || [])].sort()) {
+      if (allowed.has(importer)) continue;
+      allowed.add(importer);
+      queue.push({ file: importer, depth: current.depth + 1 });
+    }
+  }
+  return allowed;
+}
+
 function isScreen(file) {
   const path = normalizeFile(file);
   const base = path.split("/").at(-1) || "";
@@ -450,7 +621,9 @@ function endpointFilter(endpoint, backendId, options) {
   if (options.method && endpoint.method !== options.method && endpoint.method !== "ANY" && endpoint.method !== "ALL") return false;
   if (options.path) {
     const requested = normalizeHttpContractPath(options.path);
-    if (!requested || !routeShapeMatches(pathSegments(normalizeHttpContractPath(endpoint.path)), pathSegments(requested))) return false;
+    const endpointSegments = pathSegments(normalizeHttpContractPath(endpoint.path));
+    const requestedSegments = pathSegments(requested);
+    if (!requested || (!routeShapeMatches(endpointSegments, requestedSegments) && !routeShapeContains(endpointSegments, requestedSegments))) return false;
   }
   if (options.changedFiles?.size) {
     const file = normalizeFile(endpoint.file);
@@ -459,6 +632,43 @@ function endpointFilter(endpoint, backendId, options) {
   return true;
 }
 
+function bareGraphLabel(value) {
+  return String(value || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
+}
+
+function handlerNodeEvidence(endpoint, graph) {
+  const handler = /^[A-Za-z_$][\w$]{0,127}$/.test(String(endpoint?.handler || "")) ? String(endpoint.handler) : null;
+  if (!handler) return { handler: null, handlerNodeId: null, handlerResolution: "inline-or-unresolved" };
+  const matches = (graph?.nodes || []).filter((node) =>
+    normalizeFile(node?.source_file) && bareGraphLabel(node?.label) === handler && String(node?.id || "") !== normalizeFile(node?.source_file));
+  const sameFile = matches.filter((node) => normalizeFile(node?.source_file) === normalizeFile(endpoint.file));
+  const resolved = sameFile.length === 1 ? sameFile[0] : matches.length === 1 ? matches[0] : null;
+  return {
+    handler,
+    handlerNodeId: resolved ? String(resolved.id) : null,
+    handlerResolution: resolved ? "resolved" : matches.length > 1 ? "ambiguous" : "unresolved",
+  };
+}
+
+function externalUseLiveness(callsites, handlerEvidence) {
+  const proven = callsites.filter((call) => call.match?.confidence === "high" || call.match?.confidence === "medium");
+  const possible = callsites.filter((call) => call.match?.confidence === "low");
+  const status = proven.length ? "NOT_DEAD_EXTERNAL_USE" : possible.length ? "POSSIBLE_EXTERNAL_USE" : "UNKNOWN";
+  const evidence = proven.length ? proven : possible;
+  return {
+    status,
+    subject: handlerEvidence.handlerNodeId ? "handler-node" : handlerEvidence.handler ? "endpoint-handler" : "endpoint",
+    canSuppressDeadCandidate: proven.length > 0 && Boolean(handlerEvidence.handlerNodeId),
+    staticEvidence: evidence.length,
+    consumerRepositories: [...new Set(evidence.map((call) => call.clientRepo))].sort(),
+    reason: proven.length
+      ? "At least one selected external repository has a medium/high-confidence static HTTP contract match."
+      : possible.length
+        ? "Only low-confidence external HTTP contract matches were found; review before suppressing a dead-code candidate."
+        : "No selected external repository proved a static caller; absence of evidence is not a dead-code verdict.",
+  };
+}
+
 // `backends` and `clients` are arrays of {id, repoRoot, codeFiles?, graph?}. Backends may optionally
 // supply a precomputed `endpoints` array; otherwise the shared multi-language endpoint detector is used.
 export function analyzeHttpContracts(input = {}) {
@@ -483,7 +693,7 @@ export function analyzeHttpContracts(input = {}) {
     if (filtered.length > endpointBudget) completeness.push(`${id}: endpoint cap reached`);
     const accepted = filtered.slice(0, endpointBudget);
     endpointBudget -= accepted.length;
-    backends.push({ id, endpoints: accepted });
+    backends.push({ id, endpoints: accepted, graph: descriptor.graph });
   }
 
   const clients = [];
@@ -494,10 +704,20 @@ export function analyzeHttpContracts(input = {}) {
       maxFiles: limits.maxClientFiles,
       maxCalls: limits.maxCallsPerClient,
       clientNames: descriptor.clientNames || input.clientNames,
+      wrappers: descriptor.wrappers || input.wrappers,
+      autoDiscoverWrappers: descriptor.autoDiscoverWrappers ?? input.autoDiscoverWrappers,
+      graph: descriptor.graph,
       includeTests: descriptor.includeTests ?? input.includeTests,
     });
     if (detected.truncated) completeness.push(`${id}: client scan cap reached`);
-    clients.push({ id, calls: detected.calls, reverse: reverseImports(descriptor.graph), filesScanned: detected.filesScanned });
+    for (const reason of detected.reasons || []) completeness.push(`${id}: ${reason}`);
+    clients.push({
+      id,
+      calls: detected.calls,
+      reverse: reverseImports(descriptor.graph),
+      filesScanned: detected.filesScanned,
+      wrapperDiscovery: detected.discovery,
+    });
   }
 
   const results = [];
@@ -529,20 +749,24 @@ export function analyzeHttpContracts(input = {}) {
             method: call.method,
             path: call.path,
             dynamic: call.dynamic,
+            detector: call.detector,
+            wrapper: call.wrapper,
             match,
           });
         }
       }
       callsites.sort((left, right) => right.match.score - left.match.score || left.clientRepo.localeCompare(right.clientRepo) || left.file.localeCompare(right.file) || left.line - right.line);
+      const handlerEvidence = handlerNodeEvidence(endpoint, backend.graph);
       results.push({
         backend: backend.id,
         method: endpoint.method,
         path: endpoint.path,
         normalizedPath: normalizeHttpContractPath(endpoint.path),
-        handler: /^[A-Za-z_$][\w$]{0,127}$/.test(String(endpoint.handler || "")) ? String(endpoint.handler) : null,
+        ...handlerEvidence,
         file: normalizeFile(endpoint.file) || null,
         line: Number(endpoint.line) || null,
         callsites,
+        liveness: externalUseLiveness(callsites, handlerEvidence),
         affected: affectedForEndpoint(callsites, clients, limits),
       });
     }
@@ -574,7 +798,12 @@ export function analyzeHttpContracts(input = {}) {
       matches,
       methodMismatches,
       uncertainCalls: uncertainAll.length,
+      notDeadExternalUse: results.filter((endpoint) => endpoint.liveness.status === "NOT_DEAD_EXTERNAL_USE").length,
+      notDeadExternalHandlers: results.filter((endpoint) => endpoint.liveness.canSuppressDeadCandidate).length,
+      possibleExternalUse: results.filter((endpoint) => endpoint.liveness.status === "POSSIBLE_EXTERNAL_USE").length,
+      unknownLiveness: results.filter((endpoint) => endpoint.liveness.status === "UNKNOWN").length,
     },
+    wrapperDiscovery: clients.map((client) => ({ clientRepo: client.id, ...client.wrapperDiscovery })),
     endpoints: results,
     uncertain: uncertainAll.slice(0, limits.maxUncertain),
   };

package/src/graph/edge-provenance.js

@@ -0,0 +1,31 @@
+// Versioned origin classification for graph edges. `confidence` remains a compatibility field;
+// provenance says how an edge was established and leaves room for a bounded LSP precision overlay.
+export const EDGE_PROVENANCE_V = 1;
+export const EDGE_PROVENANCE_KINDS = Object.freeze([
+  "EXACT_LSP", "EXTRACTED", "RESOLVED", "INFERRED", "CONFLICT",
+]);
+
+const ALLOWED = new Set(EDGE_PROVENANCE_KINDS);
+
+export function edgeProvenance(edge) {
+  const explicit = String(edge?.provenance || "").trim().toUpperCase();
+  if (ALLOWED.has(explicit)) return explicit;
+  if (edge?.semanticOrigin === true) return "RESOLVED";
+  const legacy = String(edge?.confidence || "").trim().toUpperCase();
+  return ALLOWED.has(legacy) ? legacy : "UNKNOWN";
+}
+
+export function stampEdgeProvenance(links) {
+  for (const link of Array.isArray(links) ? links : []) {
+    const provenance = edgeProvenance(link);
+    if (provenance !== "UNKNOWN") link.provenance = provenance;
+  }
+  return links;
+}
+
+export function summarizeEdgeProvenance(links) {
+  const counts = Object.fromEntries([...EDGE_PROVENANCE_KINDS, "UNKNOWN"].map((kind) => [kind, 0]));
+  for (const link of Array.isArray(links) ? links : []) counts[edgeProvenance(link)] += 1;
+  const total = Array.isArray(links) ? links.length : 0;
+  return {version: EDGE_PROVENANCE_V, total, classified: total - counts.UNKNOWN, complete: counts.UNKNOWN === 0, counts};
+}

package/src/graph/freshness-probe.js

@@ -9,7 +9,7 @@ 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_SCHEMA_V = 2
 export const GRAPH_BUILDER_VERSION = (() => {
     try { return String(createRequire(import.meta.url)('../../package.json').version) }
     catch { return '0.0.0' }
@@ -21,6 +21,7 @@ export const GRAPH_BUILDER_VERSION = (() => {
 const CURRENT_GRAPH_SCHEMA = Object.freeze({
     extImportsV: 2,
     edgeTypesV: 2,
+    edgeProvenanceV: 1,
     complexityV: 1,
     repoBoundaryV: 1,
     barrelResolutionV: 1,

package/src/graph/incremental-refresh.js

@@ -162,7 +162,7 @@ function mergeScopedGraph(base, scoped, affected, snapshot) {
     controlHashes: snapshot.controlHashes,
     graphRevision: snapshot.revision,
   };
-  for (const key of ["extImportsV", "edgeTypesV", "complexityV", "repoBoundaryV", "barrelResolutionV", "extractorSchemaV"]) {
+  for (const key of ["extImportsV", "edgeTypesV", "edgeProvenanceV", "complexityV", "repoBoundaryV", "barrelResolutionV", "extractorSchemaV"]) {
     merged[key] = Math.max(Number(base[key]) || 0, Number(scoped[key]) || 0);
   }
   return merged;
@@ -183,7 +183,7 @@ export async function refreshGraphIncrementally(repoDir, existingGraph, {
 
   if (!existingGraph || !existingGraph.fileHashes || !existingGraph.fileExportSignatures
     || !existingGraph.controlHashes || !existingGraph.jsExportRecords || Number(existingGraph.barrelResolutionV) < 1
-    || Number(existingGraph.extractorSchemaV) < 1) {
+    || Number(existingGraph.extractorSchemaV) < 1 || Number(existingGraph.edgeProvenanceV) < 1) {
     return full("incremental-baseline-unavailable");
   }
   if (!sameRecord(existingGraph.controlHashes, snapshot.controlHashes)) return full("ignore-or-control-config-changed");

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

@@ -12,6 +12,7 @@ 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";
+import { EDGE_PROVENANCE_V, stampEdgeProvenance } from "./edge-provenance.js";
 
 // Parse a repo directory into a graph-builder-compatible { nodes, links } graph.
 export async function buildInternalGraph(repoDir, opts = {}) {
@@ -128,6 +129,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         target: tgt,
         relation: meta.relation || "imports",
         confidence: "EXTRACTED",
+        provenance: meta.provenance || "RESOLVED",
         ...(typeof meta.typeOnly === "boolean" ? { typeOnly: meta.typeOnly } : {}),
         ...(meta.compileOnly === true ? { compileOnly: true } : {}),
         ...(meta.line ? { line: meta.line } : {}),
@@ -317,6 +319,7 @@ 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.
   assignDeterministicCommunities(nodes);
+  stampEdgeProvenance(links);
 
   // 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.
@@ -328,6 +331,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     externalImports,
     extImportsV: 2,
     edgeTypesV: 2,
+    edgeProvenanceV: EDGE_PROVENANCE_V,
     complexityV: 1,
     repoBoundaryV: 1,
     barrelResolutionV: 1,

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

@@ -248,6 +248,21 @@ export function buildResolvers(repoDir, fileSet) {
   };
 
   const JS_EXTS = ["", ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs", ".json", "/index.js", "/index.ts", "/index.jsx", "/index.tsx"];
+  const resolveJsBase = (base) => {
+    for (const extension of JS_EXTS) {
+      const candidate = (base + extension).replace(/\/+/g, "/");
+      if (fileSet.has(candidate)) return candidate;
+    }
+    // TypeScript NodeNext source commonly imports the emitted extension (`./http.js`) while the
+    // repository contains `http.ts`/`http.tsx`. Exact runtime files win above; a source counterpart
+    // is accepted only when unique so same-basename ambiguity is never guessed.
+    const sourceCandidates = [];
+    if (/\.js$/i.test(base)) sourceCandidates.push(base.replace(/\.js$/i, ".ts"), base.replace(/\.js$/i, ".tsx"));
+    else if (/\.jsx$/i.test(base)) sourceCandidates.push(base.replace(/\.jsx$/i, ".tsx"));
+    const existing = [...new Set(sourceCandidates.map((candidate) => candidate.replace(/\/+/g, "/")))]
+      .filter((candidate) => fileSet.has(candidate));
+    return existing.length === 1 ? existing[0] : null;
+  };
   const resolveJsImport = (fromRel, spec) => {
     if (!spec) return null;
     let base;
@@ -258,13 +273,13 @@ export function buildResolvers(repoDir, fileSet) {
         // baseUrl-rooted internal import ("components/Button" with baseUrl:"src") — try before calling it an npm package
         for (const ctx of contextsForFile(fromRel)) for (const b of ctx.baseUrls) {
           const root = (b ? b + "/" : "") + spec;
-          for (const e of JS_EXTS) { const cand = (root + e).replace(/\/+/g, "/"); if (fileSet.has(cand)) return cand; }
+          const resolved = resolveJsBase(root);
+          if (resolved) return resolved;
         }
         return null;   // genuinely bare → npm package (stays unresolved here)
       }
     }
-    for (const e of JS_EXTS) { const cand = (base + e).replace(/\/+/g, "/"); if (fileSet.has(cand)) return cand; }
-    return null;
+    return resolveJsBase(base);
   };
 
   const resolvePyPath = (baseDir, parts) => {