@activatus/code-standards 3.3.0 → 3.3.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 +2 -2
- package/docs/Guides/regression-checks.md +9 -3
- package/docs/Structure/folder-structure.md +7 -3
- package/docs/version-history.md +23 -5
- package/package.json +1 -1
- package/static/templates/AGENTS.md +2 -2
- package/static/templates/tests/visual/playwright.config.mjs +5 -3
package/docs/Guides/migrating.md
CHANGED
|
@@ -50,7 +50,7 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
|
|
|
50
50
|
|
|
51
51
|
## Stage 0 — Regression check
|
|
52
52
|
|
|
53
|
-
Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **live production site
|
|
53
|
+
Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **last known-good page**, before anything changes: the live production site, or the branch's last commit before the migration when its page has already changed from production. Record which. Every later stage must pass it unchanged.
|
|
54
54
|
|
|
55
55
|
**Take the baseline first, then move one kind of thing at a time.** The constants moves (Stage 4) and the folder moves (Stage 5a) are separate steps, each followed by a full regression run. When a run fails, only one kind of move can have caused it.
|
|
56
56
|
|
|
@@ -188,7 +188,7 @@ Applies setup standard 12.1. Move every link into `r`, every piece of text into
|
|
|
188
188
|
- **An id moves into the object that uses it.** **CSS written as a string moves to `globals.css`**, never into a constants file. A media query the code reads stays in its object in `animation.ts`.
|
|
189
189
|
- **Only text people see or hear goes in `s`.** Internal strings, such as ids, keys and log messages, stay where they are used: a key in the object that uses them, or a named constant at the top of the file.
|
|
190
190
|
- **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its key: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete any separate lookup object that maps a key to its link.
|
|
191
|
-
- **Every constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
191
|
+
- **Every object and list constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. A single number or string needs none. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
192
192
|
|
|
193
193
|
## Stage 5 — Components
|
|
194
194
|
|
|
@@ -44,13 +44,19 @@ So every run sees the same thing, the page clock is frozen and moved on by hand,
|
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
4. **Freeze the test files.** Add `tests/visual/` to `.prettierignore`, and add this line to the project's `AGENTS.md`, outside the code standards section: "Never edit `tests/visual/` or update its baseline without the person's yes."
|
|
47
|
-
5. **Take the baseline from the live production site
|
|
47
|
+
5. **Take the baseline before the refactor starts, from the last known-good page.** That is the live production site, unless the branch's page has already changed from production for another reason, such as a redesign not yet live. Then it is the branch's last commit before the refactor: build that commit in a separate worktree, serve it, and point the baseline at it.
|
|
48
48
|
|
|
49
49
|
```bash
|
|
50
|
+
# From production
|
|
50
51
|
VISUAL_PRODUCTION_URL=https://example.com pnpm test:visual:update
|
|
52
|
+
|
|
53
|
+
# From the last commit before the refactor: build and serve it in its
|
|
54
|
+
# own worktree, then point the baseline at it
|
|
55
|
+
git worktree add ../before-refactor <commit>
|
|
56
|
+
VISUAL_PRODUCTION_URL=http://localhost:3200 pnpm test:visual:update
|
|
51
57
|
```
|
|
52
58
|
|
|
53
|
-
Commit `tests/visual/baseline
|
|
59
|
+
Commit `tests/visual/baseline/`, and **record where it came from** in `docs/testing/regression.md`: the production URL, or the commit and the date.
|
|
54
60
|
|
|
55
61
|
## Running it
|
|
56
62
|
|
|
@@ -62,7 +68,7 @@ It builds the project and starts the production build on port 3100, then measure
|
|
|
62
68
|
|
|
63
69
|
## Rules
|
|
64
70
|
|
|
65
|
-
- **The baseline comes from the
|
|
71
|
+
- **The baseline comes from the last known-good page**, never from the branch being tested: the live production site, or the branch's last commit before the refactor when its page has already changed from production. A baseline taken from the branch under test would only prove the branch matches itself.
|
|
66
72
|
- **It runs against a production build**, on its own port, never against `pnpm dev`.
|
|
67
73
|
- **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
|
|
68
74
|
- **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
|
|
@@ -475,7 +475,9 @@ export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
|
|
|
475
475
|
**`animation.ts` holds every object that says how and when something moves.**
|
|
476
476
|
|
|
477
477
|
```ts title="lib/constants/animation.ts"
|
|
478
|
-
|
|
478
|
+
import type { EntranceAnimationType } from "@/lib/types";
|
|
479
|
+
|
|
480
|
+
export const ENTRANCE_ANIMATION: EntranceAnimationType = {
|
|
479
481
|
delaySeconds: 0.1,
|
|
480
482
|
durationSeconds: 0.4,
|
|
481
483
|
offsetPixels: 24,
|
|
@@ -492,7 +494,9 @@ export const ENTRANCE_ANIMATION = {
|
|
|
492
494
|
**`artwork.ts` holds every object that says what is drawn, where it ends up, and how it is grouped.** Where something ends up is artwork; how and when it gets there is animation.
|
|
493
495
|
|
|
494
496
|
```ts title="lib/constants/artwork.ts"
|
|
495
|
-
|
|
497
|
+
import type { IllustrationLayoutType } from "@/lib/types";
|
|
498
|
+
|
|
499
|
+
export const ILLUSTRATION_LAYOUT: IllustrationLayoutType = {
|
|
496
500
|
heightPixels: 600,
|
|
497
501
|
widthPixels: 800,
|
|
498
502
|
};
|
|
@@ -516,7 +520,7 @@ export const SURFACE_CLASS_NAME =
|
|
|
516
520
|
|
|
517
521
|
### Types for constants {#types-for-constants}
|
|
518
522
|
|
|
519
|
-
**Every constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand.
|
|
523
|
+
**Every object and list constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand. **A single number or string needs no type of its own**: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed, and writing `: number` adds nothing.
|
|
520
524
|
|
|
521
525
|
```ts title="lib/types/animation.ts"
|
|
522
526
|
export interface EntranceAnimationType {
|
package/docs/version-history.md
CHANGED
|
@@ -68,10 +68,26 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
68
68
|
|
|
69
69
|
## Version 3
|
|
70
70
|
|
|
71
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.
|
|
71
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.1
|
|
72
72
|
|
|
73
73
|
Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
|
|
74
74
|
|
|
75
|
+
**Fixes in 3.3.1.** If the project already applied 3.3.0, check these:
|
|
76
|
+
|
|
77
|
+
- **A single number or string needs no type of its own.** 3.3.0 said every constant gets a type from `lib/types/`. It means every object and list constant: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed. The Animation and Artwork examples now have their types. Nothing to do, unless the project added `: number` or `: string` only to follow 3.3.0: those can stay or go.
|
|
78
|
+
- **The `readonly` search also finds `string[]`, `number[]` and `boolean[]` lists.** 3.3.0's search only found named types.
|
|
79
|
+
|
|
80
|
+
**What to do:** run the new search in 3.3.0's How to check, and make each hit that a constant uses `readonly`.
|
|
81
|
+
|
|
82
|
+
- **The regression baseline comes from the last known-good page.** That is the live production site, unless the branch's page has already changed from production, such as a redesign not yet live: then it is the branch's last commit before the refactor, built and served on its own. Record where the baseline came from in `docs/testing/regression.md`. See [Regression Checks](/docs/Guides/regression-checks). The comment and error message in the `playwright.config.mjs` template say the same; a project's frozen copy need not change.
|
|
83
|
+
|
|
84
|
+
**What to do:** if the project's `docs/testing/regression.md` does not say where its baseline came from, add it: the production URL, or the commit and the date.
|
|
85
|
+
|
|
86
|
+
- **`AGENTS.md`: an `as const` that cannot be avoided is one of the allowed lint disables**, beside `let` and a type cast, as 3.3.0 already said. Copy the Code standards section from the template again.
|
|
87
|
+
- **3.3.0's What to do had a step joined onto the end of a list.** "Copy the TypeScript skill again" and the disable-with-reason line now sit in their own paragraph. Nothing new to do.
|
|
88
|
+
|
|
89
|
+
**How to check:** the 3.3.0 How to check searches find nothing; `docs/testing/regression.md` says where the baseline came from.
|
|
90
|
+
|
|
75
91
|
**Fixes in 3.3.0.** If the project already applied 3.2.2, check these:
|
|
76
92
|
|
|
77
93
|
**Structural changes in 3.3.0.** These move files. Plan them, and take a [regression check](/docs/Guides/regression-checks) baseline first:
|
|
@@ -84,9 +100,9 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
|
|
|
84
100
|
- a class name only one file uses
|
|
85
101
|
- numbers in config files
|
|
86
102
|
|
|
87
|
-
- **Constants get real types, from `lib/types/`.** Every constant except `r` and `s` is typed where it is declared, with a type from `lib/types/`. "`lib/constants/` never imports from `lib/types/`" is withdrawn: it only ever guarded against a loop of types, which `import type` removes at build, and it pushed projects into `as const` and into retyping values wherever they were read. `lib/types/` now reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
103
|
+
- **Constants get real types, from `lib/types/`.** Every object and list constant except `r` and `s` is typed where it is declared, with a type from `lib/types/`. _Changed in 3.3.1: a single number or string needs no type of its own._ "`lib/constants/` never imports from `lib/types/`" is withdrawn: it only ever guarded against a loop of types, which `import type` removes at build, and it pushed projects into `as const` and into retyping values wherever they were read. `lib/types/` now reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
88
104
|
|
|
89
|
-
**What to do:** change every import in `lib/types/` from `@/lib/constants` to the constant's own file, as `import type`. Give every constant except `r` and `s` a type from `lib/types/`, in files named by topic, and move the types it uses there with what they depend on. Point imports at `@/lib/types`, delete component `types.ts` files left empty, and remove imports left unused. Then remove the workarounds: values retyped where they are read, test values retyped or bent around missing properties. Make every list in a constant's type `readonly`, including lists inside an item. Copy the Code standards section of `AGENTS.md` from the template again.
|
|
105
|
+
**What to do:** change every import in `lib/types/` from `@/lib/constants` to the constant's own file, as `import type`. Give every object and list constant except `r` and `s` a type from `lib/types/`, in files named by topic, and move the types it uses there with what they depend on. Point imports at `@/lib/types`, delete component `types.ts` files left empty, and remove imports left unused. Then remove the workarounds: values retyped where they are read, test values retyped or bent around missing properties. Make every list in a constant's type `readonly`, including lists inside an item. Copy the Code standards section of `AGENTS.md` from the template again.
|
|
90
106
|
|
|
91
107
|
- **No `as const` anywhere.** A written type is the contract; when the code needs exact values, they go in the type. Each constant's list type is `readonly`. A list that must hold every id is checked with a `Record` or a test. ESLint now reports `as const` as an error: `consistent-type-assertions` always let it through, so the configs ban it with `no-restricted-syntax`. See [No `as const`](/docs/Standards/readable-code#no-as-const).
|
|
92
108
|
|
|
@@ -95,7 +111,9 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
|
|
|
95
111
|
- values in tests
|
|
96
112
|
- internal strings, as a named constant at the top of the file that uses them
|
|
97
113
|
- a class name only one file uses
|
|
98
|
-
- numbers in config files
|
|
114
|
+
- numbers in config files
|
|
115
|
+
|
|
116
|
+
Copy `static/templates/skills/typescript.md` into `.agents/skills/` and `.claude/commands/` again. Where one `as const` is genuinely unavoidable, disable the rule on that line with the reason.
|
|
99
117
|
|
|
100
118
|
- **The regression test template has no `as const`**, and a frozen test may take a change that touches only types. A code standards update that changes only types may be applied to a frozen test with the person's yes. Nothing the test does changes, and the check must still pass against the existing baseline. See [Regression Checks](/docs/Guides/regression-checks).
|
|
101
119
|
|
|
@@ -113,7 +131,7 @@ grep -rn "as const" --include='*.ts' --include='*.tsx' --exclude-dir=node_module
|
|
|
113
131
|
This search lists types in `lib/types/` with a list that is not `readonly`. Fix each hit that a constant uses; a type only props or parameters use can stay as it is:
|
|
114
132
|
|
|
115
133
|
```bash
|
|
116
|
-
grep -rnE "(^|[^y] )[A-Z][A-Za-z]*Type\[\]" lib/types/
|
|
134
|
+
grep -rnE "(^|[^y] )([A-Z][A-Za-z]*Type|string|number|boolean)\[\]" lib/types/
|
|
117
135
|
```
|
|
118
136
|
|
|
119
137
|
**Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.1",
|
|
4
4
|
"description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -149,7 +149,7 @@ Follow these rules in every change:
|
|
|
149
149
|
- **One parameter per function.** Use a single object when more than one value is needed.
|
|
150
150
|
- **Return early.** Never nest more than three levels deep.
|
|
151
151
|
- **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`.
|
|
152
|
-
- **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 text people see or hear, 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 and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, 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. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. Every constant except `r` and `s` gets a real type from `lib/types/`, in files named by topic. `lib/types/` reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. 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 a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `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
|
|
152
|
+
- **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 text people see or hear, 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 and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, 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. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. Every object and list constant except `r` and `s` gets a real type from `lib/types/`, in files named by topic; a single number or string needs none. `lib/types/` reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. 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 a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `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
|
|
153
153
|
- **No nested ternaries. No boolean flag parameters.**
|
|
154
154
|
- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
|
|
155
155
|
- **Named exports only**, except where a tool requires a default export.
|
|
@@ -173,7 +173,7 @@ Follow these rules in every change:
|
|
|
173
173
|
|
|
174
174
|
**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`.
|
|
175
175
|
|
|
176
|
-
**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
|
|
176
|
+
**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`, a type cast and an `as const` that cannot be avoided, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
|
|
177
177
|
|
|
178
178
|
When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
|
|
179
179
|
|
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
// See "Regression Checks for Refactors" in the code standards.
|
|
3
3
|
import { defineConfig } from "@playwright/test";
|
|
4
4
|
|
|
5
|
-
// The baseline
|
|
6
|
-
//
|
|
5
|
+
// The baseline comes from the last known-good page, never from the
|
|
6
|
+
// branch being tested: the live production site, or the branch's last
|
|
7
|
+
// commit before the refactor, served on its own. Set it before running
|
|
8
|
+
// test:visual:update.
|
|
7
9
|
const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
|
|
8
10
|
const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
|
|
9
11
|
// The project's own production build, on a port of its own.
|
|
@@ -13,7 +15,7 @@ const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
|
|
|
13
15
|
|
|
14
16
|
if (isUpdatingBaseline && !PRODUCTION_URL) {
|
|
15
17
|
throw new Error(
|
|
16
|
-
"Set VISUAL_PRODUCTION_URL to the
|
|
18
|
+
"Set VISUAL_PRODUCTION_URL to the last known-good page before updating the baseline: the live site, or the last commit before the refactor, served on its own.",
|
|
17
19
|
);
|
|
18
20
|
}
|
|
19
21
|
|