@aperant/framework 0.19.0 → 0.20.0

package/src/cli/commands/features-audit.mjs

@@ -1,302 +0,0 @@
-/**
- * commands/features-audit.mjs — CLI entry point for the features-registry
- * audit (C33).
- *
- * Modes:
- *   - report only (default): print `new_components`, `unregistered`, `stub_patches`
- *   - `--apply-stubs`:        additionally write the stub patches to disk.
- *                             This is what the /apt:execute post-step calls.
- *
- * Diff source precedence:
- *   1. `--diff-files <a,b,c>` explicit CSV (highest priority)
- *   2. `--since <ref>` → runs `git diff --name-only <ref>..HEAD`
- *   3. fallback: `git diff HEAD --name-only` (current WIP)
- *
- * BUG-025b worktree-redirect: features-audit historically wrote to the
- * invoking cwd's `.aperant/features/`, leaking generated `*.json` into
- * main when the executor invoked it from a worktree-isolated task. The
- * fix applies a 4-step resolution order (see resolveWriteRoot below):
- *   (1) cwd IS a worktree root → write there (current behaviour)
- *   (2) --task-id maps to an active non-terminal worktree task →
- *       redirect writes to that worktree's `.aperant/features/`
- *   (3) multiple active worktree-isolated tasks + no --task-id → error
- *   (4) `--no-worktree-redirect` opt-out preserves layer (1) behaviour
- */
-
-import { execFileSync, spawnSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
-import { join, resolve, sep } from 'node:path'
-import { loadDocsPolicy, matchSurfaceToPolicy } from '../docs-audit/policy.mjs'
-import { applyStubPatches, auditFeatureRegistry } from '../features/registry-audit.mjs'
-import { parseFlags } from '../util/args.mjs'
-import { err, ok } from '../util/result.mjs'
-import { resolveMainRepoRoot } from '../util/state-paths.mjs'
-
-const TERMINAL_PHASES = new Set(['completed', 'cancelled', 'closed', 'shipped', 'merged'])
-
-/**
- * BUG-025b — resolve where features-audit should write `*.json`.
- * See module header for the 4-step order. Returns `{ writeRoot, redirect_notice }`
- * on success or a synthetic error envelope (`{ error: { ... } }`) on the
- * ambiguous-worktree case.
- *
- * @internal — exported for unit testing.
- *
- * @param {{projectDir: string, taskId?: string | null, noRedirect?: boolean}} args
- * @returns {{writeRoot?: string, redirect_notice?: string | null, error?: {kind: string, message: string, active_worktree_tasks: string[]}}}
- */
-export function resolveWriteRoot({ projectDir, taskId, noRedirect }) {
-	const root = resolve(projectDir)
-	if (noRedirect === true) {
-		return { writeRoot: root, redirect_notice: null }
-	}
-	// Layer (1): cwd IS a worktree root. Worktrees have `git rev-parse
-	// --git-dir` != `git rev-parse --git-common-dir`. Falling through to
-	// the existing behaviour writes to this worktree's .aperant/features.
-	// Fast path: git sets GIT_DIR and GIT_COMMON_DIR in the environment
-	// when running inside a worktree hook context — if both are set and
-	// differ, we are in a worktree. This env-var check is ONLY valid at
-	// Layer (1) where we ask "is this process in a worktree?"; it must
-	// NOT be used to validate an untrusted external path (Layer 2 below).
-	const envDir = process.env.GIT_DIR
-	const envCommonDir = process.env.GIT_COMMON_DIR
-	if (envDir && envCommonDir) {
-		if (resolve(envDir) !== resolve(envCommonDir)) {
-			return { writeRoot: root, redirect_notice: null }
-		}
-	} else if (isWorktreeRoot(root)) {
-		return { writeRoot: root, redirect_notice: null }
-	}
-	// Layer (2): --task-id maps to an active non-terminal worktree-isolated
-	// task → redirect.
-	const stateActive = readActiveTasks(root)
-	if (taskId) {
-		const task = stateActive[taskId]
-		if (
-			task &&
-			!TERMINAL_PHASES.has(task.lifecycle_phase) &&
-			typeof task.worktree_path === 'string' &&
-			existsSync(task.worktree_path)
-		) {
-			const resolvedWorktree = resolve(task.worktree_path)
-			const worktreesDir = resolve(root, '.aperant', 'worktrees') + sep
-			const isUnderProject = resolvedWorktree.startsWith(root + sep) || resolvedWorktree === root
-			const isUnderWorktrees = resolvedWorktree.startsWith(worktreesDir)
-			// Accept only paths under the project root, under .aperant/worktrees/,
-			// or confirmed as a real git worktree by git itself. Rejects arbitrary
-			// paths injected via a tampered state.json while preserving test
-			// fixtures that use ad-hoc worktree paths outside the project tree.
-			if (!isUnderProject && !isUnderWorktrees && !isWorktreeRoot(resolvedWorktree)) {
-				return { writeRoot: root, redirect_notice: null }
-			}
-			return {
-				writeRoot: resolvedWorktree,
-				redirect_notice: `features-audit redirected writes to worktree ${resolvedWorktree} (--task-id ${taskId})`,
-			}
-		}
-	}
-	// Layer (3): multiple active worktree-isolated tasks AND no --task-id
-	// → actionable error. Single-worktree case is OK to default to root
-	// (the executor will set up the worktree's registry on first scan).
-	const activeWorktreeTasks = Object.entries(stateActive).filter(([_id, t]) => {
-		return (
-			t &&
-			!TERMINAL_PHASES.has(t.lifecycle_phase) &&
-			typeof t.worktree_path === 'string' &&
-			existsSync(t.worktree_path)
-		)
-	})
-	if (!taskId && activeWorktreeTasks.length > 1) {
-		return {
-			error: {
-				kind: 'ambiguous-worktree-context',
-				message: 'ambiguous worktree context; pass --task-id <id> or --no-worktree-redirect',
-				active_worktree_tasks: activeWorktreeTasks.map(([id]) => id),
-			},
-		}
-	}
-	// Default: current behaviour (write into cwd).
-	return { writeRoot: root, redirect_notice: null }
-}
-
-function isWorktreeRoot(projectDir) {
-	try {
-		const dirRes = spawnSync('git', ['rev-parse', '--git-dir'], {
-			cwd: projectDir,
-			encoding: 'utf-8',
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-		const commonRes = spawnSync('git', ['rev-parse', '--git-common-dir'], {
-			cwd: projectDir,
-			encoding: 'utf-8',
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-		if (dirRes.status !== 0 || commonRes.status !== 0) return false
-		return (dirRes.stdout || '').trim() !== (commonRes.stdout || '').trim()
-	} catch {
-		return false
-	}
-}
-
-function readActiveTasks(projectDir) {
-	// state-fork-fix: read the AUTHORITATIVE main board — readActiveTasks finds
-	// each task's worktree_path for the BUG-025b feature-write redirect, so it
-	// MUST read main or the redirect-target lookup itself forks. (The feature
-	// WRITE path / resolveWriteRoot stays untouched.)
-	const statePath = join(resolveMainRepoRoot(projectDir), '.aperant', 'state.json')
-	if (!existsSync(statePath)) return {}
-	try {
-		const parsed = JSON.parse(readFileSync(statePath, 'utf-8'))
-		return parsed?.active_tasks ?? {}
-	} catch {
-		return {}
-	}
-}
-
-export function cmdFeaturesAudit(projectDir, extraArgs) {
-	if (!projectDir) return err('Usage: apt-tools features-audit <project-dir> [flags]')
-	const root = resolve(projectDir)
-	const flags = parseFlags(extraArgs)
-
-	// BUG-025b: redirect writes to the active task's worktree when the
-	// caller is in a non-worktree cwd. See resolveWriteRoot for the
-	// 4-step resolution order.
-	const taskIdFlag = flags.get('task-id')
-	const taskId = typeof taskIdFlag === 'string' && taskIdFlag.trim() ? taskIdFlag.trim() : null
-	const noRedirect = flags.get('no-worktree-redirect') === true
-	const writeRootResult = resolveWriteRoot({ projectDir: root, taskId, noRedirect })
-	if (writeRootResult.error) {
-		return err(writeRootResult.error.message, 1, {
-			kind: writeRootResult.error.kind,
-			active_worktree_tasks: writeRootResult.error.active_worktree_tasks,
-		})
-	}
-	const writeRoot = writeRootResult.writeRoot
-	const redirectNotice = writeRootResult.redirect_notice
-	if (redirectNotice) {
-		// Surface the redirect once on stderr so the executor's log carries
-		// the audit trail without polluting stdout JSON.
-		process.stderr.write(`[features-audit] ${redirectNotice}\n`)
-	}
-
-	const diffFiles = resolveDiffFiles(root, flags)
-	const applyStubs = flags.has('apply-stubs')
-	const format = (flags.get('format') || 'json').toLowerCase()
-
-	const result = auditFeatureRegistry({ projectDir: writeRoot, diffFiles })
-
-	// Honor `.aperant/config.json.docs_policy`: only apply stubs for targets
-	// whose resolved policy is `auto-update`. This closes the skill-vs-code
-	// gap where `apt-execute` §3e-features promised `--apply-stubs` would
-	// no-op on surfaces the user opted out of. Patches whose target matches
-	// `skip` / `flag-drift` (or nothing) are surfaced in `stub_patches` but
-	// never written to disk.
-	let applied_patches = null
-	let skipped_patches = null
-	if (applyStubs && result.stub_patches.length > 0) {
-		const policy = loadDocsPolicy(root)
-		const eligible = []
-		const skipped = []
-		for (const patch of result.stub_patches) {
-			const policyValue = matchSurfaceToPolicy(patch.target, policy)
-			if (policyValue === 'auto-update') {
-				eligible.push(patch)
-			} else {
-				skipped.push({ target: patch.target, policy: policyValue })
-			}
-		}
-		if (eligible.length > 0) {
-			// BUG-025b: stubs are written to the resolved `writeRoot` (which
-			// may be the active task's worktree) rather than the invoking cwd.
-			applied_patches = applyStubPatches(writeRoot, eligible)
-		}
-		if (skipped.length > 0) {
-			skipped_patches = skipped
-		}
-	}
-
-	if (format === 'md') {
-		return ok({
-			status: 'ok',
-			command: 'features-audit',
-			format: 'md',
-			markdown: renderMarkdown(result, applied_patches, skipped_patches),
-			write_root: writeRoot,
-			...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
-			...result,
-			...(applied_patches ? { applied_patches } : {}),
-			...(skipped_patches ? { skipped_patches } : {}),
-		})
-	}
-
-	return ok({
-		status: 'ok',
-		command: 'features-audit',
-		write_root: writeRoot,
-		...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
-		...result,
-		...(applied_patches ? { applied_patches } : {}),
-		...(skipped_patches ? { skipped_patches } : {}),
-	})
-}
-
-function resolveDiffFiles(root, flags) {
-	const explicit = flags.get('diff-files')
-	if (explicit && typeof explicit === 'string') {
-		return explicit
-			.split(',')
-			.map((s) => s.trim())
-			.filter(Boolean)
-	}
-	const sinceRaw = flags.get('since')
-	const since =
-		typeof sinceRaw === 'string' && /^[A-Za-z0-9/_.-]+$/.test(sinceRaw) && !sinceRaw.startsWith('-')
-			? sinceRaw
-			: null
-	try {
-		const args = since ? ['diff', '--name-only', `${since}..HEAD`] : ['diff', 'HEAD', '--name-only']
-		const out = execFileSync('git', args, {
-			cwd: root,
-			encoding: 'utf-8',
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-		return out
-			.split('\n')
-			.map((s) => s.trim())
-			.filter(Boolean)
-	} catch {
-		// Not a git repo or HEAD doesn't exist — clean slate.
-		return []
-	}
-}
-
-function renderMarkdown(result, applied, skipped) {
-	const lines = ['### Features audit', '']
-	if (result.new_components.length === 0) {
-		lines.push('_No new feature-qualifying files in diff._')
-	} else {
-		lines.push('**New candidates:**')
-		for (const c of result.new_components) {
-			lines.push(`- \`${c.file}\` — kind: \`${c.kind}\`, area: \`${c.area}\``)
-		}
-	}
-	if (result.unregistered.length > 0) {
-		lines.push('', '**Unregistered:**')
-		for (const u of result.unregistered) {
-			lines.push(`- \`${u.file}\` (area: \`${u.area}\`)`)
-		}
-	}
-	if (applied && applied.length > 0) {
-		lines.push('', '**Applied patches:**')
-		for (const p of applied) {
-			lines.push(`- ${p.target} — ${p.applied ? p.reason : `FAILED: ${p.reason}`}`)
-		}
-	}
-	if (skipped && skipped.length > 0) {
-		lines.push('', '**Skipped patches (policy opt-out):**')
-		for (const s of skipped) {
-			lines.push(`- ${s.target} — policy: \`${s.policy ?? 'unmatched'}\``)
-		}
-	}
-	return lines.join('\n')
-}

package/src/cli/features/registry-audit.mjs

@@ -1,254 +0,0 @@
-/**
- * @internal
- * registry-audit.mjs — features-registry audit + stub emitter (C33).
- *
- * Shared module used by:
- *   - `apt-execute` post-step (`apt-tools features-audit --apply-stubs`) —
- *     auto-registers new UI/core/hook/IPC files the subtask added.
- *   - `apt-reviewer` Pass 6 (`apt-tools features-audit` without `--apply-stubs`)
- *     — reports anything the executor missed.
- *
- * Feature kinds (spec §D-4):
- *   - `ui-component`  — packages/ui/src/sections/** /*.tsx
- *   - `core-service`  — packages/core/src/{services,pipeline}/**\/*.ts
- *   - `hook`          — packages/ui/src/hooks/use-*.ts
- *   - `ipc-channel`   — apps/desktop/src/main/ipc-handlers/*.ts
- *
- * Non-matching paths → null, not included in the audit.
- */
-
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
-import { atomicWriteJson } from '../util/io.mjs'
-
-/**
- * Map a file path to a feature kind, or null if it doesn't qualify.
- */
-export function detectFeatureKind(filepath) {
-	if (!filepath || typeof filepath !== 'string') return null
-	const norm = filepath.replace(/\\/g, '/').replace(/^\.\//, '')
-	// Exclude test files up-front so they never match a feature kind.
-	if (/\.(test|spec)\.(ts|tsx)$/.test(norm)) return null
-	if (/\/__tests__\//.test(norm)) return null
-	// ui-component: packages/ui/src/sections/**/*.tsx
-	if (/^packages\/ui\/src\/sections\/.+\.tsx$/.test(norm)) return 'ui-component'
-	// core-service: packages/core/src/{services,pipeline}/**/*.ts
-	if (/^packages\/core\/src\/(services|pipeline)\/.+\.ts$/.test(norm)) return 'core-service'
-	// hook: packages/ui/src/hooks/use-*.ts (also use-*.tsx allowed for hook factories)
-	if (/^packages\/ui\/src\/hooks\/use-[A-Za-z0-9-]+\.tsx?$/.test(norm)) return 'hook'
-	// ipc-channel: apps/desktop/src/main/ipc-handlers/*.ts
-	if (/^apps\/desktop\/src\/main\/ipc-handlers\/[^/]+\.ts$/.test(norm)) return 'ipc-channel'
-	return null
-}
-
-/**
- * Infer the features-registry "area" that should own a given path. The area
- * is the leaf folder under `sections/`, or a kind-specific pseudo-area when
- * the file isn't under sections/.
- */
-export function inferArea(filepath) {
-	const norm = filepath.replace(/\\/g, '/').replace(/^\.\//, '')
-	const m = /^packages\/ui\/src\/sections\/([^/]+)\//.exec(norm)
-	if (m) return m[1]
-	if (/^packages\/core\/src\/pipeline\//.test(norm)) return 'pipeline'
-	if (/^packages\/core\/src\/services\//.test(norm)) return 'services'
-	if (/^packages\/ui\/src\/hooks\//.test(norm)) return 'hooks'
-	if (/^apps\/desktop\/src\/main\/ipc-handlers\//.test(norm)) return 'ipc'
-	return null
-}
-
-/**
- * Audit a set of diff files against the features registry.
- *
- * @param {object} opts
- * @param {string} opts.projectDir
- * @param {Array<string>} opts.diffFiles  — project-relative file paths
- *
- * @returns {{
- *   new_components: Array<{file, kind, area}>,
- *   unregistered: Array<{file, kind, area}>,
- *   stub_patches: Array<StubPatch>,
- * }}
- *
- * StubPatch shape:
- *   { target: string, area: string, add_components: string[], create_area?: boolean, kind: string }
- */
-export function auditFeatureRegistry({ projectDir, diffFiles }) {
-	const root = resolve(projectDir)
-	const featuresDir = join(root, '.aperant', 'features')
-	const existing = existsSync(featuresDir) ? readFeatureArea(featuresDir) : new Map()
-
-	const new_components = []
-	const unregistered = []
-	for (const rawFile of diffFiles || []) {
-		const file = String(rawFile).replace(/\\/g, '/').replace(/^\.\//, '')
-		const kind = detectFeatureKind(file)
-		if (!kind) continue
-		const area = inferArea(file)
-		if (!area) continue
-		const entry = { file, kind, area }
-		new_components.push(entry)
-		const areaData = existing.get(area)
-		const components = Array.isArray(areaData?.components) ? areaData.components : null
-		if (!components || !components.includes(file)) {
-			unregistered.push(entry)
-		}
-	}
-
-	// Group unregistered by area → one stub_patch per area.
-	const byArea = new Map()
-	for (const u of unregistered) {
-		if (!byArea.has(u.area)) byArea.set(u.area, [])
-		byArea.get(u.area).push(u)
-	}
-	const stub_patches = []
-	for (const [area, entries] of byArea) {
-		const target = `.aperant/features/${area}.json`
-		const existingAreaData = existing.get(area)
-		stub_patches.push({
-			target,
-			area,
-			add_components: entries.map((e) => e.file),
-			create_area: !existingAreaData,
-			kind: entries[0].kind, // representative kind for new-area stubs
-		})
-	}
-
-	return { new_components, unregistered, stub_patches }
-}
-
-/**
- * Read each `<area>.json` under `.aperant/features/`. Skips REGISTRY.md and
- * malformed files silently (best-effort — the audit should still run).
- *
- * @returns Map<area, { area, route?, components, p4_sub_features?, last_scanned?, kind? }>
- */
-function readFeatureArea(featuresDir) {
-	const out = new Map()
-	let names
-	try {
-		names = readdirSync(featuresDir)
-	} catch {
-		return out
-	}
-	for (const name of names) {
-		if (!name.endsWith('.json')) continue
-		try {
-			const data = JSON.parse(readFileSync(join(featuresDir, name), 'utf-8'))
-			const area = data?.area || basename(name, '.json')
-			out.set(area, data)
-		} catch {
-			// malformed area file — skip
-		}
-	}
-	return out
-}
-
-/**
- * Apply stub patches from `auditFeatureRegistry`. Creates new area files when
- * `create_area: true` and appends new components to existing area files
- * otherwise. Updates REGISTRY.md's total row so the summary reflects the
- * latest counts.
- *
- * @returns Array<{target, applied: boolean, reason?: string}>
- */
-export function applyStubPatches(projectDir, stubPatches) {
-	const root = resolve(projectDir)
-	const featuresDir = join(root, '.aperant', 'features')
-	mkdirSync(featuresDir, { recursive: true })
-	const applied = []
-
-	for (const patch of stubPatches) {
-		const absTarget = join(root, patch.target)
-		if (patch.create_area) {
-			const stub = {
-				area: patch.area,
-				route: null,
-				components: patch.add_components,
-				kind: patch.kind,
-				last_scanned: new Date().toISOString().slice(0, 10),
-				p4_sub_features: [],
-				auto_generated: true,
-			}
-			atomicWriteJson(absTarget, stub)
-			applied.push({ target: patch.target, applied: true, reason: 'created-new-area' })
-			continue
-		}
-		// Append to existing area.
-		try {
-			const data = JSON.parse(readFileSync(absTarget, 'utf-8'))
-			const existing = Array.isArray(data.components) ? data.components : []
-			const seen = new Set(existing)
-			let added = 0
-			for (const f of patch.add_components) {
-				if (!seen.has(f)) {
-					existing.push(f)
-					seen.add(f)
-					added += 1
-				}
-			}
-			data.components = existing
-			data.last_scanned = new Date().toISOString().slice(0, 10)
-			atomicWriteJson(absTarget, data)
-			applied.push({
-				target: patch.target,
-				applied: true,
-				reason: `appended ${added} component${added === 1 ? '' : 's'}`,
-			})
-		} catch (err) {
-			applied.push({ target: patch.target, applied: false, reason: err.message })
-		}
-	}
-
-	// Touch REGISTRY.md — rewrite the TOTAL row to reflect new counts.
-	try {
-		refreshRegistryTotals(featuresDir)
-	} catch {
-		// best-effort — a malformed REGISTRY.md shouldn't fail the whole audit.
-	}
-
-	return applied
-}
-
-/**
- * Best-effort REGISTRY.md refresher. Scans every `<area>.json`, computes total
- * components count, and rewrites the `| **TOTAL** | ...` row if it exists.
- *
- * Intentionally narrow — we do NOT touch individual area rows (which carry
- * manually curated metrics like "Wired %"). The spec says auto-update should
- * "re-compute counts"; we treat the TOTAL row as the safe proxy.
- */
-function refreshRegistryTotals(featuresDir) {
-	const regPath = join(featuresDir, 'REGISTRY.md')
-	if (!existsSync(regPath)) return
-	const text = readFileSync(regPath, 'utf-8')
-	const totalComponents = tallyAllComponents(featuresDir)
-	const lines = text.split(/\r?\n/)
-	let rewrote = false
-	for (let i = 0; i < lines.length; i++) {
-		if (/^\|\s*\*\*TOTAL\*\*\s*\|/.test(lines[i])) {
-			// Rewrite as a minimal diagnostic row — preserve the shape but update
-			// the leading count columns. We don't re-derive wired %.
-			lines[i] = `| **TOTAL** | | | **${totalComponents}** | | | | auto-refreshed |`
-			rewrote = true
-			break
-		}
-	}
-	if (rewrote) {
-		writeFileSync(regPath, lines.join('\n'))
-	}
-}
-
-function tallyAllComponents(featuresDir) {
-	let count = 0
-	for (const name of readdirSync(featuresDir)) {
-		if (!name.endsWith('.json')) continue
-		try {
-			const data = JSON.parse(readFileSync(join(featuresDir, name), 'utf-8'))
-			count += Array.isArray(data.components) ? data.components.length : 0
-		} catch {
-			/* ignore */
-		}
-	}
-	return count
-}