@topogram/cli 0.3.64 → 0.3.66

package/src/import/core/context.d.ts

@@ -0,0 +1,3 @@
+export function createImportContext(...args: any[]): any;
+export function findNearestGitRoot(...args: any[]): any;
+export function normalizeWorkspacePaths(...args: any[]): any;

package/src/import/core/context.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { readJsonIfExists, readTextIfExists } from "./shared.js";
+import { resolveWorkspaceContext } from "../../workspace-paths.js";
 
 export function findNearestGitRoot(startDir) {
   let currentDir = path.resolve(startDir);
@@ -19,13 +20,10 @@ export function findNearestGitRoot(startDir) {
 }
 
 export function normalizeWorkspacePaths(inputPath) {
+  const context = resolveWorkspaceContext(inputPath);
   const absolute = path.resolve(inputPath);
-  const inputExists = fs.existsSync(absolute);
-  const topogramChild = path.join(absolute, "topogram");
-  const hasTopogramChild = fs.existsSync(topogramChild) && fs.statSync(topogramChild).isDirectory();
-  const isTopogramDir = path.basename(absolute) === "topogram" && inputExists;
-  const topogramRoot = isTopogramDir ? absolute : hasTopogramChild ? topogramChild : path.join(absolute, "topogram");
-  const workspaceRoot = isTopogramDir ? path.dirname(topogramRoot) : absolute;
+  const topogramRoot = context.topoRoot;
+  const workspaceRoot = context.projectRoot;
   const repoRoot = findNearestGitRoot(workspaceRoot);
   return {
     inputRoot: absolute,
@@ -33,7 +31,7 @@ export function normalizeWorkspacePaths(inputPath) {
     workspaceRoot,
     exampleRoot: workspaceRoot,
     repoRoot,
-    bootstrappedTopogramRoot: !fs.existsSync(topogramRoot)
+    bootstrappedTopogramRoot: context.bootstrappedTopoRoot
   };
 }
 

package/src/import/core/contracts.d.ts

@@ -0,0 +1 @@
+export const IMPORT_TRACKS: Set<string>;

package/src/import/core/registry.d.ts

@@ -0,0 +1,4 @@
+export const extractorRegistry: Record<string, any[]>;
+export const enricherRegistry: Record<string, any[]>;
+export function getExtractorsForTrack(...args: any[]): any[];
+export function getEnrichersForTrack(...args: any[]): any[];

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

@@ -0,0 +1,337 @@
+// @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 {string|null|undefined} screenId
+ * @returns {string}
+ */
+function screenConceptStem(screenId) {
+  return String(screenId || "")
+    .replace(/_(list|index|table|grid|results|detail|show|create|new|edit|form)$/, "")
+    .replace(/^(list|show|create|edit)_/, "");
+}
+
+/**
+ * @param {string|null|undefined} screenId
+ * @param {string} eventName
+ * @returns {string}
+ */
+function eventPayloadShapeId(screenId, eventName) {
+  const stem = screenConceptStem(screenId) || idHintify(String(screenId || "widget"));
+  return `shape_event_${idHintify(`${stem}_${eventName}`)}`;
+}
+
+/**
+ * @param {string|null|undefined} routePath
+ * @returns {{ name: string, field_type: string, required: boolean }[]}
+ */
+function routeParamFields(routePath) {
+  const fields = [];
+  const pathText = String(routePath || "");
+  const routeParamPattern = /[:{]([A-Za-z_][A-Za-z0-9_]*)}?/g;
+  for (const match of pathText.matchAll(routeParamPattern)) {
+    fields.push({
+      name: idHintify(match[1]),
+      field_type: "string",
+      required: true
+    });
+  }
+  return fields.length > 0 ? fields : [{ name: "id", field_type: "string", required: true }];
+}
+
+/**
+ * @param {any} sourceScreen
+ * @param {any[]} screens
+ * @returns {any|null}
+ */
+function matchingDetailScreen(sourceScreen, screens) {
+  const sourceStem = screenConceptStem(sourceScreen?.id_hint);
+  if (!sourceStem) {
+    return null;
+  }
+  return screens.find((screen) =>
+    screen?.id_hint !== sourceScreen?.id_hint &&
+    screen?.screen_kind === "detail" &&
+    screenConceptStem(screen.id_hint) === sourceStem
+  ) || null;
+}
+
+/**
+ * @param {any} screen
+ * @param {any[]} screens
+ * @returns {any[]}
+ */
+function inferredEventsForWidgetScreen(screen, screens) {
+  const detailScreen = matchingDetailScreen(screen, screens);
+  if (!detailScreen) {
+    return [];
+  }
+  return [{
+    name: "row_select",
+    kind: "selection",
+    action: "navigate",
+    target_screen: detailScreen.id_hint,
+    payload_shape: eventPayloadShapeId(screen?.id_hint, "row_select"),
+    confidence: "medium",
+    evidence: detailScreen.provenance || [],
+    payload_fields: routeParamFields(detailScreen.route_path),
+    requires_payload_shape_review: true
+  }];
+}
+
+/**
+ * @param {any[]} widgets
+ * @returns {any[]}
+ */
+function deriveUiWidgetEventShapeCandidates(widgets) {
+  return widgets.flatMap((widget) =>
+    (widget.inferred_events || [])
+      .filter((/** @type {any} */ event) => event.payload_shape)
+      .map((/** @type {any} */ event) => makeCandidateRecord({
+        kind: "shape",
+        idHint: event.payload_shape,
+        label: `${widget.label || widget.id_hint} ${event.name || "event"} payload`,
+        confidence: event.confidence || widget.confidence || "low",
+        sourceKind: "ui_widget_event",
+        sourceOfTruth: "candidate",
+        provenance: [
+          ...(widget.provenance || []),
+          ...(event.evidence || [])
+        ],
+        track: "ui",
+        widget_id: widget.id_hint,
+        event_name: event.name,
+        fields: event.payload_fields || [{ name: "id", field_type: "string", required: true }],
+        missing_decisions: [
+          "confirm selected row identity fields",
+          "confirm event payload shape name"
+        ],
+        notes: [
+          "Imported widget event payload shapes are review-only.",
+          "Adopt with the widget when the event binding is accepted."
+        ]
+      }))
+  );
+}
+
+/**
+ * @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);
+    const inferredEvents = inferredEventsForWidgetScreen(screen, screens);
+    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: inferredEvents,
+      inferred_region: "results",
+      inferred_pattern: pattern,
+      evidence: [
+        ...(screen.provenance || []),
+        ...inferredEvents.flatMap((event) => event.evidence || [])
+      ],
+      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);
+    const widgets = dedupeCandidateRecords([...explicitWidgets, ...derivedWidgets], idHint);
+    const eventShapes = deriveUiWidgetEventShapeCandidates(widgets);
+    return {
+      screens: dedupeCandidateRecords(candidates.screens || [], idHint),
+      routes: dedupeCandidateRecords(candidates.routes || [], idHint),
+      actions: dedupeCandidateRecords(candidates.actions || [], idHint),
+      widgets,
+      shapes: dedupeCandidateRecords([...(candidates.shapes || []), ...eventShapes], 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,51 @@
+// @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 shapes = candidates.shapes || [];
+    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"}\` events ${(widget.inferred_events || []).length} 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- Event payload shapes: ${shapes.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 \`topo/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- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\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
+  };
+}