@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.
- package/docs/Guides/migrating.md +92 -60
- package/docs/Guides/regression-checks.md +72 -0
- package/docs/Guides/setup.md +53 -17
- package/docs/Standards/documentation.md +38 -1
- package/docs/Standards/eslint.md +15 -13
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +98 -6
- package/docs/templates.mdx +10 -2
- package/docs/version-history.md +54 -7
- package/package.json +6 -2
- package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
- package/scripts/verifyStandards/checkComponents.mjs +129 -0
- package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
- package/scripts/verifyStandards/checkConstants.mjs +127 -0
- package/scripts/verifyStandards/checkDocs.mjs +86 -0
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +83 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +67 -0
- package/scripts/verifyStandards/checkStructure.mjs +79 -0
- package/scripts/verifyStandards/formatReport.mjs +76 -0
- package/scripts/verifyStandards/projectFiles.mjs +109 -0
- package/scripts/verifyStandards/runChecks.mjs +68 -0
- package/scripts/verifyStandards/verifyStandards.mjs +22 -0
- package/static/templates/AGENTS.md +4 -4
- package/static/templates/docs/development/coding-standards.md +6 -0
- package/static/templates/docs/overview/writing-docs.md +4 -0
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +4 -3
- package/static/templates/eslint/react/eslint.config.mjs +4 -3
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
- package/static/templates/tests/visual/playwright.config.mjs +65 -0
- 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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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);
|