@polymorphism-tech/morph-spec 7.2.0 → 7.4.0

package/src/commands/validation/validate-feature.js

@@ -1,287 +1,356 @@
-/**
- * MORPH-SPEC Feature Validation Command
- *
- * Content-aware validation of feature outputs at each phase.
- * Checks section presence, schema consistency, and contract correctness.
- *
- * Usage:
- *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
- *
- * Example:
- *   morph-spec validate user-portal --phase design
- *   morph-spec validate user-portal --json
- */
-
-import fs from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import { getFeature } from '../../core/state/state-manager.js';
-
-/**
- * Expected sections per output file
- */
-const OUTPUT_SECTIONS = {
-  'proposal.md': {
-    required: ['Overview', 'Problem', 'Solution', 'Scope'],
-    optional: ['Agents', 'Stack', 'Risks']
-  },
-  'spec.md': {
-    required: [
-      'Overview', 'Functional Requirements', 'Non-Functional Requirements',
-      'Technical Architecture', 'Data Model'
-    ],
-    optional: [
-      'Infrastructure', 'Testing Strategy', 'Security',
-      'Performance', 'Edge Cases', 'Clarifications'
-    ]
-  },
-  'mandate.md': {
-    required: ['Stack', 'Standards', 'Done'],
-    optional: ['Patterns proibidos', 'Riscos']
-  },
-  'decisions.md': {
-    required: ['ADR', 'Status', 'Context', 'Decision'],
-    optional: ['Consequences', 'Alternatives', 'Costs']
-  },
-  'tasks.md': {
-    required: ['T001', 'category', 'dependencies'],
-    optional: ['CHECKPOINT', 'estimatedMinutes']
-  },
-  'review-report.md': {
-    required: ['Scores', 'Recommendation'],
-    optional: ['Blockers', 'Improvements']
-  },
-};
-
-/**
- * Phase-to-output mapping (v5 NLH)
- */
-const PHASE_OUTPUTS = {
-  proposal: ['proposal.md'],
-  uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
-  plan: ['spec.md', 'mandate.md', 'tasks.md'],
-  implement: ['recap.md'],
-  review: ['review-report.md'],
-};
-
-/**
- * Phase-to-folder mapping (v5 filesystem convention)
- */
-const PHASE_FOLDERS = {
-  proposal: '0-proposal',
-  uiux: '1-design',
-  plan: '2-plan',
-  implement: '3-implement',
-  review: '4-review',
-};
-
-/**
- * Validate a single output file
- */
-function validateOutput(featurePath, outputFile) {
-  const filePath = path.join(featurePath, outputFile);
-  const result = {
-    file: outputFile,
-    exists: false,
-    sections: { found: [], missing: [], optional: [] },
-    warnings: [],
-    errors: [],
-    lineCount: 0
-  };
-
-  if (!fs.existsSync(filePath)) {
-    result.errors.push(`File not found: ${outputFile}`);
-    return result;
-  }
-
-  result.exists = true;
-  const content = fs.readFileSync(filePath, 'utf8');
-  result.lineCount = content.split('\n').length;
-
-  // Skip section checks for files without defined sections
-  const sections = OUTPUT_SECTIONS[outputFile];
-  if (!sections) {
-    return result;
-  }
-
-  // v5: only markdown outputs — contracts moved into spec.md
-  validateMarkdownSections(content, sections, result);
-
-  // Size warnings
-  if (result.lineCount < 10) {
-    result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
-  }
-
-  return result;
-}
-
-/**
- * Validate markdown sections
- */
-function validateMarkdownSections(content, sections, result) {
-  const contentLower = content.toLowerCase();
-
-  for (const section of sections.required) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.found.push(section);
-    } else {
-      result.sections.missing.push(section);
-      result.errors.push(`Missing required section: "${section}"`);
-    }
-  }
-
-  for (const section of (sections.optional || [])) {
-    if (contentLower.includes(section.toLowerCase())) {
-      result.sections.optional.push(section);
-    }
-  }
-}
-
-/**
- * Main validate command
- */
-export async function validateFeatureCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Error: Feature name required'));
-    console.error(chalk.gray('Usage: morph-spec validate <feature-name> [--phase <phase>]'));
-    process.exit(1);
-  }
-
-  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
-
-  if (!fs.existsSync(featurePath)) {
-    console.error(chalk.red(`Error: Feature directory not found: ${featurePath}`));
-    process.exit(1);
-  }
-
-  // Determine which outputs to validate
-  const phase = options.phase || null;
-  let outputFiles;
-
-  if (phase) {
-    outputFiles = PHASE_OUTPUTS[phase];
-    if (!outputFiles) {
-      console.error(chalk.red(`Unknown phase: ${phase}`));
-      console.error(chalk.gray(`Valid phases: ${Object.keys(PHASE_OUTPUTS).join(', ')}`));
-      process.exit(1);
-    }
-  } else {
-    // Validate all existing outputs across all phase folders
-    outputFiles = [];
-    const entries = fs.readdirSync(featurePath, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        const subDir = path.join(featurePath, entry.name);
-        const files = fs.readdirSync(subDir).filter(f => f.endsWith('.md') || f.endsWith('.cs'));
-        outputFiles.push(...files.map(f => ({ file: f, dir: subDir })));
-      } else if (entry.name.endsWith('.md') || entry.name.endsWith('.cs')) {
-        outputFiles.push({ file: entry.name, dir: featurePath });
-      }
-    }
-  }
-
-  // Resolve phase folder for path lookup
-  const phaseFolder = phase ? PHASE_FOLDERS[phase] : null;
-  const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
-
-  // Run validation
-  const results = phase
-    ? outputFiles.map(file => validateOutput(searchPath, file))
-    : outputFiles.map(({ file, dir }) => validateOutput(dir, file));
-  const schemaWarnings = []; // v5: cross-validation removed (contracts in spec.md)
-
-  // Aggregate results
-  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
-  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0) + schemaWarnings.length;
-  const totalFound = results.reduce((sum, r) => sum + r.sections.found.length, 0);
-
-  // JSON output mode
-  if (options.json) {
-    const output = {
-      feature: featureName,
-      phase: phase || 'all',
-      valid: totalErrors === 0,
-      summary: {
-        files: results.length,
-        errors: totalErrors,
-        warnings: totalWarnings,
-        sectionsFound: totalFound
-      },
-      results: results.map(r => ({
-        file: r.file,
-        exists: r.exists,
-        lineCount: r.lineCount,
-        errors: r.errors,
-        warnings: r.warnings,
-        sectionsFound: r.sections.found,
-        sectionsMissing: r.sections.missing
-      })),
-      schemaWarnings
-    };
-    console.log(JSON.stringify(output, null, 2));
-    return;
-  }
-
-  // Visual output
-  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
-  console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
-  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
-
-  console.log(chalk.white.bold(`Feature: ${featureName}`));
-  if (phase) console.log(chalk.gray(`Phase: ${phase}`));
-  console.log('');
-
-  // File-by-file results
-  for (const result of results) {
-    const symbol = result.exists
-      ? (result.errors.length === 0 ? '✅' : '❌')
-      : '⬜';
-    const name = result.exists
-      ? (result.errors.length === 0 ? chalk.green(result.file) : chalk.red(result.file))
-      : chalk.gray(result.file);
-
-    console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
-
-    // Sections found
-    if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
-      result.sections.found.forEach(s => {
-        console.log(chalk.green(`   ✓ ${s}`));
-      });
-    }
-
-    // Errors
-    result.errors.forEach(err => {
-      console.log(chalk.red(`   ✗ ${err}`));
-    });
-
-    // Warnings
-    result.warnings.forEach(warn => {
-      console.log(chalk.yellow(`   ⚠ ${warn}`));
-    });
-  }
-
-  // Schema cross-validation
-  if (schemaWarnings.length > 0) {
-    console.log(chalk.yellow('\nSchema Cross-Validation:'));
-    schemaWarnings.forEach(w => {
-      console.log(chalk.yellow(`  ⚠ ${w}`));
-    });
-  }
-
-  // Summary
-  console.log('');
-  console.log(chalk.gray('─'.repeat(60)));
-
-  if (totalErrors === 0) {
-    console.log(chalk.green(`\n✓ VALIDATION PASSED — ${results.filter(r => r.exists).length} files validated`));
-    if (totalWarnings > 0) {
-      console.log(chalk.yellow(`  ${totalWarnings} warning(s) — review recommended`));
-    }
-  } else {
-    console.log(chalk.red(`\n✗ VALIDATION FAILED — ${totalErrors} error(s), ${totalWarnings} warning(s)`));
-    console.log(chalk.yellow('  Fix errors before advancing to the next phase'));
-  }
-  console.log('');
-}
-
-export default validateFeatureCommand;
+/**
+ * MORPH-SPEC Feature Validation Command
+ *
+ * Content-aware validation of feature outputs at each phase.
+ * Checks section presence, schema consistency, and contract correctness.
+ *
+ * Usage:
+ *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
+ *
+ * Example:
+ *   morph-spec validate user-portal --phase design
+ *   morph-spec validate user-portal --json
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { getFeature } from '../../core/state/state-manager.js';
+import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
+
+/**
+ * Expected sections per output file.
+ *
+ * Each section entry can be a string (single substring to match) or an array
+ * of acceptable substrings (any-of match). This lets pt-BR and English
+ * coexist — e.g. "Problem" matches both "Problem" and "Problema", but
+ * "Scope" needs to be paired with "Escopo" explicitly.
+ *
+ * The matcher (`validateMarkdownSections`) does case-insensitive substring
+ * matching against the whole file content.
+ */
+const OUTPUT_SECTIONS = {
+  'proposal.md': {
+    required: [
+      'Overview',
+      'Problem',                       // also matches Problema
+      ['Solution', 'Solução'],
+      ['Scope', 'Escopo']
+    ],
+    optional: ['Agents', 'Stack', ['Risks', 'Riscos']]
+  },
+  'spec.md': {
+    required: [
+      'Overview',
+      ['Functional Requirements', 'Requisitos Funcionais'],
+      ['Non-Functional Requirements', 'Requisitos Não-Funcionais', 'Requisitos Nao-Funcionais'],
+      ['Technical Architecture', 'Arquitetura'],
+      ['Data Model', 'Modelo de Dados', 'Contratos']
+    ],
+    optional: [
+      ['Infrastructure', 'Infraestrutura'],
+      ['Testing Strategy', 'Estratégia de Testes', 'Testes'],
+      ['Security', 'Segurança'],
+      'Performance',
+      ['Edge Cases', 'Casos Limite'],
+      ['Clarifications', 'Esclarecimentos']
+    ]
+  },
+  'mandate.md': {
+    required: ['Stack', 'Standards', ['Done', 'Pronto']],
+    optional: [
+      ['Patterns proibidos', 'Padrões proibidos', 'Forbidden Patterns'],
+      ['Riscos', 'Risks']
+    ]
+  },
+  'decisions.md': {
+    required: ['ADR', 'Status', ['Context', 'Contexto'], ['Decision', 'Decisão']],
+    optional: [
+      ['Consequences', 'Consequências', 'Implicações'],
+      ['Alternatives', 'Alternativas'],
+      ['Costs', 'Custos']
+    ]
+  },
+  'review-report.md': {
+    required: [['Scores', 'Pontuação', 'Scoring'], ['Recommendation', 'Recomendação']],
+    optional: [['Blockers', 'Bloqueantes'], ['Improvements', 'Melhorias']]
+  },
+};
+
+/**
+ * Phase-to-output mapping (v5 NLH)
+ */
+const PHASE_OUTPUTS = {
+  proposal: ['proposal.md'],
+  uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
+  plan: ['spec.md', 'mandate.md', 'tasks.json'],
+  implement: ['recap.md'],
+  review: ['review-report.md'],
+};
+
+/**
+ * Phase-to-folder mapping (v5 filesystem convention)
+ */
+const PHASE_FOLDERS = {
+  proposal: '0-proposal',
+  uiux: '1-design',
+  plan: '2-plan',
+  implement: '3-implement',
+  review: '4-review',
+};
+
+/**
+ * Validate a single output file
+ */
+function validateOutput(featurePath, outputFile) {
+  const filePath = path.join(featurePath, outputFile);
+  const result = {
+    file: outputFile,
+    exists: false,
+    sections: { found: [], missing: [], optional: [] },
+    warnings: [],
+    errors: [],
+    lineCount: 0
+  };
+
+  if (!fs.existsSync(filePath)) {
+    result.errors.push(`File not found: ${outputFile}`);
+    return result;
+  }
+
+  result.exists = true;
+  const content = fs.readFileSync(filePath, 'utf8');
+  result.lineCount = content.split('\n').length;
+
+  // tasks.json: structural validation against the schema, not markdown sections.
+  if (outputFile === 'tasks.json') {
+    validateTasksJsonOutput(content, result);
+    return result;
+  }
+
+  // Skip section checks for files without defined sections
+  const sections = OUTPUT_SECTIONS[outputFile];
+  if (!sections) {
+    return result;
+  }
+
+  // v5: only markdown outputs — contracts moved into spec.md
+  validateMarkdownSections(content, sections, result);
+
+  // Size warnings
+  if (result.lineCount < 10) {
+    result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
+  }
+
+  return result;
+}
+
+/**
+ * Validate tasks.json structurally: parseable JSON + conforms to the schema +
+ * has at least one task.
+ */
+function validateTasksJsonOutput(content, result) {
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch (err) {
+    result.errors.push(`tasks.json is not valid JSON: ${err.message}`);
+    return;
+  }
+  const { valid, errors } = validateTasksJson(data);
+  if (!valid) {
+    for (const e of errors) result.errors.push(e);
+    return;
+  }
+  if (data.tasks.length === 0) {
+    result.errors.push('tasks.json has no task entries');
+    return;
+  }
+  result.sections.found.push(`${data.tasks.length} task(s)`);
+}
+
+/**
+ * Validate markdown sections.
+ *
+ * Each `section` entry can be:
+ *   - a string  → must appear as a substring (case-insensitive)
+ *   - an array  → any-of: at least one of the strings must appear
+ *
+ * The any-of form supports bilingual content (e.g. ['Scope', 'Escopo']).
+ */
+function validateMarkdownSections(content, sections, result) {
+  const contentLower = content.toLowerCase();
+  const matches = (entry) => {
+    const candidates = Array.isArray(entry) ? entry : [entry];
+    const hit = candidates.find(c => contentLower.includes(c.toLowerCase()));
+    return { hit, label: candidates[0] };
+  };
+
+  for (const entry of sections.required) {
+    const { hit, label } = matches(entry);
+    if (hit) {
+      result.sections.found.push(hit);
+    } else {
+      result.sections.missing.push(label);
+      const acceptable = Array.isArray(entry)
+        ? entry.map(s => `"${s}"`).join(' or ')
+        : `"${entry}"`;
+      result.errors.push(`Missing required section: ${acceptable}`);
+    }
+  }
+
+  for (const entry of (sections.optional || [])) {
+    const { hit } = matches(entry);
+    if (hit) result.sections.optional.push(hit);
+  }
+}
+
+/**
+ * Main validate command
+ */
+export async function validateFeatureCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    console.error(chalk.gray('Usage: morph-spec validate <feature-name> [--phase <phase>]'));
+    process.exit(1);
+  }
+
+  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
+
+  if (!fs.existsSync(featurePath)) {
+    console.error(chalk.red(`Error: Feature directory not found: ${featurePath}`));
+    process.exit(1);
+  }
+
+  // Determine which outputs to validate
+  const phase = options.phase || null;
+  let outputFiles;
+
+  if (phase) {
+    outputFiles = PHASE_OUTPUTS[phase];
+    if (!outputFiles) {
+      console.error(chalk.red(`Unknown phase: ${phase}`));
+      console.error(chalk.gray(`Valid phases: ${Object.keys(PHASE_OUTPUTS).join(', ')}`));
+      process.exit(1);
+    }
+  } else {
+    // Validate all existing outputs across all phase folders
+    outputFiles = [];
+    const entries = fs.readdirSync(featurePath, { withFileTypes: true });
+    const isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'tasks.json';
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const subDir = path.join(featurePath, entry.name);
+        const files = fs.readdirSync(subDir).filter(isOutput);
+        outputFiles.push(...files.map(f => ({ file: f, dir: subDir })));
+      } else if (isOutput(entry.name)) {
+        outputFiles.push({ file: entry.name, dir: featurePath });
+      }
+    }
+  }
+
+  // Resolve phase folder for path lookup
+  const phaseFolder = phase ? PHASE_FOLDERS[phase] : null;
+  const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
+
+  // Run validation
+  const results = phase
+    ? outputFiles.map(file => validateOutput(searchPath, file))
+    : outputFiles.map(({ file, dir }) => validateOutput(dir, file));
+  const schemaWarnings = []; // v5: cross-validation removed (contracts in spec.md)
+
+  // Aggregate results
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0) + schemaWarnings.length;
+  const totalFound = results.reduce((sum, r) => sum + r.sections.found.length, 0);
+
+  // JSON output mode
+  if (options.json) {
+    const output = {
+      feature: featureName,
+      phase: phase || 'all',
+      valid: totalErrors === 0,
+      summary: {
+        files: results.length,
+        errors: totalErrors,
+        warnings: totalWarnings,
+        sectionsFound: totalFound
+      },
+      results: results.map(r => ({
+        file: r.file,
+        exists: r.exists,
+        lineCount: r.lineCount,
+        errors: r.errors,
+        warnings: r.warnings,
+        sectionsFound: r.sections.found,
+        sectionsMissing: r.sections.missing
+      })),
+      schemaWarnings
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Visual output
+  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
+  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
+
+  console.log(chalk.white.bold(`Feature: ${featureName}`));
+  if (phase) console.log(chalk.gray(`Phase: ${phase}`));
+  console.log('');
+
+  // File-by-file results
+  for (const result of results) {
+    const symbol = result.exists
+      ? (result.errors.length === 0 ? '✅' : '❌')
+      : '⬜';
+    const name = result.exists
+      ? (result.errors.length === 0 ? chalk.green(result.file) : chalk.red(result.file))
+      : chalk.gray(result.file);
+
+    console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
+
+    // Sections found
+    if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
+      result.sections.found.forEach(s => {
+        console.log(chalk.green(`   ✓ ${s}`));
+      });
+    }
+
+    // Errors
+    result.errors.forEach(err => {
+      console.log(chalk.red(`   ✗ ${err}`));
+    });
+
+    // Warnings
+    result.warnings.forEach(warn => {
+      console.log(chalk.yellow(`   ⚠ ${warn}`));
+    });
+  }
+
+  // Schema cross-validation
+  if (schemaWarnings.length > 0) {
+    console.log(chalk.yellow('\nSchema Cross-Validation:'));
+    schemaWarnings.forEach(w => {
+      console.log(chalk.yellow(`  ⚠ ${w}`));
+    });
+  }
+
+  // Summary
+  console.log('');
+  console.log(chalk.gray('─'.repeat(60)));
+
+  if (totalErrors === 0) {
+    console.log(chalk.green(`\n✓ VALIDATION PASSED — ${results.filter(r => r.exists).length} files validated`));
+    if (totalWarnings > 0) {
+      console.log(chalk.yellow(`  ${totalWarnings} warning(s) — review recommended`));
+    }
+  } else {
+    console.log(chalk.red(`\n✗ VALIDATION FAILED — ${totalErrors} error(s), ${totalWarnings} warning(s)`));
+    console.log(chalk.yellow('  Fix errors before advancing to the next phase'));
+  }
+  console.log('');
+}
+
+export default validateFeatureCommand;