@principal-ai/subsystems-core 0.29.0

package/src/utils/traceAggregation.ts

@@ -0,0 +1,173 @@
+/**
+ * Trace Aggregation Utilities
+ *
+ * Functions for converting OTLP ResourceSpans to aggregated TraceInfo objects.
+ * This provides a higher-level view of traces suitable for UI display and filtering.
+ */
+
+import type {
+  OtelResourceSpansData,
+  OtelSpanData,
+  OtelResourceData,
+  TraceInfo,
+  WorkflowMatchInfo,
+} from '../types/otel';
+import {
+  getAttributeValue,
+  parseNanoTime,
+} from '../types/otel';
+
+/**
+ * Group spans by trace ID and aggregate metadata
+ *
+ * Converts OTLP ResourceSpans format into TraceInfo objects for easier
+ * consumption by UI components. Each trace gets aggregated metadata including
+ * duration, error status, and workflow matching information.
+ *
+ * @param resourceSpans - OTLP resource spans array
+ * @returns Array of aggregated trace info objects
+ *
+ * @example
+ * ```typescript
+ * const traces = groupSpansByTrace(data.resourceSpans);
+ * console.log(`Found ${traces.length} traces`);
+ * ```
+ */
+export function groupSpansByTrace(resourceSpans: OtelResourceSpansData[]): TraceInfo[] {
+  // Group spans by trace ID
+  const traceMap = new Map<string, {
+    spans: OtelSpanData[];
+    resources: OtelResourceData[];
+  }>();
+
+  for (const resourceSpan of resourceSpans) {
+    const resource = resourceSpan.resource;
+
+    for (const scopeSpan of resourceSpan.scopeSpans) {
+      for (const span of scopeSpan.spans) {
+        const traceId = span.traceId;
+
+        if (!traceMap.has(traceId)) {
+          traceMap.set(traceId, {
+            spans: [],
+            resources: [],
+          });
+        }
+
+        const trace = traceMap.get(traceId)!;
+        trace.spans.push(span);
+
+        // Collect unique resources
+        if (!trace.resources.includes(resource)) {
+          trace.resources.push(resource);
+        }
+      }
+    }
+  }
+
+  // Convert to TraceInfo objects
+  const traces: TraceInfo[] = [];
+
+  for (const [traceId, { spans, resources }] of traceMap.entries()) {
+    const traceInfo = aggregateTraceInfo(traceId, spans, resources);
+    traces.push(traceInfo);
+  }
+
+  // Sort by start time (newest first)
+  traces.sort((a, b) => b.startTime - a.startTime);
+
+  return traces;
+}
+
+/**
+ * Aggregate trace metadata from spans and resources
+ *
+ * @param traceId - Trace ID
+ * @param spans - All spans in the trace
+ * @param resources - All resources associated with the trace
+ * @returns Aggregated trace info
+ */
+function aggregateTraceInfo(
+  traceId: string,
+  spans: OtelSpanData[],
+  resources: OtelResourceData[]
+): TraceInfo {
+  // Find root span (no parent)
+  const rootSpan = spans.find((s) => !s.parentSpanId);
+
+  // Calculate trace start time (earliest span)
+  const startTimes = spans.map((s) => parseNanoTime(s.startTimeUnixNano));
+  const startTime = Math.min(...startTimes);
+
+  // Calculate trace end time (latest span)
+  const endTimes = spans.map((s) => parseNanoTime(s.endTimeUnixNano));
+  const endTime = Math.max(...endTimes);
+
+  // Calculate duration
+  const duration = endTime - startTime;
+
+  // Extract service names from resources
+  const serviceNames = new Set<string>();
+  for (const resource of resources) {
+    const serviceName = getAttributeValue(resource.attributes, 'service.name');
+    if (serviceName && typeof serviceName === 'string') {
+      serviceNames.add(serviceName);
+    }
+  }
+
+  // Check for errors
+  const hasErrors = spans.some((span) => {
+    return span.status.code === 2; // ERROR = 2 in status codes
+  });
+
+  // Extract workflow matching info from first resource
+  const matchedWorkflow = extractWorkflowMatchInfo(resources[0]);
+
+  return {
+    traceId,
+    name: rootSpan?.name ?? spans[0]?.name ?? 'Unknown',
+    startTime,
+    duration,
+    spanCount: spans.length,
+    serviceNames: Array.from(serviceNames),
+    hasErrors,
+    rootSpanId: rootSpan?.spanId,
+    matchedWorkflow,
+  };
+}
+
+/**
+ * Extract workflow matching metadata from resource attributes
+ *
+ * Looks for Principal View specific attributes like:
+ * - pv.storyboard.id
+ * - pv.storyboard.name
+ * - pv.workflow.id
+ * - pv.scenario.id
+ *
+ * @param resource - OTEL resource
+ * @returns Workflow match info if found, undefined otherwise
+ */
+function extractWorkflowMatchInfo(resource: OtelResourceData): WorkflowMatchInfo | undefined {
+  if (!resource?.attributes) return undefined;
+
+  const storyboardId = getAttributeValue(resource.attributes, 'pv.storyboard.id');
+  const storyboardName = getAttributeValue(resource.attributes, 'pv.storyboard.name');
+
+  if (!storyboardId || typeof storyboardId !== 'string') return undefined;
+  if (!storyboardName || typeof storyboardName !== 'string') return undefined;
+
+  const workflowId = getAttributeValue(resource.attributes, 'pv.workflow.id');
+  const workflowName = getAttributeValue(resource.attributes, 'pv.workflow.name');
+  const scenarioId = getAttributeValue(resource.attributes, 'pv.scenario.id');
+  const scenarioName = getAttributeValue(resource.attributes, 'pv.scenario.name');
+
+  return {
+    storyboardId,
+    storyboardName,
+    workflowId: typeof workflowId === 'string' ? workflowId : undefined,
+    workflowName: typeof workflowName === 'string' ? workflowName : undefined,
+    scenarioId: typeof scenarioId === 'string' ? scenarioId : undefined,
+    scenarioName: typeof scenarioName === 'string' ? scenarioName : undefined,
+  };
+}

package/src/validation/OtelCanvasValidator.ts

@@ -0,0 +1,86 @@
+/**
+ * OTEL Canvas Validator
+ *
+ * Validates that OTEL canvas files do not use explicit fill/color fields on event nodes.
+ * OTEL event nodes must use scope-based coloring exclusively for consistency.
+ */
+
+import type { ExtendedCanvas } from '../types/canvas';
+import { isOtelEventNode } from '../types/canvas';
+
+/**
+ * OTEL canvas validation violation
+ */
+export interface OtelCanvasViolation {
+  /** Rule ID that detected this violation */
+  ruleId: string;
+
+  /** Severity level */
+  severity: 'error' | 'warn';
+
+  /** File path where violation occurred */
+  file: string;
+
+  /** JSON path within file (optional) */
+  path?: string;
+
+  /** Human-readable description of what's wrong */
+  message: string;
+
+  /** Why this matters */
+  impact: string;
+
+  /** How to fix it */
+  suggestion: string;
+}
+
+/**
+ * Validates OTEL canvas files
+ */
+export class OtelCanvasValidator {
+  /**
+   * Validate an OTEL canvas for explicit color usage on event nodes
+   *
+   * @param canvas - The canvas to validate
+   * @param canvasPath - Path to the canvas file (for error reporting)
+   * @returns Array of violations found
+   */
+  validate(canvas: ExtendedCanvas, canvasPath: string): OtelCanvasViolation[] {
+    const violations: OtelCanvasViolation[] = [];
+
+    // Check all nodes in the canvas - only validate otel-event nodes
+    for (const node of canvas.nodes || []) {
+      if (isOtelEventNode(node)) {
+        // Check for deprecated fill field
+        if (node.fill !== undefined) {
+          const scopeHint = node.otel?.scope || 'your-scope';
+          violations.push({
+            ruleId: 'otel-event-explicit-fill-color',
+            severity: 'error',
+            file: canvasPath,
+            path: `nodes[id="${node.id}"].fill`,
+            message: `OTEL event node "${node.id}" has explicit fill color which is not allowed`,
+            impact: 'OTEL event nodes must use scope-based coloring for consistency. Explicit colors defeat this purpose.',
+            suggestion: `Remove the "fill" field and set the color on the otel-scope node for "${scopeHint}" in your .scopes.canvas file`,
+          });
+        }
+
+        // Check for deprecated color field
+        if (node.color !== undefined) {
+          const scopeHint = node.otel?.scope || 'your-scope';
+          violations.push({
+            ruleId: 'otel-event-explicit-color',
+            severity: 'error',
+            file: canvasPath,
+            path: `nodes[id="${node.id}"].color`,
+            message: `OTEL event node "${node.id}" has explicit color which is not allowed`,
+            impact: 'OTEL event nodes must use scope-based coloring for consistency. Explicit colors defeat this purpose.',
+            suggestion: `Remove the "color" field and set the color on the otel-scope node for "${scopeHint}" in your .scopes.canvas file`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Validation Module
+ *
+ * Exports validation functions for various Principal View data structures.
+ */
+
+export {
+  validateLibraryStructure,
+  type LibraryValidationError,
+  type LibraryValidationErrorType,
+  type LibraryValidationResult,
+} from './libraryValidation';
+
+export {
+  OtelCanvasValidator,
+  type OtelCanvasViolation,
+} from './OtelCanvasValidator';

package/src/validation/libraryValidation.ts

@@ -0,0 +1,206 @@
+/**
+ * Library Validation
+ *
+ * Standalone validation functions for ComponentLibrary schema.
+ * Used by both LibraryLoader (core), LibraryDiscovery, and CLI validation.
+ */
+
+import type { ComponentLibrary } from '../types/library';
+
+/**
+ * Types of library validation errors
+ */
+export type LibraryValidationErrorType =
+  | 'parse-error'
+  | 'validation-error'
+  | 'schema-error'
+  | 'scopes-canvas-required';
+
+/**
+ * A library validation error
+ *
+ * Unified type used across LibraryLoader, LibraryDiscovery, and CLI validation.
+ */
+export interface LibraryValidationError {
+  /** Error message */
+  message: string;
+  /** Path to the invalid field or file */
+  path: string;
+  /** Error category */
+  type?: LibraryValidationErrorType;
+  /** Optional suggestion for fixing the error */
+  suggestion?: string;
+}
+
+/**
+ * Result of library structure validation
+ */
+export interface LibraryValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** List of validation errors (empty if valid) */
+  errors: LibraryValidationError[];
+}
+
+/** Helper to create a schema error */
+function schemaError(message: string, path: string, suggestion?: string): LibraryValidationError {
+  return { message, path, type: 'schema-error', suggestion };
+}
+
+/**
+ * Validate a ComponentLibrary structure
+ *
+ * This validates the core schema requirements:
+ * - Required fields (version, name, nodeComponents, edgeComponents)
+ * - Event schemas structure
+ * - Top-level scopes (color required unless external)
+ * - Resources structure and owned-scopes references
+ * - Connection rules references
+ *
+ * Note: This does NOT validate unknown fields or icon names.
+ * The CLI adds those supplementary validations.
+ *
+ * @param library - The library object to validate
+ * @returns Validation result with any errors
+ */
+export function validateLibraryStructure(library: ComponentLibrary): LibraryValidationResult {
+  const errors: LibraryValidationError[] = [];
+
+  // Required fields
+  if (!library.version) {
+    errors.push(schemaError(
+      'Missing required field "version"',
+      'version',
+      'Add: version: "1.0.0"'
+    ));
+  }
+
+  if (!library.name) {
+    errors.push(schemaError(
+      'Missing required field "name"',
+      'name',
+      'Add: name: "my-library"'
+    ));
+  }
+
+  // Validate event schemas if present
+  if (library.eventSchemas !== undefined) {
+    if (typeof library.eventSchemas !== 'object' || library.eventSchemas === null) {
+      errors.push(schemaError(
+        'Field "eventSchemas" must be an object',
+        'eventSchemas',
+        'Use: eventSchemas: { "my-event": { description: "...", attributes: {} } }'
+      ));
+    } else {
+      for (const [eventName, schema] of Object.entries(library.eventSchemas)) {
+        if (!schema.description) {
+          errors.push(schemaError(
+            `Event schema "${eventName}" is missing required field "description"`,
+            `eventSchemas.${eventName}.description`,
+            'Add a description for this event schema'
+          ));
+        }
+
+        if (!schema.attributes || typeof schema.attributes !== 'object') {
+          errors.push(schemaError(
+            `Event schema "${eventName}" is missing or has invalid "attributes" field`,
+            `eventSchemas.${eventName}.attributes`,
+            'Add: attributes: {} (can be empty but must be present)'
+          ));
+        } else {
+          // Validate each attribute
+          const validTypes = ['string', 'number', 'boolean', 'object', 'array'];
+          for (const [attrName, attrSchema] of Object.entries(schema.attributes)) {
+            if (!attrSchema.type) {
+              errors.push(schemaError(
+                `Event schema "${eventName}" attribute "${attrName}" is missing required field "type"`,
+                `eventSchemas.${eventName}.attributes.${attrName}.type`,
+                `Add type: one of ${validTypes.join(', ')}`
+              ));
+            } else if (!validTypes.includes(attrSchema.type)) {
+              errors.push(schemaError(
+                `Event schema "${eventName}" attribute "${attrName}" has invalid type "${attrSchema.type}"`,
+                `eventSchemas.${eventName}.attributes.${attrName}.type`,
+                `Valid types: ${validTypes.join(', ')}`
+              ));
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Note: scopes validation removed - scopes field is deprecated
+  // The CLI validate.ts will show an error if library.scopes is present
+
+  // Validate resources if present
+  if (library.resources !== undefined) {
+    if (typeof library.resources !== 'object' || library.resources === null || Array.isArray(library.resources)) {
+      errors.push(schemaError(
+        'Field "resources" must be an object',
+        'resources',
+        'Use: resources: { my-service: { "service.name": "my-service", ... } }'
+      ));
+    } else {
+      for (const [serviceId, resourceAttrs] of Object.entries(library.resources)) {
+        if (typeof resourceAttrs !== 'object' || Array.isArray(resourceAttrs) || resourceAttrs === null) {
+          errors.push(schemaError(
+            `Resource "${serviceId}" must be an object`,
+            `resources.${serviceId}`,
+            'Use: { "service.name": "...", "owned-scopes": [...] }'
+          ));
+          continue;
+        }
+
+        // Check that service.name is present (required)
+        if (!resourceAttrs['service.name']) {
+          errors.push(schemaError(
+            `Resource "${serviceId}" is missing required attribute "service.name"`,
+            `resources.${serviceId}`,
+            'Add: "service.name": "my-service-name"'
+          ));
+        }
+
+        // Validate owned-scopes
+        const ownedScopes = resourceAttrs['owned-scopes'];
+        if (ownedScopes !== undefined) {
+          if (!Array.isArray(ownedScopes)) {
+            errors.push(schemaError(
+              `Resource "${serviceId}" owned-scopes must be an array`,
+              `resources.${serviceId}.owned-scopes`,
+              'Use: owned-scopes: ["scope-name-1", "scope-name-2"]'
+            ));
+          } else {
+            for (const scope of ownedScopes) {
+              if (typeof scope !== 'string') {
+                errors.push(schemaError(
+                  `Resource "${serviceId}" owned-scopes contains non-string value`,
+                  `resources.${serviceId}.owned-scopes`,
+                  'All owned-scopes entries must be strings'
+                ));
+              }
+              // Note: Scope existence validation removed - scopes are now defined in .scopes.canvas
+              // The CLI will validate that owned-scopes exist in .scopes.canvas
+            }
+          }
+        }
+
+        // Validate other attributes are strings (except owned-scopes)
+        for (const [attrName, attrValue] of Object.entries(resourceAttrs)) {
+          if (attrName !== 'owned-scopes' && typeof attrValue !== 'string') {
+            errors.push(schemaError(
+              `Resource "${serviceId}" attribute "${attrName}" must have a string value`,
+              `resources.${serviceId}.${attrName}`,
+              'Resource attributes (except owned-scopes) must be strings'
+            ));
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}