@principal-ai/subsystems-react 0.23.1 → 0.23.3

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

@@ -1322,7 +1322,12 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // the actual edge path (not node-center approximations).
   const edgeLabels = useMemo(() => {
     return dispEdges
-      .filter((e) => !e.hidden)
+      .filter((e) => {
+        if (e.hidden) return false;
+        const d = e?.data as { dimmed?: boolean } | undefined;
+        if (d?.dimmed) return false;
+        return true;
+      })
       .map((e) => {
         const d = e.data as {
           mechanism?: string;

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 = {