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

package/src/graphify/resolve.ts

@@ -0,0 +1,115 @@
+/**
+ * Resolve graphify type-name references to their defining nodes.
+ *
+ * A `references` edge (`parameter_type`, `return_type`, `field`,
+ * `generic_arg`) targets either the type's real definition node or a
+ * *sourceless stub* graphify left behind when the name could not be uniquely
+ * resolved at extraction time (mirrors `_rewire_unique_stub_nodes` there:
+ * ambiguous same-label definitions and never-defined names stay stubs).
+ *
+ * This module applies the same conservative matching from the consumer side so
+ * UI click targets can distinguish "jump to definition" from "N candidates"
+ * from "not in this corpus".
+ */
+
+import type { GraphifyNode } from './types';
+import type { GraphifyReferenceInfo } from './consolidated';
+
+/** Outcome of resolving one type reference. */
+export type GraphifyTypeRefStatus =
+  /** Target node is a real definition — jump to its `source_file`. */
+  | 'resolved'
+  /** Target was a stub and multiple same-label definitions exist. */
+  | 'ambiguous'
+  /** Target was a stub and nothing in the corpus defines the name. */
+  | 'unresolved'
+  /** No nodeId on the ref, or the id is not in the graph. */
+  | 'missing';
+
+export interface GraphifyTypeRefResolution {
+  status: GraphifyTypeRefStatus;
+  /** The definition node when resolved; the stub itself otherwise. */
+  node: GraphifyNode | null;
+  /** Same-label definitions when the target was an unresolved stub. */
+  candidates: GraphifyNode[];
+}
+
+/**
+ * Mirror graphify's `normalise_callable_label`: trim, strip surrounding
+ * parens/leading dots, lowercase. `SessionReader()` and `sessionreader`
+ * collapse to the same key.
+ */
+export function normalizeGraphifyLabel(label: string): string {
+  return label
+    .trim()
+    .replace(/^[()]+|[()]+$/g, '')
+    .replace(/^\.+/, '')
+    .toLowerCase();
+}
+
+const FILE_SUFFIX_RE =
+  /\.(py|js|jsx|ts|tsx|mjs|cjs|java|go|rs|rb|php|cs|cpp|cc|c|h|hpp|pas|pp|dpr|swift|kt|scala|dart|lua|pl|pm|ex|exs|zig|vue|svelte)$/i;
+
+function isDefinition(node: GraphifyNode): boolean {
+  if (node.file_type !== 'code') return false;
+  const file = typeof node.source_file === 'string' ? node.source_file : '';
+  if (!file) return false;
+  const label = typeof node.label === 'string' ? node.label.trim() : '';
+  return !!label && !FILE_SUFFIX_RE.test(label);
+}
+
+/** Prebuilt lookup state — build once per graph, resolve many refs. */
+export interface GraphifyTypeResolver {
+  resolve(nodeId: string | undefined, fallbackLabel?: string): GraphifyTypeRefResolution;
+}
+
+export function createGraphifyTypeResolver(nodes: readonly GraphifyNode[]): GraphifyTypeResolver {
+  const byId = new Map<string, GraphifyNode>();
+  const defsByExactLabel = new Map<string, GraphifyNode[]>();
+  const defsByFoldedLabel = new Map<string, GraphifyNode[]>();
+
+  for (const node of nodes) {
+    byId.set(String(node.id), node);
+    if (!isDefinition(node)) continue;
+    const label = String(node.label).trim();
+    (defsByExactLabel.get(label) ?? defsByExactLabel.set(label, []).get(label)!).push(node);
+    const folded = normalizeGraphifyLabel(label);
+    if (!folded) continue;
+    (defsByFoldedLabel.get(folded) ?? defsByFoldedLabel.set(folded, []).get(folded)!).push(node);
+  }
+
+  function resolve(nodeId: string | undefined, fallbackLabel?: string): GraphifyTypeRefResolution {
+    if (!nodeId) return { status: 'missing', node: null, candidates: [] };
+    const target = byId.get(nodeId);
+    if (!target) return { status: 'missing', node: null, candidates: [] };
+    // Real definition (graphify rewired the reference onto it, or it lived in
+    // the referencing file all along).
+    if (isDefinition(target)) return { status: 'resolved', node: target, candidates: [] };
+
+    // Sourceless stub — try the rewire tiers: exact label, then folded.
+    const label = typeof target.label === 'string' && target.label.trim() ? target.label.trim() : (fallbackLabel ?? '');
+    let candidates = defsByExactLabel.get(label) ?? [];
+    if (candidates.length !== 1) {
+      const folded = normalizeGraphifyLabel(label);
+      candidates = folded ? (defsByFoldedLabel.get(folded) ?? []) : [];
+    }
+    if (candidates.length === 1) {
+      // Unique match — same fold `_rewire_unique_stub_nodes` performs at
+      // extraction time; graphs built before that pass land here instead.
+      return { status: 'resolved', node: candidates[0]!, candidates };
+    }
+    if (candidates.length > 1) return { status: 'ambiguous', node: target, candidates };
+    return { status: 'unresolved', node: target, candidates: [] };
+  }
+
+  return { resolve };
+}
+
+/** One-shot convenience over {@link createGraphifyTypeResolver}. */
+export function resolveGraphifyTypeRef(
+  nodes: readonly GraphifyNode[],
+  ref: Pick<GraphifyReferenceInfo, 'nodeId'> | { nodeId?: string } | undefined,
+  fallbackLabel?: string,
+): GraphifyTypeRefResolution {
+  return createGraphifyTypeResolver(nodes).resolve(ref?.nodeId, fallbackLabel);
+}

package/src/index.ts

@@ -242,10 +242,29 @@ export type {
   GraphifyComponentDetail,
   GraphifyEdgeRef,
 } from './graphify';
+export type {
+  GraphifyTypeRefStatus,
+  GraphifyTypeRefResolution,
+} from './graphify';
+export {
+  normalizeGraphifyLabel,
+  createGraphifyTypeResolver,
+  resolveGraphifyTypeRef,
+} from './graphify';
 
 // Subsystem component graph
 export { SubsystemComponentGraph } from './subsystem/SubsystemComponentGraph';
 export type { SubsystemComponentGraphProps } from './subsystem/SubsystemComponentGraph';
+export { MECHANISM_COLOR, KIND_COLOR, MECHANISM_STYLE } from './subsystem/model';
+export {
+  purlRepoKey,
+  purlOwnerName,
+  buildTreePathMapping,
+} from './subsystem/paths';
+export type {
+  TreeEntry,
+  TreePathMapping,
+} from './subsystem/paths';
 export { SubsystemFileTree } from './subsystem/SubsystemFileTree';
 export type { SubsystemFileTreeProps } from './subsystem/SubsystemFileTree';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';

package/src/stories/SubsystemComponentGraph.stories.tsx

@@ -77,7 +77,6 @@ function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
         showEdgeLabels={showEdgeLabels}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selectedEdge
@@ -162,7 +161,7 @@ const readerDetail: GraphifyComponentDetail = {
   kind: 'class',
   methods: [
     { nodeId: 'm1', name: 'normalize', returnType: 'SessionEvent[]' },
-    { nodeId: 'm2', name: 'readSession', parameters: ['string'], returnType: 'SessionRecord' },
+    { nodeId: 'm2', name: 'readSession', parameters: [{ type: 'string' }], returnType: 'SessionRecord' },
     { nodeId: 'm3', name: 'toUniversalEvents', returnType: 'UniversalEvent[]' },
   ],
   properties: [{ name: 'sessionId', type: 'string' }],
@@ -201,7 +200,6 @@ function V2ReaderDemo() {
         edges={v2ReaderEdges}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selectedEdge
@@ -325,7 +323,6 @@ export const NarrowMaxWidth: Story = {
         components={investigateOnlyComponents}
         edges={investigateOnlyEdges}
         maxNodeWidth={140}
-       
       />
     </div>
   ),
@@ -385,6 +382,8 @@ const namingConventionComponents: SubsystemComponent[] = [
   },
 ];
 
+const namingConventionEdges: SubsystemComponentEdge[] = [];
+
 /** Nodes with compact `maxNodeWidth` so the different conventions visibly wrap
  *  at their word boundaries (camelCase, snake_case, PascalCase, acronyms). */
 export const NamingConventions: Story = {
@@ -392,9 +391,8 @@ export const NamingConventions: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={namingConventionComponents}
-        edges={[]}
+        edges={namingConventionEdges}
         maxNodeWidth={180}
-       
       />
     </div>
   ),
@@ -449,6 +447,75 @@ const detailKindComponents: SubsystemComponent[] = [
       callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
     } satisfies GraphifyComponentDetail,
   },
+  {
+    id: 'detail-fn-rich',
+    name: 'mergeSessions',
+    kind: 'function',
+    file: 'src/session/merge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'multi-param signature — named, positional (graphify captures types only), union types, generic return',
+    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[]>>',
+      callers: [
+        { nodeId: 'c1', name: 'capture-session', source_location: 'L88' },
+        { nodeId: 'c3', name: 'backfill', source_location: 'L210' },
+      ],
+      callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'detail-fn-void',
+    name: 'flush',
+    kind: 'function',
+    file: 'src/event-processing/sink.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'no parameters, no return type — the barest function signature',
+    symbol: 'flush',
+    detail: {
+      kind: 'function',
+      parameters: [],
+      callers: [{ nodeId: 'c4', name: 'EventProcessor.dispose', source_location: 'L142' }],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'detail-class-rich',
+    name: 'EventProcessor',
+    kind: 'class',
+    file: 'src/event-processing/EventProcessor.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'class with fully-typed members — method params + returns, field types, extends + implements',
+    symbol: 'EventProcessor',
+    detail: {
+      kind: 'class',
+      methods: [
+        { nodeId: 'rm1', name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
+        { nodeId: 'rm2', name: 'batch', parameters: [{ type: 'RawEvent[]' }], returnType: 'Promise<ProcessedEvent[]>' },
+        { nodeId: 'rm3', name: 'onError', parameters: [{ type: 'Error' }] },
+        { nodeId: 'rm4', name: 'dispose' },
+      ],
+      properties: [
+        { name: 'queue', type: 'RawEvent[]' },
+        { name: 'options', type: 'Required<ProcessingOptions>' },
+        { name: 'retryLimit', type: 'number' },
+      ],
+      extends: ['BaseProcessor'],
+      implements: ['Disposable', 'EventEmitterLike'],
+      instantiations: [
+        { nodeId: 'x1', name: 'main' },
+        { nodeId: 'x2', name: 'worker-pool' },
+      ],
+      references: [{ nodeId: 'x3', name: 'pipeline', context: 'type' }],
+    } satisfies GraphifyComponentDetail,
+  },
   {
     id: 'detail-type',
     name: 'SessionRecord',
@@ -501,15 +568,16 @@ const detailKindComponents: SubsystemComponent[] = [
   },
 ];
 
+const detailKindEdges: SubsystemComponentEdge[] = [];
+
 function DetailKindsDemo() {
   const [selected, setSelected] = useState<string | null>(null);
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={detailKindComponents}
-        edges={[]}
+        edges={detailKindEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {selected ? `selected: ${selected}` : 'click a component to see its GraphifyComponentDetail'}
@@ -522,6 +590,261 @@ export const DetailKinds: Story = {
   render: () => <DetailKindsDemo />,
 };
 
+// ---------------------------------------------------------------------------
+// Kind variations — one column per kind (class / function / type / module /
+// external), rows going bare → detailed. Click a node to see its declaration
+// panel; type names inside it are clickable when they match another node here.
+// ---------------------------------------------------------------------------
+const variationPurl = 'pkg:github/principal-ai/agent-monitoring';
+
+const kindVariationComponents: SubsystemComponent[] = [
+  // --- class: bare → members only → relationships only
+  {
+    id: 'cls-bare',
+    name: 'SessionStore',
+    kind: 'class',
+    file: 'src/session/SessionStore.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `class SessionStore`',
+    symbol: 'SessionStore',
+    layer: 1,
+  },
+  {
+    id: 'cls-members',
+    name: 'Transcoder',
+    kind: 'class',
+    file: 'src/session/Transcoder.ts',
+    purl: variationPurl,
+    purpose: 'members only — methods with typed params + returns, a typed field',
+    symbol: 'Transcoder',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [
+        { nodeId: 'tm1', name: 'encode', parameters: [{ type: 'RawFrame' }], returnType: 'Uint8Array' },
+        { nodeId: 'tm2', name: 'decode', parameters: [{ type: 'Uint8Array' }], returnType: 'RawFrame' },
+        { nodeId: 'tm3', name: 'reset' },
+      ],
+      properties: [{ name: 'bufferSize', type: 'number' }],
+      extends: [],
+      implements: [],
+      instantiations: [],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'cls-relations',
+    name: 'HttpTransport',
+    kind: 'class',
+    file: 'src/transport/HttpTransport.ts',
+    purl: variationPurl,
+    purpose: 'relationships only — extends + implements, constructed-by comment; empty body elides the braces',
+    symbol: 'HttpTransport',
+    layer: 1,
+    detail: {
+      kind: 'class',
+      methods: [],
+      properties: [],
+      extends: ['BaseTransport'],
+      implements: ['Transport'],
+      instantiations: [{ nodeId: 'x1', name: 'main' }],
+      references: [],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- function: bare → signature only → signature + call relationships
+  {
+    id: 'fn-bare',
+    name: 'bootstrap',
+    kind: 'function',
+    file: 'src/bootstrap.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `function bootstrap()`',
+    symbol: 'bootstrap',
+    layer: 2,
+  },
+  {
+    id: 'fn-signature',
+    name: 'normalizeSession',
+    kind: 'function',
+    file: 'src/event-processing/normalize.ts',
+    purl: variationPurl,
+    purpose: 'signature only — named + positional (type-only) params, array return; no callers/callees comments',
+    symbol: 'normalizeSession',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'session', type: 'SessionRecord' },
+        { type: 'NormalizeOptions' },
+      ],
+      returnType: 'SessionEvent[]',
+      callers: [],
+      callees: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'fn-calls',
+    name: 'mergeSessions',
+    kind: 'function',
+    file: 'src/session/merge.ts',
+    purl: variationPurl,
+    purpose: 'signature + call relationships — union-typed param, generic return, called-by / calls trailing comments',
+    symbol: 'mergeSessions',
+    layer: 2,
+    detail: {
+      kind: 'function',
+      parameters: [
+        { name: 'sessions', type: 'SessionRecord[]' },
+        { name: 'strategy', type: `'append' | 'replace'` },
+      ],
+      returnType: 'Promise<SessionEvent[]>',
+      callers: [{ nodeId: 'c1', name: 'capture-session', source_location: 'L88' }],
+      callees: [{ nodeId: 'c2', name: 'toUniversalEvents', source_location: 'L64' }],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- type: bare → fields only → fields + implementors + used-by
+  {
+    id: 'ty-bare',
+    name: 'RawFrame',
+    kind: 'type',
+    file: 'src/session/RawFrame.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — renders a plain `interface RawFrame`',
+    symbol: 'RawFrame',
+    layer: 3,
+  },
+  {
+    id: 'ty-fields',
+    name: 'SessionRecord',
+    kind: 'type',
+    file: 'src/session/transcript.ts',
+    purl: variationPurl,
+    purpose: 'fields only — typed interface body, nothing else',
+    symbol: 'SessionRecord',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'id', type: 'string' },
+        { name: 'admittedSeq', type: 'number' },
+      ],
+      usedBy: [],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'ty-full',
+    name: 'Transport',
+    kind: 'type',
+    file: 'src/transport/Transport.ts',
+    purl: variationPurl,
+    purpose: 'full — fields + implemented-by (clicks through to HttpTransport) + used-by comments',
+    symbol: 'Transport',
+    layer: 3,
+    detail: {
+      kind: 'type',
+      properties: [{ name: 'name', type: 'string' }],
+      usedBy: [{ nodeId: 'u1', name: 'main', context: 'parameter_type' }],
+      implementors: ['HttpTransport'],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- module: bare → exports only → exports + imports
+  {
+    id: 'mod-bare',
+    name: 'transcript',
+    kind: 'module',
+    file: 'src/session/transcript.ts',
+    purl: variationPurl,
+    purpose: 'no drill-down — symbol-less module named from its file basename',
+    symbol: '',
+    layer: 4,
+  },
+  {
+    id: 'mod-exports',
+    name: 'paths',
+    kind: 'module',
+    file: 'src/session/paths.ts',
+    purl: variationPurl,
+    purpose: 'exports only — export statement + defines comment',
+    symbol: '',
+    layer: 4,
+    detail: {
+      kind: 'module',
+      exports: ['extractToolName', 'extractFilePath'],
+      imports: [],
+      symbols: ['extractToolName', 'extractFilePath'],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'mod-full',
+    name: 'index',
+    kind: 'module',
+    file: 'src/index.ts',
+    purl: variationPurl,
+    purpose: 'full — import statements + re-export statement + defines comment',
+    symbol: '',
+    layer: 4,
+    detail: {
+      kind: 'module',
+      exports: ['SessionReader', 'SessionStore'],
+      imports: [{ nodeId: 'i1', name: 'transcript', relation: 'imports_from' }],
+      symbols: ['SessionReader', 'SessionStore'],
+    } satisfies GraphifyComponentDetail,
+  },
+
+  // --- external: bare → labeled
+  {
+    id: 'ext-bare',
+    name: 'left-pad',
+    kind: 'external',
+    file: '',
+    purl: 'pkg:npm/left-pad',
+    purpose: 'no drill-down — renders a plain `external left-pad`',
+    symbol: '',
+    layer: 5,
+  },
+  {
+    id: 'ext-label',
+    name: 'trail-viewer',
+    kind: 'external',
+    file: '',
+    purl: 'pkg:npm/@principal-ai/trail-viewer',
+    purpose: 'labeled — the full purl as a quoted string literal',
+    symbol: '',
+    layer: 5,
+    detail: {
+      kind: 'external',
+      label: 'pkg:npm/@principal-ai/trail-viewer',
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+const kindVariationEdges: SubsystemComponentEdge[] = [];
+
+function KindVariationsDemo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={kindVariationComponents}
+        edges={kindVariationEdges}
+        onSelect={(id) => setSelected(id)}
+      />
+      <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
+        columns: class · function · type · module · external — each goes bare → detailed
+        {selected ? ` · selected: ${selected}` : ''}
+      </div>
+    </div>
+  );
+}
+
+export const KindVariations: Story = {
+  render: () => <KindVariationsDemo />,
+};
+
 // ---------------------------------------------------------------------------
 // Minimal (pre-graphify) vs Resolved (post-graphify) — the SAME subsystem,
 // showing what the LLM emits (no detail) and what graphify enrichment adds.
@@ -585,7 +908,6 @@ function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
         components={resolved ? resolvedComponents : minimalComponents}
         edges={sharedEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         {resolved
@@ -662,7 +984,6 @@ function InvestigationDemo() {
         components={investigationComponents}
         edges={investigationEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         read-only investigation snapshot (grok 019fd2a9) — components analyzed, not edited
@@ -754,7 +1075,6 @@ function MermaidDemo() {
         components={mermaidComponents}
         edges={mermaidEdges}
         onSelect={(id) => setSelected(id)}
-       
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
         mermaid diagram rendering pipeline — lazy → render → zoom → modal