@principal-ai/subsystems-react 0.23.0 → 0.23.2

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

@@ -0,0 +1,242 @@
+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/Packages',
+  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 APP = 'pkg:github/acme/app';
+const LIB = 'pkg:github/acme/lib';
+
+/**
+ * Package frames are derived from `purl` when a graph spans multiple repos.
+ * No separate `package` field — single-repo graphs stay unframed at this level.
+ */
+const multiRepoComponents: SubsystemComponent[] = [
+  {
+    id: 'dispatch',
+    name: 'dispatch',
+    construct: 'function',
+    symbol: 'dispatch',
+    file: 'src/host/dispatch.ts',
+    module: 'src/host/dispatch.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'host entry',
+    layer: 1,
+  },
+  {
+    id: 'session',
+    name: 'SessionService',
+    construct: 'class',
+    symbol: 'SessionService',
+    file: 'src/host/session.ts',
+    module: 'src/host/session.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'session state',
+    layer: 2,
+  },
+  {
+    id: 'parse',
+    name: 'parseEvent',
+    construct: 'function',
+    symbol: 'parseEvent',
+    file: 'src/parse.ts',
+    module: 'src/parse.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'shared parser',
+    layer: 1,
+  },
+  {
+    id: 'normalize',
+    name: 'normalize',
+    construct: 'function',
+    symbol: 'normalize',
+    file: 'src/normalize.ts',
+    module: 'src/normalize.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'normalize payloads',
+    layer: 2,
+  },
+];
+
+const multiRepoEdges = graphSpecFromEdges([
+  ['dispatch', 'session', 'calls'],
+  ['dispatch', 'parse', 'calls'],
+  ['parse', 'normalize', 'calls'],
+]);
+
+export const MultiRepoPackageFrames: Story = {
+  name: 'Multi-repo package frames',
+  args: {
+    components: multiRepoComponents,
+    relations: multiRepoEdges.relations,
+    walkthroughs: multiRepoEdges.walkthroughs,
+  },
+  render: (args) => (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <SubsystemComponentGraph {...args} />
+    </div>
+  ),
+};
+
+/** Same components, one purl — no package frames (process/module only). */
+const singleRepo = multiRepoComponents.map((c) => ({ ...c, purl: APP }));
+
+export const SingleRepoNoPackageFrames: Story = {
+  name: 'Single-repo (no package frames)',
+  args: {
+    components: singleRepo,
+    relations: multiRepoEdges.relations,
+    walkthroughs: multiRepoEdges.walkthroughs,
+  },
+  render: (args) => (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <SubsystemComponentGraph {...args} />
+    </div>
+  ),
+};
+
+/**
+ * Full nest: package → process → module → leaves.
+ * Each module path has 2+ exports so module frames survive the singleton rule.
+ */
+const nestedComponents: SubsystemComponent[] = [
+  {
+    id: 'dispatch',
+    name: 'dispatch',
+    construct: 'function',
+    symbol: 'dispatch',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'host entry',
+    layer: 1,
+  },
+  {
+    id: 'boot',
+    name: 'boot',
+    construct: 'function',
+    symbol: 'boot',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'host bootstrap',
+    layer: 1,
+  },
+  {
+    id: 'session',
+    name: 'SessionService',
+    construct: 'class',
+    symbol: 'SessionService',
+    file: 'src/host/session.ts',
+    module: 'src/host/session.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'session state',
+    layer: 2,
+  },
+  {
+    id: 'session-types',
+    name: 'SessionRecord',
+    construct: 'type_alias',
+    symbol: 'SessionRecord',
+    file: 'src/host/session.ts',
+    module: 'src/host/session.ts',
+    process: 'app/host',
+    purl: APP,
+    purpose: 'session record shape',
+    layer: 2,
+  },
+  {
+    id: 'parse',
+    name: 'parseEvent',
+    construct: 'function',
+    symbol: 'parseEvent',
+    file: 'src/parse.ts',
+    module: 'src/parse.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'shared parser',
+    layer: 1,
+  },
+  {
+    id: 'parse-types',
+    name: 'RawEvent',
+    construct: 'type_alias',
+    symbol: 'RawEvent',
+    file: 'src/parse.ts',
+    module: 'src/parse.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'raw event shape',
+    layer: 1,
+  },
+  {
+    id: 'normalize',
+    name: 'normalize',
+    construct: 'function',
+    symbol: 'normalize',
+    file: 'src/normalize.ts',
+    module: 'src/normalize.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'normalize payloads',
+    layer: 2,
+  },
+  {
+    id: 'normalize-types',
+    name: 'NormalizedEvent',
+    construct: 'type_alias',
+    symbol: 'NormalizedEvent',
+    file: 'src/normalize.ts',
+    module: 'src/normalize.ts',
+    process: 'lib/worker',
+    purl: LIB,
+    purpose: 'normalized event shape',
+    layer: 2,
+  },
+];
+
+const nestedEdges = graphSpecFromEdges([
+  ['boot', 'dispatch', 'calls'],
+  ['dispatch', 'session', 'calls'],
+  ['dispatch', 'parse', 'calls'],
+  ['parse', 'normalize', 'calls'],
+]);
+
+export const PackageProcessModuleNesting: Story = {
+  name: 'Package → process → module nesting',
+  args: {
+    components: nestedComponents,
+    relations: nestedEdges.relations,
+    walkthroughs: nestedEdges.walkthroughs,
+  },
+  render: (args) => (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <SubsystemComponentGraph {...args} />
+    </div>
+  ),
+};

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -70,7 +70,7 @@ export interface WalkthroughViewerContext {
   /** Focused step index; `null` means the whole flow (no specific step). */
   stepIndex: number | null;
   /** Open a step's full source file over the walkthrough drawer (keeps snippets mounted). */
-  onOpenFile: (path: string) => void;
+  onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
 }
 
 type DrawerTarget =
@@ -192,12 +192,23 @@ const FileDrawerContent = memo(function FileDrawerContent({
   render,
   file,
   startLine,
+  fullFile,
 }: {
   render: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   file: string;
   startLine?: number;
+  fullFile?: boolean;
 }) {
-  return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
+  return (
+    <>
+      {render(
+        file,
+        startLine != null
+          ? { startLine, ...(fullFile ? { fullFile: true } : {}) }
+          : undefined,
+      )}
+    </>
+  );
 });
 
 function FileOverlayCloseButton({ onClose }: { onClose: () => void }) {
@@ -240,7 +251,7 @@ const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({
   render: (ctx: WalkthroughViewerContext) => ReactNode;
   walkthrough: SubsystemWalkthrough;
   stepIndex: number | null;
-  onOpenFile: (path: string) => void;
+  onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
 }) {
   return <>{render({ walkthrough, stepIndex, onOpenFile })}</>;
 });
@@ -266,7 +277,10 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   /** Bottom drawer: single file or walkthrough multi-snippet mode. */
   const [drawerTarget, setDrawerTarget] = useState<DrawerTarget | null>(null);
   /** Full-file layer over an open walkthrough drawer — walkthrough stays mounted. */
-  const [fileOverlay, setFileOverlay] = useState<{ file: string } | null>(null);
+  const [fileOverlay, setFileOverlay] = useState<{
+    file: string;
+    startLine?: number;
+  } | null>(null);
   // Mirror so step-focus can decide whether to wait for the drawer open
   // transition before fitView (avoids framing against full-height canvas).
   const drawerOpenRef = useRef(false);
@@ -356,7 +370,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
     fileOverlay?.file ??
     (drawerTarget?.kind === 'file' ? drawerTarget.file : null);
   openFileRef.current = fileOverlay
-    ? { file: fileOverlay.file }
+    ? { file: fileOverlay.file, startLine: fileOverlay.startLine }
     : drawerTarget?.kind === 'file'
       ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
       : null;
@@ -932,8 +946,8 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   );
 
   const onOpenFileFromWalkthrough = useCallback(
-    (file: string) => {
-      setFileOverlay({ file });
+    (file: string, opts?: SubsystemOpenFileOptions) => {
+      setFileOverlay({ file, startLine: opts?.startLine });
       onFileSelect?.(file);
     },
     [onFileSelect],
@@ -1955,6 +1969,8 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
             <FileDrawerContent
               render={renderDrawerContent}
               file={fileOverlay.file}
+              startLine={fileOverlay.startLine}
+              fullFile
             />
           </div>
         </div>

package/src/subsystem/model.test.ts

@@ -5,11 +5,17 @@ import {
   convertSubsystemToGroups,
   getSubsystemRegions,
   getSubsystemModuleRegions,
+  getSubsystemPackageRegions,
   processGroupNodeId,
   moduleGroupNodeId,
+  packageGroupNodeId,
+  buildBoundaryLayoutGroups,
   buildSubsystemGraph,
+  componentPackageKey,
   deriveNameFromSymbol,
   constructBadgeLabel,
+  constructBadgeColor,
+  FRAMEWORK_BADGE_COLOR,
   rightBadgeLabel,
   nodeMinWidthForBadges,
   formatPurl,
@@ -148,6 +154,15 @@ describe('subsystem graph model', () => {
     ).toBe('custom_entity');
   });
 
+  test('constructBadgeColor uses React brand only for framework stereotype badges', () => {
+    expect(
+      constructBadgeColor({ framework: 'react', stereotype: 'component' }),
+    ).toBe(FRAMEWORK_BADGE_COLOR.react);
+    expect(constructBadgeColor({ framework: 'react' })).toBeNull();
+    expect(constructBadgeColor({ stereotype: 'hook' })).toBeNull();
+    expect(constructBadgeColor({ framework: 'vue', stereotype: 'component' })).toBeNull();
+  });
+
   test('nodeMinWidthForBadges widens for long construct badges and role pairs', () => {
     const plain = nodeMinWidthForBadges({ construct: 'function' });
     expect(plain).toBe(150);
@@ -445,6 +460,158 @@ describe('subsystem graph model', () => {
     expect(nodes.find((n) => n.id === moduleGroupNodeId('src/session/transcript.ts'))).toBeDefined();
   });
 
+  test('getSubsystemPackageRegions groups by purl repo key, skipping externals', () => {
+    const regions = getSubsystemPackageRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { id: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
+      ],
+    });
+    expect(regions.map((r) => r.key).sort()).toEqual([
+      'pkg:github/acme/app',
+      'pkg:github/other/lib',
+    ].sort());
+    expect(regions.every((r) => r.kind === 'package')).toBe(true);
+    expect(componentPackageKey({ construct: 'external', purl: 'pkg:npm/stripe' })).toBeUndefined();
+  });
+
+  test('buildBoundaryLayoutGroups skips package frames for single-repo graphs', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(0);
+  });
+
+  test('buildBoundaryLayoutGroups frames packages when multi-repo', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
+      ],
+    });
+    const pkgs = groups.filter((g) => g.region.kind === 'package');
+    expect(pkgs.map((g) => g.region.key).sort()).toEqual([
+      'pkg:github/acme/app',
+      'pkg:github/other/lib',
+    ].sort());
+  });
+
+  test('buildBoundaryLayoutGroups nests process under package', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        {
+          id: 'a',
+          name: 'a',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+        },
+        {
+          id: 'b',
+          name: 'b',
+          construct: 'function',
+          file: 'b.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+        },
+        {
+          id: 'c',
+          name: 'c',
+          construct: 'function',
+          file: 'c.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+        },
+        {
+          id: 'd',
+          name: 'd',
+          construct: 'function',
+          file: 'd.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+        },
+      ],
+    });
+    const host = groups.find((g) => g.id === processGroupNodeId('app/host'));
+    expect(host?.parentId).toBe(packageGroupNodeId('pkg:github/acme/app'));
+  });
+
+  test('buildSubsystemGraph nests package → process → module', async () => {
+    const { nodes } = await buildSubsystemGraph({
+      components: [
+        {
+          id: 'a1',
+          name: 'a1',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        {
+          id: 'a2',
+          name: 'a2',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        {
+          id: 'b1',
+          name: 'b1',
+          construct: 'function',
+          file: 'b.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+          module: 'src/b.ts',
+        },
+        {
+          id: 'b2',
+          name: 'b2',
+          construct: 'function',
+          file: 'b.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+          module: 'src/b.ts',
+        },
+      ],
+      relations: [],
+    });
+    const pkgA = nodes.find((n) => n.id === packageGroupNodeId('pkg:github/acme/app'));
+    const proc = nodes.find((n) => n.id === processGroupNodeId('app/host'));
+    const mod = nodes.find((n) => n.id === moduleGroupNodeId('src/a.ts'));
+    expect(pkgA).toBeDefined();
+    expect((proc as { parentId?: string }).parentId).toBe(
+      packageGroupNodeId('pkg:github/acme/app'),
+    );
+    expect((mod as { parentId?: string }).parentId).toBe(processGroupNodeId('app/host'));
+    expect((nodes.find((n) => n.id === 'a1') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/a.ts'),
+    );
+  });
+
+  test('packageFrames always draws single-repo package frames when multi-member', () => {
+    const groups = buildBoundaryLayoutGroups(
+      {
+        components: [
+          { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+          { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        ],
+      },
+      { packageFrames: 'always' },
+    );
+    expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(1);
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = doc;
     const withRef = {