@topogram/cli 0.3.34

package/src/import/extractors/api/micronaut.js

@@ -0,0 +1,213 @@
+import {
+  dedupeCandidateRecords,
+  findImportFiles,
+  inferApiEntityIdFromPath,
+  inferRouteCapabilityId,
+  makeCandidateRecord,
+  normalizeOpenApiPath,
+  readTextIfExists,
+  relativeTo,
+  titleCase
+} from "../../core/shared.js";
+
+function buildJavaFileIndex(paths) {
+  const files = findImportFiles(paths, (filePath) => /\.java$/i.test(filePath));
+  return files.map((filePath) => ({
+    filePath,
+    relativePath: relativeTo(paths.repoRoot, filePath),
+    text: readTextIfExists(filePath) || ""
+  }));
+}
+
+function explicitHandlerHint(methodName, routePath, httpMethod) {
+  const low = String(methodName || "").toLowerCase();
+  if (httpMethod === "GET" && /\/articles\/feed$/.test(routePath)) return "feed_article";
+  if (httpMethod === "POST" && /\/articles\/\{slug\}\/favorite$/.test(routePath)) return "favorite_article";
+  if (httpMethod === "DELETE" && /\/articles\/\{slug\}\/favorite$/.test(routePath)) return "unfavorite_article";
+  if (httpMethod === "GET" && /\/articles\/\{slug\}\/comments$/.test(routePath)) return "list_comments";
+  if (httpMethod === "POST" && /\/articles\/\{slug\}\/comments$/.test(routePath)) return "create_comment";
+  if (httpMethod === "DELETE" && /\/articles\/\{slug\}\/comments\/\{id\}$/.test(routePath)) return "delete_comment";
+  if (httpMethod === "GET" && /\/profiles\/\{username\}$/.test(routePath)) return "get_profile";
+  if (httpMethod === "POST" && /\/profiles\/\{username\}\/follow$/.test(routePath)) return "follow_profile";
+  if (httpMethod === "DELETE" && /\/profiles\/\{username\}\/follow$/.test(routePath)) return "unfollow_profile";
+  if (httpMethod === "POST" && /\/users\/login$/.test(routePath)) return "sign_in_account";
+  if (httpMethod === "POST" && routePath === "/users") return "create_user";
+  if (httpMethod === "GET" && routePath === "/user") return "get_user";
+  if ((httpMethod === "PUT" || httpMethod === "PATCH") && routePath === "/user") return "update_user";
+  if (httpMethod === "GET" && routePath === "/tags") return "list_tags";
+  if (httpMethod === "GET" && /\/articles\/\{slug\}$/.test(routePath)) return "get_article";
+  if (httpMethod === "GET" && routePath === "/articles") return "list_articles";
+  if (httpMethod === "POST" && routePath === "/articles") return "create_article";
+  if ((httpMethod === "PUT" || httpMethod === "PATCH") && /\/articles\/\{slug\}$/.test(routePath)) return "update_article";
+  if (httpMethod === "DELETE" && /\/articles\/\{slug\}$/.test(routePath)) return "delete_article";
+  if (low.includes("favorite")) return low.startsWith("un") ? "unfavorite_article" : "favorite_article";
+  if (low.includes("comment")) {
+    if (low.startsWith("delete")) return "delete_comment";
+    if (low.startsWith("add") || low.startsWith("create")) return "create_comment";
+    return "list_comments";
+  }
+  if (low.includes("follow")) return low.startsWith("un") ? "unfollow_profile" : "follow_profile";
+  if (low === "login") return "sign_in_account";
+  if (low === "register") return "create_user";
+  if (low === "current") return "get_user";
+  return null;
+}
+
+function parseRecordFields(recordText) {
+  const ctorMatch = String(recordText || "").match(/record\s+[A-Za-z_][A-Za-z0-9_]*\s*\(([\s\S]*?)\)\s*(?:implements[^{]+)?\{/);
+  if (!ctorMatch) return [];
+  return ctorMatch[1]
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const cleaned = part.replace(/@[A-Za-z_][A-Za-z0-9_.]*(?:\((?:[^()]|\([^)]*\))*\))?\s*/g, "").trim();
+      const match = cleaned.match(/([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)$/);
+      return match ? { type: match[1], name: match[2] } : null;
+    })
+    .filter(Boolean);
+}
+
+function parseClassFields(classText) {
+  return [...String(classText || "").matchAll(/((?:\s*@[\w.]+(?:\((?:[^()]|\([^)]*\))*\))?\s*)*)\s*private\s+([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)\s*;/g)]
+    .map((entry) => ({
+      annotations: entry[1] || "",
+      type: entry[2],
+      name: entry[3]
+    }));
+}
+
+function findJavaTypeBlock(typeName, files, preferredFile = null) {
+  const bare = String(typeName || "").split(".").pop();
+  if (!bare) return null;
+  const patterns = [
+    new RegExp(`(?:public\\s+)?record\\s+${bare}\\b[\\s\\S]{0,2400}?\\n\\}`, "m"),
+    new RegExp(`(?:public\\s+)?class\\s+${bare}\\b[\\s\\S]{0,3600}?\\n\\}`, "m"),
+    new RegExp(`(?:public\\s+)?interface\\s+${bare}\\b[\\s\\S]{0,2400}?\\n\\}`, "m")
+  ];
+  const orderedFiles = preferredFile
+    ? [...files.filter((file) => file.filePath === preferredFile), ...files.filter((file) => file.filePath !== preferredFile)]
+    : files;
+  for (const file of orderedFiles) {
+    for (const pattern of patterns) {
+      const match = file.text.match(pattern);
+      if (match) return { filePath: file.filePath, text: match[0] };
+    }
+  }
+  return null;
+}
+
+function flattenFieldsFromType(typeName, files, preferredFile = null, seen = new Set()) {
+  const bare = String(typeName || "").split(".").pop();
+  const key = `${preferredFile || ""}:${bare}`;
+  if (!bare || seen.has(key)) return [];
+  seen.add(key);
+  const block = findJavaTypeBlock(typeName, files, preferredFile);
+  if (!block) return [];
+  const recordFields = parseRecordFields(block.text);
+  if (recordFields.length > 0) return [...new Set(recordFields.map((field) => field.name))];
+  return [...new Set(parseClassFields(block.text).map((field) => field.name))];
+}
+
+function parseQueryParams(parameters) {
+  return [...String(parameters || "").matchAll(/@QueryValue(?:\(value\s*=\s*"([^"]+)".*?\))?\s+@Nullable\s+([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)|@QueryValue(?:\(value\s*=\s*"([^"]+)".*?\))?\s+([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)/g)]
+    .map((entry) => ({
+      name: entry[1] || entry[4] || entry[3] || entry[6],
+      required: false,
+      type: entry[2] || entry[5] || null
+    }));
+}
+
+function parsePathParams(parameters) {
+  return [...String(parameters || "").matchAll(/@PathVariable\("([^"]+)"\)\s+([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)/g)]
+    .map((entry) => ({ name: entry[1] || entry[3], required: true, type: entry[2] || null }));
+}
+
+function parseBodyType(parameters) {
+  const match = String(parameters || "").match(/@Body\s+([A-Za-z0-9_<>\[\]\?\.]+)\s+([A-Za-z_][A-Za-z0-9_]*)/);
+  return match ? match[1] : null;
+}
+
+function parseMicronautRoutes(files, repoRoot) {
+  const opFiles = files.filter((file) => /\/api\/operation\/.+Operations\.java$/.test(file.relativePath) || /io\.micronaut\.http\.annotation\./.test(file.text));
+  const routes = [];
+  const methodPattern = /((?:\s*@[\w.]+(?:\((?:[^()]|\([^)]*\))*\))?\s*)+)\s*(?:public\s+)?(?:default\s+)?([A-Za-z0-9_<>\[\]\?., ]+)\s+([A-Za-z_][A-Za-z0-9_]*)\(([\s\S]*?)\)\s*;/g;
+  for (const file of opFiles) {
+    for (const match of file.text.matchAll(methodPattern)) {
+      const [, annotations, returnType, methodName, parameters] = match;
+      const verb = annotations.match(/@(Get|Post|Put|Patch|Delete)\(/)?.[1];
+      const pathRaw = annotations.match(/@(Get|Post|Put|Patch|Delete)\("([^"]+)"\)/)?.[2];
+      if (!verb || !pathRaw) continue;
+      const pathValue = normalizeOpenApiPath(pathRaw.replace(/\{\?[^}]+\}/g, ""));
+      const bodyType = parseBodyType(parameters);
+      routes.push({
+        method: verb.toUpperCase(),
+        path: pathValue,
+        handler_hint: explicitHandlerHint(methodName, pathValue, verb.toUpperCase()),
+        controller: file.relativePath.split("/").pop()?.replace(/\.java$/, "") || "MicronautOperations",
+        action: methodName,
+        auth_hint: pathValue === "/users/login" || pathValue === "/users" || pathValue === "/tags" || pathValue === "/articles" || /^\/profiles\/\{username\}$/.test(pathValue) ? "public" : "secured",
+        path_params: parsePathParams(parameters),
+        query_params: parseQueryParams(parameters),
+        header_params: [],
+        input_fields: bodyType ? flattenFieldsFromType(bodyType, files, file.filePath) : [],
+        output_fields: flattenFieldsFromType(returnType, files, file.filePath),
+        provenance: `${relativeTo(repoRoot, file.filePath)}#${verb.toUpperCase()} ${pathValue}`
+      });
+    }
+  }
+  return routes;
+}
+
+export const micronautExtractor = {
+  id: "api.micronaut",
+  track: "api",
+  detect(context) {
+    const javaFiles = findImportFiles(context.paths, (filePath) => /\.java$/i.test(filePath));
+    const count = javaFiles.filter((filePath) => /io\.micronaut\.http\.annotation|@Controller\(|@Get\(|@Post\(|@Put\(|@Delete\(/.test(readTextIfExists(filePath) || "")).length;
+    return {
+      score: count > 0 ? 95 : 0,
+      reasons: count > 0 ? ["Found Micronaut HTTP annotations or operation interfaces"] : []
+    };
+  },
+  extract(context) {
+    const javaFiles = buildJavaFileIndex(context.paths);
+    const routes = parseMicronautRoutes(javaFiles, context.paths.repoRoot);
+    const findings = [];
+    const candidates = { capabilities: [], routes: [], stacks: [] };
+    if (routes.length > 0) {
+      findings.push({
+        kind: "micronaut_routes",
+        route_count: routes.length,
+        files: [...new Set(routes.map((route) => route.provenance.split("#")[0]))]
+      });
+      candidates.stacks.push("micronaut");
+    }
+    candidates.capabilities.push(...routes.map((route) => makeCandidateRecord({
+      kind: "capability",
+      idHint: inferRouteCapabilityId(route),
+      label: route.handler_hint ? titleCase(route.handler_hint) : `${route.method} ${route.path}`,
+      confidence: "high",
+      sourceKind: "route_code",
+      provenance: route.provenance,
+      endpoint: { method: route.method, path: route.path },
+      path_params: route.path_params,
+      query_params: route.query_params,
+      header_params: route.header_params,
+      input_fields: route.input_fields,
+      output_fields: route.output_fields,
+      auth_hint: route.auth_hint,
+      entity_id: route.handler_hint === "sign_in_account" ? "entity_account" : inferApiEntityIdFromPath(route.path),
+      track: "api"
+    })));
+    candidates.routes.push(...routes.map((route) => ({
+      path: route.path,
+      method: route.method,
+      confidence: "high",
+      source_kind: "route_code",
+      provenance: route.provenance
+    })));
+    candidates.capabilities = dedupeCandidateRecords(candidates.capabilities, (record) => record.id_hint);
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/api/next-route.js

@@ -0,0 +1,50 @@
+import { inferNextApiRoutes, inferRouteCapabilityId, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
+
+export const nextRouteExtractor = {
+  id: "api.next-route",
+  track: "api",
+  detect(context) {
+    const routes = inferNextApiRoutes(context.paths.workspaceRoot, context.helpers);
+    return {
+      score: routes.length > 0 ? 95 : 0,
+      reasons: routes.length > 0 ? ["Found Next.js app/api route handlers"] : []
+    };
+  },
+  extract(context) {
+    const routes = inferNextApiRoutes(context.paths.workspaceRoot, context.helpers);
+    const findings = [];
+    const candidates = { capabilities: [], routes: [], stacks: [] };
+    if (routes.length > 0) {
+      findings.push({
+        kind: "route_inventory",
+        files: [...new Set(routes.map((route) => relativeTo(context.paths.repoRoot, route.file)))],
+        route_count: routes.length
+      });
+      candidates.capabilities.push(...routes.map((route) => makeCandidateRecord({
+        kind: "capability",
+        idHint: inferRouteCapabilityId(route),
+        label: `${route.method} ${route.path}`,
+        confidence: "medium",
+        sourceKind: "route_code",
+        provenance: `${relativeTo(context.paths.repoRoot, route.file)}#${route.method} ${route.path}`,
+        endpoint: { method: route.method, path: normalizeOpenApiPath(route.path) },
+        path_params: (route.path_params || []).map((name) => ({ name, required: true, type: null })),
+        query_params: (route.query_params || []).map((name) => ({ name, required: false, type: null })),
+        header_params: [],
+        input_fields: [],
+        output_fields: route.output_fields || [],
+        auth_hint: route.auth_hint || "unknown",
+        track: "api"
+      })));
+      candidates.routes.push(...routes.map((route) => ({
+        path: normalizeOpenApiPath(route.path),
+        method: route.method,
+        confidence: "medium",
+        source_kind: "route_code",
+        provenance: `${relativeTo(context.paths.repoRoot, route.file)}#${route.method} ${route.path}`
+      })));
+      candidates.stacks.push("next_app_router");
+    }
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/api/next-server-action.js

@@ -0,0 +1,51 @@
+import { inferCapabilityEntityId, inferFormDataFields, inferInputNames, inferNextServerActionCapabilities, makeCandidateRecord, normalizeOpenApiPath, relativeTo, titleCase } from "../../core/shared.js";
+
+export const nextServerActionExtractor = {
+  id: "api.next-server-action",
+  track: "api",
+  detect(context) {
+    const actions = inferNextServerActionCapabilities(context.paths.workspaceRoot, context.helpers);
+    return {
+      score: actions.length > 0 ? 90 : 0,
+      reasons: actions.length > 0 ? ["Found Next.js server actions"] : []
+    };
+  },
+  extract(context) {
+    const actions = inferNextServerActionCapabilities(context.paths.workspaceRoot, context.helpers);
+    const findings = [];
+    const candidates = { capabilities: [], routes: [], stacks: [] };
+    if (actions.length > 0) {
+      findings.push({
+        kind: "next_server_actions",
+        files: [...new Set(actions.map((action) => relativeTo(context.paths.repoRoot, action.file)))],
+        action_count: actions.length
+      });
+      candidates.capabilities.push(...actions.map((action) => makeCandidateRecord({
+        kind: "capability",
+        idHint: action.id_hint,
+        label: titleCase(action.id_hint.replace(/^cap_/, "")),
+        confidence: "medium",
+        sourceKind: action.source_kind,
+        provenance: `${relativeTo(context.paths.repoRoot, action.file)}#${action.function_name}`,
+        endpoint: { method: action.method, path: normalizeOpenApiPath(action.path) },
+        path_params: (action.path_params || []).map((name) => ({ name, required: true, type: null })),
+        query_params: [],
+        header_params: [],
+        input_fields: action.input_fields || [],
+        output_fields: action.output_fields || [],
+        auth_hint: action.auth_hint || "unknown",
+        entity_id: action.entity_id || inferCapabilityEntityId({ endpoint: { path: action.path }, id_hint: action.id_hint }),
+        track: "api"
+      })));
+      candidates.routes.push(...actions.map((action) => ({
+        path: normalizeOpenApiPath(action.path),
+        method: action.method,
+        confidence: "medium",
+        source_kind: action.source_kind,
+        provenance: `${relativeTo(context.paths.repoRoot, action.file)}#${action.function_name}`
+      })));
+      candidates.stacks.push("next_app_router");
+    }
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/api/nextauth.js

@@ -0,0 +1,52 @@
+import { inferNextAuthCapabilities, makeCandidateRecord, normalizeOpenApiPath } from "../../core/shared.js";
+
+export const nextAuthExtractor = {
+  id: "api.nextauth",
+  track: "api",
+  detect(context) {
+    const capabilities = inferNextAuthCapabilities(context.paths, context.helpers);
+    return {
+      score: capabilities.length > 0 ? 88 : 0,
+      reasons: capabilities.length > 0 ? ["Found NextAuth-style auth flows"] : []
+    };
+  },
+  extract(context) {
+    const capabilities = inferNextAuthCapabilities(context.paths, context.helpers);
+    const findings = [];
+    const candidates = { capabilities: [], routes: [], stacks: [] };
+    if (capabilities.length > 0) {
+      findings.push({
+        kind: "next_auth_flows",
+        files: [...new Set(capabilities.flatMap((capability) => capability.provenance || []))],
+        capability_count: capabilities.length
+      });
+      candidates.capabilities.push(...capabilities.map((capability) => makeCandidateRecord({
+        kind: "capability",
+        idHint: capability.id_hint,
+        label: capability.label,
+        confidence: "medium",
+        sourceKind: capability.source_kind,
+        provenance: capability.provenance,
+        endpoint: { method: capability.method, path: normalizeOpenApiPath(capability.path) },
+        path_params: [],
+        query_params: [],
+        header_params: [],
+        input_fields: capability.input_fields || [],
+        output_fields: capability.output_fields || [],
+        auth_hint: capability.auth_hint || "unknown",
+        entity_id: capability.entity_id,
+        target_state: capability.target_state || null,
+        track: "api"
+      })));
+      candidates.routes.push(...capabilities.map((capability) => ({
+        path: normalizeOpenApiPath(capability.path),
+        method: capability.method,
+        confidence: "medium",
+        source_kind: capability.source_kind,
+        provenance: capability.provenance
+      })));
+      candidates.stacks.push("nextauth");
+    }
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/api/openapi-code.js

@@ -0,0 +1,242 @@
+import path from "node:path";
+
+import {
+  dedupeCandidateRecords,
+  findImportFiles,
+  inferApiCapabilityIdFromOperation,
+  inferApiEntityIdFromPath,
+  makeCandidateRecord,
+  normalizeOpenApiPath,
+  pluralizeCandidateTerm,
+  relativeTo,
+  titleCase
+} from "../../core/shared.js";
+
+function splitTopLevelProperties(block) {
+  const props = [];
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let quote = null;
+  for (let i = 0; i < block.length; i += 1) {
+    const ch = block[i];
+    const prev = block[i - 1];
+    if (inString) {
+      current += ch;
+      if (ch === quote && prev !== "\\") {
+        inString = false;
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      inString = true;
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") {
+      depth += 1;
+      current += ch;
+      continue;
+    }
+    if (ch === "}" || ch === "]" || ch === ")") {
+      depth -= 1;
+      current += ch;
+      continue;
+    }
+    if (ch === "," && depth === 0) {
+      if (current.trim()) props.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) props.push(current.trim());
+  return props;
+}
+
+function parseZodObjectSchemaFields(schemaText) {
+  const schemaFields = new Map();
+  for (const match of schemaText.matchAll(/export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*z\s*\.\s*object\s*\([^)]*?\.shape\)\s*\.pick\(\s*\{([\s\S]*?)\}\s*\)/g)) {
+    const schemaName = match[1];
+    const fields = [];
+    for (const prop of splitTopLevelProperties(match[2])) {
+      const propMatch = prop.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*:/);
+      if (propMatch) fields.push(propMatch[1]);
+    }
+    schemaFields.set(schemaName, [...new Set(fields)].sort());
+  }
+  for (const match of schemaText.matchAll(/export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*z\s*\.\s*object\s*\(\s*\{([\s\S]*?)\}\s*\)/g)) {
+    const schemaName = match[1];
+    const fields = [];
+    for (const prop of splitTopLevelProperties(match[2])) {
+      const propMatch = prop.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*:/);
+      if (propMatch) fields.push(propMatch[1]);
+    }
+    schemaFields.set(schemaName, [...new Set(fields)].sort());
+  }
+  return schemaFields;
+}
+
+function extractRequestSchemaRefs(block) {
+  return {
+    body: block.match(/request\s*:\s*\{[\s\S]*?body\s*:\s*\{[\s\S]*?schema\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/m)?.[1] || null,
+    params: block.match(/request\s*:\s*\{[\s\S]*?params\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/m)?.[1] || null,
+    query: block.match(/request\s*:\s*\{[\s\S]*?query\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/m)?.[1] || null,
+    headers: block.match(/request\s*:\s*\{[\s\S]*?headers\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/m)?.[1] || null
+  };
+}
+
+function extractSecurity(block) {
+  return /security\s*:\s*\[\s*\{\s*bearerAuth\s*:\s*\[\s*\]\s*\}\s*\]/m.test(block) ? ["bearerAuth"] : [];
+}
+
+function extractTags(block) {
+  const match = block.match(/tags\s*:\s*\[([\s\S]*?)\]/m);
+  if (!match) return [];
+  return [...match[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map((entry) => entry[1]);
+}
+
+function singularStemFromSchemaRef(schemaRef) {
+  return String(schemaRef || "")
+    .replace(/(?:DataSchema|ResponseDataSchema|Schema)$/g, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+function inferOutputFieldsFromExpression(expression, schemaFields, entry) {
+  const trimmed = String(expression || "").trim();
+  if (!trimmed) return [];
+  const simpleRef = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)$/);
+  if (simpleRef) {
+    return schemaFields.get(simpleRef[1]) || [];
+  }
+  const arrayRef = trimmed.match(/^z\s*\.\s*array\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)$/);
+  if (arrayRef) {
+    const base = singularStemFromSchemaRef(arrayRef[1]).replace(/_schema$/, "");
+    return [pluralizeCandidateTerm(base)];
+  }
+  return [];
+}
+
+function extractSuccessResponseMeta(block, schemaFields, entry) {
+  const successBlockMatch = block.match(/responses\s*:\s*\{[\s\S]*?(20[0-9])\s*:\s*\{([\s\S]*?)\n\s*\}\s*(?:,|\n\s*\})/m);
+  if (!successBlockMatch) {
+    return { responseSchema: null, outputFields: [] };
+  }
+  const successBlock = successBlockMatch[2];
+  const extendMatch = successBlock.match(/schema\s*:\s*SuccessResponseSchema\s*\.extend\(\s*\{([\s\S]*?)\}\s*\)/m);
+  if (extendMatch) {
+    const dataMatch = extendMatch[1].match(/data\s*:\s*([^,\n}]+)/m);
+    const responseExpr = dataMatch ? dataMatch[1].trim() : null;
+    return {
+      responseSchema: responseExpr,
+      outputFields: responseExpr ? inferOutputFieldsFromExpression(responseExpr, schemaFields, entry) : schemaFields.get("SuccessResponseSchema") || []
+    };
+  }
+  const schemaRef = successBlock.match(/schema\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/m)?.[1] || null;
+  return {
+    responseSchema: schemaRef,
+    outputFields: schemaRef ? schemaFields.get(schemaRef) || [] : []
+  };
+}
+
+function parseOpenApiRegisterPaths(text, schemaFields) {
+  const entries = [];
+  for (const match of text.matchAll(/registry\.registerPath\(\s*\{([\s\S]*?)\n\}\s*\);/g)) {
+    const block = match[1];
+    const methodMatch = block.match(/method\s*:\s*["'`]([A-Za-z]+)["'`]/);
+    const pathMatch = block.match(/path\s*:\s*["'`]([^"'`]+)["'`]/);
+    if (!methodMatch || !pathMatch) continue;
+    const summaryMatch = block.match(/summary\s*:\s*["'`]([^"'`]+)["'`]/);
+    const requestSchemas = extractRequestSchemaRefs(block);
+    const securitySchemes = extractSecurity(block);
+    const tags = extractTags(block);
+    const entry = {
+      method: methodMatch[1].toUpperCase(),
+      path: pathMatch[1],
+      summary: summaryMatch ? summaryMatch[1] : null,
+      tags,
+      requestSchemas,
+      security_schemes: securitySchemes
+    };
+    const responseMeta = extractSuccessResponseMeta(block, schemaFields, entry);
+    entries.push({
+      ...entry,
+      requestSchema: requestSchemas.body,
+      responseSchema: responseMeta.responseSchema,
+      input_fields: requestSchemas.body ? schemaFields.get(requestSchemas.body) || [] : [],
+      query_params: requestSchemas.query ? (schemaFields.get(requestSchemas.query) || []).map((name) => ({ name, required: false, type: null })) : [],
+      path_params: requestSchemas.params
+        ? (schemaFields.get(requestSchemas.params) || []).map((name) => ({ name, required: true, type: null }))
+        : [...pathMatch[1].matchAll(/\{([^}]+)\}/g)].map((param) => ({ name: param[1], required: true, type: null })),
+      header_params: requestSchemas.headers ? (schemaFields.get(requestSchemas.headers) || []).map((name) => ({ name, required: false, type: null })) : [],
+      output_fields: responseMeta.outputFields,
+      entity_id: inferApiEntityIdFromPath(pathMatch[1], { tags, summary: summaryMatch ? summaryMatch[1] : null })
+    });
+  }
+  return entries;
+}
+
+export const openApiCodeExtractor = {
+  id: "api.openapi-code",
+  track: "api",
+  detect(context) {
+    const openApiFiles = findImportFiles(context.paths, (filePath) => /src\/docs\/openapi\.(ts|js|mjs|cjs)$/i.test(filePath));
+    return {
+      score: openApiFiles.length > 0 ? 92 : 0,
+      reasons: openApiFiles.length > 0 ? ["Found code-generated OpenAPI source"] : []
+    };
+  },
+  extract(context) {
+    const openApiFiles = findImportFiles(context.paths, (filePath) => /src\/docs\/openapi\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const schemaFile = findImportFiles(context.paths, (filePath) => /src\/docs\/openapi-schemas\.(ts|js|mjs|cjs)$/i.test(filePath))[0];
+    const schemaFields = schemaFile ? parseZodObjectSchemaFields(context.helpers.readTextIfExists(schemaFile) || "") : new Map();
+    const findings = [];
+    const candidates = { capabilities: [], routes: [], stacks: [] };
+    for (const filePath of openApiFiles) {
+      const provenanceBase = relativeTo(context.paths.repoRoot, filePath);
+      const parsed = parseOpenApiRegisterPaths(context.helpers.readTextIfExists(filePath) || "", schemaFields);
+      findings.push({
+        kind: "openapi_code",
+        file: provenanceBase,
+        capability_count: parsed.length
+      });
+      candidates.capabilities.push(...parsed.map((entry) => makeCandidateRecord({
+        kind: "capability",
+        idHint: inferApiCapabilityIdFromOperation(entry),
+        label: entry.summary || titleCase(inferApiCapabilityIdFromOperation(entry).replace(/^cap_/, "")),
+        confidence: "high",
+        sourceKind: "openapi",
+        provenance: `${provenanceBase}#${entry.method} ${entry.path}`,
+        endpoint: { method: entry.method, path: entry.path },
+        path_params: entry.path_params || [],
+        query_params: entry.query_params || [],
+        header_params: entry.header_params || [],
+        input_fields: entry.input_fields,
+        output_fields: entry.output_fields,
+        security_schemes: entry.security_schemes,
+        auth_hint: entry.security_schemes.length > 0 ? "secured" : "public",
+        entity_id: entry.entity_id,
+        tags: entry.tags,
+        track: "api"
+      })));
+      candidates.routes.push(...parsed.map((entry) => ({
+        path: normalizeOpenApiPath(entry.path),
+        method: entry.method,
+        confidence: "high",
+        source_kind: "openapi",
+        provenance: `${provenanceBase}#${entry.method} ${entry.path}`
+      })));
+      candidates.stacks.push("openapi_code");
+    }
+    candidates.capabilities = dedupeCandidateRecords(candidates.capabilities, (record) => record.id_hint);
+    candidates.routes = dedupeCandidateRecords(
+      candidates.routes.map((route) => ({ ...route, id_hint: `${route.method}_${route.path}` })),
+      (record) => `${record.method}:${record.path}:${record.source_kind}`
+    ).map(({ id_hint, ...route }) => route);
+    candidates.stacks = [...new Set(candidates.stacks)].sort();
+    return { findings, candidates };
+  }
+};