weavatrix 0.2.13 → 0.2.14

package/src/analysis/http-contracts/graph-context.js

@@ -0,0 +1,143 @@
+import { folderModuleOf } from "../graph-analysis.edges.js";
+import { isStructuralRelation } from "../../graph/relations.js";
+import { endpointId, normalizeContractFile } from "./shared.js";
+
+export function reverseRuntimeImports(graph = {}) {
+  const byId = new Map();
+  const files = new Set();
+  for (const node of graph.nodes || []) {
+    const file = normalizeContractFile(node?.source_file);
+    if (!file) continue;
+    byId.set(String(node.id), file);
+    files.add(file);
+  }
+  const reverse = new Map([...files].map((file) => [file, new Set()]));
+  for (const link of graph.links || []) {
+    if (isStructuralRelation(link?.relation) || !["imports", "re_exports"].includes(link?.relation) || link?.typeOnly === true || link?.compileOnly === true || link?.barrelProxy === true) continue;
+    const importer = byId.get(String(endpointId(link.source)));
+    const imported = byId.get(String(endpointId(link.target)));
+    if (!importer || !imported || importer === imported) continue;
+    reverse.get(imported)?.add(importer);
+  }
+  return reverse;
+}
+
+export function wrapperScopeFiles(sourceFile, graph) {
+  const source = normalizeContractFile(sourceFile);
+  if (!source || !Array.isArray(graph?.nodes)) return null;
+  const reverse = reverseRuntimeImports(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 = normalizeContractFile(file);
+  const base = path.split("/").at(-1) || "";
+  return /(^|\/)(pages?|screens?|views?|routes?)(\/|$)/i.test(path)
+    || /(^|\/)(?:page|layout)\.[cm]?[jt]sx?$/i.test(path)
+    || /^(?:App|Root)\.[cm]?[jt]sx?$/i.test(base);
+}
+
+export function affectedForEndpoint(callsites, clientContexts, limits) {
+  const collected = new Map();
+  let traversalTruncated = false;
+  for (const context of clientContexts) {
+    const seeds = callsites.filter((call) => call.clientRepo === context.id).map((call) => call.file).sort();
+    if (!seeds.length) continue;
+    const queue = [];
+    const distance = new Map();
+    for (const seed of seeds) if (!distance.has(seed)) { distance.set(seed, 0); queue.push(seed); }
+    while (queue.length) {
+      const file = queue.shift();
+      const depth = distance.get(file);
+      const key = `${context.id}\0${file}`;
+      const previous = collected.get(key);
+      if (!previous || depth < previous.distance) collected.set(key, { client: context.id, file, distance: depth });
+      if (depth >= limits.maxImpactDepth) continue;
+      for (const importer of [...(context.reverse.get(file) || [])].sort()) {
+        if (distance.has(importer)) continue;
+        if (distance.size >= limits.maxAffectedFiles * 2) { traversalTruncated = true; continue; }
+        distance.set(importer, depth + 1);
+        queue.push(importer);
+      }
+    }
+  }
+  const allFiles = [...collected.values()].sort((left, right) => left.distance - right.distance || left.client.localeCompare(right.client) || left.file.localeCompare(right.file));
+  const filesTruncated = allFiles.length > limits.maxAffectedFiles;
+  const files = allFiles.slice(0, limits.maxAffectedFiles);
+  const allScreens = files.filter((entry) => isScreen(entry.file));
+  const screensTruncated = allScreens.length > limits.maxScreens;
+  const screens = allScreens.slice(0, limits.maxScreens);
+  const moduleMap = new Map();
+  for (const entry of files) {
+    const module = folderModuleOf(entry.file);
+    const key = `${entry.client}\0${module}`;
+    const item = moduleMap.get(key) || { client: entry.client, module, files: 0, nearestDistance: entry.distance };
+    item.files++;
+    item.nearestDistance = Math.min(item.nearestDistance, entry.distance);
+    moduleMap.set(key, item);
+  }
+  const allModules = [...moduleMap.values()].sort((left, right) => left.nearestDistance - right.nearestDistance || right.files - left.files || left.client.localeCompare(right.client) || left.module.localeCompare(right.module));
+  const modulesTruncated = allModules.length > limits.maxModules;
+  return {
+    complete: !(traversalTruncated || filesTruncated || screensTruncated || modulesTruncated),
+    files,
+    screens,
+    modules: allModules.slice(0, limits.maxModules),
+    truncated: { traversal: traversalTruncated, files: filesTruncated, screens: screensTruncated, modules: modulesTruncated },
+  };
+}
+const bareGraphLabel = (value) => String(value || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
+
+export 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 nodes = graph?.nodes || [];
+  const matches = nodes.filter((node) => normalizeContractFile(node?.source_file) && bareGraphLabel(node?.label) === handler && String(node?.id || "") !== normalizeContractFile(node?.source_file));
+  const endpointFile = normalizeContractFile(endpoint.file);
+  const sameFile = matches.filter((node) => normalizeContractFile(node?.source_file) === endpointFile);
+  const byId = new Map(nodes.map((node) => [endpointId(node?.id), node]));
+  const linkFile = (value) => {
+    const id = endpointId(value);
+    return normalizeContractFile(byId.get(id)?.source_file || String(id || "").split("#")[0]);
+  };
+  const directlyImportedFiles = new Set((graph?.links || [])
+    .filter((link) => ["imports", "re_exports"].includes(link?.relation) && linkFile(link?.source) === endpointFile)
+    .map((link) => linkFile(link?.target)).filter(Boolean));
+  const imported = matches.filter((node) => directlyImportedFiles.has(normalizeContractFile(node?.source_file)));
+  const resolved = sameFile.length === 1 ? sameFile[0] : imported.length === 1 ? imported[0] : matches.length === 1 ? matches[0] : null;
+  return {
+    handler,
+    handlerNodeId: resolved ? String(resolved.id) : null,
+    handlerResolution: resolved ? "resolved" : matches.length > 1 ? "ambiguous" : "unresolved",
+  };
+}
+
+export 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.",
+  };
+}

package/src/analysis/http-contracts/matching.js

@@ -0,0 +1,61 @@
+import { normalizeHttpContractPath } from "./shared.js";
+
+export const pathSegments = (path) => String(path || "").split("/").filter(Boolean);
+const parameter = (segment) => segment === ":param";
+const wildcard = (segment) => segment === "*";
+
+export function routeShapeMatches(endpointSegments, callSegments) {
+  const catchAll = wildcard(endpointSegments.at(-1));
+  if (catchAll ? callSegments.length < endpointSegments.length - 1 : endpointSegments.length !== callSegments.length) return false;
+  const compared = catchAll ? endpointSegments.length - 1 : endpointSegments.length;
+  for (let index = 0; index < compared; index++) {
+    const expected = endpointSegments[index], actual = callSegments[index];
+    if (parameter(expected)) continue;
+    if (parameter(actual) || wildcard(actual) || expected !== actual) return false;
+  }
+  return true;
+}
+
+export function suffixShapeMatch(endpointSegments, callSegments) {
+  if (endpointSegments.length === callSegments.length || Math.min(endpointSegments.length, callSegments.length) < 2) return false;
+  if (endpointSegments.length < callSegments.length) return routeShapeMatches(endpointSegments, callSegments.slice(callSegments.length - endpointSegments.length));
+  return routeShapeMatches(endpointSegments.slice(endpointSegments.length - callSegments.length), callSegments);
+}
+
+export function routeShapeContains(endpointSegments, requestedSegments) {
+  if (!requestedSegments.length || requestedSegments.length > endpointSegments.length) return false;
+  for (let start = 0; start <= endpointSegments.length - requestedSegments.length; start++) {
+    if (routeShapeMatches(endpointSegments.slice(start, start + requestedSegments.length), requestedSegments)) return true;
+  }
+  return false;
+}
+
+export function methodMatches(endpointMethod, callMethod) {
+  return endpointMethod === "ANY" || endpointMethod === "ALL" || endpointMethod === callMethod;
+}
+
+export function matchHttpContract(endpoint, call) {
+  if (!call?.path || !methodMatches(String(endpoint?.method || "").toUpperCase(), call.method)) return null;
+  const expected = pathSegments(normalizeHttpContractPath(endpoint.path));
+  const actual = pathSegments(call.path);
+  if (routeShapeMatches(expected, actual)) {
+    if (call.unknownPrefix || call.partialDynamic) return { kind: "exact-dynamic", confidence: "medium", score: 0.78, reason: "method and normalized route shape match, but the client URL retains a dynamic component" };
+    const concreteParameter = expected.some((segment, index) => parameter(segment) && !parameter(actual[index]));
+    return {
+      kind: "exact",
+      confidence: "high",
+      score: concreteParameter ? 0.96 : 1,
+      reason: concreteParameter ? "method matches and a backend parameter accepts the concrete client segment" : "method and normalized route shape match exactly",
+    };
+  }
+  if (suffixShapeMatch(expected, actual)) {
+    const dynamic = call.dynamic || call.unknownPrefix || call.partialDynamic;
+    return {
+      kind: "suffix",
+      confidence: dynamic ? "low" : "medium",
+      score: dynamic ? 0.55 : 0.72,
+      reason: dynamic ? "method matches and at least two trailing route segments match; the client prefix is dynamic" : "method matches and at least two trailing route segments match after a client/backend base-path difference",
+    };
+  }
+  return null;
+}

package/src/analysis/http-contracts/shared.js

@@ -0,0 +1,86 @@
+export const HTTP_CONTRACTS_V = 2;
+export const HTTP_CONTRACT_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+
+export const HTTP_CONTRACT_DEFAULTS = Object.freeze({
+  maxBackendFiles: 3_000,
+  maxClientFiles: 3_000,
+  maxEndpoints: 250,
+  maxCallsPerClient: 2_000,
+  maxMatches: 1_000,
+  maxCallsitesPerEndpoint: 100,
+  maxUncertain: 200,
+  maxImpactDepth: 2,
+  maxAffectedFiles: 100,
+  maxScreens: 50,
+  maxModules: 50,
+});
+
+export const HTTP_CONTRACT_HARD_LIMITS = Object.freeze({
+  maxBackendFiles: 3_000,
+  maxClientFiles: 10_000,
+  maxEndpoints: 500,
+  maxCallsPerClient: 5_000,
+  maxMatches: 5_000,
+  maxCallsitesPerEndpoint: 500,
+  maxUncertain: 1_000,
+  maxImpactDepth: 5,
+  maxAffectedFiles: 500,
+  maxScreens: 200,
+  maxModules: 200,
+});
+
+export const endpointId = (value) => value && typeof value === "object" ? value.id : value;
+
+export function normalizeContractFile(value) {
+  const raw = String(value || "").replace(/\\/g, "/");
+  if (!raw || raw.startsWith("/") || /^[a-z]:\//i.test(raw) || /[\x00-\x1f\x7f]/.test(raw)) return "";
+  const normalized = raw.replace(/^\.\//, "");
+  return normalized.split("/").some((part) => !part || part === "." || part === "..") ? "" : normalized;
+}
+
+export function boundedInteger(value, fallback, min, max) {
+  const number = Number(value);
+  return Number.isInteger(number) ? Math.max(min, Math.min(max, number)) : fallback;
+}
+
+export function safeContractName(value, fallback) {
+  const text = String(value || "").trim();
+  return /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(text) ? text : fallback;
+}
+
+export function contractLineAt(text, index) {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor++) if (text.charCodeAt(cursor) === 10) line++;
+  return line;
+}
+
+export function normalizeHttpContractLimits(input = {}) {
+  const result = {};
+  for (const key of Object.keys(HTTP_CONTRACT_DEFAULTS)) {
+    result[key] = boundedInteger(input[key], HTTP_CONTRACT_DEFAULTS[key], key === "maxImpactDepth" ? 0 : 1, HTTP_CONTRACT_HARD_LIMITS[key]);
+  }
+  return result;
+}
+
+export function normalizeHttpContractPath(value) {
+  let path = String(value || "").trim();
+  if (!path || path.length > 2_048) return null;
+  try {
+    if (/^https?:\/\//i.test(path)) path = new URL(path).pathname;
+    else if (/^\/\//.test(path)) path = new URL(`http:${path}`).pathname;
+  } catch { return null; }
+  const queryAt = path.search(/[?#]/);
+  if (queryAt >= 0) path = path.slice(0, queryAt);
+  path = path.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (!path.startsWith("/")) path = `/${path}`;
+  path = path.replace(/\/\{[^/}]+\}/g, "/:param")
+    .replace(/\/:([A-Za-z_$][\w$-]*)(?:\?)?/g, "/:param")
+    .replace(/\/\*[^/]*/g, "/*")
+    .replace(/\[(?:\.\.\.)?[^\]]+\]/g, "/:param")
+    .replace(/\/+$/g, "") || "/";
+  return /[\x00-\x1f\x7f]/.test(path) || path.includes("..") ? null : path;
+}
+
+export function filesFromGraph(graph) {
+  return [...new Set((graph?.nodes || []).map((node) => normalizeContractFile(node?.source_file)).filter(Boolean))].sort();
+}