@principal-ai/subsystems-core 0.29.0

package/src/types/canvas-scope.ts

@@ -0,0 +1,190 @@
+/**
+ * Canvas Scope Types
+ *
+ * Defines which logs are relevant to a canvas. Only logs matching the canvas
+ * scope are considered for node routing. This acts as a pre-filter before
+ * individual node matching.
+ *
+ * @example
+ * ```yaml
+ * # Canvas configuration
+ * canvas:
+ *   id: "checkout-system"
+ *   scope:
+ *     deployment.environment: "production"
+ *     service.namespace: "checkout"
+ *   audit:
+ *     enabled: true
+ *     orphanThreshold: 100
+ *     coverageTarget: 95
+ * ```
+ */
+
+import type { ResourceMatch } from './resource-match';
+
+/**
+ * Canvas scope - filters which logs are processed by this canvas
+ *
+ * Extends ResourceMatch, so all matching operators are available.
+ * All conditions must match for a log to be "in scope" (AND logic).
+ *
+ * @example
+ * ```typescript
+ * // Only process production logs from the checkout namespace
+ * const scope: CanvasScope = {
+ *   'deployment.environment': 'production',
+ *   'service.namespace': { oneOf: ['checkout', 'payment'] }
+ * };
+ * ```
+ */
+export interface CanvasScope extends ResourceMatch {
+  // Inherits all ResourceMatch fields and operators
+  // All conditions must match for a log to be "in scope"
+}
+
+/**
+ * Duration string format
+ *
+ * Supports common time units: ms, s, m, h, d
+ *
+ * @example "30s", "5m", "1h", "24h", "7d"
+ */
+export type DurationString = string;
+
+/**
+ * Audit configuration for a canvas
+ *
+ * Controls how log routing is monitored and reported.
+ */
+export interface CanvasAuditConfig {
+  /**
+   * Enable audit collection
+   * When enabled, the system tracks:
+   * - Log counts per node
+   * - Orphaned logs (in scope but unmatched)
+   * - Silent nodes (defined but receiving no logs)
+   */
+  enabled: boolean;
+
+  /**
+   * Alert threshold for orphaned logs
+   *
+   * If the number of orphaned logs exceeds this count within
+   * the audit period, an alert or warning is generated.
+   *
+   * @default undefined (no threshold)
+   */
+  orphanThreshold?: number;
+
+  /**
+   * Duration after which a silent node triggers an alert
+   *
+   * If a node receives no logs for this duration, it's flagged
+   * as potentially misconfigured or the service may be down.
+   *
+   * @example "1h", "30m", "24h"
+   * @default undefined (no alerting)
+   */
+  silentNodeAlertAfter?: DurationString;
+
+  /**
+   * Target coverage percentage (0-100)
+   *
+   * The expected percentage of in-scope logs that should be
+   * routed to nodes. Used for coverage analysis and alerts.
+   *
+   * @example 95 (expect 95% of logs to match a node)
+   * @default undefined (no target)
+   */
+  coverageTarget?: number;
+
+  /**
+   * Maximum number of orphan signatures to track
+   *
+   * Orphans are grouped by their resource signature. This limits
+   * memory usage by capping the number of unique signatures tracked.
+   *
+   * @default 1000
+   */
+  maxOrphanSignatures?: number;
+
+  /**
+   * Maximum sample logs per orphan signature
+   *
+   * Number of sample log bodies to keep per orphan group for debugging.
+   *
+   * @default 5
+   */
+  maxSamplesPerOrphan?: number;
+}
+
+/**
+ * Canvas-level configuration for log association
+ *
+ * Top-level configuration that defines scope and audit settings
+ * for a canvas.
+ */
+export interface CanvasLogAssociation {
+  /**
+   * Unique canvas identifier
+   *
+   * Used for routing logs to the correct canvas when multiple
+   * canvases are active, and for audit reports.
+   */
+  id: string;
+
+  /**
+   * Scope filter
+   *
+   * Only logs matching this scope are considered for node routing.
+   * If not specified, all logs are in scope.
+   */
+  scope?: CanvasScope;
+
+  /**
+   * Audit configuration
+   *
+   * If not specified, auditing is disabled.
+   */
+  audit?: CanvasAuditConfig;
+}
+
+/**
+ * Default audit configuration values
+ */
+export const DEFAULT_AUDIT_CONFIG: Partial<CanvasAuditConfig> = {
+  maxOrphanSignatures: 1000,
+  maxSamplesPerOrphan: 5,
+};
+
+/**
+ * Parse a duration string to milliseconds
+ *
+ * @param duration Duration string like "30s", "5m", "1h"
+ * @returns Duration in milliseconds, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseDuration('30s');  // 30000
+ * parseDuration('5m');   // 300000
+ * parseDuration('1h');   // 3600000
+ * parseDuration('24h');  // 86400000
+ * ```
+ */
+export function parseDuration(duration: DurationString): number | null {
+  const match = duration.match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/);
+  if (!match) return null;
+
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+
+  const multipliers: Record<string, number> = {
+    ms: 1,
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+
+  return value * multipliers[unit];
+}

package/src/types/canvas.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Tests for canvas utility functions
+ */
+
+import { describe, it, expect } from 'bun:test';
+import {
+  resolveCanvasColor,
+  CANVAS_COLOR_PRESETS,
+  getOtelNodeIdentifier,
+  type OtelSpanConventionNode,
+  type OtelScopeNode,
+  type OtelResourceNode,
+  type OtelBoundaryNode,
+} from './canvas';
+
+describe('resolveCanvasColor', () => {
+  it('should return undefined for undefined input', () => {
+    expect(resolveCanvasColor(undefined)).toBeUndefined();
+  });
+
+  it('should resolve numeric presets to hex colors', () => {
+    expect(resolveCanvasColor(1)).toBe('#ef4444'); // red
+    expect(resolveCanvasColor(2)).toBe('#f97316'); // orange
+    expect(resolveCanvasColor(3)).toBe('#eab308'); // yellow
+    expect(resolveCanvasColor(4)).toBe('#22c55e'); // green
+    expect(resolveCanvasColor(5)).toBe('#06b6d4'); // cyan
+    expect(resolveCanvasColor(6)).toBe('#8b5cf6'); // purple
+  });
+
+  it('should resolve numeric string presets to hex colors (Obsidian format)', () => {
+    expect(resolveCanvasColor('1')).toBe('#ef4444'); // red
+    expect(resolveCanvasColor('2')).toBe('#f97316'); // orange
+    expect(resolveCanvasColor('3')).toBe('#eab308'); // yellow
+    expect(resolveCanvasColor('4')).toBe('#22c55e'); // green
+    expect(resolveCanvasColor('5')).toBe('#06b6d4'); // cyan
+    expect(resolveCanvasColor('6')).toBe('#8b5cf6'); // purple
+  });
+
+  it('should return hex strings as-is', () => {
+    expect(resolveCanvasColor('#22c55e')).toBe('#22c55e');
+    expect(resolveCanvasColor('#f00')).toBe('#f00');
+    expect(resolveCanvasColor('#3b82f6')).toBe('#3b82f6');
+  });
+
+  it('should return non-numeric strings as-is', () => {
+    expect(resolveCanvasColor('red')).toBe('red');
+    expect(resolveCanvasColor('rgb(255, 0, 0)')).toBe('rgb(255, 0, 0)');
+  });
+
+  it('should handle edge cases for numeric strings', () => {
+    // Out of range numeric strings should be returned as-is
+    expect(resolveCanvasColor('0')).toBe('0');
+    expect(resolveCanvasColor('7')).toBe('7');
+    expect(resolveCanvasColor('10')).toBe('10');
+  });
+
+  it('should verify all preset mappings exist', () => {
+    // Ensure all presets 1-6 are defined
+    for (let i = 1; i <= 6; i++) {
+      expect(CANVAS_COLOR_PRESETS[i]).toBeDefined();
+      expect(CANVAS_COLOR_PRESETS[i]).toMatch(/^#[0-9a-f]{6}$/i);
+    }
+  });
+});
+
+describe('getOtelNodeIdentifier', () => {
+  describe('otel-span-convention nodes', () => {
+    it('should return spanPattern for valid nodes', () => {
+      const node: OtelSpanConventionNode = {
+        id: 'test-span',
+        type: 'otel-span-convention',
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        otel: {
+          spanPattern: 'activity-feed.init',
+          spanKind: 'internal',
+        },
+      };
+      expect(getOtelNodeIdentifier(node)).toBe('activity-feed.init');
+    });
+
+    it('should handle nodes with missing otel property gracefully', () => {
+      // BUG REPRODUCTION: This test demonstrates the crash when otel is undefined
+      // The validator CLI crashes with: "Cannot read properties of undefined (reading 'spanPattern')"
+      // This happens when a .spans.canvas file has malformed otel-span-convention nodes
+      const malformedNode = {
+        id: 'malformed-span',
+        type: 'otel-span-convention' as const,
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        // otel property is missing - this causes the crash
+      } as OtelSpanConventionNode;
+
+      // Currently this throws: Cannot read properties of undefined (reading 'spanPattern')
+      // Expected behavior: should return undefined gracefully
+      expect(() => getOtelNodeIdentifier(malformedNode)).not.toThrow();
+      expect(getOtelNodeIdentifier(malformedNode)).toBeUndefined();
+    });
+  });
+
+  describe('otel-scope nodes', () => {
+    it('should return scope for valid nodes', () => {
+      const node: OtelScopeNode = {
+        id: 'test-scope',
+        type: 'otel-scope',
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        otel: {
+          scope: 'activity-feed',
+        },
+      };
+      expect(getOtelNodeIdentifier(node)).toBe('activity-feed');
+    });
+
+    it('should handle nodes with missing otel property gracefully', () => {
+      const malformedNode = {
+        id: 'malformed-scope',
+        type: 'otel-scope' as const,
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+      } as OtelScopeNode;
+
+      expect(() => getOtelNodeIdentifier(malformedNode)).not.toThrow();
+      expect(getOtelNodeIdentifier(malformedNode)).toBeUndefined();
+    });
+  });
+
+  describe('otel-resource nodes', () => {
+    it('should return first resource match entry for valid nodes', () => {
+      const node: OtelResourceNode = {
+        id: 'test-resource',
+        type: 'otel-resource',
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        otel: {
+          resourceMatch: {
+            'service.name': 'my-service',
+          },
+        },
+      };
+      expect(getOtelNodeIdentifier(node)).toBe('service.name: my-service');
+    });
+
+    it('should handle nodes with missing otel property gracefully', () => {
+      const malformedNode = {
+        id: 'malformed-resource',
+        type: 'otel-resource' as const,
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+      } as OtelResourceNode;
+
+      expect(() => getOtelNodeIdentifier(malformedNode)).not.toThrow();
+      expect(getOtelNodeIdentifier(malformedNode)).toBeUndefined();
+    });
+  });
+
+  describe('otel-boundary nodes', () => {
+    it('should return direction for valid nodes', () => {
+      const node: OtelBoundaryNode = {
+        id: 'test-boundary',
+        type: 'otel-boundary',
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+        boundary: {
+          direction: 'incoming',
+        },
+      };
+      expect(getOtelNodeIdentifier(node)).toBe('incoming');
+    });
+
+    it('should handle nodes with missing boundary property gracefully', () => {
+      const malformedNode = {
+        id: 'malformed-boundary',
+        type: 'otel-boundary' as const,
+        x: 0,
+        y: 0,
+        width: 200,
+        height: 100,
+      } as OtelBoundaryNode;
+
+      expect(() => getOtelNodeIdentifier(malformedNode)).not.toThrow();
+      expect(getOtelNodeIdentifier(malformedNode)).toBeUndefined();
+    });
+  });
+});