@principal-ai/subsystems-react 0.36.2 → 0.37.1

package/src/stories/Subsystem/ConstructsCatalog.stories.tsx

@@ -0,0 +1,443 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { ConstructsCatalog } from '../../subsystem/ConstructsCatalog';
+import { PierreFileView, PierreSnippetView } from '../../pierre';
+import type { SubsystemComponent } from '../../subsystem/model';
+import type { SubsystemOpenFileOptions } from '../../subsystem/declarationRef';
+import type { SymbolInspection } from '../../subsystem/symbolRefs';
+import type { GraphifyComponentDetail } from '../../graphify';
+
+const meta = {
+  title: 'Subsystem/ConstructsCatalog',
+  component: ConstructsCatalog,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof ConstructsCatalog>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Fixtures — two repos, two processes, one of each core construct kind, so the
+// catalog exercises process sorting, purl grouping, and every badge/anatomy.
+// ---------------------------------------------------------------------------
+const INTAKE = 'pkg:github/you/notes-intake';
+const UI = 'pkg:github/you/notes-ui';
+
+const components: SubsystemComponent[] = [
+  {
+    alias: 'submit-note',
+    name: 'submitNote',
+    construct: 'function',
+    symbol: 'submitNote',
+    role: 'entry',
+    purl: INTAKE,
+    process: 'notes-api/server',
+    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,
+  },
+  {
+    alias: 'note-service',
+    name: 'NoteService',
+    construct: 'class',
+    symbol: 'NoteService',
+    purl: INTAKE,
+    process: 'notes-api/server',
+    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' }],
+      extends: [],
+      implements: ['NoteRepository'],
+      instantiations: [],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'note-service-persist',
+    name: 'persist',
+    construct: 'method',
+    symbol: 'NoteService.persist',
+    purl: INTAKE,
+    process: 'notes-api/server',
+    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: 'method',
+      hostClass: 'NoteService',
+      parameters: [{ name: 'draft', type: 'NoteDraft' }],
+      returnType: 'Promise<NoteId>',
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'note-repository',
+    name: 'NoteRepository',
+    construct: 'interface',
+    symbol: 'NoteRepository',
+    purl: INTAKE,
+    process: 'notes-api/server',
+    file: 'src/NoteRepository.ts',
+    purpose: 'Persistence contract the service depends on.',
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'save', type: '(draft: NoteDraft) => Promise<NoteId>' },
+        { name: 'findById', type: '(id: NoteId) => Promise<Note | null>' },
+      ],
+      usedBy: [],
+      implementors: ['NoteService'],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'note-kind',
+    name: 'NoteKind',
+    construct: 'enum',
+    symbol: 'NoteKind',
+    purl: INTAKE,
+    process: 'notes-api/server',
+    file: 'src/types.ts',
+    purpose: 'Closed set of note kinds (idea, task, …).',
+    declaration: {
+      kind: 'type',
+      properties: [],
+      usedBy: [],
+      implementors: [],
+      enumMembers: [
+        { name: 'Idea', value: "'idea'" },
+        { name: 'Task', value: "'task'" },
+      ],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'note-id',
+    name: 'NoteId',
+    construct: 'type_alias',
+    symbol: 'NoteId',
+    purl: INTAKE,
+    file: 'src/types.ts',
+    purpose: 'Branded id type — no process, so it sorts to the bottom.',
+    declaration: {
+      kind: 'type',
+      properties: [],
+      usedBy: [],
+      implementors: [],
+      aliasOf: "string & { readonly __brand: 'NoteId' }",
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'note-editor',
+    name: 'NoteEditor',
+    construct: 'function',
+    framework: 'react',
+    stereotype: 'component',
+    symbol: 'NoteEditor',
+    purl: UI,
+    process: 'notes-web/client',
+    file: 'packages/ui/NoteEditor.tsx',
+    purpose: 'React component — a function playing the component stereotype.',
+    declaration: {
+      kind: 'function',
+      parameters: [{ name: 'props', type: 'NoteEditorProps' }],
+      returnType: 'JSX.Element',
+      callers: [],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'use-draft',
+    name: 'useDraft',
+    construct: 'function',
+    framework: 'react',
+    stereotype: 'hook',
+    symbol: 'useDraft',
+    purl: UI,
+    process: 'notes-web/client',
+    file: 'packages/ui/useDraft.ts',
+    purpose: 'React hook — draft state for the editor.',
+    declaration: {
+      kind: 'function',
+      parameters: [{ name: 'initial', type: 'NoteDraft' }],
+      returnType: '[NoteDraft, (next: NoteDraft) => void]',
+      callers: [],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+/** Constructs with no `file` — the Files tab should not appear. */
+const componentsWithoutFiles: SubsystemComponent[] = [
+  {
+    alias: 'remote-notes-service',
+    name: 'notes-service',
+    construct: 'external',
+    role: 'service',
+    symbol: '',
+    purl: 'pkg:npm/@you/notes-service',
+    file: '',
+    purpose: 'External package consumer — no source file in this repo.',
+    declaration: {
+      kind: 'external',
+      label: 'pkg:npm/@you/notes-service',
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    alias: 'remote-notes-client',
+    name: 'notes-client',
+    construct: 'external',
+    role: 'service',
+    symbol: '',
+    purl: 'pkg:npm/@you/notes-client',
+    file: '',
+    purpose: 'Second external dependency for the no-files case.',
+    declaration: {
+      kind: 'external',
+      label: 'pkg:npm/@you/notes-client',
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Inline source fixtures for the bottom FileDrawer (no fs in Storybook).
+// ---------------------------------------------------------------------------
+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',
+}
+`,
+  'packages/ui/NoteEditor.tsx': `import type { NoteDraft } from '../../src/types';
+import { useDraft } from './useDraft';
+
+export function NoteEditor(props: { initial: NoteDraft }) {
+  const [draft, setDraft] = useDraft(props.initial);
+  return <textarea value={draft.title} onChange={(e) => setDraft({ ...draft, title: e.target.value })} />;
+}
+`,
+  'packages/ui/useDraft.ts': `import { useState } from 'react';
+import type { NoteDraft } from '../../src/types';
+
+export function useDraft(initial: NoteDraft) {
+  return useState<NoteDraft>(initial);
+}
+`,
+};
+
+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}
+    />
+  );
+}
+
+/** Graphify lookups so referenced type tokens in declarations are clickable. */
+const INSPECTIONS: Record<string, SymbolInspection> = {
+  NoteRepository: {
+    symbol: 'NoteRepository',
+    purl: INTAKE,
+    resolution: 'resolved',
+    node: {
+      nodeId: 'note-repository',
+      label: 'NoteRepository',
+      sourceFile: 'src/NoteRepository.ts',
+      sourceLocation: 'L3',
+    },
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'save', type: '(draft: NoteDraft) => Promise<NoteId>' },
+        { name: 'findById', type: '(id: NoteId) => Promise<Note | null>' },
+      ],
+      usedBy: [],
+      implementors: ['NoteService'],
+    },
+  },
+  NoteDraft: {
+    symbol: 'NoteDraft',
+    purl: INTAKE,
+    resolution: 'resolved',
+    node: {
+      nodeId: 'note-draft',
+      label: 'NoteDraft',
+      sourceFile: 'src/types.ts',
+      sourceLocation: 'L3',
+    },
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'title', type: 'string' },
+        { name: 'kind', type: 'NoteKind' },
+      ],
+      usedBy: [],
+      implementors: [],
+    },
+  },
+};
+
+function inspectSymbol(req: { symbol: string }): SymbolInspection | null {
+  return INSPECTIONS[req.symbol] ?? null;
+}
+
+function CatalogDemo({
+  comps = components,
+  hideSidebar = false,
+}: {
+  comps?: SubsystemComponent[];
+  hideSidebar?: boolean;
+}) {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0 }}>
+        <ConstructsCatalog
+          components={comps}
+          title="Notes intake — constructs"
+          description="Nothing is selected, so every construct is listed and searchable; pick a file on the left to narrow. Every file stacks under one combined header (path + a description toggle for the whole stack), each declaration labeling the line that holds the construct in a file-like gutter. Click the header or a line to open the file."
+          hideSidebar={hideSidebar}
+          onSelect={(id) => setSelected(id)}
+          renderFileViewer={renderFileViewer}
+          onInspectSymbol={inspectSymbol}
+        />
+      </div>
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        {selected
+          ? `last toggled: ${selected}`
+          : 'click constructs to toggle their signatures'}
+      </div>
+    </div>
+  );
+}
+
+/** Full catalog: title + description chrome, two repos, process-sorted rows. */
+export const Catalog: Story = {
+  args: { components },
+  render: () => <CatalogDemo />,
+};
+
+/** Home-page embed shape — chrome suppressed via `hideSidebar`. */
+export const Embedded: Story = {
+  args: { components },
+  render: () => <CatalogDemo hideSidebar />,
+};
+
+/** Constructs with no `file` — the Files tab is hidden, constructs-only list. */
+export const NoFiles: Story = {
+  args: { components: componentsWithoutFiles },
+  render: () => <CatalogDemo comps={componentsWithoutFiles} />,
+};
+
+/** No components — the empty-state prompt in the detail pane. */
+export const Empty: Story = {
+  args: { components: [] },
+  render: () => <CatalogDemo comps={[]} />,
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -6,7 +6,7 @@
  * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
 import { createPortal } from 'react-dom';
 import { AlignLeft, FileText } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
@@ -138,6 +138,10 @@ function DetailLink({ children, onClick }: { children: ReactNode; onClick?: () =
   );
 }
 
+/** Width of the `lineNumbers` gutter column and the gap after it. */
+const GUTTER_NUMBER_WIDTH = 40;
+const GUTTER_NUMBER_GAP = 8;
+
 /** Panel props. Callbacks are wired by the graph; standalone usage without
  *  them renders the same panel with nothing clickable. */
 export interface ComponentDeclarationProps {
@@ -174,6 +178,18 @@ export interface ComponentDeclarationProps {
    *  the file badge: drop the top-right `L#` (redundant) and put the
    *  description toggle in the badge after the line segment. */
   fileBadgeChrome?: boolean;
+  /** Suppress the per-declaration action chrome entirely (file toggle, line
+   *  label, description toggle). For hosts that surface those in a shared
+   *  header instead. */
+  hideActions?: boolean;
+  /** Controlled purpose/description visibility. When provided it overrides the
+   *  internal toggle, so a host can drive it from a shared header. */
+  showPurpose?: boolean;
+  /** Render a gutter beside the declaration body and label the construct's own
+   *  line with its known start line — only that line is accurate, so the rest
+   *  of the gutter stays blank and aligned. The label opens the file at that
+   *  line when `onOpenFile` is set. */
+  lineNumbers?: boolean;
 }
 
 function verificationSummary(
@@ -318,6 +334,9 @@ export function ComponentDeclaration({
   declarationOpen = false,
   showRepoIdentity = true,
   fileBadgeChrome = false,
+  hideActions = false,
+  showPurpose: showPurposeProp,
+  lineNumbers = false,
 }: ComponentDeclarationProps) {
   const { theme, mode } = useTheme();
   const pierreSyntaxTheme = resolvePierreSyntaxThemeName(mode);
@@ -325,7 +344,8 @@ export function ComponentDeclaration({
     'path' | 'line' | 'desc' | 'action' | null
   >(null);
   const [showFile, setShowFile] = useState(defaultShowFile);
-  const [showPurpose, setShowPurpose] = useState(false);
+  const [showPurposeState, setShowPurposeState] = useState(false);
+  const showPurpose = showPurposeProp ?? showPurposeState;
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = componentColor(component, pierreSyntaxTheme);
   const inlineChrome = fileBadgeChrome && showFile && !!component.file;
@@ -497,7 +517,7 @@ export function ComponentDeclaration({
       {!inlineChrome && lineLocationLabel}
       {!inlineChrome &&
         component.purpose?.trim() &&
-        toggleBtn(showPurpose, () => setShowPurpose((v) => !v), 'Toggle description', AlignLeft)}
+        toggleBtn(showPurpose, () => setShowPurposeState((v) => !v), 'Toggle description', AlignLeft)}
     </span>
   );
 
@@ -560,7 +580,7 @@ export function ComponentDeclaration({
         'purl',
       ),
     );
-  } else if (!showRepoIdentity && !inlineChrome) {
+  } else if (!showRepoIdentity && !inlineChrome && !hideActions) {
     lines.push(line(headerActions, 'actions'));
   }
 
@@ -695,7 +715,7 @@ export function ComponentDeclaration({
                 aria-label={showPurpose ? 'Hide description' : 'Show description'}
                 onClick={(e) => {
                   e.stopPropagation();
-                  setShowPurpose((v) => !v);
+                  setShowPurposeState((v) => !v);
                 }}
                 {...segHover('desc')}
                 style={{
@@ -888,14 +908,17 @@ export function ComponentDeclaration({
   );
 
   const declLines: ReactNode[][] = [[]];
+  const declLineText: string[] = [''];
   let di = 0;
   let offset = 0;
   for (const tok of tokens) {
     if (tok.kind === 'newline') {
       declLines.push([]);
+      declLineText.push('');
       di++;
       continue;
     }
+    declLineText[di] += tok.text;
     const color = tok.color ?? tokenColor[tok.kind] ?? declarationTextColor;
     let i = 0;
     while (i < tok.text.length) {
@@ -956,8 +979,78 @@ export function ComponentDeclaration({
     }
     offset += tok.text.length;
   }
+  // The rendered line carrying the construct's own name gets the known line
+  // number — a method stub wraps it in `class Host {`, so the number belongs on
+  // the member line, not the synthetic first row. Falls back to the first line.
+  const constructName =
+    component.name || component.symbol?.split('.').pop() || '';
+  let labelDi = -1;
+  if (constructName) {
+    for (let li = 0; li < declLines.length; li++) {
+      if (declLines[li].length > 0 && declLineText[li].includes(constructName)) {
+        labelDi = li;
+        break;
+      }
+    }
+  }
+  if (labelDi === -1) {
+    labelDi = declLines.findIndex((l) => l.length > 0);
+  }
   for (let li = 0; li < declLines.length; li++) {
     if (declLines[li].length === 0) continue;
+    if (lineNumbers && declarationStartLine != null) {
+      // Only the construct's own line is known; the rest of the gutter stays
+      // blank (but aligned) since later rendered lines needn't map to source.
+      const n = li === labelDi ? declarationStartLine : null;
+      const interactive = n != null && !!onOpenFile && !!component.file;
+      const gutterStyle: CSSProperties = {
+        flexShrink: 0,
+        width: GUTTER_NUMBER_WIDTH,
+        paddingRight: GUTTER_NUMBER_GAP,
+        border: 'none',
+        background: 'transparent',
+        textAlign: 'right',
+        color: muted,
+        fontFamily: 'inherit',
+        fontSize: 'inherit',
+        lineHeight: 'inherit',
+        cursor: interactive ? 'pointer' : 'default',
+        userSelect: 'none',
+      };
+      lines.push(
+        <div
+          key={`decl-${li}`}
+          style={{ display: 'flex', alignItems: 'flex-start', minWidth: 0 }}
+        >
+          {n == null ? (
+            <span style={gutterStyle} aria-hidden="true" />
+          ) : interactive ? (
+            <button
+              type="button"
+              title={`Open line ${n}`}
+              onClick={() => onOpenFile!(component.file, { startLine: n })}
+              style={gutterStyle}
+            >
+              {n}
+            </button>
+          ) : (
+            <span style={gutterStyle}>{n}</span>
+          )}
+          <div
+            style={{
+              flex: 1,
+              minWidth: 0,
+              whiteSpace: 'pre-wrap',
+              overflowWrap: 'anywhere',
+              minHeight: 18,
+            }}
+          >
+            {declLines[li]}
+          </div>
+        </div>,
+      );
+      continue;
+    }
     lines.push(
       <div
         key={`decl-${li}`}
@@ -986,7 +1079,7 @@ export function ComponentDeclaration({
             {purposeLine.trim()}
           </span>,
           `purpose${i}`,
-          false,
+          lineNumbers ? GUTTER_NUMBER_WIDTH + GUTTER_NUMBER_GAP : false,
           'normal',
         ),
       ),
@@ -1015,7 +1108,7 @@ export function ComponentDeclaration({
         minWidth: 0,
         boxSizing: 'border-box',
         background: theme.colors.backgroundSecondary,
-        padding: '10px 12px',
+        padding: lineNumbers ? '10px 12px 10px 0' : '10px 12px',
         fontFamily: theme.fonts.monospace,
         fontSize: theme.fontSizes[1],
         lineHeight: 1.7,