@principal-ai/subsystems-react 0.49.0 → 0.51.0

package/src/stories/Subsystem/C4Graph/C4NodeGallery.stories.tsx

@@ -0,0 +1,325 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme, useTheme } from '@principal-ade/industry-theme';
+import { C4NodeCard, nodeStyle, nodeSubtitle, nodeTag, nodeMissing, NODE_W } from '../../../subsystem/C4NodeCard';
+import type { C4Node, C4ElementType } from '../../../subsystem/toC4';
+
+// ---------------------------------------------------------------------------
+// A card gallery: every C4 box variant, outside the graph.
+//
+// The graph answers "what does this system look like". This answers "what does
+// a box MEAN" — which encoding maps to which C4 concept, and which gaps the
+// notation still wants filled.
+//
+// Rendering the card directly (not through React Flow) is the point: the node
+// is a plain presentational component, so it can be reviewed and diffed
+// without a layout engine in the way.
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4NodeGallery',
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// --- sample nodes ---------------------------------------------------------
+
+function node(over: Partial<C4Node> & { id: string; label: string }): C4Node {
+  return {
+    kind: 'container',
+    members: [],
+    constructs: [],
+    isStore: false,
+    ...over,
+  };
+}
+
+const CONFIRMED = {
+  id: 'container:studio-host',
+  label: 'Studio Host',
+  type: 'application' as C4ElementType,
+  technology: 'Bun + Electrobun',
+  description: 'Runs the audit pipeline, owns the model store, serves the RPC surface.',
+  state: 'accepted' as const,
+};
+
+const VARIANTS: Array<{ group: string; note: string; node: C4Node }> = [
+  // `id` on each variant is its caption key, not a component field.
+  // --- confirmation state: the axis that matters most --------------------
+  {
+    group: 'Confirmation state',
+    note: 'The whole point of the association layer. Solid = a person signed off. Dashed = an agent asked, nobody answered. Muted = raw derivation, never reviewed.',
+    node: node({
+      id: 'a1',
+      label: 'subsystems-studio/host',
+      key: 'subsystems-studio/host',
+      members: ['a', 'b', 'c'],
+      constructs: ['function', 'store'],
+      decoration: CONFIRMED,
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'a2',
+      label: 'subsystems-core/types',
+      key: 'subsystems-core/types',
+      members: ['x', 'y'],
+      constructs: ['interface', 'type_alias'],
+      decoration: {
+        id: 'container:subsystems-core/types',
+        label: 'subsystems-core/types',
+        type: 'library',
+        state: 'proposed',
+      },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'a3',
+      label: 'principal-studio-cli',
+      key: 'principal-studio-cli',
+      members: ['cli-create'],
+      constructs: ['function'],
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'a4',
+      label: 'graphify/extract',
+      key: 'graphify/extract',
+      members: ['extract'],
+      constructs: ['function'],
+      decoration: {
+        id: 'container:graphify/extract',
+        label: 'graphify/extract',
+        type: 'application',
+        state: 'rejected',
+      },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({ id: 'a5', label: 'Studio Host', key: 'p1 + p2', sourceKeys: ['p1', 'p2'], members: ['a'], constructs: ['function'], decoration: CONFIRMED }),
+  },
+
+  // --- C4 element type ----------------------------------------------------
+  {
+    group: 'C4 element type',
+    note: 'C4 requires a type on every element. The document has no such field, so this is always a confirmation.',
+    node: node({
+      id: 'b1',
+      label: 'Subsystem model store',
+      members: ['s1'],
+      constructs: ['store'],
+      decoration: { id: 'container:ds', label: 'Subsystem model store', type: 'data-store', technology: 'JSON files on disk', state: 'accepted', description: 'Every stored model plus its index.' },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'b2',
+      label: 'Audit correction queue',
+      members: ['s2'],
+      constructs: ['store'],
+      decoration: { id: 'container:q', label: 'Audit correction queue', type: 'queue', technology: 'agent session transport', state: 'accepted', description: 'Proposals awaiting a human decision.' },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'b3',
+      label: 'subsystems-core',
+      members: ['i1', 'i2'],
+      constructs: ['interface', 'function'],
+      decoration: { id: 'container:lib', label: 'subsystems-core', type: 'library', technology: 'TypeScript', state: 'accepted', description: 'Schema and validation. Not a deployable unit.' },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'b4',
+      label: 'OpenCode v2 service',
+      kind: 'external',
+      members: ['oc2'],
+      constructs: ['external'],
+      decoration: { id: 'external:oc2', label: 'OpenCode v2 service', type: 'software-system', technology: 'HTTP', state: 'accepted', description: 'Runs maintain agent sessions.' },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'b5',
+      label: 'Maintain operator',
+      kind: 'actor',
+      members: ['a'],
+      constructs: ['custom_entity'],
+      decoration: { id: 'actor:a', label: 'Maintain operator', type: 'person', state: 'proposed', description: 'Reviews and accepts correction proposals.' },
+    }),
+  },
+
+  // --- the gaps C4 keeps asking about ------------------------------------
+  {
+    group: 'Notation gaps',
+    note: 'C4 requires technology and description on every container. A confirmed box that never got either says so on its face rather than looking finished.',
+    node: node({
+      id: 'c1',
+      label: 'site/web',
+      key: 'site/web',
+      members: ['w1', 'w2', 'w3'],
+      constructs: ['function'],
+      decoration: { id: 'container:site/web', label: 'site/web', type: 'application', state: 'accepted' },
+    }),
+  },
+  {
+    group: '',
+    note: '',
+    node: node({
+      id: 'c2',
+      label: 'subsystems-studio/renderer',
+      key: 'subsystems-studio/renderer',
+      members: ['r1', 'r2'],
+      constructs: ['function'],
+      decoration: { id: 'container:renderer', label: 'subsystems-studio/renderer', type: 'application', technology: 'React', state: 'accepted' },
+    }),
+  },
+
+  // --- component level ---------------------------------------------------
+  {
+    group: 'Component level',
+    note: 'Same card, one level down. A component has no type requirement — it inherits from its container.',
+    node: node({
+      id: 'd1',
+      label: 'buildBoundaryLayoutGroups',
+      kind: 'component',
+      members: ['b1'],
+      constructs: ['function'],
+      component: { alias: 'b1', name: 'buildBoundaryLayoutGroups', construct: 'function', file: 'src/subsystem/model.ts', purl: 'pkg:x#src/subsystem/model.ts' },
+    }),
+  },
+];
+
+function Section({ title, note }: { title?: string; note?: string }) {
+  if (!title) return null;
+  return (
+    <div style={{ marginBottom: 10, maxWidth: 720 }}>
+      <h2 style={{ margin: '0 0 3px', fontSize: 15, color: '#e8e8ea' }}>{title}</h2>
+      {note ? <p style={{ margin: 0, fontSize: 12, lineHeight: 1.45, color: '#9a9aa0' }}>{note}</p> : null}
+    </div>
+  );
+}
+
+function Row({ children }: { children: React.ReactNode }) {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 14, alignItems: 'flex-start', marginBottom: 6 }}>
+      {children}
+    </div>
+  );
+}
+
+/** Label under a card, so a reviewer can name the case they are looking at. */
+function Case({ caption, children }: { caption: string; children: React.ReactNode }) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 5, alignItems: 'flex-start' }}>
+      {children}
+      <span
+        style={{
+          fontFamily: 'monospace',
+          fontSize: 10,
+          lineHeight: 1.4,
+          color: '#6a6a70',
+          width: NODE_W,
+        }}
+      >
+        {caption}
+      </span>
+    </div>
+  );
+}
+
+function Gallery() {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? '#9a9aa0';
+
+  const legend: Array<[string, string]> = [
+    ['accepted', nodeStyle({ id: 'x', kind: 'container', label: '', members: [], constructs: [], isStore: false, decoration: CONFIRMED } as C4Node, theme).color],
+    ['proposed', nodeStyle({ id: 'x', kind: 'container', label: '', members: [], constructs: [], isStore: false, decoration: { id: 'y', state: 'proposed' } } as C4Node, theme).color],
+    ['unconfirmed', nodeStyle({ id: 'x', kind: 'container', label: '', members: [], constructs: [], isStore: false } as C4Node, theme).color],
+  ];
+
+  let currentGroup = '';
+  return (
+    <div style={{ padding: 28, background: theme.colors.background, minHeight: '100vh' }}>
+      <h1 style={{ margin: '0 0 4px', fontSize: 22, color: theme.colors.text }}>C4 node gallery</h1>
+      <p style={{ margin: '0 0 22px', fontSize: 13, color: muted, maxWidth: 720, lineHeight: 1.5 }}>
+        Every box the graph can draw, rendered on its own. The graph answers “what does this system
+        look like”; this answers “what does a box mean”. No layout engine, no edges — just the
+        encoding.
+      </p>
+
+      <div style={{ display: 'flex', gap: 16, fontFamily: 'monospace', fontSize: 11, marginBottom: 26 }}>
+        {legend.map(([name, color]) => (
+          <span key={name} style={{ display: 'flex', alignItems: 'center', gap: 6, color: muted }}>
+            <span style={{ width: 22, height: 0, borderTop: `3px solid ${color}`, display: 'inline-block' }} />
+            {name}
+          </span>
+        ))}
+      </div>
+
+      <Row>
+        {VARIANTS.map((v) => {
+          const showHeader = v.group && v.group !== currentGroup;
+          if (v.group) currentGroup = v.group;
+          return (
+            <React.Fragment key={v.id ?? v.node.id}>
+              {showHeader && (
+                <div style={{ width: '100%' }}>
+                  <Section title={v.group} note={v.note} />
+                </div>
+              )}
+              <Case
+                caption={`${v.node.id} · tag "${nodeTag(v.node)}" · ${nodeSubtitle(v.node)}${
+                  nodeMissing(v.node).length ? ` · missing ${nodeMissing(v.node).join('+')}` : ''
+                }`}
+              >
+                <C4NodeCard node={v.node} />
+              </Case>
+            </React.Fragment>
+          );
+        })}
+      </Row>
+
+      <div style={{ marginTop: 22, maxWidth: 720 }}>
+        <Section
+          title="Selected"
+          note="A selected node overrides its confirmation styling, so a click target reads differently from the graph around it."
+        />
+        <C4NodeCard node={VARIANTS[0]!.node} selected />
+      </div>
+    </div>
+  );
+}
+
+export const All: Story = {
+  render: () => <Gallery />,
+};

package/src/stories/Subsystem/C4Graph/c4Associations.fixture.ts

@@ -0,0 +1,344 @@
+// GENERATED from live store data by generateFixture.ts — do not hand-edit.
+//
+// Derived from the SAME composition as c4Fixture.ts: 225 components
+// → 13 container keys → 13 associations.
+//
+// Every association is state:'proposed'. None of it is accepted — accepting is
+// a human's decision, and this story exists to make that decision visible.
+
+import type { C4Association } from "../../../subsystem/toC4";
+
+/** Container keys whose trailing role matches — candidates for a merge. */
+export const C4_MERGE_CANDIDATES = [
+  {
+    "role": "host",
+    "keys": [
+      "principal-studio/host",
+      "subsystems-studio/host"
+    ],
+    "reason": "2 process keys end in \"/host\" (principal-studio/host, subsystems-studio/host) — one deployable unit under two names, or two units?"
+  },
+  {
+    "role": "renderer",
+    "keys": [
+      "principal-studio/renderer",
+      "subsystems-studio/renderer"
+    ],
+    "reason": "2 process keys end in \"/renderer\" (principal-studio/renderer, subsystems-studio/renderer) — one deployable unit under two names, or two units?"
+  }
+] as const;
+
+/** Every mechanical concern, for the review panel. */
+export const C4_CONCERNS = [
+  {
+    "target": "subsystems-studio/host",
+    "kind": "store_unclassified",
+    "message": "1 store(s) in \"subsystems-studio/host\" declare no storage kind (c127) — decide whether each is a C4 data store or an internal detail",
+    "members": [
+      "c127"
+    ]
+  },
+  {
+    "target": "subsystems-studio/renderer",
+    "kind": "store_unclassified",
+    "message": "4 store(s) in \"subsystems-studio/renderer\" declare no storage kind (c42, c95, c102, c131) — decide whether each is a C4 data store or an internal detail",
+    "members": [
+      "c42",
+      "c95",
+      "c102",
+      "c131"
+    ]
+  },
+  {
+    "target": "site/web",
+    "kind": "missing_technology",
+    "message": "container \"site/web\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c82",
+      "c83",
+      "c84"
+    ]
+  },
+  {
+    "target": "subsystems-core/types",
+    "kind": "missing_technology",
+    "message": "container \"subsystems-core/types\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c85",
+      "c86",
+      "c87"
+    ]
+  },
+  {
+    "target": "principal-studio-cli",
+    "kind": "singleton",
+    "message": "process \"principal-studio-cli\" has exactly one member (c88) — a lone function is not a deployable unit",
+    "members": [
+      "c88"
+    ]
+  },
+  {
+    "target": "principal-studio-cli",
+    "kind": "missing_technology",
+    "message": "container \"principal-studio-cli\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c88"
+    ]
+  },
+  {
+    "target": "subsystems-react",
+    "kind": "missing_technology",
+    "message": "container \"subsystems-react\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c96",
+      "c97",
+      "c98",
+      "c99",
+      "c100",
+      "c101",
+      "c108",
+      "c109",
+      "c112",
+      "c113",
+      "c114"
+    ]
+  },
+  {
+    "target": "subsystems-react",
+    "kind": "store_unclassified",
+    "message": "1 store(s) in \"subsystems-react\" declare no storage kind (c98) — decide whether each is a C4 data store or an internal detail",
+    "members": [
+      "c98"
+    ]
+  },
+  {
+    "target": "subsystems-core",
+    "kind": "missing_technology",
+    "message": "container \"subsystems-core\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c106",
+      "c107",
+      "c167"
+    ]
+  },
+  {
+    "target": "subsystems-studio/shared",
+    "kind": "library_shaped",
+    "message": "process \"subsystems-studio/shared\" has 2 member(s) but none execute at runtime (type_alias) — this reads as a library, not a container",
+    "members": [
+      "c132",
+      "c133"
+    ]
+  },
+  {
+    "target": "packages/subsystems-studio/run",
+    "kind": "missing_technology",
+    "message": "container \"packages/subsystems-studio/run\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c147",
+      "c148",
+      "c149"
+    ]
+  },
+  {
+    "target": "packages/subsystems-studio/run",
+    "kind": "store_unclassified",
+    "message": "1 store(s) in \"packages/subsystems-studio/run\" declare no storage kind (c148) — decide whether each is a C4 data store or an internal detail",
+    "members": [
+      "c148"
+    ]
+  },
+  {
+    "target": "principal-studio/host",
+    "kind": "singleton",
+    "message": "process \"principal-studio/host\" has exactly one member (c155) — a lone function is not a deployable unit",
+    "members": [
+      "c155"
+    ]
+  },
+  {
+    "target": "principal-studio/host",
+    "kind": "missing_technology",
+    "message": "container \"principal-studio/host\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c155"
+    ]
+  },
+  {
+    "target": "subsystems-react/session-ui",
+    "kind": "singleton",
+    "message": "process \"subsystems-react/session-ui\" has exactly one member (c211) — a lone function is not a deployable unit",
+    "members": [
+      "c211"
+    ]
+  },
+  {
+    "target": "subsystems-react/session-ui",
+    "kind": "missing_technology",
+    "message": "container \"subsystems-react/session-ui\" has no framework signal — C4 requires a technology on every container",
+    "members": [
+      "c211"
+    ]
+  }
+] as const;
+
+export const c4Associations: C4Association[] = [
+  {
+    "id": "container:(unassigned)",
+    "level": "container",
+    "sourceKeys": [
+      "(unassigned)"
+    ],
+    "label": "(unassigned)",
+    "type": "application",
+    "technology": "react",
+    "state": "proposed",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:packages/subsystems-studio/run",
+    "level": "container",
+    "sourceKeys": [
+      "packages/subsystems-studio/run"
+    ],
+    "label": "packages/subsystems-studio/run",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "container \"packages/subsystems-studio/run\" has no framework signal — C4 requires a technology on every container 1 store(s) in \"packages/subsystems-studio/run\" declare no storage kind (c148) — decide whether each is a C4 data store or an internal detail",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:principal-studio-cli",
+    "level": "container",
+    "sourceKeys": [
+      "principal-studio-cli"
+    ],
+    "label": "principal-studio-cli",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "process \"principal-studio-cli\" has exactly one member (c88) — a lone function is not a deployable unit container \"principal-studio-cli\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:principal-studio/host",
+    "level": "container",
+    "sourceKeys": [
+      "principal-studio/host"
+    ],
+    "label": "principal-studio/host",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "process \"principal-studio/host\" has exactly one member (c155) — a lone function is not a deployable unit container \"principal-studio/host\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:principal-studio/renderer",
+    "level": "container",
+    "sourceKeys": [
+      "principal-studio/renderer"
+    ],
+    "label": "principal-studio/renderer",
+    "type": "application",
+    "technology": "react",
+    "state": "proposed",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:site/web",
+    "level": "container",
+    "sourceKeys": [
+      "site/web"
+    ],
+    "label": "site/web",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "container \"site/web\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-core",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-core"
+    ],
+    "label": "subsystems-core",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "container \"subsystems-core\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-core/types",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-core/types"
+    ],
+    "label": "subsystems-core/types",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "container \"subsystems-core/types\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-react",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-react"
+    ],
+    "label": "subsystems-react",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "container \"subsystems-react\" has no framework signal — C4 requires a technology on every container 1 store(s) in \"subsystems-react\" declare no storage kind (c98) — decide whether each is a C4 data store or an internal detail",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-react/session-ui",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-react/session-ui"
+    ],
+    "label": "subsystems-react/session-ui",
+    "type": "application",
+    "state": "proposed",
+    "rationale": "process \"subsystems-react/session-ui\" has exactly one member (c211) — a lone function is not a deployable unit container \"subsystems-react/session-ui\" has no framework signal — C4 requires a technology on every container",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-studio/host",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-studio/host"
+    ],
+    "label": "subsystems-studio/host",
+    "type": "data-store",
+    "technology": "bun",
+    "state": "proposed",
+    "rationale": "1 store(s) in \"subsystems-studio/host\" declare no storage kind (c127) — decide whether each is a C4 data store or an internal detail",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-studio/renderer",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-studio/renderer"
+    ],
+    "label": "subsystems-studio/renderer",
+    "type": "application",
+    "technology": "react",
+    "state": "proposed",
+    "rationale": "4 store(s) in \"subsystems-studio/renderer\" declare no storage kind (c42, c95, c102, c131) — decide whether each is a C4 data store or an internal detail",
+    "author": "c4-proposer"
+  },
+  {
+    "id": "container:subsystems-studio/shared",
+    "level": "container",
+    "sourceKeys": [
+      "subsystems-studio/shared"
+    ],
+    "label": "subsystems-studio/shared",
+    "type": "library",
+    "state": "proposed",
+    "rationale": "process \"subsystems-studio/shared\" has 2 member(s) but none execute at runtime (type_alias) — this reads as a library, not a container",
+    "author": "c4-proposer"
+  }
+];