aios-core 1.0.0

package/.aios-core/development/scripts/squad/squad-validator.js

@@ -0,0 +1,783 @@
+/**
+ * Squad Validator Utility
+ *
+ * Validates squads against:
+ * 1. JSON Schema (squad.yaml/config.yaml)
+ * 2. Directory structure (task-first architecture)
+ * 3. Task format (TASK-FORMAT-SPECIFICATION-V1)
+ * 4. Agent definitions
+ *
+ * Used by: squad-creator agent (*validate-squad task)
+ *
+ * @module squad-validator
+ * @version 1.0.0
+ * @see Story SQS-3: Squad Validator + JSON Schema
+ */
+
+const Ajv = require('ajv');
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Load schema - handle both require and dynamic loading
+ * @returns {Object} JSON Schema
+ */
+function loadSchema() {
+  try {
+    return require('../../../schemas/squad-schema.json');
+  } catch {
+    // Fallback for test environments
+    return null;
+  }
+}
+
+/**
+ * Supported manifest file names in order of preference
+ * @constant {string[]}
+ */
+const MANIFEST_FILES = ['squad.yaml', 'config.yaml'];
+
+/**
+ * Required fields in tasks (TASK-FORMAT-SPECIFICATION-V1)
+ * @constant {string[]}
+ */
+const TASK_REQUIRED_FIELDS = [
+  'task',
+  'responsavel',
+  'responsavel_type',
+  'atomic_layer',
+  'Entrada',
+  'Saida',
+  'Checklist',
+];
+
+/**
+ * Error codes for SquadValidatorError
+ * @enum {string}
+ */
+const ValidationErrorCodes = {
+  MANIFEST_NOT_FOUND: 'MANIFEST_NOT_FOUND',
+  YAML_PARSE_ERROR: 'YAML_PARSE_ERROR',
+  SCHEMA_ERROR: 'SCHEMA_ERROR',
+  DEPRECATED_MANIFEST: 'DEPRECATED_MANIFEST',
+  MISSING_DIRECTORY: 'MISSING_DIRECTORY',
+  NO_TASKS: 'NO_TASKS',
+  TASK_MISSING_FIELD: 'TASK_MISSING_FIELD',
+  TASK_READ_ERROR: 'TASK_READ_ERROR',
+  AGENT_INVALID_FORMAT: 'AGENT_INVALID_FORMAT',
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  INVALID_NAMING: 'INVALID_NAMING',
+};
+
+/**
+ * Validation result structure
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether validation passed (no errors)
+ * @property {Array<ValidationError>} errors - Critical errors that fail validation
+ * @property {Array<ValidationWarning>} warnings - Non-critical issues
+ * @property {Array<string>} suggestions - Helpful suggestions
+ */
+
+/**
+ * Validation error structure
+ * @typedef {Object} ValidationError
+ * @property {string} code - Error code from ValidationErrorCodes
+ * @property {string} message - Human-readable error message
+ * @property {string} [suggestion] - Suggested fix
+ * @property {string} [path] - JSON path where error occurred
+ * @property {string} [file] - File where error occurred
+ */
+
+/**
+ * Squad Validator class for validating squad structure and content
+ */
+class SquadValidator {
+  /**
+   * Create a SquadValidator instance
+   * @param {Object} [options={}] - Configuration options
+   * @param {boolean} [options.verbose=false] - Enable verbose logging
+   * @param {boolean} [options.strict=false] - Treat warnings as errors
+   * @param {Object} [options.schema] - Custom schema (for testing)
+   */
+  constructor(options = {}) {
+    this.verbose = options.verbose || false;
+    this.strict = options.strict || false;
+
+    // Initialize AJV with schema
+    this.ajv = new Ajv({ allErrors: true, verbose: true });
+    const schema = options.schema || loadSchema();
+    if (schema) {
+      this.validateSchema = this.ajv.compile(schema);
+    } else {
+      this.validateSchema = null;
+    }
+  }
+
+  /**
+   * Log message if verbose mode is enabled
+   * @private
+   * @param {string} message - Message to log
+   */
+  _log(message) {
+    if (this.verbose) {
+      console.log(`[SquadValidator] ${message}`);
+    }
+  }
+
+  /**
+   * Validate entire squad
+   *
+   * Runs all validation checks:
+   * 1. Manifest validation (schema)
+   * 2. Directory structure
+   * 3. Task format
+   * 4. Agent definitions
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result
+   *
+   * @example
+   * const validator = new SquadValidator();
+   * const result = await validator.validate('./squads/my-squad');
+   * if (result.valid) {
+   *   console.log('Squad is valid!');
+   * } else {
+   *   console.log('Errors:', result.errors);
+   * }
+   */
+  async validate(squadPath) {
+    this._log(`Validating squad: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // 1. Validate manifest
+    const manifestResult = await this.validateManifest(squadPath);
+    this._mergeResults(result, manifestResult);
+
+    // 2. Validate directory structure
+    const structureResult = await this.validateStructure(squadPath);
+    this._mergeResults(result, structureResult);
+
+    // 3. Validate tasks (task-first!)
+    const tasksResult = await this.validateTasks(squadPath);
+    this._mergeResults(result, tasksResult);
+
+    // 4. Validate agents
+    const agentsResult = await this.validateAgents(squadPath);
+    this._mergeResults(result, agentsResult);
+
+    // 5. Validate config references (SQS-10)
+    const configResult = await this.validateConfigReferences(squadPath);
+    this._mergeResults(result, configResult);
+
+    // In strict mode, warnings become errors
+    if (this.strict && result.warnings.length > 0) {
+      result.errors.push(...result.warnings);
+      result.warnings = [];
+      result.valid = false;
+    }
+
+    this._log(`Validation complete: ${result.valid ? 'VALID' : 'INVALID'}`);
+    return result;
+  }
+
+  /**
+   * Validate manifest against JSON Schema
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for manifest
+   */
+  async validateManifest(squadPath) {
+    this._log(`Validating manifest in: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // Find manifest file
+    const manifestPath = await this._findManifest(squadPath);
+    if (!manifestPath) {
+      result.valid = false;
+      result.errors.push({
+        code: ValidationErrorCodes.MANIFEST_NOT_FOUND,
+        message: `No manifest found in ${squadPath}/ (expected squad.yaml or config.yaml)`,
+        suggestion: 'Create squad.yaml with required fields: name, version',
+      });
+      return result;
+    }
+
+    // Deprecation warning for config.yaml
+    const manifestFilename = path.basename(manifestPath);
+    if (manifestFilename === 'config.yaml') {
+      result.warnings.push({
+        code: ValidationErrorCodes.DEPRECATED_MANIFEST,
+        message: 'config.yaml is deprecated, rename to squad.yaml',
+        suggestion: 'mv config.yaml squad.yaml',
+        file: manifestFilename,
+      });
+    }
+
+    // Parse YAML
+    let manifest;
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8');
+      manifest = yaml.load(content);
+    } catch (error) {
+      result.valid = false;
+      result.errors.push({
+        code: ValidationErrorCodes.YAML_PARSE_ERROR,
+        message: `Failed to parse manifest: ${error.message}`,
+        suggestion: 'Check YAML syntax - use a YAML linter',
+        file: manifestFilename,
+      });
+      return result;
+    }
+
+    // Validate against schema
+    if (this.validateSchema && manifest) {
+      const schemaValid = this.validateSchema(manifest);
+      if (!schemaValid) {
+        result.valid = false;
+        for (const err of this.validateSchema.errors) {
+          result.errors.push({
+            code: ValidationErrorCodes.SCHEMA_ERROR,
+            path: err.instancePath || '/',
+            message: err.message,
+            suggestion: this._getSchemaSuggestion(err),
+          });
+        }
+      }
+    }
+
+    this._log(`Manifest validation: ${result.valid ? 'PASS' : 'FAIL'}`);
+    return result;
+  }
+
+  /**
+   * Validate directory structure
+   *
+   * Checks for expected directories in task-first architecture.
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for structure
+   */
+  async validateStructure(squadPath) {
+    this._log(`Validating structure of: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // Expected directories (task-first: tasks and agents are primary)
+    const expectedDirs = ['tasks', 'agents'];
+    const optionalDirs = [
+      'workflows',
+      'checklists',
+      'templates',
+      'tools',
+      'scripts',
+      'data',
+      'config',
+    ];
+
+    // Check expected directories (warn if missing)
+    for (const dir of expectedDirs) {
+      const dirPath = path.join(squadPath, dir);
+      if (!(await this._pathExists(dirPath))) {
+        result.warnings.push({
+          code: ValidationErrorCodes.MISSING_DIRECTORY,
+          message: `Expected directory not found: ${dir}/`,
+          suggestion: `mkdir ${dir} (task-first architecture recommends tasks/ and agents/)`,
+        });
+      }
+    }
+
+    // Validate files referenced in manifest exist
+    const manifestPath = await this._findManifest(squadPath);
+    if (manifestPath) {
+      try {
+        const content = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = yaml.load(content);
+
+        if (manifest && manifest.components) {
+          await this._validateReferencedFiles(
+            squadPath,
+            manifest.components,
+            result,
+          );
+        }
+      } catch {
+        // Already handled in manifest validation
+      }
+    }
+
+    this._log(`Structure validation: ${result.errors.length} errors, ${result.warnings.length} warnings`);
+    return result;
+  }
+
+  /**
+   * Validate task files against TASK-FORMAT-SPECIFICATION-V1
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for tasks
+   */
+  async validateTasks(squadPath) {
+    this._log(`Validating tasks in: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    const tasksDir = path.join(squadPath, 'tasks');
+
+    // Check if tasks directory exists
+    if (!(await this._pathExists(tasksDir))) {
+      return result; // Already warned in structure validation
+    }
+
+    // Get task files
+    let files;
+    try {
+      files = await fs.readdir(tasksDir);
+    } catch (error) {
+      result.errors.push({
+        code: ValidationErrorCodes.TASK_READ_ERROR,
+        message: `Failed to read tasks directory: ${error.message}`,
+      });
+      result.valid = false;
+      return result;
+    }
+
+    const taskFiles = files.filter((f) => f.endsWith('.md'));
+
+    if (taskFiles.length === 0) {
+      result.warnings.push({
+        code: ValidationErrorCodes.NO_TASKS,
+        message: 'No task files found in tasks/',
+        suggestion: 'Task-first architecture: Create at least one task file',
+      });
+      return result;
+    }
+
+    // Validate each task file
+    for (const taskFile of taskFiles) {
+      const taskPath = path.join(tasksDir, taskFile);
+      const taskResult = await this._validateTaskFile(taskPath);
+      this._mergeResults(result, taskResult);
+    }
+
+    this._log(`Task validation: ${taskFiles.length} files checked`);
+    return result;
+  }
+
+  /**
+   * Validate config references in squad.yaml
+   * Implements AC10.4: Validates that referenced config files actually exist
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for config references
+   * @see Story SQS-10: Project Config Reference for Squads
+   */
+  async validateConfigReferences(squadPath) {
+    this._log(`Validating config references in: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // Find and parse manifest
+    const manifestPath = await this._findManifest(squadPath);
+    if (!manifestPath) {
+      return result; // Already handled in manifest validation
+    }
+
+    let manifest;
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8');
+      manifest = yaml.load(content);
+    } catch {
+      return result; // Already handled in manifest validation
+    }
+
+    // Check config section
+    if (!manifest || !manifest.config) {
+      return result; // No config section to validate
+    }
+
+    const configFields = ['coding-standards', 'tech-stack', 'source-tree'];
+
+    for (const field of configFields) {
+      const configPath = manifest.config[field];
+      if (!configPath) continue;
+
+      const resolvedPath = await this._resolveConfigPath(squadPath, configPath);
+      if (!resolvedPath) {
+        // Check if this is a project-level reference that doesn't exist
+        if (configPath.includes('..') || configPath.includes('docs/framework')) {
+          result.warnings.push({
+            code: ValidationErrorCodes.FILE_NOT_FOUND,
+            message: `Config reference not found: ${configPath}`,
+            suggestion: `Create the file at ${configPath} or update squad.yaml to use local config (config/${field}.md)`,
+          });
+        } else {
+          // Local config file missing - this is an error
+          result.errors.push({
+            code: ValidationErrorCodes.FILE_NOT_FOUND,
+            message: `Local config file not found: ${configPath}`,
+            suggestion: `Create ${path.join(squadPath, configPath)} or remove from config section`,
+          });
+          result.valid = false;
+        }
+      }
+    }
+
+    this._log(`Config validation: ${result.errors.length} errors, ${result.warnings.length} warnings`);
+    return result;
+  }
+
+  /**
+   * Validate agent definitions
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for agents
+   */
+  async validateAgents(squadPath) {
+    this._log(`Validating agents in: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    const agentsDir = path.join(squadPath, 'agents');
+
+    // Check if agents directory exists
+    if (!(await this._pathExists(agentsDir))) {
+      return result; // Already warned in structure validation
+    }
+
+    // Get agent files
+    let files;
+    try {
+      files = await fs.readdir(agentsDir);
+    } catch (error) {
+      return result;
+    }
+
+    const agentFiles = files.filter((f) => f.endsWith('.md'));
+
+    // Validate each agent file
+    for (const agentFile of agentFiles) {
+      const agentPath = path.join(agentsDir, agentFile);
+      try {
+        const content = await fs.readFile(agentPath, 'utf-8');
+
+        // Check for basic agent structure (YAML frontmatter or markdown structure)
+        const hasYamlFrontmatter = content.includes('agent:');
+        const hasMarkdownHeading = content.match(/^#\s+.+/m);
+
+        if (!hasYamlFrontmatter && !hasMarkdownHeading) {
+          result.warnings.push({
+            code: ValidationErrorCodes.AGENT_INVALID_FORMAT,
+            file: agentFile,
+            message: 'Agent file may not follow AIOS agent definition format',
+            suggestion:
+              'Use agent: YAML frontmatter or markdown heading structure',
+          });
+        }
+
+        // Check naming convention (kebab-case)
+        if (!this._isKebabCase(path.basename(agentFile, '.md'))) {
+          result.warnings.push({
+            code: ValidationErrorCodes.INVALID_NAMING,
+            file: agentFile,
+            message: 'Agent filename should be kebab-case',
+            suggestion: 'Rename to use lowercase letters and hyphens only',
+          });
+        }
+      } catch (error) {
+        result.errors.push({
+          code: ValidationErrorCodes.TASK_READ_ERROR,
+          file: agentFile,
+          message: `Failed to read agent file: ${error.message}`,
+        });
+        result.valid = false;
+      }
+    }
+
+    this._log(`Agent validation: ${agentFiles.length} files checked`);
+    return result;
+  }
+
+  /**
+   * Format validation result for display
+   *
+   * @param {ValidationResult} result - Validation result
+   * @param {string} squadPath - Path to squad
+   * @returns {string} Formatted output
+   */
+  formatResult(result, squadPath) {
+    const lines = [];
+
+    lines.push(`Validating squad: ${squadPath}/`);
+    lines.push('');
+
+    // Errors
+    if (result.errors.length > 0) {
+      lines.push(`Errors: ${result.errors.length}`);
+      for (const err of result.errors) {
+        const filePart = err.file ? ` (${err.file})` : '';
+        const pathPart = err.path ? ` at ${err.path}` : '';
+        lines.push(`  - [${err.code}]${pathPart}${filePart}: ${err.message}`);
+        if (err.suggestion) {
+          lines.push(`    Suggestion: ${err.suggestion}`);
+        }
+      }
+      lines.push('');
+    }
+
+    // Warnings
+    if (result.warnings.length > 0) {
+      lines.push(`Warnings: ${result.warnings.length}`);
+      for (const warn of result.warnings) {
+        const filePart = warn.file ? ` (${warn.file})` : '';
+        lines.push(`  - [${warn.code}]${filePart}: ${warn.message}`);
+        if (warn.suggestion) {
+          lines.push(`    Suggestion: ${warn.suggestion}`);
+        }
+      }
+      lines.push('');
+    }
+
+    // Result
+    if (result.valid) {
+      if (result.warnings.length > 0) {
+        lines.push('Result: VALID (with warnings)');
+      } else {
+        lines.push('Result: VALID');
+      }
+    } else {
+      lines.push('Result: INVALID');
+    }
+
+    return lines.join('\n');
+  }
+
+  // ============ Private Helper Methods ============
+
+  /**
+   * Find manifest file in squad directory
+   * @private
+   */
+  async _findManifest(squadPath) {
+    for (const filename of MANIFEST_FILES) {
+      const manifestPath = path.join(squadPath, filename);
+      if (await this._pathExists(manifestPath)) {
+        return manifestPath;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Check if path exists
+   * @private
+   */
+  async _pathExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Resolve config path - check both local and project-level paths
+   * Implements AC10.4: Validator Path Resolution
+   *
+   * @param {string} squadPath - Squad directory
+   * @param {string} configPath - Path from squad.yaml config section
+   * @returns {Promise<string|null>} Resolved absolute path or null if not found
+   * @see Story SQS-10: Project Config Reference for Squads
+   * @private
+   */
+  async _resolveConfigPath(squadPath, configPath) {
+    if (!configPath) return null;
+
+    // Resolve path relative to squad directory
+    // path.resolve handles both local paths (config/file.md) and relative paths (../../docs/framework/...)
+    // Simplified from redundant path.resolve + path.join (CodeRabbit nitpick)
+    const resolvedPath = path.resolve(squadPath, configPath);
+    if (await this._pathExists(resolvedPath)) {
+      this._log(`Resolved config path: ${configPath} -> ${resolvedPath}`);
+      return resolvedPath;
+    }
+
+    this._log(`Config path not found: ${configPath}`);
+    return null;
+  }
+
+  /**
+   * Validate a single task file
+   * @private
+   */
+  async _validateTaskFile(taskPath) {
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+    const filename = path.basename(taskPath);
+
+    try {
+      const content = await fs.readFile(taskPath, 'utf-8');
+
+      // Check for required fields (case-insensitive, handle accents)
+      for (const field of TASK_REQUIRED_FIELDS) {
+        // Create patterns that handle Portuguese accents
+        const patterns = [
+          new RegExp(`^[#*-]*\\s*${field}\\s*:`, 'im'),
+          new RegExp(
+            `^[#*-]*\\s*${field.replace(/a/g, '[aá]').replace(/i/g, '[ií]')}\\s*:`,
+            'im',
+          ),
+          // Also check for markdown headers with the field
+          new RegExp(`^#+\\s*${field}`, 'im'),
+        ];
+
+        const found = patterns.some((p) => p.test(content));
+        if (!found) {
+          result.warnings.push({
+            code: ValidationErrorCodes.TASK_MISSING_FIELD,
+            file: filename,
+            message: `Task missing recommended field: ${field}`,
+            suggestion: `Add "${field}:" to ${filename} (TASK-FORMAT-SPECIFICATION-V1)`,
+          });
+        }
+      }
+
+      // Check naming convention
+      if (!this._isKebabCase(path.basename(filename, '.md'))) {
+        result.warnings.push({
+          code: ValidationErrorCodes.INVALID_NAMING,
+          file: filename,
+          message: 'Task filename should be kebab-case',
+          suggestion: 'Rename to use lowercase letters and hyphens only',
+        });
+      }
+    } catch (error) {
+      result.errors.push({
+        code: ValidationErrorCodes.TASK_READ_ERROR,
+        file: filename,
+        message: `Failed to read task: ${error.message}`,
+      });
+      result.valid = false;
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate files referenced in manifest components
+   * @private
+   */
+  async _validateReferencedFiles(squadPath, components, result) {
+    const componentDirs = {
+      tasks: 'tasks',
+      agents: 'agents',
+      workflows: 'workflows',
+      checklists: 'checklists',
+      templates: 'templates',
+      tools: 'tools',
+      scripts: 'scripts',
+    };
+
+    for (const [component, dir] of Object.entries(componentDirs)) {
+      if (components[component] && Array.isArray(components[component])) {
+        for (const file of components[component]) {
+          const filePath = path.join(squadPath, dir, file);
+          if (!(await this._pathExists(filePath))) {
+            result.errors.push({
+              code: ValidationErrorCodes.FILE_NOT_FOUND,
+              message: `Referenced file not found: ${dir}/${file}`,
+              suggestion: `Create ${filePath} or remove from components.${component}`,
+            });
+            result.valid = false;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if string is kebab-case
+   * @private
+   */
+  _isKebabCase(str) {
+    return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(str);
+  }
+
+  /**
+   * Get suggestion for schema error
+   * @private
+   */
+  _getSchemaSuggestion(error) {
+    const suggestions = {
+      'must match pattern':
+        'Use correct format (kebab-case for names, semver for versions)',
+      'must be string': 'Wrap value in quotes',
+      'must be array': 'Use YAML array syntax: [item1, item2] or - item',
+      'must have required property': 'Add the missing required property',
+      'must be equal to one of the allowed values': 'Use one of the allowed values',
+    };
+
+    for (const [key, suggestion] of Object.entries(suggestions)) {
+      if (error.message && error.message.includes(key)) {
+        return suggestion;
+      }
+    }
+    return 'Check squad.yaml syntax against the schema';
+  }
+
+  /**
+   * Merge validation results
+   * @private
+   */
+  _mergeResults(target, source) {
+    target.errors.push(...(source.errors || []));
+    target.warnings.push(...(source.warnings || []));
+    target.suggestions.push(...(source.suggestions || []));
+    if (source.errors && source.errors.length > 0) {
+      target.valid = false;
+    }
+  }
+}
+
+module.exports = {
+  SquadValidator,
+  ValidationErrorCodes,
+  TASK_REQUIRED_FIELDS,
+  MANIFEST_FILES,
+};