@topogram/cli 0.3.63 → 0.3.65

package/src/import/core/runner/candidates.js

@@ -0,0 +1,217 @@
+// @ts-check
+
+import { collectionPatternFromPresentations } from "../../../ui/taxonomy.js";
+import { dedupeCandidateRecords, idHintify, makeCandidateRecord } from "../shared.js";
+
+/**
+ * @param {Record<string, any>} allCandidates
+ * @returns {string[]}
+ */
+export function importedApiCapabilityIds(allCandidates) {
+  return [...(allCandidates?.api?.capabilities || [])]
+    .map((capability) => capability.id_hint)
+    .filter(Boolean)
+    .sort();
+}
+
+/**
+ * @param {any} screen
+ * @returns {string|null}
+ */
+export function loadCapabilityForScreen(screen) {
+  return capabilityHintsForScreen(screen).find((hint) => /^cap_(list|get)_/.test(hint)) || null;
+}
+
+/**
+ * @param {any} value
+ * @returns {string|null}
+ */
+function normalizeCapabilityHint(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value && typeof value === "object") {
+    return value.id_hint || value.id || value.capability_hint || value.capability?.id || null;
+  }
+  return null;
+}
+
+/**
+ * @param {any} screen
+ * @returns {string[]}
+ */
+export function capabilityHintsForScreen(screen) {
+  const rawHints = Array.isArray(screen.capability_hints)
+    ? screen.capability_hints
+    : [screen.capability_hints].filter(Boolean);
+  return rawHints.map(normalizeCapabilityHint).filter(Boolean);
+}
+
+/**
+ * @param {any} candidates
+ * @returns {any[]}
+ */
+export function uiWidgetCandidates(candidates) {
+  return [
+    ...(Array.isArray(candidates?.widgets) ? candidates.widgets : []),
+    ...(Array.isArray(candidates?.components) ? candidates.components : [])
+  ];
+}
+
+/**
+ * @param {any} widget
+ * @param {Record<string, any>} allCandidates
+ * @returns {string|null}
+ */
+export function inferredDataSourceForWidget(widget, allCandidates) {
+  if (widget.data_source) {
+    return widget.data_source;
+  }
+  const capabilityIds = importedApiCapabilityIds(allCandidates);
+  const screenStem = String(widget.screen_id || "")
+    .replace(/_(list|index|table|grid|results)$/, "")
+    .replace(/^list_/, "");
+  return capabilityIds.find((id) => /^cap_(list|get)_/.test(id) && id.includes(screenStem)) ||
+    capabilityIds.find((id) => /^cap_(list|get)_/.test(id)) ||
+    null;
+}
+
+/**
+ * @param {any} candidates
+ * @returns {any[]}
+ */
+function deriveUiWidgetCandidates(candidates) {
+  /** @type {any[]} */
+  const screens = candidates.screens || [];
+  /** @type {any[]} */
+  const actions = candidates.actions || [];
+  const presentations = [...new Set(actions
+    .filter((entry) => entry.kind === "ui_presentation")
+    .map((entry) => entry.presentation)
+    .filter(Boolean))].sort();
+  const widgetScreens = screens.filter((screen) => ["list", "dashboard", "analytics", "report", "feed", "inbox"].includes(screen.screen_kind));
+
+  return widgetScreens.map((screen) => {
+    const pattern = collectionPatternFromPresentations(presentations);
+    const widgetStem = idHintify(`${screen.id_hint}_results`);
+    const loadCapability = loadCapabilityForScreen(screen);
+    return makeCandidateRecord({
+      kind: "widget",
+      idHint: `widget_${widgetStem}`,
+      label: `${screen.label || screen.id_hint} results`,
+      confidence: presentations.length > 0 ? "medium" : "low",
+      sourceKind: "ui_projection_inference",
+      sourceOfTruth: "candidate",
+      provenance: screen.provenance || [],
+      screen_id: screen.id_hint,
+      region: "results",
+      pattern,
+      data_prop: "rows",
+      data_source: loadCapability,
+      inferred_props: [{ name: "rows", type: "array", required: true, source: loadCapability }],
+      inferred_events: [],
+      inferred_region: "results",
+      inferred_pattern: pattern,
+      evidence: screen.provenance || [],
+      missing_decisions: [
+        "confirm widget reuse boundary",
+        "confirm prop names and data source",
+        "confirm events and behavior",
+        "confirm supported regions and patterns"
+      ],
+      notes: [
+        "Imported widget candidates are review-only.",
+        "Confirm props, behavior, events, and reuse before adoption."
+      ]
+    });
+  });
+}
+
+/**
+ * @param {string} track
+ * @param {any} candidates
+ * @returns {any}
+ */
+export function normalizeCandidatesForTrack(track, candidates) {
+  /** @param {any} record */
+  const idHint = (record) => record.id_hint;
+  /** @param {any} record */
+  const apiRouteKey = (record) => `${record.method}:${record.path}:${record.source_kind}`;
+  /** @param {any} entry */
+  const withoutIdHint = ({ id_hint, ...entry }) => entry;
+  if (track === "db") {
+    return {
+      entities: dedupeCandidateRecords(candidates.entities || [], idHint),
+      enums: dedupeCandidateRecords(candidates.enums || [], idHint),
+      relations: dedupeCandidateRecords(candidates.relations || [], idHint),
+      indexes: dedupeCandidateRecords(candidates.indexes || [], idHint)
+    };
+  }
+  if (track === "api") {
+    return {
+      capabilities: dedupeCandidateRecords(candidates.capabilities || [], idHint),
+      routes: dedupeCandidateRecords(
+        /** @type {any[]} */ (candidates.routes || []).map((route) => ({ ...route, id_hint: route.id_hint || `${route.method}_${route.path}` })),
+        apiRouteKey
+      ).map(withoutIdHint),
+      stacks: [...new Set(candidates.stacks || [])].sort()
+    };
+  }
+  if (track === "ui") {
+    const explicitWidgets = uiWidgetCandidates(candidates);
+    const derivedWidgets = deriveUiWidgetCandidates(candidates);
+    return {
+      screens: dedupeCandidateRecords(candidates.screens || [], idHint),
+      routes: dedupeCandidateRecords(candidates.routes || [], idHint),
+      actions: dedupeCandidateRecords(candidates.actions || [], idHint),
+      widgets: dedupeCandidateRecords([...explicitWidgets, ...derivedWidgets], idHint),
+      stacks: [...new Set(candidates.stacks || [])].sort()
+    };
+  }
+  if (track === "verification") {
+    return {
+      verifications: dedupeCandidateRecords(candidates.verifications || [], idHint),
+      scenarios: dedupeCandidateRecords(candidates.scenarios || [], idHint),
+      frameworks: [...new Set(candidates.frameworks || [])].sort(),
+      scripts: dedupeCandidateRecords(
+        /** @type {any[]} */ (candidates.scripts || []).map((script) => ({
+          ...script,
+          id_hint: script.id_hint || `${script.file || "package.json"}:${script.name || "test"}`
+        })),
+        idHint
+      ).map(withoutIdHint)
+    };
+  }
+  return {
+    workflows: dedupeCandidateRecords(candidates.workflows || [], idHint),
+    workflow_states: dedupeCandidateRecords(candidates.workflow_states || [], idHint),
+    workflow_transitions: dedupeCandidateRecords(candidates.workflow_transitions || [], idHint)
+  };
+}
+
+/**
+ * @param {any} uiCandidates
+ * @param {Record<string, any>} allCandidates
+ * @returns {any}
+ */
+export function enrichUiWidgetDataSources(uiCandidates, allCandidates) {
+  if (!uiCandidates) {
+    return uiCandidates;
+  }
+  const widgets = uiWidgetCandidates(uiCandidates);
+  const { components, ...canonicalCandidates } = uiCandidates;
+  return {
+    ...canonicalCandidates,
+    widgets: widgets.map((widget) => {
+      const dataSource = inferredDataSourceForWidget(widget, allCandidates);
+      const dataProp = widget.data_prop || "rows";
+      return {
+        ...widget,
+        data_source: widget.data_source || dataSource,
+        inferred_props: /** @type {any[]} */ (widget.inferred_props || []).map((prop) =>
+          prop.name === dataProp ? { ...prop, source: prop.source || dataSource } : prop
+        )
+      };
+    })
+  };
+}

package/src/import/core/runner/options.js

@@ -0,0 +1,22 @@
+// @ts-check
+
+import { IMPORT_TRACKS } from "../contracts.js";
+
+/**
+ * @param {unknown} fromValue
+ * @returns {string[]}
+ */
+export function parseImportTracks(fromValue) {
+  if (!fromValue) {
+    return ["db", "api", "ui", "workflows", "verification"];
+  }
+  const tracks = String(fromValue).split(",").map((track) => track.trim().toLowerCase()).filter(Boolean);
+  if (tracks.length === 0) {
+    throw new Error("Expected --from to include at least one import track");
+  }
+  const invalid = tracks.filter((track) => !IMPORT_TRACKS.has(track));
+  if (invalid.length > 0) {
+    throw new Error(`Unsupported import track(s): ${invalid.join(", ")}`);
+  }
+  return [...new Set(tracks)];
+}

package/src/import/core/runner/reports.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import { ensureTrailingNewline } from "../shared.js";
+import { uiWidgetCandidates } from "./candidates.js";
+
+/**
+ * @param {string} track
+ * @param {any} candidates
+ * @returns {string}
+ */
+export function reportMarkdown(track, candidates) {
+  if (track === "db") {
+    return ensureTrailingNewline(
+      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n`
+    );
+  }
+  if (track === "api") {
+    return ensureTrailingNewline(
+      `# API Import Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+    );
+  }
+  if (track === "ui") {
+    const widgets = uiWidgetCandidates(candidates);
+    const widgetLines = widgets.map((widget) =>
+      `- \`${widget.id_hint}\` confidence ${widget.confidence || "unknown"} pattern \`${widget.pattern || widget.inferred_pattern || "unknown"}\` region \`${widget.region || widget.inferred_region || "unknown"}\` evidence ${(widget.evidence || widget.provenance || []).length} missing decisions ${(widget.missing_decisions || []).length}`
+    );
+    return ensureTrailingNewline(
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Widgets: ${widgets.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topogram/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+    );
+  }
+  if (track === "verification") {
+    return ensureTrailingNewline(
+      `# Verification Import Report\n\n- Verifications: ${candidates.verifications.length}\n- Scenarios: ${candidates.scenarios.length}\n- Frameworks: ${candidates.frameworks.length ? candidates.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.scripts.length}\n`
+    );
+  }
+  return ensureTrailingNewline(
+    `# Workflow Import Report\n\n- Workflows: ${candidates.workflows.length}\n- States: ${candidates.workflow_states.length}\n- Transitions: ${candidates.workflow_transitions.length}\n`
+  );
+}
+
+/**
+ * @param {Record<string, any>} candidates
+ * @param {string[]} tracks
+ * @returns {string}
+ */
+export function appReportMarkdown(candidates, tracks) {
+  return ensureTrailingNewline(
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+  );
+}

package/src/import/core/runner/run.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import { createImportContext } from "../context.js";
+import { enrichUiWidgetDataSources } from "./candidates.js";
+import { parseImportTracks } from "./options.js";
+import { appReportMarkdown, reportMarkdown } from "./reports.js";
+import { runTrack } from "./tracks.js";
+import { draftUiProjectionFiles } from "./ui-drafts.js";
+
+/**
+ * @param {string} inputPath
+ * @param {Record<string, any>} [options]
+ * @returns {{ summary: any, files: Record<string, string>, defaultOutDir: string }}
+ */
+export function runImportApp(inputPath, options = {}) {
+  const tracks = parseImportTracks(options.from);
+  const context = createImportContext(inputPath, options);
+  /** @type {Record<string, ReturnType<typeof runTrack>>} */
+  const resultsByTrack = {};
+  context.priorResults = resultsByTrack;
+  context.scanDocsSummary = options.scanDocsSummary || null;
+  /** @type {Record<string, any[]>} */
+  const findings = {};
+  /** @type {Record<string, any>} */
+  const candidates = {};
+  /** @type {Record<string, string>} */
+  const files = {};
+
+  for (const track of tracks) {
+    if (track === "workflows") {
+      if (!resultsByTrack.db) {
+        resultsByTrack.db = runTrack(context, "db");
+      }
+      if (!resultsByTrack.api) {
+        resultsByTrack.api = runTrack(context, "api");
+      }
+    }
+    if (track === "verification") {
+      if (!resultsByTrack.api) {
+        resultsByTrack.api = runTrack(context, "api");
+      }
+    }
+    const result = runTrack(context, track);
+    resultsByTrack[track] = result;
+    findings[track] = result.findings;
+    candidates[track] = result.candidates;
+    files[`candidates/app/${track}/findings.json`] = `${JSON.stringify(result.findings, null, 2)}\n`;
+    files[`candidates/app/${track}/candidates.json`] = `${JSON.stringify(result.candidates, null, 2)}\n`;
+    files[`candidates/app/${track}/report.md`] = reportMarkdown(track, result.candidates);
+  }
+
+  if (candidates.ui) {
+    candidates.ui = enrichUiWidgetDataSources(candidates.ui, candidates);
+    files["candidates/app/ui/candidates.json"] = `${JSON.stringify(candidates.ui, null, 2)}\n`;
+    files["candidates/app/ui/report.md"] = reportMarkdown("ui", candidates.ui);
+    Object.assign(files, draftUiProjectionFiles(context, candidates.ui, candidates));
+  }
+
+  const summary = {
+    type: "import_app_report",
+    workspace: context.paths.workspaceRoot,
+    topogram_root: context.paths.topogramRoot,
+    bootstrapped_topogram_root: context.paths.bootstrappedTopogramRoot,
+    tracks,
+    findings_count: Object.values(findings).reduce((total, entries) => total + entries.length, 0),
+    extractor_detections: Object.fromEntries(Object.entries(resultsByTrack).map(([track, result]) => [track, result.extractor_detections])),
+    candidates
+  };
+
+  files["candidates/app/findings.json"] = `${JSON.stringify(findings, null, 2)}\n`;
+  files["candidates/app/candidates.json"] = `${JSON.stringify(candidates, null, 2)}\n`;
+  files["candidates/app/report.md"] = appReportMarkdown(candidates, tracks);
+
+  return {
+    summary,
+    files,
+    defaultOutDir: context.paths.topogramRoot
+  };
+}

package/src/import/core/runner/tracks.js

@@ -0,0 +1,150 @@
+// @ts-check
+
+import { getEnrichersForTrack, getExtractorsForTrack } from "../registry.js";
+import { normalizeCandidatesForTrack } from "./candidates.js";
+
+/**
+ * @param {any} context
+ * @param {any[]} extractors
+ * @returns {Array<{ extractor: any, detection: any }>}
+ */
+function sortExtractors(context, extractors) {
+  return extractors
+    .map((extractor) => ({ extractor, detection: extractor.detect(context) || { score: 0, reasons: [] } }))
+    .filter((entry) => entry.detection.score > 0)
+    .sort((a, b) => b.detection.score - a.detection.score || a.extractor.id.localeCompare(b.extractor.id));
+}
+
+/**
+ * @param {string} track
+ * @param {Array<{ extractor: any, detection: any }>} detections
+ * @returns {Array<{ extractor: any, detection: any }>}
+ */
+function selectDetectionsForTrack(track, detections) {
+  if (track === "db") {
+    const prisma = detections.find((entry) => entry.extractor.id === "db.prisma");
+    if (prisma) return [prisma];
+    const djangoModels = detections.find((entry) => entry.extractor.id === "db.django-models");
+    if (djangoModels) return [djangoModels];
+    const efCore = detections.find((entry) => entry.extractor.id === "db.ef-core");
+    if (efCore) return [efCore];
+    const room = detections.find((entry) => entry.extractor.id === "db.room");
+    if (room) return [room];
+    const swiftData = detections.find((entry) => entry.extractor.id === "db.swiftdata");
+    if (swiftData) return [swiftData];
+    const dotnetModels = detections.find((entry) => entry.extractor.id === "db.dotnet-models");
+    if (dotnetModels) return [dotnetModels];
+    const flutterEntities = detections.find((entry) => entry.extractor.id === "db.flutter-entities");
+    if (flutterEntities) return [flutterEntities];
+    const reactNativeEntities = detections.find((entry) => entry.extractor.id === "db.react-native-entities");
+    if (reactNativeEntities) return [reactNativeEntities];
+    const railsSchema = detections.find((entry) => entry.extractor.id === "db.rails-schema");
+    if (railsSchema) return [railsSchema];
+    const liquibase = detections.find((entry) => entry.extractor.id === "db.liquibase");
+    if (liquibase) return [liquibase];
+    const myBatisXml = detections.find((entry) => entry.extractor.id === "db.mybatis-xml");
+    if (myBatisXml) return [myBatisXml];
+    const jpa = detections.find((entry) => entry.extractor.id === "db.jpa");
+    if (jpa) return [jpa];
+    const drizzle = detections.find((entry) => entry.extractor.id === "db.drizzle");
+    if (drizzle) return [drizzle];
+    const sql = detections.find((entry) => entry.extractor.id === "db.sql");
+    if (sql) return [sql];
+    const snapshot = detections.find((entry) => entry.extractor.id === "db.snapshot");
+    return snapshot ? [snapshot] : [];
+  }
+  if (track === "api") {
+    const openApi = detections.find((entry) => entry.extractor.id === "api.openapi");
+    if (openApi) return [openApi];
+    const openApiCode = detections.find((entry) => entry.extractor.id === "api.openapi-code");
+    if (openApiCode) return [openApiCode];
+    const graphQlSdl = detections.find((entry) => entry.extractor.id === "api.graphql-sdl");
+    if (graphQlSdl) return [graphQlSdl];
+    const trpc = detections.find((entry) => entry.extractor.id === "api.trpc");
+    if (trpc) return [trpc];
+    const aspNetCore = detections.find((entry) => entry.extractor.id === "api.aspnet-core");
+    if (aspNetCore) return [aspNetCore];
+    const retrofit = detections.find((entry) => entry.extractor.id === "api.retrofit");
+    if (retrofit) return [retrofit];
+    const swiftWebApi = detections.find((entry) => entry.extractor.id === "api.swift-webapi");
+    if (swiftWebApi) return [swiftWebApi];
+    const flutterDio = detections.find((entry) => entry.extractor.id === "api.flutter-dio");
+    if (flutterDio) return [flutterDio];
+    const reactNativeRepository = detections.find((entry) => entry.extractor.id === "api.react-native-repository");
+    if (reactNativeRepository) return [reactNativeRepository];
+    const fastify = detections.find((entry) => entry.extractor.id === "api.fastify");
+    if (fastify) return [fastify];
+    const express = detections.find((entry) => entry.extractor.id === "api.express");
+    if (express) return [express];
+    const djangoRoutes = detections.find((entry) => entry.extractor.id === "api.django-routes");
+    if (djangoRoutes) return [djangoRoutes];
+    const railsRoutes = detections.find((entry) => entry.extractor.id === "api.rails-routes");
+    if (railsRoutes) return [railsRoutes];
+    const micronaut = detections.find((entry) => entry.extractor.id === "api.micronaut");
+    if (micronaut) return [micronaut];
+    const jaxrs = detections.find((entry) => entry.extractor.id === "api.jaxrs");
+    if (jaxrs) return [jaxrs];
+    const springWeb = detections.find((entry) => entry.extractor.id === "api.spring-web");
+    if (springWeb) return [springWeb];
+  }
+  return detections;
+}
+
+/**
+ * @param {string} track
+ * @returns {any}
+ */
+function initialCandidatesForTrack(track) {
+  if (track === "db") {
+    return { entities: [], enums: [], relations: [], indexes: [] };
+  }
+  if (track === "api") {
+    return { capabilities: [], routes: [], stacks: [] };
+  }
+  if (track === "ui") {
+    return { screens: [], routes: [], actions: [], stacks: [] };
+  }
+  if (track === "verification") {
+    return { verifications: [], scenarios: [], frameworks: [], scripts: [] };
+  }
+  return { workflows: [], workflow_states: [], workflow_transitions: [] };
+}
+
+/**
+ * @param {any} context
+ * @param {string} track
+ * @returns {{ findings: any[], candidates: any, extractor_detections: any[] }}
+ */
+export function runTrack(context, track) {
+  const findings = [];
+  const rawCandidates = initialCandidatesForTrack(track);
+
+  for (const { extractor, detection } of selectDetectionsForTrack(track, sortExtractors(context, getExtractorsForTrack(track)))) {
+    const result = extractor.extract(context) || { findings: [], candidates: {} };
+    findings.push({
+      extractor: extractor.id,
+      detection,
+      findings: result.findings || []
+    });
+    for (const [key, value] of Object.entries(result.candidates || {})) {
+      if (Array.isArray(rawCandidates[key])) {
+        rawCandidates[key].push(...value);
+      } else if (Array.isArray(value)) {
+        rawCandidates[key] = [...value];
+      }
+    }
+  }
+
+  let candidates = normalizeCandidatesForTrack(track, rawCandidates);
+  for (const enricher of getEnrichersForTrack(track)) {
+    const applies = enricher.applies(context, candidates);
+    if (!applies) continue;
+    candidates = normalizeCandidatesForTrack(track, enricher.enrich(context, candidates) || candidates);
+  }
+
+  return {
+    findings: findings.flatMap((entry) => entry.findings || []),
+    candidates,
+    extractor_detections: findings.map(({ extractor, detection }) => ({ extractor, ...detection }))
+  };
+}