@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.
@@ -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**, before anything changes. Every later stage must pass it unchanged.
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**, before the refactor starts:
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 live production site**, never from the branch being tested. A baseline taken from the branch would only prove the branch matches itself.
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
- export const ENTRANCE_ANIMATION = {
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
- export const ILLUSTRATION_LAYOUT = {
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 {
@@ -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.0
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 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.
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.0",
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` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
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 always comes from the live production site, never from
6
- // the branch being tested. Set it before running test:visual:update.
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 live site before updating the baseline.",
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