@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/tasks/test-nodes.js

@@ -1,41 +1,3 @@
-/**
- * Test Nodes — the PLURAL resolver for "which test suites does this project have?".
- *
- * WHY THIS MODULE EXISTS
- *
- * `test-runner.js` answers a singular question: ONE command, resolved by a
- * four-step fallback. That shape is what defect F30 exploited — the resolver
- * found a `.sln`, answered "dotnet test", and 3.082 vitest tests in the same
- * repository never ran while the gate reported green. A project with two
- * runners had no way to say so, and a verifier that cannot be told about a
- * suite cannot fail because of it.
- *
- * So the unit of verification becomes a LIST of nodes. `project.tests[]` in
- * `.morph/config/config.json` declares them; when it is absent, the four-step
- * fallback still runs and is synthesized into exactly one node. Declared beats
- * guessed (D3): a declaration — `tests[]` OR `testCommand` — still wins
- * completely, and deeper auto-detection would only trade one silent false
- * negative for another there. But with NOTHING declared, the guess stops
- * being allowed to be a single answer: the old first-match fallback still
- * picks the primary node exactly as before, and any vitest/jest suite found
- * under a `package.json` (issue #87) is added BESIDE it, because that single
- * guess is exactly what hid 3.082 vitest tests behind a green gate (F30) —
- * the fallback found `.sln`, answered "dotnet test", and never looked twice.
- *
- * WHY VALIDATION IS FAIL-CLOSED HERE (D4)
- *
- * Every other config reader in this repo is fail-open — `JSON.parse` inside a
- * `try/catch`, optional chaining, absent means "carry on". That is right for a
- * hook: a guardrail that kills the session is worse than one that stays quiet.
- * It is exactly WRONG for the verifier. A typo in `tests[]` treated fail-open
- * falls through to the legacy resolver and reproduces F30 — green over a suite
- * that never ran. So an invalid node is not ignored: it becomes a node with a
- * pre-decided `status: 'fail'` and a reason naming the problem. It shows up in
- * `runs[]` and it reddens the gate.
- *
- * @module test-nodes
- */
-
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve, relative, sep } from 'path';
 
@@ -44,36 +6,17 @@ import { EVAL_RUNNER, evalBlockProblem } from './eval-node.js';
 import { atomicWriteJson, CONFIG_FILE_NAME } from '../../core/state/state-manager.js';
 import { PACKAGE_LOCATIONS } from '../detectors/index.js';
 
-/**
- * The count extractors that exist (one per runner, see parseTestCount).
- * `none` is the honest answer for a command whose summary nobody can read —
- * it yields an UNKNOWN count, never a fabricated zero.
- */
+/** `none` yields an UNKNOWN count, never a fabricated zero. */
 export const TEST_RUNNERS = ['dotnet', 'vitest', 'jest', 'node-test', 'playwright', 'none', EVAL_RUNNER];
 
-/**
- * A node id is what `--filter` matches and what keys `runs[]`. Lowercase and
- * dash-only so it survives a shell argument and a JSON key without quoting.
- */
 export const TEST_NODE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 
-/** Id given to the single node the fallback synthesizes — it has no name of its own. */
 const FALLBACK_NODE_ID = 'default';
 
 /**
- * Parse the `--filter` argument into the token list `nodeMatchesFilter` reads.
- *
- * Lives here, beside TEST_NODE_ID_PATTERN, because the thing being matched is
- * a node id: the spelling rules for the id and the spelling rules for what
- * selects it must never drift into two modules.
- *
- * An argument that yields NO tokens (`--filter ""`, `--filter " , "`) returns
- * an empty token list rather than null. That distinction is the point: null
- * means "the user did not filter", `[]` means "the user filtered and selected
- * nothing" — and selecting nothing is a usage error, not a full run.
- *
- * @param {string|null|undefined} raw
- * @returns {{ raw: string, tokens: string[] }|null} null when no filter was given
+ * null means "no filter given"; `{tokens: []}` means "filtered and selected nothing",
+ * which is a usage error, not a full run.
+ * @returns {{ raw: string, tokens: string[] }|null}
  */
 export function parseTestFilter(raw) {
   if (raw === undefined || raw === null || raw === false) return null;
@@ -84,64 +27,36 @@ export function parseTestFilter(raw) {
   };
 }
 
-/**
- * Does this node answer to the filter? Exact id, or the token as a substring
- * of the id (`--filter dot` selects `dotnet`), case-insensitively.
- *
- * @param {TestNode} node
- * @param {{ tokens: string[] }|null} filter - null (no filter) matches everything
- * @returns {boolean}
- */
+/** Exact id or substring of the id, case-insensitive; a null filter matches everything. */
 export function nodeMatchesFilter(node, filter) {
   if (!filter) return true;
   const id = String(node?.id ?? '').toLowerCase();
   return filter.tokens.some((token) => id === token || id.includes(token));
 }
 
-/** Reason kept WORD FOR WORD from the singular resolver: readers already print it. */
+/** Kept word for word from the singular resolver: readers already print it. */
 const NO_SUITE_REASON = 'No testCommand configured and no known project file detected';
 
 /**
- * One declared (or synthesized) test suite.
- *
  * @typedef {Object} TestNode
- * @property {string} id - Unique within the list; what `--filter` matches.
- * @property {string|null} command - Literal shell command; null only on a node already decided.
- * @property {string} cwd - Relative to the project root; '.' by default.
- * @property {string} runner - One of TEST_RUNNERS; inferred from `command` when not declared.
- * @property {number|null} expectedCount - Recorded baseline. **null is UNKNOWN, never 0**:
- *   a 0 here would fabricate a count drop out of "no baseline recorded yet".
- * @property {number|null} timeoutMs - Per-node ceiling. **null is UNKNOWN, never 0** — it
- *   means "derive the ceiling", not "no time allowed".
- * @property {string[]} build - Test projects to compile first (dotnet only); `[]` is
- *   "nothing declared", which is a real answer, not an unknown.
- * @property {boolean} e2e - Needs the stack up; feature scope only.
- * @property {string|null} linuxImage - Container image for `verify --linux`; null defers to the run's.
- * @property {number} projectCount - How many test projects `command` chains — the input to
- *   the derived timeout. Always 1 for a declared node.
- * @property {'fail'|'skip'|null} status - Pre-decided verdict. **Non-null means DO NOT
- *   EXECUTE**: the node is invalid config, or an explicit declaration of "no tests".
- *   null is the normal case: no verdict yet, the run decides.
- * @property {string|null} reason - Why, when `status` is set.
+ * @property {string} id
+ * @property {string|null} command - null only on a node already decided.
+ * @property {string} cwd - Relative to the project root.
+ * @property {string} runner - One of TEST_RUNNERS.
+ * @property {number|null} expectedCount - null is UNKNOWN, never 0.
+ * @property {number|null} timeoutMs - null means "derive the ceiling", never 0.
+ * @property {string[]} build - Test projects to compile first (dotnet only).
+ * @property {boolean} e2e
+ * @property {string|null} linuxImage - null defers to the run's image.
+ * @property {number} projectCount - Input to the derived timeout; 1 for a declared node.
+ * @property {'fail'|'skip'|null} status - Non-null means DO NOT EXECUTE.
+ * @property {string|null} reason
  */
 
-/**
- * Infer which summary extractor can read a command's output.
- *
- * Deliberately conservative: `npm test` can front ANY runner, so it infers
- * `none` (unknown count) rather than guessing. An extractor applied to the
- * wrong output produces `null` anyway — but a WRONG guess that happens to
- * match would invent a number, and numbers here fail gates.
- *
- * @param {string|null|undefined} command
- * @returns {string} one of TEST_RUNNERS
- */
+/** `npm test` can front any runner, so it infers `none`: a wrong guess would invent a number that fails gates. */
 export function inferRunner(command) {
-  // `evals` is never inferred, on purpose: it is a DECLARATION, not a shape a
-  // command line can betray. An eval command is literally `dotnet test`, so any
-  // sniffing here would classify every dotnet suite as an eval — and, worse, the
-  // reverse mistake (an eval declared and read as plain dotnet) would silently
-  // drop the cache pre-flight.
+  // `evals` is never inferred: an eval command is literally `dotnet test`, and
+  // reading a declared eval as plain dotnet would drop the cache pre-flight.
   if (typeof command !== 'string' || !command.trim()) return 'none';
   if (/\bdotnet\s+test\b/.test(command)) return 'dotnet';
   if (/\bvitest\b/.test(command)) return 'vitest';
@@ -151,10 +66,6 @@ export function inferRunner(command) {
   return 'none';
 }
 
-/**
- * Build a fully-shaped node. Every field is present on every node so that no
- * reader has to distinguish "absent" from "unknown" by optional chaining.
- */
 function makeNode(partial) {
   return {
     id: partial.id,
@@ -165,21 +76,15 @@ function makeNode(partial) {
     timeoutMs: partial.timeoutMs ?? null,
     build: partial.build ?? [],
     e2e: partial.e2e ?? false,
-    // Per-node image for `verify --linux`. **null is UNKNOWN, never ''** — it
-    // means "use the run's image", not "use no image".
     linuxImage: partial.linuxImage ?? null,
     projectCount: partial.projectCount ?? 1,
-    // The eval block travels on the node so `verify-runner` never has to go back
-    // to config.json to learn where the cache lives. **null is "this is not an
-    // eval node"** — distinct from an eval node with an empty block, which
-    // `validateTestNodes` already refused.
+    // null is "not an eval node", distinct from an empty block (already refused).
     evals: partial.evals ?? null,
     status: partial.status ?? null,
     reason: partial.reason ?? null,
   };
 }
 
-/** A node that will not run, and says why in the vocabulary of §2.2 of the spec. */
 function invalidNode(id, problem, raw = {}) {
   return makeNode({
     id,
@@ -198,15 +103,6 @@ function isNonNegativeInteger(value) {
   return Number.isInteger(value) && value >= 0;
 }
 
-/**
- * First problem with one raw `tests[]` entry, or null when it is well formed.
- * First problem only: a list of complaints about a single node buries the one
- * that has to be fixed first.
- *
- * @param {*} raw
- * @param {string|null} projectPath - When given, `cwd` is also checked against the disk.
- * @returns {string|null}
- */
 function firstProblem(raw, projectPath) {
   if (!isPlainObject(raw)) return 'must be an object';
 
@@ -231,10 +127,7 @@ function firstProblem(raw, projectPath) {
   if (raw.build !== undefined && (!Array.isArray(raw.build) || raw.build.some((b) => typeof b !== 'string'))) {
     return 'build must be an array of strings';
   }
-  // `build[]` is compiled by the dotnet prebuild and by nothing else. Declared
-  // on a vitest node it would be silently ignored — and a declaration the
-  // verifier ignores is the same fail-open shape as the typo in `tests[]`:
-  // the author believes something is being compiled that never is.
+  // A declaration the verifier would silently ignore is refused, not dropped.
   if (Array.isArray(raw.build) && raw.build.length > 0
       && (raw.runner ?? inferRunner(raw.command)) !== 'dotnet') {
     return 'build applies only to runner "dotnet"';
@@ -245,10 +138,6 @@ function firstProblem(raw, projectPath) {
   if (raw.linuxImage !== undefined && (typeof raw.linuxImage !== 'string' || !raw.linuxImage.trim())) {
     return 'linuxImage must be a non-empty string';
   }
-  // `runner: "evals"` REQUIRES its block; the block on any other runner is a
-  // declaration the verifier would silently ignore — the same fail-open shape as
-  // a typo in `tests[]`, where the author believes something is being checked
-  // that never is.
   if ((raw.runner ?? inferRunner(raw.command)) === EVAL_RUNNER) {
     const problem = evalBlockProblem(raw, projectPath);
     if (problem) return problem;
@@ -256,19 +145,14 @@ function firstProblem(raw, projectPath) {
     return `evals applies only to runner "${EVAL_RUNNER}"`;
   }
 
-  // The cwd checks come last because they are the expensive ones, and because
-  // a node that is malformed in shape has a better error to report first.
   const cwd = typeof raw.cwd === 'string' ? raw.cwd.trim() : '.';
   const root = resolve(projectPath ?? '.');
   const abs = resolve(root, cwd);
   if (!isInside(abs, root)) {
-    // A cwd that leaves the root addresses ANOTHER tree — the same damage the
-    // worktree exclusion in collectDotnetTestProjects exists to prevent.
     return `cwd "${cwd}" resolves outside the project root`;
   }
   if (projectPath && !existsSync(abs)) {
-    // P5: named failure, never a skip. A wrong cwd is a plan error, and a skip
-    // would hide it behind a green gate.
+    // Named failure, never a skip: a skip would hide a wrong cwd behind a green gate.
     return `cwd "${cwd}" does not exist`;
   }
 
@@ -276,16 +160,9 @@ function firstProblem(raw, projectPath) {
 }
 
 /**
- * Validate `config.project.tests[]` IN USE — this is called by
- * resolveTestNodes(), not merely declared in a schema. A schema that nothing
- * calls is decoration; this repo already paid for fifteen guardrails that
- * could not detect anything (v8.9/v8.11).
- *
- * Fail-closed by design (D4): a bad entry becomes a node with
- * `status: 'fail'`, never a node that disappears.
- *
- * @param {object|null} config - Parsed `.morph/config/config.json`
- * @param {string|null} [projectPath] - Project root; enables the on-disk `cwd` check
+ * Fail-CLOSED, unlike the repo's other config readers: a typo that falls through
+ * to the fallback resolver gives a green gate over a suite that never ran.
+ * A bad entry becomes a `status: 'fail'` node, never a node that disappears.
  * @returns {TestNode[]} One node per declared entry, in declaration order
  */
 export function validateTestNodes(config, projectPath = null) {
@@ -295,9 +172,7 @@ export function validateTestNodes(config, projectPath = null) {
     return [invalidNode('project.tests', 'must be an array of test nodes')];
   }
 
-  // Count ids BEFORE judging: two nodes sharing an id make `--filter` and
-  // `runs[]` ambiguous, and picking a winner would silence one declared suite.
-  // Both sides fail — the ambiguity is the defect, not either entry.
+  // Duplicate ids fail on both sides: picking a winner would silence a declared suite.
   const seen = new Map();
   for (const entry of raw) {
     if (isPlainObject(entry) && typeof entry.id === 'string') {
@@ -333,7 +208,6 @@ export function validateTestNodes(config, projectPath = null) {
   });
 }
 
-/** Turn a relative path into an id-safe slug matching TEST_NODE_ID_PATTERN. */
 function slugifyForId(text) {
   return text
     .toLowerCase()
@@ -342,20 +216,8 @@ function slugifyForId(text) {
 }
 
 /**
- * Guess which frontend test suites this project has, from `package.json`
- * alone — a GUESS (issue #87), never a declaration. Only called by the
- * fallback of `resolveTestNodes()`, and only when nothing was declared: a
- * `package.json` that names `vitest`/`jest` in `dependencies` or
- * `devDependencies` becomes one candidate suite, exactly the shape F30
- * exploited when a repo had .NET AND a frontend and the first-match fallback
- * only ever answered "dotnet test".
- *
- * Fail-open by construction (it IS a guess): an unreadable or malformed
- * `package.json` is skipped silently, never a `fail` node — that fail-closed
- * treatment is reserved for a DECLARATION (`tests[]`), which this is not.
- *
- * @param {string} projectPath - Project root
- * @param {object|null} config - Parsed `.morph/config/config.json`, or null
+ * A GUESS from `package.json` (vitest/jest in deps), never a declaration — so it
+ * is fail-open: an unreadable `package.json` is skipped, never a `fail` node.
  * @returns {Array<{ id: string, cwd: string, runner: 'vitest'|'jest', command: string }>}
  */
 export function discoverFrontendPackages(projectPath, config) {
@@ -365,9 +227,6 @@ export function discoverFrontendPackages(projectPath, config) {
   const frontendPath = config?.project?.frontendPath;
   if (typeof frontendPath === 'string' && frontendPath.trim()) {
     const abs = resolve(root, frontendPath.trim());
-    // Outside the root is IGNORED, not refused — this is a guess reusing
-    // another guess (detectProject's own frontendPath), and neither one gets
-    // to address another tree.
     if (isInside(abs, root)) candidates.push(frontendPath.trim());
   }
 
@@ -387,7 +246,7 @@ export function discoverFrontendPackages(projectPath, config) {
     try {
       pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
     } catch {
-      continue; // unreadable/invalid — skipped silently, fail-open (it's a guess)
+      continue;
     }
 
     const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
@@ -419,40 +278,19 @@ export function discoverFrontendPackages(projectPath, config) {
 }
 
 /**
- * Resolve every test suite of a project, in the order the verifier must run them.
- *
- * Precedence — the whole point is that the last three steps still work with NO
- * config at all, because this repository (the framework source) has none and
- * every project installed before this feature has none either:
- *
- *   1. `project.tests[]` declared        → one node per entry, source 'config-tests'
- *   2. `project.testCommand` declared    → ONE synthesized node,  source 'config'
- *   3. the four-step fallback of         → ONE synthesized node,  source
- *      resolveTestPlan() (root .sln,        'dotnet-root' | 'dotnet-scan' | 'npm' | 'none'
- *      *Tests.csproj scan, npm test)
- *
- * Steps 2 and 3 are `resolveTestPlan()` itself — CALLED, never re-implemented.
- * That matters twice over: it is the only place that knows the fallback order,
- * and it is the only place that excludes linked worktrees from the
- * `*Tests.csproj` scan (a worktree is another feature's checkout; scanning it
- * doubles the clock and reports on code outside the tree being judged).
- *
- * The list is never empty: "nothing to run" is expressed as ONE node already
- * decided as `skip`, so the reason travels to the report instead of vanishing.
- *
- * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * Precedence: `project.tests[]` → `project.testCommand` → `resolveTestPlan()`'s
+ * fallback (called, never re-implemented: it owns the order and the worktree
+ * exclusion). Never empty: "nothing to run" is one node decided as `skip`.
  * @returns {{ nodes: TestNode[], source: string }}
  */
 export function resolveTestNodes(projectPath = '.') {
   const config = readMorphConfig(projectPath);
 
-  // `tests` present in ANY shape is a declaration of intent. Even a malformed
-  // one: falling back from a typo is how F30 comes back.
+  // `tests` in ANY shape is a declaration: falling back from a typo hides a suite.
   if (config?.project?.tests !== undefined) {
     const nodes = validateTestNodes(config, projectPath);
     if (Array.isArray(config.project.tests) && config.project.tests.length === 0) {
-      // `[]` is an explicit "this project declares no test suites" — distinct
-      // from an absent key, which means "guess for me".
+      // `[]` declares "no suites"; an absent key means "guess for me".
       return {
         nodes: [makeNode({ id: 'none', status: 'skip', reason: 'no test nodes declared' })],
         source: 'config-tests',
@@ -469,16 +307,11 @@ export function resolveTestNodes(projectPath = '.') {
       : makeNode({ id: FALLBACK_NODE_ID, status: 'skip', reason: NO_SUITE_REASON }),
   ];
 
-  // The union (#87 PR B / F30): add discovered frontend suites BESIDE the
-  // fallback node — but only when nothing was declared. `plan.source ===
-  // 'config'` means `project.testCommand` IS a declaration (it lives inside
-  // resolveTestPlan's own step 1), and a declaration wins completely: nothing
-  // is added beside it, same as the `project.tests[]` branch above.
+  // Discovered frontend suites go BESIDE the fallback node, never beside a
+  // declaration (`plan.source === 'config'` is `project.testCommand`).
   if (plan.source !== 'config') {
     const discovered = discoverFrontendPackages(projectPath, config)
-      // The root package is already run by `npm test` when that is the
-      // fallback's own answer — adding it again would run the same suite
-      // twice under two different commands.
+      // The root package is already run by the fallback's `npm test`.
       .filter((pkg) => !(pkg.cwd === '.' && plan.source === 'npm'))
       .map((pkg) => makeNode({ id: pkg.id, command: pkg.command, cwd: pkg.cwd, runner: pkg.runner }));
     nodes.push(...discovered);
@@ -487,45 +320,15 @@ export function resolveTestNodes(projectPath = '.') {
   return { nodes, source: plan.source };
 }
 
-/**
- * Path of the config the baseline lives in. One spelling, so the writer and
- * `readMorphConfig()` can never disagree about which file is meant — and that
- * is now literally true: both derive from `CONFIG_FILE_NAME`
- * (`core/state/state-manager.js`), the same constant `state-manager.js` itself
- * reads the project identity through. It used to be a promise made by a JSDoc
- * over two hand-typed copies of the same string.
- */
 export function morphConfigPath(projectPath = '.') {
   return join(projectPath, CONFIG_FILE_NAME);
 }
 
 /**
- * Write measured `expectedCount` values back into `project.tests[]`.
- *
- * WHY THIS IS A FUNCTION AND NOT AN EDIT (D8)
- *
- * `MORPH.md` says a baseline is a COMMAND, never a number — and this feature
- * stores a number. The rule survives because nobody is allowed to type it: the
- * only writer is `verify --record-baseline`, and it writes what a real, green
- * run measured. A hand-typed number describes what someone believed; the
- * divergence between belief and the suite is exactly the failure the rule was
- * written after.
- *
- * The write is a POINTED mutation: read → set one field per declared node →
- * atomic `tmp.{pid}` + rename via `atomicWriteJson` (the same door
- * `state-manager.js` uses, not a second copy of it). Every other key of
- * `config.json` survives, because this command owns one field and nothing else.
- *
- * It refuses rather than improvises:
- *   - a measurement whose `count` is not an integer (**null is UNKNOWN, never
- *     0** — a written 0 would fabricate a drop against every later run);
- *   - a measured id that is not declared (appending a node would be inventing
- *     the declaration the command came to update);
- *   - a declared node with no measurement (a baseline recorded for part of a
- *     fleet says nothing true about the rest of it);
- *
- * @param {string} projectPath - Project root
- * @param {Array<{id: string, count: number|null}>} measurements - One per node that ran
+ * The only writer of `expectedCount`: a baseline is measured by a green run, never typed.
+ * Refuses a non-integer count (null is UNKNOWN, never 0), an undeclared id, or a
+ * declared node with no measurement. Every other config key survives.
+ * @param {Array<{id: string, count: number|null}>} measurements
  * @returns {{ recorded: boolean, reason: string|null, updates: Array<{id: string, from: number|null, to: number}>, path: string }}
  */
 export function recordTestBaselines(projectPath, measurements) {