@activatus/code-standards 0.0.0-stage → 3.0.0

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

@@ -0,0 +1,181 @@
+import comments 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";
+import nextTypescript from "eslint-config-next/typescript";
+import { flatConfigs as importX } from "eslint-plugin-import-x";
+import unicorn from "eslint-plugin-unicorn";
+import globals from "globals";
+
+export default [
+	{
+		ignores: [
+			".next/",
+			"out/",
+			"build/",
+			"coverage/",
+			"next-env.d.ts",
+			"**/vendor/**",
+		],
+	},
+	...nextVitals,
+	...nextTypescript,
+	comments.recommended,
+	importX.recommended,
+	importX.typescript,
+	unicorn.configs.recommended,
+	{
+		languageOptions: {
+			globals: { ...globals.browser, ...globals.node },
+		},
+		settings: {
+			// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
+			// Update the number when the project upgrades React.
+			react: { version: "19.0" },
+			"import-x/resolver-next": [createTypeScriptImportResolver()],
+		},
+		rules: {
+			"@eslint-community/eslint-comments/require-description":
+				"error",
+			"func-style": ["error", "expression"],
+			"max-depth": ["error", 3],
+			"max-lines": [
+				"error",
+				{ max: 300, skipBlankLines: true, skipComments: true },
+			],
+			"no-nested-ternary": "error",
+			"no-var": "error",
+			"prefer-arrow-callback": "error",
+			"prefer-const": "error",
+			"no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+				},
+			],
+			"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.",
+				},
+			],
+			"import-x/no-cycle": "error",
+			"import-x/no-default-export": "error",
+			"no-use-before-define": "error",
+			"unicorn/default-export-style": "off",
+			"unicorn/filename-case": [
+				"error",
+				{ cases: { camelCase: true, pascalCase: true } },
+			],
+			"unicorn/name-replacements": [
+				"error",
+				{
+					// Dictionary words: see "Dictionary" in the Human-Readable Names standard.
+					replacements: {
+						docs: false,
+						lib: false,
+						props: false,
+						ref: false,
+						repo: false,
+						utils: false,
+					},
+					// Third-party names, allowed only exactly as they are.
+					allowList: { params: true, searchParams: true },
+				},
+			],
+			"react/function-component-definition": [
+				"error",
+				{
+					namedComponents: "arrow-function",
+					unnamedComponents: "arrow-function",
+				},
+			],
+			"react/jsx-no-bind": "error",
+			"react/no-multi-comp": "error",
+		},
+	},
+	{
+		files: ["**/*.{ts,tsx}"],
+		rules: {
+			"no-undef": "off",
+			"no-magic-numbers": "off",
+			"no-use-before-define": "off",
+			"@typescript-eslint/consistent-type-assertions": [
+				"error",
+				{ assertionStyle: "never" },
+			],
+			"@typescript-eslint/consistent-type-imports": "error",
+			"@typescript-eslint/naming-convention": [
+				"error",
+				{
+					selector: ["typeAlias", "interface"],
+					format: ["PascalCase"],
+					custom: { regex: "(Props|Type)$", match: true },
+				},
+			],
+			"@typescript-eslint/no-explicit-any": "error",
+			"@typescript-eslint/no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+					ignoreEnums: true,
+					ignoreNumericLiteralTypes: true,
+				},
+			],
+			"@typescript-eslint/no-non-null-assertion": "error",
+			"@typescript-eslint/no-use-before-define": "error",
+		},
+	},
+	{
+		files: ["**/*.test.{ts,tsx}"],
+		rules: {
+			"max-lines": "off",
+			"no-magic-numbers": "off",
+			"@typescript-eslint/no-magic-numbers": "off",
+		},
+	},
+	{
+		files: [
+			"**/*.config.{js,mjs,ts}",
+			"**/*.stories.tsx",
+			"app/**/{page,layout,template,default,loading,error,global-error,not-found}.tsx",
+		],
+		rules: { "import-x/no-default-export": "off" },
+	},
+	{
+		files: ["**/*.config.{js,mjs,ts}"],
+		rules: { "unicorn/no-top-level-side-effects": "off" },
+	},
+	prettier,
+];

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

@@ -0,0 +1,173 @@
+import js from "@eslint/js";
+import comments 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";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import unicorn from "eslint-plugin-unicorn";
+import globals from "globals";
+import { configs as typescript } from "typescript-eslint";
+
+export default [
+	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+	js.configs.recommended,
+	comments.recommended,
+	importX.recommended,
+	importX.typescript,
+	unicorn.configs.recommended,
+	...typescript.recommended,
+	react.configs.flat.recommended,
+	react.configs.flat["jsx-runtime"],
+	reactHooks.configs.flat.recommended,
+	{
+		languageOptions: {
+			globals: { ...globals.browser, ...globals.node },
+		},
+		settings: {
+			// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
+			// Update the number when the project upgrades React.
+			react: { version: "19.0" },
+			"import-x/resolver-next": [createTypeScriptImportResolver()],
+		},
+		rules: {
+			"@eslint-community/eslint-comments/require-description":
+				"error",
+			"func-style": ["error", "expression"],
+			"max-depth": ["error", 3],
+			"max-lines": [
+				"error",
+				{ max: 300, skipBlankLines: true, skipComments: true },
+			],
+			"no-nested-ternary": "error",
+			"no-var": "error",
+			"prefer-arrow-callback": "error",
+			"prefer-const": "error",
+			"no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+				},
+			],
+			"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.",
+				},
+			],
+			"import-x/no-cycle": "error",
+			"import-x/no-default-export": "error",
+			"no-use-before-define": "error",
+			"unicorn/default-export-style": "off",
+			"unicorn/filename-case": [
+				"error",
+				{ cases: { camelCase: true, pascalCase: true } },
+			],
+			"unicorn/name-replacements": [
+				"error",
+				{
+					// Dictionary words: see "Dictionary" in the Human-Readable Names standard.
+					replacements: {
+						docs: false,
+						lib: false,
+						props: false,
+						ref: false,
+						repo: false,
+						utils: false,
+					},
+					// Third-party names, allowed only exactly as they are.
+					allowList: { params: true, searchParams: true },
+				},
+			],
+			"react/function-component-definition": [
+				"error",
+				{
+					namedComponents: "arrow-function",
+					unnamedComponents: "arrow-function",
+				},
+			],
+			"react/jsx-no-bind": "error",
+			"react/no-multi-comp": "error",
+		},
+	},
+	{
+		files: ["**/*.{ts,tsx}"],
+		rules: {
+			"no-undef": "off",
+			"no-magic-numbers": "off",
+			"no-use-before-define": "off",
+			"@typescript-eslint/consistent-type-assertions": [
+				"error",
+				{ assertionStyle: "never" },
+			],
+			"@typescript-eslint/consistent-type-imports": "error",
+			"@typescript-eslint/naming-convention": [
+				"error",
+				{
+					selector: ["typeAlias", "interface"],
+					format: ["PascalCase"],
+					custom: { regex: "(Props|Type)$", match: true },
+				},
+			],
+			"@typescript-eslint/no-explicit-any": "error",
+			"@typescript-eslint/no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+					ignoreEnums: true,
+					ignoreNumericLiteralTypes: true,
+				},
+			],
+			"@typescript-eslint/no-non-null-assertion": "error",
+			"@typescript-eslint/no-use-before-define": "error",
+		},
+	},
+	{
+		files: ["**/*.test.{ts,tsx}"],
+		rules: {
+			"max-lines": "off",
+			"no-magic-numbers": "off",
+			"@typescript-eslint/no-magic-numbers": "off",
+		},
+	},
+	{
+		files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
+		rules: { "import-x/no-default-export": "off" },
+	},
+	{
+		files: ["**/*.config.{js,mjs,ts}"],
+		rules: { "unicorn/no-top-level-side-effects": "off" },
+	},
+	prettier,
+];

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

@@ -0,0 +1,154 @@
+import js from "@eslint/js";
+import comments 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";
+import unicorn from "eslint-plugin-unicorn";
+import globals from "globals";
+import { configs as typescript } from "typescript-eslint";
+
+export default [
+	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
+	js.configs.recommended,
+	comments.recommended,
+	importX.recommended,
+	importX.typescript,
+	unicorn.configs.recommended,
+	...typescript.recommended,
+	{
+		languageOptions: { globals: { ...globals.node } },
+		settings: {
+			"import-x/resolver-next": [createTypeScriptImportResolver()],
+		},
+		rules: {
+			"@eslint-community/eslint-comments/require-description":
+				"error",
+			"func-style": ["error", "expression"],
+			"max-depth": ["error", 3],
+			"max-lines": [
+				"error",
+				{ max: 300, skipBlankLines: true, skipComments: true },
+			],
+			"no-nested-ternary": "error",
+			"no-var": "error",
+			"prefer-arrow-callback": "error",
+			"prefer-const": "error",
+			"no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+				},
+			],
+			"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.",
+				},
+			],
+			"import-x/no-cycle": "error",
+			"import-x/no-default-export": "error",
+			"no-use-before-define": "error",
+			"unicorn/default-export-style": "off",
+			"unicorn/filename-case": [
+				"error",
+				{ cases: { camelCase: true, pascalCase: true } },
+			],
+			"unicorn/name-replacements": [
+				"error",
+				{
+					// Dictionary words: see "Dictionary" in the Human-Readable Names standard.
+					replacements: {
+						docs: false,
+						lib: false,
+						props: false,
+						ref: false,
+						repo: false,
+						utils: false,
+					},
+					// Third-party names, allowed only exactly as they are.
+					allowList: { params: true, searchParams: true },
+				},
+			],
+		},
+	},
+	{
+		files: ["**/*.{ts,tsx}"],
+		rules: {
+			"no-undef": "off",
+			"no-magic-numbers": "off",
+			"no-use-before-define": "off",
+			"@typescript-eslint/consistent-type-assertions": [
+				"error",
+				{ assertionStyle: "never" },
+			],
+			"@typescript-eslint/consistent-type-imports": "error",
+			"@typescript-eslint/naming-convention": [
+				"error",
+				{
+					selector: ["typeAlias", "interface"],
+					format: ["PascalCase"],
+					custom: { regex: "(Props|Type)$", match: true },
+				},
+			],
+			"@typescript-eslint/no-explicit-any": "error",
+			"@typescript-eslint/no-magic-numbers": [
+				"error",
+				{
+					ignore: [-1, 0, 1],
+					ignoreArrayIndexes: true,
+					ignoreDefaultValues: true,
+					enforceConst: true,
+					ignoreEnums: true,
+					ignoreNumericLiteralTypes: true,
+				},
+			],
+			"@typescript-eslint/no-non-null-assertion": "error",
+			"@typescript-eslint/no-use-before-define": "error",
+		},
+	},
+	{
+		files: ["**/*.test.{ts,tsx}"],
+		rules: {
+			"max-lines": "off",
+			"no-magic-numbers": "off",
+			"@typescript-eslint/no-magic-numbers": "off",
+		},
+	},
+	{
+		files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
+		rules: { "import-x/no-default-export": "off" },
+	},
+	{
+		files: ["**/*.config.{js,mjs,ts}"],
+		rules: { "unicorn/no-top-level-side-effects": "off" },
+	},
+	prettier,
+];

package/static/templates/globals.css

@@ -0,0 +1,16 @@
+@import "tailwindcss";
+
+@theme {
+	--color-brand-primary: #3b82f6;
+	--color-brand-primary-hover: #2563eb;
+	--color-brand-secondary: #64748b;
+	--color-surface: #fff;
+	--color-text: #0f172a;
+}
+
+[data-theme="dark"] {
+	--color-brand-primary: #60a5fa;
+	--color-brand-primary-hover: #93c5fd;
+	--color-surface: #0f172a;
+	--color-text: #f8fafc;
+}

package/static/templates/husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint

package/static/templates/next.config.mjs

@@ -0,0 +1,21 @@
+const DOCS_URL = process.env.DOCS_URL;
+
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+	async rewrites() {
+		// The docs are only served when DOCS_URL is set. It is never set in production.
+		if (!DOCS_URL) {
+			return [];
+		}
+
+		return [
+			{ source: "/docs", destination: `${DOCS_URL}/docs/` },
+			{
+				source: "/docs/:path*",
+				destination: `${DOCS_URL}/docs/:path*`,
+			},
+		];
+	},
+};
+
+export default nextConfig;

package/static/templates/prettier.config.mjs

@@ -0,0 +1,26 @@
+/** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
+const config = {
+	// Short lines, so code reads well on a phone.
+	printWidth: 70,
+	// Tabs indent. A tab counts as 2 characters towards the line width.
+	useTabs: true,
+	tabWidth: 2,
+	singleQuote: false,
+	trailingComma: "all",
+	bracketSpacing: true,
+	bracketSameLine: false,
+	arrowParens: "always",
+	semi: true,
+	endOfLine: "lf",
+	plugins: ["prettier-plugin-tailwindcss"],
+	tailwindStylesheet: "./app/globals.css",
+	overrides: [
+		{
+			// YAML does not allow tabs, and Markdown reads a tab as four spaces.
+			files: ["*.md", "*.mdx", "*.yml", "*.yaml"],
+			options: { useTabs: false },
+		},
+	],
+};
+
+export default config;

package/static/templates/skills/codeReview.md

@@ -0,0 +1,31 @@
+---
+name: codeReview
+description: Review changes for bugs and standards compliance
+argument-hint: "[branch, commit or path]"
+allowed-tools: Read, Glob, Grep, Bash(git diff:*), Bash(git log:*), Bash(git status:*), Bash(git merge-base:*)
+---
+
+Review the changes and report problems. Do NOT modify any files.
+
+1. Work out what to review:
+   - If `$ARGUMENTS` is a file or folder path, review those files.
+   - If `$ARGUMENTS` is a branch or commit, review `git diff $ARGUMENTS...HEAD`.
+   - If `$ARGUMENTS` is empty, review `git diff main...HEAD` plus the uncommitted changes from `git diff`.
+2. Read `AGENTS.md` for the project's code standards.
+3. Read every changed file in full, not only the changed lines.
+4. Check each change for:
+   - **Correctness** — logic errors, unhandled cases, broken error handling
+   - **Security** — unvalidated input, secrets in code, missing permission checks
+   - **Types** — `any`, non-null `!`, and `as` casts without a comment saying why
+   - **Tests** — every new or changed function and component has a test file
+   - **Readable code** — files over 300 lines, any name that is not human-readable (folders, files, props, form field `name`s and labels, types, union values, database columns, routes, environment variables and test names as well as variables), functions doing more than one thing, more than one parameter, nesting deeper than three levels, magic numbers
+   - **Structure** — reusable functions outside a `utils/` folder, server and client code in one file, inline functions in render
+   - **Styling** — hard-coded colours, CSS grid that was not asked for
+5. Report the findings in order of severity: **Must fix**, **Should fix**, **Consider**. For each one give the file and line, what is wrong, and how to fix it.
+6. Finish with a one-line verdict: ready to commit, or not.
+
+If there are no changes to review, say so and stop.
+
+Do NOT review files in `node_modules/` or `vendor/`. Third-party code is exempt from the standards.
+Do NOT fix anything. Report only.
+Do NOT stage, commit or push.

package/static/templates/skills/format.md

@@ -0,0 +1,18 @@
+---
+name: format
+description: Format files with Prettier and report what changed
+argument-hint: "[path]"
+allowed-tools: Read, Glob, Bash(pnpm format:*), Bash(git status:*)
+---
+
+Format the project with Prettier and report which files changed.
+
+1. Read `package.json` and confirm a `format` script exists.
+2. Run `pnpm format $ARGUMENTS`.
+3. Run `git status --short` to see which files changed.
+4. Report the reformatted files. If nothing changed, say the project was already formatted.
+
+If `package.json` has no `format` script, stop and say so.
+
+Do NOT change files in `node_modules/` or `vendor/`.
+Do NOT stage, commit or push. Leave every change uncommitted.

package/static/templates/skills/lint.md

@@ -0,0 +1,21 @@
+---
+name: lint
+description: Run all linters in check-only mode and report issues
+argument-hint: "[path]"
+allowed-tools: Read, Glob, Grep, Bash(pnpm lint:*)
+---
+
+Run every configured linter and report the issues. Do NOT modify any files.
+
+1. Read `package.json` and find the lint scripts (`lint`, and `lint:css` if it exists).
+2. Run each one in check-only mode:
+   - ESLint: `pnpm lint $ARGUMENTS`
+   - Stylelint, only if the `lint:css` script exists: `pnpm lint:css`
+3. Report the findings grouped by file. For each issue give the line, the rule name and the message, then explain in one plain-English sentence what is wrong and how to fix it. Write for someone who does not read code.
+4. Finish with a one-line total: the number of errors and warnings, and how many are auto-fixable.
+
+If `package.json` has no `lint` script, stop and say so. Do NOT fall back to running `eslint` directly.
+
+Do NOT fix anything, even issues that are auto-fixable — `/lintFix` does that.
+Do NOT lint or report on files in `node_modules/` or `vendor/`. Third-party code is exempt from the standards.
+Do NOT stage, commit or push.

package/static/templates/skills/lintFix.md

@@ -0,0 +1,24 @@
+---
+name: lintFix
+description: Auto-fix lint and formatting issues, then report
+argument-hint: "[path]"
+allowed-tools: Read, Glob, Grep, Bash(pnpm lint:*), Bash(pnpm format:*), Bash(git status:*), Bash(git diff:*)
+---
+
+Run every linter in fix mode, then the formatter, and report what changed.
+
+1. Read `package.json` and find the scripts that exist: `lint:fix`, `lint:css:fix` and `format`.
+2. Run them in this order, skipping any that do not exist:
+   - ESLint: `pnpm lint:fix $ARGUMENTS`
+   - Stylelint: `pnpm lint:css:fix`
+   - Prettier: `pnpm format`
+3. Run `git status --short` and `git diff --stat` to see which files changed.
+4. Report:
+   - The files that were changed
+   - The issues that remain and could not be fixed automatically, grouped by file
+
+If none of the three scripts exist, stop and say so.
+
+Do NOT fix the remaining issues by hand. Report them and leave them for the person.
+Do NOT change files in `node_modules/` or `vendor/`. Third-party code is exempt from the standards.
+Do NOT stage, commit or push. Leave every change uncommitted.