@aperant/framework 0.7.0 → 0.7.4

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')
+}

package/src/cli/config/gitignore-drift.mjs

@@ -14,6 +14,7 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { detectWorktree } from '../git/worktree-detect.mjs'
 import { resolveSharePolicy } from './share-policy.mjs'
 import { buildAperantGitignoreTemplate } from './upgrade-gitignore.mjs'
 
@@ -35,11 +36,66 @@ const SKIP_COMMANDS = new Set([
 	'-h',
 ])
 
+/**
+ * BUG-028 — resolve the shared (main-repo) root for the dispatch hook.
+ *
+ * Mirrors `coordination/agent-identity.mjs::resolveSharedRoot` but does NOT
+ * depend on that module. The CoordinationStore seam is `@internal` (R8) —
+ * `bin/apt-tools.mjs` and its dispatch hooks must reach git through
+ * `git/worktree-detect.mjs` directly, not through `coordination/*`.
+ *
+ * @internal
+ */
+function resolveSharedRootForDrift(projectDir) {
+	try {
+		const wt = detectWorktree(projectDir)
+		return wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : projectDir
+	} catch {
+		return projectDir
+	}
+}
+
+/**
+ * BUG-028 — pretty-print the first few missing / extra lines as a
+ * unified-diff snippet for the gate's `reason` field. Capped at
+ * `maxLines` per side so the reason stays short enough for terminal
+ * output. Returns the empty string when both sides match.
+ */
+export function buildGitignoreDiffSummary(expected, actual, maxLines = 3) {
+	const expSet = new Set(String(expected).split('\n'))
+	const actSet = new Set(String(actual).split('\n'))
+	const missing = []
+	for (const line of expSet) {
+		if (line === '') continue
+		if (!actSet.has(line)) {
+			missing.push(line)
+			if (missing.length >= maxLines) break
+		}
+	}
+	const extra = []
+	for (const line of actSet) {
+		if (line === '') continue
+		if (!expSet.has(line)) {
+			extra.push(line)
+			if (extra.length >= maxLines) break
+		}
+	}
+	if (missing.length === 0 && extra.length === 0) return ''
+	const parts = []
+	for (const line of missing) parts.push(`+ ${line}`)
+	for (const line of extra) parts.push(`- ${line}`)
+	return parts.join('\n')
+}
+
 /**
  * Pure comparison primitive — returns whether the on-disk `.aperant/.gitignore`
  * differs from the policy-expected template. Returns `{ drifted: false }` when
  * the `.aperant/` dir or file is absent (nothing to compare).
  *
+ * BUG-028: when drifted, embeds a unified-diff summary (≤3 missing/extra
+ * lines per side) in `reason` so the user sees exactly what drifted
+ * without re-running `apt-tools config upgrade-gitignore --dry-run`.
+ *
  * @internal
  */
 export function checkGitignoreDrift(projectRoot) {
@@ -65,7 +121,16 @@ export function checkGitignoreDrift(projectRoot) {
 	} catch {
 		return { drifted: false, reason: 'read-failed' }
 	}
-	return { drifted: actual !== expected, reason: null }
+	const drifted = actual !== expected
+	if (!drifted) return { drifted: false, reason: null }
+	const diff = buildGitignoreDiffSummary(expected, actual)
+	return {
+		drifted: true,
+		reason: diff
+			? `.aperant/.gitignore drift detected:\n${diff}`
+			: '.aperant/.gitignore drift detected (whitespace-only)',
+		diff,
+	}
 }
 
 /**
@@ -74,15 +139,21 @@ export function checkGitignoreDrift(projectRoot) {
  *   - `command` is not in the hot-path allowlist
  *   - `.aperant/.gitignore` exists AND does not match the expected template
  *
+ * BUG-028: resolves the shared (main-repo) root internally so the same drift
+ * case produces the same verdict regardless of cwd context. Pre-fix this
+ * inspected `cwd` directly, producing a warning from one cwd context and a
+ * clean envelope from another for the same on-disk drift.
+ *
  * Never throws.
  *
  * @internal
  */
-export function emitDriftWarningIfAny(projectRoot, command) {
+export function emitDriftWarningIfAny(cwd, command) {
 	try {
 		if (process.env.APT_SUPPRESS_GITIGNORE_DRIFT === '1') return
 		if (!command || SKIP_COMMANDS.has(command)) return
-		const { drifted } = checkGitignoreDrift(projectRoot)
+		const sharedRoot = resolveSharedRootForDrift(cwd)
+		const { drifted } = checkGitignoreDrift(sharedRoot)
 		if (drifted) {
 			process.stderr.write(
 				'[apt-tools] warning: .aperant/.gitignore is out of sync with share policy — run `apt-tools config upgrade-gitignore . --dry-run` to see the diff.\n',