@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

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

@@ -1,597 +0,0 @@
-/**
- * Test Scope — which test nodes a TASK-scoped `verify {feature} {task}` runs,
- * and which tests inside each node (issue #87).
- *
- * GHLBrain ran its whole suite 121 times in 8 days from the per-task loop — about
- * five hours a week — because a task-scoped verify had no way to run less. The
- * feature-scoped verify (Gate 3) keeps running everything; this module only
- * DECIDES the task-scoped cut, verify-runner executes it (task B4).
- *
- * Two independent decisions:
- *   1. selection — the task's `group` picks the nodes (`effectiveGroups`);
- *   2. narrowing — the task's `outputs` narrow the command INSIDE each node.
- *
- * The declared command is literal and nobody's parser owns it, so narrowing is
- * string surgery on a short list of shapes that were read and, where it
- * mattered, measured (test/fixtures/test-output/README.md). Anything else runs
- * WHOLE with a reason: a narrowing that guesses runs the wrong tests or none,
- * and a run of none is the green that issue #87 must never buy.
- *
- * Pure: reads files (and one environment variable, TESTINGPLATFORM_EXITCODE_IGNORE),
- * never spawns a process.
- *
- * @module test-scope
- */
-
-import { readFileSync, statSync } from 'fs';
-import { dirname, relative, resolve } from 'path';
-
-import { effectiveGroups } from './test-nodes.js';
-import { canonicalPath, extractCsprojTargets, isInside } from './test-runner.js';
-import { normalizePath } from '../validators/traceability-check.js';
-import { samePathCase } from '../worktree/docker-audit.js';
-import {
-  csharpClasses, declaresCaseFilter, dotnetTestMode, dotnetTestProjectOf, floorOverride, ignoresExitCode,
-  imposesMinimumExpected, isDotnetSource, isDotnetTestProject, nearestCsprojOf, nearestProjectOf, readsLikeTestSource,
-} from './dotnet-test-introspection.js';
-
-// Part of this module's API (task B3); implemented beside the rest of the .NET introspection.
-export { dotnetTestMode, classNamesOf } from './dotnet-test-introspection.js';
-
-/**
- * The per-node decision B4 consumes (`preDecideRun` skips `out-of-scope`;
- * `judgeRun` reads `mode`/`zeroGuard`). `null` — in fact absent — at feature scope.
- *
- * @typedef {Object} TestSelection
- * @property {'narrowed'|'whole'|'out-of-scope'|'full'} mode
- *   - `narrowed`: `node.command` was rewritten to run only the task's tests. Its
- *     count is PARTIAL: never compare it with `expectedCount` (the whole-suite
- *     baseline, left untouched on the node), and a pass without proof that tests
- *     ran is not a pass — see `zeroGuard`.
- *   - `whole`: selected, runs its declared command unchanged; `reason` says why.
- *   - `out-of-scope`: must not run at this task scope; `reason` says why.
- *   - `full`: `--full` — declared command unchanged, no recorte by request.
- * @property {string|null} reason - Why whole/out-of-scope; null when narrowed.
- * @property {string|null} declaredCommand - The command as declared, before narrowing.
- * @property {string[]} files - Task test files this node owns (project-relative,
- *   `/`, spelled as on disk): inside its cwd, or — dotnet — belonging to a
- *   `.csproj` a link of its command names, wherever they sit (ownership is the
- *   link's project, never the cwd).
- * @property {string[]} selectors - What the narrowed command selects: BARE type
- *   names (dotnet — every class/record/struct/interface of the task's test files,
- *   no namespace, each matched namespace-free as `--filter-class "*T*"` (MTP +
- *   xunit.v3, measured) or the substring `FullyQualifiedName~T`, so any namespace,
- *   nested `Outer+Inner` and prefix siblings are covered: a SUPERSET of the file's
- *   tests, never a subset) or paths relative to the node cwd (vitest/jest). `[]`
- *   unless narrowed.
- * @property {'count'|'mtp-exit-8'|null} zeroGuard - How a narrowed run proves tests
- *   ran: `count` = only a parsed count > 0 proves it (VSTest exits 0 on an empty
- *   filter; vitest/jest print a string); `mtp-exit-8` = a parsed count > 0 proves it
- *   (the MTP summary, pt-BR/en-US, #115) and, with no readable summary, exit 0 does —
- *   MTP exits 8 on zero tests. A parsed 0 is red under both. null unless narrowed.
- */
-
-const NO_TEST_FILE = 'no test file from task outputs in this node — running it whole';
-const SHAPE = 'command shape not recognised for narrowing — running it whole';
-/**
- * Measured (test/fixtures/test-output/mtp-minimum-expected-cli-override-ignored.txt):
- * `--minimum-expected-tests 1` on the CLI does NOT override the project's floor —
- * a green narrowed run still exits 9. The global `-p:` property does, and since
- * #114 a floor floorOverride can re-pass is lowered to 1 for the recorte; every
- * other floor (VSTest, set elsewhere or conditionally) runs whole with this reason
- * rather than produce a red that no test caused. Wording pinned by the plan.
- */
-const MIN_EXPECTED = 'projeto impõe --minimum-expected-tests; recorte desligado';
-/** #114 review F6: `-p:` is global to ONE `dotnet test`, so it would replace the arguments of EVERY project the link runs. */
-const FLOOR_SHARED = 'a link runs several test projects and one has a floor — its -p: would replace the others\' arguments too; running it whole';
-/** #114 review F2: the recorte's `-p:` comes last, and the last one wins — the command's own value would be gone. */
-const COMMAND_SETS_ARGS = 'command sets TestingPlatformCommandLineArguments itself — the recorte\'s -p: would replace that value; running it whole';
-const FILTER_TAKEN = 'command already carries a test filter — a second one would replace it; running it whole';
-const CASE_FILTER = 'project declares <VSTestTestCaseFilter> — an appended --filter would replace it; running it whole';
-/**
- * Final review F3: under MTP, when the summary is NOT readable (a locale other than
- * pt-BR/en-US, #115), a narrowed run's proof that tests ran is exit 0 (zero tests
- * exit 8). Whatever makes MTP ignore an exit code takes that proof away — zero tests
- * then exit 0 — so the node runs whole, readable summary or not: this is decided
- * BEFORE the run, which is when nobody knows yet whether its summary will read.
- * The COMMAND is read by FLOOR_OR_IGNORE; these two are the project
- * (ignoresExitCode) and the environment.
- */
-const IGNORE_EXIT_PROJECT = 'project makes MTP ignore an exit code (--ignore-exit-code / TESTINGPLATFORM_EXITCODE_IGNORE in its MSBuild files or testconfig) — exit 0 would no longer prove that tests ran; running it whole';
-const IGNORE_EXIT_ENV = 'TESTINGPLATFORM_EXITCODE_IGNORE is set in the environment — MTP may exit 0 on zero tests, so exit 0 would no longer prove that tests ran; running it whole';
-
-const CLASS_NAME = /^[A-Za-z0-9_.]+$/;
-/** Characters that change meaning inside double quotes in `sh` (the `--linux` container) or `cmd.exe`. */
-const UNSAFE_IN_QUOTES = /["$`%!]/;
-const JS_TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)__tests__\/.+\.[cm]?[jt]sx?$/;
-const JS_SOURCE = /\.[cm]?[jt]sx?$/i;
-/** Read in the RAW text of a JS/TS output the recogniser did not classify as a test file (the .NET markers: readsLikeTestSource). */
-const JS_TEST_CALL = /^[ \t]*(?:describe|it|test)(?:\.\w+)*\s*\(/m;
-const EXISTING_FILTER = /(^|\s)--(?:treenode-)?filter(?=$|[\s=-])/;
-/** As a flag, or inside `-p:TestingPlatformCommandLineArguments=…` (preceded by `=` or a quote). */
-const FLOOR_OR_IGNORE = /(^|[\s="'])--(?:ignore-exit-code|minimum-expected-tests)(?=$|[\s="'])/;
-const MTP_FRAMEWORKS = new Set(['xunit.v3', 'mstest', 'nunit']);
-
-const toPosix = (p) => String(p).replace(/\\/g, '/');
-const samePath = (a, b) => isInside(a, b) && isInside(b, a);
-const whole = (reason) => ({ command: null, selectors: [], zeroGuard: null, reason });
-
-const isFile = (path) => { try { return statSync(path).isFile(); } catch { return false; } };
-const isDirectory = (path) => { try { return statSync(path).isDirectory(); } catch { return false; } };
-
-/**
- * The on-disk spelling of a path inside the root (#87 F4). A mis-cased output
- * resolves on a case-insensitive disk and was forwarded verbatim; the `--linux`
- * container is case-sensitive, and jest `--runTestsByPath` skips a path it cannot
- * find while a sibling keeps the count above zero. `canonicalPath` (test-runner.js)
- * is the one spelling, and only its CASE is taken: a path it moves ELSEWHERE — a
- * symlink or junction, inside the root or out of it — keeps the plain spelling, so a
- * file never changes node (re-review N3: `web/src/shared` → `libs/shared` left the
- * `web` node narrowed past it). Case is compared by `samePathCase` (docker-audit.js),
- * the one copy of that rule.
- */
-function spelled(abs, rootAbs) {
-  const real = canonicalPath(abs);
-  return isInside(real, rootAbs) && samePathCase(real) === samePathCase(abs) ? real : abs;
-}
-
-/** The project root as on disk: every path compared with it is spelled the same way (F4). */
-const rootOf = (projectPath) => canonicalPath(resolve(projectPath));
-const cwdOf = (node, rootAbs) => spelled(resolve(rootAbs, node?.cwd || '.'), rootAbs);
-
-/**
- * Task outputs → the existing FILES and DIRECTORIES among them, absolute and
- * spelled as on disk; ghosts dropped. A directory is kept apart and never
- * narrows: which of its files the task touched cannot be told (forcedWhole).
- */
-function existingEntries(outputs, rootAbs) {
-  const files = new Set();
-  const dirs = new Set();
-  for (const o of outputs || []) {
-    if (typeof o !== 'string' || !o.trim()) continue;
-    const abs = resolve(rootAbs, normalizePath(o.trim()));
-    if (isFile(abs)) files.add(spelled(abs, rootAbs));
-    else if (isDirectory(abs)) dirs.add(spelled(abs, rootAbs));
-  }
-  return { files: [...files], dirs: [...dirs] };
-}
-
-/** Is this file a test file for THIS runner? (A `.cs` file is nothing to a vitest node.) */
-function isTestFileFor(runner, fileAbs, rootAbs) {
-  const js = JS_TEST_FILE.test(toPosix(relative(rootAbs, fileAbs)));
-  if (runner === 'dotnet' || runner === 'evals') return dotnetTestProjectOf(fileAbs, rootAbs) !== null;
-  if (['vitest', 'jest', 'node-test', 'playwright'].includes(runner)) return js;
-  return js || dotnetTestProjectOf(fileAbs, rootAbs) !== null;
-}
-
-const readRaw = (path) => { try { return readFileSync(path, 'utf8'); } catch { return null; } };
-
-/**
- * An output the recogniser did NOT classify as a test file for this runner but
- * that READS like one in its raw text: a `.cs` carrying a test marker
- * (readsLikeTestSource — loose on purpose), or a JS/TS file with a top-level
- * `describe`/`it`/`test` call. Recognition is a heuristic (csproj name or packages
- * listed in the csproj itself; file-name pattern) — a touched test file it misses
- * would be dropped from `owned`, and the recognised files would narrow the node
- * PAST it: a green run that skipped a touched class. Such a file is named and the
- * node runs whole (and is never scoped out). Non-C# .NET sources: forcedWhole.
- */
-function unrecognisedTestFile(runner, fileAbs, rootAbs) {
-  if (isTestFileFor(runner, fileAbs, rootAbs)) return false;
-  const dotnet = runner === 'dotnet' || runner === 'evals';
-  if (/\.cs$/i.test(fileAbs)) return dotnet && readsLikeTestSource(fileAbs);
-  if (JS_SOURCE.test(fileAbs)) return !dotnet && JS_TEST_CALL.test(readRaw(fileAbs) ?? '');
-  return false;
-}
-
-/**
- * An output the recorte cannot narrow on, for THIS node: the reason to run it
- * whole — and never scope it out — or null. The final review of branch B found
- * both shapes narrowing PAST touched tests:
- * - F1: an existing DIRECTORY overlapping the node's cwd or the folder of a
- *   project a link names (either one containing the other). Dropped as "not a
- *   file", it let the task's other files narrow the node while the tests inside
- *   it never ran — and the count guard passed on the ones that did.
- * - F2 (dotnet): ANY non-`.cs` file this node may run — inside its cwd, or its
- *   nearest project is one a link names — whose nearest project is a TEST project
- *   (a bUnit `.razor`, a Reqnroll/SpecFlow `.feature`, a Verify `.verified.txt`, test
- *   data; re-review N2: a list of source kinds let the `.feature` through), or that
- *   reads like a test (readsLikeTestSource: `.razor`/`.cshtml`/`.fs`/`.fsi`/`.fsx`/`.vb`
- *   outside a recognised test project). It yields no selector, and the tests it feeds
- *   may sit in files the task did not touch, so a recorte skips them.
- */
-function forcedWhole(node, entries, cwdAbs, rootAbs) {
-  const rel = (abs) => toPosix(relative(rootAbs, abs)) || '.';
-  const targets = node?.runner === 'dotnet' ? extractCsprojTargets(node.command).map((t) => resolve(cwdAbs, t)) : [];
-  const areas = [cwdAbs, ...targets.map((t) => dirname(t))];
-  const dir = entries.dirs.find((d) => areas.some((a) => isInside(d, a) || isInside(a, d)));
-  if (dir) {
-    return `output "${rel(dir)}" is a directory — which of its files the task touched cannot be told, and a recorte would skip them; running it whole`;
-  }
-  if (node?.runner !== 'dotnet') return null;
-  const source = entries.files.find((abs) => {
-    if (/\.cs$/i.test(abs)) return false;
-    const project = nearestProjectOf(abs, rootAbs);
-    const mayRun = isInside(abs, cwdAbs) || (project !== null && targets.some((t) => samePath(t, project)));
-    return mayRun && (inTestProject(abs, rootAbs) || readsLikeTestSource(abs));
-  });
-  if (source) {
-    return `output file "${rel(source)}" is a test source the recorte cannot read — not C#, and it belongs to a test project or reads like a test; running it whole`;
-  }
-  return null;
-}
-
-/** The file belongs to a .NET test project: its nearest `.csproj`/`.fsproj`/`.vbproj` is one (N2). */
-function inTestProject(abs, rootAbs) {
-  const project = nearestProjectOf(abs, rootAbs);
-  return project !== null && isDotnetTestProject(project);
-}
-
-/**
- * The `.cs` outputs a LINK of the command owns through its `.csproj` — wherever
- * the file sits, recognised as a test file or not (the caller decides which of
- * the two questions it is asking). A link's ownership is decided by the link's
- * project, never by the node cwd: `cd tests/A.Tests && dotnet test --project
- * ../B.Tests/B.Tests.csproj` runs B's tests, so a touched `tests/B.Tests/XTests.cs`
- * belongs to that link and must select on it (round 5: it was dropped as
- * "outside the cwd", and the link with it — XTests never ran). A bare link keeps
- * the cwd rule: it runs what its cwd resolves, and a file outside is not its business.
- */
-function linkedOutputs(command, filesAbs, cwdAbs, rootAbs) {
-  const targets = extractCsprojTargets(command).map((t) => resolve(cwdAbs, t));
-  if (targets.length === 0) return [];
-  return filesAbs.filter((abs) => {
-    const csproj = nearestCsprojOf(abs, rootAbs);
-    return csproj !== null && targets.some((t) => samePath(t, csproj));
-  });
-}
-
-/**
- * The first project target a command names that is NOT an existing `.csproj`
- * inside the project root — as `extractCsprojTargets` spells it — or null.
- *
- * Link ownership is decided by the link's csproj (linkedOutputs), so a target
- * the recorte cannot resolve turns every ownership answer into a guess, and the
- * guess was "owns nothing": the link was DROPPED, and with it the touched class
- * (B3 final review — compiled, exit 0, the class never ran). Two shapes reach
- * here: `--project=PATH` / `--project:PATH`, which `extractCsprojTargets` returns
- * as ONE token, flag included (resolved, it names nothing), and a csproj OUTSIDE
- * the root, which `nearestCsprojOf` never walks to. `extractCsprojTargets` keeps
- * its semantics for its other callers; this only refuses what it cannot match.
- */
-function unresolvedProjectTarget(command, cwdAbs, rootAbs) {
-  return extractCsprojTargets(command).find((target) => {
-    const abs = resolve(cwdAbs, target);
-    return !/\.csproj$/i.test(abs) || !isFile(abs) || !isInside(abs, rootAbs);
-  }) ?? null;
-}
-
-const strayProject = (target) => whole(`command names project "${target}", which is not an existing .csproj inside the project root — the task's files cannot be matched to its link; running it whole`);
-
-/**
- * The flags of a link that names no csproj, ready to follow a re-pointed
- * project — or null when it names a target that cannot be re-pointed.
- * Re-pointing keeps the class filter off projects that do not own the class:
- * under MTP each of them exits 8, under VSTest each prints "No test matches the
- * given testcase filter" — a zero-test signature on a green run (false red).
- * MTP: a solution/folder target → null. VSTest: a `.sln` token is dropped (the
- * csproj replaces it); a folder → null. A target FLAG — `--solution`,
- * `--directory`, `--test-modules`, `--project` — → null in either spelling: as
- * its own token, or with its value after `=`/`:` in ONE token (final review C2:
- * that spelling was kept, the link re-pointed and filtered, and the `dotnet` CLI
- * refused the narrowed command — a red with no culprit test). A `--project` left
- * for this function never names a csproj: extractCsprojTargets took those, and
- * `--project=X.csproj` runs whole by unresolvedProjectTarget before reaching here.
- */
-function retargetFlags(link, mode, cwdAbs) {
-  let refused = false;
-  const flags = link.replace(/^dotnet\s+test/, '').replace(/(\s*)("[^"]*"|'[^']*'|\S+)/g, (all, _ws, raw) => {
-    const value = raw.replace(/^(["'])(.*)\1$/, '$2');
-    if (value.startsWith('-')) {
-      if (/^--(?:solution|directory|test-modules|project)(?:[=:]|$)/.test(value)) refused = true;
-      return all;
-    }
-    if (/\.slnx?f?$/i.test(value)) {
-      if (mode === 'mtp') refused = true;
-      return '';
-    }
-    if (isDirectory(resolve(cwdAbs, value))) refused = true;
-    return all;
-  });
-  return refused ? null : flags;
-}
-
-function selectorArgs(mode, framework, classes) {
-  // Namespace-free by construction (R1). Measured (test/fixtures/test-output/
-  // mtp-filter-class-any-namespace*.txt): `--filter-class "*Outer*"` runs Outer in
-  // EVERY namespace, its nested Outer+Inner classes and prefix siblings; the exact
-  // name runs Outer alone (mtp-filter-class-exact-skips-nested.txt) and a prefix
-  // without the namespace runs NOTHING (mtp-filter-class-prefix-without-namespace-
-  // zero.txt, exit 8). `FullyQualifiedName~T` is a substring of the FQN: same superset.
-  if (mode === 'mtp' && framework === 'xunit.v3') return classes.map((c) => `--filter-class "*${c}*"`).join(' ');
-  return `--filter "${classes.map((c) => `FullyQualifiedName~${c}`).join('|')}"`;
-}
-
-const classesOf = (files) => [...new Set(files.flatMap((f) => f.types))];
-
-function narrowDotnet(command, owned, cwdAbs, rootAbs) {
-  if (/[;|]/.test(command) || /(^|[^&])&(?!&)/.test(command)) return whole(SHAPE);
-  const links = command.split('&&').map((l) => l.trim());
-  if (links.some((l) => !/^dotnet\s+test(\s|$)/.test(l))) return whole(SHAPE);
-  if (links.some((l) => EXISTING_FILTER.test(l))) return whole(FILTER_TAKEN);
-  if (links.some((l) => /(^|\s)--(\s|$)/.test(l))) return whole('command passes arguments after "--" — running it whole');
-  if (links.some((l) => FLOOR_OR_IGNORE.test(l))) {
-    return whole('command carries --ignore-exit-code/--minimum-expected-tests — a recorte would be judged by the wrong exit; running it whole');
-  }
-  if (process.env.TESTINGPLATFORM_EXITCODE_IGNORE?.trim()) return whole(IGNORE_EXIT_ENV);
-
-  const mode = dotnetTestMode(cwdAbs);
-  if (mode === null) return whole('global.json unreadable — cannot tell VSTest from MTP; running it whole');
-
-  const files = owned.map((abs) => ({ abs, inside: isInside(abs, cwdAbs), ...dotnetTestProjectOf(abs, rootAbs), ...csharpClasses(abs) }));
-  // The PROJECT binds the run, in either mode. A floor exits 9 on a green
-  // recorte: under MTP it is lowered to 1 by a `-p:` that re-passes the rest of
-  // the value when floorOverride can read it from ONE place (#114); otherwise —
-  // VSTest (the MTP bridge, not measured), a floor set elsewhere or conditionally
-  // — the node runs whole. A declared case filter is REPLACED by an appended
-  // --filter (`Category!=Eval` silently gone).
-  const projects = [...new Set(files.map((f) => f.csproj))];
-  const floors = new Map();
-  for (const project of projects.filter((p) => imposesMinimumExpected(p))) {
-    const value = mode === 'mtp' ? floorOverride(project) : null;
-    if (value === null) return whole(MIN_EXPECTED);
-    if (links.some((l) => /TestingPlatformCommandLineArguments/i.test(l))) return whole(COMMAND_SETS_ARGS);
-    floors.set(project, value);
-  }
-  // `-p:` is global to ONE `dotnet test` invocation: it lowers the floor of the project
-  // it was read from and REPLACES the arguments of every other project the link runs.
-  const floorArg = (owners, projectCount) => {
-    const value = owners.map((c) => floors.get(c)).find((v) => v !== undefined);
-    if (value === undefined) return '';
-    return projectCount === 1 ? ` "-p:TestingPlatformCommandLineArguments=${value}"` : null;
-  };
-  if (projects.some((p) => ignoresExitCode(p))) return whole(IGNORE_EXIT_PROJECT);
-  if (projects.some((p) => declaresCaseFilter(p))) return whole(CASE_FILTER);
-  if (mode === 'mtp') {
-    const other = files.find((f) => !MTP_FRAMEWORKS.has(f.framework));
-    if (other) return whole(`MTP test project uses a framework with no known class filter (${other.framework ?? 'unknown'}) — running it whole`);
-  }
-
-  // Selectors are the files' BARE type names at any depth, matched namespace-free
-  // (`--filter-class "*T*"` / `FullyQualifiedName~T`): no namespace, scope or depth
-  // reading can misname a type, and a misread only ADDS a selector. A MISSED type
-  // is what must never happen — and `scannable` means exactly that every type
-  // keyword of the RAW text is a named declaration (csharpClasses states the
-  // guarantee and its limits); else the file is untrusted and never narrows.
-  const unscannable = files.find((f) => !f.scannable);
-  if (unscannable) {
-    const rel = toPosix(relative(rootAbs, unscannable.abs));
-    return whole(`test file "${rel}" could not be scanned safely (${unscannable.why}) — running it whole`);
-  }
-  // R3: an abstract class's tests run under the names of its DERIVED classes —
-  // declared in files the task may not have touched, so no selector here names them.
-  const abstractFile = files.find((f) => f.abstract.length > 0);
-  if (abstractFile) {
-    const rel = toPosix(relative(rootAbs, abstractFile.abs));
-    return whole(`test file "${rel}" declares an abstract class (${abstractFile.abstract.join(', ')}) — its tests run under derived classes' names, possibly in files the task did not touch; running it whole`);
-  }
-  if (!files.some((f) => f.hasTestClass)) return whole('no test class found in the task\'s test files — running it whole');
-  // Round 5: a test-project file WITHOUT a test attribute is a helper, fake or
-  // fixture. Its types select nothing (`*FakeClock*` → exit 8, a red no test
-  // earned) while the tests that USE it live in files the task did not touch.
-  const helper = files.find((f) => !f.hasTestAttribute);
-  if (helper) {
-    const rel = toPosix(relative(rootAbs, helper.abs));
-    return whole(`test file "${rel}" carries no test attribute ([Fact]/[Theory]/[Test…]) — a helper, fake or fixture whose tests live in files the task did not touch; running it whole`);
-  }
-  const unsafe = classesOf(files).find((c) => !CLASS_NAME.test(c));
-  if (unsafe) return whole(`type name "${unsafe}" is not safe to pass as a filter — running it whole`);
-
-  const out = [];
-  for (const link of links) {
-    const targets = extractCsprojTargets(link).map((t) => resolve(cwdAbs, t));
-    if (targets.length > 0) {
-      const mine = files.filter((f) => targets.some((t) => samePath(t, f.csproj)));
-      const classes = classesOf(mine);
-      if (classes.length > 0) {
-        const floor = floorArg([...new Set(mine.map((f) => f.csproj))], targets.length);
-        if (floor === null) return whole(FLOOR_SHARED);
-        out.push(`${link} ${selectorArgs(mode, mine[0].framework, classes)}${floor}`);
-      }
-      continue; // a link whose project owns none of the files is dropped
-    }
-    const flags = retargetFlags(link, mode, cwdAbs);
-    if (flags === null) return whole('command targets a solution or folder the recorte cannot re-point — running it whole');
-    // A bare link runs what its cwd resolves: re-point it to the projects of the
-    // files INSIDE the cwd only (a linked file outside belongs to its own link).
-    for (const csproj of [...new Set(files.filter((f) => f.inside).map((f) => f.csproj))]) {
-      const rel = toPosix(relative(cwdAbs, csproj));
-      if (UNSAFE_IN_QUOTES.test(rel)) return whole(`path "${rel}" has a character unsafe inside quotes — running it whole`);
-      const mine = files.filter((f) => f.csproj === csproj && f.inside);
-      const classes = classesOf(mine);
-      const target = mode === 'mtp' ? `--project "${rel}"` : `"${rel}"`;
-      if (classes.length > 0) out.push(`dotnet test ${target}${flags} ${selectorArgs(mode, mine[0].framework, classes)}${floorArg([csproj], 1)}`);
-    }
-  }
-  if (out.length === 0) {
-    return whole('no link of the command runs the test project owning the task\'s test files — running it whole');
-  }
-  return {
-    command: out.join(' && '),
-    selectors: classesOf(files),
-    zeroGuard: mode === 'mtp' ? 'mtp-exit-8' : 'count',
-    reason: null,
-  };
-}
-
-function narrowJs(runner, command, owned, cwdAbs) {
-  const single = !/[;&|]/.test(command) && !/^\s*(?:npm|pnpm|yarn|bun)\s+run(?:-script)?\b/.test(command);
-  const shaped = runner === 'vitest'
-    ? /\bvitest\b/.test(command) && /(^|\s)(?:--)?run(\s|$)/.test(command)
-    : /\bjest\b/.test(command);
-  if (!single || !shaped) return whole(SHAPE);
-  const rels = owned.map((abs) => toPosix(relative(cwdAbs, abs)));
-  const unsafe = rels.find((r) => UNSAFE_IN_QUOTES.test(r));
-  if (unsafe) return whole(`path "${unsafe}" has a character unsafe inside quotes — running it whole`);
-  const quoted = rels.map((r) => `"${r}"`).join(' ');
-  return {
-    command: `${command.trim()} ${runner === 'jest' ? `--runTestsByPath ${quoted}` : quoted}`,
-    selectors: rels,
-    zeroGuard: 'count',
-    reason: null,
-  };
-}
-
-/**
- * Narrow ONE node's command to the task's test files it owns.
- *
- * @param {import('./test-nodes.js').TestNode} node
- * @param {string[]} testFiles - Task output paths (project-relative or absolute),
- *   spelled as on disk before anything reads them (F4). Only EXISTING files that
- *   are test files for its runner are narrowed on: those inside the node cwd, plus
- *   (dotnet) those a link's `.csproj` owns wherever they sit (linkedOutputs). The
- *   node runs whole rather than skip anything when an output is a directory it
- *   may hold, or (dotnet) a non-C# test source it may compile (forcedWhole); when
- *   a candidate — inside the cwd OR compiled by a link's `.csproj` — merely READS
- *   like a test file (see unrecognisedTestFile); and when a dotnet command names a
- *   project that is not an existing `.csproj` inside the root
- *   (unresolvedProjectTarget): no file could be matched to that link at all.
- * @param {string} projectPath
- * @returns {{ command: string|null, selectors: string[], zeroGuard: 'count'|'mtp-exit-8'|null, reason: string|null }}
- *   `command` null ⇒ run the declared command whole, and `reason` says why.
- */
-export function narrowNode(node, testFiles, projectPath = '.') {
-  const rootAbs = rootOf(projectPath);
-  const cwdAbs = cwdOf(node, rootAbs);
-  if (!['dotnet', 'vitest', 'jest'].includes(node?.runner)) {
-    return whole(`runner "${node?.runner}" has no in-node narrowing — running it whole`);
-  }
-  if (typeof node.command !== 'string' || !node.command.trim()) return whole('node has no command to narrow');
-  if (node.runner === 'dotnet') {
-    const stray = unresolvedProjectTarget(node.command, cwdAbs, rootAbs);
-    if (stray) return strayProject(stray);
-  }
-  const entries = existingEntries(testFiles, rootAbs);
-  const forced = forcedWhole(node, entries, cwdAbs, rootAbs);
-  if (forced) return whole(forced);
-  const existing = entries.files;
-  // This node's candidates: inside its cwd, plus (dotnet) whatever a link's csproj compiles.
-  const candidates = existing.filter((abs) => isInside(abs, cwdAbs));
-  if (node.runner === 'dotnet') {
-    for (const abs of linkedOutputs(node.command, existing, cwdAbs, rootAbs)) if (!candidates.includes(abs)) candidates.push(abs);
-  }
-  const missed = candidates.find((abs) => unrecognisedTestFile(node.runner, abs, rootAbs));
-  if (missed) {
-    return whole(`output file "${toPosix(relative(rootAbs, missed))}" reads like a test file but is not recognised as one for runner "${node.runner}" — a recorte would skip it; running it whole`);
-  }
-  const owned = candidates.filter((abs) => isTestFileFor(node.runner, abs, rootAbs));
-  if (owned.length === 0) return whole(NO_TEST_FILE);
-  return node.runner === 'dotnet'
-    ? narrowDotnet(node.command.trim(), owned, cwdAbs, rootAbs)
-    : narrowJs(node.runner, node.command, owned, cwdAbs);
-}
-
-/**
- * How the node set was chosen, for the `--json` summary.
- * `feature` scope has none; `full`/`filter` switch group selection off.
- */
-function derivationOf({ full, filter, group, nodes }) {
-  if (full) return 'full';
-  if (filter) return 'filter';
-  if (group === 'docs') return 'docs';
-  if (!group) return 'no-group';
-  return nodes.some((n) => effectiveGroups(n)?.includes(group)) ? 'group' : 'unclaimed-group';
-}
-
-/**
- * Scope a test plan to one task.
- *
- * - Feature scope (`taskId` empty): nodes returned as copies, deep-equal to the
- *   input — no `selection` key at all (readers take absent as null).
- * - `full`: every node `mode: 'full'`, commands untouched.
- * - `filter`: the caller's `--filter` picks the nodes; here it only switches
- *   group selection OFF — narrowing inside the nodes still applies.
- * - Otherwise: group `docs` runs only nodes owning an output file; a group some
- *   node claims (`effectiveGroups`) runs the nodes serving it, the unmapped ones
- *   (null) and any node owning one of the task's TEST files (safety net for a
- *   mis-grouped task); an unclaimed or missing group runs every node.
- *
- * Input nodes are never mutated.
- *
- * @param {Object} args
- * @param {string} args.projectPath
- * @param {import('./test-nodes.js').TestNode[]} args.nodes
- * @param {{ group?: string, outputs?: string[] }|null} args.task
- * @param {string|null} args.taskId
- * @param {{ raw: string, tokens: string[] }|null} [args.filter]
- * @param {boolean} [args.full]
- * @returns {{ nodes: Array<import('./test-nodes.js').TestNode & { selection?: TestSelection }>,
- *   summary: { scope: 'feature'|'task', derivation: string|null, group: string|null, testFiles: string[] } }}
- */
-export function applyTaskScope({ projectPath = '.', nodes = [], task = null, taskId = null, filter = null, full = false } = {}) {
-  if (!taskId) {
-    return { nodes: nodes.map((n) => ({ ...n })), summary: { scope: 'feature', derivation: null, group: null, testFiles: [] } };
-  }
-  const rootAbs = rootOf(projectPath);
-  const rel = (abs) => toPosix(relative(rootAbs, abs));
-  const group = typeof task?.group === 'string' ? task.group : null;
-  const taskOutputs = Array.isArray(task?.outputs) ? task.outputs : [];
-  const entries = existingEntries(taskOutputs, rootAbs);
-  const outputs = entries.files;
-  const testFiles = outputs.filter((abs) => isTestFileFor(null, abs, rootAbs));
-  const derivation = derivationOf({ full, filter, group, nodes });
-
-  const scoped = nodes.map((node) => {
-    const cwdAbs = cwdOf(node, rootAbs);
-    const ownOutputs = outputs.filter((abs) => isInside(abs, cwdAbs));
-    // Dotnet: a file a LINK's csproj compiles is this node's too, wherever it sits.
-    if (node.runner === 'dotnet') {
-      for (const abs of linkedOutputs(node.command, outputs, cwdAbs, rootAbs)) if (!ownOutputs.includes(abs)) ownOutputs.push(abs);
-    }
-    // A link naming a project the recorte cannot resolve may compile ANY touched
-    // .NET source outside the cwd, run any test project's file there (N2), or
-    // anything inside a touched folder there: its ownership is unknowable, so the
-    // node is never scoped out past one (narrowNode then runs it whole, naming it).
-    const mayOwnOutside = node.runner === 'dotnet'
-      && unresolvedProjectTarget(node.command, cwdAbs, rootAbs) !== null
-      && (outputs.some((abs) => !isInside(abs, cwdAbs) && (isDotnetSource(abs) || inTestProject(abs, rootAbs)))
-        || entries.dirs.some((d) => !isInside(d, cwdAbs)));
-    // F1/F2: a folder it may hold, or a non-C# test source it may compile.
-    const forced = forcedWhole(node, entries, cwdAbs, rootAbs) !== null;
-    const ownTests = ownOutputs.filter((abs) => isTestFileFor(node.runner, abs, rootAbs));
-    // A test-looking output the recogniser missed counts as owned for the pull-in
-    // too: scoping the node out would skip it just as surely as narrowing past it.
-    const ownsTests = ownTests.length > 0 || mayOwnOutside || forced
-      || ownOutputs.some((abs) => unrecognisedTestFile(node.runner, abs, rootAbs));
-    const select = (selection, command = node.command) => ({
-      ...node,
-      command,
-      selection: {
-        declaredCommand: node.command ?? null, files: ownTests.map(rel), selectors: [], zeroGuard: null, ...selection,
-      },
-    });
-
-    if (derivation === 'full') return select({ mode: 'full', reason: '--full: task-scope narrowing switched off — running it whole' });
-    // The resolver already decided (invalid config, "no suites"): preDecideRun
-    // reports that verdict first, and a recorte would only disguise it.
-    if (node.status) return select({ mode: 'whole', reason: node.reason ?? `pre-decided: ${node.status}` });
-
-    // Ownership for docs is the SAME rule as for links (B3 carry-over): the cwd
-    // contains the file OR a link's csproj compiles it — ownOutputs holds both;
-    // a folder or non-C# test source it may run (forced) keeps it too.
-    if (derivation === 'docs' && ownOutputs.length === 0 && !mayOwnOutside && !forced) {
-      return select({ mode: 'out-of-scope', files: [], reason: 'out of task scope: task group "docs" runs only the nodes owning a file from the task\'s outputs' });
-    }
-    const groups = effectiveGroups(node);
-    if (derivation === 'group' && groups !== null && !groups.includes(group) && !ownsTests) {
-      return select({ mode: 'out-of-scope', files: [], reason: `out of task scope: node serves [${groups.join(', ')}], task group is "${group}"` });
-    }
-
-    // Every output: narrowNode keeps the cwd rule itself and adds the link-owned files.
-    const narrowed = narrowNode(node, taskOutputs, rootAbs);
-    if (narrowed.command === null) return select({ mode: 'whole', reason: narrowed.reason });
-    return select({ mode: 'narrowed', reason: null, selectors: narrowed.selectors, zeroGuard: narrowed.zeroGuard }, narrowed.command);
-  });
-
-  return { nodes: scoped, summary: { scope: 'task', derivation, group, testFiles: testFiles.map(rel) } };
-}