@polymorphism-tech/morph-spec 9.7.0 → 10.0.0

package/src/lib/generators/handoff-generator.js

@@ -1,172 +0,0 @@
-// Derived only from committed sources, so it is regenerated, never hand-edited or merged.
-// Every section is fail-open.
-
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude.js';
-import { derivePhaseForFeature, getPendingGates } from '../../../framework/hooks/shared/state-reader.js';
-import { sliceProgress, readySlices } from '../../../framework/hooks/shared/slice-progress.js';
-import { formatNext } from '../../../framework/hooks/shared/next-step.js';
-import { nextStepFor } from '../next-step.js';
-
-const POINTER_CANDIDATES = [
-  ['2-plan/plan.md', 'plano: problema, cenários com prova, decisões e fatias'],
-  ['2-plan/checks.json', 'cenários e fatias extraídos pelo plan-check'],
-  ['1-design/design-system.md', 'design system da feature'],
-  ['3-implement/reports', 'relatórios das fatias (**Arquivos:**/**Standards:**): o registro da implementação'],
-  ['4-review/verifier.md', 'verificador do Gate 3: cada cenário provado'],
-  ['4-review/reviewer.md', 'revisor do Gate 3: escopo, arquitetura, regressão'],
-  ['4-review/security.md', 'segurança do Gate 3 (só com caminho sensível)'],
-];
-
-function readJson(path) {
-  return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
-}
-
-function decisionTitles(featureDir, limit = 5) {
-  try {
-    const path = join(featureDir, '2-plan', 'checks.json');
-    if (!existsSync(path)) return [];
-    const adrs = readJson(path).adrs;
-    if (!Array.isArray(adrs)) return [];
-    return adrs.map((a) => `${a.id} — ${a.title}`).slice(-limit);
-  } catch {
-    return [];
-  }
-}
-
-function readWorktreeEnv(cwd) {
-  try {
-    const path = join(cwd, '.morph', 'worktree.env');
-    if (!existsSync(path)) return null;
-    const content = readFileSync(path, 'utf8');
-    const get = (key) => content.match(new RegExp(`^${key}=(.+)$`, 'm'))?.[1] || null;
-    const port = get('PORT');
-    return port ? { port, range: get('MORPH_PORT_RANGE') } : null;
-  } catch {
-    return null;
-  }
-}
-
-function nextLine(featureName, cwd) {
-  const fallback = `Rode \`morph-spec next ${featureName}\`.`;
-  try {
-    const next = nextStepFor(featureName, cwd);
-    return next ? formatNext(next) : fallback;
-  } catch {
-    return fallback;
-  }
-}
-
-// `opts.worktree` overrides `feature.worktree`: that field is root-owned and stripped from branch-local
-// copies, so a handoff built inside a worktree would otherwise say "no worktree registered".
-export function buildHandoff(featureName, cwd = process.cwd(), opts = {}) {
-  const featureDir = join(cwd, '.morph', 'features', featureName);
-  if (!existsSync(join(featureDir, 'feature.json'))) return null;
-
-  let feature;
-  try {
-    feature = readJson(join(featureDir, 'feature.json'));
-  } catch {
-    return null;
-  }
-
-  let phase = 'plan';
-  let pendingGates = [];
-  try {
-    phase = derivePhaseForFeature(featureName, cwd) || 'plan';
-    pendingGates = getPendingGates(featureName, cwd) || [];
-  } catch {}
-
-  const generatedAt = new Date().toISOString();
-  const slices = sliceProgress(featureDir);
-  const env = readWorktreeEnv(cwd);
-  const decisions = decisionTitles(featureDir);
-  const worktree = opts.worktree !== undefined ? opts.worktree : (feature.worktree || null);
-
-  const gates = feature.approvals || feature.approvalGates || {};
-  const gateLine = Object.entries(gates)
-    .map(([name, g]) => (g?.approved ? `${name} ✔${g.approvedBy ? ` (${g.approvedBy})` : ''}` : `${name} pendente`))
-    .join(' · ') || '—';
-
-  const relFeatureDir = `.morph/features/${featureName}`;
-  const pointers = POINTER_CANDIDATES
-    .filter(([rel]) => existsSync(join(featureDir, rel)))
-    .map(([rel, why], i) => `${i + 1}. \`${relFeatureDir}/${rel}\` — ${why}`);
-
-  const lines = [
-    `# Handoff — ${featureName}`,
-    '',
-    `> Documento derivado, gerado em ${generatedAt} por \`morph-spec handoff\`.`,
-    '> Regenere com o comando — nunca edite à mão. Aponta para os arquivos da',
-    '> feature em vez de copiá-los: leia os ponteiros, não confie em resumo velho.',
-    '',
-    '## Identidade',
-    '',
-    `- Feature: **${featureName}** (${feature.workType || 'feature'}) · fase: **${phase}** · status: ${feature.status || '—'}`,
-    worktree?.path
-      ? `- Local: worktree \`${worktree.path}\` · branch \`${worktree.branch || `morph/${featureName}`}\``
-      : '- Local: raiz primária (sem worktree registrado)',
-    env
-      ? `- Ambiente: PORT ${env.port}${env.range ? ` (bloco ${env.range})` : ''} — fonte \`.morph/worktree.env\`; suba dev servers SEMPRE nessas portas`
-      : null,
-    '',
-    '## Estado',
-    '',
-    `- Gates: ${gateLine}`,
-    slices
-      ? `- Fatias: ${slices.done}/${slices.total} feitas${slices.partial ? ` · ${slices.partial} parcial(is)` : ''}${slices.blocked ? ` · ${slices.blocked} bloqueada(s)` : ''} · prontas agora: ${readySlices(slices).map((s) => `**${s.id}** "${s.title}"`).join(', ') || 'nenhuma'}`
-      : '- Fatias: sem checks.json ainda (rode plan-check)',
-    pendingGates.length ? `- Gates pendentes: ${pendingGates.join(', ')}` : null,
-    '',
-    '## Leia nesta ordem (ponteiros — nada copiado)',
-    '',
-    ...(pointers.length ? pointers : ['1. (nenhum artefato ainda — feature recém-criada)']),
-    decisions.length ? '' : null,
-    decisions.length ? `Últimas decisões: ${decisions.map((d) => `"${d}"`).join(' · ')}` : null,
-    '',
-    '## Próxima ação',
-    '',
-    nextLine(featureName, cwd),
-    '',
-    '## Retomar',
-    '',
-    worktree?.path ? `- \`cd ${worktree.path}\` e abra o Claude Code (uma instância por worktree).` : '- Abra o Claude Code na raiz do projeto.',
-    `- Visão da frota: \`morph-spec fleet\` · status: \`morph-spec status ${featureName}\``,
-    '',
-  ].filter((l) => l !== null);
-
-  return {
-    markdown: `${lines.join('\n')}`,
-    meta: {
-      generatedAt,
-      phase,
-      slicesDone: slices?.done ?? 0,
-      slicesTotal: slices?.total ?? 0,
-    },
-  };
-}
-
-/** Marks the exclude block this generator owns in `.git/info/exclude`. */
-const HANDOFF_EXCLUDE_MARKER = '# morph-spec: derived handoff docs (managed — see handoff-generator)';
-const HANDOFF_EXCLUDE_PATTERN = '/.morph/**/handoff.md';
-
-// Never committed: left visible it lands in the `git status` the finish gates read. The common-dir
-// exclude hides it in every worktree; `**` also covers a feature folder after `archive` moves it.
-function ensureHandoffExcluded(cwd) {
-  ensureCommonExclude(cwd, [HANDOFF_EXCLUDE_PATTERN], HANDOFF_EXCLUDE_MARKER);
-}
-
-/** The written path, or null when the feature does not exist (nothing is created). */
-export function writeHandoff(featureName, cwd = process.cwd(), opts = {}) {
-  const result = buildHandoff(featureName, cwd, opts);
-  if (!result) return null;
-  const path = join(cwd, '.morph', 'features', featureName, 'handoff.md');
-  try {
-    ensureHandoffExcluded(cwd);
-    writeFileSync(path, result.markdown, 'utf8');
-    return path;
-  } catch {
-    return null;
-  }
-}

package/src/lib/mutation/adapters.js

@@ -1,79 +0,0 @@
-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 { 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 commandFor = (label) => withTrx(withFilter(base, subset.filter), { dir: trxDir, name: `${label}.trx` });
-  const runTests = async ({ label, env }) => {
-    const trxPath = join(trxDir, `${label}.trx`);
-    const r = await exec(commandFor(label), { 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,
-  };
-}
-
-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({ label, env }) {
-      const r = await exec(subset.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

@@ -1,61 +0,0 @@
-import { resolve } from 'node:path';
-import { discoverDotnetBuildTargets, dotnetBuildCommandFor } 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 discoverDotnetBuildTargets(node, resolve(projectPath || '.', node.cwd || '.'))
-    .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/dotnet-introspection.js

@@ -1,281 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from 'fs';
-import { dirname, join, resolve } from 'path';
-
-import { isInside } from '../tasks/test-runner.js';
-import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
-
-const MTP_RUNNER = 'Microsoft.Testing.Platform';
-const TYPE_HEADER = /\b(?:class|struct|record|interface)\b/;
-// `@` = verbatim identifier, `\` = unicode escape.
-const NAME_START = '[\\p{L}\\p{Nl}_@\\\\]';
-// TRIPWIRE with NO context rule: any exclusion based on what precedes the keyword can be
-// forged by a comment or exposed string. The quote in the lookahead makes every keyword
-// the blanked code counts also counted in the raw text, at the same offset.
-const TYPE_KEYWORD = new RegExp(`\\b(?:record\\s+(?:class|struct)|class|record|struct|interface)\\b(?=\\s*(?:${NAME_START}|["']|\\/[/*]|#))`, 'gu');
-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*)*`;
-const ATTRIBUTE_ARGS = '(?:\\((?:[^()\\]]|\\([^()\\]]*\\))*\\))?';
-const OTHER_ATTRIBUTE = `${QUALIFIER}${IDENT}\\s*${ATTRIBUTE_ARGS}`;
-const TEST_ATTRIBUTE_NAME = '(?:Fact|Theory|Test|TestMethod|DataTestMethod|TestCase|TestCaseSource)(?:Attribute)?';
-// A false POSITIVE is the unsafe side (a helper taken for a test file hides the tests that
-// use it), so the whole name must sit in an attribute section that CLOSES: a C# 12
-// collection such as `[\n Env.Test,\n];` must not match. Residual cases: csharpClasses.
-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',
-);
-
-// Roslyn reads CR/NEL/LS/PS as new-lines and U+001A as whitespace; JS `\s` misses NEL
-// and U+001A, which hid `class<NEL>Name`. Mapped 1:1 so offsets stay aligned with the code.
-const readText = (path) => {
-  try { return readFileSync(path, 'utf8').replace(/\x1A/g, ' ').replace(/^\uFEFF/, '').replace(/[\r\u0085\u2028\u2029]/g, '\n'); } catch { return null; }
-};
-
-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;
-}
-
-export function nearestProjectOf(fileAbs, rootAbs) {
-  return nearestProjectFile(fileAbs, rootAbs, /\.(?:cs|fs|vb)proj$/i);
-}
-
-const NON_CSHARP_SOURCE = /\.(?:razor|cshtml|fs|fsi|fsx|vb)$/i;
-
-/** No type scan, hence no class selector, for these. */
-export const isNonCSharpSource = (path) => NON_CSHARP_SOURCE.test(String(path));
-
-export const isDotnetSource = (path) => /\.cs$/i.test(String(path)) || isNonCSharpSource(path);
-
-/**
- * Nearest global.json walking up from the CWD, as the SDK resolves it (never from the
- * `.sln` argument). null when one 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';
-  }
-}
-
-const lineEnd = (text, i) => { const e = text.indexOf('\n', i); return e < 0 ? text.length : e; };
-
-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;
-}
-
-// A `"` inside a hole (`$"{d["k"]}"`) ends the literal as the scanner reads it,
-// leaving the hole 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;
-}
-
-/**
- * Comments, preprocessor lines and literals blanked, length and newlines kept; null when
- * a literal never ends or an interpolation hole is cut. A heuristic lexer that CAN misread:
- * csharpClasses never trusts it alone (it checks against the raw text).
- */
-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('');
-}
-
-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. 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.
- *
- * 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 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):
- * - 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 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
- *   it is left out of a selection;
- * - `hasTestAttribute` is still a heuristic, and ITS false positive is the unsafe
- *   side. 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 raw text is the lexer-independent truth about how many type keywords the file
-  // carries (the JSDoc explains why equal counts mean equal 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,
-  };
-}
-