@polymorphism-tech/morph-spec 8.22.0 → 8.23.0

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

@@ -0,0 +1,198 @@
+/**
+ * traceability-check.js — advisory, feature-scope-only check: do the files
+ * cited in recap.md's "**Files:**" bullet lists have an owning task in
+ * tasks.json's `outputs`?
+ *
+ * This is the DETERMINISTIC half of a two-layer fix. The NLH half lives in
+ * `framework/skills/core/morph-implement/SKILL.md` §7 ("outputs DEVE listar
+ * TODO arquivo criado ou modificado pela task") and targets the root cause: a
+ * file shipped without EVER being declared anywhere (not in outputs, not in
+ * recap.md — the real-world case that motivated this module, see the finding
+ * below). This module cannot catch THAT class of drift — a file absent from
+ * both documents is invisible to a check that only compares the two documents
+ * against each other. What it DOES catch is a narrower, complementary class:
+ * recap.md and tasks.json DISAGREEING — an author cited a file in the recap's
+ * prose but forgot (or a later task re-touched it without) declaring it in any
+ * task's `outputs`. That disagreement is real signal even though it is not the
+ * same defect the SKILL.md rule targets.
+ *
+ * Motivating evidence: run 2026-08-12T133732Z-vet-visit-followup-reminder —
+ * `ApplicationDbContextFactory.cs` shipped in production with no owning task
+ * in `outputs` AND no mention in recap.md (out of this module's reach by
+ * construction). Separately, `src/VetClinic.Api/appsettings.json` and
+ * `Properties/launchSettings.json` WERE cited in T1's recap `**Files:**` list
+ * but never appear in any task's `outputs` — exactly the disagreement this
+ * module flags.
+ *
+ * Advisory, never blocking: the returned `status` is only ever 'pass' | 'warn'
+ * | 'skip' — never 'fail'. `runVerify()` keeps this result OUTSIDE `nodes` on
+ * purpose so it can never flip the overall build/tests/validators/e2e status
+ * computed from `nodes` alone (see verify-runner.js).
+ *
+ * Fail-open throughout: no recap.md, no tasks.json, or a parse error all
+ * degrade to `{ status: 'skip' }` rather than throwing or warning about the
+ * absence itself — this is rastreabilidade tooling, not a completeness gate.
+ *
+ * @module traceability-check
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+/** Matches a `**Files:**` marker followed by one or more `- ` bullet lines. */
+const FILES_BLOCK_RE = /\*\*Files:\*\*[ \t]*\r?\n((?:^[ \t]*-[ \t].*\r?\n?)+)/gm;
+
+/** Backtick-quoted spans within a bullet line. */
+const BACKTICK_RE = /`([^`]+)`/g;
+
+/**
+ * Extract the set of file paths cited under every "**Files:**" block in a
+ * recap.md's text, applying a conservative decomposition of the natural
+ * language shorthand real recaps use:
+ *
+ *   - A line with exactly one backtick span: that span is a candidate,
+ *     whether or not it contains a `/` (a legitimate top-level file, e.g.
+ *     `` `VetClinic.sln` ``, has no slash).
+ *   - A line with multiple comma-separated backtick spans (e.g.
+ *     `` `a/b.json`, `c.json`, `d/e.json` ``): only the FIRST span and any
+ *     LATER span that itself contains `/` are candidates. A later span with
+ *     no `/` is ambiguous shorthand (a bare filename implicitly relative to
+ *     the first span's directory, or a suffix like `` `.Designer.cs` ``) and
+ *     is skipped rather than guessed — false negatives are the acceptable
+ *     failure mode for advisory tooling, false positives are not.
+ *   - Any span containing `{`/`}` (brace-expansion shorthand, e.g.
+ *     `` `Foo/{A,B,C}.cs` ``) is skipped entirely — decomposing it correctly
+ *     would require guessing at delimiters this format doesn't standardize.
+ *   - Any span ending in `/` is a directory reference, not a file — skipped.
+ *
+ * @param {string} recapText
+ * @returns {string[]} de-duplicated, normalized (forward-slash) candidate paths
+ */
+export function extractCitedFiles(recapText) {
+  const cited = new Set();
+  if (!recapText) return [];
+
+  FILES_BLOCK_RE.lastIndex = 0;
+  let blockMatch;
+  while ((blockMatch = FILES_BLOCK_RE.exec(recapText)) !== null) {
+    const block = blockMatch[1];
+    const lines = block.split(/\r?\n/).filter((l) => /^[ \t]*-[ \t]/.test(l));
+
+    for (const line of lines) {
+      const spans = [...line.matchAll(BACKTICK_RE)].map((m) => m[1].trim()).filter(Boolean);
+      spans.forEach((span, idx) => {
+        if (idx > 0 && !span.includes('/')) return; // ambiguous shorthand continuation
+        if (span.includes('{') || span.includes('}')) return; // brace-expansion, too ambiguous to decompose
+        if (span.endsWith('/')) return; // directory reference, not a file
+        cited.add(normalizePath(span));
+      });
+    }
+  }
+
+  return [...cited];
+}
+
+/** Backslashes to forward slashes, strip a leading `./`. */
+function normalizePath(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * Union of `outputs` across every `done` task in tasks.json, normalized.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {string[]|null} null when tasks.json is missing/unreadable/invalid
+ *   (the caller treats null as "cannot judge coverage" and skips, not warns)
+ */
+export function collectDoneOutputs(projectPath, featureName) {
+  let tasksPath;
+  try {
+    tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+  } catch {
+    return null;
+  }
+  if (!existsSync(tasksPath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(tasksPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const outputs = [];
+  for (const task of tasks) {
+    if (task?.status !== 'done') continue;
+    for (const output of task.outputs || []) {
+      if (typeof output === 'string' && output.trim()) outputs.push(normalizePath(output));
+    }
+  }
+  return outputs;
+}
+
+/**
+ * A cited file is covered if some done task's `outputs` names it exactly, or
+ * names a directory (an entry ending in `/`) that the cited file falls under.
+ *
+ * @param {string} file
+ * @param {string[]} outputs
+ * @returns {boolean}
+ */
+function isCovered(file, outputs) {
+  for (const output of outputs) {
+    if (output === file) return true;
+    if (output.endsWith('/') && file.startsWith(output)) return true;
+  }
+  return false;
+}
+
+/**
+ * Run the recap-vs-outputs 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) {
+  let recapPath;
+  try {
+    recapPath = getAbsoluteOutputPath(projectPath, featureName, 'recap');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'unknown feature', citedCount: 0 };
+  }
+
+  if (!existsSync(recapPath)) {
+    return { status: 'skip', warnings: [], reason: 'no recap.md', citedCount: 0 };
+  }
+
+  let recapText;
+  try {
+    recapText = readFileSync(recapPath, 'utf8');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'recap.md unreadable', citedCount: 0 };
+  }
+
+  const cited = extractCitedFiles(recapText);
+  if (cited.length === 0) {
+    return { status: 'skip', warnings: [], reason: 'no Files: entries found in recap.md', citedCount: 0 };
+  }
+
+  const outputs = collectDoneOutputs(projectPath, featureName);
+  if (outputs === null) {
+    return { status: 'skip', warnings: [], reason: 'no tasks.json', citedCount: cited.length };
+  }
+
+  const warnings = cited
+    .filter((file) => !isCovered(file, outputs))
+    .sort()
+    .map((file) => `${file} — cited in recap.md but not listed in any done task's outputs`);
+
+  return {
+    status: warnings.length > 0 ? 'warn' : 'pass',
+    warnings,
+    reason: null,
+    citedCount: cited.length,
+  };
+}

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

@@ -31,6 +31,7 @@ import { buildComposeEnv } from '../e2e/compose-env.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
+import { checkOutputsTraceability } from './traceability-check.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 
 /** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
@@ -56,6 +57,7 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
  * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
+ * @param {Function} [options._checkOutputsTraceability] - Injectable override for checkOutputsTraceability (testing)
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
@@ -70,6 +72,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
     _runE2eCheck = runE2eCheck,
+    _checkOutputsTraceability = checkOutputsTraceability,
   } = options;
 
   const stack = readStack(projectPath);
@@ -105,6 +108,16 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   });
   appendE2eFeedback(feedback, nodes.e2e);
 
+  // 5. traceability — advisory-only, feature-scope only (see traceability-check.js
+  // for the recap-vs-outputs disagreement it flags, and what it deliberately
+  // cannot catch). Lives OUTSIDE `nodes` on purpose: `status` below is computed
+  // from `nodes` alone, so this can never flip build/tests/validators/e2e green
+  // to red — recap/outputs disagreement is a rastreabilidade signal, not a
+  // correctness gate.
+  const traceability = taskId
+    ? { status: 'skip', warnings: [], reason: 'task-scoped verify does not run traceability', citedCount: 0 }
+    : _checkOutputsTraceability(projectPath, featureName);
+
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
   return {
@@ -117,6 +130,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     status,
     nodes,
     feedback,
+    traceability,
   };
 }