@polymorphism-tech/morph-spec 10.2.0 → 10.5.3

package/src/dashboard/vite.config.js

@@ -1,24 +1,24 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import tailwindcss from '@tailwindcss/vite';
-import morphDataPlugin from './vite-plugin-morph-data.js';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const frameworkDir = resolve(__dirname, '..', '..', 'framework');
-const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
-
-export default defineConfig({
-  root: __dirname,
-  plugins: [
-    react(),
-    tailwindcss(),
-    morphDataPlugin(frameworkDir, projectDir),
-  ],
-  server: {
-    port: 3200,
-  },
-});
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import morphDataPlugin from './vite-plugin-morph-data.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const frameworkDir = resolve(__dirname, '..', '..', 'framework');
+const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [
+    react(),
+    tailwindcss(),
+    morphDataPlugin(frameworkDir, projectDir),
+  ],
+  server: {
+    port: 3200,
+  },
+});

package/src/lib/heavy/gate.js

@@ -1,8 +1,12 @@
-import { minFreeMemFor, readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { freemem } from 'node:os';
+import { CPU_SHARE_ENVS, cpuShareOf, minFreeMemFor, readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { heavyClass } from '../../../framework/hooks/shared/heavy-command.js';
+import { GB, readHolders } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
 import {
   acquireHeavy, awaitFreeMemory, describeBusy, enterVerifySuite, heavyDir, isVerifySuite, releaseHeavy, updateLease,
 } from '../../../framework/hooks/shared/heavy-slots.js';
+import { reclaimUnlessDisabled } from './reclaim.js';
 
 export class HeavyBusyError extends Error {
   constructor(result, config) {
@@ -36,6 +40,29 @@ export function createHeavyGate({
   let suiteEntered = false;
   let exitHandler = null;
   let saved = null;
+  let reclaimed = false;
+  let cpuShare = null;
+  const politeRun = config.enabled && config.yieldToUser;
+
+  // Judged at each node: a run alone takes nearly the machine, and steps back once another one is in.
+  const applyCpuShare = () => {
+    if (!politeRun) return;
+    const { holders = readHolders } = deps;
+    const live = holders(heavyDir(env), { now: Date.now, isAlive: pidAlive, maxHoldMs: config.maxHoldMinutes * 60_000 });
+    cpuShare = cpuShareOf(config.slots, { alone: !live.some((h) => h.pid !== process.pid) });
+    for (const name of CPU_SHARE_ENVS) env[name] = String(cpuShare);
+  };
+
+  const reclaimBelow = (floor) => {
+    const { freeMem = freemem, reclaim = reclaimUnlessDisabled } = deps;
+    if (reclaimed || !config.reclaimIdleMinutes || freeMem() / GB >= floor) return;
+    reclaimed = true;
+    try {
+      const { freed, containers = [] } = reclaim({ projectPath, feature, config, env });
+      const gone = [...freed, ...containers];
+      if (gone.length) log(`heavy: RAM abaixo do piso, derrubei stacks paradas: ${gone.join(', ')}`);
+    } catch {}
+  };
 
   const restoreEnv = () => {
     if (!saved) return;
@@ -59,6 +86,7 @@ export function createHeavyGate({
   const raiseFloor = (kind) => {
     const floor = minFreeMemFor(config, kind);
     if (!lease || floor <= admittedGb) return;
+    reclaimBelow(floor);
     const result = awaitFreeMemory({
       minFreeMemGb: floor, waitTimeoutMs: config.waitTimeoutSec * 1000, kind, log, ...deps,
     });
@@ -85,6 +113,7 @@ export function createHeavyGate({
   return {
     config,
     get waitedMs() { return waitedMs; },
+    get cpuShare() { return cpuShare; },
 
     enter(node, kind = heavyClass(node)) {
       const suite = isVerifySuite({ label, node });
@@ -92,12 +121,14 @@ export function createHeavyGate({
         if (suite && lease && !suiteEntered) awaitSuite();
         raiseFloor(kind);
         updateLease(lease, { node });
+        applyCpuShare();
         return;
       }
       for (const warning of config.warnings ?? []) log(`heavy: ${warning}`);
 
       if (config.enabled) {
         const minFreeMemGb = minFreeMemFor(config, kind);
+        reclaimBelow(minFreeMemGb);
         const result = acquireHeavy({
           dir: heavyDir(env),
           slots: config.slots,
@@ -121,8 +152,9 @@ export function createHeavyGate({
         waitedMs = result.waitedMs;
       }
 
-      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV] };
+      saved = Object.fromEntries([NODE_REUSE_ENV, LEASE_ENV, ...CPU_SHARE_ENVS].map((name) => [name, env[name]]));
       if (config.disableNodeReuse) env[NODE_REUSE_ENV] = '1';
+      applyCpuShare();
       if (lease) env[LEASE_ENV] = String(process.pid);
       entered = true;
       if (lease) {

package/src/lib/heavy/reclaim.js

@@ -0,0 +1,107 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultExec } from '../../../framework/hooks/shared/e2e-check.js';
+import { heavyDir, readHolders } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
+import { EVENTS_FILE } from '../../../framework/hooks/shared/telemetry-logger.js';
+import { tearDownFeatureStack } from '../e2e/stack-teardown.js';
+import { projectKey, readRegistry } from '../projects/registry.js';
+import { resolveFeatureTree } from '../worktree/feature-truth.js';
+import { afterHeavyRun } from './cleanup.js';
+import { liveE2eStacks, repoMainRoot } from './live-stacks.js';
+
+const DOCKER_TIMEOUT_MS = 10_000;
+
+function lastActivityMs(tree) {
+  try {
+    return statSync(join(tree, EVENTS_FILE)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function liveHolders(config, env, now) {
+  return readHolders(heavyDir(env), { now, isAlive: pidAlive, maxHoldMs: config.maxHoldMinutes * 60_000 });
+}
+
+function registeredRoots() {
+  try {
+    return readRegistry().projects.map((p) => p.dir);
+  } catch {
+    return [];
+  }
+}
+
+const uniqueRoots = (roots) => [...new Map(roots.map((r) => [projectKey(r), r])).values()];
+
+// One daemon answers for every project: asking it once per project would add a hung timeout each.
+function onceByArgs(exec) {
+  const seen = new Map();
+  return (file, args, opts) => {
+    const key = args.join(' ');
+    if (!seen.has(key)) seen.set(key, exec(file, args, opts));
+    return seen.get(key);
+  };
+}
+
+function reclaimStacks({ root, feature, held, idleMs, now, stacks, treeOf, activityOf, tearDown, exec }) {
+  const freed = [];
+  for (const stack of stacks(root, { exec })) {
+    if (!stack.feature || stack.state === 'unknown' || stack.feature === feature || held.has(stack.feature)) continue;
+    const archived = stack.state === 'archived';
+    // A feature without a worktree lives in the root that listed it.
+    const tree = archived ? null : treeOf(stack.feature, root) ?? root;
+    if (!archived) {
+      // Unknown activity counts as live: another session's verifier may be navigating this stack.
+      const last = activityOf(tree);
+      if (last === null || now() - last < idleMs) continue;
+    }
+    // An active feature keeps its data: the next `e2e up` only rebuilds.
+    const result = tearDown(stack.feature, { root, worktreePath: tree, volumes: archived });
+    if (result?.status !== 'fail') freed.push(stack.feature);
+  }
+  return freed;
+}
+
+function reclaimContainers(prefixes, exec) {
+  const removed = [];
+  for (const prefix of prefixes) {
+    const ps = exec('docker', ['ps', '-a', '--filter', `name=^${prefix}`, '--format', '{{.Names}}'], { timeout: DOCKER_TIMEOUT_MS });
+    if (ps.code !== 0) continue;
+    for (const name of String(ps.output ?? '').split(/\r?\n/).map((n) => n.trim()).filter(Boolean)) {
+      if (exec('docker', ['rm', '-f', name], { timeout: DOCKER_TIMEOUT_MS }).code === 0) removed.push(name);
+    }
+  }
+  return removed;
+}
+
+/** The entry every real caller uses: a test suite faking low RAM must never reach this machine's stacks. */
+export function reclaimUnlessDisabled(options) {
+  if (process.env.MORPH_HEAVY_RECLAIM === 'off') return { freed: [], containers: [] };
+  return reclaimMemory(options);
+}
+
+export function reclaimMemory({ projectPath, feature = null, config, env = process.env, deps = {} }) {
+  const {
+    stacks = liveE2eStacks, tearDown = tearDownFeatureStack, treeOf = (f, root) => resolveFeatureTree(f, root).tree,
+    activityOf = lastActivityMs, holders = liveHolders, buildServer = afterHeavyRun, now = Date.now,
+    roots = registeredRoots, exec = defaultExec,
+  } = deps;
+  if (!config.reclaimIdleMinutes) return { freed: [], containers: [] };
+
+  const cachedExec = onceByArgs(exec);
+  const live = holders(config, env, now);
+  const held = new Set(live.map((h) => h.feature).filter(Boolean));
+  const idleMs = config.reclaimIdleMinutes * 60_000;
+
+  const freed = uniqueRoots([repoMainRoot(projectPath), ...roots()]).flatMap((root) => reclaimStacks({
+    root, feature, held, idleMs, now, stacks, treeOf, activityOf, tearDown, exec: cachedExec,
+  }));
+
+  // A test container has no owner to ask: any holder that may be testing protects them all.
+  const testing = live.some((h) => h.node === 'tests' || !h.node);
+  const containers = testing ? [] : reclaimContainers(config.reclaimContainers, exec);
+
+  buildServer({ projectPath, config, env, onlyUnderPressure: true });
+  return { freed, containers };
+}

package/src/lib/heavy/watchdog.js

@@ -0,0 +1,46 @@
+import { appendFileSync, existsSync, writeFileSync } from 'node:fs';
+import { freemem } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { GB } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
+import { stopTree } from '../procs/prune.js';
+import { reclaimUnlessDisabled } from './reclaim.js';
+
+const SAMPLE_MS = 10_000;
+const LOW_SAMPLES_TO_STOP = 6;
+const EXIT_BUSY = '3';
+
+/** The floor judges only the start of a node; this judges the middle of one. It only ever stops its own run. */
+export async function watchRun({
+  workerPid, exitFile, errFile, projectPath, feature, config, env = process.env, deps = {},
+}) {
+  const {
+    freeMem = freemem, isAlive = pidAlive, wait = sleep, sampleMs = SAMPLE_MS, reclaim = reclaimUnlessDisabled,
+    list, kill,
+  } = deps;
+  if (!config.criticalFreeMemGb) return 'off';
+
+  let low = 0;
+  while (isAlive(workerPid) && !existsSync(exitFile)) {
+    const freeGb = freeMem() / GB;
+    if (freeGb >= config.criticalFreeMemGb) {
+      low = 0;
+    } else {
+      low += 1;
+      if (low === 1) {
+        try {
+          reclaim({ projectPath, feature, config, env });
+        } catch {}
+      }
+      if (low >= LOW_SAMPLES_TO_STOP) {
+        if (existsSync(exitFile)) return 'finished';
+        stopTree(workerPid, { list, kill });
+        appendFileSync(errFile, `verify parado: ${freeGb.toFixed(1)} GB livres, abaixo de heavy.criticalFreeMemGb (${config.criticalFreeMemGb}) por ${LOW_SAMPLES_TO_STOP} leituras. Não é vermelho.\n`);
+        writeFileSync(exitFile, EXIT_BUSY);
+        return 'stopped';
+      }
+    }
+    await wait(sampleMs);
+  }
+  return 'finished';
+}

package/src/lib/next-step.js

@@ -6,5 +6,6 @@ export function nextStepFor(featureName, tree) {
   const signals = collectNextSignals(featureName, tree);
   if (!signals) return null;
   signals.verificationStale = treeMovedSince(tree, signals.verification?.sha);
+  signals.affectedStale = treeMovedSince(tree, signals.affected?.sha);
   return { ...decideNext(signals), phase: signals.phase, failStreak: signals.failStreak };
 }

package/src/lib/plan/checks.js

@@ -103,7 +103,7 @@ export function validatePlan(plan, { workType = null, riskRules = true, text = n
     } else if (riskRules && proof === 'teste' && risk === null) {
       errors.push(`${c.id}: "prova: teste" sem "risco:" (${RISK_KINDS.join(' | ')}) — sem risco, a prova é "leitura" ou "e2e"${at(c.line)}`);
     } else if (risk && proof === 'leitura') {
-      warnings.push(`${c.id}: risco "${risk}" provado só por leitura${at(c.line)}`);
+      (riskRules ? errors : warnings).push(`${c.id}: risco "${risk}" provado só por leitura — quem tem risco se prova executando ("teste" ou "e2e")${at(c.line)}`);
     }
     if (canonicalRung(c.rung) === false) {
       errors.push(`${c.id}: degrau "${c.rung}" fora de ${REWORK_RUNGS.join(' | ')}${at(c.line)}`);

package/src/lib/procs/prune.js

@@ -1,4 +1,26 @@
-import { readProcess } from './list.js';
+import { listProcesses, readProcess } from './list.js';
+
+export function descendantsOf(pid, procs) {
+  const found = [];
+  const queue = [pid];
+  while (queue.length) {
+    const parent = queue.shift();
+    for (const child of procs.filter((p) => p.ppid === parent && !found.includes(p.pid))) {
+      found.push(child.pid);
+      queue.push(child.pid);
+    }
+  }
+  return found;
+}
+
+export function stopTree(pid, { list = listProcesses, kill = (target) => process.kill(target) } = {}) {
+  const { procs } = list();
+  for (const target of [...descendantsOf(pid, procs ?? []).reverse(), pid]) {
+    try {
+      kill(target);
+    } catch {}
+  }
+}
 
 export function pruneOrphans(rows, { read = readProcess, kill = (pid) => process.kill(pid) } = {}) {
   const results = [];

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

@@ -90,6 +90,7 @@ function makeNode(partial) {
     projectCount: partial.projectCount ?? 1,
     // null is "not an eval node", distinct from an empty block (already refused).
     evals: partial.evals ?? null,
+    affected: partial.affected ?? null,
     status: partial.status ?? null,
     reason: partial.reason ?? null,
   };
@@ -128,6 +129,9 @@ function firstProblem(raw, projectPath) {
   if (raw.runner !== undefined && !TEST_RUNNERS.includes(raw.runner)) {
     return `runner must be one of ${TEST_RUNNERS.join(' | ')}`;
   }
+  if (raw.affected !== undefined && (!isPlainObject(raw.affected) || typeof raw.affected.flag !== 'string' || !raw.affected.flag.trim())) {
+    return 'affected must be an object with a non-empty flag';
+  }
   if (raw.expectedCount !== undefined && !isNonNegativeInteger(raw.expectedCount)) {
     return 'expectedCount must be an integer >= 0';
   }
@@ -217,6 +221,7 @@ export function validateTestNodes(config, projectPath = null) {
       e2e: entry.e2e ?? false,
       linuxImage: entry.linuxImage ?? null,
       evals: entry.evals ?? null,
+      affected: entry.affected ?? null,
       projectCount: 1,
     });
   });

package/src/lib/validators/verify-runner.js

@@ -22,6 +22,7 @@ import {
 } from '../tasks/eval-node.js';
 import { runValidation } from './validation-runner.js';
 import { createHeavyGate } from '../heavy/gate.js';
+import { selectAffected } from '../verify/affected.js';
 import {
   cacheEntryFrom, planReuse, readVerifyCache, reusedEntry, writeVerifyCache,
 } from './verify-cache.js';
@@ -48,12 +49,34 @@ export class VerifyUsageError extends Error {
 export async function runVerify(projectPath, featureName, options = {}) {
   const gate = options._heavyGate ?? createHeavyGate({ projectPath, feature: featureName });
   try {
-    return await runVerifyGated(projectPath, featureName, options, gate);
+    return await runVerifyGated(projectPath, featureName, applyAffectedScope(projectPath, options), gate);
   } finally {
     gate.release();
   }
 }
 
+export function withCpuShare(node, share) {
+  if (!share || node.runner !== 'vitest' || /--max-?workers/i.test(node.command ?? '')) return node;
+  return { ...node, command: `${node.command} --maxWorkers=${share}` };
+}
+
+function applyAffectedScope(projectPath, options) {
+  if (!options.affected) return options;
+  const conflict = [['filter', '--filter'], ['recordBaseline', '--record-baseline'], ['refreshCache', '--refresh-cache'], ['linux', '--linux']]
+    .find(([key]) => options[key]);
+  if (conflict) throw new VerifyUsageError(`--affected escolhe os testes sozinho; não combina com ${conflict[1]}`);
+
+  const selection = selectAffected({ projectPath, nodes: resolveTestNodes(projectPath).nodes, deps: options._affectedDeps });
+  if (selection.scope === 'full') return { ...options, escalatedBecause: selection.reason };
+  return {
+    ...options,
+    selection,
+    skipE2e: true,
+    skipBuild: options.skipBuild || selection.docsOnly,
+    skipTests: options.skipTests || selection.nodes.length === 0,
+  };
+}
+
 async function runVerifyGated(projectPath, featureName, options, gate) {
   const {
     timeout = DEFAULT_BUILD_TIMEOUT,
@@ -81,7 +104,8 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
 
   // Usage errors are judged before the build: paying for a build to discover a typo
   // is the worst ordering, and a refusal after the cache was touched leaves a half-rewritten tree.
-  const testPlan = resolveTestNodes(projectPath);
+  const resolvedPlan = resolveTestNodes(projectPath);
+  const testPlan = options.selection ? { ...resolvedPlan, nodes: options.selection.nodes } : resolvedPlan;
   const filter = parseTestFilter(options.filter);
   if (filter && !testPlan.nodes.some((node) => nodeMatchesFilter(node, filter))) {
     const declared = testPlan.nodes.map((node) => node.id).join(', ') || '(none)';
@@ -121,6 +145,11 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
 
   const nodes = {};
   const feedback = [];
+  if (options.escalatedBecause) feedback.push(`[verify] rodada completa: ${options.escalatedBecause}`);
+  if (options.selection) {
+    const kept = options.selection.nodes.map((n) => n.id).join(', ') || 'nenhuma';
+    feedback.push(`[verify] rodada afetada, suítes: ${kept}; a completa roda uma vez antes da aprovação`);
+  }
 
   // Only a complete run feeds or reads the cache: a partial one proves nothing about the nodes it left out.
   const cacheDir = fingerprint && !filter && !skipTests && !skipBuild && !skipE2e && !recordBaseline
@@ -212,6 +241,7 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     feature: featureName,
     stack,
     status,
+    scope: options.selection ? 'affected' : 'full',
     nodes,
     feedback,
     reused,
@@ -454,7 +484,7 @@ async function runOneTestNode({
   const start = Date.now();
   const childEnv = env || evalChannel ? { ...(env || {}), ...(evalChannel?.env || {}) } : null;
   const result = await _runTestSuite(projectPath, {
-    timeout, node, ...buildFacts, background: node.parallel === true, ...(childEnv ? { env: childEnv } : {}),
+    timeout, node: withCpuShare(node, gate.cpuShare), ...buildFacts, background: node.parallel === true, ...(childEnv ? { env: childEnv } : {}),
   });
   const durationMs = Date.now() - start;
   const logPath = writeFailedRunLog(projectPath, node, result);
@@ -596,7 +626,7 @@ function judgeRun({ node, result, durationMs, logPath = null }) {
   if (verdict.verdict === 'drop') warnings.push(verdict.reason);
 
   // Without a baseline, zero is the floor: a green run over no test is a suite that stopped running.
-  if (result.passed && count === 0 && node.runner !== EVAL_RUNNER && !Number.isInteger(node.expectedCount)) {
+  if (result.passed && count === 0 && !node.allowEmpty && node.runner !== EVAL_RUNNER && !Number.isInteger(node.expectedCount)) {
     return { ...entry, status: 'fail', durationMs, count, warnings, reason: 'suíte verde sem nenhum teste executado', output: '' };
   }
 

package/src/lib/verify/affected.js

@@ -0,0 +1,141 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { changedPathsAgainst, detectDefaultBranch } from '../git/default-branch.js';
+import { resolveBaseRef } from '../git/branch-classifier.js';
+import { contractsTouched, migrationsTouched } from '../risk-detector.js';
+import { isTestFile } from '../validators/reuse/symbol-scanner.js';
+
+const MAX_TEST_CLASSES = 40;
+const INLINE_FILTER = /(^|\s)(--filter|-Filter)\s+(?:"([^"]*)"|(\S+))/i;
+const SCRIPT_IN_COMMAND = /([\w./\\-]+\.(?:ps1|sh))\b/i;
+const PS_FILTER_PARAM = /\[string\]\s*\$Filter\b(?:\s*=\s*['"]([^'"]*)['"])?/i;
+const PS_FILTER_USED = /dotnet\s+test[^\n]*\$Filter\b/i;
+const FORWARDS_ARGS = /dotnet\s+test[^\n]*("?\$@"?|\$\{@\}|@args|\$args)/i;
+const EVAL_NODE =/(^|[-_])evals?($|[-_])/i;
+const DOC_PATH =/\.(md|mdx|txt|png|jpe?g|gif|svg|webp)$/i;
+const DOTNET_SOURCE = /\.(cs|razor|cshtml)$/i;
+const SCRIPT_SOURCE = /\.(tsx?|jsx?|mjs|cjs|css|json)$/i;
+// Everything compiles or resolves through these, so the diff says nothing about what they reach.
+const WIDE_PATH = /(^|\/)(package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|global\.json|Directory\.(Build|Packages)\.(props|targets)|tsconfig[^/]*\.json|vitest\.config\.[^/]+|[^/]+\.(csproj|sln|slnx))$/i;
+
+const defaultGit = (args, cwd) => execFileSync('git', args, { cwd, stdio: 'pipe' }).toString();
+
+function mergeBase(baseRef, cwd, git) {
+  try {
+    return git(['merge-base', 'HEAD', baseRef], cwd).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function testFilesNaming(names, cwd, git) {
+  if (names.length === 0) return [];
+  try {
+    const output = git(['grep', '-lw', ...names.flatMap((n) => ['-e', n]), '--', '*.cs'], cwd);
+    return output.split(/\r?\n/).filter((path) => path && isTestFile(path));
+  } catch {
+    // git grep exits 1 when nothing matches.
+    return [];
+  }
+}
+
+const classOf = (path) => basename(path, extname(path));
+
+const readText = (path) => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+/** Reads the wrapper the command calls, so a project gets the narrowing without declaring anything. */
+function scriptFilter(node, cwd, read) {
+  const script = SCRIPT_IN_COMMAND.exec(node.command ?? '')?.[1];
+  const text = script ? read(join(cwd, node.cwd ?? '.', script)) : null;
+  if (!text) return null;
+  if (PS_FILTER_USED.test(text)) {
+    const param = PS_FILTER_PARAM.exec(text);
+    if (param) return { flag: '-Filter', baseFilter: param[1] ?? null };
+  }
+  return FORWARDS_ARGS.test(text) ? { flag: '--filter' } : null;
+}
+
+function narrowDotnet(node, classes, cwd, read) {
+  const selected = classes.map((c) => `FullyQualifiedName~${c}`).join('|');
+  const inline = INLINE_FILTER.exec(node.command ?? '');
+  if (inline) {
+    const [whole, lead, flag, quoted, bare] = inline;
+    return node.command.replace(whole, `${lead}${flag} "(${quoted ?? bare})&(${selected})"`);
+  }
+  const plain = /\bdotnet\s+test\b/.test(node.command ?? '') ? { flag: '--filter' } : null;
+  const how = node.affected ?? plain ?? scriptFilter(node, cwd, read);
+  if (!how) return null;
+  const filter = how.baseFilter ? `(${how.baseFilter})&(${selected})` : selected;
+  return `${node.command} ${how.flag} "${filter}"`;
+}
+
+function selectDotnet(node, relevant, cwd, git, read) {
+  const tests = relevant.filter(isTestFile);
+  const sources = relevant.filter((p) => !isTestFile(p)).map(classOf);
+  const classes = [...new Set([...tests, ...testFilesNaming(sources, cwd, git)].map(classOf))].sort();
+  if (classes.length === 0) return { skip: true };
+  if (classes.length > MAX_TEST_CLASSES) return { wide: classes.length };
+  const command = narrowDotnet(node, classes, cwd, read);
+  // A command nothing can narrow runs whole, as it would without this.
+  return command ? { node: { ...node, command, allowEmpty: true }, classes } : { node };
+}
+
+function selectVitest(node, base) {
+  return { node: { ...node, command: `${node.command} --changed ${base} --passWithNoTests`, allowEmpty: true } };
+}
+
+function selectNode(node, { changed, base, cwd, git, read }) {
+  // A project may run its evals as a plain dotnet node: they cost money, so the name counts too.
+  if (node.e2e || node.evals || EVAL_NODE.test(node.id ?? '')) return { skip: true };
+  const prefix = node.cwd && node.cwd !== '.' ? `${node.cwd.replace(/\\/g, '/').replace(/\/$/, '')}/` : '';
+  const inside = changed.filter((p) => p.startsWith(prefix));
+  if (node.runner === 'dotnet') {
+    const relevant = inside.filter((p) => DOTNET_SOURCE.test(p));
+    return relevant.length ? selectDotnet(node, relevant, cwd, git, read) : { skip: true };
+  }
+  const relevant = inside.filter((p) => SCRIPT_SOURCE.test(p));
+  if (relevant.length === 0) return { skip: true };
+  return node.runner === 'vitest' ? selectVitest(node, base) : { node };
+}
+
+/** @returns {{ scope: 'full', reason: string } | { scope: 'affected', base: string, docsOnly: boolean, nodes: object[], skipped: string[] }} */
+export function selectAffected({ projectPath, nodes, deps = {} }) {
+  const {
+    git = defaultGit, changedPaths = changedPathsAgainst, read = readText,
+    baseRefOf = (p) => resolveBaseRef(detectDefaultBranch(p), p),
+  } = deps;
+  const baseRef = baseRefOf(projectPath);
+  const base = baseRef ? mergeBase(baseRef, projectPath, git) : null;
+  if (!base) return { scope: 'full', reason: 'sem base de comparação com a branch padrão' };
+
+  const changed = changedPaths(base, projectPath)
+    .map((p) => p.replace(/\\/g, '/'))
+    .filter((p) => !p.startsWith('.morph/'));
+
+  const migration = migrationsTouched(changed);
+  if (migration.length) return { scope: 'full', reason: `migration tocada: ${migration[0]}` };
+  const contract = contractsTouched(changed);
+  if (contract.length) return { scope: 'full', reason: `contrato tocado: ${contract[0]}` };
+  // A test project's own file reaches only tests, which the complete run still covers.
+  const wide = changed.find((p) => WIDE_PATH.test(p) && !isTestFile(p));
+  if (wide) return { scope: 'full', reason: `arquivo que alcança o projeto inteiro: ${wide}` };
+
+  const code = changed.filter((p) => !DOC_PATH.test(p));
+  const context = { changed: code, base, cwd: projectPath, git, read };
+  const selected = [];
+  const skipped = [];
+  for (const node of nodes) {
+    const choice = selectNode(node, context);
+    if (choice.wide) return { scope: 'full', reason: `código compartilhado: ${choice.wide} classes de teste alcançadas` };
+    if (choice.skip) skipped.push(node.id);
+    else selected.push(choice.node);
+  }
+  return { scope: 'affected', base, docsOnly: code.length === 0, nodes: selected, skipped };
+}