@principal-ai/subsystems-react 0.20.5 → 0.21.0

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

@@ -155,7 +155,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
       purl: corePurl,
       symbol: 'AnalysisStatus',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [
           { name: 'state', type: "'idle' | 'running' | 'done'" },
@@ -189,7 +189,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       file: 'packages/subsystems-studio/src/bun/verify.ts',
       purl: corePurl,
       symbol: 'VerificationPhase',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [{ name: 'idle' }, { name: 'checking' }, { name: 'done' }],
         usedBy: [],
@@ -261,7 +261,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       file: 'src/session/SessionCache.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionCache',
-      detail: {
+      declaration: {
         kind: 'class',
         methods: [{ nodeId: 'm1', name: 'put', parameters: [{ type: 'SessionRecord' }] }],
         properties: [],
@@ -282,7 +282,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       file: 'src/session/SessionCache.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionCache.put',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'SessionCache',
         parameters: [{ type: 'SessionRecord' }],
@@ -299,7 +299,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
       purl: corePurl,
       purpose: 'retained state — anchored to a state location',
-      detail: { kind: 'store', properties: [{ name: 'ROOT', type: 'string' }, { name: 'INDEX_PATH', type: 'string' }] },
+      declaration: { kind: 'store', properties: [{ name: 'ROOT', type: 'string' }, { name: 'INDEX_PATH', type: 'string' }] },
     },
   },
   {
@@ -495,7 +495,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       construct: 'store',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
       purl: corePurl,
-      detail: {
+      declaration: {
         kind: 'store',
         properties: [
           { name: 'ROOT', type: 'string' },
@@ -516,7 +516,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       file: 'src/session/SessionCache.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionCache',
-      detail: {
+      declaration: {
         kind: 'class',
         methods: [
           { nodeId: 'cm1', name: 'put', parameters: [{ type: 'SessionRecord' }] },
@@ -540,7 +540,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
       purl: corePurl,
       symbol: 'getSubsystemModel',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [{ name: 'graphId', type: 'string' }],
         returnType: 'Promise<StoredSubsystemModel | null>',
@@ -560,7 +560,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       purl: corePurl,
       symbol: 'StudioMessages',
       role: 'entry',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [
           { name: 'subsystemModelChanged', type: 'push' },
@@ -581,7 +581,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       file: 'src/session/SessionCache.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionCache.put',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'SessionCache',
         parameters: [{ name: 'record', type: 'SessionRecord' }],
@@ -599,7 +599,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
       purl: corePurl,
       symbol: 'AnalysisStatus',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [{ name: 'state', type: "'idle' | 'running'" }],
         usedBy: [],
@@ -617,7 +617,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
       file: 'packages/subsystems-studio/src/bun/verify.ts',
       purl: corePurl,
       symbol: 'VerificationPhase',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [{ name: 'idle' }, { name: 'checking' }, { name: 'done' }],
         usedBy: [],
@@ -639,7 +639,7 @@ function AnatomySpotlightsDemo() {
             {label} — {note}
           </div>
           <Row>
-            <JsonCard label="the data — component.detail" value={component.detail} width={320} />
+            <JsonCard label="the data — component.declaration" value={component.declaration} width={320} />
             <RenderPane label="the rendering — ComponentDeclaration">
               <div style={{ width: 360 }}>
                 <ComponentDeclaration component={component} />

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

@@ -1,16 +1,21 @@
 import type {
   SubsystemComponent,
   SubsystemComponentEdge,
+  SubsystemRelation,
+  SubsystemRelationType,
+  SubsystemWalkthrough,
+  SubsystemWalkthroughMechanism,
 } from '../../../subsystem/model';
+import { derivedGraphEdgeId } 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]>,
+  spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, declaration?: GraphifyComponentDetail]>,
 ): SubsystemComponent[] {
-  return spec.map(([id, name, construct, file, purl, purpose, symbol, detail]) => ({
+  return spec.map(([id, name, construct, file, purl, purpose, symbol, declaration]) => ({
     id,
     name,
     construct,
@@ -18,10 +23,56 @@ export function components(
     purl,
     purpose,
     symbol,
-    detail,
+    declaration,
   }));
 }
 
+const RELATION_TYPES = new Set<string>([
+  'imports',
+  'imports_from',
+  're_exports',
+  'defines',
+  'extends',
+  'inherits',
+  'implements',
+  'mixes_in',
+  'method',
+  'references',
+  'contains',
+]);
+
+export function relations(
+  spec: Array<[from: string, to: string, relationType: SubsystemRelationType, refs?: string[]]>,
+): SubsystemRelation[] {
+  return spec.map(([from, to, relationType, refs], i) => ({
+    id: `r${i}`,
+    from,
+    to,
+    relationType,
+    refs,
+  }));
+}
+
+/** Story helper: one walkthrough whose hops derive Set B display edges. */
+export function walkthroughFromHops(
+  id: string,
+  title: string,
+  hops: Array<[from: string, to: string, mechanism: SubsystemWalkthroughMechanism, file: string, line: number]>,
+): SubsystemWalkthrough {
+  return {
+    id,
+    title,
+    steps: hops.map(([from, to, mechanism, file, line]) => ({
+      from,
+      to,
+      mechanism,
+      file,
+      line,
+    })),
+  };
+}
+
+/** @deprecated story helper — prefer `relations` + `walkthroughFromHops`. */
 export function edges(
   spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism'], refs?: string[]]>,
 ): SubsystemComponentEdge[] {
@@ -34,6 +85,40 @@ export function edges(
   }));
 }
 
+/** Split mixed mechanism lists into relations + optional walkthrough for stories. */
+export function graphSpecFromEdges(
+  spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism'], refs?: string[]]>,
+): { relations: SubsystemRelation[]; walkthroughs?: SubsystemWalkthrough[] } {
+  const rels: SubsystemRelation[] = [];
+  const hops: SubsystemWalkthrough['steps'] = [];
+  for (const [from, to, mechanism, refs] of spec) {
+    if (RELATION_TYPES.has(mechanism)) {
+      rels.push({
+        id: derivedGraphEdgeId(from, to, mechanism as SubsystemRelationType),
+        from,
+        to,
+        relationType: mechanism as SubsystemRelationType,
+        refs,
+      });
+    } else {
+      hops.push({
+        from,
+        to,
+        mechanism: mechanism as SubsystemWalkthroughMechanism,
+        file: 'story-placeholder.ts',
+        line: 1,
+      });
+    }
+  }
+  return {
+    relations: rels,
+    walkthroughs:
+      hops.length > 0
+        ? [{ id: 'story-hops', title: 'Story hops', steps: hops }]
+        : undefined,
+  };
+}
+
 export const readerDetail: GraphifyComponentDetail = {
   kind: 'class',
   methods: [
@@ -79,39 +164,28 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
     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',
+    file: 'src/accumulateToAgentSessionEvents.ts',
     purl: 'pkg:github/principal-ai/agent-monitoring',
-    purpose: 'accumulates normalized events into agent session events',
+    purpose: 'folds normalized events into agent session events',
     symbol: 'accumulateToAgentSessionEvents',
   },
   {
     id: 'out',
     name: 'AgentSessionEvent',
     construct: 'interface',
-    file: 'src/event-processing/accumulator.ts',
+    file: 'types/AgentSessionEvent.ts',
     purl: 'pkg:github/principal-ai/agent-monitoring',
-    purpose: 'the subsystem\u2019s output type — an accumulated agent-session event',
+    purpose: 'output event shape',
     symbol: 'AgentSessionEvent',
-    detail: {
+    declaration: {
       kind: 'type',
       properties: [
-        { name: 'sessionName', type: 'string' },
-        { name: 'operation', type: 'AgentSessionEventOperation' },
+        { name: 'sessionId', type: 'string' },
         { name: 'description', type: 'string' },
       ],
       usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'return_type' }],
@@ -120,8 +194,18 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
   },
 ];
 
+const investigateSpec = graphSpecFromEdges([
+  ['v1', 'input', 'produces'],
+  ['v2', 'input', 'produces'],
+  ['input', 'acc', 'feeds'],
+  ['acc', 'out', 'produces'],
+]);
+
+export const investigateOnlyRelations = investigateSpec.relations;
+export const investigateOnlyWalkthroughs = investigateSpec.walkthroughs;
+
+/** @deprecated use investigateOnlyRelations + investigateOnlyWalkthroughs */
 export const investigateOnlyEdges: SubsystemComponentEdge[] = edges([
-  // Concept-level data flow — the LLM's semantic intent.
   ['v1', 'input', 'produces'],
   ['v2', 'input', 'produces'],
   ['input', 'acc', 'feeds'],

package/src/subsystem/ComponentDeclaration.tsx

@@ -138,7 +138,7 @@ function verificationSummary(
   const bits: string[] = [];
   if (v.file) {
     if (!v.file.exists) bits.push('file missing');
-    else if (v.file.symbolDeclared === false) bits.push('symbol not declared in file');
+    else if (v.file.symbolDeclared === false) bits.push('symbol not in graphify');
     else if (v.file.symbolDeclared === true) bits.push('file+symbol ok');
     else bits.push('file exists');
   }

package/src/subsystem/FileDrawer.tsx

@@ -1,7 +1,7 @@
 /**
  * FileDrawer — bottom panel that slides up from the bottom of the graph area
- * to show file / throughline code. Opened by sidebar file-tree clicks,
- * declaration links, and throughline step focus; content is injected as
+ * to show file / walkthrough code. Opened by sidebar file-tree clicks,
+ * declaration links, and walkthrough step focus; content is injected as
  * children by the graph component.
  */