@principal-ai/principal-view-core 0.6.3 → 0.7.0

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

@@ -0,0 +1,368 @@
+/**
+ * Tests for scenario matching logic
+ */
+
+import { selectScenario, matchesCondition, hasEventMatching, evaluateAssertion, computeAggregates, getNestedValue } from '../scenario-matcher';
+import type { NarrativeTemplate, OtelEvent, ScenarioCondition } 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);
+  });
+
+  it('should match wildcard suffix patterns', () => {
+    expect(hasEventMatching(events, 'conversion.*')).toBe(true);
+    expect(hasEventMatching(events, 'rule.*')).toBe(true);
+    expect(hasEventMatching(events, 'test.*')).toBe(false);
+  });
+
+  it('should match wildcard prefix patterns', () => {
+    expect(hasEventMatching(events, '*.error')).toBe(true);
+    expect(hasEventMatching(events, '*.completed')).toBe(true);
+    expect(hasEventMatching(events, '*.failed')).toBe(false);
+  });
+
+  it('should match full wildcard', () => {
+    expect(hasEventMatching(events, '*')).toBe(true);
+    expect(hasEventMatching([], '*')).toBe(false);
+  });
+});
+
+describe('evaluateAssertion', () => {
+  it('should evaluate $gt (greater than)', () => {
+    expect(evaluateAssertion(10, { $gt: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $gt: 5 }).matches).toBe(false);
+    expect(evaluateAssertion(3, { $gt: 5 }).matches).toBe(false);
+  });
+
+  it('should evaluate $gte (greater than or equal)', () => {
+    expect(evaluateAssertion(10, { $gte: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $gte: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(3, { $gte: 5 }).matches).toBe(false);
+  });
+
+  it('should evaluate $lt (less than)', () => {
+    expect(evaluateAssertion(3, { $lt: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $lt: 5 }).matches).toBe(false);
+    expect(evaluateAssertion(10, { $lt: 5 }).matches).toBe(false);
+  });
+
+  it('should evaluate $lte (less than or equal)', () => {
+    expect(evaluateAssertion(3, { $lte: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $lte: 5 }).matches).toBe(true);
+    expect(evaluateAssertion(10, { $lte: 5 }).matches).toBe(false);
+  });
+
+  it('should evaluate $eq (equality)', () => {
+    expect(evaluateAssertion(5, { $eq: 5 }).matches).toBe(true);
+    expect(evaluateAssertion('test', { $eq: 'test' }).matches).toBe(true);
+    expect(evaluateAssertion(true, { $eq: true }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $eq: 10 }).matches).toBe(false);
+  });
+
+  it('should evaluate $ne (not equal)', () => {
+    expect(evaluateAssertion(5, { $ne: 10 }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $ne: 5 }).matches).toBe(false);
+  });
+
+  it('should evaluate $exists', () => {
+    expect(evaluateAssertion('value', { $exists: true }).matches).toBe(true);
+    expect(evaluateAssertion(undefined, { $exists: true }).matches).toBe(false);
+    expect(evaluateAssertion(null, { $exists: true }).matches).toBe(false);
+    expect(evaluateAssertion(undefined, { $exists: false }).matches).toBe(true);
+  });
+
+  it('should evaluate $in (array membership)', () => {
+    expect(evaluateAssertion('a', { $in: ['a', 'b', 'c'] }).matches).toBe(true);
+    expect(evaluateAssertion(5, { $in: [1, 5, 10] }).matches).toBe(true);
+    expect(evaluateAssertion('d', { $in: ['a', 'b', 'c'] }).matches).toBe(false);
+  });
+
+  it('should evaluate $nin (not in array)', () => {
+    expect(evaluateAssertion('d', { $nin: ['a', 'b', 'c'] }).matches).toBe(true);
+    expect(evaluateAssertion('a', { $nin: ['a', 'b', 'c'] }).matches).toBe(false);
+  });
+
+  it('should handle undefined/null values for numeric comparisons', () => {
+    expect(evaluateAssertion(undefined, { $gt: 5 }).matches).toBe(false);
+    expect(evaluateAssertion(null, { $lt: 5 }).matches).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('matchesCondition', () => {
+  const events: OtelEvent[] = [
+    { name: 'conversion.started', timestamp: 0 },
+    { name: 'conversion.complete', timestamp: 100 },
+    { name: 'rule.completed', timestamp: 50 },
+  ];
+
+  const attributes = {
+    'result.violations.total': 5,
+    'result.violations.errors': 2,
+  };
+
+  it('should match default condition', () => {
+    const condition: ScenarioCondition = { default: true };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should match when all required events are present', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.started', 'conversion.complete'],
+    };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should not match when required events are missing', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.started', 'missing.event'],
+    };
+    const result = matchesCondition(condition, events, attributes);
+    expect(result.matches).toBe(false);
+    expect(result.reason).toContain('missing.event');
+  });
+
+  it('should match with wildcard requires', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.*'],
+    };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should not match when excluded events are present', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.*'],
+      excludes: ['rule.completed'],
+    };
+    const result = matchesCondition(condition, events, attributes);
+    expect(result.matches).toBe(false);
+    expect(result.reason).toContain('rule.completed');
+  });
+
+  it('should match when excluded events are not present', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.*'],
+      excludes: ['error.*'],
+    };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should match with assertions', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.complete'],
+      assertions: {
+        'result.violations.total': { $gt: 0 },
+      },
+    };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should not match when assertions fail', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.complete'],
+      assertions: {
+        'result.violations.total': { $eq: 0 },
+      },
+    };
+    const result = matchesCondition(condition, events, attributes);
+    expect(result.matches).toBe(false);
+    expect(result.reason).toContain('result.violations.total');
+  });
+
+  it('should match ANY when any=true', () => {
+    const condition: ScenarioCondition = {
+      requires: ['conversion.started', 'missing.event'],
+      any: true,
+    };
+    expect(matchesCondition(condition, events, attributes).matches).toBe(true);
+  });
+
+  it('should not match ANY when no requirements met', () => {
+    const condition: ScenarioCondition = {
+      requires: ['missing.one', 'missing.two'],
+      any: true,
+    };
+    const result = matchesCondition(condition, events, attributes);
+    expect(result.matches).toBe(false);
+  });
+});
+
+describe('selectScenario', () => {
+  const template: NarrativeTemplate = {
+    version: '1.0.0',
+    canvas: 'test.otel.canvas',
+    name: 'Test Template',
+    description: 'Test template for scenario selection',
+    mode: 'span-tree',
+    scenarioSelection: 'first-match',
+    scenarios: [
+      {
+        id: 'error',
+        priority: 1,
+        description: 'Error occurred',
+        condition: { requires: ['*.error'] },
+        template: { introduction: 'Error scenario' },
+      },
+      {
+        id: 'violations',
+        priority: 2,
+        description: 'Violations found',
+        condition: {
+          requires: ['conversion.complete'],
+          assertions: { 'result.violations.total': { $gt: 0 } },
+        },
+        template: { introduction: 'Violations scenario' },
+      },
+      {
+        id: 'happy',
+        priority: 3,
+        description: 'All good',
+        condition: {
+          requires: ['conversion.complete'],
+          assertions: { 'result.violations.total': { $eq: 0 } },
+        },
+        template: { introduction: 'Happy path' },
+      },
+      {
+        id: 'fallback',
+        priority: 99,
+        description: 'Fallback',
+        condition: { default: true },
+        template: { introduction: 'Fallback scenario' },
+      },
+    ],
+  };
+
+  it('should select first matching scenario (error)', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.started', timestamp: 0 },
+      { name: 'conversion.error', timestamp: 50 },
+    ];
+    const result = selectScenario(template, events, {});
+    expect(result.scenario.id).toBe('error');
+    expect(result.isDefault).toBe(false);
+  });
+
+  it('should select violations scenario', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.started', timestamp: 0 },
+      { name: 'conversion.complete', timestamp: 100 },
+    ];
+    const attributes = { 'result.violations.total': 5 };
+    const result = selectScenario(template, events, attributes);
+    expect(result.scenario.id).toBe('violations');
+  });
+
+  it('should select happy path scenario', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.started', timestamp: 0 },
+      { name: 'conversion.complete', timestamp: 100 },
+    ];
+    const attributes = { 'result.violations.total': 0 };
+    const result = selectScenario(template, events, attributes);
+    expect(result.scenario.id).toBe('happy');
+  });
+
+  it('should select fallback when no other matches', () => {
+    const events: OtelEvent[] = [{ name: 'unknown.event', timestamp: 0 }];
+    const result = selectScenario(template, events, {});
+    expect(result.scenario.id).toBe('fallback');
+    expect(result.isDefault).toBe(true);
+  });
+
+  it('should throw error if no scenario matches (missing fallback)', () => {
+    const badTemplate: NarrativeTemplate = {
+      ...template,
+      scenarios: [template.scenarios[0]], // Only error scenario, no fallback
+    };
+    const events: OtelEvent[] = [{ name: 'conversion.complete', timestamp: 0 }];
+    expect(() => selectScenario(badTemplate, events, {})).toThrow('No scenario matched');
+  });
+
+  it('should return applicable scenarios for UI', () => {
+    const events: OtelEvent[] = [
+      { name: 'conversion.complete', timestamp: 100 },
+    ];
+    const attributes = { 'result.violations.total': 5 };
+    const result = selectScenario(template, events, attributes);
+    expect(result.applicableScenarios.length).toBeGreaterThan(1);
+    expect(result.applicableScenarios[0].id).toBe('violations');
+    expect(result.applicableScenarios).toContainEqual(expect.objectContaining({ id: 'fallback' }));
+  });
+});
+
+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);
+  });
+});

package/src/narrative/__tests__/template-parser.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Tests for template expression parser
+ */
+
+import { parseTemplate, evaluateExpression } from '../template-parser';
+
+describe('evaluateExpression', () => {
+  const context = {
+    config: { nodeTypes: 5, edgeTypes: 3 },
+    result: { nodes: { count: 12 }, violations: { total: 3, errors: 2 } },
+    duration: { ms: 45 },
+    count: 10,
+    text: 'hello',
+  };
+
+  describe('property access', () => {
+    it('should access simple properties', () => {
+      expect(evaluateExpression('count', context)).toBe(10);
+      expect(evaluateExpression('text', context)).toBe('hello');
+    });
+
+    it('should access nested properties', () => {
+      expect(evaluateExpression('config.nodeTypes', context)).toBe(5);
+      expect(evaluateExpression('result.nodes.count', context)).toBe(12);
+      expect(evaluateExpression('result.violations.total', context)).toBe(3);
+    });
+
+    it('should return undefined for missing properties', () => {
+      expect(evaluateExpression('missing', context)).toBeUndefined();
+      expect(evaluateExpression('config.missing', context)).toBeUndefined();
+    });
+  });
+
+  describe('literals', () => {
+    it('should handle string literals', () => {
+      expect(evaluateExpression("'hello'", context)).toBe('hello');
+      expect(evaluateExpression('"world"', context)).toBe('world');
+    });
+
+    it('should handle number literals', () => {
+      expect(evaluateExpression('42', context)).toBe(42);
+      expect(evaluateExpression('3.14', context)).toBe(3.14);
+      expect(evaluateExpression('-5', context)).toBe(-5);
+    });
+
+    it('should handle boolean literals', () => {
+      expect(evaluateExpression('true', context)).toBe(true);
+      expect(evaluateExpression('false', context)).toBe(false);
+    });
+
+    it('should handle null and undefined', () => {
+      expect(evaluateExpression('null', context)).toBe(null);
+      expect(evaluateExpression('undefined', context)).toBe(undefined);
+    });
+  });
+
+  describe('comparisons', () => {
+    it('should evaluate greater than', () => {
+      expect(evaluateExpression('count > 5', context)).toBe(true);
+      expect(evaluateExpression('count > 10', context)).toBe(false);
+    });
+
+    it('should evaluate greater than or equal', () => {
+      expect(evaluateExpression('count >= 10', context)).toBe(true);
+      expect(evaluateExpression('count >= 11', context)).toBe(false);
+    });
+
+    it('should evaluate less than', () => {
+      expect(evaluateExpression('count < 15', context)).toBe(true);
+      expect(evaluateExpression('count < 10', context)).toBe(false);
+    });
+
+    it('should evaluate less than or equal', () => {
+      expect(evaluateExpression('count <= 10', context)).toBe(true);
+      expect(evaluateExpression('count <= 9', context)).toBe(false);
+    });
+
+    it('should evaluate equality', () => {
+      expect(evaluateExpression('count === 10', context)).toBe(true);
+      expect(evaluateExpression('count === 5', context)).toBe(false);
+      expect(evaluateExpression("text === 'hello'", context)).toBe(true);
+    });
+
+    it('should evaluate inequality', () => {
+      expect(evaluateExpression('count !== 5', context)).toBe(true);
+      expect(evaluateExpression('count !== 10', context)).toBe(false);
+    });
+  });
+
+  describe('arithmetic', () => {
+    it('should add', () => {
+      expect(evaluateExpression('count + 5', context)).toBe(15);
+      expect(evaluateExpression('config.nodeTypes + config.edgeTypes', context)).toBe(8);
+    });
+
+    it('should subtract', () => {
+      expect(evaluateExpression('count - 3', context)).toBe(7);
+    });
+
+    it('should multiply', () => {
+      expect(evaluateExpression('count * 2', context)).toBe(20);
+    });
+
+    it('should divide', () => {
+      expect(evaluateExpression('count / 2', context)).toBe(5);
+      expect(evaluateExpression('duration.ms / 1000', context)).toBe(0.045);
+    });
+  });
+
+  describe('ternary operator', () => {
+    it('should evaluate ternary with true condition', () => {
+      expect(evaluateExpression("count > 5 ? 'yes' : 'no'", context)).toBe('yes');
+    });
+
+    it('should evaluate ternary with false condition', () => {
+      expect(evaluateExpression("count < 5 ? 'yes' : 'no'", context)).toBe('no');
+    });
+
+    it('should handle nested ternaries', () => {
+      expect(evaluateExpression("count > 10 ? 'high' : count > 5 ? 'medium' : 'low'", context)).toBe('medium');
+    });
+  });
+
+  describe('string methods', () => {
+    it('should call repeat on string literal', () => {
+      expect(evaluateExpression("'━'.repeat(5)", context)).toBe('━━━━━');
+      expect(evaluateExpression("'ab'.repeat(3)", context)).toBe('ababab');
+    });
+
+    it('should call repeat on property value', () => {
+      const ctx = { separator: '=' };
+      expect(evaluateExpression("separator.repeat(10)", ctx)).toBe('==========');
+    });
+
+    it('should call substring', () => {
+      expect(evaluateExpression("'hello world'.substring(0, 5)", context)).toBe('hello');
+    });
+
+    it('should call slice', () => {
+      expect(evaluateExpression("'hello world'.slice(6)", context)).toBe('world');
+    });
+
+    it('should call toUpperCase', () => {
+      expect(evaluateExpression("'hello'.toUpperCase()", context)).toBe('HELLO');
+    });
+
+    it('should call toLowerCase', () => {
+      expect(evaluateExpression("'HELLO'.toLowerCase()", context)).toBe('hello');
+    });
+
+    it('should call trim', () => {
+      expect(evaluateExpression("'  hello  '.trim()", context)).toBe('hello');
+    });
+
+    it('should call replace', () => {
+      expect(evaluateExpression("'hello world'.replace('world', 'there')", context)).toBe('hello there');
+    });
+  });
+});
+
+describe('parseTemplate', () => {
+  const context = {
+    config: { nodeTypes: 5, edgeTypes: 3 },
+    result: { nodes: { count: 12 }, violations: { total: 3, errors: 2 } },
+    duration: { ms: 45 },
+  };
+
+  it('should parse simple property substitution', () => {
+    expect(parseTemplate('Found {result.nodes.count} nodes', context)).toBe('Found 12 nodes');
+  });
+
+  it('should parse multiple substitutions', () => {
+    expect(parseTemplate('Config has {config.nodeTypes} node types and {config.edgeTypes} edge types', context)).toBe(
+      'Config has 5 node types and 3 edge types'
+    );
+  });
+
+  it('should parse nested properties', () => {
+    expect(parseTemplate('Total violations: {result.violations.total}', context)).toBe('Total violations: 3');
+  });
+
+  it('should parse expressions', () => {
+    expect(parseTemplate('Duration: {duration.ms}ms', context)).toBe('Duration: 45ms');
+  });
+
+  it('should parse ternary expressions', () => {
+    expect(parseTemplate('{result.violations.total > 0 ? "FAILED" : "PASSED"}', context)).toBe('FAILED');
+  });
+
+  it('should parse arithmetic', () => {
+    expect(parseTemplate('Total types: {config.nodeTypes + config.edgeTypes}', context)).toBe('Total types: 8');
+  });
+
+  it('should parse string method calls', () => {
+    expect(parseTemplate('{"=".repeat(10)}', context)).toBe('==========');
+  });
+
+  it('should handle multiple expressions in one template', () => {
+    const template = 'Status: {result.violations.total > 0 ? "❌" : "✅"} - {result.nodes.count} nodes';
+    expect(parseTemplate(template, context)).toBe('Status: ❌ - 12 nodes');
+  });
+
+  it('should leave non-expression text unchanged', () => {
+    expect(parseTemplate('This is plain text', context)).toBe('This is plain text');
+    expect(parseTemplate('No substitutions here!', context)).toBe('No substitutions here!');
+  });
+
+  it('should handle empty expressions gracefully', () => {
+    expect(parseTemplate('Value: {missing.property}', context)).toBe('Value: ');
+  });
+
+  it('should handle errors in expressions', () => {
+    expect(parseTemplate('{invalid.method.call()}', context)).toContain('ERROR');
+  });
+
+  it('should format complex narrative', () => {
+    const template = `✅ Conversion Complete
+{'━'.repeat(50)}
+
+Processed {config.nodeTypes} node types
+Generated {result.nodes.count} nodes in {duration.ms}ms
+
+Status: {result.violations.total === 0 ? "✅ SUCCESS" : "⚠️ {result.violations.total} violations"}`;
+
+    const expected = `✅ Conversion Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Processed 5 node types
+Generated 12 nodes in 45ms
+
+Status: ⚠️ 3 violations`;
+
+    expect(parseTemplate(template, context)).toBe(expected);
+  });
+});