@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/utils/traceAggregation.ts

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

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

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

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