@principal-ai/subsystems-react 0.17.0

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

@@ -0,0 +1,365 @@
+import React, { useState } 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, SubsystemComponentEdge } from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+import { investigateOnlyComponents, investigateOnlyEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Appearance',
+  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>;
+
+/** Same pipeline as Captures/InvestigateOnly with a narrower `maxNodeWidth` (140) — long names wrap. */
+export const NarrowMaxWidth: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={investigateOnlyComponents}
+        edges={investigateOnlyEdges}
+        maxNodeWidth={140}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Naming-convention wrap check — one node per common symbol convention.
+// ---------------------------------------------------------------------------
+const namingConventionComponents: SubsystemComponent[] = [
+  {
+    id: 'camel',
+    name: 'accumulateToAgentSessionEvents',
+    construct: 'function',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'accumulateToAgentSessionEvents',
+  },
+  {
+    id: 'snake',
+    name: 'repo_normalized_universal_event',
+    construct: 'interface',
+    file: 'src/event-processing/repo_normalized.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'repo_normalized_universal_event',
+  },
+  {
+    id: 'pascal',
+    name: 'RepoNormalizedUniversalAgentSessionEvent',
+    construct: 'class',
+    file: 'src/event-processing/RepoNormalized.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'RepoNormalizedUniversalAgentSessionEvent',
+  },
+  {
+    id: 'acronym',
+    name: 'ProcessSSEStreamForEventToken',
+    construct: 'function',
+    file: 'src/event-processing/sse.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'ProcessSSEStreamForEventToken',
+  },
+  {
+    id: 'method',
+    name: 'normalize',
+    construct: 'function',
+    file: 'src/session/SessionReader.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    symbol: 'SessionReader.normalize',
+  },
+  {
+    id: 'pkg',
+    name: 'principal-studio',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/subsystems-studio',
+    symbol: '',
+  },
+];
+
+const namingConventionEdges: SubsystemComponentEdge[] = [];
+
+/** Nodes with compact `maxNodeWidth` so the different conventions visibly wrap
+ *  at their word boundaries (camelCase, snake_case, PascalCase, acronyms). */
+export const NamingConventions: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={namingConventionComponents}
+        edges={namingConventionEdges}
+        maxNodeWidth={180}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Kind variations — one column per kind (class / function / type / module /
+// external), rows going bare → detailed. Click a node to see its declaration
+// panel; type names inside it are clickable when they match another node here.
+// ---------------------------------------------------------------------------
+const variationPurl = 'pkg:github/principal-ai/agent-monitoring';
+
+const kindVariationComponents: SubsystemComponent[] = [
+  // --- class: bare → members only → relationships only
+  {
+    id: 'cls-bare',
+    name: 'SessionStore',
+    construct: 'class',
+    file: 'src/session/SessionStore.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `class SessionStore`',
+    symbol: 'SessionStore',
+    layer: 1,
+  },
+  {
+    id: 'cls-members',
+    name: 'Transcoder',
+    construct: 'class',
+    file: 'src/session/Transcoder.ts',
+    purl: variationPurl,
+    purpose: 'members only — methods with typed params + returns, a typed field',
+    symbol: 'Transcoder',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [
+        { nodeId: 'tm1', name: 'encode', parameters: [{ type: 'RawFrame' }], returnType: 'Uint8Array' },
+        { nodeId: 'tm2', name: 'decode', parameters: [{ type: 'Uint8Array' }], returnType: 'RawFrame' },
+        { nodeId: 'tm3', name: 'reset' },
+      ],
+      properties: [{ name: 'bufferSize', type: 'number' }],
+      extends: [],
+      implements: [],
+      instantiations: [],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'cls-relations',
+    name: 'HttpTransport',
+    construct: 'class',
+    file: 'src/transport/HttpTransport.ts',
+    purl: variationPurl,
+    purpose: 'relationships only — extends + implements, constructed-by comment; empty body elides the braces',
+    symbol: 'HttpTransport',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [],
+      properties: [],
+      extends: ['BaseTransport'],
+      implements: ['Transport'],
+      instantiations: [{ nodeId: 'x1', name: 'main' }],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- function: bare → signature only → signature + call relationships
+  {
+    id: 'fn-bare',
+    name: 'bootstrap',
+    construct: 'function',
+    file: 'src/bootstrap.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `function bootstrap()`',
+    symbol: 'bootstrap',
+    layer: 2,
+  },
+  {
+    id: 'fn-signature',
+    name: 'normalizeSession',
+    construct: 'function',
+    file: 'src/event-processing/normalize.ts',
+    purl: variationPurl,
+    purpose: 'signature only — named + positional (type-only) params, array return; no callers/callees comments',
+    symbol: 'normalizeSession',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'session', type: 'SessionRecord' },
+        { type: 'NormalizeOptions' },
+      ],
+      returnType: 'SessionEvent[]',
+      callers: [],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'fn-calls',
+    name: 'mergeSessions',
+    construct: 'function',
+    file: 'src/session/merge.ts',
+    purl: variationPurl,
+    purpose: 'signature + call relationships — union-typed param, generic return, called-by / calls trailing comments',
+    symbol: 'mergeSessions',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'sessions', type: 'SessionRecord[]' },
+        { name: 'strategy', type: `'append' | 'replace'` },
+      ],
+      returnType: 'Promise<SessionEvent[]>',
+      callers: [{ nodeId: 'c1', name: 'capture-session', source_location: 'L88' }],
+      callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- type: bare → fields only → fields + implementors + used-by
+  {
+    id: 'ty-bare',
+    name: 'RawFrame',
+    construct: 'interface',
+    file: 'src/session/RawFrame.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `interface RawFrame`',
+    symbol: 'RawFrame',
+    layer: 3,
+  },
+  {
+    id: 'ty-fields',
+    name: 'SessionRecord',
+    construct: 'interface',
+    file: 'src/session/transcript.ts',
+    purl: variationPurl,
+    purpose: 'fields only — typed interface body, nothing else',
+    symbol: 'SessionRecord',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'id', type: 'string' },
+        { name: 'admittedSeq', type: 'number' },
+      ],
+      usedBy: [],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'ty-full',
+    name: 'Transport',
+    construct: 'interface',
+    file: 'src/transport/Transport.ts',
+    purl: variationPurl,
+    purpose: 'full — fields + implemented-by (clicks through to HttpTransport) + used-by comments',
+    symbol: 'Transport',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [{ name: 'name', type: 'string' }],
+      usedBy: [{ nodeId: 'u1', name: 'main', context: 'parameter_type' }],
+      implementors: ['HttpTransport'],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- module: bare → exports only → exports + imports
+  {
+    id: 'mod-bare',
+    name: 'transcript',
+    construct: 'module',
+    file: 'src/session/transcript.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — symbol-less module named from its file basename',
+    symbol: '',
+    layer: 4,
+  },
+  {
+    id: 'mod-exports',
+    name: 'paths',
+    construct: 'module',
+    file: 'src/session/paths.ts',
+    purl: variationPurl,
+    purpose: 'exports only — export statement + defines comment',
+    symbol: '',
+    layer: 4,
+    detail: {
+      kind: 'module',
+      exports: ['extractToolName', 'extractFilePath'],
+      imports: [],
+      symbols: ['extractToolName', 'extractFilePath'],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'mod-full',
+    name: 'index',
+    construct: 'module',
+    file: 'src/index.ts',
+    purl: variationPurl,
+    purpose: 'full — import statements + re-export statement + defines comment',
+    symbol: '',
+    layer: 4,
+    detail: {
+      kind: 'module',
+      exports: ['SessionReader', 'SessionStore'],
+      imports: [{ nodeId: 'i1', name: 'transcript', relation: 'imports_from' }],
+      symbols: ['SessionReader', 'SessionStore'],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- external: bare → labeled
+  {
+    id: 'ext-bare',
+    name: 'left-pad',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/left-pad',
+    purpose: 'no drill-down — renders a plain `external left-pad`',
+    symbol: '',
+    layer: 5,
+  },
+  {
+    id: 'ext-label',
+    name: 'principal-studio',
+    construct: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/subsystems-studio',
+    purpose: 'labeled — the full purl as a quoted string literal',
+    symbol: '',
+    layer: 5,
+    detail: {
+      kind: 'external',
+      label: 'pkg:npm/@principal-ai/subsystems-studio',
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+const kindVariationEdges: SubsystemComponentEdge[] = [];
+
+function KindVariationsDemo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={kindVariationComponents}
+        edges={kindVariationEdges}
+        onSelect={(id) => setSelected(id)}
+      />
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        columns: class · function · type · module · external — each goes bare → detailed
+        {selected ? ` · selected: ${selected}` : ''}
+      </div>
+    </div>
+  );
+}
+
+export const KindVariations: Story = {
+  render: () => <KindVariationsDemo />,
+};

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

@@ -0,0 +1,137 @@
+import React, { useState } 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, SubsystemComponentEdge } from '../../../subsystem/model';
+import { components, edges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Basics',
+  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>;
+
+// ---------------------------------------------------------------------------
+// Minimal: two nodes, one edge — the simplest possible label layout test.
+// ---------------------------------------------------------------------------
+const twoNodeComponents = components([
+  ['src', 'TranscriptParser', 'class', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records'],
+  ['dst', 'SessionReader', 'class', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes sessions into events'],
+]);
+
+const twoNodeEdges = edges([
+  ['src', 'dst', 'imports'],
+]);
+
+function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  const [selectedEdge, setSelectedEdge] = useState<SubsystemComponentEdge | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={twoNodeComponents}
+        edges={twoNodeEdges}
+        onSelect={(id) => setSelected(id)}
+        onEdgeSelect={(e) => setSelectedEdge(e)}
+        showEdgeLabels={showEdgeLabels}
+      />
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        {selectedEdge
+          ? `edge: ${selectedEdge.from} --${selectedEdge.mechanism}--> ${selectedEdge.to}`
+          : selected
+            ? `selected: ${selected}`
+            : 'click a component or edge to select it'}
+      </div>
+    </div>
+  );
+}
+
+export const TwoNodeSingleEdge: Story = {
+  render: () => <TwoNodeDemo />,
+};
+
+export const TwoNodeNoLabels: Story = {
+  render: () => <TwoNodeDemo showEdgeLabels={false} />,
+};
+
+// ---------------------------------------------------------------------------
+// Playground: control the number of nodes in left and right layers.
+// All left nodes connect to all right nodes (fan-in / fan-out).
+// ---------------------------------------------------------------------------
+function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount: number; rightCount: number; showEdgeLabels: boolean }) {
+  const comps: SubsystemComponent[] = [];
+  const edgeList: SubsystemComponentEdge[] = [];
+
+  for (let i = 0; i < leftCount; i++) {
+    comps.push({
+      id: `l${i}`,
+      name: `Left${i}`,
+      construct: 'class',
+      file: `left${i}.ts`,
+      purl: 'pkg:github/principal-ai/playground',
+      purpose: `left layer node ${i}`,
+    });
+  }
+  for (let i = 0; i < rightCount; i++) {
+    comps.push({
+      id: `r${i}`,
+      name: `Right${i}`,
+      construct: 'class',
+      file: `right${i}.ts`,
+      purl: 'pkg:github/principal-ai/playground',
+      purpose: `right layer node ${i}`,
+    });
+  }
+
+  let ei = 0;
+  for (let i = 0; i < leftCount; i++) {
+    for (let j = 0; j < rightCount; j++) {
+      edgeList.push({ id: `e${ei++}`, from: `l${i}`, to: `r${j}`, mechanism: 'imports' });
+    }
+  }
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph components={comps} edges={edgeList} showEdgeLabels={showEdgeLabels} />
+    </div>
+  );
+}
+
+export const Playground: Story = {
+  render: (args) => <PlaygroundDemo {...args} />,
+  args: {
+    leftCount: 1,
+    rightCount: 1,
+    showEdgeLabels: true,
+  },
+  argTypes: {
+    leftCount: { control: { type: 'number', min: 0, max: 6, step: 1 } },
+    rightCount: { control: { type: 'number', min: 0, max: 6, step: 1 } },
+    showEdgeLabels: { control: 'boolean' },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Empty state
+// ---------------------------------------------------------------------------
+export const Empty: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph components={[]} edges={[]} />
+    </div>
+  ),
+};