@principal-ai/subsystems-react 0.20.6 → 0.21.1

package/src/subsystem/formatDeclaration.test.ts

@@ -25,7 +25,7 @@ describe('generateDeclarationString — custom_entity', () => {
       entityKind: 'agent',
       file: '',
       purl: 'pkg:github/novatech/facilities-ops',
-      detail: {
+      declaration: {
         kind: 'custom_entity',
         attributes: [
           { key: 'slack', value: 'novatech/facilities-ops' },
@@ -37,4 +37,79 @@ describe('generateDeclarationString — custom_entity', () => {
       "entity 'OpsInsightAgent' — agent\n  slack: novatech/facilities-ops\n  permission: propose-only",
     );
   });
+});
+
+describe('generateDeclarationString — type family', () => {
+  const typed = (declaration: SubsystemComponent['declaration'], construct: SubsystemComponent['construct'] = 'type_alias') => {
+    const component: SubsystemComponent = {
+      id: 't',
+      name: 'StudioMessageSubscriber',
+      symbol: 'StudioMessageSubscriber',
+      construct,
+      file: 'packages/subsystems-studio/src/mainview/rpc.ts',
+      purl: 'pkg:github/principal-ai/subsystem-modeling',
+      declaration,
+    };
+    return generateDeclarationString(component);
+  };
+
+  test('generic callable alias renders its signature, not `= unknown`', () => {
+    expect(
+      typed({
+        kind: 'type',
+        generics: [{ name: 'K', constraint: 'keyof StudioMessages' }],
+        signature: {
+          parameters: [{ name: 'payload', type: 'StudioMessages[K]' }],
+          returnType: 'void',
+        },
+      }),
+    ).toBe('type StudioMessageSubscriber<K extends keyof StudioMessages> = (payload: StudioMessages[K]) => void;');
+  });
+
+  test('plain callable alias defaults return type to void', () => {
+    expect(
+      typed({
+        kind: 'type',
+        signature: { parameters: [{ name: 'req', type: 'Request' }] },
+      }),
+    ).toBe('type StudioMessageSubscriber = (req: Request) => void;');
+  });
+
+  test('rhs override wins over the structured shapes', () => {
+    expect(
+      typed({
+        kind: 'type',
+        properties: [{ name: 'id', type: 'string' }],
+        rhs: '{ [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] }',
+      }),
+    ).toBe('type StudioMessageSubscriber = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };');
+  });
+
+  test('generic + rhs render the type parameters in the header', () => {
+    expect(
+      typed({
+        kind: 'type',
+        generics: [{ name: 'T' }],
+        rhs: '{ [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] }',
+      }),
+    ).toBe('type StudioMessageSubscriber<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };');
+  });
+
+  test('plain reference alias renders through aliasOf', () => {
+    expect(typed({ kind: 'type', aliasOf: 'ServerSessionRow[]' })).toBe(
+      'type StudioMessageSubscriber = ServerSessionRow[];',
+    );
+  });
+
+  test('union alias joins its alternatives', () => {
+    expect(
+      typed({ kind: 'type', unionOf: ["'idle'", "'busy'", "'error'"] }),
+    ).toBe("type StudioMessageSubscriber = 'idle' | 'busy' | 'error';");
+  });
+
+  test('enum renders named members with values', () => {
+    expect(
+      typed({ kind: 'type', enumMembers: [{ name: 'Running', value: "'running'" }] }, 'enum'),
+    ).toBe("enum StudioMessageSubscriber { Running = 'running' }");
+  });
 });

package/src/subsystem/formatDeclaration.ts

@@ -1,5 +1,6 @@
 /**
- * Generate a TypeScript declaration string from a SubsystemComponent's detail.
+ * Generate a TypeScript declaration string from a SubsystemComponent's
+ * structured `declaration`.
  *
  * This is the "source code" that Prettier will format. The output is valid
  * TypeScript (except for `external`, which is handled separately). The string
@@ -17,34 +18,34 @@ const TYPE_FAMILY_CONSTRUCTS: ReadonlySet<string> = new Set([
 ]);
 
 export function generateDeclarationString(component: SubsystemComponent): string {
-  const detail = component.detail;
-  // Type-family constructs own their rendering even when the detail payload
-  // is the shared `type` shape — the construct says which keyword is honest.
+  const declaration = component.declaration;
+  // Type-family constructs own their rendering even when the declaration
+  // 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;
+    : declaration?.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 (construct) {
     case 'class':
-      return generateClass(name, detail);
+      return generateClass(name, declaration);
     case 'function':
-      return generateFunction(name, detail);
+      return generateFunction(name, declaration);
     case 'method':
-      return generateMethod(name, detail);
+      return generateMethod(name, declaration);
     case 'interface':
     case 'type_alias':
     case 'enum':
-      return generateType(name, component.construct, detail);
+      return generateType(name, component.construct, declaration);
     case 'module':
-      return generateModule(detail);
+      return generateModule(declaration);
     case 'store':
-      return generateStore(name, detail);
+      return generateStore(name, declaration);
     case 'external':
       // Not valid TypeScript — caller should handle formatting.
-      return `external '${detail?.kind === 'external' ? detail.label : name}'`;
+      return `external '${declaration?.kind === 'external' ? declaration.label : name}'`;
     case 'custom_entity':
       // An actor, not code — no declaration to generate. Renders as a
       // non-TypeScript block: `entity 'Name' — kind` followed by the authored
@@ -52,7 +53,7 @@ export function generateDeclarationString(component: SubsystemComponent): string
       // bypass Prettier.
     {
       const kindLabel = component.entityKind ? ` — ${component.entityKind}` : '';
-      const attrs = detail?.kind === 'custom_entity' ? detail.attributes : [];
+      const attrs = declaration?.kind === 'custom_entity' ? declaration.attributes : [];
       const attrLines = attrs.map((a) => `  ${a.key}: ${a.value}`).join('\n');
       return attrLines
         ? `entity '${name}'${kindLabel}\n${attrLines}`
@@ -78,8 +79,8 @@ function formatParams(params: { name?: string; type: string }[]): string {
 // Per-construct generators
 // ---------------------------------------------------------------------------
 
-function generateClass(name: string, detail?: GraphifyComponentDetail): string {
-  const cls = detail?.kind === 'class' ? detail : undefined;
+function generateClass(name: string, declaration?: GraphifyComponentDetail): string {
+  const cls = declaration?.kind === 'class' ? declaration : undefined;
   const parts: string[] = [`class ${name}`];
 
   if (cls?.extends && cls.extends.length > 0) {
@@ -110,15 +111,15 @@ function generateClass(name: string, detail?: GraphifyComponentDetail): string {
   return parts.join(' ');
 }
 
-function generateFunction(name: string, detail?: GraphifyComponentDetail): string {
-  const fn = detail?.kind === 'function' ? detail : undefined;
+function generateFunction(name: string, declaration?: GraphifyComponentDetail): string {
+  const fn = declaration?.kind === 'function' ? declaration : undefined;
   const params = formatParams(fn?.parameters ?? []);
   const ret = fn?.returnType ? `: ${fn.returnType}` : '';
   return `function ${name}(${params})${ret};`;
 }
 
-function generateMethod(name: string, detail?: GraphifyComponentDetail): string {
-  const m = detail?.kind === 'method' ? detail : undefined;
+function generateMethod(name: string, declaration?: GraphifyComponentDetail): string {
+  const m = declaration?.kind === 'method' ? declaration : undefined;
   const hostClass = m?.hostClass ?? 'Host';
   const params = formatParams(m?.parameters ?? []);
   const ret = m?.returnType ? `: ${m.returnType}` : '';
@@ -128,32 +129,54 @@ function generateMethod(name: string, detail?: GraphifyComponentDetail): string
 function generateType(
   name: string,
   construct: SubsystemComponentConstruct,
-  detail?: GraphifyComponentDetail,
+  declaration?: 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 tpe = declaration?.kind === 'type' ? declaration : undefined;
+  const params = (tpe?.generics ?? [])
+    .map((g) => `${g.name}${g.constraint ? ` extends ${g.constraint}` : ''}`)
+    .join(', ');
+  const header = params ? `${name}<${params}>` : name;
+
+  // Verbatim RHS escape hatch — shown as-is when the shape doesn't fit one
+  // of the structured buckets below. Wins over everything else.
+  if (tpe?.rhs) return `type ${header} = ${tpe.rhs};`;
+  if (tpe?.aliasOf) return `type ${header} = ${tpe.aliasOf};`;
+  if (tpe?.signature) {
+    const sigParams = formatParams(tpe.signature.parameters ?? []);
+    const ret = tpe.signature.returnType ?? 'void';
+    return `type ${header} = (${sigParams}) => ${ret};`;
+  }
+  if (tpe?.unionOf?.length) {
+    return `type ${header} = ${tpe.unionOf.join(' | ')};`;
+  }
+  if (construct === 'enum') {
+    const members = tpe?.enumMembers?.length
+      ? tpe.enumMembers.map((m) => `${m.name}${m.value ? ` = ${m.value}` : ''}`).join(', ')
+      : (tpe?.properties ?? []).map((p) => p.name).join(', ');
+    return `enum ${header} { ${members} }`;
+  }
+
   const props = (tpe?.properties ?? [])
     .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
     .join('\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;`;
+        ? `type ${header} = {\n${props}\n};`
+        : `type ${header} = unknown;`;
     default:
       if (props) {
-        return `interface ${name} {\n${props}\n}`;
+        return `interface ${header} {\n${props}\n}`;
       }
-      return `interface ${name} {}`;
+      return `interface ${header} {}`;
   }
 }
 
-function generateModule(detail?: GraphifyComponentDetail): string {
-  const mod = detail?.kind === 'module' ? detail : undefined;
+function generateModule(declaration?: GraphifyComponentDetail): string {
+  const mod = declaration?.kind === 'module' ? declaration : undefined;
   if (!mod) return 'module {}';
 
   const parts: string[] = [];
@@ -174,14 +197,15 @@ function generateModule(detail?: GraphifyComponentDetail): string {
  * 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;
+function generateStore(name: string, declaration?: GraphifyComponentDetail): string {
+  const store = declaration?.kind === 'store' ? declaration : undefined;
+  const backing = store?.storage ? `\n// backing: ${store.storage}` : '';
   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} — no captured state members${backing}`;
   }
-  return `// store: ${name}\n${props}`;
+  return `// store: ${name}${backing}\n${props}`;
 }

package/src/subsystem/model.test.ts

@@ -17,26 +17,28 @@ import {
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
 
 const comps: SubsystemComponent[] = [
-  { id: 'reader', name: 'SessionReader', kind: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
-  { id: 'transcript', name: 'transcript', kind: 'module', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { id: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { id: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
 ];
 
-const edges: SubsystemComponentEdge[] = [
-  { id: 'e1', from: 'transcript', to: 'reader', mechanism: 'imports' },
+const relations = [
+  { id: 'e1', from: 'transcript', to: 'reader', relationType: 'imports' as const },
   // 'host' is NOT a component — this is the cross-package external case.
-  { id: 'e2', from: 'reader', to: 'host', mechanism: 'imports', refs: ['bun/index.ts'] },
+  { id: 'e2', from: 'reader', to: 'host', relationType: 'imports' as const, refs: ['bun/index.ts'] },
 ];
 
+const doc = { components: comps, relations };
+
 describe('subsystem graph model', () => {
   test('converts all components to flat component nodes', () => {
-    const nodes = convertSubsystemToNodes({ components: comps, edges });
+    const nodes = convertSubsystemToNodes(doc);
     const components = nodes.filter((n) => n.type === 'subsystem-component');
     expect(components).toHaveLength(comps.length);
     expect(components.every((n) => n.type === 'subsystem-component')).toBe(true);
   });
 
   test('converts edges with directed markers', () => {
-    const converted = convertSubsystemToEdges({ components: comps, edges });
+    const converted = convertSubsystemToEdges(doc);
     expect(converted).toHaveLength(2);
     expect(converted[0].source).toBe('transcript');
     expect(converted[0].target).toBe('reader');
@@ -48,7 +50,7 @@ describe('subsystem graph model', () => {
       {
         id: "proposed-watcher",
         name: "watchDir",
-        kind: "external",
+        construct: "external",
         // Intentionally omit file/purl — agents often leave these off for externals.
         file: undefined as unknown as string,
         purl: undefined as unknown as string,
@@ -56,13 +58,18 @@ describe('subsystem graph model', () => {
     ];
     const { nodes } = await buildSubsystemGraph({
       components: withExternal,
-      edges: [{ id: 'e3', from: 'reader', to: 'proposed-watcher', mechanism: 'feeds' }],
+      relations: [],
+      walkthroughs: [{
+        id: 'w1',
+        title: 'feed',
+        steps: [{ from: 'reader', to: 'proposed-watcher', mechanism: 'feeds', file: 'x.ts', line: 1 }],
+      }],
     });
     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 { nodes, edges: gEdges } = await buildSubsystemGraph(doc);
     const external = nodes.find((n) => n.id === 'external:host');
     expect(external).toBeDefined();
     expect(external!.data.component.construct).toBe('external');
@@ -71,7 +78,7 @@ describe('subsystem graph model', () => {
   });
 
   test('buildSubsystemGraph positions nodes via ELK (non-zero coords)', async () => {
-    const { nodes } = await buildSubsystemGraph({ components: comps, edges });
+    const { nodes } = await buildSubsystemGraph(doc);
     const placed = nodes.filter((n) => n.type === 'subsystem-component' && n.position);
     expect(placed.length).toBeGreaterThan(0);
     // ELK (or the grid fallback) gives finite coordinates.
@@ -218,7 +225,7 @@ describe('subsystem graph model', () => {
         { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
         { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
-      edges: [],
+      relations: [],
     });
     expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
       processGroupNodeId('app/host'),
@@ -245,7 +252,12 @@ describe('subsystem graph model', () => {
         { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
         { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
       ],
-      edges: [{ id: 'e1', from: 'a', to: 'b', mechanism: 'calls' }],
+      relations: [],
+      walkthroughs: [{
+        id: 'w1',
+        title: 'call',
+        steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'a.ts', line: 1 }],
+      }],
     });
     expect(regions.map((r) => r.key)).toEqual(['app/host']);
     expect((nodes.find((n) => n.id === 'solo') as { parentId?: string }).parentId).toBeUndefined();
@@ -253,7 +265,7 @@ describe('subsystem graph model', () => {
   });
 
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
-    const base = { components: comps, edges };
+    const base = doc;
     const withRef = {
       components: comps.map((c, i) =>
         i === 0
@@ -268,7 +280,7 @@ describe('subsystem graph model', () => {
             }
           : c,
       ),
-      edges,
+      relations,
     };
     expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withRef));
   });