@polymorphism-tech/morph-spec 7.4.0 → 7.5.0

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

@@ -8,72 +8,116 @@
  *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
  *
  * Example:
- *   morph-spec validate user-portal --phase design
+ *   morph-spec validate user-portal --phase plan
  *   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.
+ * Expected sections per output file — realigned with what the core skills
+ * actually emit (`morph-brainstorming`, `morph-plan`, `morph-review`) so that
+ * the framework's own output passes its own validator.
  *
- * 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.
+ * Three tiers:
+ *   required    → ERROR if absent. Strict subset of what the skills always emit.
+ *   recommended → WARNING if absent. Skills emit these, but a lean doc may skip.
+ *   optional    → silent. Tracked when present, never penalized.
  *
- * The matcher (`validateMarkdownSections`) does case-insensitive substring
- * matching against the whole file content.
+ * Each entry is a string or an array of acceptable strings (any-of). The array
+ * form carries bilingual aliases (pt-BR section names the skills emit AND their
+ * English equivalents in the canonical templates), e.g. ['Escopo', 'Scope'].
+ *
+ * Matching is done against *section markers* (headings and line-start bold
+ * labels), not whole-file substrings — see `extractSectionMarkers`.
  */
 const OUTPUT_SECTIONS = {
+  // morph-brainstorming emits: Problema, Escopo, Usuários e fluxos críticos,
+  // Critérios de aceite, Stack, Riscos e dependências, Compliance de stack.
   'proposal.md': {
     required: [
-      'Overview',
-      'Problem',                       // also matches Problema
-      ['Solution', 'Solução'],
-      ['Scope', 'Escopo']
+      ['Problema', 'Problem'],
+      ['Escopo', 'Scope'],
+      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
+    ],
+    recommended: [
+      ['Riscos', 'Risks'],
+    ],
+    optional: [
+      'Stack',
+      ['Usuários', 'Usuarios', 'Users', 'User Journey', 'User Stories', 'Fluxos'],
+      ['Dependências', 'Dependencias', 'Dependencies'],
+      ['Compliance'],
+      ['Overview', 'Visão geral', 'Visao geral', 'Resumo'],
     ],
-    optional: ['Agents', 'Stack', ['Risks', 'Riscos']]
   },
+  // morph-plan (spec.md) emits: Arquitetura da solução, Edge cases,
+  // Integrações externas e contratos esperados.
   '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']
+      ['Arquitetura', 'Architecture'],
+      ['Integrações', 'Integracoes', 'Integrations', 'Contratos', 'Contracts', 'Data Model', 'Modelo de Dados'],
+    ],
+    recommended: [
+      ['Edge cases', 'Edge Cases', 'Casos limite', 'Casos Limite', 'Casos de borda'],
     ],
     optional: [
-      ['Infrastructure', 'Infraestrutura'],
-      ['Testing Strategy', 'Estratégia de Testes', 'Testes'],
-      ['Security', 'Segurança'],
-      'Performance',
-      ['Edge Cases', 'Casos Limite'],
-      ['Clarifications', 'Esclarecimentos']
-    ]
+      ['Overview', 'Visão geral', 'Resumo'],
+      ['Requirements', 'Requisitos'],
+      ['Security', 'Segurança', 'Seguranca'],
+      ['Testing', 'Testes', 'Estratégia de Testes'],
+      ['Performance', 'Desempenho'],
+    ],
   },
+  // morph-plan (mandate.md) emits: Stack, Standards obrigatórios,
+  // Patterns proibidos, Checklist de done.
   'mandate.md': {
-    required: ['Stack', 'Standards', ['Done', 'Pronto']],
+    required: [
+      'Stack',
+      ['Standards', 'Padrões', 'Padroes'],
+      ['Done', 'Pronto', 'Checklist', 'Critérios de done', 'Definition of Done'],
+    ],
+    recommended: [
+      ['Patterns proibidos', 'Padrões proibidos', 'Padroes proibidos', 'Forbidden Patterns', 'Forbidden', 'Proibido'],
+    ],
     optional: [
-      ['Patterns proibidos', 'Padrões proibidos', 'Forbidden Patterns'],
-      ['Riscos', 'Risks']
-    ]
+      ['Riscos', 'Risks'],
+      ['Acesso a dados', 'Data Access', 'Repository', 'Repositório'],
+    ],
   },
+  // decisions.md follows the ADR convention: an `### ADR-NNN` heading with
+  // `**Status:** / **Context:** / **Decision:**` line-start bold labels.
   'decisions.md': {
-    required: ['ADR', 'Status', ['Context', 'Contexto'], ['Decision', 'Decisão']],
+    required: [
+      'ADR',
+      'Status',
+      ['Contexto', 'Context'],
+      ['Decisão', 'Decisao', 'Decision'],
+    ],
+    recommended: [
+      ['Consequências', 'Consequencias', 'Consequences', 'Implicações', 'Trade-offs', 'Trade-off'],
+    ],
     optional: [
-      ['Consequences', 'Consequências', 'Implicações'],
-      ['Alternatives', 'Alternativas'],
-      ['Costs', 'Custos']
-    ]
+      ['Alternativas', 'Alternatives'],
+      ['Custos', 'Costs'],
+    ],
   },
+  // morph-review emits: Scores por dimensão, Bloqueantes, Melhorias,
+  // Recomendação final.
   'review-report.md': {
-    required: [['Scores', 'Pontuação', 'Scoring'], ['Recommendation', 'Recomendação']],
-    optional: [['Blockers', 'Bloqueantes'], ['Improvements', 'Melhorias']]
+    required: [
+      ['Scores', 'Score', 'Pontuação', 'Pontuacao', 'Scoring'],
+      ['Recomendação', 'Recomendacao', 'Recommendation'],
+    ],
+    recommended: [
+      ['Bloqueantes', 'Bloqueante', 'Blockers'],
+    ],
+    optional: [
+      ['Melhorias', 'Improvements', 'Recomendadas'],
+    ],
   },
 };
 
@@ -99,6 +143,38 @@ const PHASE_FOLDERS = {
   review: '4-review',
 };
 
+/**
+ * Extract section markers from markdown content.
+ *
+ * A marker is a line that structurally introduces a section:
+ *   - a markdown heading           → `## Arquitetura da solução`
+ *   - a line-start bold label      → `**Status:** Aceito`
+ *
+ * Bold labels are included on purpose (deviation from heading-only): the ADR
+ * convention used in `decisions.md` — and in the spec.md ADR block — writes
+ * Status/Context/Decision as line-start bold labels, not headings. They are
+ * structural, not prose, so this keeps ADRs valid without reintroducing the
+ * accidental-prose-match problem that whole-file substring matching had.
+ *
+ * Returns lowercased marker texts.
+ */
+function extractSectionMarkers(content) {
+  const markers = [];
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    const heading = /^#{1,6}\s+(.+)$/.exec(line);
+    if (heading) {
+      markers.push(heading[1].toLowerCase());
+      continue;
+    }
+    const bold = /^\*\*(.+?)\*\*/.exec(line);
+    if (bold) {
+      markers.push(bold[1].toLowerCase());
+    }
+  }
+  return markers;
+}
+
 /**
  * Validate a single output file
  */
@@ -110,7 +186,7 @@ function validateOutput(featurePath, outputFile) {
     sections: { found: [], missing: [], optional: [] },
     warnings: [],
     errors: [],
-    lineCount: 0
+    lineCount: 0,
   };
 
   if (!fs.existsSync(filePath)) {
@@ -170,43 +246,130 @@ function validateTasksJsonOutput(content, result) {
 }
 
 /**
- * Validate markdown sections.
+ * Validate markdown sections against section markers (headings + bold labels).
  *
- * 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
+ * Each `entry` is a string or array of acceptable aliases (any-of). A section
+ * is present when at least one alias is a substring of at least one marker.
  *
- * The any-of form supports bilingual content (e.g. ['Scope', 'Escopo']).
+ *   required    → missing produces an ERROR
+ *   recommended → missing produces a WARNING
+ *   optional    → tracked when present, never penalized
  */
 function validateMarkdownSections(content, sections, result) {
-  const contentLower = content.toLowerCase();
-  const matches = (entry) => {
+  const markers = extractSectionMarkers(content);
+  const match = (entry) => {
     const candidates = Array.isArray(entry) ? entry : [entry];
-    const hit = candidates.find(c => contentLower.includes(c.toLowerCase()));
+    const hit = candidates.find(c => markers.some(m => m.includes(c.toLowerCase())));
     return { hit, label: candidates[0] };
   };
+  const describe = (entry) =>
+    Array.isArray(entry) ? entry.map(s => `"${s}"`).join(' or ') : `"${entry}"`;
 
-  for (const entry of sections.required) {
-    const { hit, label } = matches(entry);
+  for (const entry of (sections.required || [])) {
+    const { hit, label } = match(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}`);
+      result.errors.push(`Missing required section: ${describe(entry)}`);
+    }
+  }
+
+  for (const entry of (sections.recommended || [])) {
+    const { hit } = match(entry);
+    if (hit) {
+      result.sections.found.push(hit);
+    } else {
+      result.warnings.push(`Missing recommended section: ${describe(entry)}`);
     }
   }
 
   for (const entry of (sections.optional || [])) {
-    const { hit } = matches(entry);
+    const { hit } = match(entry);
     if (hit) result.sections.optional.push(hit);
   }
 }
 
 /**
- * Main validate command
+ * Resolve the list of `{ file, dir }` outputs to validate.
+ *
+ * @param {string} featurePath  Absolute path to the feature directory.
+ * @param {string|null} phase   Phase key, or null to validate everything.
+ * @returns {{ outputFiles?: Array<{file:string, dir:string}>, error?: string }}
+ */
+function resolveOutputFiles(featurePath, phase) {
+  if (phase) {
+    const files = PHASE_OUTPUTS[phase];
+    if (!files) return { error: `Unknown phase: ${phase}` };
+    const phaseFolder = PHASE_FOLDERS[phase];
+    const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
+    return { outputFiles: files.map(file => ({ file, dir: searchPath })) };
+  }
+
+  // Validate every existing output across the feature root + phase folders.
+  const outputFiles = [];
+  const isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'tasks.json';
+  const entries = fs.readdirSync(featurePath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const subDir = path.join(featurePath, entry.name);
+      for (const f of fs.readdirSync(subDir).filter(isOutput)) {
+        outputFiles.push({ file: f, dir: subDir });
+      }
+    } else if (isOutput(entry.name)) {
+      outputFiles.push({ file: entry.name, dir: featurePath });
+    }
+  }
+  return { outputFiles };
+}
+
+/**
+ * Pure validation core — no console output, no process.exit.
+ *
+ * @param {string} featurePath  Absolute path to the feature directory.
+ * @param {{ phase?: string }} [options]
+ * @returns {{
+ *   feature: string, phase: string, valid: boolean, error?: string,
+ *   totalErrors: number, totalWarnings: number, totalFound: number,
+ *   results: object[]
+ * }}
+ */
+export function runFeatureValidation(featurePath, options = {}) {
+  const phase = options.phase || null;
+  const feature = path.basename(featurePath);
+
+  const { outputFiles, error } = resolveOutputFiles(featurePath, phase);
+  if (error) {
+    return {
+      feature,
+      phase: phase || 'all',
+      valid: false,
+      error,
+      totalErrors: 1,
+      totalWarnings: 0,
+      totalFound: 0,
+      results: [],
+    };
+  }
+
+  const results = outputFiles.map(({ file, dir }) => validateOutput(dir, file));
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0);
+  const totalFound = results.reduce((sum, r) => sum + r.sections.found.length, 0);
+
+  return {
+    feature,
+    phase: phase || 'all',
+    valid: totalErrors === 0,
+    totalErrors,
+    totalWarnings,
+    totalFound,
+    results,
+  };
+}
+
+/**
+ * Main validate command (CLI wrapper around `runFeatureValidation`)
  */
 export async function validateFeatureCommand(featureName, options = {}) {
   if (!featureName) {
@@ -222,59 +385,28 @@ export async function validateFeatureCommand(featureName, options = {}) {
     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 });
-      }
-    }
+  if (phase && !PHASE_OUTPUTS[phase]) {
+    console.error(chalk.red(`Unknown phase: ${phase}`));
+    console.error(chalk.gray(`Valid phases: ${Object.keys(PHASE_OUTPUTS).join(', ')}`));
+    process.exit(1);
   }
 
-  // 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 validation = runFeatureValidation(featurePath, { phase });
+  const { results, totalErrors, totalWarnings, totalFound } = validation;
   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,
+      phase: validation.phase,
+      valid: validation.valid,
       summary: {
         files: results.length,
         errors: totalErrors,
-        warnings: totalWarnings,
-        sectionsFound: totalFound
+        warnings: totalWarnings + schemaWarnings.length,
+        sectionsFound: totalFound,
       },
       results: results.map(r => ({
         file: r.file,
@@ -283,9 +415,9 @@ export async function validateFeatureCommand(featureName, options = {}) {
         errors: r.errors,
         warnings: r.warnings,
         sectionsFound: r.sections.found,
-        sectionsMissing: r.sections.missing
+        sectionsMissing: r.sections.missing,
       })),
-      schemaWarnings
+      schemaWarnings,
     };
     console.log(JSON.stringify(output, null, 2));
     return;
@@ -329,14 +461,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
     });
   }
 
-  // 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)));