@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,109 +1,34 @@
-/**
- * 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 plan
- *   morph-spec validate user-portal --json
- */
-
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
-import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
-
-/**
- * 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.
- *
- * 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.
- *
- * 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`.
- */
+import { parsePlan } from '../../lib/plan/plan-parser.js';
+import { knownPersonas, planHash, validatePlan } from '../../lib/plan/checks.js';
+
+// Matched against section markers (headings and line-start bold labels), never whole-file
+// substrings. required → ERROR, recommended → WARNING, optional → never penalized; an array is any-of.
 const OUTPUT_SECTIONS = {
-  // morph-brainstorming emits: Problema, Escopo, Usuários e fluxos críticos,
-  // Stack, Riscos e dependências, Compliance de stack, Conflitos com o acervo.
-  //
-  // "Critérios de aceite" is now OPTIONAL, not required: the behaviour layer
-  // moved to the use cases (2-plan/usecases/), whose post-conditions must be
-  // observable in a test, and morph-brainstorming no longer emits the section.
-  // `optional` — not `recommended` — precisely because the skill never emits it
-  // anymore: a warning on every new proposal would be systematic noise. Legacy
-  // proposals that DO carry the section keep validating exactly as before.
-  //
-  // "Conflitos com o acervo" is recommended: morph-brainstorming always emits
-  // it ("nenhum" included), so its absence means the acervo check never ran.
-  // Not required — proposals written before the section existed stay valid.
-  'proposal.md': {
+  'verifier.md': {
     required: [
-      ['Problema', 'Problem'],
-      ['Escopo', 'Scope'],
+      ['Verdict', 'Veredito'],
     ],
     recommended: [
-      ['Riscos', 'Risks'],
-      ['Conflitos', 'Conflicts'],
-    ],
-    optional: [
-      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
-      'Stack',
-      ['Usuários', 'Usuarios', 'Users', 'User Journey', 'User Stories', 'Fluxos'],
-      ['Dependências', 'Dependencias', 'Dependencies'],
-      ['Compliance'],
-      ['Overview', 'Visão geral', 'Visao geral', 'Resumo'],
-    ],
-  },
-  // morph-plan (spec.md) emits: Arquitetura da solução, Edge cases,
-  // Integrações externas e contratos esperados.
-  'spec.md': {
-    required: [
-      ['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: [
-      ['Overview', 'Visão geral', 'Resumo'],
-      ['Requirements', 'Requisitos'],
-      ['Security', 'Segurança', 'Seguranca'],
-      ['Testing', 'Testes', 'Estratégia de Testes'],
-      ['Performance', 'Desempenho'],
+      ['Bloqueadores', 'Bloqueantes', 'Blockers'],
+      'Checks',
     ],
+    optional: [],
   },
-  // decisions.md follows the ADR convention: an `### ADR-NNN` heading with
-  // `**Status:** / **Context:** / **Decision:**` line-start bold labels.
-  'decisions.md': {
+  'reviewer.md': {
     required: [
-      'ADR',
-      'Status',
-      ['Contexto', 'Context'],
-      ['Decisão', 'Decisao', 'Decision'],
+      ['Verdict', 'Veredito'],
     ],
     recommended: [
-      ['Consequências', 'Consequencias', 'Consequences', 'Implicações', 'Trade-offs', 'Trade-off'],
-    ],
-    optional: [
-      ['Alternativas', 'Alternatives'],
-      ['Custos', 'Costs'],
+      ['Bloqueadores', 'Bloqueantes', 'Blockers'],
     ],
+    optional: [],
   },
-  'review-report.md': {
+  'security.md': {
     required: [
-      ['Veredito', 'Verdict'],
+      ['Verdict', 'Veredito'],
     ],
     recommended: [
       ['Bloqueadores', 'Bloqueantes', 'Blockers'],
@@ -112,51 +37,21 @@ const OUTPUT_SECTIONS = {
   },
 };
 
-/**
- * Phase-to-output mapping (v5 NLH)
- */
 const PHASE_OUTPUTS = {
-  proposal: ['proposal.md'],
+  plan: ['plan.md', 'checks.json'],
   uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
-  plan: ['spec.md', 'tasks.json'],
-  implement: ['recap.md'],
-  review: ['review-report.md'],
+  implement: [],
+  review: ['verifier.md', 'reviewer.md'],
 };
 
-// Work types whose plan phase (see src/core/work-types.js) skips proposal.md/
-// spec.md — chore and hotfix stamp proposal+plan gates at birth
-// (policy-approved, no human deliberation over those docs) and go straight to
-// tasks.json. Validating the full plan doc set against a feature that was
-// never asked to write those docs would be a false failure, not a real gap.
-const LEAN_PLAN_WORK_TYPES = ['chore', 'hotfix'];
-const LEAN_PLAN_OUTPUTS = ['tasks.json'];
-
-/**
- * Phase-to-folder mapping (v5 filesystem convention)
- */
 const PHASE_FOLDERS = {
-  proposal: '0-proposal',
-  uiux: '1-design',
   plan: '2-plan',
+  uiux: '1-design',
   implement: '3-implement',
   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.
- */
+// Line-start bold labels count: reports write `**Verdict:**` as a label, not a heading.
 function extractSectionMarkers(content) {
   const markers = [];
   for (const rawLine of content.split('\n')) {
@@ -174,9 +69,6 @@ function extractSectionMarkers(content) {
   return markers;
 }
 
-/**
- * Validate a single output file
- */
 function validateOutput(featurePath, outputFile) {
   const filePath = path.join(featurePath, outputFile);
   const result = {
@@ -197,22 +89,22 @@ function validateOutput(featurePath, outputFile) {
   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);
+  if (outputFile === 'plan.md') {
+    validatePlanOutput(content, featurePath, result);
+    return result;
+  }
+  if (outputFile === 'checks.json') {
+    validateChecksOutput(content, featurePath, 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`);
   }
@@ -220,40 +112,32 @@ function validateOutput(featurePath, outputFile) {
   return result;
 }
 
-/**
- * Validate tasks.json structurally: parseable JSON + conforms to the schema +
- * has at least one task.
- */
-function validateTasksJsonOutput(content, result) {
-  let data;
+// `planDir` is `.morph/features/{f}/2-plan`, so the project is four levels up.
+function validatePlanOutput(content, planDir, result) {
+  const plan = parsePlan(content);
+  const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(path.resolve(planDir, '..', '..', '..', '..')) });
+  result.errors.push(...errors);
+  result.warnings.push(...warnings);
+  result.sections.found.push(...plan.sections.filter((x) => x.key).map((x) => x.name));
+}
+
+function validateChecksOutput(content, planDir, result) {
+  let doc;
   try {
-    data = JSON.parse(content);
+    doc = JSON.parse(content);
   } catch (err) {
-    result.errors.push(`tasks.json is not valid JSON: ${err.message}`);
+    result.errors.push(`checks.json is not valid JSON: ${err.message}`);
     return;
   }
-  const { valid, errors } = validateTasksJson(data);
-  if (!valid) {
-    for (const e of errors) result.errors.push(e);
+  const planPath = path.join(planDir, 'plan.md');
+  if (!fs.existsSync(planPath)) return;
+  if (doc?.planHash !== planHash(fs.readFileSync(planPath, 'utf8'))) {
+    result.errors.push('checks.json is stale — plan.md changed after it was generated; run `morph-spec plan-check`');
     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)`);
+  result.sections.found.push(`${doc.checks?.length ?? 0} check(s), ${doc.slices?.length ?? 0} slice(s)`);
 }
 
-/**
- * Validate markdown sections against section markers (headings + bold labels).
- *
- * 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.
- *
- *   required    → missing produces an ERROR
- *   recommended → missing produces a WARNING
- *   optional    → tracked when present, never penalized
- */
 function validateMarkdownSections(content, sections, result) {
   const markers = extractSectionMarkers(content);
   const match = (entry) => {
@@ -289,30 +173,17 @@ function validateMarkdownSections(content, sections, result) {
   }
 }
 
-/**
- * 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.
- * @param {string|undefined} workType  Feature's workType (see src/core/work-types.js).
- *   When `phase === 'plan'` and workType is 'chore'/'hotfix', only tasks.json
- *   is required (see LEAN_PLAN_WORK_TYPES above).
- * @returns {{ outputFiles?: Array<{file:string, dir:string}>, error?: string }}
- */
-function resolveOutputFiles(featurePath, phase, workType) {
+function resolveOutputFiles(featurePath, phase) {
   if (phase) {
-    const files = (phase === 'plan' && LEAN_PLAN_WORK_TYPES.includes(workType))
-      ? LEAN_PLAN_OUTPUTS
-      : PHASE_OUTPUTS[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 isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'checks.json';
   const entries = fs.readdirSync(featurePath, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory()) {
@@ -327,23 +198,12 @@ function resolveOutputFiles(featurePath, phase, workType) {
   return { outputFiles };
 }
 
-/**
- * Pure validation core — no console output, no process.exit.
- *
- * @param {string} featurePath  Absolute path to the feature directory.
- * @param {{ phase?: string, workType?: string }} [options]
- * @returns {{
- *   feature: string, phase: string, valid: boolean, error?: string,
- *   totalErrors: number, totalWarnings: number, totalFound: number,
- *   results: object[]
- * }}
- */
+/** Pure core: no console output, no process.exit. */
 export function runFeatureValidation(featurePath, options = {}) {
   const phase = options.phase || null;
-  const workType = options.workType || null;
   const feature = path.basename(featurePath);
 
-  const { outputFiles, error } = resolveOutputFiles(featurePath, phase, workType);
+  const { outputFiles, error } = resolveOutputFiles(featurePath, phase);
   if (error) {
     return {
       feature,
@@ -373,9 +233,6 @@ export function runFeatureValidation(featurePath, options = {}) {
   };
 }
 
-/**
- * Main validate command (CLI wrapper around `runFeatureValidation`)
- */
 export async function validateFeatureCommand(featureName, options = {}) {
   if (!featureName) {
     console.error(chalk.red('Error: Feature name required'));
@@ -397,25 +254,10 @@ export async function validateFeatureCommand(featureName, options = {}) {
     process.exit(1);
   }
 
-  // workType is read straight off the feature's own feature.json (not via
-  // state-manager's getFeature/loadState) so a broken/missing root state.json
-  // elsewhere in the project can never make `validate` itself throw — it just
-  // falls back to the full (non-lean) output set, same as today.
-  let workType;
-  try {
-    const fjPath = path.join(featurePath, 'feature.json');
-    if (fs.existsSync(fjPath)) {
-      workType = JSON.parse(fs.readFileSync(fjPath, 'utf8')).workType;
-    }
-  } catch {
-    workType = undefined;
-  }
-
-  const validation = runFeatureValidation(featurePath, { phase, workType });
+  const validation = runFeatureValidation(featurePath, { phase });
   const { results, totalErrors, totalWarnings, totalFound } = validation;
-  const schemaWarnings = []; // v5: cross-validation removed (contracts in spec.md)
+  const schemaWarnings = [];
 
-  // JSON output mode
   if (options.json) {
     const output = {
       feature: featureName,
@@ -442,7 +284,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
     return;
   }
 
-  // Visual output
   console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
   console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
   console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
@@ -451,7 +292,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
   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 ? '✅' : '❌')
@@ -462,25 +302,21 @@ export async function validateFeatureCommand(featureName, options = {}) {
 
     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}`));
     });
   }
 
-  // Summary
   console.log('');
   console.log(chalk.gray('─'.repeat(60)));