@principal-ai/principal-view-react 0.16.56 → 0.16.57

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -0,0 +1,129 @@
+import type {
+  SubsystemComponent,
+  SubsystemComponentEdge,
+} from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+
+// ---------------------------------------------------------------------------
+// Build a subsystem graph from a compact spec - helpers
+// ---------------------------------------------------------------------------
+export function components(
+  spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, detail?: GraphifyComponentDetail]>,
+): SubsystemComponent[] {
+  return spec.map(([id, name, construct, file, purl, purpose, symbol, detail]) => ({
+    id,
+    name,
+    construct,
+    file,
+    purl,
+    purpose,
+    symbol,
+    detail,
+  }));
+}
+
+export function edges(
+  spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism'], refs?: string[]]>,
+): SubsystemComponentEdge[] {
+  return spec.map(([from, to, mechanism, refs], i) => ({
+    id: `e${i}`,
+    from,
+    to,
+    mechanism,
+    refs,
+  }));
+}
+
+export const readerDetail: GraphifyComponentDetail = {
+  kind: 'class',
+  methods: [
+    { nodeId: 'm1', name: 'normalize', returnType: 'SessionEvent[]' },
+    { nodeId: 'm2', name: 'readSession', parameters: [{ type: 'string' }], returnType: 'SessionRecord' },
+    { nodeId: 'm3', name: 'toUniversalEvents', returnType: 'UniversalEvent[]' },
+  ],
+  properties: [{ name: 'sessionId', type: 'string' }],
+  extends: [],
+  implements: ['SessionReaderLike'],
+  instantiations: [{ nodeId: 'caller1', name: 'capture-session' }],
+  references: [{ nodeId: 'ref1', name: 'supported-agents', context: 'type' }],
+};
+
+// ---------------------------------------------------------------------------
+// Single package (no consumers) - the investigate-and-pin pattern.
+// Conveys the idea via LAYERS: readers (input) → accumulator (processing).
+// ---------------------------------------------------------------------------
+export const investigateOnlyComponents: SubsystemComponent[] = [
+  {
+    id: 'v1',
+    name: 'V1EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V1EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V1 DB rows into universal events',
+    symbol: 'V1EventBridgeProcessor',
+  },
+  {
+    id: 'v2',
+    name: 'V2EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V2EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V2 durable events into universal events',
+    symbol: 'V2EventBridgeProcessor',
+  },
+  {
+    id: 'input',
+    name: 'RepoNormalizedUniversalAgentSessionEvent',
+    construct: 'interface',
+    file: 'types/RepoNormalizedUniversalAgentSessionEvent.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s input type — a repo-normalized universal event the readers produce and the accumulator consumes',
+    symbol: 'RepoNormalizedUniversalAgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'eventType', type: 'NormalizedEventType' },
+        { name: 'sessionId', type: 'string' },
+        { name: 'timestamp', type: 'number' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'parameter_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'acc',
+    name: 'accumulateToAgentSessionEvents',
+    construct: 'function',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'accumulates normalized events into agent session events',
+    symbol: 'accumulateToAgentSessionEvents',
+  },
+  {
+    id: 'out',
+    name: 'AgentSessionEvent',
+    construct: 'interface',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s output type — an accumulated agent-session event',
+    symbol: 'AgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'sessionName', type: 'string' },
+        { name: 'operation', type: 'AgentSessionEventOperation' },
+        { name: 'description', type: 'string' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'return_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+export const investigateOnlyEdges: SubsystemComponentEdge[] = edges([
+  // Concept-level data flow — the LLM's semantic intent.
+  ['v1', 'input', 'produces'],
+  ['v2', 'input', 'produces'],
+  ['input', 'acc', 'feeds'],
+  ['acc', 'out', 'produces'],
+]);

package/src/subsystem/ComponentDeclaration.tsx

@@ -1,6 +1,6 @@
 /**
  * ComponentDeclaration — the selected subsystem component rendered as it would
- * appear in code: a file-path comment + doc comment, then the kind's
+ * appear in code: a file-path comment + doc comment, then the construct's
  * declaration (`class X extends Y { ... }`, `function f(): T`, ...) with its
  * members as signatures. Graphify relationship drill-downs appear as trailing
  * comments. File content lives in the bottom FileDrawer, not here.
@@ -11,7 +11,6 @@ import { AlignLeft, FileText, ShieldCheck } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 import {
-  KIND_COLOR,
   formatPurl,
   type SubsystemComponent,
   type SubsystemDeclTokenKind,
@@ -19,6 +18,7 @@ import {
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { parseSourceLocation } from './declarationRef';
 import { tokenizeComponent } from './tokenizeComponent';
+import { constructColorsFromPierreTheme } from '../pierre/constructColors';
 
 /** Live / result state for the declaration-panel Verify control. */
 export type ComponentVerificationPhase =
@@ -49,7 +49,7 @@ export interface ComponentVerificationState {
     source_location?: string;
     candidates?: Array<{ nodeId: string; label: string; source_file?: string }>;
   };
-  kind?: {
+  construct?: {
     claimed: string;
     inferred: string;
     match: boolean;
@@ -163,11 +163,11 @@ function verificationSummary(
         ? ` · declaration ${declFresh}${v.declaration?.ref ? ` L${v.declaration.ref.startLine}` : ''}`
         : '';
     const anchorBit = `exact → ${v.anchor?.label ?? v.anchor?.nodeId ?? 'node'}${loc}${declBit}`;
-    if (v.kind && !v.kind.match) {
+    if (v.construct && !v.construct.match) {
       const why =
-        v.kind.inferred === 'unknown'
-          ? `kind unknown (claimed ${v.kind.claimed})`
-          : `kind mismatch: claimed ${v.kind.claimed}, inferred ${v.kind.inferred}`;
+        v.construct.inferred === 'unknown'
+          ? `construct unknown (claimed ${v.construct.claimed})`
+          : `construct mismatch: claimed ${v.construct.claimed}, inferred ${v.construct.inferred}`;
       return {
         text: [...bits, anchorBit, why].join(' · '),
         color: '#e5534b',
@@ -182,7 +182,7 @@ function verificationSummary(
         text: [
           ...bits,
           anchorBit,
-          v.kind?.match ? `kind ${v.kind.inferred}` : undefined,
+          v.construct?.match ? `construct ${v.construct.inferred}` : undefined,
           `signature mismatch: params [${cParams}]≠[${iParams}] return [${cRet}]≠[${iRet}]`,
         ]
           .filter(Boolean)
@@ -190,8 +190,8 @@ function verificationSummary(
         color: '#e5534b',
       };
     }
-    const kindBit =
-      v.kind?.match ? `kind ${v.kind.inferred}` : undefined;
+    const constructBit =
+      v.construct?.match ? `construct ${v.construct.inferred}` : undefined;
     const inlineBit =
       v.signature?.inlineParameters
         ? `${v.signature.inlineParameters} inline param${v.signature.inlineParameters === 1 ? '' : 's'} verified`
@@ -210,7 +210,7 @@ function verificationSummary(
         text: [
           ...bits,
           anchorBit,
-          ...(kindBit ? [kindBit] : []),
+          ...(constructBit ? [constructBit] : []),
           ...(inlineBit ? [inlineBit] : []),
           v.signature.skipCode
             ? `params/return not fully checked — ${skipPhrase[v.signature.skipCode] ?? v.signature.skipCode}`
@@ -222,7 +222,7 @@ function verificationSummary(
     const sigBit =
       v.signature && v.signature.match ? 'params/return ok' : undefined;
     return {
-      text: [...bits, anchorBit, ...(kindBit ? [kindBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
+      text: [...bits, anchorBit, ...(constructBit ? [constructBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
       color: ok,
     };
   }
@@ -263,7 +263,7 @@ export function ComponentDeclaration({
   const [showFile, setShowFile] = useState(false);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const color = KIND_COLOR[component.kind] ?? '#888';
+  const color = constructColorsFromPierreTheme(pierreSyntaxTheme)[component.construct];
   const okColor = '#3d9a5f';
   const warnColor = theme.colors.textSecondary;
 

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -181,11 +181,19 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     measuredDimsRef.current = new Map();
     prevMeasuredSigRef.current = '';
     const doc = { components: componentsRef.current, edges: edgesRef.current };
-    void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels }).then(({ nodes, edges: e }) => {
-      if (!alive) return;
-      setBuilt({ nodes, edges: e as Edge[] });
-      setLayoutReady(false);
-    });
+    void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels })
+      .then(({ nodes, edges: e }) => {
+        if (!alive) return;
+        setBuilt({ nodes, edges: e as Edge[] });
+        setLayoutReady(false);
+      })
+      .catch((err) => {
+        console.warn('[subsystem-graph] initial layout failed:', err);
+        if (!alive) return;
+        // Reveal the cover even on failure so the UI is not stuck forever.
+        setBuilt({ nodes: [], edges: [] });
+        setLayoutReady(true);
+      });
     return () => { alive = false; };
   }, [layoutKey, maxNodeWidth, showEdgeLabels]);
 
@@ -426,6 +434,18 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     [onFileSelect],
   );
 
+  // Filename-badge clicks on nodes open the drawer through the same path as
+  // the declaration panel's file link (toggle + tree sync, no start line).
+  useEffect(() => {
+    SUBSYSTEM_CALLBACKS.onOpenFile = (componentId: string) => {
+      const comp = components.find((c) => c.id === componentId);
+      if (comp?.file) onOpenDeclarationFile(comp.file);
+    };
+    return () => {
+      SUBSYSTEM_CALLBACKS.onOpenFile = undefined;
+    };
+  }, [components, onOpenDeclarationFile]);
+
   // Detail-panel links: related-name clicks select the matching component —
   // resolved by id, name, or symbol (call labels may carry a trailing `()`).
   const resolveRelatedComponent = useCallback(

package/src/subsystem/formatDeclaration.ts

@@ -7,32 +7,46 @@
  * handles all formatting.
  */
 
-import type { SubsystemComponent } from './model';
+import type { SubsystemComponent, SubsystemComponentConstruct } from './model';
 import type { GraphifyComponentDetail } from '../graphify';
 
+const TYPE_FAMILY_CONSTRUCTS: ReadonlySet<string> = new Set([
+  'interface',
+  'type_alias',
+  'enum',
+]);
+
 export function generateDeclarationString(component: SubsystemComponent): string {
   const detail = component.detail;
-  const kind = detail?.kind ?? component.kind;
+  // Type-family constructs own their rendering even when the detail payload
+  // is the shared `type` shape — the construct says which keyword is honest.
+  const construct = TYPE_FAMILY_CONSTRUCTS.has(component.construct)
+    ? component.construct
+    : detail?.kind ?? component.construct;
   const rawName = component.symbol || component.name || 'untitled';
   // Strip class/object prefix from dotted symbols (e.g. "SessionReader.normalize" → "normalize").
   const name = rawName.includes('.') ? rawName.split('.').pop()! : rawName;
 
-  switch (kind) {
+  switch (construct) {
     case 'class':
       return generateClass(name, detail);
     case 'function':
       return generateFunction(name, detail);
     case 'method':
       return generateMethod(name, detail);
-    case 'type':
-      return generateType(name, detail);
+    case 'interface':
+    case 'type_alias':
+    case 'enum':
+      return generateType(name, component.construct, detail);
     case 'module':
       return generateModule(detail);
+    case 'store':
+      return generateStore(name, detail);
     case 'external':
       // Not valid TypeScript — caller should handle formatting.
       return `external '${detail?.kind === 'external' ? detail.label : name}'`;
     default:
-      return `${kind} ${name}`;
+      return `${construct} ${name}`;
   }
 }
 
@@ -48,7 +62,7 @@ function formatParams(params: { name?: string; type: string }[]): string {
 }
 
 // ---------------------------------------------------------------------------
-// Per-kind generators
+// Per-construct generators
 // ---------------------------------------------------------------------------
 
 function generateClass(name: string, detail?: GraphifyComponentDetail): string {
@@ -98,16 +112,31 @@ function generateMethod(name: string, detail?: GraphifyComponentDetail): string
   return `class ${hostClass} {\n  ${name}(${params})${ret};\n}`;
 }
 
-function generateType(name: string, detail?: GraphifyComponentDetail): string {
+function generateType(
+  name: string,
+  construct: SubsystemComponentConstruct,
+  detail?: GraphifyComponentDetail,
+): string {
+  // The type-family constructs render their declaration keyword honestly —
+  // the construct itself says interface / type (alias) / enum / variable.
   const tpe = detail?.kind === 'type' ? detail : undefined;
   const props = (tpe?.properties ?? [])
     .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
     .join('\n');
 
-  if (props) {
-    return `interface ${name} {\n${props}\n}`;
+  switch (construct) {
+    case 'enum':
+      return `enum ${name} { ${(tpe?.properties ?? []).map((p) => p.name).join(', ')} }`;
+    case 'type_alias':
+      return props
+        ? `type ${name} = {\n${props}\n};`
+        : `type ${name} = unknown;`;
+    default:
+      if (props) {
+        return `interface ${name} {\n${props}\n}`;
+      }
+      return `interface ${name} {}`;
   }
-  return `interface ${name} {}`;
 }
 
 function generateModule(detail?: GraphifyComponentDetail): string {
@@ -126,3 +155,20 @@ function generateModule(detail?: GraphifyComponentDetail): string {
 
   return parts.join('\n') || `module {}`;
 }
+
+/**
+ * A store renders as its retained state — ambient `declare const` lines for
+ * the state members, never a class/method stub. The node's name labels the
+ * block; the access mechanism lives in separate accessor nodes.
+ */
+function generateStore(name: string, detail?: GraphifyComponentDetail): string {
+  const store = detail?.kind === 'store' ? detail : undefined;
+  const props = (store?.properties ?? [])
+    .map((p) => `declare const ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  if (!props) {
+    return `// store: ${name} — no captured state members`;
+  }
+  return `// store: ${name}\n${props}`;
+}

package/src/subsystem/model.test.ts

@@ -36,11 +36,30 @@ describe('subsystem graph model', () => {
     expect(converted[0].target).toBe('reader');
   });
 
+  test('buildSubsystemGraph tolerates external components with no file', async () => {
+    const withExternal: SubsystemComponent[] = [
+      ...comps,
+      {
+        id: "proposed-watcher",
+        name: "watchDir",
+        kind: "external",
+        // Intentionally omit file/purl — agents often leave these off for externals.
+        file: undefined as unknown as string,
+        purl: undefined as unknown as string,
+      },
+    ];
+    const { nodes } = await buildSubsystemGraph({
+      components: withExternal,
+      edges: [{ id: 'e3', from: 'reader', to: 'proposed-watcher', mechanism: 'feeds' }],
+    });
+    expect(nodes.find((n) => n.id === 'proposed-watcher')).toBeDefined();
+  });
+
   test('buildSubsystemGraph creates external stub nodes for non-component targets', async () => {
     const { nodes, edges: gEdges } = await buildSubsystemGraph({ components: comps, edges });
     const external = nodes.find((n) => n.id === 'external:host');
     expect(external).toBeDefined();
-    expect(external!.data.component.kind).toBe('external');
+    expect(external!.data.component.construct).toBe('external');
     const crossEdge = gEdges.find((e) => e.target === 'external:host');
     expect(crossEdge).toBeDefined();
   });
@@ -62,14 +81,27 @@ describe('subsystem graph model', () => {
   });
 
   test('deriveNameFromSymbol is consistent per kind', () => {
-    // class/type/module/function use the symbol as-is.
-    expect(deriveNameFromSymbol('SessionReader', 'class')).toBe('SessionReader');
-    expect(deriveNameFromSymbol('SessionRecord', 'type')).toBe('SessionRecord');
-    // falls back to existing name when no symbol.
-    expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader');
+    // brace-bodied constructs wear {}; module uses the symbol as-is.
+    expect(deriveNameFromSymbol('SessionReader', 'class')).toBe('SessionReader {}');
+    expect(deriveNameFromSymbol('SessionRecord', 'type_alias')).toBe('SessionRecord {}');
+    expect(deriveNameFromSymbol('transcript', 'module')).toBe('transcript');
+    // falls back to existing name when no symbol (still brace-decorated).
+    expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader {}');
     expect(deriveNameFromSymbol('', 'external', 'trail-viewer-host')).toBe('trail-viewer-host');
   });
 
+  test('executable constructs wear () on the node', () => {
+    expect(deriveNameFromSymbol('createSubsystemGraph', 'function')).toBe('createSubsystemGraph()');
+    // methods keep the dotted ownership symbol and wear the parens
+    expect(deriveNameFromSymbol('SessionCache.put', 'method')).toBe('SessionCache.put()');
+    // already-parenthesized labels don't double up
+    expect(deriveNameFromSymbol('run()', 'function')).toBe('run()');
+    // data-shaped constructs stay bare
+    expect(deriveNameFromSymbol('ROOT', 'store')).toBe('ROOT');
+    // brace bodies don't double up
+    expect(deriveNameFromSymbol('Foo {}', 'class')).toBe('Foo {}');
+  });
+
   test('deriveNameFromSymbol falls back to file basename for modules', () => {
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'transcript.ts')).toBe('transcript');
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'src/event-processors/index.ts')).toBe('index');