@principal-ai/principal-view-react 0.16.35 → 0.16.36

package/src/stories/SubsystemComponentGraph.stories.tsx

@@ -77,7 +77,6 @@ function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
         showEdgeLabels={showEdgeLabels}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selectedEdge
@@ -162,7 +161,7 @@ const readerDetail: GraphifyComponentDetail = {
   kind: 'class',
   methods: [
     { nodeId: 'm1', name: 'normalize', returnType: 'SessionEvent[]' },
-    { nodeId: 'm2', name: 'readSession', parameters: ['string'], returnType: 'SessionRecord' },
+    { nodeId: 'm2', name: 'readSession', parameters: [{ type: 'string' }], returnType: 'SessionRecord' },
     { nodeId: 'm3', name: 'toUniversalEvents', returnType: 'UniversalEvent[]' },
   ],
   properties: [{ name: 'sessionId', type: 'string' }],
@@ -201,7 +200,6 @@ function V2ReaderDemo() {
         edges={v2ReaderEdges}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selectedEdge
@@ -325,7 +323,6 @@ export const NarrowMaxWidth: Story = {
         components={investigateOnlyComponents}
         edges={investigateOnlyEdges}
         maxNodeWidth={140}
-       
       />
     </div>
   ),
@@ -385,6 +382,8 @@ const namingConventionComponents: SubsystemComponent[] = [
   },
 ];
 
+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 = {
@@ -392,9 +391,8 @@ export const NamingConventions: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={namingConventionComponents}
-        edges={[]}
+        edges={namingConventionEdges}
         maxNodeWidth={180}
-       
       />
     </div>
   ),
@@ -449,6 +447,75 @@ const detailKindComponents: SubsystemComponent[] = [
       callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
     } satisfies GraphifyComponentDetail,
   },
+  {
+    id: 'detail-fn-rich',
+    name: 'mergeSessions',
+    kind: 'function',
+    file: 'src/session/merge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'multi-param signature — named, positional (graphify captures types only), union types, generic return',
+    symbol: 'mergeSessions',
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'sessions', type: 'SessionRecord[]' },
+        { type: 'MergeOptions' },
+        { name: 'strategy', type: `'append' | 'replace' | 'skip'` },
+        { name: 'onConflict', type: '((a: SessionRecord, b: SessionRecord) => SessionRecord)' },
+      ],
+      returnType: 'Promise<Map<string, SessionEvent[]>>',
+      callers: [
+        { nodeId: 'c1', name: 'capture-session', source_location: 'L88' },
+        { nodeId: 'c3', name: 'backfill', source_location: 'L210' },
+      ],
+      callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'detail-fn-void',
+    name: 'flush',
+    kind: 'function',
+    file: 'src/event-processing/sink.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'no parameters, no return type — the barest function signature',
+    symbol: 'flush',
+    detail: {
+      kind: 'function',
+      parameters: [],
+      callers: [{ nodeId: 'c4', name: 'EventProcessor.dispose', source_location: 'L142' }],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'detail-class-rich',
+    name: 'EventProcessor',
+    kind: 'class',
+    file: 'src/event-processing/EventProcessor.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'class with fully-typed members — method params + returns, field types, extends + implements',
+    symbol: 'EventProcessor',
+    detail: {
+      kind: 'class',
+      methods: [
+        { nodeId: 'rm1', name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
+        { nodeId: 'rm2', name: 'batch', parameters: [{ type: 'RawEvent[]' }], returnType: 'Promise<ProcessedEvent[]>' },
+        { nodeId: 'rm3', name: 'onError', parameters: [{ type: 'Error' }] },
+        { nodeId: 'rm4', name: 'dispose' },
+      ],
+      properties: [
+        { name: 'queue', type: 'RawEvent[]' },
+        { name: 'options', type: 'Required<ProcessingOptions>' },
+        { name: 'retryLimit', type: 'number' },
+      ],
+      extends: ['BaseProcessor'],
+      implements: ['Disposable', 'EventEmitterLike'],
+      instantiations: [
+        { nodeId: 'x1', name: 'main' },
+        { nodeId: 'x2', name: 'worker-pool' },
+      ],
+      references: [{ nodeId: 'x3', name: 'pipeline', context: 'type' }],
+    } satisfies GraphifyComponentDetail,
+  },
   {
     id: 'detail-type',
     name: 'SessionRecord',
@@ -501,15 +568,16 @@ const detailKindComponents: SubsystemComponent[] = [
   },
 ];
 
+const detailKindEdges: SubsystemComponentEdge[] = [];
+
 function DetailKindsDemo() {
   const [selected, setSelected] = useState<string | null>(null);
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={detailKindComponents}
-        edges={[]}
+        edges={detailKindEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selected ? `selected: ${selected}` : 'click a component to see its GraphifyComponentDetail'}
@@ -522,6 +590,261 @@ export const DetailKinds: Story = {
   render: () => <DetailKindsDemo />,
 };
 
+// ---------------------------------------------------------------------------
+// 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',
+    kind: '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',
+    kind: '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',
+    kind: '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',
+    kind: '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',
+    kind: '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',
+    kind: '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',
+    kind: 'type',
+    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',
+    kind: 'type',
+    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',
+    kind: 'type',
+    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',
+    kind: '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',
+    kind: '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',
+    kind: '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',
+    kind: 'external',
+    file: '',
+    purl: 'pkg:npm/left-pad',
+    purpose: 'no drill-down — renders a plain `external left-pad`',
+    symbol: '',
+    layer: 5,
+  },
+  {
+    id: 'ext-label',
+    name: 'trail-viewer',
+    kind: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/trail-viewer',
+    purpose: 'labeled — the full purl as a quoted string literal',
+    symbol: '',
+    layer: 5,
+    detail: {
+      kind: 'external',
+      label: 'pkg:npm/@principal-ai/trail-viewer',
+    } 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 />,
+};
+
 // ---------------------------------------------------------------------------
 // Minimal (pre-graphify) vs Resolved (post-graphify) — the SAME subsystem,
 // showing what the LLM emits (no detail) and what graphify enrichment adds.
@@ -585,7 +908,6 @@ function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
         components={resolved ? resolvedComponents : minimalComponents}
         edges={sharedEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {resolved
@@ -662,7 +984,6 @@ function InvestigationDemo() {
         components={investigationComponents}
         edges={investigationEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         read-only investigation snapshot (grok 019fd2a9) — components analyzed, not edited
@@ -754,7 +1075,6 @@ function MermaidDemo() {
         components={mermaidComponents}
         edges={mermaidEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         mermaid diagram rendering pipeline — lazy → render → zoom → modal