@principal-ai/subsystems-react 0.37.12 → 0.39.0

package/src/subsystem/nodes.group.test.tsx

@@ -62,3 +62,55 @@ describe('SubsystemGroupNode frame color', () => {
     expect(frame.style.border).toContain('#ff6b35');
   });
 });
+
+describe('SubsystemGroupNode boundary badge', () => {
+  // A boundary finding is a property of the region's shape, so it badges the
+  // frame with its own icon rather than borrowing the verification-rung chips
+  // that leaf constructs wear.
+  const moduleRegion = {
+    kind: 'module' as const,
+    key: 'src/bun/index.ts',
+    label: 'src/bun/index.ts',
+    memberAliases: ['a', 'b', 'c'],
+  };
+
+  test('a boundary finding badges the frame with its own icon', () => {
+    const { container } = renderGroup({
+      region: moduleRegion,
+      issue: {
+        severity: 'info',
+        kind: 'boundary_process_nest_disagree',
+        count: 1,
+      },
+    });
+    // The chip is aria-hidden and inert; its lucide icon carries the class.
+    expect(container.querySelector('.lucide-split')).not.toBeNull();
+  });
+
+  test('a finding with no dedicated frame icon is not badged', () => {
+    // `construct_unconfirmed` belongs on a leaf node, not the frame — badging
+    // the region with it would imply the region is at fault.
+    const { container } = renderGroup({
+      region: moduleRegion,
+      issue: { severity: 'error', kind: 'construct_unconfirmed', count: 1 },
+    });
+    expect(container.querySelector('svg')).toBeNull();
+  });
+
+  test('a region with no findings renders no chip', () => {
+    const { container } = renderGroup({ region: moduleRegion });
+    expect(container.querySelector('svg')).toBeNull();
+  });
+
+  test('the chip shows a count when the region has more than one finding', () => {
+    const { container } = renderGroup({
+      region: moduleRegion,
+      issue: {
+        severity: 'error',
+        kind: 'boundary_process_nest_disagree',
+        count: 3,
+      },
+    });
+    expect(container.textContent).toContain('3');
+  });
+});

package/src/subsystem/nodes.tsx

@@ -17,8 +17,8 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
-  MECHANISM_COLOR,
-  MECHANISM_STYLE,
+  edgeColor,
+  edgeStrokeStyle,
   PROPOSED_COLOR,
   constructBadgeColor,
   constructBadgeLabel,
@@ -36,9 +36,12 @@ import {
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
+  type SubsystemNodeIssue,
 } from './model';
 import { componentColor } from '../pierre/constructColors';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+import { ISSUE_KIND_ICON, ISSUE_RUNG_ICON } from './IssueList';
+import type { LucideIcon } from 'lucide-react';
 
 export const CONSTRUCT_LABEL: Record<string, string> = {
   class: 'class',
@@ -112,6 +115,80 @@ function useSubsystemCallbacks(): SubsystemGraphCallbacks {
   return useContext(SubsystemCallbacksContext) ?? SUBSYSTEM_CALLBACKS;
 }
 
+/**
+ * The diagnostics overlay for a component node: the node's own border turns
+ * dotted (see the node's `borderStyle`) and an earliest-failing-rung corner
+ * chip (file → symbol → declaration → type → signature) carries the severity
+ * color, with a count when the node has more than one finding. The chip is
+ * purely additive and non-interactive; the border stays construct-colored, so
+ * severity never has to compete with the construct palette.
+ */
+function NodeIssueOverlay({ issue }: { issue: SubsystemNodeIssue }) {
+  const { theme } = useTheme();
+  const isError = issue.severity === 'error';
+  const color = isError
+    ? (theme.colors.error ?? '#e5534b')
+    : (theme.colors.warning ?? '#d4a017');
+  return (
+    <IssueChip
+      color={color}
+      Icon={ISSUE_RUNG_ICON[issue.rung]}
+      count={issue.count}
+      anchor={{ right: -9, bottom: -8 }}
+    />
+  );
+}
+
+/**
+ * The shared severity chip: a severity-colored ring around the finding's icon,
+ * with a count when there is more than one. Component nodes anchor it to the
+ * bottom-right corner; a region frame anchors it to the top-right so it never
+ * collides with the frame's own name badge. `aria-hidden` and inert — the
+ * canvas badge never competes with the sidebar card for the interaction.
+ */
+function IssueChip({
+  color,
+  Icon,
+  count,
+  anchor,
+}: {
+  color: string;
+  Icon: LucideIcon;
+  count: number;
+  anchor: React.CSSProperties;
+}) {
+  const { theme } = useTheme();
+  const badgeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: 'absolute',
+        zIndex: 2,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 4,
+        minWidth: 22,
+        padding: '3px 5px',
+        borderRadius: 5,
+        border: `2px solid ${color}`,
+        background: badgeBg,
+        color,
+        fontFamily: theme.fonts.monospace,
+        fontSize: theme.fontSizes[1],
+        fontWeight: 700,
+        lineHeight: 1.1,
+        pointerEvents: 'none',
+        ...anchor,
+      }}
+    >
+      <Icon size={14} color={color} />
+      {count > 1 ? <span>{count}</span> : null}
+    </div>
+  );
+}
+
 export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeData, 'subsystem-component'>>) {
   const { theme, mode } = useTheme();
   const callbacks = useSubsystemCallbacks();
@@ -168,6 +245,12 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const borderW = isSelected || fileMatch ? 4 : 2;
   const badgeTop = -9 - borderW;
   const badgeEdge = -borderW;
+  // A node with diagnostics turns its border dotted — a "something's off"
+  // sibling of `proposed`'s dashed, but distinct so the two don't read alike.
+  // The border keeps its construct color; the severity rides on the chip.
+  // Verification skips `proposed` nodes, so the two rarely stack — issue wins.
+  const hasIssue = data.issue != null;
+  const borderStyle = hasIssue ? 'dotted' : c.proposed ? 'dashed' : 'solid';
 
   return (
     <div
@@ -198,8 +281,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         borderRadius: nodeRadius,
         background: hover ? hoverBg : nodeBg,
         // Selected / file-matched nodes get a thicker border. Proposed nodes
-        // use a dashed goldenrod border; left construct badge keeps construct color.
-        border: `${borderW}px ${c.proposed ? 'dashed' : 'solid'} ${borderColor}`,
+        // use a dashed goldenrod border, issue nodes a dotted construct-colored
+        // one; the left construct badge keeps construct color either way.
+        border: `${borderW}px ${borderStyle} ${borderColor}`,
         boxShadow: fileMatch
           ? `0 1px 4px rgba(0,0,0,0.25), 0 0 12px ${theme.colors.primary}55`
           : '0 1px 4px rgba(0,0,0,0.25)',
@@ -339,6 +423,8 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         </div>
       )}
 
+      {data.issue && <NodeIssueOverlay issue={data.issue} />}
+
       <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
       <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
     </div>
@@ -494,6 +580,20 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           label
         )}
       </div>
+      {/* Boundary diagnostics badge — top-right, opposite the name badge, so the
+          two never collide however long the module path grows. */}
+      {data.issue && ISSUE_KIND_ICON[data.issue.kind] && (
+        <IssueChip
+          color={
+            data.issue.severity === 'error'
+              ? (theme.colors.error ?? '#e5534b')
+              : (theme.colors.warning ?? '#d4a017')
+          }
+          Icon={ISSUE_KIND_ICON[data.issue.kind]!}
+          count={data.issue.count}
+          anchor={{ right: 12, top: 0, transform: 'translateY(-50%)' }}
+        />
+      )}
     </div>
   );
 }
@@ -560,10 +660,14 @@ export function SubsystemEdge({
 }: EdgeProps<SubsystemGraphEdge>) {
   const path = data?.elkPath ?? '';
   const mechanism = data?.mechanism ?? 'uses';
-  const color = MECHANISM_COLOR[mechanism] ?? '#888';
-  // Dash style comes from the mechanism table (dashed = inverted-control or
-  // observational relationships: hierarchy, registration, watches).
-  const isDashed = MECHANISM_STYLE[mechanism] === 'dashed';
+  // Color + dash resolve from provenance: subsystem mechanisms use the
+  // MECHANISM_* tables, graphify-native relations use the separate
+  // GRAPHIFY_RELATION_* palette (see edgeColor / edgeStrokeStyle).
+  const edgeRef = { mechanism, provenance: data?.provenance };
+  const color = edgeColor(edgeRef);
+  // Dash style encodes provenance (graphify) and relationship kind (dashed =
+  // inverted-control or observational: hierarchy, registration, watches).
+  const isDashed = edgeStrokeStyle(edgeRef) === 'dashed';
   const dimmed = data?.dimmed === true;
   // Dim the stroke by color, never via path `opacity`. SVG markers are shared
   // by id; opacity on the referencing path paints every arrowhead that uses

package/src/subsystem/symbolRefs.ts

@@ -335,6 +335,8 @@ export function extractDeclarationSymbolRefs(
       for (const alt of declaration.unionOf ?? []) addType(alt, undefined, 'union');
       break;
     case 'store':
+      // The store's own value type (`valueTypeRef`), then its members.
+      addType(declaration.valueType, declaration.valueTypeRef, 'field');
       for (const p of declaration.properties ?? []) {
         addType(p.type, p.typeRef, 'field');
       }

package/src/subsystem/toC4.test.ts

@@ -20,9 +20,9 @@ const doc: SubsystemModelDocument = {
   ],
   relations: [
     { id: 'r1', from: 'a', to: 'b', relationType: 'method' }, // intra p1
-    { id: 'r2', from: 'a', to: 'c', relationType: 'references' },
-    { id: 'r3', from: 'b', to: 'c', relationType: 'references' },
-    { id: 'r4', from: 'a', to: 'x', relationType: 'references' },
+    { id: 'r2', from: 'a', to: 'c', relationType: 'method' },
+    { id: 'r3', from: 'b', to: 'c', relationType: 'method' },
+    { id: 'r4', from: 'a', to: 'x', relationType: 'method' },
   ],
   walkthroughs: [
     {

package/src/utils/elkLayout.ts

@@ -84,6 +84,16 @@ export interface ElkLayoutOptions {
    */
   direction?: 'RIGHT' | 'LEFT' | 'DOWN' | 'UP';
 
+  /**
+   * Order same-layer nodes by their source line (ascending) instead of leaving
+   * it to the crossing-minimizer. Nodes must carry a `data.component.line`
+   * (used when set; nodes without one keep ELK's neutral ordering). Off by
+   * default — the generic layered layout is tuned for crossings, and line order
+   * only makes sense for graphs that model a source region top-to-bottom.
+   * @default false
+   */
+  orderByLine?: boolean;
+
   /**
    * Compound groups — each becomes an ELK parent whose `memberIds` are laid
    * out inside it. `memberIds` may be leaf node ids or other group ids
@@ -323,11 +333,15 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     interLayerSpacing = 0,
     edgeLabels,
     direction = 'RIGHT',
+    orderByLine = false,
   } = options;
 
   const baseOptions: LayoutOptions = {
     'elk.algorithm': 'layered',
     'elk.direction': direction,
+    // Keep same-layer ordering stable (not reversed / randomized) so a
+    // line-ordered rewrite or ELK's own ordering is predictable.
+    'elk.layered.crossingMinimization.semiInteractive': 'true',
     // Spacing
     'elk.spacing.nodeNode': String(nodeSpacing),
     'elk.spacing.edgeEdge': String(edgeSpacing),
@@ -346,6 +360,14 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
     'elk.layered.thoroughness': '50',
   };
 
+  // Model order (position hints) so a per-node `data.line` can drive same-layer
+  // ordering. ELK honours the `y` of each node as a position hint against the
+  // model order.
+  if (orderByLine) {
+    baseOptions['elk.layered.fixedAlignment'] = 'NONE';
+    baseOptions['elk.layered.considerModelOrder.strategy'] = 'NODES_AND_EDGES';
+  }
+
   // Reserve space for inline edge labels so they don't overlap nodes/edges.
   if (edgeLabels?.enabled !== false) {
     const placement = edgeLabels?.placement ?? 'CENTER';
@@ -507,6 +529,7 @@ export async function computeElkLayout(
   const edgeLabels = options.edgeLabels;
   const endpointInset = options.endpointInset ?? 0;
   const direction = options.direction ?? 'RIGHT';
+  const orderByLine = options.orderByLine ?? false;
 
   // Build a map of original node positions BEFORE passing to ELK
   // (ELK mutates the input nodes in place, so we must save positions first)
@@ -527,12 +550,20 @@ export async function computeElkLayout(
     const nd = node.data as { component?: { layer?: number }; layer?: number } | undefined;
     layer = nd?.layer ?? nd?.component?.layer;
 
+    // Optional source-line ordering: seed each node's `y` hint from its line so
+    // ELK's model-order placement puts lower lines further down within a layer.
+    let y = node.position.y;
+    if (orderByLine) {
+      const line = (node.data as { component?: { line?: number } } | undefined)?.component?.line;
+      if (typeof line === 'number') y = line;
+    }
+
     return {
       id: node.id,
       width,
       height,
       x: node.position.x,
-      y: node.position.y,
+      y,
       // Add ports on each side for edge connections
       ports: [
         { id: `${node.id}_top`, properties: { 'port.side': 'NORTH' } },