@principal-ai/subsystems-react 0.17.0

package/src/stories/RealWorld/RealCanvasFiles.stories.tsx

@@ -0,0 +1,336 @@
+import React, { useState, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '@xyflow/react/dist/style.css';
+import { GraphRenderer } from '../../components/GraphRenderer';
+import type { ExtendedCanvas } from '@principal-ai/subsystems-core';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+
+// Import canvas files as URLs
+import scopesCanvasUrl from '../../../../../.principal-views/architecture.scopes.canvas?url';
+import spansCanvasUrl from '../../../../../.principal-views/architecture.spans.canvas?url';
+import resourcesCanvasUrl from '../../../../../.principal-views/resources.canvas?url';
+import matchingLogicCanvasUrl from '../../../../../.principal-views/matching-logic-current-state.canvas?url';
+import validationCanvasUrl from '../../../../../.principal-views/validation/validation.otel.canvas?url';
+
+// Helper to load canvas from URL
+async function loadCanvas(url: string): Promise<ExtendedCanvas> {
+  const response = await fetch(url);
+  return await response.json();
+}
+
+// Wrapper component that loads canvas data
+function CanvasLoader({ url, children }: { url: string; children: (canvas: ExtendedCanvas) => React.ReactNode }) {
+  const [canvas, setCanvas] = useState<ExtendedCanvas | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadCanvas(url)
+      .then(setCanvas)
+      .catch((err) => setError(err.message));
+  }, [url]);
+
+  if (error) {
+    return <div style={{ padding: 20, color: 'red' }}>Error loading canvas: {error}</div>;
+  }
+
+  if (!canvas) {
+    return <div style={{ padding: 20 }}>Loading canvas...</div>;
+  }
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      {children(canvas)}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'RealWorld/RealCanvasFiles',
+  component: GraphRenderer,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ width: '100vw', height: '100vh' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof GraphRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================================================
+// Architecture Canvas Files
+// ============================================================================
+
+/**
+ * Scopes Canvas - Documents instrumentation scopes
+ *
+ * File: .principal-views/architecture.scopes.canvas
+ * Type: otel-scope nodes
+ * Purpose: Shows OpenTelemetry instrumentation scopes (getTracer calls)
+ */
+export const ScopesCanvas: Story = {
+  render: () => (
+    <CanvasLoader url={scopesCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the actual **architecture.scopes.canvas** file from the project.
+
+This canvas documents instrumentation scopes using \`otel-scope\` nodes with:
+- Top-level \`type: "otel-scope"\`
+- \`label\` for display name
+- \`otel.scope\` for the scope identifier
+- Circular node shape
+
+**Use this to:**
+- Preview how scope architecture canvases render
+- Verify visual changes to scope nodes
+- Test new features on real project files
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Spans Canvas - Defines span naming conventions
+ *
+ * File: .principal-views/architecture.spans.canvas
+ * Type: otel-span-convention nodes
+ * Purpose: Documents span patterns and valid parent-child relationships
+ */
+export const SpansCanvas: Story = {
+  render: () => (
+    <CanvasLoader url={spansCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the actual **architecture.spans.canvas** file from the project.
+
+This canvas defines span naming conventions using \`otel-span-convention\` nodes with:
+- Top-level \`type: "otel-span-convention"\`
+- \`label\` for display name
+- \`otel.spanPattern\` for matching pattern
+- \`otel.spanKind\` for span kind
+- Hexagon shape
+
+**Use this to:**
+- Preview how span convention canvases render
+- Verify workflow chips display
+- Test edge relationships between spans
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Resources Canvas - Documents OTEL resources
+ *
+ * File: .principal-views/resources.canvas
+ * Type: Mixed (text nodes and otel-resource nodes)
+ * Purpose: Shows service resources and their instrumentation scopes
+ */
+export const ResourcesCanvas: Story = {
+  render: () => (
+    <CanvasLoader url={resourcesCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the actual **resources.canvas** file from the project.
+
+This canvas documents OTEL resources (service.name) and how they map to instrumentation scopes.
+
+**Use this to:**
+- Preview resource topology visualization
+- Test resource node rendering
+- Verify resource → scope relationships
+        `,
+      },
+    },
+  },
+};
+
+// ============================================================================
+// Workflow/Event Canvas Files
+// ============================================================================
+
+/**
+ * Validation Workflow Canvas - Event-driven workflow
+ *
+ * File: .principal-views/validation/validation.otel.canvas
+ * Type: otel-event nodes
+ * Purpose: Documents validation pipeline events and transitions
+ */
+export const ValidationOtelCanvas: Story = {
+  render: () => (
+    <CanvasLoader url={validationCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the actual **validation.otel.canvas** file from the project.
+
+This canvas shows the validation pipeline workflow using \`otel-event\` nodes with:
+- Top-level \`type: "otel-event"\`
+- \`label\` for display name
+- \`event.name\` for the event identifier
+- \`event.attributes\` for event schema
+- Rectangle/rounded shapes
+
+**Use this to:**
+- Preview workflow event canvases
+- Test event node rendering
+- Verify event schema tooltips
+        `,
+      },
+    },
+  },
+};
+
+// ============================================================================
+// General Canvas Files
+// ============================================================================
+
+/**
+ * Matching Logic Canvas - Planning/documentation canvas
+ *
+ * File: .principal-views/matching-logic-current-state.canvas
+ * Type: Regular canvas (text nodes with pv extensions)
+ * Purpose: Documents implementation status and architecture planning
+ */
+export const MatchingLogicCanvas: Story = {
+  render: () => (
+    <CanvasLoader url={matchingLogicCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the actual **matching-logic-current-state.canvas** file from the project.
+
+This is a regular \`.canvas\` file used for architecture planning and implementation tracking.
+Uses standard JSON Canvas \`text\` nodes with \`pv\` extensions for:
+- Custom node types (\`pv.nodeType\`)
+- Visual styling (\`pv.shape\`, \`pv.fill\`, \`pv.stroke\`)
+- References to code files (\`pv.references\`)
+
+**Use this to:**
+- Preview general-purpose canvas files
+- Test pv extension rendering
+- Verify backward compatibility with old format
+        `,
+      },
+    },
+  },
+};
+
+// ============================================================================
+// Combined View - All Canvas Files Side by Side
+// ============================================================================
+
+/**
+ * All Canvas Files - Side by side comparison
+ */
+export const AllCanvasTypes: Story = {
+  render: () => {
+    const [canvases, setCanvases] = useState<{
+      scopes?: ExtendedCanvas;
+      spans?: ExtendedCanvas;
+      resources?: ExtendedCanvas;
+      validation?: ExtendedCanvas;
+      matching?: ExtendedCanvas;
+    }>({});
+
+    useEffect(() => {
+      Promise.all([
+        loadCanvas(scopesCanvasUrl),
+        loadCanvas(spansCanvasUrl),
+        loadCanvas(resourcesCanvasUrl),
+        loadCanvas(validationCanvasUrl),
+        loadCanvas(matchingLogicCanvasUrl),
+      ]).then(([scopes, spans, resources, validation, matching]) => {
+        setCanvases({ scopes, spans, resources, validation, matching });
+      });
+    }, []);
+
+    if (!canvases.scopes) {
+      return <div style={{ padding: 20 }}>Loading all canvases...</div>;
+    }
+
+    return (
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '20px', padding: '20px' }}>
+        <div>
+          <h3 style={{ marginTop: 0 }}>Scopes Canvas</h3>
+          <div style={{ height: '300px', border: '1px solid #ccc' }}>
+            <GraphRenderer canvas={canvases.scopes} />
+          </div>
+        </div>
+        <div>
+          <h3 style={{ marginTop: 0 }}>Spans Canvas</h3>
+          <div style={{ height: '300px', border: '1px solid #ccc' }}>
+            {canvases.spans && <GraphRenderer canvas={canvases.spans} />}
+          </div>
+        </div>
+        <div>
+          <h3 style={{ marginTop: 0 }}>Resources Canvas</h3>
+          <div style={{ height: '300px', border: '1px solid #ccc' }}>
+            {canvases.resources && <GraphRenderer canvas={canvases.resources} />}
+          </div>
+        </div>
+        <div>
+          <h3 style={{ marginTop: 0 }}>Validation (OTEL Events)</h3>
+          <div style={{ height: '300px', border: '1px solid #ccc' }}>
+            {canvases.validation && <GraphRenderer canvas={canvases.validation} />}
+          </div>
+        </div>
+        <div style={{ gridColumn: '1 / -1' }}>
+          <h3 style={{ marginTop: 0 }}>Matching Logic (Regular Canvas)</h3>
+          <div style={{ height: '400px', border: '1px solid #ccc' }}>
+            {canvases.matching && <GraphRenderer canvas={canvases.matching} />}
+          </div>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Shows all canvas file types rendered side by side for comparison.
+
+This view helps:
+- Compare visual styling across different canvas types
+- Test layout consistency
+- Verify theme application
+- Spot visual regressions quickly
+        `,
+      },
+    },
+  },
+};

package/src/stories/Subsystem/ComponentDeclarationAudit.stories.tsx

@@ -0,0 +1,321 @@
+import React 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';
+
+const meta = {
+  title: 'Subsystem/ComponentDeclarationAudit',
+  component: ComponentDeclaration,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  argTypes: {
+    constrained: { control: 'boolean', description: 'Toggle 80ch max-width wrapping' },
+  },
+  args: {
+    constrained: true,
+  },
+  decorators: [
+    (Story, ctx) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ maxWidth: ctx.args.constrained ? '80ch' : 'none', margin: '0 auto' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof ComponentDeclaration>;
+export default meta;
+
+// ---------------------------------------------------------------------------
+// All cases — one SubsystemComponent per shape, rendered stacked
+// ---------------------------------------------------------------------------
+
+const cases: { label: string; component: SubsystemComponent }[] = [
+  {
+    label: 'function — no params',
+    component: {
+      id: 'fn-void',
+      name: 'flush',
+      construct: 'function',
+      file: 'src/event-processing/sink.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'flush',
+      detail: {
+        kind: 'function',
+        parameters: [],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — single param',
+    component: {
+      id: 'fn-one',
+      name: 'normalize',
+      construct: 'function',
+      file: 'src/session/SessionReader.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'SessionReader.normalize',
+      detail: {
+        kind: 'function',
+        parameters: [{ name: 'session', type: 'SessionRecord' }],
+        returnType: 'SessionEvent[]',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — two params',
+    component: {
+      id: 'fn-two',
+      name: 'normalizeSession',
+      construct: 'function',
+      file: 'src/event-processing/normalize.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'normalizeSession',
+      detail: {
+        kind: 'function',
+        parameters: [
+          { name: 'session', type: 'SessionRecord' },
+          { name: 'limit', type: 'number' },
+        ],
+        returnType: 'SessionEvent[]',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — rich params (positional, union, callback, generic return)',
+    component: {
+      id: 'fn-rich',
+      name: 'mergeSessions',
+      construct: 'function',
+      file: 'src/session/merge.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      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[]>>',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — no body',
+    component: {
+      id: 'class-empty',
+      name: 'EmptyClass',
+      construct: 'class',
+      file: 'src/empty.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'EmptyClass',
+      detail: {
+        kind: 'class',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — properties only',
+    component: {
+      id: 'class-props',
+      name: 'Config',
+      construct: 'class',
+      file: 'src/config.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'Config',
+      detail: {
+        kind: 'class',
+        properties: [
+          { name: 'host', type: 'string' },
+          { name: 'port', type: 'number' },
+          { name: 'tls', type: 'boolean' },
+        ],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'class — methods + properties + extends + implements',
+    component: {
+      id: 'class-rich',
+      name: 'EventProcessor',
+      construct: 'class',
+      file: 'src/event-processing/EventProcessor.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'EventProcessor',
+      detail: {
+        kind: 'class',
+        methods: [
+          { name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
+          { name: 'batch', parameters: [{ type: 'RawEvent[]' }], returnType: 'Promise<ProcessedEvent[]>' },
+          { name: 'onError', parameters: [{ type: 'Error' }] },
+          { name: 'dispose' },
+        ],
+        properties: [
+          { name: 'queue', type: 'RawEvent[]' },
+          { name: 'options', type: 'Required<ProcessingOptions>' },
+          { name: 'retryLimit', type: 'number' },
+        ],
+        extends: ['BaseProcessor'],
+        implements: ['Disposable', 'EventEmitterLike'],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'type — properties',
+    component: {
+      id: 'type-props',
+      name: 'SessionRecord',
+      construct: 'interface',
+      file: 'src/session/transcript.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'SessionRecord',
+      detail: {
+        kind: 'type',
+        properties: [
+          { name: 'id', type: 'string' },
+          { name: 'admittedSeq', type: 'number' },
+        ],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'type — no properties',
+    component: {
+      id: 'type-empty',
+      name: 'BrandedId',
+      construct: 'interface',
+      file: 'src/types.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'BrandedId',
+      detail: {
+        kind: 'type',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'module — imports + exports',
+    component: {
+      id: 'mod-full',
+      name: 'index',
+      construct: 'module',
+      file: 'src/index.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'index',
+      detail: {
+        kind: 'module',
+        imports: [
+          { name: './session/SessionReader' },
+          { name: './event-processing/EventProcessor' },
+        ],
+        exports: ['SessionReader', 'EventProcessor'],
+        symbols: ['SessionReader', 'EventProcessor', 'normalizeSession'],
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'module — no detail (fallback)',
+    component: {
+      id: 'mod-plain',
+      name: 'utils',
+      construct: 'module',
+      file: 'src/utils.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'utils',
+    },
+  },
+  {
+    label: 'external',
+    component: {
+      id: 'ext',
+      name: 'principal-studio',
+      construct: 'external',
+      file: '',
+      purl: 'pkg:npm/@principal-ai/subsystems-studio',
+      symbol: '',
+      detail: {
+        kind: 'external',
+        label: 'pkg:npm/@principal-ai/subsystems-studio',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'function — no symbol (uses name fallback)',
+    component: {
+      id: 'fn-no-symbol',
+      name: 'anonymousHelper',
+      construct: 'function',
+      file: 'src/helpers.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      detail: {
+        kind: 'function',
+        parameters: [{ name: 'input', type: 'string' }],
+        returnType: 'void',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'method — standalone from class',
+    component: {
+      id: 'method-normalize',
+      name: 'normalize',
+      construct: 'method',
+      file: 'src/session/SessionReader.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'SessionReader.normalize',
+      detail: {
+        kind: 'method',
+        hostClass: 'SessionReader',
+        parameters: [{ name: 'session', type: 'SessionRecord' }],
+        returnType: 'SessionEvent[]',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+  {
+    label: 'method — no params',
+    component: {
+      id: 'method-dispose',
+      name: 'dispose',
+      construct: 'method',
+      file: 'src/event-processing/EventProcessor.ts',
+      purl: 'pkg:github/principal-ai/agent-monitoring',
+      symbol: 'EventProcessor.dispose',
+      detail: {
+        kind: 'method',
+        hostClass: 'EventProcessor',
+      } satisfies GraphifyComponentDetail,
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Story — all cases stacked
+// ---------------------------------------------------------------------------
+
+export const AllCases: StoryObj<{ constrained: boolean }> = {
+  render: ({ constrained }) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      {cases.map((c) => (
+        <div key={c.label}>
+          <div
+            style={{
+              fontFamily: 'monospace',
+              fontSize: 11,
+              color: '#888',
+              marginBottom: 4,
+              textTransform: 'uppercase',
+              letterSpacing: '0.05em',
+            }}
+          >
+            {c.label}
+          </div>
+          <ComponentDeclaration component={c.component} maxWidth={constrained ? '80ch' : undefined} />
+        </div>
+      ))}
+    </div>
+  ),
+};