magus-cli 7.3.1 → 7.4.0

package/src/__tests__/blind/c14-cli-row-label.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Blind tests — contract C14 (requirement R9.6).
+ *
+ * Written from requirements.md and architecture.md only.
+ *
+ * A CLI Tools row in state `unknown` shows a short label chosen by its
+ * reason: at most 24 terminal cells, never a filesystem path. The long note
+ * (today "on PATH at /Users/…", always cut off) belongs to the detail pane's
+ * "Why" line, not to the row.
+ *
+ * Pure: rows are built by hand to the CliToolRow contract. No IO.
+ */
+import { describe, expect, test } from "bun:test";
+import { type CliTool, cliTools } from "../../data/cli-tools.js";
+import type { ToolStatus } from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+import {
+	type CliToolRow,
+	cliToolStatusText,
+} from "../../ui/adapters/cliToolsAdapter.js";
+
+const MAX_CELLS = 24;
+
+const LONG_PATH_NOTE =
+	"on PATH at /Users/someone/.nvm/versions/node/v24/lib/node_modules/x/run.js, which is not the copy npm manages (npm root -g is /Users/someone/.local/lib/node_modules)";
+const OTHER_NOTE =
+	"a second copy was found at /opt/homebrew/lib/node_modules/x/bin/x.js and another under ~/.bun/install/global/node_modules/x";
+
+// ── terminal cell width, independent of the code under test ────────────────
+
+/** BMP code points that terminals draw two cells wide as emoji. */
+const WIDE_BMP_EMOJI = new Set([
+	0x231a, 0x231b, 0x23e9, 0x23ea, 0x23eb, 0x23ec, 0x23f0, 0x23f3, 0x25fd,
+	0x25fe, 0x2614, 0x2615, 0x267f, 0x2693, 0x26a1, 0x26aa, 0x26ab, 0x26bd,
+	0x26be, 0x26c4, 0x26c5, 0x26ce, 0x26d4, 0x26ea, 0x26f2, 0x26f3, 0x26f5,
+	0x26fa, 0x26fd, 0x2705, 0x270a, 0x270b, 0x2728, 0x274c, 0x274e, 0x2753,
+	0x2754, 0x2755, 0x2757, 0x2795, 0x2796, 0x2797, 0x27b0, 0x27bf, 0x2b1b,
+	0x2b1c, 0x2b50, 0x2b55,
+]);
+
+function isWide(cp: number): boolean {
+	return (
+		(cp >= 0x1100 && cp <= 0x115f) ||
+		(cp >= 0x2648 && cp <= 0x2653) ||
+		(cp >= 0x2e80 && cp <= 0x303e) ||
+		(cp >= 0x3041 && cp <= 0x33ff) ||
+		(cp >= 0x3400 && cp <= 0x4dbf) ||
+		(cp >= 0x4e00 && cp <= 0x9fff) ||
+		(cp >= 0xa000 && cp <= 0xa4cf) ||
+		(cp >= 0xac00 && cp <= 0xd7a3) ||
+		(cp >= 0xf900 && cp <= 0xfaff) ||
+		(cp >= 0xfe30 && cp <= 0xfe4f) ||
+		(cp >= 0xff00 && cp <= 0xff60) ||
+		(cp >= 0xffe0 && cp <= 0xffe6) ||
+		(cp >= 0x1f300 && cp <= 0x1f64f) ||
+		(cp >= 0x1f900 && cp <= 0x1f9ff) ||
+		(cp >= 0x1f680 && cp <= 0x1f6ff) ||
+		(cp >= 0x1fa70 && cp <= 0x1faff) ||
+		(cp >= 0x20000 && cp <= 0x3fffd) ||
+		WIDE_BMP_EMOJI.has(cp)
+	);
+}
+
+function isZeroWidth(cp: number): boolean {
+	return (
+		(cp >= 0x0300 && cp <= 0x036f) ||
+		(cp >= 0x200b && cp <= 0x200f) ||
+		(cp >= 0xfe00 && cp <= 0xfe0e) ||
+		cp === 0x2060
+	);
+}
+
+/** An ANSI CSI sequence (ESC [ … letter); built so no control byte sits in source. */
+const ANSI_CSI = new RegExp(
+	`${String.fromCharCode(27)}\\[[0-9;?]*[A-Za-z]`,
+	"g",
+);
+
+/** Terminal cells: wide characters count 2, combining marks 0, ANSI 0. */
+function cells(text: string): number {
+	const plain = text.replace(ANSI_CSI, "");
+	const cps = Array.from(plain, (ch) => ch.codePointAt(0) ?? 0);
+	let width = 0;
+	for (let i = 0; i < cps.length; i++) {
+		const cp = cps[i] as number;
+		if (cp === 0xfe0f) continue; // counted with its base, below
+		if (isZeroWidth(cp)) continue;
+		// A narrow base with emoji presentation (U+FE0F) is drawn two wide.
+		width += isWide(cp) || cps[i + 1] === 0xfe0f ? 2 : 1;
+	}
+	return width;
+}
+
+describe("C14 — the test's own cell counter", () => {
+	test("R9.6 control: ASCII counts 1, CJK and emoji count 2", () => {
+		expect(cells("abc")).toBe(3);
+		expect(cells("路径")).toBe(4);
+		expect(cells("⚠️")).toBe(2);
+		expect(cells("✅ ok")).toBe(5);
+	});
+});
+
+// ── rows ────────────────────────────────────────────────────────────────────
+
+const TOOL: CliTool = (cliTools.find((t) => t.name === "crush") ??
+	cliTools[0]) as CliTool;
+
+const SPEC: BinRequirement = {
+	name: TOOL.name,
+	via: "npm",
+	package: "@example/x",
+};
+
+type UnknownReason = Exclude<
+	ToolStatus["reason"],
+	"absent" | "up-to-date" | "behind" | "at-pin" | "behind-pin"
+>;
+
+/** Every reason that can put a row in `unknown`, with realistic versions. */
+const UNKNOWN: Record<
+	UnknownReason,
+	Pick<ToolStatus, "installed" | "latest" | "target"> & { pin?: string }
+> = {
+	"version-unreadable": { installed: null, latest: "2.0.0", target: null },
+	unorderable: {
+		installed: "nightly-2026-09-01",
+		latest: "2.0.0",
+		target: null,
+	},
+	"ahead-of-pin": {
+		installed: "2.1.0",
+		latest: "2.1.0",
+		target: null,
+		pin: "2.0.0",
+	},
+	"not-managed": { installed: "1.2.3", latest: "2.0.0", target: null },
+	"held-back": {
+		installed: "1.2.3",
+		latest: "2.0.0",
+		target: null,
+		pin: "1.2.3",
+	},
+	"pin-not-installable": {
+		installed: "1.2.3",
+		latest: "2.0.0",
+		target: null,
+		pin: "9.9.9",
+	},
+	"latest-unavailable": { installed: "1.2.3", latest: null, target: null },
+	"not-probed": { installed: null, latest: null, target: null },
+};
+
+function row(status: ToolStatus): CliToolRow {
+	return {
+		tool: TOOL,
+		spec: SPEC,
+		checking: false,
+		status,
+		installCommand: { cmd: "npm", args: ["install", "-g", "@example/x"] },
+	};
+}
+
+function unknownRow(reason: UnknownReason, note: string | undefined) {
+	const fields = UNKNOWN[reason];
+	const status: ToolStatus = {
+		name: TOOL.name,
+		state: "unknown",
+		reason,
+		installed: fields.installed,
+		latest: fields.latest,
+		target: fields.target,
+		...(fields.pin ? { pin: fields.pin } : {}),
+		...(note !== undefined ? { note } : {}),
+	};
+	return row(status);
+}
+
+const REASONS = Object.keys(UNKNOWN) as UnknownReason[];
+
+describe("C14 — cliToolStatusText on an unknown row", () => {
+	test("R9.6 control: the test covers all eight unknown-capable reasons", () => {
+		expect([...REASONS].sort()).toEqual(
+			[
+				"ahead-of-pin",
+				"held-back",
+				"latest-unavailable",
+				"not-managed",
+				"not-probed",
+				"pin-not-installable",
+				"unorderable",
+				"version-unreadable",
+			].sort(),
+		);
+	});
+
+	for (const reason of REASONS) {
+		test(`R9.6 unknown / ${reason} with a long path note: the suffix is at most ${MAX_CELLS} cells`, () => {
+			const { suffix } = cliToolStatusText(unknownRow(reason, LONG_PATH_NOTE));
+			// The suffix rides along so a failure shows what the row printed.
+			expect({ suffix, fits: cells(suffix) <= MAX_CELLS }).toEqual({
+				suffix,
+				fits: true,
+			});
+		});
+
+		test(`R9.6 unknown / ${reason} with a long path note: the suffix holds no filesystem path`, () => {
+			const { suffix } = cliToolStatusText(unknownRow(reason, LONG_PATH_NOTE));
+			expect(suffix).not.toContain("/");
+			expect(suffix).not.toContain("node_modules");
+		});
+
+		test(`R9.6 unknown / ${reason}: the row shows a label, not nothing`, () => {
+			const { suffix } = cliToolStatusText(unknownRow(reason, LONG_PATH_NOTE));
+			expect(suffix.trim().length).toBeGreaterThan(0);
+		});
+
+		test(`R9.6 unknown / ${reason}: the label is chosen by the reason, not by the note`, () => {
+			const a = cliToolStatusText(unknownRow(reason, LONG_PATH_NOTE)).suffix;
+			const b = cliToolStatusText(unknownRow(reason, OTHER_NOTE)).suffix;
+			expect(b).toBe(a);
+		});
+	}
+
+	test("R9.6 a note full of wide characters still yields a suffix within the cell budget", () => {
+		const note = "工具在路径 /opt/工具/bin/工具 找到，但不是 npm 管理的副本 ⚠️";
+		for (const reason of REASONS) {
+			const { suffix } = cliToolStatusText(unknownRow(reason, note));
+			expect({ reason, cells: cells(suffix) <= MAX_CELLS }).toEqual({
+				reason,
+				cells: true,
+			});
+			expect({ reason, slash: suffix.includes("/") }).toEqual({
+				reason,
+				slash: false,
+			});
+		}
+	});
+});
+
+describe("C14 — control: rows that are not unknown", () => {
+	test("R9.6 control: an upgrade row with a target still shows the target version", () => {
+		const status: ToolStatus = {
+			name: TOOL.name,
+			state: "upgrade",
+			reason: "behind",
+			installed: "1.0.0",
+			latest: "9.8.7",
+			target: "9.8.7",
+		};
+		const { suffix } = cliToolStatusText({
+			...row(status),
+			updateCommand: {
+				cmd: "npm",
+				args: ["install", "-g", "@example/x@latest"],
+			},
+		});
+		expect(suffix).toContain("9.8.7");
+	});
+});