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

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;