@principal-ai/subsystems-react 0.38.0 → 0.40.0

package/src/subsystem/formatDeclaration.test.ts

@@ -2,6 +2,70 @@ import { describe, expect, test } from 'bun:test';
 import { generateDeclarationString, resolveComponentDeclaration } from './formatDeclaration';
 import type { SubsystemComponent } from './model';
 
+describe('generateDeclarationString — store', () => {
+  const base: Omit<SubsystemComponent, 'declaration'> = {
+    id: 'st',
+    name: 'feeds',
+    construct: 'store',
+    symbol: 'feeds',
+    file: 'src/live.ts',
+    purl: 'pkg:github/acme/app',
+  };
+
+  test('renders a declared valueType as the store signature', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        properties: [],
+        valueType: 'Map<string, OpencodeLiveFeedState>',
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — Map<string, OpencodeLiveFeedState>\n// backing: memory',
+    );
+  });
+
+  test('named members render as a body under the valueType', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        valueType: 'Map<string, { width: number }>',
+        properties: [{ name: 'current', type: 'Map<string, { width: number }>' }],
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — Map<string, { width: number }>\n// backing: memory\n  current: Map<string, { width: number }>;',
+    );
+  });
+
+  test('members without a valueType still render as declare const lines', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        properties: [{ name: 'ROOT', type: 'string' }],
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds\ndeclare const ROOT: string;',
+    );
+  });
+
+  test('a store with neither valueType nor members says so explicitly', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: { kind: 'store', storage: 'memory', properties: [] },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — no declared type (no valueType or state members)\n// backing: memory',
+    );
+  });
+});
+
 describe('generateDeclarationString — custom_entity', () => {
   test('renders entity identity + entityKind, no attributes when none authored', () => {
     const component: SubsystemComponent = {

package/src/subsystem/formatDeclaration.ts

@@ -223,19 +223,34 @@ function generateType(
 }
 
 /**
- * A store renders as its retained state — ambient `declare const` lines for
- * the state members, never a class/method stub. The node's name labels the
- * block; the access mechanism lives in separate accessor nodes.
+ * A store renders as its retained state — the declaration of what it holds,
+ * the way every other construct renders its signature. The node's name labels
+ * the block; the access mechanism lives in separate accessor nodes.
+ *
+ * Order: the backing comment, then the store's own typed declaration
+ * (`valueType` when declared, otherwise the named members as a body), then any
+ * remaining members. A store that declares neither says so explicitly rather
+ * than rendering as an empty block.
  */
 function generateStore(name: string, declaration?: GraphifyComponentDetail): string {
   const store = declaration?.kind === 'store' ? declaration : undefined;
   const backing = store?.storage ? `\n// backing: ${store.storage}` : '';
-  const props = (store?.properties ?? [])
+  const members = store?.properties ?? [];
+  const props = members
     .map((p) => `declare const ${p.name}${p.type ? `: ${p.type}` : ''};`)
     .join('\n');
 
+  if (store?.valueType) {
+    const named = members.length
+      ? `\n${members
+          .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
+          .join('\n')}`
+      : '';
+    return `// store: ${name} — ${store.valueType}${backing}${named}`;
+  }
+
   if (!props) {
-    return `// store: ${name} — no captured state members${backing}`;
+    return `// store: ${name} — no declared type (no valueType or state members)${backing}`;
   }
   return `// store: ${name}${backing}\n${props}`;
 }

package/src/subsystem/model.ts

@@ -1038,6 +1038,50 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
   fileMatch?: boolean;
   /** True while this node is on an opened-but-unselected flow. */
   dimmed?: boolean;
+  /** Diagnostics badge — see `SubsystemNodeIssue`. Absent when no findings. */
+  issue?: SubsystemNodeIssue;
+}
+
+/**
+ * The per-construct verification ladder, in order. A finding's rung is the
+ * earliest step it fails: file → symbol → declaration → type → signature.
+ */
+export type SubsystemIssueRung =
+  | 'file'
+  | 'symbol'
+  | 'declaration'
+  | 'type'
+  | 'signature';
+
+/**
+ * Per-node diagnostics badge — the proposed issue overlay (severity ring +
+ * earliest-rung corner chip). The graph derives one per component from the
+ * audit issues whose component target resolves to that node. Absent when the
+ * node has no rung-mapped findings.
+ */
+export interface SubsystemNodeIssue {
+  /** Worst severity on the node — `error` (contradicts source) beats `info`. */
+  severity: 'error' | 'info';
+  /** Earliest failing rung across the node's findings. */
+  rung: SubsystemIssueRung;
+  /** Total findings on this node. */
+  count: number;
+}
+
+/**
+ * Per-frame diagnostics badge — a finding about the BOUNDARY itself (its
+ * containment / nesting), not about any member construct. Separate from
+ * `SubsystemNodeIssue` because these have no construct rung to report: the
+ * fault is the region's shape, which is also why it badges the frame rather
+ * than a leaf. `kind` selects the icon (see `ISSUE_KIND_ICON`).
+ */
+export interface SubsystemRegionIssue {
+  /** Worst severity across the region's findings — `error` beats `info`. */
+  severity: 'error' | 'info';
+  /** The kind that supplies the badge icon. */
+  kind: string;
+  /** Total findings on this region. */
+  count: number;
 }
 
 export interface SubsystemGroupNodeData extends Record<string, unknown> {
@@ -1046,6 +1090,8 @@ export interface SubsystemGroupNodeData extends Record<string, unknown> {
   dimmed?: boolean;
   /** Host-supplied frame color override; falls back to the derived color. */
   color?: string;
+  /** Boundary diagnostics badge — see `SubsystemRegionIssue`. */
+  issue?: SubsystemRegionIssue;
 }
 
 export type SubsystemGraphNode =

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

@@ -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>
   );
 }

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');
       }