@principal-ai/subsystems-core 0.29.0

package/src/discovery/types.ts

@@ -0,0 +1,453 @@
+/**
+ * Type definitions for canvas and execution file discovery
+ */
+
+import type { ExtendedCanvas } from '../types/canvas';
+import type { ExecutionData } from '../execution/ExecutionValidator';
+import type { WorkflowTemplate } from '../workflow/types';
+
+/**
+ * Canvas file type discriminator
+ * - 'otel': OpenTelemetry canvas (.otel.canvas) for workflow/tracing visualization
+ * - 'scopes': Scopes canvas (.scopes.canvas) for documenting instrumentation scopes
+ * - 'resources': Resources canvas (.resources.canvas) for documenting OTel resources
+ * - 'spans': Spans canvas (.spans.canvas) for documenting span conventions
+ * - 'events': Events canvas (.events.canvas) for documenting event namespaces and adjacency
+ * - 'regular': Regular canvas (.canvas) for documentation/architecture diagrams
+ *
+ * Note: Dashboards (.dashboard.json) are NOT canvases - they live in .principal-views/dashboards/
+ * and are discovered separately as DiscoveredDashboard.
+ */
+export type CanvasType = 'otel' | 'scopes' | 'resources' | 'spans' | 'events' | 'regular';
+
+/**
+ * Test trace file type discriminator based on extension
+ * Only .otel.json files are supported
+ */
+export type TestTraceType = 'otel';
+
+/**
+ * Discovered canvas file with package metadata
+ */
+export interface DiscoveredCanvas {
+  /** Unique ID with package prefix (e.g., "core/my-flow" or "my-flow") */
+  id: string;
+  /** Display name (Title Case from basename) */
+  name: string;
+  /** Full relative path from repo root */
+  path: string;
+  /** Canvas basename (without .canvas/.otel.canvas extension) */
+  basename: string;
+  /** Canvas type */
+  type: CanvasType;
+  /** Package name if in a package (e.g., "core" from packages/subsystems-core) */
+  packageName?: string;
+  /** Package path if in a package (e.g., "packages/subsystems-core") */
+  packagePath?: string;
+  /** Whether this is from repo root vs package */
+  scope: 'root' | 'package';
+  /**
+   * Associated markdown documentation file path (relative to repo root)
+   * Only populated for otel.canvas files when canvas content is loaded
+   */
+  markdownPath?: string;
+}
+
+/**
+ * Discovered test trace file with package metadata
+ */
+export interface DiscoveredTestTrace {
+  /** Unique ID with package prefix (e.g., "core/api-tests" or "api-tests") */
+  id: string;
+  /** Display name (Title Case from basename) */
+  name: string;
+  /** Full relative path from repo root */
+  path: string;
+  /** Test trace basename (without .otel.json extension) */
+  basename: string;
+  /** Test trace file type */
+  type: TestTraceType;
+  /** Canvas basename this test trace is linked to */
+  canvasBasename: string;
+  /** Package name if in a package */
+  packageName?: string;
+  /** Package path if in a package */
+  packagePath?: string;
+  /** Whether this is from repo root vs package */
+  scope: 'root' | 'package';
+}
+
+/**
+ * Discovered dashboard file in .principal-views/dashboards/
+ */
+export interface DiscoveredDashboard {
+  /** Unique ID with package prefix (e.g., "core/auth-health" or "auth-health") */
+  id: string;
+  /** Display name (Title Case from basename) */
+  name: string;
+  /** Full relative path from repo root */
+  path: string;
+  /** Dashboard basename (without .dashboard.json extension) */
+  basename: string;
+  /** Package name if in a package */
+  packageName?: string;
+  /** Package path if in a package */
+  packagePath?: string;
+  /** Whether this is from repo root vs package */
+  scope: 'root' | 'package';
+}
+
+/**
+ * Discovered dashboard with parsed content
+ */
+export interface DiscoveredDashboardWithContent extends DiscoveredDashboard {
+  /** Parsed dashboard content (only when includeContent: true) */
+  content: import('../types/dashboard').DashboardDefinition;
+}
+
+/**
+ * A span convention (surface) referenced by a workflow
+ */
+export interface ReferencedSpan {
+  /** The span pattern (e.g., "canvas.load", "multi-canvas-panel.render") */
+  pattern: string;
+  /** Display label from the spans.canvas node, if found */
+  label?: string;
+  /** Instrumentation scope from the spans.canvas node otel.scope, if found */
+  scope?: string;
+}
+
+/**
+ * Discovered workflow file within a storyboard
+ */
+export interface DiscoveredWorkflow {
+  /** Workflow basename ID (e.g., "checkout" for checkout.workflow.json) */
+  id: string;
+  /** Display name (Title Case from basename) */
+  name: string;
+  /** Full relative path from repo root to workflow.json file */
+  path: string;
+  /** Workflow basename (without .workflow.json extension) */
+  basename: string;
+  /** Parent storyboard ID this workflow belongs to */
+  storyboardId: string;
+  /** Package name if in a package */
+  packageName?: string;
+  /** Package path if in a package */
+  packagePath?: string;
+  /** Whether this is from repo root vs package */
+  scope: 'root' | 'package';
+  /** Associated test trace files for this workflow */
+  testTraces: DiscoveredTestTrace[];
+  /**
+   * All span conventions (surfaces) referenced by this workflow.
+   * Includes rootSpan and any explicit span fields in event templates.
+   * Only populated when includeContent: true during discovery.
+   */
+  referencedSpans?: ReferencedSpan[];
+
+  /**
+   * The instrumentation scope this workflow belongs to.
+   * Derived from the rootSpan's scope in spans.canvas.
+   * Only populated when includeContent: true during discovery.
+   */
+  instrumentationScope?: string;
+
+  /**
+   * Display label for the workflow's instrumentation scope.
+   * Resolved from scopes.canvas using the scope name.
+   * Only populated when includeContent: true during discovery.
+   */
+  instrumentationScopeLabel?: string;
+}
+
+/**
+ * Discovered storyboard folder containing canvas, workflows, and executions
+ */
+export interface DiscoveredStoryboard {
+  /** Unique ID with package prefix (e.g., "core/checkout-flow" or "checkout-flow") */
+  id: string;
+  /** Display name (Title Case from basename) */
+  name: string;
+  /** Full relative path from repo root to storyboard folder */
+  path: string;
+  /** Storyboard basename (folder name) */
+  basename: string;
+  /** The main canvas file for this storyboard */
+  canvas: DiscoveredCanvas;
+  /** Workflows within this storyboard */
+  workflows: DiscoveredWorkflow[];
+  /** Package name if in a package */
+  packageName?: string;
+  /** Package path if in a package */
+  packagePath?: string;
+  /** Whether this is from repo root vs package */
+  scope: 'root' | 'package';
+}
+
+/**
+ * Result of canvas discovery operation
+ */
+export interface CanvasDiscoveryResult {
+  /** All discovered canvas files, sorted by package then name */
+  canvases: DiscoveredCanvas[];
+  /** All discovered test trace files, sorted by package then name */
+  testTraces: DiscoveredTestTrace[];
+  /** All discovered storyboards (hierarchical organization of canvas + workflows + test traces) */
+  storyboards: DiscoveredStoryboard[];
+  /** All discovered dashboard files from .principal-views/dashboards/ */
+  dashboards: DiscoveredDashboard[];
+  /** Any errors encountered during discovery */
+  errors: Array<{ path: string; error: string }>;
+  /** Deprecation warnings for legacy structures */
+  warnings: Array<{ path: string; message: string; type: 'deprecation' }>;
+}
+
+/**
+ * Options for file discovery
+ */
+export interface DiscoveryOptions {
+  /**
+   * Optional function to read and parse canvas file contents
+   * Useful when you want parsed canvas objects, not just metadata
+   *
+   * @example
+   * // In CLI with filesystem access:
+   * fileReader: async (path) => fs.promises.readFile(path, 'utf-8')
+   *
+   * @example
+   * // In panels with cache:
+   * fileReader: async (path) => context.getSlice('fileCache').read(path)
+   */
+  fileReader?: (path: string) => Promise<string>;
+
+  /**
+   * Whether to include canvas content in results
+   * Requires fileReader to be provided
+   */
+  includeContent?: boolean;
+}
+
+/**
+ * Discovered canvas with parsed content
+ */
+export interface DiscoveredCanvasWithContent extends DiscoveredCanvas {
+  /** Parsed canvas content (only when includeContent: true) */
+  content: ExtendedCanvas;
+}
+
+/**
+ * Discovered test trace with parsed content
+ */
+export interface DiscoveredTestTraceWithContent extends DiscoveredTestTrace {
+  /** Parsed test trace artifact (only when includeContent: true) */
+  content: ExecutionData;
+}
+
+/**
+ * Discovered workflow with parsed content
+ */
+export interface DiscoveredWorkflowWithContent extends DiscoveredWorkflow {
+  /** Parsed workflow template (only when includeContent: true) */
+  content: WorkflowTemplate;
+  /** Test traces with parsed content */
+  testTraces: (DiscoveredTestTrace | DiscoveredTestTraceWithContent)[];
+}
+
+/**
+ * Discovered storyboard with parsed content
+ */
+export interface DiscoveredStoryboardWithContent extends DiscoveredStoryboard {
+  /** Canvas with parsed content */
+  canvas: DiscoveredCanvas | DiscoveredCanvasWithContent;
+  /** Workflows with parsed content */
+  workflows: (DiscoveredWorkflow | DiscoveredWorkflowWithContent)[];
+}
+
+/**
+ * Discovery result with content
+ */
+export interface CanvasDiscoveryResultWithContent {
+  canvases: (DiscoveredCanvas | DiscoveredCanvasWithContent)[];
+  testTraces: (DiscoveredTestTrace | DiscoveredTestTraceWithContent)[];
+  storyboards: (DiscoveredStoryboard | DiscoveredStoryboardWithContent)[];
+  dashboards: (DiscoveredDashboard | DiscoveredDashboardWithContent)[];
+  errors: Array<{ path: string; error: string }>;
+  warnings: Array<{ path: string; message: string; type: 'deprecation' }>;
+}
+
+// =============================================================================
+// Canvas File Manifest Types
+// =============================================================================
+
+/**
+ * Classification of how a file relates to a canvas/workflow
+ */
+export type CanvasFileRole =
+  | 'instrumentation' // File contains OTEL instrumentation (from otel.files)
+  | 'reference' // External reference/documentation (from otel.references)
+  | 'root-span'; // Root span instrumentation (from workflow.files)
+
+/**
+ * Origin of the file - internal to repo or external
+ */
+export type CanvasFileOrigin = 'internal' | 'external';
+
+/**
+ * Source level where the file was defined
+ */
+export type CanvasFileLevel = 'canvas-node' | 'workflow';
+
+/**
+ * A file referenced by a canvas, workflow, or scenario
+ */
+export interface CanvasFile {
+  /** File path (relative to repo root for internal, URL/package ref for external) */
+  path: string;
+
+  /** How this file relates to the canvas */
+  role: CanvasFileRole;
+
+  /** Whether the file is in this repo or external */
+  origin: CanvasFileOrigin;
+
+  /** Where this file reference was defined */
+  level: CanvasFileLevel;
+
+  /** IDs of nodes that reference this file (for canvas-node level) */
+  nodeIds: string[];
+
+  /** Node types that reference this file */
+  nodeTypes: string[];
+
+  /** Workflow IDs that reference this file (for workflow level) */
+  workflowIds: string[];
+
+  /** Event names associated with this file's nodes */
+  eventNames: string[];
+}
+
+/**
+ * Canvas-level statistics
+ */
+export interface CanvasFileStats {
+  totalFiles: number;
+  internalFiles: number;
+  externalFiles: number;
+  instrumentationFiles: number;
+  referenceFiles: number;
+  nodesWithFiles: number;
+  nodesWithoutFiles: number;
+  uniqueEventNames: number;
+}
+
+/**
+ * Storyboard-level statistics
+ */
+export interface StoryboardFileStats extends CanvasFileStats {
+  workflowCount: number;
+  scenarioCount: number;
+  rootSpanFiles: number;
+}
+
+/**
+ * File manifest for a single canvas (without workflows)
+ */
+export interface CanvasFileManifest {
+  /** Canvas ID */
+  canvasId: string;
+
+  /** Canvas path */
+  canvasPath: string;
+
+  /** Canvas type */
+  canvasType: CanvasType;
+
+  /** All files from canvas nodes, deduplicated */
+  files: CanvasFile[];
+
+  /** Quick lookup by role */
+  byRole: Record<CanvasFileRole, CanvasFile[]>;
+
+  /** Quick lookup by origin */
+  byOrigin: Record<CanvasFileOrigin, CanvasFile[]>;
+
+  /** Reverse mapping: file path -> node IDs */
+  fileToNodes: Map<string, string[]>;
+
+  /** Reverse mapping: node ID -> file paths */
+  nodeToFiles: Map<string, string[]>;
+
+  /** Reverse mapping: event name -> file paths */
+  eventToFiles: Map<string, string[]>;
+
+  /** Summary statistics */
+  stats: CanvasFileStats;
+}
+
+/**
+ * File manifest for a workflow (includes canvas + workflow-level files)
+ */
+export interface WorkflowFileManifest extends CanvasFileManifest {
+  /** Workflow ID */
+  workflowId: string;
+
+  /** Workflow path */
+  workflowPath: string;
+
+  /** Root span name */
+  rootSpan?: string;
+
+  /** Files from workflow.files property */
+  workflowFiles: CanvasFile[];
+
+  /** Merged files (canvas + workflow) */
+  allFiles: CanvasFile[];
+
+  /** Files filtered by scenario (scenario ID -> files) */
+  byScenario: Map<string, CanvasFile[]>;
+}
+
+/**
+ * File manifest for an entire storyboard
+ */
+export interface StoryboardFileManifest {
+  /** Storyboard ID */
+  storyboardId: string;
+
+  /** Storyboard path */
+  storyboardPath: string;
+
+  /** Main canvas manifest */
+  canvas: CanvasFileManifest;
+
+  /** Workflow manifests */
+  workflows: WorkflowFileManifest[];
+
+  /** All files across canvas and all workflows */
+  allFiles: CanvasFile[];
+
+  /** Summary statistics */
+  stats: StoryboardFileStats;
+}
+
+/**
+ * Discovered canvas with content AND file manifest
+ */
+export interface DiscoveredCanvasWithManifest extends DiscoveredCanvasWithContent {
+  manifest: CanvasFileManifest;
+}
+
+/**
+ * Discovered workflow with content AND file manifest
+ */
+export interface DiscoveredWorkflowWithManifest extends DiscoveredWorkflowWithContent {
+  manifest: WorkflowFileManifest;
+}
+
+/**
+ * Discovered storyboard with content AND file manifest
+ */
+export interface DiscoveredStoryboardWithManifest extends DiscoveredStoryboardWithContent {
+  manifest: StoryboardFileManifest;
+}

package/src/events/EventsCanvasValidator.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { NodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
+import { EventsCanvasValidator } from './EventsCanvasValidator';
+import type { ExtendedCanvas } from '../types/canvas';
+
+let testRoot: string;
+
+beforeAll(() => {
+  testRoot = mkdtempSync(join(tmpdir(), 'events-canvas-validator-'));
+  mkdirSync(join(testRoot, 'src/events'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/workflow/scenarios'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/trace'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/generated/events'), { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(testRoot, { recursive: true, force: true });
+});
+
+function namespaceNode(
+  id: string,
+  name: string,
+  opts: { paths?: string[]; eventNames?: string[] } = {},
+): any {
+  const eventNames = opts.eventNames ?? [`${name}.happened`];
+  return {
+    id,
+    type: 'event-namespace',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    namespace: {
+      name,
+      description: `${name} description`,
+      paths: opts.paths,
+      events: eventNames.map((n) => ({
+        name: n,
+        severity: 'INFO',
+        description: `desc for ${n}`,
+      })),
+    },
+  };
+}
+
+function canvas(nodes: any[]): ExtendedCanvas {
+  return { nodes, edges: [] } as unknown as ExtendedCanvas;
+}
+
+async function runValidator(nodes: any[]) {
+  const validator = new EventsCanvasValidator(new NodeFileSystemAdapter());
+  return validator.validate({
+    eventsCanvas: canvas(nodes),
+    eventsCanvasPath: 'test.events.canvas',
+    basePath: testRoot,
+  });
+}
+
+function rules(result: { violations: Array<{ ruleId: string }> }, ruleId: string) {
+  return result.violations.filter((v) => v.ruleId === ruleId);
+}
+
+describe('EventsCanvasValidator — paths field', () => {
+  test('namespace without paths: no path-related violations (opt-in, backward compatible)', async () => {
+    const result = await runValidator([namespaceNode('events', 'events')]);
+
+    expect(rules(result, 'events-namespace-multiple-paths')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-missing')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('namespace with one existing path: no path-related violations', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', { paths: ['src/events'] }),
+    ]);
+
+    expect(rules(result, 'events-namespace-multiple-paths')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-missing')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('namespace with missing path: warns events-namespace-paths-missing', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', { paths: ['src/does-not-exist'] }),
+    ]);
+
+    const missing = rules(result, 'events-namespace-paths-missing');
+    expect(missing).toHaveLength(1);
+    expect(missing[0].severity).toBe('warn');
+    expect(missing[0].message).toContain('src/does-not-exist');
+  });
+
+  test('namespace with multiple paths: warns events-namespace-multiple-paths', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', {
+        paths: ['src/events', 'src/generated/events'],
+      }),
+    ]);
+
+    const multi = rules(result, 'events-namespace-multiple-paths');
+    expect(multi).toHaveLength(1);
+    expect(multi[0].severity).toBe('warn');
+    expect(multi[0].message).toContain('2 paths');
+  });
+
+  test('two namespaces declaring identical paths: errors events-namespace-paths-overlap', async () => {
+    const result = await runValidator([
+      namespaceNode('a', 'alpha', {
+        paths: ['src/events'],
+        eventNames: ['alpha.happened'],
+      }),
+      namespaceNode('b', 'beta', {
+        paths: ['src/events'],
+        eventNames: ['beta.happened'],
+      }),
+    ]);
+
+    const overlap = rules(result, 'events-namespace-paths-overlap');
+    expect(overlap).toHaveLength(1);
+    expect(overlap[0].severity).toBe('error');
+    expect(result.valid).toBe(false);
+  });
+
+  test('parent-child partition (workflow / workflow.scenarios): no overlap error', async () => {
+    const result = await runValidator([
+      namespaceNode('workflow', 'workflow', {
+        paths: ['src/workflow'],
+        eventNames: ['workflow.happened'],
+      }),
+      namespaceNode('workflow.scenarios', 'workflow.scenarios', {
+        paths: ['src/workflow/scenarios'],
+        eventNames: ['workflow.scenarios.matched'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('disjoint sibling paths: no overlap error', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', {
+        paths: ['src/events'],
+        eventNames: ['events.happened'],
+      }),
+      namespaceNode('trace', 'trace', {
+        paths: ['src/trace'],
+        eventNames: ['trace.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('path normalization: trailing slashes and "./" prefix compared equivalently', async () => {
+    const result = await runValidator([
+      namespaceNode('a', 'alpha', {
+        paths: ['src/events/'],
+        eventNames: ['alpha.happened'],
+      }),
+      namespaceNode('b', 'beta', {
+        paths: ['./src/events'],
+        eventNames: ['beta.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(1);
+  });
+
+  test('similar-prefix paths that are not parent/child: no overlap error', async () => {
+    // src/foo and src/foobar share a prefix but neither is a descendant of the other.
+    // These should not trigger the overlap rule.
+    mkdirSync(join(testRoot, 'src/foo'), { recursive: true });
+    mkdirSync(join(testRoot, 'src/foobar'), { recursive: true });
+
+    const result = await runValidator([
+      namespaceNode('a', 'foo', {
+        paths: ['src/foo'],
+        eventNames: ['foo.happened'],
+      }),
+      namespaceNode('b', 'foobar', {
+        paths: ['src/foobar'],
+        eventNames: ['foobar.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+});