@activatus/code-standards 3.0.4 → 3.0.5

package/README.md

@@ -1,5 +1,7 @@
 # 🦘 Activatus Code Standards
 
+## 👋 About Code Standards
+
 **One way of doing things, written down, so nobody has to guess.**
 
 This is the rulebook for how we write code at Activatus. It's a docs site, a pile of copy-paste config files, and a set of lint rules that'll dob you in before your reviewer has to.
@@ -30,7 +32,7 @@ pnpm add -D @activatus/code-standards
 
 Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
 
-The package version is the standards version: `2.0.0` is version 2.
+The package version is the standards version: `3.0.0` is version 3.
 
 > 🔢 **Updating a project to newer standards?** Run `pnpm update @activatus/code-standards --latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
 
@@ -72,7 +74,7 @@ The live site is at **[activatus-code-standards.vercel.app](https://activatus-co
 | 📖 **Ontology**                                                                                              | The code words we use and what each one means                                                                                                         |
 | 🔢 **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**                   | What changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md` |
 | 🧭 **Guides**                                                                                                | Setting up a new project, dragging an old one up to scratch, and how design becomes code                                                              |
-| 📏 **Standards**                                                                                             | Readable code, linting, formatting, styling, commits, the tech stack and AI agent rules                                                               |
+| 📏 **Standards**                                                                                             | Readable code, linting, formatting, styling, the tech stack and AI agent rules                                                                        |
 | 🏗️ **Structure**                                                                                             | Folders, components, naming, imports and API routes                                                                                                   |
 | 🧩 **[Design System Components](https://activatus-code-standards.vercel.app/docs/design-system-components)** | Every standard component and its props, so each project builds them the same way                                                                      |
 
@@ -131,7 +133,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
 
 ## 📋 Just want the files?
 
-Fair enough. Head to the **Templates** page on the site, or grab them straight from [`static/templates/`](static/templates):
+Fair enough. Head to the **Templates** page on the site, or grab them straight from [`static/templates/`](https://github.com/activatus-life/code-standards/tree/main/static/templates):
 
 ```text
 static/templates/
@@ -177,7 +179,7 @@ Reckon a rule's wrong, or there's one missing? Good. Standards that never change
 
 1. 🌿 **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
 2. 📝 **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
-3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart.
+3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart. For an ESLint config, run `pnpm check:eslint-templates`: it lints each config against itself and fails if the ESLint page shows an old copy. Add `--update-docs` to copy the configs onto the page.
 4. 🔢 **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump the major version in `package.json` to match (version 3 is `3.0.0`), and publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
 5. 🔨 **Run `pnpm build`.** It fails on broken links, so you'll know quick smart if you've stuffed one.
 6. 🚀 **Open a pull request** and say why the change makes life better.

package/docs/Guides/migrating.md

@@ -54,7 +54,7 @@ Add the `.editorconfig` file. No code changes needed — your editor will handle
 Add the [standard config](/docs/Standards/eslint) for your project type, then start in warn-only mode to see what you're dealing with. Add a block before `prettier`:
 
 ```js
-export default [
+const config = [
   // ...
   {
     rules: {
@@ -66,6 +66,8 @@ export default [
   },
   prettier,
 ];
+
+export default config;
 ```
 
 Run `pnpm lint` and triage the output. Fix them one kind at a time (for example, all `any` removals together). Once clean, remove the overrides.

package/docs/Guides/setup.md

@@ -64,7 +64,7 @@ Tell me the numbers to skip or change, or say "all good".
 10. Node version set by .nvmrc and direnv
 11. Styling: Tailwind, flexbox first, colours only from the global palette
 12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
-12.1. Constants: r for every link, s for every piece of text, noData for local stand-in data, all in lib/constants/
+12.1. Constants: r for every link, s for every piece of text, noData for local stand-in data, shared numbers by topic, all in lib/constants/
 13. Components live where they are used: components/ui/, components/shared/, or beside their page
 14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
 15. Design System Components: every project builds the standard components with the same props

package/docs/Standards/eslint.md

@@ -68,22 +68,70 @@ pnpm add -D eslint-config-next
 
 ## Usage
 
-Create `eslint.config.mjs` in your project root.
+Create `eslint.config.mjs` in your project root. Each config passes its own rules, so it lints clean the moment it is copied in. The code standards repo checks this with `pnpm check:eslint-templates` whenever a config changes.
 
 ### Base (JavaScript / Node.js)
 
 ```js title="eslint.config.mjs"
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
 import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+// Code patterns that are errors in every file.
+const RESTRICTED_SYNTAX = [
+	{
+		selector: "ClassDeclaration",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "ClassExpression",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "VariableDeclarator > FunctionExpression",
+		message: "Use an arrow function.",
+	},
+	{
+		selector: "VariableDeclaration[kind='let']",
+		message:
+			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
+	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
+	{
+		selector: "FunctionDeclaration[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+	{
+		selector:
+			"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+];
+
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	unicorn.configs.recommended,
 	{
@@ -92,7 +140,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -112,34 +160,8 @@ export default [
 			],
 			"no-restricted-syntax": [
 				"error",
-				{
-					selector: "ClassDeclaration",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "ClassExpression",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "VariableDeclarator > FunctionExpression",
-					message: "Use an arrow function.",
-				},
-				{
-					selector: "VariableDeclaration[kind='let']",
-					message:
-						"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
-				},
-				{
-					selector: "FunctionDeclaration[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
-				{
-					selector:
-						"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -177,13 +199,15 @@ export default [
 	},
 	prettier,
 ];
+
+export default config;
 ```
 
 ### TypeScript
 
 ```js title="eslint.config.mjs"
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -210,6 +234,10 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -223,6 +251,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -230,10 +261,19 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -247,7 +287,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -269,6 +309,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -351,11 +392,17 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;
 ```
 
 TypeScript files are checked by the compiler, so `no-undef` is off for them. The Node globals still earn their place: your `eslint.config.mjs`, build scripts and any remaining `.js` files are linted with `no-undef` on.
@@ -366,7 +413,7 @@ Start from the [TypeScript](#typescript) config and make five changes:
 
 ```js title="eslint.config.mjs"
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -395,6 +442,10 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -408,6 +459,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -415,10 +469,19 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -440,7 +503,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -462,6 +525,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -553,11 +617,17 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;
 ```
 
 :::caution[Pin the React version]
@@ -568,10 +638,10 @@ Set `settings.react.version` to the project's React version rather than `"detect
 
 ### Next.js
 
-`eslint-config-next` already brings the React, React Hooks and TypeScript rules, so it replaces the `js` and `typescript-eslint` presets rather than adding to them. Default exports are allowed in the files where Next.js requires them (`page.tsx`, `layout.tsx` and so on):
+`eslint-config-next` already brings the React, React Hooks and TypeScript rules, so it replaces the `js` and `typescript-eslint` presets rather than adding to them. Default exports are allowed in the files where Next.js requires them (`page.tsx`, `layout.tsx` and so on). Route handlers in `app/**/route.ts` may take two parameters, because Next.js calls them as `(request, context)`:
 
 ```js title="eslint.config.mjs"
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import nextVitals from "eslint-config-next/core-web-vitals";
@@ -599,6 +669,11 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+// Route handlers are the exception: see below.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -612,6 +687,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -619,7 +697,7 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
+const config = [
 	{
 		ignores: [
 			".next/",
@@ -627,12 +705,14 @@ export default [
 			"build/",
 			"coverage/",
 			"next-env.d.ts",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
 			"**/vendor/**",
 		],
 	},
 	...nextVitals,
 	...nextTypescript,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -650,7 +730,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -672,6 +752,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -767,11 +848,28 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
+		},
+	},
+	{
+		// Next.js calls a route handler with two values, (request, context), so route.ts files may take two parameters.
+		files: ["app/**/route.ts"],
+		rules: {
+			"no-restricted-syntax": [
+				"error",
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;
 ```
 
 Next.js genuinely runs in both environments — client components in the browser, route handlers, server components and `next.config.js` in Node — so both sets of globals apply.
@@ -787,7 +885,7 @@ Use the `globals` package rather than turning `no-undef` off or hand-writing a g
 Add a block before `prettier` to add or override rules:
 
 ```js
-export default [
+const config = [
   // ...
   {
     rules: {
@@ -797,6 +895,8 @@ export default [
   },
   prettier,
 ];
+
+export default config;
 ```
 
 Keep `prettier` last — it switches off every rule that would fight the formatter.
@@ -885,7 +985,7 @@ No file is longer than 300 lines, not counting blank lines and comments. Test fi
 
 ### `max-depth: 3`
 
-Blocks nest at most three levels deep. Return early instead. See [Readable Code](/docs/Standards/readable-code#return-early-nest-shallow).
+Blocks nest at most three levels deep. Return early instead. The configs name it `MAXIMUM_NESTING_DEPTH`, because they follow their own `no-magic-numbers` rule. See [Readable Code](/docs/Standards/readable-code#return-early-nest-shallow).
 
 ### `no-nested-ternary`
 
@@ -902,6 +1002,8 @@ These are banned by syntax, along with `function` expressions (above):
 - **Class declarations and class expressions.** See [Readable Code](/docs/Standards/readable-code#functions-never-classes).
 - **Functions you define with more than one parameter.** Use a single object parameter. Inline callbacks whose signature is set by someone else — `array.reduce((total, item) => …)`, event handlers — are not affected. See [Readable Code](/docs/Standards/readable-code#one-parameter-always-an-object-for-more).
 
+The configs keep the one-parameter selectors in their own `SINGLE_OBJECT_PARAMETER` list, so a file that must take more than one parameter can switch off just those. The Next.js config does this for route handlers in `app/**/route.ts`, which Next.js calls as `(request, context)`.
+
 ### `import-x/no-cycle`: no circular imports
 
 A file may never import a file that imports it back, directly or through a chain of other files. See [Import safety](/docs/Structure/import-organization#import-safety).

package/docs/Standards/readable-code.md

@@ -309,7 +309,9 @@ if (order.status === "shipped") {
 }
 ```
 
-`-1`, `0` and `1` are allowed. See [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name constants.
+**`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
+
+A number used in one file is named at the top of that file. One shared across the app goes in `lib/constants/`, in a file named after its topic. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
 
 ---
 

package/docs/Structure/folder-structure.md

@@ -272,7 +272,7 @@ Add the export to `utils/index.ts` whenever you add a function.
 
 ---
 
-## 🔤 Constants: `r`, `s` and noData {#constants}
+## 🔤 Constants: `r`, `s`, noData and numbers {#constants}
 
 Every link, every piece of text on screen and every piece of stand-in data lives in `lib/constants/`, never written straight into a component:
 
@@ -281,6 +281,7 @@ lib/constants/
 ├── routes.ts      # r: every link
 ├── strings.ts     # s: every piece of static text
 ├── noData.ts      # Stand-in data for local development
+├── durations.ts   # Shared numbers, one file per topic
 └── index.ts       # Exports all of them
 ```
 
@@ -356,13 +357,33 @@ const insights =
 - **Dummy values sit at the top of `noData.ts`** as their own constants, `DUMMY_HEADING` and the rest. They are never added to `s`.
 - **noData is for the whole site.** All of it lives in this one file.
 
+### Numbers: named, and kept by topic
+
+**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`.
+
+There is no `n` object. Text and links are one kind of thing each, but numbers are not: a retry limit, a cookie lifetime and a page size have nothing in common. Put each number where its meaning lives:
+
+| Used by            | Where it goes                                     | Example                                                                                |
+| ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| One file           | At the top of that file                           | `const MAXIMUM_NESTING_DEPTH = 3;` in `eslint.config.mjs`                              |
+| More than one file | `lib/constants/`, in a file named after its topic | `lib/constants/durations.ts`, `lib/constants/limits.ts`, `lib/constants/httpStatus.ts` |
+
+```ts title="lib/constants/durations.ts"
+export const COOKIE_DURATION_DAYS = 30;
+export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
+```
+
+- **Start in the file that uses it**, and move it to `lib/constants/` when a second file needs it.
+- **Never a `numbers.ts`** or any other file of unrelated values. Name the file after the topic.
+- **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
+
 ### Rules
 
 - **Named exports only:** `export const r`, `export const s`. No default exports.
 - **Files outside `lib/constants/` import from `@/lib/constants`**, all in one import line.
 - **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
 - **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
-- **Other constants** that hold a single value, such as `MAXIMUM_RETRY_ATTEMPTS`, follow [Naming Conventions](/docs/Structure/naming-conventions#constants).
+- **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
 
 ---
 

package/docs/version-history.md

@@ -44,9 +44,18 @@ Anyone changing the standards adds a version, alongside the change:
 
 ## Version 3
 
-**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.4
+**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.5
 
-Install it with `pnpm add -D @activatus/code-standards@3.0.4`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
+Install it with `pnpm add -D @activatus/code-standards@3.0.5`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
+
+**Fixes in 3.0.5.** The ESLint configs now pass their own rules. Copied in as they were, they gave three problems on the config file itself: `No magic number: 3` (`no-magic-numbers`), and in Next.js projects two warnings, `import/no-anonymous-default-export` and `import-x/no-named-as-default-member`. Copy the new [ESLint config](/docs/Standards/eslint) for the project's framework over `eslint.config.mjs`, keeping any project-specific block. Then run `pnpm lint`: the config file itself has no problems. If the project already fixed these three by hand, there is nothing to do.
+
+- `max-depth` uses a named constant, `MAXIMUM_NESTING_DEPTH`.
+- The array is assigned to `config` before `export default config`.
+- The eslint-comments preset is imported by name: `import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";`.
+- Numbers have a home: [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic). A number used in one file is named at the top of that file, and one shared across the app goes in `lib/constants/`, in a file named after its topic, such as `durations.ts`. There is no `n` object and no `numbers.ts`. If the project has a file of unrelated numbers, split it by topic. Copy the updated **No magic numbers** line from the [`AGENTS.md` template](/docs/templates#agents).
+- `docsSite/` is ignored. It is the standard docs viewer, with its own packages and build, and without the ignore ESLint lints its built files. If the project already ignores it, nothing changes.
+- The one-parameter selectors moved into their own `SINGLE_OBJECT_PARAMETER` list. **Next.js:** route handlers in `app/**/route.ts` may now take `(request, context)`. If the project switched the rule off for them some other way, such as an override block or `eslint-disable` comments, remove it.
 
 **Fixes in 3.0.4.** If the project already applied 3.0.3, do these:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activatus/code-standards",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "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.",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   "homepage": "https://activatus-code-standards.vercel.app",
   "files": [
     "docs",
-    "scripts",
+    "scripts/renameSymbol.mjs",
     "static/templates",
     "README.md"
   ],
@@ -18,22 +18,36 @@
   },
   "devDependencies": {
     "@docusaurus/core": "3.10.2",
+    "@docusaurus/mdx-loader": "3.10.2",
     "@docusaurus/module-type-aliases": "3.10.2",
     "@docusaurus/preset-classic": "3.10.2",
     "@docusaurus/theme-mermaid": "3.10.2",
     "@docusaurus/tsconfig": "3.10.2",
     "@docusaurus/types": "3.10.2",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",
+    "@eslint/js": "^10.0.1",
     "@getcanary/docusaurus-theme-search-pagefind": "1.0.2",
     "@getcanary/web": "^1.0.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
+    "eslint": "^10.13.0",
+    "eslint-config-next": "^16.4.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-unicorn": "^78.0.0",
+    "globals": "^17.13.0",
+    "next": "^16.4.2",
     "pagefind": "^1.3.0",
     "prettier": "^3.9.10",
     "prism-react-renderer": "^2.3.0",
     "raw-loader": "^4.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "typescript": "~5.6.2"
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.71.2"
   },
   "browserslist": {
     "production": [
@@ -58,6 +72,7 @@
     "clear": "docusaurus clear",
     "typecheck": "tsc",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "check:eslint-templates": "node scripts/checkEslintTemplates.mjs"
   }
 }

package/static/templates/AGENTS.md

@@ -113,7 +113,7 @@ Follow these rules in every change:
 - **Functions, never classes.**
 - **One parameter per function.** Use a single object when more than one value is needed.
 - **Return early.** Never nest more than three levels deep.
-- **No magic numbers or strings.** Use named constants.
+- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. A number used in one file is named at the top of that file; one shared across the app goes in `lib/constants/`, in a file named after its topic (`durations.ts`, `limits.ts`), never a `numbers.ts`. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
 - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
 - **No nested ternaries. No boolean flag parameters.**
 - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**

package/static/templates/eslint/base/eslint.config.mjs

@@ -1,14 +1,62 @@
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
 import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+// Code patterns that are errors in every file.
+const RESTRICTED_SYNTAX = [
+	{
+		selector: "ClassDeclaration",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "ClassExpression",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "VariableDeclarator > FunctionExpression",
+		message: "Use an arrow function.",
+	},
+	{
+		selector: "VariableDeclaration[kind='let']",
+		message:
+			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
+	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
+	{
+		selector: "FunctionDeclaration[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+	{
+		selector:
+			"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+];
+
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	unicorn.configs.recommended,
 	{
@@ -17,7 +65,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -37,34 +85,8 @@ export default [
 			],
 			"no-restricted-syntax": [
 				"error",
-				{
-					selector: "ClassDeclaration",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "ClassExpression",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "VariableDeclarator > FunctionExpression",
-					message: "Use an arrow function.",
-				},
-				{
-					selector: "VariableDeclaration[kind='let']",
-					message:
-						"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
-				},
-				{
-					selector: "FunctionDeclaration[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
-				{
-					selector:
-						"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -102,3 +124,5 @@ export default [
 	},
 	prettier,
 ];
+
+export default config;

package/static/templates/eslint/nextjs/eslint.config.mjs

@@ -1,4 +1,4 @@
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import nextVitals from "eslint-config-next/core-web-vitals";
@@ -26,6 +26,11 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+// Route handlers are the exception: see below.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -39,6 +44,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -46,7 +54,7 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
+const config = [
 	{
 		ignores: [
 			".next/",
@@ -54,12 +62,14 @@ export default [
 			"build/",
 			"coverage/",
 			"next-env.d.ts",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
 			"**/vendor/**",
 		],
 	},
 	...nextVitals,
 	...nextTypescript,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -77,7 +87,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -99,6 +109,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -194,8 +205,25 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
+		},
+	},
+	{
+		// Next.js calls a route handler with two values, (request, context), so route.ts files may take two parameters.
+		files: ["app/**/route.ts"],
+		rules: {
+			"no-restricted-syntax": [
+				"error",
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;

package/static/templates/eslint/react/eslint.config.mjs

@@ -1,5 +1,5 @@
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -28,6 +28,10 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -41,6 +45,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -48,10 +55,19 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -73,7 +89,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -95,6 +111,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -186,8 +203,14 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;

package/static/templates/eslint/typescript/eslint.config.mjs

@@ -1,5 +1,5 @@
 import js from "@eslint/js";
-import comments from "@eslint-community/eslint-plugin-eslint-comments/configs";
+import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
 import prettier from "eslint-config-prettier";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -26,6 +26,10 @@ const RESTRICTED_SYNTAX = [
 		message:
 			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
 	},
+];
+
+// Functions take one parameter: a single object when they need more than one value.
+const SINGLE_OBJECT_PARAMETER = [
 	{
 		selector: "FunctionDeclaration[params.length>1]",
 		message:
@@ -39,6 +43,9 @@ const RESTRICTED_SYNTAX = [
 	},
 ];
 
+// Deeper than this, return early instead.
+const MAXIMUM_NESTING_DEPTH = 3;
+
 // Type a value where it is declared. Story files are the exception: see below.
 const NO_SATISFIES = {
 	selector: "TSSatisfiesExpression",
@@ -46,10 +53,19 @@ const NO_SATISFIES = {
 		"Type a value where it is declared, not with satisfies afterwards.",
 };
 
-export default [
-	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+const config = [
+	{
+		ignores: [
+			"dist/",
+			"build/",
+			"coverage/",
+			// The docs viewer is the standard template, with its own packages and build.
+			"docsSite/",
+			"**/vendor/**",
+		],
+	},
 	js.configs.recommended,
-	comments.recommended,
+	eslintCommentsRecommended,
 	importX.recommended,
 	importX.typescript,
 	unicorn.configs.recommended,
@@ -63,7 +79,7 @@ export default [
 			"@eslint-community/eslint-comments/require-description":
 				"error",
 			"func-style": ["error", "expression"],
-			"max-depth": ["error", 3],
+			"max-depth": ["error", MAXIMUM_NESTING_DEPTH],
 			"max-lines": [
 				"error",
 				{ max: 300, skipBlankLines: true, skipComments: true },
@@ -85,6 +101,7 @@ export default [
 				"error",
 				NO_SATISFIES,
 				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -167,8 +184,14 @@ export default [
 		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
 		files: ["**/*.stories.{ts,tsx}"],
 		rules: {
-			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+			"no-restricted-syntax": [
+				"error",
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
+			],
 		},
 	},
 	prettier,
 ];
+
+export default config;