tdd-enforcer 0.3.2 → 0.3.4

package/engine/orchestrate.test.ts

@@ -0,0 +1,445 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { advancePhase, getStatusInfo, revertPhase } from "./orchestrate.js";
+import type { Config, Phase, PhaseState } from "./types.js";
+
+const CONFIG: Config = {
+	blockedInRed: ["tests/**/*.test.ts"],
+	blockedInGreen: ["src/**/*.ts"],
+	testCommands: ["npm test"],
+	timeoutSeconds: 30,
+};
+
+function enabledState(current: Phase): PhaseState {
+	return { enabled: true, current };
+}
+
+describe("advancePhase", () => {
+	let mockGetDisallowedChanges: ReturnType<typeof vi.fn>;
+	let mockCheckGate: ReturnType<typeof vi.fn>;
+	let mockNextPhase: ReturnType<typeof vi.fn>;
+	let mockSnapshot: ReturnType<typeof vi.fn>;
+	let mockSavePhaseState: ReturnType<typeof vi.fn>;
+	let mockTestRunner: ReturnType<typeof vi.fn>;
+
+	function makeDeps(overrides = {}) {
+		return {
+			getDisallowedChanges: mockGetDisallowedChanges,
+			checkGate: mockCheckGate,
+			nextPhase: mockNextPhase,
+			snapshot: mockSnapshot,
+			savePhaseState: mockSavePhaseState,
+			testRunner: mockTestRunner,
+			...overrides,
+		};
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockGetDisallowedChanges = vi.fn().mockReturnValue([]);
+		mockCheckGate = vi.fn().mockResolvedValue({ passed: true, message: "ok" });
+		mockNextPhase = vi
+			.fn()
+			.mockImplementation((p: string) =>
+				p === "red"
+					? "green"
+					: p === "green"
+						? "refactor"
+						: p === "refactor"
+							? "red"
+							: null,
+			);
+		mockSnapshot = vi.fn().mockReturnValue("hash123");
+		mockSavePhaseState = vi.fn();
+		mockTestRunner = vi.fn();
+	});
+
+	it("returns allowlist violation error with revert hint when files blocked", async () => {
+		mockGetDisallowedChanges.mockReturnValue(["src/violation.ts"]);
+		const result = await advancePhase(
+			"/test",
+			enabledState("red"),
+			CONFIG,
+			makeDeps(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.message).toBe(
+			"BLOCKED: files not allowed in RED phase:\n" +
+				"  - src/violation.ts" +
+				"\nRevert or remove them before proceeding.\n\nInspect with: cd .pi/tdd && git diff HEAD -- src/violation.ts",
+		);
+	});
+
+	it("returns allowlist violation for multiple blocked files", async () => {
+		mockGetDisallowedChanges.mockReturnValue(["src/a.ts", "src/b.ts"]);
+		const result = await advancePhase(
+			"/test",
+			enabledState("red"),
+			CONFIG,
+			makeDeps(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.message).toContain("src/a.ts");
+		expect(result.message).toContain("src/b.ts");
+		expect(result.message).toContain("cd .pi/tdd && git diff HEAD -- src/a.ts");
+	});
+
+	it("returns gate failure error when checkGate fails", async () => {
+		mockCheckGate.mockResolvedValue({
+			passed: false,
+			message: "Tests failed:\n  - npm test",
+		});
+		const result = await advancePhase(
+			"/test",
+			enabledState("green"),
+			CONFIG,
+			makeDeps(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.message).toBe("Tests failed:\n  - npm test");
+	});
+
+	it("passes testRunner to checkGate", () => {
+		advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockCheckGate).toHaveBeenCalledWith(
+			"red",
+			"green",
+			mockTestRunner,
+			CONFIG,
+		);
+	});
+
+	it("passes correct phase transition red→green", () => {
+		advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockCheckGate).toHaveBeenCalledWith(
+			"red",
+			"green",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+
+	it("passes correct phase transition green→refactor", () => {
+		advancePhase("/test", enabledState("green"), CONFIG, makeDeps());
+		expect(mockCheckGate).toHaveBeenCalledWith(
+			"green",
+			"refactor",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+
+	it("passes correct phase transition refactor→red", () => {
+		advancePhase("/test", enabledState("refactor"), CONFIG, makeDeps());
+		expect(mockCheckGate).toHaveBeenCalledWith(
+			"refactor",
+			"red",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+
+	it("calls snapshot with root and from phase on success", async () => {
+		await advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockSnapshot).toHaveBeenCalledWith("/test", "red");
+	});
+
+	it("calls savePhaseState with root and new state on success", async () => {
+		await advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "green",
+		});
+	});
+
+	it("returns ok true with newState on success", async () => {
+		const result = await advancePhase(
+			"/test",
+			enabledState("red"),
+			CONFIG,
+			makeDeps(),
+		);
+		expect(result.ok).toBe(true);
+		expect(result.message).toBe("");
+		expect(result.newState).toEqual({
+			enabled: true,
+			current: "green",
+		});
+	});
+
+	it("does not snapshot or save when allowlist check fails", async () => {
+		mockGetDisallowedChanges.mockReturnValue(["src/violation.ts"]);
+		await advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockSnapshot).not.toHaveBeenCalled();
+		expect(mockSavePhaseState).not.toHaveBeenCalled();
+	});
+
+	it("does not snapshot or save when gate check fails", async () => {
+		mockCheckGate.mockResolvedValue({
+			passed: false,
+			message: "fail",
+		});
+		await advancePhase("/test", enabledState("green"), CONFIG, makeDeps());
+		expect(mockSnapshot).not.toHaveBeenCalled();
+		expect(mockSavePhaseState).not.toHaveBeenCalled();
+	});
+
+	it("calls getDisallowedChanges with root, current phase, and config", () => {
+		advancePhase("/test", enabledState("red"), CONFIG, makeDeps());
+		expect(mockGetDisallowedChanges).toHaveBeenCalledWith(
+			"/test",
+			"red",
+			CONFIG,
+		);
+	});
+
+	it("uses nextPhase from deps if provided", () => {
+		const customNext = vi.fn().mockReturnValue("refactor");
+		advancePhase(
+			"/test",
+			enabledState("red"),
+			CONFIG,
+			makeDeps({ nextPhase: customNext }),
+		);
+		expect(customNext).toHaveBeenCalledWith("red");
+	});
+
+	it("falls back to real nextPhase when not provided in deps", () => {
+		advancePhase(
+			"/test",
+			enabledState("red"),
+			CONFIG,
+			makeDeps({ nextPhase: undefined }),
+		);
+		// Should use the real nextPhase function (red→green)
+		expect(mockCheckGate).toHaveBeenCalledWith(
+			"red",
+			"green",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+});
+
+describe("revertPhase", () => {
+	let mockHasParent: ReturnType<typeof vi.fn>;
+	let mockHeadMessage: ReturnType<typeof vi.fn>;
+	let mockResetHard: ReturnType<typeof vi.fn>;
+	let mockUndoLastCommit: ReturnType<typeof vi.fn>;
+	let mockSavePhaseState: ReturnType<typeof vi.fn>;
+
+	function makeDeps(overrides = {}) {
+		return {
+			hasParent: mockHasParent,
+			headMessage: mockHeadMessage,
+			resetHard: mockResetHard,
+			undoLastCommit: mockUndoLastCommit,
+			savePhaseState: mockSavePhaseState,
+			...overrides,
+		};
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockHasParent = vi.fn().mockReturnValue(true);
+		mockHeadMessage = vi.fn().mockReturnValue("tdd: red");
+		mockResetHard = vi.fn();
+		mockUndoLastCommit = vi.fn();
+		mockSavePhaseState = vi.fn();
+	});
+
+	it("returns error when no parent commit", async () => {
+		mockHasParent.mockReturnValue(false);
+		const result = await revertPhase(
+			"/test",
+			enabledState("green"),
+			makeDeps(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.message).toBe("No previous phase to revert to.");
+	});
+
+	it("returns error with tampering warning when HEAD is not a TDD snapshot", async () => {
+		mockHeadMessage.mockReturnValue("some random commit");
+		const result = await revertPhase(
+			"/test",
+			enabledState("green"),
+			makeDeps(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.message).toBe(
+			'HEAD commit "some random commit" is not a TDD snapshot. Cannot determine previous phase.\n' +
+				"The private git repo at .pi/tdd must not be manually modified. " +
+				"Tampering with it will cause TDD state corruption.",
+		);
+	});
+
+	it("resets hard and pops last commit on success", async () => {
+		const result = await revertPhase(
+			"/test",
+			enabledState("green"),
+			makeDeps(),
+		);
+		expect(result.ok).toBe(true);
+		expect(result.message).toBe("Reverted to RED.");
+		expect(result.newState?.current).toBe("red");
+		expect(mockResetHard).toHaveBeenCalledWith("/test");
+		expect(mockUndoLastCommit).toHaveBeenCalledWith("/test");
+	});
+
+	it("saves the reverted phase state", async () => {
+		await revertPhase("/test", enabledState("green"), makeDeps());
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "red",
+		});
+	});
+
+	it("determines previous phase from HEAD commit message", async () => {
+		mockHeadMessage.mockReturnValue("tdd: green");
+		const result = await revertPhase(
+			"/test",
+			enabledState("refactor"),
+			makeDeps(),
+		);
+		expect(result.ok).toBe(true);
+		expect(result.newState?.current).toBe("green");
+	});
+
+	it("determines refactor phase from HEAD commit message", async () => {
+		mockHeadMessage.mockReturnValue("tdd: refactor");
+		const result = await revertPhase("/test", enabledState("red"), makeDeps());
+		expect(result.ok).toBe(true);
+		expect(result.newState?.current).toBe("refactor");
+	});
+
+	it("preserves enabled state in new state", async () => {
+		const result = await revertPhase(
+			"/test",
+			{ enabled: false, current: "green" },
+			makeDeps(),
+		);
+		expect(result.ok).toBe(true);
+		expect(result.newState?.enabled).toBe(false);
+	});
+
+	it("calls deps from provided deps object", async () => {
+		const customHasParent = vi.fn().mockReturnValue(true);
+		const customHeadMessage = vi.fn().mockReturnValue("tdd: green");
+		const customResetHard = vi.fn();
+		const customUndoLastCommit = vi.fn();
+		const customSavePhaseState = vi.fn();
+
+		await revertPhase("/test", enabledState("refactor"), {
+			hasParent: customHasParent,
+			headMessage: customHeadMessage,
+			resetHard: customResetHard,
+			undoLastCommit: customUndoLastCommit,
+			savePhaseState: customSavePhaseState,
+		});
+
+		expect(customHasParent).toHaveBeenCalled();
+		expect(customHeadMessage).toHaveBeenCalled();
+		expect(customResetHard).toHaveBeenCalled();
+		expect(customUndoLastCommit).toHaveBeenCalled();
+		expect(customSavePhaseState).toHaveBeenCalled();
+	});
+
+	it("falls back to real functions when deps not provided", async () => {
+		// Should use real hasParent, headMessage, etc. from engine
+		const result = await revertPhase("/test", enabledState("green"));
+		// Real hasParent will fail because /test isn't a git repo
+		expect(result.ok).toBe(false);
+	});
+});
+
+describe("getStatusInfo", () => {
+	it("returns enabled status with RED phase", () => {
+		const info = getStatusInfo(
+			{ enabled: true, current: "red" },
+			{
+				blockedInRed: ["tests/**/*.test.ts"],
+				blockedInGreen: ["src/**/*.ts"],
+				testCommands: ["npm test"],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toBe(
+			"TDD enforcer enabled\n" +
+				"Current phase: RED\n" +
+				"Blocked in RED: tests/**/*.test.ts\n" +
+				"Blocked in GREEN: src/**/*.ts\n" +
+				"Test commands: npm test",
+		);
+	});
+
+	it("returns disabled status", () => {
+		const info = getStatusInfo(
+			{ enabled: false, current: "red" },
+			{
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toBe(
+			"TDD enforcer disabled\n" +
+				"Current phase: RED\n" +
+				"Blocked in RED: (none)\n" +
+				"Blocked in GREEN: (none)\n" +
+				"Test commands: (none)",
+		);
+	});
+
+	it("shows GREEN phase", () => {
+		const info = getStatusInfo(
+			{ enabled: true, current: "green" },
+			{
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toContain("GREEN");
+	});
+
+	it("shows REFACTOR phase", () => {
+		const info = getStatusInfo(
+			{ enabled: true, current: "refactor" },
+			{
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toContain("REFACTOR");
+	});
+
+	it("shows multiple blocked files for RED", () => {
+		const info = getStatusInfo(
+			{ enabled: true, current: "red" },
+			{
+				blockedInRed: ["*.ts", "*.json", "src/**"],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toContain("Blocked in RED: *.ts, *.json, src/**");
+	});
+
+	it("shows multiple test commands", () => {
+		const info = getStatusInfo(
+			{ enabled: true, current: "red" },
+			{
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: ["npx vitest run", "npm run lint"],
+				timeoutSeconds: 30,
+			},
+		);
+		expect(info).toContain("Test commands: npx vitest run, npm run lint");
+	});
+});

package/engine/orchestrate.ts

@@ -0,0 +1,159 @@
+import {
+	hasParent as realHasParent,
+	headMessage as realHeadMessage,
+	resetHard as realResetHard,
+	snapshot as realSnapshot,
+	undoLastCommit as realUndoLastCommit,
+} from "./git.js";
+import { savePhaseState as realSavePhaseState } from "./state.js";
+import {
+	checkGate as realCheckGate,
+	getDisallowedChanges as realGetDisallowedChanges,
+	nextPhase as realNextPhase,
+} from "./transition.js";
+import type { Config, Phase, PhaseState } from "./types.js";
+
+export interface AdvanceResult {
+	ok: boolean;
+	message: string;
+	newState?: PhaseState;
+}
+
+export interface AdvanceDeps {
+	nextPhase?: typeof realNextPhase;
+	getDisallowedChanges?: typeof realGetDisallowedChanges;
+	checkGate?: typeof realCheckGate;
+	snapshot?: typeof realSnapshot;
+	savePhaseState?: typeof realSavePhaseState;
+}
+
+export interface RevertDeps {
+	hasParent?: typeof realHasParent;
+	headMessage?: typeof realHeadMessage;
+	resetHard?: typeof realResetHard;
+	undoLastCommit?: typeof realUndoLastCommit;
+	savePhaseState?: typeof realSavePhaseState;
+}
+
+/**
+ * Advance to the next phase in the RED→GREEN→REFACTOR cycle.
+ * Runs allowlist check and transition gate before advancing.
+ * Returns a result object — caller (adapter) handles logging and formatting.
+ */
+export async function advancePhase(
+	root: string,
+	state: PhaseState,
+	config: Config,
+	deps: AdvanceDeps & {
+		testRunner: (
+			commands: string[],
+			timeoutSeconds: number,
+		) => Promise<{ passed: boolean; message: string }>;
+	},
+): Promise<AdvanceResult> {
+	const np = deps.nextPhase ?? realNextPhase;
+	const gdc = deps.getDisallowedChanges ?? realGetDisallowedChanges;
+	const cg = deps.checkGate ?? realCheckGate;
+	const snap = deps.snapshot ?? realSnapshot;
+	const sps = deps.savePhaseState ?? realSavePhaseState;
+
+	const from = state.current;
+	const to = np(from) as Phase;
+
+	// 1. Allowlist check
+	const violations = gdc(root, from, config);
+	if (violations.length > 0) {
+		return {
+			ok: false,
+			message:
+				`BLOCKED: files not allowed in ${from.toUpperCase()} phase:\n` +
+				violations.map((f) => `  - ${f}`).join("\n") +
+				`\nRevert or remove them before proceeding.\n\nInspect with: cd .pi/tdd && git diff HEAD -- ${violations[0]}`,
+		};
+	}
+
+	// 2. Gate check
+	const gate = await cg(from, to, deps.testRunner, config);
+	if (!gate.passed) {
+		return { ok: false, message: gate.message };
+	}
+
+	// 3. Snapshot
+	snap(root, from);
+
+	// 4. Save state
+	const newState: PhaseState = { ...state, current: to };
+	sps(root, newState);
+
+	return { ok: true, message: "", newState };
+}
+
+/**
+ * Revert to the previous phase using the private git snapshot log.
+ * Reads the phase label from HEAD commit and restores that state.
+ * Returns a result object — caller (adapter) handles logging and formatting.
+ */
+export async function revertPhase(
+	root: string,
+	state: PhaseState,
+	deps?: RevertDeps,
+): Promise<AdvanceResult> {
+	const hp = deps?.hasParent ?? realHasParent;
+	const hm = deps?.headMessage ?? realHeadMessage;
+	const rh = deps?.resetHard ?? realResetHard;
+	const ulc = deps?.undoLastCommit ?? realUndoLastCommit;
+	const sps = deps?.savePhaseState ?? realSavePhaseState;
+
+	if (!hp(root)) {
+		return { ok: false, message: "No previous phase to revert to." };
+	}
+
+	const headMsg = hm(root);
+	const phaseMatch = headMsg.match(/^tdd: (red|green|refactor)/);
+	if (!phaseMatch) {
+		return {
+			ok: false,
+			message:
+				`HEAD commit "${headMsg}" is not a TDD snapshot. Cannot determine previous phase.\n` +
+				"The private git repo at .pi/tdd must not be manually modified. " +
+				"Tampering with it will cause TDD state corruption.",
+		};
+	}
+
+	const prevPhase = phaseMatch[1] as Phase;
+
+	// Nuke uncommitted changes
+	rh(root);
+
+	// Pop last snapshot
+	ulc(root);
+
+	// Update phase
+	const newState: PhaseState = { ...state, current: prevPhase };
+	sps(root, newState);
+
+	return {
+		ok: true,
+		message: `Reverted to ${prevPhase.toUpperCase()}.`,
+		newState,
+	};
+}
+
+/**
+ * Get a human-readable status string from current state and config.
+ */
+export function getStatusInfo(state: PhaseState, config: Config): string {
+	const enabledStr = state.enabled ? "enabled" : "disabled";
+	const phaseStr = state.current.toUpperCase();
+	const redBlk = config.blockedInRed.join(", ") || "(none)";
+	const greenBlk = config.blockedInGreen.join(", ") || "(none)";
+	const commands = config.testCommands.join(", ") || "(none)";
+
+	return (
+		`TDD enforcer ${enabledStr}\n` +
+		`Current phase: ${phaseStr}\n` +
+		`Blocked in RED: ${redBlk}\n` +
+		`Blocked in GREEN: ${greenBlk}\n` +
+		`Test commands: ${commands}`
+	);
+}

package/engine/prompts.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { getNudgePrompt } from "./prompts.js";
+import type { Config } from "./types.js";
+
+const config: Config = {
+	blockedInRed: ["tests/**/*.test.ts"],
+	blockedInGreen: ["src/**/*.ts"],
+	testCommands: ["npm test"],
+	timeoutSeconds: 30,
+};
+
+const emptyConfig: Config = {
+	blockedInRed: [],
+	blockedInGreen: [],
+	testCommands: [],
+	timeoutSeconds: 30,
+};
+
+describe("getNudgePrompt", () => {
+	it("returns RED prompt with blocked files when phase is red", () => {
+		const result = getNudgePrompt("red", config);
+		expect(result).toBe(
+			"You are now in **RED** phase. Write failing tests.\n" +
+				"Blocked files: tests/**/*.test.ts\n" +
+				"All other files are free to modify. Call `next_tdd_phase` to proceed to GREEN.\n" +
+				"Think about what could go wrong and test for it — don't just verify the happy path, " +
+				"cover unhappy paths and edge cases too.\n" +
+				"Minimise the scope of each TDD cycle so reverting is cheap.",
+		);
+	});
+
+	it("returns GREEN prompt with blocked files when phase is green", () => {
+		const result = getNudgePrompt("green", config);
+		expect(result).toBe(
+			"You are now in **GREEN** phase. Implement features.\n" +
+				"Blocked files: src/**/*.ts\n" +
+				"All other files are free to modify. Call `next_tdd_phase` to proceed to REFACTOR.\n" +
+				"Write minimal code to make the failing tests pass — nothing more.\n" +
+				"If the RED phase tests were wrong, call `previous_tdd_phase` to go back and fix them.",
+		);
+	});
+
+	it("returns REFACTOR prompt when phase is refactor", () => {
+		const result = getNudgePrompt("refactor", config);
+		expect(result).toBe(
+			"You are now in **REFACTOR** phase. Both test and implementation files are free to modify. " +
+				"Refactor without changing behavior. Call `next_tdd_phase` to start a new RED cycle.",
+		);
+	});
+
+	it("returns empty string for unknown phase", () => {
+		const result = getNudgePrompt("blurple" as any, config);
+		expect(result).toBe("");
+	});
+
+	it("shows empty blocked files list when no blocks configured", () => {
+		const result = getNudgePrompt("red", emptyConfig);
+		expect(result).toContain("Blocked files: ");
+	});
+
+	it("shows multiple blocked files comma-separated in RED", () => {
+		const cfg: Config = {
+			...config,
+			blockedInRed: ["*.ts", "*.json", "src/**"],
+		};
+		const result = getNudgePrompt("red", cfg);
+		expect(result).toContain("Blocked files: *.ts, *.json, src/**");
+	});
+
+	it("shows multiple blocked files comma-separated in GREEN", () => {
+		const cfg: Config = {
+			...config,
+			blockedInGreen: ["*.test.ts", "*.spec.ts"],
+		};
+		const result = getNudgePrompt("green", cfg);
+		expect(result).toContain("Blocked files: *.test.ts, *.spec.ts");
+	});
+
+	it("includes RED keyword in red phase prompt", () => {
+		expect(getNudgePrompt("red", config)).toContain("RED");
+	});
+
+	it("includes GREEN keyword in green phase prompt", () => {
+		expect(getNudgePrompt("green", config)).toContain("GREEN");
+	});
+
+	it("includes REFACTOR keyword in refactor phase prompt", () => {
+		expect(getNudgePrompt("refactor", config)).toContain("REFACTOR");
+	});
+});

package/{adapters/pi → engine}/prompts.ts

@@ -1,4 +1,4 @@
-import type { Config, Phase } from "../../engine/types.js";
+import type { Config, Phase } from "./types.js";
 
 export function getNudgePrompt(phase: Phase, config: Config): string {
 	const redBlock = config.blockedInRed.join(", ");