@principal-ai/subsystems-core 0.29.0

package/dist/workflow/validator.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Workflow Template Validator
+ * Validates .workflow.json files against their corresponding .otel.canvas files
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { WorkflowTemplate } from './types';
+import type { ExtendedCanvas } from '../types/canvas';
+import type { EventRegistry } from '../registry/EventRegistry';
+export interface WorkflowValidationContext {
+    /** The workflow template being validated */
+    workflow: WorkflowTemplate;
+    /** Path to the workflow file */
+    workflowPath: string;
+    /** The canvas file (if found) */
+    canvas?: ExtendedCanvas;
+    /** Path to the canvas file */
+    canvasPath?: string;
+    /** Base path for resolving relative paths */
+    basePath: string;
+    /** Raw workflow content for line number lookup */
+    rawContent?: string;
+    /** Execution data for validating attribute references (optional) */
+    executionData?: {
+        /** Aggregated attributes available in templates */
+        aggregates: Record<string, unknown>;
+        /** Attributes grouped by event name */
+        eventAttributes: Map<string, Record<string, unknown>>;
+    };
+    /**
+     * Co-located execution files for validating template completeness.
+     * Array of paths to .otel.json files in the same directory as the workflow.
+     */
+    executionFiles?: string[];
+    /**
+     * Optional: Events used across all workflows that reference this canvas.
+     * When provided, coverage warnings are only emitted for canvas events
+     * that are NOT in this set (i.e., truly unused across all workflows).
+     * This enables multi-workflow canvas patterns where different workflows
+     * cover different subsets of canvas events.
+     */
+    allWorkflowEvents?: Set<string>;
+    /**
+     * Optional: Registry of all events across the project.
+     * When provided, enables enhanced error messages that show where
+     * missing events are defined (in library or other canvases).
+     */
+    eventRegistry?: EventRegistry;
+    /**
+     * Optional: List of owned instrumentation scopes from library.yaml.
+     * When provided, validates that workflow scope is in this list.
+     */
+    ownedScopes?: string[];
+}
+export interface WorkflowViolation {
+    /** Rule ID that detected this violation */
+    ruleId: string;
+    /** Severity level */
+    severity: 'error' | 'warn';
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line?: number;
+    /** JSON path to the problematic field */
+    path?: string;
+    /** Clear error message */
+    message: string;
+    /** Explanation of impact */
+    impact: string;
+    /** Suggestion for fixing */
+    suggestion?: string;
+    /** Whether this can be auto-fixed */
+    fixable: boolean;
+}
+export interface WorkflowValidationResult {
+    /** All violations found */
+    violations: WorkflowViolation[];
+    /** Count of errors */
+    errorCount: number;
+    /** Count of warnings */
+    warningCount: number;
+    /** Count of fixable violations */
+    fixableCount: number;
+}
+export declare class WorkflowValidator {
+    private fsAdapter;
+    constructor(fsAdapter: FileSystemAdapter);
+    /**
+     * Validate a workflow template
+     */
+    validate(context: WorkflowValidationContext): Promise<WorkflowValidationResult>;
+    /**
+     * Validate multiple workflows for duplicate spanPatterns
+     *
+     * This is a CLI-level validation that checks for conflicts across workflows.
+     * Call this method after validating individual workflows.
+     *
+     * @param workflows Array of workflow templates with their file paths
+     * @returns Array of violations for duplicate spanPatterns
+     */
+    static validateSpanPatterns(workflows: Array<{
+        workflow: WorkflowTemplate;
+        workflowPath: string;
+    }>): WorkflowViolation[];
+    /**
+     * Check schema validity (required fields, valid values)
+     */
+    private checkSchema;
+    /**
+     * Check that the referenced canvas file exists
+     */
+    private checkCanvasExists;
+    /**
+     * Check OTEL node labels are meaningful (not equal to their IDs).
+     * Labels should be human-readable display names, not technical identifiers.
+     */
+    private checkCanvasNodeLabels;
+    /**
+     * Convert a dot-separated ID to a human-readable label.
+     * E.g., "multi-canvas-panel.render" → "Multi Canvas Panel Render"
+     */
+    private idToHumanReadable;
+    /**
+     * Check if workflow references a canvas from a different storyboard folder.
+     * Workflows should be co-located with their canvas in the same storyboard.
+     */
+    private checkCanvasCrossReference;
+    /**
+     * Extract storyboard name from a path within .principal-views
+     * e.g., ".principal-views/task-management/task-workflow/file.json" -> "task-management"
+     * e.g., ".principal-views/cleanup-operations/cleanup-operations.otel.canvas" -> "cleanup-operations"
+     */
+    private extractStoryboardName;
+    /**
+     * Check for deprecated fields (condition, condition.requires, etc.)
+     */
+    private checkDeprecatedFields;
+    /**
+     * Check that events referenced in templates exist in the canvas
+     *
+     * Note: This is currently a placeholder as canvas files don't yet define event schemas.
+     * In the future, when canvas files include OTEL event schema definitions,
+     * this will validate event references.
+     */
+    private checkEventReferences;
+    /**
+     * Check that scenarios are well-formed
+     */
+    private checkScenarios;
+    /**
+     * Check for subset relationships between scenarios
+     *
+     * Ensures no scenario's event set is a strict subset of another scenario's event set.
+     * This prevents ambiguous matching where a trace could match multiple scenarios.
+     */
+    private checkScenarioSubsets;
+    /**
+     * Check if set A is a strict subset of set B
+     *
+     * A is a strict subset of B if:
+     * 1. All elements of A are in B
+     * 2. A has fewer elements than B
+     */
+    private isStrictSubset;
+    /**
+     * Check if two sets have identical elements
+     *
+     * Two sets are identical if they have the same size and all elements match.
+     */
+    private areIdenticalSets;
+    /**
+     * Generate helpful suggestion for fixing identical event sets
+     */
+    private generateIdenticalFixSuggestion;
+    /**
+     * Generate helpful suggestion for fixing subset relationship
+     */
+    private generateSubsetFixSuggestion;
+    /**
+     * Check that all events in a scenario come from nodes with the same scope
+     *
+     * This ensures scenarios don't accidentally span multiple instrumentation boundaries.
+     * Cross-scope workflows should be explicitly designed and documented.
+     */
+    private checkScenarioScopeConsistency;
+    /**
+     * Check that template uses valid fields (not legacy format)
+     */
+    private checkTemplateStructure;
+    /**
+     * Check that event names don't use attribute filter syntax
+     */
+    private checkEventNameSyntax;
+    /**
+     * Check template syntax (balanced braces, valid expressions)
+     */
+    private checkTemplateSyntax;
+    /**
+     * Validate a single template string
+     */
+    private validateTemplateString;
+    /**
+     * Check for conflicting attribute paths in templates
+     *
+     * Detects when one attribute path is a prefix of another, which causes
+     * rendering issues. For example:
+     * - `git.branch` (expects string value)
+     * - `git.branch.source` (expects git.branch to be an object)
+     *
+     * When both are used, the nested object conversion will clobber the string
+     * value, resulting in `[object Object]` being rendered.
+     */
+    private checkConflictingAttributePaths;
+    /**
+     * Check attribute references against execution data
+     *
+     * Validates that:
+     * - Attributes referenced in templates exist in execution data
+     * - Object attributes are accessed via properties (not used directly)
+     * - Attribute names are correct (catches typos)
+     */
+    private checkAttributeReferences;
+    /**
+     * Validate a list of attribute references against available data
+     *
+     * @param attributes - Attribute paths to validate
+     * @param aggregates - Global aggregate attributes
+     * @param eventAttributes - Event-specific attributes (if validating event template)
+     * @param file - File path for violation reporting
+     * @param path - JSON path for violation reporting
+     * @param eventName - Event name (if validating event template)
+     * @returns Array of violations found
+     */
+    private validateAttributes;
+    /**
+     * Check event attribute requirements:
+     * All attributes defined in event schemas must be used in at least one template.
+     *
+     * This ensures all defined attributes have a purpose and are displayed to users.
+     */
+    private checkEventAttributeRequirements;
+    /**
+     * Check that template attributes are defined in the canvas event schema.
+     *
+     * This validates the reverse of checkEventAttributeRequirements:
+     * - checkEventAttributeRequirements: schema defines attr not used in template → error
+     * - checkTemplateAttributesDefinedInSchema: template uses attr not in schema → error
+     *
+     * This catches cases where:
+     * - Template references {{context.projectRoot}} but schema doesn't define it
+     * - Typos in attribute names (e.g., {{contex.projectRoot}})
+     * - Attributes emitted by instrumentation but not documented in schema
+     */
+    private checkTemplateAttributesDefinedInSchema;
+    /**
+     * Check if all events in scenario templates are connected through canvas edges
+     */
+    private checkEventConnectivity;
+    /**
+     * Find nodes that are not connected to the main component
+     */
+    private findDisconnectedNodes;
+    /**
+     * Find similar attribute names for helpful suggestions
+     *
+     * Uses simple string similarity (Levenshtein-like) to find typos
+     *
+     * @param target - The attribute being searched for
+     * @param available - Available attribute names
+     * @returns Array of similar attribute names (max 3)
+     */
+    private findSimilarAttributes;
+    /**
+     * Check formatting options
+     */
+    private checkFormattingOptions;
+    /**
+     * Check execution data completeness
+     *
+     * Validates that co-located execution files contain the events and attributes
+     * that workflow templates reference.
+     */
+    private checkExecutionDataCompleteness;
+    /**
+     * Extract template variable references from a template string
+     * Matches {{variableName}} and {{@span.attributeName}} patterns
+     */
+    private extractTemplateVariables;
+    /**
+     * Check if execution data contains the template data needed
+     */
+    private executionHasTemplateData;
+    /**
+     * Find what specific data is missing from executions
+     */
+    private findMissingTemplateData;
+    /**
+     * Aggregate violations into result
+     */
+    private aggregateResults;
+    /**
+     * Check if a version string is valid semver
+     */
+    private isValidSemver;
+    /**
+     * Check if an event name matches any available event (supports globs)
+     */
+    private matchesEventPattern;
+    /**
+     * Extract base event name from event pattern
+     *
+     * Examples:
+     * - "installation.started" -> "installation.started"
+     * - "installation.progress[stage=skills_discovered]" -> "installation.progress"
+     * - "error.*[severity=high]" -> "error.*"
+     */
+    private extractBaseEventName;
+    /**
+     * Extract attribute value from event pattern for suggestion
+     *
+     * Examples:
+     * - "installation.progress[stage=skills_discovered]" -> "skills_discovered"
+     * - "error.*[severity=high]" -> "high"
+     * - "installation.started" -> ""
+     */
+    private extractAttributeValue;
+    /**
+     * Extract attribute references from Handlebars template
+     *
+     * Parses template strings like:
+     * - "{{source}}" -> ["source"]
+     * - "{{source.url}}" -> ["source.url"]
+     * - "{{#if options.global}}" -> ["options.global"]
+     * - "{{#if (eq install.mode 'symlink')}}" -> ["install.mode"]
+     *
+     * @param template - Handlebars template string
+     * @returns Array of attribute paths referenced in the template
+     */
+    private extractAttributeReferences;
+    /**
+     * Extract attribute references from a single Handlebars expression
+     *
+     * Handles:
+     * - Simple references: source.url
+     * - Helper calls: (eq install.mode 'symlink')
+     * - Nested expressions
+     *
+     * @param expression - The expression to parse
+     * @param attributes - Set to add found attributes to
+     */
+    private extractAttributesFromExpression;
+    /**
+     * Check if an attribute is an object type
+     *
+     * @param value - The attribute value to check
+     * @returns true if value is a plain object (not array, not null)
+     */
+    private isObjectType;
+}
+/**
+ * Create a validator instance
+ */
+export declare function createWorkflowValidator(fsAdapter: FileSystemAdapter): WorkflowValidator;
+//# sourceMappingURL=validator.d.ts.map

package/dist/workflow/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/workflow/validator.ts"],"names":[],"mappings":"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"}