auditor-lambda 0.6.9 → 0.6.11

package/dist/extractors/graph.js

@@ -4,9 +4,12 @@ import { posix } from "node:path";
 import { buildDispositionMap, isAuditExcludedStatus } from "./disposition.js";
 import { extractChromeExtensionManifestEdges, extractHtmlResourceEdges, } from "./browserExtension.js";
 import { extractCargoWorkspaceMemberEdges, extractGoWorkspaceModuleEdges, extractMavenModuleEdges, extractPackageEntrypointEdges, extractPackageScriptEdges, extractPyprojectTestpathLinks, extractTypescriptProjectReferenceEdges, extractWorkspacePackageEdges, extractYamlPathReferenceEdges, isCargoManifestPath, isGoWorkspaceManifestPath, isMavenPomPath, isPyprojectPath, } from "./graphManifestEdges.js";
-import { graphEdge, graphLookupKey, normalizeGraphPath, resolveCandidate, } from "./graphPathUtils.js";
-import { extractPythonImportEdges, isPythonSourcePath, } from "./graphPythonImports.js";
+import { graphEdge, graphLookupKey, isPytestConftestPath, normalizeGraphPath, resolveCandidate, resolveReferenceLiteral, resolveSpecifier, SOURCE_EXTENSIONS, STRING_LITERAL_PATTERN, } from "./graphPathUtils.js";
+import { extractPythonImportEdges } from "./graphPythonImports.js";
 import { isTestPath, normalizeExtractorPath } from "./pathPatterns.js";
+import { extractConventionalRouteEvidence, extractFrameworkRouteEvidence, extractRegisteredRouteEvidence, fallbackRouteEdge, uniqueSortedRoutes, } from "./graphRoutes.js";
+import { extractBoundedSuiteEdges, extractJsonSchemaReferenceEdges, extractSchemaContractTestEdges, } from "./graphSuites.js";
+import { extractTestSourceEdges } from "./graphTestSources.js";
 const MAX_GRAPH_SOURCE_BYTES = 512 * 1024;
 const SOURCE_LANGUAGES = new Set([
     "typescript",
@@ -20,43 +23,6 @@ const SOURCE_LANGUAGES = new Set([
     "java",
     "csharp",
 ]);
-const SOURCE_EXTENSIONS = [
-    ".ts",
-    ".tsx",
-    ".mts",
-    ".cts",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs",
-    ".json",
-    ".html",
-    ".htm",
-    ".yml",
-    ".yaml",
-    ".py",
-    ".pyi",
-    ".go",
-    ".rs",
-    ".java",
-    ".cs",
-];
-const TYPESCRIPT_TYPE_CONTRACT_EXTENSIONS = [
-    ".ts",
-    ".tsx",
-    ".mts",
-    ".cts",
-];
-const PACKAGE_SCRIPT_SUITE_EXTENSIONS = [
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs",
-    ".ts",
-    ".tsx",
-    ".mts",
-    ".cts",
-];
 const IMPORT_PATTERNS = [
     {
         pattern: /\bimport\s+(?:type\s+)?(?:[^"'()]*?\s+from\s+)?["']([^"']+)["']/g,
@@ -75,55 +41,13 @@ const IMPORT_PATTERNS = [
         kind: "commonjs",
     },
 ];
-const STRING_LITERAL_PATTERN = /["'`]([^"'`\r\n]{1,260})["'`]/g;
 const IMPORT_EDGE_CONFIDENCE = 0.95;
 const REFERENCE_EDGE_CONFIDENCE = 0.72;
 const RELATIVE_REFERENCE_EDGE_CONFIDENCE = 0.82;
-const TEST_SOURCE_EDGE_CONFIDENCE = 0.88;
 const CONFTEST_LINK_CONFIDENCE = 0.85;
 const ANALYZER_OWNERSHIP_EDGE_CONFIDENCE = 0.84;
-const JSON_SCHEMA_REF_EDGE_CONFIDENCE = 0.93;
-const SCHEMA_CONTRACT_TEST_EDGE_CONFIDENCE = 0.86;
-const SCHEMA_SUITE_EDGE_CONFIDENCE = 0.78;
-const GITHUB_WORKFLOW_SUITE_EDGE_CONFIDENCE = 0.78;
-const PACKAGE_SCRIPT_SUITE_EDGE_CONFIDENCE = 0.78;
-const TYPESCRIPT_TYPE_SUITE_EDGE_CONFIDENCE = 0.78;
-const PYTHON_TEST_UTIL_SUITE_EDGE_CONFIDENCE = 0.72;
-const PYTHON_TEST_UTIL_SEGMENT_NAMES = new Set(["utils", "helpers", "support"]);
-const ROUTE_HANDLER_EDGE_CONFIDENCE = 0.92;
 const CONTAINER_EDGE_CONFIDENCE = 0.25;
 const AUTH_SESSION_EDGE_CONFIDENCE = 0.55;
-const MAX_BOUNDED_SUITE_EDGE_FILES = 12;
-const MAX_BOUNDED_TYPE_SUITE_EDGE_FILES = 16;
-const MAX_TYPE_CONTRACT_SOURCE_BYTES = 64 * 1024;
-const TOP_LEVEL_TEST_SEGMENTS = new Set(["test", "tests", "spec", "specs"]);
-const COLOCATED_TEST_SEGMENTS = new Set([
-    "__test__",
-    "__tests__",
-    "__spec__",
-    "__specs__",
-    "test",
-    "tests",
-    "spec",
-    "specs",
-]);
-const ROUTE_REGISTRATION_PATTERN = /\b(?:app|router|server|fastify)\s*\.\s*(get|post|put|patch|delete|del|options|head|all)\s*\(\s*["'`]([^"'`]+)["'`]\s*,\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)/gi;
-const ROUTE_OBJECT_PATTERN = /\b(?:app|router|server|fastify)\s*\.\s*route\s*\(\s*\{([\s\S]{0,1200}?)\}\s*\)/gi;
-const ROUTE_METHOD_EXPORT_PATTERN = /\bexport\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/g;
-const ROUTE_METHODS = new Set([
-    "GET",
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "OPTIONS",
-    "HEAD",
-    "ALL",
-]);
-const IMPORT_BINDING_PATTERN = /\bimport\s+(?:type\s+)?([^;"'](?:[^;]*?))\s+from\s+["']([^"']+)["']/g;
-const REQUIRE_BINDING_PATTERN = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*["']([^"']+)["']\s*\)/g;
-const REQUIRE_DESTRUCTURING_PATTERN = /\b(?:const|let|var)\s*\{([^}]+)\}\s*=\s*require\s*\(\s*["']([^"']+)["']\s*\)/g;
-const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;
 function shouldReadForGraph(file) {
     const normalized = normalizeGraphPath(file.path);
     return (file.size_bytes <= MAX_GRAPH_SOURCE_BYTES &&
@@ -142,23 +66,6 @@ export function buildPathLookup(repoManifest, dispositionMap) {
     })
         .map((file) => [graphLookupKey(file.path), file.path]));
 }
-function resolveSpecifier(fromPath, specifier, pathLookup) {
-    if (!specifier.startsWith(".")) {
-        return undefined;
-    }
-    const baseDir = posix.dirname(normalizeGraphPath(fromPath));
-    return resolveCandidate(posix.join(baseDir, specifier), pathLookup);
-}
-function resolveReferenceLiteral(fromPath, literal, pathLookup) {
-    const normalizedLiteral = normalizeGraphPath(literal);
-    if (literal.startsWith(".")) {
-        return resolveSpecifier(fromPath, literal, pathLookup);
-    }
-    if (!normalizedLiteral.includes("/")) {
-        return undefined;
-    }
-    return resolveCandidate(normalizedLiteral, pathLookup);
-}
 function edgeSignature(edge) {
     return `${edge.from}\0${edge.to}\0${edge.kind ?? ""}`;
 }
@@ -241,103 +148,6 @@ function extractAnalyzerOwnershipEdges(externalAnalyzerResults, pathLookup) {
     }
     return edges;
 }
-function routeSignature(route) {
-    return `${route.method ?? ""}\0${route.path}\0${route.handler}`;
-}
-function uniqueSortedRoutes(routes) {
-    const deduped = new Map();
-    for (const route of routes) {
-        deduped.set(routeSignature(route), route);
-    }
-    return [...deduped.values()].sort((a, b) => a.path.localeCompare(b.path) ||
-        a.handler.localeCompare(b.handler) ||
-        (a.method ?? "").localeCompare(b.method ?? ""));
-}
-function normalizeRoutePath(routePath) {
-    const trimmed = routePath.trim();
-    if (trimmed === "*" || trimmed === "/*") {
-        return trimmed;
-    }
-    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-    return prefixed.replace(/\/{2,}/g, "/");
-}
-function normalizeHttpMethod(method) {
-    const upper = method.toUpperCase();
-    return upper === "DEL" ? "DELETE" : upper;
-}
-function isIdentifier(value) {
-    return typeof value === "string" && IDENTIFIER_PATTERN.test(value);
-}
-function addImportBinding(bindings, localName, binding) {
-    if (isIdentifier(localName)) {
-        bindings.set(localName, binding);
-    }
-}
-function parseNamedImportLocal(rawName) {
-    const normalized = rawName.trim().replace(/^type\s+/i, "").trim();
-    if (!normalized) {
-        return undefined;
-    }
-    const [, aliasedName] = normalized.split(/\s+as\s+/i);
-    const localName = (aliasedName ?? normalized.split(/\s*:\s*/).at(-1) ?? "")
-        .trim()
-        .replace(/=.*$/, "")
-        .trim();
-    return isIdentifier(localName) ? localName : undefined;
-}
-function addNamedImportBindings(bindings, rawBindings, binding) {
-    for (const rawName of rawBindings.split(",")) {
-        addImportBinding(bindings, parseNamedImportLocal(rawName), binding);
-    }
-}
-function extractImportBindings(fromPath, content, pathLookup) {
-    const bindings = new Map();
-    IMPORT_BINDING_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(IMPORT_BINDING_PATTERN)) {
-        const clause = match[1]?.trim();
-        const specifier = match[2];
-        if (!clause || !specifier)
-            continue;
-        const target = resolveSpecifier(fromPath, specifier, pathLookup);
-        if (!target)
-            continue;
-        const binding = { target, specifier };
-        const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
-        addImportBinding(bindings, namespaceMatch?.[1], binding);
-        const namedMatch = clause.match(/\{([^}]*)\}/);
-        if (namedMatch?.[1]) {
-            addNamedImportBindings(bindings, namedMatch[1], binding);
-        }
-        const defaultCandidate = clause
-            .split(/[,{]/, 1)[0]
-            ?.trim()
-            .replace(/^type\s+/i, "");
-        addImportBinding(bindings, defaultCandidate, binding);
-    }
-    REQUIRE_BINDING_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(REQUIRE_BINDING_PATTERN)) {
-        const localName = match[1];
-        const specifier = match[2];
-        if (!localName || !specifier)
-            continue;
-        const target = resolveSpecifier(fromPath, specifier, pathLookup);
-        if (target) {
-            addImportBinding(bindings, localName, { target, specifier });
-        }
-    }
-    REQUIRE_DESTRUCTURING_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(REQUIRE_DESTRUCTURING_PATTERN)) {
-        const rawBindings = match[1];
-        const specifier = match[2];
-        if (!rawBindings || !specifier)
-            continue;
-        const target = resolveSpecifier(fromPath, specifier, pathLookup);
-        if (target) {
-            addNamedImportBindings(bindings, rawBindings, { target, specifier });
-        }
-    }
-    return bindings;
-}
 function extractImportEdges(fromPath, content, pathLookup) {
     const edges = [];
     for (const { pattern, kind } of IMPORT_PATTERNS) {
@@ -416,636 +226,6 @@ function extractReferenceEdges(fromPath, content, pathLookup) {
     }
     return edges;
 }
-function isJsonSchemaPath(path) {
-    return posix
-        .basename(normalizeGraphPath(path))
-        .toLowerCase()
-        .endsWith(".schema.json");
-}
-function collectJsonSchemaRefs(value, refs) {
-    if (Array.isArray(value)) {
-        for (const item of value) {
-            collectJsonSchemaRefs(item, refs);
-        }
-        return;
-    }
-    if (value === null || typeof value !== "object") {
-        return;
-    }
-    for (const [key, item] of Object.entries(value)) {
-        if (key === "$ref" && typeof item === "string" && item.trim().length > 0) {
-            refs.add(item.trim());
-            continue;
-        }
-        collectJsonSchemaRefs(item, refs);
-    }
-}
-function resolveJsonSchemaRef(fromPath, ref, pathLookup) {
-    const targetSpecifier = (ref.split("#", 1)[0] ?? "").trim();
-    if (targetSpecifier.length === 0) {
-        return undefined;
-    }
-    const normalizedSpecifier = normalizeGraphPath(targetSpecifier);
-    if (normalizedSpecifier.startsWith("/") ||
-        /^[a-z][a-z0-9+.-]*:/i.test(normalizedSpecifier)) {
-        return undefined;
-    }
-    const baseDir = posix.dirname(normalizeGraphPath(fromPath));
-    const candidate = targetSpecifier.startsWith(".") || !normalizedSpecifier.includes("/")
-        ? posix.join(baseDir, normalizedSpecifier)
-        : normalizedSpecifier;
-    return resolveCandidate(candidate, pathLookup);
-}
-function extractJsonSchemaReferenceEdges(fromPath, content, pathLookup) {
-    if (!isJsonSchemaPath(fromPath)) {
-        return [];
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(content);
-    }
-    catch {
-        return [];
-    }
-    const refs = new Set();
-    collectJsonSchemaRefs(parsed, refs);
-    const edges = [];
-    for (const ref of refs) {
-        const target = resolveJsonSchemaRef(fromPath, ref, pathLookup);
-        if (!target || target === fromPath) {
-            continue;
-        }
-        edges.push(graphEdge({
-            from: fromPath,
-            to: target,
-            kind: "json-schema-ref",
-            confidence: JSON_SCHEMA_REF_EDGE_CONFIDENCE,
-            reason: `JSON Schema $ref '${ref}' resolves to '${target}'.`,
-        }));
-    }
-    return edges;
-}
-function extractSchemaContractTestEdges(fromPath, content, pathLookup) {
-    if (!isTestPath(normalizeExtractorPath(fromPath)) ||
-        !/schema/i.test(fromPath) ||
-        !/\.schema\.json/i.test(content)) {
-        return [];
-    }
-    const literalBasenames = new Set();
-    STRING_LITERAL_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(STRING_LITERAL_PATTERN)) {
-        const literal = match[1];
-        if (!literal || !literal.toLowerCase().endsWith(".schema.json")) {
-            continue;
-        }
-        literalBasenames.add(posix.basename(normalizeGraphPath(literal)).toLowerCase());
-    }
-    if (literalBasenames.size === 0 ||
-        literalBasenames.size > MAX_BOUNDED_SUITE_EDGE_FILES) {
-        return [];
-    }
-    const targets = [...new Set(pathLookup.values())]
-        .filter((path) => {
-        const normalized = normalizeGraphPath(path);
-        return (isJsonSchemaPath(normalized) &&
-            literalBasenames.has(posix.basename(normalized).toLowerCase()));
-    })
-        .sort((a, b) => a.localeCompare(b));
-    if (targets.length > MAX_BOUNDED_SUITE_EDGE_FILES) {
-        return [];
-    }
-    return targets.map((target) => graphEdge({
-        from: fromPath,
-        to: target,
-        kind: "schema-contract-test-link",
-        confidence: SCHEMA_CONTRACT_TEST_EDGE_CONFIDENCE,
-        reason: `Schema contract test references '${posix.basename(target)}'.`,
-    }));
-}
-function isGithubWorkflowPath(path) {
-    const normalized = normalizeGraphPath(path).toLowerCase();
-    return (normalized.startsWith(".github/workflows/") &&
-        (normalized.endsWith(".yml") || normalized.endsWith(".yaml")));
-}
-function isTypescriptTypeContractPath(path, fileContents) {
-    const normalized = normalizeGraphPath(path);
-    const segments = normalized.split("/").filter(Boolean);
-    if (!segments.includes("types") ||
-        isTestPath(normalizeExtractorPath(normalized)) ||
-        !TYPESCRIPT_TYPE_CONTRACT_EXTENSIONS.some((extension) => normalized.endsWith(extension))) {
-        return false;
-    }
-    const content = fileContents[path];
-    if (!content || content.length > MAX_TYPE_CONTRACT_SOURCE_BYTES) {
-        return false;
-    }
-    return /\bexport\s+(?:declare\s+)?(?:interface|type|enum|const)\b/.test(content);
-}
-function packageScriptSuiteDirectories(graphEdges) {
-    const directories = new Set();
-    for (const edge of graphEdges) {
-        if (edge.kind !== "package-script-link") {
-            continue;
-        }
-        const directory = posix.dirname(normalizeGraphPath(edge.to));
-        const basename = posix.basename(directory);
-        if (basename === "scripts" || basename === "bin") {
-            directories.add(directory);
-        }
-    }
-    return directories;
-}
-function isPackageScriptSuitePath(path, suiteDirectories) {
-    const normalized = normalizeGraphPath(path);
-    return (suiteDirectories.has(posix.dirname(normalized)) &&
-        PACKAGE_SCRIPT_SUITE_EXTENSIONS.some((extension) => normalized.endsWith(extension)));
-}
-function isPythonTestUtilSuitePath(path) {
-    const normalized = normalizeGraphPath(path);
-    if (!normalized.endsWith(".py"))
-        return false;
-    if (isPytestConftestPath(normalized))
-        return false;
-    const dir = posix.dirname(normalized);
-    if (!PYTHON_TEST_UTIL_SEGMENT_NAMES.has(posix.basename(dir).toLowerCase()))
-        return false;
-    return isTestPath(normalizeExtractorPath(dir));
-}
-function extractBoundedSuiteEdges(pathLookup, fileContents, graphEdges) {
-    const files = [...new Set(pathLookup.values())].sort((a, b) => a.localeCompare(b));
-    const edges = [];
-    const scriptSuiteDirectories = packageScriptSuiteDirectories(graphEdges);
-    const addSuiteEdges = (params) => {
-        const groups = new Map();
-        for (const file of files) {
-            if (!params.predicate(file)) {
-                continue;
-            }
-            const directory = posix.dirname(normalizeGraphPath(file));
-            const group = groups.get(directory) ?? [];
-            group.push(file);
-            groups.set(directory, group);
-        }
-        for (const [directory, group] of groups) {
-            const maxFiles = params.maxFiles ?? MAX_BOUNDED_SUITE_EDGE_FILES;
-            if (group.length < 2 ||
-                group.length > maxFiles) {
-                continue;
-            }
-            const suiteName = directory === "." ? "repository root" : directory;
-            for (let index = 1; index < group.length; index++) {
-                edges.push(graphEdge({
-                    from: group[index - 1],
-                    to: group[index],
-                    kind: params.kind,
-                    direction: "undirected",
-                    confidence: params.confidence,
-                    reason: `${params.label} suite '${suiteName}' groups ${group.length} related file(s).`,
-                }));
-            }
-        }
-    };
-    addSuiteEdges({
-        predicate: isJsonSchemaPath,
-        kind: "schema-suite-link",
-        confidence: SCHEMA_SUITE_EDGE_CONFIDENCE,
-        label: "JSON Schema",
-    });
-    addSuiteEdges({
-        predicate: isGithubWorkflowPath,
-        kind: "github-workflow-suite-link",
-        confidence: GITHUB_WORKFLOW_SUITE_EDGE_CONFIDENCE,
-        label: "GitHub Actions workflow",
-    });
-    addSuiteEdges({
-        predicate: (path) => isPackageScriptSuitePath(path, scriptSuiteDirectories),
-        kind: "package-script-suite-link",
-        confidence: PACKAGE_SCRIPT_SUITE_EDGE_CONFIDENCE,
-        label: "Package script",
-    });
-    addSuiteEdges({
-        predicate: (path) => isTypescriptTypeContractPath(path, fileContents),
-        kind: "typescript-type-suite-link",
-        confidence: TYPESCRIPT_TYPE_SUITE_EDGE_CONFIDENCE,
-        label: "TypeScript type contract",
-        maxFiles: MAX_BOUNDED_TYPE_SUITE_EDGE_FILES,
-    });
-    addSuiteEdges({
-        predicate: isPythonTestUtilSuitePath,
-        kind: "python-test-util-suite-link",
-        confidence: PYTHON_TEST_UTIL_SUITE_EDGE_CONFIDENCE,
-        label: "Python test utility",
-    });
-    return edges;
-}
-function importedHandlerBinding(handlerExpression, bindings) {
-    const rootIdentifier = handlerExpression.split(".")[0];
-    return rootIdentifier ? bindings.get(rootIdentifier) : undefined;
-}
-function addRouteEvidence(params) {
-    const method = params.method ? normalizeHttpMethod(params.method) : undefined;
-    if (method && !ROUTE_METHODS.has(method)) {
-        return;
-    }
-    const handlerBinding = params.handlerExpression
-        ? importedHandlerBinding(params.handlerExpression, params.bindings)
-        : undefined;
-    const handlerPath = handlerBinding?.target ?? params.fromPath;
-    const route = {
-        path: normalizeRoutePath(params.routePath),
-        handler: handlerPath,
-    };
-    if (method) {
-        route.method = method;
-    }
-    params.routes.push(route);
-    if (handlerBinding && handlerPath !== params.fromPath) {
-        params.calls.push(graphEdge({
-            from: params.fromPath,
-            to: handlerPath,
-            kind: "route-handler-link",
-            confidence: ROUTE_HANDLER_EDGE_CONFIDENCE,
-            reason: `Route ${method ?? "handler"} '${route.path}' passes handler '${params.handlerExpression}' from '${handlerBinding.specifier}'.`,
-        }));
-    }
-}
-function extractRegisteredRouteEvidence(fromPath, content, pathLookup) {
-    const bindings = extractImportBindings(fromPath, content, pathLookup);
-    const calls = [];
-    const routes = [];
-    ROUTE_REGISTRATION_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(ROUTE_REGISTRATION_PATTERN)) {
-        const method = match[1];
-        const routePath = match[2];
-        const handlerExpression = match[3];
-        if (!method || !routePath)
-            continue;
-        addRouteEvidence({
-            fromPath,
-            routes,
-            calls,
-            method,
-            routePath,
-            handlerExpression,
-            bindings,
-        });
-    }
-    ROUTE_OBJECT_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(ROUTE_OBJECT_PATTERN)) {
-        const body = match[1];
-        if (!body)
-            continue;
-        const method = body.match(/\bmethod\s*:\s*["'`]([A-Za-z]+)["'`]/i)?.[1];
-        const routePath = body.match(/\b(?:url|path)\s*:\s*["'`]([^"'`]+)["'`]/i)?.[1];
-        const handlerExpression = body.match(/\bhandler\s*:\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)/)?.[1];
-        if (!routePath)
-            continue;
-        addRouteEvidence({
-            fromPath,
-            routes,
-            calls,
-            method,
-            routePath,
-            handlerExpression,
-            bindings,
-        });
-    }
-    return { calls, routes };
-}
-function stripSourceExtension(path) {
-    const lowerPath = path.toLowerCase();
-    const extension = SOURCE_EXTENSIONS.find((item) => lowerPath.endsWith(item));
-    return extension ? path.slice(0, -extension.length) : path;
-}
-function nextRouteSegment(segment) {
-    if (!segment || (segment.startsWith("(") && segment.endsWith(")"))) {
-        return undefined;
-    }
-    const catchAll = segment.match(/^\[\.\.\.(.+)\]$/);
-    if (catchAll?.[1]) {
-        return `:${catchAll[1]}*`;
-    }
-    const dynamic = segment.match(/^\[(.+)\]$/);
-    if (dynamic?.[1]) {
-        return `:${dynamic[1]}`;
-    }
-    return segment;
-}
-function routePathFromSegments(segments) {
-    const routeSegments = segments
-        .map(nextRouteSegment)
-        .filter((segment) => segment !== undefined);
-    if (routeSegments.length === 0) {
-        return undefined;
-    }
-    return normalizeRoutePath(routeSegments.join("/"));
-}
-function conventionalRoutePath(filePath) {
-    const normalized = normalizeGraphPath(filePath);
-    const parts = normalized.split("/").filter(Boolean);
-    const lowerParts = parts.map((part) => part.toLowerCase());
-    const fileName = lowerParts.at(-1);
-    if (!fileName) {
-        return undefined;
-    }
-    const appIndex = lowerParts.lastIndexOf("app");
-    if (appIndex >= 0 && fileName.startsWith("route.")) {
-        return routePathFromSegments(parts.slice(appIndex + 1, -1));
-    }
-    const pagesIndex = lowerParts.lastIndexOf("pages");
-    const apiIndex = pagesIndex >= 0
-        ? lowerParts.indexOf("api", pagesIndex + 1)
-        : lowerParts.indexOf("api");
-    if (apiIndex >= 0 && apiIndex < parts.length - 1) {
-        const withoutExtension = stripSourceExtension(parts.at(-1) ?? "");
-        return routePathFromSegments([...parts.slice(apiIndex, -1), withoutExtension]);
-    }
-    return undefined;
-}
-function extractConventionalRouteEvidence(fromPath, content) {
-    const routePath = conventionalRoutePath(fromPath);
-    if (!routePath) {
-        return [];
-    }
-    const routes = [];
-    if (content) {
-        ROUTE_METHOD_EXPORT_PATTERN.lastIndex = 0;
-        for (const match of content.matchAll(ROUTE_METHOD_EXPORT_PATTERN)) {
-            const method = match[1];
-            if (method) {
-                routes.push({
-                    path: routePath,
-                    handler: fromPath,
-                    method,
-                });
-            }
-        }
-    }
-    return routes.length > 0 ? routes : [{ path: routePath, handler: fromPath }];
-}
-// ---- Phase 4A: decorator / framework route detection ----
-// Deterministic route patterns for NestJS, FastAPI, Flask, and Angular. These
-// emit only the existing RouteEdge / route-handler-link shapes — no new
-// planning-topology edge kinds. Each branch is gated on a framework marker so
-// the patterns do not fire on unrelated decorators or object literals. An
-// AST-based version can later move behind the analyzer seam; this is the
-// regex floor for these frameworks.
-const NEST_CONTROLLER_PATTERN = /@Controller\s*\(([\s\S]{0,200}?)\)/g;
-const NEST_METHOD_DECORATOR_PATTERN = /@(Get|Post|Put|Patch|Delete|Options|Head|All)\s*\(\s*(?:["'`]([^"'`]*)["'`])?/g;
-const PY_DECORATOR_METHOD_PATTERN = /@\s*[A-Za-z_]\w*\s*\.\s*(get|post|put|patch|delete|options|head|trace|websocket)\s*\(\s*["']([^"']+)["']/g;
-const PY_ROUTE_DECORATOR_PATTERN = /@\s*[A-Za-z_]\w*\s*\.\s*(api_route|route)\s*\(\s*["']([^"']+)["']([\s\S]{0,200}?)\)/g;
-const PY_METHODS_LIST_PATTERN = /methods\s*=\s*\[([^\]]*)\]/;
-const PY_METHOD_LITERAL_PATTERN = /["']([A-Za-z]+)["']/g;
-const ANGULAR_FILE_MARKER_PATTERN = /\b(?:RouterModule|provideRouter|loadChildren|loadComponent)\b|:\s*Routes\b/;
-const ANGULAR_ROUTE_OBJECT_PATTERN = /\{[^{}]*?\bpath\s*:\s*["'`]([^"'`]*)["'`][^{}]*?\}/g;
-const ANGULAR_ROUTE_KEY_PATTERN = /\b(?:component|loadChildren|loadComponent|redirectTo)\s*:/;
-const ANGULAR_COMPONENT_PATTERN = /\b(?:component|loadComponent)\s*:\s*([A-Za-z_$][\w$]*)/;
-const ANGULAR_LAZY_IMPORT_PATTERN = /\b(?:loadChildren|loadComponent)\s*:[\s\S]*?import\s*\(\s*["']([^"']+)["']\s*\)/;
-const TS_LIKE_EXTENSION_PATTERN = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
-/** Join route segments (controller prefix + method path) into one clean path. */
-function joinRouteSegments(...segments) {
-    return segments
-        .map((segment) => segment.trim().replace(/^\/+|\/+$/g, ""))
-        .filter((segment) => segment.length > 0)
-        .join("/");
-}
-/** Controller prefixes in document order, so each method can take the nearest. */
-function nestControllerPrefixes(content) {
-    const prefixes = [];
-    NEST_CONTROLLER_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(NEST_CONTROLLER_PATTERN)) {
-        const arg = match[1] ?? "";
-        const pathProp = arg.match(/\bpath\s*:\s*["'`]([^"'`]*)["'`]/);
-        const firstString = arg.match(/["'`]([^"'`]*)["'`]/);
-        const prefix = pathProp?.[1] ?? firstString?.[1] ?? "";
-        prefixes.push({ index: match.index ?? 0, prefix });
-    }
-    return prefixes;
-}
-function collectNestRoutes(fromPath, content, routes) {
-    if (!content.includes("@Controller")) {
-        return;
-    }
-    const controllers = nestControllerPrefixes(content);
-    if (controllers.length === 0) {
-        return;
-    }
-    NEST_METHOD_DECORATOR_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(NEST_METHOD_DECORATOR_PATTERN)) {
-        const method = match[1];
-        if (!method)
-            continue;
-        const subPath = match[2] ?? "";
-        const at = match.index ?? 0;
-        let prefix = "";
-        for (const controller of controllers) {
-            if (controller.index <= at)
-                prefix = controller.prefix;
-            else
-                break;
-        }
-        routes.push({
-            path: normalizeRoutePath(joinRouteSegments(prefix, subPath)),
-            handler: fromPath,
-            method: method.toUpperCase(),
-        });
-    }
-}
-function pythonRouteMethods(args) {
-    const listMatch = args.match(PY_METHODS_LIST_PATTERN);
-    if (!listMatch?.[1])
-        return [];
-    PY_METHOD_LITERAL_PATTERN.lastIndex = 0;
-    return [...listMatch[1].matchAll(PY_METHOD_LITERAL_PATTERN)].map((method) => method[1].toUpperCase());
-}
-function collectPythonFrameworkRoutes(fromPath, content, routes) {
-    // FastAPI / Starlette: @app.get("/x"), @router.post("/y"), @router.websocket("/ws")
-    PY_DECORATOR_METHOD_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(PY_DECORATOR_METHOD_PATTERN)) {
-        const verb = match[1];
-        const routePath = match[2];
-        if (!verb || !routePath)
-            continue;
-        const method = verb.toUpperCase();
-        routes.push({
-            path: normalizeRoutePath(routePath),
-            handler: fromPath,
-            method: method === "WEBSOCKET" ? "WS" : method,
-        });
-    }
-    // FastAPI api_route + Flask route: @app.route("/x", methods=["GET","POST"])
-    PY_ROUTE_DECORATOR_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(PY_ROUTE_DECORATOR_PATTERN)) {
-        const routePath = match[2];
-        if (!routePath)
-            continue;
-        const methods = pythonRouteMethods(match[3] ?? "");
-        const path = normalizeRoutePath(routePath);
-        if (methods.length === 0) {
-            routes.push({ path, handler: fromPath, method: "GET" });
-            continue;
-        }
-        for (const method of methods) {
-            routes.push({ path, handler: fromPath, method });
-        }
-    }
-}
-function collectAngularRoutes(fromPath, content, pathLookup, calls, routes) {
-    if (!ANGULAR_FILE_MARKER_PATTERN.test(content)) {
-        return;
-    }
-    const bindings = extractImportBindings(fromPath, content, pathLookup);
-    ANGULAR_ROUTE_OBJECT_PATTERN.lastIndex = 0;
-    for (const match of content.matchAll(ANGULAR_ROUTE_OBJECT_PATTERN)) {
-        const body = match[0];
-        if (!ANGULAR_ROUTE_KEY_PATTERN.test(body)) {
-            continue;
-        }
-        const routePath = normalizeRoutePath(match[1] ?? "");
-        let handlerPath = fromPath;
-        let handlerExpression;
-        const lazyImport = body.match(ANGULAR_LAZY_IMPORT_PATTERN);
-        const component = body.match(ANGULAR_COMPONENT_PATTERN);
-        if (lazyImport?.[1]) {
-            const target = resolveSpecifier(fromPath, lazyImport[1], pathLookup) ??
-                resolveReferenceLiteral(fromPath, lazyImport[1], pathLookup);
-            if (target) {
-                handlerPath = target;
-                handlerExpression = lazyImport[1];
-            }
-        }
-        else if (component?.[1]) {
-            const binding = bindings.get(component[1]);
-            if (binding) {
-                handlerPath = binding.target;
-                handlerExpression = component[1];
-            }
-        }
-        routes.push({ path: routePath, handler: handlerPath });
-        if (handlerPath !== fromPath) {
-            calls.push(graphEdge({
-                from: fromPath,
-                to: handlerPath,
-                kind: "route-handler-link",
-                confidence: ROUTE_HANDLER_EDGE_CONFIDENCE,
-                reason: `Angular route '${routePath}' maps to '${handlerExpression ?? handlerPath}'.`,
-            }));
-        }
-    }
-}
-function extractFrameworkRouteEvidence(fromPath, content, pathLookup) {
-    const normalized = normalizeGraphPath(fromPath).toLowerCase();
-    const calls = [];
-    const routes = [];
-    if (normalized.endsWith(".py")) {
-        collectPythonFrameworkRoutes(fromPath, content, routes);
-    }
-    else if (TS_LIKE_EXTENSION_PATTERN.test(normalized)) {
-        collectNestRoutes(fromPath, content, routes);
-        collectAngularRoutes(fromPath, content, pathLookup, calls, routes);
-    }
-    return { calls, routes };
-}
-function fallbackRouteEdge(filePath) {
-    const normalized = filePath.toLowerCase();
-    if (normalized.includes("api/") || normalized.includes("route")) {
-        return {
-            path: `/${filePath.replaceAll("/", "_")}`,
-            handler: filePath,
-            method: "GET",
-        };
-    }
-    return undefined;
-}
-function stripKnownSourceExtension(path) {
-    const lowerPath = path.toLowerCase();
-    const extension = SOURCE_EXTENSIONS.find((item) => lowerPath.endsWith(item));
-    if (!extension) {
-        return undefined;
-    }
-    return path.slice(0, -extension.length);
-}
-function stripTestSuffix(pathWithoutExtension) {
-    const stripped = pathWithoutExtension.replace(/[._-](?:test|spec)$/i, "");
-    return stripped === pathWithoutExtension ? undefined : stripped;
-}
-function stripPythonTestPrefix(pathWithoutExtension) {
-    const basename = posix.basename(pathWithoutExtension);
-    const match = /^test[._-](.+)$/i.exec(basename);
-    if (!match?.[1]) {
-        return undefined;
-    }
-    const directory = posix.dirname(pathWithoutExtension);
-    return directory === "." ? match[1] : posix.join(directory, match[1]);
-}
-function addTestSourceCandidatesForBase(basePath, candidates) {
-    candidates.add(basePath);
-    const parts = basePath.split("/").filter(Boolean);
-    const topLevelSegment = parts[0]?.toLowerCase();
-    if (topLevelSegment && TOP_LEVEL_TEST_SEGMENTS.has(topLevelSegment)) {
-        const mirroredParts = parts.slice(1);
-        if (mirroredParts.length > 0) {
-            candidates.add(posix.join("src", ...mirroredParts));
-        }
-    }
-    for (let index = 1; index < parts.length; index++) {
-        if (COLOCATED_TEST_SEGMENTS.has(parts[index].toLowerCase())) {
-            const colocatedParts = [
-                ...parts.slice(0, index),
-                ...parts.slice(index + 1),
-            ];
-            if (colocatedParts.length > 0) {
-                candidates.add(posix.join(...colocatedParts));
-            }
-        }
-    }
-}
-function testSourceCandidates(testPath) {
-    const normalizedPath = normalizeGraphPath(testPath);
-    const withoutExtension = stripKnownSourceExtension(normalizedPath);
-    if (!withoutExtension) {
-        return [];
-    }
-    const baseCandidates = new Set();
-    const withoutTestSuffix = stripTestSuffix(withoutExtension);
-    if (withoutTestSuffix) {
-        baseCandidates.add(withoutTestSuffix);
-    }
-    if (isPythonSourcePath(normalizedPath)) {
-        const withoutPythonPrefix = stripPythonTestPrefix(withoutExtension);
-        if (withoutPythonPrefix) {
-            baseCandidates.add(withoutPythonPrefix);
-        }
-    }
-    const candidates = new Set();
-    for (const basePath of baseCandidates) {
-        addTestSourceCandidatesForBase(basePath, candidates);
-    }
-    return [...candidates];
-}
-function extractTestSourceEdges(fromPath, pathLookup) {
-    if (!isTestPath(normalizeExtractorPath(fromPath))) {
-        return [];
-    }
-    const edges = [];
-    for (const candidate of testSourceCandidates(fromPath)) {
-        const target = resolveCandidate(candidate, pathLookup);
-        if (!target || isTestPath(normalizeExtractorPath(target))) {
-            continue;
-        }
-        edges.push(graphEdge({
-            from: fromPath,
-            to: target,
-            kind: "test-source-link",
-            confidence: TEST_SOURCE_EDGE_CONFIDENCE,
-            reason: `Test path naming maps to source path '${target}'.`,
-        }));
-    }
-    return edges;
-}
-function isPytestConftestPath(path) {
-    return posix.basename(normalizeGraphPath(path)).toLowerCase() === "conftest.py";
-}
 function extractPytestConftestLinks(pathLookup) {
     const allPaths = [...new Set(pathLookup.values())];
     const conftestPaths = allPaths.filter((p) => isPytestConftestPath(p));