@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/tasks/linux-runner.js

@@ -1,72 +1,24 @@
-/**
- * Linux Runner — run the declared test nodes inside a Linux container.
- *
- * WHY THIS MODULE EXISTS
- *
- * Defect F35: 3.057 tests green on Windows, ten failures on Linux. The ten
- * were `Link=` casing and `Uri.TryCreate` — defects of CASE, invisible on a
- * case-insensitive filesystem. The CI has had an ubuntu leg since 8.24.2 and
- * F35 still reached the field, because the CI answers minutes-to-hours after
- * the loop has moved on. `--linux` is the desk-side complement: the same
- * suites, on Linux, inside the loop.
- *
- * WHY THE TREE IS COPIED AND NOT MOUNTED (D5) — the load-bearing decision
- *
- * Docker Desktop's bind mount on Windows crosses a 9p / gRPC-FUSE translation
- * layer that is **case-insensitive**. Running the suite on top of that mount
- * gives back exactly the green Windows already gave: the flag would exist and
- * prove nothing about the one class of defect it was built for. So the host
- * tree is mounted READ-ONLY at `/src` purely as the source of a copy, the copy
- * lands on the container's own filesystem (the overlayfs) at `/work`, and every
- * node runs from `/work/{cwd}`. Nothing ever executes out of `/src`.
- *
- * The copy is `tar | tar` rather than a literal `cp -r` because `cp` has no
- * portable exclusion: `node_modules`, `bin`, `obj`, `.git` and the worktree
- * container directories must not travel (a worktree is ANOTHER feature's
- * checkout — copying it doubles the clock and reports on code outside the tree
- * under judgement, the same reason `collectDotnetTestProjects` excludes them).
- * The effect is the one the issue asked for: the executed tree lives in the
- * container.
- *
- * WHY `exec` IS INJECTED
- *
- * The CI has no guaranteed Docker daemon and no .NET at all. Every test of
- * this module drives a recorded `exec` and asserts the command line that WOULD
- * have run — a verifier whose own tests need a container is a verifier that
- * stops being tested.
- *
- * @module linux-runner
- */
-
+// The Docker Desktop bind mount is case-insensitive (9p/gRPC-FUSE), so the tree is
+// mounted read-only at /src and COPIED to the container's own filesystem at /work:
+// running on the mount would hide exactly the casing defects this runner exists for.
 import { createHash } from 'crypto';
 import { resolve } from 'path';
 
 import { defaultExec, isDockerAvailable } from '../../../framework/hooks/shared/e2e-check.js';
 import { WORKTREES_DIR, LEGACY_WORKTREES_DIR } from '../worktree/dirs.js';
 
-/** The SDK image `--linux` runs in by default (spec §5.1); overridable per run and per node. */
 export const LINUX_DEFAULT_IMAGE = 'mcr.microsoft.com/dotnet/sdk:10.0';
 
-/** Where the host tree is mounted (read-only) and where the copy is executed from. */
 const SRC_MOUNT = '/src';
 const WORK_DIR = '/work';
 
-/**
- * Markers that fence one node's output inside the single container's stdout.
- * Deliberately noisy: a delimiter that could occur in real test output would
- * split a run at the wrong line and attribute failures to the wrong suite.
- */
+// Deliberately noisy: a delimiter that could occur in real test output would
+// attribute failures to the wrong suite.
 export const NODE_START = '@@MORPH-NODE-START@@';
 export const NODE_EXIT = '@@MORPH-NODE-EXIT@@';
 
-/**
- * What never travels into the container.
- *
- * The two worktree container names are IMPORTED from `dirs.js`, never retyped:
- * duplicating that string is the documented way the C1 bug comes back. They are
- * anchored at the root (`./name`) because they are root-level containers; the
- * build artifacts are unanchored because they nest anywhere in a tree.
- */
+// Worktree dirs are anchored at the root (`./name`); build artifacts nest anywhere.
+// A worktree is another feature's checkout and must never be copied.
 export const COPY_EXCLUDES = [
   'node_modules',
   'bin',
@@ -76,21 +28,12 @@ export const COPY_EXCLUDES = [
   `./${LEGACY_WORKTREES_DIR}`,
 ];
 
-/** Single-quote a POSIX shell word — the container's shell is always sh. */
 function shq(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
-/**
- * Why `--linux` cannot run, or null when it can.
- *
- * A missing daemon is a USAGE ERROR (exit 2), never a skipped node. A skip
- * would mean "we could not check on Linux" reading as green — which is F35
- * itself, restated as a feature.
- *
- * @param {{ projectPath: string, skipTests: boolean, exec?: Function }} params
- * @returns {string|null}
- */
+// A missing daemon is a usage error, never a skipped node: a skip would read
+// "could not check on Linux" as green.
 export function checkLinuxPreconditions({ projectPath, skipTests, exec = defaultExec }) {
   if (skipTests) {
     return '--linux com --skip-tests se anulam: a flag existe para RODAR a suíte em Linux';
@@ -102,14 +45,8 @@ export function checkLinuxPreconditions({ projectPath, skipTests, exec = default
   return null;
 }
 
-/**
- * Which nodes can actually run inside the container, and why the others cannot.
- *
- * An `e2e: true` node needs the application stack up; bringing docker up INSIDE
- * a container is out of scope, so it is refused by name rather than silently
- * dropped — a suite that disappears from the report is the defect this whole
- * feature exists to close.
- */
+// e2e nodes are refused by name, never dropped: a suite that disappears from the
+// report reads as green.
 function partitionNodes(nodes) {
   const runnable = [];
   const refused = [];
@@ -130,63 +67,31 @@ function partitionNodes(nodes) {
   return { runnable, refused };
 }
 
-/**
- * The shell script the container executes: copy first, then every node.
- *
- * Order is the contract — the copy precedes the first command, and every
- * command is `cd`-ed into `/work/{cwd}`. `set -e` is deliberately NOT used
- * around the nodes: one red suite must not cancel the ones after it (the same
- * rule the local loop follows for a timeout).
- *
- * @param {{ nodes: Array<import('./test-nodes.js').TestNode> }} params
- * @returns {string}
- */
+// No `set -e` around the nodes: one red suite must not cancel the ones after it.
 export function buildContainerScript({ nodes }) {
   const excludes = COPY_EXCLUDES.map((e) => `--exclude=${e}`).join(' ');
   const lines = [
     'set -u',
     `mkdir -p ${WORK_DIR}`,
-    // The copy that makes this flag mean something: after it, the executed
-    // files live on the container's own filesystem, which is case-SENSITIVE.
     `tar -C ${SRC_MOUNT} ${excludes} -cf - . | tar -C ${WORK_DIR} -xf -`,
   ];
 
   for (const node of nodes) {
     const dir = `${WORK_DIR}/${node.cwd || '.'}`;
-    // The clock is read into a variable BEFORE the marker is echoed, and the
-    // exit code into another one: a `$(date)` sharing an echo with `$?` is one
-    // shell quirk away from reporting the timestamp's exit code as the suite's.
-    // An image without `date` degrades to an UNKNOWN duration, never a zero.
+    // `$?` is captured into its own variable: sharing an echo with `$(date)` can
+    // report the timestamp's exit code as the suite's.
     lines.push(`__ms=$(date +%s 2>/dev/null); echo "${NODE_START} ${node.id} $__ms"`);
     lines.push(`cd ${shq(dir)} && ${node.command}`);
-    // `$?` of the compound above: a cd that fails is a failure too, and one
-    // that reported success would run the suite from the wrong directory.
     lines.push(`__code=$?; __me=$(date +%s 2>/dev/null); echo "${NODE_EXIT} ${node.id} $__code $__me"`);
   }
 
   return lines.join('\n');
 }
 
-/**
- * The exact `docker` argv. Split out from the execution so a test can assert
- * the command line without a daemon — this is the canary that keeps the
- * read-only `/src` and the absence of a writable `/work` mount honest.
- *
- * @param {{ projectPath: string, image: string, script: string }} params
- * @returns {string[]}
- */
 export function buildLinuxArgv({ projectPath, image, script, runId = null }) {
   return [
     'run', '--rm',
     ...(runId ? ['--label', `${LABEL_RUN}=${runId}`, '--label', `${LABEL_ROOT}=${rootHash(projectPath)}`] : []),
-    // Read-only, and mounted at /src: the SOURCE of the copy, never the tree
-    // the tests run from. See the module docs for why that distinction is the
-    // entire point of the flag.
-    //
-    // Forward slashes even on Windows: `C:\a\b` and `C:/a/b` are both accepted
-    // by Docker Desktop, but the backslash form is the one that breaks first
-    // when a path is re-parsed downstream, and the mount spec is already
-    // colon-delimited.
     '-v', `${resolve(projectPath).replace(/\\/g, '/')}:${SRC_MOUNT}:ro`,
     '-w', WORK_DIR,
     image,
@@ -194,13 +99,7 @@ export function buildLinuxArgv({ projectPath, image, script, runId = null }) {
   ];
 }
 
-/**
- * Split the container's stdout back into one result per node.
- *
- * A node whose exit marker never arrived did not pass: the container died
- * mid-run (image pull, OOM, killed clock). Reporting it as anything but a
- * failure would be a green verdict over a suite nobody observed.
- */
+// A node whose exit marker never arrived did not pass: the container died mid-run.
 function splitByMarkers(output, nodes) {
   const text = String(output || '');
   const escape = (v) => String(v).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -229,8 +128,7 @@ function splitByMarkers(output, nodes) {
         reason: 'o container terminou sem reportar o código de saída deste nó',
       };
     }
-    // **null is UNKNOWN, never 0** — an image without `date` did not run the
-    // suite in zero milliseconds.
+    // null is UNKNOWN, never 0: an image without `date` did not run in zero ms.
     const durationMs = startMatch[1] && exitMatch[2]
       ? (Number(exitMatch[2]) - Number(startMatch[1])) * 1000
       : null;
@@ -239,29 +137,11 @@ function splitByMarkers(output, nodes) {
 }
 
 /**
- * Run every runnable node inside ONE container and return the raw per-node
- * results — exit code and output, nothing judged.
- *
- * Judgement (count comparison, baseline drop, feedback lines) stays in
- * verify-runner beside the local path, so a container run and a host run are
- * decided by the SAME code. A second copy of that rule is how two environments
- * start disagreeing about the same suite.
- *
- * @param {Object} params
- * @param {string} params.projectPath - Project root (the copy source)
- * @param {Array<import('./test-nodes.js').TestNode>} params.nodes - Nodes to run
- * @param {string} [params.image] - Image override (`--linux-image`)
- * @param {number} [params.timeout] - Ceiling for the whole container, in ms
- * @param {Function} [params.exec] - Injected executor (defaults to e2e-check's defaultExec)
- * @returns {{ results: Array<{id: string, exitCode: number|null, output: string, reason: string|null, skipped?: boolean}>,
- *            environment: {kind: string, image: string}, argv: string[], script: string, containerCode: number|null }}
+ * Runs every runnable node in ONE container and returns raw per-node results,
+ * unjudged: verify-runner judges container and host runs with the same code.
  */
 export function runLinuxSuite({ projectPath, nodes, image, timeout, exec = defaultExec }) {
   const { runnable, refused } = partitionNodes(nodes);
-  // Precedence: explicit override > a node that declares its own image > the
-  // default. A per-node image only decides the single container everyone shares
-  // when it is the only one asked for — two images would mean two copies of the
-  // tree and two clocks, which is not what this flag is for.
   const declared = runnable.map((n) => n.linuxImage).filter(Boolean);
   const resolvedImage = image || declared[0] || LINUX_DEFAULT_IMAGE;
   const environment = { kind: 'linux-container', image: resolvedImage };
@@ -286,9 +166,6 @@ export function runLinuxSuite({ projectPath, nodes, image, timeout, exec = defau
       : r
   );
 
-  // A container that never produced a single marker failed as a whole (a pull
-  // failure, say). The reason has to name the container, or the reader goes
-  // hunting through a test log for a suite that never started.
   const nothingRan = results.every((r) => r.exitCode === null);
   const enriched = results.map((r) =>
     r.exitCode === null && nothingRan
@@ -318,7 +195,6 @@ export function reapLabeledContainers({ runId, exec, cwd }) {
   } catch { /* limpeza best-effort: nunca muda o veredito da suíte */ }
 }
 
-/** Last few lines of the container output — enough to name a pull failure. */
 function tail(output, lines = 5) {
   return String(output || '').split('\n').slice(-lines).join('\n').trim();
 }