@topogram/cli 0.3.63 → 0.3.65

package/src/workflows/docs.js

@@ -0,0 +1,15 @@
+export {
+  confidenceRank,
+  renderCandidateActor,
+  renderCandidateRole,
+  scanDocsWorkflow
+} from "./docs-scan.js";
+export {
+  docDirForKind,
+  generateDocsBundleFromGraph,
+  generateDocsWorkflow,
+  generateJourneyDraftsWorkflow,
+  loadResolvedGraph,
+  refreshDocsWorkflow,
+  tryLoadResolvedGraph
+} from "./docs-generate.js";

package/src/workflows/import-app/api/collect.js

@@ -0,0 +1,221 @@
+// @ts-check
+
+import path from "node:path";
+
+import { relativeTo } from "../../../path-helpers.js";
+import { titleCase } from "../../../text-helpers.js";
+import { readTextIfExists } from "../../shared.js";
+import { dedupeCandidateRecords, makeCandidateRecord, normalizeOpenApiPath } from "../shared.js";
+import { inferReactRoutes, inferSvelteRoutes } from "../ui.js";
+import { parseOpenApiDocument, parseOpenApiYaml } from "./openapi.js";
+import {
+  inferNextApiRoutes,
+  inferNextAuthCapabilities,
+  inferNextServerActionCapabilities,
+  inferRouteCapabilityId,
+  inferServerRoutes
+} from "./routes.js";
+import { discoverApiSources } from "./sources.js";
+
+/** @param {WorkspacePaths} paths @returns {any} */
+export function collectApiImport(paths) {
+  /** @type {any[]} */
+  const findings = [];
+  /** @type {WorkflowRecord} */
+  const candidates = {
+    capabilities: [],
+    routes: [],
+    stacks: []
+  };
+  const { openApiFiles } = discoverApiSources(paths);
+  let usedOpenApi = false;
+  for (const filePath of openApiFiles) {
+    const provenance = relativeTo(paths.repoRoot, filePath);
+    const text = readTextIfExists(filePath) || "";
+    const document = filePath.endsWith(".json") ? JSON.parse(text) : parseOpenApiYaml(text);
+    const parsed = parseOpenApiDocument(document, provenance, "openapi");
+    usedOpenApi = true;
+    findings.push({
+      kind: "openapi",
+      file: provenance,
+      capability_count: parsed.capabilities.length
+    });
+    candidates.capabilities.push(...parsed.capabilities);
+    candidates.routes.push(...parsed.routes.map((/** @type {any} */ route) => ({
+      path: route.path,
+      method: route.method,
+      confidence: "high",
+      source_kind: route.source_kind,
+      provenance: route.provenance
+    })));
+  }
+  if (!usedOpenApi) {
+    const inferredRoutes = [
+      ...inferNextApiRoutes(paths),
+      ...inferServerRoutes(paths)
+    ];
+    const inferredServerActions = inferNextServerActionCapabilities(paths);
+    const inferredAuthCapabilities = inferNextAuthCapabilities(paths);
+    if (inferredRoutes.length > 0) {
+      findings.push({
+        kind: "route_inventory",
+        files: [...new Set(inferredRoutes.map((/** @type {any} */ route) => relativeTo(paths.repoRoot, route.file)))],
+        route_count: inferredRoutes.length
+      });
+      candidates.capabilities.push(
+        ...inferredRoutes.map((/** @type {any} */ route) =>
+          makeCandidateRecord({
+            kind: "capability",
+            idHint: inferRouteCapabilityId(route),
+            label: `${route.method} ${route.path}`,
+            confidence: "medium",
+            sourceKind: "route_code",
+            provenance: `${relativeTo(paths.repoRoot, route.file)}#${route.method} ${route.path}`,
+            endpoint: {
+              method: route.method,
+              path: normalizeOpenApiPath(route.path)
+            },
+            path_params: (route.path_params || []).map((/** @type {any} */ name) => ({ name, required: true, type: null })),
+            query_params: (route.query_params || []).map((/** @type {any} */ name) => ({ name, required: false, type: null })),
+            header_params: [],
+            input_fields: [],
+            output_fields: route.output_fields || [],
+            auth_hint: route.auth_hint || "unknown"
+          })
+        )
+      );
+      candidates.routes.push(
+        ...inferredRoutes.map((/** @type {any} */ route) => ({
+          path: normalizeOpenApiPath(route.path),
+          method: route.method,
+          confidence: "medium",
+          source_kind: "route_code",
+          provenance: `${relativeTo(paths.repoRoot, route.file)}#${route.method} ${route.path}`
+        }))
+      );
+    }
+    if (inferredServerActions.length > 0) {
+      findings.push({
+        kind: "next_server_actions",
+        files: [...new Set(inferredServerActions.map((/** @type {any} */ action) => relativeTo(paths.repoRoot, action.file)))],
+        action_count: inferredServerActions.length
+      });
+      candidates.capabilities.push(
+        ...inferredServerActions.map((/** @type {any} */ action) =>
+          makeCandidateRecord({
+            kind: "capability",
+            idHint: action.id_hint,
+            label: titleCase(action.id_hint.replace(/^cap_/, "")),
+            confidence: "medium",
+            sourceKind: action.source_kind,
+            provenance: `${relativeTo(paths.repoRoot, action.file)}#${action.function_name}`,
+            endpoint: {
+              method: action.method,
+              path: normalizeOpenApiPath(action.path)
+            },
+            path_params: (action.path_params || []).map((/** @type {any} */ 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"
+          })
+        )
+      );
+      candidates.routes.push(
+        ...inferredServerActions.map((/** @type {any} */ action) => ({
+          path: normalizeOpenApiPath(action.path),
+          method: action.method,
+          confidence: "medium",
+          source_kind: action.source_kind,
+          provenance: `${relativeTo(paths.repoRoot, action.file)}#${action.function_name}`
+        }))
+      );
+    }
+    if (inferredAuthCapabilities.length > 0) {
+      findings.push({
+        kind: "next_auth_flows",
+        files: [...new Set(inferredAuthCapabilities.flatMap((/** @type {any} */ capability) => capability.provenance || []))],
+        capability_count: inferredAuthCapabilities.length
+      });
+      candidates.capabilities.push(
+        ...inferredAuthCapabilities.map((/** @type {any} */ 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
+          })
+        )
+      );
+      candidates.routes.push(
+        ...inferredAuthCapabilities.map((/** @type {any} */ capability) => ({
+          path: normalizeOpenApiPath(capability.path),
+          method: capability.method,
+          confidence: "medium",
+          source_kind: capability.source_kind,
+          provenance: capability.provenance
+        }))
+      );
+    }
+  }
+  const reactRoutes = inferReactRoutes(path.join(paths.workspaceRoot, "apps", "web"));
+  if (reactRoutes.length > 0) {
+    findings.push({
+      kind: "react_routes",
+      file: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web", "src", "App.tsx")),
+      routes: reactRoutes
+    });
+    candidates.routes.push(...reactRoutes.map((/** @type {any} */ route) => ({
+      path: route,
+      method: "GET",
+      confidence: "medium",
+      source_kind: "generated_artifact",
+      provenance: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web", "src", "App.tsx"))
+    })));
+    candidates.stacks.push("react_web");
+  }
+  const svelteRoutes = inferSvelteRoutes(path.join(paths.workspaceRoot, "apps", "web-sveltekit"));
+  if (svelteRoutes.length > 0) {
+    findings.push({
+      kind: "sveltekit_routes",
+      file: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web-sveltekit", "src", "routes")),
+      routes: svelteRoutes
+    });
+    candidates.routes.push(...svelteRoutes.map((/** @type {any} */ route) => ({
+      path: route,
+      method: "GET",
+      confidence: "medium",
+      source_kind: "generated_artifact",
+      provenance: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web-sveltekit", "src", "routes"))
+    })));
+    candidates.stacks.push("sveltekit_web");
+  }
+  candidates.capabilities = dedupeCandidateRecords(candidates.capabilities, (/** @type {any} */ record) => record.id_hint);
+  candidates.routes = dedupeCandidateRecords(
+    candidates.routes.map((/** @type {any} */ route) => ({
+      ...route,
+      id_hint: route.id_hint || `${route.method}_${route.path}`
+    })),
+    (/** @type {any} */ record) => `${record.method}:${record.path}:${record.source_kind}`
+  ).map((/** @type {any} */ record) => {
+    const { id_hint, ...route } = record;
+    return route;
+  });
+
+  return { findings, candidates };
+}

package/src/workflows/import-app/api/openapi.js

@@ -0,0 +1,257 @@
+// @ts-check
+
+import { slugify, titleCase } from "../../../text-helpers.js";
+import { makeCandidateRecord } from "../shared.js";
+
+/** @param {WorkflowRecord} document @param {any} provenance @param {string} sourceKind @returns {any} */
+export function parseOpenApiDocument(document, provenance, sourceKind = "openapi") {
+  /** @type {any[]} */
+  const capabilities = [];
+  /** @type {any[]} */
+  const routes = [];
+  const pathsObject = document.paths || {};
+  for (const [endpointPath, operations] of Object.entries(pathsObject)) {
+    for (const [method, operation] of Object.entries(operations || {})) {
+      const normalizedMethod = method.toUpperCase();
+      const operationId = operation.operationId || `candidate_${normalizedMethod.toLowerCase()}_${slugify(endpointPath)}`;
+      const requestSchema =
+        operation.requestBody?.content?.["application/json"]?.schema?.$ref ||
+        operation.requestBody?.content?.["application/json"]?.schema?.type ||
+        null;
+      const successResponse = Object.entries(operation.responses || {}).find((/** @type {any} */ [status]) => /^2/.test(status));
+      const responseSchema =
+        successResponse?.[1]?.content?.["application/json"]?.schema?.$ref ||
+        successResponse?.[1]?.content?.["application/json"]?.schema?.type ||
+        null;
+      const parameterHints = extractOpenApiParameterHints(document, endpointPath, operation);
+      const requestFieldHints = extractOpenApiSchemaFieldHints(document, operation.requestBody?.content?.["application/json"]?.schema);
+      const responseFieldHints = extractOpenApiSchemaFieldHints(document, successResponse?.[1]?.content?.["application/json"]?.schema);
+      const securitySchemes = extractOpenApiSecuritySchemes(document, operation);
+      capabilities.push(
+        makeCandidateRecord({
+          kind: "capability",
+          idHint: operationId,
+          label: operation.summary || titleCase(operationId.replace(/^cap_/, "")),
+          confidence: "high",
+          sourceKind,
+          provenance: `${provenance}#${normalizedMethod} ${endpointPath}`,
+          endpoint: {
+            method: normalizedMethod,
+            path: endpointPath
+          },
+          input_hint: requestSchema,
+          output_hint: responseSchema,
+          input_fields: requestFieldHints.body_fields,
+          output_fields: responseFieldHints.body_fields,
+          path_params: parameterHints.path,
+          query_params: parameterHints.query,
+          header_params: parameterHints.header,
+          security_schemes: securitySchemes,
+          auth_hint: securitySchemes.length > 0 ? "secured" : "unknown"
+        })
+      );
+      routes.push({
+        path: endpointPath,
+        method: normalizedMethod,
+        source_kind: sourceKind,
+        provenance: `${provenance}#${normalizedMethod} ${endpointPath}`
+      });
+    }
+  }
+  return { capabilities, routes };
+}
+
+/** @param {string} ref @returns {any} */
+function openApiRefName(ref) {
+  if (!ref || typeof ref !== "string") {
+    return null;
+  }
+  return ref.split("/").pop() || null;
+}
+
+/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @param {Set<any>} seen @returns {any} */
+function resolveOpenApiSchema(document, schema, seen = new Set()) {
+  if (!schema || typeof schema !== "object") {
+    return null;
+  }
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) {
+      return null;
+    }
+    seen.add(schema.$ref);
+    if (!schema.$ref.startsWith("#/")) {
+      return null;
+    }
+    const segments = schema.$ref.slice(2).split("/");
+    let current = document;
+    for (const segment of segments) {
+      current = current?.[segment];
+      if (current == null) {
+        return null;
+      }
+    }
+    return resolveOpenApiSchema(document, current, seen) || current;
+  }
+  return schema;
+}
+
+/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @param {Set<any>} fields @param {Set<any>} seen @returns {any} */
+function collectOpenApiObjectFields(document, schema, fields = new Set(), seen = new Set()) {
+  const resolved = resolveOpenApiSchema(document, schema, seen);
+  if (!resolved || typeof resolved !== "object") {
+    return fields;
+  }
+  if (resolved.type === "array" && resolved.items) {
+    collectOpenApiObjectFields(document, resolved.items, fields, seen);
+    return fields;
+  }
+  for (const propertyName of Object.keys(resolved.properties || {})) {
+    fields.add(propertyName);
+  }
+  for (const entry of resolved.allOf || []) {
+    collectOpenApiObjectFields(document, entry, fields, seen);
+  }
+  for (const entry of resolved.oneOf || []) {
+    collectOpenApiObjectFields(document, entry, fields, seen);
+  }
+  for (const entry of resolved.anyOf || []) {
+    collectOpenApiObjectFields(document, entry, fields, seen);
+  }
+  return fields;
+}
+
+/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @returns {any} */
+function extractOpenApiSchemaFieldHints(document, schema) {
+  const fieldNames = [...collectOpenApiObjectFields(document, schema)].sort();
+  return {
+    schema_ref: openApiRefName(schema?.$ref || null),
+    body_fields: fieldNames
+  };
+}
+
+/** @param {string} endpointPath @param {WorkflowRecord} operation @returns {any} */
+function collectOpenApiParameters(endpointPath, operation) {
+  const pathParams = [...String(endpointPath || "").matchAll(/\{([^}]+)\}/g)].map((/** @type {any} */ match) => ({
+    name: match[1],
+    in: "path",
+    required: true
+  }));
+  return [...pathParams, ...((operation.parameters || []).filter(Boolean))];
+}
+
+/** @param {WorkflowRecord} document @param {string} endpointPath @param {WorkflowRecord} operation @returns {any} */
+function extractOpenApiParameterHints(document, endpointPath, operation) {
+  /** @type {WorkflowRecord} */
+  const grouped = {
+    path: [],
+    query: [],
+    header: []
+  };
+  for (const parameter of collectOpenApiParameters(endpointPath, operation)) {
+    const schema = resolveOpenApiSchema(document, parameter.schema || null);
+    const target = parameter.in === "query" ? "query" : parameter.in === "header" ? "header" : "path";
+    grouped[target].push({
+      name: parameter.name,
+      required: Boolean(parameter.required),
+      type: schema?.type || null
+    });
+  }
+  for (const key of Object.keys(grouped)) {
+    grouped[key] = grouped[key].sort((/** @type {any} */ a, /** @type {any} */ b) => a.name.localeCompare(b.name));
+  }
+  return grouped;
+}
+
+/** @param {WorkflowRecord} document @param {WorkflowRecord} operation @returns {any} */
+function extractOpenApiSecuritySchemes(document, operation) {
+  const securityEntries = [...(operation.security || []), ...(document.security || [])];
+  const schemes = new Set();
+  for (const entry of securityEntries) {
+    for (const key of Object.keys(entry || {})) {
+      schemes.add(key);
+    }
+  }
+  return [...schemes].sort();
+}
+
+/** @param {string} text @returns {any} */
+export function parseOpenApiYaml(text) {
+  /** @type {WorkflowRecord} */
+  const doc = { paths: {} };
+  let currentPath = null;
+  let currentMethod = null;
+  let inRequestBody = false;
+  let inResponses = false;
+  let currentResponseStatus = null;
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/#.*$/, "");
+    if (!line.trim()) {
+      continue;
+    }
+    const pathMatch = line.match(/^\s{2}(\/[^:]+):\s*$/);
+    if (pathMatch) {
+      currentPath = pathMatch[1];
+      currentMethod = null;
+      doc.paths[currentPath] = doc.paths[currentPath] || {};
+      inRequestBody = false;
+      inResponses = false;
+      currentResponseStatus = null;
+      continue;
+    }
+    const methodMatch = line.match(/^\s{4}(get|post|put|patch|delete):\s*$/i);
+    if (methodMatch && currentPath) {
+      currentMethod = methodMatch[1].toLowerCase();
+      doc.paths[currentPath][currentMethod] = { responses: {} };
+      inRequestBody = false;
+      inResponses = false;
+      currentResponseStatus = null;
+      continue;
+    }
+    if (!currentPath || !currentMethod) {
+      continue;
+    }
+    const operation = doc.paths[currentPath][currentMethod];
+    const operationIdMatch = line.match(/^\s{6}operationId:\s*(.+)$/);
+    if (operationIdMatch) {
+      operation.operationId = operationIdMatch[1].trim().replace(/^["']|["']$/g, "");
+      continue;
+    }
+    const summaryMatch = line.match(/^\s{6}summary:\s*(.+)$/);
+    if (summaryMatch) {
+      operation.summary = summaryMatch[1].trim().replace(/^["']|["']$/g, "");
+      continue;
+    }
+    if (/^\s{6}requestBody:\s*$/.test(line)) {
+      inRequestBody = true;
+      inResponses = false;
+      currentResponseStatus = null;
+      continue;
+    }
+    if (/^\s{6}responses:\s*$/.test(line)) {
+      inResponses = true;
+      inRequestBody = false;
+      currentResponseStatus = null;
+      continue;
+    }
+    const responseStatusMatch = line.match(/^\s{8}['"]?([0-9Xx]{3})['"]?:\s*$/);
+    if (inResponses && responseStatusMatch) {
+      currentResponseStatus = responseStatusMatch[1];
+      operation.responses[currentResponseStatus] = operation.responses[currentResponseStatus] || {};
+      continue;
+    }
+    const refMatch = line.match(/^\s+\$ref:\s*(.+)$/);
+    if (refMatch) {
+      const ref = refMatch[1].trim().replace(/^["']|["']$/g, "");
+      if (inRequestBody) {
+        operation.requestBody = operation.requestBody || { content: { "application/json": { schema: {} } } };
+        operation.requestBody.content["application/json"].schema.$ref = ref;
+      } else if (inResponses && currentResponseStatus) {
+        operation.responses[currentResponseStatus].content = operation.responses[currentResponseStatus].content || { "application/json": { schema: {} } };
+        operation.responses[currentResponseStatus].content["application/json"].schema.$ref = ref;
+      }
+    }
+  }
+
+  return doc;
+}