@principal-ai/subsystems-react 0.24.0 → 0.24.2

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

@@ -0,0 +1,287 @@
+import React, { useState } from 'react';
+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 { PierreFileView, PierreSnippetView } from '../../../pierre';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import type { SubsystemOpenFileOptions } from '../../../subsystem/declarationRef';
+import type { GraphifyComponentDetail } from '../../../graphify';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Constructs',
+  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/you/notes-intake';
+
+/** One construct of each core kind, no relations — the catalog view. */
+const constructsOnly: SubsystemComponent[] = [
+  {
+    id: 'submit-note',
+    name: 'submitNote',
+    construct: 'function',
+    symbol: 'submitNote',
+    role: 'entry',
+    purl: PURL,
+    file: 'src/api/submitNote.ts',
+    purpose: 'HTTP/handler entry — validates and hands off to the service.',
+    declarationRef: {
+      file: 'src/api/submitNote.ts',
+      startLine: 7,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'function',
+      parameters: [
+        { name: 'req', type: 'SubmitNoteRequest' },
+        { name: 'ctx', type: 'RequestContext' },
+      ],
+      returnType: 'Promise<NoteId>',
+      callers: [],
+      callees: [{ nodeId: 'note-service', name: 'NoteService' }],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'note-service',
+    name: 'NoteService',
+    construct: 'class',
+    symbol: 'NoteService',
+    purl: PURL,
+    file: 'src/NoteService.ts',
+    purpose: 'Owns intake rules; methods are separate nodes when they matter.',
+    declarationRef: {
+      file: 'src/NoteService.ts',
+      startLine: 3,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'class',
+      methods: [
+        {
+          nodeId: 'note-service-persist',
+          name: 'persist',
+          parameters: [{ name: 'draft', type: 'NoteDraft' }],
+          returnType: 'Promise<NoteId>',
+        },
+      ],
+      properties: [{ name: 'repo', type: 'NoteRepository' }],
+      implements: ['NoteRepository'],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'note-service-persist',
+    name: 'persist',
+    construct: 'method',
+    symbol: 'NoteService.persist',
+    purl: PURL,
+    file: 'src/NoteService.ts',
+    purpose: 'Instance method on NoteService — written as its own construct.',
+    declarationRef: {
+      file: 'src/NoteService.ts',
+      startLine: 14,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'function',
+      parameters: [{ name: 'draft', type: 'NoteDraft' }],
+      returnType: 'Promise<NoteId>',
+      callers: [{ nodeId: 'submit-note', name: 'submitNote' }],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'note-repository',
+    name: 'NoteRepository',
+    construct: 'interface',
+    symbol: 'NoteRepository',
+    purl: PURL,
+    file: 'src/NoteRepository.ts',
+    purpose: 'Persistence contract the service depends on.',
+    declarationRef: {
+      file: 'src/NoteRepository.ts',
+      startLine: 1,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'save', type: '(draft: NoteDraft) => Promise<NoteId>' },
+        { name: 'findById', type: '(id: NoteId) => Promise<Note | null>' },
+      ],
+      implementors: ['NoteService'],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'note-id',
+    name: 'NoteId',
+    construct: 'type_alias',
+    symbol: 'NoteId',
+    purl: PURL,
+    file: 'src/types.ts',
+    purpose: 'Branded id type — a declaration, not a runtime instance.',
+    declarationRef: {
+      file: 'src/types.ts',
+      startLine: 1,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'type',
+      aliasOf: "string & { readonly __brand: 'NoteId' }",
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'note-kind',
+    name: 'NoteKind',
+    construct: 'enum',
+    symbol: 'NoteKind',
+    purl: PURL,
+    file: 'src/types.ts',
+    purpose: 'Closed set of note kinds (idea, task, …).',
+    declarationRef: {
+      file: 'src/types.ts',
+      startLine: 5,
+      lineHash: 'storybook-placeholder',
+      capturedAt: new Date(0).toISOString(),
+    },
+    declaration: {
+      kind: 'type',
+      enumMembers: [
+        { name: 'Idea', value: "'idea'" },
+        { name: 'Task', value: "'task'" },
+      ],
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+const storyFiles: Record<string, string> = {
+  'src/api/submitNote.ts': `import { NoteService } from '../NoteService';
+import type { NoteId, SubmitNoteRequest, RequestContext } from '../types';
+
+const service = new NoteService();
+
+/** HTTP/handler entry — validates and hands off to the service. */
+export async function submitNote(
+  req: SubmitNoteRequest,
+  ctx: RequestContext,
+): Promise<NoteId> {
+  return service.persist({ ...req, actor: ctx.actor });
+}
+`,
+  'src/NoteService.ts': `import type { NoteDraft, NoteId, NoteRepository } from './types';
+
+export class NoteService implements NoteRepository {
+  constructor(readonly repo: NoteRepository) {}
+
+  async save(draft: NoteDraft): Promise<NoteId> {
+    return this.persist(draft);
+  }
+
+  async findById(id: NoteId): Promise<Note | null> {
+    return this.repo.findById(id);
+  }
+
+  async persist(draft: NoteDraft): Promise<NoteId> {
+    return this.repo.save(draft);
+  }
+}
+`,
+  'src/NoteRepository.ts': `import type { Note, NoteDraft, NoteId } from './types';
+
+export interface NoteRepository {
+  save(draft: NoteDraft): Promise<NoteId>;
+  findById(id: NoteId): Promise<Note | null>;
+}
+`,
+  'src/types.ts': `export type NoteId = string & { readonly __brand: 'NoteId' };
+
+export type NoteDraft = { title: string; kind: NoteKind };
+
+export enum NoteKind {
+  Idea = 'idea',
+  Task = 'task',
+}
+`,
+};
+
+function readStoryFile(path: string): Promise<string> {
+  const content = storyFiles[path];
+  if (content == null) return Promise.reject(new Error(`No story fixture for ${path}`));
+  return Promise.resolve(content);
+}
+
+function renderFileViewer(file: string, opts?: SubsystemOpenFileOptions) {
+  const startLine = opts?.startLine;
+  if (startLine != null && !opts?.fullFile) {
+    return (
+      <PierreSnippetView
+        filePath={file}
+        fileName={file.split('/').pop() ?? file}
+        startLine={startLine}
+        endLine={startLine}
+        focusLine={startLine}
+        contextLines={12}
+        readFile={readStoryFile}
+      />
+    );
+  }
+  return (
+    <PierreFileView
+      filePath={file}
+      fileName={file.split('/').pop() ?? file}
+      readFile={readStoryFile}
+      focusLine={opts?.fullFile ? startLine : undefined}
+    />
+  );
+}
+
+function CatalogDemo({ hideSidebar = false }: { hideSidebar?: boolean }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={constructsOnly}
+        relations={[]}
+        title="Constructs at a glance"
+        description="Layer 1 — constructs only. Click a file path or L# to open the declaration source."
+        hideSidebar={hideSidebar}
+        onSelect={(id) => setSelected(id)}
+        renderFileViewer={renderFileViewer}
+      />
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        {selected
+          ? `last toggled: ${selected}`
+          : 'click constructs to toggle their signatures'}
+      </div>
+    </div>
+  );
+}
+
+/** Homepage-style embed: list of constructs on the left, signature on the right. */
+export const Catalog: Story = {
+  render: () => <CatalogDemo />,
+};
+
+/** Same catalog, no title chrome — the shape the home-page constructs layer uses. */
+export const CatalogEmbed: Story = {
+  render: () => <CatalogDemo hideSidebar />,
+};

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

@@ -0,0 +1,138 @@
+import '@xyflow/react/dist/style.css';
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import {
+  SubsystemDiagnosticToggle,
+  type SubsystemDiagnosticStatus,
+} from '../../../subsystem/DiagnosticToggle';
+import { components, graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Diagnostics',
+  component: SubsystemComponentGraph,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const graphComponents = components([
+  ['entry', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
+  ['store', 'cartStore', 'store', 'src/checkout/cartStore.ts', 'pkg:github/you/your-app', 'Retained cart state.', 'cartStore'],
+  ['stripe', 'Stripe', 'external', '', 'external', undefined, undefined],
+  ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
+]);
+
+const graphEdges = graphSpecFromEdges([
+  ['caller', 'entry', 'calls'],
+  ['entry', 'store', 'writes'],
+  ['entry', 'stripe', 'calls'],
+]);
+
+const GRAPH_DESCRIPTION =
+  'A small e-commerce checkout subsystem: an HTTP entry point that writes to retained cart state and calls out to Stripe.';
+
+/** Every chip state side by side, for quick visual review. */
+export const States: Story = {
+  render: () => {
+    const rows: Array<{ label: string; status: SubsystemDiagnosticStatus; issueCount?: number; stale?: boolean; busy?: boolean }> = [
+      { label: 'ok', status: 'ok' },
+      { label: 'ok (stale)', status: 'ok', stale: true },
+      { label: 'issues · 3', status: 'issues', issueCount: 3 },
+      { label: 'gaps · 2', status: 'gaps', issueCount: 2 },
+      { label: 'unknown (never checked)', status: 'unknown' },
+      { label: 'issues (busy)', status: 'issues', issueCount: 3, busy: true },
+    ];
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 18, padding: 32 }}>
+        {rows.map((row) => (
+          <div key={row.label} style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+            <span style={{ width: 200, fontFamily: 'monospace', fontSize: 12, opacity: 0.7 }}>
+              {row.label}
+            </span>
+            <SubsystemDiagnosticToggle
+              status={row.status}
+              issueCount={row.issueCount}
+              stale={row.stale}
+              busy={row.busy}
+              onOpen={() => {}}
+            />
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+/** The chip in its real home: the sidebar title row, beside the description toggle. */
+export const GraphClean: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'ok', onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+export const GraphWithIssues: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'issues', issueCount: 3, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+/** Stale report: the color stays, a hollow ring marks that inputs changed. */
+export const GraphStale: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'issues', issueCount: 3, stale: true, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+/** No title/description — the chip still anchors the title row at the right. */
+export const GraphChipOnly: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        diagnostic={{ status: 'gaps', issueCount: 2, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,130 @@
+import '@xyflow/react/dist/style.css';
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import { SubsystemIssueList, type SubsystemIssue } from '../../../subsystem/IssueList';
+import { components, graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Issues',
+  component: SubsystemComponentGraph,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ISSUES: SubsystemIssue[] = [
+  {
+    id: 'i1',
+    severity: 'error',
+    kind: 'missing_file',
+    message: 'File src/checkout/cartStore.ts is not present on disk (repo pkg:github/you/your-app).',
+    target: { kind: 'component', id: 'store', label: 'cartStore' },
+    fix: { label: 'Use graphify file' },
+  },
+  {
+    id: 'i2',
+    severity: 'error',
+    kind: 'construct_mismatch',
+    message: 'Claimed function but graphify infers class.',
+    target: { kind: 'component', id: 'entry', label: 'checkoutApi' },
+  },
+  {
+    id: 'i3',
+    severity: 'info',
+    kind: 'signature_unconfirmed',
+    message: 'Named parameter types are not present in the graphify cache.',
+    target: { kind: 'component', id: 'entry', label: 'checkoutApi' },
+  },
+  {
+    id: 'i4',
+    severity: 'error',
+    kind: 'topology_broken_endpoint',
+    message: 'Relation endpoint "store" does not resolve to a component.',
+    target: { kind: 'relation', id: 'r1', label: 'checkoutApi → cartStore', detail: 'writes' },
+  },
+  {
+    id: 'i5',
+    severity: 'warn',
+    kind: 'boundary_module_file_mismatch',
+    message: 'Module "src/checkout" contains a file outside its declared root.',
+    target: { kind: 'module', id: 'src/checkout', label: 'src/checkout' },
+  },
+  {
+    id: 'i6',
+    severity: 'info',
+    kind: 'walkthrough',
+    message: 'Step 2 references a line that moved (was :42).',
+    target: { kind: 'walkthrough', id: 'flow-1', label: 'Checkout', detail: 'step 2' },
+  },
+  {
+    id: 'i7',
+    severity: 'warn',
+    kind: 'boundary_process_nest_disagree',
+    message: 'Component is nested in process "api" but Graphify places it outside.',
+    target: { kind: 'module', id: 'api', label: 'api' },
+  },
+];
+
+const graphComponents = components([
+  ['entry', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
+  ['store', 'cartStore', 'store', 'src/checkout/cartStore.ts', 'pkg:github/you/your-app', 'Retained cart state.', 'cartStore'],
+  ['stripe', 'Stripe', 'external', '', 'external', undefined, undefined],
+]);
+
+const graphEdges = graphSpecFromEdges([
+  ['entry', 'store', 'writes'],
+  ['entry', 'stripe', 'calls'],
+]);
+
+/** The catalogue, grouped by verification layer. */
+export const List: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList
+        issues={ISSUES}
+        onSelectIssue={() => {}}
+        onApplyFix={() => {}}
+      />
+    </div>
+  ),
+};
+
+/** All four layers clean — the happy state. */
+export const AllGood: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList issues={[]} />
+    </div>
+  ),
+};
+
+/** In place: diagnostics active, so the sidebar bottom panel is the issue list. */
+export const GraphWithIssues: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description="A small e-commerce checkout subsystem."
+        diagnostic={{ status: 'issues', issueCount: 5, onOpen: () => {} }}
+        issues={ISSUES}
+        onSelectIssue={() => {}}
+        onApplyIssueFix={() => {}}
+      />
+    </div>
+  ),
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -118,6 +118,8 @@ export interface ComponentDeclarationProps {
   onVerify?: (componentId: string) => void;
   /** Live verification status for the selected component. */
   verification?: ComponentVerificationState | null;
+  /** Start with the file path row visible (catalog / source-first views). */
+  defaultShowFile?: boolean;
 }
 
 function verificationSummary(
@@ -256,11 +258,12 @@ export function ComponentDeclaration({
   maxWidth,
   onVerify,
   verification,
+  defaultShowFile = false,
 }: ComponentDeclarationProps) {
   const { theme, mode } = useTheme();
   const pierreSyntaxTheme = resolvePierreSyntaxThemeName(mode);
   const [fileHovered, setFileHovered] = useState(false);
-  const [showFile, setShowFile] = useState(false);
+  const [showFile, setShowFile] = useState(defaultShowFile);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = componentColor(component, pierreSyntaxTheme);