@activatus/code-standards 3.3.1 โ 3.3.3
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/README.md +28 -3
- package/docs/Guides/migrating.md +6 -6
- package/docs/Guides/regression-checks.md +9 -0
- package/docs/Guides/setup.md +29 -19
- package/docs/Standards/documentation.md +1 -0
- package/docs/Standards/eslint.md +10 -10
- package/docs/Standards/prettier.md +56 -5
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +61 -23
- package/docs/Structure/import-organization.md +31 -46
- package/docs/Structure/naming-conventions.md +1 -1
- package/docs/templates.mdx +14 -0
- package/docs/version-history.md +80 -5
- package/package.json +1 -1
- package/scripts/verifyStandards/checkComponents.mjs +2 -0
- package/scripts/verifyStandards/checkConstants.mjs +22 -48
- package/scripts/verifyStandards/checkStructure.mjs +60 -5
- package/scripts/verifyStandards/formatReport.mjs +1 -1
- package/scripts/verifyStandards/projectFiles.mjs +1 -46
- package/scripts/verifyStandards/recordedExceptions.mjs +176 -0
- package/scripts/verifyStandards/runChecks.mjs +23 -5
- package/static/templates/.prettierignore +7 -0
- package/static/templates/AGENTS.md +29 -26
- package/static/templates/docs/development/coding-standards.md +2 -2
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +2 -2
- package/static/templates/eslint/react/eslint.config.mjs +2 -2
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/prettier.config.mjs +20 -2
package/README.md
CHANGED
|
@@ -32,9 +32,9 @@ pnpm add -D @activatus/code-standards@latest
|
|
|
32
32
|
|
|
33
33
|
Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
|
|
34
34
|
|
|
35
|
-
The package version is the standards version
|
|
35
|
+
The package version is the standards version, and a project records it in full, such as `3.3.2`, so the agent always knows where the project's up to.
|
|
36
36
|
|
|
37
|
-
> ๐ข **Updating a project to newer standards?** Run `pnpm add -D @activatus/code-standards@latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the
|
|
37
|
+
> ๐ข **Updating a project to newer standards?** Run `pnpm add -D @activatus/code-standards@latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the entries newer than the project's version, does exactly what each one says, and records the new version. Cheaper than shouting the whole pub a round.
|
|
38
38
|
|
|
39
39
|
---
|
|
40
40
|
|
|
@@ -90,6 +90,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
|
|
|
90
90
|
- ๐ฃ๏ธ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
|
|
91
91
|
- ๐ **Always `const`.** Need `let`? Fine, but leave a comment saying why, or the linter knocks it back.
|
|
92
92
|
- ๐น **Arrow functions everywhere.** `const Button = () => {}`. The word `function` is clutter, so we don't use it.
|
|
93
|
+
- ๐งน **Imports sort themselves.** Prettier puts them in order every time you format, so nobody burns an afternoon shuffling them by hand.
|
|
93
94
|
- ๐ **No circular imports. Ever.** If two files import each other, pull the shared bit into a third file.
|
|
94
95
|
- ๐ฏ **A function does one thing.** If you need the word "and" to describe it, it's two functions.
|
|
95
96
|
- ๐งช **Every function and component gets a test file.** One test file, one thing tested. No test, not finished.
|
|
@@ -97,6 +98,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
|
|
|
97
98
|
- ๐ฆ **One parameter per function.** Need more? Pass an object, so the call explains itself.
|
|
98
99
|
- ๐ช **Return early.** Deal with the dodgy cases up top instead of nesting four `if`s deep like a set of Russian dolls.
|
|
99
100
|
- ๐ข **No magic numbers.** `MAXIMUM_RETRY_ATTEMPTS`, not a random `3` sitting there like it owns the place.
|
|
101
|
+
- ๐๏ธ **Links go in `r`, words people see go in `s`.** Everything else sits at the top of the file that uses it until something else needs it too. Not sure where a value goes? The agent parks it in `unsortedValues.ts` and asks you at the end, instead of stopping the job to have a yarn about it.
|
|
100
102
|
- ๐ท๏ธ **Type names end in `Props` or `Type`.** So you can tell what you're looking at.
|
|
101
103
|
- ๐ฌ **Comments explain why, not what.** And no commented-out code. Git remembers, you don't have to.
|
|
102
104
|
|
|
@@ -116,6 +118,28 @@ The full detail's on the site. This is the version you'd tell someone over a sch
|
|
|
116
118
|
|
|
117
119
|
- ๐งญ **Branches, commit messages, Pull Requests and whether AI agents may commit are up to each project.** Every team runs its work differently, so it goes in the project's own `AGENTS.md` and docs, not here. These standards are the base for the code itself.
|
|
118
120
|
|
|
121
|
+
### ๐ฆ Status circles
|
|
122
|
+
|
|
123
|
+
Setup asks if you want them. Say yes, and the agent reports every ticket or piece of work as one line, with a circle that tells you at a glance whether you need to lift a finger:
|
|
124
|
+
|
|
125
|
+
| Circle | Means |
|
|
126
|
+
| ------ | ---------------------------------------------------------------------------- |
|
|
127
|
+
| โ
| Merged, in UAT or done. Nothing to do |
|
|
128
|
+
| ๐ข | Pull Request ready for you to review and merge. The link is the Pull Request |
|
|
129
|
+
| ๐ฃ | The agent's working on it |
|
|
130
|
+
| ๐ก | Done and checked, but not committed yet. You commit it, or tell the agent to |
|
|
131
|
+
| ๐ | Waiting on another ticket or Pull Request first |
|
|
132
|
+
| ๐ด | Blocked, or you need to do something. It says what |
|
|
133
|
+
| โช | Not started |
|
|
134
|
+
|
|
135
|
+
A line looks like this:
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
๐ข ACT-12 Short title: #19
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The ticket ID links to the ticket and the number links to the Pull Request. Only what you need to act on makes the list: no essay about what it did while you were at smoko. Full detail in [Working with Agents](https://activatus-code-standards.vercel.app/docs/Standards/working-with-agents#status-circles).
|
|
142
|
+
|
|
119
143
|
### ๐ฆ Third-party code
|
|
120
144
|
|
|
121
145
|
- ๐ฆ **Third-party code is exempt.** Anything in `node_modules/` or `vendor/` isn't ours. Don't lint it, don't tidy it, leave it be.
|
|
@@ -144,6 +168,7 @@ static/templates/
|
|
|
144
168
|
โโโ eslint/ # ๐จ Four flavours: base, typescript, react, nextjs
|
|
145
169
|
โโโ stylelint/ # ๐
CSS and SCSS
|
|
146
170
|
โโโ prettier.config.mjs # โจ Formatting
|
|
171
|
+
โโโ .prettierignore # ๐ What Prettier leaves alone
|
|
147
172
|
โโโ globals.css # ๐จ Tailwind + starter colour palette
|
|
148
173
|
โโโ .editorconfig # โจ๏ธ Editor whitespace rules
|
|
149
174
|
โโโ .nvmrc / .envrc # ๐ข Node version switching
|
|
@@ -180,7 +205,7 @@ Reckon a rule's wrong, or there's one missing? Good. Standards that never change
|
|
|
180
205
|
1. ๐ฟ **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
|
|
181
206
|
2. ๐ **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
|
|
182
207
|
3. ๐ **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart. For an ESLint config, run `pnpm check:eslint-templates`: it lints each config against itself and fails if the ESLint page shows an old copy. Add `--update-docs` to copy the configs onto the page.
|
|
183
|
-
4. ๐ข **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump
|
|
208
|
+
4. ๐ข **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump `package.json` to match: the first number when most projects rework most of their code, the middle when files move, the last when only the inside of files changes. See [How versions are numbered](https://activatus-code-standards.vercel.app/docs/version-history#how-versions-are-numbered). Publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
|
|
184
209
|
5. ๐จ **Run `pnpm build`.** It fails on broken links, so you'll know quick smart if you've stuffed one.
|
|
185
210
|
6. ๐ **Open a pull request** and say why the change makes life better.
|
|
186
211
|
|
package/docs/Guides/migrating.md
CHANGED
|
@@ -61,7 +61,7 @@ Applies setup standards 7, 9 and 10. Three commits, in this order:
|
|
|
61
61
|
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.
|
|
62
62
|
|
|
63
63
|
```bash
|
|
64
|
-
pnpm add -D prettier prettier-plugin-tailwindcss
|
|
64
|
+
pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
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.
|
|
@@ -179,16 +179,16 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
|
|
|
179
179
|
|
|
180
180
|
## Stage 4 โ Constants
|
|
181
181
|
|
|
182
|
-
Applies setup standard 12.1. Move every link into `r
|
|
182
|
+
Applies setup standard 12.1. Move every link into `r` and every piece of text people see or hear into `s`, in `lib/constants/`. Every other value stays with the code that uses it until more than one file needs it; a shared value moves to the file in `lib/constants/` that fits. See [Constants](/docs/Structure/folder-structure#constants).
|
|
183
183
|
|
|
184
184
|
- **Move the values, nothing else.** The page must look and work exactly as before.
|
|
185
|
-
- **
|
|
186
|
-
- **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`.
|
|
187
|
-
- **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide.
|
|
185
|
+
- **A value one file uses moves to the top of that file.** A component's own constants file is folded into the files that use it, or into `lib/constants/` for the values more than one file shares.
|
|
186
|
+
- **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`.
|
|
187
|
+
- **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. When it is not clear, put the value in `lib/constants/unsortedValues.ts`, carry on, and ask the person at the end of the stage: see [When it is not clear where a value goes](/docs/Structure/folder-structure#unsorted-values).
|
|
188
188
|
- **An id moves into the object that uses it.** **CSS written as a string moves to `globals.css`**, never into a constants file. A media query the code reads stays in its object in `animation.ts`.
|
|
189
189
|
- **Only text people see or hear goes in `s`.** Internal strings, such as ids, keys and log messages, stay where they are used: a key in the object that uses them, or a named constant at the top of the file.
|
|
190
190
|
- **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its key: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete any separate lookup object that maps a key to its link.
|
|
191
|
-
- **Every object and list constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. A single number or string needs none. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
191
|
+
- **Every object and list constant in `lib/constants/` except `r` and `s` gets a real type from `lib/types/`**, never `as const`. A constant at the top of the file that uses it is typed from that file's own `.types.ts`. A single number or string needs none. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
192
192
|
|
|
193
193
|
## Stage 5 โ Components
|
|
194
194
|
|
|
@@ -72,8 +72,17 @@ It builds the project and starts the production build on port 3100, then measure
|
|
|
72
72
|
- **It runs against a production build**, on its own port, never against `pnpm dev`.
|
|
73
73
|
- **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
|
|
74
74
|
- **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
|
|
75
|
+
- **Record a check only after it has run.** `docs/testing/regression.md` says what was decided, and gets the baseline's source and each result only once they exist. Never write a URL, commit, date or "passed" for a check that has not happened yet.
|
|
75
76
|
- **A code standards update that changes only types may still be applied to a frozen test**, such as replacing `as const` with a real type, with the person's yes. A copy of the template takes the new template whole; a project's own test takes just the typing change. Nothing the test does may change, and the check must still pass against the **existing** baseline, never a new one: passing proves nothing changed.
|
|
76
77
|
|
|
78
|
+
## Comparing two local servers instead
|
|
79
|
+
|
|
80
|
+
A project that skips Playwright can still compare the page before and after: run the last known-good commit and the branch side by side, each with `next dev` on its own port, and compare their rendered HTML or screenshots.
|
|
81
|
+
|
|
82
|
+
- **Export the old commit to its own folder**, such as with `git worktree add ../before-refactor <commit>`.
|
|
83
|
+
- **Copy `node_modules` into it. Never symlink it.** Turbopack refuses a `node_modules` that points outside the project folder. On macOS, `cp -Rc node_modules ../before-refactor/` makes a copy-on-write clone in seconds that takes almost no extra disk space.
|
|
84
|
+
- **Record what was compared, and the result, only once it has run**, the same as the Playwright check.
|
|
85
|
+
|
|
77
86
|
## The blind spot
|
|
78
87
|
|
|
79
88
|
**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
|
@@ -37,10 +37,13 @@ minimumReleaseAgeExclude:
|
|
|
37
37
|
|
|
38
38
|
Newer pnpm versions may add this exclusion for you when you run `pnpm add`. Check the file either way, and add it if it is not there: an update hits the same check when a new version of the standards has only just been published. 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.
|
|
39
39
|
|
|
40
|
-
**pnpm owns `pnpm-workspace.yaml
|
|
40
|
+
**Copy `static/templates/.prettierignore`** to the project root, or add its lines to the project's own. pnpm owns `pnpm-workspace.yaml` and rewrites it on every install, with single quotes, so `pnpm format:check` would fail after every update. `AGENTS.md` and the agent skills are copied from the standards and compared word for word by the [standards check](#checking-a-project), so Prettier must leave them alone too:
|
|
41
41
|
|
|
42
42
|
```text title=".prettierignore"
|
|
43
43
|
pnpm-workspace.yaml
|
|
44
|
+
AGENTS.md
|
|
45
|
+
.agents/skills/
|
|
46
|
+
.claude/commands/
|
|
44
47
|
```
|
|
45
48
|
|
|
46
49
|
The standards are now in `node_modules/@activatus/code-standards/`:
|
|
@@ -83,8 +86,8 @@ Tell me the numbers to skip or change, or say "all good".
|
|
|
83
86
|
10. Node version set by .nvmrc and direnv
|
|
84
87
|
11. Styling: Tailwind, flexbox first, colours only from the global palette
|
|
85
88
|
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
|
|
87
|
-
13. Components live where they are used: components/ui/, components/shared/, or beside their page
|
|
89
|
+
12.1. Constants: r for every link and s for every piece of text, in lib/constants/; other values stay with the code that uses them until they are shared
|
|
90
|
+
13. Components live where they are used: components/ui/, components/layout/, components/shared/, or beside their page
|
|
88
91
|
14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
|
|
89
92
|
15. Design System Components: every project builds the standard components with the same props
|
|
90
93
|
16. Imports: no circular imports, import from folders not files
|
|
@@ -113,7 +116,14 @@ Then wait for the answer.
|
|
|
113
116
|
| "Change 7: we use Biome for formatting" | Apply 7 as they describe it |
|
|
114
117
|
| Something unclear | Ask. Do not guess |
|
|
115
118
|
|
|
116
|
-
**Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write its number
|
|
119
|
+
**Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write one line with its number and name from the list, then what is different and the reason the person gave. An exception that covers only some files names them, in backticks, after `for`:
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
- 7. Prettier โ skipped: the project uses Biome for formatting (2026-10-23).
|
|
123
|
+
- 4. Every function and component has a test file โ changed for `app/api/**`: legacy routes, tested when each is replaced (2026-10-27).
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**Every path after `for` goes in backticks**: a `for` with none fails the check, because it would otherwise cover every file. **Start no other line under "Details" with a number.** The [standards check](#checking-a-project) reads a line that starts with a number as an exception to that standard, and fails on one it cannot read. Use bullet points for anything else. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
|
|
117
127
|
|
|
118
128
|
The list has nothing about branches or commit messages. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
|
|
119
129
|
|
|
@@ -165,17 +175,17 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
|
|
|
165
175
|
|
|
166
176
|
**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.
|
|
167
177
|
|
|
168
|
-
| Standard | What to set up
|
|
169
|
-
| ------------------------ |
|
|
170
|
-
| 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"`
|
|
171
|
-
| 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)
|
|
172
|
-
| 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)
|
|
173
|
-
| 9. EditorConfig | Copy `static/templates/.editorconfig`
|
|
174
|
-
| 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv)
|
|
175
|
-
| 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette
|
|
176
|
-
| 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`)
|
|
177
|
-
| 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)
|
|
178
|
-
| 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)
|
|
178
|
+
| Standard | What to set up |
|
|
179
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
180
|
+
| 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"` |
|
|
181
|
+
| 7. Prettier | `pnpm add -D prettier @ianvs/prettier-plugin-sort-imports 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) |
|
|
182
|
+
| 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) |
|
|
183
|
+
| 9. EditorConfig | Copy `static/templates/.editorconfig` |
|
|
184
|
+
| 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
|
|
185
|
+
| 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
|
|
186
|
+
| 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`) and an `index.ts` that exports them. Create `noData.ts` once the data's shape is decided, and `numbers.ts`, `animation.ts`, `status.ts` and the others once more than one file shares a value. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
|
|
187
|
+
| 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) |
|
|
188
|
+
| 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) |
|
|
179
189
|
|
|
180
190
|
The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
|
|
181
191
|
|
|
@@ -258,15 +268,15 @@ It reports, and never changes a file. Each finding gives the standard's number a
|
|
|
258
268
|
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
259
269
|
| 21 | `AGENTS.md` has the code standards version and an unchanged Code standards section; the skills match the templates |
|
|
260
270
|
| 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 |
|
|
261
|
-
| 12.1 | `lib/constants/` has `index.ts`, `routes.ts
|
|
262
|
-
| 13 |
|
|
263
|
-
| 21 | `docs/development/coding-standards.md` records the five agent answers under "Details"
|
|
271
|
+
| 12.1 | `lib/constants/` has `index.ts`, `routes.ts` and `strings.ts`, and no `unsortedValues.ts` is left waiting |
|
|
272
|
+
| 13 | `components/` holds only `ui/`, `layout/` and `shared/`, every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
|
|
273
|
+
| 21 | `docs/development/coding-standards.md` records the five agent answers under "Details", and every numbered line there is a well-formed exception |
|
|
264
274
|
| 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
|
|
265
275
|
| 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
|
|
266
276
|
| 4 | Every file that exports a function or component has a test file beside it |
|
|
267
277
|
| 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 |
|
|
268
278
|
|
|
269
|
-
**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.
|
|
279
|
+
**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. An exception that names files covers only those files. A numbered line under "Details" that is not shaped like an exception fails the check, because it would otherwise switch a standard off by accident. The project's ESLint changes live in `eslint.overrides.mjs`, which it never compares. It also lists any Unfinished changes.
|
|
270
280
|
|
|
271
281
|
**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.
|
|
272
282
|
|
|
@@ -357,5 +357,6 @@ Converting a doc does not change its decision, so the **Updated** date stays as
|
|
|
357
357
|
- **Read the files directly.** Do not start the docs site to read them.
|
|
358
358
|
- **Check the Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** โ do not treat them as one, and do not invent one. Ask.
|
|
359
359
|
- **Update the docs in the same change** as the code, and change the **Updated** date.
|
|
360
|
+
- **Record a check only after it has run.** Never write a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists.
|
|
360
361
|
- **Write into the matching file.** Create a new file only when a topic has no home, in kebab-case, using the [doc format](#-the-doc-format).
|
|
361
362
|
- **Do not edit anything in `docsSite/`** unless the task is about the docs viewer itself.
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -196,8 +196,8 @@ const config = [
|
|
|
196
196
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
197
197
|
},
|
|
198
198
|
{
|
|
199
|
-
// The
|
|
200
|
-
files: ["lib/constants
|
|
199
|
+
// The constants files are data, not logic, so they can be long.
|
|
200
|
+
files: ["lib/constants/*.{js,mjs}"],
|
|
201
201
|
rules: { "max-lines": "off" },
|
|
202
202
|
},
|
|
203
203
|
{
|
|
@@ -401,8 +401,8 @@ const config = [
|
|
|
401
401
|
},
|
|
402
402
|
},
|
|
403
403
|
{
|
|
404
|
-
// The
|
|
405
|
-
files: ["lib/constants
|
|
404
|
+
// The constants files are data, not logic, so they can be long.
|
|
405
|
+
files: ["lib/constants/*.ts"],
|
|
406
406
|
rules: { "max-lines": "off" },
|
|
407
407
|
},
|
|
408
408
|
{
|
|
@@ -646,8 +646,8 @@ const config = [
|
|
|
646
646
|
},
|
|
647
647
|
},
|
|
648
648
|
{
|
|
649
|
-
// The
|
|
650
|
-
files: ["lib/constants
|
|
649
|
+
// The constants files are data, not logic, so they can be long.
|
|
650
|
+
files: ["lib/constants/*.ts"],
|
|
651
651
|
rules: { "max-lines": "off" },
|
|
652
652
|
},
|
|
653
653
|
{
|
|
@@ -893,8 +893,8 @@ const config = [
|
|
|
893
893
|
},
|
|
894
894
|
},
|
|
895
895
|
{
|
|
896
|
-
// The
|
|
897
|
-
files: ["lib/constants
|
|
896
|
+
// The constants files are data, not logic, so they can be long.
|
|
897
|
+
files: ["lib/constants/*.ts"],
|
|
898
898
|
rules: { "max-lines": "off" },
|
|
899
899
|
},
|
|
900
900
|
{
|
|
@@ -1054,7 +1054,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
|
|
|
1054
1054
|
|
|
1055
1055
|
### `max-lines: 300`
|
|
1056
1056
|
|
|
1057
|
-
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the
|
|
1057
|
+
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the files in `lib/constants/`, which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
1058
1058
|
|
|
1059
1059
|
### `max-depth: 3`
|
|
1060
1060
|
|
|
@@ -1091,7 +1091,7 @@ Named exports only. Default exports are allowed where a tool requires them: conf
|
|
|
1091
1091
|
|
|
1092
1092
|
### Import order is not linted
|
|
1093
1093
|
|
|
1094
|
-
There is deliberately no import-**order** rule (circular imports are a different matter โ see above).
|
|
1094
|
+
There is deliberately no import-**order** rule (circular imports are a different matter โ see above). Prettier sorts imports instead, every time a file is formatted: see [Import sorting](/docs/Standards/prettier#import-sorting).
|
|
1095
1095
|
|
|
1096
1096
|
### `unicorn/filename-case: camelCase or PascalCase`
|
|
1097
1097
|
|
|
@@ -10,7 +10,7 @@ A single shared Prettier config keeps formatting consistent and eliminates "styl
|
|
|
10
10
|
## Installation
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
pnpm add -D prettier prettier-plugin-tailwindcss
|
|
13
|
+
pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
## Usage
|
|
@@ -18,7 +18,7 @@ pnpm add -D prettier prettier-plugin-tailwindcss
|
|
|
18
18
|
Create `prettier.config.mjs` in your project root:
|
|
19
19
|
|
|
20
20
|
```js title="prettier.config.mjs"
|
|
21
|
-
/** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
|
|
21
|
+
/** @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
|
|
22
22
|
const config = {
|
|
23
23
|
// Short lines, so code reads well on a phone.
|
|
24
24
|
printWidth: 70,
|
|
@@ -32,7 +32,25 @@ const config = {
|
|
|
32
32
|
arrowParens: "always",
|
|
33
33
|
semi: true,
|
|
34
34
|
endOfLine: "lf",
|
|
35
|
-
|
|
35
|
+
// The Tailwind plugin must stay last.
|
|
36
|
+
plugins: [
|
|
37
|
+
"@ianvs/prettier-plugin-sort-imports",
|
|
38
|
+
"prettier-plugin-tailwindcss",
|
|
39
|
+
],
|
|
40
|
+
// Node's own modules, packages, the project's @/ aliases, then
|
|
41
|
+
// ../ and ./, with a blank line between groups. Side-effect
|
|
42
|
+
// imports, such as CSS, never move.
|
|
43
|
+
importOrder: [
|
|
44
|
+
"<BUILTIN_MODULES>",
|
|
45
|
+
"",
|
|
46
|
+
"<THIRD_PARTY_MODULES>",
|
|
47
|
+
"",
|
|
48
|
+
"^@/",
|
|
49
|
+
"",
|
|
50
|
+
"^[.][.]/",
|
|
51
|
+
"",
|
|
52
|
+
"^[.]/",
|
|
53
|
+
],
|
|
36
54
|
tailwindStylesheet: "./app/globals.css",
|
|
37
55
|
overrides: [
|
|
38
56
|
{
|
|
@@ -72,11 +90,15 @@ Both scripts work on the same list of files: every file git tracks, plus every n
|
|
|
72
90
|
| One person's local tool files, such as `.claude/settings.local.json` | That person's `.git/info/exclude` or global git ignore. Never `.prettierignore` |
|
|
73
91
|
| Files the whole project keeps out of git, such as `build/` | `.gitignore` |
|
|
74
92
|
| Files in git that Prettier must not format, such as `pnpm-workspace.yaml` | `.prettierignore`, shared by the whole project |
|
|
93
|
+
| `AGENTS.md`, `.agents/skills/` and `.claude/commands/` | `.prettierignore`, shared by the whole project |
|
|
75
94
|
|
|
76
|
-
pnpm rewrites `pnpm-workspace.yaml` in its own style on every install, so it always goes in `.prettierignore
|
|
95
|
+
pnpm rewrites `pnpm-workspace.yaml` in its own style on every install, so it always goes in `.prettierignore`. So do `AGENTS.md` and the agent skills: they are copied from the standards, and `pnpm standards:check` compares them word for word, so a Prettier rewrite would fail it. The template has all four: copy `static/templates/.prettierignore`.
|
|
77
96
|
|
|
78
97
|
```text title=".prettierignore"
|
|
79
98
|
pnpm-workspace.yaml
|
|
99
|
+
AGENTS.md
|
|
100
|
+
.agents/skills/
|
|
101
|
+
.claude/commands/
|
|
80
102
|
```
|
|
81
103
|
|
|
82
104
|
## Tailwind class sorting
|
|
@@ -93,7 +115,36 @@ The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindl
|
|
|
93
115
|
|
|
94
116
|
- **It is part of the standard**, not a project extra. Every project that uses Tailwind has it.
|
|
95
117
|
- **`tailwindStylesheet` points at the project's global stylesheet**, so the plugin knows the project's own colours. Change the path if `globals.css` lives somewhere else.
|
|
96
|
-
- **A project with no Tailwind** (a plain Node.js service) removes
|
|
118
|
+
- **A project with no Tailwind** (a plain Node.js service) removes `prettier-plugin-tailwindcss` from `plugins`, and the `tailwindStylesheet` line.
|
|
119
|
+
|
|
120
|
+
## Import sorting {#import-sorting}
|
|
121
|
+
|
|
122
|
+
The config includes [`@ianvs/prettier-plugin-sort-imports`](https://github.com/IanVS/prettier-plugin-sort-imports). It sorts the imports of every file when the file is formatted, so **nobody sorts imports by hand, and agents never reorder them themselves**: `pnpm format`, or saving in the editor, does it.
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
"use client";
|
|
126
|
+
|
|
127
|
+
import { readFileSync } from "node:fs";
|
|
128
|
+
|
|
129
|
+
import Link from "next/link";
|
|
130
|
+
import { useState } from "react";
|
|
131
|
+
|
|
132
|
+
import { Button } from "@/components/ui";
|
|
133
|
+
import { r, s } from "@/lib/constants";
|
|
134
|
+
|
|
135
|
+
import { formatDate } from "../utils/formatDate";
|
|
136
|
+
|
|
137
|
+
import type { SampleProps } from "./Sample.types";
|
|
138
|
+
|
|
139
|
+
import "./sample.css";
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **The groups, in order:** Node's own modules (`node:fs`), packages, the project's `@/` aliases, parent folders (`../`), then the same folder (`./`). Each group is alphabetical, with a blank line between groups.
|
|
143
|
+
- **Directives such as `"use client"` stay at the top.**
|
|
144
|
+
- **Side-effect imports never move**, such as `import "./globals.css";`, because the order they load in can matter. The plugin sorts the imports above and below one separately. **Put them after every other import**, so the rest sort as one block. Never add a setting that moves them.
|
|
145
|
+
- **Type imports stay on their own line**, `import type { CardProps } from "./Card.types";`. Leave `importOrderTypeScriptVersion` unset: setting it to 4.5 or above merges type imports into value imports.
|
|
146
|
+
- **`prettier-plugin-tailwindcss` stays last in `plugins`.** The Tailwind plugin needs that to work beside other plugins.
|
|
147
|
+
- **Switching it on reorders the imports in most files.** Do it in a commit of its own, with nothing else in it, so the reordering never hides a real change in a review.
|
|
97
148
|
|
|
98
149
|
## Settings reference
|
|
99
150
|
|
|
@@ -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
|
-
**The
|
|
46
|
+
**The files in `lib/constants/` are exempt too**, such as `routes.ts`, `strings.ts` and `numbers.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
|
-
|
|
316
|
+
A number only one file uses is a named constant at the top of that file; a number more than one file uses lives in `lib/constants/numbers.ts`. 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
|
|