@principal-ai/subsystems-react 0.21.1 → 0.22.0

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

@@ -0,0 +1,287 @@
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import { graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Modules',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const PURL = 'pkg:github/principal-ai/agent-monitoring';
+
+/**
+ * Module frames replace `construct: module`. Each export keeps its real
+ * construct; shared `module` (the source path) draws the file as a boundary.
+ */
+const moduleComponents: SubsystemComponent[] = [
+  {
+    id: 'record',
+    name: 'CodexRolloutRecord',
+    construct: 'type_alias',
+    symbol: 'CodexRolloutRecord',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'parsed rollout record shape',
+    layer: 1,
+  },
+  {
+    id: 'is-rollout',
+    name: 'isCodexRollout',
+    construct: 'function',
+    symbol: 'isCodexRollout',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'type guard for rollout records',
+    layer: 1,
+  },
+  {
+    id: 'parse',
+    name: 'parseTranscript',
+    construct: 'function',
+    symbol: 'parseTranscript',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'parses session transcript lines',
+    layer: 1,
+  },
+  {
+    id: 'tool-name',
+    name: 'extractToolName',
+    construct: 'function',
+    symbol: 'extractToolName',
+    file: 'src/session/paths.ts',
+    module: 'src/session/paths.ts',
+    purl: PURL,
+    purpose: 'pulls tool names from path-like strings',
+    layer: 2,
+  },
+  {
+    id: 'file-path',
+    name: 'extractFilePath',
+    construct: 'function',
+    symbol: 'extractFilePath',
+    file: 'src/session/paths.ts',
+    module: 'src/session/paths.ts',
+    purl: PURL,
+    purpose: 'pulls file paths from tool args',
+    layer: 2,
+  },
+  {
+    id: 'reader',
+    name: 'SessionReader',
+    construct: 'class',
+    symbol: 'SessionReader',
+    file: 'src/session/SessionReader.ts',
+    module: 'src/session/SessionReader.ts',
+    purl: PURL,
+    purpose: 'normalizes a session into universal events',
+    layer: 3,
+  },
+  {
+    id: 'normalize',
+    name: 'normalize',
+    construct: 'method',
+    symbol: 'SessionReader.normalize',
+    file: 'src/session/SessionReader.ts',
+    module: 'src/session/SessionReader.ts',
+    purl: PURL,
+    purpose: 'maps a session into universal events',
+    layer: 3,
+  },
+  {
+    id: 'registry',
+    name: 'registerAgent',
+    construct: 'function',
+    symbol: 'registerAgent',
+    file: 'src/supported-agents.ts',
+    // Singleton module — no frame (same rule as process: need 2+ members).
+    module: 'src/supported-agents.ts',
+    purl: PURL,
+    purpose: 'registers a supported agent (singleton file — no module frame)',
+    layer: 4,
+  },
+];
+
+const moduleEdges = graphSpecFromEdges([
+  ['parse', 'record', 'references'],
+  ['is-rollout', 'record', 'references'],
+  ['reader', 'normalize', 'method'],
+  ['normalize', 'parse', 'calls'],
+  ['normalize', 'tool-name', 'calls'],
+  ['normalize', 'file-path', 'calls'],
+  ['reader', 'registry', 'registers-into'],
+]);
+
+export const ModuleBoundaries: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Module boundaries"
+        description="Concrete exports keep their real construct. Shared `module` (the source path) draws the file as a dashed frame — not `construct: module`. Singleton modules (registerAgent) stay unframed."
+        components={moduleComponents}
+        relations={moduleEdges.relations}
+        walkthroughs={moduleEdges.walkthroughs}
+      />
+    </div>
+  ),
+};
+
+/** Process → module → export nesting (host / renderer). */
+const nestedComponents: SubsystemComponent[] = [
+  {
+    id: 'boot',
+    name: 'boot',
+    construct: 'function',
+    symbol: 'boot',
+    role: 'entry',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Boots the host process',
+    layer: 1,
+  },
+  {
+    id: 'create-host',
+    name: 'createHost',
+    construct: 'function',
+    symbol: 'createHost',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Constructs the host runtime',
+    layer: 1,
+  },
+  {
+    id: 'session-store',
+    name: 'SessionStore',
+    construct: 'store',
+    symbol: 'SessionStore',
+    file: 'src/host/store.ts',
+    module: 'src/host/store.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Retained host session state',
+    layer: 2,
+  },
+  {
+    id: 'write-session',
+    name: 'writeSession',
+    construct: 'function',
+    symbol: 'writeSession',
+    file: 'src/host/store.ts',
+    module: 'src/host/store.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Mutates SessionStore',
+    layer: 2,
+  },
+  {
+    id: 'bridge',
+    name: 'bridge',
+    construct: 'function',
+    symbol: 'bridge',
+    role: 'entry',
+    file: 'src/renderer/bridge.ts',
+    module: 'src/renderer/bridge.ts',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Renderer IPC entry',
+    layer: 3,
+  },
+  {
+    id: 'post-to-host',
+    name: 'postToHost',
+    construct: 'function',
+    symbol: 'postToHost',
+    file: 'src/renderer/bridge.ts',
+    module: 'src/renderer/bridge.ts',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Sends a message to the host',
+    layer: 3,
+  },
+  {
+    id: 'trail-view',
+    name: 'TrailView',
+    construct: 'function',
+    symbol: 'TrailView',
+    framework: 'react',
+    stereotype: 'component',
+    file: 'src/renderer/view.tsx',
+    module: 'src/renderer/view.tsx',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Renders the trail',
+    layer: 4,
+  },
+  {
+    id: 'use-trail',
+    name: 'useTrail',
+    construct: 'function',
+    symbol: 'useTrail',
+    framework: 'react',
+    stereotype: 'hook',
+    file: 'src/renderer/view.tsx',
+    module: 'src/renderer/view.tsx',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Subscribes the view to trail updates',
+    layer: 4,
+  },
+  {
+    id: 'telemetry',
+    name: 'telemetry',
+    construct: 'external',
+    role: 'service',
+    file: '',
+    purl: 'external',
+    purpose: 'External sink — outside every frame',
+    layer: 5,
+  },
+];
+
+const nestedEdges = graphSpecFromEdges([
+  ['boot', 'write-session', 'imports'],
+  ['trail-view', 'bridge', 'imports'],
+  ['trail-view', 'use-trail', 'references'],
+  ['boot', 'create-host', 'calls'],
+  ['create-host', 'write-session', 'calls'],
+  ['write-session', 'session-store', 'writes'],
+  ['bridge', 'boot', 'calls'],
+  ['trail-view', 'post-to-host', 'calls'],
+  ['boot', 'telemetry', 'uses'],
+]);
+
+export const ProcessAndModuleNesting: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Process × module nesting"
+        description="process frames wrap module frames wrap exports. Leaves parent to module:; module groups parent to process: when every member shares that process."
+        components={nestedComponents}
+        relations={nestedEdges.relations}
+        walkthroughs={nestedEdges.walkthroughs}
+      />
+    </div>
+  ),
+};

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

@@ -28,7 +28,7 @@ const processComponents = [
     ['main', 'main', 'function', 'src/host/main.ts', 'pkg:github/principal-ai/principal-studio', 'boots the host process', 'main'],
     ['store', 'SessionStore', 'store', 'src/host/store.ts', 'pkg:github/principal-ai/principal-studio', 'retained host state', 'SessionStore'],
     ['view', 'TrailView', 'function', 'src/renderer/view.tsx', 'pkg:github/principal-ai/principal-studio', 'renders the trail', 'TrailView'],
-    ['bridge', 'bridge', 'module', 'src/renderer/bridge.ts', 'pkg:github/principal-ai/principal-studio', 'IPC bridge to the host', 'bridge'],
+    ['bridge', 'bridge', 'function', 'src/renderer/bridge.ts', 'pkg:github/principal-ai/principal-studio', 'IPC bridge to the host', 'bridge'],
   ]),
   {
     id: 'svc',

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

@@ -84,7 +84,7 @@ const mermaidComponents: SubsystemComponent[] = [
   {
     id: 'helpers',
     name: 'beautifulMermaid',
-    construct: 'module',
+    construct: 'function',
     file: 'industryMarkdown/utils/beautifulMermaid.ts',
     purl: mermaidPurl,
     purpose: 'engine detection, theme\u2192options mapping, SVG post-processing',
@@ -130,11 +130,11 @@ const coreLibPurl = 'pkg:github/principal-ai/principal-view-core-library';
 const graphifyPurl = 'pkg:github/Graphify-Labs/graphify';
 
 const multiRepoComponents = components([
-  ['resolver', 'resolve.ts', 'module', 'packages/subsystems-react/src/graphify/resolve.ts', coreLibPurl, 'consumer-side resolution mirroring graphify rewire tiers', 'createGraphifyTypeResolver'],
-  ['reftypes', 'consolidated.ts', 'module', 'packages/subsystems-react/src/graphify/consolidated.ts', coreLibPurl, 'drill-down payload types carrying ref.nodeId', 'GraphifyParamInfo'],
-  ['detail', 'ComponentDeclaration.tsx', 'module', 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx', coreLibPurl, 'declaration panel rendering the selected component as code, with clickable type tokens', 'ComponentDeclaration'],
-  ['engine', 'engine.py', 'module', 'graphify/extractors/engine.py', graphifyPurl, 'tree-sitter walk emitting references[parameter_type] edges + sourceless stubs', 'ensure_named_node'],
-  ['rewire', 'extract.py', 'module', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
+  ['resolver', 'resolve.ts', 'function', 'packages/subsystems-react/src/graphify/resolve.ts', coreLibPurl, 'consumer-side resolution mirroring graphify rewire tiers', 'createGraphifyTypeResolver'],
+  ['reftypes', 'consolidated.ts', 'function', 'packages/subsystems-react/src/graphify/consolidated.ts', coreLibPurl, 'drill-down payload types carrying ref.nodeId', 'GraphifyParamInfo'],
+  ['detail', 'ComponentDeclaration.tsx', 'function', 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx', coreLibPurl, 'declaration panel rendering the selected component as code, with clickable type tokens', 'ComponentDeclaration'],
+  ['engine', 'engine.py', 'function', 'graphify/extractors/engine.py', graphifyPurl, 'tree-sitter walk emitting references[parameter_type] edges + sourceless stubs', 'ensure_named_node'],
+  ['rewire', 'extract.py', 'function', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
 ]);
 
 const multiRepoEdges = graphSpecFromEdges([

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

@@ -29,9 +29,6 @@ export function components(
 
 const RELATION_TYPES = new Set<string>([
   'imports',
-  'imports_from',
-  're_exports',
-  'defines',
   'extends',
   'inherits',
   'implements',

package/src/subsystem/formatDeclaration.ts

@@ -39,8 +39,6 @@ export function generateDeclarationString(component: SubsystemComponent): string
     case 'type_alias':
     case 'enum':
       return generateType(name, component.construct, declaration);
-    case 'module':
-      return generateModule(declaration);
     case 'store':
       return generateStore(name, declaration);
     case 'external':
@@ -175,23 +173,6 @@ function generateType(
   }
 }
 
-function generateModule(declaration?: GraphifyComponentDetail): string {
-  const mod = declaration?.kind === 'module' ? declaration : undefined;
-  if (!mod) return 'module {}';
-
-  const parts: string[] = [];
-
-  for (const imp of mod.imports ?? []) {
-    parts.push(`import '${imp.name}';`);
-  }
-
-  if ((mod.exports ?? []).length > 0) {
-    parts.push(`export { ${mod.exports!.join(', ')} };`);
-  }
-
-  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

package/src/subsystem/model.test.ts

@@ -4,7 +4,9 @@ import {
   convertSubsystemToEdges,
   convertSubsystemToGroups,
   getSubsystemRegions,
+  getSubsystemModuleRegions,
   processGroupNodeId,
+  moduleGroupNodeId,
   buildSubsystemGraph,
   deriveNameFromSymbol,
   constructBadgeLabel,
@@ -94,10 +96,10 @@ describe('subsystem graph model', () => {
   });
 
   test('deriveNameFromSymbol is consistent per kind', () => {
-    // brace-bodied constructs wear {}; classes render bare; module uses the symbol as-is.
+    // brace-bodied constructs wear {}; classes render bare.
     expect(deriveNameFromSymbol('SessionReader', 'class')).toBe('SessionReader');
     expect(deriveNameFromSymbol('SessionRecord', 'type_alias')).toBe('SessionRecord {}');
-    expect(deriveNameFromSymbol('transcript', 'module')).toBe('transcript');
+    expect(deriveNameFromSymbol('transcript', 'function')).toBe('transcript()');
     // falls back to existing name when no symbol (class stays bare).
     expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader');
     expect(deriveNameFromSymbol('', 'external', 'principal-studio-host')).toBe('principal-studio-host');
@@ -187,13 +189,13 @@ describe('subsystem graph model', () => {
     expect(rightBadgeLabel({ role: 'service', proposed: true })).toBe('proposed');
   });
 
-  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');
-    // Symbol wins over file basename.
-    expect(deriveNameFromSymbol('CodexRolloutRecord', 'module', undefined, 'transcript.ts')).toBe('CodexRolloutRecord');
-    // File basename wins over a supplied name for modules (derivation precedence).
-    expect(deriveNameFromSymbol(undefined, 'module', 'MyModule', 'x.ts')).toBe('x');
+  test('deriveNameFromSymbol falls back to existing name when no symbol', () => {
+    expect(deriveNameFromSymbol(undefined, 'class', undefined, 'transcript.ts')).toBe('untitled');
+    expect(deriveNameFromSymbol(undefined, 'function', 'MyFn', 'x.ts')).toBe('MyFn()');
+    // Symbol wins over a supplied name.
+    expect(deriveNameFromSymbol('CodexRolloutRecord', 'function', undefined, 'transcript.ts')).toBe(
+      'CodexRolloutRecord()',
+    );
   });
 
   test('formatPurl renders the human identity', () => {
@@ -216,9 +218,49 @@ describe('subsystem graph model', () => {
       ],
     });
     expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
+    expect(regions.every((r) => r.kind === 'process')).toBe(true);
     expect(regions[0]!.memberIds).toEqual(['a', 'b']);
   });
 
+  test('getSubsystemModuleRegions groups by module, skipping module-less nodes', () => {
+    const regions = getSubsystemModuleRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { id: 'b', name: 'b', construct: 'type_alias', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { id: 'c', name: 'c', construct: 'function', file: 'paths.ts', purl: 'pkg:github/acme/app', module: 'src/session/paths.ts' },
+        { id: 'd', name: 'd', construct: 'function', file: 'other.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(regions.map((r) => r.key)).toEqual([
+      'src/session/transcript.ts',
+      'src/session/paths.ts',
+    ]);
+    expect(regions.every((r) => r.kind === 'module')).toBe(true);
+    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+  });
+
+  test('convertSubsystemToNodes prefers module parentId over process', () => {
+    const nodes = convertSubsystemToNodes({
+      components: [
+        {
+          id: 'a',
+          name: 'a',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+      relations: [],
+    });
+    expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/a.ts'),
+    );
+    expect((nodes.find((n) => n.id === 'd') as { parentId?: string }).parentId).toBeUndefined();
+  });
+
   test('convertSubsystemToNodes stamps parentId for process members only', () => {
     const nodes = convertSubsystemToNodes({
       components: [
@@ -245,6 +287,103 @@ describe('subsystem graph model', () => {
     expect(groups[0]!.type).toBe('subsystem-group');
   });
 
+  test('convertSubsystemToGroups nests module frames under a shared process', () => {
+    const groups = convertSubsystemToGroups({
+      components: [
+        {
+          id: 'a',
+          name: 'a',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        {
+          id: 'b',
+          name: 'b',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+      ],
+    });
+    expect(groups.map((g) => g.id).sort()).toEqual(
+      [moduleGroupNodeId('src/a.ts'), processGroupNodeId('app/host')].sort(),
+    );
+    const mod = groups.find((g) => g.id === moduleGroupNodeId('src/a.ts'));
+    expect((mod as { parentId?: string }).parentId).toBe(processGroupNodeId('app/host'));
+    const proc = groups.find((g) => g.id === processGroupNodeId('app/host'));
+    expect((proc as { parentId?: string }).parentId).toBeUndefined();
+  });
+
+  test('buildSubsystemGraph nests module frames inside process frames', async () => {
+    const { nodes, regions } = await buildSubsystemGraph({
+      components: [
+        {
+          id: 'boot',
+          name: 'boot',
+          construct: 'function',
+          file: 'main.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/main.ts',
+          symbol: 'boot',
+        },
+        {
+          id: 'create',
+          name: 'createHost',
+          construct: 'function',
+          file: 'main.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/main.ts',
+          symbol: 'createHost',
+        },
+        {
+          id: 'write',
+          name: 'writeSession',
+          construct: 'function',
+          file: 'store.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/store.ts',
+          symbol: 'writeSession',
+        },
+        {
+          id: 'store',
+          name: 'SessionStore',
+          construct: 'store',
+          file: 'store.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/store.ts',
+          symbol: 'SessionStore',
+        },
+      ],
+      relations: [],
+    });
+    expect(regions.map((r) => r.key).sort()).toEqual(
+      ['app/host', 'src/main.ts', 'src/store.ts'].sort(),
+    );
+    const processNode = nodes.find((n) => n.id === processGroupNodeId('app/host'));
+    const mainMod = nodes.find((n) => n.id === moduleGroupNodeId('src/main.ts'));
+    const storeMod = nodes.find((n) => n.id === moduleGroupNodeId('src/store.ts'));
+    expect(processNode).toBeDefined();
+    expect(mainMod).toBeDefined();
+    expect(storeMod).toBeDefined();
+    expect((mainMod as { parentId?: string }).parentId).toBe(processGroupNodeId('app/host'));
+    expect((storeMod as { parentId?: string }).parentId).toBe(processGroupNodeId('app/host'));
+    expect((nodes.find((n) => n.id === 'boot') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/main.ts'),
+    );
+    expect((nodes.find((n) => n.id === 'store') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/store.ts'),
+    );
+  });
+
   test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
@@ -264,6 +403,48 @@ describe('subsystem graph model', () => {
     expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
   });
 
+  test('buildSubsystemGraph frames multi-member modules', async () => {
+    const { nodes, regions } = await buildSubsystemGraph({
+      components: [
+        {
+          id: 'rec',
+          name: 'CodexRolloutRecord',
+          construct: 'type_alias',
+          file: 'transcript.ts',
+          purl: 'pkg:github/acme/app',
+          module: 'src/session/transcript.ts',
+          symbol: 'CodexRolloutRecord',
+        },
+        {
+          id: 'parse',
+          name: 'parseTranscript',
+          construct: 'function',
+          file: 'transcript.ts',
+          purl: 'pkg:github/acme/app',
+          module: 'src/session/transcript.ts',
+          symbol: 'parseTranscript',
+        },
+        {
+          id: 'solo',
+          name: 'lonely',
+          construct: 'function',
+          file: 'solo.ts',
+          purl: 'pkg:github/acme/app',
+          module: 'src/solo.ts',
+          symbol: 'lonely',
+        },
+      ],
+      relations: [],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['src/session/transcript.ts']);
+    expect(regions[0]!.kind).toBe('module');
+    expect((nodes.find((n) => n.id === 'rec') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/session/transcript.ts'),
+    );
+    expect((nodes.find((n) => n.id === 'solo') as { parentId?: string }).parentId).toBeUndefined();
+    expect(nodes.find((n) => n.id === moduleGroupNodeId('src/session/transcript.ts'))).toBeDefined();
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = doc;
     const withRef = {