@andares/pi-toolkits 0.9.8 → 0.11.0

package/src/features/init/coverage.ts

@@ -0,0 +1,163 @@
+/**
+ * init feature — coverage accounting.
+ *
+ * "Nothing was lost" is only checkable if the migration *declares* where every
+ * source section went. This module extracts source sections, looks for a
+ * destination that already contains the same heading or its opening paragraph,
+ * and renders the remaining rows as a table the model must fill in.
+ *
+ * What it proves: every source section has a destination or a written reason.
+ * What it cannot prove: that the destination kept the fact intact. That is why
+ * the default migration pass is conservative and why the diff is reviewed.
+ */
+import {
+	normalizeHeading,
+	normalizeProse,
+	sectionAnchor,
+	topSections,
+} from "./analyze.js";
+import type {
+	CoverageReport,
+	CoverageRow,
+	DocInfo,
+} from "./types.js";
+
+/** Destination docs searched for a section's heading or anchor. */
+export function buildCoverage(
+	sources: readonly DocInfo[],
+	targets: readonly DocInfo[],
+	mapping: ReadonlyMap<string, { destination: string; reason?: string }> = new Map(),
+): CoverageReport {
+	const rows: CoverageRow[] = [];
+	const targetText = targets.map((doc) => ({
+		rel: doc.rel,
+		headings: new Map(topSections(doc).map((heading) => [normalizeHeading(heading.text), heading])),
+		prose: normalizeProse(doc.text),
+	}));
+
+	for (const source of sources) {
+		for (const heading of topSections(source)) {
+			const key = normalizeHeading(heading.text);
+			if (key.length < 2) continue;
+			const anchor = normalizeProse(sectionAnchor(source, heading)).slice(0, 60);
+
+			let hit: string | undefined;
+			for (const target of targetText) {
+				if (target.headings.has(key)) {
+					hit = `${target.rel} §${target.headings.get(key)?.text ?? heading.text}`;
+					break;
+				}
+				if (anchor.length >= 8 && target.prose.includes(anchor)) {
+					hit = `${target.rel} (opening paragraph)`;
+					break;
+				}
+			}
+
+			const declared = mapping.get(`${source.rel}#${heading.text}`);
+			if (hit) {
+				rows.push({ source: source.rel, heading: heading.text, status: "hit", destination: hit });
+			} else if (declared) {
+				rows.push({
+					source: source.rel,
+					heading: heading.text,
+					status: "mapped",
+					destination: declared.destination,
+					reason: declared.reason,
+				});
+			} else {
+				rows.push({ source: source.rel, heading: heading.text, status: "open" });
+			}
+		}
+	}
+
+	return {
+		rows,
+		hit: rows.filter((row) => row.status === "hit").length,
+		mapped: rows.filter((row) => row.status === "mapped").length,
+		open: rows.filter((row) => row.status === "open").length,
+	};
+}
+
+const STATUS_LABEL = {
+	hit: "found",
+	mapped: "declared",
+	open: "OPEN",
+} as const;
+
+/** Render the table the model fills in (and the audit reads back). */
+export function renderCoverage(
+	report: CoverageReport,
+	context: { createdAt: string; sources: string[]; targets: string[] },
+): string {
+	const lines = [
+		"# Migration coverage",
+		"",
+		`- created: ${context.createdAt}`,
+		`- sources: ${context.sources.join(", ")}`,
+		`- targets: ${context.targets.join(", ")}`,
+		"",
+		"> Every section of every source must end up either found in a destination,",
+		"> declared with a destination, or declared as dropped with a reason. A row",
+		"> left `OPEN` blocks the migration from being called complete.",
+		"",
+		"| Source | Section | Status | Destination | Reason |",
+		"| --- | --- | --- | --- | --- |",
+	];
+	for (const row of report.rows) {
+		lines.push(
+			`| ${row.source} | ${escapeCell(row.heading)} | ${STATUS_LABEL[row.status]} | ${
+				row.destination ? escapeCell(row.destination) : ""
+			} | ${row.reason ? escapeCell(row.reason) : ""} |`,
+		);
+	}
+	lines.push(
+		"",
+		`Summary: ${report.hit} found, ${report.mapped} declared, ${report.open} open.`,
+		"",
+	);
+	return lines.join("\n");
+}
+
+function escapeCell(text: string): string {
+	return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+/**
+ * Read a filled coverage table back. Tolerant on purpose: the model edits this
+ * file, and a formatting wobble should not make the audit blind.
+ */
+export function parseCoverage(text: string): CoverageReport {
+	const rows: CoverageRow[] = [];
+	for (const line of text.split("\n")) {
+		if (!line.startsWith("|")) continue;
+		const cells = line
+			.split("|")
+			.slice(1, -1)
+			.map((cell) => cell.trim());
+		if (cells.length < 3) continue;
+		if (/^-+$/.test(cells[0]) || cells[0] === "Source") continue;
+		const status = cells[2].toLowerCase();
+		// A declared/found row without a destination is not accounted for: the
+		// table is the evidence, so an empty cell must not make it pass.
+		const hasDestination = Boolean(cells[3]);
+		const parsed =
+			(status === "found" || status === "hit") && hasDestination
+				? "hit"
+				: (status === "declared" || status === "mapped") && hasDestination
+					? "mapped"
+					: "open";
+		rows.push({
+			source: cells[0],
+			heading: cells[1],
+			status: parsed,
+			destination: cells[3] ? cells[3] : undefined,
+			reason: cells[4] ? cells[4] : undefined,
+		});
+	}
+	return {
+		rows,
+		hit: rows.filter((row) => row.status === "hit").length,
+		mapped: rows.filter((row) => row.status === "mapped").length,
+		open: rows.filter((row) => row.status === "open").length,
+	};
+}

package/src/features/init/detect.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import {
+	countBareRefs,
+	detect,
+	isBareRef,
+	parseHeadings,
+	parseState,
+	readDoc,
+	scanRefs,
+} from "./detect.js";
+import { project, remove } from "./test-helpers.js";
+
+describe("isBareRef", () => {
+	const text = "see memory/DESIGN.md, .agents/memory/X.md, my-memory/y, ~/.pi/agent/memory/z";
+
+	it("counts a reference that starts a path token", () => {
+		const index = text.indexOf("memory/");
+		expect(isBareRef(text, index, "memory/")).toBe(true);
+	});
+
+	it("ignores the framework path, compound names and other path tails", () => {
+		expect(countBareRefs(text, "memory/")).toBe(1);
+	});
+
+	it("counts references inside backticks and parentheses", () => {
+		expect(countBareRefs("(`memory/A.md`)", "memory/")).toBe(1);
+		expect(countBareRefs("(memory/A.md)", "memory/")).toBe(1);
+	});
+});
+
+describe("parseHeadings", () => {
+	it("skips headings inside fenced code blocks", () => {
+		const text = ["# Title", "```md", "## not a heading", "```", "## Real", "### Nested"].join("\n");
+		expect(parseHeadings(text).map((heading) => heading.text)).toEqual(["Title", "Real", "Nested"]);
+	});
+});
+
+describe("detect", () => {
+	it("reads context files, headings and language", () => {
+		const root = project({
+			"AGENTS.md": "# 项目指南\n\n这是给代理看的说明，内容以中文为主。\n\n## 定位\n\n相片管理软件。\n\n## 硬规则\n\n不要猜。\n",
+			"src/app.ts": "// 见 memory/ARCHITECTURE.md\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.language).toBe("zh");
+			expect(facts.context.agents?.headings.map((heading) => heading.text)).toContain("硬规则");
+			expect(facts.refs.hits).toBe(1);
+			expect(facts.isGit).toBe(false);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("detects legacy directories with real file counts", () => {
+		const root = project({
+			"memory/ARCHITECTURE.md": "# Architecture\n",
+			"memory/PLAN.md": "# Plan\n\n## Route\n\n- item\n",
+			"implementations/2026-01-01_a.md": "# a\n",
+			"implementations/2026-01-02_b.md": "# b\n",
+			"todos/2026-01-03-x.md": "# x\n",
+			"specs/a.md": "# a\n",
+			"AGENTS.md": "# demo\n\nSee `implementations/2026-01-01_a.md` and `memory/PLAN.md`.\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.deprecated.memory).toBe(true);
+			expect(facts.deprecated.implementations).toBe(true);
+			expect(facts.deprecatedFiles.implementations).toBe(2);
+			expect(facts.retiredTodos).toBe(true);
+			expect(facts.legacyMemory.map((doc) => doc.rel).sort()).toEqual([
+				"memory/ARCHITECTURE.md",
+				"memory/PLAN.md",
+			]);
+			expect(facts.refs.hits).toBe(2);
+			expect(facts.refs.byArea["(root)"]?.hits).toBe(2);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("detects a CLAUDE-only project and nested scope cards", () => {
+		const root = project({
+			"CLAUDE.md": "# rules\n",
+			"website/AGENTS.md": "# website\n\nScope card.\n",
+			".pi/AGENTS.md": "# pi\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.context.claude?.rel).toBe("CLAUDE.md");
+			expect(facts.context.agents).toBeUndefined();
+			expect(facts.context.piAgents?.rel).toBe(".pi/AGENTS.md");
+			expect(facts.nestedAgents.map((file) => file.rel)).toContain("website/AGENTS.md");
+			expect(facts.warnings.join("\n")).toMatch(/only CLAUDE\.md exists/);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("warns when AGENTS.override.md shadows the entry", () => {
+		const root = project({
+			"AGENTS.md": "# a\n",
+			"AGENTS.override.md": "# b\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.warnings.join("\n")).toMatch(/AGENTS\.override\.md/);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("round-trips the state file", () => {
+		const root = project({
+			".agents/framework/state.toml": [
+				"version = 1",
+				'tool = "1.2.3"',
+				'created = "2026-01-01T00:00:00+08:00"',
+				'updated = "2026-01-02T00:00:00+08:00"',
+				'profile = "core"',
+				'modules = ["design"]',
+				'lang = "zh"',
+				"",
+				"[[roots]]",
+				'label = "api"',
+				'path = "../api"',
+				'absolute = "/tmp/api"',
+				'role = "backend"',
+				'agents_md = "none"',
+				'source = "add-dir"',
+				"",
+			].join("\n"),
+			"AGENTS.md": "# 中文\n\n说明。\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.state?.version).toBe(1);
+			expect(facts.state?.tool).toBe("1.2.3");
+			expect(facts.state?.modules).toEqual(["design"]);
+			expect(facts.state?.roots[0]).toMatchObject({ label: "api", agentsMd: "none" });
+			expect(facts.language).toBe("zh");
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("flags a state version that is newer than the tool", () => {
+		const root = project({
+			".agents/framework/state.toml": 'version = 99\ntool = "x"\n',
+			"AGENTS.md": "# a\n",
+		});
+		try {
+			const facts = detect(root);
+			expect(facts.warnings.join("\n")).toMatch(/newer than this tool/);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("scans references but never inside the framework runtime directory", () => {
+		const root = project({
+			"src/a.ts": "// memory/X.md\n",
+			".agents/framework/reports/old.md": "memory/X.md\n",
+		});
+		try {
+			const scan = scanRefs(root);
+			expect(scan.paths).toEqual(["src/a.ts"]);
+			expect(scan.hits).toBe(1);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("reads a zero-byte root file and a document heading map", () => {
+		const root = project({ "crash-dump": "", "AGENTS.md": "# A\n\n## B\n" });
+		try {
+			writeFileSync(join(root, "crash-dump"), "", "utf8");
+			const facts = detect(root);
+			expect(facts.rootEmptyFiles).toContain("crash-dump");
+			expect(readDoc(root, "AGENTS.md")?.headings).toHaveLength(2);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("parses a deliberately partial state file", () => {
+		const state = parseState('version = 1\nroots = []\n');
+		expect(state.version).toBe(1);
+		expect(state.lang).toBe("en");
+		expect(state.profile).toBe("core");
+	});
+});
+
+
+describe("review regressions", () => {
+	it("treats ./ and ../ prefixes as references but not other path tails", () => {
+		const text = [
+			"`../memory/A.md`",
+			"`./memory/B.md`",
+			"`../../implementations/C.md`",
+			"~/.pi/agent/memory/D.md",
+			"/memory/E.md",
+		].join("\n");
+		expect(countBareRefs(text, "memory/")).toBe(2);
+		expect(countBareRefs(text, "implementations/")).toBe(1);
+	});
+
+	it("round-trips custom budgets through the state TOML keys", async () => {
+		const { stateToToml } = await import("./apply.js");
+		const parsed = parseState(
+			stateToToml({
+				version: 1,
+				tool: "test",
+				created: "2026-01-01T00:00:00+08:00",
+				updated: "2026-01-01T00:00:00+08:00",
+				profile: "core",
+				modules: [],
+				lang: "en",
+				budgets: {
+					agentsMdSoftChars: 9000,
+					agentsMdHardChars: 16000,
+					memoryFileChars: 50000,
+				},
+				roots: [],
+				managed: [],
+				migrations: [],
+			}),
+		);
+		expect(parsed.budgets).toEqual({
+			agentsMdSoftChars: 9000,
+			agentsMdHardChars: 16000,
+			memoryFileChars: 50000,
+		});
+	});
+});