@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.
@@ -71,11 +71,9 @@ project-root/
71
71
  │ ├── constants/ # Constants shared across the app: see Constants below
72
72
  │ │ ├── routes.ts # r: every link
73
73
  │ │ ├── strings.ts # s: every piece of static text
74
- │ │ ├── numbers.ts # Every loose named number
74
+ │ │ ├── numbers.ts # Numbers more than one file uses
75
75
  │ │ ├── noData.ts # Stand-in data for local development
76
- │ │ ├── animation.ts # How things move, once there is any
77
- │ │ ├── artwork.ts # What is drawn and where, once there is any
78
- │ │ ├── classNames.ts # Class names shared between files, once there are any
76
+ │ │ ├── status.ts # Statuses the app shares, once there are any
79
77
  │ │ └── index.ts
80
78
  │ ├── errors/ # Error types and handlers shared across the app
81
79
  │ └── types/ # Types shared across the app; a component's own types stay in its types.ts
@@ -148,10 +146,11 @@ project-root/
148
146
  | **The site frame** — navigation, header, footer | `components/layout/` | `components/layout/siteHeader/` |
149
147
  | **Three or more pages** of this project | `components/shared/` | `components/shared/pricingTable/` |
150
148
  | **Three or more pages in one section** | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/` |
149
+ | **Three or more pages in a section that already shares a folder** | A `components/` folder in that shared folder | `app/orders/[id]/components/orderSummary/` |
151
150
  | **One or two pages** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
152
151
  | **The homepage** | `app/(homepage)/components/` | `app/(homepage)/components/heroSection/` |
153
152
 
154
- A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`.
153
+ A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`. **A route group is only needed when a section's pages do not already share a folder.** When they all sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and its components go in its own `components/` folder. Never move pages just to make a route group.
155
154
 
156
155
  **The homepage is a route group too: `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/` folders, and is served at `/`. Without it, the homepage's components sit loose in `app/components/` beside the root layout, with no clean place for the next page's. `app/` keeps only the root `layout.tsx` and the files Next.js needs there, such as `globals.css`. A folder inside `app/` is only a route when it holds a `page.tsx` or `route.ts`, so `components/` and `utils/` folders inside `app/` are safe: they never become URLs.
157
156
 
@@ -299,25 +298,29 @@ Add the export to `utils/index.ts` whenever you add a function.
299
298
 
300
299
  ---
301
300
 
302
- ## 🔤 Constants: `r`, `s`, numbers, noData, animation, artwork and class names {#constants}
301
+ ## 🔤 Constants: `r`, `s` and shared values {#constants}
303
302
 
304
- Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files. Internal strings people never see are the one exception: see [`s`: strings](#s-strings).
303
+ **Every link goes in `r`, and every piece of text people see or hear goes in `s`**, both in `lib/constants/`, never written straight into a component. A link then changes in one place, and every piece of text is in one place when the site is translated into other languages.
304
+
305
+ **Every other value lives with the code that uses it, until it is shared.** A number, list or internal string that one file uses is a named constant at the top of that file. Once more than one file needs it, it moves to `lib/constants/`, into the file that fits it.
305
306
 
306
307
  ```text
307
308
  lib/constants/
308
- ├── routes.ts # r: every link
309
- ├── strings.ts # s: every piece of static text
310
- ├── numbers.ts # Every loose named number
311
- ├── noData.ts # Stand-in data, once the data's shape is decided
312
- ├── animation.ts # How things move, once there is any
313
- ├── artwork.ts # What is drawn and where, once there is any
314
- ├── classNames.ts # Class names shared between files, once there are any
315
- └── index.ts # Exports all of them
309
+ ├── routes.ts # r: every link
310
+ ├── strings.ts # s: every piece of text people see or hear
311
+ ├── numbers.ts # Numbers more than one file uses
312
+ ├── noData.ts # Stand-in data, once the data's shape is decided
313
+ ├── animation.ts # How things move, when more than one file uses it
314
+ ├── artwork.ts # What is drawn and where, when more than one file uses it
315
+ ├── classNames.ts # Class names shared between files
316
+ ├── status.ts # Statuses the app shares
317
+ ├── unsortedValues.ts # Values waiting for the person to say where they go
318
+ └── index.ts # Exports all of them
316
319
  ```
317
320
 
318
- **These seven files are the only ones.** Each is one file, never split by topic. `routes.ts`, `strings.ts`, `numbers.ts` and `index.ts` exist from the start; the other four are created only once the project has something to put in them.
321
+ `routes.ts`, `strings.ts` and `index.ts` exist from the start. Every other file is created only once there is something to put in it. Each is one file, never split by topic.
319
322
 
320
- | A value that is… | Goes in |
323
+ | A shared value that is… | Goes in |
321
324
  | ----------------------------------------------------------- | ------------------- |
322
325
  | A link | `r` in `routes.ts` |
323
326
  | Text people see or hear | `s` in `strings.ts` |
@@ -326,8 +329,9 @@ lib/constants/
326
329
  | A group of values that together say how something moves | `animation.ts` |
327
330
  | A group of values that together say what is drawn and where | `artwork.ts` |
328
331
  | A Tailwind class string used by more than one file | `classNames.ts` |
332
+ | A status more than one part of the app reads | `status.ts` |
329
333
 
330
- **This table is the base, and where each value goes is the project's call.** The table says what each file is for, not where every value in every project goes. The project reads its own values, decides which file each one belongs in, and keeps that choice the same across the codebase. A value that fits none of them goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, where the project records why. It is a coding decision, so the work carries on without waiting for a yes.
334
+ **This table is the base, and where each value goes is the project's call.** A shared value that fits none of these goes in a file of its own in `lib/constants/`, named after what it holds. When it is not clear where a value goes, it goes in [`unsortedValues.ts`](#unsorted-values) until the person says.
331
335
 
332
336
  A file outside the folder imports everything it needs in one line:
333
337
 
@@ -371,7 +375,7 @@ export const s = {
371
375
 
372
376
  - **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
373
377
  - **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
374
- - **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. The code is never pulled apart to move them into `lib/constants/`.
378
+ - **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. A status more than one part of the app reads goes in [`status.ts`](#statuses).
375
379
 
376
380
  ### A list of items with links
377
381
 
@@ -453,11 +457,11 @@ const insights =
453
457
  - **Dummy values sit at the top of `noData.ts`** as their own constants, `DUMMY_HEADING` and the rest. They are never added to `s`.
454
458
  - **noData is for the whole site.** All of it lives in this one file.
455
459
 
456
- ### Numbers: named, in one file {#numbers-named-and-kept-by-topic}
460
+ ### Numbers: named, and shared from one file {#numbers-named-and-kept-by-topic}
457
461
 
458
462
  **A number other than `-1`, `0` or `1` gets a name**, such as `MAXIMUM_RETRY_ATTEMPTS`. Those three mean "nothing", "one more" and "not found", so they read clearly as they are. Any other number was chosen by someone, and its name says what it controls. ESLint checks this with `no-magic-numbers`.
459
463
 
460
- **Every loose named number lives in `lib/constants/numbers.ts`**, even one that only one file uses, so every project finds its numbers in the same place. There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
464
+ **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`.** There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
461
465
 
462
466
  ```ts title="lib/constants/numbers.ts"
463
467
  export const COOKIE_DURATION_DAYS = 30;
@@ -518,9 +522,42 @@ export const SURFACE_CLASS_NAME =
518
522
  - **A class name used in one file stays inline in that file.**
519
523
  - **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
520
524
 
525
+ ### Statuses {#statuses}
526
+
527
+ **`status.ts` holds the statuses more than one part of the app reads**, such as the states a review or a workflow can be in. A status only one file reads stays at the top of that file.
528
+
529
+ ```ts title="lib/types/status.ts"
530
+ export type ReviewStatusType = "passed" | "rejected" | "errored";
531
+ ```
532
+
533
+ ```ts title="lib/constants/status.ts"
534
+ import type { ReviewStatusType } from "@/lib/types";
535
+
536
+ export const REVIEW_FAILED_STATUSES: readonly ReviewStatusType[] = [
537
+ "rejected",
538
+ "errored",
539
+ ];
540
+ ```
541
+
542
+ - **The status is the value the code checks. The words people see stay in `s`**, under the same key: `"rejected"` is what the code compares, and `s.reviewStatuses.rejected` is the "Rejected" on the badge.
543
+ - **Name each export after what it lists**, ending in `_STATUSES` or `_STATES`.
544
+
545
+ ### When it is not clear where a value goes {#unsorted-values}
546
+
547
+ **Put it in `lib/constants/unsortedValues.ts`, and carry on.** The work never waits for the answer.
548
+
549
+ **At the end of the work, ask the person about every value in it**, one line each, with where you would put it: at the top of the file that uses it, or in a shared file named after what it holds.
550
+
551
+ ```text
552
+ REVIEW_FAILED_STATUSES (used in runReview and ReviewBadge)
553
+ → keep it in runReview.ts, or move it to lib/constants/status.ts?
554
+ ```
555
+
556
+ Move each value where the person says, then delete the file. [`pnpm standards:check`](/docs/Guides/setup#checking-a-project) reports `unsortedValues.ts` for as long as it exists, so nothing is left waiting.
557
+
521
558
  ### Types for constants {#types-for-constants}
522
559
 
523
- **Every object and list constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand. **A single number or string needs no type of its own**: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed, and writing `: number` adds nothing.
560
+ **Every object and list constant in `lib/constants/` gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand. **A single number or string needs no type of its own**: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed, and writing `: number` adds nothing.
524
561
 
525
562
  ```ts title="lib/types/animation.ts"
526
563
  export interface EntranceAnimationType {
@@ -540,6 +577,7 @@ export const ENTRANCE_ANIMATION: EntranceAnimationType = {
540
577
  };
541
578
  ```
542
579
 
580
+ - **A constant kept at the top of the file that uses it is typed beside it**, from that file's own `.types.ts`, the same as its `Props`. `lib/types/` is for the shared constants.
543
581
  - **Types live in `lib/types/`, in files named by topic**, such as `animation.ts` and `artwork.ts`. A types file is not exempt from the 300-line limit: split it by topic when it grows.
544
582
  - **A type a constant needs lives in `lib/types/`**, with every type it depends on. Components import it from `@/lib/types`.
545
583
  - **`lib/types/` reads a constant's type straight from its file**: `import type { r } from "@/lib/constants/routes";`, never through `@/lib/constants`. It is the one exception to importing constants in one line. `import type` is removed at build, so the two folders reading each other's types never makes a real loop.
@@ -590,7 +628,7 @@ export const ENTRANCE_ANIMATION: EntranceAnimationType = {
590
628
  A list of keys a loop runs over, such as `planIds` in [A list of items with links](#a-list-of-items-with-links), is not a loose id: it stays a list.
591
629
 
592
630
  - **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`; a browser without that query misses the fallback, and the standard accepts that. **A media query the code reads is not CSS**, such as the one an animation library matches to switch motion off: it stays in its object in `animation.ts`.
593
- - **All seven files can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
631
+ - **Every file in `lib/constants/` can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
594
632
 
595
633
  ---
596
634
 
@@ -6,63 +6,52 @@ sidebar_position: 4
6
6
 
7
7
  Consistent import organization makes code easier to read and understand.
8
8
 
9
- ## Import Order
9
+ ## Import order is sorted for you
10
10
 
11
- Follow this order in all files:
11
+ **Prettier sorts the imports of every file** with `@ianvs/prettier-plugin-sort-imports`, the same way it sorts Tailwind classes. Nobody sorts imports by hand, and agents never reorder them themselves: `pnpm format`, or saving in the editor, does it. See [Import sorting](/docs/Standards/prettier#import-sorting).
12
12
 
13
- 1. **React and core packages**
14
- 2. **Internal workspace packages** (the project's own scope, e.g. `@acme/*`)
15
- 3. **External packages**
16
- 4. **Side effect imports**
17
- 5. **Parent imports** (`../`)
18
- 6. **Same-folder imports** (`./`)
19
- 7. **Style imports** (`.css`, `.module.css`)
13
+ ```tsx
14
+ "use client";
20
15
 
21
- ## Example
16
+ import { readFileSync } from "node:fs";
22
17
 
23
- ```tsx
24
- // 1. React and core packages
25
- import React, { useState, useEffect } from "react";
26
- import { Link } from "@radix-ui/react-navigation-menu";
18
+ import Link from "next/link";
19
+ import { useState } from "react";
20
+
21
+ import { Button } from "@/components/ui";
22
+ import { r, s } from "@/lib/constants";
23
+
24
+ import { formatDate } from "../utils/formatDate";
27
25
 
28
- // 2. Internal workspace packages
29
- import { Button } from "@acme/ui";
30
- import { useAuthentication } from "@acme/authentication";
26
+ import type { SampleProps } from "./Sample.types";
31
27
 
32
- // 3. External packages
33
- import { format } from "date-fns";
34
- import clsx from "clsx";
28
+ import "./sample.css";
29
+ ```
35
30
 
36
- // 4. Side effect imports
37
- import "prismjs/themes/prism-tomorrow.css";
31
+ Node's own modules, then packages, the project's `@/` aliases, parent folders (`../`), and the same folder (`./`). **Side-effect imports, such as CSS, go after every other import**: the sorter never moves them, because the order they load in can matter.
38
32
 
39
- // 5. Parent imports
40
- import { formatDate } from "../utils";
33
+ ## Importing components
41
34
 
42
- // 6. Same-folder imports
43
- import { Header } from "./Header";
44
- import { useUserData } from "./useUserData";
35
+ **`components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`**, and code outside a category imports from it, so imports stay short:
45
36
 
46
- // 7. Style imports
47
- import "./UserProfile.css";
48
- import styles from "./styles.module.css";
37
+ ```tsx
38
+ import { Button, Card } from "@/components/ui";
49
39
  ```
50
40
 
51
- ## Why This Order?
41
+ - **No `index.ts` directly in `components/`.** The import shows whether a component is a Design System Component, part of the site frame, or shared.
42
+ - **Inside a category, components import each other by file**, never through the category's own `index.ts`. See [Inside a folder, import files directly](#2-inside-a-folder-import-files-directly).
43
+ - **A category's `index.ts` exports only components a Client Component can import.** A Client Component that imports a category pulls in everything its `index.ts` exports, so one server-only component in it breaks the build for every Client Component that imports the category.
44
+ - **A component that reaches server-only code**, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`. It is left out of its category's `index.ts`, and imported from its own folder:
52
45
 
53
- 1. **React first** - Most important dependency, immediately visible
54
- 2. **Internal packages** - Your team's code, separate from third-party
55
- 3. **External packages** - Third-party dependencies
56
- 4. **Side effects** - Imports that don't export values (CSS, polyfills)
57
- 5. **Parent imports** - Code from parent directories
58
- 6. **Same-folder** - Code from the current directory
59
- 7. **Styles last** - Visual separation, easy to find style imports
46
+ ```tsx
47
+ // components/layout/siteHeader/SiteHeader.tsx
48
+ import "server-only";
60
49
 
61
- ## Rules
50
+ // app/layout.tsx
51
+ import { SiteHeader } from "@/components/layout/siteHeader";
52
+ ```
62
53
 
63
- - ✅ **Alphabetized** within each group
64
- - ✅ **Blank lines** between groups
65
- - ✅ **No duplicates** - Import each module once
54
+ `import "server-only";` makes a mistake fail the build with a clear error, instead of sending server code to the browser.
66
55
 
67
56
  ## Import Safety
68
57
 
@@ -152,7 +141,3 @@ export const database = createConnection(DATABASE_URL);
152
141
  Code that runs on import makes the order files load in matter. Code that only defines things does not.
153
142
 
154
143
  Enforced by ESLint `unicorn/no-top-level-side-effects`.
155
-
156
- ## Import Order Is Not Enforced
157
-
158
- The **order of the import lines** is a convention, not a lint rule. Follow the same pattern in every file so imports are easy to read, but ESLint will not report an error if the order differs.
@@ -330,7 +330,7 @@ Code files are camelCase or PascalCase. A short list of things are kebab-case in
330
330
  Use ESLint and Prettier to enforce these conventions automatically:
331
331
 
332
332
  - **eslint-plugin-react** - React naming conventions
333
- - **simple-import-sort** - Import ordering
333
+ - **@ianvs/prettier-plugin-sort-imports** - Import ordering, run by Prettier
334
334
  - **@typescript-eslint** - TypeScript naming rules
335
335
 
336
336
  See [ESLint](/docs/Standards/eslint) and [Prettier](/docs/Standards/prettier) configuration for setup.
@@ -9,6 +9,7 @@ import eslintReact from "!!raw-loader!@site/static/templates/eslint/react/eslint
9
9
  import eslintNextjs from "!!raw-loader!@site/static/templates/eslint/nextjs/eslint.config.mjs";
10
10
  import eslintBase from "!!raw-loader!@site/static/templates/eslint/base/eslint.config.mjs";
11
11
  import prettier from "!!raw-loader!@site/static/templates/prettier.config.mjs";
12
+ import prettierIgnore from "!!raw-loader!@site/static/templates/.prettierignore";
12
13
  import stylelintCss from "!!raw-loader!@site/static/templates/stylelint/css/stylelint.config.mjs";
13
14
  import stylelintScss from "!!raw-loader!@site/static/templates/stylelint/scss/stylelint.config.mjs";
14
15
  import globalsCss from "!!raw-loader!@site/static/templates/globals.css";
@@ -50,6 +51,7 @@ Each file is also served as a plain file, so a person or an AI agent can fetch i
50
51
  | [ESLint — Next.js](#eslintnextjs) | `eslint.config.mjs` in the project root | [`/templates/eslint/nextjs/eslint.config.mjs`](pathname:///templates/eslint/nextjs/eslint.config.mjs) |
51
52
  | [ESLint — JavaScript / Node.js](#eslintbase) | `eslint.config.mjs` in the project root | [`/templates/eslint/base/eslint.config.mjs`](pathname:///templates/eslint/base/eslint.config.mjs) |
52
53
  | [Prettier](#prettier) | `prettier.config.mjs` in the project root | [`/templates/prettier.config.mjs`](pathname:///templates/prettier.config.mjs) |
54
+ | [Prettier ignore](#prettierignore) | `.prettierignore` in the project root | [`/templates/.prettierignore`](pathname:///templates/.prettierignore) |
53
55
  | [Stylelint — CSS and CSS Modules](#stylelintcss) | `stylelint.config.mjs` in the project root | [`/templates/stylelint/css/stylelint.config.mjs`](pathname:///templates/stylelint/css/stylelint.config.mjs) |
54
56
  | [Stylelint — SCSS](#stylelintscss) | `stylelint.config.mjs` in the project root | [`/templates/stylelint/scss/stylelint.config.mjs`](pathname:///templates/stylelint/scss/stylelint.config.mjs) |
55
57
  | [Global styles and colour palette](#globalscss) | `app/globals.css` | [`/templates/globals.css`](pathname:///templates/globals.css) |
@@ -135,6 +137,18 @@ See the [Prettier page](/docs/Standards/prettier).
135
137
 
136
138
  ---
137
139
 
140
+ ## Prettier ignore {#prettierignore}
141
+
142
+ **Copy to:** `.prettierignore` in the project root, or add its lines to the project's own
143
+
144
+ See [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
145
+
146
+ <CodeBlock language="text" title=".prettierignore">
147
+ {prettierIgnore}
148
+ </CodeBlock>
149
+
150
+ ---
151
+
138
152
  ## Stylelint — CSS and CSS Modules {#stylelintcss}
139
153
 
140
154
  **Copy to:** `stylelint.config.mjs` in the project root
@@ -60,6 +60,7 @@ Anyone changing the standards adds a version, alongside the change:
60
60
  - **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
61
61
  - **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
62
62
  - **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
63
+ - **Anything a version can change in the `AGENTS.md` template lives between the `code-standards` markers.** A project copies only that section on an update, and `pnpm standards:check` compares only that section, so a rule outside the markers never reaches a project that is already set up.
63
64
  - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.2.2 — full version numbers`, so releases are easy to find in the git log.
64
65
  - **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
65
66
  - **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
@@ -68,10 +69,84 @@ Anyone changing the standards adds a version, alongside the change:
68
69
 
69
70
  ## Version 3
70
71
 
71
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.1
72
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.3
72
73
 
73
74
  Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
74
75
 
76
+ **Fixes in 3.3.3.** If the project already applied 3.3.2, check these:
77
+
78
+ - **The Ontology and Documentation sections of `AGENTS.md` are now inside the `code-standards` markers.** They were above them, so copying the Code standards section on an update never brought them in, and `pnpm standards:check` never noticed a project without them. 3.3.2's "Record a check only after it has run" rule was one of the rules that never arrived. Anything a version can change now lives inside the markers. The Documentation section's line about `docsSite/` now starts "If the project has a `docsSite/`".
79
+
80
+ **What to do:** copy the Code standards section of `AGENTS.md` from the template again: everything from `<!-- code-standards:start -->` to `<!-- code-standards:end -->`. It now ends with the Ontology and Documentation sections. Then delete the project's old Ontology and Documentation sections above the markers, so neither appears twice. Anything project-specific in them moves to a section of its own, outside the markers.
81
+
82
+ - **A section whose pages already share a folder needs no route group.** When all a section's pages sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and components three or more of its pages use go in its own `components/` folder. Never move pages just to make a route group. See [Where components live](/docs/Structure/folder-structure#-where-components-live). Nothing to do.
83
+ - **Prettier sorts imports.** The Prettier template adds `@ianvs/prettier-plugin-sort-imports`: Node's own modules, then packages, `@/` aliases, `../`, then `./`, with a blank line between groups. Directives such as `"use client"` stay at the top, type imports stay on their own line, and side-effect imports, such as CSS, never move. Nobody sorts imports by hand. The seven-step order on [Import Organization](/docs/Structure/import-organization) is gone. See [Import sorting](/docs/Standards/prettier#import-sorting).
84
+
85
+ **What to do:**
86
+
87
+ 1. `pnpm add -D @ianvs/prettier-plugin-sort-imports`.
88
+ 2. Copy `static/templates/prettier.config.mjs` over the project's again. A project without Tailwind removes `prettier-plugin-tailwindcss` and `tailwindStylesheet` as before.
89
+ 3. Move each side-effect import, such as `import "./globals.css";`, below the file's other imports.
90
+ 4. Run `pnpm format`, and **commit the result on its own**, with nothing else in it, so the reordering never hides a real change in a review.
91
+
92
+ - **Components are imported from their category.** `components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`, and code outside a category imports from it: `import { Button } from "@/components/ui";`. There is no `components/index.ts`, and `pnpm standards:check` now reports one. **A category's `index.ts` exports only components a Client Component can import**: a Client Component that imports a category pulls in everything it exports, so one server-only component in it breaks the build. A component that reaches server-only code, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`, is left out of the `index.ts`, and is imported from its own folder, such as `@/components/layout/siteHeader`. Tested with a Next.js 16 build: the build fails with a server-only component in the category's `index.ts`, and passes once it is imported from its own folder. See [Importing components](/docs/Structure/import-organization#importing-components).
93
+
94
+ **What to do:**
95
+
96
+ 1. Delete any `components/index.ts`, and point its imports at the category: `@/components/ui`, `@/components/layout` or `@/components/shared`.
97
+ 2. Give each category an `index.ts` if it has none.
98
+ 3. For each component that reaches server-only code, add `import "server-only";` at the top, take it out of its category's `index.ts`, and import it from its own folder.
99
+ 4. Copy the Code standards section of `AGENTS.md` from the template again, if not already done for the first fix above.
100
+
101
+ - **"Unfinished changes": write "None", with no note after it.** 3.3.2 said "exactly None", but the check also accepts "None." with a full stop. The template now says what the check does. Nothing to do.
102
+
103
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `AGENTS.md` has one Ontology and one Documentation section, both inside the markers; `pnpm format:check` passes; `git ls-files components/index.ts` finds nothing; no category's `index.ts` exports a file that `grep -rln "server-only" components` lists.
104
+
105
+ **Fixes in 3.3.2.** If the project already applied 3.3.1, check these:
106
+
107
+ - **Only well-formed lines under "Details" count as exceptions.** `pnpm standards:check` used to read any line under "Details" in `docs/development/coding-standards.md` that started with a number as an exception to that standard, so a plain numbered list switched standards off without a word. Now a line counts only in the shape `N. Name — skipped: reason` or `N. Name — changed: reason`, with the number and name from the [setup list](/docs/Guides/setup#3-agree-the-standards). Any other line that starts with a number fails the check, and a misread line can never be hidden as an exception itself.
108
+
109
+ **What to do:** run `pnpm standards:check`. For each line under "Details" it reports, write it in the exception shape, or turn it into a bullet point that does not start with a number. Copy the "Details" and "Unfinished changes" notes from `static/templates/docs/development/coding-standards.md` if the project's still has the old ones.
110
+
111
+ - **An exception can cover only some files.** Name them in backticks after `for`, as in the [setup example](/docs/Guides/setup#3-agree-the-standards). The check then hides findings for those files only. `**` matches any depth, `*` stays inside one folder, and a path ending in `/` covers the whole folder. An exception that names no files still covers the whole standard. A `for` with no path in backticks fails the check, because it would otherwise cover every file.
112
+
113
+ **What to do:** nothing, unless the project skipped a whole standard only to cover some files. Then narrow that exception to the files, with the person's yes.
114
+
115
+ - **`AGENTS.md` and the agent skills are Prettier-ignored.** The check compares them word for word with the templates, and Prettier reformatted them, so a formatted project always failed standard 21. There is now a `.prettierignore` template: see [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
116
+
117
+ **What to do:** add these lines to the project's `.prettierignore`, then copy the Code standards section of `AGENTS.md` and the skills from the templates again, so Prettier's changes to them are undone:
118
+
119
+ ```text title=".prettierignore"
120
+ AGENTS.md
121
+ .agents/skills/
122
+ .claude/commands/
123
+ ```
124
+
125
+ If the project wrapped the section in `<!-- prettier-ignore-start -->` and `<!-- prettier-ignore-end -->` to work around this, remove those two comments.
126
+
127
+ - **`components/` holds only `ui/`, `layout/` and `shared/`**, as [Where components live](/docs/Structure/folder-structure#-where-components-live) already said. `pnpm standards:check` now reports any other folder, and any component file, directly in `components/`.
128
+
129
+ **What to do:** run `pnpm standards:check`, and move each folder or file it reports into the home that fits: `components/ui/`, `components/layout/`, `components/shared/`, or the `components/` folder of the page or section that uses it.
130
+
131
+ - **Only `r`, `s` and shared values go in `lib/constants/`.** Every link still goes in `r` and every piece of text people see or hear in `s`, so links change in one place and the text can be translated. Every other value, such as a number, list, status or internal string, now lives at the top of the file that uses it until more than one file needs it, then moves to the file in `lib/constants/` that fits. Forcing a value only one file uses into a global file sent readers across the project to find it. `lib/constants/` may hold any file named after what it holds, such as the new `status.ts` for statuses the app shares; only `routes.ts`, `strings.ts` and `index.ts` are required, and every file in it is exempt from `max-lines`. A constant kept at the top of its file is typed from that file's own `.types.ts`; `lib/types/` is for the shared constants. See [Constants](/docs/Structure/folder-structure#constants).
132
+
133
+ **What to do:** nothing has to move. Copy the Code standards section of `AGENTS.md` from the template again, and copy the project's ESLint template over `eslint.config.mjs` again: the `max-lines` block now reads `lib/constants/*.ts`. A value moved into `lib/constants/` only because the old rule said so may move back to the file that uses it when that file is next changed. Remove any comment that names a "Details" entry for a value that fitted no file: such a value now goes in `unsortedValues.ts`, below.
134
+
135
+ - **When it is not clear where a value goes, it goes in `lib/constants/unsortedValues.ts`.** The agent carries on, and at the end of the work asks the person where each value in it goes, then moves each one and deletes the file. `pnpm standards:check` reports the file for as long as it exists. See [When it is not clear where a value goes](/docs/Structure/folder-structure#unsorted-values).
136
+
137
+ **What to do:** nothing. Copied in with the `AGENTS.md` section above.
138
+
139
+ - **Record a check only after it has run.** A doc never says 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. The `AGENTS.md` template, [Docs](/docs/Standards/documentation) and [Regression Checks](/docs/Guides/regression-checks) say so.
140
+
141
+ **What to do:** read `docs/testing/regression.md` and any other doc that records a check. Remove any result, URL or commit for a check that has not actually run. Copied into `AGENTS.md` with the section above. _Changed in 3.3.3: the rule was in the template's Documentation section, outside the markers, so copying the section did not bring it in. Do the 3.3.3 step._
142
+
143
+ - **Comparing two local servers: copy `node_modules`, never symlink it.** Turbopack refuses a `node_modules` that points outside the project folder. On macOS, `cp -Rc` makes a copy-on-write clone in seconds. See [Comparing two local servers instead](/docs/Guides/regression-checks#comparing-two-local-servers-instead). Nothing to do.
144
+ - **"Unfinished changes" says exactly "None" when nothing is left.** A note after it, such as "None. ESLint was switched on in an earlier ticket.", reads as an unfinished change. The template and the check's report now say so.
145
+
146
+ **What to do:** if the project's "Unfinished changes" says "None" with a note after it, leave only "None". The history belongs in the change that did the work.
147
+
148
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `.prettierignore` lists `AGENTS.md`, `.agents/skills/` and `.claude/commands/`; `grep -rn "prettier-ignore" AGENTS.md` finds nothing; `pnpm format:check` passes; `lib/constants/unsortedValues.ts` does not exist.
149
+
75
150
  **Fixes in 3.3.1.** If the project already applied 3.3.0, check these:
76
151
 
77
152
  - **A single number or string needs no type of its own.** 3.3.0 said every constant gets a type from `lib/types/`. It means every object and list constant: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed. The Animation and Artwork examples now have their types. Nothing to do, unless the project added `: number` or `: string` only to follow 3.3.0: those can stay or go.
@@ -144,7 +219,7 @@ grep -rnE "(^|[^y] )([A-Z][A-Za-z]*Type|string|number|boolean)\[\]" lib/types/
144
219
 
145
220
  - **Where each constant goes is the project's call.** The [Constants table](/docs/Structure/folder-structure#constants) says what each file is for, not where every value in every project goes. 3.2.1's examples and check named values from one project; they are now neutral, and `pnpm standards:check` no longer guesses a value's file from its name. It lists the file, and the project decides.
146
221
 
147
- **What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
222
+ **What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
148
223
 
149
224
  - **An id lives in the object that uses it.** A value that picks which item something acts on is a key inside that object, never a loose constant. A list of keys a loop runs over stays a list. See the [before and after](/docs/Structure/folder-structure#constants-rules).
150
225
 
@@ -192,7 +267,7 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
192
267
 
193
268
  Each animation and artwork object stays whole, its values named by their keys. Never lift them out into `numbers.ts`, which keeps loose single numbers only: lifting them out makes long names and splits one object across files. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
194
269
 
195
- **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
270
+ **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
196
271
 
197
272
  - **A loop over a list looks each item up by its key.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's key, typed from `r`: `keyof typeof r.plans`. Delete separate lookup objects that map a key to its link: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
198
273
 
@@ -249,8 +324,8 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
249
324
  - **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
250
325
  - **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
251
326
  - **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
252
- - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top.
253
- - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._
327
+ - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
328
+ - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._ _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
254
329
  - **Write `r` and `s` keys out by name**, `r.plans.starter`, never `r.plans[planId]`. A list of items keeps its words in `s` and its links in `r` under the same keys. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
255
330
  - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
256
331
  - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant. _Withdrawn in 3.3.0: constants now take their types from `lib/types/`. Do the 3.3.0 step instead._
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.3.1",
3
+ "version": "3.3.3",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -73,6 +73,7 @@ const checkUiComponents = ({
73
73
  )
74
74
  .map((folder) => ({
75
75
  standard: "15",
76
+ file: `components/ui/${folder}/`,
76
77
  message: `components/ui/${folder} is not on the Design System Components list. If it takes everything through props, record it under "Components for the standards" in docs/development/coding-standards.md; otherwise move it out of components/ui/`,
77
78
  page: "docs/design-system-components.md",
78
79
  }));
@@ -109,6 +110,7 @@ const checkTestFiles = ({ projectDirectory, projectFiles }) => {
109
110
  .filter((filePath) => !findTestFile({ filePath, projectFileSet }))
110
111
  .map((filePath) => ({
111
112
  standard: "4",
113
+ file: filePath,
112
114
  message: `${filePath} has no test file beside it`,
113
115
  page: "docs/Standards/readable-code.md#every-function-and-component-has-a-test-file",
114
116
  }));
@@ -1,65 +1,39 @@
1
- // Standard 12.1: lib/constants/ holds the seven standard files and
2
- // nothing else, and no component keeps its own constants file.
1
+ // Standard 12.1: lib/constants/ has r, s and the index that exports
2
+ // them, and nothing is left waiting in unsortedValues.ts.
3
3
  const REQUIRED_FILES = [
4
4
  "lib/constants/index.ts",
5
5
  "lib/constants/routes.ts",
6
6
  "lib/constants/strings.ts",
7
- "lib/constants/numbers.ts",
8
7
  ];
9
- // Created only once the project has something to put in them.
10
- const OPTIONAL_FILES = [
11
- "lib/constants/noData.ts",
12
- "lib/constants/animation.ts",
13
- "lib/constants/artwork.ts",
14
- "lib/constants/classNames.ts",
15
- ];
16
- const CONSTANTS_FOLDER = "lib/constants/";
17
- const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
18
- const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
8
+ const UNSORTED_VALUES_FILE = "lib/constants/unsortedValues.ts";
19
9
  const PAGE = "docs/Structure/folder-structure.md#constants";
20
- // Where each value goes is the project's call, made from the table.
21
- const NEXT_STEP =
22
- "Move each of its values into the file the Constants table says fits, and record any value that fits none in docs/development/coding-standards.md";
23
10
 
24
11
  const checkMissingFiles = ({ projectFileSet }) =>
25
12
  REQUIRED_FILES.filter(
26
13
  (filePath) => !projectFileSet.has(filePath),
27
14
  ).map((filePath) => ({
28
15
  standard: "12.1",
16
+ file: filePath,
29
17
  message: `${filePath} is missing`,
30
18
  page: PAGE,
31
19
  }));
32
20
 
33
- const checkExtraFiles = ({ projectFiles }) => {
34
- const standardFiles = new Set([
35
- ...REQUIRED_FILES,
36
- ...OPTIONAL_FILES,
37
- ]);
38
- return projectFiles
39
- .filter((filePath) => filePath.startsWith(CONSTANTS_FOLDER))
40
- .filter((filePath) => CODE_FILE_PATTERN.test(filePath))
41
- .filter((filePath) => !filePath.includes(".test."))
42
- .filter((filePath) => !standardFiles.has(filePath))
43
- .map((filePath) => ({
44
- standard: "12.1",
45
- message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
46
- page: PAGE,
47
- }));
48
- };
49
-
50
- const checkComponentFiles = ({ projectFiles }) =>
51
- projectFiles
52
- .filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
53
- .filter((filePath) => !filePath.startsWith("node_modules/"))
54
- .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
55
- .map((filePath) => ({
56
- standard: "12.1",
57
- message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
58
- page: PAGE,
59
- }));
21
+ const checkUnsortedValues = ({ projectFileSet }) =>
22
+ projectFileSet.has(UNSORTED_VALUES_FILE)
23
+ ? [
24
+ {
25
+ standard: "12.1",
26
+ file: UNSORTED_VALUES_FILE,
27
+ message: `${UNSORTED_VALUES_FILE} still holds values. Ask the person where each one goes, move it there, and delete the file`,
28
+ page: PAGE,
29
+ },
30
+ ]
31
+ : [];
60
32
 
61
- export const checkConstants = ({ projectFiles }) => [
62
- ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
63
- ...checkExtraFiles({ projectFiles }),
64
- ...checkComponentFiles({ projectFiles }),
65
- ];
33
+ export const checkConstants = ({ projectFiles }) => {
34
+ const projectFileSet = new Set(projectFiles);
35
+ return [
36
+ ...checkMissingFiles({ projectFileSet }),
37
+ ...checkUnsortedValues({ projectFileSet }),
38
+ ];
39
+ };