@principal-ai/principal-view-react 0.16.47 → 0.16.50

package/src/subsystem/ComponentDeclaration.tsx

@@ -6,8 +6,8 @@
  * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
-import { AlignLeft, FileText } from 'lucide-react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { AlignLeft, FileText, ShieldCheck } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
   KIND_COLOR,
@@ -17,6 +17,53 @@ import {
 } from './model';
 import { tokenizeComponent } from './tokenizeComponent';
 
+/** Live / result state for the declaration-panel Verify control. */
+export type ComponentVerificationPhase =
+  | 'idle'
+  | 'checking'
+  | 'done'
+  | 'error';
+
+export interface ComponentVerificationState {
+  phase: ComponentVerificationPhase;
+  message?: string;
+  /** Mirrors host `ok` when a structured verify result is available. */
+  ok?: boolean;
+  code?: string;
+  file?: {
+    exists: boolean;
+    symbolDeclared?: boolean | null;
+  };
+  cache?: {
+    status: 'ready' | 'missing' | 'unavailable';
+    purl: string;
+  };
+  anchor?: {
+    resolution: 'exact' | 'file-only' | 'ambiguous' | 'missing';
+    nodeId?: string;
+    label?: string;
+    source_file?: string;
+    source_location?: string;
+    candidates?: Array<{ nodeId: string; label: string; source_file?: string }>;
+  };
+  kind?: {
+    claimed: string;
+    inferred: string;
+    match: boolean;
+    evidence?: string[];
+  };
+  signature?: {
+    match: boolean;
+    skipped: boolean;
+    skipCode?: string;
+    reason?: string;
+    claimed: { parameterTypes: string[]; returnTypes: string[] };
+    inferred: { parameterTypes: string[]; returnTypes: string[] };
+    /** Graphify `inline_parameter` marker count (anonymous eager args). */
+    inlineParameters?: number;
+  };
+}
+
 /** Shared affordance for clickable text pieces. */
 const clickableStyle = {
   cursor: 'pointer',
@@ -46,8 +93,8 @@ function DetailLink({ children, onClick }: { children: ReactNode; onClick?: () =
   );
 }
 
-/** Panel props. The two callbacks are wired by the graph; standalone usage
- *  without them renders the same panel with nothing clickable. */
+/** Panel props. Callbacks are wired by the graph; standalone usage without
+ *  them renders the same panel with nothing clickable. */
 export interface ComponentDeclarationProps {
   component: SubsystemComponent;
   /** File-path click → open that file in the bottom drawer. */
@@ -57,20 +104,153 @@ export interface ComponentDeclarationProps {
   onRelatedSelect?: (ref: string) => void;
   /** Max width of the declaration panel (CSS value). Defaults to none. */
   maxWidth?: string | number;
+  /** When set, shows a Verify control that calls back with the component id. */
+  onVerify?: (componentId: string) => void;
+  /** Live verification status for the selected component. */
+  verification?: ComponentVerificationState | null;
+}
+
+function verificationSummary(
+  v: ComponentVerificationState,
+  muted: string,
+  ok: string,
+  warn: string,
+): { text: string; color: string } {
+  if (v.phase === 'checking') {
+    return { text: v.message ?? 'Verifying…', color: muted };
+  }
+  if (v.phase === 'error') {
+    return { text: v.message ?? 'Verification failed', color: '#e5534b' };
+  }
+  if (v.phase !== 'done') {
+    return { text: '', color: muted };
+  }
+  const bits: string[] = [];
+  if (v.file) {
+    if (!v.file.exists) bits.push('file missing');
+    else if (v.file.symbolDeclared === false) bits.push('symbol not declared in file');
+    else if (v.file.symbolDeclared === true) bits.push('file+symbol ok');
+    else bits.push('file exists');
+  }
+  if (v.cache?.status === 'missing') {
+    return {
+      text: [...bits, 'graphify cache not ready — run graphify from Subsystems list'].join(' · '),
+      color: warn,
+    };
+  }
+  if (v.cache?.status === 'unavailable') {
+    return {
+      text: [...bits, 'no local checkout for this purl'].join(' · '),
+      color: muted,
+    };
+  }
+  const res = v.anchor?.resolution;
+  if (res === 'exact') {
+    const loc = v.anchor?.source_location ? ` @ ${v.anchor.source_location}` : '';
+    const anchorBit = `exact → ${v.anchor?.label ?? v.anchor?.nodeId ?? 'node'}${loc}`;
+    if (v.kind && !v.kind.match) {
+      const why =
+        v.kind.inferred === 'unknown'
+          ? `kind unknown (claimed ${v.kind.claimed})`
+          : `kind mismatch: claimed ${v.kind.claimed}, inferred ${v.kind.inferred}`;
+      return {
+        text: [...bits, anchorBit, why].join(' · '),
+        color: '#e5534b',
+      };
+    }
+    if (v.signature && !v.signature.skipped && !v.signature.match) {
+      const cParams = v.signature.claimed.parameterTypes.join(', ') || '∅';
+      const iParams = v.signature.inferred.parameterTypes.join(', ') || '∅';
+      const cRet = v.signature.claimed.returnTypes.join(', ') || '∅';
+      const iRet = v.signature.inferred.returnTypes.join(', ') || '∅';
+      return {
+        text: [
+          ...bits,
+          anchorBit,
+          v.kind?.match ? `kind ${v.kind.inferred}` : undefined,
+          `signature mismatch: params [${cParams}]≠[${iParams}] return [${cRet}]≠[${iRet}]`,
+        ]
+          .filter(Boolean)
+          .join(' · '),
+        color: '#e5534b',
+      };
+    }
+    const kindBit =
+      v.kind?.match ? `kind ${v.kind.inferred}` : undefined;
+    const inlineBit =
+      v.signature?.inlineParameters
+        ? `${v.signature.inlineParameters} inline param${v.signature.inlineParameters === 1 ? '' : 's'} verified`
+        : undefined;
+    if (v.signature?.skipped) {
+      const skipPhrase: Record<string, string> = {
+        no_claimed_types: 'no claimable named types (primitives/inline only)',
+        generic_arg_only:
+          'return only as generic_arg — wrapper types (Promise/Omit/Map/Array) not read as return edges',
+        partially_generic_arg:
+          'claimed types resolve only via generic_arg; rest unresolved',
+        unresolved_claimed_types:
+          'claimed return type has no graphify edge (npm/global/DOM type)',
+      };
+      return {
+        text: [
+          ...bits,
+          anchorBit,
+          ...(kindBit ? [kindBit] : []),
+          ...(inlineBit ? [inlineBit] : []),
+          v.signature.skipCode
+            ? `params/return not fully checked — ${skipPhrase[v.signature.skipCode] ?? v.signature.skipCode}`
+            : 'params/return not checked',
+        ].join(' · '),
+        color: warn,
+      };
+    }
+    const sigBit =
+      v.signature && v.signature.match ? 'params/return ok' : undefined;
+    return {
+      text: [...bits, anchorBit, ...(kindBit ? [kindBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
+      color: ok,
+    };
+  }
+  if (res === 'file-only') {
+    return {
+      text: [...bits, 'file in graph, symbol not uniquely matched'].join(' · '),
+      color: warn,
+    };
+  }
+  if (res === 'ambiguous') {
+    const n = v.anchor?.candidates?.length ?? 0;
+    return {
+      text: [...bits, `ambiguous (${n} candidates)`].join(' · '),
+      color: warn,
+    };
+  }
+  if (res === 'missing') {
+    return {
+      text: [...bits, 'no matching graphify node'].join(' · '),
+      color: '#e5534b',
+    };
+  }
+  return { text: bits.join(' · ') || 'done', color: muted };
 }
 
 /** Declaration panel for the selected component — its definition, code-style. */
-export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _onRelatedSelect, maxWidth }: ComponentDeclarationProps) {
+export function ComponentDeclaration({
+  component,
+  onOpenFile,
+  onRelatedSelect: _onRelatedSelect,
+  maxWidth,
+  onVerify,
+  verification,
+}: ComponentDeclarationProps) {
   const { theme } = useTheme();
   const [fileHovered, setFileHovered] = useState(false);
-  // Header visibility toggles — off by default so the panel opens as pure
-  // code; the repo-row icons bring the path and description back.
   const [showFile, setShowFile] = useState(false);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = KIND_COLOR[component.kind] ?? '#888';
+  const okColor = '#3d9a5f';
+  const warnColor = theme.colors.textSecondary;
 
-  // Token-kind → theme-color map (used by the token iterator below).
   const tokenColor: Record<SubsystemDeclTokenKind, string> = {
     keyword: theme.colors.secondary,
     name: color,
@@ -78,7 +258,7 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     type: theme.colors.accent,
     punctuation: muted,
     string: theme.colors.success,
-    newline: '', // not rendered — drives line breaks
+    newline: '',
   };
 
   const line = (children: ReactNode, key?: string, indent?: boolean | number) => {
@@ -98,9 +278,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
       key,
       indent,
     );
-  // Purpose is the panel's actual prose, not code — body font, readable
-  // size/contrast, capped measure. The `//` metadata lines above it stay
-  // muted mono on purpose.
   const purposeStyle = {
     color: theme.colors.text,
     fontFamily: theme.fonts.body,
@@ -108,17 +285,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     lineHeight: 1.5,
     maxWidth: '52ch',
   } as const;
-  // Trailing relationship comments (`// called by:`, `// constructed by:`,
-  // `// 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.
+
   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
-  // hides itself on load failure (offline / blocked hosts).
   const ghMatch = /^pkg:github\/([^/]+)\/([^/#?]+)/.exec(component.purl ?? '');
-  // Small ghost icon button for the header toggles — accent when its section
-  // is shown, muted when hidden.
   const toggleBtn = (on: boolean, onClick: () => void, title: string, Icon: typeof FileText) => (
     <button
       type="button"
@@ -142,6 +311,44 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
       <Icon size={13} />
     </button>
   );
+  const verifyBusy = verification?.phase === 'checking';
+  const headerActions = (
+    <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 2 }}>
+      {onVerify && (
+        <button
+          type="button"
+          title="Verify against graphify"
+          aria-label="Verify against graphify"
+          disabled={verifyBusy}
+          onClick={(e) => {
+            e.stopPropagation();
+            onVerify(component.id);
+          }}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 4,
+            height: 20,
+            padding: '0 6px',
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 4,
+            background: 'transparent',
+            color: verifyBusy ? muted : theme.colors.textSecondary,
+            cursor: verifyBusy ? 'wait' : 'pointer',
+            fontSize: theme.fontSizes[0],
+            fontFamily: theme.fonts.body,
+            opacity: verifyBusy ? 0.7 : 1,
+          }}
+        >
+          <ShieldCheck size={12} />
+          {verifyBusy ? '…' : 'Verify'}
+        </button>
+      )}
+      {toggleBtn(showFile, () => setShowFile((v) => !v), 'Toggle file path', FileText)}
+      {toggleBtn(showPurpose, () => setShowPurpose((v) => !v), 'Toggle description', AlignLeft)}
+    </span>
+  );
+
   if (ghMatch) {
     const [, ghOwner, ghRepo] = ghMatch;
     lines.push(
@@ -166,17 +373,68 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
           >
             {ghRepo}
           </span>
-          <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 2 }}>
-            {toggleBtn(showFile, () => setShowFile((v) => !v), 'Toggle file path', FileText)}
-            {toggleBtn(showPurpose, () => setShowPurpose((v) => !v), 'Toggle description', AlignLeft)}
-          </span>
+          {headerActions}
         </span>,
         'repo',
       ),
     );
   } else if (component.purl) {
-    lines.push(commentLine(`// ${formatPurl(component.purl)}`, 'purl'));
+    lines.push(
+      line(
+        <span style={{ display: 'flex', alignItems: 'center', gap: 6, width: '100%' }}>
+          <span style={commentStyle}>{`// ${formatPurl(component.purl)}`}</span>
+          {headerActions}
+        </span>,
+        'purl',
+      ),
+    );
+  } else if (onVerify) {
+    lines.push(line(headerActions, 'actions'));
   }
+
+  if (verification && verification.phase !== 'idle') {
+    const summary = verificationSummary(verification, muted, okColor, warnColor);
+    if (summary.text) {
+      lines.push(
+        line(
+          <span
+            style={{
+              color: summary.color,
+              fontFamily: theme.fonts.body,
+              fontSize: theme.fontSizes[0],
+              whiteSpace: 'normal',
+            }}
+          >
+            {summary.text}
+          </span>,
+          'verify-status',
+        ),
+      );
+    }
+    if (
+      verification.anchor?.resolution === 'ambiguous' &&
+      verification.anchor.candidates &&
+      verification.anchor.candidates.length > 0
+    ) {
+      for (const c of verification.anchor.candidates.slice(0, 5)) {
+        lines.push(
+          commentLine(
+            `//   ${c.label}${c.source_file ? ` — ${c.source_file}` : ''}`,
+            `cand-${c.nodeId}`,
+          ),
+        );
+      }
+    }
+    if (verification.signature?.skipped && verification.signature.reason) {
+      lines.push(
+        commentLine(
+          `// why: ${verification.signature.reason}`,
+          'verify-skip-reason',
+        ),
+      );
+    }
+  }
+
   if (showFile && component.file)
     lines.push(
       line(
@@ -185,8 +443,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
             onMouseEnter={() => setFileHovered(true)}
             onMouseLeave={() => setFileHovered(false)}
             style={{
-              // Path as UI text, not a code comment — matches the repo-name
-              // row. Quiet until hover; the underline only appears then.
               color: theme.colors.textSecondary ?? muted,
               fontFamily: theme.fonts.body,
               fontSize: theme.fontSizes[1],
@@ -201,38 +457,33 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
       ),
     );
 
-  // --- Container width measurement --------------------------------------
-  // Approximate character count from the container's clientWidth so Prettier
-  // wraps at the same column the code block will actually use.
   const containerRef = useRef<HTMLDivElement>(null);
   const [printWidth, setPrintWidth] = useState(80);
 
-  const measure = useCallback(() => {
+  useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
-    const ch = el.querySelector('[data-declaration-line]');
-    if (ch) {
-      // Use the width of a single `ch` unit from the monospace container.
-      const charWidth = ch.getBoundingClientRect().width || 8.4;
-      setPrintWidth(Math.max(40, Math.floor(el.clientWidth / charWidth)));
-    } else {
-      // Fallback: assume ~8.4 px per char at 14px monospace.
-      setPrintWidth(Math.max(40, Math.floor(el.clientWidth / 8.4)));
+
+    function measureWidth() {
+      const probe = document.createElement('div');
+      probe.style.cssText =
+        'position:absolute;visibility:hidden;white-space:pre;' +
+        `font-family:${getComputedStyle(el!).fontFamily};` +
+        `font-size:${getComputedStyle(el!).fontSize};` +
+        'line-height:1;width:auto';
+      probe.textContent = 'x';
+      document.body.appendChild(probe);
+      const ch = probe.getBoundingClientRect().width || 8.4;
+      document.body.removeChild(probe);
+      setPrintWidth(Math.max(40, Math.floor(el!.clientWidth / ch)));
     }
-  }, []);
 
-  useEffect(() => {
-    measure();
-    const el = containerRef.current;
-    if (!el) return;
-    const ro = new ResizeObserver(measure);
+    measureWidth();
+    const ro = new ResizeObserver(measureWidth);
     ro.observe(el);
     return () => ro.disconnect();
-  }, [measure]);
+  }, []);
 
-  // --- 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) {
@@ -243,7 +494,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     tokenizeComponent(component, printWidth).then((t) => {
       if (!cancelled) setTokens(t);
     });
-    return () => { cancelled = true; };
+    return () => {
+      cancelled = true;
+    };
   }, [component, printWidth]);
   const declLines: ReactNode[][] = [[]];
   let di = 0;
@@ -262,18 +515,15 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
   for (let li = 0; li < declLines.length; li++) {
     if (declLines[li].length === 0) continue;
     lines.push(
-      <div key={`decl-${li}`} data-declaration-line style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18 }}>
+      <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
-  // explanation underneath. Newlines split into separate prose lines so a
-  // two-thought purpose reads as a short paragraph instead of one blob.
   if (showPurpose && component.purpose) {
     lines.push(line(<div style={{ height: 6 }} />, 'purpose-gap'));
-    component.purpose.split("\n").forEach((purposeLine, i) =>
+    component.purpose.split('\n').forEach((purposeLine, i) =>
       lines.push(
         line(
           <span style={{ ...purposeStyle, display: 'block' }} key={`purpose${i}`}>

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -45,6 +45,7 @@ import { SubsystemComponentNode, SubsystemEdge, SUBSYSTEM_CALLBACKS } from './no
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
+import type { ComponentVerificationState } from './ComponentDeclaration';
 import { FileDrawer } from './FileDrawer';
 import { EdgeLegendModal, MECHANISM_DESCRIPTIONS } from './EdgeLegendModal';
 import { buildRepoGroups, repoAvatarUrl, type RepoGroup } from './paths';
@@ -88,6 +89,10 @@ export interface SubsystemComponentGraphProps {
    * path). The tree is derived from the components' `file` values.
    */
   onFileSelect?: (file: string) => void;
+  /** Verify the selected component against graphify (declaration panel). */
+  onVerifyComponent?: (componentId: string) => void;
+  /** Live verification status for the selected component. */
+  componentVerification?: ComponentVerificationState | null;
 }
 
 const nodeTypes: NodeTypes = {
@@ -117,7 +122,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect }: InnerProps) {
+function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -699,6 +704,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
               component={selected}
               onOpenFile={onTreeSelectFile}
               onRelatedSelect={resolveRelatedComponent}
+              onVerify={onVerifyComponent}
+              verification={componentVerification}
             />
           </div>
         )}

package/src/subsystem/formatDeclaration.ts

@@ -13,13 +13,17 @@ import type { GraphifyComponentDetail } from '../graphify';
 export function generateDeclarationString(component: SubsystemComponent): string {
   const detail = component.detail;
   const kind = detail?.kind ?? component.kind;
-  const name = component.symbol || component.name || 'untitled';
+  const rawName = component.symbol || component.name || 'untitled';
+  // Strip class/object prefix from dotted symbols (e.g. "SessionReader.normalize" → "normalize").
+  const name = rawName.includes('.') ? rawName.split('.').pop()! : rawName;
 
   switch (kind) {
     case 'class':
       return generateClass(name, detail);
     case 'function':
       return generateFunction(name, detail);
+    case 'method':
+      return generateMethod(name, detail);
     case 'type':
       return generateType(name, detail);
     case 'module':
@@ -86,6 +90,14 @@ function generateFunction(name: string, detail?: GraphifyComponentDetail): strin
   return `function ${name}(${params})${ret};`;
 }
 
+function generateMethod(name: string, detail?: GraphifyComponentDetail): string {
+  const m = detail?.kind === 'method' ? detail : undefined;
+  const hostClass = m?.hostClass ?? 'Host';
+  const params = formatParams(m?.parameters ?? []);
+  const ret = m?.returnType ? `: ${m.returnType}` : '';
+  return `class ${hostClass} {\n  ${name}(${params})${ret};\n}`;
+}
+
 function generateType(name: string, detail?: GraphifyComponentDetail): string {
   const tpe = detail?.kind === 'type' ? detail : undefined;
   const props = (tpe?.properties ?? [])

package/src/subsystem/model.ts

@@ -23,6 +23,7 @@ import type { GraphifyComponentDetail } from '../graphify';
 export type SubsystemComponentKind =
   | 'class'
   | 'function'
+  | 'method'
   | 'type'
   | 'module'
   | 'external';
@@ -269,6 +270,7 @@ export function packageColor(name: string): string {
 export const KIND_COLOR: Record<SubsystemComponentKind, string> = {
   class: '#0893d2', // blue
   function: '#6c5ce7', // indigo
+  method: '#d4a03c', // gold
   type: '#e07a5f', // terracotta
   module: '#4ec9b0', // teal
   external: '#b48ead', // purple