@activatus/code-standards 3.1.1 → 3.2.0

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.
@@ -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,62 @@
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 { checkRequiredFiles } from "./checkRequiredFiles.mjs";
11
+ import {
12
+ listProjectFiles,
13
+ PACKAGE_DIRECTORY,
14
+ readRecordedExceptions,
15
+ } from "./projectFiles.mjs";
16
+
17
+ const readPackageMajorVersion = () => {
18
+ const packageText = readFileSync(
19
+ path.join(PACKAGE_DIRECTORY, "package.json"),
20
+ "utf8",
21
+ );
22
+ const [majorVersion] = JSON.parse(packageText).version.split(
23
+ ".",
24
+ 1,
25
+ );
26
+ return Number(majorVersion);
27
+ };
28
+
29
+ export const runChecks = ({ projectDirectory }) => {
30
+ const templatesDirectory = path.join(
31
+ PACKAGE_DIRECTORY,
32
+ "static/templates",
33
+ );
34
+ const standardsDocsDirectory = path.join(PACKAGE_DIRECTORY, "docs");
35
+ const projectFiles = listProjectFiles({ projectDirectory });
36
+ const recordedExceptions = readRecordedExceptions({
37
+ projectDirectory,
38
+ });
39
+ const findings = [
40
+ ...checkAgentFiles({
41
+ projectDirectory,
42
+ templatesDirectory,
43
+ packageMajorVersion: readPackageMajorVersion(),
44
+ }),
45
+ ...checkConfigFiles({ projectDirectory, templatesDirectory }),
46
+ ...checkRequiredFiles({ templatesDirectory, projectFiles }),
47
+ ...checkComponents({
48
+ projectDirectory,
49
+ projectFiles,
50
+ standardsDocsDirectory,
51
+ recordedExceptions,
52
+ }),
53
+ ...checkDocs({ projectDirectory, projectFiles }),
54
+ ];
55
+ const isRecorded = (finding) =>
56
+ recordedExceptions.standardNumbers.has(finding.standard);
57
+ return {
58
+ failures: findings.filter((finding) => !isRecorded(finding)),
59
+ recorded: findings.filter((finding) => isRecorded(finding)),
60
+ unfinishedChanges: recordedExceptions.unfinishedChanges,
61
+ };
62
+ };
@@ -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
+ }
@@ -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,6 +8,10 @@
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".]
@@ -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)
@@ -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
  },
@@ -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
  },
@@ -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 = ["/"];