@principal-ai/subsystems-react 0.33.0 → 0.34.0

package/src/stories/Subsystem/ComponentDeclarationSymbols.stories.tsx

@@ -0,0 +1,269 @@
+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 { ComponentDeclaration } from '../../subsystem/ComponentDeclaration';
+import type { SubsystemComponent } from '../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../graphify';
+import type { SymbolInspection } from '../../subsystem/symbolRefs';
+
+const meta = {
+  title: 'Subsystem/ComponentDeclarationSymbols',
+  component: ComponentDeclaration,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ maxWidth: '80ch', margin: '0 auto' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof ComponentDeclaration>;
+export default meta;
+
+// ---------------------------------------------------------------------------
+// Fixture graphify lookups — one per information level. Names absent from the
+// map resolve as `missing`, mirroring "nothing in the cached graph".
+// ---------------------------------------------------------------------------
+
+const INSPECTIONS: Record<string, SymbolInspection> = {
+  RawEvent: {
+    symbol: 'RawEvent',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    resolution: 'resolved',
+    node: {
+      nodeId: 'eventprocessing_types_rawevent',
+      label: 'RawEvent',
+      sourceFile: 'src/event-processing/types.ts',
+      sourceLocation: 'L8',
+    },
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'id', type: 'string' },
+        { name: 'at', type: 'number' },
+        { name: 'payload', type: 'unknown' },
+      ],
+      usedBy: [],
+      implementors: [],
+    },
+  },
+  BaseProcessor: {
+    symbol: 'BaseProcessor',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    resolution: 'resolved',
+    node: {
+      nodeId: 'eventprocessing_baseprocessor_baseprocessor',
+      label: 'BaseProcessor',
+      sourceFile: 'src/event-processing/BaseProcessor.ts',
+      sourceLocation: 'L3',
+    },
+    declaration: {
+      kind: 'class',
+      methods: [{ nodeId: 'm-run', name: 'run', parameters: [], returnType: 'void' }],
+      properties: [],
+      extends: [],
+      implements: [],
+      instantiations: [],
+      references: [],
+    },
+  },
+  // Limited: graphify resolved the location but couldn't reconstruct the
+  // shape — the card falls back to the source declaration, still offering
+  // "Add to references" because the model has no structured declaration.
+  ProcessingOptions: {
+    symbol: 'ProcessingOptions',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    resolution: 'resolved',
+    node: {
+      nodeId: 'eventprocessing_types_processingoptions',
+      label: 'ProcessingOptions',
+      sourceFile: 'src/event-processing/types.ts',
+      sourceLocation: 'L21',
+    },
+    source: {
+      file: 'src/event-processing/types.ts',
+      startLine: 21,
+      text: 'interface ProcessingOptions {\n  retries: number;\n  timeoutMs: number;\n}',
+    },
+  },
+  // Limited: multiple same-label definitions.
+  ProcessedEvent: {
+    symbol: 'ProcessedEvent',
+    resolution: 'ambiguous',
+    candidates: [
+      { nodeId: 'a1', label: 'ProcessedEvent', sourceFile: 'src/event-processing/types.ts' },
+      { nodeId: 'a2', label: 'ProcessedEvent', sourceFile: 'src/legacy/types.ts' },
+    ],
+  },
+  // Limited: referenced but not defined in this corpus (external/ambient type).
+  Disposable: {
+    symbol: 'Disposable',
+    resolution: 'unresolved',
+    reason: 'referenced but not defined in this corpus',
+  },
+  // Limited: nothing in the corpus.
+  EventEmitterLike: {
+    symbol: 'EventEmitterLike',
+    resolution: 'missing',
+    reason: 'no matching definition in the cached graph',
+  },
+  SessionRecord: {
+    symbol: 'SessionRecord',
+    resolution: 'resolved',
+    node: {
+      nodeId: 'session_transcript_sessionrecord',
+      label: 'SessionRecord',
+      sourceFile: 'src/session/transcript.ts',
+      sourceLocation: 'L12',
+    },
+    declaration: {
+      kind: 'type',
+      properties: [
+        { name: 'id', type: 'string' },
+        { name: 'admittedSeq', type: 'number' },
+        { name: 'events', type: 'SessionEvent[]' },
+      ],
+      usedBy: [],
+      implementors: [],
+    },
+  },
+  'capture-session': {
+    symbol: 'capture-session',
+    resolution: 'resolved',
+    node: {
+      nodeId: 'session_capture_capture_session',
+      label: 'capture-session()',
+      sourceFile: 'src/session/capture.ts',
+      sourceLocation: 'L40',
+    },
+    declaration: {
+      kind: 'function',
+      parameters: [{ name: 'session', type: 'SessionRecord' }],
+      returnType: 'Promise<void>',
+      callers: [],
+      callees: [],
+    },
+  },
+};
+
+const inspect = (symbol: string): Promise<SymbolInspection> =>
+  new Promise((resolve) =>
+    setTimeout(
+      () =>
+        resolve(
+          INSPECTIONS[symbol] ?? {
+            symbol,
+            resolution: 'missing',
+            reason: 'no matching definition in the cached graph',
+          },
+        ),
+      220,
+    ),
+  );
+
+function Harness({ component }: { component: SubsystemComponent }) {
+  const [log, setLog] = useState<string[]>([]);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <div style={{ fontFamily: 'monospace', fontSize: 11, color: '#888' }}>
+        Click a dotted-underlined symbol to inspect what graphify has on it.
+      </div>
+      <ComponentDeclaration
+        component={component}
+        onInspectSymbol={inspect}
+        onAddToModel={(ref, info) =>
+          setLog((l) => [`add ${ref.name} (${info?.resolution ?? 'no info'})`, ...l])
+        }
+        onOpenFile={(file, opts) =>
+          setLog((l) => [
+            `open ${file}${opts?.startLine ? `:${opts.startLine}` : ''}`,
+            ...l,
+          ])
+        }
+      />
+      <div
+        data-symbol-action-log
+        style={{ fontFamily: 'monospace', fontSize: 11, color: '#6a9955', minHeight: 16 }}
+      >
+        {log.length ? `actions: ${log.join(' · ')}` : 'actions: —'}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// A class whose declaration references a range of symbols — resolved
+// (type/class), thin (unknown construct → "Add to references"), ambiguous,
+// unresolved, and missing.
+// ---------------------------------------------------------------------------
+
+const classComponent: SubsystemComponent = {
+  alias: 'class-event-processor',
+  name: 'EventProcessor',
+  construct: 'class',
+  file: 'src/event-processing/EventProcessor.ts',
+  purl: 'pkg:github/principal-ai/agent-monitoring',
+  symbol: 'EventProcessor',
+  purpose: 'Consumes raw events and emits processed ones.',
+  declaration: {
+    kind: 'class',
+    methods: [
+      {
+        nodeId: 'm-process',
+        name: 'process',
+        parameters: [
+          { name: 'event', type: 'RawEvent' },
+          { name: 'options', type: 'ProcessingOptions' },
+        ],
+        returnType: 'ProcessedEvent',
+      },
+      {
+        nodeId: 'm-batch',
+        name: 'batch',
+        parameters: [{ name: 'events', type: 'RawEvent[]' }],
+        returnType: 'Promise<ProcessedEvent[]>',
+      },
+      { nodeId: 'm-dispose', name: 'dispose' },
+    ],
+    properties: [
+      { name: 'queue', type: 'RawEvent[]' },
+      { name: 'options', type: 'Required<ProcessingOptions>' },
+    ],
+    extends: ['BaseProcessor'],
+    implements: ['Disposable', 'EventEmitterLike'],
+    instantiations: [],
+    references: [{ nodeId: 'n-emitter', name: 'EventEmitterLike', context: 'type' }],
+  } satisfies GraphifyComponentDetail,
+};
+
+export const InspectableSymbols: StoryObj<Record<string, never>> = {
+  render: () => <Harness component={classComponent} />,
+};
+
+// ---------------------------------------------------------------------------
+// A function — callers/callees are clickable too, alongside param/return types.
+// ---------------------------------------------------------------------------
+
+const functionComponent: SubsystemComponent = {
+  alias: 'fn-normalize',
+  name: 'normalize',
+  construct: 'function',
+  file: 'src/session/SessionReader.ts',
+  purl: 'pkg:github/principal-ai/agent-monitoring',
+  symbol: 'SessionReader.normalize',
+  declaration: {
+    kind: 'function',
+    parameters: [{ name: 'session', type: 'SessionRecord' }],
+    returnType: 'SessionEvent[]',
+    callers: [{ nodeId: 'c1', name: 'capture-session', source_location: 'L120' }],
+    callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+  } satisfies GraphifyComponentDetail,
+};
+
+export const CallableRelated: StoryObj<Record<string, never>> = {
+  render: () => <Harness component={functionComponent} />,
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -6,7 +6,7 @@
  * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { AlignLeft, FileText } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
@@ -19,6 +19,38 @@ import type { SubsystemOpenFileOptions } from './declarationRef';
 import { parseSourceLocation } from './declarationRef';
 import { tokenizeComponent } from './tokenizeComponent';
 import { componentColor } from '../pierre/constructColors';
+import type { DeclarationSymbolRef, SymbolInspection } from './symbolRefs';
+import { extractDeclarationSymbolRefs } from './symbolRefs';
+import { SymbolInspectionCard } from './SymbolInspectionCard';
+
+/** One clickable span in the token stream, mapped to a referenced symbol. */
+interface SymbolClickRange {
+  start: number;
+  end: number;
+  ref: DeclarationSymbolRef;
+}
+
+/** Whole-word occurrences of `name` in `text` (identifier boundaries only). */
+function findSymbolOccurrences(
+  text: string,
+  name: string,
+): { start: number; end: number }[] {
+  const out: { start: number; end: number }[] = [];
+  if (!name) return out;
+  const isWordChar = (ch: string) => /[\w$]/.test(ch);
+  let from = 0;
+  for (;;) {
+    const idx = text.indexOf(name, from);
+    if (idx < 0) break;
+    const before = idx > 0 ? text[idx - 1]! : '';
+    const after = text[idx + name.length] ?? '';
+    if ((!before || !isWordChar(before)) && (!after || !isWordChar(after))) {
+      out.push({ start: idx, end: idx + name.length });
+    }
+    from = idx + name.length;
+  }
+  return out;
+}
 
 /** Live / result state for the declaration-panel Verify control. */
 export type ComponentVerificationPhase =
@@ -113,6 +145,14 @@ export interface ComponentDeclarationProps {
   /** Related-name click (types, callers/callees, implementors, …) → select
    *  that component if one matches; unmatched refs no-op. */
   onRelatedSelect?: (ref: string) => void;
+  /** Referenced-symbol click → resolve it against graphify. When absent,
+   *  symbols are not clickable. Host-injected; stories pass a fixture. */
+  onInspectSymbol?: (
+    symbol: string,
+    ref: DeclarationSymbolRef,
+  ) => Promise<SymbolInspection | null> | SymbolInspection | null;
+  /** "Add to references" from the inspection card. */
+  onAddToModel?: (ref: DeclarationSymbolRef, info?: SymbolInspection) => void;
   /** Max width of the declaration panel (CSS value). Defaults to none. */
   maxWidth?: string | number;
   /** Live verification status for the selected component. */
@@ -267,6 +307,8 @@ export function ComponentDeclaration({
   component,
   onOpenFile,
   onRelatedSelect: _onRelatedSelect,
+  onInspectSymbol,
+  onAddToModel,
   maxWidth,
   verification,
   defaultShowFile = false,
@@ -300,6 +342,53 @@ export function ComponentDeclaration({
   /** Fallback when wire tokens omit Shiki colors. */
   const declarationTextColor = muted;
 
+  // Symbols the declaration references — made clickable for a graphify lookup.
+  const symbolRefs = useMemo(
+    () => extractDeclarationSymbolRefs(component.declaration),
+    [component.declaration],
+  );
+  const [inspection, setInspection] = useState<
+    | {
+        ref: DeclarationSymbolRef;
+        loading: boolean;
+        info?: SymbolInspection;
+        error?: string;
+        x: number;
+        y: number;
+      }
+    | null
+  >(null);
+  // Symbol name currently hovered, so every occurrence of the same symbol can
+  // highlight together (and stay lit while its popover is open).
+  const [hoveredSymbol, setHoveredSymbol] = useState<string | null>(null);
+  const activeSymbol = inspection?.ref.name ?? null;
+
+  // Dismiss the inspection card on outside click / Escape.
+  useEffect(() => {
+    if (!inspection) return;
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as HTMLElement | null;
+      // The popover, and the symbol spans themselves (they toggle on click),
+      // must not be treated as outside.
+      if (t?.closest('[data-symbol-inspection]')) return;
+      if (t?.closest('[data-symbol-ref]')) return;
+      setInspection(null);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        // Drop focus from the symbol span so no focus ring lingers after close.
+        (document.activeElement as HTMLElement | null)?.blur?.();
+        setInspection(null);
+      }
+    };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [inspection]);
+
   const declarationStartLine =
     component.declarationRef?.startLine ??
     verification?.declaration?.ref?.startLine ??
@@ -729,22 +818,140 @@ export function ComponentDeclaration({
       cancelled = true;
     };
   }, [component, printWidth, pierreSyntaxTheme]);
+
+  // Map character offsets in the concatenated token text to referenced symbols,
+  // so inline occurrences render as clickable spans. `-1` = not a symbol.
+  const clickIndex = useMemo(() => {
+    const full = tokens.map((t) => t.text).join('');
+    const rangeAt = new Int32Array(full.length).fill(-1);
+    if (!onInspectSymbol || symbolRefs.length === 0) {
+      return { ranges: [] as SymbolClickRange[], rangeAt };
+    }
+    const ranges: SymbolClickRange[] = [];
+    for (const ref of symbolRefs) {
+      for (const occ of findSymbolOccurrences(full, ref.name)) {
+        ranges.push({ start: occ.start, end: occ.end, ref });
+      }
+    }
+    ranges.sort((a, b) => a.start - b.start);
+    ranges.forEach((r, i) => {
+      for (let k = r.start; k < r.end && k < rangeAt.length; k++) {
+        if (rangeAt[k] === -1) rangeAt[k] = i;
+      }
+    });
+    return { ranges, rangeAt };
+  }, [onInspectSymbol, symbolRefs, tokens]);
+
+  const handleInspect = useCallback(
+    async (ref: DeclarationSymbolRef, el: HTMLElement) => {
+      if (!onInspectSymbol) return;
+      // Toggle: clicking the symbol whose popover is already open closes it.
+      if (inspection?.ref.name === ref.name) {
+        setInspection(null);
+        return;
+      }
+      let x = 0;
+      let y = 0;
+      const cont = containerRef.current;
+      if (cont) {
+        const crect = cont.getBoundingClientRect();
+        const r = el.getBoundingClientRect();
+        x = r.left - crect.left;
+        y = r.bottom - crect.top + 4;
+      }
+      setInspection({ ref, loading: true, x, y });
+      try {
+        const info = await onInspectSymbol(ref.name, ref);
+        setInspection((cur) =>
+          cur?.ref.name === ref.name
+            ? { ref, loading: false, info: info ?? undefined, x, y }
+            : cur,
+        );
+      } catch (err) {
+        setInspection((cur) =>
+          cur?.ref.name === ref.name
+            ? {
+                ref,
+                loading: false,
+                error: err instanceof Error ? err.message : String(err),
+                x,
+                y,
+              }
+            : cur,
+        );
+      }
+    },
+    [onInspectSymbol, inspection],
+  );
+
   const declLines: ReactNode[][] = [[]];
   let di = 0;
+  let offset = 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: tok.color ?? tokenColor[tok.kind] ?? declarationTextColor }}
-      >
-        {tok.text}
-      </span>,
-    );
+    const color = tok.color ?? tokenColor[tok.kind] ?? declarationTextColor;
+    let i = 0;
+    while (i < tok.text.length) {
+      const rIdx = clickIndex.rangeAt[offset + i] ?? -1;
+      let j = i + 1;
+      while (j < tok.text.length && (clickIndex.rangeAt[offset + j] ?? -1) === rIdx) {
+        j++;
+      }
+      const piece = tok.text.slice(i, j);
+      const key = `${di}-${declLines[di].length}`;
+      const range = rIdx >= 0 ? clickIndex.ranges[rIdx] : undefined;
+      if (range) {
+        const ref = range.ref;
+        const hovered = hoveredSymbol === ref.name;
+        // Active (popover open for this symbol) is the only state that gets a
+        // solid underline; hover just shifts the color.
+        const active = activeSymbol === ref.name;
+        const lit = hovered || active;
+        declLines[di].push(
+          <span
+            key={key}
+            role="button"
+            tabIndex={0}
+            data-symbol-ref={ref.name}
+            // Don't take focus on mouse click — otherwise closing the popover
+            // (Escape) leaves a focus ring around the clicked symbol.
+            onMouseDown={(e) => e.preventDefault()}
+            onMouseEnter={() => setHoveredSymbol(ref.name)}
+            onMouseLeave={(e) => {
+              // Keep it lit when moving straight to another occurrence of the
+              // same symbol; otherwise clear on unhover.
+              const to = e.relatedTarget as HTMLElement | null;
+              const next = to?.closest('[data-symbol-ref]')?.getAttribute('data-symbol-ref');
+              if (next === ref.name) return;
+              setHoveredSymbol((s) => (s === ref.name ? null : s));
+            }}
+            onClick={(e) => handleInspect(ref, e.currentTarget)}
+            style={{
+              // Lit occurrences shift to the accent color (no background fill).
+              color: lit ? theme.colors.accent ?? theme.colors.secondary : color,
+              cursor: 'pointer',
+              textDecorationLine: 'underline',
+              textDecorationStyle: active ? 'solid' : 'dotted',
+              textUnderlineOffset: 2,
+            }}
+          >
+            {piece}
+          </span>,
+        );
+      } else {
+        declLines[di].push(
+          <span key={key} style={{ color }}>
+            {piece}
+          </span>,
+        );
+      }
+      i = j;
+    }
+    offset += tok.text.length;
   }
   for (let li = 0; li < declLines.length; li++) {
     if (declLines[li].length === 0) continue;
@@ -783,10 +990,22 @@ export function ComponentDeclaration({
     );
   }
 
+  const inspectionLeft = inspection
+    ? Math.max(
+        0,
+        Math.min(
+          inspection.x,
+          Math.max(0, (containerRef.current?.clientWidth ?? 320) - 320),
+        ),
+      )
+    : 0;
+
   return (
     <div
       ref={containerRef}
+      onMouseLeave={() => setHoveredSymbol(null)}
       style={{
+        position: 'relative',
         width: '100%',
         minWidth: 0,
         boxSizing: 'border-box',
@@ -800,6 +1019,17 @@ export function ComponentDeclaration({
       }}
     >
       {lines}
+      {inspection && !inspection.loading && (
+        <SymbolInspectionCard
+          symbolRef={inspection.ref}
+          inspection={inspection.info}
+          error={inspection.error}
+          onClose={() => setInspection(null)}
+          onAddToModel={onAddToModel}
+          onOpenFile={onOpenFile}
+          style={{ left: inspectionLeft, top: inspection.y }}
+        />
+      )}
     </div>
   );
 }

package/src/subsystem/IssueList.tsx

@@ -38,13 +38,15 @@ export type SubsystemIssueTargetKind =
 
 /**
  * The four verification layers, in order. Mirrors the docs' progression:
- * constructs → static topology → runtime topology → walkthrough.
+ * constructs → static topology → dynamic topology → walkthrough.
+ * Static topology = relations; dynamic topology = process (runtime) +
+ * package/module (containment).
  */
 export type SubsystemIssueCategory =
   | 'repo'
   | 'construct'
   | 'static-topology'
-  | 'runtime-topology'
+  | 'dynamic-topology'
   | 'walkthrough';
 
 /** Layer order + display names, shared by the list and its headers. */
@@ -52,7 +54,7 @@ export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
   'repo',
   'construct',
   'static-topology',
-  'runtime-topology',
+  'dynamic-topology',
   'walkthrough',
 ];
 
@@ -64,7 +66,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_ICON: Record<
   repo: FolderGit2,
   construct: Component,
   'static-topology': Network,
-  'runtime-topology': Server,
+  'dynamic-topology': Server,
   walkthrough: Route,
 };
 
@@ -75,11 +77,11 @@ export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
   repo: 'Repositories',
   construct: 'Constructs',
   'static-topology': 'Static topology',
-  'runtime-topology': 'Runtime topology',
+  'dynamic-topology': 'Dynamic topology',
   walkthrough: 'Walkthrough',
 };
 
-/** Default `kind` → layer. `boundary_*` splits by module (static) vs process (runtime). */
+/** Default `kind` → layer. `boundary_*` (module containment + process) is dynamic. */
 const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   missing_file: 'construct',
   symbol_ambiguous: 'construct',
@@ -94,8 +96,8 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   topology_broken_endpoint: 'static-topology',
   topology_import_unconfirmed: 'static-topology',
   topology_relation_unconfirmed: 'static-topology',
-  boundary_module_file_mismatch: 'static-topology',
-  boundary_process_nest_disagree: 'runtime-topology',
+  boundary_module_file_mismatch: 'dynamic-topology',
+  boundary_process_nest_disagree: 'dynamic-topology',
   walkthrough: 'walkthrough',
 };