@principal-ai/subsystems-core 0.29.0

package/src/workflow/__tests__/edge-validation.test.ts

@@ -0,0 +1,417 @@
+/**
+ * Tests for edge validation against spans.canvas
+ */
+
+import {
+  extractSpanNodes,
+  extractCanvasEdges,
+  matchSpanToPattern,
+  findMatchingNode,
+  validateEdges,
+  formatValidationResult,
+} from '../edge-validation';
+import type { ExtendedCanvas } from '../../types/canvas';
+import type { DerivedEdge } from '../edge-derivation';
+
+describe('extractSpanNodes', () => {
+  it('extracts nodes with spanPattern', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'cli-command',
+          type: 'text',
+          text: 'CLI Command',
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          pv: {
+            nodeType: 'span-convention',
+            otel: {
+              spanPattern: 'cli.command',
+            },
+          },
+        },
+        {
+          id: 'validate',
+          type: 'text',
+          text: 'Validate',
+          x: 200,
+          y: 0,
+          width: 100,
+          height: 50,
+          pv: {
+            nodeType: 'span-convention',
+            name: 'Validation',
+            otel: {
+              spanPattern: 'validate.*',
+            },
+          },
+        },
+        {
+          id: 'no-span',
+          type: 'text',
+          text: 'No Span',
+          x: 400,
+          y: 0,
+          width: 100,
+          height: 50,
+        },
+      ],
+    };
+
+    const nodes = extractSpanNodes(canvas);
+
+    expect(nodes).toHaveLength(2);
+    expect(nodes[0]).toEqual({
+      nodeId: 'cli-command',
+      spanPattern: 'cli.command',
+      name: undefined,
+    });
+    expect(nodes[1]).toEqual({
+      nodeId: 'validate',
+      spanPattern: 'validate.*',
+      name: 'Validation',
+    });
+  });
+
+  it('returns empty array for canvas without nodes', () => {
+    const canvas: ExtendedCanvas = {};
+    expect(extractSpanNodes(canvas)).toEqual([]);
+  });
+});
+
+describe('extractCanvasEdges', () => {
+  it('extracts edges with span patterns', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'a',
+          type: 'text',
+          text: 'A',
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          pv: { nodeType: 'span', otel: { spanPattern: 'span.a' } },
+        },
+        {
+          id: 'b',
+          type: 'text',
+          text: 'B',
+          x: 200,
+          y: 0,
+          width: 100,
+          height: 50,
+          pv: { nodeType: 'span', otel: { spanPattern: 'span.b' } },
+        },
+      ],
+      edges: [
+        { id: 'e1', fromNode: 'a', toNode: 'b' },
+      ],
+    };
+
+    const spanNodes = extractSpanNodes(canvas);
+    const edges = extractCanvasEdges(canvas, spanNodes);
+
+    expect(edges).toHaveLength(1);
+    expect(edges[0]).toEqual({
+      fromNodeId: 'a',
+      toNodeId: 'b',
+      fromSpanPattern: 'span.a',
+      toSpanPattern: 'span.b',
+    });
+  });
+
+  it('handles missing span patterns', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        { id: 'a', type: 'text', text: 'A', x: 0, y: 0, width: 100, height: 50 },
+        {
+          id: 'b',
+          type: 'text',
+          text: 'B',
+          x: 200,
+          y: 0,
+          width: 100,
+          height: 50,
+          pv: { nodeType: 'span', otel: { spanPattern: 'span.b' } },
+        },
+      ],
+      edges: [
+        { id: 'e1', fromNode: 'a', toNode: 'b' },
+      ],
+    };
+
+    const spanNodes = extractSpanNodes(canvas);
+    const edges = extractCanvasEdges(canvas, spanNodes);
+
+    expect(edges).toHaveLength(1);
+    expect(edges[0].fromSpanPattern).toBeUndefined();
+    expect(edges[0].toSpanPattern).toBe('span.b');
+  });
+});
+
+describe('matchSpanToPattern', () => {
+  it('matches exact span names', () => {
+    expect(matchSpanToPattern('cli.command', 'cli.command')).toBe(true);
+    expect(matchSpanToPattern('cli.command', 'cli.other')).toBe(false);
+  });
+
+  it('matches glob patterns', () => {
+    expect(matchSpanToPattern('validate.canvas', 'validate.*')).toBe(true);
+    expect(matchSpanToPattern('validate.schema', 'validate.*')).toBe(true);
+    expect(matchSpanToPattern('other.canvas', 'validate.*')).toBe(false);
+  });
+
+  it('matches multi-segment patterns', () => {
+    expect(matchSpanToPattern('api.user.create', 'api.*.*')).toBe(true);
+    expect(matchSpanToPattern('api.user', 'api.*.*')).toBe(false);
+  });
+
+  it('matches double-star patterns', () => {
+    expect(matchSpanToPattern('api.user.create', 'api.**')).toBe(true);
+    expect(matchSpanToPattern('api.user', 'api.**')).toBe(true);
+    expect(matchSpanToPattern('other.thing', 'api.**')).toBe(false);
+  });
+});
+
+describe('findMatchingNode', () => {
+  const spanNodes = [
+    { nodeId: 'cli', spanPattern: 'cli.command', name: 'CLI' },
+    { nodeId: 'validate', spanPattern: 'validate.*', name: 'Validate' },
+    { nodeId: 'file', spanPattern: 'file.*', name: 'File' },
+  ];
+
+  it('finds exact match first', () => {
+    const match = findMatchingNode('cli.command', spanNodes);
+    expect(match?.nodeId).toBe('cli');
+  });
+
+  it('falls back to pattern match', () => {
+    const match = findMatchingNode('validate.canvas', spanNodes);
+    expect(match?.nodeId).toBe('validate');
+  });
+
+  it('returns undefined for no match', () => {
+    const match = findMatchingNode('unknown.span', spanNodes);
+    expect(match).toBeUndefined();
+  });
+});
+
+describe('validateEdges', () => {
+  const canvas: ExtendedCanvas = {
+    nodes: [
+      {
+        id: 'root',
+        type: 'text',
+        text: 'Root',
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 50,
+        pv: { nodeType: 'span', otel: { spanPattern: 'cli.command' } },
+      },
+      {
+        id: 'validate',
+        type: 'text',
+        text: 'Validate',
+        x: 200,
+        y: 0,
+        width: 100,
+        height: 50,
+        pv: { nodeType: 'span', otel: { spanPattern: 'validate.*' } },
+      },
+      {
+        id: 'file',
+        type: 'text',
+        text: 'File',
+        x: 400,
+        y: 0,
+        width: 100,
+        height: 50,
+        pv: { nodeType: 'span', otel: { spanPattern: 'file.*' } },
+      },
+    ],
+    edges: [
+      { id: 'e1', fromNode: 'root', toNode: 'validate' },
+      { id: 'e2', fromNode: 'validate', toNode: 'file' },
+    ],
+  };
+
+  it('validates matching edges', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'validate.canvas',
+        scenarioId: 'success',
+        eventNames: ['start', 'validate'],
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    expect(result.validEdges).toHaveLength(1);
+    expect(result.validEdges[0].fromSpan).toBe('cli.command');
+    expect(result.validEdges[0].toSpan).toBe('validate.canvas');
+    expect(result.missingEdges).toHaveLength(0);
+  });
+
+  it('detects missing edges', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'file.read', // No edge from root to file in canvas
+        scenarioId: 'success',
+        eventNames: ['start', 'file'],
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    expect(result.validEdges).toHaveLength(0);
+    expect(result.missingEdges).toHaveLength(1);
+    expect(result.missingEdges[0].fromSpan).toBe('cli.command');
+    expect(result.missingEdges[0].toSpan).toBe('file.read');
+    expect(result.missingEdges[0].fromNodeId).toBe('root');
+    expect(result.missingEdges[0].toNodeId).toBe('file');
+    expect(result.missingEdges[0].reason).toBe('no-edge-in-canvas');
+  });
+
+  it('detects unused canvas edges', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'validate.canvas',
+        scenarioId: 'success',
+        eventNames: ['start', 'validate'],
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    // validate -> file edge is not used
+    expect(result.unusedEdges).toHaveLength(1);
+    expect(result.unusedEdges[0].canvasEdge.fromNodeId).toBe('validate');
+    expect(result.unusedEdges[0].canvasEdge.toNodeId).toBe('file');
+  });
+
+  it('detects unmatched spans', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'unknown.span',
+        scenarioId: 'success',
+        eventNames: ['start', 'unknown'],
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    expect(result.unmatchedSpans).toHaveLength(1);
+    expect(result.unmatchedSpans[0].spanName).toBe('unknown.span');
+  });
+
+  it('aggregates sources for same edge from multiple scenarios', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'validate.canvas',
+        scenarioId: 'success',
+        eventNames: ['start', 'validate'],
+        workflowFile: 'a.json',
+      },
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'validate.canvas',
+        scenarioId: 'failure',
+        eventNames: ['start', 'validate'],
+        workflowFile: 'a.json',
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    expect(result.validEdges).toHaveLength(1);
+    expect(result.validEdges[0].sources).toHaveLength(2);
+  });
+
+  it('provides accurate summary', () => {
+    const derivedEdges: DerivedEdge[] = [
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'validate.canvas',
+        scenarioId: 'success',
+        eventNames: ['start', 'validate'],
+      },
+      {
+        fromSpan: 'cli.command',
+        toSpan: 'file.read', // Missing edge
+        scenarioId: 'success',
+        eventNames: ['start', 'file'],
+      },
+    ];
+
+    const result = validateEdges(derivedEdges, canvas);
+
+    expect(result.summary).toEqual({
+      totalDerivedEdges: 2,
+      totalCanvasEdges: 2,
+      matchedEdges: 1,
+      missingEdges: 1,
+      unusedEdges: 1, // validate -> file
+      unmatchedSpans: 0,
+    });
+  });
+});
+
+describe('formatValidationResult', () => {
+  it('formats validation result as readable text', () => {
+    const result = {
+      validEdges: [
+        {
+          fromSpan: 'cli.command',
+          toSpan: 'validate.canvas',
+          canvasEdge: { fromNodeId: 'root', toNodeId: 'validate' },
+          sources: [{ scenarioId: 'success' }],
+        },
+      ],
+      missingEdges: [
+        {
+          fromSpan: 'cli.command',
+          toSpan: 'file.read',
+          fromNodeId: 'root',
+          toNodeId: 'file',
+          sources: [{ scenarioId: 'success' }],
+          reason: 'no-edge-in-canvas' as const,
+        },
+      ],
+      unusedEdges: [
+        {
+          canvasEdge: {
+            fromNodeId: 'validate',
+            toNodeId: 'file',
+            fromSpanPattern: 'validate.*',
+            toSpanPattern: 'file.*',
+          },
+        },
+      ],
+      unmatchedSpans: [],
+      summary: {
+        totalDerivedEdges: 2,
+        totalCanvasEdges: 2,
+        matchedEdges: 1,
+        missingEdges: 1,
+        unusedEdges: 1,
+        unmatchedSpans: 0,
+      },
+    };
+
+    const formatted = formatValidationResult(result);
+
+    expect(formatted).toContain('Edge Validation Results');
+    expect(formatted).toContain('✓ cli.command → validate.canvas');
+    expect(formatted).toContain('✗ cli.command → file.read');
+    expect(formatted).toContain('⚠ validate.* → file.*');
+  });
+});

package/src/workflow/__tests__/scenario-matcher.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Tests for scenario matching logic
+ */
+
+import { selectScenario, hasEventMatching, computeAggregates, getNestedValue } from '../scenario-matcher';
+import type { WorkflowTemplate, OtelEvent } from '../types';
+
+describe('hasEventMatching', () => {
+  const events: OtelEvent[] = [
+    { name: 'conversion.started', timestamp: 0 },
+    { name: 'conversion.complete', timestamp: 100 },
+    { name: 'rule.completed', timestamp: 50 },
+    { name: 'rule.error', timestamp: 75 },
+    { name: 'log.info', timestamp: 25, type: 'log', severityText: 'INFO' },
+  ];
+
+  it('should match exact event names', () => {
+    expect(hasEventMatching(events, 'conversion.started')).toBe(true);
+    expect(hasEventMatching(events, 'conversion.complete')).toBe(true);
+    expect(hasEventMatching(events, 'nonexistent')).toBe(false);
+  });
+});
+
+describe('getNestedValue', () => {
+  const obj = {
+    result: {
+      violations: {
+        total: 10,
+        errors: 5,
+      },
+    },
+    simple: 'value',
+  };
+
+  it('should get simple property', () => {
+    expect(getNestedValue(obj, 'simple')).toBe('value');
+  });
+
+  it('should get nested property', () => {
+    expect(getNestedValue(obj, 'result.violations.total')).toBe(10);
+    expect(getNestedValue(obj, 'result.violations.errors')).toBe(5);
+  });
+
+  it('should return undefined for missing property', () => {
+    expect(getNestedValue(obj, 'nonexistent')).toBeUndefined();
+    expect(getNestedValue(obj, 'result.missing.path')).toBeUndefined();
+  });
+});
+
+describe('selectScenario', () => {
+  const template: WorkflowTemplate = {
+    version: '1.0.0',
+    canvas: 'test.otel.canvas',
+    name: 'Test Template',
+    description: 'Test template for scenario selection',
+    scenarioSelection: 'first-match',
+    scenarios: [
+      {
+        id: 'error',
+        priority: 1,
+        description: 'Error occurred',
+        template: {
+          introduction: 'Error scenario',
+          events: {
+            'rule.error': 'Error: {{span.name}}',
+          },
+        },
+      },
+      {
+        id: 'complete',
+        priority: 2,
+        description: 'Conversion complete',
+        template: {
+          introduction: 'Complete scenario',
+          events: {
+            'conversion.started': 'Started',
+            'conversion.complete': 'Complete',
+          },
+        },
+      },
+      {
+        id: 'partial',
+        priority: 3,
+        description: 'Partially complete',
+        template: {
+          introduction: 'Partial scenario',
+          events: {
+            'conversion.started': 'Started',
+          },
+        },
+      },
+      {
+        id: 'catch-all',
+        priority: 99,
+        description: 'Fallback',
+        template: {
+          introduction: 'Fallback scenario',
+          events: {}, // No required events (catch-all)
+        },
+      },
+    ],
+  };
+
+  it('should return all full matches sorted by priority', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.started', timestamp: 0 },
+      { name: 'conversion.complete', timestamp: 100 },
+    ];
+    const result = selectScenario(template, events);
+
+    // Both 'complete' and 'partial' should match fully
+    expect(result.fullMatches.length).toBe(2);
+    expect(result.fullMatches[0].scenario.id).toBe('complete'); // Priority 2
+    expect(result.fullMatches[1].scenario.id).toBe('partial'); // Priority 3
+    expect(result.fullMatches[0].isFullMatch).toBe(true);
+    expect(result.fullMatches[0].matchPercentage).toBe(100);
+  });
+
+  it('should recommend highest priority full match', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.started', timestamp: 0 },
+      { name: 'conversion.complete', timestamp: 100 },
+    ];
+    const result = selectScenario(template, events);
+
+    expect(result.recommendedScenario).not.toBeNull();
+    expect(result.recommendedScenario?.scenario.id).toBe('complete');
+    expect(result.recommendedScenario?.isFullMatch).toBe(true);
+  });
+
+  it('should return partial matches when no full match exists', () => {
+    const events: OtelEvent[] = [{ name: 'conversion.started', timestamp: 0 }];
+    const result = selectScenario(template, events);
+
+    // Only 'partial' matches fully
+    expect(result.fullMatches.length).toBe(1);
+    expect(result.fullMatches[0].scenario.id).toBe('partial');
+
+    // Partial matches: 'complete' (50%), 'error' (0%), 'catch-all' (0%)
+    expect(result.partialMatches.length).toBe(3);
+    // Should be sorted by percentage descending, then priority ascending
+    expect(result.partialMatches[0].scenario.id).toBe('complete'); // 50%
+    expect(result.partialMatches[0].matchPercentage).toBe(50);
+  });
+
+  it('should include detailed match information', () => {
+    const events: OtelEvent[] = [{ name: 'conversion.started', timestamp: 0 }];
+    const result = selectScenario(template, events);
+
+    const partialMatch = result.partialMatches.find((m) => m.scenario.id === 'complete');
+    expect(partialMatch).toBeDefined();
+    expect(partialMatch?.matchedEventNames).toEqual(['conversion.started']);
+    expect(partialMatch?.missingEventNames).toEqual(['conversion.complete']);
+    expect(partialMatch?.matchedEventCount).toBe(1);
+    expect(partialMatch?.totalRequiredEvents).toBe(2);
+  });
+
+  it('should handle catch-all scenarios (zero required events)', () => {
+    const events: OtelEvent[] = [{ name: 'unknown.event', timestamp: 0 }];
+    const result = selectScenario(template, events);
+
+    // No full matches - all scenarios should be partial
+    expect(result.fullMatches.length).toBe(0);
+
+    // Catch-all should be in partial matches
+    const catchAll = result.partialMatches.find((m) => m.scenario.id === 'catch-all');
+    expect(catchAll).toBeDefined();
+    expect(catchAll?.isCatchAll).toBe(true);
+    expect(catchAll?.matchPercentage).toBe(0);
+    expect(catchAll?.totalRequiredEvents).toBe(0);
+  });
+
+  it('should return null when no scenarios exist', () => {
+    const emptyTemplate: WorkflowTemplate = {
+      ...template,
+      scenarios: [],
+    };
+    const events: OtelEvent[] = [{ name: 'test', timestamp: 0 }];
+    const result = selectScenario(emptyTemplate, events);
+
+    expect(result.fullMatches.length).toBe(0);
+    expect(result.partialMatches.length).toBe(0);
+    expect(result.recommendedScenario).toBeNull();
+  });
+});
+
+describe('computeAggregates', () => {
+  const events: OtelEvent[] = [
+    { name: 'conversion.started', timestamp: 0, type: 'span' },
+    { name: 'conversion.complete', timestamp: 100, type: 'span', attributes: { 'result.nodes.count': 12 } },
+    { name: 'log.info', timestamp: 25, type: 'log', severityNumber: 9 },
+    { name: 'log.error', timestamp: 75, type: 'log', severityNumber: 17 },
+    { name: 'log.debug', timestamp: 50, type: 'log', severityNumber: 5 },
+  ];
+
+  it('should count total events', () => {
+    const aggregates = computeAggregates(events);
+    expect(aggregates['events.count']).toBe(5);
+    expect(aggregates['events.length']).toBe(5);
+  });
+
+  it('should count spans', () => {
+    const aggregates = computeAggregates(events);
+    expect(aggregates['spans.count']).toBe(2);
+  });
+
+  it('should count logs by severity', () => {
+    const aggregates = computeAggregates(events);
+    expect(aggregates['logs.count']).toBe(3);
+    expect(aggregates['errorLogs.count']).toBe(1);
+    expect(aggregates['debugLogs.count']).toBe(1);
+  });
+
+  it('should extract common attributes', () => {
+    const aggregates = computeAggregates(events);
+    expect(aggregates['result.nodes.count']).toBe(12);
+  });
+
+  it('should handle empty events', () => {
+    const aggregates = computeAggregates([]);
+    expect(aggregates['events.count']).toBe(0);
+    expect(aggregates['spans.count']).toBe(0);
+    expect(aggregates['logs.count']).toBe(0);
+  });
+});