@activatus/code-standards 3.2.1 → 3.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/Guides/migrating.md +9 -4
- package/docs/Guides/regression-checks.md +1 -0
- package/docs/Guides/setup.md +22 -16
- package/docs/Standards/eslint.md +34 -3
- package/docs/Standards/readable-code.md +30 -1
- package/docs/Standards/working-with-agents.md +5 -1
- package/docs/Structure/folder-structure.md +102 -44
- package/docs/version-history.md +132 -29
- package/package.json +1 -1
- package/scripts/verifyStandards/checkAgentFiles.mjs +50 -8
- package/scripts/verifyStandards/checkConstants.mjs +10 -72
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +5 -1
- package/scripts/verifyStandards/formatReport.mjs +3 -1
- package/scripts/verifyStandards/runChecks.mjs +4 -8
- package/static/templates/AGENTS.md +8 -5
- package/static/templates/docs/development/coding-standards.md +1 -1
- package/static/templates/eslint/nextjs/eslint.config.mjs +11 -0
- package/static/templates/eslint/react/eslint.config.mjs +10 -0
- package/static/templates/eslint/typescript/eslint.config.mjs +10 -0
- package/static/templates/skills/typescript.md +3 -1
- package/static/templates/tests/visual/pageLayout.visual.ts +9 -1
package/docs/version-history.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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. **
|
|
45
|
+
9. **Set the version** in `AGENTS.md` to the installed package's full version once every change is done.
|
|
29
46
|
|
|
30
|
-
**A
|
|
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,47 +52,133 @@ sidebar_label: "Version History"
|
|
|
35
52
|
|
|
36
53
|
Anyone changing the standards adds a version, alongside the change:
|
|
37
54
|
|
|
38
|
-
- **
|
|
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:
|
|
44
|
-
- **
|
|
45
|
-
- **
|
|
46
|
-
- **
|
|
47
|
-
- **
|
|
48
|
-
- **Every
|
|
49
|
-
- **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.
|
|
50
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.
|
|
51
66
|
|
|
52
67
|
---
|
|
53
68
|
|
|
54
69
|
## Version 3
|
|
55
70
|
|
|
56
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest
|
|
71
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.0
|
|
57
72
|
|
|
58
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.
|
|
59
74
|
|
|
75
|
+
**Fixes in 3.3.0.** If the project already applied 3.2.2, check these:
|
|
76
|
+
|
|
77
|
+
**Structural changes in 3.3.0.** These move files. Plan them, and take a [regression check](/docs/Guides/regression-checks) baseline first:
|
|
78
|
+
|
|
79
|
+
- Every type a constant needs moves into `lib/types/`, with the types it depends on: one move per type. A component's `types.ts` left empty is deleted.
|
|
80
|
+
- Every `as const` value found outside `lib/constants/` moves into the constants file that fits, with its type: one move per value. These stay where they are:
|
|
81
|
+
|
|
82
|
+
- values in tests
|
|
83
|
+
- internal strings, as a named constant at the top of the file that uses them
|
|
84
|
+
- a class name only one file uses
|
|
85
|
+
- numbers in config files
|
|
86
|
+
|
|
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).
|
|
88
|
+
|
|
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.
|
|
90
|
+
|
|
91
|
+
- **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
|
+
|
|
93
|
+
**What to do:** copy the project's ESLint template over `eslint.config.mjs` again. Replace each `as const` with a real type where the value is declared. An `as const` value found outside `lib/constants/` moves into the matching constants file with its type. These stay where they are, each given a type:
|
|
94
|
+
|
|
95
|
+
- values in tests
|
|
96
|
+
- internal strings, as a named constant at the top of the file that uses them
|
|
97
|
+
- 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.
|
|
99
|
+
|
|
100
|
+
- **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
|
+
|
|
102
|
+
**What to do:** if the project has a copy of `static/templates/tests/visual/pageLayout.visual.ts`, copy the new one over it. In a project's own visual test, replace any `as const` with a real type. Run the regression check against the existing baseline: it must pass unchanged.
|
|
103
|
+
|
|
104
|
+
**How to check:** `pnpm lint` and `pnpm typecheck` pass; these searches find nothing:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# lib/types/ reading constants through the barrel
|
|
108
|
+
grep -rn 'from "@/lib/constants"' lib/types/
|
|
109
|
+
# as const anywhere in code we write
|
|
110
|
+
grep -rn "as const" --include='*.ts' --include='*.tsx' --exclude-dir=node_modules --exclude-dir=vendor .
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
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
|
+
|
|
115
|
+
```bash
|
|
116
|
+
grep -rnE "(^|[^y] )[A-Z][A-Za-z]*Type\[\]" lib/types/
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
|
|
120
|
+
|
|
121
|
+
- **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.
|
|
122
|
+
|
|
123
|
+
**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.
|
|
124
|
+
|
|
125
|
+
- **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.
|
|
126
|
+
|
|
127
|
+
- **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.
|
|
128
|
+
|
|
129
|
+
**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`.
|
|
130
|
+
|
|
131
|
+
- **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).
|
|
132
|
+
|
|
133
|
+
**What to do:** move each loose id constant into the object that uses it.
|
|
134
|
+
|
|
135
|
+
- **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`.
|
|
136
|
+
|
|
137
|
+
**What to do:** move any CSS string out of `lib/constants/` and components into `globals.css`.
|
|
138
|
+
|
|
139
|
+
- **`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.
|
|
140
|
+
|
|
141
|
+
**What to do:** nothing, unless the project moved internal strings into `s`. Move those back beside the code that uses them.
|
|
142
|
+
|
|
143
|
+
- **`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.
|
|
144
|
+
|
|
145
|
+
- **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).
|
|
146
|
+
|
|
147
|
+
- **`pnpm standards:check` reports headings for standards 11 and 13**, which 3.2.1 printed blank. Nothing to do.
|
|
148
|
+
|
|
149
|
+
- **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).
|
|
150
|
+
|
|
151
|
+
**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`.
|
|
152
|
+
|
|
153
|
+
**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:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
# CSS written in TypeScript, however it is quoted, on one line or many
|
|
157
|
+
grep -rnE "@media|@keyframes|!important|[a-z-]+: *[^;,]*(px|rem|none|auto|block|flex|grid);" \
|
|
158
|
+
lib/constants/ app/ components/ --include='*.ts' --include='*.tsx' --exclude='*.test.*'
|
|
159
|
+
# A loose id constant
|
|
160
|
+
grep -rnE "export const [A-Z_]+_ID = " lib/constants/
|
|
161
|
+
```
|
|
162
|
+
|
|
60
163
|
**Fixes in 3.2.1.** If the project already applied 3.2.0, check these:
|
|
61
164
|
|
|
62
165
|
**Structural changes in 3.2.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
|
|
63
166
|
|
|
64
|
-
- Every component `constants.ts
|
|
65
|
-
-
|
|
167
|
+
- 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.
|
|
168
|
+
- 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.
|
|
66
169
|
|
|
67
170
|
- **`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:
|
|
68
|
-
- **`animation.ts`**: how
|
|
69
|
-
- **`artwork.ts`**: what is drawn
|
|
70
|
-
- **`classNames.ts`**: Tailwind class
|
|
171
|
+
- **`animation.ts`**: how and when things move.
|
|
172
|
+
- **`artwork.ts`**: what is drawn, where it ends up, and how it is grouped.
|
|
173
|
+
- **`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.
|
|
71
174
|
|
|
72
|
-
Each animation and artwork object stays whole, its
|
|
175
|
+
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).
|
|
73
176
|
|
|
74
|
-
**What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files.
|
|
177
|
+
**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.
|
|
75
178
|
|
|
76
|
-
- **A loop over a list looks each item up by its
|
|
179
|
+
- **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).
|
|
77
180
|
|
|
78
|
-
- **`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
|
|
181
|
+
- **`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.
|
|
79
182
|
|
|
80
183
|
- **Keep every docs folder.** 3.2.0's rule is final: no docs folder is deleted, even one that does not apply yet.
|
|
81
184
|
|
|
@@ -100,8 +203,8 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
|
|
|
100
203
|
|
|
101
204
|
- The homepage moves into `app/(homepage)/`: `app/page.tsx` and the homepage's components. Small.
|
|
102
205
|
- The site frame moves into `components/layout/`: the navigation, header and footer. Small.
|
|
103
|
-
- Every component `constants.ts` moves into `lib/constants
|
|
104
|
-
- Every nested sub-component folder moves flat into its parent's `components/` folder
|
|
206
|
+
- Every component `constants.ts` moves into `lib/constants/`: one move per file. Follow the 3.2.1 rule, not this version's.
|
|
207
|
+
- Every nested sub-component folder moves flat into its parent's `components/` folder: one move per folder.
|
|
105
208
|
- `r` or `s` split into several files only to stay under 300 lines goes back into one file. Small.
|
|
106
209
|
|
|
107
210
|
- **`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:
|
|
@@ -132,7 +235,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
|
|
|
132
235
|
- **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._
|
|
133
236
|
- **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).
|
|
134
237
|
- **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
|
|
135
|
-
- **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
|
|
238
|
+
- **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant. _Withdrawn in 3.3.0: constants now take their types from `lib/types/`. Do the 3.3.0 step instead._
|
|
136
239
|
- **Create `noData.ts` only once the data's shape is decided.** An empty `noData.ts` can be deleted. Stand-in data asked for earlier carries the comment `// Not the real schema: a basic shape to finish the task.`
|
|
137
240
|
- **A component's sub-components sit flat in its one `components/` folder**, two levels at most. Move any sub-component folder sitting directly in its parent, or nested inside another sub-component, into the parent's `components/` folder.
|
|
138
241
|
- **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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.3.0",
|
|
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 =
|
|
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
|
|
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
|
|
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 =
|
|
45
|
-
if (projectVersion <
|
|
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 ${
|
|
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
|
-
|
|
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,
|
|
186
|
+
...checkVersion({ agentsText, packageVersion }),
|
|
145
187
|
...checkStandardsSection({ agentsText, templatesDirectory }),
|
|
146
188
|
...checkSkills({ projectDirectory, templatesDirectory }),
|
|
147
189
|
];
|
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
// Standard 12.1: lib/constants/ holds the seven standard files and
|
|
2
2
|
// nothing else, and no component keeps its own constants file.
|
|
3
|
-
import { readTextFile } from "./projectFiles.mjs";
|
|
4
|
-
|
|
5
3
|
const REQUIRED_FILES = [
|
|
6
4
|
"lib/constants/index.ts",
|
|
7
5
|
"lib/constants/routes.ts",
|
|
@@ -18,67 +16,10 @@ const OPTIONAL_FILES = [
|
|
|
18
16
|
const CONSTANTS_FOLDER = "lib/constants/";
|
|
19
17
|
const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
|
|
20
18
|
const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
|
|
21
|
-
const EXPORT_PATTERN =
|
|
22
|
-
/^export const ([\w$]+)\s*(?::[^=]+)?=\s*(\S)/gm;
|
|
23
|
-
const MAXIMUM_NAMES_SHOWN = 3;
|
|
24
19
|
const PAGE = "docs/Structure/folder-structure.md#constants";
|
|
25
|
-
|
|
26
|
-
const
|
|
27
|
-
|
|
28
|
-
// The name says what most exports are; the first character of the
|
|
29
|
-
// value settles the rest. Checked in this order.
|
|
30
|
-
const NAME_HOMES = [
|
|
31
|
-
{ pattern: /CLASS_NAMES?$/, home: "classNames.ts" },
|
|
32
|
-
{
|
|
33
|
-
pattern:
|
|
34
|
-
/MOTION|ANIMATION|ENTRANCE|SCROLL|DRIFT|ZOOM|EASE|SPRING|TRANSITION|KEYFRAME|QUERY|QUERIES/,
|
|
35
|
-
home: "animation.ts",
|
|
36
|
-
},
|
|
37
|
-
{
|
|
38
|
-
pattern:
|
|
39
|
-
/ARTWORK|LAYOUT|SHAPE|PATH|CANVAS|TILE|IMAGE|PIECE|GEOMETRY|SVG/,
|
|
40
|
-
home: "artwork.ts",
|
|
41
|
-
},
|
|
42
|
-
{ pattern: /ROUTE|HREF|LINK|URL/, home: "r in routes.ts" },
|
|
43
|
-
{ pattern: /^NO_DATA_|^DUMMY_/, home: "noData.ts" },
|
|
44
|
-
// Raw CSS is not text for s, and not a class name.
|
|
45
|
-
{ pattern: /STYLES?$/, home: UNSURE_HOME },
|
|
46
|
-
];
|
|
47
|
-
const VALUE_HOMES = [
|
|
48
|
-
{ pattern: /[\d-]/, home: "numbers.ts" },
|
|
49
|
-
{ pattern: /["'`]/, home: "s in strings.ts" },
|
|
50
|
-
];
|
|
51
|
-
|
|
52
|
-
const findHome = ({ name, valueStart }) =>
|
|
53
|
-
NAME_HOMES.find(({ pattern }) => pattern.test(name))?.home ??
|
|
54
|
-
VALUE_HOMES.find(({ pattern }) => pattern.test(valueStart))?.home ??
|
|
55
|
-
UNSURE_HOME;
|
|
56
|
-
|
|
57
|
-
const describeNames = (names) => {
|
|
58
|
-
const shown = names.slice(0, MAXIMUM_NAMES_SHOWN).join(", ");
|
|
59
|
-
const hiddenCount = names.length - MAXIMUM_NAMES_SHOWN;
|
|
60
|
-
return hiddenCount > 0 ? `${shown} and ${hiddenCount} more` : shown;
|
|
61
|
-
};
|
|
62
|
-
|
|
63
|
-
// "Move CONFIDENCE_MOTION to animation.ts; CARD_FACE_CLASS_NAME to
|
|
64
|
-
// classNames.ts".
|
|
65
|
-
const suggestHomes = ({ projectDirectory, filePath }) => {
|
|
66
|
-
const source = readTextFile({ projectDirectory, filePath }) ?? "";
|
|
67
|
-
// Map.groupBy needs Node 21, and the package supports Node 20.
|
|
68
|
-
const namesByHome = new Map();
|
|
69
|
-
for (const [, name, valueStart] of source.matchAll(
|
|
70
|
-
EXPORT_PATTERN,
|
|
71
|
-
)) {
|
|
72
|
-
const home = findHome({ name, valueStart });
|
|
73
|
-
namesByHome.set(home, [...(namesByHome.get(home) ?? []), name]);
|
|
74
|
-
}
|
|
75
|
-
const moves = [...namesByHome].map(
|
|
76
|
-
([home, names]) => `${describeNames(names)} to ${home}`,
|
|
77
|
-
);
|
|
78
|
-
return moves.length > 0
|
|
79
|
-
? `Move ${moves.join("; ")}`
|
|
80
|
-
: "Move its values into the seven files in lib/constants/";
|
|
81
|
-
};
|
|
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";
|
|
82
23
|
|
|
83
24
|
const checkMissingFiles = ({ projectFileSet }) =>
|
|
84
25
|
REQUIRED_FILES.filter(
|
|
@@ -89,7 +30,7 @@ const checkMissingFiles = ({ projectFileSet }) =>
|
|
|
89
30
|
page: PAGE,
|
|
90
31
|
}));
|
|
91
32
|
|
|
92
|
-
const checkExtraFiles = ({
|
|
33
|
+
const checkExtraFiles = ({ projectFiles }) => {
|
|
93
34
|
const standardFiles = new Set([
|
|
94
35
|
...REQUIRED_FILES,
|
|
95
36
|
...OPTIONAL_FILES,
|
|
@@ -101,27 +42,24 @@ const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
|
|
|
101
42
|
.filter((filePath) => !standardFiles.has(filePath))
|
|
102
43
|
.map((filePath) => ({
|
|
103
44
|
standard: "12.1",
|
|
104
|
-
message: `${filePath} is not one of the seven constants files. ${
|
|
45
|
+
message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
|
|
105
46
|
page: PAGE,
|
|
106
47
|
}));
|
|
107
48
|
};
|
|
108
49
|
|
|
109
|
-
const checkComponentFiles = ({
|
|
50
|
+
const checkComponentFiles = ({ projectFiles }) =>
|
|
110
51
|
projectFiles
|
|
111
52
|
.filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
|
|
112
53
|
.filter((filePath) => !filePath.startsWith("node_modules/"))
|
|
113
54
|
.filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
|
|
114
55
|
.map((filePath) => ({
|
|
115
56
|
standard: "12.1",
|
|
116
|
-
message: `${filePath}: there is no component-level constants file. ${
|
|
57
|
+
message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
|
|
117
58
|
page: PAGE,
|
|
118
59
|
}));
|
|
119
60
|
|
|
120
|
-
export const checkConstants = ({
|
|
121
|
-
projectDirectory,
|
|
122
|
-
projectFiles,
|
|
123
|
-
}) => [
|
|
61
|
+
export const checkConstants = ({ projectFiles }) => [
|
|
124
62
|
...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
|
|
125
|
-
...checkExtraFiles({
|
|
126
|
-
...checkComponentFiles({
|
|
63
|
+
...checkExtraFiles({ projectFiles }),
|
|
64
|
+
...checkComponentFiles({ projectFiles }),
|
|
127
65
|
];
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// What setup asks the person and writes down: the
|
|
1
|
+
// What setup asks the person and writes down: the five agent answers
|
|
2
2
|
// (standard 21) and the colour palette (standard 11).
|
|
3
3
|
import {
|
|
4
4
|
CODING_STANDARDS_PATH,
|
|
@@ -12,6 +12,10 @@ const AGENT_ANSWERS = [
|
|
|
12
12
|
{ name: "the Linear project", pattern: /linear/i },
|
|
13
13
|
{ name: "the status circles", pattern: /status circles?/i },
|
|
14
14
|
{ name: "asking before committing", pattern: /commit/i },
|
|
15
|
+
{
|
|
16
|
+
name: "being told about decisions",
|
|
17
|
+
pattern: /told about decisions/i,
|
|
18
|
+
},
|
|
15
19
|
];
|
|
16
20
|
// The template's unfilled line: "[link or None]", "[yes or no]".
|
|
17
21
|
const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
|
|
@@ -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",
|
|
@@ -17,16 +17,12 @@ import {
|
|
|
17
17
|
readRecordedExceptions,
|
|
18
18
|
} from "./projectFiles.mjs";
|
|
19
19
|
|
|
20
|
-
const
|
|
20
|
+
const readPackageVersion = () => {
|
|
21
21
|
const packageText = readFileSync(
|
|
22
22
|
path.join(PACKAGE_DIRECTORY, "package.json"),
|
|
23
23
|
"utf8",
|
|
24
24
|
);
|
|
25
|
-
|
|
26
|
-
".",
|
|
27
|
-
1,
|
|
28
|
-
);
|
|
29
|
-
return Number(majorVersion);
|
|
25
|
+
return JSON.parse(packageText).version;
|
|
30
26
|
};
|
|
31
27
|
|
|
32
28
|
export const runChecks = ({ projectDirectory }) => {
|
|
@@ -43,11 +39,11 @@ export const runChecks = ({ projectDirectory }) => {
|
|
|
43
39
|
...checkAgentFiles({
|
|
44
40
|
projectDirectory,
|
|
45
41
|
templatesDirectory,
|
|
46
|
-
|
|
42
|
+
packageVersion: readPackageVersion(),
|
|
47
43
|
}),
|
|
48
44
|
...checkConfigFiles({ projectDirectory, templatesDirectory }),
|
|
49
45
|
...checkRequiredFiles({ templatesDirectory, projectFiles }),
|
|
50
|
-
...checkConstants({
|
|
46
|
+
...checkConstants({ projectFiles }),
|
|
51
47
|
...checkStructure({ projectFiles }),
|
|
52
48
|
...checkRecordedAnswers({ projectDirectory }),
|
|
53
49
|
...checkComponents({
|
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
[How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
|
|
43
43
|
|
|
44
44
|
- **Who commits**: [whether AI agents may commit, push or make branches, and when. If the person said yes to asking before committing during setup: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, leave the asking rule out]
|
|
45
|
+
- **Decisions**: [Optional. If the person said yes to being told about decisions during setup: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." Delete this line if they said no]
|
|
45
46
|
- **Branches**: [how branches are named]
|
|
46
47
|
- **Commit messages**: [the commit message format]
|
|
47
48
|
- **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
|
|
@@ -109,13 +110,15 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
|
|
|
109
110
|
|
|
110
111
|
This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
|
|
111
112
|
|
|
112
|
-
**Code standards version:** [the
|
|
113
|
+
**Code standards version:** [the full version of the installed `@activatus/code-standards` package when the standards were last applied, such as 3.2.2]
|
|
113
114
|
|
|
114
|
-
This is the version the code follows
|
|
115
|
+
This is the version the code follows, written in full so it pairs with the installed package. When the package is updated, read only the entries newer than this number in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
|
|
116
|
+
|
|
117
|
+
**The standards are the base, and you build freely from there.** Most of a project's code is something the standards never mention: decide it yourself, and keep the decision the same across the codebase. This covers how the code is built: its structure, names, files and where each value goes. It never covers what the product does, says or shows: those are product decisions, and you ask. Only skipping, loosening or changing a standard needs the person's yes.
|
|
115
118
|
|
|
116
119
|
**Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
|
|
117
120
|
|
|
118
|
-
**The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
|
|
121
|
+
**The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change and keep going. Never stop the work to wait for a new version of the standards. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
|
|
119
122
|
|
|
120
123
|
Follow these rules in every change:
|
|
121
124
|
|
|
@@ -146,11 +149,11 @@ Follow these rules in every change:
|
|
|
146
149
|
- **One parameter per function.** Use a single object when more than one value is needed.
|
|
147
150
|
- **Return early.** Never nest more than three levels deep.
|
|
148
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`.
|
|
149
|
-
- **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
|
|
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
|
|
150
153
|
- **No nested ternaries. No boolean flag parameters.**
|
|
151
154
|
- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
|
|
152
155
|
- **Named exports only**, except where a tool requires a default export.
|
|
153
|
-
- **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`. Every function still has its own `Props` for its single object parameter, such as `LaunchSessionProps` for `launchSession`, used wherever that function is written: `async ({ worktreePath }: LaunchSessionProps) =>`. Type a value where it is declared, never afterwards with `satisfies`. The one exception is Storybook story files, which follow Storybook's docs: `satisfies Meta<typeof Component>`.
|
|
156
|
+
- **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`. Every function still has its own `Props` for its single object parameter, such as `LaunchSessionProps` for `launchSession`, used wherever that function is written: `async ({ worktreePath }: LaunchSessionProps) =>`. Type a value where it is declared, never afterwards with `satisfies`, and never `as const`: when the code needs exact values, put them in the type. A constant's list type is `readonly`. The one exception is Storybook story files, which follow Storybook's docs: `satisfies Meta<typeof Component>`.
|
|
154
157
|
- **One component per file.** Server and client components live in separate files.
|
|
155
158
|
- **A component's children sit flat in its own `components/` folder**, `accordion/components/item/` and `accordion/components/ctaArrow/`, even when one child is only used by another. Never a `components/` folder inside a child: two levels at most.
|
|
156
159
|
- **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
|