@topogram/cli 0.3.54 → 0.3.55

package/src/validator/index.js

@@ -2449,23 +2449,23 @@ function validateProjectionUiOwnership(errors, statement, fieldMap) {
     return;
   }
 
-  const platform = symbolValue(getFieldValue(statement, "type"));
+  const projectionType = symbolValue(getFieldValue(statement, "type"));
   for (const key of SHARED_UI_SEMANTIC_BLOCKS) {
     const field = fieldMap.get(key)?.[0];
     if (!field || field.value.type !== "block") {
       continue;
     }
-    if (platform !== "ui_contract") {
+    if (projectionType !== "ui_contract") {
       pushError(
         errors,
-        `Projection ${statement.id} ${key} belongs on shared UI projections; concrete UI projections may define screen_routes and platform surface hints only`,
+        `Projection ${statement.id} ${key} belongs on shared UI projections; concrete UI projections may define screen_routes and surface hints only`,
         field.loc
       );
     }
   }
 
   const routesField = fieldMap.get("screen_routes")?.[0];
-  if (routesField?.value.type === "block" && !["web_surface", "ios_surface"].includes(platform || "")) {
+  if (routesField?.value.type === "block" && !["web_surface", "ios_surface"].includes(projectionType || "")) {
     pushError(
       errors,
       `Projection ${statement.id} screen_routes belongs on concrete UI projections; shared UI projections own semantic screens and regions`,
@@ -2979,7 +2979,7 @@ function validateProjectionUiRoutes(errors, statement, fieldMap, registry) {
 
   const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
   const seenPaths = new Set();
-  const platform = symbolValue(getFieldValue(statement, "type"));
+  const projectionType = symbolValue(getFieldValue(statement, "type"));
 
   for (const entry of routesField.value.entries) {
     const tokens = blockSymbolItems(entry).map((item) => item.value);
@@ -2999,7 +2999,7 @@ function validateProjectionUiRoutes(errors, statement, fieldMap, registry) {
       pushError(errors, `Projection ${statement.id} screen_routes for '${screenId}' must include a path`, entry.loc);
       continue;
     }
-    if ((platform === "web_surface" || platform === "ios_surface") && !routePath.startsWith("/")) {
+    if ((projectionType === "web_surface" || projectionType === "ios_surface") && !routePath.startsWith("/")) {
       pushError(errors, `Projection ${statement.id} screen_routes for '${screenId}' must use an absolute path`, entry.loc);
     }
     if (seenPaths.has(routePath)) {
@@ -3009,7 +3009,7 @@ function validateProjectionUiRoutes(errors, statement, fieldMap, registry) {
   }
 }
 
-function validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry, surfaceBlockKey, expectedPlatform) {
+function validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry, surfaceBlockKey, expectedProjectionType) {
   if (statement.kind !== "projection") {
     return;
   }
@@ -3019,9 +3019,9 @@ function validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry,
     return;
   }
 
-  const platform = symbolValue(getFieldValue(statement, "type"));
-  if (platform !== expectedPlatform) {
-    pushError(errors, `Projection ${statement.id} may only use '${surfaceBlockKey}' when platform is '${expectedPlatform}'`, surfaceField.loc);
+  const projectionType = symbolValue(getFieldValue(statement, "type"));
+  if (projectionType !== expectedProjectionType) {
+    pushError(errors, `Projection ${statement.id} may only use '${surfaceBlockKey}' when projection type is '${expectedProjectionType}'`, surfaceField.loc);
     return;
   }
 

package/src/workflows.js

@@ -1464,14 +1464,14 @@ function renderCandidateUiReportDoc(screen, routes, actions) {
   return renderMarkdownDoc(metadata, body);
 }
 
-function renderCandidateComponent(component) {
-  const propName = component.data_prop || "rows";
-  const pattern = component.pattern || "search_results";
-  const region = component.region || "results";
+function renderCandidateWidget(widget) {
+  const propName = widget.data_prop || "rows";
+  const pattern = widget.pattern || "search_results";
+  const region = widget.region || "results";
   return ensureTrailingNewline(
     [
-      `widget ${component.id_hint} {`,
-      `  name "${component.label || component.id_hint}"`,
+      `widget ${widget.id_hint} {`,
+      `  name "${widget.label || widget.id_hint}"`,
       '  description "Candidate reusable widget inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."',
       "  category collection",
       "  props {",
@@ -1491,7 +1491,7 @@ function renderProjectionPatchDoc(patch) {
     "",
     `Projection: \`${patch.projection_id}\``,
     `Kind: \`${patch.kind}\``,
-    patch.platform ? `Platform: \`${patch.platform}\`` : null,
+    patch.projection_type ? `Projection type: \`${patch.projection_type}\`` : null,
     "",
     patch.reason || "Candidate additive projection patch inferred during reconcile.",
     ""
@@ -1694,7 +1694,7 @@ function buildBundleOperatorSummary(bundle) {
     bundle.id;
   const participants = summarizeBundleParticipants(bundle);
   const capabilityIds = [...new Set((bundle.capabilities || []).map((entry) => entry.id_hint))].slice(0, 4);
-  const componentIds = [...new Set((bundle.components || []).map((entry) => entry.id_hint))].slice(0, 4);
+  const widgetIds = [...new Set((bundle.widgets || []).map((entry) => entry.id_hint))].slice(0, 4);
   const screenIds = [...new Set((bundle.screens || []).map((entry) => entry.id_hint))].slice(0, 4);
   const routePaths = [...new Set((bundle.uiRoutes || []).map((entry) => entry.path).filter(Boolean))].slice(0, 4);
   const workflowIds = [...new Set((bundle.workflows || []).map((entry) => entry.id_hint))].slice(0, 4);
@@ -1710,7 +1710,7 @@ function buildBundleOperatorSummary(bundle) {
   const evidenceKinds = [
     (bundle.entities || []).length > 0 ? "entity evidence" : null,
     (bundle.capabilities || []).length > 0 ? "API capability evidence" : null,
-    (bundle.components || []).length > 0 ? "UI widget evidence" : null,
+    (bundle.widgets || []).length > 0 ? "UI widget evidence" : null,
     (bundle.screens || []).length > 0 || (bundle.uiRoutes || []).length > 0 ? "UI screen/route evidence" : null,
     (bundle.workflows || []).length > 0 ? "workflow evidence" : null,
     (bundle.docs || []).length > 0 ? "doc evidence" : null,
@@ -1726,7 +1726,7 @@ function buildBundleOperatorSummary(bundle) {
     primaryEntityId,
     participants,
     capabilityIds,
-    componentIds,
+    widgetIds,
     screenIds,
     routePaths,
     workflowIds,
@@ -2418,7 +2418,7 @@ function getOrCreateCandidateBundle(bundles, conceptId, label) {
       enums: [],
       capabilities: [],
       shapes: [],
-      components: [],
+      widgets: [],
       screens: [],
       uiRoutes: [],
       uiActions: [],
@@ -2715,7 +2715,7 @@ function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `Enums: ${bundle.enums.length}`,
     `Capabilities: ${bundle.capabilities.length}`,
     `Shapes: ${bundle.shapes.length}`,
-    `Widgets: ${bundle.components.length}`,
+    `Widgets: ${bundle.widgets.length}`,
     `Screens: ${bundle.screens.length}`,
     `UI routes: ${bundle.uiRoutes.length}`,
     `UI actions: ${bundle.uiActions.length}`,
@@ -2733,7 +2733,7 @@ function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `- Primary entity: ${summary.primaryEntityId ? `\`${summary.primaryEntityId}\`` : "_none_"}`,
     `- Participants: ${summary.participants.label}`,
     `- Main capabilities: ${summarizeBundleSurface(bundle, summary.capabilityIds)}`,
-    `- Main widgets: ${summarizeBundleSurface(bundle, summary.componentIds)}`,
+    `- Main widgets: ${summarizeBundleSurface(bundle, summary.widgetIds)}`,
     `- Main screens: ${summarizeBundleSurface(bundle, summary.screenIds)}`,
     `- Main routes: ${summarizeBundleSurface(bundle, summary.routePaths)}`,
     `- Main workflows: ${summarizeBundleSurface(bundle, summary.workflowIds)}`,
@@ -3013,15 +3013,15 @@ function capabilityEntityTargets(capability) {
 }
 
 function projectionKindForImpact(projection) {
-  if ((projection.http || []).length > 0 || projection.platform === "api_contract") {
+  if ((projection.http || []).length > 0 || projection.type === "api_contract") {
     return "api";
   }
   if (
     (projection.uiRoutes || []).length > 0 ||
     (projection.uiWeb || []).length > 0 ||
     (projection.uiIos || []).length > 0 ||
-    projection.platform === "web_surface" ||
-    projection.platform === "ios_surface"
+    projection.type === "web_surface" ||
+    projection.type === "ios_surface"
   ) {
     return "ui";
   }
@@ -3068,7 +3068,7 @@ function buildProjectionEntityIndex(graph) {
 
   return projections.map((projection) => ({
     id: projection.id,
-    platform: projection.platform || null,
+    projection_type: projection.type || null,
     kind: projectionKindForImpact(projection),
     realizes: (projection.realizes || []).map((entry) => entry.id),
     entityIds: [...collectEntities(projection.id)].sort()
@@ -3188,7 +3188,7 @@ function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       canonical_rel_path: `verifications/${dashedTopogramId(entry.id_hint)}.tg`
     });
   }
-  for (const entry of bundle.components || []) {
+  for (const entry of bundle.widgets || []) {
     steps.push({
       action: "promote_widget",
       item: entry.id_hint,
@@ -3281,7 +3281,7 @@ function buildProjectionImpacts(bundle, projectionIndex) {
       }
       return {
         projection_id: projection.id,
-        platform: projection.platform,
+        projection_type: projection.type,
         kind: projection.kind,
         missing_capabilities: missingCapabilities,
         reason: `Projection ${projection.id} already covers the same entity surface but does not realize these imported capabilities.`
@@ -3295,7 +3295,7 @@ function buildUiImpacts(bundle, graph) {
   if ((bundle.screens || []).length === 0) {
     return [];
   }
-  const uiProjections = (graph?.byKind.projection || []).filter((projection) => ["ui_contract", "web_surface"].includes(projection.platform));
+  const uiProjections = (graph?.byKind.projection || []).filter((projection) => ["ui_contract", "web_surface"].includes(projection.type));
   const bundleScreenIds = bundle.screens.map((screen) => screen.id_hint);
   return uiProjections
     .map((projection) => {
@@ -3307,7 +3307,7 @@ function buildUiImpacts(bundle, graph) {
       return {
         projection_id: projection.id,
         kind: "ui",
-        platform: projection.platform,
+        projection_type: projection.type,
         missing_screens: missingScreens,
         reason: `UI projection ${projection.id} does not currently represent these imported screens.`
       };
@@ -3372,7 +3372,7 @@ function buildProjectionPatchCandidates(bundle) {
     patches.push({
       projection_id: impact.projection_id,
       kind: impact.kind,
-      platform: impact.platform,
+      projection_type: impact.projection_type,
       reason: impact.reason,
       missing_realizes: missingRealizes,
       missing_http: missingHttp,
@@ -3402,7 +3402,7 @@ function buildProjectionPatchCandidates(bundle) {
     patches.push({
       projection_id: impact.projection_id,
       kind: impact.kind,
-      platform: impact.platform,
+      projection_type: impact.projection_type,
       reason: impact.reason,
       missing_realizes: [],
       missing_http: [],
@@ -3448,7 +3448,7 @@ function buildProjectionPatchCandidates(bundle) {
       patches.push({
         projection_id: impact.projection_id,
         kind: impact.kind,
-        platform: impact.platform,
+        projection_type: impact.projection_type,
         reason: `Projection ${impact.projection_id} likely needs claim-based auth rules for the imported ${bundle.label.toLowerCase()} surface.`,
         missing_realizes: relatedCapabilities,
         missing_http: [],
@@ -3494,7 +3494,7 @@ function buildProjectionPatchCandidates(bundle) {
       patches.push({
         projection_id: impact.projection_id,
         kind: impact.kind,
-        platform: impact.platform,
+        projection_type: impact.projection_type,
         reason: `Projection ${impact.projection_id} likely needs permission-based auth rules for the imported ${bundle.label.toLowerCase()} surface.`,
         missing_realizes: relatedCapabilities,
         missing_http: [],
@@ -3543,7 +3543,7 @@ function buildProjectionPatchCandidates(bundle) {
       patches.push({
         projection_id: impact.projection_id,
         kind: impact.kind,
-        platform: impact.platform,
+        projection_type: impact.projection_type,
         reason: `Projection ${impact.projection_id} likely needs ownership-based auth rules for the imported ${bundle.label.toLowerCase()} surface.`,
         missing_realizes: relatedCapabilities,
         missing_http: [],
@@ -3680,7 +3680,8 @@ function bestContextBundleForCandidate(bundles, candidate) {
 function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const dbCandidates = appImport.candidates.db || { entities: [], enums: [] };
   const apiCandidates = appImport.candidates.api || { capabilities: [] };
-  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], components: [] };
+  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], widgets: [] };
+  const uiWidgetCandidates = uiCandidates.widgets || uiCandidates.components || [];
   const workflowCandidates = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
   const verificationCandidates = appImport.candidates.verification || { verifications: [], scenarios: [], frameworks: [], scripts: [] };
   const docCandidates = appImport.candidates.docs || [];
@@ -3691,7 +3692,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const canonicalRoleIds = new Set((graph?.byKind.role || []).map((entry) => entry.id));
   const canonicalEntityIds = new Set((graph?.byKind.entity || []).map((entry) => entry.id));
   const canonicalEnumIds = new Set((graph?.byKind.enum || []).map((entry) => entry.id));
-  const canonicalComponentIds = new Set((graph?.byKind.component || []).map((entry) => entry.id));
+  const canonicalWidgetIds = new Set((graph?.byKind.widget || []).map((entry) => entry.id));
   const canonicalUi = collectCanonicalUiSurface(graph || { byKind: { projection: [] } });
   const canonicalWorkflow = collectCanonicalWorkflowSurface(graph || { byKind: { decision: [] }, docs: [] });
   const canonicalDocsByKind = new Map();
@@ -3790,7 +3791,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
     bundle.uiActions.push(entry);
   }
-  function componentConceptId(entry) {
+  function widgetConceptId(entry) {
     if (entry.entity_id || entry.concept_id) {
       return entry.entity_id || entry.concept_id;
     }
@@ -3800,13 +3801,13 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     return `entity_${canonicalCandidateTerm(screenStem || entry.id_hint)}`;
   }
 
-  for (const entry of uiCandidates.components || []) {
-    if (canonicalComponentIds.has(entry.id_hint)) {
+  for (const entry of uiWidgetCandidates) {
+    if (canonicalWidgetIds.has(entry.id_hint)) {
       continue;
     }
-    const conceptId = componentConceptId(entry);
+    const conceptId = widgetConceptId(entry);
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
-    bundle.components.push(entry);
+    bundle.widgets.push(entry);
   }
   for (const entry of workflowCandidates.workflows || []) {
     if (canonicalWorkflow.workflow_docs.includes(entry.id_hint)) {
@@ -3893,7 +3894,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       bundle.enums.length > 0 ||
       bundle.capabilities.length > 0 ||
       bundle.shapes.length > 0 ||
-      bundle.components.length > 0 ||
+      bundle.widgets.length > 0 ||
       bundle.screens.length > 0 ||
       bundle.uiRoutes.length > 0 ||
       bundle.uiActions.length > 0 ||
@@ -3911,7 +3912,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
         enums: bundle.enums.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         capabilities: bundle.capabilities.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         shapes: bundle.shapes.sort((a, b) => a.id.localeCompare(b.id)),
-        components: bundle.components.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
+        widgets: bundle.widgets.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         screens: bundle.screens.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         uiRoutes: bundle.uiRoutes.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         uiActions: bundle.uiActions.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
@@ -4013,8 +4014,8 @@ function buildCandidateModelFiles(graph, appImport, topogramRoot) {
     for (const entry of bundle.verifications || []) {
       files[`${bundleRoot}/verifications/${entry.id_hint}.tg`] = renderCandidateVerification(entry, entry.scenarios || []);
     }
-    for (const entry of bundle.components || []) {
-      files[`${bundleRoot}/widgets/${entry.id_hint}.tg`] = renderCandidateComponent(entry);
+    for (const entry of bundle.widgets || []) {
+      files[`${bundleRoot}/widgets/${entry.id_hint}.tg`] = renderCandidateWidget(entry);
     }
     for (const entry of bundle.docs) {
       if (entry.existing_canonical) {
@@ -4257,7 +4258,7 @@ function projectionImpactsForAdoptionItem(bundle, step) {
     .map((impact) => ({
       projection_id: impact.projection_id,
       kind: impact.kind,
-      platform: impact.platform,
+      projection_type: impact.projection_type,
       reason: impact.reason
     }));
 }
@@ -4268,7 +4269,7 @@ function blockingDependenciesForProjectionImpacts(projectionImpacts) {
     id: `projection_review:${impact.projection_id}`,
     projection_id: impact.projection_id,
     kind: impact.kind,
-    platform: impact.platform,
+    projection_type: impact.projection_type,
     reason: impact.reason
   }));
 }
@@ -4279,7 +4280,7 @@ function blockingDependenciesForUiImpacts(uiImpacts) {
     id: `ui_review:${impact.projection_id}`,
     projection_id: impact.projection_id,
     kind: impact.kind,
-    platform: impact.platform,
+    projection_type: impact.projection_type,
     reason: impact.reason
   }));
 }
@@ -4324,7 +4325,7 @@ function buildAdoptionPlan(bundles) {
               {
                 projection_id: step.target,
                 kind: step.projection_kind || "api",
-                platform: null,
+                projection_type: null,
                 reason: `Projection ${step.target} auth rules need explicit review before promotion.`
               }
             ])
@@ -4394,7 +4395,7 @@ function buildAdoptionPlan(bundles) {
           {
             projection_id: patch.projection_id,
             kind: patch.kind,
-            platform: patch.platform,
+            projection_type: patch.projection_type,
             missing_capabilities: patch.missing_realizes || []
           }
         ],
@@ -4402,7 +4403,7 @@ function buildAdoptionPlan(bundles) {
           {
             projection_id: patch.projection_id,
             kind: patch.kind,
-            platform: patch.platform,
+            projection_type: patch.projection_type,
             missing_screens: patch.missing_screens || []
           }
         ] : [],
@@ -4411,7 +4412,7 @@ function buildAdoptionPlan(bundles) {
           {
             projection_id: patch.projection_id,
             kind: patch.kind,
-            platform: patch.platform,
+            projection_type: patch.projection_type,
             reason: patch.reason || `Projection ${patch.projection_id} needs additive review.`
           }
         ])
@@ -6975,7 +6976,7 @@ function collectCanonicalUiSurface(graph) {
   const screens = new Set();
   const routes = new Set();
   for (const projection of graph.byKind.projection || []) {
-    if (!["ui_contract", "web_surface"].includes(projection.platform)) {
+    if (!["ui_contract", "web_surface"].includes(projection.type)) {
       continue;
     }
     for (const screen of projection.uiScreens || []) {
@@ -7587,8 +7588,7 @@ function reconcileWorkflow(inputPath, options = {}) {
       enums: bundle.enums.map((entry) => entry.id_hint),
       capabilities: bundle.capabilities.map((entry) => entry.id_hint),
       shapes: bundle.shapes.map((entry) => entry.id),
-      components: bundle.components.map((entry) => entry.id_hint),
-      widgets: bundle.components.map((entry) => entry.id_hint),
+      widgets: bundle.widgets.map((entry) => entry.id_hint),
       screens: bundle.screens.map((entry) => entry.id_hint),
       workflows: bundle.workflows.map((entry) => entry.id_hint),
       docs: bundle.docs.map((entry) => entry.id),
@@ -7612,11 +7612,11 @@ function reconcileWorkflow(inputPath, options = {}) {
     : "## Promoted Canonical Items";
   files["candidates/reconcile/report.json"] = `${stableStringify(report)}\n`;
   const candidateModelBundlesMarkdown = report.candidate_model_bundles.length
-    ? report.candidate_model_bundles.map((bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.components.length} widgets, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
+    ? report.candidate_model_bundles.map((bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
   - primary concept \`${bundle.operator_summary.primaryConcept}\`${bundle.operator_summary.primaryEntityId ? `, primary entity \`${bundle.operator_summary.primaryEntityId}\`` : ""}
   - participants ${bundle.operator_summary.participants.label}
   - main capabilities ${summarizeBundleSurface(bundle, bundle.operator_summary.capabilityIds)}
-  - main widgets ${summarizeBundleSurface(bundle, bundle.operator_summary.componentIds)}
+  - main widgets ${summarizeBundleSurface(bundle, bundle.operator_summary.widgetIds)}
   - main routes ${summarizeBundleSurface(bundle, bundle.operator_summary.routePaths)}
   - candidate maintained seam mappings ${renderMaintainedSeamCandidatesInline(bundle)}
   - permission hints ${bundle.auth_permission_hints?.length ? bundle.auth_permission_hints.map((entry) => formatAuthPermissionHintInline(entry)).join(", ") : "_none_"}