@activatus/code-standards 3.1.1 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/docs/Guides/migrating.md +92 -60
  2. package/docs/Guides/regression-checks.md +72 -0
  3. package/docs/Guides/setup.md +53 -17
  4. package/docs/Standards/documentation.md +38 -1
  5. package/docs/Standards/eslint.md +15 -13
  6. package/docs/Standards/readable-code.md +2 -2
  7. package/docs/Structure/folder-structure.md +98 -6
  8. package/docs/templates.mdx +10 -2
  9. package/docs/version-history.md +54 -7
  10. package/package.json +6 -2
  11. package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
  12. package/scripts/verifyStandards/checkComponents.mjs +129 -0
  13. package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
  14. package/scripts/verifyStandards/checkConstants.mjs +127 -0
  15. package/scripts/verifyStandards/checkDocs.mjs +86 -0
  16. package/scripts/verifyStandards/checkRecordedAnswers.mjs +83 -0
  17. package/scripts/verifyStandards/checkRequiredFiles.mjs +67 -0
  18. package/scripts/verifyStandards/checkStructure.mjs +79 -0
  19. package/scripts/verifyStandards/formatReport.mjs +76 -0
  20. package/scripts/verifyStandards/projectFiles.mjs +109 -0
  21. package/scripts/verifyStandards/runChecks.mjs +68 -0
  22. package/scripts/verifyStandards/verifyStandards.mjs +22 -0
  23. package/static/templates/AGENTS.md +4 -4
  24. package/static/templates/docs/development/coding-standards.md +6 -0
  25. package/static/templates/docs/overview/writing-docs.md +4 -0
  26. package/static/templates/eslint/base/eslint.config.mjs +2 -2
  27. package/static/templates/eslint/nextjs/eslint.config.mjs +4 -3
  28. package/static/templates/eslint/react/eslint.config.mjs +4 -3
  29. package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
  30. package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
  31. package/static/templates/tests/visual/playwright.config.mjs +65 -0
  32. package/static/templates/tests/visual/visualPages.mjs +3 -0
@@ -0,0 +1,76 @@
1
+ // Turns the findings into the report printed for the person or agent:
2
+ // grouped by standard, with the page to read for each.
3
+ import path from "node:path";
4
+
5
+ import { PACKAGE_DIRECTORY } from "./projectFiles.mjs";
6
+
7
+ // The names from the numbered list in docs/Guides/setup.md.
8
+ const STANDARD_NAMES = {
9
+ 4: "Every function and component has a test file",
10
+ 6: "ESLint",
11
+ 7: "Prettier",
12
+ 8: "Stylelint",
13
+ 9: "EditorConfig",
14
+ 10: "Node version",
15
+ 12.1: "Constants",
16
+ 15: "Design System Components",
17
+ 18: "Docs",
18
+ 21: "AGENTS.md and the agent skills",
19
+ };
20
+
21
+ const toPagePath = ({ page, projectDirectory }) =>
22
+ path.relative(projectDirectory, path.join(PACKAGE_DIRECTORY, page));
23
+
24
+ const formatStandard = ({ standard, findings, projectDirectory }) => {
25
+ const standardFindings = findings.filter(
26
+ (finding) => finding.standard === standard,
27
+ );
28
+ const lines = standardFindings.map(
29
+ (finding) => ` - ${finding.message}`,
30
+ );
31
+ const pages = [
32
+ ...new Set(
33
+ standardFindings.map((finding) => finding.page).filter(Boolean),
34
+ ),
35
+ ].map(
36
+ (page) => ` Read: ${toPagePath({ page, projectDirectory })}`,
37
+ );
38
+ const heading = `${standard}. ${STANDARD_NAMES[standard] ?? ""}`;
39
+ return [heading, ...lines, ...pages].join("\n");
40
+ };
41
+
42
+ const formatGroup = ({ findings, projectDirectory }) => {
43
+ const standards = [
44
+ ...new Set(findings.map((finding) => finding.standard)),
45
+ ];
46
+ return standards
47
+ .map((standard) =>
48
+ formatStandard({ standard, findings, projectDirectory }),
49
+ )
50
+ .join("\n\n");
51
+ };
52
+
53
+ export const formatReport = ({ result, projectDirectory }) => {
54
+ const sections = [];
55
+ if (result.failures.length > 0) {
56
+ sections.push(
57
+ `To fix (${result.failures.length}):\n\n${formatGroup({ findings: result.failures, projectDirectory })}`,
58
+ );
59
+ }
60
+ if (result.recorded.length > 0) {
61
+ sections.push(
62
+ `Recorded exceptions in docs/development/coding-standards.md. Check each one matches what was agreed (${result.recorded.length}):\n\n${formatGroup({ findings: result.recorded, projectDirectory })}`,
63
+ );
64
+ }
65
+ if (result.unfinishedChanges) {
66
+ sections.push(
67
+ `Unfinished changes, from docs/development/coding-standards.md:\n\n${result.unfinishedChanges}`,
68
+ );
69
+ }
70
+ if (result.failures.length === 0) {
71
+ sections.push(
72
+ "The project follows the code standards, with its recorded exceptions.",
73
+ );
74
+ }
75
+ return sections.join("\n\n---\n\n");
76
+ };
@@ -0,0 +1,109 @@
1
+ // Reads what the checks need from the project: its files, and the
2
+ // exceptions it has recorded in docs/development/coding-standards.md.
3
+ import { execFileSync } from "node:child_process";
4
+ import { existsSync, readFileSync } from "node:fs";
5
+ import path from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+
8
+ // The installed @activatus/code-standards package: its templates and
9
+ // its docs are what the project is checked against.
10
+ export const PACKAGE_DIRECTORY = path.resolve(
11
+ path.dirname(fileURLToPath(import.meta.url)),
12
+ "../..",
13
+ );
14
+
15
+ export const CODING_STANDARDS_PATH =
16
+ "docs/development/coding-standards.md";
17
+
18
+ const NO_VALUE_WORDS = new Set(["none", "no differences"]);
19
+
20
+ // A recorded exception starts with its standard number:
21
+ // "7. Prettier — skipped", "- 12.1. Constants — changed".
22
+ const STANDARD_NUMBER_PATTERN =
23
+ /^\s*(?:[-*]\s+)?(?:\*\*)?(\d+(?:\.\d+)?)\.\s/;
24
+
25
+ export const readTextFile = ({ projectDirectory, filePath }) => {
26
+ const fullPath = path.join(projectDirectory, filePath);
27
+ return existsSync(fullPath)
28
+ ? readFileSync(fullPath, "utf8")
29
+ : undefined;
30
+ };
31
+
32
+ // Git lists the files, so every git ignore rule applies, the same way
33
+ // as the format scripts. Outside git, nothing is listed.
34
+ export const listProjectFiles = ({ projectDirectory }) => {
35
+ try {
36
+ const output = execFileSync(
37
+ "git",
38
+ ["ls-files", "--cached", "--others", "--exclude-standard"],
39
+ { cwd: projectDirectory, encoding: "utf8" },
40
+ );
41
+ return output
42
+ .split("\n")
43
+ .filter((filePath) => filePath.length > 0)
44
+ .filter((filePath) =>
45
+ existsSync(path.join(projectDirectory, filePath)),
46
+ );
47
+ } catch {
48
+ return [];
49
+ }
50
+ };
51
+
52
+ // The text under one "## Heading" of a Markdown file, up to the next
53
+ // "## " heading.
54
+ export const readSection = ({ markdown, heading }) => {
55
+ const lines = markdown.split("\n");
56
+ const startIndex = lines.findIndex(
57
+ (line) => line.trim() === `## ${heading}`,
58
+ );
59
+ if (startIndex === -1) {
60
+ return "";
61
+ }
62
+ const sectionLines = [];
63
+ const linesAfterHeading = lines.slice(startIndex + 1);
64
+ for (const line of linesAfterHeading) {
65
+ if (line.startsWith("## ")) {
66
+ break;
67
+ }
68
+ sectionLines.push(line);
69
+ }
70
+ return sectionLines.join("\n").trim();
71
+ };
72
+
73
+ const hasContent = (sectionText) => {
74
+ const words = sectionText
75
+ .replaceAll(/[".]/g, "")
76
+ .trim()
77
+ .toLowerCase();
78
+ return words.length > 0 && !NO_VALUE_WORDS.has(words);
79
+ };
80
+
81
+ export const readRecordedExceptions = ({ projectDirectory }) => {
82
+ const markdown =
83
+ readTextFile({
84
+ projectDirectory,
85
+ filePath: CODING_STANDARDS_PATH,
86
+ }) ?? "";
87
+ const details = readSection({ markdown, heading: "Details" });
88
+ const standardNumbers = new Set(
89
+ details
90
+ .split("\n")
91
+ .map((line) => STANDARD_NUMBER_PATTERN.exec(line)?.[1])
92
+ .filter(Boolean),
93
+ );
94
+ const componentsSection = readSection({
95
+ markdown,
96
+ heading: "Components for the standards",
97
+ });
98
+ const unfinishedSection = readSection({
99
+ markdown,
100
+ heading: "Unfinished changes",
101
+ });
102
+ return {
103
+ standardNumbers,
104
+ componentsText: componentsSection.toLowerCase(),
105
+ unfinishedChanges: hasContent(unfinishedSection)
106
+ ? unfinishedSection
107
+ : undefined,
108
+ };
109
+ };
@@ -0,0 +1,68 @@
1
+ // Runs every check, and separates the findings for standards the
2
+ // project has recorded as skipped or changed.
3
+ import { readFileSync } from "node:fs";
4
+ import path from "node:path";
5
+
6
+ import { checkAgentFiles } from "./checkAgentFiles.mjs";
7
+ import { checkComponents } from "./checkComponents.mjs";
8
+ import { checkConfigFiles } from "./checkConfigFiles.mjs";
9
+ import { checkDocs } from "./checkDocs.mjs";
10
+ import { checkConstants } from "./checkConstants.mjs";
11
+ import { checkRecordedAnswers } from "./checkRecordedAnswers.mjs";
12
+ import { checkRequiredFiles } from "./checkRequiredFiles.mjs";
13
+ import { checkStructure } from "./checkStructure.mjs";
14
+ import {
15
+ listProjectFiles,
16
+ PACKAGE_DIRECTORY,
17
+ readRecordedExceptions,
18
+ } from "./projectFiles.mjs";
19
+
20
+ const readPackageMajorVersion = () => {
21
+ const packageText = readFileSync(
22
+ path.join(PACKAGE_DIRECTORY, "package.json"),
23
+ "utf8",
24
+ );
25
+ const [majorVersion] = JSON.parse(packageText).version.split(
26
+ ".",
27
+ 1,
28
+ );
29
+ return Number(majorVersion);
30
+ };
31
+
32
+ export const runChecks = ({ projectDirectory }) => {
33
+ const templatesDirectory = path.join(
34
+ PACKAGE_DIRECTORY,
35
+ "static/templates",
36
+ );
37
+ const standardsDocsDirectory = path.join(PACKAGE_DIRECTORY, "docs");
38
+ const projectFiles = listProjectFiles({ projectDirectory });
39
+ const recordedExceptions = readRecordedExceptions({
40
+ projectDirectory,
41
+ });
42
+ const findings = [
43
+ ...checkAgentFiles({
44
+ projectDirectory,
45
+ templatesDirectory,
46
+ packageMajorVersion: readPackageMajorVersion(),
47
+ }),
48
+ ...checkConfigFiles({ projectDirectory, templatesDirectory }),
49
+ ...checkRequiredFiles({ templatesDirectory, projectFiles }),
50
+ ...checkConstants({ projectDirectory, projectFiles }),
51
+ ...checkStructure({ projectFiles }),
52
+ ...checkRecordedAnswers({ projectDirectory }),
53
+ ...checkComponents({
54
+ projectDirectory,
55
+ projectFiles,
56
+ standardsDocsDirectory,
57
+ recordedExceptions,
58
+ }),
59
+ ...checkDocs({ projectDirectory, projectFiles }),
60
+ ];
61
+ const isRecorded = (finding) =>
62
+ recordedExceptions.standardNumbers.has(finding.standard);
63
+ return {
64
+ failures: findings.filter((finding) => !isRecorded(finding)),
65
+ recorded: findings.filter((finding) => isRecorded(finding)),
66
+ unfinishedChanges: recordedExceptions.unfinishedChanges,
67
+ };
68
+ };
@@ -0,0 +1,22 @@
1
+ #!/usr/bin/env node
2
+ // Checks a project against the Activatus Code Standards, and against
3
+ // the exceptions it has recorded in docs/development/coding-standards.md.
4
+ // It reports; it never changes a file.
5
+ //
6
+ // Run it from the project root:
7
+ // node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs
8
+ //
9
+ // A finding for a standard the project has recorded as skipped or
10
+ // changed is listed as a recorded exception, to check by hand, and does
11
+ // not fail the run.
12
+ import { formatReport } from "./formatReport.mjs";
13
+ import { runChecks } from "./runChecks.mjs";
14
+
15
+ const projectDirectory = process.cwd();
16
+ const result = runChecks({ projectDirectory });
17
+
18
+ console.log(formatReport({ result, projectDirectory }));
19
+
20
+ if (result.failures.length > 0) {
21
+ process.exitCode = 1;
22
+ }
@@ -120,7 +120,7 @@ This is the version the code follows. It is the major version only: fixes such a
120
120
  Follow these rules in every change:
121
121
 
122
122
  - **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
123
- - **No file longer than 300 lines.** Test files are exempt, and so are `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/`, which hold data only.
123
+ - **No file longer than 300 lines.** Test files are exempt, and so are the seven constants files in `lib/constants/`, which hold data only.
124
124
  - **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters (except `r` and `s`, below), no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/docs/Standards/human-readable-names).
125
125
 
126
126
  | Never | Always |
@@ -145,8 +145,8 @@ Follow these rules in every change:
145
145
  - **Functions, never classes.**
146
146
  - **One parameter per function.** Use a single object when more than one value is needed.
147
147
  - **Return early.** Never nest more than three levels deep.
148
- - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
149
- - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. There is no component-level `constants.ts`: every link, piece of text and number goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
148
+ - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every loose named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
149
+ - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. `animation.ts` holds how things move and `artwork.ts` what is drawn and where, each object kept whole with its numbers named by their keys, never lifted out into `numbers.ts`. `classNames.ts` holds Tailwind class strings shared between files, only when a component cannot hold them and they still repeat; a class name one file uses stays inline. Create each of these three only once there is something to put in it. These seven files are the only ones in `lib/constants/`, each never split by topic. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`, except inside a loop over the list, which looks each item up by an id typed `keyof typeof r.plans`. No separate id-to-link lookup objects such as `PLAN_ROUTES`: `r` already is the lookup. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
150
150
  - **No nested ternaries. No boolean flag parameters.**
151
151
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
152
152
  - **Named exports only**, except where a tool requires a default export.
@@ -168,7 +168,7 @@ Follow these rules in every change:
168
168
 
169
169
  **Look before you build a component.** Check the project's `components/ui/`, then the Design System Components in the code standards, then other Activatus projects, then shadcn. Build to the props listed in the Design System Components; never invent new prop names for a component that is already listed. A component in `components/ui/` takes everything through props and never imports from features, services, stores or `app/`.
170
170
 
171
- **Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code.
171
+ **Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code. After setting up or updating the standards, also run `pnpm standards:check`.
172
172
 
173
173
  **Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
174
174
 
@@ -8,10 +8,16 @@
8
8
 
9
9
  This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (steps 3 and 4 of `docs/Guides/setup.md` in the package).
10
10
 
11
+ ## Why
12
+
13
+ Every Activatus project follows the same standards, so people and agents can move between projects without relearning the basics. Recording each difference here keeps it visible, and stops the next update from undoing it.
14
+
11
15
  ## Details
12
16
 
13
17
  [For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
14
18
 
19
+ - Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([YYYY-MM-DD]).
20
+
15
21
  ## Components for the standards
16
22
 
17
23
  [Props-only components this project keeps in `components/ui/` that are not in the Design System Components list yet, each with its props, to be added in the next release of the standards. If there are none, write "None".]
@@ -10,6 +10,10 @@ This project's docs follow the Activatus documentation standard: https://activat
10
10
 
11
11
  Every file in `docs/` is a Decision Doc. Read the standard before adding or editing one.
12
12
 
13
+ ## Why
14
+
15
+ One format for every doc, so people and agents always know where to look.
16
+
13
17
  ## Related
14
18
 
15
19
  - [What Is It](what-is-it.md)
@@ -121,8 +121,8 @@ const config = [
121
121
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
122
122
  },
123
123
  {
124
- // r, s, numbers and noData are lists, not logic, so they can be long.
125
- files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
124
+ // The seven constants files are data, not logic, so they can be long.
125
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
126
126
  rules: { "max-lines": "off" },
127
127
  },
128
128
  {
@@ -81,7 +81,8 @@ const config = [
81
81
  },
82
82
  settings: {
83
83
  // Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
84
- // Update the number when the project upgrades React.
84
+ // A project on another React version sets settings.react.version
85
+ // in eslint.overrides.mjs, never here.
85
86
  react: { version: "19.0" },
86
87
  "import-x/resolver-next": [createTypeScriptImportResolver()],
87
88
  },
@@ -192,8 +193,8 @@ const config = [
192
193
  },
193
194
  },
194
195
  {
195
- // r, s, numbers and noData are lists, not logic, so they can be long.
196
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
196
+ // The seven constants files are data, not logic, so they can be long.
197
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
197
198
  rules: { "max-lines": "off" },
198
199
  },
199
200
  {
@@ -83,7 +83,8 @@ const config = [
83
83
  },
84
84
  settings: {
85
85
  // Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
86
- // Update the number when the project upgrades React.
86
+ // A project on another React version sets settings.react.version
87
+ // in eslint.overrides.mjs, never here.
87
88
  react: { version: "19.0" },
88
89
  "import-x/resolver-next": [createTypeScriptImportResolver()],
89
90
  },
@@ -194,8 +195,8 @@ const config = [
194
195
  },
195
196
  },
196
197
  {
197
- // r, s, numbers and noData are lists, not logic, so they can be long.
198
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
198
+ // The seven constants files are data, not logic, so they can be long.
199
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
199
200
  rules: { "max-lines": "off" },
200
201
  },
201
202
  {
@@ -175,8 +175,8 @@ const config = [
175
175
  },
176
176
  },
177
177
  {
178
- // r, s, numbers and noData are lists, not logic, so they can be long.
179
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
178
+ // The seven constants files are data, not logic, so they can be long.
179
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
180
180
  rules: { "max-lines": "off" },
181
181
  },
182
182
  {
@@ -0,0 +1,188 @@
1
+ // Measures every page at every half-screen scroll stop: each element's
2
+ // box and opacity, the element count, the page height and a screenshot.
3
+ // A refactor passes only when every measurement matches the baseline.
4
+ import { expect, type Page, test } from "@playwright/test";
5
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
6
+ import path from "node:path";
7
+
8
+ import { VISUAL_PAGES } from "./visualPages.mjs";
9
+
10
+ const BOX_TOLERANCE_PIXELS = 1;
11
+ const OPACITY_TOLERANCE = 0.02;
12
+ const SCREENSHOT_DIFFERENCE_RATIO = 0.005;
13
+ const SCROLL_STEP_FRACTION = 0.5;
14
+ // The page clock is frozen and moved on by hand, so every run sees the
15
+ // same frames. A timing change between frames is not caught: see the
16
+ // guide's blind spot.
17
+ const FIXED_TIME = new Date("2026-01-01T00:00:00Z");
18
+ const SETTLE_MILLISECONDS = 2000;
19
+ const MAXIMUM_DIFFERENCES_SHOWN = 20;
20
+
21
+ const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
22
+
23
+ type ElementMeasurementType = {
24
+ x: number;
25
+ y: number;
26
+ width: number;
27
+ height: number;
28
+ opacity: number;
29
+ };
30
+
31
+ type PageProps = { page: Page };
32
+
33
+ type ScrollStopType = {
34
+ scrollTop: number;
35
+ pageHeight: number;
36
+ elements: Record<string, ElementMeasurementType>;
37
+ };
38
+
39
+ const settlePage = async ({ page }: PageProps) => {
40
+ await page.clock.runFor(SETTLE_MILLISECONDS);
41
+ await page.evaluate(async () => {
42
+ const finiteAnimations = document
43
+ .getAnimations()
44
+ .filter(
45
+ (animation) =>
46
+ animation.effect?.getTiming().iterations !== Infinity,
47
+ );
48
+ for (const animation of finiteAnimations) {
49
+ animation.finish();
50
+ }
51
+ const images = [...document.images];
52
+ await Promise.all(
53
+ images.map((image) => image.decode().catch(() => null)),
54
+ );
55
+ });
56
+ };
57
+
58
+ const measurePage = ({ page }: PageProps) =>
59
+ page.evaluate(() => {
60
+ const describePath = (element: Element): string => {
61
+ const parent = element.parentElement;
62
+ if (!parent) {
63
+ return element.tagName.toLowerCase();
64
+ }
65
+ const position = [...parent.children].indexOf(element) + 1;
66
+ return `${describePath(parent)}>${element.tagName.toLowerCase()}:${position}`;
67
+ };
68
+ const elements = Object.fromEntries(
69
+ [...document.body.querySelectorAll("*")].map((element) => {
70
+ const box = element.getBoundingClientRect();
71
+ return [
72
+ describePath(element),
73
+ {
74
+ x: box.x,
75
+ y: box.y,
76
+ width: box.width,
77
+ height: box.height,
78
+ opacity: Number(getComputedStyle(element).opacity),
79
+ },
80
+ ];
81
+ }),
82
+ );
83
+ return {
84
+ scrollTop: window.scrollY,
85
+ pageHeight: document.documentElement.scrollHeight,
86
+ elements,
87
+ };
88
+ });
89
+
90
+ type DescribeDifferencesProps = {
91
+ baseline: ScrollStopType;
92
+ current: ScrollStopType;
93
+ };
94
+
95
+ const describeDifferences = ({
96
+ baseline,
97
+ current,
98
+ }: DescribeDifferencesProps) => {
99
+ const differences: string[] = [];
100
+ if (baseline.pageHeight !== current.pageHeight) {
101
+ differences.push(
102
+ `page height ${baseline.pageHeight} → ${current.pageHeight}`,
103
+ );
104
+ }
105
+ const baselineKeys = Object.keys(baseline.elements);
106
+ const currentKeys = Object.keys(current.elements);
107
+ if (baselineKeys.length !== currentKeys.length) {
108
+ differences.push(
109
+ `element count ${baselineKeys.length} → ${currentKeys.length}`,
110
+ );
111
+ }
112
+ for (const key of baselineKeys) {
113
+ const before = baseline.elements[key];
114
+ const after = current.elements[key];
115
+ if (!after) {
116
+ differences.push(`${key} is missing`);
117
+ continue;
118
+ }
119
+ const isBoxMoved = (["x", "y", "width", "height"] as const).some(
120
+ (side) =>
121
+ Math.abs(before[side] - after[side]) > BOX_TOLERANCE_PIXELS,
122
+ );
123
+ const isOpacityChanged =
124
+ Math.abs(before.opacity - after.opacity) > OPACITY_TOLERANCE;
125
+ if (isBoxMoved || isOpacityChanged) {
126
+ differences.push(`${key} moved or faded`);
127
+ }
128
+ }
129
+ return differences.slice(0, MAXIMUM_DIFFERENCES_SHOWN);
130
+ };
131
+
132
+ const toFileName = (pagePath: string) =>
133
+ pagePath === "/" ? "home" : pagePath.replaceAll(/[^a-z0-9]+/gi, "-");
134
+
135
+ for (const pagePath of VISUAL_PAGES) {
136
+ test(`${pagePath} looks exactly as before`, async ({
137
+ page,
138
+ }, testInfo) => {
139
+ await page.clock.install({ time: FIXED_TIME });
140
+ await page.goto(pagePath);
141
+ await settlePage({ page });
142
+
143
+ const viewportHeight = page.viewportSize()?.height ?? 0;
144
+ const scrollStep = viewportHeight * SCROLL_STEP_FRACTION;
145
+ const stops: ScrollStopType[] = [];
146
+ // eslint-disable-next-line no-restricted-syntax -- the scroll position moves down the page one stop at a time
147
+ let scrollTop = 0;
148
+ const pageHeight = await page.evaluate(
149
+ () => document.documentElement.scrollHeight,
150
+ );
151
+ while (scrollTop <= pageHeight - viewportHeight) {
152
+ await page.evaluate(
153
+ (top) => window.scrollTo(0, top),
154
+ scrollTop,
155
+ );
156
+ await settlePage({ page });
157
+ stops.push(await measurePage({ page }));
158
+ await expect(page).toHaveScreenshot(
159
+ `${toFileName(pagePath)}-${stops.length}.png`,
160
+ { maxDiffPixelRatio: SCREENSHOT_DIFFERENCE_RATIO },
161
+ );
162
+ scrollTop += scrollStep;
163
+ }
164
+
165
+ // Saved beside the screenshots: baseline/<project>/<page>.json
166
+ const baselinePath = testInfo.snapshotPath(
167
+ `${toFileName(pagePath)}.json`,
168
+ );
169
+ if (isUpdatingBaseline) {
170
+ mkdirSync(path.dirname(baselinePath), { recursive: true });
171
+ writeFileSync(baselinePath, JSON.stringify(stops));
172
+ return;
173
+ }
174
+ const baseline: ScrollStopType[] = JSON.parse(
175
+ readFileSync(baselinePath, "utf8"),
176
+ );
177
+ expect(stops.length, "number of scroll stops").toBe(
178
+ baseline.length,
179
+ );
180
+ const differences = baseline.flatMap((baselineStop, index) =>
181
+ describeDifferences({
182
+ baseline: baselineStop,
183
+ current: stops[index],
184
+ }).map((difference) => `stop ${index + 1}: ${difference}`),
185
+ );
186
+ expect(differences).toEqual([]);
187
+ });
188
+ }
@@ -0,0 +1,65 @@
1
+ // The regression check: proves a refactor changed nothing visible.
2
+ // See "Regression Checks for Refactors" in the code standards.
3
+ import { defineConfig } from "@playwright/test";
4
+
5
+ // The baseline always comes from the live production site, never from
6
+ // the branch being tested. Set it before running test:visual:update.
7
+ const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
8
+ const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
9
+ // The project's own production build, on a port of its own.
10
+ const LOCAL_PORT = 3100;
11
+ const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
12
+ const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
13
+
14
+ if (isUpdatingBaseline && !PRODUCTION_URL) {
15
+ throw new Error(
16
+ "Set VISUAL_PRODUCTION_URL to the live site before updating the baseline.",
17
+ );
18
+ }
19
+
20
+ /** @type {import("@playwright/test").PlaywrightTestConfig} */
21
+ const config = {
22
+ testDir: ".",
23
+ testMatch: "*.visual.ts",
24
+ snapshotPathTemplate: "{testDir}/baseline/{projectName}/{arg}{ext}",
25
+ fullyParallel: true,
26
+ use: {
27
+ baseURL: isUpdatingBaseline ? PRODUCTION_URL : LOCAL_URL,
28
+ },
29
+ projects: [
30
+ {
31
+ name: "desktop",
32
+ use: { viewport: { width: 1440, height: 900 } },
33
+ },
34
+ {
35
+ name: "tablet",
36
+ use: { viewport: { width: 768, height: 1024 } },
37
+ },
38
+ {
39
+ name: "mobile",
40
+ use: {
41
+ viewport: { width: 390, height: 844 },
42
+ isMobile: true,
43
+ hasTouch: true,
44
+ },
45
+ },
46
+ {
47
+ name: "desktopReducedMotion",
48
+ use: {
49
+ viewport: { width: 1440, height: 900 },
50
+ contextOptions: { reducedMotion: "reduce" },
51
+ },
52
+ },
53
+ ],
54
+ // Rebuilt before every run, so a stale build is never measured.
55
+ webServer: isUpdatingBaseline
56
+ ? undefined
57
+ : {
58
+ command: `pnpm build && pnpm start --port ${LOCAL_PORT}`,
59
+ url: LOCAL_URL,
60
+ reuseExistingServer: false,
61
+ timeout: SERVER_START_TIMEOUT_MILLISECONDS,
62
+ },
63
+ };
64
+
65
+ export default defineConfig(config);
@@ -0,0 +1,3 @@
1
+ // The pages the regression check measures, as paths from the site root.
2
+ // Add every page a refactor could change.
3
+ export const VISUAL_PAGES = ["/"];