@askjo/pi-reflect 1.0.0

package/tests/helpers-and-utils.test.ts

@@ -0,0 +1,174 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import {
+	resolvePath,
+	formatTimestamp,
+	escapeRegex,
+	truncateText,
+	projectNameFromDir,
+} from "../extensions/reflect.js";
+
+describe("resolvePath", () => {
+	it("expands ~ to HOME", () => {
+		const home = process.env.HOME!;
+		assert.equal(resolvePath("~/foo/bar"), `${home}/foo/bar`);
+	});
+
+	it("expands ~/", () => {
+		const home = process.env.HOME!;
+		assert.equal(resolvePath("~/.pi/agent"), `${home}/.pi/agent`);
+	});
+
+	it("resolves absolute paths as-is", () => {
+		assert.equal(resolvePath("/tmp/test"), "/tmp/test");
+	});
+
+	it("resolves relative paths against cwd", () => {
+		const result = resolvePath("foo/bar");
+		assert.ok(result.startsWith("/"));
+		assert.ok(result.endsWith("foo/bar"));
+	});
+});
+
+describe("formatTimestamp", () => {
+	it("returns a 15-char string", () => {
+		const ts = formatTimestamp();
+		assert.equal(ts.length, 15);
+	});
+
+	it("contains no colons or periods", () => {
+		const ts = formatTimestamp();
+		assert.ok(!ts.includes(":"));
+		assert.ok(!ts.includes("."));
+	});
+
+	it("starts with a year", () => {
+		const ts = formatTimestamp();
+		assert.match(ts, /^20\d{2}/);
+	});
+
+	it("contains underscore separator between date and time", () => {
+		const ts = formatTimestamp();
+		assert.ok(ts.includes("_"));
+	});
+});
+
+describe("escapeRegex", () => {
+	it("escapes dots", () => {
+		assert.equal(escapeRegex("a.b"), "a\\.b");
+	});
+
+	it("escapes parentheses", () => {
+		assert.equal(escapeRegex("(foo)"), "\\(foo\\)");
+	});
+
+	it("escapes brackets", () => {
+		assert.equal(escapeRegex("[a]"), "\\[a\\]");
+	});
+
+	it("escapes all special regex chars", () => {
+		const specials = ".*+?^${}()|[]\\";
+		const escaped = escapeRegex(specials);
+		// Every special char should be preceded by a backslash
+		for (const ch of specials) {
+			assert.ok(escaped.includes(`\\${ch}`), `Expected \\${ch} in ${escaped}`);
+		}
+	});
+
+	it("leaves normal text unchanged", () => {
+		assert.equal(escapeRegex("hello world"), "hello world");
+	});
+
+	it("handles empty string", () => {
+		assert.equal(escapeRegex(""), "");
+	});
+
+	it("escaped string works in RegExp constructor", () => {
+		const dangerous = "price is $100.00 (USD)";
+		const re = new RegExp(escapeRegex(dangerous));
+		assert.ok(re.test(dangerous));
+		assert.ok(!re.test("price is X100Y00 ZUSDW")); // shouldn't match with unescaped
+	});
+});
+
+describe("truncateText", () => {
+	it("returns null for null input", () => {
+		assert.equal(truncateText(null, 100), null);
+	});
+
+	it("returns text unchanged when under limit", () => {
+		assert.equal(truncateText("short", 100), "short");
+	});
+
+	it("returns text unchanged when exactly at limit", () => {
+		const text = "a".repeat(100);
+		assert.equal(truncateText(text, 100), text);
+	});
+
+	it("truncates text over limit", () => {
+		const text = "a".repeat(200);
+		const result = truncateText(text, 100)!;
+		assert.ok(result.startsWith("a".repeat(100)));
+		assert.ok(result.includes("[...truncated"));
+	});
+
+	it("includes omitted char count in truncation message", () => {
+		const text = "a".repeat(200);
+		const result = truncateText(text, 100)!;
+		assert.ok(result.includes("100 chars omitted"));
+	});
+
+	it("handles limit of 0", () => {
+		const result = truncateText("hello", 0)!;
+		assert.ok(result.includes("truncated"));
+		assert.ok(result.includes("5 chars omitted"));
+	});
+});
+
+describe("projectNameFromDir", () => {
+	const user = process.env.USER ?? "user";
+
+	it("strips macOS home prefix", () => {
+		// pi uses -- as path separator, single dashes are part of names
+		const dirname = `--Users-${user}-personal--myproject`;
+		assert.equal(projectNameFromDir(dirname), "personal/myproject");
+	});
+
+	it("strips Linux home prefix", () => {
+		const dirname = `--home-${user}-projects--myapp`;
+		assert.equal(projectNameFromDir(dirname), "projects/myapp");
+	});
+
+	it("preserves single dashes within path segments", () => {
+		const dirname = `--Users-${user}-my-project`;
+		// Single dash is part of the name, not a separator
+		assert.equal(projectNameFromDir(dirname), "my-project");
+	});
+
+	it("converts double dashes to slashes", () => {
+		const dirname = `--Users-${user}-a--b--c`;
+		assert.equal(projectNameFromDir(dirname), "a/b/c");
+	});
+
+	it("returns 'workspace' for empty result after stripping", () => {
+		const dirname = `--Users-${user}-`;
+		assert.equal(projectNameFromDir(dirname), "workspace");
+	});
+
+	it("returns dirname as-is when no prefix matches", () => {
+		const dirname = "some-random-dirname";
+		assert.equal(projectNameFromDir(dirname), "some-random-dirname");
+	});
+
+	it("handles nested project paths", () => {
+		const dirname = `--Users-${user}-personal--workspace--jo_bot`;
+		assert.equal(projectNameFromDir(dirname), "personal/workspace/jo_bot");
+	});
+
+	it("strips leading/trailing dashes and slashes from result", () => {
+		const dirname = `--Users-${user}---leading`;
+		const result = projectNameFromDir(dirname);
+		assert.ok(!result.startsWith("/"));
+		assert.ok(!result.startsWith("-"));
+	});
+});

package/tests/helpers.ts

@@ -0,0 +1,84 @@
+/**
+ * Test helpers — temp directories, fixture builders, mock sessions.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+export function makeTempDir(): string {
+	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-reflect-test-"));
+}
+
+export function cleanup(dir: string): void {
+	fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Build a JSONL session file from a simple exchange list.
+ * Each exchange is { role, text?, thinking? }.
+ */
+export function buildSessionJsonl(exchanges: Array<{ role: string; text?: string; thinking?: string }>): string {
+	const lines: string[] = [];
+	for (const ex of exchanges) {
+		const content: any[] = [];
+		if (ex.text) content.push({ type: "text", text: ex.text });
+		if (ex.thinking) content.push({ type: "thinking", thinking: ex.thinking });
+		lines.push(JSON.stringify({
+			type: "message",
+			message: { role: ex.role, content },
+		}));
+	}
+	return lines.join("\n") + "\n";
+}
+
+/**
+ * Create a fake sessions directory structure for collectTranscripts testing.
+ * Returns the sessions dir path.
+ *
+ *   sessionsDir/
+ *     --Users-<user>-project-name/
+ *       2026-02-12T03:00:00.000Z.jsonl
+ */
+export function createSessionFixture(
+	baseDir: string,
+	opts: {
+		projectDirName: string;
+		fileName: string;
+		exchanges: Array<{ role: string; text?: string; thinking?: string }>;
+	}[],
+): string {
+	const sessionsDir = path.join(baseDir, "sessions");
+	for (const opt of opts) {
+		const projectDir = path.join(sessionsDir, opt.projectDirName);
+		fs.mkdirSync(projectDir, { recursive: true });
+		const content = buildSessionJsonl(opt.exchanges);
+		fs.writeFileSync(path.join(projectDir, opt.fileName), content, "utf-8");
+	}
+	return sessionsDir;
+}
+
+/**
+ * A realistic AGENTS.md fixture for edit testing.
+ */
+export const SAMPLE_AGENTS_MD = `# Agent Guide
+
+## Communication Style
+- Maintain a professional demeanor
+- Avoid excessive enthusiasm or positivity
+
+## Read Before Acting
+- **ALWAYS read existing code before writing any code**. The #1 source of rework is acting before understanding.
+- **Check if functionality already exists**: Before implementing, search docs/code/examples first.
+- **Verify assumptions**: Before implementing, verify that variable names, function signatures, file paths actually exist.
+
+## Rules
+- **Execute first, explain minimally**: Do the work, then say what you did in 1-2 sentences.
+- **Don't ask clarifying questions when the directive is clear**: If the user gives a specific command, execute it.
+- **ANTI-OVER-ENGINEERING**: Implement EXACTLY what was asked for. Do NOT add "helpful" additional complexity.
+- **Keep code DRY**: NEVER duplicate logic.
+
+## Deployment
+- **NEVER push to main/master**: Pushing to main triggers production deployment.
+- **Deploy by pushing to main/master**: All deployments happen automatically via CI/CD.
+`;

package/tests/prompt-building.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { buildReflectionPrompt } from "../extensions/reflect.js";
+import { SAMPLE_AGENTS_MD } from "./helpers.js";
+
+describe("buildReflectionPrompt", () => {
+	it("includes the target file name", () => {
+		const prompt = buildReflectionPrompt("/path/to/AGENTS.md", SAMPLE_AGENTS_MD, "transcripts here");
+		assert.ok(prompt.includes("AGENTS.md"));
+	});
+
+	it("includes the target file content in <target_file> tags", () => {
+		const prompt = buildReflectionPrompt("/path/to/AGENTS.md", SAMPLE_AGENTS_MD, "transcripts");
+		assert.ok(prompt.includes("<target_file>"));
+		assert.ok(prompt.includes("</target_file>"));
+		assert.ok(prompt.includes("ANTI-OVER-ENGINEERING"));
+	});
+
+	it("includes transcripts in <transcripts> tags", () => {
+		const transcriptContent = "### Session: project [2026-02-12]\n\n**USER:** fix the bug\n";
+		const prompt = buildReflectionPrompt("/AGENTS.md", SAMPLE_AGENTS_MD, transcriptContent);
+		assert.ok(prompt.includes("<transcripts>"));
+		assert.ok(prompt.includes("</transcripts>"));
+		assert.ok(prompt.includes("fix the bug"));
+	});
+
+	it("instructs JSON-only output", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes("single JSON object"));
+		assert.ok(prompt.includes("No markdown, no explanation, no preamble"));
+	});
+
+	it("describes the strengthen edit type", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes('"strengthen"'));
+		assert.ok(prompt.includes("old_text"));
+		assert.ok(prompt.includes("character-for-character"));
+	});
+
+	it("describes the add edit type", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes('"add"'));
+		assert.ok(prompt.includes("after_text"));
+	});
+
+	it("mentions duplication prevention", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes("Never duplicate content"));
+	});
+
+	it("requires 2+ occurrences for new rules", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes("2+ occurrences"));
+	});
+
+	it("lists correction signals to look for", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes("bro"));
+		assert.ok(prompt.includes("wtf"));
+		assert.ok(prompt.includes("actually"));
+	});
+
+	it("warns about false positives", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes("no worries"));
+		assert.ok(prompt.includes("NOT corrections"));
+	});
+
+	it("uses basename, not full path in prompt", () => {
+		const prompt = buildReflectionPrompt("/very/long/path/to/RULES.md", "content", "transcripts");
+		assert.ok(prompt.includes("RULES.md"));
+		// Should not leak full filesystem path into the prompt
+		assert.ok(!prompt.includes("/very/long/path/to/RULES.md") || prompt.includes("Target file: RULES.md"));
+	});
+
+	it("includes expected JSON structure with all fields", () => {
+		const prompt = buildReflectionPrompt("/AGENTS.md", "content", "transcripts");
+		assert.ok(prompt.includes('"corrections_found"'));
+		assert.ok(prompt.includes('"sessions_with_corrections"'));
+		assert.ok(prompt.includes('"edits"'));
+		assert.ok(prompt.includes('"patterns_not_added"'));
+		assert.ok(prompt.includes('"summary"'));
+		assert.ok(prompt.includes('"reason"'));
+	});
+});

package/tests/realistic-edits.test.ts

@@ -0,0 +1,227 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { applyEdits, type AnalysisEdit } from "../extensions/reflect.js";
+import { SAMPLE_AGENTS_MD } from "./helpers.js";
+
+/**
+ * Tests that simulate realistic LLM-generated edit payloads against AGENTS.md.
+ * These are the exact patterns the extension encounters in production.
+ */
+
+describe("realistic LLM edit patterns", () => {
+	it("strengthens a rule with added emphasis and examples", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			section: "Read Before Acting",
+			old_text: "- **ALWAYS read existing code before writing any code**. The #1 source of rework is acting before understanding.",
+			new_text: '- **ALWAYS read existing code before writing any code**. The #1 source of rework is acting before understanding. If a file, doc, or plan is referenced — read it completely first. If a bug is reported — read the logs first.',
+			reason: "Agent repeatedly started implementing before reading existing code in 5 sessions",
+		}];
+		const { result, applied } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes("read the logs first"));
+		// Ensure no duplication of the original rule
+		const matches = result.match(/ALWAYS read existing code/g);
+		assert.equal(matches?.length, 1);
+	});
+
+	it("adds a new rule after an existing one", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			section: "Rules",
+			after_text: '- **ANTI-OVER-ENGINEERING**: Implement EXACTLY what was asked for. Do NOT add "helpful" additional complexity.',
+			new_text: '- **3-Attempt Rule**: If a fix fails 3 times, STOP. Try a fundamentally different approach or ask the user.',
+			reason: "Agent spiraled into 5+ attempts on the same approach in multiple sessions",
+		}];
+		const { result, applied } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes("3-Attempt Rule"));
+		// Verify ordering
+		const overEngIdx = result.indexOf("ANTI-OVER-ENGINEERING");
+		const newIdx = result.indexOf("3-Attempt Rule");
+		assert.ok(newIdx > overEngIdx);
+	});
+
+	it("handles a batch of mixed edits like a real LLM response", () => {
+		const edits: AnalysisEdit[] = [
+			{
+				type: "strengthen",
+				section: "Communication Style",
+				old_text: "- Avoid excessive enthusiasm or positivity",
+				new_text: '- Avoid excessive enthusiasm or positivity. When the user says "continue", that means get on with the work.',
+			},
+			{
+				type: "add",
+				section: "Read Before Acting",
+				after_text: "- **Verify assumptions**: Before implementing, verify that variable names, function signatures, file paths actually exist.",
+				new_text: "- **Read recent commits when debugging**: ALWAYS run `git log --oneline -10` before diagnosing issues. The user expects you to know what changed recently.",
+			},
+			{
+				type: "strengthen",
+				section: "Rules",
+				old_text: '- **Don\'t ask clarifying questions when the directive is clear**: If the user gives a specific command, execute it.',
+				new_text: '- **Don\'t ask clarifying questions when the directive is clear**: If the user gives a specific command, execute it. Don\'t present multiple-choice options when a single obvious action exists.',
+			},
+		];
+		const { result, applied, skipped } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 3);
+		assert.equal(skipped.length, 0);
+		assert.ok(result.includes("get on with the work"));
+		assert.ok(result.includes("git log --oneline -10"));
+		assert.ok(result.includes("multiple-choice options"));
+	});
+
+	it("rejects an edit that would create duplication (old_text > 50 chars)", () => {
+		// Simulates an LLM that accidentally repeats the old content in the replacement
+		// The duplication check only triggers when old_text > 50 chars
+		const longRule = "- **ALWAYS read existing code before writing any code**. The #1 source of rework is acting before understanding.";
+		const content = `## Rules\n\n${longRule}\n- **Other rule**: Do Y.\n`;
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: longRule,
+			new_text: longRule + " " + longRule, // obvious duplication
+		}];
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.equal(skipped.length, 1);
+		assert.ok(skipped[0].includes("Duplication"));
+	});
+
+	it("does not catch duplication when old_text < 50 chars (by design)", () => {
+		// Short old_text bypasses the duplication check — this is expected behavior
+		// because short snippets appearing twice is less likely to be a real problem
+		const content = "## Rules\n\n- **Rule A**: Do X.\n- **Rule B**: Do Y.\n";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule A**: Do X.",
+			new_text: "- **Rule A**: Do X. - **Rule A**: Do X.", // duplicated but short
+		}];
+		const { applied } = applyEdits(content, edits);
+		assert.equal(applied, 1); // passes because < 50 chars
+	});
+
+	it("handles real-world multiline bullet points", () => {
+		const content = [
+			"## Rules",
+			"- **NEVER push to main/master**: Pushing to main triggers production deployment.",
+			"  Only the user pushes. Agents may commit on branches, build artifacts.",
+			"- **Keep code DRY**: NEVER duplicate logic.",
+		].join("\n");
+
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **NEVER push to main/master**: Pushing to main triggers production deployment.\n  Only the user pushes. Agents may commit on branches, build artifacts.",
+			new_text: "- **NEVER push to main/master**: Pushing to main triggers production deployment.\n  Only the user pushes. Agents may commit on branches, build artifacts.\n  Even if the user's instructions seem to imply pushing, stop and confirm first.",
+		}];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		assert.ok(result.includes("stop and confirm first"));
+	});
+
+	it("preserves file structure when adding at the end of a section", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- **Deploy by pushing to main/master**: All deployments happen automatically via CI/CD.",
+			new_text: "- **Verify deployment completion**: After pushing, check logs to confirm the deploy succeeded.",
+		}];
+		const { result, applied } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied, 1);
+		// The new rule should be the last line (after Deployment section's last rule)
+		assert.ok(result.includes("Verify deployment completion"));
+	});
+
+	it("idempotent: running the same add edit twice fails on second run (dedup)", () => {
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+			new_text: "- **New rule**: Something new.",
+		}];
+
+		// First application
+		const { result: result1, applied: applied1 } = applyEdits(SAMPLE_AGENTS_MD, edits);
+		assert.equal(applied1, 1);
+
+		// Second application on the modified content
+		const { applied: applied2, skipped: skipped2 } = applyEdits(result1, edits);
+		assert.equal(applied2, 0);
+		assert.ok(skipped2[0].includes("already exists"));
+	});
+
+	it("handles edits with special markdown characters", () => {
+		const content = '- **Use `backticks` for code**: Always wrap code in backticks.\n- Other rule.';
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: '- **Use `backticks` for code**: Always wrap code in backticks.',
+			new_text: '- **Use `backticks` for code**: Always wrap code in backticks. Use triple backticks for multi-line blocks.',
+		}];
+		const { applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+	});
+
+	it("handles edits near markdown headers", () => {
+		const content = "## Section A\n\n- Rule under A.\n\n## Section B\n\n- Rule under B.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule under A.",
+			new_text: "- New rule under A.",
+		}];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		// Verify the new rule is between Section A and Section B
+		const ruleIdx = result.indexOf("New rule under A.");
+		const sectionBIdx = result.indexOf("## Section B");
+		assert.ok(ruleIdx < sectionBIdx);
+	});
+});
+
+describe("edge cases in edit content", () => {
+	it("handles old_text that is a substring of another rule", () => {
+		// Two rules where one is a prefix of the other
+		const content = "- **Rule**: Short.\n- **Rule**: Short. But also long with extra text.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule**: Short.",
+			new_text: "- **Rule**: Short, improved.",
+		}];
+		// "- **Rule**: Short." appears in both lines, so this should be ambiguous
+		const { applied, skipped } = applyEdits(content, edits);
+		assert.equal(applied, 0);
+		assert.ok(skipped[0].includes("Ambiguous"));
+	});
+
+	it("handles new_text with trailing newlines", () => {
+		const content = "- Rule A.\n- Rule B.";
+		const edits: AnalysisEdit[] = [{
+			type: "add",
+			after_text: "- Rule A.",
+			new_text: "- New rule.\n",
+		}];
+		const { result, applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+		// Should not create triple newlines
+		assert.ok(!result.includes("\n\n\n"));
+	});
+
+	it("handles unicode in edit text", () => {
+		const content = "- **Rule**: Use → arrows and • bullets.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: "- **Rule**: Use → arrows and • bullets.",
+			new_text: "- **Rule**: Use → arrows, • bullets, and — dashes.",
+		}];
+		const { applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+	});
+
+	it("handles very long edit text (>1000 chars)", () => {
+		const longRule = "- **Long rule**: " + "word ".repeat(200);
+		const content = longRule + "\n- Short rule.";
+		const edits: AnalysisEdit[] = [{
+			type: "strengthen",
+			old_text: longRule,
+			new_text: longRule + " Plus more words at the end.",
+		}];
+		const { applied } = applyEdits(content, edits);
+		assert.equal(applied, 1);
+	});
+});