Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

17.1 KB
Raw Blame
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import test from "node:test";
import { fileURLToPath } from "node:url";

const ROOT = path.resolve(fileURLToPath(new URL("../..", import.meta.url)));
const CANONICAL_DOCS = [
	"docs/dev-rules/environment-setup.md",
	"docs/dev-rules/desktop-development.md",
	"docs/dev-rules/mobile-development.md",
];
const CONTRIBUTING_DOCS = ["CONTRIBUTING.md", "CONTRIBUTING.en.md"];
const CHECKED_DOCS = [...CONTRIBUTING_DOCS, ...CANONICAL_DOCS];
const COMMAND_CHECKED_DOCS = [...CHECKED_DOCS, "apps/desktop/README.md"];
const WORKSPACES = new Map([
	["desktop", "apps/desktop/package.json"],
	["mobile", "apps/mobile/package.json"],
]);
const PNPM_BUILTINS = new Set(["install", "--version"]);

function readText(relativePath) {
	return fs.readFileSync(path.join(ROOT, relativePath), "utf8");
}

function readJson(relativePath) {
	return JSON.parse(readText(relativePath));
}

function readSupportedLocales(relativePath) {
	const declaration = readText(relativePath).match(/SUPPORTED_LOCALES\s*=\s*\[([^\]]*)\]/s)?.[1];
	const locales = declaration
		? [...declaration.matchAll(/["']([^"']+)["']/g)].map((match) => match[1])
		: [];
	assert.ok(locales.length, `${relativePath} must declare SUPPORTED_LOCALES`);
	return locales;
}

function workflowJob(workflow, jobId) {
	const lines = workflow.split(/\r?\n/);
	const start = lines.findIndex((line) => line === `  ${jobId}:`);
	if (start === -1) return undefined;
	const endOffset = lines
		.slice(start + 1)
		.findIndex((line) => /^  [a-zA-Z0-9_-]+:$/.test(line));
	const end = endOffset === -1 ? lines.length : start + 1 + endOffset;
	return lines.slice(start + 1, end).join("\n");
}

function shellLines(relativePath) {
	const markdown = readText(relativePath);
	return [...markdown.matchAll(/```(?:bash|sh)?\r?\n([\s\S]*?)```/g)]
		.flatMap((match) => match[1].split(/\r?\n/))
		.map((line) => line.trim())
		.filter((line) => line.startsWith("pnpm "));
}

function assertPnpmCommandExists(line, rootPackage) {
	const tokens = line.split(/\s+/);
	if (tokens[1] === "--filter") {
		const selector = tokens[2];
		const command = tokens[3];
		const workspaceManifest = WORKSPACES.get(selector);
		assert.ok(workspaceManifest, `unknown workspace selector in documented command: ${line}`);
		const workspacePackage = readJson(workspaceManifest);
		if (command === "exec") {
			const binary = tokens[4];
			assert.ok(
				workspacePackage.dependencies?.[binary] || workspacePackage.devDependencies?.[binary],
				`documented binary '${binary}' is not declared by ${workspaceManifest}: ${line}`,
			);
			return;
		}
		assert.ok(
			workspacePackage.scripts?.[command],
			`documented script '${command}' is missing from ${workspaceManifest}: ${line}`,
		);
		return;
	}

	const command = tokens[1];
	if (PNPM_BUILTINS.has(command)) return;
	assert.ok(rootPackage.scripts?.[command], `documented root script is missing: ${line}`);
}

/**
 * 去掉 fenced code block 与 inline code span,再抽链接。顺序不能反 —— fenced block
 * 内部含反引号,先剥 inline 会把围栏本身吃掉。
 *
 * 这样 `[x](y)` 这类**演示 markdown 语法**的写法不会被当成真链接(design-rules/DESIGN.md
 * 里有多处);而 [`foo.md`](./foo.md) 这种「链接文本本身是 inline code」的常见写法,剥完
 * 变成 [](./foo.md),目标仍在括号里,正则照常命中。
 */
function stripCodeSpans(text) {
	return (
		text
			// 围栏允许带缩进 —— 列表项里的围栏本就是缩进的(docs/design-rules/DESIGN.md
			// 与 docs/dev-rules/pi-remaining-work.md 各有一处)。只认行首 ``` 会漏掉它们,
			// 块内的示例链接就会被当成真链接。
			.replace(/^[ \t]*```[\s\S]*?^[ \t]*```/gm, "")
			// inline code 用「等长反引号串」配对,这样内容本身含反引号的写法也能整段剥掉
			// (docs/product-rules/task-and-conversation-naming.md 有 `` `${n} 个会话` ``)。
			// 刻意不跨行:落单的反引号不应该让后面整篇文档漏检。
			.replace(/(`+)(?:(?!\1)[^\n])*?\1/g, "")
	);
}

function localMarkdownLinks(relativePath) {
	return [...stripCodeSpans(readText(relativePath)).matchAll(/\[[^\]]*\]\(([^)]+)\)/g)]
		.map((match) => match[1].trim())
		.filter((target) => !/^(?:https?:|mailto:|#)/.test(target));
}

/**
 * 需要做内链体检的全部文档:根目录与模块 AGENTS + `docs/` 下所有 markdown(递归)。
 *
 * 覆盖面刻意做全 —— 悬空内链最容易出现在深层目录里:文档被删除时,引用它的索引
 * (如 `docs/legal/README.md`、`docs/README.md`)常常漏改。只体检 CHECKED_DOCS 那几篇
 * canonical 文档挡不住这类回归。
 */
function listLinkCheckedDocs() {
	// Include newly added, unstaged module rules without traversing node_modules,
	// runtime binaries or generated build trees. Git is already required by the runner.
	const agentDocs = execFileSync("git", [
		"ls-files", "-z", "--cached", "--others", "--exclude-standard", "--",
		"AGENTS.md", ":(glob)apps/**/AGENTS.md", ":(glob)packages/**/AGENTS.md",
	], { cwd: ROOT, encoding: "utf8" }).split("\0").filter((relativePath) =>
		relativePath && fs.existsSync(path.join(ROOT, relativePath)));
	const out = ["AGENTS.md", ...agentDocs, ...CONTRIBUTING_DOCS];
	const walk = (relativeDir) => {
		for (const entry of fs.readdirSync(path.join(ROOT, relativeDir), { withFileTypes: true })) {
			const relativePath = path.join(relativeDir, entry.name);
			if (entry.isDirectory()) walk(relativePath);
			else if (entry.name.endsWith(".md")) out.push(relativePath);
		}
	};
	walk("docs");
	return [...new Set(out)].sort();
}

test("developer docs only document pnpm commands that exist", () => {
	const rootPackage = readJson("package.json");
	for (const relativePath of COMMAND_CHECKED_DOCS) {
		for (const line of shellLines(relativePath)) {
			assertPnpmCommandExists(line, rootPackage);
		}
	}
});

test("developer docs do not duplicate canonical command lines", () => {
	const owners = new Map();
	for (const relativePath of CHECKED_DOCS) {
		for (const line of shellLines(relativePath)) {
			assert.equal(
				owners.get(line),
				undefined,
				`documented command is duplicated in ${owners.get(line)} and ${relativePath}: ${line}`,
			);
			owners.set(line, relativePath);
		}
	}
	for (const relativePath of CONTRIBUTING_DOCS) {
		assert.equal(shellLines(relativePath).length, 0, `${relativePath} must link to canonical command docs`);
	}
});

test("AGENTS and CONTRIBUTING route to the canonical developer docs", () => {
	const agents = readText("AGENTS.md");
	const contributingDocs = CONTRIBUTING_DOCS.map(readText);
	for (const relativePath of CANONICAL_DOCS) {
		assert.match(agents, new RegExp(relativePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
		for (const contributing of contributingDocs) {
			assert.match(contributing, new RegExp(relativePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
		}
	}
});

test("developer documentation links resolve", () => {
	for (const relativePath of listLinkCheckedDocs()) {
		const sourceDir = path.dirname(path.join(ROOT, relativePath));
		for (const target of localMarkdownLinks(relativePath)) {
			const fileTarget = decodeURIComponent(target.split("#", 1)[0]);
			assert.ok(
				fs.existsSync(path.resolve(sourceDir, fileTarget)),
				`broken local link in ${relativePath}: ${target}`,
			);
		}
	}
});

test("login-all-hifi embeds generated truth as a script-safe static literal", () => {
	const html = readText("docs/design-previews/login-all-hifi/index.html");
	const match = html.match(/<script id="qa-truth">const RAW = ([\s\S]*?)<\/script>/);
	assert.ok(match, "login-all-hifi must define RAW directly from its generated truth literal");
	assert.doesNotMatch(
		html,
		/document\.getElementById\(["']qa-truth["']\)\.textContent/,
		"generated truth must not re-enter HTML rendering through DOM text",
	);
	assert.deepEqual(JSON.parse(match[1]), readJson("docs/design-previews/login-all-hifi/truth.json"));
});

test("login QA preview countdowns match Desktop and Mobile product constants", () => {
	const desktopMs = Number(readText("apps/desktop/src/renderer/components/login/loginDesignTokens.ts")
		.match(/RESEND_COUNTDOWN_MS\s*=\s*([\d_]+)/)?.[1].replaceAll("_", ""));
	const mobileSeconds = Number(readText("apps/mobile/src/auth/loginSkinLayout.ts")
		.match(/RESEND_COUNTDOWN_SECONDS\s*=\s*([\d_]+)/)?.[1].replaceAll("_", ""));
	assert.ok(desktopMs > 0 && mobileSeconds > 0);
	assert.equal(desktopMs, mobileSeconds * 1000);
	for (const demo of ["login-flow-hifi", "login-all-hifi"]) {
		const dir = `docs/design-previews/${demo}`;
		const truth = readJson(`${dir}/truth.json`);
		const block = readText(`${dir}/index.html`).match(/<script id="qa-truth"[^>]*>([\s\S]*?)<\/script>/);
		assert.ok(block, `${demo} must embed truth`);
		assert.deepEqual(JSON.parse(block[1].replace(/^const RAW = /, "")), truth);
		assert.equal((truth.desk ?? truth).constants.resendCountdownMs.value, desktopMs, demo);
		if (truth.mobile) assert.equal(truth.mobile.constants.resendSeconds.value, mobileSeconds, demo);
	}
});

test("current locale-aware QA artifacts cover every supported locale", () => {
	const supportedLocales = readSupportedLocales("apps/desktop/src/shared/locale.ts");
	assert.deepEqual(
		readSupportedLocales("apps/mobile/src/i18n/locale.ts"),
		supportedLocales,
		"Desktop and Mobile must expose the same concrete locale set",
	);
	const expectedSet = [...supportedLocales].sort();
	const currentLoginDemos = [
		{
			dir: "docs/design-previews/login-flow-hifi",
			copyPaths: [["copy"]],
		},
		{
			dir: "docs/design-previews/login-all-hifi",
			copyPaths: [["desk", "copy"], ["mobile", "copy"]],
		},
		{
			dir: "docs/design-previews/login-deletion-bubble",
			copyPaths: [["desktop", "copy"], ["mobile", "copy"]],
		},
	];

	for (const { dir, copyPaths } of currentLoginDemos) {
		const spec = readJson(`${dir}/spec.json`);
		const truth = readJson(`${dir}/truth.json`);
		assert.deepEqual(spec.matrix.langs, supportedLocales, `${dir} matrix locale order drifted`);
		assert.deepEqual(
			truth.supportedLocales.map(({ value }) => value),
			supportedLocales,
			`${dir} embedded locale order drifted`,
		);
		assert.deepEqual(
			[...new Set(spec.verify.cases.map(({ prefs }) => prefs.lang))].sort(),
			expectedSet,
			`${dir} representative cases must exercise every supported locale`,
		);
		for (const copyPath of copyPaths) {
			const copy = copyPath.reduce((value, key) => value?.[key], truth);
			assert.deepEqual(
				Object.keys(copy ?? {}).sort(),
				expectedSet,
				`${dir} truth ${copyPath.join(".")} locale coverage drifted`,
			);
		}
	}

	const newMakerDir = "docs/design-previews/newmaker-quickstart-cards";
	const newMakerSpec = readJson(`${newMakerDir}/spec.json`);
	const newMakerTruth = readJson(`${newMakerDir}/truth.json`);
	assert.deepEqual(newMakerSpec.matrix.langs, supportedLocales, `${newMakerDir} matrix locale order drifted`);
	assert.deepEqual(
		newMakerTruth.supportedLocales.map(({ value }) => value),
		supportedLocales,
		`${newMakerDir} embedded locale order drifted`,
	);
	assert.deepEqual(
		[...new Set(newMakerSpec.verify.cases.map(({ prefs }) => prefs.lang))].sort(),
		expectedSet,
		`${newMakerDir} representative cases must exercise every supported locale`,
	);
	assert.deepEqual(
		Object.keys(newMakerTruth.section.titles).sort(),
		expectedSet,
		`${newMakerDir} section-title locale coverage drifted`,
	);
	for (const [index, card] of newMakerTruth.cards.entries()) {
		assert.deepEqual(
			Object.keys(card.labels).sort(),
			expectedSet,
			`${newMakerDir} card ${index} locale coverage drifted`,
		);
	}

	for (const dir of ["docs/design-previews/login-deletion-bubble", newMakerDir]) {
		const html = readText(`${dir}/index.html`);
		const embedded = html.match(
			/<script id="qa-truth" type="application\/json">([\s\S]*?)<\/script>/,
		)?.[1];
		assert.ok(embedded, `${dir} must embed generated truth`);
		assert.deepEqual(JSON.parse(embedded), readJson(`${dir}/truth.json`), `${dir} embedded truth drifted`);
	}
});

test("runtime versions and the docs contract are code-owned", () => {
	const rootPackage = readJson("package.json");
	assert.equal(rootPackage.engines.node, ">=22.12");
	assert.equal(rootPackage.engines.pnpm, ">=10.7 <11");
	assert.match(rootPackage.packageManager, /^pnpm@10\./);
	assert.match(rootPackage.scripts["test:runner"], /scripts\/__tests__\/dev-docs-contract\.test\.mjs/);
});

// A shard matrix is complete only when it lists every index 1..N and the
// runner splits by the same N; a missing index or mismatched count would
// silently drop part of the unit tier from the gate.
function assertCompleteShardMatrix(job) {
	const matrix = /^        shard: \[([\d, ]+)\]$/m.exec(job);
	assert.ok(matrix, "unit shard job must declare a numeric shard matrix");
	const indexes = matrix[1].split(",").map((value) => Number(value.trim()));
	const count = indexes.length;
	assert.ok(count >= 2, "unit shard job must split the tier across parallel jobs");
	assert.deepEqual(indexes, Array.from({ length: count }, (_, i) => i + 1));
	assert.match(job, new RegExp(`^      XDT_UNIT_TEST_SHARD: \\$\\{\\{ matrix\\.shard \\}\\}/${count}$`, "m"));
	assert.match(job, /^      fail-fast: false$/m);
}

test("client CI keeps the complete sharded unit gate on Windows", () => {
	const workflow = readText(".github/workflows/ci.yml");
	const shards = workflowJob(workflow, "windows-unit-shards");
	assert.ok(shards, "client CI must define Windows unit shards");
	assert.match(shards, /^    runs-on: windows-latest$/m);
	assertCompleteShardMatrix(shards);
	assert.match(shards, /^        run: pnpm run test:workspaces --tier unit$/m);
	assert.doesNotMatch(shards, /pnpm test:unit(?:\s|$)/);
	assert.doesNotMatch(shards, /pnpm test:runner/);

	// One-off Windows checks run once, in parallel, outside the shard critical path.
	const runnerChecks = workflowJob(workflow, "windows-runner-checks");
	assert.ok(runnerChecks, "client CI must run Windows runner self-tests once");
	assert.match(runnerChecks, /^    runs-on: windows-latest$/m);
	assert.doesNotMatch(runnerChecks, /^    needs:/m);
	assert.doesNotMatch(runnerChecks, /^    strategy:/m);
	assert.equal([...runnerChecks.matchAll(/^        run: pnpm test:runner$/gm)].length, 1);
	assert.match(runnerChecks, /botCanonicalSession\.test\.ts/);

	const gate = workflowJob(workflow, "windows-unit");
	assert.ok(gate, "client CI must preserve the stable Windows unit check");
	assert.match(gate, /^    name: Windows unit tests$/m);
	assert.match(gate, /^    if: \$\{\{ always\(\) \}\}$/m);
	assert.match(gate, /^      - windows-unit-shards$/m);
	assert.match(gate, /^      - windows-runner-checks$/m);
	assert.match(gate, /^          WINDOWS_UNIT_SHARDS_RESULT: \$\{\{ needs\.windows-unit-shards\.result \}\}$/m);
	assert.match(gate, /^          WINDOWS_RUNNER_CHECKS_RESULT: \$\{\{ needs\.windows-runner-checks\.result \}\}$/m);
	assert.match(gate, /^          test "\$WINDOWS_UNIT_SHARDS_RESULT" = "success"$/m);
	assert.match(gate, /^          test "\$WINDOWS_RUNNER_CHECKS_RESULT" = "success"$/m);
});

test("client CI runs Linux checks and complete unit shards in parallel behind stable verify", () => {
	const workflow = readText(".github/workflows/ci.yml");
	const checks = workflowJob(workflow, "verify-checks");
	assert.ok(checks, "client CI must define independent Linux verification checks");
	assert.doesNotMatch(checks, /^    needs:/m);
	assert.match(checks, /^        run: pnpm test:runner$/m);
	assert.match(
		checks,
		/^      - name: Run Desktop and Mobile source-contract guards\r?\n        run: pnpm test:guard$/m,
	);
	// engineering-conventions.md §3.2 performance budget is only binding while CI
	// blocks on the hygiene ratchet; without this step the baseline stops mattering.
	assert.match(checks, /^      - name: Check unit test hygiene\r?\n        run: pnpm check:test-hygiene$/m);
	assert.doesNotMatch(checks, /node scripts\/test-workspaces\.mjs --tier unit/);

	const shards = workflowJob(workflow, "linux-unit-shards");
	assert.ok(shards, "client CI must define Linux unit shards");
	assert.match(shards, /^    runs-on: ubuntu-latest$/m);
	assert.doesNotMatch(shards, /^    needs:/m);
	assertCompleteShardMatrix(shards);
	assert.match(shards, /^        run: pnpm run test:workspaces --tier unit$/m);
	assert.doesNotMatch(shards, /pnpm test:(?:unit|runner)/);
	assert.equal([...shards.matchAll(/--tier integration --workspace @cindy\/maker-pi-manager/g)].length, 1);
	assert.match(shards, /^      - name: Run Pi manager integration tests\r?\n        if: matrix\.shard == 1\r?\n        run: pnpm run test:workspaces --tier integration --workspace @cindy\/maker-pi-manager$/m);

	const gate = workflowJob(workflow, "verify");
	assert.ok(gate, "client CI must preserve the stable verify check");
	assert.match(gate, /^    name: verify$/m);
	assert.match(gate, /^    if: \$\{\{ always\(\) \}\}$/m);
	assert.match(gate, /^      - verify-checks$/m);
	assert.match(gate, /^      - linux-unit-shards$/m);
	assert.match(gate, /^          VERIFY_CHECKS_RESULT: \$\{\{ needs\.verify-checks\.result \}\}$/m);
	assert.match(gate, /^          LINUX_UNIT_SHARDS_RESULT: \$\{\{ needs\.linux-unit-shards\.result \}\}$/m);
	assert.match(gate, /^          test "\$VERIFY_CHECKS_RESULT" = "success"$/m);
	assert.match(gate, /^          test "\$LINUX_UNIT_SHARDS_RESULT" = "success"$/m);
});