@polymorphism-tech/morph-spec 8.35.1 → 8.37.0

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

@@ -15,6 +15,7 @@
  *   - runBuildCheck()  from framework/hooks/shared/build-check.js
  *   - runTestSuite()      from src/lib/tasks/test-runner.js (one node)
  *   - resolveTestNodes()  from src/lib/tasks/test-nodes.js (the LIST of suites)
+ *   - applyTaskScope()    from src/lib/tasks/test-scope.js (the task-scoped cut, #87)
  *   - runValidation()  from ./validation-runner.js
  *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
  *   - loadRubric() + aggregateScores() from ./score-aggregator.js
@@ -23,16 +24,19 @@
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, rmSync } from 'fs';
 import { join, resolve } from 'path';
 
 import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
 import { runE2eCheck } from '../../../framework/hooks/shared/e2e-check.js';
 import { buildComposeEnv } from '../e2e/compose-env.js';
-import { runTestSuite, parseTestCount, compareTestCount, resolveTestTimeout } from '../tasks/test-runner.js';
+import {
+  runTestSuite, parseTestCount, compareTestCount, resolveTestTimeout, isZeroTestRun, mtpSummaryTotals,
+} from '../tasks/test-runner.js';
 import {
   resolveTestNodes, parseTestFilter, nodeMatchesFilter, recordTestBaselines, morphConfigPath,
 } from '../tasks/test-nodes.js';
+import { applyTaskScope } from '../tasks/test-scope.js';
 import { runLinuxSuite, checkLinuxPreconditions } from '../tasks/linux-runner.js';
 import {
   EVAL_RUNNER, evalPreflight, evalNodeEnv, readEvalSummary, evalScenarioCount,
@@ -50,6 +54,14 @@ const DEFAULT_BUILD_TIMEOUT = 120_000;
 /** Number of trailing output lines kept for feedback/reporting. */
 const OUTPUT_TAIL_LINES = 20;
 
+/** A narrowed run that proved ZERO tests ran (#87) — wording pinned by the plan. */
+const NARROWED_ZERO_TESTS = 'narrowed-zero-tests: o recorte executou 0 testes';
+const NARROWED_ZERO_TESTS_LINK = 'narrowed-zero-tests: um link do recorte executou 0 testes (bloco MTP com total: 0)';
+
+/** A narrowed run that exited green with no count anyone could read (#87): null is UNKNOWN, and unknown is never green. */
+const NARROWED_COUNT_UNKNOWN = 'narrowed-count-unknown: o recorte saiu verde sem contagem legível — '
+  + 'nada prova que algum teste rodou (desconhecido nunca vira verde)';
+
 /**
  * The caller asked for something impossible — not a red verification, a wrong
  * invocation. The distinction is the exit code: `verify` answers 1 for "the
@@ -86,6 +98,8 @@ export class VerifyUsageError extends Error {
  * @param {boolean} [options.linux] - Run the test nodes inside a Linux container, on a COPY
  *   of the tree (see linux-runner.js for why a bind mount would prove nothing)
  * @param {string} [options.linuxImage] - Image override for --linux
+ * @param {boolean} [options.full] - Task scope only: switch the recorte off and run every
+ *   node whole (#87). A documented no-op at feature scope, which never narrows anything.
  * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
@@ -105,6 +119,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     refreshCache = false,
     linux = false,
     linuxImage = null,
+    full = false,
     _runLinuxSuite = runLinuxSuite,
     _exec = undefined,
     _runBuildCheck = runBuildCheck,
@@ -130,13 +145,18 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     );
   }
 
+  // The task is read ONCE: its group picks the rubric and the e2e
+  // applicability and, with its outputs, the test scope (#87). One reader of
+  // tasks.json for verify, so the three can never disagree about the task.
+  const task = taskId ? readTask(projectPath, featureName, taskId) : null;
+
   // `--record-baseline` is judged in the same breath, and for the same reason:
   // discovering that there is nowhere to write AFTER running the whole fleet
   // would charge the user a full suite for a usage error. `config.json` is
   // never created here — this repository deliberately has none, and inventing
   // one would break `doctor --full`.
   if (recordBaseline) {
-    const problem = baselineTargetProblem(projectPath, testPlan, { skipTests });
+    const problem = baselineTargetProblem(projectPath, testPlan, { skipTests, taskId });
     if (problem) throw new VerifyUsageError(problem);
   }
 
@@ -175,6 +195,16 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     }
   }
 
+  // #87: at task scope the task's group picks the nodes and its outputs narrow
+  // the command inside each; test-scope.js DECIDES, this runner executes. The
+  // scoping happens ONCE, here, before runTestsNode, so the host loop and the
+  // `--linux` container receive the SAME scoped nodes (the container script is
+  // written from `node.command`) and preDecideRun/judgeRun stay the single copy
+  // of each rule for both. `--filter` was judged above on the ORIGINAL ids: a
+  // typo is a typo whatever the task. Feature scope gets the nodes back
+  // unchanged, because Gate 3 always runs every suite, whole.
+  const scoped = applyTaskScope({ projectPath, nodes: testPlan.nodes, task, taskId, filter, full });
+
   const nodes = {};
   const feedback = [];
 
@@ -190,7 +220,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   const explicitTimeout = Number.isFinite(options.timeout) ? options.timeout : undefined;
   nodes.tests = await runTestsNode({
     projectPath,
-    testPlan,
+    testPlan: { ...testPlan, nodes: scoped.nodes },
     filter,
     skipTests,
     buildNode: nodes.build,
@@ -203,10 +233,14 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     _runLinuxSuite,
     _exec,
   });
+  // How the nodes were chosen, for whoever reads --json. It lives on the rollup
+  // and nowhere else: nodeStatuses() (verify.js) persists status strings only,
+  // so no part of the selection ever reaches feature.json.
+  nodes.tests.scope = scoped.summary;
   appendTestsFeedback(feedback, nodes.tests);
 
   // 3. validators — ALWAYS runs, even on a red build (free static feedback).
-  const rubricId = resolveRubricId({ projectPath, featureName, taskId, rubricOverride });
+  const rubricId = resolveRubricId({ task, rubricOverride, projectPath });
   nodes.validators = await runValidatorsNode({ projectPath, featureName, rubricId, _runValidation });
   appendValidatorsFeedback(feedback, nodes.validators);
 
@@ -217,6 +251,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     projectPath,
     featureName,
     taskId,
+    task,
     skipE2e,
     freshE2e,
     buildNode: nodes.build,
@@ -356,7 +391,8 @@ async function runTestsNode({
  * Run the executable nodes inside ONE Linux container and judge them with the
  * SAME rules the local path uses.
  *
- * The pre-decisions (invalid config, `--filter`, an e2e node at task scope)
+ * The pre-decisions (invalid config, `--filter`, a node outside the task
+ * scope, an e2e node at task scope)
  * happen HERE, before the container exists: a node that must not run must not
  * be written into the container script either, or the flag would quietly run
  * what the user filtered out. What the container returns — an exit code and an
@@ -434,14 +470,27 @@ async function runOneTestNode({
   const evalChannel = node.runner === EVAL_RUNNER
     ? evalNodeEnv(node, projectPath, { refresh: refreshCache })
     : null;
+  // The summary path is fixed per node id and pid, and nothing else removes the
+  // file: one left there by an earlier run (an earlier verify in the same
+  // process, a recycled pid) was read as THIS run's, handing a harness that
+  // wrote nothing the old scenario count — and hiding an empty run behind it.
+  if (evalChannel) discardFile(evalChannel.summaryPath);
 
   const start = Date.now();
   const result = await _runTestSuite(projectPath, {
     timeout, node, ...(evalChannel ? { env: evalChannel.env } : {}),
   });
   const entry = judgeRun({ node, result, durationMs: Date.now() - start });
+  if (!evalChannel) return entry;
 
-  return evalChannel ? judgeEvalRun(entry, node, evalChannel.summaryPath) : entry;
+  const judged = judgeEvalRun(entry, node, evalChannel.summaryPath);
+  discardFile(evalChannel.summaryPath);
+  return judged;
+}
+
+/** Remove a scratch file the CLI owns; a file that is not there (or will not go) changes nothing. */
+function discardFile(path) {
+  try { rmSync(path, { force: true }); } catch { /* best effort — the next run removes it first */ }
 }
 
 /**
@@ -449,10 +498,12 @@ async function runOneTestNode({
  * code said.
  *
  * Two things the exit code cannot see:
- *   - the scenario COUNT, which is what `expectedCount` is compared against.
- *     The summary wins when readable; otherwise the `dotnet` extractor's number
- *     stands, because an eval IS `dotnet test`. **null stays UNKNOWN, never 0** —
- *     an unreadable summary must not manufacture a count drop;
+ *   - the scenario COUNT, which is what `expectedCount` is compared against and
+ *     what `--record-baseline` writes. Read ONLY from the summary: the `dotnet`
+ *     extractor counts xunit cases, another unit — compared with (or recorded as)
+ *     a scenario baseline it failed green runs as drops (#110, #117 review). No
+ *     readable summary → **null, UNKNOWN, never 0** — an unreadable summary must
+ *     not manufacture a count drop;
  *   - a suite that evaluated ZERO scenarios and exited 0. Nothing failed, because
  *     nothing ran: the guardrail-inert shape this repository has already paid to
  *     learn to detect.
@@ -464,8 +515,7 @@ function judgeEvalRun(entry, node, summaryPath) {
   const cold = evalColdCacheWarning(summary);
   if (cold) warnings.push(cold);
 
-  const fromSummary = evalScenarioCount(summary);
-  const count = fromSummary ?? entry.count;
+  const count = evalScenarioCount(summary);
   const verdict = compareTestCount(count, node.expectedCount);
   if (verdict.warning) warnings.push(verdict.warning);
 
@@ -508,6 +558,11 @@ function emptyRunEntry(node) {
     reason: null,
     warnings: [],
     output: '',
+    // What the task-scope recorte did to this node (#87): `command` above is
+    // what actually ran, `selection.declaredCommand` what was declared. null at
+    // feature scope, where applyTaskScope leaves the key ABSENT; absent is read
+    // as null here so no reader has to tell the two apart.
+    selection: node.selection ?? null,
   };
 }
 
@@ -537,6 +592,14 @@ function preDecideRun({ node, filter, taskId, projectPath = '.', refreshCache =
     return { ...entry, reason: `filtered out (--filter ${filter.raw})` };
   }
 
+  // The task's group scoped this node out (#87). AFTER the filter on purpose:
+  // a node the user filtered out reports the filter, never a scope it was not
+  // judged by. BEFORE the e2e and eval checks: a node outside the task scope
+  // has nothing left to decide.
+  if (node.selection?.mode === 'out-of-scope') {
+    return { ...entry, reason: node.selection.reason };
+  }
+
   if (node.e2e && taskId) {
     return { ...entry, reason: 'e2e node runs at feature scope only' };
   }
@@ -590,7 +653,19 @@ function judgeRun({ node, result, durationMs }) {
   // is chosen for the failures, not for the summary.
   const parsed = parseTestCount(result.output, node.runner);
   const count = parsed ? parsed.total : null;
-  const verdict = compareTestCount(count, node.expectedCount);
+
+  // A narrowed run is PARTIAL by construction (#87): it has a verdict of its
+  // own, and the count rule below never sees it.
+  if (entry.selection?.mode === 'narrowed') {
+    return judgeNarrowedRun({ entry, node, result, durationMs, count });
+  }
+
+  // An eval node's unit is the SCENARIO (#110 part 2): its baseline is the
+  // summary's scenario count, and `judgeEvalRun` is the one that compares it.
+  // Comparing here too, with the extractor's count of xunit cases, failed a
+  // 24/24 run as "esperado 24, executado 2" — and `judgeEvalRun` only turns a
+  // pass into a fail, never the reverse.
+  const verdict = compareTestCount(count, node.runner === EVAL_RUNNER ? null : node.expectedCount);
   const warnings = verdict.warning ? [verdict.warning] : [];
 
   // A drop is the one count verdict that fails a node by itself: tests that
@@ -618,6 +693,68 @@ function judgeRun({ node, result, durationMs }) {
   };
 }
 
+/**
+ * The verdict of a NARROWED run (#87): what `judgeRun` hands over instead of
+ * its count rule. Reached from the host loop and from `--linux` alike, because
+ * both go through `judgeRun`.
+ *
+ * Two things change, and both follow from "partial by construction":
+ *
+ *   - NO `compareTestCount`. `expectedCount` is the WHOLE suite's baseline: a
+ *     recorte running 12 of 3.082 is not a drop, and a superset selection
+ *     running more than the baseline is not a rise. Either comparison would
+ *     report something about the suite that this run never measured.
+ *   - a pass needs PROOF that tests ran. A filter that matches nothing exits 0
+ *     under VSTest, and "zero tests, all green" is exactly the verdict issue #87
+ *     must never buy. What counts as proof is the selection's `zeroGuard`
+ *     (test-scope.js):
+ *       `count`      only a parsed count > 0. **null is UNKNOWN, never green**;
+ *       `mtp-exit-8` a parsed count > 0 proves it (the MTP summary is read in
+ *                    pt-BR and en-US, #115); with no readable summary (another
+ *                    locale), exit 0 does — MTP exits 8 on zero tests.
+ *     A parsed 0 is refused under either guard: it is positive evidence. It is
+ *     also what closes limit (f): with exit 8 IGNORED, MTP exits 0 over a
+ *     summary that says `total: 0` (measured, mtp-ignore-exit-code-8-zero-tests.txt).
+ *     In a narrowed `&&` chain the SUM would hide that link behind another's
+ *     count, so under `mtp-exit-8` every MTP block is checked on its own — MTP
+ *     prints one block per invocation (measured), and a `total: 0` block is red.
+ *
+ * A FAILED run is renamed `narrowed-zero-tests (…)` only when it carries the
+ * runner's zero-test signature AND no count proves tests ran. A multi-project
+ * VSTest output may print "No test matches…" for one project while another
+ * ran and failed; that failure is the lead, never a zero. Anything else,
+ * exit 9 included, keeps the executor's own raw reason: a project that imposes
+ * `--minimum-expected-tests` is narrowed only with its floor lowered to 1 by
+ * `-p:` (#114, test-scope.js), where a run with tests cannot exit 9 — so a 9
+ * here is not ours to reinterpret.
+ *
+ * Every red leads its output with the verdict, like a timeout does: the
+ * feedback line reads `output` before `reason`, and a tail alone would bury it.
+ */
+function judgeNarrowedRun({ entry, node, result, durationMs, count }) {
+  const tail = tailLines(result.output, OUTPUT_TAIL_LINES);
+  const base = { ...entry, durationMs, count, warnings: [] };
+  const red = (reason) => ({ ...base, status: 'fail', reason, output: tail ? `${reason}\n${tail}` : reason });
+  const green = () => ({ ...base, status: 'pass', reason: result.reason ?? null, output: '' });
+  const ranTests = Number.isInteger(count) && count > 0;
+
+  if (result.passed) {
+    if (count === 0) return red(NARROWED_ZERO_TESTS);
+    if (entry.selection.zeroGuard === 'mtp-exit-8' && mtpSummaryTotals(result.output).includes(0)) {
+      return red(NARROWED_ZERO_TESTS_LINK);
+    }
+    if (ranTests) return green();
+    if (entry.selection.zeroGuard === 'mtp-exit-8' && result.exitCode === 0) return green();
+    return red(NARROWED_COUNT_UNKNOWN);
+  }
+
+  if (!ranTests && isZeroTestRun(result.output, node.runner, result.exitCode)) {
+    return red(`narrowed-zero-tests (${node.runner}, exit ${result.exitCode ?? 'desconhecido'}): o recorte executou 0 testes`);
+  }
+
+  return { ...base, status: 'fail', reason: result.reason ?? null, output: tail };
+}
+
 /**
  * Aggregate the per-node runs into the single node `verify` publishes.
  *
@@ -747,12 +884,22 @@ function refreshCacheProblem(projectPath, testPlan, filter, { skipTests }) {
  * never created — the framework repository has none on purpose (creating it
  * breaks `doctor --full`), so the honest answer is a named usage error.
  *
+ * A TASK id is refused first (#87): at task scope the runner narrows the nodes
+ * AND the commands, so what it measures is a recorte, while `expectedCount` is
+ * the whole fleet's number. `recordTestBaselines` refuses a measurement that
+ * carries a selection (the second barrier), but paying for the recorte to
+ * learn that is the ordering this function exists to prevent.
+ *
  * @param {string} projectPath
  * @param {{ nodes: Array, source: string }} testPlan
- * @param {{ skipTests: boolean }} opts
+ * @param {{ skipTests: boolean, taskId?: string|null }} opts
  * @returns {string|null}
  */
-function baselineTargetProblem(projectPath, testPlan, { skipTests }) {
+function baselineTargetProblem(projectPath, testPlan, { skipTests, taskId = null }) {
+  if (taskId) {
+    return `--record-baseline é manutenção da frota: rode sem {task} (recebeu "${taskId}") — `
+      + 'no escopo de task o verify recorta nós e testes, e baseline de recorte não é baseline';
+  }
   if (skipTests) {
     return '--record-baseline com --skip-tests não mede nada — uma baseline vem de uma execução, não de uma omissão';
   }
@@ -796,9 +943,11 @@ function recordBaselineFrom(projectPath, testsNode) {
     );
   }
 
+  // The selection travels with the count so the WRITER can refuse a recorte
+  // (#87) — the second barrier behind baselineTargetProblem's usage error.
   return recordTestBaselines(
     projectPath,
-    runs.map((r) => ({ id: r.id, count: r.count }))
+    runs.map((r) => ({ id: r.id, count: r.count, selection: r.selection ?? null }))
   );
 }
 
@@ -867,7 +1016,7 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
 // E2E node
 // ============================================================================
 
-async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
+async function runE2eNode({ projectPath, featureName, taskId, task = null, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
   if (buildNode.status === 'fail') {
     return {
       status: 'skip',
@@ -879,7 +1028,7 @@ async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e,
   }
 
   const config = readConfig(projectPath);
-  const taskGroup = taskId ? readTaskGroup(projectPath, featureName, taskId) : null;
+  const taskGroup = task?.group ?? null;
   const gitCommonDir = resolveGitCommonDir(projectPath);
 
   const start = Date.now();
@@ -931,14 +1080,11 @@ function appendE2eFeedback(feedback, e2eNode) {
 // Rubric selection — flag > task group > config > default
 // ============================================================================
 
-function resolveRubricId({ projectPath, featureName, taskId, rubricOverride }) {
+function resolveRubricId({ projectPath, task, rubricOverride }) {
   if (rubricOverride) return rubricOverride;
 
-  if (taskId) {
-    const group = readTaskGroup(projectPath, featureName, taskId);
-    const mapped = mapGroupToRubric(group);
-    if (mapped) return mapped;
-  }
+  const mapped = mapGroupToRubric(task?.group);
+  if (mapped) return mapped;
 
   const configRubric = readConfigRubric(projectPath);
   if (configRubric) return configRubric;
@@ -959,13 +1105,30 @@ function mapGroupToRubric(group) {
   return null;
 }
 
-function readTaskGroup(projectPath, featureName, taskId) {
+/**
+ * The task as verify needs it, or null when tasks.json or the task is missing.
+ *
+ * The ONE reader of tasks.json for verify (#87): the group picks the rubric and
+ * the e2e applicability, group + outputs pick the test scope, and the command
+ * uses the null to refuse an unknown task id. Two readers is how a rubric and
+ * a scope start disagreeing about the same task.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @param {string} taskId
+ * @returns {{ group: string|null, outputs: string[] }|null}
+ */
+export function readTask(projectPath, featureName, taskId) {
   try {
     const tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
     if (!existsSync(tasksPath)) return null;
     const tasksJson = JSON.parse(readFileSync(tasksPath, 'utf8'));
     const task = (tasksJson.tasks || []).find((t) => t.id === taskId);
-    return task?.group ?? null;
+    if (!task) return null;
+    return {
+      group: task.group ?? null,
+      outputs: Array.isArray(task.outputs) ? task.outputs : [],
+    };
   } catch {
     return null;
   }

package/src/lib/worktree/docker-audit.js

@@ -72,8 +72,12 @@ function resolveGitCommonDir(cwd) {
  * Path comparison that matches the host's own rules. Windows paths differ in
  * drive-letter case between what git reports and what docker echoes back;
  * treating those as different paths would make every stack look foreign.
+ *
+ * Exported as the ONE copy of that rule: `doctor.js` compares a declared test
+ * node `cwd` with a discovered `package.json` folder through it (#87 F5), and
+ * `test-scope.js` takes only the CASE of a canonical path through it (#87 N3).
  */
-const samePathCase = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+export const samePathCase = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
 const norm = (p) => samePathCase(resolve(String(p)).replace(/\\/g, '/'));
 
 /**