qgraphflow 0.0.6

package/skills/q-flow/assets/viewer/src/export-svg.js

@@ -0,0 +1,90 @@
+import { createEdgeRoutes, graphBounds, pathFromRoute, cardinalityMarks } from './edge-routing.js';
+import { layoutText } from './text-layout.js';
+import { DIAGRAM_TYPES, diagramTypeOf, getDiagram, edgeMarkers, isDashed, labelRoleColors } from './diagrams/registry.js';
+import { renderNode } from './node-svg.js';
+import { text, fit, escapeXml, svgStyles, groupHeadingSvg, groupFrameSvg } from './diagrams/drawing.js';
+import { PALETTES, dataKinds, edgeColor, sequenceGroupColor, moduleColorMap, groupAppearanceMap, TYPOGRAPHY } from './visual-style.js';
+import { RADIX_COLORS_NOTICE } from './radix-colors.js';
+import { sequencePairs, sequenceExecutions } from './sequence-executions.js';
+import { sequenceFragment, renderFragment, fragmentDepth, fragmentSurfaceAt } from './sequence-fragments.js';
+import { requireDiagramQuality } from './layout-quality.js';
+
+function edgeMarker(edge, type, target, moduleColors, source, pair) {
+  const { end } = edgeMarkers(edge, type);
+  if (!end) return '';
+  if (end !== 'arrow') return ` marker-end="url(#${end})"`;
+  const marker = pair ? 'arrow-module' : edge.kind === 'failure' ? 'arrow-warn' : edge.kind === 'success' ? 'arrow-ok' : moduleColors?.has(edge.module ?? source?.module ?? target?.module) ? 'arrow-module' : dataKinds.has(target?.kind) ? 'arrow-data' : 'arrow';
+  return ` marker-end="url(#${marker})"`;
+}
+
+function edgeStartMarker(edge, type) {
+  const { start } = edgeMarkers(edge, type);
+  return start ? ` marker-start="url(#${start})"` : '';
+}
+
+function renderGroup(group, offsetX, offsetY, fragment, appearance) {
+  const x = group.position.x + offsetX;
+  const y = group.position.y + offsetY;
+  const label = fit(group.label, fragment?.heading?.width ?? group.size.width - (['alt', 'opt', 'loop', 'par'].includes(group.kind) ? 88 : 32));
+  return `<g data-diagram-group-id="${escapeXml(group.id)}"><title>${escapeXml(group.label)}</title>${groupFrameSvg(group, appearance, x, y)}${fragment ? (fragment.heading?.lines ?? [label]).map((line, i) => text(fragment.heading ? fragment.heading.x + offsetX : x + 16, y + 23 + i * 22, line, 'group')).join('') : groupHeadingSvg(group, x, y)}${['alt', 'opt', 'loop', 'par'].includes(group.kind) ? text(x + group.size.width - 16, y + 25, group.kind, 'group-kind', ' text-anchor="end"') : ''}</g>`;
+}
+
+function renderEdge(edge, route, type, offsetX, offsetY, palette, target, moduleColors, source, pair, labelSurface) {
+  const stroke = edgeColor(edge, target, palette, moduleColors, source, pair);
+  const dash = isDashed(edge, type) ? ' stroke-dasharray="7 6"' : '';
+  const label = route.label;
+  const labelX = route.labelPoint.x + offsetX;
+  const labelY = route.labelPoint.y + offsetY;
+  const labelSize = route.labelBox;
+  const pairLine = pair ? `<path d="M${labelX - layoutText(route.labelLines[0], Infinity).width / 2} ${labelY - labelSize.height / 2 + 3 + TYPOGRAPHY.body + 3}h${layoutText(pair.label, Infinity).width}" stroke="${stroke}" stroke-width="2"/>` : '';
+  const background = label ? `<rect x="${labelX - labelSize.width / 2}" y="${labelY - labelSize.height / 2}" width="${labelSize.width}" height="${labelSize.height}" rx="4" class="edge-bg"${labelSurface ? ` style="fill:${labelSurface}"` : ''}/>` : '';
+  const cardinalities = getDiagram(type).cardinalities ? [
+    cardinalityMarks(edge.sourceCardinality, route.points[0], route.points[1]),
+    cardinalityMarks(edge.targetCardinality, route.points.at(-1), route.points.at(-2))
+  ].map((mark, index) => `<g data-cardinality-endpoint="${index ? 'target' : 'source'}" transform="translate(${offsetX} ${offsetY})" fill="none" stroke="${palette.accent}" stroke-width="1.5"><path d="${mark.path}"/>${mark.circle ? `<circle cx="${mark.circle.cx}" cy="${mark.circle.cy}" r="${mark.circle.r}" fill="${palette.surface}"/>` : ''}</g>`).join('') : '';
+  const multiplicities = (route.endpointLabels ?? []).map(item => `<g class="edge-multiplicity" data-endpoint="${item.role}"><rect x="${item.labelBox.x + offsetX}" y="${item.labelBox.y + offsetY}" width="${item.labelBox.width}" height="${item.labelBox.height}" rx="4" class="edge-bg"/>${text(item.labelPoint.x + offsetX, item.labelBox.y + offsetY + 3 + TYPOGRAPHY.body, item.label, 'edge', ' text-anchor="middle"')}</g>`).join('');
+  return `<g data-diagram-edge-id="${escapeXml(edge.id)}"><path d="${pathFromRoute(route, offsetX, offsetY)}" fill="none" stroke="${stroke}" stroke-width="1.5"${dash}${edgeMarker(edge, type, target, moduleColors, source, pair)}${edgeStartMarker(edge, type)}/>${cardinalities}${background}${pairLine}${label ? route.labelLines.map((line, index) => text(labelX, labelY - labelSize.height / 2 + 3 + TYPOGRAPHY.body + index * TYPOGRAPHY.edgeLineHeight, route.labelRuns ? { runs: route.labelRuns[index], colors: labelRoleColors(type, palette) } : line, 'edge', ' text-anchor="middle"')).join('') : ''}${multiplicities}</g>`;
+}
+
+export function createDiagramSvg(graph, theme = 'light', moduleColors) {
+  requireDiagramQuality(graph);
+  const palette = PALETTES[theme] ?? PALETTES.light;
+  moduleColors ??= moduleColorMap([graph], palette);
+  const groupAppearances = groupAppearanceMap(graph.groups ?? [], palette);
+  const type = diagramTypeOf(graph);
+  const routes = createEdgeRoutes(graph);
+  const pairs = sequencePairs(graph), executions = sequenceExecutions(graph);
+  const nodeById = new Map(graph.nodes.map(node => [node.id, node]));
+  const bounds = graphBounds(graph, routes);
+  const margin = 64;
+  const width = bounds.width + margin * 2;
+  const titleLayout = layoutText(graph.meta.title, width - margin * 2, 24);
+  const subtitleLayout = layoutText(graph.meta.subtitle ?? '', width - margin * 2, TYPOGRAPHY.small);
+  const subtitleY = 66 + Math.max(0, titleLayout.lines.length - 1) * titleLayout.lineHeight;
+  const header = Math.max(88, subtitleLayout.lines.length ? subtitleY + (subtitleLayout.lines.length - 1) * subtitleLayout.lineHeight + 22 : 43 + Math.max(0, titleLayout.lines.length - 1) * titleLayout.lineHeight + 24);
+  const height = bounds.height + margin * 2 + header;
+  const offsetX = margin - bounds.x;
+  const offsetY = margin + header - bounds.y;
+  const fragments = new Map((graph.groups ?? []).map(group => [group.id, type === 'sequence' ? sequenceFragment(group, routes, graph.meta.locale, graph.groups ?? [], executions) : null]));
+  const groups = [...(graph.groups ?? [])].sort((a, b) => fragmentDepth(a, graph.groups ?? []) - fragmentDepth(b, graph.groups ?? [])).map(group => renderGroup(group, offsetX, offsetY, fragments.get(group.id), groupAppearances.get(group.id)) + (type === 'sequence' ? renderFragment({ ...fragments.get(group.id), guards: [], bodies: [] }, group, offsetX, offsetY, palette.ink3, groupAppearances.get(group.id).fill) : '')).join('');
+  const fragmentText = type === 'sequence' ? (graph.groups ?? []).map(group => renderFragment({ ...fragments.get(group.id), separators: [] }, group, offsetX, offsetY, palette.ink3, groupAppearances.get(group.id).fill)).join('') : '';
+
+  const edges = graph.edges.map(edge => renderEdge(edge, routes.get(edge.id), type, offsetX, offsetY, palette, nodeById.get(edge.target), moduleColors, nodeById.get(edge.source), pairs.get(edge.id), type === 'sequence' && routes.get(edge.id).label ? fragmentSurfaceAt(routes.get(edge.id).labelBox, graph.groups ?? [], groupAppearances) : undefined)).join('');
+  const nodes = graph.nodes.map(node => renderNode({ ...node, executionRects: executions.filter(item => item.participantId === node.id).map(item => ({ ...item, x: item.x - node.position.x, y: item.y - node.position.y, color: sequenceGroupColor(pairs.get(item.start.edgeId), palette) ?? palette.edge })) }, type, offsetX, offsetY, palette, graph.meta.locale, moduleColors)).join('');
+  const boardX = 24;
+  const boardY = header;
+  const boardWidth = width - 48;
+  const boardHeight = height - header - 24;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!-- Radix Colors\n${RADIX_COLORS_NOTICE}-->\n<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" data-graph-offset-x="${offsetX}" data-graph-offset-y="${offsetY}" role="img" aria-labelledby="title desc"><title id="title">${escapeXml(graph.meta.title)}</title><desc id="desc">${escapeXml(type)} diagram for ${escapeXml(graph.meta.sourceRef)}</desc><defs><filter id="node-shadow" x="-20%" y="-20%" width="140%" height="150%"><feDropShadow dx="0" dy="5" stdDeviation="7" flood-color="${palette.ink}" flood-opacity=".045"/></filter><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.edge}"/></marker><marker id="arrow-module" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="context-stroke"/></marker><marker id="arrow-warn" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.warn}"/></marker><marker id="arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.accent}"/></marker><marker id="arrow-data" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.data}"/></marker><marker id="arrow-open" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M1 1L9 5L1 9" fill="none" stroke="context-stroke" stroke-width="1.5"/></marker><marker id="triangle" viewBox="0 0 12 12" refX="11" refY="6" markerWidth="9" markerHeight="9" orient="auto"><path d="M1 1L11 6L1 11Z" fill="${palette.surface}" stroke="context-stroke"/></marker><marker id="diamond-filled" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="context-stroke"/></marker><marker id="diamond-open" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="${palette.surface}" stroke="context-stroke"/></marker><style>${svgStyles(palette)}</style></defs><rect width="100%" height="100%" fill="${palette.paper}"/><rect x="${boardX}" y="${boardY}" width="${boardWidth}" height="${boardHeight}" rx="16" fill="${palette.surface}" stroke="${palette.rule}"/>${titleLayout.lines.map((line, index) => text(margin, 43 + index * titleLayout.lineHeight, line, 'heading')).join('')}${subtitleLayout.lines.map((line, index) => text(margin, subtitleY + index * subtitleLayout.lineHeight, line, 'meta')).join('')}${groups}${type === 'sequence' ? nodes + edges : edges + nodes}${fragmentText}</svg>\n`;
+}
+
+// The generator and the Viewer's in-place save both write these files, so names and bytes come from one place: light
+// theme whatever the screen shows, and one module colour map shared by every view, as the Viewer computes it.
+export const SVG_FILE = new RegExp(`^diagram(-\\d+-(${DIAGRAM_TYPES.join('|')}))?\\.svg$`);
+
+export function diagramSvgFiles(input) {
+  const collection = Array.isArray(input.diagrams), views = collection ? input.diagrams : [input];
+  const moduleColors = moduleColorMap(views, PALETTES.light);
+  return views.map((view, index) => ({ name: collection ? `diagram-${index + 1}-${diagramTypeOf(view)}.svg` : 'diagram.svg', svg: createDiagramSvg(view, 'light', moduleColors) }));
+}

package/skills/q-flow/assets/viewer/src/graph-validation.js

@@ -0,0 +1,286 @@
+import { SUPPORTED_LOCALES } from './i18n.js';
+import { auditGraphLayout } from './edge-routing.js';
+import { missingCallExecutions, validateExecutions } from './sequence-executions.js';
+import { validateOperands } from './sequence-fragments.js';
+import { DIAGRAM_TYPES, diagramTypeOf, getDiagram } from './diagrams/registry.js';
+
+const EVIDENCE_KINDS = new Set(['source', 'code', 'config', 'schema', 'test', 'document', 'framework', 'inference']);
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function requireString(value, label, errors) {
+  if (typeof value !== 'string' || value.trim() === '') errors.push(`${label} must be a non-empty string`);
+}
+
+function optionalString(value, label, errors) {
+  if (value !== undefined && typeof value !== 'string') errors.push(`${label} must be a string`);
+}
+
+function requireBox(item, label, errors, inputOnly = false) {
+  for (const [group, keys] of [['position', ['x', 'y']], ['size', ['width', 'height']]]) {
+    if (inputOnly && item[group] === undefined) continue;
+    if (!isObject(item[group])) {
+      errors.push(`${label}.${group} is required`);
+      continue;
+    }
+    for (const key of keys) {
+      const value = item[group][key];
+      if (!Number.isFinite(value) || value < 0) errors.push(`${label}.${group}.${key} must be a non-negative finite number`);
+    }
+  }
+}
+
+function requirePoint(point, label, errors) {
+  if (!point || typeof point !== 'object' || Array.isArray(point)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  for (const key of ['x', 'y']) {
+    if (!Number.isFinite(point[key]) || point[key] < 0) errors.push(`${label}.${key} must be a non-negative finite number`);
+  }
+}
+
+function validateStringArray(value, label, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.trim() === '')) {
+    errors.push(`${label} must be an array of non-empty strings`);
+  }
+}
+
+export function graphsOf(input) {
+  return input && typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.diagrams)
+    ? input.diagrams
+    : [input];
+}
+
+export function validateGraph(graph, { inputOnly = false, audit = true } = {}) {
+  const errors = [];
+  if (!isObject(graph)) return ['graph must be an object'];
+
+  if (!isObject(graph.meta)) errors.push('meta must be an object');
+  requireString(graph.meta?.title, 'meta.title', errors);
+  requireString(graph.meta?.sourceRef, 'meta.sourceRef', errors);
+  for (const key of ['subtitle', 'scope']) optionalString(graph.meta?.[key], `meta.${key}`, errors);
+  if (graph.meta?.locale !== undefined && !SUPPORTED_LOCALES.includes(graph.meta.locale)) errors.push('meta.locale is unsupported');
+  const diagramType = diagramTypeOf(graph);
+  if (!DIAGRAM_TYPES.includes(diagramType)) errors.push('meta.diagramType is unsupported');
+  const rules = getDiagram(diagramType) ?? getDiagram('architecture');
+  if (!Array.isArray(graph.nodes) || graph.nodes.length === 0) errors.push('nodes must be a non-empty array');
+  if (!Array.isArray(graph.edges)) errors.push('edges must be an array');
+  if (graph.groups !== undefined && !Array.isArray(graph.groups)) errors.push('groups must be an array when provided');
+  if (errors.length) return errors;
+
+  const ids = new Set();
+  const nodeIds = new Set();
+  for (const [index, node] of (graph.nodes ?? []).entries()) {
+    const label = `nodes[${index}]`;
+    if (!isObject(node)) { errors.push(`${label} must be an object`); continue; }
+    requireString(node?.id, `${label}.id`, errors);
+    requireString(node?.label, `${label}.label`, errors);
+    optionalString(node.subtitle, `${label}.subtitle`, errors);
+    if (node.module !== undefined) requireString(node.module, `${label}.module`, errors);
+    if (!rules.nodeKinds.includes(node?.kind)) errors.push(`${label}.kind is unsupported for ${diagramType}`);
+    requireBox(node ?? {}, label, errors, inputOnly);
+    if (typeof node.id === 'string' && ids.has(node.id)) errors.push(`${label}.id duplicates ${node.id}`);
+    ids.add(node?.id);
+    nodeIds.add(node?.id);
+    if (node.source !== undefined && !isObject(node.source)) errors.push(`${label}.source must be an object`);
+    else if (node.source) {
+      requireString(node.source.file, `${label}.source.file`, errors);
+      optionalString(node.source.symbol, `${label}.source.symbol`, errors);
+      if (node.source.kind !== undefined && !EVIDENCE_KINDS.has(node.source.kind)) errors.push(`${label}.source.kind is unsupported`);
+      if (!Number.isInteger(node.source.lineStart) || node.source.lineStart < 1) errors.push(`${label}.source.lineStart must be a positive integer`);
+      if (node.source.lineEnd !== undefined && (!Number.isInteger(node.source.lineEnd) || (Number.isInteger(node.source.lineStart) && node.source.lineEnd < node.source.lineStart))) {
+        errors.push(`${label}.source.lineEnd must be an integer at or after lineStart`);
+      }
+    }
+    for (const key of ['facts', 'tags', 'attributes', 'methods']) validateStringArray(node[key], `${label}.${key}`, errors);
+    if (node.fields !== undefined) {
+      if (!Array.isArray(node.fields)) errors.push(`${label}.fields must be an array`);
+      else for (const [index, field] of node.fields.entries()) {
+        const prefix = `${label}.fields[${index}]`;
+        if (!isObject(field)) { errors.push(`${prefix} must be an object`); continue; }
+        requireString(field.name, `${prefix}.name`, errors);
+        requireString(field.type, `${prefix}.type`, errors);
+        if (field.key !== undefined && !['PK', 'FK', 'UK'].includes(field.key)) errors.push(`${prefix}.key is unsupported`);
+        if (field.nullable !== undefined && typeof field.nullable !== 'boolean') errors.push(`${prefix}.nullable must be boolean`);
+      }
+    }
+    rules.validateNode?.(node, label, errors, { requireString, validateStringArray });
+  }
+
+  for (const [index, group] of (graph.groups ?? []).entries()) {
+    const label = `groups[${index}]`;
+    if (!isObject(group)) { errors.push(`${label} must be an object`); continue; }
+    requireString(group?.id, `${label}.id`, errors);
+    requireString(group?.label, `${label}.label`, errors);
+    if (!rules.groupKinds.includes(group?.kind)) errors.push(`${label}.kind is unsupported for ${diagramType}`);
+    requireBox(group ?? {}, label, errors, inputOnly);
+    if (typeof group.id === 'string' && ids.has(group.id)) errors.push(`${label}.id duplicates ${group.id}`);
+    ids.add(group?.id);
+  }
+
+  const edgeIds = new Set();
+  const sequenceOrders = new Set();
+  for (const [index, edge] of (graph.edges ?? []).entries()) {
+    const label = `edges[${index}]`;
+    if (!isObject(edge)) { errors.push(`${label} must be an object`); continue; }
+    requireString(edge?.id, `${label}.id`, errors);
+    optionalString(edge.label, `${label}.label`, errors);
+    if (edge.module !== undefined) requireString(edge.module, `${label}.module`, errors);
+    requireString(edge?.source, `${label}.source`, errors);
+    requireString(edge?.target, `${label}.target`, errors);
+    if (!rules.edgeKinds.includes(edge?.kind)) errors.push(`${label}.kind is unsupported for ${diagramType}`);
+    if (!EVIDENCE_KINDS.has(edge?.evidence)) errors.push(`${label}.evidence is unsupported`);
+    if (typeof edge.id === 'string' && edgeIds.has(edge.id)) errors.push(`${label}.id duplicates ${edge.id}`);
+    edgeIds.add(edge?.id);
+    if (typeof edge.source === 'string' && !nodeIds.has(edge.source)) errors.push(`${label}.source does not name a node: ${edge.source}`);
+    if (typeof edge.target === 'string' && !nodeIds.has(edge.target)) errors.push(`${label}.target does not name a node: ${edge.target}`);
+    if (edge?.route !== undefined) {
+      if (!edge.route || typeof edge.route !== 'object' || Array.isArray(edge.route)) {
+        errors.push(`${label}.route must be an object`);
+      } else {
+        if (edge.route.via !== undefined) {
+          if (!Array.isArray(edge.route.via)) errors.push(`${label}.route.via must be an array`);
+          else edge.route.via.forEach((point, pointIndex) => requirePoint(point, `${label}.route.via[${pointIndex}]`, errors));
+        }
+        if (edge.route.labelAt !== undefined) requirePoint(edge.route.labelAt, `${label}.route.labelAt`, errors);
+        if (edge.route.messageY !== undefined && (diagramType !== 'sequence' || !Number.isFinite(edge.route.messageY) || edge.route.messageY < 0)) errors.push(`${label}.route.messageY must be a non-negative finite number for sequence`);
+      }
+    }
+    if (diagramType === 'sequence' && !inputOnly && edge.route?.messageY === undefined) errors.push(`${label}.route.messageY is required for a positioned sequence message; regenerate with --layout auto`);
+    rules.validateEdge?.(edge, label, errors, { requireString, sequenceOrders });
+  }
+  if (errors.length === 0) errors.push(...validateLayoutSemantics(graph));
+  if (errors.length === 0) errors.push(...validateOperands(graph));
+  if (errors.length === 0) errors.push(...validateExecutions(graph, { inputOnly }));
+  if (errors.length === 0 && !inputOnly && audit) errors.push(...auditGraphLayout(graph).errors);
+  return errors;
+}
+
+function validateLayoutSemantics(graph) {
+  const errors = [], type = diagramTypeOf(graph), sequence = type === 'sequence';
+  const nodes = new Map(graph.nodes.map(node => [node.id, node])), groups = new Map((graph.groups ?? []).map(group => [group.id, group]));
+  for (const node of graph.nodes) {
+    if (node.groupId !== undefined) {
+      if (sequence) errors.push(`node ${node.id}.groupId is not supported for sequence participants`);
+      else if (typeof node.groupId !== 'string' || !groups.has(node.groupId)) errors.push(`node ${node.id}.groupId does not name a group: ${String(node.groupId)}`);
+      else if (type === 'usecase' && node.kind === 'actor') errors.push(`node ${node.id}.groupId places an actor inside a system boundary`);
+    }
+    if (node.layout !== undefined) {
+      if (!isObject(node.layout)) errors.push(`node ${node.id}.layout must be an object`);
+      else for (const key of ['rank', 'order']) if (node.layout[key] !== undefined && (!Number.isInteger(node.layout[key]) || node.layout[key] < 0)) errors.push(`node ${node.id}.layout.${key} must be a non-negative integer`);
+    }
+  }
+  if (!sequence) for (const group of groups.values()) {
+    if (group.parentId === undefined) continue;
+    if (typeof group.parentId !== 'string' || !groups.has(group.parentId)) errors.push(`group ${group.id}.parentId does not name a group: ${String(group.parentId)}`);
+    const seen = new Set([group.id]); let parent = groups.get(group.parentId);
+    while (parent) {
+      if (seen.has(parent.id)) { errors.push(`group ${group.id}.parentId contains a cycle at ${parent.id}`); break; }
+      seen.add(parent.id); parent = groups.get(parent.parentId);
+    }
+  }
+  if (graph.layout !== undefined && !isObject(graph.layout)) errors.push('layout must be an object');
+  else for (const key of ['primaryPath', 'participantOrder']) {
+    const list = graph.layout?.[key];
+    if (list === undefined) continue;
+    if (!Array.isArray(list) || !list.length || list.some(id => typeof id !== 'string' || !nodes.has(id)) || new Set(list).size !== list.length) {
+      errors.push(`layout.${key} must be a non-empty list of distinct node IDs`); continue;
+    }
+    if (key === 'participantOrder') {
+      if (!sequence || list.length !== nodes.size) errors.push('layout.participantOrder must be a complete permutation of sequence participants');
+      const ordered = list.map(id => nodes.get(id).layout?.order).filter(value => value !== undefined);
+      if (ordered.some((value, i) => i && value <= ordered[i - 1])) errors.push('layout.participantOrder conflicts with node.layout.order');
+    } else {
+      if (sequence) errors.push('layout.primaryPath is not supported for sequence; use participantOrder');
+      for (let i = 1; i < list.length; i++) {
+        if (!graph.edges.some(edge => edge.source === list[i - 1] && edge.target === list[i])) errors.push(`layout.primaryPath has no directed edge from ${list[i - 1]} to ${list[i]}`);
+        const before = nodes.get(list[i - 1]).layout?.rank, after = nodes.get(list[i]).layout?.rank;
+        if (before !== undefined && after !== undefined && before >= after) errors.push(`layout.primaryPath conflicts with node.layout.rank at ${list[i]}`);
+      }
+    }
+  }
+  if (sequence && new Set(graph.nodes.map(node => node.layout?.rank).filter(value => value !== undefined)).size > 1) errors.push('sequence participants must share one layout.rank');
+  for (const edge of graph.edges) {
+    const source = nodes.get(edge.source), target = nodes.get(edge.target);
+    if (type === 'class' && ['inheritance', 'implementation'].includes(edge.kind)) {
+      if (edge.kind === 'implementation' && target.kind !== 'interface') errors.push(`edge ${edge.id} implementation target must be an interface`);
+      if (source.layout?.rank !== undefined && target.layout?.rank !== undefined && target.layout.rank >= source.layout.rank) errors.push(`edge ${edge.id} layout.rank must place parent/interface ${target.id} above ${source.id}`);
+    }
+    if (type === 'usecase' && ['include', 'extend'].includes(edge.kind) && (source.kind !== 'usecase' || target.kind !== 'usecase')) errors.push(`edge ${edge.id} ${edge.kind} endpoints must both be use cases`);
+  }
+  return errors;
+}
+
+// The CLI's entry point (validate, generate, --fix). On top of what the Viewer renders, it asks for the callee bar of
+// every answered sync call, so pages generated earlier still open while new and refreshed graphs carry their bars.
+export function validateGraphInput(input, options = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return ['graph must be an object'];
+  const authored = graph => { const errors = validateGraph(graph, options); return errors.length ? errors : missingCallExecutions(graph); };
+  if (!Object.hasOwn(input, 'diagrams')) return authored(input);
+  if (!Array.isArray(input.diagrams) || input.diagrams.length < 1 || input.diagrams.length > DIAGRAM_TYPES.length) {
+    return [`diagrams must contain between 1 and ${DIAGRAM_TYPES.length} graphs`];
+  }
+
+  const errors = [];
+  const types = new Set();
+  input.diagrams.forEach((graph, index) => {
+    const type = diagramTypeOf(graph);
+    if (types.has(type)) errors.push(`diagrams[${index}].meta.diagramType duplicates ${type}`);
+    types.add(type);
+    errors.push(...authored(graph).map(error => `diagrams[${index}].${error}`));
+  });
+  return errors;
+}
+
+// Advisory review of an authored graph or collection: warnings, never errors, so every graph that validated before
+// still validates. It reads the card-identity contract back to the author: a node without `module` renders on the
+// plain surface, one module for a whole flow deserves a second look, and only a decision branches in a flowchart.
+// Outsiders (`external`, `actor`, `device`) may stay plain; what is flagged for them is inconsistency across views.
+const PLAIN_KINDS = new Set(['initial', 'final']);
+const OUTSIDER_KINDS = new Set(['external', 'actor', 'device']);
+const moduleOf = item => (typeof item?.module === 'string' && item.module.trim() ? item.module : undefined);
+
+export function reviewComposition(input) {
+  if (validateGraphInput(input, { inputOnly: true }).length) return [];
+  const graphs = graphsOf(input), warnings = [];
+  const members = graph => [...graph.nodes, ...graph.edges];
+  const modules = new Set(graphs.flatMap(graph => members(graph).map(moduleOf).filter(Boolean)));
+  // The same label across views is the same component: its module must be present everywhere and be the same one.
+  const byLabel = new Map();
+  for (const graph of graphs) for (const node of graph.nodes) if (typeof node.label === 'string' && !PLAIN_KINDS.has(node.kind)) {
+    byLabel.set(node.label, [...(byLabel.get(node.label) ?? []), { diagramType: diagramTypeOf(graph), id: node.id, module: moduleOf(node) }]);
+  }
+  for (const graph of graphs) {
+    const diagramType = diagramTypeOf(graph);
+    const warn = (ruleId, elementIds, message, remediation) => warnings.push({ ruleId, severity: 'warning', diagramType, elementIds, message, remediation });
+    if (modules.size) {
+      const plain = graph.nodes.filter(node => !PLAIN_KINDS.has(node.kind) && !OUTSIDER_KINDS.has(node.kind) && !moduleOf(node));
+      if (plain.length) warn('module.missing', plain.map(node => node.id),
+        `${plain.length === 1 ? 'node' : 'nodes'} ${plain.map(node => node.id).join(', ')} ${plain.length === 1 ? 'has' : 'have'} no module and render${plain.length === 1 ? 's' : ''} on the plain surface without identity`,
+        'Give every ordinary node the module of the subsystem whose work it performs (a step: the subsystem that does the work; an external hub or broker: its channel); leave only true outsiders plain.');
+      for (const node of graph.nodes) {
+        const elsewhere = (byLabel.get(node.label) ?? []).filter(item => item.diagramType !== diagramType && item.module && item.module !== moduleOf(node));
+        if (!elsewhere.length || PLAIN_KINDS.has(node.kind)) continue;
+        const other = elsewhere[0];
+        warn('module.inconsistent', [node.id], `node ${node.id} "${node.label}" ${moduleOf(node) ? `carries module "${moduleOf(node)}"` : 'has no module'} here but "${other.module}" in ${other.diagramType}`,
+          'The same component keeps the same module in every view of a collection; copy the module name or make the labels differ when they are different things.');
+      }
+    }
+    const washed = graph.nodes.filter(moduleOf);
+    if (['flowchart', 'dataflow'].includes(diagramType) && washed.length >= 6 && new Set(washed.map(moduleOf)).size === 1) {
+      warn('module.single-tone', washed.map(node => node.id),
+        `${diagramType} gives all ${washed.length} nodes the module "${moduleOf(washed[0])}", so the wash tells the reader nothing`,
+        'Check whether the steps really are one subsystem\'s work: a step performed by another subsystem (a store, a cache layer, a queue) takes that subsystem\'s module, start and end take the caller. If everything truly belongs to one subsystem, leave it.');
+    }
+    if (diagramType === 'flowchart') {
+      const outgoing = new Map();
+      for (const edge of graph.edges) outgoing.set(edge.source, (outgoing.get(edge.source) ?? 0) + 1);
+      for (const node of graph.nodes) if (node.kind !== 'decision' && (outgoing.get(node.id) ?? 0) > 1) {
+        warn('flowchart.process-branch', [node.id], `node ${node.id} (${node.kind}) has ${outgoing.get(node.id)} outgoing edges; only a decision branches`,
+          'Insert a decision that asks the actual condition, or merge the paths into one.');
+      }
+    }
+  }
+  return warnings;
+}