@ricky-stevens/context-guardian 2.1.0

package/test/integration.test.mjs

@@ -0,0 +1,582 @@
+/**
+ * Critical integration tests — verify actual data integrity, not just code paths.
+ * These tests protect against the scenarios that would lose or corrupt user context.
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { performCompaction } from "../lib/checkpoint.mjs";
+import { extractConversation, extractRecent } from "../lib/transcript.mjs";
+
+const HOOK_PATH = path.resolve("hooks/submit.mjs");
+
+let tmpDir, cwd, dataDir, transcriptPath;
+
+const HIGH_USAGE = {
+	input_tokens: 5000,
+	cache_creation_input_tokens: 0,
+	cache_read_input_tokens: 0,
+	output_tokens: 10,
+};
+
+function writeLine(obj) {
+	fs.appendFileSync(transcriptPath, `${JSON.stringify(obj)}\n`);
+}
+
+function makeUser(text) {
+	return { type: "user", message: { role: "user", content: text } };
+}
+
+function makeAssistant(text, usage) {
+	return {
+		type: "assistant",
+		message: {
+			role: "assistant",
+			model: "claude-sonnet-4-20250514",
+			content: [{ type: "text", text }],
+			usage: usage || undefined,
+		},
+	};
+}
+
+function runHook(input) {
+	const stdin = JSON.stringify({
+		session_id: "test-session-1234",
+		prompt: input.prompt ?? "",
+		transcript_path: input.transcript_path ?? transcriptPath,
+		cwd: input.cwd ?? cwd,
+		...input,
+	});
+	try {
+		const stdout = execFileSync("node", [HOOK_PATH], {
+			input: stdin,
+			encoding: "utf8",
+			timeout: 5000,
+			env: { ...process.env, CLAUDE_PLUGIN_DATA: dataDir },
+		});
+		return stdout ? JSON.parse(stdout) : null;
+	} catch (e) {
+		if (e.status === 0 && !e.stdout?.trim()) return null;
+		if (e.status === 0 && e.stdout?.trim()) return JSON.parse(e.stdout);
+		throw e;
+	}
+}
+
+beforeEach(() => {
+	tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cg-integ-"));
+	cwd = path.join(tmpDir, "project");
+	dataDir = path.join(tmpDir, "data");
+	fs.mkdirSync(cwd, { recursive: true });
+	fs.mkdirSync(dataDir, { recursive: true });
+	fs.mkdirSync(path.join(dataDir, "checkpoints"), { recursive: true });
+	transcriptPath = path.join(tmpDir, "transcript.jsonl");
+	fs.writeFileSync(
+		path.join(dataDir, "config.json"),
+		JSON.stringify({ threshold: 0.01, max_tokens: 200000 }),
+	);
+});
+
+afterEach(() => {
+	fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// =========================================================================
+// 1. Checkpoint content verification — the checkpoint must contain the
+//    actual conversation, not garbage or empty content
+// =========================================================================
+describe("checkpoint content integrity", () => {
+	it("smart compact checkpoint contains all user and assistant text", () => {
+		writeLine(makeUser("Please refactor the auth module"));
+		writeLine(
+			makeAssistant("I'll refactor the auth module for you.", HIGH_USAGE),
+		);
+		writeLine(makeUser("Now add unit tests for the refactored code"));
+		writeLine(
+			makeAssistant("Done, I've added comprehensive unit tests.", HIGH_USAGE),
+		);
+
+		process.env.CLAUDE_PLUGIN_DATA = dataDir;
+		const result = performCompaction({
+			mode: "smart",
+			transcriptPath,
+			sessionId: "test-session-1234",
+		});
+
+		assert.ok(result, "performCompaction should return a result");
+		assert.ok(result.checkpointPath, "Should have a checkpoint path");
+		const checkpoint = fs.readFileSync(result.checkpointPath, "utf8");
+
+		// Verify ALL user messages are present
+		assert.ok(
+			checkpoint.includes("refactor the auth module"),
+			"Missing user message 1",
+		);
+		assert.ok(checkpoint.includes("add unit tests"), "Missing user message 2");
+		// Verify ALL assistant messages are present
+		assert.ok(
+			checkpoint.includes("refactor the auth module for you"),
+			"Missing assistant message 1",
+		);
+		assert.ok(
+			checkpoint.includes("comprehensive unit tests"),
+			"Missing assistant message 2",
+		);
+		// Verify the checkpoint has the header
+		assert.ok(checkpoint.includes("# Context Checkpoint (Smart Compact)"));
+	});
+
+	it("keep recent checkpoint contains the correct last N messages", () => {
+		// Write 6 exchanges (12 messages)
+		for (let i = 0; i < 6; i++) {
+			writeLine(makeUser(`question number ${i}`));
+			writeLine(makeAssistant(`answer number ${i}`, HIGH_USAGE));
+		}
+
+		process.env.CLAUDE_PLUGIN_DATA = dataDir;
+		const result = performCompaction({
+			mode: "recent",
+			transcriptPath,
+			sessionId: "test-session-1234",
+		});
+
+		assert.ok(result, "performCompaction should return a result");
+		assert.ok(result.checkpointPath, "Should have a checkpoint path");
+		const checkpoint = fs.readFileSync(result.checkpointPath, "utf8");
+
+		// All 12 messages should be present (20 > 12)
+		for (let i = 0; i < 6; i++) {
+			assert.ok(
+				checkpoint.includes(`question number ${i}`),
+				`Missing question ${i}`,
+			);
+			assert.ok(
+				checkpoint.includes(`answer number ${i}`),
+				`Missing answer ${i}`,
+			);
+		}
+	});
+
+	it("smart compact replaces tool-only responses with placeholder and tracks files", () => {
+		writeLine(makeUser("read the file please"));
+		// Tool-only response (no text block)
+		writeLine({
+			type: "assistant",
+			message: {
+				role: "assistant",
+				model: "claude-sonnet-4-20250514",
+				content: [
+					{
+						type: "tool_use",
+						id: "t1",
+						name: "Read",
+						input: { path: "/foo.js" },
+					},
+				],
+				usage: HIGH_USAGE,
+			},
+		});
+		// Text response
+		writeLine(
+			makeAssistant(
+				"Here is the file content, the bug is on line 42.",
+				HIGH_USAGE,
+			),
+		);
+		writeLine(makeUser("fix line 42"));
+		writeLine(
+			makeAssistant("Fixed! The issue was a null pointer.", HIGH_USAGE),
+		);
+
+		process.env.CLAUDE_PLUGIN_DATA = dataDir;
+		const result = performCompaction({
+			mode: "smart",
+			transcriptPath,
+			sessionId: "test-session-1234",
+		});
+
+		assert.ok(result, "performCompaction should return a result");
+		assert.ok(result.checkpointPath, "Should have a checkpoint path");
+		const checkpoint = fs.readFileSync(result.checkpointPath, "utf8");
+
+		// Text messages preserved
+		assert.ok(checkpoint.includes("read the file please"));
+		assert.ok(checkpoint.includes("bug is on line 42"));
+		assert.ok(checkpoint.includes("fix line 42"));
+		assert.ok(checkpoint.includes("null pointer"));
+		// Tool-only response gets tool summary instead of placeholder
+		assert.ok(
+			checkpoint.includes("→ Read"),
+			"Should have tool summary for Read",
+		);
+		assert.ok(checkpoint.includes("/foo.js"), "Should reference the file path");
+	});
+});
+
+// =========================================================================
+// 2. Message ordering — messages must come out in the same order
+// =========================================================================
+describe("message ordering preservation", () => {
+	it("extractConversation preserves chronological order", () => {
+		for (let i = 1; i <= 5; i++) {
+			writeLine(makeUser(`step ${i} request`));
+			writeLine(makeAssistant(`step ${i} done`));
+		}
+
+		const result = extractConversation(transcriptPath);
+
+		// Every message found
+		for (let i = 1; i <= 5; i++) {
+			assert.ok(result.includes(`step ${i} request`), `Missing request ${i}`);
+			assert.ok(result.includes(`step ${i} done`), `Missing done ${i}`);
+		}
+
+		// Find positions of User: and Asst: tagged messages
+		// (skip the Session State header which may reference the last message)
+		const bodyStart = result.indexOf("---\n\n[");
+		assert.ok(bodyStart >= 0, "Should have message body after header");
+		const body = result.slice(bodyStart);
+		const positions = [];
+		for (let i = 1; i <= 5; i++) {
+			positions.push(body.indexOf(`step ${i} request`));
+			positions.push(body.indexOf(`step ${i} done`));
+		}
+
+		// Strictly ascending order within the body
+		for (let i = 1; i < positions.length; i++) {
+			assert.ok(positions[i] > positions[i - 1], `Message ${i} out of order`);
+		}
+	});
+
+	it("extractRecent preserves chronological order within window", () => {
+		for (let i = 1; i <= 10; i++) {
+			writeLine(makeUser(`msg ${i}`));
+			writeLine(makeAssistant(`reply ${i}`));
+		}
+
+		const result = extractRecent(transcriptPath, 6); // last 6 messages
+		// Search in message body after the Session State header
+		const bodyStart = result.indexOf("---\n\n[");
+		assert.ok(bodyStart >= 0, "Should have message body after header");
+		const body = result.slice(bodyStart);
+		const pos8 = body.indexOf("User: msg 8");
+		const pos9 = body.indexOf("User: msg 9");
+		const pos10 = body.indexOf("User: msg 10");
+		assert.ok(pos8 >= 0, "msg 8 should be present");
+		assert.ok(pos9 >= 0, "msg 9 should be present");
+		assert.ok(pos10 >= 0, "msg 10 should be present");
+		assert.ok(pos8 < pos9, "msg 8 should come before msg 9");
+		assert.ok(pos9 < pos10, "msg 9 should come before msg 10");
+	});
+});
+
+// =========================================================================
+// 3. Successive compaction — second compact must not duplicate first
+// =========================================================================
+describe("successive compaction integrity", () => {
+	it("second extractConversation uses last marker as boundary", () => {
+		// Simulate a restored checkpoint (first compaction result)
+		writeLine({
+			type: "user",
+			message: {
+				role: "user",
+				content:
+					"[SMART COMPACT — restored checkpoint]\n\nUser: original question\n\nAsst: original answer",
+			},
+		});
+		// New messages after restore
+		writeLine(makeUser("follow-up question"));
+		writeLine(makeAssistant("follow-up answer"));
+
+		const result = extractConversation(transcriptPath);
+
+		// Preamble should contain the first compaction's content
+		assert.ok(result.includes("[SMART COMPACT"));
+		assert.ok(result.includes("original question"));
+		// New messages should be present
+		assert.ok(result.includes("follow-up question"));
+		assert.ok(result.includes("follow-up answer"));
+
+		// "follow-up question" appears in the message body; it may also
+		// appear in the Session State header's "Goal:" line as a summary.
+		// The key invariant is that it appears exactly once as a User: message.
+		const userMatches = result.match(/User: follow-up question/g);
+		assert.equal(
+			userMatches.length,
+			1,
+			"follow-up question should appear exactly once as a User message",
+		);
+	});
+
+	it("markers from prior compactions are not included as user messages", () => {
+		writeLine({
+			type: "user",
+			message: {
+				role: "user",
+				content: "[KEEP RECENT — restored checkpoint]\n\nold stuff",
+			},
+		});
+		writeLine(makeUser("new stuff"));
+
+		const result = extractConversation(transcriptPath);
+		// The marker should be the preamble, not a User: entry
+		assert.ok(!result.includes("User: [KEEP RECENT"));
+		assert.ok(result.includes("User: new stuff"));
+	});
+});
+
+// =========================================================================
+// 4. State file accuracy — headroom and recommendation must be correct
+// =========================================================================
+describe("state file accuracy", () => {
+	it("headroom is mathematically correct", () => {
+		writeLine(makeUser("hello"));
+		writeLine(makeAssistant("hi", HIGH_USAGE)); // 5000 tokens
+
+		runHook({ prompt: "test" });
+
+		const sf = path.join(dataDir, "state-test-session-1234.json");
+		const state = JSON.parse(fs.readFileSync(sf, "utf8"));
+
+		// threshold=0.01, max_tokens=200000, current=5000
+		// headroom = max(0, round(200000 * 0.01 - 5000)) = max(0, round(2000 - 5000)) = 0
+		assert.equal(state.headroom, 0);
+		assert.equal(state.threshold, 0.01);
+	});
+
+	it("recommendation says 'at threshold' when above", () => {
+		writeLine(makeUser("hello"));
+		writeLine(makeAssistant("hi", HIGH_USAGE)); // 5000 tokens, well above 0.01 * 200K = 2000
+
+		runHook({ prompt: "test" });
+
+		const sf = path.join(dataDir, "state-test-session-1234.json");
+		const state = JSON.parse(fs.readFileSync(sf, "utf8"));
+		assert.ok(state.recommendation.includes("At threshold"));
+	});
+
+	it("recommendation says 'all clear' when well below threshold", () => {
+		// Use high threshold so low usage is below 50% of threshold
+		fs.writeFileSync(
+			path.join(dataDir, "config.json"),
+			JSON.stringify({ threshold: 0.9, max_tokens: 200000 }),
+		);
+		writeLine(makeUser("hello"));
+		writeLine(
+			makeAssistant("hi", {
+				input_tokens: 100,
+				cache_creation_input_tokens: 0,
+				cache_read_input_tokens: 0,
+				output_tokens: 5,
+			}),
+		);
+
+		runHook({ prompt: "test" });
+
+		const sf = path.join(dataDir, "state-test-session-1234.json");
+		const state = JSON.parse(fs.readFileSync(sf, "utf8"));
+		assert.ok(state.recommendation.includes("All clear"));
+	});
+
+	it("recommendation says 'approaching' when between 50-100% of threshold", () => {
+		// threshold=0.10, usage=15000 → pct=7.5% → 75% of threshold
+		fs.writeFileSync(
+			path.join(dataDir, "config.json"),
+			JSON.stringify({ threshold: 0.1, max_tokens: 200000 }),
+		);
+		writeLine(makeUser("hello"));
+		writeLine(
+			makeAssistant("hi", {
+				input_tokens: 15000,
+				cache_creation_input_tokens: 0,
+				cache_read_input_tokens: 0,
+				output_tokens: 50,
+			}),
+		);
+
+		runHook({ prompt: "test" });
+
+		const sf = path.join(dataDir, "state-test-session-1234.json");
+		const state = JSON.parse(fs.readFileSync(sf, "utf8"));
+		assert.ok(state.recommendation.includes("Approaching"));
+	});
+});
+
+// =========================================================================
+// 6. Empty/degenerate transcripts don't produce corrupt checkpoints
+// =========================================================================
+describe("degenerate transcript handling", () => {
+	it("transcript with only system messages produces no user/assistant content", () => {
+		writeLine({ type: "system", message: { content: "System prompt here" } });
+		writeLine({ type: "system", message: { content: "More system stuff" } });
+
+		const result = extractConversation(transcriptPath);
+		assert.ok(!result.includes("**User:**"));
+		assert.ok(!result.includes("**Assistant:**"));
+	});
+
+	it("transcript with only tool interactions produces header but no message body", () => {
+		writeLine(makeUser(""));
+		writeLine({
+			type: "assistant",
+			message: {
+				role: "assistant",
+				content: [
+					{ type: "tool_use", id: "t1", name: "Read", input: { path: "/a" } },
+					{ type: "tool_use", id: "t2", name: "Edit", input: { path: "/b" } },
+				],
+			},
+		});
+		writeLine(makeUser(""));
+		writeLine({
+			type: "assistant",
+			message: {
+				role: "assistant",
+				content: [
+					{ type: "tool_use", id: "t3", name: "Bash", input: { cmd: "ls" } },
+				],
+			},
+		});
+
+		const result = extractConversation(transcriptPath);
+		// Empty user messages are skipped; tool-only assistants without a user exchange are omitted
+		assert.ok(
+			result.startsWith("## Session State"),
+			"Should have state header",
+		);
+		assert.ok(
+			result.includes("Tool operations:"),
+			"Should track tool operations",
+		);
+		assert.ok(
+			result.includes("Files modified:"),
+			"Should track files modified",
+		);
+	});
+
+	it("mixed tool and text preserves text and tracks files", () => {
+		writeLine(makeUser("fix the bug"));
+		writeLine({
+			type: "assistant",
+			message: {
+				role: "assistant",
+				content: [
+					{ type: "text", text: "I'll fix that bug now." },
+					{
+						type: "tool_use",
+						id: "t1",
+						name: "Edit",
+						input: { path: "/bug.js" },
+					},
+					{ type: "text", text: "Done, the bug is fixed." },
+				],
+			},
+		});
+
+		const result = extractConversation(transcriptPath);
+		assert.ok(result.includes("fix the bug"));
+		assert.ok(result.includes("I'll fix that bug now."));
+		assert.ok(result.includes("Done, the bug is fixed."));
+		// File tracked in Session State header as "Files modified"
+		assert.ok(
+			result.includes("Files modified"),
+			"Should have Files modified in header",
+		);
+		assert.ok(result.includes("/bug.js"), "Should reference the edited file");
+		// Tool use produces a summary, not raw tool_use JSON
+		assert.ok(!result.includes('"type":"tool_use"'));
+	});
+});
+
+// =========================================================================
+// 7. Concurrent session isolation
+// =========================================================================
+describe("session isolation", () => {
+	it("different session IDs write to different state files", () => {
+		writeLine(makeUser("hello"));
+		writeLine(makeAssistant("hi", HIGH_USAGE));
+
+		runHook({ prompt: "test", session_id: "session-AAA" });
+		runHook({ prompt: "test", session_id: "session-BBB" });
+
+		const stateA = path.join(dataDir, "state-session-AAA.json");
+		const stateB = path.join(dataDir, "state-session-BBB.json");
+		assert.ok(fs.existsSync(stateA));
+		assert.ok(fs.existsSync(stateB));
+
+		const dataA = JSON.parse(fs.readFileSync(stateA, "utf8"));
+		const dataB = JSON.parse(fs.readFileSync(stateB, "utf8"));
+		assert.equal(dataA.session_id, "session-AAA");
+		assert.equal(dataB.session_id, "session-BBB");
+	});
+});
+
+// =========================================================================
+// capCheckpointContent and writeCompactionState — unit coverage
+// =========================================================================
+
+describe("capCheckpointContent", () => {
+	it("returns content unchanged when under limit", async () => {
+		const { capCheckpointContent } = await import("../lib/checkpoint.mjs");
+		const short = "Hello world";
+		assert.equal(capCheckpointContent(short, 200000), short);
+	});
+
+	it("trims content that exceeds the limit", async () => {
+		const { capCheckpointContent } = await import("../lib/checkpoint.mjs");
+		// maxTokens=100 → maxChars = max(50000, 300) = 50000
+		// Need content > 50000 chars
+		const big = "A".repeat(60000);
+		const result = capCheckpointContent(big, 100);
+		assert.ok(result.length < big.length);
+		assert.ok(result.includes("chars trimmed from middle"));
+		assert.ok(result.startsWith("AAAA"));
+		assert.ok(result.endsWith("AAAA"));
+	});
+
+	it("uses default maxTokens when not provided", async () => {
+		const { capCheckpointContent } = await import("../lib/checkpoint.mjs");
+		const content = "X".repeat(100);
+		assert.equal(capCheckpointContent(content), content);
+	});
+});
+
+describe("writeCompactionState", () => {
+	it("writes a state file with correct fields via performCompaction", () => {
+		process.env.CLAUDE_PLUGIN_DATA = dataDir;
+		writeLine(makeUser("test the state write"));
+		writeLine(makeAssistant("Done.", HIGH_USAGE));
+
+		const result = performCompaction({
+			mode: "smart",
+			transcriptPath,
+			sessionId: "test-wcs",
+		});
+		assert.ok(result, "Should produce a result");
+		assert.ok(result.stats.postTokens > 0, "Should have post-token count");
+		assert.ok(result.stats.saved >= 0, "Should compute savings");
+	});
+
+	it("performCompaction reads baseline_overhead from state file", () => {
+		process.env.CLAUDE_PLUGIN_DATA = dataDir;
+		// Write a state file with baseline_overhead before compacting
+		fs.writeFileSync(
+			path.join(dataDir, "state-test-bo.json"),
+			JSON.stringify({ baseline_overhead: 12000 }),
+		);
+		writeLine(makeUser("test baseline overhead"));
+		writeLine(makeAssistant("Done.", HIGH_USAGE));
+
+		const result = performCompaction({
+			mode: "smart",
+			transcriptPath,
+			sessionId: "test-bo",
+		});
+		assert.ok(result, "Should produce a result");
+		// The overhead should factor into post-token calculation
+		assert.ok(result.stats.postTokens > 0);
+	});
+});

package/test/logger.test.mjs

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import { describe, it } from "node:test";
+
+// logger.mjs imports LOG_DIR and LOG_FILE from paths.mjs which reads
+// CLAUDE_PLUGIN_DATA at import time. We can't easily redirect the log
+// file, so we test via the real log file location. The log function is
+// designed to never throw, so these tests verify behaviour + safety.
+
+// We import once and test the singleton behaviour.
+import { log } from "../lib/logger.mjs";
+import { LOG_DIR, LOG_FILE } from "../lib/paths.mjs";
+
+// ===========================================================================
+// log()
+// ===========================================================================
+
+describe("log", () => {
+	it("writes a line to the log file", () => {
+		const marker = `test-marker-${Date.now()}-${Math.random()}`;
+		log(marker);
+		const content = fs.readFileSync(LOG_FILE, "utf8");
+		assert.ok(content.includes(marker));
+	});
+
+	it("prepends an ISO timestamp", () => {
+		const marker = `ts-check-${Date.now()}`;
+		log(marker);
+		const lines = fs.readFileSync(LOG_FILE, "utf8").split("\n");
+		const line = lines.find((l) => l.includes(marker));
+		assert.ok(line, "log line should exist");
+		// Format: [2025-01-01T00:00:00.000Z] message
+		assert.match(line, /^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+	});
+
+	it("appends a newline after each message", () => {
+		const marker = `newline-check-${Date.now()}`;
+		log(marker);
+		const content = fs.readFileSync(LOG_FILE, "utf8");
+		assert.ok(content.includes(`${marker}\n`));
+	});
+
+	it("creates LOG_DIR if it does not exist", () => {
+		// LOG_DIR should exist after calling log (it's created lazily)
+		log("dir-check");
+		assert.ok(fs.existsSync(LOG_DIR));
+	});
+
+	it("does not throw on empty message", () => {
+		log("");
+	});
+
+	it("does not throw on null message", () => {
+		log(null);
+	});
+
+	it("does not throw on undefined message", () => {
+		log(undefined);
+	});
+
+	it("does not throw on object message", () => {
+		log({ key: "value" });
+	});
+
+	it("handles multiple rapid calls without error", () => {
+		for (let i = 0; i < 50; i++) {
+			log(`rapid-${i}`);
+		}
+	});
+});