@aperant/framework 0.7.0 → 0.7.3

package/src/cli/commands/pr-review-audit-fixer.mjs

@@ -668,10 +668,14 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	}
 }
 
-function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
-	// Try the group-specific naming first (fixes-applied-group{N}.md) for
-	// fixer-{N}, then fall back to the unscoped fixes-applied.md which the
-	// self-reviewer writes to self-review.md separately.
+export function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
+	// BUG-030: strict-ordered candidate list. Parallel fixers write to
+	// distinct fixer-named markdowns (fixes-applied-fixer-{N}.md AND/OR
+	// fixes-applied-{fixer}.md); the legacy group-named form remains for
+	// backward-compat with reviews started before this fix. fixes-applied.md
+	// (unscoped) stays last as the legacy single-fixer fallback. NO broad
+	// glob — false-positives on the wrong fixer's file are what caused the
+	// `hallucinated` flake (4 sightings in 3 days per spec-gaps).
 	const iterDir = join(reviewDir, 'iterations', String(iteration))
 	const candidates = []
 	if (fixer === 'self-reviewer') {
@@ -681,7 +685,9 @@ function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
 		const match = /^fixer-(\d+)$/.exec(fixer)
 		if (match) {
 			candidates.push(join(iterDir, `fixes-applied-group${match[1]}.md`))
+			candidates.push(join(iterDir, `fixes-applied-fixer-${match[1]}.md`))
 		}
+		candidates.push(join(iterDir, `fixes-applied-${fixer}.md`))
 		candidates.push(join(iterDir, 'fixes-applied.md'))
 	}
 	for (const c of candidates) {
@@ -802,7 +808,14 @@ export function cmdPrReviewAuditFixer(projectDir, extraArgs) {
 
 	const worktreeArg = flags.get('worktree')
 	if (!worktreeArg) return err('Required: --worktree <path>')
-	const worktree = resolve(worktreeArg)
+	// BUG-015: resolve relative to the passed projectDir (not process.cwd()).
+	// Callers invoke audit-fixer from a non-worktree cwd (the main repo) with
+	// a relative --worktree like `../worktrees/foo`; resolving against cwd
+	// returned a bogus path that didn't exist, causing the audit to see zero
+	// staged files and false-positive `hallucinated`. The existing `cwd:
+	// worktree` at the spawn site (line 437-473) already scopes git
+	// invocations correctly, so no `git -C` change is needed.
+	const worktree = resolve(projectDir, worktreeArg)
 
 	const statusLineArg = flags.get('status-line')
 	// Missing / empty status line is fail-closed to hallucinated, not a

package/src/cli/commands/task.mjs

@@ -14,7 +14,11 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { getTaskIsolationConfig, loadProjectConfig } from '../config/load.mjs'
+import {
+	getTaskIsolationConfig,
+	loadMergedProjectConfig,
+	loadProjectConfig,
+} from '../config/load.mjs'
 import { findMostRecentEventForTask } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { getGitIdentity } from '../git/identity.mjs'
@@ -127,9 +131,16 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 				// a later roadmap add-milestone/add-phase may populate it.
 			}
 
-			// Load config for date format preference
-			const configPath = join(targetDir, '.aperant', 'config.json')
-			const config = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf-8')) : {}
+			// AUDIT-001: read through the merged loader so local-only
+			// overrides for preferences.date_format / preferences.time_format
+			// win over the shared config.json fallback.
+			// Guard: malformed config.local.json must not crash task creation.
+			let config
+			try {
+				config = loadMergedProjectConfig(targetDir) ?? {}
+			} catch {
+				config = {}
+			}
 			// User-supplied --id bypasses the collision guard (caller owns the
 			// uniqueness contract). Generated ids run through a numeric-counter
 			// disambiguator that appends -2, -3, … when the candidate already
@@ -982,7 +993,50 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
 					if (prUrlForCiWatch) {
-						ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+						// BUG-027 (a): pre-arm gh check. If the PR is already
+						// MERGED/CLOSED, skip arming so we don't leak a new
+						// watcher state file we'll immediately have to GC. gh
+						// rate-limit / offline / ENOENT falls back to arm (mirror
+						// the existing rate_limited/offline patterns at lines
+						// 1322/1326) — non-fatal so a transient gh failure
+						// doesn't prevent legitimate watcher arming.
+						const ghFixture = process.env.APT_GH_FIXTURE_JSON
+						let terminalState = null
+						if (ghFixture) {
+							try {
+								const parsed = JSON.parse(ghFixture)
+								if (parsed?.state === 'MERGED' || parsed?.state === 'CLOSED') {
+									terminalState = parsed.state
+								}
+							} catch {
+								/* malformed fixture → fall through to arm */
+							}
+						} else {
+							try {
+								const res = spawnSync('gh', ['pr', 'view', prUrlForCiWatch, '--json', 'state'], {
+									cwd: targetDir,
+									encoding: 'utf-8',
+								})
+								if (res.status === 0 && res.stdout) {
+									const parsed = JSON.parse(res.stdout)
+									if (parsed?.state === 'MERGED' || parsed?.state === 'CLOSED') {
+										terminalState = parsed.state
+									}
+								}
+								/* non-zero exit / ENOENT / parse error → fall through to arm */
+							} catch {
+								/* never block arming on gh transport error */
+							}
+						}
+						if (terminalState) {
+							ciWatchResult = {
+								ci_watch_armed: false,
+								ci_watch_skip_reason: 'pr-terminal-state',
+								ci_watch: null,
+							}
+						} else {
+							ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+						}
 					}
 
 					regenerateTaskIndex(targetDir)
@@ -1479,6 +1533,30 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					mergedAt: parsed.mergedAt ?? null,
 				})
 
+				// BUG-027 (b): tear down any armed ci-watch state for this PR.
+				// `doStop` is idempotent (returns `not-found` for missing state
+				// files), so calling unconditionally here is safe. Without this
+				// the watcher state file leaks past PR-terminal-state and
+				// downstream operations (ci-watch sweep, health-check) flag it
+				// as orphaned. Failure is logged into errors[] as a warning;
+				// the merge close itself has already succeeded.
+				try {
+					const prNumber = parsed.number ?? extractPrNumber(task.pr_url)
+					if (prNumber !== null) {
+						cmdCiWatch('stop', targetDir, [
+							'--pr',
+							String(prNumber),
+							'--reason',
+							'task-closed-merged',
+						])
+					}
+				} catch (e) {
+					errors.push({
+						id,
+						reason: `ci-watch-stop-failed: ${e?.message ?? String(e)}`,
+					})
+				}
+
 				// Append a pending_narration[] ledger entry on successful merged close
 				// so /apt:close-task --narrate-only can drain it later. The ledger is
 				// additive-only; failure to write must never undo the close above

package/src/cli/commands/validate-evidence.mjs

@@ -166,7 +166,12 @@ export function isAnnotationLine(line, sourceWindow) {
  */
 export function parseFindingsMarkdown(markdown) {
 	const findings = []
-	const headerRx = /^## Finding:\s*([A-Z]+-\d+)\s*--\s*(.+)$/gm
+	// BUG-032: widen to accept H2|H3, optional `Finding:` prefix, and any of
+	// ASCII `--`, em-dash `—`, or en-dash `–` as the id/title separator. The
+	// validator-agent's consolidated `validated.md` shape uses H3 + em-dash
+	// with no `Finding:` prefix; the specialist shape uses H2 + `Finding:` +
+	// ASCII `--`. Both must round-trip through the same parser.
+	const headerRx = /^#{2,3}\s+(?:Finding:\s*)?([A-Z]+-\d+)\s*(?:--|—|–)\s*(.+)$/gm
 	const matches = [...markdown.matchAll(headerRx)]
 	for (let i = 0; i < matches.length; i++) {
 		const m = matches[i]
@@ -202,23 +207,45 @@ function parseFindingBlock(body, id, title, start, end) {
 	// FRAMEWORK-BUG-001 surfaced by /apt:pr-review on PR #68 in 2026-04).
 	// `(?:-\d+)?` consumes the trailing range so it doesn't leak into the
 	// file capture.
+	// BUG-032: the validator-agent's `validated.md` carries the cited path
+	// in `- **Original**:` instead of `- **File**:`. Map either spelling
+	// onto `file`/`line`; specialist shape continues to write to `file`.
+	const fileField = fields.file ?? fields.original
 	let file = null
 	let line = null
-	if (fields.file) {
-		const fileMatch = /^`?([^`:]+?)(?::(\d+)(?:-\d+)?)?`?\s*$/.exec(fields.file)
+	let lineRangeFromField = null
+	if (fileField) {
+		const fileMatch = /^`?([^`:]+?)(?::(\d+)(?:-(\d+))?)?`?\s*$/.exec(fileField)
 		if (fileMatch) {
 			file = fileMatch[1].trim()
 			line = fileMatch[2] ? Number(fileMatch[2]) : null
+			if (fileMatch[2] && fileMatch[3]) {
+				lineRangeFromField = [Number(fileMatch[2]), Number(fileMatch[3])]
+			}
 		}
 	}
 
 	// Description block: everything between `### Description` and the next `###`.
 	const description = extractSection(body, 'Description') ?? ''
 
-	// Evidence code block: first triple-backticked block after `### Evidence`.
+	// Evidence code block: first triple-backticked block after `### Evidence`
+	// (specialist shape). BUG-032: validator-consolidated `validated.md`
+	// shape carries evidence as a `- **Evidence**:` field whose value is the
+	// fenced block immediately following the field line. Fall back to the
+	// first fenced block after that field marker when the section heading
+	// form yields nothing.
 	const evidenceSection = extractSection(body, 'Evidence') ?? ''
+	let evidence
 	const fenced = /```[^\n]*\n([\s\S]*?)```/.exec(evidenceSection)
-	const evidence = fenced ? fenced[1] : evidenceSection
+	if (fenced) {
+		evidence = fenced[1]
+	} else if (evidenceSection) {
+		evidence = evidenceSection
+	} else {
+		const fieldEvidenceRx = /-\s*\*\*Evidence\*\*:\s*(?:\n+)```[^\n]*\n([\s\S]*?)```/i
+		const fieldFenced = fieldEvidenceRx.exec(body)
+		evidence = fieldFenced ? fieldFenced[1] : (fields.evidence ?? '')
+	}
 
 	// Suggested Fix section (prose + optional fenced snippets). Unlike
 	// Evidence we keep the whole section — snippets AND surrounding
@@ -231,9 +258,11 @@ function parseFindingBlock(body, id, title, start, end) {
 	const rangeMatch = /Lines? examined[^\d]*(\d+)\s*-\s*(\d+)/i.exec(contextSection)
 	const lineRange = rangeMatch
 		? [Number(rangeMatch[1]), Number(rangeMatch[2])]
-		: line
-			? [line, line]
-			: null
+		: lineRangeFromField
+			? lineRangeFromField
+			: line
+				? [line, line]
+				: null
 
 	// Cross-file evidence (optional): `### Cross-File Evidence` block.
 	// Each file gets a `- **File**: path` + fenced snippet.
@@ -294,11 +323,64 @@ export function detectReferencedFiles(finding) {
 	return [...tokens].sort()
 }
 
+/**
+ * BUG-014 fuzzy-evidence helpers — token-set Jaccard + line-anchor count.
+ *
+ * Tokenize on word characters so whitespace, punctuation, and operator
+ * spacing don't perturb similarity. Same tokenizer runs on both sides so
+ * the ratio is symmetric.
+ */
+export function tokenizeForJaccard(text) {
+	if (!text) return []
+	return (
+		String(text)
+			.toLowerCase()
+			.match(/[a-z0-9_$]+/g) ?? []
+	)
+}
+
+export function jaccardSimilarity(a, b) {
+	const setA = new Set(tokenizeForJaccard(a))
+	const setB = new Set(tokenizeForJaccard(b))
+	if (setA.size === 0 && setB.size === 0) return 1
+	if (setA.size === 0 || setB.size === 0) return 0
+	let intersection = 0
+	for (const t of setA) if (setB.has(t)) intersection++
+	const union = setA.size + setB.size - intersection
+	return intersection / union
+}
+
+/**
+ * Count evidence lines that appear as literal substrings of the cited
+ * file range (after `normalizeForLiteralMatch`). Used as the
+ * anchor-count mitigation against token-stuffing under fuzzy mode.
+ */
+export function countExactLineAnchors(evidenceLines, target) {
+	const normTarget = normalizeForLiteralMatch(target)
+	let count = 0
+	for (const line of evidenceLines) {
+		const normLine = normalizeForLiteralMatch(line)
+		if (!normLine) continue
+		if (normTarget.includes(normLine)) count++
+	}
+	return count
+}
+
 /**
  * Check a single finding against the literal-substring rule. Returns
  * a decision object; caller applies it to the markdown.
+ *
+ * Optional `opts.allowApprox` enables BUG-014 opt-in fuzzy fallback —
+ * when the literal check fails, compute Jaccard ≥ `approxFloor` on the
+ * cited range AND require ≥2 exact line anchors in the cited range
+ * (token-stuffing mitigation). On success, emit downgraded status
+ * `dismissed_evidence_approx_confirmed` unless `opts.llmValidatorConfirmed`
+ * is also set, in which case status becomes `confirmed_valid_approx`.
  */
-export function checkFinding(finding, worktreeRoot) {
+export function checkFinding(finding, worktreeRoot, opts = {}) {
+	const allowApprox = Boolean(opts.allowApprox)
+	const approxFloor = typeof opts.approxFloor === 'number' ? opts.approxFloor : 0.85
+	const llmValidatorConfirmed = Boolean(opts.llmValidatorConfirmed)
 	// Rule 1: evidence must be a literal substring of the cited file range.
 	if (!finding.file) {
 		return {
@@ -361,6 +443,10 @@ export function checkFinding(finding, worktreeRoot) {
 	const normTarget = normalizeForLiteralMatch(target)
 	const normWholeEvidence = normalizeForLiteralMatch(keptLines.join('\n'))
 
+	// Capture the first literal-mismatch reason so the fuzzy fallback can
+	// reuse it as the rejection note when fuzzy ALSO fails.
+	let literalRejectNote = null
+
 	if (normTarget.includes(normWholeEvidence)) {
 		// Fast path: the kept evidence (joined back) is still a literal
 		// contiguous substring of the cited range. This is the common
@@ -370,17 +456,43 @@ export function checkFinding(finding, worktreeRoot) {
 		// (e.g. `code line A\n// ... 10 more\ncode line B`). Match each
 		// kept line individually against the cited range. Every kept
 		// line must appear; any miss is a paraphrase / fabrication and
-		// the whole finding is rejected.
+		// the whole finding is rejected — unless the caller opted into
+		// fuzzy fallback (BUG-014).
 		for (const line of keptLines) {
 			const normLine = normalizeForLiteralMatch(line)
 			if (!normLine) continue
 			if (!normTarget.includes(normLine)) {
-				return {
-					status: 'dismissed_evidence_not_literal',
-					note: `Evidence not found as literal substring of ${finding.file} lines ${safeStart}-${safeEnd}: line "${normLine.slice(0, 120)}" missing from cited range.`,
-				}
+				literalRejectNote = `Evidence not found as literal substring of ${finding.file} lines ${safeStart}-${safeEnd}: line "${normLine.slice(0, 120)}" missing from cited range.`
+				break
+			}
+		}
+	}
+
+	// BUG-014: opt-in fuzzy fallback. Default behaviour (allowApprox=false)
+	// preserves the anti-fabrication guarantee — literal mismatch returns
+	// `dismissed_evidence_not_literal` unchanged. When the caller passes
+	// `--allow-approx-evidence`, attempt Jaccard ≥ floor AND ≥2 exact
+	// line anchors in the cited range (mitigates token-stuffing). On
+	// success, downgrade status to `dismissed_evidence_approx_confirmed`
+	// unless the caller also passed `--llm-validator-confirmed`, in
+	// which case promote to `confirmed_valid_approx`.
+	if (literalRejectNote) {
+		if (!allowApprox) {
+			return { status: 'dismissed_evidence_not_literal', note: literalRejectNote }
+		}
+		const similarity = jaccardSimilarity(keptLines.join('\n'), target)
+		const anchors = countExactLineAnchors(keptLines, target)
+		if (similarity < approxFloor || anchors < 2) {
+			return {
+				status: 'dismissed_evidence_not_literal',
+				note: `${literalRejectNote} Fuzzy fallback also rejected (jaccard=${similarity.toFixed(3)} floor=${approxFloor}, anchors=${anchors}/2).`,
 			}
 		}
+		const approxNote = `Approximate match accepted under --allow-approx-evidence (jaccard=${similarity.toFixed(3)} ≥ ${approxFloor}, anchors=${anchors} ≥ 2).`
+		if (llmValidatorConfirmed) {
+			return { status: 'confirmed_valid_approx', note: approxNote }
+		}
+		return { status: 'dismissed_evidence_approx_confirmed', note: approxNote }
 	}
 
 	// Rule 2: multi-file references require Cross-File Evidence.
@@ -490,6 +602,18 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 	const worktreeRoot = resolve(worktree)
 	if (!existsSync(worktreeRoot)) return err(`Worktree not found: ${worktreeRoot}`)
 
+	// BUG-014: opt-in fuzzy-evidence flags. Defaults preserve the
+	// anti-fabrication guarantee — literal substring is still the only
+	// matcher when no flag is set.
+	const allowApprox = flags.get('allow-approx-evidence') === true
+	const approxFloorRaw = flags.get('approx-floor')
+	const approxFloor = typeof approxFloorRaw === 'string' ? Number(approxFloorRaw) : 0.85
+	if (allowApprox && (!Number.isFinite(approxFloor) || approxFloor <= 0 || approxFloor > 1)) {
+		return err(`Invalid --approx-floor value: ${approxFloorRaw} (expected 0 < n ≤ 1)`)
+	}
+	const llmValidatorConfirmed = flags.get('llm-validator-confirmed') === true
+	const checkOpts = { allowApprox, approxFloor, llmValidatorConfirmed }
+
 	const files = readdirSync(dir).filter((f) => f.endsWith('.md'))
 	const summary = {
 		status: 'ok',
@@ -506,13 +630,21 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 		const full = join(dir, f)
 		const md = readFileSync(full, 'utf-8')
 		const findings = parseFindingsMarkdown(md)
+
+		// BUG-032: always record the file in `processed_files`. The
+		// previous `continue` on empty findings caused validated.md to
+		// silently no-op when the header regex didn't match, leaving
+		// downstream gates with `processed_files: []` and no audit trail
+		// that the file was even read.
+		summary.processed_files.push({ file: f, findings_count: findings.length })
+
 		if (findings.length === 0) continue
 
 		const decisions = []
 		for (const finding of findings) {
-			const decision = checkFinding(finding, worktreeRoot)
+			const decision = checkFinding(finding, worktreeRoot, checkOpts)
 			decisions.push({ finding, decision })
-			if (decision.status === 'confirmed_valid') {
+			if (decision.status === 'confirmed_valid' || decision.status === 'confirmed_valid_approx') {
 				summary.validated++
 			} else {
 				summary.rejected++
@@ -530,7 +662,16 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 		if (rewritten !== md) {
 			writeFileSync(full, rewritten, 'utf-8')
 		}
-		summary.processed_files.push(f)
+	}
+
+	// BUG-032: surface parser-shape drift early. If we read N markdown
+	// files but extracted zero findings, warn on stderr so future schema
+	// changes don't silently no-op the gate.
+	const totalFindings = summary.processed_files.reduce((acc, e) => acc + (e.findings_count ?? 0), 0)
+	if (files.length > 0 && totalFindings === 0) {
+		process.stderr.write(
+			`WARNING: validate-evidence read ${files.length} markdown file(s) but extracted 0 findings — parser shape mismatch?\n`,
+		)
 	}
 
 	return ok(summary)

package/src/cli/commands/vitest-doctor.mjs

@@ -0,0 +1,173 @@
+/**
+ * commands/vitest-doctor.mjs — FRAMEWORK-BUG-026 diagnostic subcommand.
+ *
+ * Globs every `vitest.config.{ts,js,mjs}` under the project root (skipping
+ * node_modules), parses each for the two shim signals the framework
+ * centralizes in `packages/framework/test-utils/vitest.shared.mjs`:
+ *
+ *   - `NODE_ENV='test'`            (process.env.NODE_ENV set OR defineVitestShim active)
+ *   - `oxc.jsx.runtime='automatic'` (jsxAutomaticShim active)
+ *
+ * Reports a matrix and warns when a workspace has JSX-rendering tests
+ * (any `*.test.tsx` under `src/`) but no jsxAutomaticShim coverage —
+ * that's the BUG-026 first-test paper cut.
+ *
+ * Exit codes:
+ *   0 — no warnings (or only informational matrix output)
+ *   1 — at least one workspace has JSX-rendering tests without
+ *       jsxAutomaticShim coverage
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+const VITEST_CONFIG_NAMES = new Set(['vitest.config.ts', 'vitest.config.js', 'vitest.config.mjs'])
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'out', '.next', '.aperant'])
+
+export function cmdVitestDoctor(projectDir, extraArgs) {
+	if (!projectDir) return err('Usage: apt-tools vitest doctor <project-dir> [--format json|md]')
+	const root = resolve(projectDir)
+	if (!existsSync(root)) return err(`project-dir not found: ${root}`)
+	const flags = parseFlags(extraArgs ?? [])
+	const format = (flags.get('format') || 'json').toLowerCase()
+
+	const configs = findVitestConfigs(root)
+	const matrix = configs.map((configPath) => inspectConfig(root, configPath))
+	const warnings = matrix
+		.filter((row) => row.has_jsx_rendering_tests && !row.jsx_automatic_shim)
+		.map((row) => ({
+			workspace: row.workspace,
+			reason:
+				'has JSX-rendering tests under src/ but vitest.config does not enable jsxAutomaticShim',
+		}))
+
+	const envelope = {
+		status: 'ok',
+		command: 'vitest-doctor',
+		project_dir: root,
+		configs_found: matrix.length,
+		matrix,
+		warnings,
+	}
+
+	if (format === 'md') {
+		envelope.markdown = renderMarkdown(matrix, warnings)
+	}
+
+	if (warnings.length > 0) {
+		// Exit code 1 — surface drift so the user knows to wire the shim.
+		return exitWith(envelope, 1)
+	}
+	return ok(envelope)
+}
+
+function findVitestConfigs(root) {
+	const out = []
+	walk(root, root, out)
+	return out
+}
+
+function walk(rootAbs, dirAbs, out) {
+	let names
+	try {
+		names = readdirSync(dirAbs)
+	} catch {
+		return
+	}
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue
+		const abs = join(dirAbs, name)
+		let st
+		try {
+			st = statSync(abs)
+		} catch {
+			continue
+		}
+		if (st.isDirectory()) {
+			walk(rootAbs, abs, out)
+		} else if (st.isFile() && VITEST_CONFIG_NAMES.has(name)) {
+			out.push(abs)
+		}
+	}
+}
+
+function inspectConfig(rootAbs, configPath) {
+	const workspace = relative(rootAbs, configPath)
+	const dir = join(configPath, '..')
+	let body = ''
+	try {
+		body = readFileSync(configPath, 'utf-8')
+	} catch {
+		return {
+			workspace,
+			node_env_shim: false,
+			jsx_automatic_shim: false,
+			has_jsx_rendering_tests: false,
+			error: 'read-failed',
+		}
+	}
+	// NODE_ENV shim: either the literal `process.env.NODE_ENV = 'test'`
+	// pattern OR `defineVitestShim(` (any non-explicit-false arg).
+	const node_env_shim =
+		/process\.env\.NODE_ENV\s*=\s*['"`]test['"`]/.test(body) ||
+		/defineVitestShim\([^)]*\)/.test(body)
+	// jsxAutomaticShim: literal `oxc.jsx.runtime` = 'automatic' OR
+	// `jsxAutomaticShim: true` inside a defineVitestShim() arg.
+	const jsx_automatic_shim =
+		/oxc\s*:\s*\{[^}]*jsx[^}]*runtime\s*:\s*['"`]automatic['"`]/s.test(body) ||
+		/jsxAutomaticShim\s*:\s*true/.test(body)
+	const has_jsx_rendering_tests = workspaceHasJsxRenderingTests(dir)
+	return { workspace, node_env_shim, jsx_automatic_shim, has_jsx_rendering_tests }
+}
+
+function workspaceHasJsxRenderingTests(workspaceDir) {
+	const srcDir = join(workspaceDir, 'src')
+	if (!existsSync(srcDir)) return false
+	return scanForTsxTest(srcDir)
+}
+
+function scanForTsxTest(dirAbs) {
+	let names
+	try {
+		names = readdirSync(dirAbs)
+	} catch {
+		return false
+	}
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue
+		const abs = join(dirAbs, name)
+		let st
+		try {
+			st = statSync(abs)
+		} catch {
+			continue
+		}
+		if (st.isDirectory()) {
+			if (scanForTsxTest(abs)) return true
+		} else if (st.isFile() && /\.test\.tsx$/.test(name)) {
+			return true
+		}
+	}
+	return false
+}
+
+function renderMarkdown(matrix, warnings) {
+	const lines = ['## vitest-doctor matrix', '']
+	lines.push('| workspace | NODE_ENV shim | jsxAutomaticShim | has JSX tests |')
+	lines.push('|-----------|---------------|------------------|---------------|')
+	for (const r of matrix) {
+		lines.push(
+			`| \`${r.workspace}\` | ${r.node_env_shim ? '✓' : '✗'} | ${r.jsx_automatic_shim ? '✓' : '✗'} | ${r.has_jsx_rendering_tests ? '✓' : '—'} |`,
+		)
+	}
+	if (warnings.length > 0) {
+		lines.push('', '## Warnings', '')
+		for (const w of warnings) {
+			lines.push(`- \`${w.workspace}\` — ${w.reason}`)
+		}
+	}
+	return lines.join('\n')
+}