Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

17.1 KB
Raw Blame
/**
 * Subprocess integration tests for validate-write.ts — skip rules,
 * frontmatter warnings, wikilink heuristic, robustness to bad input.
 */

import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { fileURLToPath } from "node:url";
import { dirname, join, resolve } from "node:path";
import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { runScript as spawnHook, rmTemp } from "./_helpers.ts";

const SCRIPT = resolve(
	dirname(fileURLToPath(import.meta.url)),
	"../validate-write.ts",
);

let TMP_DIR = "";

before(() => {
	TMP_DIR = mkdtempSync(join(tmpdir(), "validate-write-test-"));
});

after(() => {
	rmTemp(TMP_DIR);
});

// The hook skips files outside the vault root; fixtures live in the OS
// tmpdir, so route the subprocess's vault root there — scoped to the spawn
// via envOverrides rather than mutating this process's env.
const runScript = (stdin: string | object | null) =>
	spawnHook(SCRIPT, stdin, { CLAUDE_PROJECT_DIR: TMP_DIR });

function makeMd(content: string, name = "test.md"): string {
	const path = join(TMP_DIR, name);
	writeFileSync(path, content, { encoding: "utf-8" });
	return path;
}

function runOn(filePath: string) {
	return runScript({ tool_input: { file_path: filePath } });
}

// --- Skip rules ---
describe("validate-write — skip rules (silent exit, no stdout)", () => {
	test("skips non-markdown", () => {
		const { stdout, code } = runOn("/tmp/test.txt");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips README.md", () => {
		const { stdout, code } = runOn("/some/path/README.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips translated READMEs", () => {
		for (const lang of ["ja", "ko", "zh-CN"]) {
			const { stdout, code } = runOn(`/some/path/README.${lang}.md`);
			assert.equal(code, 0);
			assert.equal(stdout.trim(), "");
		}
	});
	test("skips CHANGELOG.md", () => {
		const { stdout, code } = runOn("/some/path/CHANGELOG.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips .claude/ dir", () => {
		const { stdout, code } = runOn("/vault/.claude/commands/foo.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips templates/", () => {
		const { stdout, code } = runOn("/vault/templates/Work Note.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips thinking/", () => {
		const { stdout, code } = runOn("/vault/thinking/draft.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
	test("skips Windows backslash path", () => {
		const { stdout, code } = runOn("C:\\vault\\.claude\\commands\\foo.md");
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
});

// --- Frontmatter validation ---
describe("validate-write — frontmatter validation", () => {
	test("missing frontmatter", () => {
		const path = makeMd("No frontmatter here\n" + "x".repeat(300), "a.md");
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		const data = JSON.parse(stdout) as {
			hookSpecificOutput: {
				hookEventName: string;
				additionalContext: string;
			};
		};
		assert.equal(data.hookSpecificOutput.hookEventName, "PostToolUse");
		assert.ok(
			data.hookSpecificOutput.additionalContext.includes(
				"Missing YAML frontmatter",
			),
		);
	});

	test("missing tags", () => {
		const path = makeMd(
			"---\ndate: 2026-04-05\ndescription: test\n---\n# Note\n[[Link]] " +
				"x".repeat(300),
			"b.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.ok(stdout.includes("Missing `tags`"));
	});

	test("missing description", () => {
		const path = makeMd(
			"---\ndate: 2026-04-05\ntags:\n  - test\n---\n# Note\n[[Link]] " +
				"x".repeat(300),
			"c.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.ok(stdout.includes("Missing `description`"));
	});

	test("missing date", () => {
		const path = makeMd(
			"---\ndescription: test\ntags:\n  - test\n---\n# Note\n[[Link]] " +
				"x".repeat(300),
			"d.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.ok(stdout.includes("Missing `date`"));
	});
});

// --- Wikilink validation ---
describe("validate-write — wikilink validation", () => {
	test("no wikilinks in long note", () => {
		const path = makeMd(
			"---\ndate: 2026-04-05\ndescription: test\ntags:\n  - test\n---\n# Note\n" +
				"x".repeat(300),
			"e.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.ok(stdout.includes("No [[wikilinks]]"));
	});

	test("short note without wikilink is OK", () => {
		const path = makeMd(
			"---\ndate: 2026-04-05\ndescription: test\ntags:\n  - test\n---\nShort note.",
			"f.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
});

// --- Valid note ---
describe("validate-write — valid note produces no warnings", () => {
	test("fully-formed note", () => {
		const path = makeMd(
			"---\ndate: 2026-04-05\ndescription: A valid test note\ntags:\n  - test\n---\n" +
				// Filler is its own paragraph: on the next line it would be a
				// hard-wrapped one (#247).
				"# Note\n\nSome content with [[a wikilink]] and more text.\n\n" +
				"x".repeat(300),
			"g.md",
		);
		const { stdout, code } = runOn(path);
		assert.equal(code, 0);
		assert.equal(stdout.trim(), "");
	});
});

// --- Performance ---
describe("validate-write — performance", () => {
	test("1MB note validates in under 500ms", () => {
		const path = join(TMP_DIR, "big.md");
		const header =
			"---\ndate: 2026-04-17\ndescription: large note\ntags:\n  - test\n---\n[[link]]\n";
		const body = "lorem ipsum ".repeat(90_000);
		writeFileSync(path, header + body);

		const start = performance.now();
		const { code } = runScript({ tool_input: { file_path: path } });
		const elapsed = performance.now() - start;

		assert.equal(code, 0);
		assert.ok(
			elapsed < 1500,
			`validate-write took ${elapsed.toFixed(1)}ms on ~1MB note (budget 1500ms; includes subprocess spawn)`,
		);
	});
});

// --- Type safety ---
describe("validate-write — robustness to bad input", () => {
	test("null tool_input", () => {
		const { code } = runScript({ tool_input: null });
		assert.equal(code, 0);
	});
	test("non-string file_path", () => {
		const { code } = runScript({ tool_input: { file_path: 123 } });
		assert.equal(code, 0);
	});
	test("invalid JSON", () => {
		const { code } = runScript("not json");
		assert.equal(code, 0);
	});
	test("nonexistent file", () => {
		const { code } = runOn("/nonexistent/path/note.md");
		assert.equal(code, 0);
	});
	test("empty object", () => {
		const { code } = runScript({});
		assert.equal(code, 0);
	});
	test("empty stdin", () => {
		// Regression guard: empty stdin must short-circuit AND keep stderr
		// clean. Without the `--disable-warning=ExperimentalWarning` flag
		// in _helpers.ts, Node's type-stripping warning would leak here.
		const { code, stdout, stderr } = runScript(null);
		assert.equal(code, 0);
		assert.equal(stdout, "");
		assert.equal(stderr, "");
	});
});

describe("phantom-edge policy result (#117)", () => {
	test("ticket-ID wikilinks emit the machine-readable finding next to the prose", () => {
		const path = makeMd(
			'---\ntags: [x]\ndescription: "d"\ndate: 2026-01-01\n---\n' +
				"[[Real Note]] and a phantom [[PROJ-1234]] edge.\n",
			"phantom.md",
		);
		const { stdout } = runOn(path);
		const parsed = JSON.parse(stdout) as {
			hookSpecificOutput: {
				additionalContext: string;
				policyResults?: Array<{ policy_id: string; classification: string }>;
			};
		};
		assert.match(parsed.hookSpecificOutput.additionalContext, /ticket-ID/);
		assert.ok(
			parsed.hookSpecificOutput.policyResults?.some(
				(r) =>
					r.policy_id === "phantom-edge" &&
					r.classification === "ticket-id-wikilink",
			),
		);
	});
});

describe("validate-write — required fields come from the manifest", () => {
	test("a work note missing `quarter` is flagged when the manifest requires it", () => {
		const vault = mkdtempSync(join(tmpdir(), "validate-write-manifest-"));
		try {
			mkdirSync(join(vault, "work", "active"), { recursive: true });
			writeFileSync(
				join(vault, "vault-manifest.json"),
				JSON.stringify({ frontmatter_required: { "work-note": ["status", "quarter"] } }),
			);
			const note = join(vault, "work", "active", "A.md");
			writeFileSync(note, "---\ndate: 2026-01-01\ndescription: d\ntags: [work-note]\nstatus: active\n---\nShort.");
			const { stdout, code } = spawnHook(SCRIPT, { tool_input: { file_path: note } }, { CLAUDE_PROJECT_DIR: vault });
			assert.equal(code, 0);
			assert.match(stdout, /Missing `quarter`/);
			assert.doesNotMatch(stdout, /Missing `status`/);
		} finally {
			rmTemp(vault);
		}
	});
});

describe("validate-write — under Gemini's AfterTool (#353)", () => {
	// Gemini's file tools are write_file and replace, and both take file_path
	// (gemini-cli tools/definitions/base-declarations.ts, as of 2026-10-13);
	// AfterTool reads hookSpecificOutput.additionalContext (hooks/types.ts).
	test("a write_file payload gets its warning back in an AfterTool envelope", () => {
		const path = makeMd("No frontmatter here\n" + "x".repeat(300), "gemini.md");
		const { stdout, code } = runScript({
			hook_event_name: "AfterTool",
			tool_name: "write_file",
			tool_input: { file_path: path, content: "" },
		});
		assert.equal(code, 0);
		const data = JSON.parse(stdout) as { hookSpecificOutput: { hookEventName: string; additionalContext: string } };
		assert.equal(data.hookSpecificOutput.hookEventName, "AfterTool");
		assert.match(data.hookSpecificOutput.additionalContext, /frontmatter/i);
	});
});

// With HOOK_DEBUG=1 the refresh trigger logs "refresh requested" before it
// branches, so whether a write asked for a refresh shows with or without qmd
// installed; a sentinel appears only where qmd resolves, and the leg without
// qmd failed on it. Each sentinel is touched first, so the request is
// debounced and no worker spawns.
const refreshEnv = (name: string): Record<string, string> => {
	const sentinel = join(TMP_DIR, `${name}.sentinel`);
	writeFileSync(sentinel, "");
	return { HOOK_DEBUG: "1", QMD_REFRESH_SENTINEL: sentinel };
};
const refreshed = (stderr: string) => stderr.includes("validate-write: refresh requested");

describe("validate-write — Codex apply_patch, whose payload names no file_path (#354)", () => {
	// openai/codex core/src/tools/handlers/apply_patch.rs: tool_input is
	// { command: <raw patch> }, and the request carries an absolute cwd
	// (hooks/src/events/post_tool_use.rs), as of 2026-10-13.
	const applyPatch = (patch: string, env: Record<string, string> = {}) =>
		spawnHook(
			SCRIPT,
			{ hook_event_name: "PostToolUse", tool_name: "apply_patch", cwd: TMP_DIR, tool_input: { command: patch } },
			{ CLAUDE_PROJECT_DIR: TMP_DIR, ...env },
		);
	const context = (stdout: string) =>
		(JSON.parse(stdout) as { hookSpecificOutput: { hookEventName: string; additionalContext: string } }).hookSpecificOutput;

	test("an added note without frontmatter gets its warning, relative to the payload's cwd", () => {
		makeMd("No frontmatter here\n" + "x".repeat(300), "codex-added.md");
		const { stdout, code } = applyPatch("*** Begin Patch\n*** Add File: codex-added.md\n+No frontmatter here\n*** End Patch\n");
		assert.equal(code, 0);
		const out = context(stdout);
		assert.equal(out.hookEventName, "PostToolUse");
		assert.match(out.additionalContext, /codex-added\.md/);
	});

	test("every note a patch writes is validated, in one envelope", () => {
		makeMd("No frontmatter one\n" + "x".repeat(300), "codex-one.md");
		makeMd("No frontmatter two\n" + "x".repeat(300), "codex-two.md");
		const { stdout } = applyPatch(
			"*** Begin Patch\n*** Add File: codex-one.md\n+a\n*** Update File: codex-two.md\n@@\n+b\n*** End Patch\n",
		);
		const out = context(stdout);
		assert.match(out.additionalContext, /Vault hygiene warnings for `codex-one\.md`/);
		assert.match(out.additionalContext, /Vault hygiene warnings for `codex-two\.md`/);
	});

	test("a misplaced memory file in a patch is flagged, with its policy result", () => {
		const { stdout } = applyPatch(
			"*** Begin Patch\n*** Add File: /Users/foo/.claude/projects/-Users-foo-dev-bar/memory/feedback_x.md\n+x\n*** End Patch\n",
		);
		const out = JSON.parse(stdout) as {
			hookSpecificOutput: { additionalContext: string; policyResults?: Array<{ policy_id: string }> };
		};
		assert.match(out.hookSpecificOutput.additionalContext, /Memory location violation/);
		assert.deepEqual(out.hookSpecificOutput.policyResults?.map((p) => p.policy_id), ["memory-location"]);
	});

	test("a patch that writes a vault note triggers the refresh (the control for the case below)", () => {
		makeMd("---\ndate: 2026-10-13\n---\n" + "x".repeat(300), "codex-refresh.md");
		const { stderr } = applyPatch("*** Begin Patch\n*** Add File: codex-refresh.md\n+x\n*** End Patch\n", refreshEnv("md"));
		assert.ok(refreshed(stderr), "the refresh was requested");
	});

	test("a patch touching only non-.md files warns nothing and triggers no refresh", () => {
		writeFileSync(join(TMP_DIR, "code.ts"), "export {};\n");
		const { stdout, stderr, code } = applyPatch("*** Begin Patch\n*** Add File: code.ts\n+export {};\n*** End Patch\n", refreshEnv("nomd"));
		assert.equal(code, 0);
		assert.equal(stdout, "");
		assert.equal(refreshed(stderr), false, "no refresh was requested");
	});

	test("a patch touching only a note outside the vault warns nothing, as a single-file write does", () => {
		const outside = mkdtempSync(join(tmpdir(), "validate-write-outside-"));
		try {
			const note = join(outside, "elsewhere.md");
			writeFileSync(note, "No frontmatter here\n" + "x".repeat(300));
			const { stdout, code } = applyPatch(`*** Begin Patch\n*** Add File: ${note}\n+x\n*** End Patch\n`);
			assert.equal(code, 0);
			assert.equal(stdout, "");
		} finally {
			rmTemp(outside);
		}
	});
});

describe("validate-write — apply_patch review follow-ups (#354)", () => {
	const applyPatch = (patch: string, env: Record<string, string> = {}) =>
		spawnHook(
			SCRIPT,
			{ hook_event_name: "PostToolUse", tool_name: "apply_patch", cwd: TMP_DIR, tool_input: { command: patch } },
			{ CLAUDE_PROJECT_DIR: TMP_DIR, ...env },
		);

	test("a patch that only deletes a note still refreshes the index, which would otherwise serve it", () => {
		const { stdout, stderr } = applyPatch("*** Begin Patch\n*** Delete File: gone.md\n*** End Patch\n", refreshEnv("delete"));
		assert.equal(stdout, "", "nothing to validate");
		assert.ok(refreshed(stderr), "the refresh was requested");
	});

	test("three new notes joining one cluster give its hint once, not once per note", () => {
		const active = join(TMP_DIR, "work", "active");
		mkdirSync(active, { recursive: true });
		const fm = "---\ndate: 2026-10-13\ndescription: d\ntags: [work-note]\nquarter: Q4-2026\n---\n\nSee [[Home]].\n" + "x".repeat(300);
		// A cluster needs a root of at least 4 notes, its token in no more than
		// half of them (lib/active-hygiene.ts): 3 Pelican notes beside 3 others.
		for (const n of ["Pelican Plan.md", "Pelican Notes.md", "Pelican Risks.md", "Zebra Budget.md", "Otter Hiring.md", "Falcon Launch.md"]) {
			writeFileSync(join(active, n), fm);
		}
		const { stdout } = applyPatch(
			"*** Begin Patch\n*** Add File: work/active/Pelican Plan.md\n+x\n*** Add File: work/active/Pelican Notes.md\n+x\n*** Add File: work/active/Pelican Risks.md\n+x\n*** End Patch\n",
		);
		const out = JSON.parse(stdout) as { hookSpecificOutput: { additionalContext: string; policyResults?: Array<{ policy_id: string }> } };
		assert.equal(out.hookSpecificOutput.additionalContext.split("loose sibling(s)").length - 1, 1, out.hookSpecificOutput.additionalContext);
		// The machine-readable results stay one per file: each names its own path.
		const clusterPaths = (out.hookSpecificOutput.policyResults as Array<{ policy_id: string; path: string }> | undefined)
			?.filter((p) => p.policy_id === "topic-cluster")
			.map((p) => p.path)
			.sort();
		assert.deepEqual(clusterPaths, ["work/active/Pelican Notes.md", "work/active/Pelican Plan.md", "work/active/Pelican Risks.md"]);
	});
});

describe("validate-write — the refresh covers only notes inside the vault (#366)", () => {
	const write = (filePath: string, env: Record<string, string>) =>
		spawnHook(SCRIPT, { tool_input: { file_path: filePath } }, { CLAUDE_PROJECT_DIR: TMP_DIR, ...env });

	test("a note written outside the vault requests no refresh", () => {
		const outside = mkdtempSync(join(tmpdir(), "validate-write-refresh-outside-"));
		try {
			const note = join(outside, "README.md");
			writeFileSync(note, "# Elsewhere\n");
			const { code, stderr } = write(note, refreshEnv("outside"));
			assert.equal(code, 0);
			assert.equal(refreshed(stderr), false, "a write the index can't see starts no worker");
		} finally {
			rmTemp(outside);
		}
	});

	test("an in-vault template, skipped by validation, still requests one (the control)", () => {
		mkdirSync(join(TMP_DIR, "templates"), { recursive: true });
		const note = join(TMP_DIR, "templates", "Refresh Control.md");
		writeFileSync(note, "# Template\n");
		const { code, stderr } = write(note, refreshEnv("template"));
		assert.equal(code, 0);
		assert.equal(refreshed(stderr), true);
	});
});