@topogram/cli 0.3.34

package/src/proofs/contract-audit.js

@@ -0,0 +1,220 @@
+import { stableStringify } from "../format.js";
+
+function normalizeVisibility(visibility = []) {
+  return [...visibility]
+    .map((entry) => ({
+      capabilityId: entry.capabilityId ?? null,
+      predicate: entry.predicate ?? null,
+      value: entry.value ?? null,
+      ownershipField: entry.ownershipField ?? null,
+      claimValue: entry.claimValue ?? null
+    }))
+    .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+}
+
+function normalizeScreen(screen) {
+  return {
+    id: screen.id ?? null,
+    route: screen.route ?? null,
+    kind: screen.kind ?? null,
+    title: screen.title ?? null,
+    loadCapabilityId: screen.loadCapability?.id ?? screen.loadCapabilityId ?? null,
+    viewShapeId: screen.viewShape?.id ?? screen.viewShapeId ?? null,
+    primaryActionId: screen.actions?.primary?.id ?? null,
+    secondaryActionId: screen.actions?.secondary?.id ?? null,
+    destructiveActionId: screen.actions?.destructive?.id ?? null,
+    screenActionIds: (screen.actions?.screen ?? []).map((action) => action.id ?? null).filter(Boolean).sort(),
+    visibility: normalizeVisibility(screen.visibility)
+  };
+}
+
+function normalizeNavigationItem(item) {
+  return {
+    screenId: item.screenId ?? null,
+    route: item.route ?? null,
+    label: item.label ?? null,
+    placement: item.placement ?? null,
+    visible: item.visible ?? null,
+    breadcrumb: item.breadcrumb ?? null,
+    pattern: item.pattern ?? null
+  };
+}
+
+function normalizeUiContract(contract) {
+  return {
+    appShell: contract.appShell ?? {},
+    navigation: {
+      defaultScreenId: contract.navigation?.defaultScreenId ?? null,
+      items: (contract.navigation?.items ?? []).map(normalizeNavigationItem).sort((a, b) => stableStringify(a).localeCompare(stableStringify(b))),
+      patterns: [...(contract.navigation?.patterns ?? [])].sort()
+    },
+    screens: (contract.screens ?? []).map(normalizeScreen).sort((a, b) => a.id.localeCompare(b.id))
+  };
+}
+
+function extractServerContractObject(moduleSource) {
+  const match = moduleSource.match(/export const serverContract = (\{[\s\S]*\}) as const;\s*$/);
+  if (!match) {
+    throw new Error("Could not parse emitted server-contract module");
+  }
+  return JSON.parse(match[1]);
+}
+
+function normalizeServerAuthz(authz = []) {
+  return [...authz]
+    .map((entry) => ({
+      role: entry.role ?? null,
+      permission: entry.permission ?? null,
+      claim: entry.claim ?? null,
+      claimValue: entry.claimValue ?? null,
+      ownership: entry.ownership ?? null,
+      ownershipField: entry.ownershipField ?? null
+    }))
+    .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+}
+
+function normalizeRoute(route) {
+  return {
+    capabilityId: route.capabilityId ?? null,
+    method: route.method ?? null,
+    path: route.path ?? null,
+    successStatus: route.successStatus ?? null,
+    requestFields: (route.requestContract?.fields ?? [])
+      .map((field) => ({
+        name: field.name ?? null,
+        required: field.required ?? null,
+        location: field.transport?.location ?? null,
+        wireName: field.transport?.wireName ?? null
+      }))
+      .sort((a, b) => stableStringify(a).localeCompare(stableStringify(b))),
+    errorCases: (route.errorCases ?? [])
+      .map((entry) => ({
+        code: entry.code ?? null,
+        status: entry.status ?? null,
+        source: entry.source ?? null
+      }))
+      .sort((a, b) => stableStringify(a).localeCompare(stableStringify(b))),
+    endpoint: {
+      auth: route.endpoint?.auth ?? null,
+      authz: normalizeServerAuthz(route.endpoint?.authz),
+      preconditions: (route.endpoint?.preconditions ?? []).map((entry) => ({
+        header: entry.header ?? null,
+        required: entry.required ?? null,
+        error: entry.error ?? null,
+        code: entry.code ?? null
+      })),
+      idempotency: (route.endpoint?.idempotency ?? []).map((entry) => ({
+        header: entry.header ?? null,
+        required: entry.required ?? null,
+        error: entry.error ?? null,
+        code: entry.code ?? null
+      }))
+    }
+  };
+}
+
+function normalizeServerContract(contract) {
+  return {
+    projection: {
+      id: contract.projection?.id ?? null,
+      platform: contract.projection?.platform ?? null
+    },
+    routes: (contract.routes ?? []).map(normalizeRoute).sort((a, b) => {
+      const leftKey = `${a.method}:${a.path}:${a.capabilityId}`;
+      const rightKey = `${b.method}:${b.path}:${b.capabilityId}`;
+      return leftKey.localeCompare(rightKey);
+    })
+  };
+}
+
+function buildScreenDiffs(leftScreens, rightScreens) {
+  const rightById = new Map(rightScreens.map((screen) => [screen.id, screen]));
+  const leftById = new Map(leftScreens.map((screen) => [screen.id, screen]));
+  const diffs = [];
+
+  for (const screen of leftScreens) {
+    const other = rightById.get(screen.id);
+    if (!other) {
+      diffs.push({ type: "missing_on_right", screenId: screen.id });
+      continue;
+    }
+    if (stableStringify(screen) !== stableStringify(other)) {
+      diffs.push({ type: "screen_mismatch", screenId: screen.id });
+    }
+  }
+
+  for (const screen of rightScreens) {
+    if (!leftById.has(screen.id)) {
+      diffs.push({ type: "missing_on_left", screenId: screen.id });
+    }
+  }
+
+  return diffs;
+}
+
+function buildRouteDiffs(leftRoutes, rightRoutes) {
+  const rightByKey = new Map(rightRoutes.map((route) => [`${route.method}:${route.path}:${route.capabilityId}`, route]));
+  const leftByKey = new Map(leftRoutes.map((route) => [`${route.method}:${route.path}:${route.capabilityId}`, route]));
+  const diffs = [];
+
+  for (const route of leftRoutes) {
+    const key = `${route.method}:${route.path}:${route.capabilityId}`;
+    const other = rightByKey.get(key);
+    if (!other) {
+      diffs.push({ type: "missing_on_right", route: key });
+      continue;
+    }
+    if (stableStringify(route) !== stableStringify(other)) {
+      diffs.push({ type: "route_mismatch", route: key });
+    }
+  }
+
+  for (const route of rightRoutes) {
+    const key = `${route.method}:${route.path}:${route.capabilityId}`;
+    if (!leftByKey.has(key)) {
+      diffs.push({ type: "missing_on_left", route: key });
+    }
+  }
+
+  return diffs;
+}
+
+export function auditUiContractPair(leftContract, rightContract) {
+  const left = normalizeUiContract(leftContract);
+  const right = normalizeUiContract(rightContract);
+  const screenDiffs = buildScreenDiffs(left.screens, right.screens);
+  const navigationParity = stableStringify(left.navigation) === stableStringify(right.navigation);
+  const appShellParity = stableStringify(left.appShell) === stableStringify(right.appShell);
+
+  return {
+    seam: "ui_web_contract",
+    semanticParity: screenDiffs.length === 0 && navigationParity && appShellParity,
+    summary: {
+      screenCount: left.screens.length,
+      navigationItemCount: left.navigation.items.length
+    },
+    differences: {
+      appShell: appShellParity ? [] : ["app_shell_mismatch"],
+      navigation: navigationParity ? [] : ["navigation_mismatch"],
+      screens: screenDiffs
+    }
+  };
+}
+
+export function auditServerContractModules(leftModuleSource, rightModuleSource) {
+  const left = normalizeServerContract(extractServerContractObject(leftModuleSource));
+  const right = normalizeServerContract(extractServerContractObject(rightModuleSource));
+  const routeDiffs = buildRouteDiffs(left.routes, right.routes);
+
+  return {
+    seam: "server_contract",
+    semanticParity: routeDiffs.length === 0,
+    summary: {
+      routeCount: left.routes.length,
+      capabilityIds: left.routes.map((route) => route.capabilityId)
+    },
+    differences: {
+      routes: routeDiffs
+    }
+  };
+}

package/src/proofs/ios-parity.js

@@ -0,0 +1,7 @@
+import { stableStringify } from "../format.js";
+import { normalizeScreens } from "./web-parity.js";
+
+/** Semantic fingerprint of screens slice embedded in Swift ui-web-contract JSON (matches web normalization). */
+export function fingerprintIosEmbeddedUiContract(contract) {
+  return stableStringify(normalizeScreens(contract));
+}

package/src/proofs/issues-parity.js

@@ -0,0 +1,10 @@
+import { buildBackendParityEvidence } from "./backend-parity.js";
+import { buildWebParityEvidence } from "./web-parity.js";
+
+export function buildIssuesParityEvidence(graph) {
+  const web = buildWebParityEvidence(graph, "proj_ui_web__react", "proj_ui_web__sveltekit");
+  return {
+    web,
+    runtime: buildBackendParityEvidence(graph, "proj_api")
+  };
+}

package/src/proofs/web-parity.js

@@ -0,0 +1,50 @@
+import { stableStringify } from "../format.js";
+import { buildWebRealization } from "../realization/ui/index.js";
+
+function normalizeVisibility(visibility = []) {
+  return visibility
+    .map((entry) => ({
+      capabilityId: entry.capabilityId ?? entry.capability?.id ?? null,
+      predicate: entry.predicate ?? null,
+      value: entry.value ?? null,
+      ownershipField: entry.ownershipField ?? null,
+      claimValue: entry.claimValue ?? null
+    }))
+    .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+}
+
+function normalizeScreen(screen) {
+  return {
+    id: screen.id,
+    route: screen.route ?? null,
+    kind: screen.kind ?? null,
+    title: screen.title ?? null,
+    loadCapabilityId: screen.loadCapability?.id ?? null,
+    viewShapeId: screen.viewShape?.id ?? null,
+    primaryActionId: screen.actions?.primary?.id ?? null,
+    secondaryActionId: screen.actions?.secondary?.id ?? null,
+    screenActionIds: (screen.actions?.screen ?? []).map((action) => action.id ?? action.capability?.id).sort(),
+    visibility: normalizeVisibility(screen.visibility)
+  };
+}
+
+export function normalizeScreens(contract) {
+  return contract.screens.map(normalizeScreen).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function buildWebParityEvidence(graph, leftProjectionId, rightProjectionId) {
+  const left = buildWebRealization(graph, { projectionId: leftProjectionId });
+  const right = buildWebRealization(graph, { projectionId: rightProjectionId });
+  const leftScreens = normalizeScreens(left.contract);
+  const rightScreens = normalizeScreens(right.contract);
+
+  return {
+    leftProjectionId,
+    rightProjectionId,
+    leftProfile: left.contract.generatorDefaults.profile,
+    rightProfile: right.contract.generatorDefaults.profile,
+    leftScreens,
+    rightScreens,
+    semanticParity: stableStringify(leftScreens) === stableStringify(rightScreens)
+  };
+}

package/src/realization/api/build-api-realization.js

@@ -0,0 +1,5 @@
+import { generateApiContractGraph } from "../../generator/api.js";
+
+export function buildApiRealization(graph, options = {}) {
+  return generateApiContractGraph(graph, options);
+}

package/src/realization/api/index.js

@@ -0,0 +1 @@
+export { buildApiRealization } from "./build-api-realization.js";

package/src/realization/backend/build-backend-runtime-realization.js

@@ -0,0 +1,82 @@
+import { buildDbRealization } from "../db/index.js";
+import { generateServerContract } from "../../generator/surfaces/services/server-contract.js";
+import { dbProjectionCandidates } from "../../generator/surfaces/databases/shared.js";
+import { getExampleImplementation } from "../../example-implementation.js";
+
+function uiLookupBindings(graph) {
+  const bindings = [];
+  for (const projection of graph.byKind.projection || []) {
+    for (const entry of projection.uiLookups || []) {
+      if (entry.entity?.id) {
+        bindings.push(entry);
+      }
+    }
+  }
+  return bindings;
+}
+
+export function getDefaultBackendDbProjection(graph, options = {}) {
+  const candidates = dbProjectionCandidates(graph);
+  const implementation = getExampleImplementation(graph, options);
+  const preferredProjectionId = implementation.runtime?.reference?.localDbProjectionId || null;
+  const explicit = options.dbProjectionId
+    ? candidates.find((projection) => projection.id === options.dbProjectionId)
+    : null;
+  const preferred = preferredProjectionId
+    ? candidates.find((projection) => projection.id === preferredProjectionId)
+    : null;
+  return (
+    explicit ||
+    preferred ||
+    candidates.find((projection) => projection.platform === "db_postgres") ||
+    candidates.find((projection) => projection.platform === "db_sqlite") ||
+    candidates[0] ||
+    null
+  );
+}
+
+export function buildBackendRuntimeRealization(graph, options = {}) {
+  if (!options.projectionId) {
+    throw new Error("Backend runtime realization requires --projection <id>");
+  }
+
+  const dbProjection = getDefaultBackendDbProjection(graph, options);
+  if (!dbProjection) {
+    throw new Error("Backend runtime realization requires at least one DB projection");
+  }
+
+  const implementation = getExampleImplementation(graph, options);
+  const repositoryReference = implementation.backend.repositoryReference;
+  const backendReference = implementation.backend.reference;
+  const runtimeReference = implementation.runtime?.reference || null;
+  const contract = generateServerContract(graph, { projectionId: options.projectionId });
+  const db = buildDbRealization(graph, { projectionId: dbProjection.id });
+  const lookupRoutes = Array.from(
+    new Map(
+      uiLookupBindings(graph).map((entry) => [
+        entry.entity.id,
+        repositoryReference.lookupBindings.find((binding) => binding.entityId === entry.entity.id)
+      ])
+    ).values()
+  ).filter((entry) => entry.repositoryMethod);
+
+  return {
+    type: "backend_runtime_realization",
+    app: {
+      id: options.projectionId,
+      family: "backend",
+      target: "hono",
+      name: contract.projection.name
+    },
+    contract,
+    db,
+    lookupRoutes,
+    backendReference,
+    runtimeReference,
+    repositoryReference,
+    dbProjection: {
+      id: dbProjection.id,
+      platform: dbProjection.platform
+    }
+  };
+}

package/src/realization/backend/index.d.ts

@@ -0,0 +1 @@
+export function getDefaultBackendDbProjection(graph: any, options?: any): any;

package/src/realization/backend/index.js

@@ -0,0 +1,4 @@
+export {
+  buildBackendRuntimeRealization,
+  getDefaultBackendDbProjection
+} from "./build-backend-runtime-realization.js";

package/src/realization/db/build-db-realization.js

@@ -0,0 +1,17 @@
+import {
+  buildDbProjectionContract,
+  dbProjectionCandidates,
+  getProjection
+} from "../../generator/surfaces/databases/shared.js";
+
+export function buildDbRealization(graph, options = {}) {
+  if (options.projectionId) {
+    return buildDbProjectionContract(graph, getProjection(graph, options.projectionId));
+  }
+
+  const output = {};
+  for (const projection of dbProjectionCandidates(graph)) {
+    output[projection.id] = buildDbProjectionContract(graph, projection);
+  }
+  return output;
+}

package/src/realization/db/index.js

@@ -0,0 +1,3 @@
+export { buildDbRealization } from "./build-db-realization.js";
+export { buildDbSnapshotRealization } from "./snapshot.js";
+export { buildDbMigrationPlanRealization } from "./migration-plan.js";

package/src/realization/db/migration-plan.js

@@ -0,0 +1,5 @@
+import { generateDbMigrationPlan } from "../../generator/surfaces/databases/migration-plan.js";
+
+export function buildDbMigrationPlanRealization(graph, options = {}) {
+  return generateDbMigrationPlan(graph, options);
+}

package/src/realization/db/snapshot.js

@@ -0,0 +1,5 @@
+import { generateDbSchemaSnapshot } from "../../generator/surfaces/databases/snapshot.js";
+
+export function buildDbSnapshotRealization(graph, options = {}) {
+  return generateDbSchemaSnapshot(graph, options);
+}