@principal-ai/subsystems-react 0.37.12 → 0.39.0

package/src/stories/Subsystem/EgoGraph/EgoGraph.stories.tsx

@@ -0,0 +1,354 @@
+/**
+ * Ego-graph prototype: reuse the subsystem component nodes to render one
+ * graphify symbol at the center plus its real connections.
+ *
+ * The center + neighbors come from `graphify/__fixtures__/ego-samples.json`
+ * (extracted from this repo's cached graph). Each graphify node is mapped onto
+ * a `SubsystemComponent`; the graphify edges are passed through the dedicated
+ * `graphifyRelations` input, so they render with the separate
+ * `GRAPHIFY_RELATION_COLOR` palette — visually distinct from authored subsystem
+ * mechanisms — and keep their raw verb as the label (no folding to
+ * `references`).
+ */
+import React from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type {
+  SubsystemComponent,
+  SubsystemComponentConstruct,
+  SubsystemGraphifyRelation,
+} from '../../../subsystem/model';
+import { inferConstructFromGraphify } from '../../../graphify';
+import type { GraphifyEdge, GraphifyNode } from '../../../graphify';
+import egoSamples from '../../../graphify/__fixtures__/ego-samples.json';
+
+const meta = {
+  title: 'Subsystem/EgoGraph',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Fixture shape
+// ---------------------------------------------------------------------------
+
+type FixtureNode = {
+  id: string;
+  label: string;
+  file_type?: string;
+  source_file?: string;
+  source_location?: string;
+  type?: string;
+};
+
+type FixtureEdge = {
+  source: string;
+  target: string;
+  relation: string;
+  confidence?: string;
+  context?: string;
+  source_file?: string;
+  source_location?: string;
+};
+
+type FixtureCategory = {
+  center?: FixtureNode;
+  degree?: number;
+  neighborCount?: number;
+  neighbors?: FixtureNode[];
+  edges?: FixtureEdge[];
+};
+
+type Category = 'class' | 'function' | 'method' | 'type' | 'module';
+
+const categories = egoSamples.categories as unknown as Record<Category, FixtureCategory>;
+const authoredCategories = egoSamples.authoredCategories as unknown as Record<
+  string,
+  { component: SubsystemComponent }
+>;
+
+const REPO_PURL = 'pkg:github/principal-ai/subsystem-modeling';
+
+// ---------------------------------------------------------------------------
+// graphify -> subsystem mapping
+// ---------------------------------------------------------------------------
+
+/** The fixture center's category, expressed as a subsystem construct. */
+const CENTER_CONSTRUCT: Record<Category, SubsystemComponentConstruct> = {
+  class: 'class',
+  function: 'function',
+  method: 'method',
+  type: 'interface',
+  // Subsystem models draw files as module *frames*, not nodes — there is no
+  // `module` construct. Stand in with `external` so the file node still draws.
+  module: 'external',
+};
+
+/** Coarse graphify-inferred construct -> subsystem construct. */
+const INFERRED_TO_CONSTRUCT: Record<string, SubsystemComponentConstruct> = {
+  class: 'class',
+  function: 'function',
+  method: 'method',
+  type: 'interface',
+  module: 'external',
+  unknown: 'external',
+};
+
+function parseLine(location?: string): number | undefined {
+  const m = /^L(\d+)$/.exec(location ?? '');
+  return m ? Number(m[1]) : undefined;
+}
+
+function purlFor(sourceFile?: string): string {
+  return sourceFile ? `${REPO_PURL}#${sourceFile}` : REPO_PURL;
+}
+
+/**
+ * Graphify labels carry their own decoration: functions end `name()`, methods
+ * start `.name()`. A subsystem `symbol` is the bare code identity and the node
+ * renderer re-derives the `()` / `.` decoration itself, so passing a decorated
+ * label through would double it (`readFoo()()` → the name printed twice).
+ * Strip the graphify decoration and hand back a clean symbol.
+ */
+function stripGraphifyDecoration(label: string): string {
+  let s = label.trim();
+  if (s.endsWith('()')) s = s.slice(0, -2);
+  if (s.startsWith('.')) s = s.slice(1);
+  return s;
+}
+
+function toComponent(
+  alias: string,
+  node: FixtureNode,
+  construct: SubsystemComponentConstruct,
+  purpose: string,
+  lineOverride?: number,
+): SubsystemComponent {
+  const line = lineOverride ?? parseLine(node.source_location);
+  const symbol = stripGraphifyDecoration(node.label);
+  return {
+    alias,
+    name: symbol,
+    construct,
+    symbol,
+    file: node.source_file ?? '',
+    purl: purlFor(node.source_file),
+    purpose,
+    // `line` also seeds ELK's same-layer ordering (orderByLine).
+    ...(line != null ? { line } : {}),
+    ...(line != null
+      ? {
+          declarationRef: {
+            file: node.source_file ?? '',
+            startLine: line,
+            lineHash: 'ego-fixture',
+            capturedAt: new Date(0).toISOString(),
+          },
+        }
+      : {}),
+  };
+}
+
+interface EgoGraph {
+  components: SubsystemComponent[];
+  graphifyRelations: SubsystemGraphifyRelation[];
+}
+
+/** Turn one fixture category into a subsystem graph centered on its symbol. */
+function toEgoGraph(cat: FixtureCategory, category: Category): EgoGraph {
+  const center = cat.center;
+  if (!center) return { components: [], graphifyRelations: [] };
+
+  const edges = cat.edges ?? [];
+  const neighbors = cat.neighbors ?? [];
+
+  // graphify file nodes (`inferConstructFromGraphify` → 'module') are not
+  // symbols — they are the CONTAINER of symbols. The center's own file becomes
+  // a `module` boundary (a frame around its members) and its `contains` edges
+  // are dropped: membership is expressed by the frame, exactly as an authored
+  // model does it. Files reached as neighbors stay as nodes (they are external
+  // to the center's file), so only the center's file is framed.
+  const isFileNode = (n: FixtureNode): boolean =>
+    inferConstructFromGraphify(
+      n as unknown as GraphifyNode,
+      edges as unknown as GraphifyEdge[],
+    ).construct === 'module';
+
+  const centerFile = center.source_file;
+  const fileNodeIds = new Set(
+    neighbors.filter((n) => isFileNode(n)).map((n) => n.id),
+  );
+  // Neighbors that live in the center's file stay; the file node for that file
+  // is dropped (its containment is now the frame).
+  const knotless = neighbors.filter(
+    (n) => !(fileNodeIds.has(n.id) && n.source_file === centerFile),
+  );
+
+  const aliasById = new Map<string, string>([[center.id, 'center']]);
+  knotless.forEach((n, i) => aliasById.set(n.id, `n${i}`));
+  const aliasFor = (id: string): string | undefined => aliasById.get(id);
+
+  const centerConstruct = CENTER_CONSTRUCT[category];
+  const framedCenter: SubsystemComponent = {
+    ...toComponent(
+      'center',
+      center,
+      centerConstruct,
+      `graphify center — ${center.label}`,
+    ),
+    ...(centerConstruct !== 'external' && centerFile ? { module: centerFile } : {}),
+  };
+  const components: SubsystemComponent[] = [framedCenter];
+
+  // `component.line` is the CALL-SITE line, not the declaration line: the
+  // edge's `source_location` on an edge FROM the center (L115, L119, …), which
+  // `orderByLine` uses to stack callees in the order the center calls them.
+  // (The neighbor's own node `source_location` — where it is declared — is
+  // deliberately ignored here; declaration order would read arbitrarily.)
+  const callLineByAlias = new Map<string, number>();
+  for (const e of edges) {
+    const from = aliasFor(e.source);
+    const to = aliasFor(e.target);
+    const line = parseLine(e.source_location);
+    if (from === 'center' && to && line != null) callLineByAlias.set(to, line);
+  }
+
+  knotless.forEach((n, i) => {
+    const inferred = inferConstructFromGraphify(
+      n as unknown as GraphifyNode,
+      edges as unknown as GraphifyEdge[],
+    ).construct;
+    const construct = INFERRED_TO_CONSTRUCT[inferred] ?? 'external';
+    const purpose =
+      inferred === 'module'
+        ? 'graphify file node in ANOTHER file — kept as a node (outside the center frame)'
+        : `graphify ${inferred} neighbor (${n.file_type ?? 'code'})`;
+    // Members of the center's file join the frame; others stand alone.
+    const module = n.source_file === centerFile ? centerFile : undefined;
+    const c = toComponent(`n${i}`, n, construct, purpose, callLineByAlias.get(`n${i}`));
+    components.push(module ? { ...c, module } : c);
+  });
+
+  // Raw graphify edges — passed straight through (no verb folding). The
+  // canvas colors them from GRAPHIFY_RELATION_COLOR and draws them dashed.
+  // `contains` is dropped: the frame carries containment, not an edge.
+  const graphifyRelations: SubsystemGraphifyRelation[] = edges
+    .map((e, i): SubsystemGraphifyRelation | null => {
+      if (e.relation === 'contains') return null;
+      const from = aliasFor(e.source);
+      const to = aliasFor(e.target);
+      if (!from || !to) return null;
+      return {
+        id: `g${i}`,
+        from,
+        to,
+        relation: e.relation,
+        refs: e.source_file ? [e.source_file] : undefined,
+        line: parseLine(e.source_location),
+        confidence: e.confidence,
+        context: e.context,
+      };
+    })
+    .filter((x): x is SubsystemGraphifyRelation => x != null);
+
+  return { components, graphifyRelations };
+}
+
+function EgoDemo({ category, orderByLine }: { category: Category; orderByLine: boolean }) {
+  const graph = React.useMemo(() => toEgoGraph(categories[category], category), [category]);
+  const cat = categories[category];
+  const verbs = [...new Set(graph.graphifyRelations.map((r) => r.relation))];
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={graph.components}
+        relations={[]}
+        graphifyRelations={graph.graphifyRelations}
+        orderByLine={orderByLine}
+        showSingletonFrames
+        title={`Ego graph — ${category}`}
+        description={`graphify center ${cat.center?.label ?? '?'} · ${cat.degree ?? 0} edges · verbs: ${verbs.join(', ')}${orderByLine ? ' · ordered by call-site line' : ''}`}
+        showEdgeLabels
+        hideSidebar={false}
+      />
+    </div>
+  );
+}
+
+/** Everything on disk for the center: node + neighbor nodes + raw edges. */
+function RawDump({ category }: { category: Category }) {
+  const cat = categories[category];
+  return (
+    <pre
+      style={{
+        margin: 0,
+        padding: 12,
+        fontSize: 12,
+        lineHeight: 1.5,
+        fontFamily: 'monospace',
+        color: '#ddd',
+        background: '#111',
+        height: '100vh',
+        overflow: 'auto',
+        boxSizing: 'border-box',
+      }}
+    >
+      {JSON.stringify({ category, ...cat }, null, 2)}
+    </pre>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Stories — one per graphify node category
+// ---------------------------------------------------------------------------
+
+export const Class: Story = { render: () => <EgoDemo category="class" orderByLine /> };
+export const Function: Story = { render: () => <EgoDemo category="function" orderByLine /> };
+export const Method: Story = { render: () => <EgoDemo category="method" orderByLine /> };
+export const Type: Story = { render: () => <EgoDemo category="type" orderByLine /> };
+export const Module: Story = { render: () => <EgoDemo category="module" orderByLine /> };
+
+/** Same centers, ELK's default ordering — compare against the line-ordered set. */
+export const MethodReorderOff: Story = {
+  render: () => <EgoDemo category="method" orderByLine={false} />,
+};
+
+/** The raw extracted data behind each center — no rendering involved. */
+export const Raw: Story = { render: () => <RawDump category="class" /> };
+
+// ---------------------------------------------------------------------------
+// Authored-only constructs (no graphify node) pulled from the model store
+// ---------------------------------------------------------------------------
+
+const authoredComponents: SubsystemComponent[] = [
+  authoredCategories.store?.component,
+  authoredCategories.external?.component,
+  authoredCategories.custom_entity?.component,
+].filter(Boolean) as SubsystemComponent[];
+
+/** store / external / custom_entity — authored nodes, no graphify anchor. */
+export const AuthoredConstructs: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={authoredComponents}
+        relations={[]}
+        title="Authored-only constructs"
+        description="store / external / custom_entity — reused cast from stored subsystem models (no graphify node, no edges)."
+      />
+    </div>
+  ),
+};

package/src/stories/Subsystem/StoreValueTypeDeclaration.stories.tsx

@@ -0,0 +1,182 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { generateDeclarationString } from '../../subsystem/formatDeclaration';
+import type { SubsystemComponent } from '../../subsystem/model';
+
+/**
+ * StoreValueType — how a store's declared value type renders in the
+ * **declaration panel** (the click panel), not on the node.
+ *
+ * A store is a state declaration, so it declares its type the way every other
+ * declaration does: `declaration.valueType` (`Map<string, FeedState>` for a state
+ * block, a row type for a table), orthogonal to `declaration.storage`. The
+ * rendered string comes from the real `generateStore` in
+ * `formatDeclaration.ts` — not a sketch.
+ *
+ * The node itself is unchanged: title = the state declaration's name, badge =
+ * storage backing. The value type is panel-only.
+ */
+const meta = {
+  title: 'Subsystem/StoreValueTypeDeclaration',
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ maxWidth: '80ch', margin: '0 auto' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta;
+export default meta;
+
+type Case = {
+  label: string;
+  note: string;
+  component: SubsystemComponent;
+};
+
+const CASES: Case[] = [
+  {
+    label: 'memory · value type, no named members',
+    note: 'The store declares what it holds; nothing else to render.',
+    component: {
+      id: 'feeds',
+      name: 'feeds',
+      construct: 'store',
+      symbol: 'feeds',
+      file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        properties: [],
+        valueType: 'Map<string, OpencodeLiveFeedState>',
+      },
+    },
+  },
+  {
+    label: 'memory · closure-local state',
+    note: 'State created inside a factory, reached through an accessor. Still a declaration.',
+    component: {
+      id: 'landed',
+      name: 'landed',
+      construct: 'store',
+      symbol: 'landed',
+      file: 'packages/subsystems-studio/src/bun/maintainer-probe.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        properties: [],
+        valueType: 'Map<string, number>',
+      },
+    },
+  },
+  {
+    label: 'disk · value type + named members',
+    note: 'Members render as a typed body under the value type.',
+    component: {
+      id: 'runs',
+      name: 'runs',
+      construct: 'store',
+      symbol: 'runs',
+      file: 'packages/subsystems-studio/src/bun/subsystem-model-runs.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration: {
+        kind: 'store',
+        storage: 'disk',
+        valueType: 'SubsystemModelRun[]',
+        properties: [{ name: 'runs', type: 'SubsystemModelRun[]' }],
+      },
+    },
+  },
+  {
+    label: 'memory · no value type → the gap',
+    note: 'Says so explicitly — the completeness finding reads this back.',
+    component: {
+      id: 'tabs',
+      name: 'tabs',
+      construct: 'store',
+      symbol: 'tabs',
+      file: 'packages/subsystems-studio/src/bun/index.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration: { kind: 'store', storage: 'memory', properties: [] },
+    },
+  },
+  {
+    label: 'db · row shape, no scalar value type',
+    note: 'A table names its row/record type; columns stay as members.',
+    component: {
+      id: 'session_v2',
+      name: 'session_v2',
+      construct: 'store',
+      symbol: 'session_v2',
+      file: 'packages/subsystems-studio/src/bun/maintain-sessions.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration: {
+        kind: 'store',
+        storage: 'external',
+        properties: [
+          { name: 'id', type: 'text' },
+          { name: 'title', type: 'text' },
+          { name: 'agent', type: 'text' },
+          { name: 'time_created', type: 'integer' },
+        ],
+      },
+    },
+  },
+];
+
+function Panel({ component }: { component: SubsystemComponent }) {
+  return (
+    <pre
+      style={{
+        margin: 0,
+        padding: '10px 12px',
+        borderRadius: 6,
+        background: 'rgba(0,0,0,0.35)',
+        border: '1px solid rgba(255,255,255,0.08)',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+        fontSize: 12,
+        lineHeight: 1.5,
+        color: '#e5e7eb',
+        whiteSpace: 'pre-wrap',
+        overflowX: 'auto',
+      }}
+    >
+      {generateDeclarationString(component)}
+    </pre>
+  );
+}
+
+export const StoreDeclaration: StoryObj = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 26 }}>
+      <div style={{ fontSize: 12, color: '#b0b0b0', lineHeight: 1.7 }}>
+        <strong>Rendered by the real <code>generateStore</code>.</strong> A store declares
+        its type the way every other declaration does — <code>declaration.valueType</code> —
+        and the value type is panel-only, not a node channel. The node stays{' '}
+        <code>name → title</code>, <code>storage → badge</code>.
+      </div>
+      {CASES.map((c) => (
+        <div key={c.component.id}>
+          <div
+            style={{
+              fontFamily: 'ui-monospace, monospace',
+              fontSize: 12,
+              color: '#f3f4f6',
+              marginBottom: 6,
+            }}
+          >
+            {c.label}
+          </div>
+          <div style={{ fontSize: 11, color: '#9ca3af', marginBottom: 8 }}>{c.note}</div>
+          <Panel component={c.component} />
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/subsystem/IssueList.focus.test.tsx

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemIssueList, type SubsystemIssue } from './IssueList';
+
+// Bun's happy-dom test environment isn't registered (no @happy-dom/global-
+// registrator), so wire the DOM primitives React DOM needs before rendering.
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+
+afterEach(cleanup);
+
+const issues: SubsystemIssue[] = [
+  {
+    id: 'ct',
+    severity: 'error',
+    kind: 'missing_file',
+    message: 'construct finding',
+    target: { kind: 'component', id: 'alpha', label: 'Alpha' },
+  },
+  {
+    id: 'wl',
+    severity: 'info',
+    kind: 'walkthrough',
+    message: 'walkthrough finding',
+    target: { kind: 'walkthrough', id: 'w', label: 'Walkthrough' },
+  },
+];
+
+function setup() {
+  const events: string[] = [];
+  const view = render(
+    createElement(
+      ThemeProvider,
+      { theme: defaultEditorTheme },
+      createElement(SubsystemIssueList, {
+        issues,
+        onSelectIssue: (i) => events.push(`select:${i.id}`),
+        onDeselectIssue: (i) => events.push(`deselect:${i.id}`),
+      }),
+    ),
+  );
+  const category = (name: string) =>
+    [...view.container.querySelectorAll('button')].find((b) =>
+      b.textContent?.includes(name),
+    ) as HTMLElement;
+  const card = (label: string) =>
+    [...view.container.querySelectorAll('[role="button"]')].find((b) =>
+      b.textContent?.includes(label),
+    ) as HTMLElement;
+  return { ...view, events, category, card };
+}
+
+describe('collapsing a category retracts the focus it established', () => {
+  // Closing a CATEGORY unmounts its cards, so a card stops being expanded
+  // without ever toggling itself. A host that framed a target on expand has to
+  // hear about it, or the canvas stays parked on a target the list no longer
+  // shows as open.
+  test('clicking the open category emits a deselect for its expanded card', () => {
+    const { events, category, card } = setup();
+    fireEvent.click(category('Constructs'));
+    fireEvent.click(card('Alpha'));
+    expect(events).toEqual(['select:ct']);
+
+    fireEvent.click(category('Constructs'));
+    expect(events).toEqual(['select:ct', 'deselect:ct']);
+  });
+
+  test('opening a sibling layer retracts the other layer’s card', () => {
+    // The accordion closes every other layer, so that layer's cards unmount
+    // on this click — same obligation as collapsing the layer directly.
+    const { events, category, card } = setup();
+    fireEvent.click(category('Constructs'));
+    fireEvent.click(card('Alpha'));
+
+    fireEvent.click(category('Walkthrough'));
+    expect(events).toEqual(['select:ct', 'deselect:ct']);
+  });
+
+  test('collapsing a layer with nothing expanded emits no deselect', () => {
+    const { events, category } = setup();
+    fireEvent.click(category('Constructs'));
+    fireEvent.click(category('Constructs'));
+    expect(events).toEqual([]);
+  });
+
+  test('collapsing the card itself still emits exactly one deselect', () => {
+    // The ref is cleared by the card's own collapse, so closing the layer
+    // afterwards must not re-report it.
+    const { events, category, card } = setup();
+    fireEvent.click(category('Constructs'));
+    fireEvent.click(card('Alpha'));
+    fireEvent.click(card('Alpha'));
+    expect(events).toEqual(['select:ct', 'deselect:ct']);
+
+    fireEvent.click(category('Constructs'));
+    expect(events).toEqual(['select:ct', 'deselect:ct']);
+  });
+});