@activatus/code-standards 3.3.0 → 3.3.2

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,7 @@
1
+ # pnpm rewrites this on every install, in its own style.
2
+ pnpm-workspace.yaml
3
+ # Copied from the code standards and compared word for word by
4
+ # pnpm standards:check, so Prettier leaves them as they are.
5
+ AGENTS.md
6
+ .agents/skills/
7
+ .claude/commands/
@@ -99,6 +99,7 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
99
99
  - **Read them before starting work** — the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
100
100
  - **Check each doc's Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** — do not treat them as one and do not invent one. Ask.
101
101
  - **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
102
+ - **Record a check only after it has run.** Never write a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists.
102
103
  - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
103
104
  - Do not edit `docsSite/` unless the task is about the docs viewer itself.
104
105
 
@@ -123,7 +124,7 @@ This is the version the code follows, written in full so it pairs with the insta
123
124
  Follow these rules in every change:
124
125
 
125
126
  - **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
126
- - **No file longer than 300 lines.** Test files are exempt, and so are the seven constants files in `lib/constants/`, which hold data only.
127
+ - **No file longer than 300 lines.** Test files are exempt, and so are the files in `lib/constants/`, which hold data only.
127
128
  - **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).
128
129
 
129
130
  | Never | Always |
@@ -148,8 +149,8 @@ Follow these rules in every change:
148
149
  - **Functions, never classes.**
149
150
  - **One parameter per function.** Use a single object when more than one value is needed.
150
151
  - **Return early.** Never nest more than three levels deep.
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
+ - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`. Config files keep their numbers at the top of the file.
153
+ - **Links go in `r` and text people see or hear goes in `s`**, both in `lib/constants/`, never written straight into a component. The keys of `s` become the translation keys when the site gets more languages. **Every other value lives with the code that uses it until it is shared:** a number, list, status or internal string (ids, keys, event names, log messages) one file uses is a named constant at the top of that file. Once more than one file needs it, it moves to the file in `lib/constants/` that fits, such as `numbers.ts`, `animation.ts`, `classNames.ts` or `status.ts`, or a new file named after what it holds. Stand-in data for local development goes in `noData.ts`, named `NO_DATA_` plus the thing it replaces. **Not sure where a value goes?** Put it in `lib/constants/unsortedValues.ts` and carry on. At the end of the work, ask the person where each value in it goes, move each one there, and delete the file. Constants in `lib/constants/` get real types from `lib/types/`, never `as const`. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. `r` and `s` are the only single-letter names allowed anywhere. Import constants in one line: `import { r, s } from "@/lib/constants";`. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
153
154
  - **No nested ternaries. No boolean flag parameters.**
154
155
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
155
156
  - **Named exports only**, except where a tool requires a default export.
@@ -173,7 +174,7 @@ Follow these rules in every change:
173
174
 
174
175
  **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
176
 
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.
177
+ **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
178
 
178
179
  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
180
 
@@ -14,7 +14,7 @@ Every Activatus project follows the same standards, so people and agents can mov
14
14
 
15
15
  ## Details
16
16
 
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".]
17
+ [For each standard this project skips or changes, at setup or later, one line: its number and name from the setup list, "skipped" or "changed", why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." An exception for only some files names them in backticks after "for": "4. Every function and component has a test file — changed for `app/api/**`: legacy routes, tested when replaced (2026-10-27)." Start no other line here with a number: `pnpm standards:check` reads every numbered line as an exception. Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
18
18
 
19
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]; told about decisions [yes or no] ([YYYY-MM-DD]).
20
20
 
@@ -24,7 +24,7 @@ Every Activatus project follows the same standards, so people and agents can mov
24
24
 
25
25
  ## Unfinished changes
26
26
 
27
- [Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write "None".]
27
+ [Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write exactly "None", with nothing after it: a note after "None" reads as an unfinished change.]
28
28
 
29
29
  ## Related
30
30
 
@@ -121,8 +121,8 @@ const config = [
121
121
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
122
122
  },
123
123
  {
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}"],
124
+ // The constants files are data, not logic, so they can be long.
125
+ files: ["lib/constants/*.{js,mjs}"],
126
126
  rules: { "max-lines": "off" },
127
127
  },
128
128
  {
@@ -202,8 +202,8 @@ const config = [
202
202
  },
203
203
  },
204
204
  {
205
- // The seven constants files are data, not logic, so they can be long.
206
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
205
+ // The constants files are data, not logic, so they can be long.
206
+ files: ["lib/constants/*.ts"],
207
207
  rules: { "max-lines": "off" },
208
208
  },
209
209
  {
@@ -204,8 +204,8 @@ const config = [
204
204
  },
205
205
  },
206
206
  {
207
- // The seven constants files are data, not logic, so they can be long.
208
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
207
+ // The constants files are data, not logic, so they can be long.
208
+ files: ["lib/constants/*.ts"],
209
209
  rules: { "max-lines": "off" },
210
210
  },
211
211
  {
@@ -184,8 +184,8 @@ const config = [
184
184
  },
185
185
  },
186
186
  {
187
- // The seven constants files are data, not logic, so they can be long.
188
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
187
+ // The constants files are data, not logic, so they can be long.
188
+ files: ["lib/constants/*.ts"],
189
189
  rules: { "max-lines": "off" },
190
190
  },
191
191
  {
@@ -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