| 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 | install: { recommended: string }; |
| 28 | control: { modes: string[]; permissionPostures: string[] }; |
| 29 | }; |
| 30 | |
| 31 | const BANNED_COPY = /\bAgent mode\b|Agent 模式|\bYOLO\b|approval_mode|first-class|一级支持/; |
| 32 | |
| 33 | describe("shared product vocabulary", () => { |
| 34 | it("keeps the execution nouns verbatim with the public fact matrix", () => { |
| 35 | expect(PRODUCT_TERMS.map((t) => t.term)).toEqual(["Fleet", "Workflow", "Lane", "Runtime"]); |
| 36 | for (const term of PRODUCT_TERMS) { |
| 37 | expect(term.short.en, term.term).toBe(matrix.product.terminology[term.term]); |
| 38 | } |
| 39 | }); |
| 40 | |
| 41 | it("keeps mode and posture names exact", () => { |
| 42 | expect(CONTROL_MODES.map((t) => t.term)).toEqual(matrix.control.modes); |
| 43 | expect(PERMISSION_POSTURES.map((t) => t.term)).toEqual(matrix.control.permissionPostures); |
| 44 | for (const term of [...CONTROL_MODES, ...PERMISSION_POSTURES]) { |
| 45 | expect(term.kind).toMatch(/^mode$|^permission-posture$/); |
| 46 | } |
| 47 | }); |
| 48 | |
| 49 | it("has complete en/zh pairs everywhere and no banned legacy copy", () => { |
| 50 | const pairs = [ |
| 51 | ...PRODUCT_TERMS.flatMap((t) => [t.short, t.long]), |
| 52 | ...[...CONTROL_MODES, ...PERMISSION_POSTURES, ...ROUTE_IDENTITY].map((t) => t.description), |
| 53 | ADVISORY_ROLE.description, |
| 54 | ...MEASUREMENT_PRINCIPLES, |
| 55 | ]; |
| 56 | for (const pair of pairs) { |
| 57 | expect(pair.en.trim().length).toBeGreaterThan(0); |
| 58 | expect(pair.zh.trim().length).toBeGreaterThan(0); |
| 59 | expect(pair.en).not.toBe(pair.zh); |
| 60 | expect(`${pair.en}\n${pair.zh}`).not.toMatch(BANNED_COPY); |
| 61 | } |
| 62 | }); |
| 63 | |
| 64 | it("states measurement truth without claiming results", () => { |
| 65 | expect(MEASUREMENT_PRINCIPLES.length).toBeGreaterThanOrEqual(3); |
| 66 | const combined = MEASUREMENT_PRINCIPLES.map((p) => p.en).join("\n"); |
| 67 | // No fabricated numbers: the module must not publish any benchmark score. |
| 68 | expect(combined).not.toMatch(/\b\d+(\.\d+)?\s?(%|percent|tokens\/s|tok\/s)\b/i); |
| 69 | expect(combined).toContain("no benchmark leaderboard"); |
| 70 | expect(combined).toContain("provider, model, requested and effective reasoning"); |
| 71 | }); |
| 72 | |
| 73 | it("separates requested and effective reasoning and names route provenance", () => { |
| 74 | const requested = ROUTE_IDENTITY.find((r) => r.term === "Requested reasoning"); |
| 75 | const effective = ROUTE_IDENTITY.find((r) => r.term === "Effective reasoning"); |
| 76 | const source = ROUTE_IDENTITY.find((r) => r.term === "Routing source"); |
| 77 | expect(requested).toBeTruthy(); |
| 78 | expect(effective?.description.en).toContain("unavailable"); |
| 79 | expect(source?.description.en).toContain("provenance"); |
| 80 | for (const tier of ["off", "low", "medium", "high", "max", "auto"]) { |
| 81 | expect(requested!.description.en).toContain(tier); |
| 82 | } |
| 83 | }); |
| 84 | |
| 85 | it("uses Advisor publicly and keeps old advisory names as aliases only", () => { |
| 86 | expect(ADVISORY_ROLE.term).toBe("Advisor"); |
| 87 | expect(ADVISORY_ROLE.description.en).toContain("oracle"); |
| 88 | expect(ADVISORY_ROLE.description.en).toContain("consultant"); |
| 89 | expect(ADVISORY_ROLE.description.en).toContain("compatibility aliases"); |
| 90 | }); |
| 91 | }); |
| 92 | |
| 93 | describe("shared getting-started path", () => { |
| 94 | it("connects a provider before the first task, with Fleet optional afterward", () => { |
| 95 | expect(GETTING_STARTED_STEPS.map((s) => s.id)).toEqual([ |
| 96 | "install", |
| 97 | "connect-provider", |
| 98 | "first-session", |
| 99 | "fleet-workflow", |
| 100 | ]); |
| 101 | }); |
| 102 | |
| 103 | it("points every step and next link at a real on-site route", () => { |
| 104 | const knownRoutes = [ |
| 105 | "/install", |
| 106 | "/models", |
| 107 | "/docs", |
| 108 | "/docs/guide", |
| 109 | "/docs/vocabulary", |
| 110 | "/docs/fleet", |
| 111 | "/docs/hooks", |
| 112 | "/docs/modes", |
| 113 | ]; |
| 114 | for (const step of GETTING_STARTED_STEPS) { |
| 115 | expect(knownRoutes, step.link.href).toContain(step.link.href); |
| 116 | expect(step.title.en.trim().length).toBeGreaterThan(0); |
| 117 | expect(step.title.zh.trim().length).toBeGreaterThan(0); |
| 118 | expect(`${step.body.en}\n${step.body.zh}`).not.toMatch(BANNED_COPY); |
| 119 | } |
| 120 | for (const link of GUIDE_NEXT_LINKS) { |
| 121 | expect(knownRoutes, link.href).toContain(link.href); |
| 122 | } |
| 123 | // Hooks discovery is a first-class next step, not buried prose. |
| 124 | expect(GUIDE_NEXT_LINKS.some((l) => l.href === "/docs/hooks")).toBe(true); |
| 125 | }); |
| 126 | |
| 127 | it("keeps offline setup documented without requiring it before a first task", () => { |
| 128 | // The keyless-launch claim must stay backed by documented runtime |
| 129 | // behavior. Assert the meaning docs/GUIDE.md owes this step -- a first |
| 130 | // launch that asks only for the decisions still needed, and a provider |
| 131 | // step that keeps an explicit offline route -- rather than one frozen |
| 132 | // sentence, which is what broke when the first-run flow was rewritten. |
| 133 | // Heading-level hashes only: shell comments inside the fenced install |
| 134 | // snippets start with a single "#" and must not end the section slice. |
| 135 | const guide = repoText("docs/GUIDE.md"); |
| 136 | const firstLaunch = guide.split(/^#{2,} .*First Launch.*$/m)[1]?.split(/^#{2,} /m)[0] ?? ""; |
| 137 | expect(firstLaunch, "docs/GUIDE.md must keep a First Launch section").not.toBe(""); |
| 138 | expect(firstLaunch).toMatch(/asks only for decisions/i); |
| 139 | expect(firstLaunch).toMatch(/offline route/i); |
| 140 | }); |
| 141 | |
| 142 | it("uses only documented commands", () => { |
| 143 | const guide = repoText("docs/GUIDE.md"); |
| 144 | // docs/FLEET.md keeps its filename (published links, receipts) while |
| 145 | // leading with the Fleet noun; see its naming/compatibility section. |
| 146 | const fleetDoc = repoText("docs/FLEET.md"); |
| 147 | const install = GETTING_STARTED_STEPS.find((s) => s.id === "install")!; |
| 148 | expect(install.commands[0]).toBe(matrix.install.recommended); |
| 149 | expect(repoText("docs/INSTALL.md")).toContain(install.commands[0]); |
| 150 | expect(guide).toContain("codewhale doctor"); |
| 151 | const provider = GETTING_STARTED_STEPS.find((s) => s.id === "connect-provider")!; |
| 152 | expect(provider.commands).toContain("codewhale auth set --provider deepseek"); |
| 153 | expect(guide).toContain("codewhale auth set --provider deepseek"); |
| 154 | const fleet = GETTING_STARTED_STEPS.find((s) => s.id === "fleet-workflow")!; |
| 155 | for (const command of fleet.commands) { |
| 156 | expect(`${fleetDoc}\n${guide}`, command).toContain(command); |
| 157 | } |
| 158 | }); |
| 159 | |
| 160 | it("keeps repo source documents resolvable", () => { |
| 161 | for (const path of ["docs/GUIDE.md", "docs/KEYBINDINGS.md", "docs/FLEET.md", "docs/MODES.md"]) { |
| 162 | expect(existsSync(new URL(path, root)), path).toBe(true); |
| 163 | } |
| 164 | }); |
| 165 | }); |
| 166 |