@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,297 @@
+/**
+ * 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
+ */
+
+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.
+ */
+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.
+ */
+export const COPY_EXCLUDES = [
+  'node_modules',
+  'bin',
+  'obj',
+  '.git',
+  `./${WORKTREES_DIR}`,
+  `./${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}
+ */
+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';
+  }
+  if (!isDockerAvailable(projectPath, exec)) {
+    return '--linux exige Docker e o daemon não respondeu — '
+      + 'rode onde ele exista (nunca reportamos "não deu para checar no Linux" como verde)';
+  }
+  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.
+ */
+function partitionNodes(nodes) {
+  const runnable = [];
+  const refused = [];
+  for (const node of nodes) {
+    if (node.e2e) {
+      refused.push({
+        id: node.id,
+        skipped: true,
+        reason: 'nó e2e não roda dentro do container do --linux (docker-em-docker fora de escopo)',
+        output: '',
+        exitCode: null,
+        durationMs: 0,
+      });
+      continue;
+    }
+    runnable.push(node);
+  }
+  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}
+ */
+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.
+    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 }) {
+  return [
+    'run', '--rm',
+    // 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,
+    'sh', '-c', script,
+  ];
+}
+
+/**
+ * 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.
+ */
+function splitByMarkers(output, nodes) {
+  const text = String(output || '');
+  const escape = (v) => String(v).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return nodes.map((node) => {
+    const startRe = new RegExp(`${escape(NODE_START)} ${escape(node.id)}(?: (\\d+))?`);
+    const exitRe = new RegExp(`${escape(NODE_EXIT)} ${escape(node.id)} (-?\\d+)(?: (\\d+))?`);
+    const startMatch = startRe.exec(text);
+    if (!startMatch) {
+      return {
+        id: node.id,
+        exitCode: null,
+        durationMs: null,
+        output: '',
+        reason: 'o container terminou antes deste nó — nenhum veredito foi observado',
+      };
+    }
+    const rest = text.slice(startMatch.index + startMatch[0].length);
+    const exitMatch = exitRe.exec(rest);
+    const body = (exitMatch ? rest.slice(0, exitMatch.index) : rest).replace(/^\r?\n/, '').trimEnd();
+    if (!exitMatch) {
+      return {
+        id: node.id,
+        exitCode: null,
+        durationMs: null,
+        output: body,
+        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.
+    const durationMs = startMatch[1] && exitMatch[2]
+      ? (Number(exitMatch[2]) - Number(startMatch[1])) * 1000
+      : null;
+    return { id: node.id, exitCode: Number(exitMatch[1]), durationMs, output: body, reason: null };
+  });
+}
+
+/**
+ * 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 }}
+ */
+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 };
+
+  if (runnable.length === 0) {
+    return { results: refused, environment, argv: [], script: '', containerCode: null };
+  }
+
+  const script = buildContainerScript({ nodes: runnable });
+  const argv = buildLinuxArgv({ projectPath, image: resolvedImage, script });
+  const run = exec('docker', argv, { cwd: projectPath, timeout });
+
+  const results = splitByMarkers(run.output, runnable).map((r) =>
+    r.exitCode === null && !r.reason
+      ? { ...r, reason: 'o container não reportou este nó' }
+      : 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
+      ? { ...r, reason: `${r.reason} (container saiu com ${run.code}): ${tail(run.output)}` }
+      : r
+  );
+
+  return { results: [...enriched, ...refused], environment, argv, script, containerCode: run.code };
+}
+
+/** 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();
+}

package/src/lib/tasks/task-classifier.js

@@ -1,30 +1,30 @@
-/**
- * Task classifier — identifies test/validation and infrastructure tasks by title.
- */
-
-const TEST_TASK_PATTERN = /\b(tests?|testing|specs?|coverage|e2e|unit|integration|integra[cç][aã]o|valida[cç][aã]o|cobertura|testes?)\b/i;
-
-/**
- * Returns true if the task title indicates a testing or validation task.
- *
- * @param {string} taskTitle
- * @returns {boolean}
- */
-export function isTestTask(taskTitle) {
-  if (!taskTitle) return false;
-  return TEST_TASK_PATTERN.test(taskTitle);
-}
-
-const INFRA_TASK_PATTERN = /\b(infrastructure|infra|cleanup|migration|migra[cç][aã]o|config|setup|ci\/cd|devops|deploy|docker|packages?|dependencies|tags)\b/i;
-
-/**
- * Returns true if the task title indicates an infrastructure/cleanup/migration task.
- * Used to skip contract validation and suppress breaking change warnings.
- *
- * @param {string} taskTitle
- * @returns {boolean}
- */
-export function isInfrastructureTask(taskTitle) {
-  if (!taskTitle) return false;
-  return INFRA_TASK_PATTERN.test(taskTitle);
-}
+/**
+ * Task classifier — identifies test/validation and infrastructure tasks by title.
+ */
+
+const TEST_TASK_PATTERN = /\b(tests?|testing|specs?|coverage|e2e|unit|integration|integra[cç][aã]o|valida[cç][aã]o|cobertura|testes?)\b/i;
+
+/**
+ * Returns true if the task title indicates a testing or validation task.
+ *
+ * @param {string} taskTitle
+ * @returns {boolean}
+ */
+export function isTestTask(taskTitle) {
+  if (!taskTitle) return false;
+  return TEST_TASK_PATTERN.test(taskTitle);
+}
+
+const INFRA_TASK_PATTERN = /\b(infrastructure|infra|cleanup|migration|migra[cç][aã]o|config|setup|ci\/cd|devops|deploy|docker|packages?|dependencies|tags)\b/i;
+
+/**
+ * Returns true if the task title indicates an infrastructure/cleanup/migration task.
+ * Used to skip contract validation and suppress breaking change warnings.
+ *
+ * @param {string} taskTitle
+ * @returns {boolean}
+ */
+export function isInfrastructureTask(taskTitle) {
+  if (!taskTitle) return false;
+  return INFRA_TASK_PATTERN.test(taskTitle);
+}