@principal-ai/subsystems-core 0.29.0

package/src/types/library.ts

@@ -0,0 +1,283 @@
+/**
+ * Component Library Types
+ *
+ * Defines the structure for component libraries (.yaml/.json files)
+ * that contain reusable node and edge type definitions.
+ *
+ * Libraries are separate from canvas files:
+ * - Canvas files (.canvas) = actual graph layouts that get rendered
+ * - Library files (.yaml/.json) = collections of reusable type definitions
+ *
+ * When a user adds a component from the library to a canvas,
+ * the type definition gets embedded into the node's `pv` field.
+ */
+
+import type {
+  PVNodeShape,
+  PVEdgeStyle,
+  PVAnimationType,
+  // PVActionPattern removed - see docs/LEGACY_PATH_BASED_PATTERNS.md
+  PVNodeState,
+  PVEventSchema,
+} from './canvas';
+
+// ============================================================================
+// Resource Types
+// ============================================================================
+
+/**
+ * Definition for an instrumentation scope
+ *
+ * Describes a scope with its color and optional metadata.
+ * Used for consistent visual representation across canvases.
+ *
+ * @deprecated Scope visual metadata is now defined in .scopes.canvas files using OtelScopeNode type.
+ * This type is kept for backward compatibility during migration but will be removed in a future version.
+ * Use .scopes.canvas files instead of the top-level scopes section in library.yaml.
+ */
+export interface ScopeDefinition {
+  /** Color for nodes belonging to this scope (hex format). Required unless external. */
+  color?: string;
+
+  /** Icon identifier (Lucide icons) */
+  icon?: string;
+
+  /** Human-readable description of what this scope covers */
+  description?: string;
+
+  /**
+   * Mark this scope as external - defined in another library/package.
+   * External scopes don't require color (they inherit from the defining library).
+   */
+  external?: boolean;
+}
+
+/**
+ * Owned scopes: array of scope names that reference top-level scopes
+ *
+ * Scope definitions are declared in the top-level `scopes` section of library.yaml.
+ * Resources reference those scopes by name.
+ */
+export type OwnedScopes = string[];
+
+/**
+ * OTEL resource attributes for a service/component
+ *
+ * Represents the actual resource attribute values (not match patterns).
+ * These are the attributes that would be set when instrumenting the service.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/
+ */
+export interface ResourceAttributes {
+  /** Service identification (required) */
+  'service.name': string;
+
+  /** Service version (recommended) */
+  'service.version'?: string;
+
+  /** Service namespace (optional) */
+  'service.namespace'?: string;
+
+  /** Service instance ID (optional) */
+  'service.instance.id'?: string;
+
+  /** Deployment environment (recommended) */
+  'deployment.environment'?: string;
+
+  /** Kubernetes namespace */
+  'k8s.namespace.name'?: string;
+
+  /** Kubernetes deployment name */
+  'k8s.deployment.name'?: string;
+
+  /** Kubernetes pod name */
+  'k8s.pod.name'?: string;
+
+  /** Kubernetes container name */
+  'k8s.container.name'?: string;
+
+  /** Kubernetes node name */
+  'k8s.node.name'?: string;
+
+  /** Database system */
+  'db.system'?: string;
+
+  /** Database name */
+  'db.name'?: string;
+
+  /** Host name */
+  'host.name'?: string;
+
+  /** Host ID */
+  'host.id'?: string;
+
+  /** Cloud provider */
+  'cloud.provider'?: string;
+
+  /** Cloud region */
+  'cloud.region'?: string;
+
+  /** Messaging system */
+  'messaging.system'?: string;
+
+  /** Messaging destination name */
+  'messaging.destination.name'?: string;
+
+  /**
+   * Instrumentation scopes owned by this service
+   *
+   * Lists the tracer/instrumentation scope names that belong to this service.
+   * Spans from these scopes will be matched against this service's storyboards
+   * rather than looking up external registries.
+   *
+   * Scope names must reference scopes defined in the top-level `scopes` section.
+   *
+   * @example
+   * ```yaml
+   * scopes:
+   *   auth-flow:
+   *     color: "#DC2626"
+   *     description: "Authentication flow instrumentation"
+   *
+   * resources:
+   *   auth-service:
+   *     service.name: "auth-service"
+   *     owned-scopes:
+   *       - "auth-flow"
+   * ```
+   */
+  'owned-scopes'?: OwnedScopes;
+
+  /** Allow arbitrary OTEL resource attributes */
+  [key: string]: string | string[] | undefined;
+}
+
+
+// ============================================================================
+// Component Library Root Type
+// ============================================================================
+
+/**
+ * Root type for a component library file (.yaml or .json).
+ *
+ * Example library.yaml:
+ * ```yaml
+ * version: "1.0.0"
+ * name: "My Service"
+ * description: "OTEL instrumentation configuration"
+ *
+ * resources:
+ *   auth-service:
+ *     service.name: "auth-service"
+ *     service.version: "1.0.0"
+ *     deployment.environment: "production"
+ *     owned-scopes:
+ *       - "auth-flow"
+ *
+ * eventSchemas:
+ *   user.login.success:
+ *     description: "User successfully logged in"
+ *     attributes:
+ *       user.id:
+ *         type: string
+ *         required: true
+ *       session.id:
+ *         type: string
+ *         required: true
+ * ```
+ *
+ * Note: Scope visual metadata (colors, icons) are now defined in .scopes.canvas files.
+ * The `owned-scopes` field in resources is used for telemetry routing only.
+ */
+export interface ComponentLibrary {
+  /** Library schema version */
+  version: string;
+
+  /** Library name */
+  name: string;
+
+  /** Library description */
+  description?: string;
+
+  /**
+   * Service resource registry
+   *
+   * Defines the services in this package and their expected OTEL resource attributes.
+   * Each service configures its own resources at runtime (via env vars or SDK),
+   * but declaring them here provides:
+   * - Service documentation/registry
+   * - Expected resource schema for validation
+   * - Dev instrumentation defaults
+   * - Canvas node generation
+   *
+   * The key is a service identifier (used for reference), and the value contains
+   * the OTEL resource attributes for that service.
+   *
+   * @example
+   * ```yaml
+   * resources:
+   *   payment-api:
+   *     service.name: "payment-api"
+   *     service.version: "1.0.0"
+   *     deployment.environment: "development"
+   *
+   *   payment-worker:
+   *     service.name: "payment-worker"
+   *     service.version: "1.0.0"
+   *     deployment.environment: "development"
+   * ```
+   */
+  resources?: Record<string, ResourceAttributes>;
+
+  /**
+   * Reusable event schema definitions
+   *
+   * Defines event schemas that can be referenced by canvas nodes via `pv.eventRef`.
+   * This promotes reusability and consistency across canvases.
+   *
+   * @example
+   * ```yaml
+   * eventSchemas:
+   *   auth.callback.started:
+   *     description: "Authentication callback initiated"
+   *     attributes:
+   *       session.id:
+   *         type: string
+   *         required: true
+   *         description: "Session identifier"
+   * ```
+   */
+  eventSchemas?: Record<string, Omit<PVEventSchema, 'name'>>;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Result of loading a component library
+ */
+export interface LibraryLoadResult {
+  /** Whether the library was loaded successfully */
+  success: boolean;
+
+  /** The loaded library (if successful) */
+  library?: ComponentLibrary;
+
+  /** Error message (if failed) */
+  error?: string;
+
+  /** Path the library was loaded from */
+  path: string;
+}
+
+/**
+ * Options for the library loader
+ */
+export interface LibraryLoaderOptions {
+  /** Base directory to search for library files */
+  baseDir?: string;
+
+  /** Custom library file name (default: "library.yaml" or "library.json") */
+  fileName?: string;
+}

package/src/types/otel.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  getAttributeStringValue,
+  findAttribute,
+  getAttributeValue,
+  flattenResourceAttributes,
+  parseNanoTime,
+  getSpanDuration,
+  isErrorSeverity,
+  isWarnSeverity,
+  type OtelAnyValue,
+  type OtelKeyValue,
+  type OtelResourceData,
+  type OtelSpanData,
+} from './otel';
+
+describe('OTEL Helper Functions', () => {
+  describe('getAttributeStringValue', () => {
+    it('should extract string value', () => {
+      const value: OtelAnyValue = { stringValue: 'test' };
+      expect(getAttributeStringValue(value)).toBe('test');
+    });
+
+    it('should return undefined for non-string values', () => {
+      expect(getAttributeStringValue({ intValue: 123 })).toBeUndefined();
+      expect(getAttributeStringValue({ boolValue: true })).toBeUndefined();
+      expect(getAttributeStringValue({})).toBeUndefined();
+    });
+  });
+
+  describe('findAttribute', () => {
+    const attributes: OtelKeyValue[] = [
+      { key: 'service.name', value: { stringValue: 'test-service' } },
+      { key: 'http.status_code', value: { intValue: 200 } },
+      { key: 'error', value: { boolValue: false } },
+    ];
+
+    it('should find attribute by key', () => {
+      const attr = findAttribute(attributes, 'service.name');
+      expect(attr).toBeDefined();
+      expect(attr?.key).toBe('service.name');
+      expect(attr?.value.stringValue).toBe('test-service');
+    });
+
+    it('should return undefined for missing key', () => {
+      expect(findAttribute(attributes, 'missing.key')).toBeUndefined();
+    });
+
+    it('should handle undefined attributes array', () => {
+      expect(findAttribute(undefined, 'any.key')).toBeUndefined();
+    });
+  });
+
+  describe('getAttributeValue', () => {
+    const attributes: OtelKeyValue[] = [
+      { key: 'http.method', value: { stringValue: 'GET' } },
+      { key: 'http.status_code', value: { intValue: 200 } },
+      { key: 'response.time', value: { doubleValue: 123.45 } },
+      { key: 'success', value: { boolValue: true } },
+    ];
+
+    it('should get string values', () => {
+      expect(getAttributeValue(attributes, 'http.method')).toBe('GET');
+    });
+
+    it('should get integer values', () => {
+      expect(getAttributeValue(attributes, 'http.status_code')).toBe(200);
+    });
+
+    it('should get double values', () => {
+      expect(getAttributeValue(attributes, 'response.time')).toBe(123.45);
+    });
+
+    it('should get boolean values', () => {
+      expect(getAttributeValue(attributes, 'success')).toBe(true);
+    });
+
+    it('should return undefined for missing keys', () => {
+      expect(getAttributeValue(attributes, 'missing')).toBeUndefined();
+    });
+
+    it('should handle undefined attributes array', () => {
+      expect(getAttributeValue(undefined, 'any.key')).toBeUndefined();
+    });
+  });
+
+  describe('flattenResourceAttributes', () => {
+    it('should flatten resource attributes to string map', () => {
+      const resource: OtelResourceData = {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'checkout-api' } },
+          { key: 'deployment.environment', value: { stringValue: 'production' } },
+          { key: 'service.version', value: { stringValue: '1.2.3' } },
+        ],
+      };
+
+      const flattened = flattenResourceAttributes(resource);
+
+      expect(flattened).toEqual({
+        'service.name': 'checkout-api',
+        'deployment.environment': 'production',
+        'service.version': '1.2.3',
+      });
+    });
+
+    it('should skip non-string attributes', () => {
+      const resource: OtelResourceData = {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'api' } },
+          { key: 'port', value: { intValue: 8080 } },
+          { key: 'enabled', value: { boolValue: true } },
+        ],
+      };
+
+      const flattened = flattenResourceAttributes(resource);
+
+      expect(flattened).toEqual({
+        'service.name': 'api',
+      });
+    });
+
+    it('should handle empty attributes', () => {
+      const resource: OtelResourceData = { attributes: [] };
+      expect(flattenResourceAttributes(resource)).toEqual({});
+    });
+  });
+
+  describe('parseNanoTime', () => {
+    it('should convert nanoseconds to milliseconds (string input)', () => {
+      expect(parseNanoTime('1737835200000000000')).toBe(1737835200000);
+      expect(parseNanoTime('1000000000')).toBe(1000);
+    });
+
+    it('should convert nanoseconds to milliseconds (number input)', () => {
+      expect(parseNanoTime(1737835200000000000)).toBe(1737835200000);
+      expect(parseNanoTime(1000000000)).toBe(1000);
+    });
+
+    it('should handle zero', () => {
+      expect(parseNanoTime('0')).toBe(0);
+      expect(parseNanoTime(0)).toBe(0);
+    });
+  });
+
+  describe('getSpanDuration', () => {
+    it('should calculate span duration in milliseconds', () => {
+      const span: OtelSpanData = {
+        traceId: 'abc123',
+        spanId: 'span1',
+        name: 'test',
+        kind: 2,
+        startTimeUnixNano: '1737835200000000000',
+        endTimeUnixNano: '1737835200150000000', // 150ms later
+        attributes: [],
+        events: [],
+        status: { code: 1 },
+      };
+
+      expect(getSpanDuration(span)).toBeCloseTo(150, 0);
+    });
+
+    it('should handle zero duration', () => {
+      const span: OtelSpanData = {
+        traceId: 'abc123',
+        spanId: 'span1',
+        name: 'test',
+        kind: 2,
+        startTimeUnixNano: '1737835200000000000',
+        endTimeUnixNano: '1737835200000000000',
+        attributes: [],
+        events: [],
+        status: { code: 1 },
+      };
+
+      expect(getSpanDuration(span)).toBe(0);
+    });
+  });
+
+  describe('isErrorSeverity', () => {
+    it('should detect ERROR severity text', () => {
+      expect(isErrorSeverity('ERROR')).toBe(true);
+      expect(isErrorSeverity('FATAL')).toBe(true);
+    });
+
+    it('should detect ERROR severity numbers', () => {
+      expect(isErrorSeverity(17)).toBe(true);
+      expect(isErrorSeverity(20)).toBe(true);
+      expect(isErrorSeverity(24)).toBe(true);
+    });
+
+    it('should not detect non-error severities', () => {
+      expect(isErrorSeverity('INFO')).toBe(false);
+      expect(isErrorSeverity('WARN')).toBe(false);
+      expect(isErrorSeverity('DEBUG')).toBe(false);
+      expect(isErrorSeverity(12)).toBe(false);
+      expect(isErrorSeverity(undefined)).toBe(false);
+    });
+  });
+
+  describe('isWarnSeverity', () => {
+    it('should detect WARN severity text', () => {
+      expect(isWarnSeverity('WARN')).toBe(true);
+    });
+
+    it('should detect WARN severity numbers', () => {
+      expect(isWarnSeverity(13)).toBe(true);
+      expect(isWarnSeverity(14)).toBe(true);
+      expect(isWarnSeverity(16)).toBe(true);
+    });
+
+    it('should not detect non-warn severities', () => {
+      expect(isWarnSeverity('INFO')).toBe(false);
+      expect(isWarnSeverity('ERROR')).toBe(false);
+      expect(isWarnSeverity(12)).toBe(false);
+      expect(isWarnSeverity(17)).toBe(false);
+      expect(isWarnSeverity(undefined)).toBe(false);
+    });
+  });
+});