@activatus/code-standards 3.1.1 → 3.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/Guides/migrating.md +92 -60
- package/docs/Guides/regression-checks.md +72 -0
- package/docs/Guides/setup.md +53 -17
- package/docs/Standards/documentation.md +38 -1
- package/docs/Standards/eslint.md +15 -13
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +98 -6
- package/docs/templates.mdx +10 -2
- package/docs/version-history.md +54 -7
- package/package.json +6 -2
- package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
- package/scripts/verifyStandards/checkComponents.mjs +129 -0
- package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
- package/scripts/verifyStandards/checkConstants.mjs +127 -0
- package/scripts/verifyStandards/checkDocs.mjs +86 -0
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +83 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +67 -0
- package/scripts/verifyStandards/checkStructure.mjs +79 -0
- package/scripts/verifyStandards/formatReport.mjs +76 -0
- package/scripts/verifyStandards/projectFiles.mjs +109 -0
- package/scripts/verifyStandards/runChecks.mjs +68 -0
- package/scripts/verifyStandards/verifyStandards.mjs +22 -0
- package/static/templates/AGENTS.md +4 -4
- package/static/templates/docs/development/coding-standards.md +6 -0
- package/static/templates/docs/overview/writing-docs.md +4 -0
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +4 -3
- package/static/templates/eslint/react/eslint.config.mjs +4 -3
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
- package/static/templates/tests/visual/playwright.config.mjs +65 -0
- package/static/templates/tests/visual/visualPages.mjs +3 -0
package/docs/Guides/migrating.md
CHANGED
|
@@ -4,9 +4,40 @@ sidebar_position: 3
|
|
|
4
4
|
|
|
5
5
|
# Migrating an Existing Project
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Moving an established codebase onto the standards is done in stages, so each change stays small enough to check properly. This is the order that worked on a real 600-file project.
|
|
8
8
|
|
|
9
|
-
**Already following the standards, and just updating to a newer version?** You don't need this
|
|
9
|
+
**Already following the standards, and just updating to a newer version?** You don't need this guide. Read the [Version History](/docs/version-history) from your project's version onward, and do only what it lists.
|
|
10
|
+
|
|
11
|
+
**Agree the standards first.** Print the list in [Setup, step 3](/docs/Guides/setup#3-agree-the-standards), and ask the [step 4](/docs/Guides/setup#4-working-with-the-agent) questions. Skip any stage for a standard the person turned down.
|
|
12
|
+
|
|
13
|
+
## The stages
|
|
14
|
+
|
|
15
|
+
| Stage | What | Setup standard | Why this order |
|
|
16
|
+
| ----- | ---------------------------------------------------------------------- | -------------- | --------------------------------------------------------- |
|
|
17
|
+
| 0 | [Regression check](#stage-0--regression-check) | — | Every later stage is measured against it |
|
|
18
|
+
| 1 | [Formatting](#stage-1--formatting) | 7, 9, 10 | The reformat touches every file, so it goes first, alone |
|
|
19
|
+
| 2 | [ESLint](#stage-2--eslint) | 6 | Fix the code, never the rules |
|
|
20
|
+
| 3 | [Names](#stage-3--names) | 1 | The lint errors show most of the names to change |
|
|
21
|
+
| 4 | [Constants](#stage-4--constants) | 12.1 | Components move next, and will import these |
|
|
22
|
+
| 5 | [Components](#stage-5--components) | 12, 13, 14 | Pure moves first, then shared code, which needs the paths |
|
|
23
|
+
| 6 | [Docs](#stage-6--docs) | 18 | The mechanical copy first, then the rewrite |
|
|
24
|
+
| 7 | [AGENTS.md, skills and version](#stage-7--agentsmd-skills-and-version) | 21 | Describes the final layout, so it goes last |
|
|
25
|
+
|
|
26
|
+
## How to work through the stages
|
|
27
|
+
|
|
28
|
+
- **One branch per stage, stacked.** Each stage branches from the one before it. Stop after each stage for the person to review and commit. This is what keeps a large migration reviewable.
|
|
29
|
+
- **Each stage changes one kind of thing.** A stage that moves files does not also change what they do.
|
|
30
|
+
- **Run `pnpm lint`, `pnpm format:check`, the tests and the build at the end of every stage**, and the regression check from Stage 0 if the project has one.
|
|
31
|
+
- **Record anything left for later** under "Unfinished changes" in `docs/development/coding-standards.md`. See [Finishing a change later](/docs/Guides/setup#finishing-a-change-later).
|
|
32
|
+
|
|
33
|
+
:::warning[Squash merges lose the reformat commit]
|
|
34
|
+
|
|
35
|
+
If the project squash-merges pull requests, the reformat commit's hash disappears from `main` when the stack is merged, and `.git-blame-ignore-revs` stops working. Decide before starting:
|
|
36
|
+
|
|
37
|
+
- **Land Stages 0 and 1 on `main` by themselves first**, with a merge that keeps the commits, so the reformat survives as its own commit. Then stack the rest on top. Recommended.
|
|
38
|
+
- **Or accept losing blame-ignore**, and squash everything.
|
|
39
|
+
|
|
40
|
+
:::
|
|
10
41
|
|
|
11
42
|
## Before you start: third-party code is exempt
|
|
12
43
|
|
|
@@ -17,70 +48,54 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
|
|
|
17
48
|
- Add `vendor/` to `.prettierignore` too.
|
|
18
49
|
- **shadcn components are not third-party.** They are our code: convert them to the standards rather than moving them to `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
|
|
19
50
|
|
|
20
|
-
## Stage
|
|
21
|
-
|
|
22
|
-
Applies setup standard 7.
|
|
23
|
-
|
|
24
|
-
Formatting changes are safe to make all at once because they don't change behaviour.
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
pnpm add -D prettier prettier-plugin-tailwindcss
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Add `prettier.config.mjs` — see the [Prettier page](/docs/Standards/prettier) for the full file contents.
|
|
51
|
+
## Stage 0 — Regression check
|
|
31
52
|
|
|
32
|
-
|
|
53
|
+
Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **live production site**, before anything changes. Every later stage must pass it unchanged.
|
|
33
54
|
|
|
34
|
-
|
|
35
|
-
pnpm format
|
|
36
|
-
```
|
|
55
|
+
## Stage 1 — Formatting
|
|
37
56
|
|
|
38
|
-
|
|
57
|
+
Applies setup standards 7, 9 and 10. Three commits, in this order:
|
|
39
58
|
|
|
40
|
-
|
|
59
|
+
1. **The config files.** Rename every config to `.mjs` ([why](/docs/Guides/setup#5-apply-the-standards)). Add `prettier.config.mjs` from the [Prettier page](/docs/Standards/prettier), with its `format` and `format:check` scripts, `.editorconfig`, `.nvmrc` and `.envrc`. Do not reformat anything yet.
|
|
41
60
|
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
coverage/
|
|
46
|
-
vendor/
|
|
47
|
-
*.generated.ts
|
|
48
|
-
```
|
|
61
|
+
```bash
|
|
62
|
+
pnpm add -D prettier prettier-plugin-tailwindcss
|
|
63
|
+
```
|
|
49
64
|
|
|
50
|
-
|
|
65
|
+
2. **The reformat, on its own.** Run `pnpm format` and commit the result with nothing else in it. Every file changes, and none of it changes behaviour.
|
|
66
|
+
3. **`.git-blame-ignore-revs`.** Create it with the reformat commit's full hash and a comment saying what it was. GitHub reads it automatically. For local `git blame`, each person runs once:
|
|
51
67
|
|
|
52
|
-
|
|
68
|
+
```bash
|
|
69
|
+
git config blame.ignoreRevsFile .git-blame-ignore-revs
|
|
70
|
+
```
|
|
53
71
|
|
|
54
|
-
Add
|
|
72
|
+
Add a `.prettierignore` for generated files and anything Prettier must not format. See [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
|
|
55
73
|
|
|
56
|
-
## Stage
|
|
74
|
+
## Stage 2 — ESLint
|
|
57
75
|
|
|
58
76
|
Applies setup standard 6.
|
|
59
77
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```js
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
prettier,
|
|
78
|
+
Copy the [standard config](/docs/Standards/eslint) for the project's framework to `eslint.config.mjs`, unchanged, and `eslint.overrides.mjs` beside it. To see the size of the job first, turn the noisiest rules down to warnings **in `eslint.overrides.mjs`**, never in `eslint.config.mjs`:
|
|
79
|
+
|
|
80
|
+
```js title="eslint.overrides.mjs"
|
|
81
|
+
// Temporary, while migrating: see Unfinished changes in
|
|
82
|
+
// docs/development/coding-standards.md.
|
|
83
|
+
export const projectOverrides = [
|
|
84
|
+
{
|
|
85
|
+
rules: {
|
|
86
|
+
"@typescript-eslint/no-explicit-any": "warn",
|
|
87
|
+
"unicorn/filename-case": "warn",
|
|
88
|
+
"unicorn/name-replacements": "warn",
|
|
89
|
+
},
|
|
90
|
+
},
|
|
74
91
|
];
|
|
75
|
-
|
|
76
|
-
export default config;
|
|
77
92
|
```
|
|
78
93
|
|
|
79
|
-
Run `pnpm lint
|
|
94
|
+
Record the temporary warnings under "Unfinished changes". Run `pnpm lint`, and fix one kind of error at a time, such as every `any`. **Fix the code, not the rules.** When the warnings are gone, empty `eslint.overrides.mjs` again.
|
|
80
95
|
|
|
81
|
-
## Stage
|
|
96
|
+
## Stage 3 — Names
|
|
82
97
|
|
|
83
|
-
Applies setup standard 1.
|
|
98
|
+
Applies setup standard 1. Its own branch, after ESLint: the lint errors show most of the names to change.
|
|
84
99
|
|
|
85
100
|
Renaming is the biggest job in most migrations, and the easiest place to get confused. Every name we write becomes [Human-Readable Names](/docs/Standards/human-readable-names). Work through it in this order.
|
|
86
101
|
|
|
@@ -160,26 +175,43 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
|
|
|
160
175
|
- **It cannot reach keys in plain object literals that aren't typed**, such as the expected value in a test's `toEqual({ properties: … })`. Search the tests for the old name and fix those keys by hand.
|
|
161
176
|
- **Run the type check and tests after each batch** of renames.
|
|
162
177
|
|
|
163
|
-
## Stage
|
|
178
|
+
## Stage 4 — Constants
|
|
164
179
|
|
|
165
|
-
Applies setup standard
|
|
180
|
+
Applies setup standard 12.1. Move every link into `r`, every piece of text into `s`, every loose number into `numbers.ts`, motion into `animation.ts`, drawing layouts into `artwork.ts`, and class names shared between files into `classNames.ts`, all in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
|
|
166
181
|
|
|
167
|
-
|
|
182
|
+
- **Move the values, nothing else.** The page must look and work exactly as before.
|
|
183
|
+
- **No component-level `constants.ts` survives this stage.**
|
|
184
|
+
- **Move motion and artwork objects whole.** Never pull their numbers out into `numbers.ts`. A topic file such as `motion.ts` or `durations.ts` is renamed or folded into the matching standard file.
|
|
185
|
+
- **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its id: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete lookup objects such as `PLAN_ROUTES`.
|
|
186
|
+
- **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
|
|
168
187
|
|
|
169
|
-
## Stage
|
|
188
|
+
## Stage 5 — Components
|
|
170
189
|
|
|
171
|
-
Applies setup
|
|
190
|
+
Applies setup standards 12, 13 and 14. Two branches:
|
|
191
|
+
|
|
192
|
+
1. **5a: move the component folders, and nothing else.** Use `git mv` so the history follows, and rewrite the import paths. No code inside a file changes. Pure moves are quick to review. Follow [Where components live](/docs/Structure/folder-structure#-where-components-live): the homepage in `app/(homepage)/`, the site frame in `components/layout/`, and no `components/features/`.
|
|
193
|
+
2. **5b: move the code several components share** to its standard home, now that the final paths are known: a shared component up one level, a hook beside the component that owns it, and sort, find, get, filter and format functions into `utils/`. Sub-components sit flat in their parent's `components/` folder.
|
|
194
|
+
|
|
195
|
+
## Stage 6 — Docs
|
|
172
196
|
|
|
173
|
-
|
|
197
|
+
Applies setup standard 18. Two branches:
|
|
174
198
|
|
|
175
|
-
|
|
199
|
+
1. **6a: the mechanical part.** Copy the [doc templates](/docs/templates#document-templates) and the [`docsSite/` viewer](/docs/Standards/documentation#-setting-it-up), move images into `docs/assets/`, and delete the old viewer's leftovers.
|
|
200
|
+
2. **6b: rewrite the content as Decision Docs.** This is the part that needs judgement, so it is reviewed on its own. Follow [Converting existing docs](/docs/Standards/documentation#-converting-existing-docs).
|
|
176
201
|
|
|
177
|
-
|
|
202
|
+
**Keep every docs folder and file from the templates, even ones that do not apply yet.** This rule is final: no docs folder is deleted, whatever the size of the project. See [Setting it up](/docs/Standards/documentation#-setting-it-up).
|
|
203
|
+
|
|
204
|
+
## Stage 7 — AGENTS.md, skills and version
|
|
205
|
+
|
|
206
|
+
Applies setup standard 21.
|
|
178
207
|
|
|
179
|
-
|
|
208
|
+
1. Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. It describes the final layout, so it goes last.
|
|
209
|
+
2. Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
|
|
210
|
+
3. Set `**Code standards version:**` from the [Version History](/docs/version-history).
|
|
211
|
+
4. Run the [standards check](/docs/Guides/setup#checking-a-project), and fix what it finds.
|
|
180
212
|
|
|
181
213
|
## Tips
|
|
182
214
|
|
|
183
215
|
- **Don't mix formatting and logic changes.** Reformat on its own, then change the code.
|
|
184
|
-
- **
|
|
185
|
-
- **
|
|
216
|
+
- **Generated files** are ignored with an entry in `eslint.overrides.mjs`, such as `{ ignores: ["generated/**"] }`, and a line in `.prettierignore`. Record the reason in `coding-standards.md`.
|
|
217
|
+
- **New files follow the full standards from day one**, even before the migration is finished.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 4
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Regression Checks for Refactors
|
|
6
|
+
|
|
7
|
+
A refactor that moves code around should change nothing a visitor can see. The regression check proves it: it measures every page before and after, and fails on any difference.
|
|
8
|
+
|
|
9
|
+
**It is optional.** Use it for large refactors that are meant to change nothing visible, such as Stages 4 to 6 of [Migrating an Existing Project](/docs/Guides/migrating). A normal feature change does not need it.
|
|
10
|
+
|
|
11
|
+
## What it checks
|
|
12
|
+
|
|
13
|
+
On each page in `tests/visual/visualPages.mjs`, at every half-screen scroll stop, in four sizes (desktop 1440×900, tablet 768×1024, mobile 390×844, and desktop with reduced motion):
|
|
14
|
+
|
|
15
|
+
| Measurement | Must match the baseline to |
|
|
16
|
+
| ------------------------ | -------------------------- |
|
|
17
|
+
| Every element's box | 1 pixel |
|
|
18
|
+
| Every element's opacity | 0.02 |
|
|
19
|
+
| The number of elements | Exactly |
|
|
20
|
+
| The page height | Exactly |
|
|
21
|
+
| A screenshot of the stop | 0.5% of pixels |
|
|
22
|
+
|
|
23
|
+
So every run sees the same thing, the page clock is frozen and moved on by hand, finite CSS animations are finished, and images are decoded before measuring.
|
|
24
|
+
|
|
25
|
+
## Setting it up
|
|
26
|
+
|
|
27
|
+
1. **Install Playwright:**
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm add -D @playwright/test
|
|
31
|
+
pnpm exec playwright install chromium
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
2. **Copy `static/templates/tests/visual/`** to `tests/visual/` in the project, and list the pages to check in `visualPages.mjs`.
|
|
35
|
+
3. **Add the scripts** to `package.json`:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"scripts": {
|
|
40
|
+
"test:visual": "playwright test --config tests/visual/playwright.config.mjs",
|
|
41
|
+
"test:visual:update": "VISUAL_UPDATE=true playwright test --config tests/visual/playwright.config.mjs --update-snapshots"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
4. **Freeze the test files.** Add `tests/visual/` to `.prettierignore`, and add this line to the project's `AGENTS.md`, outside the code standards section: "Never edit `tests/visual/` or update its baseline without the person's yes."
|
|
47
|
+
5. **Take the baseline from the live production site**, before the refactor starts:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
VISUAL_PRODUCTION_URL=https://example.com pnpm test:visual:update
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Commit `tests/visual/baseline/`.
|
|
54
|
+
|
|
55
|
+
## Running it
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pnpm test:visual
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
It builds the project and starts the production build on port 3100, then measures it against the baseline. **It rebuilds on every run**, so a stale build is never measured. Run it at the end of every refactor stage.
|
|
62
|
+
|
|
63
|
+
## Rules
|
|
64
|
+
|
|
65
|
+
- **The baseline comes from the live production site**, never from the branch being tested. A baseline taken from the branch would only prove the branch matches itself.
|
|
66
|
+
- **It runs against a production build**, on its own port, never against `pnpm dev`.
|
|
67
|
+
- **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
|
|
68
|
+
- **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
|
|
69
|
+
|
|
70
|
+
## The blind spot
|
|
71
|
+
|
|
72
|
+
**A frozen clock only samples fixed moments.** The check measures each scroll stop after moving the clock on by the same amount every time. A change to the timing between those moments, such as an animation that now runs slower but ends in the same place, passes. When a refactor touches animation timing, check those parts by eye as well.
|
package/docs/Guides/setup.md
CHANGED
|
@@ -83,7 +83,7 @@ Tell me the numbers to skip or change, or say "all good".
|
|
|
83
83
|
10. Node version set by .nvmrc and direnv
|
|
84
84
|
11. Styling: Tailwind, flexbox first, colours only from the global palette
|
|
85
85
|
12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
|
|
86
|
-
12.1. Constants: r for every link, s for every piece of text, every number in numbers.ts, noData for stand-in data, all in lib/constants/
|
|
86
|
+
12.1. Constants: r for every link, s for every piece of text, every loose number in numbers.ts, noData for stand-in data, animation, artwork and shared class names in their own files, all in lib/constants/
|
|
87
87
|
13. Components live where they are used: components/ui/, components/shared/, or beside their page
|
|
88
88
|
14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
|
|
89
89
|
15. Design System Components: every project builds the standard components with the same props
|
|
@@ -148,7 +148,7 @@ Would you like AI to ask you before every commit and push
|
|
|
148
148
|
to git? Yes or no?
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
-
**Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "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, write nothing about it: the agent uses its own judgement. Write all four answers in `docs/development/coding-standards.md`, under "Details", so a later update knows not to ask again
|
|
151
|
+
**Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "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, write nothing about it: the agent uses its own judgement. Write all four answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
|
|
152
152
|
|
|
153
153
|
## 5. Apply the standards
|
|
154
154
|
|
|
@@ -158,24 +158,24 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
|
|
|
158
158
|
|
|
159
159
|
**An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
|
|
160
160
|
|
|
161
|
-
| Standard | What to set up
|
|
162
|
-
| ------------------------ |
|
|
163
|
-
| 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`
|
|
164
|
-
| 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage)
|
|
165
|
-
| 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint)
|
|
166
|
-
| 9. EditorConfig | Copy `static/templates/.editorconfig`
|
|
167
|
-
| 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv)
|
|
168
|
-
| 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette
|
|
169
|
-
| 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants)
|
|
170
|
-
| 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up)
|
|
171
|
-
| 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands
|
|
161
|
+
| Standard | What to set up |
|
|
162
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
|
+
| 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
|
|
164
|
+
| 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
|
|
165
|
+
| 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
|
|
166
|
+
| 9. EditorConfig | Copy `static/templates/.editorconfig` |
|
|
167
|
+
| 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
|
|
168
|
+
| 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
|
|
169
|
+
| 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided, and `animation.ts`, `artwork.ts` and `classNames.ts` once there is something to put in them. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
|
|
170
|
+
| 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
|
|
171
|
+
| 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
|
|
172
172
|
|
|
173
173
|
The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
|
|
174
174
|
|
|
175
175
|
**Finish by:**
|
|
176
176
|
|
|
177
177
|
1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's major version. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
|
|
178
|
-
2. Running `pnpm lint`, `pnpm format:check
|
|
178
|
+
2. Running `pnpm lint`, `pnpm format:check`, the tests and the [standards check](#checking-a-project), and fixing what they find.
|
|
179
179
|
3. **Printing this to the person**, filled in, so every project's handover reads the same:
|
|
180
180
|
|
|
181
181
|
```text
|
|
@@ -199,7 +199,8 @@ The project's `AGENTS.md` has the same major version as the installed package, s
|
|
|
199
199
|
|
|
200
200
|
1. **Read the version's Fixes** in `node_modules/@activatus/code-standards/docs/version-history.md`, and do anything they ask.
|
|
201
201
|
2. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles and asking before committing. Ask the person any that are not recorded, and record them as step 4 says.
|
|
202
|
-
3. **
|
|
202
|
+
3. **Run the [standards check](#checking-a-project)**, and fix what it finds.
|
|
203
|
+
4. **Tell the person** what you changed, or that the project was already up to date.
|
|
203
204
|
|
|
204
205
|
---
|
|
205
206
|
|
|
@@ -207,7 +208,7 @@ The project's `AGENTS.md` has the same major version as the installed package, s
|
|
|
207
208
|
|
|
208
209
|
The project already follows the standards, and a newer version is out.
|
|
209
210
|
|
|
210
|
-
**A
|
|
211
|
+
**A fix or a minor version keeps the same version number.** When only the last number changes (a fix, such as 3.0.0 → 3.0.1) or the middle number changes (a minor version, such as 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.
|
|
211
212
|
|
|
212
213
|
1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
|
|
213
214
|
2. **Update the package:**
|
|
@@ -222,12 +223,47 @@ The project already follows the standards, and a newer version is out.
|
|
|
222
223
|
4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
|
|
223
224
|
5. **Do every other change** as its "What to do" says, and run its "How to check" search.
|
|
224
225
|
6. **Ask any [step 4](#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
|
|
225
|
-
7. **
|
|
226
|
+
7. **Run the [standards check](#checking-a-project)**, and fix what it finds.
|
|
227
|
+
8. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
|
|
226
228
|
|
|
227
229
|
See the [Version History](/docs/version-history) for the full update rules.
|
|
228
230
|
|
|
229
231
|
---
|
|
230
232
|
|
|
233
|
+
## Checking a project
|
|
234
|
+
|
|
235
|
+
The package ships a script that checks the project against the standards. Add it to the project's `package.json` during setup:
|
|
236
|
+
|
|
237
|
+
```json
|
|
238
|
+
{
|
|
239
|
+
"scripts": {
|
|
240
|
+
"standards:check": "node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs"
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
pnpm standards:check
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
It reports, and never changes a file. Each finding gives the standard's number and the page to read. It checks:
|
|
250
|
+
|
|
251
|
+
| Standard | What it checks |
|
|
252
|
+
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
253
|
+
| 21 | `AGENTS.md` has the code standards version and an unchanged Code standards section; the skills match the templates |
|
|
254
|
+
| 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
|
|
255
|
+
| 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, no component has its own `constants.ts`, and no other file sits beside the seven standard ones |
|
|
256
|
+
| 13 | Every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
|
|
257
|
+
| 21 | `docs/development/coding-standards.md` records the four agent answers under "Details" |
|
|
258
|
+
| 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
|
|
259
|
+
| 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
|
|
260
|
+
| 4 | Every file that exports a function or component has a test file beside it |
|
|
261
|
+
| 18 | Every doc template is in place, and every doc has one "Group — Menu item" title matching its file name, a Status line, and Decision, Why and Related sections |
|
|
262
|
+
|
|
263
|
+
**It follows the project's own rules, not only the standard ones.** A finding for a standard recorded as skipped or changed in `docs/development/coding-standards.md` is listed as a recorded exception to check by hand, and does not fail the check. The project's ESLint changes live in `eslint.overrides.mjs`, which it never compares. It also lists any Unfinished changes.
|
|
264
|
+
|
|
265
|
+
**The check is a helper, not the standard.** Passing it does not mean every rule is followed: names, the order inside a component and much more still need reading. And a finding that is wrong for the project is not fixed by bending the code to the script: record the exception in `coding-standards.md`, with the person's yes.
|
|
266
|
+
|
|
231
267
|
## Finishing a change later
|
|
232
268
|
|
|
233
269
|
Sometimes a change is too big for the update, such as switching on the standard ESLint config in a project that never had it. It can be finished later, but **the version number must stay honest**.
|
|
@@ -95,7 +95,7 @@ Keep these pairs distinct:
|
|
|
95
95
|
|
|
96
96
|
A `Not started` file is a visible gap: it shows a decision that has not been made yet.
|
|
97
97
|
|
|
98
|
-
**
|
|
98
|
+
**Keep every folder and file, even ones that do not apply yet.** They keep every project's docs laid out the same way, and a small project such as a one-page site grows into them. Never delete one to tidy the menu.
|
|
99
99
|
|
|
100
100
|
### Decision Docs belong to the person
|
|
101
101
|
|
|
@@ -268,6 +268,43 @@ export default nextConfig;
|
|
|
268
268
|
|
|
269
269
|
---
|
|
270
270
|
|
|
271
|
+
## 🔄 Converting existing docs
|
|
272
|
+
|
|
273
|
+
How to turn a project's existing documentation into Decision Docs. **Every word is kept**: converting changes where things live and how they are laid out, never what they say. Confirm the plan with the person before starting.
|
|
274
|
+
|
|
275
|
+
### Outside material, such as client briefs
|
|
276
|
+
|
|
277
|
+
A brief says what to build rather than recording a decision, but it is still a decision: to build what the brief says.
|
|
278
|
+
|
|
279
|
+
1. **Give the product its own folder**, such as `docs/homepage/`, with one doc per part of the product.
|
|
280
|
+
2. **Decision:** "Build it as the brief below says."
|
|
281
|
+
3. **Why:** the client's reason, and which brief wins where two disagree.
|
|
282
|
+
4. **Details:** the brief's full text, unchanged.
|
|
283
|
+
5. **A superseded brief** goes under `## History`, marked "Reference only".
|
|
284
|
+
6. **The table of which brief wins** goes in `scope/core.md`.
|
|
285
|
+
|
|
286
|
+
### Build decisions made along the way
|
|
287
|
+
|
|
288
|
+
**One decision per file.** A decision made while building a part, such as "the hero cards become the rail's cards", gets its own doc beside that part's doc, in the same product folder. It is never folded into the part's doc.
|
|
289
|
+
|
|
290
|
+
### Headings
|
|
291
|
+
|
|
292
|
+
A doc has one `#` heading, its title. Push every heading in the old content down by the **smallest step that frees `#`**: if the old doc's top level is `#`, every heading moves down one level. Skip headings inside code blocks. **If that pushes any heading past `######`, split the doc** into one doc per top-level part instead. The site's menu on the right shows levels 2 and 3 only, so keep the important structure there.
|
|
293
|
+
|
|
294
|
+
### Images
|
|
295
|
+
|
|
296
|
+
**Images go in `docs/assets/`, in a folder per product area**, such as `docs/assets/homepage/`. Link each image from the doc that uses it, with a relative path. **Refer to a folder of images as a code path, `docs/assets/homepage/`, never a link**: the docs site cannot open a folder, so the link breaks the build.
|
|
297
|
+
|
|
298
|
+
### Old viewer leftovers
|
|
299
|
+
|
|
300
|
+
Delete every `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md` once its content has moved to `overview/`.
|
|
301
|
+
|
|
302
|
+
### The Updated date
|
|
303
|
+
|
|
304
|
+
Converting a doc does not change its decision, so the **Updated** date stays as it was. Use the date of the last real decision, from the old doc or the git history.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
271
308
|
## 🚀 Setting it up
|
|
272
309
|
|
|
273
310
|
1. **Copy the docs.** Copy the [`docs/` templates](/docs/templates#document-templates) into the project's `docs/` folder. Converting docs from version 2 or earlier? Delete the old viewer's leftovers: every `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md` once its content has moved to `overview/`. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`), update its title, and update the link to it in `overview/writing-docs.md`. The docs build fails on a broken link.
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -30,7 +30,7 @@ pnpm add -D eslint@latest @eslint/js@latest
|
|
|
30
30
|
|
|
31
31
|
:::note[eslint-plugin-react on ESLint 10]
|
|
32
32
|
|
|
33
|
-
`eslint-plugin-react` 7.37 officially supports ESLint only up to 9.7, and on ESLint 10 it crashes when it tries to detect the React version by itself. The React and Next.js configs below avoid this by setting the version: `settings: { react: { version: "19.0" } }`. **Keep that setting
|
|
33
|
+
`eslint-plugin-react` 7.37 officially supports ESLint only up to 9.7, and on ESLint 10 it crashes when it tries to detect the React version by itself. The React and Next.js configs below avoid this by setting the version: `settings: { react: { version: "19.0" } }`. **Keep that setting.** A project on a React version other than 19 sets the number in `eslint.overrides.mjs`, `{ settings: { react: { version: "19.2" } } }`, never in `eslint.config.mjs`. pnpm warns about the unmet peer dependency on install; that warning is expected.
|
|
34
34
|
|
|
35
35
|
:::
|
|
36
36
|
|
|
@@ -196,8 +196,8 @@ const config = [
|
|
|
196
196
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
197
197
|
},
|
|
198
198
|
{
|
|
199
|
-
//
|
|
200
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
|
|
199
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
200
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
|
|
201
201
|
rules: { "max-lines": "off" },
|
|
202
202
|
},
|
|
203
203
|
{
|
|
@@ -392,8 +392,8 @@ const config = [
|
|
|
392
392
|
},
|
|
393
393
|
},
|
|
394
394
|
{
|
|
395
|
-
//
|
|
396
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
395
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
396
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
397
397
|
rules: { "max-lines": "off" },
|
|
398
398
|
},
|
|
399
399
|
{
|
|
@@ -515,7 +515,8 @@ const config = [
|
|
|
515
515
|
},
|
|
516
516
|
settings: {
|
|
517
517
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
518
|
-
//
|
|
518
|
+
// A project on another React version sets settings.react.version
|
|
519
|
+
// in eslint.overrides.mjs, never here.
|
|
519
520
|
react: { version: "19.0" },
|
|
520
521
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
521
522
|
},
|
|
@@ -626,8 +627,8 @@ const config = [
|
|
|
626
627
|
},
|
|
627
628
|
},
|
|
628
629
|
{
|
|
629
|
-
//
|
|
630
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
630
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
631
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
631
632
|
rules: { "max-lines": "off" },
|
|
632
633
|
},
|
|
633
634
|
{
|
|
@@ -659,7 +660,7 @@ export default config;
|
|
|
659
660
|
|
|
660
661
|
:::caution[Pin the React version]
|
|
661
662
|
|
|
662
|
-
|
|
663
|
+
Keep `settings.react.version` set rather than `"detect"`; change the number in `eslint.overrides.mjs`. On ESLint 10, `eslint-plugin-react` 7 crashes while detecting the version (`contextOrFilename.getFilename is not a function`).
|
|
663
664
|
|
|
664
665
|
:::
|
|
665
666
|
|
|
@@ -751,7 +752,8 @@ const config = [
|
|
|
751
752
|
},
|
|
752
753
|
settings: {
|
|
753
754
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
754
|
-
//
|
|
755
|
+
// A project on another React version sets settings.react.version
|
|
756
|
+
// in eslint.overrides.mjs, never here.
|
|
755
757
|
react: { version: "19.0" },
|
|
756
758
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
757
759
|
},
|
|
@@ -862,8 +864,8 @@ const config = [
|
|
|
862
864
|
},
|
|
863
865
|
},
|
|
864
866
|
{
|
|
865
|
-
//
|
|
866
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
867
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
868
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
867
869
|
rules: { "max-lines": "off" },
|
|
868
870
|
},
|
|
869
871
|
{
|
|
@@ -1021,7 +1023,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
|
|
|
1021
1023
|
|
|
1022
1024
|
### `max-lines: 300`
|
|
1023
1025
|
|
|
1024
|
-
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are `lib/constants
|
|
1026
|
+
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the seven constants files in `lib/constants/` (`routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`), which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
1025
1027
|
|
|
1026
1028
|
### `max-depth: 3`
|
|
1027
1029
|
|
|
@@ -43,7 +43,7 @@ A file over 300 lines is doing more than one job. Split it before it gets there:
|
|
|
43
43
|
|
|
44
44
|
Blank lines and comments do not count towards the limit. **Test files are exempt** — a thorough test file can run long.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
**The seven constants files in `lib/constants/` are exempt too**: `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`. They are lists of data, not logic, and a big app has a lot of links, text and motion. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
|
|
47
47
|
|
|
48
48
|
---
|
|
49
49
|
|
|
@@ -313,7 +313,7 @@ if (order.status === "shipped") {
|
|
|
313
313
|
|
|
314
314
|
**`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
|
|
315
315
|
|
|
316
|
-
Every named number lives in `lib/constants/numbers.ts`, even one only one file uses. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
|
|
316
|
+
Every loose named number lives in `lib/constants/numbers.ts`, even one only one file uses. Numbers that only mean something together, such as the steps of an animation, stay whole as one object in `animation.ts` or `artwork.ts`. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
|
|
317
317
|
|
|
318
318
|
---
|
|
319
319
|
|