@polymorphism-tech/morph-spec 8.41.0 → 8.43.0

package/src/lib/detectors/claude-config-detector.js

@@ -11,21 +11,50 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
+/**
+ * Plugin ids (`name@marketplace`) that are switched ON. User settings first, then
+ * the project's; a later file overrides an earlier one, and `false` turns one off.
+ *
+ * @param {string} targetPath - Root path of the project
+ * @param {string} [home] - Home directory holding `.claude/settings.json`
+ * @returns {string[]}
+ */
+export function readEnabledPlugins(targetPath, home = homedir()) {
+  const merged = new Map();
+  const files = [
+    join(home, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.local.json'),
+  ];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    try {
+      const map = JSON.parse(readFileSync(file, 'utf8').replace(/^/, '')).enabledPlugins;
+      if (!map || typeof map !== 'object') continue;
+      for (const [id, on] of Object.entries(map)) merged.set(id, on === true);
+    } catch { /* invalid JSON */ }
+  }
+  return [...merged].filter(([, on]) => on).map(([id]) => id);
+}
+
 /**
  * Detect Claude Code configuration for a project.
  *
  * @param {string} targetPath - Root path of the project
- * @returns {{ plugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
+ * @returns {{ plugins: string[], enabledPlugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
  */
 export function detectClaudeConfig(targetPath) {
   const result = {
     plugins: [],
+    enabledPlugins: [],
     mcpServers: [],
     customSkills: [],
     customCommands: [],
     hooks: [],
   };
 
+  result.enabledPlugins = readEnabledPlugins(targetPath);
+
   const mcpJsonNames = new Set();
 
   try {

package/src/lib/heavy/cleanup.js

@@ -0,0 +1,70 @@
+import { readdirSync } from 'node:fs';
+import { getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
+import { listProcesses, defaultProcExec } from '../procs/list.js';
+import { readProjectConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { heavyDir, runExclusive } from '../../../framework/hooks/shared/heavy-slots.js';
+
+const DOTNET_ACTIVE = /\bdotnet(?:\.exe)?["']?\s+(?:build|test|publish|pack|msbuild|restore|run|watch|vstest)\b/i;
+const IDLE_WORKER = /\/nodemode:\d|vbcscompiler|razorserver/i;
+const SHUTDOWN_SCOPES = new Set(['feature', 'e2e-down', 'prune']);
+const SHUTDOWN_TIMEOUT_MS = 30_000;
+const TAIL_CHARS = 400;
+
+function hasDotnet(projectPath) {
+  const config = readProjectConfig(projectPath);
+  const stack = config?.project?.stack;
+  try {
+    if (stack && getBuildSteps(stack, { cwd: projectPath }).some((s) => /\bdotnet\b/.test(s.command))) return true;
+  } catch { /* stack sem passo de build */ }
+  try {
+    return readdirSync(projectPath).some((n) => /\.(sln|slnx|csproj)$/i.test(n));
+  } catch {
+    return false;
+  }
+}
+
+export function dotnetBusy(procs) {
+  return procs.some((p) => {
+    if (p.name === 'testhost') return true;
+    const cmd = p.cmd ?? '';
+    if (p.name === 'vbcscompiler' || IDLE_WORKER.test(cmd)) return false;
+    if (p.name === 'msbuild') return true;
+    return p.name === 'dotnet' && DOTNET_ACTIVE.test(cmd);
+  });
+}
+
+export function afterHeavyRun({ projectPath, config, scope, env = process.env, deps = {} }) {
+  const {
+    exec = defaultProcExec, list = listProcesses, dotnet = hasDotnet, exclusive = runExclusive,
+  } = deps;
+
+  if (!config.enabled) return { status: 'skipped', reason: 'semáforo desligado: sem ele nada prova que outra sessão não está compilando' };
+  if (!config.shutdownBuildServer) return { status: 'skipped', reason: 'desligado em heavy.shutdownBuildServer' };
+  if (!SHUTDOWN_SCOPES.has(scope)) {
+    return { status: 'skipped', reason: 'escopo de task: o servidor de compilação segue quente para a próxima task' };
+  }
+  if (!dotnet(projectPath)) return { status: 'skipped', reason: 'projeto sem .NET' };
+
+  const guarded = exclusive({
+    dir: heavyDir(env), label: 'build-server-shutdown', maxHoldMs: config.maxHoldMinutes * 60_000, env,
+  }, () => {
+    const listing = list();
+    if (listing.procs === null) return { status: 'skipped', reason: `não consegui listar processos (${listing.reason})` };
+    if (dotnetBusy(listing.procs)) return { status: 'skipped', reason: 'há dotnet build/test vivo fora do semáforo' };
+
+    const res = exec('dotnet', ['build-server', 'shutdown'], { timeout: SHUTDOWN_TIMEOUT_MS });
+    if (res.missing) return { status: 'skipped', reason: 'dotnet indisponível no PATH' };
+    if (res.code !== 0) {
+      return { status: 'failed', reason: `dotnet build-server shutdown saiu ${res.code}`, output: String(res.output ?? '').slice(-TAIL_CHARS) };
+    }
+    return { status: 'ran' };
+  });
+
+  if (!guarded.ran) {
+    const why = guarded.reason === 'holders'
+      ? 'outra sessão segura slot do semáforo pesado'
+      : `semáforo indisponível (${guarded.reason})`;
+    return { status: 'skipped', reason: why };
+  }
+  return guarded.result;
+}

package/src/lib/heavy/gate.js

@@ -0,0 +1,96 @@
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import {
+  acquireHeavy, describeBusy, heavyDir, releaseHeavy, updateLease,
+} from '../../../framework/hooks/shared/heavy-slots.js';
+
+export class HeavyBusyError extends Error {
+  constructor(result, config) {
+    super(HeavyBusyError.message(result, config));
+    this.name = 'HeavyBusyError';
+    this.code = 'heavy-busy';
+    this.reason = result.reason;
+    this.holders = result.holders;
+    this.freeGb = result.freeGb;
+    this.waitedMs = result.waitedMs;
+  }
+
+  static message(result, config) {
+    return describeBusy(result, config);
+  }
+}
+
+const NODE_REUSE_ENV = 'MSBUILDDISABLENODEREUSE';
+const LEASE_ENV = 'MORPH_HEAVY_LEASE';
+
+export function createHeavyGate({
+  projectPath, label = 'verify', feature = null, config = readHeavyConfig(projectPath),
+  env = process.env, deps = {}, log = (m) => process.stderr.write(`${m}\n`),
+} = {}) {
+  let entered = false;
+  let lease = null;
+  let waitedMs = 0;
+  let exitHandler = null;
+  let saved = null;
+
+  const restoreEnv = () => {
+    if (!saved) return;
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete env[key];
+      else env[key] = value;
+    }
+    saved = null;
+  };
+
+  const release = () => {
+    if (exitHandler) process.removeListener('exit', exitHandler);
+    exitHandler = null;
+    releaseHeavy(lease);
+    lease = null;
+    restoreEnv();
+    entered = false;
+  };
+
+  return {
+    config,
+    get waitedMs() { return waitedMs; },
+
+    enter(node) {
+      if (entered) {
+        updateLease(lease, { node });
+        return;
+      }
+      for (const warning of config.warnings ?? []) log(`heavy: ${warning}`);
+
+      if (config.enabled) {
+        const result = acquireHeavy({
+          dir: heavyDir(env),
+          slots: config.slots,
+          label,
+          feature,
+          node,
+          cwd: projectPath,
+          minFreeMemGb: config.minFreeMemGb,
+          waitTimeoutMs: config.waitTimeoutSec * 1000,
+          maxHoldMs: config.maxHoldMinutes * 60_000,
+          env,
+          log,
+          ...deps,
+        });
+        if (result.status === 'busy') throw new HeavyBusyError(result, config);
+        lease = result.lease;
+        waitedMs = result.waitedMs;
+      }
+
+      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV] };
+      if (config.disableNodeReuse) env[NODE_REUSE_ENV] = '1';
+      if (lease) env[LEASE_ENV] = String(process.pid);
+      entered = true;
+      if (lease) {
+        exitHandler = release;
+        process.once('exit', exitHandler);
+      }
+    },
+
+    release,
+  };
+}

package/src/lib/installers/mcp-installer.js

@@ -11,6 +11,7 @@ import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { homedir } from 'os';
 import { installMcpServers } from '../../utils/claude-settings-manager.js';
+import { mcpServerNames } from '../../utils/agents-installer.js';
 
 /**
  * Load the enhanced MCP registry (v3.0.0)
@@ -56,9 +57,11 @@ export function filterByStack(registry, stack, integrations = []) {
  * Match detected MCP servers against the registry
  * @param {Array} existingServers - From detectClaudeConfig().mcpServers
  * @param {Object} registry - MCP registry
+ * @param {string[]} [enabledPlugins] - From detectClaudeConfig().enabledPlugins. A plugin
+ *   that ships the server already runs it, and writing it to `.mcp.json` too starts it twice.
  * @returns {Object} Map of mcpName → { installed: true, source }
  */
-export function getInstalledMcps(existingServers, registry) {
+export function getInstalledMcps(existingServers, registry, enabledPlugins = []) {
   const installed = {};
   const registryNames = Object.keys(registry.mcps);
 
@@ -71,6 +74,15 @@ export function getInstalledMcps(existingServers, registry) {
     }
   }
 
+  const prefixes = enabledPlugins.map(id => `plugin_${String(id).split('@')[0].replace(/[^A-Za-z0-9_-]/g, '_')}_`);
+  for (const regName of registryNames) {
+    if (installed[regName]) continue;
+    const names = mcpServerNames(regName, registry.mcps[regName]);
+    if (names.some(n => prefixes.some(p => n.startsWith(p)))) {
+      installed[regName] = { installed: true, source: 'plugin' };
+    }
+  }
+
   return installed;
 }
 
@@ -597,12 +609,13 @@ export function generateSetupInstructions(name, mcpEntry) {
  * @param {Object} options
  * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
  * @param {string[]} [options.integrations] - `project.integrations`, matched like the stack
+ * @param {string[]} [options.enabledPlugins] - `detectClaudeConfig().enabledPlugins`
  * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
  */
 export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
   const registry = loadMcpRegistry();
   const relevant = filterByStack(registry, stack, options.integrations ?? []);
-  const installed = getInstalledMcps(existingMcps || [], registry);
+  const installed = getInstalledMcps(existingMcps || [], registry, options.enabledPlugins ?? []);
 
   const autoInstallable = {};
   const alreadyInstalled = {};

package/src/lib/mutation/adapters.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { dotnetBuildCommands, withFilter, withTrx, withoutBuild } from './commands.js';
+import { methodOf, parseTrx } from './trx.js';
+import { stripAnsi } from '../tasks/test-runner.js';
+
+const MAX_CAPTURE = 16 * 1024 * 1024;
+
+export function spawnExec(command, { cwd, env, timeoutMs }) {
+  return new Promise((done) => {
+    const start = Date.now();
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const child = spawn(command, { cwd, env, shell: true, windowsHide: true });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { if (stdout.length < MAX_CAPTURE) stdout += chunk; });
+    child.stderr.on('data', (chunk) => { if (stderr.length < MAX_CAPTURE) stderr += chunk; });
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    const finish = (status) => { clearTimeout(timer); done({ status, stdout, stderr, durationMs: Date.now() - start, timedOut }); };
+    child.on('error', (err) => { stderr += String(err.message); finish(null); });
+    child.on('close', (status) => finish(status));
+  });
+}
+
+const FAIL_LINE = /^\s*(?:FAIL|✗|×|✖|not ok)\b|AssertionError|Error:|Expected/i;
+
+function genericFailures(output) {
+  const lines = stripAnsi(output).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const first = lines.findIndex((l) => FAIL_LINE.test(l));
+  if (first === -1) return lines.slice(-3).map((l) => ({ name: l, message: '' }));
+  return [{ name: lines[first], message: lines.slice(first + 1, first + 3).join(' ⏎ ') }];
+}
+
+export function dotnetAdapter({ node, root, workDir, exec, subset, timeoutMs }) {
+  const cwd = resolve(root, node.cwd || '.');
+  const trxDir = join(workDir, 'trx');
+  mkdirSync(trxDir, { recursive: true });
+  const base = withoutBuild(node.command);
+  const filterOf = { subset: () => subset.filter, names: (filter) => filter };
+  const commandFor = (scope, label, filter) => withTrx(
+    scope === 'full' ? base : withFilter(base, filterOf[scope](filter)),
+    { dir: trxDir, name: `${label}.trx` },
+  );
+  const runTests = async ({ scope, label, env, filter }) => {
+    const trxPath = join(trxDir, `${label}.trx`);
+    const r = await exec(commandFor(scope, label, filter), { cwd, env, timeoutMs, label });
+    if (!existsSync(trxPath)) {
+      return { outcome: 'crash', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs, note: r.timedOut ? `timeout de ${timeoutMs} ms` : `sem TRX (exit ${r.status})` };
+    }
+    const t = parseTrx(readFileSync(trxPath, 'utf8'));
+    if (!t.parsed || t.aborted > 0 || /abort/i.test(t.runOutcome ?? '')) {
+      return { outcome: 'crash', executed: t.executed, total: t.total, failed: t.failed, failedTests: t.failedTests, durationMs: r.durationMs, note: 'a rodada foi abortada (testhost caiu ou estourou o tempo)' };
+    }
+    return { outcome: t.failed > 0 ? 'red' : 'green', executed: t.executed, total: t.total, failed: t.failed, failedTests: t.failedTests, durationMs: r.durationMs };
+  };
+  return {
+    kind: 'dotnet',
+    hasSubset: Boolean(subset?.usable),
+    buildCommands: dotnetBuildCommands(node, root),
+    cwd,
+    runTests,
+    reproduce: ({ names, label, env }) => runTests({
+      scope: 'names',
+      label,
+      env,
+      filter: [...new Set(names.map(methodOf))].map((n) => `FullyQualifiedName~${n}`).join('|'),
+    }),
+  };
+}
+
+export function genericAdapter({ node, root, exec, subset, timeoutMs }) {
+  const cwd = resolve(root, node.cwd || '.');
+  return {
+    kind: node.runner,
+    hasSubset: Boolean(subset?.usable),
+    buildCommands: [],
+    cwd,
+    async runTests({ scope, label, env }) {
+      const command = scope === 'subset' ? subset.command : node.command;
+      const r = await exec(command, { cwd, env, timeoutMs, label });
+      if (r.timedOut) return { outcome: 'crash', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs, note: `timeout de ${timeoutMs} ms` };
+      if (r.status === 0) return { outcome: 'green', executed: null, total: null, failed: 0, failedTests: [], durationMs: r.durationMs };
+      const failedTests = genericFailures(`${r.stdout}\n${r.stderr}`);
+      return { outcome: 'red', executed: null, total: null, failed: failedTests.length, failedTests, durationMs: r.durationMs };
+    },
+  };
+}

package/src/lib/mutation/commands.js

@@ -0,0 +1,60 @@
+import { dotnetBuildCommandFor, resolveTestBuildTargets } from '../tasks/test-runner.js';
+
+const FILTER = /--filter(?:[ =:])(?:"([^"]*)"|'([^']*)'|(\S+))/;
+const quote = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
+
+export function declaredFilter(command) {
+  const m = FILTER.exec(command);
+  return m ? (m[1] ?? m[2] ?? m[3]) : null;
+}
+
+export function withFilter(command, expression) {
+  const declared = declaredFilter(command);
+  if (declared === null) return `${command} --filter ${quote(expression)}`;
+  return command.replace(FILTER, () => `--filter ${quote(`(${declared})&(${expression})`)}`);
+}
+
+export function withTrx(command, { dir, name }) {
+  return `${command} --results-directory ${quote(dir)} --logger ${quote(`trx;LogFileName=${name}`)}`;
+}
+
+export function withoutBuild(command) {
+  return /(?:^|\s)--no-build(?:\s|$)/.test(command) ? command : `${command} --no-build`;
+}
+
+const CONFIGURATION = /(?:^|\s)(?:-c|--configuration)[ =:]?(?:"([^"]*)"|(\S+))/;
+const VERBOSITY = /\s(?:-v|--verbosity)[ =:]?\S+/g;
+
+/**
+ * The verify's build command per target. The test command's `-c` follows it, and
+ * verbosity is minimal: at `quiet` the `Project -> dll` line the binary proof reads is gone.
+ */
+export function dotnetBuildCommands(node, projectPath) {
+  const configuration = CONFIGURATION.exec(node.command ?? '');
+  const flag = configuration ? ` -c ${configuration[1] ?? configuration[2]}` : '';
+  return resolveTestBuildTargets(node)
+    .map((target) => dotnetBuildCommandFor(target, projectPath))
+    .filter(Boolean)
+    .map((command) => `${command.replace(VERBOSITY, '')} -v m${flag}`);
+}
+
+const BUILT = /^\s*(?<project>\S.*?) -> (?<dll>.+\.dll)\s*$/gm;
+
+export function parseBuiltDlls(output) {
+  const dlls = new Map();
+  for (const m of String(output).matchAll(BUILT)) dlls.set(m.groups.project, m.groups.dll.trim());
+  return dlls;
+}
+
+const VITEST_RUN = /(vitest(?:\.mjs|\.js)?)\s+run\b/;
+
+export function relatedCommand(runner, command, files) {
+  const list = files.map(quote).join(' ');
+  if (runner === 'vitest' && VITEST_RUN.test(command)) {
+    return `${command.replace(/\s+run\b/, ' related')} ${list} --run`;
+  }
+  if (runner === 'jest' && /\bjest\b/.test(command) && !/[;&|]/.test(command)) {
+    return `${command} --findRelatedTests ${list}`;
+  }
+  return null;
+}

package/src/lib/mutation/manifest.js

@@ -0,0 +1,138 @@
+import { isAbsolute, normalize, sep } from 'node:path';
+
+export const MUTANT_ID = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+export const MODES = ['schemata', 'rebuild'];
+export const BACKSLASH_TOKEN = '{{BS}}';
+
+const expandBackslash = (s) => (typeof s === 'string' ? s.split(BACKSLASH_TOKEN).join(String.fromCharCode(92)) : s);
+
+export class ManifestError extends Error {
+  constructor(problems) {
+    super(`manifesto de mutantes inválido:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+    this.name = 'ManifestError';
+    this.problems = problems;
+  }
+}
+
+export function eolOf(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+const toEol = (s, eol) => s.replace(/\r?\n/g, eol);
+
+function lineBounds(text, line) {
+  let start = 0;
+  for (let n = 1; n < line; n++) {
+    const nl = text.indexOf('\n', start);
+    if (nl === -1) return null;
+    start = nl + 1;
+  }
+  const nl = text.indexOf('\n', start);
+  return { start, end: nl === -1 ? text.length : nl };
+}
+
+/**
+ * Where `find` begins: it must start on `line` and occur there exactly once,
+ * so the `arquivo:linha` of the report is a fact the tool derived, not typed.
+ */
+export function locate(text, { line, find }) {
+  const bounds = lineBounds(text, line);
+  if (!bounds) return { error: `o arquivo tem menos de ${line} linhas` };
+  const needle = toEol(find, eolOf(text));
+  const at = text.indexOf(needle, bounds.start);
+  if (at === -1) return { error: `\`find\` não aparece a partir da linha ${line}` };
+  if (at > bounds.end) {
+    const first = text.slice(0, at).split('\n').length;
+    return { error: `\`find\` começa na linha ${first}, não na ${line}` };
+  }
+  const again = text.indexOf(needle, at + 1);
+  if (again !== -1 && again <= bounds.end) {
+    return { error: `\`find\` aparece mais de uma vez na linha ${line}: estenda-o até ficar único` };
+  }
+  return { start: at, end: at + needle.length, needle };
+}
+
+export function validateManifest(manifest, { fileExists } = {}) {
+  const problems = [];
+  const list = manifest?.mutants;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new ManifestError(['`mutants` precisa ser um array com ao menos um mutante']);
+  }
+  const seen = new Set();
+  const mutants = list.map((raw, index) => {
+    const at = `mutants[${index}]${typeof raw?.id === 'string' ? ` (${raw.id})` : ''}`;
+    const m = raw ?? {};
+    if (typeof m.id !== 'string' || !MUTANT_ID.test(m.id)) problems.push(`${at}: \`id\` inválido (letra + letras/dígitos/_/-, até 32)`);
+    else if (seen.has(m.id)) problems.push(`${at}: \`id\` repetido`);
+    else seen.add(m.id);
+    if (typeof m.file !== 'string' || m.file === '') problems.push(`${at}: \`file\` ausente`);
+    else if (isAbsolute(m.file) || normalize(m.file).split(sep).includes('..')) problems.push(`${at}: \`file\` tem de ser relativo à raiz do projeto, sem \`..\``);
+    else if (fileExists && !fileExists(m.file)) problems.push(`${at}: \`file\` não existe: ${m.file}`);
+    if (!Number.isInteger(m.line) || m.line < 1) problems.push(`${at}: \`line\` tem de ser inteiro >= 1`);
+    if (typeof m.find !== 'string' || m.find === '') problems.push(`${at}: \`find\` ausente`);
+    if (typeof m.replace !== 'string') problems.push(`${at}: \`replace\` ausente (use string vazia para apagar)`);
+    else if (m.replace === m.find) problems.push(`${at}: \`replace\` igual a \`find\` não é mutação`);
+    if (m.mode !== undefined && !MODES.includes(m.mode)) problems.push(`${at}: \`mode\` tem de ser ${MODES.join(' | ')}`);
+    return {
+      id: m.id, file: typeof m.file === 'string' ? m.file.replace(/\\/g, '/') : m.file,
+      line: m.line, find: expandBackslash(m.find), replace: expandBackslash(m.replace), mode: m.mode ?? null,
+      note: typeof m.note === 'string' ? m.note : null,
+    };
+  });
+  if (problems.length > 0) throw new ManifestError(problems);
+  return mutants;
+}
+
+/**
+ * Resolves every mutant against the file text and refuses overlaps: two
+ * regions of one file inside each other cannot both be a switch in one build.
+ */
+export function resolveRegions(mutants, readText) {
+  const problems = [];
+  const byFile = new Map();
+  for (const m of mutants) {
+    const text = readText(m.file);
+    if (text === null) { problems.push(`${m.id}: não consegui ler ${m.file}`); continue; }
+    const at = locate(text, m);
+    if (at.error) { problems.push(`${m.id}: ${at.error}`); continue; }
+    const eol = eolOf(text);
+    const region = {
+      ...m, start: at.start, end: at.end, eol,
+      findText: at.needle, replaceText: toEol(m.replace, eol),
+    };
+    if (!byFile.has(m.file)) byFile.set(m.file, []);
+    byFile.get(m.file).push(region);
+  }
+  for (const regions of byFile.values()) {
+    regions.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < regions.length; i++) {
+      if (regions[i].start < regions[i - 1].end) {
+        problems.push(`${regions[i].id} e ${regions[i - 1].id} se sobrepõem em ${regions[i].file}: rode-os em manifestos separados`);
+      }
+    }
+  }
+  if (problems.length > 0) throw new ManifestError(problems);
+  return mutants.map((m) => [...byFile.values()].flat().find((r) => r.id === m.id));
+}
+
+export function applyRegions(text, regions, produce) {
+  let out = '';
+  let cursor = 0;
+  const spans = new Map();
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    out += text.slice(cursor, region.start);
+    const from = out.split('\n').length;
+    out += produce(region);
+    spans.set(region.id, { from, to: out.split('\n').length });
+    cursor = region.end;
+  }
+  return { text: out + text.slice(cursor), spans };
+}
+
+export function diffOf(m, limit = 160) {
+  const one = (s) => {
+    const flat = s.replace(/\r?\n\s*/g, ' ').replace(/\|/g, '\\|');
+    return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+  };
+  return `\`- ${one(m.find)}\` / \`+ ${one(m.replace)}\``;
+}

package/src/lib/mutation/plan.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isInside } from '../tasks/test-runner.js';
+import { isDotnetSource } from '../tasks/dotnet-test-introspection.js';
+import { resolveRegions, validateManifest } from './manifest.js';
+
+const JS_RUNNERS = new Set(['vitest', 'jest', 'node-test']);
+
+export function loadPlan({ root, planPath }) {
+  const manifest = JSON.parse(readFileSync(planPath, 'utf8').replace(/^/, ''));
+  const mutants = validateManifest(manifest, { fileExists: (f) => existsSync(join(root, f)) });
+  return resolveRegions(mutants, (f) => {
+    try { return readFileSync(join(root, f), 'utf8'); } catch { return null; }
+  });
+}
+
+export function pickNode(file, nodes, root) {
+  const abs = resolve(root, file);
+  if (isDotnetSource(file)) return nodes.find((n) => n.runner === 'dotnet') ?? null;
+  const owners = nodes
+    .filter((n) => JS_RUNNERS.has(n.runner) && isInside(abs, resolve(root, n.cwd || '.')))
+    .sort((a, b) => resolve(root, b.cwd || '.').length - resolve(root, a.cwd || '.').length);
+  return owners[0] ?? null;
+}
+
+export function groupByNode(regions, nodes, root) {
+  const groups = new Map();
+  const orphans = [];
+  for (const region of regions) {
+    const node = pickNode(region.file, nodes, root);
+    if (!node) { orphans.push(region); continue; }
+    if (!groups.has(node.id)) groups.set(node.id, { node, regions: [] });
+    groups.get(node.id).regions.push(region);
+  }
+  return { groups: [...groups.values()], orphans };
+}

package/src/lib/mutation/report.js

@@ -0,0 +1,66 @@
+const cell = (s) => String(s ?? '').replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
+const short = (md5) => (md5 ? md5.slice(0, 12) : '—');
+const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+
+function countCell(m) {
+  const scope = m.scope === 'subset' ? 'subconjunto' : 'suíte inteira';
+  switch (m.verdict) {
+    case 'killed': return m.scope === 'subset' ? `≥${m.killers} de ${m.executed} (${scope})` : `${m.killers} de ${m.executed ?? '?'} (${scope})`;
+    case 'survived': return `**0 de ${m.executed ?? '?'} (SOBREVIVEU, ${scope})**`;
+    case 'build-error': return '— (o mutante não compila: não é morte)';
+    default: return '— (inconclusivo: não conta como morte nem como sobrevivência)';
+  }
+}
+
+function reasonCell(m) {
+  if (m.verdict === 'survived') return m.reason || 'nenhum teste falhou na suíte inteira, com o mutante compilado de verdade';
+  const how = m.demoted ? ` [rebuild: ${m.demoted}]` : '';
+  return `${m.reason || '—'}${how}`;
+}
+
+const BINARY = {
+  md5: 'DLL do rebuild final idêntica (md5) à DLL construída da árvore limpa antes de qualquer mutante',
+  rebuilt: 'DLL recompilada DEPOIS da restauração e sem a chave de schemata, mas com md5 diferente da baseline — o build não é determinístico neste projeto, então o conteúdo não se compara',
+  unavailable: 'sem etapa de build neste runner: nada a provar sobre binário',
+  unlocated: 'ATENÇÃO — o build não informou a DLL dos projetos mutados, então o binário final NÃO pôde ser provado',
+  mismatch: 'ATENÇÃO — a DLL do rebuild final NÃO bate com a baseline e ainda carrega a chave de schemata',
+};
+
+export function renderSection(result, { head = null, date = null, subset = null, note = null } = {}) {
+  const lines = ['## Mutações', ''];
+  const { method } = result;
+  const where = subset?.usable
+    ? `${subset.classes.length} classe(s) de teste (${subset.files.changed?.length ?? 0} alterada(s) pela feature, ${subset.files.mentions?.length ?? 0} citando os tipos mutados)`
+    : (subset?.reason ?? 'nenhum');
+  lines.push(`**Método:** \`morph-spec mutate\`${head ? ` sobre ${head.slice(0, 8)}` : ''}${date ? ` em ${date}` : ''}.`);
+  lines.push(`- ${method.schemata} mutante(s) por chave em UM build (schemata), ${method.rebuild} por rebuild real${(method.jobs ?? 1) > 1 ? `; rodadas de escopo rápido em ${method.jobs} workers` : ''}.`);
+  lines.push(`- Escopo rápido: ${method.subset.live ? where : `desligado (${method.subset.note ?? subset?.reason ?? 'sem subconjunto'})`}.`);
+  lines.push('- Morto = falha nova (ausente na rodada-base do mesmo escopo) com o motivo abaixo; na suíte inteira, a falha também tem de se repetir. Sobrevivente de escopo rápido é SEMPRE refeito com o mutante compilado de verdade e a suíte inteira; "sobreviveu" só sai desse caminho.');
+  if (result.baseline.subset) lines.push(`- Rodada-base do subconjunto: ${result.baseline.subset.executed} executados, ${result.baseline.subset.failed} falhando.`);
+  if (result.baseline.full) lines.push(`- Rodada-base da suíte inteira: ${result.baseline.full.executed} executados, ${result.baseline.full.failed} falhando.`);
+  if (note) lines.push(`- ${note}`);
+  lines.push('');
+  lines.push('| # | Arquivo:linha | Mutação (diff) | md5 antes | md5 depois | Testes derrubados | Motivo da falha |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const m of result.mutants) {
+    lines.push(`| ${m.id} | ${cell(`${m.file}:${m.line}`)} | ${m.diff} | ${short(m.md5Before)} | ${short(m.md5After)} | ${cell(countCell(m))} | ${cell(reasonCell(m))} |`);
+  }
+  lines.push('');
+  const r = result.restore;
+  const bad = r.files.filter((f) => !f.ok).map((f) => f.file);
+  lines.push(`**Reversão:** snapshot/restore de bytes, md5 de cada arquivo conferido${bad.length ? ` — FALHOU em ${bad.join(', ')}` : ' (todos iguais ao original)'}; sem \`git checkout\`. Escrita nova a cada restauração, então o arquivo é mais novo que qualquer binário de mutante e o build recompila.`);
+  lines.push(`**Binário:** ${BINARY[result.binary.proof]}.`);
+  lines.push(`**Árvore:** \`git status --porcelain\` ${r.treeClean ? 'idêntico ao de antes da rodada (vazio em src/)' : 'DIFERENTE do de antes da rodada — investigar antes de qualquer nota'}.`);
+  const sum = result.timings.reduce((acc, t) => acc + t.ms, 0);
+  const jobs = method.jobs ?? 1;
+  const wall = result.wallMs ?? sum;
+  lines.push(`**Tempo:** ${seconds(wall)} de relógio${jobs > 1 ? ` com ${jobs} workers` : ''}; soma das ${result.timings.length} etapas de build+teste: ${seconds(sum)}.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function summarize(result) {
+  const tally = { killed: 0, survived: 0, 'build-error': 0, inconclusive: 0 };
+  for (const m of result.mutants) tally[m.verdict] = (tally[m.verdict] ?? 0) + 1;
+  return tally;
+}