qa360 2.1.7 → 2.2.0

package/core/src/pack-v2/loader.ts

@@ -0,0 +1,358 @@
+/**
+ * QA360 Pack v2 Loader
+ *
+ * Loads and parses pack.yml v2 files from the filesystem.
+ * Supports environment variable substitution with ${VAR} and ${VAR:-default} syntax.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import * as yaml from 'js-yaml';
+import { PackConfigV2, PackValidationResultV2, ValidationError, PackMigrationResultV2 } from '../types/pack-v2.js';
+import { PackValidatorV2 } from './validator.js';
+import { PackMigrator } from './migrator.js';
+import { PackConfigV1 } from '../types/pack-v1.js';
+
+/**
+ * Substitute environment variables in a string
+ * Supports ${VAR} and ${VAR:-default} syntax
+ */
+function substituteEnvVars(str: string): string {
+  return str.replace(/\$\{([^}:]+)(:-([^}]*))?\}/g, (match, varName, _, defaultValue) => {
+    return process.env[varName] ?? defaultValue ?? match;
+  });
+}
+
+/**
+ * Recursively substitute environment variables in an object
+ */
+function substituteEnvVarsRecursive(obj: any): any {
+  if (typeof obj === 'string') {
+    return substituteEnvVars(obj);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(substituteEnvVarsRecursive);
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = substituteEnvVarsRecursive(value);
+    }
+    return result;
+  }
+  return obj;
+}
+
+export interface PackLoadResult {
+  success: boolean;
+  pack?: PackConfigV2 | any;  // Can be v1 or v2
+  validation?: PackValidationResultV2;
+  valid?: boolean;
+  error?: Error;
+  sourcePath?: string;
+  format?: 'v1' | 'v2' | 'unknown' | 'legacy';
+  migrated?: boolean;
+  changes?: string[];
+  warnings?: string[];
+  foundFiles?: string[];
+  missingFiles?: string[];
+  validationErrors?: ValidationError[];
+}
+
+export class PackLoaderV2 {
+  private cache = new Map<string, PackConfigV2>();
+
+  /**
+   * Load a pack configuration from a file path
+   */
+  async load(packPath: string, options?: {
+    validate?: boolean;
+    checkFilesExist?: boolean;
+    useCache?: boolean;
+    migrate?: boolean;
+  }): Promise<PackLoadResult> {
+    try {
+      // Resolve absolute path
+      const resolvedPath = resolve(packPath);
+
+      // Check if file exists
+      if (!existsSync(resolvedPath)) {
+        return {
+          success: false,
+          error: new Error(`Pack file not found: ${resolvedPath}`),
+          sourcePath: resolvedPath,
+          format: 'unknown'
+        };
+      }
+
+      // Read file
+      const content = readFileSync(resolvedPath, 'utf-8');
+
+      // Parse YAML
+      const parsed = yaml.load(content) as any;
+
+      // Substitute environment variables
+      const substituted = substituteEnvVarsRecursive(parsed);
+
+      // Detect version
+      const migrator = new PackMigrator();
+      const detectedVersion = migrator.detectVersion(substituted);
+
+      // Set format
+      const format: 'v1' | 'v2' | 'unknown' = detectedVersion === 1 ? 'v1' : detectedVersion === 2 ? 'v2' : 'unknown';
+
+      // For v1 without migration
+      if (detectedVersion === 1 && options?.migrate === false) {
+        return {
+          success: true,
+          pack: substituted,
+          format: 'v1',
+          migrated: false,
+          sourcePath: resolvedPath
+        };
+      }
+
+      let pack: PackConfigV2;
+      let migrated = false;
+      let changes: string[] = [];
+      let migrationWarnings: string[] = [];
+
+      if (detectedVersion === 1) {
+        // Check for legacy format before migrating
+        if (migrator.isLegacyFormat(substituted)) {
+          return {
+            success: false,
+            error: new Error(
+              `Legacy pack format detected (version ${substituted.version || '0.9.x'}). ` +
+              `This format is no longer supported.\n\n` +
+              `To fix this:\n` +
+              `  1. Delete the old pack file: ${resolvedPath}\n` +
+              `  2. Create a new pack: qa360 init\n` +
+              `  3. Or copy an example: qa360 examples copy api-basic`
+            ),
+            sourcePath: resolvedPath,
+            format: 'legacy'
+          };
+        }
+
+        // Migrate v1 to v2
+        const migrationResult = migrator.migrate(substituted as PackConfigV1) as unknown as PackMigrationResultV2;
+        if (!migrationResult.success) {
+          return {
+            success: false,
+            error: new Error(`Migration failed: ${migrationResult.warnings.join(', ')}`),
+            sourcePath: resolvedPath,
+            format: 'v1'
+          };
+        }
+
+        pack = migrationResult.migrated;
+        migrated = true;
+        changes = migrationResult.changes;
+        migrationWarnings = migrationResult.warnings;
+      } else if (detectedVersion === 2) {
+        pack = substituted as PackConfigV2;
+      } else {
+        // Check for legacy format and provide helpful error
+        if (migrator.isLegacyFormat(substituted)) {
+          return {
+            success: false,
+            error: new Error(
+              `Legacy pack format detected (version ${substituted.version || '0.9.x'}). ` +
+              `This format is no longer supported.\n\n` +
+              `To fix this:\n` +
+              `  1. Delete the old pack file: ${resolvedPath}\n` +
+              `  2. Create a new pack: qa360 init\n` +
+              `  3. Or copy an example: qa360 examples copy api-basic`
+            ),
+            sourcePath: resolvedPath,
+            format: 'legacy'
+          };
+        }
+
+        return {
+          success: false,
+          error: new Error(`Unknown pack format. Version: ${substituted.version}`),
+          sourcePath: resolvedPath,
+          format: 'unknown'
+        };
+      }
+
+      // Cache the pack
+      if (options?.useCache !== false) {
+        this.cache.set(resolvedPath, pack);
+      }
+
+      // Validate if requested (or by default)
+      const shouldValidate = options?.validate !== false;
+      if (shouldValidate) {
+        const validator = new PackValidatorV2(resolvedPath);
+        const validation = await validator.validate(pack, { checkFilesExist: options?.checkFilesExist });
+
+        return {
+          success: validation.valid,
+          pack,
+          valid: validation.valid,
+          validation,
+          validationErrors: validation.errors,
+          sourcePath: resolvedPath,
+          format: 'v2',
+          migrated,
+          changes,
+          warnings: migrationWarnings,
+          foundFiles: validation.info?.totalTests ? [`found ${validation.info.totalTests} tests`] : undefined
+        };
+      }
+
+      return {
+        success: true,
+        pack,
+        valid: true,
+        sourcePath: resolvedPath,
+        format: 'v2',
+        migrated,
+        changes,
+        warnings: migrationWarnings
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: error as Error,
+        sourcePath: packPath,
+        format: 'unknown'
+      };
+    }
+  }
+
+  /**
+   * Load and validate in one step
+   */
+  async loadAndValidate(packPath: string, options?: {
+    checkFilesExist?: boolean;
+  }): Promise<PackLoadResult> {
+    return this.load(packPath, {
+      validate: true,
+      checkFilesExist: options?.checkFilesExist,
+      useCache: false
+    });
+  }
+
+  /**
+   * Load multiple packs from a directory
+   */
+  async loadFromDir(dirPath: string, options?: {
+    pattern?: string;
+    validate?: boolean;
+    checkFilesExist?: boolean;
+  }): Promise<PackLoadResult[]> {
+    const { glob } = await import('glob');
+    const pattern = options?.pattern || '**/*.yml';
+    const results: PackLoadResult[] = [];
+
+    try {
+      const files = await glob(pattern, {
+        cwd: dirPath,
+        absolute: true,
+        ignore: ['**/node_modules/**']
+      });
+
+      for (const file of files) {
+        const result = await this.load(file, options);
+        results.push(result);
+      }
+
+      return results;
+    } catch (error) {
+      return [{
+        success: false,
+        error: new Error(`Failed to scan directory: ${(error as Error).message}`)
+      }];
+    }
+  }
+
+  /**
+   * Load from a YAML string (useful for testing or dynamic configs)
+   */
+  async loadFromString(yamlContent: string, options?: {
+    validate?: boolean;
+    filename?: string;
+  }): Promise<PackLoadResult> {
+    try {
+      const parsed = yaml.load(yamlContent) as any;
+
+      // Substitute environment variables
+      const substituted = substituteEnvVarsRecursive(parsed);
+
+      // Detect version and migrate if needed
+      const migrator = new PackMigrator();
+      const detectedVersion = migrator.detectVersion(substituted);
+
+      let pack: PackConfigV2;
+      let migrated = false;
+
+      if (detectedVersion === 1) {
+        const migrationResult = migrator.migrate(substituted as PackConfigV1) as unknown as PackMigrationResultV2;
+        if (!migrationResult.success) {
+          return {
+            success: false,
+            error: new Error(`Migration failed: ${migrationResult.warnings.join(', ')}`)
+          };
+        }
+        pack = migrationResult.migrated;
+        migrated = true;
+      } else if (detectedVersion === 2) {
+        pack = substituted as PackConfigV2;
+      } else {
+        return {
+          success: false,
+          error: new Error(`Unknown pack format. Version: ${substituted.version}`)
+        };
+      }
+
+      // Validate if requested
+      if (options?.validate !== false) {
+        const fakePath = options?.filename || 'pack.yml';
+        const validator = new PackValidatorV2(fakePath);
+        const validation = await validator.validate(pack);
+
+        return {
+          success: validation.valid,
+          pack,
+          validation,
+          migrated
+        };
+      }
+
+      return {
+        success: true,
+        pack,
+        migrated
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: new Error(`Failed to parse YAML: ${(error as Error).message}`)
+      };
+    }
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache(path?: string): void {
+    if (path) {
+      this.cache.delete(resolve(path));
+    } else {
+      this.cache.clear();
+    }
+  }
+
+  /**
+   * Get cache size
+   */
+  getCacheSize(): number {
+    return this.cache.size;
+  }
+}