@principal-ai/principal-view-react 0.16.35 → 0.16.37

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -12,7 +12,7 @@
  * injection, onNodeClick) adapted to the subsystem model — read-only.
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
 import {
   ReactFlow,
@@ -47,6 +47,7 @@ import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDetail } from './ComponentDetail';
 import { FileDrawer } from './FileDrawer';
 import { EdgeLegendModal, MECHANISM_DESCRIPTIONS } from './EdgeLegendModal';
+import { buildTreePathMapping } from './paths';
 
 export interface SubsystemComponentGraphProps {
   components: SubsystemComponent[];
@@ -97,6 +98,21 @@ const edgeTypes: EdgeTypes = {
   'subsystem-edge': SubsystemEdge,
 };
 
+// Memoized drawer body: only rebuilds children when the open file changes.
+// Inner re-renders on every viewport pan/zoom and hover; recreating host
+// elements then would churn their readFile closures and flash the file
+// viewer's loading state on each render.
+const DrawerContent = memo(function DrawerContent({
+  render,
+  file,
+}: {
+  render: (file: string) => ReactNode;
+  file: string | null;
+}) {
+  if (!file) return null;
+  return <>{render(file)}</>;
+});
+
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
@@ -347,9 +363,13 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
   }, []);
 
   // Sidebar file-tree click → toggle in the bottom drawer (+ host hook only
-  // when opening, so hosts don't see close events).
+  // when opening, so hosts don't see close events). The tree shows
+  // repo-prefixed display paths on multi-repo graphs; map back to the
+  // component's own `file` before touching drawer/host state.
+  const treeMapping = useMemo(() => buildTreePathMapping(components), [components]);
   const onTreeSelectFile = useCallback(
-    (file: string) => {
+    (displayPath: string) => {
+      const file = treeMapping.toFile.get(displayPath) ?? displayPath;
       if (openFileRef.current === file) {
         setOpenFile(null);
         return;
@@ -357,7 +377,27 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
       setOpenFile(file);
       onFileSelect?.(file);
     },
-    [onFileSelect],
+    [treeMapping, onFileSelect],
+  );
+
+  // Detail-panel links: related-name clicks select the matching component —
+  // resolved by id, name, or symbol (call labels may carry a trailing `()`).
+  const resolveRelatedComponent = useCallback(
+    (ref: string) => {
+      const clean = ref.replace(/\(\)$/, '');
+      const comp = components.find(
+        (c) =>
+          c.id === clean ||
+          c.name === clean ||
+          c.symbol === clean ||
+          c.symbol?.replace(/\(\)$/, '') === clean,
+      );
+      if (!comp || comp.id === selectedRef.current?.id) return;
+      setSelected(comp);
+      setSelectedEdgeId(null);
+      onSelect?.(comp.id);
+    },
+    [components, onSelect],
   );
 
   // Edge label data for the overlay (rendered OUTSIDE ReactFlow so the pane
@@ -380,10 +420,11 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     return new Set(edgeLabels.map((l) => l.mechanism));
   }, [edgeLabels]);
 
-  // Unique source files across components → sidebar file tree.
-  const files = useMemo(
-    () => Array.from(new Set(components.map((c) => c.file).filter(Boolean))).sort(),
-    [components],
+  // Unique source files across components → sidebar file tree. Multi-repo
+  // graphs render `<owner>/<name>/…` display paths, grouped by repo.
+  const treeFilePaths = useMemo(
+    () => treeMapping.entries.map((e) => e.displayPath).sort(),
+    [treeMapping],
   );
 
   // The hovered node's file (null when not hovering / file-less component).
@@ -408,10 +449,19 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     return undefined;
   }, [renderFileViewer, renderFileView, components]);
 
+  // Latest-viewer ref + stable callback so DrawerContent's memo holds across
+  // unrelated Inner renders (see comment there).
+  const fileViewerRef = useRef(fileViewer);
+  fileViewerRef.current = fileViewer;
+  const renderDrawerContent = useCallback(
+    (file: string) => fileViewerRef.current?.(file) ?? null,
+    [],
+  );
+
   return (
     <div style={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }}>
       {/* Sidebar: scrollable title/description on top, file tree pinned to the bottom half */}
-      {(title || description || sidebarExtra || sidebarAfterDescription || files.length > 0) && (
+      {(title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0) && (
         <div
           style={{
             width: 340,
@@ -465,11 +515,16 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
           )}
           {sidebarAfterDescription}
           </div>
-          {files.length > 0 && (
+          {treeFilePaths.length > 0 && (
             <SubsystemFileTree
-              files={files}
-              selectedFile={selected?.file ?? openFile}
-              hoveredFile={hoveredFile}
+              files={treeFilePaths}
+              selectedFile={
+                treeMapping.toDisplay.get(selected?.file ?? openFile ?? '') ??
+                selected?.file ??
+                openFile ??
+                null
+              }
+              hoveredFile={hoveredFile ? (treeMapping.toDisplay.get(hoveredFile) ?? hoveredFile) : null}
               onSelectFile={onTreeSelectFile}
             />
           )}
@@ -596,9 +651,15 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
         mechanisms={usedMechanisms}
         onClose={() => setLegendOpen(false)}
       />
-      {selected && <ComponentDetail component={selected} />}
+      {selected && (
+        <ComponentDetail
+          component={selected}
+          onOpenFile={onTreeSelectFile}
+          onRelatedSelect={resolveRelatedComponent}
+        />
+      )}
       <FileDrawer file={openFile} onClose={() => setOpenFile(null)}>
-        {fileViewer && openFile ? fileViewer(openFile) : null}
+        <DrawerContent render={renderDrawerContent} file={openFile} />
       </FileDrawer>
       {/* Startup cover — hides measurement, layout swap, and camera settle. */}
       <GraphLayoutCover revealed={layoutReady} />

package/src/subsystem/model.test.ts

@@ -4,6 +4,7 @@ import {
   convertSubsystemToEdges,
   buildSubsystemGraph,
   deriveNameFromSymbol,
+  formatPurl,
   packageColor,
 } from './model';
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
@@ -76,4 +77,14 @@ describe('subsystem graph model', () => {
     // File basename wins over a supplied name for modules (derivation precedence).
     expect(deriveNameFromSymbol(undefined, 'module', 'MyModule', 'x.ts')).toBe('x');
   });
+
+  test('formatPurl renders the human identity', () => {
+    expect(formatPurl('pkg:npm/@principal-ai/core')).toBe('@principal-ai/core');
+    expect(formatPurl('pkg:github/principal-ai/agent-monitoring')).toBe('principal-ai/agent-monitoring');
+    expect(formatPurl('pkg:npm/left-pad@1.3.0')).toBe('left-pad');
+    expect(formatPurl('pkg:gitlab/group/proj?arch=amd64')).toBe('group/proj');
+    expect(formatPurl('pkg:generic/local--Users-me-my-app')).toBe('Users-me-my-app (local)');
+    // Malformed purls pass through untouched.
+    expect(formatPurl('not-a-purl')).toBe('not-a-purl');
+  });
 });

package/src/subsystem/model.ts

@@ -119,6 +119,30 @@ export function deriveNameFromSymbol(
   return existingName ?? 'untitled';
 }
 
+/**
+ * Human-readable purl identity — drops the `pkg:<type>/` scheme wrapper and
+ * trailing version, keeping the package / owner-repo identity:
+ *
+ *   pkg:npm/@principal-ai/core         → `@principal-ai/core`
+ *   pkg:github/principal-ai/my-repo    → `principal-ai/my-repo`
+ *   pkg:npm/left-pad@1.3.0             → `left-pad`
+ *   pkg:generic/local--Users-me-my-app → `Users-me-my-app (local)`
+ *
+ * Local purls encode the absolute path with dashes for slashes, which is not
+ * losslessly decodable — shown as-is with a `(local)` marker.
+ */
+export function formatPurl(purl: string): string {
+  const match = /^pkg:[^/#?]+\/(.+)$/.exec(purl);
+  if (!match) return purl;
+  let identity = match[1].split(/[?#]/)[0];
+  const at = identity.indexOf('@');
+  if (at > 0) identity = identity.slice(0, at); // trailing @version
+  if (identity.startsWith('local--')) {
+    return `${identity.slice('local--'.length)} (local)`;
+  }
+  return identity;
+}
+
 export interface SubsystemGraphDocument {
   components: SubsystemComponent[];
   edges: SubsystemComponentEdge[];
@@ -174,7 +198,7 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   'registers-into': '#ff6b35', // orange
 };
 
-const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed' | 'dotted'> = {
+export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed' | 'dotted'> = {
   imports: 'solid',
   imports_from: 'solid',
   re_exports: 'solid',

package/src/subsystem/paths.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import { buildTreePathMapping, purlOwnerName, purlRepoKey } from './paths';
+
+describe('purlRepoKey', () => {
+  test('strips fragments and whitespace', () => {
+    expect(purlRepoKey('pkg:github/acme/widget#src/x.ts')).toBe('pkg:github/acme/widget');
+    expect(purlRepoKey('  pkg:github/acme/widget ')).toBe('pkg:github/acme/widget');
+    expect(purlRepoKey(undefined)).toBeUndefined();
+    expect(purlRepoKey('#only-a-fragment')).toBeUndefined();
+  });
+});
+
+describe('purlOwnerName', () => {
+  test('extracts the last two path segments', () => {
+    expect(purlOwnerName('pkg:github/acme/widget#src/x.ts')).toBe('acme/widget');
+    expect(purlOwnerName('pkg:npm/@scope/lib')).toBe('@scope/lib');
+  });
+});
+
+describe('buildTreePathMapping', () => {
+  test('single-repo graphs keep bare file paths', () => {
+    const m = buildTreePathMapping([
+      { file: 'src/a.ts', purl: 'pkg:github/acme/widget' },
+      { file: 'src/b.ts', purl: 'pkg:github/acme/widget' },
+    ]);
+    expect(m.multiRepo).toBe(false);
+    expect(m.entries.map((e) => e.displayPath)).toEqual(['src/a.ts', 'src/b.ts']);
+    expect(m.toFile.get('src/a.ts')).toBe('src/a.ts');
+  });
+
+  test('multi-repo graphs prefix entries with owner/name', () => {
+    const m = buildTreePathMapping([
+      { file: 'graphify/ids.py', purl: 'pkg:github/Graphify-Labs/graphify' },
+      { file: 'packages/react/src/x.ts', purl: 'pkg:github/principal-ai/core-lib#packages/react/src/x.ts' },
+    ]);
+    expect(m.multiRepo).toBe(true);
+    expect(m.toFile.get('Graphify-Labs/graphify/graphify/ids.py')).toBe('graphify/ids.py');
+    expect(m.toDisplay.get('packages/react/src/x.ts')).toBe(
+      'principal-ai/core-lib/packages/react/src/x.ts',
+    );
+  });
+
+  test('same-named files in different repos stay distinct', () => {
+    const m = buildTreePathMapping([
+      { file: 'README.md', purl: 'pkg:github/acme/widget' },
+      { file: 'README.md', purl: 'pkg:github/acme/other' },
+    ]);
+    expect(m.entries).toHaveLength(2);
+  });
+
+  test('components without files are skipped; purl-less components stay unprefixed', () => {
+    const m = buildTreePathMapping([
+      { file: 'a.ts', purl: 'pkg:github/acme/widget' },
+      { file: '', purl: 'pkg:github/acme/widget' },
+      { purl: 'pkg:github/acme/widget' },
+      { file: 'loose.ts' },
+    ]);
+    // Two repos' worth of purls? No — the purl-less one has no repo key.
+    expect(m.multiRepo).toBe(false);
+    expect(m.toFile.get('loose.ts')).toBe('loose.ts');
+  });
+});

package/src/subsystem/paths.ts

@@ -0,0 +1,69 @@
+/**
+ * Multi-repo path handling for subsystem graphs.
+ *
+ * A component's `file` is relative to ITS OWN repo root — the repo identified
+ * by its `purl` (`pkg:github/<owner>/<name>[#<path>]`) — never to the machine.
+ * When a graph spans several repos the sidebar tree needs synthetic
+ * `<owner>/<name>/` prefixes to keep same-named paths apart; hosts resolve
+ * each file against `repoRoots[purlRepo] ?? repoRoot`.
+ */
+
+/** Normalize a purl to its repo key: fragment and surrounding whitespace stripped. */
+export function purlRepoKey(purl: string | undefined): string | undefined {
+  if (!purl) return undefined;
+  const base = purl.split('#')[0]?.trim();
+  return base || undefined;
+}
+
+/** `owner/name` from a purl (`pkg:github/acme/widget#x/y.ts` → `acme/widget`). */
+export function purlOwnerName(purl: string | undefined): string | undefined {
+  const key = purlRepoKey(purl);
+  if (!key) return undefined;
+  // pkg:<type>/<owner>/<name> → take the last two segments.
+  const parts = key.split('/').filter(Boolean);
+  if (parts.length < 2) return undefined;
+  return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`;
+}
+
+export interface TreeEntry {
+  /** Path as shown in the sidebar tree (repo-prefixed when multi-repo). */
+  displayPath: string;
+  /** The component's own file value — what hosts resolve + drawers open. */
+  file: string;
+}
+
+export interface TreePathMapping {
+  entries: TreeEntry[];
+  /** True when components span more than one repo (prefixes are shown). */
+  multiRepo: boolean;
+  /** displayPath → file. */
+  toFile: Map<string, string>;
+  /** file → displayPath (first component wins). */
+  toDisplay: Map<string, string>;
+}
+
+/**
+ * Build the sidebar tree's path set from components. Single-repo graphs (and
+ * purl-less components) keep bare `file` values; mixed-repo graphs prefix each
+ * entry with its purl's `owner/name` so the tree groups by repo.
+ */
+export function buildTreePathMapping(components: ReadonlyArray<{ file?: string; purl?: string }>): TreePathMapping {
+  const withFiles = components.filter((c) => c.file);
+  const repos = new Set(
+    withFiles.map((c) => purlRepoKey(c.purl)).filter((k): k is string => !!k),
+  );
+  const multiRepo = repos.size > 1;
+
+  const entries: TreeEntry[] = [];
+  const toFile = new Map<string, string>();
+  const toDisplay = new Map<string, string>();
+  for (const c of withFiles) {
+    const ownerName = multiRepo ? purlOwnerName(c.purl) : undefined;
+    const displayPath = ownerName ? `${ownerName}/${c.file}` : c.file!;
+    if (toFile.has(displayPath)) continue;
+    entries.push({ displayPath, file: c.file! });
+    toFile.set(displayPath, c.file!);
+    if (!toDisplay.has(c.file!)) toDisplay.set(c.file!, displayPath);
+  }
+  return { entries, multiRepo, toFile, toDisplay };
+}