@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/dist/workflow/validator.d.ts

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

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