weavatrix 0.2.12 → 0.2.14

package/src/analysis/health-capabilities.js

@@ -0,0 +1,82 @@
+// Honest Health capability coverage. `status` says whether a check actually ran for this repository;
+// `completeness` says whether its evidence can support a repository-wide conclusion.
+const capability = (status, completeness, detail, extra = {}) => ({ status, completeness, detail, ...extra });
+
+const sourceLanguages = (files) => {
+  const languages = new Set();
+  for (const file of files || []) {
+    if (/\.(?:[cm]?js|jsx|[cm]?ts|tsx)$/i.test(file)) languages.add("javascript/typescript");
+    else if (/\.py$/i.test(file)) languages.add("python");
+    else if (/\.go$/i.test(file)) languages.add("go");
+    else if (/\.java$/i.test(file)) languages.add("java");
+    else if (/\.rs$/i.test(file)) languages.add("rust");
+    else if (/\.cs$/i.test(file)) languages.add("csharp");
+  }
+  return languages;
+};
+
+const checkCapability = (check, supported, label) => {
+  if (!supported) return capability("NOT_SUPPORTED", "PARTIAL", `${label} is not supported for the discovered package ecosystem.`);
+  if (check?.status === "OK") return capability("CHECKED", "COMPLETE", check.detail || `${label} completed.`);
+  if (check?.status === "PARTIAL") return capability("NOT_CHECKED", "PARTIAL", check.detail || `${label} evidence is partial.`);
+  if (check?.status === "ERROR") return capability("NOT_CHECKED", "PARTIAL", check.detail || `${label} failed.`);
+  return capability("NOT_CHECKED", "PARTIAL", check?.detail || `${label} was not requested.`);
+};
+
+export function buildHealthCapabilityMatrix({
+  graphComplete,
+  dependencyStatus,
+  dependencyEcosystems = {},
+  checks = {},
+  sourceFiles = [],
+  correctnessCoverage = {},
+  measuredCoverageFiles = 0,
+} = {}) {
+  const languages = sourceLanguages(sourceFiles);
+  const ecosystemRows = Object.values(dependencyEcosystems).filter((item) => item?.present);
+  const supportedDependencyRows = ecosystemRows.filter((item) => item.status === "CHECKED");
+  const unsupportedDependencyRows = ecosystemRows.filter((item) => item.status === "NOT_SUPPORTED");
+  const noDependencyEvidence = ecosystemRows.length === 0;
+  const onlyUnsupportedDependencies = unsupportedDependencyRows.length > 0 && supportedDependencyRows.length === 0;
+  const advisorySupported = supportedDependencyRows.some((item) => ["npm", "go", "python"].includes(item.ecosystem));
+  const malwareSupported = supportedDependencyRows.some((item) => ["npm", "go", "python"].includes(item.ecosystem));
+  const coverageSupported = [...languages].some((language) => ["javascript/typescript", "python", "go"].includes(language));
+  const runtimeFiles = Number(correctnessCoverage.runtimeCorrectnessFiles || 0);
+  const concurrencyFiles = Number(correctnessCoverage.concurrencyFiles || 0);
+
+  return {
+    capabilityMatrixV: 1,
+    structure: capability(
+      "CHECKED",
+      graphComplete ? "COMPLETE" : "PARTIAL",
+      graphComplete
+        ? "Graph cycles, orphans and configured boundaries were checked over the complete graph."
+        : "Structure checks ran, but the graph is scoped or excludes part of the repository.",
+    ),
+    dependencies: capability(
+      noDependencyEvidence ? "NOT_CHECKED" : onlyUnsupportedDependencies ? "NOT_SUPPORTED" : "CHECKED",
+      !noDependencyEvidence && dependencyStatus === "COMPLETE" ? "COMPLETE" : "PARTIAL",
+      noDependencyEvidence
+        ? "No dependency manifest was discovered, so manifest-to-import verification did not run."
+        : onlyUnsupportedDependencies
+        ? "Dependency manifests were detected, but every discovered build ecosystem lacks import-to-artifact verification."
+        : unsupportedDependencyRows.length
+          ? `Supported ecosystems were checked; ${unsupportedDependencyRows.map((item) => item.ecosystem).join(", ")} remains NOT_SUPPORTED.`
+          : "Discovered supported manifests were compared with indexed imports at their documented evidence level.",
+      { ecosystems: dependencyEcosystems },
+    ),
+    runtimeCorrectness: runtimeFiles
+      ? capability("CHECKED", "PARTIAL", `Checked ${runtimeFiles} product source file(s) for the bounded Go/Java/retry correctness patterns. This is not compiler or runtime proof.`, { checks: correctnessCoverage.checks || {} })
+      : capability("NOT_SUPPORTED", "PARTIAL", "No source file matched the currently supported bounded correctness patterns."),
+    concurrency: concurrencyFiles
+      ? capability("CHECKED", "PARTIAL", `Checked ${concurrencyFiles} Java source file(s) for direct InterruptedException restore/rethrow evidence. No race detector ran; race freedom is not claimed.`)
+      : capability("NOT_SUPPORTED", "PARTIAL", "No supported Java interruption check applied. No race detector ran; race freedom is not claimed."),
+    advisories: checkCapability(checks.osv, advisorySupported, "OSV advisory matching"),
+    malware: checkCapability(checks.malware, malwareSupported, "Installed-package malware scanning"),
+    coverage: measuredCoverageFiles > 0
+      ? capability("CHECKED", "COMPLETE", `Mapped an existing supported coverage report to ${measuredCoverageFiles} file(s).`)
+      : coverageSupported
+        ? capability("NOT_CHECKED", "PARTIAL", "No supported measured coverage report was found; static test reachability is not coverage.")
+        : capability("NOT_SUPPORTED", "PARTIAL", `No supported coverage format applies to the discovered language set${languages.size ? ` (${[...languages].join(", ")})` : ""}.`),
+  };
+}

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

@@ -0,0 +1,169 @@
+import { detectEndpoints } from "../endpoints.js";
+import { detectHttpClientCalls } from "./client-call-detection.js";
+import { affectedForEndpoint, externalUseLiveness, handlerNodeEvidence, reverseRuntimeImports } from "./graph-context.js";
+import { matchHttpContract, methodMatches, pathSegments, routeShapeContains, routeShapeMatches, suffixShapeMatch } from "./matching.js";
+import {
+  HTTP_CONTRACTS_V,
+  HTTP_CONTRACT_METHODS,
+  filesFromGraph,
+  normalizeContractFile,
+  normalizeHttpContractLimits,
+  normalizeHttpContractPath,
+  safeContractName,
+} from "./shared.js";
+
+const descriptorFiles = (descriptor) => descriptor.codeFiles || filesFromGraph(descriptor.graph);
+
+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);
+    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 = normalizeContractFile(endpoint.file);
+    if (!options.changedFiles.has(file) && !options.changedFiles.has(`${backendId}::${file}`)) return false;
+  }
+  return true;
+}
+
+export function analyzeHttpContracts(input = {}) {
+  const limits = normalizeHttpContractLimits(input);
+  const method = input.method ? String(input.method).toUpperCase() : null;
+  if (method && !HTTP_CONTRACT_METHODS.has(method)) throw new Error("method must be a concrete HTTP method");
+  const changedFiles = new Set((Array.isArray(input.changedFiles) ? input.changedFiles : []).map((file) => normalizeContractFile(file)).filter(Boolean));
+  const backendDescriptors = (Array.isArray(input.backends) ? input.backends : input.backend ? [input.backend] : []).slice(0, 20);
+  const clientDescriptors = (Array.isArray(input.clients) ? input.clients : input.client ? [input.client] : []).slice(0, 20);
+  const completeness = [], backends = [];
+  let endpointBudget = limits.maxEndpoints;
+  for (let index = 0; index < backendDescriptors.length; index++) {
+    const descriptor = backendDescriptors[index] || {};
+    const id = safeContractName(descriptor.id, `backend-${index + 1}`);
+    const candidates = descriptorFiles(descriptor).slice().sort();
+    if (candidates.length > limits.maxBackendFiles) completeness.push(`${id}: backend file cap reached`);
+    const detected = Array.isArray(descriptor.endpoints)
+      ? descriptor.endpoints
+      : detectEndpoints(descriptor.repoRoot, candidates.slice(0, limits.maxBackendFiles));
+    const filtered = detected
+      .filter((endpoint) => normalizeHttpContractPath(endpoint?.path) && normalizeContractFile(endpoint?.file) && endpointFilter(endpoint, id, { method, path: input.path, changedFiles }))
+      .sort((left, right) => left.path.localeCompare(right.path) || left.method.localeCompare(right.method) || String(left.file).localeCompare(String(right.file)) || Number(left.line) - Number(right.line));
+    if (filtered.length > endpointBudget) completeness.push(`${id}: endpoint cap reached`);
+    const accepted = filtered.slice(0, endpointBudget);
+    endpointBudget -= accepted.length;
+    backends.push({ id, endpoints: accepted, graph: descriptor.graph });
+  }
+
+  const clients = [];
+  for (let index = 0; index < clientDescriptors.length; index++) {
+    const descriptor = clientDescriptors[index] || {};
+    const id = safeContractName(descriptor.id, `client-${index + 1}`);
+    const detected = detectHttpClientCalls(descriptor.repoRoot, descriptorFiles(descriptor), {
+      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`);
+    for (const reason of detected.reasons || []) completeness.push(`${id}: ${reason}`);
+    clients.push({
+      id,
+      calls: detected.calls,
+      reverse: reverseRuntimeImports(descriptor.graph),
+      filesScanned: detected.filesScanned,
+      wrapperDiscovery: detected.discovery,
+    });
+  }
+
+  const results = [];
+  let matches = 0, methodMismatches = 0, callsiteCapReached = false;
+  for (const backend of backends) {
+    for (const endpoint of backend.endpoints) {
+      const callsites = [];
+      for (const client of clients) {
+        for (const call of client.calls) {
+          if (call.path && !methodMatches(endpoint.method, call.method)) {
+            const expected = pathSegments(normalizeHttpContractPath(endpoint.path));
+            const actual = pathSegments(call.path);
+            if (routeShapeMatches(expected, actual) || suffixShapeMatch(expected, actual)) methodMismatches++;
+            continue;
+          }
+          const match = matchHttpContract(endpoint, call);
+          if (!match) continue;
+          if (matches >= limits.maxMatches || callsites.length >= limits.maxCallsitesPerEndpoint) {
+            callsiteCapReached = true;
+            continue;
+          }
+          matches++;
+          callsites.push({
+            clientRepo: client.id,
+            file: call.file,
+            line: call.line,
+            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),
+        ...handlerEvidence,
+        file: normalizeContractFile(endpoint.file) || null,
+        line: Number(endpoint.line) || null,
+        callsites,
+        liveness: externalUseLiveness(callsites, handlerEvidence),
+        affected: affectedForEndpoint(callsites, clients, limits),
+      });
+    }
+  }
+  if (callsiteCapReached) completeness.push("match or per-endpoint callsite cap reached");
+
+  const uncertainAll = clients.flatMap((client) => client.calls
+    .filter((call) => !call.path || call.unknownPrefix || call.partialDynamic || call.method === "UNKNOWN")
+    .map((call) => ({
+      clientRepo: client.id,
+      file: call.file,
+      line: call.line,
+      method: call.method,
+      reason: call.reason || "URL retains an unresolved dynamic component",
+    })))
+    .sort((left, right) => left.clientRepo.localeCompare(right.clientRepo) || left.file.localeCompare(right.file) || left.line - right.line);
+  if (uncertainAll.length > limits.maxUncertain) completeness.push("uncertain callsite cap reached");
+  if (results.some((endpoint) => !endpoint.affected.complete)) completeness.push("affected-file traversal cap reached");
+
+  return {
+    httpContractsV: HTTP_CONTRACTS_V,
+    status: completeness.length ? "partial" : "complete",
+    filters: { method, path: input.path ? normalizeHttpContractPath(input.path) : null, changedFiles: [...changedFiles].sort() },
+    limits,
+    completeness: { complete: completeness.length === 0, reasons: [...new Set(completeness)] },
+    totals: {
+      backends: backends.length,
+      clients: clients.length,
+      endpoints: results.length,
+      clientCalls: clients.reduce((sum, client) => sum + client.calls.length, 0),
+      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/analysis/http-contracts/client-call-detection.js

@@ -0,0 +1,81 @@
+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 {
+  discoverHttpWrappers,
+  loadHttpContractConfig,
+  normalizeHttpClientNames,
+  normalizeHttpWrapperDescriptors,
+} from "../http-contract-wrappers.js";
+import { wrapperScopeFiles } from "./graph-context.js";
+import { extractHttpClientCallsFromText } from "./client-call-parser.js";
+import {
+  HTTP_CONTRACT_DEFAULTS,
+  HTTP_CONTRACT_HARD_LIMITS,
+  boundedInteger,
+  normalizeContractFile,
+} from "./shared.js";
+
+export function detectHttpClientCalls(repoRoot, codeFiles, options = {}) {
+  const boundary = createRepoBoundary(repoRoot);
+  if (!boundary.root) return { calls: [], truncated: false, filesScanned: 0, discovery: { enabled: false, configured: 0, discovered: 0, ambiguous: [] }, reasons: [] };
+  const maxFiles = boundedInteger(options.maxFiles, HTTP_CONTRACT_DEFAULTS.maxClientFiles, 1, HTTP_CONTRACT_HARD_LIMITS.maxClientFiles);
+  const maxCalls = boundedInteger(options.maxCalls, HTTP_CONTRACT_DEFAULTS.maxCallsPerClient, 1, HTTP_CONTRACT_HARD_LIMITS.maxCallsPerClient);
+  const ignoreRules = loadWeavatrixIgnore(boundary.root);
+  const classifier = createPathClassifier(boundary.root);
+  const candidates = [...new Set((codeFiles || []).map((entry) => normalizeContractFile(entry?.path || entry)).filter(Boolean))].sort();
+  let truncated = candidates.length > maxFiles;
+  let filesScanned = 0;
+  const sources = [], calls = [];
+  for (const file of candidates.slice(0, maxFiles)) {
+    if (!/\.(?:[cm]?[jt]sx?|vue|svelte)$/i.test(file) || isWeavatrixIgnored(file, ignoreRules)) continue;
+    const classification = classifier.explain(file, { content: "" });
+    if (classification.excluded || (!options.includeTests && hasPathClass(classification, "test", "e2e"))) continue;
+    const resolved = boundary.resolve(file);
+    if (!resolved.ok) continue;
+    const text = safeRead(resolved.path);
+    if (!text) continue;
+    filesScanned++;
+    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,
+      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)));
+  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,
+  };
+}

package/src/analysis/http-contracts/client-call-parser.js

@@ -0,0 +1,255 @@
+import { DEFAULT_HTTP_CLIENT_NAMES, normalizeHttpClientNames, normalizeHttpWrapperDescriptors } from "../http-contract-wrappers.js";
+import {
+  HTTP_CONTRACT_DEFAULTS,
+  HTTP_CONTRACT_HARD_LIMITS,
+  boundedInteger,
+  contractLineAt,
+  normalizeContractFile,
+  normalizeHttpContractPath,
+} from "./shared.js";
+
+function maskNonCode(text) {
+  const chars = String(text || "").split("");
+  let index = 0;
+  while (index < chars.length) {
+    const char = chars[index], next = chars[index + 1];
+    if (char === "/" && next === "/") {
+      chars[index++] = " "; chars[index++] = " ";
+      while (index < chars.length && chars[index] !== "\n") chars[index++] = " ";
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      chars[index++] = " "; chars[index++] = " ";
+      while (index < chars.length) {
+        if (chars[index] === "*" && chars[index + 1] === "/") { chars[index++] = " "; chars[index++] = " "; break; }
+        if (chars[index] !== "\n") chars[index] = " ";
+        index++;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      chars[index++] = " ";
+      while (index < chars.length) {
+        if (chars[index] === "\\") {
+          chars[index++] = " ";
+          if (index < chars.length && chars[index] !== "\n") chars[index] = " ";
+          index++;
+          continue;
+        }
+        const closes = chars[index] === quote;
+        if (chars[index] !== "\n") chars[index] = " ";
+        index++;
+        if (closes) break;
+      }
+      continue;
+    }
+    index++;
+  }
+  return chars.join("");
+}
+
+function quotedArgument(text, start, quote) {
+  let value = "";
+  for (let index = start + 1; index < text.length; index++) {
+    const char = text[index];
+    if (char === "\\") {
+      if (index + 1 >= text.length) break;
+      value += text[++index];
+      continue;
+    }
+    if (char === quote) return { value, endIndex: index + 1 };
+    if (char === "\n" || char === "\r") break;
+    value += char;
+  }
+  return null;
+}
+
+function templateArgument(text, start, constants = null, requireStatic = false) {
+  let value = "", dynamicSegments = 0, unknownPrefix = false, partialDynamic = false;
+  for (let index = start + 1; index < text.length; index++) {
+    const char = text[index];
+    if (char === "\\") {
+      if (index + 1 >= text.length) break;
+      value += text[++index];
+      continue;
+    }
+    if (char === "`") return { value, endIndex: index + 1, dynamicSegments, unknownPrefix, partialDynamic };
+    if (char !== "$" || text[index + 1] !== "{") { value += char; continue; }
+    let cursor = index + 2, depth = 1, quote = null;
+    while (cursor < text.length && depth > 0) {
+      const token = text[cursor];
+      if (quote) {
+        if (token === "\\") cursor += 2;
+        else { if (token === quote) quote = null; cursor++; }
+        continue;
+      }
+      if (token === "'" || token === '"' || token === "`") { quote = token; cursor++; continue; }
+      if (token === "{") depth++;
+      else if (token === "}") depth--;
+      cursor++;
+    }
+    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 === "`";
+    dynamicSegments++;
+    if (value === "" && next === "/") unknownPrefix = true;
+    else if (leftBoundary && rightBoundary) value += ":param";
+    else { value += ":dynamic"; partialDynamic = true; }
+    index = cursor - 1;
+  }
+  return null;
+}
+
+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++;
+    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);
+  }
+  for (let pass = 0; pass < Math.min(8, declarations.length); pass++) {
+    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++) {
+    const char = text[index];
+    if (current === target && !/\s|,/.test(char)) return index;
+    if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      for (index++; index < text.length; index++) {
+        if (text[index] === "\\") index++;
+        else if (text[index] === quote) break;
+      }
+      continue;
+    }
+    if (char === "(") round++;
+    else if (char === "[") square++;
+    else if (char === "{") curly++;
+    else if (char === ")") {
+      if (round === 0 && square === 0 && curly === 0) return null;
+      round--;
+    } else if (char === "]") square--;
+    else if (char === "}") curly--;
+    else if (char === "," && round === 0 && square === 0 && curly === 0) current++;
+  }
+  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++;
+  const quote = text[start];
+  if (quote === "'" || quote === '"') {
+    const parsed = quotedArgument(text, start, quote);
+    if (!parsed) return { path: null, endIndex: start, kind: "dynamic", dynamic: true, reason: "unterminated URL literal" };
+    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, constants);
+    if (!parsed) return { path: null, endIndex: start, kind: "dynamic", dynamic: true, reason: "unterminated URL template" };
+    return {
+      path: normalizeHttpContractPath(parsed.value), endIndex: parsed.endIndex,
+      kind: parsed.dynamicSegments ? "template" : "literal", dynamic: parsed.dynamicSegments > 0,
+      unknownPrefix: parsed.unknownPrefix, partialDynamic: parsed.partialDynamic,
+      reason: parsed.partialDynamic ? "URL template contains a partial dynamic segment" : null,
+    };
+  }
+  return { path: null, endIndex: start, kind: "dynamic", dynamic: true, unknownPrefix: false, partialDynamic: true, reason: "URL argument is not a string or template literal" };
+}
+
+function fetchMethod(text, argumentEnd) {
+  const tail = text.slice(argumentEnd, argumentEnd + 500);
+  if (!/^\s*,/.test(tail)) return { method: "GET", uncertain: false };
+  const config = tail.replace(/^\s*,\s*/, "");
+  if (!config.startsWith("{") || /^\{\s*\.\.\./.test(config)) return { method: "UNKNOWN", uncertain: true };
+  const literal = /\bmethod\s*:\s*(["'`])(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\1/i.exec(tail);
+  if (literal) return { method: literal[2].toUpperCase(), uncertain: false };
+  return /\bmethod\s*:/.test(tail) ? { method: "UNKNOWN", uncertain: true } : { method: "GET", uncertain: false };
+}
+
+function normalizedClientNames(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, HTTP_CONTRACT_DEFAULTS.maxCallsPerClient, 1, HTTP_CONTRACT_HARD_LIMITS.maxCallsPerClient);
+  const calls = [], seen = new Set();
+  let truncated = 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, constants, urlArgument);
+    const fetchInfo = fetch ? fetchMethod(source, parsed.endIndex) : { method: method.toUpperCase(), uncertain: false };
+    calls.push({
+      file: normalizeContractFile(file), line: contractLineAt(source, openParen), client: clientName, method: fetchInfo.method,
+      path: parsed.path, kind: parsed.kind, dynamic: parsed.dynamic, 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*(?:<[^>\n]{1,200}>)?\s*\(/gim;
+  let match;
+  while ((match = member.exec(mask))) if (allowed.has(match[2].toLowerCase())) add(match[2], match[3], member.lastIndex - 1);
+  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(normalizeContractFile(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 };
+}