@principal-ai/subsystems-react 0.33.0 → 0.35.0

package/dist/subsystem/symbolRefs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Referenced symbols inside a component's declaration.
+ *
+ * A declaration mentions other symbols — parameter/return types, property
+ * types, `extends`/`implements`, and related callables (`callers`/`callees`,
+ * `references`/`usedBy`). This module flattens the structured declaration into
+ * a deduped, lookup-friendly list so the panel can offer a graphify inspection
+ * per name, and defines the payload graphify returns for one.
+ *
+ * Slice 1 is display-only: the inspection payload is produced by the host (or,
+ * in stories, by a fixture). Nothing here reads the graph.
+ */
+import type { GraphifyComponentDetail } from '../graphify';
+/** One symbol a declaration references, normalized for lookup. */
+export interface DeclarationSymbolRef {
+    /** Referenced name as written (e.g. `SessionRecord`), no call/`()` decoration. */
+    name: string;
+    /** Graphify node id when the backing reference carried one. */
+    nodeId?: string;
+    /** Reference context (`parameter_type`, `return_type`, `field`, `caller`, …). */
+    context?: string;
+    /** `L<line>` of the reference site, when known. */
+    sourceLocation?: string;
+}
+/**
+ * How a symbol resolved against the cached graphify graph. Name-first, so it
+ * mirrors the type-ref resolver (`graphify/resolve.ts`) rather than component
+ * anchoring — there is no claimed file to fall back to.
+ */
+export type SymbolInspectionResolution = 
+/** Exactly one definition node for the name. */
+'resolved'
+/** Referenced, but no definition in this corpus (external / ambient type). */
+ | 'unresolved'
+/** Multiple same-label definitions. */
+ | 'ambiguous'
+/** The name isn't in the graph at all. */
+ | 'missing';
+export interface SymbolInspectionNode {
+    nodeId: string;
+    label: string;
+    /** Repo-root-relative source path. */
+    sourceFile?: string;
+    /** `L<line>` of the definition. */
+    sourceLocation?: string;
+    fileType?: string;
+    community?: string;
+}
+export interface SymbolInspectionCandidate {
+    nodeId: string;
+    label: string;
+    sourceFile?: string;
+}
+/**
+ * The actual source declaration, read from the checkout at the node's anchor.
+ * Used when graphify resolved a location but couldn't reconstruct the shape.
+ */
+export interface SymbolInspectionSource {
+    file: string;
+    startLine?: number;
+    /** Declaration text as read from source. */
+    text: string;
+}
+/**
+ * What graphify has on one symbol. The useful payload is `declaration` — the
+ * symbol's declaration shape, rebuilt from graph edges — with `source` as the
+ * fallback when graphify knows where the symbol is but not what it is.
+ * `resolution` and `candidates` explain a miss; the rest of the graph's
+ * inference bookkeeping is deliberately not part of this payload.
+ */
+export interface SymbolInspection {
+    symbol: string;
+    purl?: string;
+    resolution: SymbolInspectionResolution;
+    node?: SymbolInspectionNode;
+    /** The symbol's declaration, when graphify could reconstruct it. */
+    declaration?: GraphifyComponentDetail;
+    /** The declaration as read from source, when only the location is known. */
+    source?: SymbolInspectionSource;
+    candidates?: SymbolInspectionCandidate[];
+    /** Human-readable reason when there's neither a declaration nor source. */
+    reason?: string;
+}
+/**
+ * True when there's no declaration to show — either graphify couldn't resolve
+ * the symbol or couldn't reconstruct its shape. The case where offering
+ * "add to model + agent" is worthwhile.
+ */
+export declare function isLimitedInspection(info: SymbolInspection | null | undefined): boolean;
+/**
+ * Flatten a declaration into the set of symbols it references, deduped by name.
+ * Entries backed by a `nodeId` win over bare-name entries.
+ */
+export declare function extractDeclarationSymbolRefs(declaration: GraphifyComponentDetail | undefined): DeclarationSymbolRef[];
+//# sourceMappingURL=symbolRefs.d.ts.map

package/dist/subsystem/symbolRefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbolRefs.d.ts","sourceRoot":"","sources":["../../src/subsystem/symbolRefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAyB,MAAM,aAAa,CAAC;AAElF,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD;;;;GAIG;AACH,MAAM,MAAM,0BAA0B;AACpC,gDAAgD;AAC9C,UAAU;AACZ,8EAA8E;GAC5E,YAAY;AACd,uCAAuC;GACrC,WAAW;AACb,0CAA0C;GACxC,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,0BAA0B,CAAC;IACvC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,oEAAoE;IACpE,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,UAAU,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACzC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACxC,OAAO,CAET;AAwDD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,uBAAuB,GAAG,SAAS,GAC/C,oBAAoB,EAAE,CAyFxB"}

package/dist/subsystem/symbolRefs.js

@@ -0,0 +1,167 @@
+/**
+ * Referenced symbols inside a component's declaration.
+ *
+ * A declaration mentions other symbols — parameter/return types, property
+ * types, `extends`/`implements`, and related callables (`callers`/`callees`,
+ * `references`/`usedBy`). This module flattens the structured declaration into
+ * a deduped, lookup-friendly list so the panel can offer a graphify inspection
+ * per name, and defines the payload graphify returns for one.
+ *
+ * Slice 1 is display-only: the inspection payload is produced by the host (or,
+ * in stories, by a fixture). Nothing here reads the graph.
+ */
+/**
+ * True when there's no declaration to show — either graphify couldn't resolve
+ * the symbol or couldn't reconstruct its shape. The case where offering
+ * "add to model + agent" is worthwhile.
+ */
+export function isLimitedInspection(info) {
+    return !info?.declaration;
+}
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+/** Names that carry no lookup value — primitives and non-identifiers. */
+const PRIMITIVES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'bigint',
+    'symbol',
+    'void',
+    'null',
+    'undefined',
+    'never',
+    'any',
+    'unknown',
+    'object',
+    'true',
+    'false',
+    'self',
+    'None',
+    'True',
+    'False',
+    'bool',
+    'int',
+    'float',
+    'str',
+    'bytes',
+    'list',
+    'dict',
+    'tuple',
+    'set',
+]);
+/** A bare (optionally dotted) identifier we can look up by name. */
+function isSimpleSymbolName(type) {
+    if (!type)
+        return false;
+    const t = type.trim();
+    if (!/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(t))
+        return false;
+    return !PRIMITIVES.has(t);
+}
+/**
+ * Normalize a callable/related label (`normalize()`, `.get`, `capture-session`)
+ * to a name. Labels are freer than type expressions — kebab-case is common.
+ */
+function normalizeRelatedName(raw) {
+    if (!raw)
+        return null;
+    const t = raw.trim().replace(/^\./, '').replace(/\(\)$/, '');
+    if (!/^[A-Za-z_$][\w$.-]*$/.test(t))
+        return null;
+    return PRIMITIVES.has(t) ? null : t;
+}
+/**
+ * Flatten a declaration into the set of symbols it references, deduped by name.
+ * Entries backed by a `nodeId` win over bare-name entries.
+ */
+export function extractDeclarationSymbolRefs(declaration) {
+    if (!declaration)
+        return [];
+    const byName = new Map();
+    const add = (name, opts = {}) => {
+        if (!name)
+            return;
+        const existing = byName.get(name);
+        const nodeId = opts.ref?.nodeId;
+        const next = {
+            name,
+            nodeId: nodeId ?? existing?.nodeId,
+            context: opts.ref?.context ?? opts.context ?? existing?.context,
+            sourceLocation: opts.ref?.source_location ?? opts.sourceLocation ?? existing?.sourceLocation,
+        };
+        // Prefer the richer entry when we already have one with a nodeId.
+        if (existing?.nodeId && !nodeId)
+            return;
+        byName.set(name, next);
+    };
+    const addType = (type, ref, context) => {
+        if (!isSimpleSymbolName(type))
+            return;
+        add(type.trim(), { ref, context });
+    };
+    const addCall = (call, context) => {
+        if (!call)
+            return;
+        add(normalizeRelatedName(call.name), {
+            context,
+            sourceLocation: call.source_location,
+        });
+    };
+    switch (declaration.kind) {
+        case 'function':
+            for (const p of declaration.parameters ?? [])
+                addType(p.type, p.ref, 'parameter_type');
+            addType(declaration.returnType, declaration.returnTypeRef, 'return_type');
+            for (const c of declaration.callers ?? [])
+                addCall(c, 'caller');
+            for (const c of declaration.callees ?? [])
+                addCall(c, 'callee');
+            break;
+        case 'method':
+            for (const p of declaration.parameters ?? [])
+                addType(p.type, p.ref, 'parameter_type');
+            addType(declaration.returnType, undefined, 'return_type');
+            break;
+        case 'class':
+            for (const m of declaration.methods ?? []) {
+                for (const p of m.parameters ?? [])
+                    addType(p.type, p.ref, 'parameter_type');
+                addType(m.returnType, m.returnTypeRef, 'return_type');
+            }
+            for (const p of declaration.properties ?? []) {
+                addType(p.type, p.typeRef, 'field');
+            }
+            for (const name of declaration.extends ?? [])
+                addType(name, undefined, 'extends');
+            for (const name of declaration.implements ?? [])
+                addType(name, undefined, 'implements');
+            for (const r of declaration.references ?? []) {
+                add(normalizeRelatedName(r.name), { ref: r, context: r.context ?? 'references' });
+            }
+            break;
+        case 'type':
+            for (const p of declaration.properties ?? []) {
+                addType(p.type, p.typeRef, 'field');
+            }
+            for (const r of declaration.usedBy ?? []) {
+                add(normalizeRelatedName(r.name), { ref: r, context: r.context ?? 'usedBy' });
+            }
+            for (const name of declaration.implementors ?? [])
+                addType(name, undefined, 'implementor');
+            addType(declaration.aliasOf, undefined, 'alias');
+            for (const alt of declaration.unionOf ?? [])
+                addType(alt, undefined, 'union');
+            break;
+        case 'store':
+            for (const p of declaration.properties ?? []) {
+                addType(p.type, p.typeRef, 'field');
+            }
+            break;
+        default:
+            break;
+    }
+    return [...byName.values()];
+}
+//# sourceMappingURL=symbolRefs.js.map

package/dist/subsystem/symbolRefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbolRefs.js","sourceRoot":"","sources":["../../src/subsystem/symbolRefs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -101,6 +101,20 @@ export type {
   ComponentDeclarationProps,
 } from './subsystem/ComponentDeclaration';
 export { ComponentDeclaration } from './subsystem/ComponentDeclaration';
+export { SymbolInspectionCard } from './subsystem/SymbolInspectionCard';
+export type { SymbolInspectionCardProps } from './subsystem/SymbolInspectionCard';
+export {
+  extractDeclarationSymbolRefs,
+  isLimitedInspection,
+} from './subsystem/symbolRefs';
+export type {
+  DeclarationSymbolRef,
+  SymbolInspection,
+  SymbolInspectionResolution,
+  SymbolInspectionNode,
+  SymbolInspectionSource,
+  SymbolInspectionCandidate,
+} from './subsystem/symbolRefs';
 export {
   SubsystemDiagnosticToggle,
   diagnosticStatusColor,

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} />,
+};