@polymorphism-tech/morph-spec 8.47.0 → 9.0.0

package/src/lib/{tasks/dotnet-test-introspection.js → mutation/dotnet-introspection.js}

@@ -1,40 +1,17 @@
 /**
- * .NET test-project introspection for the task-scope recorte (issue #87): which
- * test project owns a `.cs` file and with which framework, which project-level
- * settings bind every run, which test mode the SDK picks, and which types a C#
- * file declares. Split out of test-scope.js, which decides; this only reads.
- *
- * Every answer errs toward "run the node whole". A wrong answer that NARROWS runs
- * fewer tests and still comes out green — the one failure issue #87 must never buy.
- *
- * The C# scan is NOT a parser. What narrowing relies on is narrower than "the
- * scan is right" and is stated exactly in csharpClasses: every type-keyword
- * token of the RAW text (nothing blanked, no context rule) must be a declaration
- * the scanner NAMED. Type names are BARE and the selectors namespace-free
- * (`*Type*` / `FullyQualifiedName~Type`), so no scope reading can misname one.
- * What that does NOT cover is listed there too.
+ * .NET introspection the targeted mutation (`morph-spec mutate`) needs: which
+ * project owns a file, which test mode the SDK picks, and which types a C# file
+ * declares — read FAIL-SAFE (see csharpClasses).
  *
  * Pure: reads files, never spawns a process.
- *
- * @module dotnet-test-introspection
  */
-
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 
-import { isInside } from './test-runner.js';
+import { isInside } from '../tasks/test-runner.js';
 import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
 
 const MTP_RUNNER = 'Microsoft.Testing.Platform';
-const FLOOR_PROPERTY = /<TestingPlatformCommandLineArguments\b[^>]*>[^<]*--minimum-expected-tests/i;
-/**
- * `--ignore-exit-code`, or the env var MTP reads for the same thing, named ANYWHERE in an
- * MSBuild file that binds the project — not only inside `<TestingPlatformCommandLineArguments>`:
- * a property indirection (`<MtpExtraArgs>--ignore-exit-code 8</MtpExtraArgs>` referenced as
- * `$(MtpExtraArgs)`) carries it just as well (re-review N4, probed). Errs wide.
- */
-const IGNORE_EXIT_MARKER = /--ignore-exit-code|TESTINGPLATFORM_EXITCODE_IGNORE/i;
-const CASE_FILTER_PROPERTY = /<VSTestTestCaseFilter\b[^>]*>/i;
 const TYPE_HEADER = /\b(?:class|struct|record|interface)\b/;
 /** A C# identifier's first character: a letter, an Nl letter (`Ⅱ`), `_`, `@` (verbatim) or `\` (a unicode escape). */
 const NAME_START = '[\\p{L}\\p{Nl}_@\\\\]';
@@ -52,7 +29,7 @@ const NAME_START = '[\\p{L}\\p{Nl}_@\\\\]';
  * the code counts is a keyword the raw text counts, by offset.
  * A constraint keyword is therefore counted too whenever a name-shaped token
  * follows it (`where T : class where U : …`, `: class // note`): it is not named,
- * so the file runs whole. `class,` / `class\n{` / `class?` are not counted at all.
+ * so the file is unscannable. `class,` / `class\n{` / `class?` are not counted at all.
  */
 const TYPE_KEYWORD = new RegExp(`\\b(?:record\\s+(?:class|struct)|class|record|struct|interface)\\b(?=\\s*(?:${NAME_START}|["']|\\/[/*]|#))`, 'gu');
 /** A type declaration the scanner can NAME: after `; { } ]`, a newline or the file start; attributes; modifiers; a NAME_START name. */
@@ -75,14 +52,13 @@ const TEST_ATTRIBUTE_NAME = '(?:Fact|Theory|Test|TestMethod|DataTestMethod|TestC
  * or the end of the input.
  *
  * A false POSITIVE is the unsafe direction here: a helper taken for a test file
- * narrows to its own name, and a test whose name contains it makes the run green
- * while the tests that USE the helper never run. The final review of branch B found
+ * narrows the subset to its own name, and the tests that USE the helper never run. The final review of branch B found
  * exactly that with the old prefix match (`, TestContext` / `, Factory` / `, TheoryData`
  * after any `,`), and its re-review (N1) with a test name merely FOLLOWED by `(` or `,`:
  * a C# 12 collection laid out with `[` alone on its line (`[\n    Env.Dev,\n    Env.Test,\n];`,
  * a row `[Env.Test, Env.Dev],`, `[\n    Test("a"),\n];`). Requiring the section to close
  * rejects all three; what still matches is stated in csharpClasses. A false NEGATIVE
- * only runs the node whole (a custom attribute such as `[SkippableFact]`, a test
+ * only leaves a test file out of a selection (a custom attribute such as `[SkippableFact]`, a test
  * attribute after an argument holding `]`).
  */
 export const CS_TEST_ATTRIBUTE = new RegExp(
@@ -109,35 +85,6 @@ const readText = (path) => {
 };
 
 /** Which test framework a csproj references, by package (or MSBuild SDK) name. */
-function testFrameworkOf(csprojText) {
-  const refs = [...csprojText.matchAll(/(?:Include|Sdk)\s*=\s*"([^"/]+)/gi)].map((m) => m[1].toLowerCase());
-  if (refs.some((r) => r.startsWith('xunit.v3'))) return 'xunit.v3';
-  if (refs.some((r) => r.startsWith('mstest'))) return 'mstest';
-  if (refs.some((r) => r === 'nunit')) return 'nunit';
-  if (refs.some((r) => r === 'xunit')) return 'xunit';
-  return null;
-}
-
-/**
- * A test project: named `*Tests.csproj`/`.fsproj`/`.vbproj`, OR referencing a
- * test framework / `Microsoft.NET.Test.Sdk` in the project file itself.
- */
-export function isDotnetTestProject(projectAbs) {
-  const text = readText(projectAbs) ?? '';
-  return /Tests\.(?:cs|fs|vb)proj$/i.test(projectAbs) || testFrameworkOf(text) !== null || /Microsoft\.NET\.Test\.Sdk/i.test(text);
-}
-
-/**
- * The test project owning a `.cs` file — nearest `.csproj` walking up, as MSBuild
- * globs it — or null when the file is not a test file (see isDotnetTestProject).
- *
- * @returns {{ csproj: string, framework: 'xunit.v3'|'mstest'|'nunit'|'xunit'|null }|null}
- */
-export function dotnetTestProjectOf(fileAbs, rootAbs) {
-  const csproj = nearestCsprojOf(fileAbs, rootAbs);
-  if (csproj === null || !isDotnetTestProject(csproj)) return null;
-  return { csproj, framework: testFrameworkOf(readText(csproj) ?? '') };
-}
 
 /** Nearest file matching `projectName` walking up from a file's directory, inside the root; null when none. */
 function nearestProjectFile(fileAbs, rootAbs, projectName) {
@@ -150,21 +97,10 @@ function nearestProjectFile(fileAbs, rootAbs, projectName) {
   return null;
 }
 
-/**
- * The `.csproj` that compiles a `.cs` file — nearest one walking up, as MSBuild
- * globs it — test project or not; null when there is none inside the root.
- * The one door for "which project owns this file": link ownership in test-scope
- * asks it about every touched `.cs`, recognised as a test file or not.
- */
-export function nearestCsprojOf(fileAbs, rootAbs) {
-  if (!/\.cs$/i.test(fileAbs)) return null;
-  return nearestProjectFile(fileAbs, rootAbs, /\.csproj$/i);
-}
-
 /**
  * The project — `.csproj`, `.fsproj` or `.vbproj` — nearest to ANY file walking
  * up, or null inside the root. Asked about the .NET sources the C# scan cannot
- * read (a bUnit `.razor`, an F# `.fs`), which nearestCsprojOf does not answer.
+ * read (a bUnit `.razor`, an F# `.fs`).
  */
 export function nearestProjectOf(fileAbs, rootAbs) {
   return nearestProjectFile(fileAbs, rootAbs, /\.(?:cs|fs|vb)proj$/i);
@@ -173,33 +109,12 @@ export function nearestProjectOf(fileAbs, rootAbs) {
 /** .NET sources the C# scan cannot read: Razor (`.razor`, `.cshtml`), F# (`.fs`, `.fsi`, `.fsx`), VB (`.vb`). */
 const NON_CSHARP_SOURCE = /\.(?:razor|cshtml|fs|fsi|fsx|vb)$/i;
 
-/** A .NET source other than C#: the recorte has no type scan, hence no selector, for it. */
+/** A .NET source other than C#: no type scan, hence no class selector, for it. */
 export const isNonCSharpSource = (path) => NON_CSHARP_SOURCE.test(String(path));
 
 /** Any .NET source a project compiles — C# or one of the others. */
 export const isDotnetSource = (path) => /\.cs$/i.test(String(path)) || isNonCSharpSource(path);
 
-const MARKER_TAIL = '\\s*(?:[\\p{L}_][\\p{L}\\p{N}_]*\\s*(?:\\.|::)\\s*)*(?:Fact|Theory|Test|DataTestMethod)';
-/** Per language, the LOOSE test marker readsLikeTestSource looks for in the raw text. */
-const LOOSE_TEST_MARKERS = [
-  [/\.(?:cs|razor|cshtml)$/i, new RegExp(`[[,]${MARKER_TAIL}`, 'u')], // C#, Razor: `[Fact`, `, Theory`, `[Xunit.Fact(`
-  [/\.(?:fs|fsi|fsx)$/i, new RegExp(`(?:\\[<|;)${MARKER_TAIL}`, 'u')], // F#: `[<Fact>]`, `[<Trait(…); Fact>]`
-  [/\.vb$/i, new RegExp(`[<,]${MARKER_TAIL}`, 'u')], // VB: `<Fact>`, `<Trait(…), Fact>`
-];
-
-/**
- * Does a file the recogniser did NOT classify READ like a test, in its raw text
- * (comments and strings included)? The question test-scope asks before narrowing
- * PAST a touched file, so its errors cost the OPPOSITE of CS_TEST_ATTRIBUTE's: a
- * false positive runs a node whole (time), a false negative skips a touched test.
- * So it errs wide on purpose — a name PREFIX is enough (`[TestContext` counts).
- * false for any extension it has no marker for.
- */
-export function readsLikeTestSource(fileAbs) {
-  const marker = LOOSE_TEST_MARKERS.find(([ext]) => ext.test(fileAbs))?.[1];
-  return marker ? marker.test(readText(fileAbs) ?? '') : false;
-}
-
 /**
  * `.NET` test mode for a cwd: nearest `global.json` walking UP (as the SDK
  * resolves it — from the CWD, never from the `.sln` argument), read as JSONC.
@@ -224,172 +139,6 @@ export function dotnetTestMode(absCwd) {
   }
 }
 
-/** Read on EVERY level from the project's folder up (bindingMsbuildFiles). */
-const DIRECTORY_FILES = ['Directory.Build.props', 'Directory.Build.targets', 'Directory.Build.rsp', 'Directory.Packages.props'];
-
-/**
- * The MSBuild files that bind a project, as far as this module reads them: the csproj,
- * the `<csproj>.user` Microsoft.Common.targets imports beside it, and every
- * DIRECTORY_FILES walking up to the FILESYSTEM root — MSBuild's lookup does not stop at
- * the repository, and a Directory.Build.targets above it binds the project just the same
- * (#114 review F3). Every level is read, not only the first file MSBuild would import:
- * that errs wide. Not read: an `<Import Project=…>` (floorOverride refuses a csproj that
- * has one), a NuGet package's `build/*.targets`, the SDK's own imports.
- */
-function bindingMsbuildFiles(csprojAbs) {
-  const files = [csprojAbs, `${csprojAbs}.user`];
-  for (let dir = dirname(csprojAbs); ; dir = dirname(dir)) {
-    files.push(...DIRECTORY_FILES.map((name) => join(dir, name)));
-    if (dirname(dir) === dir) return files;
-  }
-}
-
-/**
- * Does an MSBuild file that binds this project (bindingMsbuildFiles) match `pattern`?
- * It errs wide: a false positive costs a whole run, a false negative a red (or a
- * green) that no test earned.
- */
-function msbuildDeclares(csprojAbs, pattern) {
-  return bindingMsbuildFiles(csprojAbs).some((p) => pattern.test(readText(p) ?? ''));
-}
-
-/**
- * The project imposes `--minimum-expected-tests` on every run: in the MSBuild
- * property (attributes such as `Condition=` allowed), or in a `*testconfig.json`
- * beside the csproj. Measured: the CLI flag cannot override it, so a green recorte
- * exits 9 — unless floorOverride can lower it (#114).
- */
-export function imposesMinimumExpected(csprojAbs) {
-  return msbuildDeclares(csprojAbs, FLOOR_PROPERTY) || testconfigDeclares(csprojAbs, /minimum-?expected-?tests/i);
-}
-
-const ARGS_NAME = 'TestingPlatformCommandLineArguments';
-const ARGS_ELEMENT = /<TestingPlatformCommandLineArguments\b([^>]*)>([^<]*)<\/TestingPlatformCommandLineArguments\s*>/gi;
-const ARGS_OPENING = /<TestingPlatformCommandLineArguments\b/gi;
-/** Named anywhere: an element, a `$(…)` read, a `-p:` in a Directory.Build.rsp. */
-const ARGS_MENTION = /TestingPlatformCommandLineArguments/i;
-const IMPORT_ELEMENT = /<Import\b/i;
-/**
- * A tag — or a comment, CDATA section, declaration or processing instruction, which
- * enclosingElements skips. An attribute value may hold `>` (`Condition="'$(A)' > '1'"`),
- * so a quoted value is consumed whole.
- */
-const XML_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<[!?][^>]*>|<(\/?)([A-Za-z_][\w.:-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
-/**
- * What a value cannot carry and still be re-passed as ONE double-quoted `-p:`
- * argument meaning the same thing: MSBuild expansion and escapes (`$ @ %`), its
- * property separators (`; ,`), an XML entity (`&`), and shell quoting (`" ' \` \ !`).
- */
-const UNSAFE_IN_PROPERTY = /[$@%;,&"'`\\!]/;
-/** Read after ASCII whitespace is collapsed: a no-break space between flag and number matches nothing (review F7). */
-const FLOOR_ARGUMENT = /(^| )--minimum-expected-tests \d+(?= |$)/;
-
-/**
- * The elements enclosing the opening tag of `name`, outermost first — or null when the
- * tags do not balance. Fails SAFE: a document it cannot walk is null, and the node runs
- * whole.
- */
-function enclosingElements(text, name) {
-  const stack = [];
-  let enclosing = null;
-  for (const [, closing, tag, attributes, selfClosing] of text.matchAll(XML_TOKEN)) {
-    if (tag === undefined) continue;
-    if (closing) {
-      if (stack.pop()?.tag.toLowerCase() !== tag.toLowerCase()) return null;
-      continue;
-    }
-    if (tag.toLowerCase() === name.toLowerCase()) enclosing = [...stack];
-    if (!selfClosing) stack.push({ tag, attributes });
-  }
-  return stack.length === 0 ? enclosing : null;
-}
-
-/**
- * The element is set on EVERY evaluation, by nothing but itself: its parent is a
- * `<PropertyGroup>` with no attribute, directly under `<Project>` — never a `<Target>`, a
- * `<Choose>/<When>`, an `<ItemDefinitionGroup>` or a conditional group (#114 review F1:
- * the element's OWN attributes were the only ones read, and a false `Condition` on its
- * group got the value injected into a run MSBuild would never give it). `<Project>` does
- * not mark it `TreatAsLocalProperty` (the csproj would beat the global `-p:` and a green
- * recorte exit 9, review F5), and the csproj imports nothing that could append to it.
- */
-function setUnconditionally(text) {
-  if (IMPORT_ELEMENT.test(text)) return false;
-  const enclosing = enclosingElements(text, ARGS_NAME);
-  if (enclosing?.length !== 2) return false;
-  const [project, group] = enclosing;
-  return /^Project$/i.test(project.tag) && !/TreatAsLocalProperty/i.test(project.attributes)
-    && /^PropertyGroup$/i.test(group.tag) && group.attributes.trim() === '';
-}
-
-/**
- * The value for `-p:TestingPlatformCommandLineArguments=` that lowers the project's
- * floor to 1 and keeps every other argument (#114) — or null, and the node runs whole.
- *
- * Measured (test/fixtures/test-output/): the CLI flag does NOT override the project's
- * floor — a green recorte still exits 9 —, the global MSBuild property does — green
- * exits 0, zero tests still exit 8 — and it replaces the value WHOLE, so the rest is
- * re-passed verbatim (mtp-minimum-expected-override-multiarg.txt). No rebuild: six
- * runs alternating with and without it kept the test DLL's mtime, ~3 s each.
- *
- * So the value has to be exactly the one MSBuild would use, read from ONE place:
- *   - ONE `<TestingPlatformCommandLineArguments>` in the csproj itself, set on every
- *     evaluation (setUnconditionally) — no attribute of its own, no second opening
- *     (another element, or one in an XML comment: the count is over the raw text);
- *   - the property named in no other file that binds the project (bindingMsbuildFiles:
- *     the `.user` file, Directory.Build.* up to the filesystem root) — one could append
- *     to it or replace it;
- *   - no floor in a `*testconfig.json` beside it (`-p:` does not reach that file);
- *   - exactly one literal `--minimum-expected-tests N`, and nothing UNSAFE_IN_PROPERTY.
- * Out of reach: a NuGet package's build targets appending to the property. The override
- * drops that argument during the recorte, and one like xunit.v3's `--explicit` changes
- * WHICH tests run — a limit framework/docs/CLI.md states.
- *
- * @returns {string|null}
- */
-export function floorOverride(csprojAbs) {
-  const text = readText(csprojAbs);
-  if (text === null) return null;
-  const elements = [...text.matchAll(ARGS_ELEMENT)];
-  if (elements.length !== 1 || (text.match(ARGS_OPENING) ?? []).length !== 1) return null;
-  const [, attributes, raw] = elements[0];
-  if (attributes.trim() !== '' || !setUnconditionally(text)) return null;
-  if (bindingMsbuildFiles(csprojAbs).slice(1).some((p) => ARGS_MENTION.test(readText(p) ?? ''))) return null;
-  if (testconfigDeclares(csprojAbs, /minimum-?expected-?tests/i)) return null;
-  const value = raw.replace(/[ \t\r\n]+/g, ' ').trim();
-  if (UNSAFE_IN_PROPERTY.test(value)) return null;
-  if ((value.match(/--minimum-expected-tests/g) ?? []).length !== 1 || !FLOOR_ARGUMENT.test(value)) return null;
-  return value.replace(FLOOR_ARGUMENT, '$1--minimum-expected-tests 1');
-}
-
-/**
- * The project can make MTP IGNORE an exit code on every run: `--ignore-exit-code` or
- * the `TESTINGPLATFORM_EXITCODE_IGNORE` variable named anywhere in an MSBuild file that
- * binds the project — inside `<TestingPlatformCommandLineArguments>` or in a property
- * it references through `$(…)` — or either one in a `*testconfig.json` beside the csproj.
- * Under MTP a narrowed run's proof that tests ran is the summary's count and — when
- * the summary is not readable (#115: pt-BR and en-US are) — exit 0 (zero tests exit
- * 8); with 8 ignored, zero tests exit 0 and that proof is gone — the final review of
- * branch B probed it end to end. Errs wide, like the floor.
- */
-export function ignoresExitCode(csprojAbs) {
-  return msbuildDeclares(csprojAbs, IGNORE_EXIT_MARKER)
-    || testconfigDeclares(csprojAbs, /ignore-?exit-?code|exit-?code-?ignore|TESTINGPLATFORM_EXITCODE_IGNORE/i);
-}
-
-/** Does a `*testconfig.json` beside the csproj (MTP reads it from the project) match `pattern`? */
-function testconfigDeclares(csprojAbs, pattern) {
-  const projectDir = dirname(csprojAbs);
-  let names = [];
-  try { names = readdirSync(projectDir).filter((n) => /testconfig\.json$/i.test(n)); } catch { /* none */ }
-  return names.some((n) => pattern.test(readText(join(projectDir, n)) ?? ''));
-}
-
-/** The project declares `<VSTestTestCaseFilter>` — an appended `--filter` would silently REPLACE it. */
-export function declaresCaseFilter(csprojAbs) {
-  return msbuildDeclares(csprojAbs, CASE_FILTER_PROPERTY);
-}
-
 const lineEnd = (text, i) => { const e = text.indexOf('\n', i); return e < 0 ? text.length : e; };
 
 /** End (exclusive) of a regular string or char literal opened at `start`; -1 if the line ends first. */
@@ -431,7 +180,7 @@ function holeLeftOpen(content) {
  *
  * This is a heuristic lexer and it CAN misread (known: `holeLeftOpen` counts the
  * braces of a char literal such as `'}'`, so `$"{(c == '}' ? "a" : "/*")}"` is cut
- * at the inner quote and `"/*"` becomes code). Nothing in narrowing relies on the
+ * at the inner quote and `"/*"` becomes code). Nothing relies on the
  * blanking being right: csharpClasses compares the declarations it names against
  * the type keywords of the RAW text, and any declaration a misread hides makes the
  * file unscannable.
@@ -490,8 +239,8 @@ const typeKeywordCount = (text) => [...text.matchAll(TYPE_KEYWORD)].length;
  * The types of a C# file, read FAIL-SAFE.
  *
  * `types` lists the BARE name of EVERY type declaration (class, record, struct,
- * interface) at ANY depth, in source order, with no namespace. That list is what
- * narrowing selects on, namespace-free (`--filter-class "*T*"`, measured, or the
+ * interface) at ANY depth, in source order, with no namespace. A selection built
+ * from these names is namespace-free (`--filter-class "*T*"`, measured, or the
  * substring `FullyQualifiedName~T`): any namespace, `Outer+Inner`, `Name`1` — a
  * selection that can only run MORE tests than the file's, never fewer.
  *
@@ -517,25 +266,24 @@ const typeKeywordCount = (text) => [...text.matchAll(TYPE_KEYWORD)].length;
  *   opener, a quote inside an interpolation hole, a char literal — is still in R
  *   and cannot be compensated by anything (a fake the code exposes is in R too).
  * - `abstract` lists the abstract types: their tests run under the names of DERIVED
- *   classes, possibly in files the task did not touch, so narrowing refuses them.
+ *   classes, possibly in other files.
  * - `hasTestAttribute`: a test attribute (CS_TEST_ATTRIBUTE: a whole name inside an
  *   attribute section) is present in the blanked code (a file without one is a
  *   helper/fake/fixture: the tests using it are elsewhere).
  * - kept fail-safes: braces balance and blankCSharpLiterals returning null → unscannable.
  *
  * NOT guaranteed (stated, not hidden):
- * - narrowing itself: keyword-shaped text in a real comment or string (`// the
+ * - completeness: keyword-shaped text in a real comment or string (`// the
  *   class under test`), a constraint keyword followed by a name-shaped token
  *   (`where T : class where …`, `: class // note`), `record with`, a directive
- *   splitting a name — all run the node whole. A cost in time, never a skipped test;
- * - which scope a type was read in (`names`, the top-level subset, is
- *   informational only — nothing in narrowing depends on it);
+ *   splitting a name — all make the file unscannable;
+ * - which scope a type was read in;
  * - a NON-abstract class whose tests are inherited by derived classes declared in
  *   OTHER files: the touched class runs; the derived copies only if their names
  *   contain it;
  * - a test attribute reached through an alias (`using F = Xunit.FactAttribute; [F]`)
  *   or a custom one (`[SkippableFact]`) is not seen: the file counts as a helper and
- *   the node runs whole (safe, slower);
+ *   it is left out of a selection;
  * - `hasTestAttribute` is still a heuristic, and ITS false positive is the unsafe
  *   side. Since the re-review (N1) the section must close; what still matches in a
  *   helper — probed — is a LIST PATTERN opening a line (or after `;` `{` `}` `]`)
@@ -617,16 +365,3 @@ export function csharpClasses(csFileAbs) {
   };
 }
 
-/**
- * BARE names of the TOP-LEVEL `class` declarations in a C# file — no namespace
- * (the selectors are namespace-free by construction, see csharpClasses). Records
- * are not test classes. Nested classes are left out. `[]` also when the file
- * cannot be scanned safely.
- *
- * @param {string} csFileAbs
- * @returns {string[]} unvalidated — narrowNode refuses names outside `[A-Za-z0-9_.]`
- */
-export function classNamesOf(csFileAbs) {
-  const { names, scannable } = csharpClasses(csFileAbs);
-  return scannable ? names : [];
-}

package/src/lib/mutation/plan.js

@@ -1,7 +1,7 @@
 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 { isDotnetSource } from './dotnet-introspection.js';
 import { resolveRegions, validateManifest } from './manifest.js';
 
 const JS_RUNNERS = new Set(['vitest', 'jest', 'node-test']);
@@ -14,23 +14,31 @@ export function loadPlan({ root, planPath }) {
   });
 }
 
-export function pickNode(file, nodes, root) {
+function ownersOf(file, nodes, root) {
+  if (isDotnetSource(file)) return nodes.filter((n) => n.runner === 'dotnet');
   const abs = resolve(root, file);
-  if (isDotnetSource(file)) return nodes.find((n) => n.runner === 'dotnet') ?? null;
-  const owners = nodes
+  return 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;
+}
+
+// An `e2e: true` suite tests the running compose stack, which mutate never
+// rebuilds: it is picked only when no other suite owns the file, and the caller refuses.
+export function pickNode(file, nodes, root) {
+  const owners = ownersOf(file, nodes, root);
+  return owners.find((n) => !n.e2e) ?? owners[0] ?? null;
 }
 
 export function groupByNode(regions, nodes, root) {
   const groups = new Map();
   const orphans = [];
+  const stackOnly = [];
   for (const region of regions) {
     const node = pickNode(region.file, nodes, root);
     if (!node) { orphans.push(region); continue; }
+    if (node.e2e) { stackOnly.push({ region, node }); continue; }
     if (!groups.has(node.id)) groups.set(node.id, { node, regions: [] });
     groups.get(node.id).regions.push(region);
   }
-  return { groups: [...groups.values()], orphans };
+  return { groups: [...groups.values()], orphans, stackOnly };
 }

package/src/lib/mutation/runner.js

@@ -5,7 +5,7 @@ import { blame, parseCompilerErrors, patchFile, switchClassName, switchSource, S
 import { md5Of, md5OfFile, openSnapshot, restoreSnapshot, trackGenerated } from './snapshot.js';
 import { parseBuiltDlls } from './commands.js';
 import { firstLines, methodOf } from './trx.js';
-import { nearestProjectOf } from '../tasks/dotnet-test-introspection.js';
+import { nearestProjectOf } from './dotnet-introspection.js';
 
 const posix = (p) => p.replace(/\\/g, '/');
 const MAX_SCHEMATA_ATTEMPTS = 3;

package/src/lib/mutation/subset.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { csharpClasses } from '../tasks/dotnet-test-introspection.js';
+import { csharpClasses } from './dotnet-introspection.js';
 import { relatedCommand } from './commands.js';
 
 const SKIP_DIRS = new Set(['bin', 'obj', 'node_modules', '.git', 'worktrees', 'TestResults']);
@@ -24,18 +24,40 @@ function walkCs(dir, out = []) {
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+export function mutatedTypesOf(root, files) {
+  const types = new Set();
+  for (const file of files) {
+    for (const t of csharpClasses(resolve(root, file)).types) if (t.length >= MIN_TYPE_LENGTH) types.add(t);
+  }
+  return [...types];
+}
+
+const mentionOf = (types) => (types.length > 0 ? new RegExp(`\\b(?:${types.map(escapeRe).join('|')})\\b`) : null);
+
+/** Test files (a test attribute in the code) under `testProjectDirs` naming one of `types` as a whole word. */
+export function testFilesCiting({ root, testProjectDirs, types, exclude = [] }) {
+  const mention = mentionOf(types);
+  if (mention === null) return [];
+  const skip = new Set(exclude.map(posix));
+  const found = [];
+  for (const dir of testProjectDirs) {
+    for (const abs of walkCs(resolve(root, dir))) {
+      const rel = posix(relative(root, abs));
+      if (skip.has(rel)) continue;
+      const info = csharpClasses(abs);
+      if (info.scannable && info.hasTestAttribute && mention.test(readFileSync(abs, 'utf8'))) found.push(rel);
+    }
+  }
+  return found.sort();
+}
+
 /**
  * The tests to run FIRST, chosen by the tool: files the feature changed, and files naming a
  * type the mutated files declare. A mutant the subset does not kill goes to the whole suite.
  */
 export function dotnetSubset({ root, testProjectDirs, mutatedFiles, changed = [] }) {
   const changedSet = new Set(changed.map(posix));
-  const mutatedTypes = new Set();
-  for (const file of mutatedFiles) {
-    for (const t of csharpClasses(resolve(root, file)).types) if (t.length >= MIN_TYPE_LENGTH) mutatedTypes.add(t);
-  }
-  const mention = mutatedTypes.size > 0
-    ? new RegExp(`\\b(?:${[...mutatedTypes].map(escapeRe).join('|')})\\b`) : null;
+  const mention = mentionOf(mutatedTypesOf(root, mutatedFiles));
 
   const byChange = new Set();
   const byMention = new Set();
@@ -70,6 +92,21 @@ export function jsSubset({ runner, command, root, mutatedFiles }) {
   return { usable: true, command: cmd, files: { related: files } };
 }
 
-export function testProjectDirsOf(root, csprojs) {
-  return [...new Set(csprojs.map((c) => posix(relative(root, dirname(resolve(root, c))))))];
+const SLN_PROJECT = /^Project\("[^"]*"\)\s*=\s*"[^"]*",\s*"([^"]+\.csproj)"/gim;
+const SLNX_PROJECT = /<Project\b[^>]*\bPath="([^"]+\.csproj)"/gi;
+
+function solutionProjects(solutionAbs) {
+  let text;
+  try { text = readFileSync(solutionAbs, 'utf8'); } catch { return []; }
+  const pattern = /\.slnx$/i.test(solutionAbs) ? SLNX_PROJECT : SLN_PROJECT;
+  return [...text.matchAll(pattern)].map((m) => resolve(dirname(solutionAbs), posix(m[1])));
+}
+
+/** A solution stands for every project it lists; one that lists none yields no directory. */
+export function testProjectDirsOf(root, targets, cwd = root) {
+  const projects = targets.flatMap((t) => {
+    const abs = resolve(cwd, t);
+    return /\.slnx?$/i.test(t) ? solutionProjects(abs) : [abs];
+  });
+  return [...new Set(projects.map((p) => posix(relative(root, dirname(p)))))];
 }

package/src/lib/plan/artifact-vocabulary.js

@@ -0,0 +1,60 @@
+/** The inline justification that lets a criterion talk about an artifact on purpose. */
+export const ARTIFACT_MARKER_RE = /por\s+que\s+artefato\s*:/i;
+
+/**
+ * Case-insensitive spelling of `word` inside a regex that must stay
+ * case-SENSITIVE elsewhere — Node 18 has no inline `(?i:…)` modifier.
+ */
+const anyCase = (word) => [...word].map((c) => {
+  const lo = c.toLowerCase();
+  const up = c.toUpperCase();
+  return lo === up ? c : `[${lo}${up}]`;
+}).join('');
+
+/**
+ * What follows "arquivo em" in a behavioural export criterion ("exporta o
+ * arquivo em CSV", "salva o arquivo em formato aberto"): an uppercase file
+ * format acronym or the word `formato`. Case-sensitive on purpose — `src`,
+ * `docs` or `lib` after "arquivo em" are places, and places are artifacts.
+ */
+const FORMAT_TOKEN = String.raw`\s+(?:[A-Z]{2,5}(?![\p{L}\d_])|${anyCase('formato')}(?![\p{L}]))`;
+
+/**
+ * Vocabulary of artifact-shaped phrasing. `term` is the label surfaced in
+ * warnings and cited by the `morph-plan` skill prose — keep it stable, a
+ * parity test imports it verbatim.
+ *
+ * Unicode lookarounds, never `\b`: in JS, `\b` does not treat accented
+ * letters (é, á, ó…) as word characters, so it would false-boundary inside
+ * "não" or "binário".
+ */
+export const ARTIFACT_VOCABULARY = [
+  { term: 'grep',                        re: /(?<![\p{L}\d_])grep(?![\p{L}\d_])/iu },
+  { term: 'contém a string',             re: /cont[ée]m\s+as?\s+strings?/iu },
+  { term: 'o binário',                   re: /(?<![\p{L}])o\s+bin[áa]rio(?![\p{L}])/iu },
+  { term: 'nenhum arquivo',              re: /(?<![\p{L}])nenhum\s+arquivo(?![\p{L}])/iu },
+  {
+    term: 'arquivo/pasta/diretório em',
+    re: new RegExp(
+      String.raw`(?<![\p{L}])(?:${anyCase('arquivo')}|${anyCase('pasta')}|${anyCase('diret')}[óoÓO]${anyCase('rio')})` +
+      String.raw`[sS]?\s+${anyCase('em')}(?![\p{L}])(?!${FORMAT_TOKEN})`,
+      'u',
+    ),
+  },
+  { term: 'glob **/',                    re: /\*\*\/|\/\*\*/ },
+];
+
+/**
+ * Vocabulary terms matched in `text`, in vocabulary order, each at most once.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function findArtifactTerms(text) {
+  const s = String(text ?? '');
+  const found = [];
+  for (const { term, re } of ARTIFACT_VOCABULARY) {
+    if (re.test(s)) found.push(term);
+  }
+  return found;
+}