@activatus/code-standards 2.0.0 → 3.0.0

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

@@ -8,119 +8,147 @@ 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, props: false, utils: false },
-          // Third-party names, allowed only exactly as they are.
-          allowList: { ref: true, 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,
+	{ 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

@@ -1,16 +1,16 @@
 @import "tailwindcss";
 
 @theme {
-  --color-brand-primary: #3b82f6;
-  --color-brand-primary-hover: #2563eb;
-  --color-brand-secondary: #64748b;
-  --color-surface: #fff;
-  --color-text: #0f172a;
+	--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;
+	--color-brand-primary: #60a5fa;
+	--color-brand-primary-hover: #93c5fd;
+	--color-surface: #0f172a;
+	--color-text: #f8fafc;
 }

package/static/templates/next.config.mjs

@@ -2,17 +2,20 @@ 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 [];
-    }
+	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*` },
-    ];
-  },
+		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/stylelint/css/stylelint.config.mjs

@@ -1,28 +1,40 @@
 /** @type {import("stylelint").Config} */
 export default {
-  ignoreFiles: ["**/vendor/**"],
-  extends: ["stylelint-config-standard", "stylelint-config-recess-order"],
-  rules: {
-    "selector-max-id": 0,
-    "property-no-vendor-prefix": true,
-    "color-function-notation": "modern",
-    "import-notation": "string",
-    "at-rule-no-unknown": [
-      true,
-      { ignoreAtRules: ["theme", "utility", "variant", "custom-variant", "source", "plugin"] },
-    ],
-  },
-  overrides: [
-    {
-      files: ["**/*.module.css"],
-      rules: {
-        "color-named": "never",
-        "color-no-hex": true,
-        "selector-class-pattern": [
-          "^[a-z][a-zA-Z0-9]*$",
-          { message: "Expected class selector to be camelCase" },
-        ],
-      },
-    },
-  ],
+	ignoreFiles: ["**/vendor/**"],
+	extends: [
+		"stylelint-config-standard",
+		"stylelint-config-recess-order",
+	],
+	rules: {
+		"selector-max-id": 0,
+		"property-no-vendor-prefix": true,
+		"color-function-notation": "modern",
+		"import-notation": "string",
+		"at-rule-no-unknown": [
+			true,
+			{
+				ignoreAtRules: [
+					"theme",
+					"utility",
+					"variant",
+					"custom-variant",
+					"source",
+					"plugin",
+				],
+			},
+		],
+	},
+	overrides: [
+		{
+			files: ["**/*.module.css"],
+			rules: {
+				"color-named": "never",
+				"color-no-hex": true,
+				"selector-class-pattern": [
+					"^[a-z][a-zA-Z0-9]*$",
+					{ message: "Expected class selector to be camelCase" },
+				],
+			},
+		},
+	],
 };

package/static/templates/stylelint/scss/stylelint.config.mjs

@@ -1,10 +1,13 @@
 /** @type {import("stylelint").Config} */
 export default {
-  ignoreFiles: ["**/vendor/**"],
-  extends: ["stylelint-config-standard-scss", "stylelint-config-recess-order"],
-  rules: {
-    "selector-max-id": 0,
-    "property-no-vendor-prefix": true,
-    "color-function-notation": "modern",
-  },
+	ignoreFiles: ["**/vendor/**"],
+	extends: [
+		"stylelint-config-standard-scss",
+		"stylelint-config-recess-order",
+	],
+	rules: {
+		"selector-max-id": 0,
+		"property-no-vendor-prefix": true,
+		"color-function-notation": "modern",
+	},
 };

package/docs/Standards/branch-naming.md

@@ -1,66 +0,0 @@
----
-sidebar_position: 6.5
----
-
-# Branch Naming
-
-Every branch name says what kind of work it holds and what the work is.
-
-## Format
-
-```text
-<type>/<short-description>
-```
-
-```text
-feat/invoice-export
-fix/login-redirect-loop
-docs/update-readme
-```
-
-## Rules
-
-- **Start with a type**, followed by a slash. The types are the same as [Conventional Commits](/Standards/conventional-commits#type-reference).
-- **Describe the work in two to five words**, in lower-case kebab-case. Branch names are kebab-case, like route folders, documentation files and CSS variables — it is the Git convention, and it is safe on every operating system.
-- **Use full English words**, the same as in code: `fix/button-alignment`, not `fix/btn-align`.
-- **One piece of work per branch.** If the description needs the word "and", it is two branches.
-- **Never work directly on `main`.**
-
-## Types
-
-| Type       | Use for                                | Example                       |
-| ---------- | -------------------------------------- | ----------------------------- |
-| `feat`     | A new feature                          | `feat/invoice-export`         |
-| `fix`      | A bug fix                              | `fix/login-redirect-loop`     |
-| `docs`     | Documentation only                     | `docs/update-readme`          |
-| `refactor` | Restructuring with no behaviour change | `refactor/split-user-service` |
-| `test`     | Adding or correcting tests             | `test/invoice-total-rounding` |
-| `chore`    | Maintenance, dependencies, tooling     | `chore/upgrade-next`          |
-
-## Examples
-
-```text
-✅ Good
-feat/hero-question-rail
-fix/checkout-total-rounding
-chore/upgrade-tailwind
-
-❌ Bad
-hero                         # No type, and too vague
-feature/HeroQuestionRail     # Not a standard type, and not kebab-case
-fix/btn                      # Shorthand
-toms-branch                  # Says nothing about the work
-feat/invoices-and-login-fix  # Two pieces of work
-```
-
-## Ticket numbers
-
-When the work has a ticket, put the ticket number after the type:
-
-```text
-feat/ACT-142-invoice-export
-```
-
-## AI agents
-
-AI agents **never commit code**, so they do not create branches to commit to either. A person creates the branch, reviews the agent's changes, and commits them. See [AGENTS.md](/Standards/agent-specs#agents-never-commit-code).