@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/validators/traceability-check.js

@@ -1,55 +1,17 @@
-/**
- * traceability-check.js — advisory, feature-scope-only check: do the files
- * cited under `**Arquivos:**` in the slice reports (`3-implement/reports/F{n}.md`)
- * belong to some slice of the plan (its `arquivos:`, as extracted by plan-check)?
- *
- * It catches the reports and the plan DISAGREEING: a file the implementation
- * says it touched that no slice declared. A file absent from both documents
- * is invisible to it by construction — that drift is the reuse/contract
- * reviewer's job.
- *
- * Advisory, never blocking: `status` is only ever 'pass' | 'warn' | 'skip'.
- * `runVerify()` keeps this result OUTSIDE `nodes` so it can never flip the
- * overall build/tests/validators/e2e status.
- *
- * Fail-open throughout: no slice report, no extracted plan or a parse error
- * all degrade to `{ status: 'skip' }`.
- *
- * @module traceability-check
- */
+// Advisory: status is only 'pass' | 'warn' | 'skip', and runVerify() keeps it outside
+// `nodes` so it never flips the verify rollup.
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { readPlanChecks } from '../plan/checks.js';
 import { sliceProgress, sliceReportPath } from '../../../framework/hooks/shared/slice-progress.js';
 
-/**
- * An `**Arquivos:**` marker and what follows it: the rest of its own line
- * (inline list) plus any `- ` bullet lines right below.
- */
 const FILES_BLOCK_RE = /\*\*Arquivos:\*\*([^\r\n]*)\r?\n?((?:^[ \t]*-[ \t].*\r?\n?)*)/gm;
 
-/** Backtick-quoted spans within a line. */
 const BACKTICK_RE = /`([^`]+)`/g;
 
-/**
- * Extract the set of file paths cited under every `**Arquivos:**` marker of a
- * slice report, applying a conservative decomposition of the shorthand real
- * reports use:
- *
- *   - A line with exactly one backtick span: that span is a candidate,
- *     whether or not it contains a `/`.
- *   - A line with several comma-separated spans: only the FIRST span and any
- *     LATER span that itself contains `/` are candidates. A later span with
- *     no `/` is ambiguous shorthand and is skipped rather than guessed —
- *     false negatives are acceptable for advisory tooling, false positives
- *     are not.
- *   - Any span containing `{`/`}` (brace expansion) is skipped.
- *   - Any span ending in `/` is a directory reference, not a file — skipped.
- *
- * @param {string} reportText
- * @returns {string[]} de-duplicated, normalized (forward-slash) candidate paths
- */
+// A later span without `/` is ambiguous shorthand and is skipped, not guessed: false
+// negatives are acceptable for advisory tooling, false positives are not.
 export function extractCitedFiles(reportText) {
   const cited = new Set();
   if (!reportText) return [];
@@ -72,16 +34,11 @@ export function extractCitedFiles(reportText) {
   return [...cited];
 }
 
-/** Backslashes to forward slashes, strip a leading `./`. */
 export function normalizePath(p) {
   return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
 }
 
-/**
- * Union of the `arquivos:` of every slice of the plan, normalized.
- *
- * @returns {string[]|null} null when the plan has no readable extraction
- */
+/** null when the plan has no readable extraction. */
 export function collectSliceFiles(projectPath, featureName) {
   const checks = readPlanChecks(projectPath, featureName).checks;
   if (!checks) return null;
@@ -90,14 +47,6 @@ export function collectSliceFiles(projectPath, featureName) {
     .map(normalizePath));
 }
 
-/**
- * A cited file is covered if some slice names it exactly, or names a
- * directory (an entry ending in `/`) that the cited file falls under.
- *
- * @param {string} file
- * @param {string[]} declared
- * @returns {boolean}
- */
 function isCovered(file, declared) {
   for (const entry of declared) {
     if (entry === file) return true;
@@ -114,13 +63,6 @@ function readOrNull(path) {
   }
 }
 
-/**
- * Run the reports-vs-slices traceability check for a feature.
- *
- * @param {string} projectPath
- * @param {string} featureName
- * @returns {{ status: 'pass'|'warn'|'skip', warnings: string[], reason: string|null, citedCount: number }}
- */
 export function checkOutputsTraceability(projectPath, featureName) {
   const featureDir = join(projectPath, '.morph', 'features', featureName);
   const progress = sliceProgress(featureDir);

package/src/lib/validators/validation-runner.js

@@ -1,12 +1,3 @@
-/**
- * MORPH-SPEC Validation Runner
- *
- * Unified orchestrator that runs the right validators based on the project's
- * stack profile. Called by task-done before marking tasks complete.
- *
- * MORPH-SPEC 3.0 - Phase A: Active Validation Pipeline
- */
-
 import { existsSync } from 'fs';
 import chalk from 'chalk';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../core/paths/output-schema.js';
@@ -18,14 +9,8 @@ const HEAVY_VALIDATORS = new Set([
 ]);
 
 /**
- * Run all relevant validators for a feature
- *
- * @param {string} projectPath - Project root path
- * @param {string} featureName - Feature name from state.json
- * @param {Object} options - Options
- * @param {boolean} options.verbose - Show detailed output
- * @param {string[]} options.validators - Specific validators to run (overrides stack-based detection)
- * @returns {Object} { passed, errors, warnings, issues, summary }
+ * @param {string[]} [options.validators] - overrides stack-based detection
+ * @returns {Object} { passed, errors, warnings, issues, summary, results, skipped, _skipReason? }
  */
 export async function runValidation(projectPath, featureName, options = {}) {
   const result = {
@@ -34,24 +19,13 @@ export async function runValidation(projectPath, featureName, options = {}) {
     warnings: 0,
     issues: [],
     summary: '',
-    results: {} // Per-validator results for hooks integration
+    results: {}
   };
 
-  // Decision constraints support (stub - decision-constraint-loader removed as orphaned code)
-  const constraints = {
-    enabledValidators: [], // No constraint-based validators
-    validators: {} // No validator-specific constraints
-  };
-
-  // Determine which validators to run.
-  // COPY: the mode filter below used to splice in place, and when the caller
-  // passed `options.validators` that array WAS this array — so a light run
-  // emptied the caller's own list, and running the same list twice validated
-  // less the second time.
+  // A copy: filtering in place would empty the caller's own `options.validators`.
   const detected = options.validators || detectValidators(projectPath);
   let validatorIds = [...detected];
 
-  // Filter by mode: 'light' skips heavy validators, 'full' (default) runs all
   const mode = options.mode || 'full';
   const droppedByMode = [];
   if (mode === 'light') {
@@ -61,35 +35,17 @@ export async function runValidation(projectPath, featureName, options = {}) {
     });
   }
 
-  // Merge constraint-enabled validators
-  validatorIds.push(...constraints.enabledValidators);
-
-  // Reuse is stack-agnostic: "isto já existe?" é a mesma pergunta em C# e em
-  // TypeScript, e o validador se cala sozinho quando não há grafo (ADR-002).
-  // Por isso ele não entra no `defaultValidators` de stack profile nenhum —
-  // entra aqui, ANTES do early-return de "nenhum validador": num projeto de
-  // stack `empty`/`nodejs-cli` não há outro validador para carregá-lo, e é
-  // exatamente lá que ele seria a única verificação a rodar.
-  // Em `light` (checkpoint) ele fica de fora, como todo validador pesado — é
-  // uma leitura de graph.json (11-24 MB nos repos medidos) — e por isso está
-  // em HEAVY_VALIDATORS, que é onde essa política se declara. Não entra em
-  // `droppedByMode`: essa lista responde "o que o modo tirou da SUA lista", e
-  // é ela que distingue "light pulou os pesados" de "este stack não tem
-  // validador nenhum" na mensagem final.
+  // Stack-agnostic validators join here, before the "no validators" early return:
+  // on an `empty`/`nodejs-cli` stack they are the only check. Not in `droppedByMode`,
+  // which only lists what light mode removed from the stack's own list.
   if (!options.skipReuse && mode !== 'light') {
     validatorIds.push('reuse');
   }
-  // Mesma política, pelo mesmo motivo: comentário e orçamento de teste valem
-  // em qualquer stack, e a medida é da feature, não de um checkpoint.
   if (mode !== 'light') {
     validatorIds.push('code-budget');
   }
 
   if (validatorIds.length === 0) {
-    // Say which of the two it is. On a pure `dotnet` project every default
-    // validator is heavy, so a light run legitimately runs none — but the old
-    // message blamed the stack ("no validators configured"), which reads as
-    // "your stack has nothing to check" when the full run has two.
     result.summary = droppedByMode.length > 0
       ? `No validators ran — light mode skipped ${droppedByMode.length} heavy validator(s): ${droppedByMode.join(', ')}`
       : 'No validators ran — no validators configured for this stack';
@@ -99,49 +55,29 @@ export async function runValidation(projectPath, featureName, options = {}) {
     return result;
   }
 
-  // Always show what's running (even non-verbose) — helps confirm validators are active
   console.log(chalk.gray(`\n  Running ${validatorIds.length} validator(s): ${validatorIds.join(', ')}`));
-  if (constraints.enabledValidators.length > 0) {
-    console.log(chalk.gray(`  (+ ${constraints.enabledValidators.length} from decisions)`));
-  }
 
-  // Always run contract compliance if the contracts file exists (stack-aware)
   if (!options.skipContracts) {
     const _profileForContracts = getStackProfile(projectPath);
     const contractsType = resolveContractsOutputType(_profileForContracts.stack);
     const contractsPath = getAbsoluteOutputPath(projectPath, featureName, contractsType);
-    // Positive check on isDotnet (contract-compliance is a VSA/.NET concern) —
-    // NOT `!isNextjs`, which used to wrongly suppress it for a compound
-    // "dotnet-nextjs" stack that has a .NET backend but is ALSO isNextjs.
-    // `mode: 'light'` has to hold here too. This push sits AFTER the mode
-    // filter, so contract-compliance — which is in HEAVY_VALIDATORS — used to
-    // slip into every light run that had a contracts file, making light mode
-    // heavier than declared on exactly the compound stacks it matters for.
+    // Positive `isDotnet`, not `!isNextjs`: a "dotnet-nextjs" stack is both. This push
+    // sits after the mode filter, so light mode has to be honored again here.
     const contractsIsHeavyAndSkipped = mode === 'light' && HEAVY_VALIDATORS.has('contract-compliance');
     if (existsSync(contractsPath) && _profileForContracts.isDotnet && !contractsIsHeavyAndSkipped) {
       validatorIds.push('contract-compliance');
     }
   }
 
-  // Deduplicate
   const uniqueValidators = [...new Set(validatorIds)];
 
-  // Validadores que rodaram mas se declararam inaplicáveis (ex.: `reuse` num
-  // projeto sem grafo). Um validador assim não acha nada — e "não achou nada"
-  // é indistinguível de "verificou e está limpo" se ninguém contar.
+  // A validator that declared itself inapplicable found nothing, which is not "clean".
   const selfSkipped = [];
   result.skipped = selfSkipped;
 
-  // Run each validator
   for (const validatorId of uniqueValidators) {
     try {
-      // Pass validator-specific constraints from decisions.md
-      const validatorOptions = {
-        ...options,
-        constraints: constraints.validators[validatorId] || {}
-      };
-
-      const validatorResult = await runSingleValidator(validatorId, projectPath, featureName, validatorOptions);
+      const validatorResult = await runSingleValidator(validatorId, projectPath, featureName, options);
 
       if (validatorResult) {
         if (validatorResult._skipReason) {
@@ -156,8 +92,6 @@ export async function runValidation(projectPath, featureName, options = {}) {
         result.warnings += warnings;
         result.issues.push(...issues);
 
-        // A validator that skipped itself checked nothing: in `results` it would
-        // read as a validator that ran clean.
         if (!validatorResult._skipReason) result.results[validatorId] = { passed: errors === 0, issues };
       }
     } catch (err) {
@@ -178,10 +112,7 @@ export async function runValidation(projectPath, featureName, options = {}) {
     }
   }
 
-  // Todos os validadores se declararam inaplicáveis: o resultado é SKIP, não um
-  // verde. Sem isto, um projeto de stack sem validadores e sem grafo receberia
-  // `validators: pass` do `morph-spec verify` tendo verificado exatamente nada
-  // — o modo de falha que este repositório já pagou caro (guardrail inerte).
+  // Every validator self-skipped: SKIP, never a green over nothing checked.
   if (selfSkipped.length > 0 && selfSkipped.length === uniqueValidators.length) {
     result._skipReason = `No validators ran — ${selfSkipped.map((s) => `${s.validator}: ${s.reason}`).join('; ')}`;
     result.summary = result._skipReason;
@@ -196,44 +127,20 @@ export async function runValidation(projectPath, featureName, options = {}) {
   return result;
 }
 
-/**
- * Detect which validators to run, driven by the project's stack profile.
- * @param {string} projectPath - Project root path (default: current directory)
- * @returns {string[]} Array of validator IDs to run
- */
 function detectValidators(projectPath = '.') {
   const profile = getStackProfile(projectPath);
   return [...profile.defaultValidators];
 }
 
 /**
- * Reduce any validator's return value to the runner's contract:
- * `{ errors, warnings, issues }`.
- *
- * Validators were written at different times and return different shapes. The
- * runner used to read `errors`/`warnings`/`issues` off the raw object, so a
- * validator that reports through any other shape contributed ZERO — and since
- * `passed = errors === 0`, its findings were recorded as a pass. Measured: of
- * seven validators only two returned all three keys. `packages` — one of the
- * two defaults for the `dotnet` stack — returned
- * `{status, totalFiles, filesWithIssues, results}` and had every NuGet
- * incompatibility it found thrown away, while `verify` reported green.
- *
- * Reading the nested `results` shape here keeps that contract in ONE place
- * instead of asking every validator to remember it.
- *
- * @param {string} validatorId
- * @param {Object} raw - whatever the validator returned
- * @returns {{errors: number, warnings: number, issues: Array}}
+ * Reduce any validator's return shape to `{ errors, warnings, issues }`, so a
+ * validator reporting through nested `results` never contributes zero and reads as a pass.
  */
 export function normalizeValidatorResult(validatorId, raw) {
   if (!raw || typeof raw !== 'object') return { errors: 0, warnings: 0, issues: [] };
 
-  // Issues can be top-level, or nested one level under `results` — either as
-  // an array of `{issues}` (packages: one entry per .csproj) or an object of
-  // them keyed by check name. The nested read is a FALLBACK,
-  // never additive: validators that expose both would otherwise report every
-  // finding twice.
+  // The nested read is a FALLBACK, never additive: validators exposing both
+  // shapes would otherwise report every finding twice.
   const topLevel = Array.isArray(raw.issues) ? raw.issues : [];
   const nested = raw.results && typeof raw.results === 'object'
     ? (Array.isArray(raw.results) ? raw.results : Object.values(raw.results))
@@ -242,8 +149,7 @@ export function normalizeValidatorResult(validatorId, raw) {
   const issues = (topLevel.length ? topLevel : nested)
     .map(i => ({ validator: validatorId, ...i }));
 
-  // Prefer the validator's own counts when it reports them — it may weigh
-  // issues differently than one-each. Otherwise derive from the issue levels.
+  // The validator's own counts win: it may weigh issues differently than one-each.
   const counted = {
     errors: issues.filter(i => i.level === 'error').length,
     warnings: issues.filter(i => i.level === 'warning').length,
@@ -251,8 +157,7 @@ export function normalizeValidatorResult(validatorId, raw) {
   const errors = Number.isFinite(raw.errors) ? raw.errors : counted.errors;
   const warnings = Number.isFinite(raw.warnings) ? raw.warnings : counted.warnings;
 
-  // Last resort: a validator that says `status: 'error'` but exposes no
-  // countable detail still must not read as a pass.
+  // `status: 'error'` with no countable detail still must not read as a pass.
   if (errors === 0 && raw.status === 'error') {
     return {
       errors: 1,
@@ -268,9 +173,6 @@ export function normalizeValidatorResult(validatorId, raw) {
   return { errors, warnings, issues };
 }
 
-/**
- * Run a single validator by ID
- */
 async function runSingleValidator(validatorId, projectPath, featureName, options) {
   switch (validatorId) {
     case 'packages': {
@@ -299,11 +201,8 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
     }
 
     default:
-      // A warning, not silence: an id with no case runs nothing, and returning
-      // a bare null made that indistinguishable from a validator that ran and
-      // found nothing. A typo in a validator list would have read as a clean
-      // pass. Not an error — an unknown id is a configuration mistake, not a
-      // defect in the code under validation.
+      // A warning, not silence (a typo would read as a clean pass) and not an
+      // error (a config mistake, not a defect in the code under validation).
       if (options.verbose) {
         console.log(chalk.gray(`  Unknown validator: ${validatorId}`));
       }
@@ -320,9 +219,6 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
   }
 }
 
-/**
- * Format validation results for console output
- */
 export function formatValidationResults(result) {
   if (result.passed && result.warnings === 0) {
     const ranCount = Object.keys(result.results || {}).length;
@@ -337,7 +233,6 @@ export function formatValidationResults(result) {
     console.log(chalk.red(`\n  ❌ Validation FAILED: ${result.errors} error(s), ${result.warnings} warning(s)\n`));
   }
 
-  // Group issues by level
   const errors = result.issues.filter(i => i.level === 'error');
   const warnings = result.issues.filter(i => i.level === 'warning');