@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/ConfigurationLoader.ts

@@ -1,184 +0,0 @@
-/**
- * Configuration loader for managing multiple graph configurations
- *
- * Supports loading configurations from the .principal-views/ folder using the adapter pattern
- * for environment-agnostic file operations.
- */
-
-import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
-import type { PathBasedGraphConfiguration } from './types/path-based-config';
-import { parseYaml, isYamlFile, getConfigNameFromFilename } from './utils/YamlParser';
-
-/**
- * Represents a single configuration file
- */
-export interface ConfigurationFile {
-  /** Configuration name (filename without extension) */
-  name: string;
-  /** Full path to the configuration file */
-  path: string;
-  /** Parsed configuration data */
-  config: PathBasedGraphConfiguration;
-}
-
-/**
- * Result of loading all configurations
- */
-export interface ConfigurationLoadResult {
-  /** Successfully loaded configurations */
-  configs: ConfigurationFile[];
-  /** Errors encountered during loading */
-  errors: Array<{ file: string; error: string }>;
-}
-
-/**
- * Loader for managing multiple graph configurations from .principal-views/ folder
- */
-export class ConfigurationLoader {
-  private static readonly CONFIG_DIR = '.principal-views';
-
-  constructor(private fsAdapter: FileSystemAdapter) {}
-
-  /**
-   * Check if the .principal-views/ configuration directory exists
-   *
-   * @param baseDir - Base directory to search from
-   * @returns True if .principal-views/ directory exists
-   */
-  async hasConfigDirectory(baseDir: string): Promise<boolean> {
-    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
-    const exists = await this.fsAdapter.exists(configPath);
-    if (!exists) return false;
-    return await this.fsAdapter.isDirectory(configPath);
-  }
-
-  /**
-   * List all available configuration names in .principal-views/ folder
-   *
-   * @param baseDir - Base directory containing .principal-views/ folder
-   * @returns Array of configuration names (without extensions)
-   */
-  async listConfigurations(baseDir: string): Promise<string[]> {
-    if (!(await this.hasConfigDirectory(baseDir))) {
-      return [];
-    }
-
-    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
-    const files = await this.fsAdapter.readDir(configPath);
-
-    return files.filter(isYamlFile).map(getConfigNameFromFilename).sort();
-  }
-
-  /**
-   * Load a specific configuration by name
-   *
-   * @param name - Configuration name (without extension)
-   * @param baseDir - Base directory containing .principal-views/ folder
-   * @returns Configuration file or null if not found/invalid
-   */
-  async loadByName(name: string, baseDir: string): Promise<ConfigurationFile | null> {
-    if (!(await this.hasConfigDirectory(baseDir))) {
-      return null;
-    }
-
-    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
-
-    // Try both .yaml and .yml extensions
-    for (const ext of ['yaml', 'yml']) {
-      const filename = `${name}.${ext}`;
-      const fullPath = this.fsAdapter.join(configPath, filename);
-
-      if (await this.fsAdapter.exists(fullPath)) {
-        try {
-          const content = await this.fsAdapter.readFile(fullPath);
-          const parseResult = parseYaml(content, filename);
-
-          if (parseResult.success && parseResult.data) {
-            return {
-              name,
-              path: fullPath,
-              config: parseResult.data,
-            };
-          }
-        } catch (error) {
-          // File exists but couldn't be read or parsed
-          return null;
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Load all configurations from .principal-views/ folder
-   *
-   * @param baseDir - Base directory containing .principal-views/ folder
-   * @returns Result containing all loaded configs and any errors
-   */
-  async loadAll(baseDir: string): Promise<ConfigurationLoadResult> {
-    const result: ConfigurationLoadResult = {
-      configs: [],
-      errors: [],
-    };
-
-    if (!(await this.hasConfigDirectory(baseDir))) {
-      result.errors.push({
-        file: '.principal-views',
-        error: 'Configuration directory .principal-views/ not found',
-      });
-      return result;
-    }
-
-    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
-    const files = await this.fsAdapter.readDir(configPath);
-
-    for (const filename of files) {
-      if (!isYamlFile(filename)) {
-        continue; // Skip non-YAML files
-      }
-
-      const fullPath = this.fsAdapter.join(configPath, filename);
-      const name = getConfigNameFromFilename(filename);
-
-      try {
-        const content = await this.fsAdapter.readFile(fullPath);
-        const parseResult = parseYaml(content, filename);
-
-        if (parseResult.success && parseResult.data) {
-          result.configs.push({
-            name,
-            path: fullPath,
-            config: parseResult.data,
-          });
-        } else if (parseResult.error) {
-          result.errors.push({
-            file: filename,
-            error: parseResult.error,
-          });
-        }
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        result.errors.push({
-          file: filename,
-          error: `Failed to read file: ${errorMessage}`,
-        });
-      }
-    }
-
-    // Sort configs by name for consistent ordering
-    result.configs.sort((a, b) => a.name.localeCompare(b.name));
-
-    return result;
-  }
-
-  /**
-   * Get the configuration directory path
-   *
-   * @param baseDir - Base directory
-   * @returns Full path to .principal-views/ directory
-   */
-  getConfigDirectoryPath(baseDir: string): string {
-    return this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
-  }
-}

package/src/ConfigurationValidator.test.ts

@@ -1,200 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { ConfigurationValidator } from './ConfigurationValidator';
-import type { GraphConfiguration } from './types';
-
-describe('ConfigurationValidator', () => {
-  test('validates a correct configuration', () => {
-    const validConfig: GraphConfiguration = {
-      metadata: {
-        name: 'Test Graph',
-        version: '1.0.0',
-      },
-      nodeTypes: {
-        process: {
-          shape: 'rectangle',
-          color: '#4A90E2',
-          dataSchema: {
-            name: { type: 'string', required: true },
-          },
-        },
-      },
-      edgeTypes: {
-        dataflow: {
-          style: 'solid',
-          color: '#999',
-        },
-      },
-      allowedConnections: [
-        {
-          from: 'process',
-          to: 'process',
-          via: 'dataflow',
-        },
-      ],
-    };
-
-    const result = ConfigurationValidator.validate(validConfig);
-    expect(result.valid).toBe(true);
-    expect(result.errors).toHaveLength(0);
-  });
-
-  test('catches missing node type in connection rules', () => {
-    const invalidConfig: GraphConfiguration = {
-      metadata: {
-        name: 'Test Graph',
-        version: '1.0.0',
-      },
-      nodeTypes: {
-        process: {
-          shape: 'rectangle',
-          dataSchema: {},
-        },
-      },
-      edgeTypes: {
-        dataflow: {
-          style: 'solid',
-        },
-      },
-      allowedConnections: [
-        {
-          from: 'process',
-          to: 'nonexistent', // ❌ This doesn't exist
-          via: 'dataflow',
-        },
-      ],
-    };
-
-    const result = ConfigurationValidator.validate(invalidConfig);
-    expect(result.valid).toBe(false);
-    expect(result.errors.some((e) => e.message.includes('nonexistent'))).toBe(true);
-  });
-
-  test('catches missing edge type in connection rules', () => {
-    const invalidConfig: GraphConfiguration = {
-      metadata: {
-        name: 'Test Graph',
-        version: '1.0.0',
-      },
-      nodeTypes: {
-        process: {
-          shape: 'rectangle',
-          dataSchema: {},
-        },
-      },
-      edgeTypes: {
-        dataflow: {
-          style: 'solid',
-        },
-      },
-      allowedConnections: [
-        {
-          from: 'process',
-          to: 'process',
-          via: 'nonexistent_edge', // ❌ This doesn't exist
-        },
-      ],
-    };
-
-    const result = ConfigurationValidator.validate(invalidConfig);
-    expect(result.valid).toBe(false);
-    expect(result.errors.some((e) => e.message.includes('nonexistent_edge'))).toBe(true);
-  });
-
-  test('catches missing metadata', () => {
-    const invalidConfig = {
-      nodeTypes: {
-        process: { shape: 'rectangle', dataSchema: {} },
-      },
-      edgeTypes: {
-        dataflow: { style: 'solid' },
-      },
-      allowedConnections: [],
-    } as unknown as GraphConfiguration;
-
-    const result = ConfigurationValidator.validate(invalidConfig);
-    expect(result.valid).toBe(false);
-    expect(result.errors.some((e) => e.path.includes('metadata'))).toBe(true);
-  });
-
-  test('warns about undefined states in state transitions', () => {
-    const configWithBadStates: GraphConfiguration = {
-      metadata: {
-        name: 'Test Graph',
-        version: '1.0.0',
-      },
-      nodeTypes: {
-        order: {
-          shape: 'rectangle',
-          dataSchema: {},
-          states: {
-            pending: { color: '#FFA500' },
-            shipped: { color: '#00FF00' },
-          },
-        },
-      },
-      edgeTypes: {
-        flow: { style: 'solid' },
-      },
-      allowedConnections: [],
-      validation: {
-        stateTransitions: {
-          order: [
-            {
-              from: 'pending',
-              to: ['shipped', 'nonexistent'], // ❌ nonexistent state
-            },
-          ],
-        },
-      },
-    };
-
-    const result = ConfigurationValidator.validate(configWithBadStates);
-    expect(result.warnings.some((w) => w.message.includes('nonexistent'))).toBe(true);
-  });
-
-  test('validateOrThrow throws on invalid config', () => {
-    const invalidConfig: GraphConfiguration = {
-      metadata: {
-        name: 'Test',
-        version: '1.0.0',
-      },
-      nodeTypes: {}, // Empty!
-      edgeTypes: {
-        flow: { style: 'solid' },
-      },
-      allowedConnections: [],
-    };
-
-    expect(() => {
-      ConfigurationValidator.validateOrThrow(invalidConfig);
-    }).toThrow('Invalid GraphConfiguration');
-  });
-
-  test('formatReport creates readable output', () => {
-    const result = {
-      valid: false,
-      errors: [
-        {
-          type: 'error' as const,
-          message: 'Node type not found',
-          path: 'nodeTypes.missing',
-          suggestion: 'Add the node type definition',
-        },
-      ],
-      warnings: [
-        {
-          type: 'warning' as const,
-          message: 'No data schema',
-          path: 'nodeTypes.process.dataSchema',
-        },
-      ],
-    };
-
-    const report = ConfigurationValidator.formatReport(result);
-    expect(report).toContain('❌');
-    expect(report).toContain('Node type not found');
-    expect(report).toContain('⚠️');
-    expect(report).toContain('No data schema');
-    expect(report).toContain('💡');
-  });
-});

package/src/ConfigurationValidator.ts

@@ -1,273 +0,0 @@
-import type { GraphConfiguration } from './types';
-
-export interface ConfigurationValidationError {
-  type: 'error' | 'warning';
-  message: string;
-  path: string;
-  suggestion?: string;
-}
-
-export interface ConfigurationValidationResult {
-  valid: boolean;
-  errors: ConfigurationValidationError[];
-  warnings: ConfigurationValidationError[];
-}
-
-/**
- * Validates GraphConfiguration to catch issues early
- * Use this before creating EventProcessor or rendering graphs
- */
-export class ConfigurationValidator {
-  /**
-   * Validate a GraphConfiguration
-   */
-  static validate(config: GraphConfiguration): ConfigurationValidationResult {
-    const errors: ConfigurationValidationError[] = [];
-    const warnings: ConfigurationValidationError[] = [];
-
-    // Validate metadata
-    if (!config.metadata?.name) {
-      errors.push({
-        type: 'error',
-        message: 'Configuration must have a name',
-        path: 'metadata.name',
-      });
-    }
-
-    // Validate nodeTypes
-    if (!config.nodeTypes || Object.keys(config.nodeTypes).length === 0) {
-      errors.push({
-        type: 'error',
-        message: 'Configuration must define at least one node type',
-        path: 'nodeTypes',
-      });
-    } else {
-      // Validate each node type
-      for (const [typeName, nodeType] of Object.entries(config.nodeTypes)) {
-        if (!nodeType.shape) {
-          errors.push({
-            type: 'error',
-            message: `Node type '${typeName}' must have a shape`,
-            path: `nodeTypes.${typeName}.shape`,
-          });
-        }
-
-        if (!nodeType.dataSchema || Object.keys(nodeType.dataSchema).length === 0) {
-          warnings.push({
-            type: 'warning',
-            message: `Node type '${typeName}' has no data schema defined`,
-            path: `nodeTypes.${typeName}.dataSchema`,
-            suggestion: 'Consider defining data schema for better type safety',
-          });
-        }
-
-        // Validate states if defined
-        if (nodeType.states) {
-          for (const [stateName, state] of Object.entries(nodeType.states)) {
-            if (!state.label && !state.color && !state.icon) {
-              warnings.push({
-                type: 'warning',
-                message: `State '${stateName}' of node type '${typeName}' has no visual properties`,
-                path: `nodeTypes.${typeName}.states.${stateName}`,
-                suggestion: 'Add at least one of: label, color, or icon',
-              });
-            }
-          }
-        }
-      }
-    }
-
-    // Validate edgeTypes
-    if (!config.edgeTypes || Object.keys(config.edgeTypes).length === 0) {
-      errors.push({
-        type: 'error',
-        message: 'Configuration must define at least one edge type',
-        path: 'edgeTypes',
-      });
-    } else {
-      // Validate each edge type
-      for (const [typeName, edgeType] of Object.entries(config.edgeTypes)) {
-        if (!edgeType.style) {
-          errors.push({
-            type: 'error',
-            message: `Edge type '${typeName}' must have a style`,
-            path: `edgeTypes.${typeName}.style`,
-          });
-        }
-      }
-    }
-
-    // Validate allowedConnections
-    if (!config.allowedConnections || config.allowedConnections.length === 0) {
-      warnings.push({
-        type: 'warning',
-        message: 'No connection rules defined',
-        path: 'allowedConnections',
-        suggestion: 'Define connection rules to validate graph structure',
-      });
-    } else {
-      const nodeTypeNames = Object.keys(config.nodeTypes);
-      const edgeTypeNames = Object.keys(config.edgeTypes);
-
-      config.allowedConnections.forEach((rule, index) => {
-        // Check if 'from' node type exists
-        if (!nodeTypeNames.includes(rule.from)) {
-          errors.push({
-            type: 'error',
-            message: `Connection rule references undefined node type '${rule.from}'`,
-            path: `allowedConnections[${index}].from`,
-            suggestion: `Available node types: ${nodeTypeNames.join(', ')}`,
-          });
-        }
-
-        // Check if 'to' node type exists
-        if (!nodeTypeNames.includes(rule.to)) {
-          errors.push({
-            type: 'error',
-            message: `Connection rule references undefined node type '${rule.to}'`,
-            path: `allowedConnections[${index}].to`,
-            suggestion: `Available node types: ${nodeTypeNames.join(', ')}`,
-          });
-        }
-
-        // Check if 'via' edge type exists
-        if (!edgeTypeNames.includes(rule.via)) {
-          errors.push({
-            type: 'error',
-            message: `Connection rule references undefined edge type '${rule.via}'`,
-            path: `allowedConnections[${index}].via`,
-            suggestion: `Available edge types: ${edgeTypeNames.join(', ')}`,
-          });
-        }
-      });
-    }
-
-    // Validate validation rules if present
-    if (config.validation) {
-      // Validate state transitions
-      if (config.validation.stateTransitions) {
-        const nodeTypeNames = Object.keys(config.nodeTypes);
-
-        for (const [nodeType, transitions] of Object.entries(config.validation.stateTransitions)) {
-          if (!nodeTypeNames.includes(nodeType)) {
-            errors.push({
-              type: 'error',
-              message: `State transition rule references undefined node type '${nodeType}'`,
-              path: `validation.stateTransitions.${nodeType}`,
-              suggestion: `Available node types: ${nodeTypeNames.join(', ')}`,
-            });
-          } else {
-            // Check if states exist in node type definition
-            const nodeTypeDef = config.nodeTypes[nodeType];
-            const definedStates = nodeTypeDef.states ? Object.keys(nodeTypeDef.states) : [];
-
-            transitions.forEach((transition, index) => {
-              if (definedStates.length > 0 && !definedStates.includes(transition.from)) {
-                warnings.push({
-                  type: 'warning',
-                  message: `State transition references undefined state '${transition.from}' for node type '${nodeType}'`,
-                  path: `validation.stateTransitions.${nodeType}[${index}].from`,
-                  suggestion: `Defined states: ${definedStates.join(', ')}`,
-                });
-              }
-
-              transition.to.forEach((toState) => {
-                if (definedStates.length > 0 && !definedStates.includes(toState)) {
-                  warnings.push({
-                    type: 'warning',
-                    message: `State transition references undefined state '${toState}' for node type '${nodeType}'`,
-                    path: `validation.stateTransitions.${nodeType}[${index}].to`,
-                    suggestion: `Defined states: ${definedStates.join(', ')}`,
-                  });
-                }
-              });
-            });
-          }
-        }
-      }
-
-      // Validate cardinality rules
-      if (config.validation.cardinality) {
-        const nodeTypeNames = Object.keys(config.nodeTypes);
-
-        for (const nodeType of Object.keys(config.validation.cardinality)) {
-          if (!nodeTypeNames.includes(nodeType)) {
-            errors.push({
-              type: 'error',
-              message: `Cardinality rule references undefined node type '${nodeType}'`,
-              path: `validation.cardinality.${nodeType}`,
-              suggestion: `Available node types: ${nodeTypeNames.join(', ')}`,
-            });
-          }
-        }
-      }
-    }
-
-    return {
-      valid: errors.length === 0,
-      errors,
-      warnings,
-    };
-  }
-
-  /**
-   * Validate and throw if invalid
-   */
-  static validateOrThrow(config: GraphConfiguration): void {
-    const result = this.validate(config);
-
-    if (!result.valid) {
-      const errorMessages = result.errors.map(
-        (e) => `  - ${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`
-      );
-
-      throw new Error(
-        `Invalid GraphConfiguration:\n${errorMessages.join('\n')}\n\n` +
-          `Found ${result.errors.length} error(s) and ${result.warnings.length} warning(s)`
-      );
-    }
-
-    // Log warnings
-    if (result.warnings.length > 0) {
-      console.warn(`Configuration has ${result.warnings.length} warning(s):`);
-      result.warnings.forEach((w) => {
-        console.warn(`  - ${w.path}: ${w.message}${w.suggestion ? ` (${w.suggestion})` : ''}`);
-      });
-    }
-  }
-
-  /**
-   * Get a formatted report of validation results
-   */
-  static formatReport(result: ConfigurationValidationResult): string {
-    const lines: string[] = [];
-
-    if (result.valid) {
-      lines.push('✅ Configuration is valid');
-    } else {
-      lines.push(`❌ Configuration has ${result.errors.length} error(s)`);
-    }
-
-    if (result.errors.length > 0) {
-      lines.push('\nErrors:');
-      result.errors.forEach((e) => {
-        lines.push(`  ❌ ${e.path}: ${e.message}`);
-        if (e.suggestion) {
-          lines.push(`     💡 ${e.suggestion}`);
-        }
-      });
-    }
-
-    if (result.warnings.length > 0) {
-      lines.push(`\n⚠️  ${result.warnings.length} warning(s):`);
-      result.warnings.forEach((w) => {
-        lines.push(`  ⚠️  ${w.path}: ${w.message}`);
-        if (w.suggestion) {
-          lines.push(`     💡 ${w.suggestion}`);
-        }
-      });
-    }
-
-    return lines.join('\n');
-  }
-}