@activatus/code-standards 3.3.3 → 3.3.5

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.
@@ -171,7 +171,7 @@ it makes that the code standards do not cover? Yes or no?
171
171
 
172
172
  Do only the standards the person agreed to. Copy every file from `node_modules/@activatus/code-standards/static/templates/` — never write a config file from scratch.
173
173
 
174
- **Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment, for example `/** @type {import("next").NextConfig} */`. A tool that cannot read `.mjs` keeps its own format.
174
+ **Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment over three lines, `/**`, then `@type {import("next").NextConfig}`, then `*/`, as in the templates. ESLint rejects the one-line form and a `*` at the start of each line. A tool that cannot read `.mjs` keeps its own format.
175
175
 
176
176
  **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
177
177
 
@@ -179,7 +179,7 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
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
181
  | 7. Prettier | `pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
182
- | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
182
+ | 8. Stylelint | Every project with hand-written CSS or SCSS, and a Tailwind `globals.css` counts. Install the packages and 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) |
185
185
  | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
@@ -245,7 +245,9 @@ The project's `next.config.mjs` forwards `/docs` to the docs site, but only when
245
245
  ```js title="next.config.mjs"
246
246
  const DOCS_URL = process.env.DOCS_URL;
247
247
 
248
- /** @type {import("next").NextConfig} */
248
+ /**
249
+ @type {import("next").NextConfig}
250
+ */
249
251
  const nextConfig = {
250
252
  async rewrites() {
251
253
  // The docs are only served when DOCS_URL is set. It is never set in production.
@@ -18,7 +18,9 @@ pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwin
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("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
21
+ /**
22
+ @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions}
23
+ */
22
24
  const config = {
23
25
  // Short lines, so code reads well on a phone.
24
26
  printWidth: 70,
@@ -5,7 +5,7 @@ sidebar_label: "Stylelint"
5
5
 
6
6
  # Stylelint Configuration
7
7
 
8
- Components are styled with [Tailwind CSS](/docs/Standards/styling), and Stylelint lints the CSS that is still written by hand — `globals.css` and any CSS Modules. Start from the config below that matches the project:
8
+ Components are styled with [Tailwind CSS](/docs/Standards/styling), and Stylelint lints the CSS that is still written by hand — `globals.css` and any CSS Modules. **Every project with a `.css` or `.scss` file has Stylelint**, so a Tailwind project with only `globals.css` has it too. `pnpm standards:check` reports a missing `stylelint.config.mjs`. CSS in `vendor/` and `docsSite/` does not count. Start from the config below that matches the project:
9
9
 
10
10
  | Config | Use when |
11
11
  | --------------------------------------- | ----------------------------------------- |
@@ -31,7 +31,9 @@ Create `stylelint.config.mjs` in your project root:
31
31
  ### Plain CSS and CSS Modules
32
32
 
33
33
  ```js title="stylelint.config.mjs"
34
- /** @type {import("stylelint").Config} */
34
+ /**
35
+ @type {import("stylelint").Config}
36
+ */
35
37
  const config = {
36
38
  ignoreFiles: ["**/vendor/**"],
37
39
  extends: [
@@ -78,7 +80,9 @@ export default config;
78
80
  ### SCSS
79
81
 
80
82
  ```js title="stylelint.config.mjs"
81
- /** @type {import("stylelint").Config} */
83
+ /**
84
+ @type {import("stylelint").Config}
85
+ */
82
86
  const config = {
83
87
  ignoreFiles: ["**/vendor/**"],
84
88
  extends: [
@@ -53,6 +53,16 @@ import { Button, Card } from "@/components/ui";
53
53
 
54
54
  `import "server-only";` makes a mistake fail the build with a clear error, instead of sending server code to the browser.
55
55
 
56
+ - **Tests mock `server-only`.** Outside a Next.js build, `import "server-only";` always throws, so a Vitest test of the component, or of anything that imports it, fails before it runs. Mock it once in the Vitest setup file, and list that file in `setupFiles` in `vitest.config.mjs`:
57
+
58
+ ```js
59
+ // vitest.setup.mjs
60
+ import { vi } from "vitest";
61
+
62
+ // server-only throws outside a Next.js build.
63
+ vi.mock("server-only", () => ({}));
64
+ ```
65
+
56
66
  ## Import Safety
57
67
 
58
68
  These four rules **are** enforced, and they are not about tidiness. They stop a whole class of bug: code that runs before the thing it needs exists.
@@ -61,6 +61,7 @@ Anyone changing the standards adds a version, alongside the change:
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
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.
64
+ - **`pnpm devtest` must pass before publishing.** Run it, then `pnpm publish`. It checks the lint packages are the latest a project would install, then runs the tests, lints every template the way a project does, and checks formatting, types and the site build.
64
65
  - **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.
65
66
  - **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.
66
67
  - **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.
@@ -69,10 +70,35 @@ Anyone changing the standards adds a version, alongside the change:
69
70
 
70
71
  ## Version 3
71
72
 
72
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.3
73
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.5
73
74
 
74
75
  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.
75
76
 
77
+ **Fixes in 3.3.5.** If the project already applied 3.3.4, check these:
78
+
79
+ - **`pnpm standards:check` now reports a missing Stylelint config.** Standard 8 covers all hand-written CSS, and a Tailwind `globals.css` is hand-written CSS, but the check only looked at `stylelint.config.mjs` when there was one. A project with a `.css` or `.scss` file outside `vendor/` and `docsSite/`, and no `stylelint.config.mjs`, now fails standard 8. See [Stylelint](/docs/Standards/stylelint).
80
+
81
+ **What to do:** if the project has no `stylelint.config.mjs`:
82
+
83
+ 1. Install the packages from the [Stylelint page](/docs/Standards/stylelint#installation).
84
+ 2. Copy `static/templates/stylelint/css/stylelint.config.mjs`, or the `scss` one for SCSS.
85
+ 3. Add the `lint:css` and `lint:css:fix` scripts from the [Stylelint page](/docs/Standards/stylelint), run `pnpm lint:css`, and fix what it finds.
86
+ 4. If `docs/development/coding-standards.md` says Stylelint was set up, check that it really was.
87
+
88
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `pnpm lint:css` passes.
89
+
90
+ **Fixes in 3.3.4.** If the project already applied 3.3.3, check these:
91
+
92
+ - **The config templates now pass the template ESLint config.** `prettier.config.mjs`, `next.config.mjs`, both `stylelint.config.mjs` templates and the regression check's `playwright.config.mjs` started with a one-line `/** @type … */` comment, which `unicorn/single-line-block-comment-style` rejects. They now use a JSDoc comment over three lines, with no `*` at the start of each line, which TypeScript reads the same way. The regression check's `playwright.config.mjs` and `pageLayout.visual.ts` had three more lint errors, now fixed. The code standards now lint every template the way a project does, with the latest lint packages, before every release, so this cannot ship again.
93
+
94
+ **What to do:** copy each of these templates the project uses over its own again: `prettier.config.mjs`, `next.config.mjs`, `stylelint.config.mjs`, and, if the project has a regression check, `tests/visual/playwright.config.mjs` and `tests/visual/pageLayout.visual.ts`. If the project turned a lint rule off for one of them while waiting for this version, remove that from `eslint.overrides.mjs` and from `docs/development/coding-standards.md`.
95
+
96
+ - **Tests mock `server-only`.** `import "server-only";` always throws outside a Next.js build, so any Vitest test that imports a server-only component fails before it runs. See [Importing components](/docs/Structure/import-organization#importing-components).
97
+
98
+ **What to do:** if any file imports `server-only`, add `vi.mock("server-only", () => ({}));` to the Vitest setup file, and make sure `vitest.config.mjs` lists that file in `setupFiles`. Copy the Code standards section of `AGENTS.md` from the template again.
99
+
100
+ **How to check:** `pnpm lint` passes with no rule turned off for a template; `pnpm test` passes; `pnpm standards:check` passes, or lists only recorded exceptions.
101
+
76
102
  **Fixes in 3.3.3.** If the project already applied 3.3.2, check these:
77
103
 
78
104
  - **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/`".
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.3.3",
3
+ "version": "3.3.5",
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",
@@ -34,13 +34,13 @@
34
34
  "@mdx-js/react": "^3.0.0",
35
35
  "clsx": "^2.0.0",
36
36
  "eslint": "^10.13.0",
37
- "eslint-config-next": "^16.4.2",
37
+ "eslint-config-next": "^16.4.3",
38
38
  "eslint-config-prettier": "^10.1.8",
39
39
  "eslint-import-resolver-typescript": "^4.4.5",
40
40
  "eslint-plugin-import-x": "^4.17.1",
41
41
  "eslint-plugin-react": "^7.37.5",
42
42
  "eslint-plugin-react-hooks": "^7.1.1",
43
- "eslint-plugin-unicorn": "^78.0.0",
43
+ "eslint-plugin-unicorn": "^79.0.0",
44
44
  "globals": "^17.13.0",
45
45
  "next": "^16.4.2",
46
46
  "pagefind": "^1.3.0",
@@ -50,7 +50,7 @@
50
50
  "react": "^18.3.1",
51
51
  "react-dom": "^18.3.1",
52
52
  "typescript": "~5.6.2",
53
- "typescript-eslint": "^8.71.2"
53
+ "typescript-eslint": "^8.72.1"
54
54
  },
55
55
  "browserslist": {
56
56
  "production": [
@@ -77,6 +77,7 @@
77
77
  "format": "prettier --write .",
78
78
  "format:check": "prettier --check .",
79
79
  "check:eslint-templates": "node scripts/checkEslintTemplates.mjs",
80
+ "devtest": "node scripts/developmentTest.mjs",
80
81
  "test": "node --test \"scripts/verifyStandards/*.test.mjs\""
81
82
  }
82
83
  }
@@ -10,6 +10,10 @@ const ESLINT_TEMPLATE_NAMES = [
10
10
  "nextjs",
11
11
  ];
12
12
  const STYLELINT_TEMPLATE_NAMES = ["css", "scss"];
13
+ // Hand-written CSS. vendor/ is someone else's, and docsSite/ is the
14
+ // standard template, ignored like it is by ESLint.
15
+ const STYLESHEET_PATTERN = /\.(?:css|scss)$/;
16
+ const NOT_HAND_WRITTEN_PATTERN = /(?:^|\/)(?:vendor|docsSite)\//;
13
17
  const FORMAT_SCRIPTS = {
14
18
  format:
15
19
  "git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --write --ignore-unknown --no-error-on-unmatched-pattern",
@@ -163,14 +167,35 @@ const checkExactCopy = ({
163
167
  ];
164
168
  };
165
169
 
166
- const checkStylelint = ({ projectDirectory, templatesDirectory }) => {
170
+ const hasHandWrittenCss = (projectFiles) =>
171
+ projectFiles.some(
172
+ (filePath) =>
173
+ STYLESHEET_PATTERN.test(filePath) &&
174
+ !NOT_HAND_WRITTEN_PATTERN.test(filePath),
175
+ );
176
+
177
+ const checkStylelint = ({
178
+ projectDirectory,
179
+ templatesDirectory,
180
+ projectFiles,
181
+ }) => {
167
182
  const config = readTextFile({
168
183
  projectDirectory,
169
184
  filePath: "stylelint.config.mjs",
170
185
  });
171
- // Stylelint is only for projects with hand-written CSS.
186
+ // Stylelint is for projects with hand-written CSS, such as
187
+ // globals.css.
172
188
  if (config === undefined) {
173
- return [];
189
+ return hasHandWrittenCss(projectFiles)
190
+ ? [
191
+ {
192
+ standard: "8",
193
+ message:
194
+ "stylelint.config.mjs is missing. The project has hand-written CSS, such as globals.css, so it needs Stylelint",
195
+ page: "docs/Standards/stylelint.md",
196
+ },
197
+ ]
198
+ : [];
174
199
  }
175
200
  const isCopy = matchesAnyTemplate({
176
201
  projectText: config,
@@ -193,6 +218,7 @@ const checkStylelint = ({ projectDirectory, templatesDirectory }) => {
193
218
  export const checkConfigFiles = ({
194
219
  projectDirectory,
195
220
  templatesDirectory,
221
+ projectFiles,
196
222
  }) => {
197
223
  const nodeVersion = readTextFile({
198
224
  projectDirectory,
@@ -201,7 +227,11 @@ export const checkConfigFiles = ({
201
227
  return [
202
228
  ...checkEslint({ projectDirectory, templatesDirectory }),
203
229
  ...checkPrettier({ projectDirectory, templatesDirectory }),
204
- ...checkStylelint({ projectDirectory, templatesDirectory }),
230
+ ...checkStylelint({
231
+ projectDirectory,
232
+ templatesDirectory,
233
+ projectFiles,
234
+ }),
205
235
  ...checkExactCopy({
206
236
  projectDirectory,
207
237
  templatesDirectory,
@@ -44,7 +44,11 @@ export const runChecks = ({ projectDirectory }) => {
44
44
  templatesDirectory,
45
45
  packageVersion: readPackageVersion(),
46
46
  }),
47
- ...checkConfigFiles({ projectDirectory, templatesDirectory }),
47
+ ...checkConfigFiles({
48
+ projectDirectory,
49
+ templatesDirectory,
50
+ projectFiles,
51
+ }),
48
52
  ...checkRequiredFiles({ templatesDirectory, projectFiles }),
49
53
  ...checkConstants({ projectFiles }),
50
54
  ...checkStructure({ projectFiles }),
@@ -121,7 +121,7 @@ Follow these rules in every change:
121
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.
122
122
  - **Arrow functions everywhere.** Never use the `function` keyword: `export const Button = () => {}`, not `export function Button() {}`.
123
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`.
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`. Tests mock it: `vi.mock("server-only", () => ({}));` in the Vitest setup file.
125
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.
126
126
  - **Define before use.** A function or variable is written above the code that uses it.
127
127
  - **A function does one thing.**
@@ -1,6 +1,8 @@
1
1
  const DOCS_URL = process.env.DOCS_URL;
2
2
 
3
- /** @type {import("next").NextConfig} */
3
+ /**
4
+ @type {import("next").NextConfig}
5
+ */
4
6
  const nextConfig = {
5
7
  async rewrites() {
6
8
  // The docs are only served when DOCS_URL is set. It is never set in production.
@@ -1,4 +1,6 @@
1
- /** @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
1
+ /**
2
+ @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions}
3
+ */
2
4
  const config = {
3
5
  // Short lines, so code reads well on a phone.
4
6
  printWidth: 70,
@@ -1,4 +1,6 @@
1
- /** @type {import("stylelint").Config} */
1
+ /**
2
+ @type {import("stylelint").Config}
3
+ */
2
4
  const config = {
3
5
  ignoreFiles: ["**/vendor/**"],
4
6
  extends: [
@@ -1,4 +1,6 @@
1
- /** @type {import("stylelint").Config} */
1
+ /**
2
+ @type {import("stylelint").Config}
3
+ */
2
4
  const config = {
3
5
  ignoreFiles: ["**/vendor/**"],
4
6
  extends: [
@@ -56,9 +56,9 @@ const settlePage = async ({ page }: PageProps) => {
56
56
  for (const animation of finiteAnimations) {
57
57
  animation.finish();
58
58
  }
59
- const images = [...document.images];
60
- await Promise.all(
61
- images.map((image) => image.decode().catch(() => null)),
59
+ // An image that fails to load does not stop the check.
60
+ await Promise.allSettled(
61
+ [...document.images].map((image) => image.decode()),
62
62
  );
63
63
  });
64
64
  };
@@ -8,10 +8,6 @@ import { defineConfig } from "@playwright/test";
8
8
  // test:visual:update.
9
9
  const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
10
10
  const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
11
- // The project's own production build, on a port of its own.
12
- const LOCAL_PORT = 3100;
13
- const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
14
- const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
15
11
 
16
12
  if (isUpdatingBaseline && !PRODUCTION_URL) {
17
13
  throw new Error(
@@ -19,7 +15,14 @@ if (isUpdatingBaseline && !PRODUCTION_URL) {
19
15
  );
20
16
  }
21
17
 
22
- /** @type {import("@playwright/test").PlaywrightTestConfig} */
18
+ // The project's own production build, on a port of its own.
19
+ const LOCAL_PORT = 3100;
20
+ const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
21
+ const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
22
+
23
+ /**
24
+ @type {import("@playwright/test").PlaywrightTestConfig}
25
+ */
23
26
  const config = {
24
27
  testDir: ".",
25
28
  testMatch: "*.visual.ts",