@principal-ai/principal-view-react 0.16.44 → 0.16.46

package/src/stories/ComponentDeclarationAudit.stories.tsx

@@ -0,0 +1,290 @@
+import React from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { ComponentDeclaration } from '../subsystem/ComponentDeclaration';
+import type { SubsystemComponent } from '../subsystem/model';
+import type { GraphifyComponentDetail } from '../graphify';
+
+const meta = {
+  title: 'Subsystem/Component Declaration Audit',
+  component: ComponentDeclaration,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  argTypes: {
+    constrained: { control: 'boolean', description: 'Toggle 80ch max-width wrapping' },
+  },
+  args: {
+    constrained: true,
+  },
+  decorators: [
+    (Story, ctx) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ maxWidth: ctx.args.constrained ? '80ch' : 'none', margin: '0 auto' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof ComponentDeclaration>;
+export default meta;
+type Story = StoryObj<typeof ComponentDeclaration>;
+
+// ---------------------------------------------------------------------------
+// All cases — one SubsystemComponent per shape, rendered stacked
+// ---------------------------------------------------------------------------
+
+const cases: { label: string; component: SubsystemComponent }[] = [
+  {
+    label: 'function — no params',
+    component: {
+      id: 'fn-void',
+      name: 'flush',
+      kind: 'function',
+      file: 'src/event-processing/sink.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'flush',
+      detail: {
+        kind: 'function',
+        parameters: [],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — single param',
+    component: {
+      id: 'fn-one',
+      name: 'normalize',
+      kind: 'function',
+      file: 'src/session/SessionReader.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'SessionReader.normalize',
+      detail: {
+        kind: 'function',
+        parameters: [{ name: 'session', type: 'SessionRecord' }],
+        returnType: 'SessionEvent[]',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — two params',
+    component: {
+      id: 'fn-two',
+      name: 'normalizeSession',
+      kind: 'function',
+      file: 'src/event-processing/normalize.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'normalizeSession',
+      detail: {
+        kind: 'function',
+        parameters: [
+          { name: 'session', type: 'SessionRecord' },
+          { name: 'limit', type: 'number' },
+        ],
+        returnType: 'SessionEvent[]',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — rich params (positional, union, callback, generic return)',
+    component: {
+      id: 'fn-rich',
+      name: 'mergeSessions',
+      kind: 'function',
+      file: 'src/session/merge.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'mergeSessions',
+      detail: {
+        kind: 'function',
+        parameters: [
+          { name: 'sessions', type: 'SessionRecord[]' },
+          { type: 'MergeOptions' },
+          { name: 'strategy', type: "'append' | 'replace' | 'skip'" },
+          { name: 'onConflict', type: '((a: SessionRecord, b: SessionRecord) => SessionRecord)' },
+        ],
+        returnType: 'Promise<Map<string, SessionEvent[]>>',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — no body',
+    component: {
+      id: 'class-empty',
+      name: 'EmptyClass',
+      kind: 'class',
+      file: 'src/empty.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'EmptyClass',
+      detail: {
+        kind: 'class',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — properties only',
+    component: {
+      id: 'class-props',
+      name: 'Config',
+      kind: 'class',
+      file: 'src/config.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'Config',
+      detail: {
+        kind: 'class',
+        properties: [
+          { name: 'host', type: 'string' },
+          { name: 'port', type: 'number' },
+          { name: 'tls', type: 'boolean' },
+        ],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — methods + properties + extends + implements',
+    component: {
+      id: 'class-rich',
+      name: 'EventProcessor',
+      kind: 'class',
+      file: 'src/event-processing/EventProcessor.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'EventProcessor',
+      detail: {
+        kind: 'class',
+        methods: [
+          { name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
+          { name: 'batch', parameters: [{ type: 'RawEvent[]' }], returnType: 'Promise<ProcessedEvent[]>' },
+          { name: 'onError', parameters: [{ type: 'Error' }] },
+          { name: 'dispose' },
+        ],
+        properties: [
+          { name: 'queue', type: 'RawEvent[]' },
+          { name: 'options', type: 'Required<ProcessingOptions>' },
+          { name: 'retryLimit', type: 'number' },
+        ],
+        extends: ['BaseProcessor'],
+        implements: ['Disposable', 'EventEmitterLike'],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'type — properties',
+    component: {
+      id: 'type-props',
+      name: 'SessionRecord',
+      kind: 'type',
+      file: 'src/session/transcript.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'SessionRecord',
+      detail: {
+        kind: 'type',
+        properties: [
+          { name: 'id', type: 'string' },
+          { name: 'admittedSeq', type: 'number' },
+        ],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'type — no properties',
+    component: {
+      id: 'type-empty',
+      name: 'BrandedId',
+      kind: 'type',
+      file: 'src/types.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'BrandedId',
+      detail: {
+        kind: 'type',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'module — imports + exports',
+    component: {
+      id: 'mod-full',
+      name: 'index',
+      kind: 'module',
+      file: 'src/index.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'index',
+      detail: {
+        kind: 'module',
+        imports: [
+          { name: './session/SessionReader' },
+          { name: './event-processing/EventProcessor' },
+        ],
+        exports: ['SessionReader', 'EventProcessor'],
+        symbols: ['SessionReader', 'EventProcessor', 'normalizeSession'],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'module — no detail (fallback)',
+    component: {
+      id: 'mod-plain',
+      name: 'utils',
+      kind: 'module',
+      file: 'src/utils.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'utils',
+    },
+  },
+  {
+    label: 'external',
+    component: {
+      id: 'ext',
+      name: 'trail-viewer',
+      kind: 'external',
+      file: '',
+      purl: 'pkg:npm/@principal-ai/trail-viewer',
+      symbol: '',
+      detail: {
+        kind: 'external',
+        label: 'pkg:npm/@principal-ai/trail-viewer',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — no symbol (uses name fallback)',
+    component: {
+      id: 'fn-no-symbol',
+      name: 'anonymousHelper',
+      kind: 'function',
+      file: 'src/helpers.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      detail: {
+        kind: 'function',
+        parameters: [{ name: 'input', type: 'string' }],
+        returnType: 'void',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Story — all cases stacked
+// ---------------------------------------------------------------------------
+
+export const AllCases: StoryObj<{ constrained: boolean }> = {
+  render: ({ constrained }) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      {cases.map((c) => (
+        <div key={c.label}>
+          <div
+            style={{
+              fontFamily: 'monospace',
+              fontSize: 11,
+              color: '#888',
+              marginBottom: 4,
+              textTransform: 'uppercase',
+              letterSpacing: '0.05em',
+            }}
+          >
+            {c.label}
+          </div>
+          <ComponentDeclaration component={c.component} maxWidth={constrained ? '80ch' : undefined} />
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -6,15 +6,16 @@
  * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import { Fragment, useState, type ReactNode } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 import { AlignLeft, FileText } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
   KIND_COLOR,
-  deriveNameFromSymbol,
   formatPurl,
   type SubsystemComponent,
+  type SubsystemDeclTokenKind,
 } from './model';
+import { tokenizeComponent } from './tokenizeComponent';
 
 /** Shared affordance for clickable text pieces. */
 const clickableStyle = {
@@ -54,10 +55,12 @@ export interface ComponentDeclarationProps {
   /** Related-name click (types, callers/callees, implementors, …) → select
    *  that component if one matches; unmatched refs no-op. */
   onRelatedSelect?: (ref: string) => void;
+  /** Max width of the declaration panel (CSS value). Defaults to none. */
+  maxWidth?: string | number;
 }
 
 /** Declaration panel for the selected component — its definition, code-style. */
-export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }: ComponentDeclarationProps) {
+export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _onRelatedSelect, maxWidth }: ComponentDeclarationProps) {
   const { theme } = useTheme();
   const [fileHovered, setFileHovered] = useState(false);
   // Header visibility toggles — off by default so the panel opens as pure
@@ -66,26 +69,26 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = KIND_COLOR[component.kind] ?? '#888';
-  const displayName = deriveNameFromSymbol(component.symbol, component.kind, component.name, component.file);
 
-  // Token styles — keyword / name / member / type / string / punctuation.
-  const kw = (text: string) => <span style={{ color: theme.colors.secondary }}>{text}</span>;
-  const nm = (text: string) => <span style={{ color }}>{text}</span>;
-  const mb = (text: string) => <span style={{ color: theme.colors.info }}>{text}</span>;
-  // Type tokens are links into the graph (other components often own them).
-  const ty = (text: string) => (
-    <DetailLink onClick={onRelatedSelect ? () => onRelatedSelect(text) : undefined}>
-      <span style={{ color: theme.colors.accent }}>{text}</span>
-    </DetailLink>
-  );
-  const str = (text: string) => <span style={{ color: theme.colors.success }}>{text}</span>;
-  const pn = (text: string) => <span style={{ color: muted }}>{text}</span>;
+  // Token-kind → theme-color map (used by the token iterator below).
+  const tokenColor: Record<SubsystemDeclTokenKind, string> = {
+    keyword: theme.colors.secondary,
+    name: color,
+    member: theme.colors.info,
+    type: theme.colors.accent,
+    punctuation: muted,
+    string: theme.colors.success,
+    newline: '', // not rendered — drives line breaks
+  };
 
-  const line = (children: ReactNode, key?: string, indent?: boolean) => (
-    <div key={key} style={indent ? { paddingLeft: 16 } : undefined}>
-      {children}
-    </div>
-  );
+  const line = (children: ReactNode, key?: string, indent?: boolean | number) => {
+    const paddingLeft = typeof indent === 'number' ? indent : indent ? 16 : 0;
+    return (
+      <div key={key} style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18, ...(paddingLeft ? { paddingLeft } : {}) }}>
+        {children}
+      </div>
+    );
+  };
   const commentStyle = { color: muted, fontStyle: 'italic' } as const;
   const commentLine = (text: string, key?: string, indent?: boolean, onClick?: () => void) =>
     line(
@@ -109,15 +112,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
   // `// implemented by:`, …) are deliberately not rendered — the graph's
   // edges carry interactions, and duplicated name lists read as clutter. The
   // data stays on the Graphify detail types for other surfaces.
-  // Comma-join rendered tokens without raw-array key churn.
-  const list = (items: ReactNode[]) =>
-    items.map((item, i) => (
-      <Fragment key={i}>
-        {i > 0 ? ', ' : null}
-        {item}
-      </Fragment>
-    ));
-
   const lines: ReactNode[] = [];
   // Repo identity — owner avatar + name for GitHub-hosted purls; anything
   // else falls back to the formatted purl as a quiet comment. The avatar
@@ -207,246 +201,42 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
       ),
     );
 
-  const detail = component.detail;
-  // Detail facets may be hand-authored (see `detailProvenance`) and the wire
-  // carries no guarantee that every typed array is present — treat all of
-  // them as optional so a partial detail degrades to fewer lines, never a
-  // render crash.
-  switch (detail?.kind ?? component.kind) {
-    case 'class': {
-      const members: ReactNode[] = [];
-      if (detail?.kind === 'class') {
-        (detail.methods ?? []).forEach((m, i) =>
-          members.push(
-            line(
-              <>
-                {mb(m.name)}
-                {pn('(')}
-                {(m.parameters ?? []).length > 0 &&
-                  list(
-                    (m.parameters ?? []).map((p, j) => (
-                      <Fragment key={j}>
-                        {p.name ? (
-                          <>
-                            {mb(p.name)}
-                            {pn(': ')}
-                          </>
-                        ) : null}
-                        {ty(p.type)}
-                      </Fragment>
-                    )),
-                  )}
-                {pn(')')}
-                {m.returnType ? (
-                  <>
-                    {pn(': ')}
-                    {ty(m.returnType)}
-                  </>
-                ) : null}
-              </>,
-              `m${i}`,
-              true,
-            ),
-          ),
-        );
-        (detail.properties ?? []).forEach((prop, i) =>
-          members.push(
-            line(
-              <>
-                {mb(prop.name)}
-                {prop.type ? (
-                  <>
-                    {pn(': ')}
-                    {ty(prop.type)}
-                  </>
-                ) : null}
-              </>,
-              `p${i}`,
-              true,
-            ),
-          ),
-        );
-      }
-      const cls = detail?.kind === 'class' ? detail : undefined;
-      const hasBody = members.length > 0;
-      lines.push(
-        line(
-          <>
-            {kw('class')}
-            {' '}
-            {nm(displayName)}
-            {cls && (cls.extends ?? []).length > 0 && (
-              <>
-                {' '}
-                {kw('extends')}
-                {' '}
-                {list((cls.extends ?? []).map((e, i) => <Fragment key={i}>{ty(e)}</Fragment>))}
-              </>
-            )}
-            {cls && (cls.implements ?? []).length > 0 && (
-              <>
-                {' '}
-                {kw('implements')}
-                {' '}
-                {list((cls.implements ?? []).map((e, i) => <Fragment key={i}>{ty(e)}</Fragment>))}
-              </>
-            )}
-            {hasBody ? pn(' {') : null}
-          </>,
-          'decl',
-        ),
-      );
-      lines.push(...members);
-      if (hasBody) lines.push(line(pn('}'), 'end'));
-      break;
+  // --- Declaration tokens ------------------------------------------------
+  // Tokenize asynchronously via Prettier + highlight.js. Pre-tokenized
+  // tokens from the wire skip the pipeline entirely.
+  const [tokens, setTokens] = useState(component.tokens ?? []);
+  useEffect(() => {
+    if (component.tokens) {
+      setTokens(component.tokens);
+      return;
     }
-    case 'function': {
-      const fn = detail?.kind === 'function' ? detail : undefined;
-      const params = fn?.parameters ?? [];
-      lines.push(
-        line(
-          <>
-            {kw('function')}
-            {' '}
-            {nm(displayName)}
-            {pn('(')}
-            {params.length > 0 &&
-              list(
-                params.map((param, i) => (
-                  <Fragment key={i}>
-                    {param.name ? (
-                      <>
-                        {mb(param.name)}
-                        {pn(': ')}
-                      </>
-                    ) : null}
-                    {ty(param.type)}
-                  </Fragment>
-                )),
-              )}
-            {pn(')')}
-            {fn?.returnType ? (
-              <>
-                {pn(': ')}
-                {ty(fn.returnType)}
-              </>
-            ) : null}
-            {pn(';')}
-          </>,
-          'decl',
-        ),
-      );
-      // Caller/callee relationship comments (`// called by:` / `// calls:`)
-      // are deliberately not rendered here — the graph's edges carry
-      // interactions, and duplicated call lists read as clutter. The data
-      // stays on `GraphifyFunctionDetail` for other surfaces.
-      break;
-    }
-    case 'type': {
-      const tpe = detail?.kind === 'type' ? detail : undefined;
-      const hasBody = ((tpe?.properties ?? []).length) > 0;
-      lines.push(
-        line(
-          <>
-            {kw('interface')}
-            {' '}
-            {nm(displayName)}
-            {hasBody ? pn(' {') : null}
-          </>,
-          'decl',
-        ),
-      );
-      if (tpe) {
-        (tpe.properties ?? []).forEach((prop, i) =>
-          lines.push(
-            line(
-              <>
-                {mb(prop.name)}
-                {prop.type ? (
-                  <>
-                    {pn(': ')}
-                    {ty(prop.type)}
-                  </>
-                ) : null}
-                {pn(';')}
-              </>,
-              `p${i}`,
-              true,
-            ),
-          ),
-        );
-      }
-      if (hasBody) lines.push(line(pn('}'), 'end'));
-      break;
-    }
-    case 'module': {
-      const mod = detail?.kind === 'module' ? detail : undefined;
-      if (mod) {
-        (mod.imports ?? []).forEach((imp, i) =>
-          lines.push(
-            line(
-              <>
-                {kw('import')}
-                {' '}
-                {pn("'")}
-                {str(imp.name)}
-                {pn("';")}
-              </>,
-              `imp${i}`,
-            ),
-          ),
-        );
-        if ((mod.exports ?? []).length > 0)
-          lines.push(
-            line(
-              <>
-                {kw('export')}
-                {' '}
-                {pn('{ ')}
-                {list((mod.exports ?? []).map((e, i) => <Fragment key={i}>{mb(e)}</Fragment>))}
-                {pn(' }')}
-                {pn(';')}
-              </>,
-              'exports',
-            ),
-          );
-        if ((mod.symbols ?? []).length > 0)
-          lines.push(commentLine(`// defines: ${(mod.symbols ?? []).join(', ')}`, 'symbols'));
-      } else {
-        lines.push(
-          line(
-            <>
-              {kw('module')}
-              {' '}
-              {nm(displayName)}
-            </>,
-            'decl',
-          ),
-        );
-      }
-      break;
-    }
-    case 'external': {
-      lines.push(
-        line(
-          <>
-            {kw('external')}
-            {' '}
-            {detail?.kind === 'external' ? (
-              <>
-                {pn("'")}
-                {str(detail.label)}
-                {pn("'")}
-              </>
-            ) : (
-              nm(displayName)
-            )}
-          </>,
-          'decl',
-        ),
-      );
-      break;
+    let cancelled = false;
+    tokenizeComponent(component).then((t) => {
+      if (!cancelled) setTokens(t);
+    });
+    return () => { cancelled = true; };
+  }, [component]);
+  const declLines: ReactNode[][] = [[]];
+  let di = 0;
+  for (const tok of tokens) {
+    if (tok.kind === 'newline') {
+      declLines.push([]);
+      di++;
+      continue;
     }
+    declLines[di].push(
+      <span key={`${di}-${declLines[di].length}`} style={{ color: tokenColor[tok.kind] }}>
+        {tok.text}
+      </span>,
+    );
+  }
+  for (let li = 0; li < declLines.length; li++) {
+    if (declLines[li].length === 0) continue;
+    lines.push(
+      <div key={`decl-${li}`} style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18 }}>
+        {declLines[li]}
+      </div>,
+    );
   }
 
   // Purpose prose follows the declaration — identity and syntax first, the
@@ -474,7 +264,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
         fontFamily: theme.fonts.monospace,
         fontSize: theme.fontSizes[1],
         lineHeight: 1.7,
-        wordBreak: 'break-word',
+        ...(maxWidth != null
+          ? { maxWidth, wordBreak: 'break-word' }
+          : { overflowX: 'auto' }),
       }}
     >
       {lines}