@principal-ai/principal-view-core 0.5.6

package/src/ConfigurationLoader.ts

@@ -0,0 +1,185 @@
+/**
+ * Configuration loader for managing multiple graph configurations
+ *
+ * Supports loading configurations from the .vgc/ 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 .vgc/ folder
+ */
+export class ConfigurationLoader {
+  private static readonly CONFIG_DIR = '.vgc';
+
+  constructor(private fsAdapter: FileSystemAdapter) {}
+
+  /**
+   * Check if the .vgc/ configuration directory exists
+   *
+   * @param baseDir - Base directory to search from
+   * @returns True if .vgc/ directory exists
+   */
+  hasConfigDirectory(baseDir: string): boolean {
+    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
+    return this.fsAdapter.exists(configPath) && this.fsAdapter.isDirectory(configPath);
+  }
+
+  /**
+   * List all available configuration names in .vgc/ folder
+   *
+   * @param baseDir - Base directory containing .vgc/ folder
+   * @returns Array of configuration names (without extensions)
+   */
+  listConfigurations(baseDir: string): string[] {
+    if (!this.hasConfigDirectory(baseDir)) {
+      return [];
+    }
+
+    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
+    const files = 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 .vgc/ folder
+   * @returns Configuration file or null if not found/invalid
+   */
+  loadByName(name: string, baseDir: string): ConfigurationFile | null {
+    if (!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 (this.fsAdapter.exists(fullPath)) {
+        try {
+          const content = 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 .vgc/ folder
+   *
+   * @param baseDir - Base directory containing .vgc/ folder
+   * @returns Result containing all loaded configs and any errors
+   */
+  loadAll(baseDir: string): ConfigurationLoadResult {
+    const result: ConfigurationLoadResult = {
+      configs: [],
+      errors: [],
+    };
+
+    if (!this.hasConfigDirectory(baseDir)) {
+      result.errors.push({
+        file: '.vgc',
+        error: 'Configuration directory .vgc/ not found',
+      });
+      return result;
+    }
+
+    const configPath = this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
+    const files = 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 = 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 .vgc/ directory
+   */
+  getConfigDirectoryPath(baseDir: string): string {
+    return this.fsAdapter.join(baseDir, ConfigurationLoader.CONFIG_DIR);
+  }
+}

package/src/ConfigurationValidator.test.ts

@@ -0,0 +1,200 @@
+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

@@ -0,0 +1,283 @@
+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',
+      });
+    }
+
+    if (!config.metadata?.version) {
+      errors.push({
+        type: 'error',
+        message: 'Configuration must have a version',
+        path: 'metadata.version',
+      });
+    }
+
+    // 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');
+  }
+}