@activatus/code-standards 3.0.2 → 3.0.5

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";
@@ -191,10 +215,65 @@ import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 import { configs as typescript } from "typescript-eslint";
 
-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;
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
+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,
@@ -208,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 },
@@ -228,34 +307,9 @@ 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.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -334,8 +388,21 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// 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,
+				...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.
@@ -346,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";
@@ -356,10 +423,65 @@ import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 import { configs as typescript } from "typescript-eslint";
 
-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;
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
+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,
@@ -381,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 },
@@ -401,34 +523,9 @@ 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.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -516,8 +613,21 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// 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,
+				...SINGLE_OBJECT_PARAMETER,
+			],
+		},
+	},
 	prettier,
 ];
+
+export default config;
 ```
 
 :::caution[Pin the React version]
@@ -528,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";
@@ -540,7 +650,54 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
 import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 
-export default [
+// 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.
+// Route handlers are the exception: see below.
+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;
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
+const config = [
 	{
 		ignores: [
 			".next/",
@@ -548,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,
@@ -571,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 },
@@ -591,34 +750,9 @@ 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.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
+				...SINGLE_OBJECT_PARAMETER,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -710,8 +844,32 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// 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,
+				...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.
@@ -727,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: {
@@ -737,6 +895,8 @@ export default [
   },
   prettier,
 ];
+
+export default config;
 ```
 
 Keep `prettier` last — it switches off every rule that would fight the formatter.
@@ -786,7 +946,7 @@ Third-party code that is copied into the repository lives in a `vendor/` folder,
 
 `vendor/` is only for third-party code we **do not change** — code that is replaced wholesale when the package updates.
 
-Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/Guides/component-library-workflow#adding-a-shadcn-component).
+Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
 
 | Code                                                      | Ours?   | Follows the standards?                     |
 | --------------------------------------------------------- | ------- | ------------------------------------------ |
@@ -799,11 +959,11 @@ If a vendored package lives somewhere else and cannot be moved, add its path to
 
 ## Key rule decisions
 
-Most of these enforce the [Readable Code](/Standards/readable-code) rules. For what each error means and how to fix it, see [Fixing Lint Errors](/Standards/lint-errors).
+Most of these enforce the [Readable Code](/docs/Standards/readable-code) rules. For what each error means and how to fix it, see [Fixing Lint Errors](/docs/Standards/lint-errors).
 
 ### `func-style`, `prefer-arrow-callback`: arrow functions everywhere
 
-Every function is an arrow function. See [Readable Code](/Standards/readable-code#arrow-functions-everywhere).
+Every function is an arrow function. See [Readable Code](/docs/Standards/readable-code#arrow-functions-everywhere).
 
 - `func-style: expression` rejects `function name() {}` declarations.
 - `prefer-arrow-callback` rejects `function` callbacks.
@@ -813,58 +973,60 @@ Every function is an arrow function. See [Readable Code](/Standards/readable-cod
 
 ### `no-restricted-syntax`, `prefer-const`, `no-var`: always `const`
 
-Variables are declared with `const`. `let` is an error unless the line carries a disable comment with a reason; `var` is never allowed. See [Readable Code](/Standards/readable-code#always-const).
+Variables are declared with `const`. `let` is an error unless the line carries a disable comment with a reason; `var` is never allowed. See [Readable Code](/docs/Standards/readable-code#always-const).
 
 ### `@eslint-community/eslint-comments/require-description`
 
-Every `eslint-disable` comment must say why, after `--`. A rule is never switched off silently. See [the only allowed exceptions](/Standards/lint-errors#the-only-allowed-exceptions).
+Every `eslint-disable` comment must say why, after `--`. A rule is never switched off silently. See [the only allowed exceptions](/docs/Standards/lint-errors#the-only-allowed-exceptions).
 
 ### `max-lines: 300`
 
-No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/Standards/readable-code#no-file-longer-than-300-lines).
+No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
 
 ### `max-depth: 3`
 
-Blocks nest at most three levels deep. Return early instead. See [Readable Code](/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`
 
-A ternary inside a ternary is an error. See [Readable Code](/Standards/readable-code#no-nested-ternaries).
+A ternary inside a ternary is an error. See [Readable Code](/docs/Standards/readable-code#no-nested-ternaries).
 
 ### `no-magic-numbers`
 
-Numbers other than `-1`, `0` and `1` must be named constants. Test files are exempt. TypeScript files use `@typescript-eslint/no-magic-numbers`, which understands enums and numeric literal types. See [Readable Code](/Standards/readable-code#no-magic-numbers-or-strings).
+Numbers other than `-1`, `0` and `1` must be named constants. Test files are exempt. TypeScript files use `@typescript-eslint/no-magic-numbers`, which understands enums and numeric literal types. See [Readable Code](/docs/Standards/readable-code#no-magic-numbers-or-strings).
 
 ### `no-restricted-syntax`: no classes, one parameter
 
 These are banned by syntax, along with `function` expressions (above):
 
-- **Class declarations and class expressions.** See [Readable Code](/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](/Standards/readable-code#one-parameter-always-an-object-for-more).
+- **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](/Structure/import-organization#import-safety).
+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).
 
 ### `no-use-before-define`
 
-A function or variable is defined above the code that uses it. TypeScript files use `@typescript-eslint/no-use-before-define`. See [Import safety](/Structure/import-organization#import-safety).
+A function or variable is defined above the code that uses it. TypeScript files use `@typescript-eslint/no-use-before-define`. See [Import safety](/docs/Structure/import-organization#import-safety).
 
 ### `import-x/no-default-export`
 
-Named exports only. Default exports are allowed where a tool requires them: config files, Storybook stories and Next.js route files. See [Readable Code](/Standards/readable-code#named-exports-only).
+Named exports only. Default exports are allowed where a tool requires them: config files, Storybook stories and Next.js route files. See [Readable Code](/docs/Standards/readable-code#named-exports-only).
 
 ### Import order is not linted
 
-There is deliberately no import-**order** rule (circular imports are a different matter — see above). Follow the [Import Organization](/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
+There is deliberately no import-**order** rule (circular imports are a different matter — see above). Follow the [Import Organization](/docs/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
 
 ### `unicorn/filename-case: camelCase or PascalCase`
 
-The plugin's default is kebab-case, which contradicts our [naming conventions](/Structure/naming-conventions). Files are camelCase (`formatDate.ts`), and component files are PascalCase (`UserProfile.tsx`).
+The plugin's default is kebab-case, which contradicts our [naming conventions](/docs/Structure/naming-conventions). Files are camelCase (`formatDate.ts`), and component files are PascalCase (`UserProfile.tsx`).
 
 ### `unicorn/name-replacements: error`
 
-Names are full English words: `btn` must be `button`, `e` must be `error` or `event`, `acc` must be `accumulator`. `docs`, `lib`, `props`, `ref`, `repo` and `utils` are allowed because they are on the [dictionary](/Standards/human-readable-names#dictionary) list. Only three names owned by React and Next.js are allowed exactly as they are — `ref`, `params` and `searchParams` — and our own names built from them are still flagged (`inputRef` must be `inputReference`). See [Human-Readable Names](/Standards/human-readable-names). (Before `eslint-plugin-unicorn` 77 this rule was called `unicorn/prevent-abbreviations`.)
+Names are full English words: `btn` must be `button`, `e` must be `error` or `event`, `acc` must be `accumulator`. `docs`, `lib`, `props`, `ref`, `repo` and `utils` are allowed because they are on the [dictionary](/docs/Standards/human-readable-names#dictionary) list. Only three names owned by React and Next.js are allowed exactly as they are — `ref`, `params` and `searchParams` — and our own names built from them are still flagged (`inputRef` must be `inputReference`). See [Human-Readable Names](/docs/Standards/human-readable-names). (Before `eslint-plugin-unicorn` 77 this rule was called `unicorn/prevent-abbreviations`.)
 
 ### `@typescript-eslint/no-explicit-any: error`
 
@@ -874,9 +1036,13 @@ Names are full English words: `btn` must be `button`, `e` must be `error` or `ev
 
 The `!` operator tells the compiler a value exists without checking. Check it instead.
 
+### `no-restricted-syntax`: type first, never `satisfies`
+
+A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. The rule lists live in `RESTRICTED_SYNTAX` and `NO_SATISFIES` at the top of each config, so story files use every other restriction without repeating it. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
+
 ### `@typescript-eslint/consistent-type-assertions: never`
 
-`as` casts are errors (`as const` is still allowed). When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/Standards/readable-code#no-any-no--no-unexplained-as) requires:
+`as` casts are errors (`as const` is still allowed). When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/docs/Standards/readable-code#no-any-no--no-unexplained-as) requires:
 
 ```ts
 // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- the API returns untyped JSON; validated by parseUser below
@@ -885,7 +1051,7 @@ const user = response.data as UserType;
 
 ### `@typescript-eslint/naming-convention`: `Props` or `Type` suffix
 
-Every interface and type alias ends in `Props` or `Type`. See [Naming Conventions](/Structure/naming-conventions#types--interfaces).
+Every interface and type alias ends in `Props` or `Type`. See [Naming Conventions](/docs/Structure/naming-conventions#types--interfaces).
 
 ### `@typescript-eslint/consistent-type-imports: error`
 
@@ -893,8 +1059,8 @@ Type-only imports use `import type { Foo }` or inline `import { type Foo }`. Thi
 
 ### `react/jsx-no-bind: error`
 
-No inline functions in render. A function passed as a JSX prop must be wrapped in `useCallback`, so it is not recreated on every render. See [Writing a component](/Structure/component-organization#-writing-a-component).
+No inline functions in render. A function passed as a JSX prop must be wrapped in `useCallback`, so it is not recreated on every render. See [Writing a component](/docs/Structure/component-organization#-writing-a-component).
 
 ### `react/no-multi-comp: error`
 
-One component per file. See [Readable Code](/Standards/readable-code#one-component-per-file).
+One component per file. See [Readable Code](/docs/Standards/readable-code#one-component-per-file).