@polymorphism-tech/morph-spec 8.35.0 → 8.36.0

package/src/lib/tasks/dotnet-test-introspection.js

@@ -0,0 +1,517 @@
+/**
+ * .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.
+ *
+ * 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 { jsoncToJson } from '../ai/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}_@\\\\]';
+/**
+ * TRIPWIRE: every type-declaration keyword wherever it sits — applied to the RAW
+ * text (nothing blanked) and to the blanked code alike, with NO context rule:
+ * round 5 showed that any exclusion decided by what precedes the keyword (the
+ * `:` of a generic constraint, a `where T :` shape) can be forged by a comment in
+ * the raw text or by string content a cut exposes in the code. `record class`/
+ * `record struct` count once. What follows the keyword, after optional whitespace,
+ * is a name start (NAME_START), a comment or preprocessor line standing between
+ * the keyword and its name (`class/**\/BTests` is legal), OR a quote — a quote is
+ * what the RAW text shows where the blanked code shows the spaces of a string the
+ * keyword is followed by (`"; class " : " Fake"` exposed as code): every keyword
+ * 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.
+ */
+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. */
+const TYPE_DECL = new RegExp(`(?:^|[;{}\\]\\n])[ \\t]*(?:\\[[^\\]\\n]*\\][ \\t]*)*(?:(?:public|internal|private|protected|sealed|static|partial|abstract|unsafe|file|new|readonly|ref)\\s+)*(record\\s+(?:class|struct)|class|record|struct|interface)\\s+(${NAME_START}[^\\s:<({;,=]*)`, 'gu');
+const IDENT = '[\\p{L}_][\\p{L}\\p{N}_]*';
+const QUALIFIER = `(?:${IDENT}\\s*(?:\\.|::)\\s*)*`;
+/** An attribute's optional arguments: one nested level of parentheses, no `]`. */
+const ATTRIBUTE_ARGS = '(?:\\((?:[^()\\]]|\\([^()\\]]*\\))*\\))?';
+/** Any other attribute of the same section: a name, optionally with arguments. */
+const OTHER_ATTRIBUTE = `${QUALIFIER}${IDENT}\\s*${ATTRIBUTE_ARGS}`;
+const TEST_ATTRIBUTE_NAME = '(?:Fact|Theory|Test|TestMethod|DataTestMethod|TestCase|TestCaseSource)(?:Attribute)?';
+/**
+ * A test attribute, read on the BLANKED code of a test-project file (hasTestAttribute):
+ * a WHOLE name — `Fact`, `Theory`, `Test`, `TestMethod`, `DataTestMethod`, `TestCase`,
+ * `TestCaseSource`, optionally `…Attribute` and qualified (`Xunit.Fact`) — inside an
+ * attribute section that CLOSES as one: `[` where a declaration may start (line start,
+ * after `;` `{` `}` `]` or a `*\/`), an optional target, other attributes before it
+ * separated by `,`, the test name with its optional arguments, any further attributes,
+ * then the `]` — followed by a declaration start (`[`, a name, a comment, a directive)
+ * 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
+ * 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
+ * attribute after an argument holding `]`).
+ */
+export const CS_TEST_ATTRIBUTE = new RegExp(
+  '(?:^|[;{}\\]]|\\*\\/)[ \\t]*\\['
+  + `\\s*(?:${IDENT}\\s*:(?!:)\\s*)?`
+  + `(?:${OTHER_ATTRIBUTE}\\s*,\\s*)*`
+  + `${QUALIFIER}${TEST_ATTRIBUTE_NAME}(?![\\p{L}\\p{N}_])\\s*${ATTRIBUTE_ARGS}`
+  + `(?:\\s*,\\s*${OTHER_ATTRIBUTE})*`
+  + '\\s*\\]\\s*(?:[\\[\\p{L}_@/#]|(?![\\s\\S]))',
+  'mu',
+);
+
+/**
+ * File text with a leading UTF-8 BOM stripped (VS and `charset=utf-8-bom` write
+ * one) and every C# new-line character mapped 1:1 to `\n` — CR, NEL (U+0085),
+ * LS (U+2028), PS (U+2029): JS `\s` excludes NEL, so `class<NEL>Name` was
+ * invisible to both regexes (compiled and discovered by xunit); a CR-only file had
+ * no line ends at all. U+001A (Ctrl-Z) is mapped 1:1 to a space: Roslyn reads it
+ * as whitespace and JS `\s` does not, so `class<SUB>Name` hid a declaration the
+ * same way (B3 carry-over: compiled, green while skipping the class). Length is kept (CRLF becomes `\n\n`). null when unreadable.
+ */
+const readText = (path) => {
+  try { return readFileSync(path, 'utf8').replace(/\x1A/g, ' ').replace(/^\uFEFF/, '').replace(/[\r\u0085\u2028\u2029]/g, '\n'); } catch { return null; }
+};
+
+/** 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) {
+  for (let dir = dirname(fileAbs); isInside(dir, rootAbs); dir = dirname(dir)) {
+    let names = [];
+    try { names = readdirSync(dir).filter((n) => projectName.test(n)).sort(); } catch { /* unreadable dir */ }
+    if (names.length > 0) return join(dir, names[0]);
+    if (dirname(dir) === dir) break;
+  }
+  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.
+ */
+export function nearestProjectOf(fileAbs, rootAbs) {
+  return nearestProjectFile(fileAbs, rootAbs, /\.(?:cs|fs|vb)proj$/i);
+}
+
+/** .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. */
+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.
+ *
+ * @param {string} absCwd
+ * @returns {'mtp'|'vstest'|null} `mtp` when `test.runner` is Microsoft.Testing.Platform;
+ *   `vstest` when readable without it (or absent: the SDK default); null when a
+ *   global.json exists but cannot be read — never a guess.
+ */
+export function dotnetTestMode(absCwd) {
+  for (let dir = resolve(absCwd); ; dir = dirname(dir)) {
+    const file = join(dir, 'global.json');
+    if (existsSync(file)) {
+      try {
+        const parsed = JSON.parse(jsoncToJson(readFileSync(file, 'utf8')));
+        return parsed?.test?.runner === MTP_RUNNER ? 'mtp' : 'vstest';
+      } catch {
+        return null;
+      }
+    }
+    if (dirname(dir) === dir) return 'vstest';
+  }
+}
+
+/**
+ * Does an MSBuild file that binds this project — the csproj, or any
+ * `Directory.Build.props/.targets` up to the project root — match `pattern`?
+ * `<Import Project=…>` is not followed (deferred). 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, rootAbs, pattern) {
+  const files = [csprojAbs];
+  for (let dir = dirname(csprojAbs); isInside(dir, rootAbs); dir = dirname(dir)) {
+    files.push(join(dir, 'Directory.Build.props'), join(dir, 'Directory.Build.targets'));
+    if (dirname(dir) === dir) break;
+  }
+  return files.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 cannot override it, so a green recorte exits 9.
+ */
+export function imposesMinimumExpected(csprojAbs, rootAbs) {
+  return msbuildDeclares(csprojAbs, rootAbs, FLOOR_PROPERTY) || testconfigDeclares(csprojAbs, /minimum-?expected-?tests/i);
+}
+
+/**
+ * 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 exit 0 (zero tests exit 8);
+ * with 8 ignored, zero tests exit 0 and the proof is gone — the final review of
+ * branch B probed it end to end. Errs wide, like the floor.
+ */
+export function ignoresExitCode(csprojAbs, rootAbs) {
+  return msbuildDeclares(csprojAbs, rootAbs, 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, rootAbs) {
+  return msbuildDeclares(csprojAbs, rootAbs, 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. */
+function closeOnLine(text, start, quote) {
+  for (let j = start + 1; j < text.length && text[j] !== '\n'; j++) {
+    if (text[j] === '\\') j++;
+    else if (text[j] === quote) return j + 1;
+  }
+  return -1;
+}
+
+/**
+ * Does an interpolated literal's content end inside a hole? A `"` inside a hole
+ * (`$"{d["k"]}"`) ends the literal as the scanner reads it, so what it took for
+ * the literal stops with the hole still open. `{{`/`}}` outside a hole are escapes.
+ */
+function holeLeftOpen(content) {
+  let depth = 0;
+  for (let k = 0; k < content.length; k++) {
+    const c = content[k];
+    if (depth === 0 && (c === '{' || c === '}') && content[k + 1] === c) { k++; continue; }
+    if (c === '{') depth++;
+    else if (c === '}' && depth > 0) depth--;
+  }
+  return depth > 0;
+}
+
+/**
+ * C# source with every comment, preprocessor line and string/char literal
+ * blanked — newlines and length kept — or null when the file cannot be read this way:
+ * - a literal or comment never ends;
+ * - an interpolated `$"…"`/`$@"…"`/`@$"…"` literal is cut by a quote inside a hole
+ *   (its content ends with the hole open). Blanking the part before the cut would
+ *   leave the rest of the hole as "code", with braces that can cancel out.
+ *
+ * Raw strings (`"""…"""`, 3+ quotes, with or without `$`/`$$`) end at the same run
+ * of quotes; a quote inside a raw interpolation hole is NOT checked. Verbatim `@"…"`
+ * ends at a lone `"`. Regular and char literals cannot cross a line.
+ *
+ * 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
+ * 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.
+ *
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function blankCSharpLiterals(text) {
+  const out = text.split('');
+  const blank = (from, to) => { for (let k = from; k < to; k++) if (out[k] !== '\n') out[k] = ' '; };
+  for (let i = 0; i < text.length;) {
+    const c = text[i];
+    let end = -1;
+    if (c === '#' && /^[ \t]*$/.test(text.slice(text.lastIndexOf('\n', i - 1) + 1, i))) {
+      end = lineEnd(text, i);
+    } else if (c === '/' && text[i + 1] === '/') {
+      end = lineEnd(text, i);
+    } else if (c === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close < 0) return null;
+      end = close + 2;
+    } else if (c === '"' && (text[i - 1] === '@' || (text[i - 1] === '$' && text[i - 2] === '@'))) {
+      let j = i + 1;
+      while (j < text.length && !(text[j] === '"' && text[j + 1] !== '"')) j += text[j] === '"' ? 2 : 1;
+      if (j >= text.length) return null;
+      end = j + 1;
+      const interpolated = text[i - 1] === '$' || text[i - 2] === '$';
+      if (interpolated && holeLeftOpen(text.slice(i + 1, end - 1))) return null;
+    } else if (c === '"') {
+      let quotes = 0;
+      while (text[i + quotes] === '"') quotes++;
+      if (quotes >= 3) {
+        const close = text.indexOf('"'.repeat(quotes), i + quotes);
+        if (close < 0) return null;
+        end = close + quotes;
+      } else {
+        end = closeOnLine(text, i, '"');
+        if (end < 0) return null;
+        if (text[i - 1] === '$' && holeLeftOpen(text.slice(i + 1, end - 1))) return null;
+      }
+    } else if (c === "'") {
+      end = closeOnLine(text, i, "'");
+      if (end < 0) return null;
+    }
+    if (end < 0) { i++; continue; }
+    blank(i, end);
+    i = end;
+  }
+  return out.join('');
+}
+
+/** Type-keyword tokens in a text (raw or blanked) — every one; no context rule (see TYPE_KEYWORD). */
+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
+ * substring `FullyQualifiedName~T`): any namespace, `Outer+Inner`, `Name`1` — a
+ * selection that can only run MORE tests than the file's, never fewer.
+ *
+ * THE GUARANTEE (what `scannable: true` means), and why it holds:
+ *   every type-keyword token of the RAW text is a declaration in `types`.
+ * - R = keyword tokens of the raw text (TYPE_KEYWORD, no context rule); C = the
+ *   same on the blanked code; D = the declarations named (TYPE_DECL on the code).
+ *   `scannable` requires |R| = |D| and |C| = |D|. By construction D ⊆ C ⊆ R as
+ *   sets of offsets: blanking keeps length and only replaces characters by spaces,
+ *   a blanked region starts at `"` `'` `/` `#` and ends at `"` `'` `*` `/` or a
+ *   line end (never inside an identifier), and the raw lookahead accepts every
+ *   character the code lookahead can be looking past (a name, a comment, `#`, a
+ *   quote). So |R| = |D| forces R = D. A real declaration's keyword is always in R
+ *   (it is followed by its name, or by a comment/directive before the name) —
+ *   UNDER ONE ASSUMPTION: every character Roslyn reads as whitespace or a new-line
+ *   between a keyword and its name is whitespace to JS `\s` once readText has run.
+ *   Roslyn's whitespace is Unicode Zs, TAB, VT, FF and U+001A; its new-lines are
+ *   CR, LF, NEL, LS and PS. JS `\s` already covers Zs, TAB, VT, FF and LF, and
+ *   readText maps CR/NEL/LS/PS to `\n` and U+001A to a space. A separator outside
+ *   that shared set would hide a declaration from R; none is known, and that is a
+ *   statement about the two lexers as read, not a proof.
+ *   Hence: a declaration swallowed by ANY misread — `"/*"` taken for a comment
+ *   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.
+ * - `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
+ *   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);
+ * - 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);
+ * - `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 `;` `{` `}` `]`)
+ *   whose element is named exactly `Test`/`Fact`/… (qualified or not) and whose `]`
+ *   is followed by a combinator: `[Env.Test] or [Env.Dev] => true`. Such a helper is
+ *   taken for a test file. (`[Env.Test] => 1` does not match: `=` starts no declaration.)
+ *
+ * @param {string} csFileAbs
+ * @returns {{ names: string[], types: string[], abstract: string[], hasTestClass: boolean, hasTestAttribute: boolean, scannable: boolean, why: string|null }}
+ *   `names`: top-level `class` names (classNamesOf). `abstract`: the abstract
+ *   types. `hasTestClass`: some plain `class` is declared (records, structs and
+ *   interfaces hold no tests). `hasTestAttribute`: see above. `why`: the reason
+ *   when `scannable` is false.
+ */
+export function csharpClasses(csFileAbs) {
+  const unscannable = (why) => ({ names: [], types: [], abstract: [], hasTestClass: false, hasTestAttribute: false, scannable: false, why });
+  const text = readText(csFileAbs);
+  if (text === null) return { names: [], types: [], abstract: [], hasTestClass: false, hasTestAttribute: false, scannable: true, why: null };
+  const code = blankCSharpLiterals(text);
+  if (code === null) return unscannable('a literal or comment never ends, or an interpolation hole is cut by an inner quote');
+
+  const decls = [...code.matchAll(TYPE_DECL)].map((m) => ({
+    at: m.index + m[0].length - m[2].length,
+    kind: m[1].split(/\s+/)[0],
+    name: m[2],
+    abstract: /\babstract\b/.test(m[0]),
+    gap: m[0].slice(0, m[0].length - m[2].length).match(/\s*$/)[0].length,
+  }));
+  // A preprocessor line between a keyword and its name (`class\n#if X\nA\n#else\nB…`)
+  // makes the compiled name depend on a symbol this scan cannot see. Blanking keeps
+  // length, so the raw text at the same offsets shows the directive.
+  const split = decls.find((d) => /(^|\n)[ \t]*#/.test(text.slice(d.at - d.gap, d.at)));
+  if (split) return unscannable(`a preprocessor directive stands between a type keyword and the name "${split.name}"`);
+  // THE NET (R2, tightened in round 5): the raw text is the lexer-independent
+  // truth about how many type keywords the file carries. Compare it — and the
+  // blanked code — against what was actually named (see the JSDoc for why
+  // equality of counts is equality of sets).
+  const rawKeywords = typeKeywordCount(text);
+  if (rawKeywords !== decls.length) {
+    return unscannable(`${rawKeywords} type keyword(s) in the file but ${decls.length} declaration(s) recognised`);
+  }
+  const codeKeywords = typeKeywordCount(code);
+  if (codeKeywords !== decls.length) {
+    return unscannable(`${codeKeywords} type keyword(s) in the code but ${decls.length} declaration(s) recognised`);
+  }
+
+  const names = [];
+  const types = [];
+  const abstractTypes = [];
+  const scopes = [];
+  let hasTestClass = false;
+  let header = 0;
+  for (let i = 0, d = 0; i < code.length; i++) {
+    for (; d < decls.length && decls[d].at === i; d++) {
+      types.push(decls[d].name);
+      if (decls[d].abstract) abstractTypes.push(decls[d].name);
+      if (decls[d].kind === 'class') {
+        hasTestClass = true;
+        if (!scopes.some((s) => s.type)) names.push(decls[d].name);
+      }
+    }
+    const c = code[i];
+    if (c === '{') {
+      scopes.push({ type: TYPE_HEADER.test(code.slice(header, i)) });
+    } else if (c === '}' && scopes.pop() === undefined) {
+      return unscannable('a `}` closes nothing');
+    }
+    if (c === '{' || c === '}' || c === ';') header = i + 1;
+  }
+  if (scopes.length > 0) return unscannable('braces left open at end of file');
+  return {
+    names: [...new Set(names)],
+    types: [...new Set(types)],
+    abstract: [...new Set(abstractTypes)],
+    hasTestClass,
+    hasTestAttribute: CS_TEST_ATTRIBUTE.test(code),
+    scannable: true,
+    why: null,
+  };
+}
+
+/**
+ * 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 : [];
+}