@topogram/cli 0.3.64 → 0.3.65

package/src/generator/widget-conformance/projection-context.js

@@ -0,0 +1,200 @@
+// @ts-check
+
+import { sharedUiProjectionForWeb } from "../surfaces/shared.js";
+
+/**
+ * @param {any} entries
+ * @returns {any}
+ */
+export function byId(entries = []) {
+  return new Map(entries.map(/** @param {any} entry */ (entry) => [entry.id, entry]));
+}
+
+/**
+ * @param {any} values
+ * @returns {any}
+ */
+export function stableUnique(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+/**
+ * @param {any} entry
+ * @returns {any}
+ */
+export function sourcePath(entry) {
+  return entry?.loc?.file || null;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetStatement} widget
+ * @returns {any}
+ */
+export function widgetContract(widget) {
+  return widget?.widgetContract || null;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function summarizeProjection(projection) {
+  return projection
+    ? {
+        id: projection.id,
+        name: projection.name || projection.id,
+        type: projection.type || projection.type || null,
+        status: projection.status || null,
+        source_path: sourcePath(projection)
+      }
+    : null;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetStatement} widget
+ * @returns {any}
+ */
+export function summarizeWidget(widget) {
+  return widget
+    ? {
+        id: widget.id,
+        name: widget.name || widget.id,
+        category: widget.category || null,
+        version: widget.version || null,
+        status: widget.status || null,
+        source_path: sourcePath(widget)
+      }
+    : null;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetStatement} widget
+ * @returns {any}
+ */
+export function summarizeWidgetContract(widget) {
+  const contract = widgetContract(widget);
+  if (!contract) return null;
+  return {
+    id: contract.id,
+    name: contract.name,
+    category: contract.category || null,
+    version: contract.version || null,
+    status: contract.status || null,
+    props: contract.props || [],
+    events: contract.events || [],
+    behaviors: contract.behaviors || [],
+    behavior: contract.behavior || [],
+    approvals: contract.approvals || [],
+    dependencies: contract.dependencies || [],
+    source_path: sourcePath(widget)
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function projectionRealizesIds(projection) {
+  return new Set((projection?.realizes || []).map(/** @param {any} ref */ (ref) => ref.id).filter(Boolean));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function ownProjectionScreenMap(projection) {
+  return new Map((projection?.uiScreens || []).map(/** @param {any} screen */ (screen) => [screen.id, screen]));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function ownProjectionRegionKeys(projection) {
+  return new Set((projection?.uiScreenRegions || []).map(/** @param {any} entry */ (entry) => `${entry.screenId}:${entry.region}`));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @returns {any}
+ */
+export function projectionById(graph) {
+  return byId(graph.byKind.projection || []);
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function projectionContext(graph, projection) {
+  const projections = /** @type {any[]} */ ([]);
+  const seen = new Set();
+  const projectionsById = projectionById(graph);
+
+  /**
+   * @param {any} current
+   * @returns {void}
+   */
+  function visit(current) {
+    if (!current || seen.has(current.id)) {
+      return;
+    }
+    seen.add(current.id);
+    projections.push(current);
+    for (const ref of current.realizes || []) {
+      const target = projectionsById.get(ref.id);
+      if (target) {
+        visit(target);
+      }
+    }
+  }
+
+  visit(projection);
+  return projections;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function projectionScreenMap(graph, projection) {
+  const screens = new Map();
+  for (const contextProjection of projectionContext(graph, projection).reverse()) {
+    for (const [id, screen] of ownProjectionScreenMap(contextProjection)) {
+      screens.set(id, screen);
+    }
+  }
+  return screens;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function projectionRegionKeys(graph, projection) {
+  const regions = new Set();
+  for (const contextProjection of projectionContext(graph, projection)) {
+    for (const key of ownProjectionRegionKeys(contextProjection)) {
+      regions.add(key);
+    }
+  }
+  return regions;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {any}
+ */
+export function projectionContextRealizesIds(graph, projection) {
+  const ids = new Set();
+  for (const contextProjection of projectionContext(graph, projection)) {
+    for (const id of projectionRealizesIds(contextProjection)) {
+      ids.add(id);
+    }
+  }
+  return ids;
+}

package/src/generator/widget-conformance/report.js

@@ -0,0 +1,166 @@
+// @ts-check
+
+import { getProjection, sharedUiProjectionForWeb, uiProjectionCandidates } from "../surfaces/shared.js";
+import { buildWidgetBehaviorRealizations } from "../../widget-behavior.js";
+import { collectUsageChecks, widgetUsageKey } from "./checks.js";
+import {
+  byId,
+  projectionScreenMap,
+  sourcePath,
+  stableUnique,
+  summarizeProjection,
+  summarizeWidget,
+  summarizeWidgetContract,
+  widgetContract
+} from "./projection-context.js";
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetProjection} projection
+ * @returns {import("./types.d.ts").WidgetUsageEntry[]}
+ */
+export function projectionUsageEntries(graph, projection) {
+  const sharedProjection = sharedUiProjectionForWeb(graph, projection);
+  const entries = /** @type {import("./types.d.ts").WidgetUsageEntry[]} */ ([]);
+  if (sharedProjection) {
+    entries.push(...(sharedProjection.widgetBindings || []).map(/** @param {import("./types.d.ts").WidgetUsage} usage @param {any} index */ (usage, index) => ({
+      projection,
+      sourceProjection: sharedProjection,
+      usage,
+      index
+    })));
+  }
+  entries.push(...(projection.widgetBindings || []).map(/** @param {import("./types.d.ts").WidgetUsage} usage @param {any} index */ (usage, index) => ({
+    projection,
+    sourceProjection: projection,
+    usage,
+    index
+  })));
+  return entries;
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {string | null | undefined} projectionId
+ * @returns {any}
+ */
+export function candidateProjections(graph, projectionId) {
+  if (projectionId) {
+    return [getProjection(graph, projectionId)];
+  }
+  const direct = uiProjectionCandidates(graph).filter(/** @param {import("./types.d.ts").WidgetProjection} projection */ (projection) => (projection.widgetBindings || []).length > 0);
+  const inherited = (graph.byKind.projection || []).filter(/** @param {import("./types.d.ts").WidgetProjection} projection */ (projection) => {
+    if ((projection.widgetBindings || []).length > 0) return false;
+    return Boolean(sharedUiProjectionForWeb(graph, projection)?.widgetBindings?.length);
+  });
+  return [...direct, ...inherited].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {Iterable<string>} widgetIds
+ * @param {Iterable<string>} projectionIds
+ * @returns {any}
+ */
+export function relatedVerificationFiles(graph, widgetIds, projectionIds) {
+  const ids = new Set([...widgetIds, ...projectionIds]);
+  return stableUnique((graph.byKind.verification || [])
+    .filter(/** @param {any} verification */ (verification) => (verification.validates || []).some(/** @param {any} ref */ (ref) => ids.has(ref.id)))
+    .map(/** @param {any} verification */ (verification) => sourcePath(verification)));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetOptions} options
+ * @returns {any}
+ */
+export function generateWidgetConformanceReport(graph, options = {}) {
+  const selectedWidgetId = options.widgetId || options.componentId || null;
+  const widgets = byId(graph.byKind.widget || []);
+  if (selectedWidgetId && !widgets.has(selectedWidgetId)) {
+    throw new Error(`No widget found with id '${selectedWidgetId}'`);
+  }
+
+  const projectionUsageRecords = /** @type {import("./types.d.ts").WidgetProjectionUsageRecord[]} */ ([]);
+  const checks = /** @type {any[]} */ ([]);
+  const referencedWidgetIds = /** @type {Set<string>} */ (new Set());
+  const affectedProjectionIds = /** @type {Set<string>} */ (new Set());
+
+  for (const projection of candidateProjections(graph, options.projectionId)) {
+    for (const entry of projectionUsageEntries(graph, projection)) {
+      const widgetId = entry.usage.widget?.id || null;
+      if (selectedWidgetId && widgetId !== selectedWidgetId) {
+        continue;
+      }
+      const widget = widgetId ? widgets.get(widgetId) : null;
+      if (widgetId) referencedWidgetIds.add(widgetId);
+      affectedProjectionIds.add(entry.projection.id);
+      if (entry.sourceProjection?.id) affectedProjectionIds.add(entry.sourceProjection.id);
+      const usageChecks = collectUsageChecks({ graph, projection: entry.projection, sourceProjection: entry.sourceProjection, usage: entry.usage, widget });
+      checks.push(...usageChecks);
+      const outcome = usageChecks.some(/** @param {any} check */ (check) => check.severity === "error")
+        ? "error"
+        : usageChecks.some(/** @param {any} check */ (check) => check.severity === "warning")
+          ? "warning"
+          : "pass";
+      projectionUsageRecords.push({
+        key: widgetUsageKey(entry.projection, entry.sourceProjection, entry.usage, entry.index),
+        projection: summarizeProjection(entry.projection),
+        source_projection: entry.sourceProjection.id === entry.projection.id ? null : summarizeProjection(entry.sourceProjection),
+        screen: {
+          id: entry.usage.screenId || null,
+          kind: projectionScreenMap(graph, entry.sourceProjection).get(entry.usage.screenId)?.kind || null,
+          title: projectionScreenMap(graph, entry.sourceProjection).get(entry.usage.screenId)?.title || null
+        },
+        region: entry.usage.region || null,
+        widget: summarizeWidget(widget) || { id: widgetId, name: widgetId, category: null, version: null, status: null, source_path: null },
+        data_bindings: entry.usage.dataBindings || [],
+        event_bindings: entry.usage.eventBindings || [],
+        behavior_realizations: buildWidgetBehaviorRealizations(widgetContract(widget), entry.usage),
+        outcome,
+        check_codes: usageChecks.map(/** @param {any} check */ (check) => check.code)
+      });
+    }
+  }
+
+  const widgetFiles = stableUnique([...referencedWidgetIds].map(/** @param {any} id */ (id) => sourcePath(widgets.get(id))));
+  const projectionFiles = stableUnique(
+    [...affectedProjectionIds].map(/** @param {any} id */ (id) => sourcePath((graph.byKind.projection || []).find(/** @param {import("./types.d.ts").WidgetProjection} projection */ (projection) => projection.id === id)))
+  );
+  const verificationFiles = relatedVerificationFiles(graph, referencedWidgetIds, affectedProjectionIds);
+  const errors = checks.filter(/** @param {any} check */ (check) => check.severity === "error");
+  const warnings = checks.filter(/** @param {any} check */ (check) => check.severity === "warning");
+
+  return {
+    type: "widget_conformance_report",
+    filters: {
+      projection: options.projectionId || null,
+      widget: selectedWidgetId
+    },
+    summary: {
+      total_usages: projectionUsageRecords.length,
+      passed_usages: projectionUsageRecords.filter(/** @param {import("./types.d.ts").WidgetProjectionUsageRecord} usage */ (usage) => usage.outcome === "pass").length,
+      warning_usages: projectionUsageRecords.filter(/** @param {import("./types.d.ts").WidgetProjectionUsageRecord} usage */ (usage) => usage.outcome === "warning").length,
+      error_usages: projectionUsageRecords.filter(/** @param {import("./types.d.ts").WidgetProjectionUsageRecord} usage */ (usage) => usage.outcome === "error").length,
+      warnings: warnings.length,
+      errors: errors.length,
+      affected_projections: stableUnique([...affectedProjectionIds]),
+      affected_widgets: stableUnique([...referencedWidgetIds])
+    },
+    projection_usages: projectionUsageRecords,
+    checks,
+    widget_contracts: stableUnique([...referencedWidgetIds])
+      .map(/** @param {any} id */ (id) => summarizeWidgetContract(widgets.get(id)))
+      .filter(Boolean),
+    write_scope: {
+      widget_files: widgetFiles,
+      projection_files: projectionFiles,
+      verification_files: verificationFiles,
+      paths: stableUnique([...widgetFiles, ...projectionFiles, ...verificationFiles])
+    },
+    impact: {
+      projections: stableUnique([...affectedProjectionIds]),
+      widgets: stableUnique([...referencedWidgetIds])
+    }
+  };
+}

package/src/generator/widget-conformance/types.d.ts

@@ -0,0 +1,121 @@
+export type WidgetReference = {
+  id?: string;
+  kind?: string;
+  target?: {
+    id?: string;
+    kind?: string;
+  };
+  [key: string]: any;
+};
+
+export type WidgetGraph = {
+  statements: any[];
+  byKind: Record<string, any[]>;
+  [key: string]: any;
+};
+
+export type WidgetProjection = {
+  id: string;
+  name?: string;
+  type?: string;
+  status?: string;
+  realizes?: WidgetReference[];
+  uiScreens?: any[];
+  uiScreenRegions?: any[];
+  widgetBindings?: WidgetUsage[];
+  loc?: {
+    file?: string;
+  };
+  [key: string]: any;
+};
+
+export type WidgetContract = {
+  id?: string;
+  name?: string;
+  category?: string;
+  version?: string;
+  status?: string;
+  props?: any[];
+  events?: any[];
+  behaviors?: WidgetBehavior[];
+  behavior?: WidgetBehavior[];
+  approvals?: any[];
+  dependencies?: any[];
+  patterns?: string[];
+  regions?: string[];
+  [key: string]: any;
+};
+
+export type WidgetStatement = {
+  id: string;
+  name?: string;
+  category?: string;
+  version?: string;
+  status?: string;
+  widgetContract?: WidgetContract;
+  loc?: {
+    file?: string;
+  };
+  [key: string]: any;
+};
+
+export type WidgetUsage = {
+  widget?: WidgetReference;
+  screenId?: string;
+  region?: string;
+  dataBindings?: any[];
+  eventBindings?: any[];
+  [key: string]: any;
+};
+
+export type WidgetUsageEntry = {
+  projection: WidgetProjection;
+  sourceProjection: WidgetProjection;
+  usage: WidgetUsage;
+  index: number;
+};
+
+export type WidgetBehavior = {
+  kind?: string;
+  source?: string;
+  status?: string;
+  directives?: any;
+  dataDependencies?: any[];
+  emits?: any[];
+  actions?: any[];
+  effects?: any[];
+  [key: string]: any;
+};
+
+export type WidgetUsageReport = {
+  key?: string;
+  projection?: any;
+  source_projection?: any;
+  screen?: any;
+  region?: string | null;
+  widget?: any;
+  behavior_realizations?: WidgetBehavior[];
+  [key: string]: any;
+};
+
+export type WidgetProjectionUsageRecord = WidgetUsageReport & {
+  outcome: "pass" | "warning" | "error";
+  check_codes: string[];
+};
+
+export type WidgetConformanceReport = {
+  filters?: any;
+  summary?: any;
+  projection_usages?: WidgetUsageReport[];
+  checks?: any[];
+  write_scope?: any;
+  impact?: any;
+  [key: string]: any;
+};
+
+export type WidgetOptions = {
+  widgetId?: string | null;
+  componentId?: string | null;
+  projectionId?: string | null;
+  [key: string]: any;
+};