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

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');

package/src/subsystem/model.ts

@@ -2,7 +2,7 @@
  * Subsystem component-graph data model + converters.
  *
  * A subsystem snapshot (see the "Subsystem artifact: facets" topic) is captured
- * as component nodes (kind-tagged source units), file refs, integration edges,
+ * as component nodes (construct-tagged source units), file refs, integration edges,
  * and entry points. This module defines the minimal document shape for the
  * *graph* facet and converts it to React Flow nodes/edges — packages render as
  * subgraphs, only cross-package edges leave the box, and shared seams
@@ -21,14 +21,30 @@ import { computeElkLayout } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
-export type SubsystemComponentKind =
+export type SubsystemComponentConstruct =
   | 'class'
   | 'function'
   | 'method'
-  | 'type'
+  | 'interface'
+  | 'type_alias'
+  | 'enum'
   | 'module'
+  | 'store'
   | 'external';
 
+/**
+ * Semantic role — where the node sits in the topology, orthogonal to
+ * `construct` (what it is). Roles have *inherited* anatomy: an entry renders
+ * as its real code shape (function dispatcher, type contract); a service has
+ * no source at all (`construct: 'external'` + purl identity). Contrast with
+ * `construct: 'store'`, which introduces its own anatomy (the state block) —
+ * that is why store is a construct and not a role. Role nodes must stay anchored to real code: an
+ * `entry` is a boundary element (route dispatcher, message contract) carrying
+ * the wire address as identity; a `service` is an external system the process
+ * calls out to (identity via purl, no `process` — it belongs to no region).
+ */
+export type SubsystemComponentRole = 'entry' | 'service';
+
 // ---------------------------------------------------------------------------
 // Declaration tokens — structured source representation
 // ---------------------------------------------------------------------------
@@ -65,19 +81,48 @@ export type SubsystemEdgeMechanism =
   | 'contains'
   | 'feeds'
   | 'produces'
+  | 'writes'
+  | 'reads'
+  | 'watches'
   | 'registers-into';
 
-/** A component node — the named unit, kind-tagged; `file` is its location. */
+/** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   id: string;
   name: string;
-  kind: SubsystemComponentKind;
+  /**
+   * The node's construct — what it IS as a declaration (class, function,
+   * method, interface, type alias, enum, store, external), driving node
+   * anatomy, color, badge, and the verification strategy. Every construct
+   * anchors to a definition; runtime occurrences (variables, activations,
+   * instances) are NOT constructs — they belong to a future execution-mode
+   * graph whose occurrence nodes reference these definitions. Ontology:
+   * construct = what it is, role = where it sits, process = where it runs.
+   */
+  construct: SubsystemComponentConstruct;
   /** Source location the component lives in (repo-root-relative path). */
   file: string;
   /** PURL identifying the repo or package this component lives in (for subgraph grouping). */
   purl: string;
   /** One-line purpose shown on the node. */
   purpose?: string;
+  /**
+   * Semantic role — where the node sits in the topology (boundary element,
+   * external system), orthogonal to `construct` (what it is). Drives the
+   * glyph and the edge-pairing rules: boundary-crossing edges must terminate
+   * at an entry or a service. Retained state is NOT a role — it is
+   * `construct: 'store'` (state-block anatomy, `writes`/`reads`/`watches`
+   * inbound, `produces` outbound).
+   */
+  role?: SubsystemComponentRole;
+  /**
+   * Runtime process membership — which deployment unit this node is a
+   * member of (e.g. `trail-viewer/host`, `trail-viewer/renderer`). Nodes
+   * sharing a `process` are drawn inside one boundary region (grouping is
+   * `process ?? purl`); nodes without one sit outside every boundary
+   * (external actors, services, libraries).
+   */
+  process?: string;
   /** A symbol this component exposes / is (the node's identity). */
   symbol?: string;
   /**
@@ -96,7 +141,7 @@ export interface SubsystemComponent {
   capture?: 'edited' | 'analyzed' | 'referenced';
   /**
    * Graphify drill-down detail for this component, when the facet is anchored
-   * to a graphify node. Discriminated by kind (class/function/type/module/
+   * to a graphify node. Discriminated by kind (class/function/type/module/store/
    * external); rendered in the detail panel on click.
    */
   detail?: GraphifyComponentDetail;
@@ -133,10 +178,42 @@ export interface SubsystemComponentEdge {
 }
 
 /**
- * Derive a consistent display `name` from a code `symbol` + kind.
+ * A single site on an existing edge — the exact `file:line` where that edge's
+ * seam manifests for a given flow. The edge stays the abstract contract
+ * (`from`, `to`, `mechanism`); a throughline step picks the concrete
+ * manifestation. One edge can appear in many steps.
+ */
+export interface SubsystemThroughlineStep {
+  /** Id of the existing edge this hop traverses. */
+  edgeId: string;
+  /** Repo-root-relative path of the file where the edge fires. */
+  file: string;
+  /** 1-based line of the site within `file`. */
+  line: number;
+  /**
+   * Frame name for this hop — the function/method/symbol on the stack at
+   * this site. Optional so existing throughlines keep working; when set the
+   * flows list shows it instead of mechanism + filename.
+   */
+  symbol?: string;
+}
+
+/**
+ * An ordered execution story over a graph's edges — each step references an
+ * existing edge and the exact site where that relationship fires for a flow;
+ * ordering is the array. One throughline per flow (save flow, load flow, …).
+ */
+export interface SubsystemThroughline {
+  id: string;
+  title: string;
+  steps: SubsystemThroughlineStep[];
+}
+
+/**
+ * Derive a consistent display `name` from a code `symbol` + construct.
  *
- * `symbol` is the source of truth (fully-qualified code identity). For most
- * kinds the name is the symbol itself or its last dotted segment:
+ * `symbol` is the source of truth (fully-qualified code identity). The name
+ * is the symbol itself:
  *  - class/type/module/function/script/...  symbol → symbol (e.g. `SessionReader`)
  *  - method                               `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
  *  - module, no symbol → basename of `file` (e.g. `transcript.ts` → `transcript`) —
@@ -145,20 +222,37 @@ export interface SubsystemComponentEdge {
  */
 export function deriveNameFromSymbol(
   symbol: string | undefined,
-  kind: SubsystemComponentKind,
+  construct: SubsystemComponentConstruct,
   existingName?: string,
   file?: string,
 ): string {
+  let name: string | undefined;
   if (symbol && symbol.trim()) {
-    return symbol;
-  }
-  // Module nodes without a symbol are whole files → use the file basename.
-  if (kind === 'module' && file) {
+    name = symbol;
+  } else if (construct === 'module' && file) {
     const base = file.split('/').pop() ?? '';
     const clean = base.replace(/\.[^.]+$/, ''); // strip extension
-    if (clean) return clean;
+    if (clean) name = clean;
+  }
+  if (!name) name = existingName ?? 'untitled';
+
+  // Decoration = what the drill-down shows. Executable constructs wear `()`
+  // (a signature you can call); brace-bodied constructs wear ` {}` (a member
+  // body — fields for types/interfaces/enums, fields+methods for classes).
+  // Everything else (store, variable, module, external) renders bare.
+  if ((construct === 'function' || construct === 'method') && !name.endsWith('()')) {
+    name = `${name}()`;
+  }
+  if (
+    (construct === 'class' ||
+      construct === 'interface' ||
+      construct === 'type_alias' ||
+      construct === 'enum') &&
+    !name.endsWith('{}')
+  ) {
+    name = `${name} {}`;
   }
-  return existingName ?? 'untitled';
+  return name;
 }
 
 /**
@@ -188,6 +282,8 @@ export function formatPurl(purl: string): string {
 export interface SubsystemGraphDocument {
   components: SubsystemComponent[];
   edges: SubsystemComponentEdge[];
+  /** Ordered execution stories over the graph's edges (one per flow). */
+  throughlines?: SubsystemThroughline[];
 }
 
 // ---------------------------------------------------------------------------
@@ -202,6 +298,8 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
    *  lives in that file (spotlighted), false otherwise (dimmed). Absent when
    *  no file is open — render neutrally. */
   fileMatch?: boolean;
+  /** True while this node is on an opened-but-unselected flow. */
+  dimmed?: boolean;
 }
 
 export type SubsystemGraphNode = Node<SubsystemGraphNodeData, SubsystemGraphNodeType>;
@@ -237,6 +335,9 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   contains: '#6c5ce7', // indigo
   feeds: '#22c55e', // green — data-flow into a processor
   produces: '#e07a5f', // terracotta — emits an output type
+  writes: '#2f9e44', // deep green — mutates retained state
+  reads: '#0ea5e9', // sky — pulls from retained state
+  watches: '#9ca3af', // gray — observes, owns nothing
   'registers-into': '#ff6b35', // orange
 };
 
@@ -256,6 +357,9 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   contains: 'solid',
   feeds: 'solid',
   produces: 'solid',
+  writes: 'solid',
+  reads: 'solid',
+  watches: 'dashed',
   'registers-into': 'dashed',
 };
 
@@ -274,14 +378,19 @@ export function packageColor(name: string): string {
   return palette[h % palette.length];
 }
 
-/** Color per component kind — the informative signal (rather than package). */
-export const KIND_COLOR: Record<SubsystemComponentKind, string> = {
-  class: '#0893d2', // blue
-  function: '#6c5ce7', // indigo
-  method: '#d4a03c', // gold
-  type: '#e07a5f', // terracotta
-  module: '#4ec9b0', // teal
-  external: '#b48ead', // purple
+/** Color per semantic role — applied ONLY to the role badge (top-right tab on
+ *  nodes that carry a role). The node border stays construct-colored. Note:
+ *  `service` currently equals the old class hex; harmless while role badges
+ *  are the only surface using it, but pick a distinct value if roles ever
+ *  take over node borders. */
+export const ROLE_COLOR: Record<SubsystemComponentRole, string> = {
+  entry: '#ff6b35', // orange — boundary element
+  service: '#0893d2', // blue — external system
+};
+
+export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
+  entry: 'entry',
+  service: 'service',
 };
 
 /**
@@ -297,12 +406,16 @@ export function convertSubsystemToNodes(
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   const { maxNodeWidth } = opts;
-  // Group components by package.
+  // Group components into boundary regions by process when authored, else by
+  // package. Process is runtime membership (drawn as one boundary region);
+  // purl is code identity — nodes without a process (external actors,
+  // services, libraries) fall back to purl and sit outside every boundary.
   const byPkg = new Map<string, SubsystemComponent[]>();
   for (const c of doc.components) {
-    const list = byPkg.get(c.purl) ?? [];
+    const regionKey = c.process ?? c.purl;
+    const list = byPkg.get(regionKey) ?? [];
     list.push(c);
-    byPkg.set(c.purl, list);
+    byPkg.set(regionKey, list);
   }
 
   const nodes: SubsystemGraphNode[] = [];
@@ -322,7 +435,7 @@ export function convertSubsystemToNodes(
       const row = Math.floor(i / COLS);
       // Estimate rendered node width from the longest text line so ELK reserves
       // the right space (names can wrap, so we cap at the configurable max).
-      const text = [c.symbol, c.name, c.file.split('/').pop() ?? '']
+      const text = [c.symbol, c.name, c.file?.split('/').pop() ?? '']
         .filter((t): t is string => !!t)
         .sort((a, b) => b.length - a.length)[0];
       const cap = maxNodeWidth ?? 300;
@@ -370,7 +483,7 @@ export function convertSubsystemToEdges(doc: SubsystemGraphDocument): SubsystemG
       target: targetId,
       data: { mechanism: e.mechanism, refs: e.refs },
       type: 'subsystem-edge',
-      markerEnd: { type: MarkerType.ArrowClosed, color, width: 16, height: 16 },
+      markerEnd: { type: MarkerType.ArrowClosed, color, width: 32, height: 32 },
       style: { color, stroke: color, strokeDasharray: style === 'dashed' ? '6 4' : undefined },
       // `label` feeds ELK's label-space reservation only; the visible label is
       // rendered by the custom SubsystemEdge as an HTML overlay.
@@ -387,8 +500,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemGraphDocument, 'components' | 'edges'>,
 ): string {
   const components = doc.components
-    .map(({ id, purl, name, symbol, kind, file, purpose }) =>
-      [id, purl, name, symbol ?? '', kind, file, purpose ?? ''].join('\0'))
+    .map(({ id, purl, name, symbol, construct, file, purpose, process }) =>
+      [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? ''].join('\0'))
     .sort()
     .join('\n');
   const edgeKey = doc.edges
@@ -437,7 +550,7 @@ export async function buildSubsystemGraph(
         component: {
           id: extId,
           name: label,
-          kind: 'external',
+          construct: 'external',
           purl: 'external',
           file: '',
           purpose: 'cross-package integration target (not a member node)',

package/src/subsystem/nodes.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+import { EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility, hexWithAlpha } from './nodes';
+
+describe('hexWithAlpha', () => {
+  test('appends a two-digit alpha to #rrggbb', () => {
+    expect(hexWithAlpha('#4ec9b0', 1)).toBe('#4ec9b0ff');
+    expect(hexWithAlpha('#4ec9b0', EDGE_DIM_ALPHA)).toBe('#4ec9b026');
+  });
+
+  test('expands #rgb', () => {
+    expect(hexWithAlpha('#abc', 1)).toBe('#aabbccff');
+  });
+
+  test('leaves non-hex values alone', () => {
+    expect(hexWithAlpha('teal', 0.15)).toBe('teal');
+  });
+});
+
+describe('fileMatchForNode', () => {
+  test('no open file → neutral', () => {
+    expect(fileMatchForNode('src/a.ts', null, false)).toBeUndefined();
+  });
+
+  test('open file spotlights matches and dims others', () => {
+    expect(fileMatchForNode('src/a.ts', 'src/a.ts', false)).toBe(true);
+    expect(fileMatchForNode('src/b.ts', 'src/a.ts', false)).toBe(false);
+  });
+
+  test('focused-edge endpoint is not dimmed when it lives in another file', () => {
+    expect(fileMatchForNode('src/target.ts', 'src/source.ts', true)).toBeUndefined();
+    expect(fileMatchForNode('src/source.ts', 'src/source.ts', true)).toBe(true);
+  });
+});
+
+describe('flowElementVisibility', () => {
+  test('nothing open or selected → everything full', () => {
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: false, anySelected: false }))
+      .toEqual({ hidden: false, dimmed: false });
+  });
+
+  test('opened, nothing selected → opened members full, rest hidden', () => {
+    expect(flowElementVisibility({ inOpened: true, inSelected: false, anyOpened: true, anySelected: false }))
+      .toEqual({ hidden: false, dimmed: false });
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: true, anySelected: false }))
+      .toEqual({ hidden: true, dimmed: false });
+  });
+
+  test('selected flow or step full; other opened members dimmed; rest hidden', () => {
+    expect(flowElementVisibility({ inOpened: true, inSelected: true, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: false, dimmed: false });
+    expect(flowElementVisibility({ inOpened: true, inSelected: false, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: false, dimmed: true });
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: true, dimmed: false });
+  });
+});