@activatus/code-standards 3.1.0 → 3.1.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.
Files changed (30) hide show
  1. package/docs/Guides/migrating.md +14 -0
  2. package/docs/Guides/setup.md +55 -20
  3. package/docs/Standards/documentation.md +17 -7
  4. package/docs/Standards/eslint.md +54 -14
  5. package/docs/Standards/lint-errors.md +4 -4
  6. package/docs/Standards/readable-code.md +4 -1
  7. package/docs/Standards/stylelint.md +9 -3
  8. package/docs/Standards/styling.md +5 -1
  9. package/docs/Standards/working-with-agents.md +5 -5
  10. package/docs/Structure/component-organization.md +30 -26
  11. package/docs/Structure/folder-structure.md +85 -32
  12. package/docs/Structure/import-organization.md +4 -4
  13. package/docs/design-system-components.md +16 -12
  14. package/docs/ontology.md +1 -1
  15. package/docs/templates.mdx +2 -2
  16. package/docs/version-history.md +48 -5
  17. package/package.json +1 -1
  18. package/static/templates/AGENTS.md +18 -9
  19. package/static/templates/docs/design/design-system.md +6 -0
  20. package/static/templates/docs/development/coding-standards.md +6 -2
  21. package/static/templates/docs/overview/how-it-works.md +1 -1
  22. package/static/templates/docs/product/ontology.md +32 -0
  23. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  24. package/static/templates/eslint/nextjs/eslint.config.mjs +9 -0
  25. package/static/templates/eslint/react/eslint.config.mjs +9 -0
  26. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  27. package/static/templates/eslint.overrides.mjs +18 -0
  28. package/static/templates/skills/codeReview.md +2 -1
  29. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  30. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
@@ -47,7 +47,7 @@
47
47
  - **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
48
48
  - **Merging and releases**: [merge strategy, and how work reaches production]
49
49
  - **GitHub repo**: [Optional. https://github.com/organisation/repo, read from the git remote and confirmed with the person. Delete this line if the project does not use it]
50
- - **Linear project**: [Optional. Workspace, project and ticket prefix, such as `activatus-life`, Launchpad, `ACT`, read from the project's docs or asked for, and confirmed with the person. Delete this line if the project does not use Linear]
50
+ - **Linear project**: [Optional. Workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad. The ticket prefix is the team's key, shared by every project in that team. Read it from the project's docs or asked for, and confirmed with the person. Delete this line if the project does not use Linear]
51
51
 
52
52
  **Never copy a Linear workspace or ticket prefix from another project.** If the Linear project above is missing, ask before creating, linking or citing any ticket.
53
53
 
@@ -101,20 +101,26 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
101
101
  - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
102
102
  - Do not edit `docsSite/` unless the task is about the docs viewer itself.
103
103
 
104
+ <!-- code-standards:start -->
105
+
104
106
  ## Code standards
105
107
 
108
+ **This section is copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
109
+
106
110
  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.
107
111
 
108
112
  **Code standards version:** [the major version of the installed `@activatus/code-standards` package when the standards were last applied]
109
113
 
110
- This is the version the code follows. When the package is updated, read only the newer versions 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`.
114
+ This is the version the code follows. It is the major version only: fixes such as 3.1.1 keep it at 3, but can still ask for changes, so read the Fixes for the installed version on every update. When the package is updated, read only the newer versions 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`.
111
115
 
112
116
  **Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
113
117
 
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.
119
+
114
120
  Follow these rules in every change:
115
121
 
116
122
  - **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
117
- - **No file longer than 300 lines** (test files are exempt).
123
+ - **No file longer than 300 lines.** Test files are exempt, and so are `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/`, which hold data only.
118
124
  - **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters (except `r` and `s`, below), no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/docs/Standards/human-readable-names).
119
125
 
120
126
  | Never | Always |
@@ -139,20 +145,21 @@ Follow these rules in every change:
139
145
  - **Functions, never classes.**
140
146
  - **One parameter per function.** Use a single object when more than one value is needed.
141
147
  - **Return early.** Never nest more than three levels deep.
142
- - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. A number used in one file is named at the top of that file; one shared across the app goes in `lib/constants/`, in a file named after its topic (`durations.ts`, `limits.ts`), never a `numbers.ts`. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
143
- - **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 static text, 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`. 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
148
+ - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every 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 static text, 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`. There is no component-level `constants.ts`: every link, piece of text and number goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`. 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
144
150
  - **No nested ternaries. No boolean flag parameters.**
145
151
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
146
152
  - **Named exports only**, except where a tool requires a default export.
147
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>`.
148
154
  - **One component per file.** Server and client components live in separate files.
155
+ - **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.
149
156
  - **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
150
- - **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`.
151
- - **Components live where they are used:** Design System Components in `components/ui/`; components used on more than one page in `components/shared/`; components used by a few pages in one section in that section's route group (`app/(billing)/components/`); components used by one page in that page's `components/` folder. Start a new component beside its page, and move it up when a second page needs it. No `components/features/` folder.
157
+ - **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`. A function that sorts, finds, gets, filters or formats the data passed to it goes in a `utils/` folder the first time it is written. Move a function up a level when a second user needs it.
158
+ - **Components live where they are used:** Design System Components in `components/ui/`, plus any props-only component not on the list yet, recorded under "Components for the standards" in `docs/development/coding-standards.md`; the site frame (navigation, header, footer) in `components/layout/`; the homepage's components in `app/(homepage)/components/`; components used on three or more pages in `components/shared/`; components used by three or more pages in one section in that section's route group (`app/(billing)/components/`); everything else in its page's `components/` folder. Start a new component beside its page. When a second page needs it, copy it there: one copy only, and each copy has a comment naming the other. When a third page needs it, merge the copies into one shared component, with props designed from all three uses. No `components/features/` folder.
152
159
  - **Code file names are camelCase**; component files are PascalCase. **Anything that becomes a URL is kebab-case**: route folders and documentation folders and files (`docs/architecture/background-jobs.md`). CSS variables are kebab-case too.
153
160
  - **Lay out with flexbox first**, and split layouts into child components. Only use CSS grid when specifically asked.
154
161
  - **Style with Tailwind.** Colours come from the global colour palette in `app/globals.css` only — never a hard-coded or arbitrary colour. The design decisions are in `docs/design/design-system.md`.
155
- - **Comments explain why, not what.** Never leave commented-out code.
162
+ - **Comments explain why, not what.** Never leave commented-out code. Mark unfinished work with `// TODO: Message` (`{/* TODO: Message */}` in JSX).
156
163
  - **Error messages say what happened and what to do.**
157
164
 
158
165
  **Third-party code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules.
@@ -163,10 +170,12 @@ Follow these rules in every change:
163
170
 
164
171
  **Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code.
165
172
 
166
- **Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit the ESLint config, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
173
+ **Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
167
174
 
168
175
  When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
169
176
 
177
+ <!-- code-standards:end -->
178
+
170
179
  ## Available skills
171
180
 
172
181
  Skill files live in `.agents/skills/`, mirrored to `.claude/commands/`.
@@ -8,6 +8,12 @@
8
8
 
9
9
  [What was decided.]
10
10
 
11
+ ## Colour palette
12
+
13
+ | Colour | Value | Class names | Use for |
14
+ | --- | --- | --- | --- |
15
+ | [Brand primary] | [`#3b82f6`, or a Tailwind colour such as `slate-900`] | [`bg-brand-primary`, `text-brand-primary`] | [Buttons and links] |
16
+
11
17
  ## Why
12
18
 
13
19
  [The reasons.]
@@ -6,11 +6,15 @@
6
6
 
7
7
  ## Decision
8
8
 
9
- This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (step 3 of `docs/Guides/setup.md` in the package).
9
+ This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (steps 3 and 4 of `docs/Guides/setup.md` in the package).
10
10
 
11
11
  ## Details
12
12
 
13
- [For each standard this project skips or changes: its number and name from the setup list, what is different, and why. For example: "7. Prettier — skipped: the project uses Biome for formatting." If nothing differs, write "No differences".]
13
+ [For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
14
+
15
+ ## Components for the standards
16
+
17
+ [Props-only components this project keeps in `components/ui/` that are not in the Design System Components list yet, each with its props, to be added in the next release of the standards. If there are none, write "None".]
14
18
 
15
19
  ## Unfinished changes
16
20
 
@@ -1,4 +1,4 @@
1
- # Overview — How it Works
1
+ # Overview — How It Works
2
2
 
3
3
  > [One line: what this doc decides.]
4
4
 
@@ -0,0 +1,32 @@
1
+ # Product — Ontology
2
+
3
+ > The words this product uses, what each one means, and how it speaks.
4
+
5
+ **Status:** Not started · **Updated:** [YYYY-MM-DD]
6
+
7
+ ## Decision
8
+
9
+ These are this product's words. Code, docs, tickets and copy all use them exactly as written here. The shared words for code are in the code standards' Ontology; this file is for the product's own.
10
+
11
+ ## Product words
12
+
13
+ | Word | What it means | Not to be confused with |
14
+ | --- | --- | --- |
15
+ | [Word] | [What it means in this product] | [A word that sounds close but means something else] |
16
+
17
+ ## How we speak
18
+
19
+ | | |
20
+ | --- | --- |
21
+ | **Tone** | [How the product sounds, such as "plain, warm and direct"] |
22
+ | **Words we use** | [Words that fit, such as "start" rather than "commence"] |
23
+ | **Words we avoid** | [Words that do not fit, and what to say instead] |
24
+ | **Audience** | [Who reads the copy, and what they already know] |
25
+
26
+ ## Why
27
+
28
+ [Why these words and this voice.]
29
+
30
+ ## Related
31
+
32
+ - [What Is It](../overview/what-is-it.md)
@@ -5,6 +5,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
5
5
  import unicorn from "eslint-plugin-unicorn";
6
6
  import globals from "globals";
7
7
 
8
+ import { projectOverrides } from "./eslint.overrides.mjs";
9
+
8
10
  // Code patterns that are errors in every file.
9
11
  const RESTRICTED_SYNTAX = [
10
12
  {
@@ -118,10 +120,17 @@ const config = [
118
120
  files: ["**/*.test.{js,mjs}"],
119
121
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
120
122
  },
123
+ {
124
+ // r, s, numbers and noData are lists, not logic, so they can be long.
125
+ files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
126
+ rules: { "max-lines": "off" },
127
+ },
121
128
  {
122
129
  files: ["**/*.config.{js,mjs}"],
123
130
  rules: { "import-x/no-default-export": "off" },
124
131
  },
132
+ // This project's own changes: see eslint.overrides.mjs.
133
+ ...projectOverrides,
125
134
  prettier,
126
135
  ];
127
136
 
@@ -7,6 +7,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
7
7
  import unicorn from "eslint-plugin-unicorn";
8
8
  import globals from "globals";
9
9
 
10
+ import { projectOverrides } from "./eslint.overrides.mjs";
11
+
10
12
  // Code patterns that are errors in every file.
11
13
  const RESTRICTED_SYNTAX = [
12
14
  {
@@ -189,6 +191,11 @@ const config = [
189
191
  "@typescript-eslint/no-magic-numbers": "off",
190
192
  },
191
193
  },
194
+ {
195
+ // r, s, numbers and noData are lists, not logic, so they can be long.
196
+ files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
197
+ rules: { "max-lines": "off" },
198
+ },
192
199
  {
193
200
  files: [
194
201
  "**/*.config.{js,mjs,ts}",
@@ -223,6 +230,8 @@ const config = [
223
230
  ],
224
231
  },
225
232
  },
233
+ // This project's own changes: see eslint.overrides.mjs.
234
+ ...projectOverrides,
226
235
  prettier,
227
236
  ];
228
237
 
@@ -9,6 +9,8 @@ import unicorn from "eslint-plugin-unicorn";
9
9
  import globals from "globals";
10
10
  import { configs as typescript } from "typescript-eslint";
11
11
 
12
+ import { projectOverrides } from "./eslint.overrides.mjs";
13
+
12
14
  // Code patterns that are errors in every file.
13
15
  const RESTRICTED_SYNTAX = [
14
16
  {
@@ -191,6 +193,11 @@ const config = [
191
193
  "@typescript-eslint/no-magic-numbers": "off",
192
194
  },
193
195
  },
196
+ {
197
+ // r, s, numbers and noData are lists, not logic, so they can be long.
198
+ files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
199
+ rules: { "max-lines": "off" },
200
+ },
194
201
  {
195
202
  files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
196
203
  rules: { "import-x/no-default-export": "off" },
@@ -210,6 +217,8 @@ const config = [
210
217
  ],
211
218
  },
212
219
  },
220
+ // This project's own changes: see eslint.overrides.mjs.
221
+ ...projectOverrides,
213
222
  prettier,
214
223
  ];
215
224
 
@@ -7,6 +7,8 @@ import unicorn from "eslint-plugin-unicorn";
7
7
  import globals from "globals";
8
8
  import { configs as typescript } from "typescript-eslint";
9
9
 
10
+ import { projectOverrides } from "./eslint.overrides.mjs";
11
+
10
12
  // Code patterns that are errors in every file.
11
13
  const RESTRICTED_SYNTAX = [
12
14
  {
@@ -172,6 +174,11 @@ const config = [
172
174
  "@typescript-eslint/no-magic-numbers": "off",
173
175
  },
174
176
  },
177
+ {
178
+ // r, s, numbers and noData are lists, not logic, so they can be long.
179
+ files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
180
+ rules: { "max-lines": "off" },
181
+ },
175
182
  {
176
183
  files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
177
184
  rules: { "import-x/no-default-export": "off" },
@@ -191,6 +198,8 @@ const config = [
191
198
  ],
192
199
  },
193
200
  },
201
+ // This project's own changes: see eslint.overrides.mjs.
202
+ ...projectOverrides,
194
203
  prettier,
195
204
  ];
196
205
 
@@ -0,0 +1,18 @@
1
+ // This project's changes to the Activatus ESLint config.
2
+ // eslint.config.mjs is copied from the code standards unchanged, so an
3
+ // update can copy it again. Every change to a lint rule goes here.
4
+ //
5
+ // Add a change only after the person agrees to it, and record it in
6
+ // docs/development/coding-standards.md, under "Details", with the
7
+ // standard's number and the reason. Name that number in a comment on
8
+ // each rule:
9
+ //
10
+ // {
11
+ // files: ["scripts/**/*.mjs"],
12
+ // rules: {
13
+ // // Standard 6: scripts print to the terminal.
14
+ // "no-console": "off",
15
+ // },
16
+ // },
17
+
18
+ export const projectOverrides = [];
@@ -19,7 +19,8 @@ Review the changes and report problems. Do NOT modify any files.
19
19
  - **Types** — `any`, non-null `!`, and `as` casts without a comment saying why
20
20
  - **Tests** — every new or changed function and component has a test file
21
21
  - **Readable code** — files over 300 lines, any name that is not human-readable (folders, files, props, form field `name`s and labels, types, union values, database columns, routes, environment variables and test names as well as variables), functions doing more than one thing, more than one parameter, nesting deeper than three levels, magic numbers
22
- - **Structure** — reusable functions outside a `utils/` folder, server and client code in one file, inline functions in render
22
+ - **Structure** — reusable functions outside a `utils/` folder (a sort, find, get, filter or format function inside a component), server and client code in one file, inline functions in render, a component copied a third time instead of merged, a copied component without a comment naming its other copy
23
+ - **Changed standards** — any change to `eslint.config.mjs`, and any rule in `eslint.overrides.mjs` or other change to a standard with no matching entry in `docs/development/coding-standards.md`
23
24
  - **Styling** — hard-coded colours, CSS grid that was not asked for
24
25
  5. Report the findings in order of severity: **Must fix**, **Should fix**, **Consider**. For each one give the file and line, what is wrong, and how to fix it.
25
26
  6. Finish with a one-line verdict: ready to commit, or not.
@@ -1,5 +1,5 @@
1
1
  /** @type {import("stylelint").Config} */
2
- export default {
2
+ const config = {
3
3
  ignoreFiles: ["**/vendor/**"],
4
4
  extends: [
5
5
  "stylelint-config-standard",
@@ -38,3 +38,5 @@ export default {
38
38
  },
39
39
  ],
40
40
  };
41
+
42
+ export default config;
@@ -1,5 +1,5 @@
1
1
  /** @type {import("stylelint").Config} */
2
- export default {
2
+ const config = {
3
3
  ignoreFiles: ["**/vendor/**"],
4
4
  extends: [
5
5
  "stylelint-config-standard-scss",
@@ -11,3 +11,5 @@ export default {
11
11
  "color-function-notation": "modern",
12
12
  },
13
13
  };
14
+
15
+ export default config;