@activatus/code-standards 3.2.0 → 3.2.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.
@@ -7,27 +7,44 @@ sidebar_label: "Version History"
7
7
 
8
8
  > What changed in each version of the standards, and exactly what a project has to do about it. Written for the AI agent doing the update.
9
9
 
10
- **Every change to the standards gets a new version number.** Each project records the version it follows in its `AGENTS.md`, under "Code standards":
10
+ **Every change to the standards gets a new version number.** Each project records the full version it last applied in its `AGENTS.md`, under "Code standards", so the project pairs with the package and knows where to start:
11
11
 
12
12
  ```md
13
- **Code standards version:** 2
13
+ **Code standards version:** 3.2.2
14
14
  ```
15
15
 
16
+ ## How versions are numbered
17
+
18
+ | Part that changes | Example | Means |
19
+ | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
20
+ | First | 3.2.2 → 4.0.0 | A major update: it changes how most of a project's code is written, so every project reworks it |
21
+ | Middle | 3.2.2 → 3.3.0 | Files move: the update moves or renames files in a project. Plan it, and take a regression baseline first |
22
+ | Last | 3.2.2 → 3.2.3 | Changes inside files only. Nothing moves |
23
+
24
+ **The first number goes up only when most projects must rework most of their code**, such as a new framework or a standard replaced by a different one. A rule added, changed or clarified never bumps it. Every new number can ask for work, whichever part changed. 3.1.1 and 3.2.1 came out before this rule and moved files in a last-number update; their moves are listed under **Structural changes**.
25
+
16
26
  ## Updating a project to a new version
17
27
 
18
- **Read only the versions newer than the project's.** A project on version 1 that is updating to version 3 reads version 2 and version 3 on this page, and nothing else. Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
28
+ **Read only the entries newer than the project's version.** A project on 3.2.1 updating to 3.3.0 reads the 3.2.2 and 3.3.0 entries on this page, and nothing else. **A project that recorded only a major number, such as `3`,** first finds the full version it actually applied: the `@activatus/code-standards` version in `pnpm-lock.yaml` at the last commit that changed its `**Code standards version:**` line. Record that version in `AGENTS.md` and start from there. Only when it cannot tell does it read every entry of that major version from its start:
29
+
30
+ ```bash
31
+ git show "$(git log -1 --format=%h -G'Code standards version' -- AGENTS.md)":pnpm-lock.yaml \
32
+ | grep -o "@activatus/code-standards@[0-9.]*" | head -1
33
+ ```
34
+
35
+ Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
19
36
 
20
- 1. **Find the project's version** in its `AGENTS.md`. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
37
+ 1. **Find the project's version** in its `AGENTS.md`. If it is only a major number, find the full one first, as above. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
21
38
  2. **Update the package:** `pnpm add -D @activatus/code-standards@latest`, never a typed version number. If pnpm refuses because the version is too new, add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, as in [Setup](/docs/Guides/setup#1-install-the-standards). The entry is the plain package name, with no version. If pnpm wrote one with versions in it, such as `'@activatus/code-standards@3.0.4 || 3.0.5'`, replace it with the plain name: otherwise pnpm adds another version to it on every update. Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
22
- 3. **Read each version newer than the project's**, oldest first. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
39
+ 3. **Read each entry newer than the project's version**, oldest first. For a middle-number entry, take the [regression check](/docs/Guides/regression-checks) baseline before any file moves. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
23
40
  4. **For each change, do the "What to do" steps**, then run the "How to check" searches. A search that still finds something means the change is not finished. When a change says to copy a line from the `AGENTS.md` template, and the project's `AGENTS.md` records the standards in its own words instead, write the updated rule there in the project's own shape.
24
41
  5. **Strike out what the standard now covers.** After the changes, re-read the project's list of opted-out and changed standards in `docs/development/coding-standards.md`. Take off the list any exception the new version has made part of the standard, and update any rule it records for an old shape of the standard. A differences list that still describes the old standard sends the next agent wrong.
25
42
  6. **Run `pnpm lint`, `pnpm format:check`, `pnpm test` and the build** after each change. `format:check` checks every file git does not ignore; never narrow it to changed files.
26
43
  7. **Ask any [Working with the agent](/docs/Guides/setup#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
27
44
  8. **Run `pnpm standards:check`**, and fix what it finds. See [Checking a project](/docs/Guides/setup#checking-a-project).
28
- 9. **Update the version number** in `AGENTS.md` once every change is done.
45
+ 9. **Set the version** in `AGENTS.md` to the installed package's full version once every change is done.
29
46
 
30
- **A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
47
+ **A project already on the installed full version** has no version changes to make: follow [Already on this version](/docs/Guides/setup#already-on-this-version).
31
48
 
32
49
  **When a change does not fit the project**, for example it renames a folder the project does not have, skip it. If you are not sure, ask; do not guess.
33
50
 
@@ -35,29 +52,98 @@ sidebar_label: "Version History"
35
52
 
36
53
  Anyone changing the standards adds a version, alongside the change:
37
54
 
38
- - **One version per release**, numbered one higher than the last. Whole numbers only. A version can collect several changes before it is released.
39
- - **Bump the package's major version to match** in `package.json`: version 3 is `3.0.0`. Then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
55
+ - **Pick the number from [How versions are numbered](#how-versions-are-numbered).** A major update is `4.0.0`. An update that moves files bumps the middle number, `3.2.2` → `3.3.0`. An update that only changes the inside of files bumps the last, `3.2.2` → `3.2.3`. Set it in `package.json`, then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
40
56
  - **For every change, write:** what changed, why, what to do in a project, and how to check it is done. Write it for an agent that has not read the rest of the standards.
41
57
  - **If a project has nothing to do, say so.**
42
58
  - **Newest version at the top.**
43
- - **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: pilot it (below), drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
44
- - **Pilot a version in a real project before releasing it.** Once the work-in-progress version is written, have one real project apply it exactly as written, reading only what the page says. Every judgement call the agent has to make, and every instruction that does not fit the project, is a missing sentence: fold it back into the version before publishing. Release only when the pilot runs without the agent asking a question the page does not answer.
45
- - **Fixing a released version** bumps only the last number: `3.0.0` → `3.0.1`. Update the version's changes in place, and list what was fixed under its **Fixes**. Projects keep the same version number in `AGENTS.md`. Write each fix so a project already on that version knows what to do.
46
- - **Adding something optional** to a released version, such as a new setup question, bumps the middle number: `3.0.9` → `3.1.0`. It is written up the same way as a fix, and projects keep the same version number in `AGENTS.md`.
47
- - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.0.9 — optional project links`, so releases are easy to find in the git log.
48
- - **Every patch number is published.** Publish each patch to npm as soon as its Fixes are written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
59
+ - **Work in progress on a major update goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
60
+ - **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
61
+ - **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
62
+ - **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
63
+ - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.2.2 — full version numbers`, so releases are easy to find in the git log.
64
+ - **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
49
65
  - **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
50
66
 
51
67
  ---
52
68
 
53
69
  ## Version 3
54
70
 
55
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.2.0
71
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.2.2
56
72
 
57
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.
58
74
 
75
+ **Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
76
+
77
+ - **The project records the full version.** `**Code standards version:**` in `AGENTS.md` is now the full version last applied, such as `3.1.0`, not the major number alone, so the project and the package pair up and the next update knows where to start. Versions are now numbered by what they do: see [How versions are numbered](#how-versions-are-numbered). `pnpm standards:check` reads the full version, and flags a project that recorded only `3`, an older version, or a version newer than the installed package.
78
+
79
+ **What to do:** if `AGENTS.md` records only a major number, find the full version the project applied from its lockfile, as in [Updating a project to a new version](#updating-a-project-to-a-new-version), and start this update from there. Copy the Code standards section of `AGENTS.md` from the template again. When the update is done, set the version to the installed package's full version.
80
+
81
+ - **The standards are the base, and agents build freely from there.** The `AGENTS.md` template now says so: most code is something the standards never mention, and the agent decides it and keeps it the same across the codebase. Only skipping, loosening or changing a standard needs the person's yes; the agent then records it and keeps going, never stopping to wait for a new version of the standards. Copied in with the section above.
82
+
83
+ - **Where each constant goes is the project's call.** The [Constants table](/docs/Structure/folder-structure#constants) says what each file is for, not where every value in every project goes. 3.2.1's examples and check named values from one project; they are now neutral, and `pnpm standards:check` no longer guesses a value's file from its name. It lists the file, and the project decides.
84
+
85
+ **What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
86
+
87
+ - **An id lives in the object that uses it.** A value that picks which item something acts on is a key inside that object, never a loose constant. A list of keys a loop runs over stays a list. See the [before and after](/docs/Structure/folder-structure#constants-rules).
88
+
89
+ **What to do:** move each loose id constant into the object that uses it.
90
+
91
+ - **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there 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`.
92
+
93
+ **What to do:** move any CSS string out of `lib/constants/` and components into `globals.css`.
94
+
95
+ - **`s` holds only text people see or hear.** Internal strings, such as ids, keys, event names and 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.
96
+
97
+ **What to do:** nothing, unless the project moved internal strings into `s`. Move those back beside the code that uses them.
98
+
99
+ - **`animation.ts` and `artwork.ts` are split by one question.** Where something ends up is artwork; how and when it gets there is animation. Drawing data the code reads goes in `artwork.ts`; a static drawing nothing reads goes in an `.svg` file or an icon component. `classNames.ts` can hold a set of class names keyed by variant, named `_CLASS_NAMES`. Nothing to move unless the project placed a value by the old wording.
100
+
101
+ - **The regression baseline comes first.** Take it before any file moves, then do the constants moves and the folder moves as separate steps, with a full regression run after each. See [Stage 0](/docs/Guides/migrating#stage-0--regression-check).
102
+
103
+ - **`pnpm standards:check` reports headings for standards 11 and 13**, which 3.2.1 printed blank. Nothing to do.
104
+
105
+ - **Setup asks a fifth agent question:** does the person want to be told about coding decisions the agent makes that the code standards do not cover? Someone who reads the code may want to hear each one; someone who does not may not care. See [Told about decisions](/docs/Standards/working-with-agents#told-about-decisions).
106
+
107
+ **What to do:** ask the person the question in [setup step 4](/docs/Guides/setup#4-working-with-the-agent), and add the answer to the "Working with the agent" line under "Details" in `coding-standards.md`. If they said yes, add the rule under **Decisions** in the Project workflow section of `AGENTS.md`.
108
+
109
+ **How to check:** `AGENTS.md` records the full installed version; `pnpm standards:check` passes, or lists only recorded exceptions; these searches find nothing, or only values the project has recorded:
110
+
111
+ ```bash
112
+ # CSS written in TypeScript, however it is quoted, on one line or many
113
+ grep -rnE "@media|@keyframes|!important|[a-z-]+: *[^;,]*(px|rem|none|auto|block|flex|grid);" \
114
+ lib/constants/ app/ components/ --include='*.ts' --include='*.tsx' --exclude='*.test.*'
115
+ # A loose id constant
116
+ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
117
+ ```
118
+
119
+ **Fixes in 3.2.1.** If the project already applied 3.2.0, check these:
120
+
121
+ **Structural changes in 3.2.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
122
+
123
+ - Every component `constants.ts`, and every other file in `lib/constants/`, moves into the seven standard files: one move per file. `pnpm standards:check` lists them.
124
+ - Every sub-component folder that is not directly in its root component's `components/` folder moves there: one move per folder. If the project did 3.1.1's move, only folders inside a grouping folder are left. `pnpm standards:check` lists them.
125
+
126
+ - **`lib/constants/` has seven standard files:** `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, and three new ones, created only once there is something to put in them:
127
+ - **`animation.ts`**: how and when things move.
128
+ - **`artwork.ts`**: what is drawn, where it ends up, and how it is grouped.
129
+ - **`classNames.ts`**: Tailwind class names shared between files, only when a component cannot hold them and they still repeat. A class name one file uses stays inline.
130
+
131
+ Each animation and artwork object stays whole, its values named by their keys. Never lift them out into `numbers.ts`, which keeps loose single numbers only: lifting them out makes long names and splits one object across files. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
132
+
133
+ **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
134
+
135
+ - **A loop over a list looks each item up by its key.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's key, typed from `r`: `keyof typeof r.plans`. Delete separate lookup objects that map a key to its link: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
136
+
137
+ - **`pnpm standards:check` checks more of the How to check lists:** sub-components sit flat in their root component's `components/` folder; the homepage is in `app/(homepage)/`; `docs/development/coding-standards.md` records the agent answers under "Details"; `docs/design/design-system.md` has a filled-in Colour palette table; and `lib/constants/` holds only the seven standard files. Fix what it finds.
138
+
139
+ - **Keep every docs folder.** 3.2.0's rule is final: no docs folder is deleted, even one that does not apply yet.
140
+
141
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `lib/constants/` holds only the seven standard files and `index.ts`; no component has its own `constants.ts`.
142
+
59
143
  **Fixes in 3.2.0.** If the project already applied 3.1.1, check these:
60
144
 
145
+ **Structural changes in 3.2.0.** Only one: restore any docs folder deleted under 3.1.1, from the templates. Small.
146
+
61
147
  - **A standards check ships with the package.** Add the script `"standards:check": "node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs"` to `package.json`, run `pnpm standards:check`, and fix what it finds. It follows the exceptions recorded in `docs/development/coding-standards.md`. See [Checking a project](/docs/Guides/setup#checking-a-project). Copy the Code standards section of `AGENTS.md` from the template again: it now says to run the check.
62
148
  - **Keep every docs folder and file**, even ones that do not apply yet. 3.1.1 allowed deleting a folder that could not apply; that is withdrawn, because the folders keep every project's docs laid out the same and a small project grows into them. Restore any folder deleted under 3.1.1 from the templates, and remove its entry from `coding-standards.md`.
63
149
  - **The React version lives in `eslint.overrides.mjs`.** A project on a React version other than 19 sets `{ settings: { react: { version: "19.2" } } }` there, and copies the template over `eslint.config.mjs` unchanged.
@@ -69,6 +155,14 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
69
155
 
70
156
  **Fixes in 3.1.1.** If the project already applied 3.1.0, check these:
71
157
 
158
+ **Structural changes in 3.1.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
159
+
160
+ - The homepage moves into `app/(homepage)/`: `app/page.tsx` and the homepage's components. Small.
161
+ - The site frame moves into `components/layout/`: the navigation, header and footer. Small.
162
+ - Every component `constants.ts` moves into `lib/constants/`: one move per file. Follow the 3.2.1 rule, not this version's.
163
+ - Every nested sub-component folder moves flat into its parent's `components/` folder: one move per folder.
164
+ - `r` or `s` split into several files only to stay under 300 lines goes back into one file. Small.
165
+
72
166
  - **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They hold data only, so `max-lines` no longer applies to them. Splitting `r` or `s` across files to stay under 300 lines only made labels harder to find. In `eslint.config.mjs`, add this block straight after the test-file block:
73
167
 
74
168
  ```js
@@ -93,8 +187,8 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
93
187
  - **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
94
188
  - **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
95
189
  - **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
96
- - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. Config files and scripts outside the app keep theirs at the top.
97
- - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`.
190
+ - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top.
191
+ - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._
98
192
  - **Write `r` and `s` keys out by name**, `r.plans.starter`, never `r.plans[planId]`. A list of items keeps its words in `s` and its links in `r` under the same keys. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
99
193
  - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
100
194
  - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
@@ -103,7 +197,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
103
197
  - **The palette is listed in `docs/design/design-system.md`**: each colour's name, value, class names and use. `globals.css` holds only colours Tailwind does not have. Copy the Colour palette section from the template and fill it in.
104
198
  - **AGENTS.md: the Code standards section sits between `<!-- code-standards:start -->` and `<!-- code-standards:end -->`**, and an update replaces everything between them. Copy the section from the template, markers included. Move any project exception written into it into `docs/development/coding-standards.md`, and anything else the project added, such as a framework's block, outside the markers.
105
199
  - **Docs:** copy the new `docs/product/ontology.md` template if the project has none, and ask the person to review it. Fix the link in `overview/writing-docs.md` if `what-is-it.md` was renamed. Retitle `how-it-works.md` "Overview — How It Works". Delete any version 2 leftovers: `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md`.
106
- - **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`. Moving or reformatting a doc does not change its Updated date.
200
+ - **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. ~~A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`.~~ _Withdrawn in 3.2.0: keep every folder._ Moving or reformatting a doc does not change its Updated date.
107
201
  - **Stylelint configs name their export:** `const config = { … }; export default config;`. Change the project's `stylelint.config.mjs` to match.
108
202
  - **The Linear ticket prefix is the team's, not the project's.** In `AGENTS.md`, Project workflow, write the Linear workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad.
109
203
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.2.0",
3
+ "version": "3.2.2",
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",
@@ -8,7 +8,9 @@ import { readTextFile } from "./projectFiles.mjs";
8
8
  const SECTION_START = "<!-- code-standards:start -->";
9
9
  const SECTION_END = "<!-- code-standards:end -->";
10
10
  const VERSION_LINE_START = "**Code standards version:**";
11
- const VERSION_PATTERN = /\*\*Code standards version:\*\*\s*(\d+)/;
11
+ const VERSION_PATTERN =
12
+ /\*\*Code standards version:\*\*\s*(\d+(?:\.\d+){0,2})/;
13
+ const VERSION_PART_COUNT = 3;
12
14
  const SKILL_FOLDERS = [".agents/skills", ".claude/commands"];
13
15
  const PAGE = "docs/Standards/agent-specs.md";
14
16
 
@@ -29,28 +31,68 @@ const readStandardsSection = (agentsText) => {
29
31
  : undefined;
30
32
  };
31
33
 
32
- const checkVersion = ({ agentsText, packageMajorVersion }) => {
34
+ const toVersionParts = (version) =>
35
+ Array.from({ length: VERSION_PART_COUNT }, (_unused, index) =>
36
+ Number(version.split(".")[index] ?? 0),
37
+ );
38
+
39
+ // Below zero when the project's version is older than the package's,
40
+ // above zero when it is newer, and zero when they match.
41
+ const compareVersions = ({ projectVersion, packageVersion }) => {
42
+ const projectParts = toVersionParts(projectVersion);
43
+ const packageParts = toVersionParts(packageVersion);
44
+ const differentIndex = projectParts.findIndex(
45
+ (part, index) => part !== packageParts[index],
46
+ );
47
+ return differentIndex === -1
48
+ ? 0
49
+ : projectParts[differentIndex] - packageParts[differentIndex];
50
+ };
51
+
52
+ const checkVersion = ({ agentsText, packageVersion }) => {
33
53
  const match = VERSION_PATTERN.exec(agentsText);
34
54
  if (!match) {
35
55
  return [
36
56
  {
37
57
  standard: "21",
38
58
  message:
39
- "AGENTS.md has no code standards version. Set **Code standards version:** to the major version the code follows",
59
+ "AGENTS.md has no code standards version. Set **Code standards version:** to the full version the code follows, such as 3.2.2",
40
60
  page: "docs/Guides/setup.md",
41
61
  },
42
62
  ];
43
63
  }
44
- const projectVersion = Number(match[1]);
45
- if (projectVersion < packageMajorVersion) {
64
+ const projectVersion = match[1];
65
+ if (projectVersion.split(".").length < VERSION_PART_COUNT) {
66
+ return [
67
+ {
68
+ standard: "21",
69
+ message: `AGENTS.md records version ${projectVersion}, not a full version. Record the full version the project last applied, such as 3.1.0: read the @activatus/code-standards version in pnpm-lock.yaml at the last commit that changed the version line, then update from there`,
70
+ page: "docs/version-history.md#updating-a-project-to-a-new-version",
71
+ },
72
+ ];
73
+ }
74
+ const comparison = compareVersions({
75
+ projectVersion,
76
+ packageVersion,
77
+ });
78
+ if (comparison < 0) {
46
79
  return [
47
80
  {
48
81
  standard: "21",
49
- message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageMajorVersion}. Follow "Updating to a newer version"`,
82
+ message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageVersion}. Follow "Updating to a newer version"`,
50
83
  page: "docs/Guides/setup.md#updating-to-a-newer-version",
51
84
  },
52
85
  ];
53
86
  }
87
+ if (comparison > 0) {
88
+ return [
89
+ {
90
+ standard: "21",
91
+ message: `AGENTS.md says version ${projectVersion}, newer than the installed package, version ${packageVersion}. Correct the version in AGENTS.md, or install the package with @latest`,
92
+ page: "docs/Guides/setup.md#2-work-out-where-the-project-is",
93
+ },
94
+ ];
95
+ }
54
96
  return [];
55
97
  };
56
98
 
@@ -125,7 +167,7 @@ const checkSkills = ({ projectDirectory, templatesDirectory }) => {
125
167
  export const checkAgentFiles = ({
126
168
  projectDirectory,
127
169
  templatesDirectory,
128
- packageMajorVersion,
170
+ packageVersion,
129
171
  }) => {
130
172
  const agentsText = readTextFile({
131
173
  projectDirectory,
@@ -141,7 +183,7 @@ export const checkAgentFiles = ({
141
183
  ];
142
184
  }
143
185
  return [
144
- ...checkVersion({ agentsText, packageMajorVersion }),
186
+ ...checkVersion({ agentsText, packageVersion }),
145
187
  ...checkStandardsSection({ agentsText, templatesDirectory }),
146
188
  ...checkSkills({ projectDirectory, templatesDirectory }),
147
189
  ];
@@ -0,0 +1,65 @@
1
+ // Standard 12.1: lib/constants/ holds the seven standard files and
2
+ // nothing else, and no component keeps its own constants file.
3
+ const REQUIRED_FILES = [
4
+ "lib/constants/index.ts",
5
+ "lib/constants/routes.ts",
6
+ "lib/constants/strings.ts",
7
+ "lib/constants/numbers.ts",
8
+ ];
9
+ // Created only once the project has something to put in them.
10
+ const OPTIONAL_FILES = [
11
+ "lib/constants/noData.ts",
12
+ "lib/constants/animation.ts",
13
+ "lib/constants/artwork.ts",
14
+ "lib/constants/classNames.ts",
15
+ ];
16
+ const CONSTANTS_FOLDER = "lib/constants/";
17
+ const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
18
+ const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
19
+ const PAGE = "docs/Structure/folder-structure.md#constants";
20
+ // Where each value goes is the project's call, made from the table.
21
+ const NEXT_STEP =
22
+ "Move each of its values into the file the Constants table says fits, and record any value that fits none in docs/development/coding-standards.md";
23
+
24
+ const checkMissingFiles = ({ projectFileSet }) =>
25
+ REQUIRED_FILES.filter(
26
+ (filePath) => !projectFileSet.has(filePath),
27
+ ).map((filePath) => ({
28
+ standard: "12.1",
29
+ message: `${filePath} is missing`,
30
+ page: PAGE,
31
+ }));
32
+
33
+ const checkExtraFiles = ({ projectFiles }) => {
34
+ const standardFiles = new Set([
35
+ ...REQUIRED_FILES,
36
+ ...OPTIONAL_FILES,
37
+ ]);
38
+ return projectFiles
39
+ .filter((filePath) => filePath.startsWith(CONSTANTS_FOLDER))
40
+ .filter((filePath) => CODE_FILE_PATTERN.test(filePath))
41
+ .filter((filePath) => !filePath.includes(".test."))
42
+ .filter((filePath) => !standardFiles.has(filePath))
43
+ .map((filePath) => ({
44
+ standard: "12.1",
45
+ message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
46
+ page: PAGE,
47
+ }));
48
+ };
49
+
50
+ const checkComponentFiles = ({ projectFiles }) =>
51
+ projectFiles
52
+ .filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
53
+ .filter((filePath) => !filePath.startsWith("node_modules/"))
54
+ .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
55
+ .map((filePath) => ({
56
+ standard: "12.1",
57
+ message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
58
+ page: PAGE,
59
+ }));
60
+
61
+ export const checkConstants = ({ projectFiles }) => [
62
+ ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
63
+ ...checkExtraFiles({ projectFiles }),
64
+ ...checkComponentFiles({ projectFiles }),
65
+ ];
@@ -0,0 +1,87 @@
1
+ // What setup asks the person and writes down: the five agent answers
2
+ // (standard 21) and the colour palette (standard 11).
3
+ import {
4
+ CODING_STANDARDS_PATH,
5
+ readSection,
6
+ readTextFile,
7
+ } from "./projectFiles.mjs";
8
+
9
+ const DESIGN_SYSTEM_PATH = "docs/design/design-system.md";
10
+ const AGENT_ANSWERS = [
11
+ { name: "the GitHub repo", pattern: /github/i },
12
+ { name: "the Linear project", pattern: /linear/i },
13
+ { name: "the status circles", pattern: /status circles?/i },
14
+ { name: "asking before committing", pattern: /commit/i },
15
+ {
16
+ name: "being told about decisions",
17
+ pattern: /told about decisions/i,
18
+ },
19
+ ];
20
+ // The template's unfilled line: "[link or None]", "[yes or no]".
21
+ const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
22
+ const TABLE_ROW_PATTERN = /^\|/;
23
+ const TABLE_SEPARATOR_PATTERN = /^\|[\s:|-]+\|$/;
24
+ const PLACEHOLDER_ROW_PATTERN = /^\|\s*\[/;
25
+ // The header row comes before the separator.
26
+ const HEADER_ROW_COUNT = 1;
27
+
28
+ const checkAgentAnswers = ({ projectDirectory }) => {
29
+ const markdown = readTextFile({
30
+ projectDirectory,
31
+ filePath: CODING_STANDARDS_PATH,
32
+ });
33
+ if (markdown === undefined) {
34
+ return [];
35
+ }
36
+ const details = readSection({ markdown, heading: "Details" })
37
+ .split("\n")
38
+ .filter((line) => !UNFILLED_ANSWER_PATTERN.test(line))
39
+ .join("\n");
40
+ return AGENT_ANSWERS.filter(
41
+ ({ pattern }) => !pattern.test(details),
42
+ ).map(({ name }) => ({
43
+ standard: "21",
44
+ message: `${CODING_STANDARDS_PATH} does not record ${name} under "Details". Ask the person, and write their answer down, even if it is "None" or "No"`,
45
+ page: "docs/Guides/setup.md#4-working-with-the-agent",
46
+ }));
47
+ };
48
+
49
+ const readPaletteRows = ({ section }) =>
50
+ section
51
+ .split("\n")
52
+ .map((line) => line.trim())
53
+ .filter((line) => TABLE_ROW_PATTERN.test(line))
54
+ .filter((line) => !TABLE_SEPARATOR_PATTERN.test(line))
55
+ .slice(HEADER_ROW_COUNT);
56
+
57
+ const checkPalette = ({ projectDirectory }) => {
58
+ const markdown = readTextFile({
59
+ projectDirectory,
60
+ filePath: DESIGN_SYSTEM_PATH,
61
+ });
62
+ if (markdown === undefined) {
63
+ return [];
64
+ }
65
+ const section = readSection({
66
+ markdown,
67
+ heading: "Colour palette",
68
+ });
69
+ const rows = readPaletteRows({ section });
70
+ const isFilledIn =
71
+ rows.length > 0 &&
72
+ rows.every((row) => !PLACEHOLDER_ROW_PATTERN.test(row));
73
+ return isFilledIn
74
+ ? []
75
+ : [
76
+ {
77
+ standard: "11",
78
+ message: `${DESIGN_SYSTEM_PATH} has no filled-in "## Colour palette" table. List each colour, its value, its class names and what it is for`,
79
+ page: "docs/Standards/styling.md#-colours-always-come-from-global-variables",
80
+ },
81
+ ];
82
+ };
83
+
84
+ export const checkRecordedAnswers = ({ projectDirectory }) => [
85
+ ...checkAgentAnswers({ projectDirectory }),
86
+ ...checkPalette({ projectDirectory }),
87
+ ];
@@ -1,19 +1,12 @@
1
- // Standards 12.1 and 18: the files every project has.
1
+ // Standards 18 and 21: the docs every project has.
2
2
  import { readdirSync, statSync } from "node:fs";
3
3
  import path from "node:path";
4
4
 
5
5
  import { CODING_STANDARDS_PATH } from "./projectFiles.mjs";
6
6
 
7
- const CONSTANTS_FILES = [
8
- "lib/constants/index.ts",
9
- "lib/constants/routes.ts",
10
- "lib/constants/strings.ts",
11
- "lib/constants/numbers.ts",
12
- ];
13
7
  // Setup renames this file after the project: what-is-launchpad.md.
14
8
  const RENAMED_OVERVIEW_PATH = "overview/what-is-it.md";
15
9
  const RENAMED_OVERVIEW_PATTERN = /^docs\/overview\/what-is-.+\.md$/;
16
- const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
17
10
 
18
11
  const listTemplateDocs = ({ directory, prefix = "" }) =>
19
12
  readdirSync(directory).flatMap((entry) => {
@@ -54,27 +47,6 @@ const checkDocsFiles = ({ templatesDirectory, projectFiles }) => {
54
47
  }));
55
48
  };
56
49
 
57
- const checkConstantsFiles = ({ projectFiles }) => {
58
- const projectFileSet = new Set(projectFiles);
59
- const missing = CONSTANTS_FILES.filter(
60
- (filePath) => !projectFileSet.has(filePath),
61
- ).map((filePath) => ({
62
- standard: "12.1",
63
- message: `${filePath} is missing`,
64
- page: "docs/Structure/folder-structure.md#constants",
65
- }));
66
- const componentConstants = projectFiles
67
- .filter((filePath) => !filePath.startsWith("lib/constants/"))
68
- .filter((filePath) => !filePath.startsWith("node_modules/"))
69
- .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
70
- .map((filePath) => ({
71
- standard: "12.1",
72
- message: `${filePath}: there is no component-level constants file. Move its values into r, s and numbers.ts in lib/constants/`,
73
- page: "docs/Structure/folder-structure.md#constants",
74
- }));
75
- return [...missing, ...componentConstants];
76
- };
77
-
78
50
  export const checkRequiredFiles = ({
79
51
  templatesDirectory,
80
52
  projectFiles,
@@ -91,6 +63,5 @@ export const checkRequiredFiles = ({
91
63
  return [
92
64
  ...codingStandards,
93
65
  ...checkDocsFiles({ templatesDirectory, projectFiles }),
94
- ...checkConstantsFiles({ projectFiles }),
95
66
  ];
96
67
  };
@@ -0,0 +1,79 @@
1
+ // Standard 13: components sit at most two levels deep, the component
2
+ // then its sub-components, and the homepage is in app/(homepage)/.
3
+ import path from "node:path";
4
+
5
+ const COMPONENT_FILE_PATTERN = /^[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
6
+ const COMPONENTS_FOLDER = "components";
7
+ const UNGROUPED_HOMEPAGE_PATTERN =
8
+ /^(?:src\/)?app\/page\.(?:tsx|jsx)$/;
9
+ const NESTED_PAGE =
10
+ "docs/Structure/component-organization.md#nested-components";
11
+
12
+ // A component folder holds a PascalCase component file, Card.tsx.
13
+ const listComponentFolders = ({ projectFiles }) =>
14
+ new Set(
15
+ projectFiles
16
+ .filter((filePath) => !filePath.startsWith("node_modules/"))
17
+ .filter((filePath) =>
18
+ COMPONENT_FILE_PATTERN.test(path.posix.basename(filePath)),
19
+ )
20
+ .map((filePath) => path.posix.dirname(filePath)),
21
+ );
22
+
23
+ // The topmost component folder above this one, or undefined for a
24
+ // component that is not inside another.
25
+ const findRootComponent = ({ folder, componentFolders }) => {
26
+ const ancestors = [];
27
+ // eslint-disable-next-line no-restricted-syntax -- walks up one folder at a time
28
+ let parent = path.posix.dirname(folder);
29
+ while (parent !== ".") {
30
+ ancestors.push(parent);
31
+ parent = path.posix.dirname(parent);
32
+ }
33
+ return ancestors.findLast((ancestor) =>
34
+ componentFolders.has(ancestor),
35
+ );
36
+ };
37
+
38
+ // A sub-component's only home is its root component's components/
39
+ // folder: card/components/cardHeader/. Never card/cardHeader/,
40
+ // card/parts/cardHeader/ or card/components/cardHeader/components/.
41
+ const checkSubComponentFolders = ({ componentFolders }) =>
42
+ [...componentFolders]
43
+ .map((folder) => ({
44
+ folder,
45
+ rootComponent: findRootComponent({ folder, componentFolders }),
46
+ }))
47
+ .filter(({ rootComponent }) => rootComponent !== undefined)
48
+ .map(({ folder, rootComponent }) => ({
49
+ folder,
50
+ rootComponent,
51
+ flatFolder: path.posix.join(
52
+ rootComponent,
53
+ COMPONENTS_FOLDER,
54
+ path.posix.basename(folder),
55
+ ),
56
+ }))
57
+ .filter(({ folder, flatFolder }) => folder !== flatFolder)
58
+ .map(({ folder, rootComponent, flatFolder }) => ({
59
+ standard: "13",
60
+ message: `${folder} is not flat in ${rootComponent}/${COMPONENTS_FOLDER}/. Move it to ${flatFolder}`,
61
+ page: NESTED_PAGE,
62
+ }));
63
+
64
+ const checkHomepage = ({ projectFiles }) =>
65
+ projectFiles
66
+ .filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
67
+ .map((filePath) => ({
68
+ standard: "13",
69
+ message: `${filePath} is the homepage outside its route group. Move it to app/(homepage)/`,
70
+ page: "docs/Structure/folder-structure.md#-where-components-live",
71
+ }));
72
+
73
+ export const checkStructure = ({ projectFiles }) => {
74
+ const componentFolders = listComponentFolders({ projectFiles });
75
+ return [
76
+ ...checkSubComponentFolders({ componentFolders }),
77
+ ...checkHomepage({ projectFiles }),
78
+ ];
79
+ };
@@ -5,14 +5,16 @@ import path from "node:path";
5
5
  import { PACKAGE_DIRECTORY } from "./projectFiles.mjs";
6
6
 
7
7
  // The names from the numbered list in docs/Guides/setup.md.
8
- const STANDARD_NAMES = {
8
+ export const STANDARD_NAMES = {
9
9
  4: "Every function and component has a test file",
10
10
  6: "ESLint",
11
11
  7: "Prettier",
12
12
  8: "Stylelint",
13
13
  9: "EditorConfig",
14
14
  10: "Node version",
15
+ 11: "Styling",
15
16
  12.1: "Constants",
17
+ 13: "Components live where they are used",
16
18
  15: "Design System Components",
17
19
  18: "Docs",
18
20
  21: "AGENTS.md and the agent skills",