@topogram/cli 0.3.63 → 0.3.65

package/src/workflows/reconcile/canonical-surface.js

@@ -0,0 +1,264 @@
+// @ts-check
+import { generateApiContractGraph } from "../../generator/api.js";
+import { confidenceRank } from "../docs.js";
+import { normalizeEndpointPathForMatch, normalizeOpenApiPath } from "../import-app/index.js";
+
+/** @param {import("../types.d.ts").CandidateRecord} importedEntity @param {WorkflowRecord} graphEntity @returns {any} */
+export function compareEntityFields(importedEntity, graphEntity) {
+  const graphFields = new Map((graphEntity.fields || []).map((/** @type {any} */ field) => [field.name, field]));
+  /** @type {any[]} */
+  const missing = [];
+  /** @type {any[]} */
+  const typeMismatches = [];
+  /** @type {any[]} */
+  const requiredMismatches = [];
+  for (const field of importedEntity.fields || []) {
+    const graphField = graphFields.get(field.name);
+    if (!graphField) {
+      missing.push(field.name);
+      continue;
+    }
+    if (String(graphField.fieldType) !== String(field.field_type)) {
+      typeMismatches.push({
+        field: field.name,
+        imported: field.field_type,
+        topogram: graphField.fieldType
+      });
+    }
+    if (Boolean(graphField.required) !== Boolean(field.required)) {
+      requiredMismatches.push({
+        field: field.name,
+        imported: Boolean(field.required),
+        topogram: Boolean(graphField.required)
+      });
+    }
+  }
+  return { missing, typeMismatches, requiredMismatches };
+}
+
+/** @param {string} value @returns {any} */
+export function normalizeApiCandidateId(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+/** @param {any[]} fields @param {any} jsonSchema @returns {any} */
+export function collectContractFieldNames(fields, jsonSchema) {
+  const names = new Set((fields || []).map((/** @type {any} */ field) => field.name).filter(Boolean));
+  for (const propertyName of Object.keys(jsonSchema?.properties || {})) {
+    names.add(propertyName);
+  }
+  return [...names].sort();
+}
+
+/** @param {ResolvedGraph} graph @returns {any} */
+export function buildTopogramApiCapabilityIndex(graph) {
+  const contracts = generateApiContractGraph(graph);
+  /** @type {any[]} */
+  const records = [];
+  for (const capability of graph.byKind.capability || []) {
+    const contract = contracts[capability.id];
+    if (!contract) {
+      continue;
+    }
+    records.push({
+      id: capability.id,
+      endpoint: {
+        method: contract.endpoint.method,
+        path: normalizeOpenApiPath(contract.endpoint.path)
+      },
+      input_fields: collectContractFieldNames(contract.requestContract?.fields, contract.requestContract?.jsonSchema),
+      output_fields: collectContractFieldNames(contract.responseContract?.fields, contract.responseContract?.jsonSchema),
+      path_params: (contract.requestContract?.transport?.path || []).map((/** @type {any} */ field) => field.name).filter(Boolean).sort(),
+      query_params: (contract.requestContract?.transport?.query || []).map((/** @type {any} */ field) => field.name).filter(Boolean).sort()
+    });
+  }
+  return records;
+}
+
+/** @param {any} importedCapability @param {any[]} topogramCapabilities @returns {any} */
+export function matchImportedApiCapability(importedCapability, topogramCapabilities) {
+  const importedId = normalizeApiCandidateId(importedCapability.id_hint);
+  const importedMethod = String(importedCapability.endpoint?.method || "").toUpperCase();
+  const importedPath = normalizeEndpointPathForMatch(importedCapability.endpoint?.path || "");
+  return topogramCapabilities.find((/** @type {any} */ capability) =>
+    normalizeApiCandidateId(capability.id) === importedId ||
+    (capability.endpoint.method === importedMethod && normalizeEndpointPathForMatch(capability.endpoint.path) === importedPath)
+  ) || null;
+}
+
+/** @param {any} importedCapability @param {any} topogramCapability @returns {any} */
+export function compareApiCapabilityFields(importedCapability, topogramCapability) {
+  const missingInputFields = (importedCapability.input_fields || []).filter((/** @type {any} */ field) => !topogramCapability.input_fields.includes(field));
+  const missingOutputFields = (importedCapability.output_fields || []).filter((/** @type {any} */ field) => !topogramCapability.output_fields.includes(field));
+  const missingPathParams = (importedCapability.path_params || []).map((/** @type {any} */ entry) => entry.name).filter((/** @type {any} */ name) => !topogramCapability.path_params.includes(name));
+  const missingQueryParams = (importedCapability.query_params || []).map((/** @type {any} */ entry) => entry.name).filter((/** @type {any} */ name) => !topogramCapability.query_params.includes(name));
+  return {
+    missing_input_fields_in_topogram: missingInputFields,
+    missing_output_fields_in_topogram: missingOutputFields,
+    missing_path_params_in_topogram: missingPathParams,
+    missing_query_params_in_topogram: missingQueryParams
+  };
+}
+
+/** @param {ResolvedGraph} graph @returns {any} */
+export 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.type)) {
+      continue;
+    }
+    for (const screen of projection.uiScreens || []) {
+      screens.add(screen.id);
+    }
+    for (const route of projection.uiRoutes || []) {
+      routes.add(route.path);
+    }
+  }
+  return {
+    screens: [...screens].sort(),
+    routes: [...routes].sort()
+  };
+}
+
+/** @param {ResolvedGraph} graph @returns {any} */
+export function collectCanonicalWorkflowSurface(graph) {
+  const docs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "workflow");
+  const decisions = (graph.byKind.decision || []).map((/** @type {any} */ decision) => decision.id);
+  return {
+    workflow_docs: docs.map((/** @type {any} */ doc) => doc.id).sort(),
+    decisions: decisions.sort()
+  };
+}
+
+/** @param {ResolvedGraph} graph @returns {any} */
+export function collectCanonicalActorRoleSurface(graph) {
+  const journeyDocs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey");
+  const workflowDocs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "workflow");
+  return {
+    actor_ids: ((graph.byKind.actor || []).map((/** @type {any} */ entry) => entry.id)).sort(),
+    role_ids: ((graph.byKind.role || []).map((/** @type {any} */ entry) => entry.id)).sort(),
+    journey_docs: journeyDocs,
+    workflow_docs: workflowDocs
+  };
+}
+
+/** @param {CandidateBundle} bundle @param {ResolvedGraph} graph @returns {any} */
+export function buildBundleDocLinkSuggestions(bundle, graph) {
+  if (!graph) {
+    return [];
+  }
+  const canonicalDocs = new Map(
+    (graph.docs || [])
+      .filter((/** @type {any} */ doc) => ["journey", "workflow"].includes(doc.kind))
+      .map((/** @type {any} */ doc) => [doc.id, doc])
+  );
+  const suggestions = new Map();
+  const getOrCreateSuggestion = (/** @type {any} */ doc) => {
+    if (!suggestions.has(doc.id)) {
+      suggestions.set(doc.id, {
+        doc_id: doc.id,
+        doc_kind: doc.kind,
+        canonical_rel_path: doc.relativePath,
+        add_related_actors: [],
+        add_related_roles: [],
+        add_related_capabilities: [],
+        add_related_rules: [],
+        add_related_workflows: []
+      });
+    }
+    return suggestions.get(doc.id);
+  };
+  for (const entry of [...(bundle.actors || []), ...(bundle.roles || [])]) {
+    const kind = entry.id_hint.startsWith("actor_") ? "actor" : "role";
+    for (const docId of entry.related_docs || []) {
+      const doc = canonicalDocs.get(docId);
+      if (!doc) {
+        continue;
+      }
+      const target = getOrCreateSuggestion(doc);
+      if (kind === "actor" && !(doc.relatedActors || []).includes(entry.id_hint)) {
+        target.add_related_actors.push(entry.id_hint);
+      }
+      if (kind === "role" && !(doc.relatedRoles || []).includes(entry.id_hint)) {
+        target.add_related_roles.push(entry.id_hint);
+      }
+    }
+  }
+  for (const entry of bundle.docs || []) {
+    const doc = canonicalDocs.get(entry.id);
+    if (!doc) {
+      continue;
+    }
+    const target = getOrCreateSuggestion(doc);
+    for (const capabilityId of entry.related_capabilities || []) {
+      if (!(doc.relatedCapabilities || []).includes(capabilityId)) {
+        target.add_related_capabilities.push(capabilityId);
+      }
+    }
+    for (const ruleId of entry.related_rules || []) {
+      if (!(doc.relatedRules || []).includes(ruleId)) {
+        target.add_related_rules.push(ruleId);
+      }
+    }
+    for (const workflowId of entry.related_workflows || []) {
+      if (!(doc.relatedWorkflows || []).includes(workflowId)) {
+        target.add_related_workflows.push(workflowId);
+      }
+    }
+  }
+  return [...suggestions.values()]
+    .map((/** @type {any} */ entry) => ({
+      ...entry,
+      add_related_actors: [...new Set(entry.add_related_actors)].sort(),
+      add_related_roles: [...new Set(entry.add_related_roles)].sort(),
+      add_related_capabilities: [...new Set(entry.add_related_capabilities)].sort(),
+      add_related_rules: [...new Set(entry.add_related_rules)].sort(),
+      add_related_workflows: [...new Set(entry.add_related_workflows)].sort()
+    }))
+    .filter((/** @type {any} */ entry) =>
+      entry.add_related_actors.length > 0 ||
+      entry.add_related_roles.length > 0 ||
+      entry.add_related_capabilities.length > 0 ||
+      entry.add_related_rules.length > 0 ||
+      entry.add_related_workflows.length > 0
+    )
+    .map((/** @type {any} */ entry) => ({
+      ...entry,
+      patch_rel_path: `doc-link-patches/${entry.doc_id}.md`,
+      recommendation:
+        `Update \`${entry.doc_id}\` to add` +
+        `${entry.add_related_actors.length ? ` related_actors ${entry.add_related_actors.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}` : ""}` +
+        `${entry.add_related_actors.length && (entry.add_related_roles.length || entry.add_related_capabilities.length || entry.add_related_rules.length || entry.add_related_workflows.length) ? " and" : ""}` +
+        `${entry.add_related_roles.length ? ` related_roles ${entry.add_related_roles.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}` : ""}` +
+        `${entry.add_related_roles.length && (entry.add_related_capabilities.length || entry.add_related_rules.length || entry.add_related_workflows.length) ? "," : ""}` +
+        `${entry.add_related_capabilities.length ? ` related_capabilities ${entry.add_related_capabilities.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}` : ""}` +
+        `${entry.add_related_capabilities.length && (entry.add_related_rules.length || entry.add_related_workflows.length) ? "," : ""}` +
+        `${entry.add_related_rules.length ? ` related_rules ${entry.add_related_rules.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}` : ""}` +
+        `${entry.add_related_rules.length && entry.add_related_workflows.length ? "," : ""}` +
+        `${entry.add_related_workflows.length ? ` related_workflows ${entry.add_related_workflows.map((/** @type {any} */ item) => `\`${item}\``).join(", ")}` : ""}.`
+    }))
+    .sort((/** @type {any} */ a, /** @type {any} */ b) =>
+      (b.add_related_actors.length + b.add_related_roles.length) - (a.add_related_actors.length + a.add_related_roles.length) ||
+      a.doc_id.localeCompare(b.doc_id)
+    );
+}
+
+/** @param {any[]} records @returns {any} */
+export function summarizeGapCandidates(records = []) {
+  return records
+    .map((/** @type {any} */ record) => ({
+      id: record.id_hint,
+      confidence: record.confidence || "low",
+      inference: record.inference_summary || null,
+      related_docs: record.related_docs || [],
+      related_capabilities: record.related_capabilities || []
+    }))
+    .sort((/** @type {any} */ a, /** @type {any} */ b) => {
+      const confidenceDelta = confidenceRank(b.confidence) - confidenceRank(a.confidence);
+      if (confidenceDelta !== 0) {
+        return confidenceDelta;
+      }
+      return a.id.localeCompare(b.id);
+    });
+}

package/src/workflows/reconcile/gap-report.js

@@ -0,0 +1,333 @@
+// @ts-check
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import { ensureTrailingNewline } from "../../text-helpers.js";
+import { tryLoadResolvedGraph, scanDocsWorkflow } from "../docs.js";
+import { importAppWorkflow } from "../import-app/index.js";
+import { normalizeWorkspacePaths, readJsonIfExists } from "../shared.js";
+import {
+  buildTopogramApiCapabilityIndex,
+  collectCanonicalActorRoleSurface,
+  collectCanonicalUiSurface,
+  collectCanonicalWorkflowSurface,
+  compareApiCapabilityFields,
+  compareEntityFields,
+  matchImportedApiCapability,
+  summarizeGapCandidates
+} from "./canonical-surface.js";
+
+/** @param {WorkspacePaths} paths @param {string} inputPath @returns {any} */
+export function loadImportArtifacts(paths, inputPath) {
+  const dbCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "db", "candidates.json"));
+  const apiCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "api", "candidates.json"));
+  const uiCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "ui", "candidates.json"));
+  const workflowCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "workflows", "candidates.json"));
+  const verificationCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "verification", "candidates.json"));
+  const docsReport = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "docs", "import-report.json"));
+  if (dbCandidates || apiCandidates || uiCandidates || workflowCandidates || verificationCandidates || docsReport) {
+    return {
+      type: "import_app_report",
+      workspace: paths.workspaceRoot,
+      candidates: {
+        db: dbCandidates || { entities: [], enums: [], relations: [], indexes: [] },
+        api: apiCandidates || { capabilities: [], routes: [], stacks: [] },
+        ui: uiCandidates || { screens: [], routes: [], actions: [], stacks: [] },
+        workflows: workflowCandidates || { workflows: [], workflow_states: [], workflow_transitions: [] },
+        verification: verificationCandidates || { verifications: [], scenarios: [], frameworks: [], scripts: [] },
+        docs: docsReport?.candidate_docs || [],
+        actors: docsReport?.candidate_actors || [],
+        roles: docsReport?.candidate_roles || []
+      }
+    };
+  }
+  const imported = importAppWorkflow(inputPath, { from: "db,api,ui,workflows,verification" }).summary;
+  const docsSummary = scanDocsWorkflow(inputPath).summary;
+  imported.candidates.docs = docsSummary.candidate_docs || [];
+  imported.candidates.actors = docsSummary.candidate_actors || [];
+  imported.candidates.roles = docsSummary.candidate_roles || [];
+  return imported;
+}
+
+/** @param {string} inputPath @returns {any} */
+export function reportGapsWorkflow(inputPath) {
+  const paths = normalizeWorkspacePaths(inputPath);
+  const graph = tryLoadResolvedGraph(paths.topogramRoot);
+  const scan = graph ? scanDocsWorkflow(paths.topogramRoot).summary : { candidate_docs: [] };
+  const appImport = loadImportArtifacts(paths, inputPath);
+
+  const importedDb = appImport.candidates.db || { entities: [], enums: [], relations: [], indexes: [] };
+  const importedApi = appImport.candidates.api || { capabilities: [], routes: [], stacks: [] };
+  const importedUi = appImport.candidates.ui || { screens: [], routes: [], actions: [], stacks: [] };
+  const importedWorkflows = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
+  const importedActors = appImport.candidates.actors || [];
+  const importedRoles = appImport.candidates.roles || [];
+
+  if (!graph) {
+    /** @type {WorkflowRecord} */
+    const report = {
+      type: "gap_report",
+      workspace: paths.workspaceRoot,
+      bootstrapped_topogram_root: paths.bootstrappedTopogramRoot,
+      topogram_available: false,
+      imported: {
+        db: {
+          entity_count: importedDb.entities.length,
+          enum_count: importedDb.enums.length,
+          relation_count: importedDb.relations.length
+        },
+        api: {
+          capability_count: importedApi.capabilities.length,
+          route_count: importedApi.routes.length
+        },
+        ui: {
+          screen_count: importedUi.screens.length,
+          route_count: importedUi.routes.length
+        },
+        workflows: {
+          workflow_count: importedWorkflows.workflows.length,
+          transition_count: importedWorkflows.workflow_transitions.length
+        },
+        actors_roles: {
+          actor_count: importedActors.length,
+          role_count: importedRoles.length
+        }
+      }
+    };
+    /** @type {WorkflowFiles} */
+    const files = {
+      "candidates/reports/gap-report.json": `${stableStringify(report)}\n`,
+      "candidates/reports/gap-report.md": ensureTrailingNewline(
+        `# Gap Report\n\nNo canonical Topogram was found.\n\n- Imported DB entities: ${importedDb.entities.length}\n- Imported DB enums: ${importedDb.enums.length}\n- Imported API capabilities: ${importedApi.capabilities.length}\n- Imported API routes: ${importedApi.routes.length}\n- Imported UI screens: ${importedUi.screens.length}\n- Imported workflows: ${importedWorkflows.workflows.length}\n- Imported actors: ${importedActors.length}\n- Imported roles: ${importedRoles.length}\n`
+      )
+    };
+    return {
+      summary: report,
+      files,
+      defaultOutDir: paths.topogramRoot
+    };
+  }
+
+  const glossaryDocs = new Set((graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "glossary").map((/** @type {any} */ doc) => doc.id));
+  const workflowDocs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "workflow");
+  const canonicalUi = collectCanonicalUiSurface(graph);
+  const canonicalWorkflow = collectCanonicalWorkflowSurface(graph);
+  const canonicalActorRole = collectCanonicalActorRoleSurface(graph);
+  const entityMap = new Map((graph.byKind.entity || []).map((/** @type {any} */ entity) => [entity.id.replace(/^entity_/, ""), entity]));
+  const enumMap = new Map((graph.byKind.enum || []).map((/** @type {any} */ entry) => [entry.id, entry]));
+  const topogramApiCapabilities = buildTopogramApiCapabilityIndex(graph);
+  const capabilityIds = new Set(topogramApiCapabilities.map((/** @type {any} */ capability) => capability.id));
+  const canonicalActorIds = new Set(canonicalActorRole.actor_ids);
+  const canonicalRoleIds = new Set(canonicalActorRole.role_ids);
+  const capabilityById = new Map((graph.byKind.capability || []).map((/** @type {any} */ entry) => [entry.id, entry]));
+
+  const missingGlossary = [...entityMap.keys()].filter((/** @type {any} */ id) => !glossaryDocs.has(id));
+  const missingWorkflowDocs = (graph.byKind.capability || [])
+    .filter((/** @type {any} */ capability) => [...capability.creates, ...capability.updates, ...capability.deletes].length > 0)
+    .filter((/** @type {any} */ capability) => !workflowDocs.some((/** @type {any} */ doc) => doc.relatedCapabilities.includes(capability.id)))
+    .map((/** @type {any} */ capability) => capability.id);
+
+  /** @type {any[]} */
+
+  const dbEntitiesMissing = [];
+  /** @type {any[]} */
+  const dbFieldMismatches = [];
+  for (const candidate of importedDb.entities || []) {
+    const canonicalId = candidate.id_hint.replace(/^entity_/, "");
+    const graphEntity = entityMap.get(canonicalId);
+    if (!graphEntity) {
+      dbEntitiesMissing.push(canonicalId);
+      continue;
+    }
+    const mismatch = compareEntityFields(candidate, graphEntity);
+    if (mismatch.missing.length || mismatch.typeMismatches.length || mismatch.requiredMismatches.length) {
+      dbFieldMismatches.push({
+        entity: canonicalId,
+        missing_fields_in_topogram: mismatch.missing,
+        type_mismatches: mismatch.typeMismatches,
+        required_mismatches: mismatch.requiredMismatches
+      });
+    }
+  }
+
+  /** @type {any[]} */
+
+  const dbEnumsMissing = [];
+  /** @type {any[]} */
+  const dbEnumValueMismatches = [];
+  for (const candidate of importedDb.enums || []) {
+    const graphEnum = enumMap.get(candidate.id_hint);
+    if (!graphEnum) {
+      dbEnumsMissing.push(candidate.id_hint);
+      continue;
+    }
+    const graphValues = new Set((graphEnum.values || []).map((/** @type {any} */ value) => value.id || value));
+    const missingValues = (candidate.values || []).filter((/** @type {any} */ value) => !graphValues.has(value));
+    if (missingValues.length > 0) {
+      dbEnumValueMismatches.push({
+        enum: candidate.id_hint,
+        missing_values_in_topogram: missingValues
+      });
+    }
+  }
+
+  /** @type {any[]} */
+
+  const importedCapabilitiesMissing = [];
+  /** @type {any[]} */
+  const importedEndpointsWithoutMatchingCapabilities = [];
+  /** @type {any[]} */
+  const apiFieldMismatches = [];
+  const matchedTopogramCapabilities = new Set();
+  for (const entry of importedApi.capabilities || []) {
+    const match = matchImportedApiCapability(entry, topogramApiCapabilities);
+    if (!match) {
+      importedCapabilitiesMissing.push(entry.id_hint);
+      importedEndpointsWithoutMatchingCapabilities.push({
+        capability: entry.id_hint,
+        method: entry.endpoint?.method || null,
+        path: entry.endpoint?.path || null
+      });
+      continue;
+    }
+    matchedTopogramCapabilities.add(match.id);
+    const fieldMismatch = compareApiCapabilityFields(entry, match);
+    if (
+      fieldMismatch.missing_input_fields_in_topogram.length > 0 ||
+      fieldMismatch.missing_output_fields_in_topogram.length > 0 ||
+      fieldMismatch.missing_path_params_in_topogram.length > 0 ||
+      fieldMismatch.missing_query_params_in_topogram.length > 0
+    ) {
+      apiFieldMismatches.push({
+        capability: match.id,
+        imported_capability: entry.id_hint,
+        method: entry.endpoint?.method || null,
+        path: entry.endpoint?.path || null,
+        ...fieldMismatch
+      });
+    }
+  }
+  const topogramCapabilitiesWithoutImportedEndpointEvidence = topogramApiCapabilities
+    .filter((/** @type {any} */ capability) => !matchedTopogramCapabilities.has(capability.id))
+    .map((/** @type {any} */ capability) => capability.id);
+
+  const scannedTermsMissingInGlossary = (scan.candidate_docs || [])
+    .filter((/** @type {any} */ doc) => doc.kind === "glossary")
+    .map((/** @type {any} */ doc) => doc.id)
+    .filter((/** @type {any} */ id) => entityMap.has(id) && !glossaryDocs.has(id));
+
+  const importedScreensMissing = (importedUi.screens || [])
+    .map((/** @type {any} */ screen) => screen.id_hint)
+    .filter((/** @type {any} */ id) => !canonicalUi.screens.includes(id));
+  const importedUiRoutesMissing = (importedUi.routes || [])
+    .map((/** @type {any} */ route) => route.path)
+    .filter((/** @type {any} */ route) => !canonicalUi.routes.includes(route));
+
+  const importedWorkflowsMissing = (importedWorkflows.workflows || [])
+    .map((/** @type {any} */ workflow) => workflow.id_hint)
+    .filter((/** @type {any} */ id) => !canonicalWorkflow.workflow_docs.includes(id));
+  const importedWorkflowTransitionsMissing = (importedWorkflows.workflow_transitions || []).map((/** @type {any} */ transition) => ({
+    workflow: transition.workflow_id,
+    capability: transition.capability_id,
+    to_state: transition.to_state
+  }));
+
+  const actorGapCandidates = summarizeGapCandidates(importedActors.filter((/** @type {any} */ entry) => !canonicalActorIds.has(entry.id_hint)));
+  const roleGapCandidates = summarizeGapCandidates(importedRoles.filter((/** @type {any} */ entry) => !canonicalRoleIds.has(entry.id_hint)));
+  const importedActorsMissing = importedActors
+    .map((/** @type {any} */ entry) => entry.id_hint)
+    .filter((/** @type {any} */ id) => !canonicalActorIds.has(id));
+  const importedRolesMissing = importedRoles
+    .map((/** @type {any} */ entry) => entry.id_hint)
+    .filter((/** @type {any} */ id) => !canonicalRoleIds.has(id));
+  /** @type {any[]} */
+  const securedCapabilitiesWithoutCanonicalRoles = [];
+  for (const entry of importedApi.capabilities || []) {
+    if (entry.auth_hint !== "secured") {
+      continue;
+    }
+    const match = matchImportedApiCapability(entry, topogramApiCapabilities);
+    if (!match) {
+      continue;
+    }
+    const canonicalCapability = capabilityById.get(match.id);
+    if (!canonicalCapability || (canonicalCapability.roles || []).length > 0) {
+      continue;
+    }
+    securedCapabilitiesWithoutCanonicalRoles.push(match.id);
+  }
+  const journeyDocsMissingActorLinks = canonicalActorRole.journey_docs
+    .filter((/** @type {any} */ doc) => (doc.relatedActors || []).length === 0)
+    .filter((/** @type {any} */ doc) => importedActors.some((/** @type {any} */ entry) => (entry.related_docs || []).includes(doc.id)))
+    .map((/** @type {any} */ doc) => doc.id);
+  const journeyDocsMissingRoleLinks = canonicalActorRole.journey_docs
+    .filter((/** @type {any} */ doc) => (doc.relatedRoles || []).length === 0)
+    .filter((/** @type {any} */ doc) => importedRoles.some((/** @type {any} */ entry) => (entry.related_docs || []).includes(doc.id)))
+    .map((/** @type {any} */ doc) => doc.id);
+  const workflowDocsMissingActorLinks = canonicalActorRole.workflow_docs
+    .filter((/** @type {any} */ doc) => (doc.relatedActors || []).length === 0)
+    .filter((/** @type {any} */ doc) => importedActors.some((/** @type {any} */ entry) => (entry.related_docs || []).includes(doc.id)))
+    .map((/** @type {any} */ doc) => doc.id);
+  const workflowDocsMissingRoleLinks = canonicalActorRole.workflow_docs
+    .filter((/** @type {any} */ doc) => (doc.relatedRoles || []).length === 0)
+    .filter((/** @type {any} */ doc) => importedRoles.some((/** @type {any} */ entry) => (entry.related_docs || []).includes(doc.id)))
+    .map((/** @type {any} */ doc) => doc.id);
+
+  const report = {
+    type: "gap_report",
+    workspace: paths.workspaceRoot,
+    bootstrapped_topogram_root: paths.bootstrappedTopogramRoot,
+    topogram_available: true,
+    docs_vs_topogram: {
+      missing_glossary_docs: missingGlossary,
+      missing_workflow_docs: missingWorkflowDocs,
+      scanned_terms_missing_in_glossary: scannedTermsMissingInGlossary
+    },
+    db_vs_topogram: {
+      entities_missing_in_topogram: dbEntitiesMissing,
+      field_mismatches: dbFieldMismatches,
+      enums_missing_in_topogram: dbEnumsMissing,
+      enum_value_mismatches: dbEnumValueMismatches
+    },
+    api_vs_topogram: {
+      capabilities_missing_in_topogram: importedCapabilitiesMissing,
+      endpoints_without_matching_capabilities: importedEndpointsWithoutMatchingCapabilities,
+      field_mismatches: apiFieldMismatches,
+      topogram_capabilities_without_imported_endpoint_evidence: topogramCapabilitiesWithoutImportedEndpointEvidence
+    },
+    ui_vs_topogram: {
+      screens_missing_in_topogram: importedScreensMissing,
+      routes_missing_in_topogram: importedUiRoutesMissing
+    },
+    workflows_vs_topogram: {
+      workflows_missing_in_topogram: importedWorkflowsMissing,
+      transitions_without_canonical_workflow_representation: importedWorkflowTransitionsMissing
+    },
+    actors_roles_vs_topogram: {
+      actors_missing_in_topogram: importedActorsMissing,
+      actor_gap_candidates: actorGapCandidates,
+      roles_missing_in_topogram: importedRolesMissing,
+      role_gap_candidates: roleGapCandidates,
+      secured_capabilities_without_canonical_roles: [...new Set(securedCapabilitiesWithoutCanonicalRoles)].sort(),
+      journey_docs_missing_actor_links: journeyDocsMissingActorLinks,
+      journey_docs_missing_role_links: journeyDocsMissingRoleLinks,
+      workflow_docs_missing_actor_links: workflowDocsMissingActorLinks,
+      workflow_docs_missing_role_links: workflowDocsMissingRoleLinks
+    }
+  };
+
+  /** @type {WorkflowFiles} */
+
+  const files = {
+    "candidates/reports/gap-report.json": `${stableStringify(report)}\n`,
+    "candidates/reports/gap-report.md": ensureTrailingNewline(
+      `# Gap Report\n\n## Docs vs Topogram\n\n- Missing glossary docs: ${missingGlossary.length}\n- Missing workflow docs: ${missingWorkflowDocs.length}\n- Scanned terms not in glossary: ${scannedTermsMissingInGlossary.length}\n\n## DB vs Topogram\n\n- Imported entities missing in Topogram: ${dbEntitiesMissing.length}\n- Imported field mismatches: ${dbFieldMismatches.length}\n- Imported enums missing in Topogram: ${dbEnumsMissing.length}\n- Imported enum value mismatches: ${dbEnumValueMismatches.length}\n\n## API vs Topogram\n\n- Imported capabilities missing in Topogram: ${importedCapabilitiesMissing.length}\n- Imported endpoints without matching capabilities: ${importedEndpointsWithoutMatchingCapabilities.length}\n- Topogram capabilities without imported endpoint evidence: ${topogramCapabilitiesWithoutImportedEndpointEvidence.length}\n\n## UI vs Topogram\n\n- Imported screens missing in Topogram: ${importedScreensMissing.length}\n- Imported routes missing in Topogram: ${importedUiRoutesMissing.length}\n\n## Workflows vs Topogram\n\n- Imported workflows missing in Topogram: ${importedWorkflowsMissing.length}\n- Imported transitions without canonical workflow representation: ${importedWorkflowTransitionsMissing.length}\n\n## Actors/Roles vs Topogram\n\n- Imported actors missing in Topogram: ${importedActorsMissing.length}\n- Imported roles missing in Topogram: ${importedRolesMissing.length}\n- Secured capabilities without canonical roles: ${securedCapabilitiesWithoutCanonicalRoles.length}\n- Journey docs missing actor links: ${journeyDocsMissingActorLinks.length}\n- Journey docs missing role links: ${journeyDocsMissingRoleLinks.length}\n- Workflow docs missing actor links: ${workflowDocsMissingActorLinks.length}\n- Workflow docs missing role links: ${workflowDocsMissingRoleLinks.length}\n\n### Ranked Missing Actors\n\n${actorGapCandidates.length ? actorGapCandidates.map((/** @type {any} */ entry) => `- \`${entry.id}\` (${entry.confidence})${entry.inference ? ` ${entry.inference}` : ""}`).join("\n") : "- None"}\n\n### Ranked Missing Roles\n\n${roleGapCandidates.length ? roleGapCandidates.map((/** @type {any} */ entry) => `- \`${entry.id}\` (${entry.confidence})${entry.inference ? ` ${entry.inference}` : ""}`).join("\n") : "- None"}\n`
+    )
+  };
+
+  return {
+    summary: report,
+    files,
+    defaultOutDir: paths.topogramRoot
+  };
+}

package/src/workflows/reconcile/ids.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+/** @param {string} id @returns {any} */
+export function dashedTopogramId(id) {
+  return String(id || "").replaceAll("_", "-");
+}