@activatus/code-standards 3.1.0 → 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.
Files changed (44) hide show
  1. package/docs/Guides/migrating.md +93 -50
  2. package/docs/Guides/regression-checks.md +72 -0
  3. package/docs/Guides/setup.md +89 -21
  4. package/docs/Standards/documentation.md +54 -7
  5. package/docs/Standards/eslint.md +60 -18
  6. package/docs/Standards/lint-errors.md +4 -4
  7. package/docs/Standards/readable-code.md +4 -1
  8. package/docs/Standards/stylelint.md +9 -3
  9. package/docs/Standards/styling.md +5 -1
  10. package/docs/Standards/working-with-agents.md +5 -5
  11. package/docs/Structure/component-organization.md +30 -26
  12. package/docs/Structure/folder-structure.md +85 -32
  13. package/docs/Structure/import-organization.md +4 -4
  14. package/docs/design-system-components.md +16 -12
  15. package/docs/ontology.md +1 -1
  16. package/docs/templates.mdx +12 -4
  17. package/docs/version-history.md +61 -6
  18. package/package.json +6 -2
  19. package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
  20. package/scripts/verifyStandards/checkComponents.mjs +129 -0
  21. package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
  22. package/scripts/verifyStandards/checkDocs.mjs +86 -0
  23. package/scripts/verifyStandards/checkRequiredFiles.mjs +96 -0
  24. package/scripts/verifyStandards/formatReport.mjs +76 -0
  25. package/scripts/verifyStandards/projectFiles.mjs +109 -0
  26. package/scripts/verifyStandards/runChecks.mjs +62 -0
  27. package/scripts/verifyStandards/verifyStandards.mjs +22 -0
  28. package/static/templates/AGENTS.md +19 -10
  29. package/static/templates/docs/design/design-system.md +6 -0
  30. package/static/templates/docs/development/coding-standards.md +10 -2
  31. package/static/templates/docs/overview/how-it-works.md +1 -1
  32. package/static/templates/docs/overview/writing-docs.md +4 -0
  33. package/static/templates/docs/product/ontology.md +32 -0
  34. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  35. package/static/templates/eslint/nextjs/eslint.config.mjs +11 -1
  36. package/static/templates/eslint/react/eslint.config.mjs +11 -1
  37. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  38. package/static/templates/eslint.overrides.mjs +18 -0
  39. package/static/templates/skills/codeReview.md +2 -1
  40. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  41. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
  42. package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
  43. package/static/templates/tests/visual/playwright.config.mjs +65 -0
  44. package/static/templates/tests/visual/visualPages.mjs +3 -0
@@ -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 = ["/"];