| 1 | /** |
| 2 | * Shared-content contracts: the locale-aware vocabulary and getting-started |
| 3 | * modules that pages render from. These tests pin the copy to the repo's |
| 4 | * public fact matrix and to real routes/documents, so the localization lane |
| 5 | * can extend the modules without ever drifting from runtime truth. |
| 6 | */ |
| 7 | import { existsSync, readFileSync } from "node:fs"; |
| 8 | import { describe, expect, it } from "vitest"; |
| 9 | import { |
| 10 | ADVISORY_ROLE, |
| 11 | CONTROL_MODES, |
| 12 | MEASUREMENT_PRINCIPLES, |
| 13 | PERMISSION_POSTURES, |
| 14 | PRODUCT_TERMS, |
| 15 | ROUTE_IDENTITY, |
| 16 | } from "./vocabulary"; |
| 17 | import { GETTING_STARTED_STEPS, GUIDE_NEXT_LINKS } from "./getting-started"; |
| 18 | |
| 19 | const root = new URL("../../../", import.meta.url); |
| 20 | |
| 21 | function repoText(path: string): string { |
| 22 | return readFileSync(new URL(path, root), "utf8"); |
| 23 | } |
| 24 | |
| 25 | const matrix = JSON.parse(repoText("docs/public-surface-facts.json")) as { |
| 26 | product: { terminology: Record<string, string> }; |
| 27 | control: { modes: string[]; permissionPostures: string[] }; |
| 28 | }; |
| 29 | |
| 30 | const BANNED_COPY = /\bAgent mode\b|Agent 模式|\bYOLO\b|approval_mode|first-class|一级支持/; |
| 31 | |
| 32 | describe("shared product vocabulary", () => { |
| 33 | it("keeps the execution nouns verbatim with the public fact matrix", () => { |
| 34 | expect(PRODUCT_TERMS.map((t) => t.term)).toEqual(["Fleet", "Workflow", "Lane", "Runtime"]); |
| 35 | for (const term of PRODUCT_TERMS) { |
| 36 | expect(term.short.en, term.term).toBe(matrix.product.terminology[term.term]); |
| 37 | } |
| 38 | }); |
| 39 | |
| 40 | it("keeps mode and posture names exact", () => { |
| 41 | expect(CONTROL_MODES.map((t) => t.term)).toEqual(matrix.control.modes); |
| 42 | expect(PERMISSION_POSTURES.map((t) => t.term)).toEqual(matrix.control.permissionPostures); |
| 43 | for (const term of [...CONTROL_MODES, ...PERMISSION_POSTURES]) { |
| 44 | expect(term.kind).toMatch(/^mode$|^permission-posture$/); |
| 45 | } |
| 46 | }); |
| 47 | |
| 48 | it("has complete en/zh pairs everywhere and no banned legacy copy", () => { |
| 49 | const pairs = [ |
| 50 | ...PRODUCT_TERMS.flatMap((t) => [t.short, t.long]), |
| 51 | ...[...CONTROL_MODES, ...PERMISSION_POSTURES, ...ROUTE_IDENTITY].map((t) => t.description), |
| 52 | ADVISORY_ROLE.description, |
| 53 | ...MEASUREMENT_PRINCIPLES, |
| 54 | ]; |
| 55 | for (const pair of pairs) { |
| 56 | expect(pair.en.trim().length).toBeGreaterThan(0); |
| 57 | expect(pair.zh.trim().length).toBeGreaterThan(0); |
| 58 | expect(pair.en).not.toBe(pair.zh); |
| 59 | expect(`${pair.en}\n${pair.zh}`).not.toMatch(BANNED_COPY); |
| 60 | } |
| 61 | }); |
| 62 | |
| 63 | it("states measurement truth without claiming results", () => { |
| 64 | expect(MEASUREMENT_PRINCIPLES.length).toBeGreaterThanOrEqual(3); |
| 65 | const combined = MEASUREMENT_PRINCIPLES.map((p) => p.en).join("\n"); |
| 66 | // No fabricated numbers: the module must not publish any benchmark score. |
| 67 | expect(combined).not.toMatch(/\b\d+(\.\d+)?\s?(%|percent|tokens\/s|tok\/s)\b/i); |
| 68 | expect(combined).toContain("no benchmark leaderboard"); |
| 69 | expect(combined).toContain("provider, model, requested and effective reasoning"); |
| 70 | }); |
| 71 | |
| 72 | it("separates requested and effective reasoning and names route provenance", () => { |
| 73 | const requested = ROUTE_IDENTITY.find((r) => r.term === "Requested reasoning"); |
| 74 | const effective = ROUTE_IDENTITY.find((r) => r.term === "Effective reasoning"); |
| 75 | const source = ROUTE_IDENTITY.find((r) => r.term === "Routing source"); |
| 76 | expect(requested).toBeTruthy(); |
| 77 | expect(effective?.description.en).toContain("unavailable"); |
| 78 | expect(source?.description.en).toContain("provenance"); |
| 79 | for (const tier of ["off", "low", "medium", "high", "max", "auto"]) { |
| 80 | expect(requested!.description.en).toContain(tier); |
| 81 | } |
| 82 | }); |
| 83 | |
| 84 | it("uses Consultant publicly and keeps old advisory names as aliases only", () => { |
| 85 | expect(ADVISORY_ROLE.term).toBe("Consultant"); |
| 86 | expect(ADVISORY_ROLE.description.en).toContain("oracle"); |
| 87 | expect(ADVISORY_ROLE.description.en).toContain("advisor"); |
| 88 | expect(ADVISORY_ROLE.description.en).toContain("compatibility aliases"); |
| 89 | }); |
| 90 | }); |
| 91 | |
| 92 | describe("shared getting-started path", () => { |
| 93 | it("keeps the four-step order: install → offline session → provider → fleet", () => { |
| 94 | expect(GETTING_STARTED_STEPS.map((s) => s.id)).toEqual([ |
| 95 | "install", |
| 96 | "first-session", |
| 97 | "connect-provider", |
| 98 | "fleet-workflow", |
| 99 | ]); |
| 100 | }); |
| 101 | |
| 102 | it("points every step and next link at a real on-site route", () => { |
| 103 | const knownRoutes = [ |
| 104 | "/install", |
| 105 | "/models", |
| 106 | "/docs", |
| 107 | "/docs/guide", |
| 108 | "/docs/vocabulary", |
| 109 | "/docs/fleet", |
| 110 | "/docs/hooks", |
| 111 | "/docs/modes", |
| 112 | ]; |
| 113 | for (const step of GETTING_STARTED_STEPS) { |
| 114 | expect(knownRoutes, step.link.href).toContain(step.link.href); |
| 115 | expect(step.title.en.trim().length).toBeGreaterThan(0); |
| 116 | expect(step.title.zh.trim().length).toBeGreaterThan(0); |
| 117 | expect(`${step.body.en}\n${step.body.zh}`).not.toMatch(BANNED_COPY); |
| 118 | } |
| 119 | for (const link of GUIDE_NEXT_LINKS) { |
| 120 | expect(knownRoutes, link.href).toContain(link.href); |
| 121 | } |
| 122 | // Hooks discovery is a first-class next step, not buried prose. |
| 123 | expect(GUIDE_NEXT_LINKS.some((l) => l.href === "/docs/hooks")).toBe(true); |
| 124 | }); |
| 125 | |
| 126 | it("describes the first session truthfully: keyless launch, provider for replies", () => { |
| 127 | const first = GETTING_STARTED_STEPS.find((s) => s.id === "first-session")!; |
| 128 | expect(first.body.en).toContain("without any API key"); |
| 129 | expect(first.body.en).toContain("Plan mode"); |
| 130 | expect(first.body.en).toMatch(/Model replies need a provider/); |
| 131 | // The keyless-launch claim is documented behavior, not invented copy. |
| 132 | const guide = repoText("docs/GUIDE.md"); |
| 133 | expect(guide).toContain("On first launch, Codewhale starts with a short constitution-first setup path"); |
| 134 | }); |
| 135 | |
| 136 | it("uses only documented commands", () => { |
| 137 | const guide = repoText("docs/GUIDE.md"); |
| 138 | const fleetDoc = repoText("docs/FLEET.md"); |
| 139 | const install = GETTING_STARTED_STEPS.find((s) => s.id === "install")!; |
| 140 | expect(install.commands).toContain("npm install -g codewhale"); |
| 141 | expect(guide).toContain("codewhale doctor"); |
| 142 | const provider = GETTING_STARTED_STEPS.find((s) => s.id === "connect-provider")!; |
| 143 | expect(provider.commands).toContain("codewhale auth set --provider deepseek"); |
| 144 | expect(guide).toContain("codewhale auth set --provider deepseek"); |
| 145 | const fleet = GETTING_STARTED_STEPS.find((s) => s.id === "fleet-workflow")!; |
| 146 | for (const command of fleet.commands) { |
| 147 | expect(`${fleetDoc}\n${guide}`, command).toContain(command); |
| 148 | } |
| 149 | }); |
| 150 | |
| 151 | it("keeps repo source documents resolvable", () => { |
| 152 | for (const path of ["docs/GUIDE.md", "docs/KEYBINDINGS.md", "docs/FLEET.md", "docs/MODES.md"]) { |
| 153 | expect(existsSync(new URL(path, root)), path).toBe(true); |
| 154 | } |
| 155 | }); |
| 156 | }); |
| 157 |