@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/types/canvas-scope.ts

@@ -1,190 +0,0 @@
-/**
- * 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

@@ -1,199 +0,0 @@
-/**
- * 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();
-    });
-  });
-});