@opencodehub/ingestion 0.1.0

package/dist/pipeline/phases/mro.js

@@ -0,0 +1,303 @@
+/**
+ * MRO phase — emit `METHOD_OVERRIDES` / `METHOD_IMPLEMENTS` edges by
+ * linearising each class's ancestor chain with its language-specific
+ * strategy.
+ *
+ * Strategy-per-language table:
+ *  - `python` → `c3` (raises on ambiguity; caught + skipped per-class).
+ *  - `typescript`, `tsx`, `javascript`, `rust` → `first-wins`.
+ *  - `java`, `csharp` → `single-inheritance`; interfaces drive
+ *    `METHOD_IMPLEMENTS` edges separately.
+ *  - `go` → `none`; no class-based inheritance. Skipped entirely.
+ *
+ * Determinism: parents and methods are iterated in sorted-id order, so the
+ * edge set is byte-identical across runs.
+ */
+import { getProvider } from "../../providers/registry.js";
+import { MroConflictError } from "../../providers/resolution/c3.js";
+import { getMroStrategy } from "../../providers/resolution/mro.js";
+import { CROSS_FILE_PHASE_NAME } from "./cross-file.js";
+import { buildFilePathLookup, partitionPriorEdges, resolveIncrementalView, } from "./incremental-helper.js";
+import { INCREMENTAL_SCOPE_PHASE_NAME } from "./incremental-scope.js";
+import { STRUCTURE_PHASE_NAME } from "./structure.js";
+export const MRO_PHASE_NAME = "mro";
+/**
+ * Kinds that own methods and participate in the MRO walk.
+ */
+const OWNER_KINDS = new Set(["Class", "Interface", "Struct", "Trait"]);
+export const mroPhase = {
+    name: MRO_PHASE_NAME,
+    deps: [CROSS_FILE_PHASE_NAME, STRUCTURE_PHASE_NAME, INCREMENTAL_SCOPE_PHASE_NAME],
+    async run(ctx) {
+        return runMro(ctx);
+    },
+};
+function runMro(ctx) {
+    // ---- : incremental carry-forward. -----------------------------
+    //
+    // When the incremental view is active we replay every prior-graph
+    // METHOD_OVERRIDES / METHOD_IMPLEMENTS edge whose both endpoints live
+    // outside the closure. The closure already pulled in a 1-hop heritage
+    // expansion (incremental-scope.ts lines 31-32), so any class whose
+    // ancestor moved is already in scope and will re-linearise below. Carry-
+    // forward for the rest keeps the graph hash byte-identical to a full
+    // run at the same commit (see `incremental-determinism.test.ts`).
+    const view = resolveIncrementalView(ctx);
+    if (view.active &&
+        view.previousGraph?.edges !== undefined &&
+        view.previousGraph.nodes !== undefined) {
+        const filePathByNodeId = buildFilePathLookup(view.previousGraph.nodes);
+        const carried = partitionPriorEdges(view.previousGraph.edges, filePathByNodeId, view.closure, new Set(["METHOD_OVERRIDES", "METHOD_IMPLEMENTS"]));
+        for (const e of carried) {
+            ctx.graph.addEdge({
+                from: e.from,
+                to: e.to,
+                type: e.type,
+                confidence: e.confidence,
+                ...(e.reason !== undefined ? { reason: e.reason } : {}),
+            });
+        }
+    }
+    // ---- Collect owner nodes + their methods + their heritage. -------------
+    //
+    // We always collect metadata for EVERY owner in the graph — linearisation
+    // walks ancestor chains that may reach owners outside the closure, and
+    // those still need their methods + heritage loaded so the walk terminates
+    // correctly. The incremental gate applies at edge-emission time.
+    const ownerIds = [];
+    const ownerFilePath = new Map();
+    for (const n of ctx.graph.nodes()) {
+        if (OWNER_KINDS.has(n.kind)) {
+            ownerIds.push(n.id);
+            ownerFilePath.set(n.id, n.filePath);
+        }
+    }
+    ownerIds.sort();
+    // Per-owner method map: name → method node id (one entry per name; if a
+    // class declares two overloads with the same name the last id wins for the
+    // MRO walk, which matches the `HAS_METHOD` edge set emitted at parse time).
+    const methodsByOwner = new Map();
+    const extendsByOwner = new Map();
+    const implementsByOwner = new Map();
+    for (const id of ownerIds) {
+        methodsByOwner.set(id, new Map());
+        extendsByOwner.set(id, []);
+        implementsByOwner.set(id, []);
+    }
+    const nodeKindById = new Map();
+    const nodeNameById = new Map();
+    for (const n of ctx.graph.nodes()) {
+        nodeKindById.set(n.id, n.kind);
+        nodeNameById.set(n.id, n.name);
+    }
+    for (const edge of ctx.graph.edges()) {
+        if (edge.type === "HAS_METHOD") {
+            const owner = edge.from;
+            const methodId = edge.to;
+            const name = nodeNameById.get(methodId);
+            if (name === undefined)
+                continue;
+            const map = methodsByOwner.get(owner);
+            if (map !== undefined)
+                map.set(name, methodId);
+        }
+        else if (edge.type === "EXTENDS") {
+            const list = extendsByOwner.get(edge.from);
+            if (list !== undefined)
+                list.push(edge.to);
+        }
+        else if (edge.type === "IMPLEMENTS") {
+            const list = implementsByOwner.get(edge.from);
+            if (list !== undefined)
+                list.push(edge.to);
+        }
+    }
+    for (const list of extendsByOwner.values())
+        list.sort();
+    for (const list of implementsByOwner.values())
+        list.sort();
+    // ---- Linearize each owner using its provider's MRO strategy. -----------
+    const linearizationCache = new Map();
+    function linearizeFor(id) {
+        const cached = linearizationCache.get(id);
+        if (cached !== undefined)
+            return cached;
+        // Placeholder to break cycles — the strategies do not recurse into
+        // indirect ancestors through this lookup, but belt-and-suspenders.
+        linearizationCache.set(id, [id]);
+        const filePath = ownerFilePath.get(id) ?? "";
+        const lang = inferLanguageFromFile(filePath);
+        if (lang === undefined) {
+            linearizationCache.set(id, [id]);
+            return [id];
+        }
+        const provider = getProvider(lang);
+        const strategy = getMroStrategy(provider.mroStrategy);
+        if (provider.mroStrategy === "none") {
+            linearizationCache.set(id, [id]);
+            return [id];
+        }
+        const bases = extendsByOwner.get(id) ?? [];
+        try {
+            const linearization = strategy.linearize(id, bases, (baseId) => linearizeFor(baseId));
+            linearizationCache.set(id, linearization);
+            return linearization;
+        }
+        catch (err) {
+            if (err instanceof MroConflictError) {
+                ctx.onProgress?.({
+                    phase: MRO_PHASE_NAME,
+                    kind: "warn",
+                    message: `mro: conflict linearising ${id}: ${err.message}`,
+                });
+                linearizationCache.set(id, [id]);
+                conflictCount += 1;
+                return [id];
+            }
+            throw err;
+        }
+    }
+    let conflictCount = 0;
+    let overridesCount = 0;
+    let implementsCount = 0;
+    for (const id of ownerIds) {
+        const ownerPath = ownerFilePath.get(id) ?? "";
+        const lang = inferLanguageFromFile(ownerPath);
+        if (lang === undefined)
+            continue;
+        const provider = getProvider(lang);
+        if (provider.mroStrategy === "none")
+            continue;
+        const ownerMethods = methodsByOwner.get(id) ?? new Map();
+        if (ownerMethods.size === 0)
+            continue;
+        // Incremental gate: owners outside the closure keep their prior-graph
+        // MRO edges (carried forward above). Correctness for the in-closure
+        // case holds because incremental-scope already widened the closure by
+        // one heritage hop.
+        if (view.active && !view.closure.has(ownerPath))
+            continue;
+        // Sort method names for deterministic iteration.
+        const sortedNames = [...ownerMethods.keys()].sort();
+        // `METHOD_OVERRIDES`: walk the class's linearization; the first ancestor
+        // with a matching method wins. Skip the class itself (index 0).
+        const linearization = linearizeFor(id);
+        for (const name of sortedNames) {
+            const childMethodId = ownerMethods.get(name);
+            if (childMethodId === undefined)
+                continue;
+            for (let i = 1; i < linearization.length; i += 1) {
+                const ancestor = linearization[i];
+                if (ancestor === undefined)
+                    continue;
+                // Skip interface/trait ancestors — they produce METHOD_IMPLEMENTS
+                // instead. We detect by kind.
+                const ancestorKind = nodeKindById.get(ancestor);
+                if (ancestorKind === "Interface" || ancestorKind === "Trait")
+                    continue;
+                const ancestorMethods = methodsByOwner.get(ancestor);
+                if (ancestorMethods === undefined)
+                    continue;
+                const parentMethodId = ancestorMethods.get(name);
+                if (parentMethodId === undefined)
+                    continue;
+                ctx.graph.addEdge({
+                    from: childMethodId,
+                    to: parentMethodId,
+                    type: "METHOD_OVERRIDES",
+                    confidence: 0.9,
+                    reason: "mro-linearization",
+                });
+                overridesCount += 1;
+                break; // first hit wins in the linearization.
+            }
+        }
+        // `METHOD_IMPLEMENTS`: direct `IMPLEMENTS` edges identify interfaces /
+        // traits whose contract the class claims. For each same-name method on
+        // those interfaces emit the edge.
+        const interfaces = implementsByOwner.get(id) ?? [];
+        for (const name of sortedNames) {
+            const childMethodId = ownerMethods.get(name);
+            if (childMethodId === undefined)
+                continue;
+            for (const ifaceId of interfaces) {
+                const ifaceMethods = methodsByOwner.get(ifaceId);
+                if (ifaceMethods === undefined)
+                    continue;
+                const interfaceMethodId = ifaceMethods.get(name);
+                if (interfaceMethodId === undefined)
+                    continue;
+                ctx.graph.addEdge({
+                    from: childMethodId,
+                    to: interfaceMethodId,
+                    type: "METHOD_IMPLEMENTS",
+                    confidence: 0.95,
+                    reason: "interface-contract",
+                });
+                implementsCount += 1;
+            }
+        }
+    }
+    return { overridesCount, implementsCount, conflictCount };
+}
+function inferLanguageFromFile(filePath) {
+    const idx = filePath.lastIndexOf(".");
+    if (idx < 0)
+        return undefined;
+    const ext = filePath.slice(idx).toLowerCase();
+    switch (ext) {
+        case ".ts":
+        case ".mts":
+        case ".cts":
+            return "typescript";
+        case ".tsx":
+            return "tsx";
+        case ".js":
+        case ".mjs":
+        case ".cjs":
+        case ".jsx":
+            return "javascript";
+        case ".py":
+        case ".pyi":
+            return "python";
+        case ".go":
+            return "go";
+        case ".rs":
+            return "rust";
+        case ".java":
+            return "java";
+        case ".cs":
+            return "csharp";
+        case ".c":
+        case ".h":
+            // .h is ambiguous between C/C++; default to C. A dedicated C++ header
+            // detector can upgrade the classification later.
+            return "c";
+        case ".cpp":
+        case ".cc":
+        case ".cxx":
+        case ".hpp":
+        case ".hh":
+        case ".hxx":
+            return "cpp";
+        case ".rb":
+            return "ruby";
+        case ".kt":
+        case ".kts":
+            return "kotlin";
+        case ".swift":
+            return "swift";
+        case ".php":
+        case ".php3":
+        case ".php4":
+        case ".php5":
+        case ".php7":
+        case ".phtml":
+            return "php";
+        case ".dart":
+            return "dart";
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=mro.js.map

package/dist/pipeline/phases/mro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mro.js","sourceRoot":"","sources":["../../../src/pipeline/phases/mro.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/phases/openapi.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenAPI phase — materialises HTTP operations described by OpenAPI /
+ * Swagger specs as `Operation` nodes and links them to existing `Route`
+ * nodes whose method + templated path match.
+ *
+ * Pipeline placement:
+ *   - deps: [routes, profile]
+ *   - If the ProjectProfile's `apiContracts` list does NOT include
+ *     "openapi", the phase is a no-op (skips all spec discovery).
+ *
+ * What the phase does:
+ *   1. Walks scan output for every file whose basename matches
+ *      `openapi.{yaml,json}` / `swagger.{yaml,json}`, sorted by relPath.
+ *   2. For each spec, invokes `SwaggerParser.dereference(absPath, { resolve: { external: false } })`
+ *      which resolves internal `$ref`s inline while refusing any HTTP or
+ *      external file lookups (hard offline posture).
+ *   3. For each (method, path) pair, emits one `Operation` node with id
+ *      `Operation:<specRelPath>:<METHOD>:<path>` plus optional `summary`
+ *      and `operationId` properties.
+ *   4. Looks up an existing `Route` node whose method + normalised path
+ *      matches the operation. Matches exact strings first, then falls
+ *      back to path-parameter normalisation:
+ *        OpenAPI `{id}` → `:id`
+ *        Next.js `[id]` → `:id`
+ *        Express `:id`  unchanged
+ *      Both sides are normalised before comparison so any combination of
+ *      the three notations produces a single canonical key.
+ *   5. On a match, emits a `HANDLES_ROUTE` edge Operation → Route with
+ *      confidence 0.95 and reason `openapi-spec`. The direction encodes
+ *      "this spec describes this route handler".
+ *
+ * Determinism:
+ *   - Spec files are processed in scan-sorted order (same order scan emits).
+ *   - Operations are materialised in `(METHOD, path)` lex order so edge
+ *     insertion and graphHash byte-stability hold across runs.
+ *
+ * Error handling:
+ *   - Any swagger-parser throw (malformed spec, unresolved $ref, circular
+ *     references without handling) is caught and surfaced as a `warn`
+ *     progress event. The offending spec is skipped; the phase continues.
+ *   - No network calls: `resolve.external = false` disables the HTTP and
+ *     file-based external resolvers.
+ */
+import type { PipelinePhase } from "../types.js";
+export declare const OPENAPI_PHASE_NAME: "openapi";
+export interface OpenApiOutput {
+    readonly operationsEmitted: number;
+    readonly routesLinked: number;
+    readonly specsProcessed: number;
+}
+export declare const openapiPhase: PipelinePhase<OpenApiOutput>;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/pipeline/phases/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAUH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAKlE,eAAO,MAAM,kBAAkB,EAAG,SAAkB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAsCD,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,aAAa,CAUrD,CAAC"}

package/dist/pipeline/phases/openapi.js

@@ -0,0 +1,285 @@
+/**
+ * OpenAPI phase — materialises HTTP operations described by OpenAPI /
+ * Swagger specs as `Operation` nodes and links them to existing `Route`
+ * nodes whose method + templated path match.
+ *
+ * Pipeline placement:
+ *   - deps: [routes, profile]
+ *   - If the ProjectProfile's `apiContracts` list does NOT include
+ *     "openapi", the phase is a no-op (skips all spec discovery).
+ *
+ * What the phase does:
+ *   1. Walks scan output for every file whose basename matches
+ *      `openapi.{yaml,json}` / `swagger.{yaml,json}`, sorted by relPath.
+ *   2. For each spec, invokes `SwaggerParser.dereference(absPath, { resolve: { external: false } })`
+ *      which resolves internal `$ref`s inline while refusing any HTTP or
+ *      external file lookups (hard offline posture).
+ *   3. For each (method, path) pair, emits one `Operation` node with id
+ *      `Operation:<specRelPath>:<METHOD>:<path>` plus optional `summary`
+ *      and `operationId` properties.
+ *   4. Looks up an existing `Route` node whose method + normalised path
+ *      matches the operation. Matches exact strings first, then falls
+ *      back to path-parameter normalisation:
+ *        OpenAPI `{id}` → `:id`
+ *        Next.js `[id]` → `:id`
+ *        Express `:id`  unchanged
+ *      Both sides are normalised before comparison so any combination of
+ *      the three notations produces a single canonical key.
+ *   5. On a match, emits a `HANDLES_ROUTE` edge Operation → Route with
+ *      confidence 0.95 and reason `openapi-spec`. The direction encodes
+ *      "this spec describes this route handler".
+ *
+ * Determinism:
+ *   - Spec files are processed in scan-sorted order (same order scan emits).
+ *   - Operations are materialised in `(METHOD, path)` lex order so edge
+ *     insertion and graphHash byte-stability hold across runs.
+ *
+ * Error handling:
+ *   - Any swagger-parser throw (malformed spec, unresolved $ref, circular
+ *     references without handling) is caught and surfaced as a `warn`
+ *     progress event. The offending spec is skipped; the phase continues.
+ *   - No network calls: `resolve.external = false` disables the HTTP and
+ *     file-based external resolvers.
+ */
+import { makeNodeId } from "@opencodehub/core-types";
+import { PROFILE_PHASE_NAME } from "./profile.js";
+import { ROUTES_PHASE_NAME } from "./routes.js";
+import { SCAN_PHASE_NAME } from "./scan.js";
+export const OPENAPI_PHASE_NAME = "openapi";
+/**
+ * HTTP verbs recognised by the OpenAPI spec, upper-cased for the Operation
+ * node `method` property. `trace` is in OpenAPI 3.x even though few runtime
+ * servers implement it — we surface it anyway so our operations mirror the
+ * authored spec.
+ */
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+/** Basenames that flag a file as an OpenAPI / Swagger spec unambiguously. */
+const SPEC_BASENAME_RE = /^(openapi|swagger)\.(ya?ml|json)$/i;
+export const openapiPhase = {
+    name: OPENAPI_PHASE_NAME,
+    deps: [ROUTES_PHASE_NAME, PROFILE_PHASE_NAME],
+    async run(ctx) {
+        const scan = ctx.phaseOutputs.get(SCAN_PHASE_NAME);
+        if (scan === undefined) {
+            throw new Error("openapi: scan output missing from phase outputs");
+        }
+        return runOpenApi(ctx, scan);
+    },
+};
+async function runOpenApi(ctx, scan) {
+    // Skip unless profile phase detected openapi.
+    const profile = findProjectProfile(ctx.graph);
+    if (!profile?.apiContracts.includes("openapi")) {
+        return { operationsEmitted: 0, routesLinked: 0, specsProcessed: 0 };
+    }
+    const specs = selectSpecFiles(scan.files);
+    if (specs.length === 0) {
+        return { operationsEmitted: 0, routesLinked: 0, specsProcessed: 0 };
+    }
+    // Build a method + normalised-path → Route node id lookup once, so per-
+    // operation matches stay O(1).
+    const routeIndex = indexRoutesByMethodAndPath(ctx.graph);
+    let operationsEmitted = 0;
+    let routesLinked = 0;
+    let specsProcessed = 0;
+    for (const spec of specs) {
+        const parsedOps = await dereferenceSpec(ctx, spec);
+        if (parsedOps === null) {
+            // Already warned in dereferenceSpec; skip spec, keep pipeline alive.
+            continue;
+        }
+        specsProcessed += 1;
+        // Sort operations deterministically before insertion.
+        const sorted = [...parsedOps].sort(compareParsedOperation);
+        for (const op of sorted) {
+            const opId = operationNodeId(spec.relPath, op.method, op.path);
+            const node = {
+                id: opId,
+                kind: "Operation",
+                name: `${op.method} ${op.path}`,
+                filePath: spec.relPath,
+                method: op.method,
+                path: op.path,
+                ...(op.summary !== undefined ? { summary: op.summary } : {}),
+                ...(op.operationId !== undefined ? { operationId: op.operationId } : {}),
+            };
+            ctx.graph.addNode(node);
+            operationsEmitted += 1;
+            const routeKey = routeLookupKey(op.method, op.path);
+            const routeId = routeIndex.get(routeKey);
+            if (routeId !== undefined) {
+                ctx.graph.addEdge({
+                    from: opId,
+                    to: routeId,
+                    type: "HANDLES_ROUTE",
+                    confidence: 0.95,
+                    reason: "openapi-spec",
+                });
+                routesLinked += 1;
+            }
+        }
+    }
+    return { operationsEmitted, routesLinked, specsProcessed };
+}
+/** Look up the singleton ProjectProfile node in the graph, if any. */
+function findProjectProfile(graph) {
+    for (const n of graph.nodes()) {
+        if (n.kind === "ProjectProfile")
+            return n;
+    }
+    return undefined;
+}
+function selectSpecFiles(files) {
+    const out = [];
+    for (const f of files) {
+        const basename = basenameOf(f.relPath);
+        if (SPEC_BASENAME_RE.test(basename))
+            out.push(f);
+    }
+    // scan output is already sorted by relPath, but sort defensively so
+    // tests that construct ScannedFile[] directly still get a stable order.
+    return out.slice().sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+}
+/**
+ * Invoke swagger-parser's `dereference` with external resolution disabled
+ * and walk the resulting paths object. Returns `null` on any parser throw
+ * (after emitting a warn event); otherwise returns the list of operations
+ * found on the spec.
+ */
+async function dereferenceSpec(ctx, spec) {
+    let SwaggerParser;
+    try {
+        const mod = (await import("@apidevtools/swagger-parser"));
+        SwaggerParser = mod.default;
+    }
+    catch (err) {
+        ctx.onProgress?.({
+            phase: OPENAPI_PHASE_NAME,
+            kind: "warn",
+            message: `openapi: @apidevtools/swagger-parser not available: ${errMessage(err)}`,
+        });
+        return null;
+    }
+    let api;
+    try {
+        api = await SwaggerParser.dereference(spec.absPath, {
+            resolve: { external: false },
+        });
+    }
+    catch (err) {
+        ctx.onProgress?.({
+            phase: OPENAPI_PHASE_NAME,
+            kind: "warn",
+            message: `openapi: failed to parse ${spec.relPath}: ${errMessage(err)}`,
+        });
+        return null;
+    }
+    const paths = extractPaths(api);
+    if (paths === undefined) {
+        ctx.onProgress?.({
+            phase: OPENAPI_PHASE_NAME,
+            kind: "warn",
+            message: `openapi: ${spec.relPath} has no paths object`,
+        });
+        return [];
+    }
+    const ops = [];
+    for (const [pathTemplate, pathItemRaw] of Object.entries(paths)) {
+        if (!isRecord(pathItemRaw))
+            continue;
+        const pathItem = pathItemRaw;
+        for (const method of HTTP_METHODS) {
+            const opRaw = pathItem[method];
+            if (!isRecord(opRaw))
+                continue;
+            const opRecord = opRaw;
+            const summary = stringOrUndefined(opRecord["summary"]);
+            const operationId = stringOrUndefined(opRecord["operationId"]);
+            ops.push({
+                method: method.toUpperCase(),
+                path: pathTemplate,
+                ...(summary !== undefined ? { summary } : {}),
+                ...(operationId !== undefined ? { operationId } : {}),
+            });
+        }
+    }
+    return ops;
+}
+function extractPaths(api) {
+    if (!isRecord(api))
+        return undefined;
+    const paths = api["paths"];
+    if (!isRecord(paths))
+        return undefined;
+    return paths;
+}
+/**
+ * Walk the graph and build a method+normalisedPath → NodeId index of
+ * existing Route nodes. We snapshot the node set at call time; later
+ * Operation emissions don't invalidate the map because Route nodes are
+ * populated by the routes phase which strictly precedes this one.
+ */
+function indexRoutesByMethodAndPath(graph) {
+    const index = new Map();
+    for (const n of graph.nodes()) {
+        if (n.kind !== "Route")
+            continue;
+        const route = n;
+        // Routes without a method are rare (catch-all `app.use`) — they can't
+        // match a method-specific OpenAPI operation.
+        const method = route.method;
+        if (method === undefined)
+            continue;
+        const key = routeLookupKey(method.toUpperCase(), route.url);
+        // First-write wins; routes are emitted in a deterministic order so the
+        // winner is stable across runs.
+        if (!index.has(key)) {
+            index.set(key, route.id);
+        }
+    }
+    return index;
+}
+function routeLookupKey(method, path) {
+    return `${method.toUpperCase()}\u0000${normalisePath(path)}`;
+}
+/**
+ * Normalise route path templates so OpenAPI `/users/{id}`, Express
+ * `/users/:id`, and Next.js `/users/[id]` all collapse onto the same
+ * canonical form (`/users/:id`). The transformation is purely syntactic:
+ * we rewrite brace- and bracket-style parameters in place and otherwise
+ * leave the path untouched.
+ */
+function normalisePath(path) {
+    if (path.length === 0)
+        return path;
+    let out = path;
+    // `{param}` → `:param`
+    out = out.replace(/\{([^}]+)\}/g, ":$1");
+    // `[param]` → `:param`
+    out = out.replace(/\[([^\]]+)\]/g, ":$1");
+    return out;
+}
+function operationNodeId(specPath, method, pathTemplate) {
+    return makeNodeId("Operation", specPath, `${method}:${pathTemplate}`);
+}
+function compareParsedOperation(a, b) {
+    if (a.method !== b.method)
+        return a.method < b.method ? -1 : 1;
+    if (a.path !== b.path)
+        return a.path < b.path ? -1 : 1;
+    return 0;
+}
+function basenameOf(relPath) {
+    const idx = relPath.lastIndexOf("/");
+    return idx < 0 ? relPath : relPath.slice(idx + 1);
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function stringOrUndefined(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=openapi.js.map