@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,486 @@
+/**
+ * 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): deeper auto-detection would only trade one silent false
+ * negative for another, and the cost of the error here is a green gate over
+ * untested code.
+ *
+ * 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 } from 'path';
+
+import { resolveTestPlan, readMorphConfig, isInside } from './test-runner.js';
+import { EVAL_RUNNER, evalBlockProblem } from './eval-node.js';
+import { atomicWriteJson, CONFIG_FILE_NAME } from '../../core/state/state-manager.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.
+ */
+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
+ */
+export function parseTestFilter(raw) {
+  if (raw === undefined || raw === null || raw === false) return null;
+  const text = String(raw);
+  return {
+    raw: text,
+    tokens: text.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean),
+  };
+}
+
+/**
+ * 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}
+ */
+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. */
+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.
+ */
+
+/**
+ * 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
+ */
+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.
+  if (typeof command !== 'string' || !command.trim()) return 'none';
+  if (/\bdotnet\s+test\b/.test(command)) return 'dotnet';
+  if (/\bvitest\b/.test(command)) return 'vitest';
+  if (/\bplaywright\b/.test(command)) return 'playwright';
+  if (/\bjest\b/.test(command)) return 'jest';
+  if (/\bnode\b[^&|]*\s--test\b/.test(command) || /run-tests\.mjs\b/.test(command)) return 'node-test';
+  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,
+    command: partial.command ?? null,
+    cwd: partial.cwd ?? '.',
+    runner: partial.runner ?? inferRunner(partial.command),
+    expectedCount: partial.expectedCount ?? null,
+    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.
+    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,
+    command: typeof raw.command === 'string' ? raw.command : null,
+    cwd: typeof raw.cwd === 'string' ? raw.cwd : '.',
+    status: 'fail',
+    reason: `invalid-test-node: ${id}: ${problem}`,
+  });
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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';
+
+  if (typeof raw.id !== 'string' || !TEST_NODE_ID_PATTERN.test(raw.id)) {
+    return `id must be a string matching ${TEST_NODE_ID_PATTERN.source}`;
+  }
+  if (typeof raw.command !== 'string' || !raw.command.trim()) {
+    return 'command must be a non-empty string';
+  }
+  if (raw.cwd !== undefined && (typeof raw.cwd !== 'string' || !raw.cwd.trim())) {
+    return 'cwd must be a non-empty string';
+  }
+  if (raw.runner !== undefined && !TEST_RUNNERS.includes(raw.runner)) {
+    return `runner must be one of ${TEST_RUNNERS.join(' | ')}`;
+  }
+  if (raw.expectedCount !== undefined && !isNonNegativeInteger(raw.expectedCount)) {
+    return 'expectedCount must be an integer >= 0';
+  }
+  if (raw.timeoutMs !== undefined && !(Number.isInteger(raw.timeoutMs) && raw.timeoutMs > 0)) {
+    return 'timeoutMs must be an integer > 0';
+  }
+  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.
+  if (Array.isArray(raw.build) && raw.build.length > 0
+      && (raw.runner ?? inferRunner(raw.command)) !== 'dotnet') {
+    return 'build applies only to runner "dotnet"';
+  }
+  if (raw.e2e !== undefined && typeof raw.e2e !== 'boolean') {
+    return 'e2e must be a boolean';
+  }
+  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;
+  } else if (raw.evals !== undefined) {
+    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.
+    return `cwd "${cwd}" does not exist`;
+  }
+
+  return null;
+}
+
+/**
+ * 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
+ * @returns {TestNode[]} One node per declared entry, in declaration order
+ */
+export function validateTestNodes(config, projectPath = null) {
+  const raw = config?.project?.tests;
+
+  if (!Array.isArray(raw)) {
+    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.
+  const seen = new Map();
+  for (const entry of raw) {
+    if (isPlainObject(entry) && typeof entry.id === 'string') {
+      seen.set(entry.id, (seen.get(entry.id) ?? 0) + 1);
+    }
+  }
+
+  return raw.map((entry, index) => {
+    const id = isPlainObject(entry) && typeof entry.id === 'string' && entry.id
+      ? entry.id
+      : `tests[${index}]`;
+
+    const problem = firstProblem(entry, projectPath);
+    if (problem) return invalidNode(id, problem, isPlainObject(entry) ? entry : {});
+
+    if (seen.get(entry.id) > 1) {
+      return invalidNode(id, `duplicate id "${entry.id}" — ids must be unique within tests[]`, entry);
+    }
+
+    return makeNode({
+      id: entry.id,
+      command: entry.command,
+      cwd: typeof entry.cwd === 'string' ? entry.cwd.trim() : '.',
+      runner: entry.runner ?? inferRunner(entry.command),
+      expectedCount: entry.expectedCount ?? null,
+      timeoutMs: entry.timeoutMs ?? null,
+      build: entry.build ?? [],
+      e2e: entry.e2e ?? false,
+      linuxImage: entry.linuxImage ?? null,
+      evals: entry.evals ?? null,
+      projectCount: 1,
+    });
+  });
+}
+
+/**
+ * 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 '.')
+ * @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.
+  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".
+      return {
+        nodes: [makeNode({ id: 'none', status: 'skip', reason: 'no test nodes declared' })],
+        source: 'config-tests',
+      };
+    }
+    return { nodes, source: 'config-tests' };
+  }
+
+  const plan = resolveTestPlan(projectPath);
+
+  if (!plan.command) {
+    return {
+      nodes: [makeNode({ id: FALLBACK_NODE_ID, status: 'skip', reason: NO_SUITE_REASON })],
+      source: plan.source,
+    };
+  }
+
+  return {
+    nodes: [makeNode({
+      id: FALLBACK_NODE_ID,
+      command: plan.command,
+      cwd: '.',
+      projectCount: plan.projectCount,
+    })],
+    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 ("mandate afirmando 2366 quando já eram 2375").
+ *
+ * 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
+ * @returns {{ recorded: boolean, reason: string|null, updates: Array<{id: string, from: number|null, to: number}>, path: string }}
+ */
+export function recordTestBaselines(projectPath, measurements) {
+  const path = morphConfigPath(projectPath);
+  const refuse = (reason) => ({ recorded: false, reason, updates: [], path });
+
+  if (!existsSync(path)) return refuse('não existe .morph/config/config.json — não há onde gravar');
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    return refuse(`config.json ilegível (${err.message})`);
+  }
+
+  const declared = config?.project?.tests;
+  if (!Array.isArray(declared)) {
+    return refuse('config.json não declara project.tests[] — não há entrada onde gravar a baseline');
+  }
+
+  const unreadable = measurements.filter((m) => !Number.isInteger(m.count)).map((m) => m.id);
+  if (unreadable.length > 0) {
+    return refuse(`contagem desconhecida em: ${unreadable.join(', ')} — desconhecido nunca vira 0`);
+  }
+
+  const byId = new Map(measurements.map((m) => [m.id, m.count]));
+  const undeclared = [...byId.keys()].filter(
+    (id) => !declared.some((entry) => entry && entry.id === id)
+  );
+  if (undeclared.length > 0) {
+    return refuse(`nó medido não declarado em project.tests[]: ${undeclared.join(', ')}`);
+  }
+
+  const unmeasured = declared
+    .map((entry) => entry?.id)
+    .filter((id) => typeof id === 'string' && !byId.has(id));
+  if (unmeasured.length > 0) {
+    return refuse(`nó declarado sem medição: ${unmeasured.join(', ')} — baseline parcial não é baseline`);
+  }
+
+  const updates = [];
+  for (const entry of declared) {
+    if (!entry || !byId.has(entry.id)) continue;
+    const to = byId.get(entry.id);
+    updates.push({
+      id: entry.id,
+      from: Number.isInteger(entry.expectedCount) ? entry.expectedCount : null,
+      to,
+    });
+    entry.expectedCount = to;
+  }
+
+  atomicWriteJson(path, config);
+  return { recorded: true, reason: null, updates, path };
+}