@activatus/code-standards 3.3.3 → 3.3.4
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/docs/Guides/setup.md +1 -1
- package/docs/Standards/documentation.md +3 -1
- package/docs/Standards/prettier.md +3 -1
- package/docs/Standards/stylelint.md +6 -2
- package/docs/Structure/import-organization.md +10 -0
- package/docs/version-history.md +14 -1
- package/package.json +5 -4
- package/static/templates/AGENTS.md +1 -1
- package/static/templates/next.config.mjs +3 -1
- package/static/templates/prettier.config.mjs +3 -1
- package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
- package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
- package/static/templates/tests/visual/pageLayout.visual.ts +3 -3
- package/static/templates/tests/visual/playwright.config.mjs +8 -5
package/docs/Guides/setup.md
CHANGED
|
@@ -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,
|
|
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
|
|
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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,
|
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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.
|
package/docs/version-history.md
CHANGED
|
@@ -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,22 @@ 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.
|
|
73
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.4
|
|
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.4.** If the project already applied 3.3.3, check these:
|
|
78
|
+
|
|
79
|
+
- **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.
|
|
80
|
+
|
|
81
|
+
**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`.
|
|
82
|
+
|
|
83
|
+
- **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).
|
|
84
|
+
|
|
85
|
+
**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.
|
|
86
|
+
|
|
87
|
+
**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.
|
|
88
|
+
|
|
76
89
|
**Fixes in 3.3.3.** If the project already applied 3.3.2, check these:
|
|
77
90
|
|
|
78
91
|
- **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
|
+
"version": "3.3.4",
|
|
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.
|
|
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": "^
|
|
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.
|
|
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
|
}
|
|
@@ -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,4 +1,6 @@
|
|
|
1
|
-
/**
|
|
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,
|
|
@@ -56,9 +56,9 @@ const settlePage = async ({ page }: PageProps) => {
|
|
|
56
56
|
for (const animation of finiteAnimations) {
|
|
57
57
|
animation.finish();
|
|
58
58
|
}
|
|
59
|
-
|
|
60
|
-
await Promise.
|
|
61
|
-
images.map((image) => image.decode()
|
|
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
|
-
|
|
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",
|