@activatus/code-standards 3.3.2 โ 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 +1 -0
- package/docs/Guides/migrating.md +1 -1
- package/docs/Guides/setup.md +1 -1
- package/docs/Standards/eslint.md +1 -1
- package/docs/Standards/prettier.md +51 -4
- package/docs/Structure/folder-structure.md +2 -1
- package/docs/Structure/import-organization.md +31 -46
- package/docs/Structure/naming-conventions.md +1 -1
- package/docs/version-history.md +32 -2
- package/package.json +1 -1
- package/scripts/verifyStandards/checkStructure.mjs +15 -0
- package/static/templates/AGENTS.md +26 -24
- package/static/templates/docs/development/coding-standards.md +1 -1
- package/static/templates/prettier.config.mjs +20 -2
package/README.md
CHANGED
|
@@ -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.
|
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.
|
package/docs/Guides/setup.md
CHANGED
|
@@ -178,7 +178,7 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
|
|
|
178
178
|
| Standard | What to set up |
|
|
179
179
|
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
180
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 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)
|
|
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
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
183
|
| 9. EditorConfig | Copy `static/templates/.editorconfig` |
|
|
184
184
|
| 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -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
|
{
|
|
@@ -97,7 +115,36 @@ The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindl
|
|
|
97
115
|
|
|
98
116
|
- **It is part of the standard**, not a project extra. Every project that uses Tailwind has it.
|
|
99
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.
|
|
100
|
-
- **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.
|
|
101
148
|
|
|
102
149
|
## Settings reference
|
|
103
150
|
|
|
@@ -146,10 +146,11 @@ project-root/
|
|
|
146
146
|
| **The site frame** โ navigation, header, footer | `components/layout/` | `components/layout/siteHeader/` |
|
|
147
147
|
| **Three or more pages** of this project | `components/shared/` | `components/shared/pricingTable/` |
|
|
148
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/` |
|
|
149
150
|
| **One or two pages** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
|
|
150
151
|
| **The homepage** | `app/(homepage)/components/` | `app/(homepage)/components/heroSection/` |
|
|
151
152
|
|
|
152
|
-
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.
|
|
153
154
|
|
|
154
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.
|
|
155
156
|
|
|
@@ -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
|
|
9
|
+
## Import order is sorted for you
|
|
10
10
|
|
|
11
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
16
|
+
import { readFileSync } from "node:fs";
|
|
22
17
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
import {
|
|
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
|
-
|
|
29
|
-
import { Button } from "@acme/ui";
|
|
30
|
-
import { useAuthentication } from "@acme/authentication";
|
|
26
|
+
import type { SampleProps } from "./Sample.types";
|
|
31
27
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
import clsx from "clsx";
|
|
28
|
+
import "./sample.css";
|
|
29
|
+
```
|
|
35
30
|
|
|
36
|
-
|
|
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
|
-
|
|
40
|
-
import { formatDate } from "../utils";
|
|
33
|
+
## Importing components
|
|
41
34
|
|
|
42
|
-
|
|
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
|
-
|
|
47
|
-
import "
|
|
48
|
-
import styles from "./styles.module.css";
|
|
37
|
+
```tsx
|
|
38
|
+
import { Button, Card } from "@/components/ui";
|
|
49
39
|
```
|
|
50
40
|
|
|
51
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
50
|
+
// app/layout.tsx
|
|
51
|
+
import { SiteHeader } from "@/components/layout/siteHeader";
|
|
52
|
+
```
|
|
62
53
|
|
|
63
|
-
-
|
|
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
|
-
-
|
|
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.
|
package/docs/version-history.md
CHANGED
|
@@ -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,39 @@ 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.
|
|
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
|
+
|
|
75
105
|
**Fixes in 3.3.2.** If the project already applied 3.3.1, check these:
|
|
76
106
|
|
|
77
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,7 +138,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
|
|
|
108
138
|
|
|
109
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.
|
|
110
140
|
|
|
111
|
-
**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.
|
|
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._
|
|
112
142
|
|
|
113
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.
|
|
114
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.3.
|
|
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",
|
|
@@ -13,6 +13,10 @@ const UNGROUPED_HOMEPAGE_PATTERN =
|
|
|
13
13
|
const TOP_COMPONENTS_FOLDER_PATTERN =
|
|
14
14
|
/^((?:src\/)?components\/([^/]+))\//;
|
|
15
15
|
const COMPONENTS_HOMES = new Set(["ui", "layout", "shared"]);
|
|
16
|
+
// The project's components/ has no index.ts of its own: code imports
|
|
17
|
+
// from a category, "@/components/ui".
|
|
18
|
+
const COMPONENTS_INDEX_PATTERN =
|
|
19
|
+
/^(?:src\/)?components\/index\.(?:ts|tsx|js|jsx)$/;
|
|
16
20
|
// A component file directly in components/: components/Foo.tsx.
|
|
17
21
|
const LOOSE_COMPONENT_FILE_PATTERN =
|
|
18
22
|
/^(?:src\/)?components\/[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
|
|
@@ -99,6 +103,16 @@ const checkLooseComponentFolders = ({ projectFiles }) => {
|
|
|
99
103
|
}));
|
|
100
104
|
};
|
|
101
105
|
|
|
106
|
+
const checkComponentsIndex = ({ projectFiles }) =>
|
|
107
|
+
projectFiles
|
|
108
|
+
.filter((filePath) => COMPONENTS_INDEX_PATTERN.test(filePath))
|
|
109
|
+
.map((filePath) => ({
|
|
110
|
+
standard: "13",
|
|
111
|
+
file: filePath,
|
|
112
|
+
message: `${filePath} should not exist. Import from a category instead, such as "@/components/ui", and delete it`,
|
|
113
|
+
page: "docs/Structure/import-organization.md#importing-components",
|
|
114
|
+
}));
|
|
115
|
+
|
|
102
116
|
const checkHomepage = ({ projectFiles }) =>
|
|
103
117
|
projectFiles
|
|
104
118
|
.filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
|
|
@@ -113,6 +127,7 @@ export const checkStructure = ({ projectFiles }) => {
|
|
|
113
127
|
const componentFolders = listComponentFolders({ projectFiles });
|
|
114
128
|
return [
|
|
115
129
|
...checkLooseComponentFolders({ projectFiles }),
|
|
130
|
+
...checkComponentsIndex({ projectFiles }),
|
|
116
131
|
...checkSubComponentFolders({ componentFolders }),
|
|
117
132
|
...checkHomepage({ projectFiles }),
|
|
118
133
|
];
|
|
@@ -80,34 +80,11 @@ Example: `๐ข [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title
|
|
|
80
80
|
| --- | --- | --- |
|
|
81
81
|
| `[VARIABLE_NAME]` | [Yes / No] | [What it is for] |
|
|
82
82
|
|
|
83
|
-
## Ontology
|
|
84
|
-
|
|
85
|
-
Activatus uses a fixed vocabulary, the ontology, in two parts:
|
|
86
|
-
|
|
87
|
-
- **Code words** โ component, utils, Decision Doc and the rest โ are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
|
|
88
|
-
- **Product words** โ what this project builds and how its work is planned โ are defined in `docs/product/ontology.md`.
|
|
89
|
-
|
|
90
|
-
- **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win โ point the difference out.
|
|
91
|
-
- **Use their terms** in code, docs, database names and messages โ never a synonym. It is `utils`, not `helpers` or `utilities`.
|
|
92
|
-
- **Never use a term either ontology has removed.**
|
|
93
|
-
- If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
|
|
94
|
-
|
|
95
|
-
## Documentation
|
|
96
|
-
|
|
97
|
-
The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
|
|
98
|
-
|
|
99
|
-
- **Read them before starting work** โ the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
|
|
100
|
-
- **Check each doc's 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.
|
|
101
|
-
- **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
|
|
102
|
-
- **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.
|
|
103
|
-
- **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
|
|
104
|
-
- Do not edit `docsSite/` unless the task is about the docs viewer itself.
|
|
105
|
-
|
|
106
83
|
<!-- code-standards:start -->
|
|
107
84
|
|
|
108
85
|
## Code standards
|
|
109
86
|
|
|
110
|
-
**This section
|
|
87
|
+
**This section, and the Ontology and Documentation sections after it, are 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.
|
|
111
88
|
|
|
112
89
|
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.
|
|
113
90
|
|
|
@@ -143,6 +120,8 @@ Follow these rules in every change:
|
|
|
143
120
|
- **The linter only checks some names.** Folders, props, form fields, database columns, routes and environment variables are not linted โ check every one of them yourself.
|
|
144
121
|
- **Always `const`.** Never `var`. Use `let` only when a value must be reassigned, with `// eslint-disable-next-line no-restricted-syntax -- <reason>` on the line above.
|
|
145
122
|
- **Arrow functions everywhere.** Never use the `function` keyword: `export const Button = () => {}`, not `export function Button() {}`.
|
|
123
|
+
- **Never sort imports by hand.** Prettier sorts them on `pnpm format`. Side-effect imports, such as CSS, go after every other import.
|
|
124
|
+
- **Import components from their category:** `import { Button } from "@/components/ui";`. There is no `components/index.ts`. A category's `index.ts` exports only components a Client Component can import: a component that reaches server-only code starts with `import "server-only";`, is left out of it, and is imported from its own folder, such as `@/components/layout/siteHeader`.
|
|
146
125
|
- **No circular imports, ever.** A file never imports a file that imports it back. Inside a folder, import files directly โ never through the folder's own `index.ts` โ and never import a parent component from its sub-component.
|
|
147
126
|
- **Define before use.** A function or variable is written above the code that uses it.
|
|
148
127
|
- **A function does one thing.**
|
|
@@ -178,6 +157,29 @@ Follow these rules in every change:
|
|
|
178
157
|
|
|
179
158
|
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.
|
|
180
159
|
|
|
160
|
+
## Ontology
|
|
161
|
+
|
|
162
|
+
Activatus uses a fixed vocabulary, the ontology, in two parts:
|
|
163
|
+
|
|
164
|
+
- **Code words** โ component, utils, Decision Doc and the rest โ are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
|
|
165
|
+
- **Product words** โ what this project builds and how its work is planned โ are defined in `docs/product/ontology.md`.
|
|
166
|
+
|
|
167
|
+
- **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win โ point the difference out.
|
|
168
|
+
- **Use their terms** in code, docs, database names and messages โ never a synonym. It is `utils`, not `helpers` or `utilities`.
|
|
169
|
+
- **Never use a term either ontology has removed.**
|
|
170
|
+
- If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
|
|
171
|
+
|
|
172
|
+
## Documentation
|
|
173
|
+
|
|
174
|
+
The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
|
|
175
|
+
|
|
176
|
+
- **Read them before starting work** โ the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
|
|
177
|
+
- **Check each doc's 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.
|
|
178
|
+
- **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
|
|
179
|
+
- **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.
|
|
180
|
+
- **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
|
|
181
|
+
- If the project has a `docsSite/`, do not edit it unless the task is about the docs viewer itself.
|
|
182
|
+
|
|
181
183
|
<!-- code-standards:end -->
|
|
182
184
|
|
|
183
185
|
## Available skills
|
|
@@ -24,7 +24,7 @@ Every Activatus project follows the same standards, so people and agents can mov
|
|
|
24
24
|
|
|
25
25
|
## Unfinished changes
|
|
26
26
|
|
|
27
|
-
[Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write
|
|
27
|
+
[Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write "None", with no note after it: a note after "None" reads as an unfinished change.]
|
|
28
28
|
|
|
29
29
|
## Related
|
|
30
30
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
|
|
1
|
+
/** @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
|
|
2
2
|
const config = {
|
|
3
3
|
// Short lines, so code reads well on a phone.
|
|
4
4
|
printWidth: 70,
|
|
@@ -12,7 +12,25 @@ const config = {
|
|
|
12
12
|
arrowParens: "always",
|
|
13
13
|
semi: true,
|
|
14
14
|
endOfLine: "lf",
|
|
15
|
-
|
|
15
|
+
// The Tailwind plugin must stay last.
|
|
16
|
+
plugins: [
|
|
17
|
+
"@ianvs/prettier-plugin-sort-imports",
|
|
18
|
+
"prettier-plugin-tailwindcss",
|
|
19
|
+
],
|
|
20
|
+
// Node's own modules, packages, the project's @/ aliases, then
|
|
21
|
+
// ../ and ./, with a blank line between groups. Side-effect
|
|
22
|
+
// imports, such as CSS, never move.
|
|
23
|
+
importOrder: [
|
|
24
|
+
"<BUILTIN_MODULES>",
|
|
25
|
+
"",
|
|
26
|
+
"<THIRD_PARTY_MODULES>",
|
|
27
|
+
"",
|
|
28
|
+
"^@/",
|
|
29
|
+
"",
|
|
30
|
+
"^[.][.]/",
|
|
31
|
+
"",
|
|
32
|
+
"^[.]/",
|
|
33
|
+
],
|
|
16
34
|
tailwindStylesheet: "./app/globals.css",
|
|
17
35
|
overrides: [
|
|
18
36
|
{
|