@principal-ai/subsystems-react 0.24.8 → 0.24.10

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

@@ -0,0 +1,508 @@
+import React from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ReactFlowProvider, type NodeProps } from '@xyflow/react';
+import { ThemeProvider, defaultEditorTheme, useTheme } from '@principal-ade/industry-theme';
+import { FileX, Search, MapPin, Shapes, Sigma } from 'lucide-react';
+import { SubsystemComponentNode } from '../../../subsystem/nodes';
+import type { GraphifyComponentDetail } from '../../../graphify';
+import type { SubsystemComponent, SubsystemGraphNode } from '../../../subsystem/model';
+
+/**
+ * NodeAnatomy — a dissection of the component node's visual language.
+ *
+ * Section 1 lays out every channel the node already spends (border, corners,
+ * left badge, right badge cluster, fill) so an added channel can be chosen
+ * against it. Section 2 shows the *proposed* diagnostics layer (severity ring +
+ * earliest-rung corner chip) composed over real nodes. Nothing here is wired
+ * into the production node yet — this is the reference to design against.
+ */
+const meta = {
+  title: 'Subsystem/ComponentGraph/NodeAnatomy',
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <ReactFlowProvider>
+          <Story />
+        </ReactFlowProvider>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const PURL = 'pkg:github/principal-ai/subsystem-modeling';
+const NODE_W = 230;
+const NODE_H = 84;
+const MONO = 'ui-monospace, SFMono-Regular, Menlo, monospace';
+
+function nodeProps(
+  component: SubsystemComponent,
+  opts?: { selected?: boolean; width?: number; height?: number },
+): NodeProps<SubsystemGraphNode> {
+  return {
+    data: { component },
+    selected: opts?.selected ?? false,
+    width: opts?.width ?? NODE_W,
+    height: opts?.height ?? NODE_H,
+  } as unknown as NodeProps<SubsystemGraphNode>;
+}
+
+// ---------------------------------------------------------------------------
+// Section 1 — the channels the node already spends
+// ---------------------------------------------------------------------------
+
+type Channel = {
+  label: string;
+  note: string;
+  component: SubsystemComponent;
+  selected?: boolean;
+};
+
+const storeDetail: GraphifyComponentDetail = {
+  kind: 'store',
+  storage: 'memory',
+} as GraphifyComponentDetail;
+
+const CHANNELS: Channel[] = [
+  {
+    label: 'baseline — function',
+    note: 'border color = construct (function-indigo); left badge = construct.',
+    component: {
+      id: 'fn',
+      name: 'auditSubsystemModel',
+      construct: 'function',
+      file: 'src/bun/verify-subsystem-component.ts',
+      purl: PURL,
+      symbol: 'auditSubsystemModel',
+    },
+  },
+  {
+    label: 'class',
+    note: 'construct color changes per kind; nothing else moves.',
+    component: {
+      id: 'cls',
+      name: 'MaintainModelAgent',
+      construct: 'class',
+      file: 'src/bun/maintain-model.ts',
+      purl: PURL,
+      symbol: 'MaintainModelAgent',
+    },
+  },
+  {
+    label: 'external',
+    note: 'outside the system — square corners, no file.',
+    component: {
+      id: 'ext',
+      name: '@opencode-ai/cli',
+      construct: 'external',
+      file: '',
+      purl: 'pkg:npm/@opencode-ai/cli',
+      symbol: '',
+    },
+  },
+  {
+    label: 'role badge',
+    note: 'top-right badge = role.',
+    component: {
+      id: 'role',
+      name: 'handleRequest',
+      construct: 'function',
+      file: 'src/bun/http-server.ts',
+      purl: PURL,
+      symbol: 'handleRequest',
+      role: 'entry',
+    },
+  },
+  {
+    label: 'store + storage badge',
+    note: 'store backs a storage badge beside the role badge.',
+    component: {
+      id: 'store',
+      name: 'sessionCache',
+      construct: 'store',
+      file: 'src/bun/session-cache.ts',
+      purl: PURL,
+      symbol: 'sessionCache',
+      declaration: storeDetail,
+    },
+  },
+  {
+    label: 'proposed',
+    note: 'dashed goldenrod border + right badge; fileless.',
+    component: {
+      id: 'prop',
+      name: 'OpenCodeV2Lifecycle',
+      construct: 'function',
+      file: '',
+      purl: PURL,
+      symbol: 'OpenCodeV2Lifecycle',
+      proposed: true,
+    },
+  },
+  {
+    label: 'proposed + role',
+    note: 'proposed wins the right badge; role stays on the model.',
+    component: {
+      id: 'prop-role',
+      name: 'startMaintainFlow',
+      construct: 'function',
+      file: '',
+      purl: PURL,
+      symbol: 'startMaintainFlow',
+      proposed: true,
+      role: 'service',
+    },
+  },
+  {
+    label: 'framework stereotype',
+    note: 'left badge prefers "framework · stereotype"; border stays construct.',
+    component: {
+      id: 'react',
+      name: 'SubsystemComponentNode',
+      construct: 'function',
+      file: 'src/subsystem/nodes.tsx',
+      purl: PURL,
+      symbol: 'SubsystemComponentNode',
+      framework: 'react',
+      stereotype: 'component',
+    },
+  },
+  {
+    label: 'custom entity',
+    note: 'left badge wears the entityKind.',
+    component: {
+      id: 'entity',
+      name: 'WorkRequester',
+      construct: 'custom_entity',
+      file: '',
+      purl: 'external',
+      entityKind: 'Person',
+    },
+  },
+  {
+    label: 'selected',
+    note: 'selection only thickens the border (2 → 4); color stays construct.',
+    component: {
+      id: 'sel',
+      name: 'runMaintainModel',
+      construct: 'function',
+      file: 'src/bun/maintain-model.ts',
+      purl: PURL,
+      symbol: 'runMaintainModel',
+    },
+    selected: true,
+  },
+];
+
+function ChannelCell({ channel }: { channel: Channel }) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 6, width: 280 }}>
+      <div style={{ fontFamily: MONO, fontSize: 11, color: muted, minHeight: 28 }}>
+        {channel.label}
+      </div>
+      <div style={{ position: 'relative', width: NODE_W, height: NODE_H, margin: '14px 0 16px' }}>
+        <SubsystemComponentNode {...nodeProps(channel.component, { selected: channel.selected })} />
+      </div>
+      <div style={{ fontSize: 10, fontFamily: MONO, color: muted, lineHeight: 1.5 }}>
+        {channel.note}
+      </div>
+    </div>
+  );
+}
+
+const LEGEND: Array<[string, string]> = [
+  ['border color', 'construct kind (Pierre palette) — or primary when a file is open (spotlight)'],
+  ['border style', 'solid normally; dashed goldenrod when `proposed`'],
+  ['border width', '2px; 4px when selected or file-matched'],
+  ['corners', '8px rounded; square for `external`'],
+  ['left badge (top edge)', 'construct / framework stereotype / entityKind'],
+  ['right badge (top edge)', 'role, or `proposed` (wins); storage sits beside it'],
+  ['bottom strip (bottom edge)', 'filename — hover only, or while that file is open'],
+  ['fill', 'backgroundSecondary; opacity 0.18 when dimmed'],
+  ['OCCUPIED', 'top-left · top-right · bottom-center · border · fill'],
+  ['FREE', 'an outer ring/halo, and the bottom-left / bottom-right corners'],
+];
+
+/** The node's existing channels, one per cell, with a legend. */
+export const Channels: Story = {
+  render: () => {
+    return (
+      <div style={{ padding: 32, minHeight: '100vh', boxSizing: 'border-box' }}>
+        <Legend />
+        <div
+          style={{
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '40px 28px',
+            alignItems: 'flex-start',
+            marginTop: 28,
+          }}
+        >
+          {CHANNELS.map((c) => (
+            <ChannelCell key={c.component.id} channel={c} />
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+function Legend() {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  return (
+    <div style={{ maxWidth: 720 }}>
+      <div
+        style={{
+          fontSize: 12,
+          fontFamily: MONO,
+          textTransform: 'uppercase',
+          letterSpacing: 0.4,
+          color: muted,
+          marginBottom: 10,
+        }}
+      >
+        Channel legend
+      </div>
+      <div style={{ display: 'grid', gridTemplateColumns: '180px 1fr', rowGap: 4, columnGap: 12 }}>
+        {LEGEND.map(([k, v]) => (
+          <React.Fragment key={k}>
+            <span style={{ fontFamily: MONO, fontSize: 11, color: theme.colors.text }}>{k}</span>
+            <span style={{ fontSize: 11, color: muted, lineHeight: 1.5 }}>{v}</span>
+          </React.Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Section 2 — proposed diagnostics layer: severity ring + earliest-rung chip
+// ---------------------------------------------------------------------------
+
+type Severity = 'error' | 'warn' | 'info';
+type Rung = 'file' | 'symbol' | 'declaration' | 'type' | 'signature';
+
+const RUNG_ICON = {
+  file: FileX,
+  symbol: Search,
+  declaration: MapPin,
+  type: Shapes,
+  signature: Sigma,
+} as const;
+
+const RUNG_LABEL: Record<Rung, string> = {
+  file: 'file',
+  symbol: 'symbol',
+  declaration: 'declaration',
+  type: 'type',
+  signature: 'signature',
+};
+
+function IssueOverlayNode({
+  component,
+  severity,
+  rung,
+  count = 1,
+}: {
+  component: SubsystemComponent;
+  severity: Severity;
+  rung: Rung;
+  count?: number;
+}) {
+  const { theme } = useTheme();
+  const color =
+    severity === 'error'
+      ? (theme.colors.error ?? '#e5534b')
+      : severity === 'warn'
+        ? (theme.colors.warning ?? '#d4a017')
+        : (theme.colors.info ?? '#0893d2');
+  // Gaps (info) read hollow/dashed — "couldn't confirm"; errors/warns solid.
+  const dashed = severity === 'info';
+  const Icon = RUNG_ICON[rung];
+  const badgeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
+  return (
+    <div style={{ position: 'relative', width: NODE_W, height: NODE_H }}>
+      <SubsystemComponentNode {...nodeProps(component)} />
+      {/* severity ring — additive, outside the construct-colored border */}
+      <div
+        style={{
+          position: 'absolute',
+          inset: -5,
+          borderRadius: 11,
+          border: `2px ${dashed ? 'dashed' : 'solid'} ${color}`,
+          pointerEvents: 'none',
+        }}
+      />
+      {/* earliest-rung corner chip + count */}
+      <div
+        style={{
+          position: 'absolute',
+          right: -8,
+          bottom: -7,
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 3,
+          padding: '1px 6px',
+          borderRadius: 999,
+          border: `1.5px solid ${color}`,
+          background: badgeBg,
+          color,
+          fontFamily: MONO,
+          fontSize: 10,
+          fontWeight: 600,
+          lineHeight: 1.4,
+        }}
+      >
+        <Icon size={11} color={color} />
+        {count > 1 ? <span>{count}</span> : null}
+      </div>
+    </div>
+  );
+}
+
+function IssueCell({
+  caption,
+  clean,
+  ...node
+}: {
+  caption: string;
+  component: SubsystemComponent;
+  severity: Severity;
+  rung: Rung;
+  count?: number;
+  clean?: boolean;
+}) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 6, width: 280 }}>
+      <div style={{ fontFamily: MONO, fontSize: 11, color: muted, minHeight: 28 }}>{caption}</div>
+      <div style={{ position: 'relative', width: NODE_W, height: NODE_H, margin: '16px 0 18px' }}>
+        {clean ? (
+          <SubsystemComponentNode {...nodeProps(node.component)} />
+        ) : (
+          <IssueOverlayNode
+            component={node.component}
+            severity={node.severity}
+            rung={node.rung}
+            count={node.count}
+          />
+        )}
+      </div>
+      <div style={{ fontSize: 10, fontFamily: MONO, color: muted }}>
+        {clean
+          ? 'no issues'
+          : `${node.severity} · ${RUNG_LABEL[node.rung]}${
+              node.count && node.count > 1 ? ` · ${node.count} issues` : ''
+            }`}
+      </div>
+    </div>
+  );
+}
+
+const ISSUE_EXAMPLES: Array<{
+  caption: string;
+  component: SubsystemComponent;
+  severity: Severity;
+  rung: Rung;
+  count?: number;
+  clean?: boolean;
+}> = [
+  {
+    caption: 'clean node — no ring, no chip',
+    component: CHANNELS[0]!.component,
+    severity: 'error',
+    rung: 'file',
+    clean: true,
+  },
+  {
+    caption: 'error · earliest rung is file (declaration file missing)',
+    component: { ...CHANNELS[0]!.component, id: 'e-file' },
+    severity: 'error',
+    rung: 'file',
+    count: 2,
+  },
+  {
+    caption: 'warn · earliest rung is symbol (multiple symbol matches)',
+    component: { ...CHANNELS[1]!.component, id: 'e-sym' },
+    severity: 'warn',
+    rung: 'symbol',
+  },
+  {
+    caption: 'info/gap · dashed ring · declaration drift',
+    component: { ...CHANNELS[1]!.component, id: 'e-decl' },
+    severity: 'info',
+    rung: 'declaration',
+  },
+  {
+    caption: 'error · type mismatch',
+    component: { ...CHANNELS[7]!.component, id: 'e-type' },
+    severity: 'error',
+    rung: 'type',
+  },
+  {
+    caption: 'error · signature mismatch (deepest rung)',
+    component: { ...CHANNELS[0]!.component, id: 'e-sig' },
+    severity: 'error',
+    rung: 'signature',
+  },
+];
+
+/** Proposed diagnostics layer over real nodes — ring by severity, chip = earliest rung. */
+export const IssueOverlayProposal: Story = {
+  render: () => {
+    return (
+      <div style={{ padding: 32, minHeight: '100vh', boxSizing: 'border-box' }}>
+        <div style={{ maxWidth: 720 }}>
+          <div
+            style={{
+              fontSize: 12,
+              fontFamily: MONO,
+              textTransform: 'uppercase',
+              letterSpacing: 0.4,
+              color: '#a0a0a0',
+              marginBottom: 10,
+            }}
+          >
+            Proposed · not wired yet
+          </div>
+          <ul style={{ margin: 0, paddingLeft: 18, fontSize: 12, lineHeight: 1.7, color: '#b0b0b0' }}>
+            <li>
+              <b>Ring</b> (outside the construct border): <b>solid</b> = error/warn (contradicts
+              source), <b>dashed</b> = info/gap (couldn&apos;t confirm). Color = severity.
+            </li>
+            <li>
+              <b>Corner chip</b> = the <i>earliest failing rung</i> by verification order (file →
+              symbol → declaration → type → signature), with a count when a node has more than one.
+            </li>
+            <li>
+              First cell is the clean node for contrast — no ring, no chip. Compose with selection,
+              file-open spotlight, and dimming without touching the border.
+            </li>
+          </ul>
+        </div>
+        <div
+          style={{
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '40px 28px',
+            alignItems: 'flex-start',
+            marginTop: 28,
+          }}
+        >
+          {ISSUE_EXAMPLES.map((ex) => (
+            <IssueCell key={ex.caption} {...ex} />
+          ))}
+        </div>
+      </div>
+    );
+  },
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -511,69 +511,91 @@ export function ComponentDeclaration({
 
   if (showFile && component.file) {
     const fileInteractive = !!onOpenFile;
+    const segBorder =
+      fileHovered && fileInteractive
+        ? theme.colors.accent ?? color
+        : theme.colors.border;
+    const openAt = fileInteractive
+      ? (e: { stopPropagation: () => void }) => {
+          e.stopPropagation();
+          openDeclarationFile();
+        }
+      : undefined;
     lines.push(
       line(
         <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
           <span
-            role={fileInteractive ? 'button' : undefined}
-            tabIndex={fileInteractive ? 0 : undefined}
-            title={fileInteractive ? `Open ${component.file}` : component.file}
             onMouseEnter={() => setFileHovered(true)}
             onMouseLeave={() => setFileHovered(false)}
-            onClick={
-              fileInteractive
-                ? (e) => {
-                    e.stopPropagation();
-                    openDeclarationFile();
-                  }
-                : undefined
-            }
             style={{
               display: 'inline-flex',
-              alignItems: 'center',
-              padding: '1px 8px',
+              alignItems: 'stretch',
               borderRadius: 6,
-              border: `1px solid ${
-                fileHovered && fileInteractive
-                  ? theme.colors.accent ?? color
-                  : theme.colors.border
-              }`,
+              overflow: 'hidden',
+              border: `1px solid ${segBorder}`,
               background: theme.colors.backgroundSecondary ?? 'transparent',
-              color:
-                fileHovered && fileInteractive
-                  ? theme.colors.text
-                  : theme.colors.textSecondary ?? muted,
-              fontFamily: theme.fonts.monospace,
-              fontSize: theme.fontSizes[0],
               whiteSpace: 'nowrap',
-              cursor: fileInteractive ? 'pointer' : 'default',
             }}
           >
-            {component.file}
-          </span>
-          {fileOpen && (
             <span
-              title="This file is open below"
+              role={fileInteractive ? 'button' : undefined}
+              tabIndex={fileInteractive ? 0 : undefined}
+              title={fileInteractive ? `Open ${component.file}` : component.file}
+              onClick={openAt}
               style={{
                 display: 'inline-flex',
                 alignItems: 'center',
-                gap: 4,
-                height: 16,
-                padding: '0 5px',
-                border: `1px solid ${theme.colors.accent ?? color}`,
-                borderRadius: 999,
-                color: theme.colors.accent ?? color,
+                padding: '1px 8px',
+                color:
+                  fileHovered && fileInteractive
+                    ? theme.colors.text
+                    : theme.colors.textSecondary ?? muted,
                 fontFamily: theme.fonts.monospace,
-                fontSize: theme.fontSizes[0] * 0.8,
-                letterSpacing: 0.4,
-                textTransform: 'uppercase',
-                whiteSpace: 'nowrap',
+                fontSize: theme.fontSizes[0],
+                cursor: fileInteractive ? 'pointer' : 'default',
               }}
             >
-              open
+              {component.file}
             </span>
-          )}
-          {lineLocationLabel}
+            {declarationStartLine != null && (
+              <span
+                role={fileInteractive ? 'button' : undefined}
+                tabIndex={fileInteractive ? 0 : undefined}
+                title="Open at declaration line"
+                onClick={openAt}
+                style={{
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  padding: '1px 6px',
+                  borderLeft: `1px solid ${segBorder}`,
+                  color: theme.colors.accent ?? color,
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  cursor: fileInteractive ? 'pointer' : 'default',
+                }}
+              >
+                L{declarationStartLine}
+              </span>
+            )}
+            {fileOpen && (
+              <span
+                title="This file is open below"
+                style={{
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  padding: '1px 6px',
+                  borderLeft: `1px solid ${segBorder}`,
+                  color: theme.colors.accent ?? color,
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0] * 0.85,
+                  letterSpacing: 0.4,
+                  textTransform: 'uppercase',
+                }}
+              >
+                open
+              </span>
+            )}
+          </span>
         </span>,
         'file',
       ),