@principal-ai/subsystems-react 0.51.1 → 0.51.3

package/src/stories/Subsystem/ComponentGraph/Issues.stories.tsx

@@ -61,8 +61,34 @@ const ISSUES: SubsystemIssue[] = [
     message: 'Step 2 references a line that moved (was :42).',
     target: {
       kind: 'step',
-      id: 'flow-1',
-      label: 'Checkout',
+      id: 'story-steps',
+      label: 'Story steps',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+  {
+    id: 'i20',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Story steps" step 1: call site not verified (entry → store via writes)',
+    target: {
+      kind: 'step',
+      id: 'story-steps',
+      label: 'Story steps',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'i21',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Story steps" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'story-steps',
+      label: 'Story steps',
       detail: 'step 2',
       stepIndex: 1,
     },
@@ -181,3 +207,143 @@ export const GraphWithIssues: Story = {
     </div>
   ),
 };
+
+/** Trail step verification findings — unconfirmed and stale call sites. */
+const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
+  {
+    id: 'ts1',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Add to Cart" step 1: call site not verified (addToCart → cartStore via writes)',
+    target: {
+      kind: 'step',
+      id: 'add-to-cart',
+      label: 'Add to Cart',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'ts2',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Add to Cart" step 2: call site not verified (cartStore → inventoryService via calls)',
+    target: {
+      kind: 'step',
+      id: 'add-to-cart',
+      label: 'Add to Cart',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+  {
+    id: 'ts3',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 1: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout',
+      label: 'Checkout',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'ts4',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 3: call site changed since verification (lines 78-82 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout',
+      label: 'Checkout',
+      detail: 'step 3',
+      stepIndex: 2,
+    },
+  },
+];
+
+/** Trail step verification: shows unconfirmed and stale call site findings. */
+export const TrailStepVerification: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList
+        issues={TRAIL_STEP_ISSUES}
+        focusCategory="trail"
+        onSelectIssue={() => {}}
+      />
+    </div>
+  ),
+};
+
+/** Trail step verification badges on graph edges. */
+const stepVerificationComponents = components([
+  ['api', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
+  ['store', 'cartStore', 'store', 'src/checkout/cartStore.ts', 'pkg:github/you/your-app', 'Retained cart state.', 'cartStore'],
+  ['payment', 'PaymentService', 'class', 'src/payment/service.ts', 'pkg:github/you/your-app', 'Processes payments.', 'PaymentService'],
+]);
+
+const stepVerificationTrails = [
+  {
+    id: 'checkout-flow',
+    title: 'Checkout',
+    steps: [
+      { from: 'api', to: 'store', mechanism: 'writes' as const },
+      { from: 'store', to: 'payment', mechanism: 'calls' as const },
+    ],
+  },
+];
+
+const stepVerificationIssues: SubsystemIssue[] = [
+  {
+    id: 'sv1',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Checkout" step 1: call site not verified (checkoutApi → cartStore via writes)',
+    target: {
+      kind: 'step',
+      id: 'checkout-flow',
+      label: 'Checkout',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'sv2',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout-flow',
+      label: 'Checkout',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+];
+
+/** Graph with trail step verification badges on edges — ? for unconfirmed, clock for stale. */
+export const GraphWithStepVerificationBadges: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={stepVerificationComponents}
+        trails={stepVerificationTrails}
+        initialTrailId="checkout-flow"
+        title="Checkout with Step Verification"
+        description="Shows edge badges for step verification status: question mark (?) for unconfirmed call sites, clock for stale call sites."
+        diagnostic={{
+          status: 'issues',
+          issueCount: stepVerificationIssues.length,
+          onToggle: () => {},
+        }}
+        issues={stepVerificationIssues}
+        showIssues
+        onSelectIssue={() => {}}
+        onApplyIssueFix={() => {}}
+      />
+    </div>
+  ),
+};

package/src/subsystem/C4Graph.tsx

@@ -1,7 +1,7 @@
 /**
  * C4Graph — a C4 projection of a (composed) subsystem model on React Flow.
  *
- * Feed it a `C4Model` from `buildC4Model()` and it draws the
+ * Feed it an authored `C4Model` and it draws the
  * system as a compound frame, its containers (or components) as boxes, and
  * externals/actors outside the system. `trail` steps render as flow
  * edges. Click a box to list the source components it rolled up.
@@ -22,9 +22,11 @@ import {
   ReactFlow,
   ReactFlowProvider,
   useReactFlow,
+  useViewport,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
+import { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, EDGE_LABEL_WIDTH } from '../utils/edgeLabel';
 import { MECHANISM_COLOR } from './model';
 import { C4NodeCard, NODE_H, NODE_W, nodeSize, nodeStyle } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
@@ -34,6 +36,17 @@ export interface C4GraphProps {
   model: C4Model;
   title?: string;
   onSelectNode?: (id: string | null) => void;
+  /**
+   * Extra width / height reserved around each card when laying out, in flow px.
+   * The visible gap between boxes is `2 × gutter` (ELK's `nodeNode` spacing,
+   * plus the frame padding where a frame adds one).
+   *
+   * Above the default 28 the `needs …` gap row was removed, so cards are
+   * shorter and packing them tighter than the spacing they were tuned at makes
+   * them collide. Raise it for a more airy graph.
+   * @default 28
+   */
+  gutter?: number;
 }
 
 function edgeColor(mechanism: string | undefined, fallback: string): string {
@@ -57,6 +70,98 @@ function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>)
   );
 }
 
+/**
+ * Edge-label overlay.
+ *
+ * Drawn as an HTML layer above the canvas rather than React Flow's built-in
+ * edge label, so a C4 line's label reads like the subsystem graph's: an opaque
+ * rounded chip in the mechanism colour, monospace text, scaling with zoom.
+ *
+ * Positions come from ELK's computed label anchors (`edgeLabelPositions`, flow
+ * coords); the current viewport converts them to screen space.
+ */
+function C4EdgeLabels({
+  positions,
+  edges,
+  muted,
+}: {
+  positions: Map<string, { x: number; y: number }>;
+  edges: C4Model['edges'];
+  muted: string;
+}) {
+  const { theme } = useTheme();
+  const viewport = useViewport();
+  const surface = theme.colors.backgroundSecondary ?? theme.colors.background;
+  const byId = useMemo(() => new Map(edges.map((e) => [e.id, e])), [edges]);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        zIndex: 5,
+      }}
+    >
+      {[...positions].map(([id, p]) => {
+        const edge = byId.get(id);
+        if (!edge) return null;
+        const color = edgeColor(edge.mechanisms[0], muted);
+        // C4 asks the line to name the interaction's protocol; fall back to the
+        // label when a caller supplied none.
+        const text = edge.protocol ?? edge.label;
+        return (
+          <div
+            key={id}
+            style={{
+              position: 'absolute',
+              left: p.x * viewport.zoom + viewport.x,
+              top: p.y * viewport.zoom + viewport.y,
+              transform: `translate(-50%, -50%) scale(${viewport.zoom})`,
+              transformOrigin: 'center center',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: EDGE_LABEL_WIDTH,
+              height: EDGE_LABEL_HEIGHT,
+              boxSizing: 'border-box',
+              padding: '7px 8px',
+            }}
+          >
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                inset: 0,
+                borderRadius: 4,
+                border: `0.5px solid ${color}`,
+                background: surface,
+              }}
+            />
+            <span
+              style={{
+                position: 'relative',
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontSize: EDGE_LABEL_FONT_SIZE,
+                lineHeight: 1,
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 500,
+                color,
+              }}
+            >
+              {text}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'container'; color: string }>>) {
   const { theme } = useTheme();
   const color = props.data.color;
@@ -106,7 +211,7 @@ const nodeTypes = {
   'c4-group': C4GroupView,
 };
 
-function Inner({ model, title, onSelectNode }: C4GraphProps) {
+function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -114,6 +219,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
   const [rfEdges, setRfEdges] = useState<Edge[]>([]);
   const [ready, setReady] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [labelPositions, setLabelPositions] = useState<Map<string, { x: number; y: number }>>(
+    () => new Map(),
+  );
 
   const layoutKey = useMemo(
     () =>
@@ -130,10 +238,11 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     setReady(false);
     setSelectedId(null);
 
-    // Per-node size, so a square component is laid out as a square. Feeding the
-    // container dimensions for everything would make ELK reserve 210x138 of
-    // space around a 132x132 box and space the component view twice as far
-    // apart as it needs.
+    // Per-kind size, so a square component is laid out as a square. Feeding the
+    // container dimensions for everything would make ELK reserve 250x150 of
+    // space around a 140x140 box and space the component view twice as far
+    // apart as it needs. `gutter` is added here, not passed as node spacing, so
+    // a frame's padding clears the card inside it by the same margin.
     const rfNodes: Node[] = model.nodes.map((n, i) => {
       const size = nodeSize(n);
       return {
@@ -142,8 +251,8 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         // Fallback grid pitch uses the container box — the largest, so the
         // pre-layout positions never overlap. ELK replaces them on success.
         position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
-        width: size.width,
-        height: size.height,
+        width: size.width + gutter,
+        height: size.height + gutter,
         ...(n.parentId ? { parentId: n.parentId } : {}),
         data: { node: n, selected: false },
       };
@@ -162,16 +271,17 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         id: e.id,
         source: e.source,
         target: e.target,
-        label: e.label,
-        labelShowBg: false,
-        labelStyle: { fill: muted, fontSize: theme.fontSizes[0], fontFamily: theme.fonts.monospace },
+        // The reserved label box and the chip must agree on size, so ELK is
+        // given the same text the chip draws (protocol first, then label). The
+        // chip itself is the C4EdgeLabels overlay, not this field.
+        label: e.protocol ?? e.label,
         style: {
           stroke: color,
           strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
           strokeDasharray: '6 4',
         },
         markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
-        data: { edge: e },
+        data: { edge: e, color },
       };
     });
 
@@ -180,10 +290,12 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       preserveNodePositions: false,
       groups,
       keepSingletonGroups: true,
+      edgeLabels: { enabled: true, placement: 'CENTER' },
     })
       .then((result) => {
         if (!alive) return;
         const positioned = new Map(result.nodes.map((n) => [n.id, n]));
+        setLabelPositions(result.edgeLabelPositions ?? new Map());
         const builtGroups = new Set(result.groupBounds.keys());
         const groupById = new Map(model.groups.map((g) => [g.id, g]));
 
@@ -293,6 +405,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       >
         <GraphChrome />
       </ReactFlow>
+      {ready && labelPositions.size > 0 && (
+        <C4EdgeLabels positions={labelPositions} edges={model.edges} muted={muted} />
+      )}
       {!ready && (
         <div
           style={{

package/src/subsystem/C4NodeCard.test.ts

@@ -3,6 +3,8 @@ import {
   nodeStyle,
   nodeSubtitle,
   nodeTag,
+  nodeKindIcon,
+  nodeTopLabel,
   nodeShape,
   nodeMissing,
   NODE_W,
@@ -111,6 +113,47 @@ describe('nodeTag — what the box IS', () => {
   });
 });
 
+describe('nodeKindIcon — a container’s sort, not its C4 kind', () => {
+  test('application and data-store get different icons', () => {
+    const app = nodeKindIcon(node({ containerKind: 'application' }));
+    const store = nodeKindIcon(node({ containerKind: 'data-store' }));
+    expect(app).toBeDefined();
+    expect(store).toBeDefined();
+    expect(app).not.toBe(store);
+  });
+
+  test('only containers get an icon — the shape carries the rest', () => {
+    for (const kind of ['component', 'external-system', 'person'] as const) {
+      expect(nodeKindIcon(node({ kind }))).toBeUndefined();
+    }
+  });
+
+  test('the icon does not depend on confirmation state', () => {
+    expect(nodeKindIcon(node({ state: 'proposed' }))).toBe(
+      nodeKindIcon(node({ state: 'accepted' })),
+    );
+  });
+});
+
+describe('nodeTopLabel — the technology, or the kind when none is stated', () => {
+  test('a stated technology is the label', () => {
+    expect(
+      nodeTopLabel(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
+    ).toBe('Bun + Electrobun');
+    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
+  });
+
+  test('a container with no technology falls back to its kind', () => {
+    expect(nodeTopLabel(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
+  });
+
+  test('the other kinds fall back to their C4 kind', () => {
+    expect(nodeTopLabel(node({ kind: 'component' }))).toBe('component');
+    expect(nodeTopLabel(node({ kind: 'external-system' }))).toBe('external-system');
+    expect(nodeTopLabel(node({ kind: 'person' }))).toBe('person');
+  });
+});
+
 describe('nodeShape — kind without relying on colour or dash', () => {
   test('a container is a sharp rectangle', () => {
     const s = nodeShape(node());
@@ -142,47 +185,28 @@ describe('nodeShape — kind without relying on colour or dash', () => {
 });
 
 describe('nodeSubtitle', () => {
-  test('shows the container kind and technology', () => {
+  test('is the element description when it has one', () => {
     expect(
-      nodeSubtitle(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
-    ).toBe('application · Bun + Electrobun');
-  });
-
-  test('shows a data store with no technology as just the kind', () => {
-    expect(nodeSubtitle(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
-  });
-
-  test('falls back to the construct breakdown when neither is stated', () => {
-    const s = nodeSubtitle(node({ constructs: ['function', 'store'], members: ['a', 'b'] }));
-    expect(s).toContain('function');
-    expect(s).toContain('store');
-    expect(s).toContain('2 components');
-  });
-
-  test('singularises a single member', () => {
-    const s = nodeSubtitle(node({ constructs: ['function'], members: ['a'] }));
-    expect(s).toContain('1 component');
-    expect(s).not.toContain('1 components');
-  });
-
-  test('a component shows its construct and file basename', () => {
-    const s = nodeSubtitle(
-      node({
-        kind: 'component',
-        component: {
-          alias: 'a',
-          name: 'buildGroups',
-          construct: 'function',
-          file: 'src/subsystem/model.ts',
-          purl: 'pkg:x#src/subsystem/model.ts',
-        },
-      }),
-    );
-    expect(s).toBe('function · model.ts');
-  });
-
-  test('a component shows its technology when it has one', () => {
-    expect(nodeSubtitle(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
+      nodeSubtitle(node({ technology: 'Bun', description: 'Runs the audit pipeline.' })),
+    ).toBe('Runs the audit pipeline.');
+  });
+
+  test('is empty when nothing is stated — there is no fallback', () => {
+    const withTech = node({ technology: 'Bun + Electrobun' });
+    const withMembers = node({ constructs: ['function', 'store'], members: ['a', 'b'] });
+    const component = node({
+      kind: 'component',
+      component: {
+        alias: 'a',
+        name: 'buildGroups',
+        construct: 'function',
+        file: 'src/subsystem/model.ts',
+        purl: 'pkg:x#src/subsystem/model.ts',
+      },
+    });
+    for (const n of [withTech, withMembers, component]) {
+      expect(nodeSubtitle(n)).toBe('');
+    }
   });
 });
 
@@ -248,8 +272,8 @@ describe('nodeSize — a component is a proper square', () => {
 
 describe('card metrics', () => {
   test('exposes the size the graph lays out against', () => {
-    expect(NODE_W).toBe(210);
-    expect(NODE_H).toBe(138);
+    expect(NODE_W).toBe(250);
+    expect(NODE_H).toBe(150);
   });
 
   test('COMPONENT_SIZE is a square, not just a smaller rectangle', () => {
@@ -258,23 +282,23 @@ describe('card metrics', () => {
   });
 
   test('is near-square, not a wide strip', () => {
-    // The card carries four fields (tag, label, kind+technology, notation
-    // gap). A 3:1 strip truncates the last two; this is the aspect ratio that
-    // lets each sit on its own line.
+    // The card carries three fields (technology row, label, description). A
+    // 3:1 strip wraps the last two hard; this is the aspect ratio that lets
+    // each sit on its own line.
     const ratio = NODE_W / NODE_H;
     expect(ratio).toBeGreaterThan(1);
     expect(ratio).toBeLessThan(1.8);
   });
 
-  test('is tall enough for four lines of content', () => {
-    // tag + 2-line label + subtitle + gap marker, plus 8px padding top/bottom.
+  test('is tall enough for three lines of content', () => {
+    // technology row + 2-line label + description, plus padding.
     expect(NODE_H).toBeGreaterThanOrEqual(130);
   });
 
-  test('leaves breathing room around four lines of text', () => {
+  test('leaves breathing room around three lines of text', () => {
     // Top-aligned now, not centred, so this is about slack rather than
-    // balance: tag + 2-line label slot + subtitle + gap slot + padding.
-    const contentBudget = 16 + 40 + 16 + 18 + 20; // lines + 10px padding ×2
+    // balance: technology row + 2-line label slot + description + padding.
+    const contentBudget = 16 + 40 + 16 + 20; // lines + 10px padding ×2
     expect(NODE_H - contentBudget).toBeGreaterThanOrEqual(12);
   });
 
@@ -286,16 +310,23 @@ describe('card metrics', () => {
 });
 
 describe('container kinds', () => {
-  test('every container kind renders as a subtitle without special-casing', () => {
-    const kinds = ['application', 'data-store', 'queue'] as const;
-    for (const containerKind of kinds) {
-      expect(nodeSubtitle(node({ containerKind, technology: '' }))).toBe(containerKind);
+  test('each container kind has an icon and a fallback label', () => {
+    for (const containerKind of ['application', 'data-store'] as const) {
+      expect(nodeKindIcon(node({ containerKind }))).toBeDefined();
+      // No technology stated, so the label falls back to the kind.
+      expect(nodeTopLabel(node({ containerKind, technology: '' }))).toBe(containerKind);
     }
   });
 
+  test('application and data-store do not share an icon', () => {
+    expect(nodeKindIcon(node({ containerKind: 'application' }))).not.toBe(
+      nodeKindIcon(node({ containerKind: 'data-store' })),
+    );
+  });
+
   test('a library is not one of them', () => {
     // C4 says a module "typically" is not an element at all, so there is no
     // kind to render. A library-shaped group is a review comment.
-    expect(['application', 'data-store', 'queue']).not.toContain('library');
+    expect(['application', 'data-store']).not.toContain('library');
   });
 });