@activatus/code-standards 2.0.0 → 3.0.1

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).

package/docs/Standards/conventional-commits.md

@@ -1,189 +0,0 @@
----
-sidebar_position: 6
----
-
-# Conventional Commits
-
-All Activatus repositories follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This gives us machine-readable history, automatic changelogs, and a shared vocabulary for what a commit does.
-
-## Format
-
-```text
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-The first line (header) must not exceed **72 characters**. Everything else is optional.
-
-## Quick examples
-
-```text
-feat(authentication): add magic-link login flow
-fix(api): handle null response from payment provider
-docs: clarify AGENTS.md authoring guide
-refactor(ui): extract Button into shared component library
-chore(deps): bump eslint-config to v0.2.0
-feat!: drop support for Node 18
-```
-
-## Type reference
-
-| Type | When to use |
-| --- | --- |
-| `feat` | A new feature visible to users or API consumers |
-| `fix` | A bug fix |
-| `docs` | Documentation changes only |
-| `style` | Formatting or whitespace — no logic change |
-| `refactor` | Code restructuring with no feature or bug change |
-| `perf` | A performance improvement |
-| `test` | Adding or correcting tests |
-| `build` | Build system or dependency changes |
-| `ci` | CI/CD pipeline changes |
-| `chore` | Maintenance that doesn't fit elsewhere |
-| `revert` | Reverts a previous commit |
-
-## Scope
-
-The scope is optional and goes in parentheses after the type. It names the part of the codebase the commit touches:
-
-```text
-feat(authentication): ...
-fix(checkout): ...
-refactor(ui/button): ...
-```
-
-Use lowercase, kebab-case names. If a commit spans many areas, omit the scope rather than writing a vague one.
-
-## Description
-
-- Imperative, present tense: **"add"** not "added" or "adds"
-- No capital letter at the start
-- No period at the end
-- Describes *what* the commit does, not *how*
-
-```text
-✓  feat: add dark mode toggle
-✗  feat: Added dark mode toggle.
-✗  feat: dark mode
-```
-
-## Body
-
-The body explains the *why* behind a change — context that won't be obvious from the diff. Wrap at 72 characters.
-
-```text
-fix(api): retry on transient 503 from payments provider
-
-The payments API returns a 503 during brief maintenance windows.
-Previously this caused checkout to fail immediately. Now we retry
-up to 3 times with exponential back-off before surfacing an error.
-```
-
-## Breaking changes
-
-Signal a breaking change in one of two ways:
-
-**Inline `!` after the type** (for the header only):
-
-```text
-feat!: remove deprecated /v1/users endpoint
-```
-
-**`BREAKING CHANGE:` footer** (required when a body explains the break):
-
-```text
-feat(api)!: require explicit content-type header on all requests
-
-BREAKING CHANGE: requests without a Content-Type header now return
-400. Previously the API defaulted to application/json.
-```
-
-A breaking change bumps the **major** version in SemVer (`1.0.0` → `2.0.0`).
-
-## Versioning implications
-
-When using [Changesets](https://github.com/changesets/changesets) or a changelog tool that understands Conventional Commits:
-
-| Commit type | SemVer bump |
-| --- | --- |
-| `fix`, `perf` | patch (`1.0.0` → `1.0.1`) |
-| `feat` | minor (`1.0.0` → `1.1.0`) |
-| Any with `!` or `BREAKING CHANGE` | major (`1.0.0` → `2.0.0`) |
-| All others (`docs`, `chore`, `ci`, …) | none |
-
-## Multi-commit PRs
-
-Each commit in a PR should be independently meaningful and deployable. Prefer:
-
-```text
-feat(authentication): scaffold magic-link token model
-feat(authentication): add magic-link send endpoint
-feat(authentication): add magic-link verify endpoint
-test(authentication): add integration tests for magic-link flow
-docs(authentication): document magic-link API in AGENTS.md
-```
-
-Over a single `feat(authentication): implement magic-link` that touches everything at once. Granular commits make `git bisect` and revert effective.
-
-## People commit, not AI agents
-
-Commits are made by people. [AI agents never commit code](/Standards/agent-specs#agents-never-commit-code) — an agent leaves its changes uncommitted, and a person reviews them and writes the commit.
-
-Branches follow the [Branch Naming](/Standards/branch-naming) standard.
-
-## Enforcing commit messages
-
-Every project uses [Commitlint](https://commitlint.io) with a [Husky](https://typicode.github.io/husky/) git hook, so a commit with a badly formatted message is refused. **Set up both — the config file on its own enforces nothing.**
-
-### Setup
-
-1. Install the packages:
-
-   ```bash
-   pnpm add -D @commitlint/cli @commitlint/config-conventional husky
-   ```
-
-2. Add the `prepare` script to `package.json`, so the hooks are installed whenever someone runs `pnpm install`:
-
-   ```json
-   {
-     "scripts": {
-       "prepare": "husky"
-     }
-   }
-   ```
-
-3. Add [`.commitlintrc.json`](/templates#commitlint) to the project root.
-
-4. Add the hook file [`.husky/commit-msg`](/templates#husky):
-
-   ```text title=".husky/commit-msg"
-   pnpm exec commitlint --edit "$1"
-   ```
-
-5. Run `pnpm install` once to activate the hook.
-
-After that, every commit runs the `commit-msg` hook.
-
-### Lint before every commit
-
-Add a second hook, [`.husky/pre-commit`](/templates#husky), so code that breaks the standards cannot be committed:
-
-```text title=".husky/pre-commit"
-pnpm lint
-```
-
-If `pnpm lint` reports an error, the commit is refused. See [Fixing Lint Errors](/Standards/lint-errors).
-
-### Configuration
-
-The configuration is in `.commitlintrc.json`:
-
-```json
-{
-  "extends": ["@commitlint/config-conventional"]
-}
-```

package/static/templates/.commitlintrc.json

@@ -1,3 +0,0 @@
-{
-  "extends": ["@commitlint/config-conventional"]
-}

package/static/templates/docsSite/docusaurus.config.ts

@@ -1,119 +0,0 @@
-import {themes as prismThemes} from 'prism-react-renderer';
-import type {Config} from '@docusaurus/types';
-import type * as Preset from '@docusaurus/preset-classic';
-
-const TITLE_SEPARATOR = ' — ';
-const FIRST_GROUP = 'overview';
-
-// Each doc is titled "# Group — Menu item". The folder is the menu group and the
-// part after the dash is the menu item. Overview comes first; everything else is alphabetical.
-const generateSidebarItems = async ({defaultSidebarItemsGenerator, docs: pages, ...remainingArguments}) => {
-  const items = await defaultSidebarItemsGenerator({docs: pages, ...remainingArguments});
-  const titleById = new Map(pages.map((page) => [page.id, page.title]));
-
-  const labelled = items.map((item) => {
-    if (item.type !== 'category') {
-      return item;
-    }
-
-    const children = item.items
-      .map((child) => {
-        if (child.type !== 'doc') {
-          return child;
-        }
-        const title = titleById.get(child.id) ?? child.id;
-        const label = title.includes(TITLE_SEPARATOR) ? title.split(TITLE_SEPARATOR)[1] : title;
-        return {...child, label};
-      })
-      .sort((first, second) => first.label.localeCompare(second.label));
-
-    const firstDoc = item.items.find((child) => child.type === 'doc');
-    const firstTitle = firstDoc ? (titleById.get(firstDoc.id) ?? '') : '';
-    const label = firstTitle.includes(TITLE_SEPARATOR) ? firstTitle.split(TITLE_SEPARATOR)[0] : item.label;
-    const folder = firstDoc ? firstDoc.id.split('/')[0] : item.label;
-
-    return {...item, label, items: children, customProps: {folder}};
-  });
-
-  return labelled.sort((first, second) => {
-    const firstFolder = first.customProps?.folder ?? '';
-    const secondFolder = second.customProps?.folder ?? '';
-    if (firstFolder === FIRST_GROUP) {
-      return -1;
-    }
-    if (secondFolder === FIRST_GROUP) {
-      return 1;
-    }
-    return String(first.label).localeCompare(String(second.label));
-  });
-};
-
-// TODO: set the project name
-const PROJECT_NAME = 'Project Name';
-
-const config: Config = {
-  title: `${PROJECT_NAME} Docs`,
-  favicon: 'images/logo.svg',
-
-  // The docs are only ever served behind the app's /docs route, so this URL is a placeholder.
-  url: 'http://localhost:3000',
-  baseUrl: '/docs/',
-
-  // Internal docs must never be indexed by search engines.
-  noIndex: true,
-
-  onBrokenLinks: 'throw',
-
-  markdown: {
-    // Plain .md files are read as CommonMark, so < and { in a doc never break the build.
-    format: 'detect',
-    mermaid: true,
-  },
-
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          // The Markdown lives in the project's root docs/ folder, not inside this site.
-          path: '../docs',
-          routeBasePath: '/',
-          sidebarPath: './sidebars.ts',
-          sidebarItemsGenerator: generateSidebarItems,
-        },
-        blog: false,
-        theme: {
-          customCss: './src/css/custom.css',
-        },
-      } satisfies Preset.Options,
-    ],
-  ],
-
-  themes: [['@getcanary/docusaurus-theme-search-pagefind', {}], '@docusaurus/theme-mermaid'],
-
-  themeConfig: {
-    tableOfContents: {
-      minHeadingLevel: 2,
-      maxHeadingLevel: 3,
-    },
-    colorMode: {
-      defaultMode: 'light',
-      respectPrefersColorScheme: true,
-    },
-    navbar: {
-      title: `${PROJECT_NAME} Docs`,
-      logo: {
-        alt: 'Logo',
-        src: 'images/logo.svg',
-      },
-      items: [],
-    },
-    prism: {
-      theme: prismThemes.oneLight,
-      darkTheme: prismThemes.oneDark,
-      additionalLanguages: ['bash', 'json'],
-    },
-  } satisfies Preset.ThemeConfig,
-};
-
-export default config;

package/static/templates/docsSite/sidebars.ts

@@ -1,8 +0,0 @@
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
-
-const sidebars: SidebarsConfig = {
-  // Built from the folder structure of the project's docs/ folder
-  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
-};
-
-export default sidebars;

package/static/templates/husky/commit-msg

@@ -1 +0,0 @@
-pnpm exec commitlint --edit "$1"

package/static/templates/husky/pre-commit

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

package/static/templates/prettier.config.js

@@ -1,17 +0,0 @@
-/** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
-const config = {
-  printWidth: 100,
-  tabWidth: 2,
-  useTabs: false,
-  singleQuote: false,
-  trailingComma: "all",
-  bracketSpacing: true,
-  bracketSameLine: false,
-  arrowParens: "always",
-  semi: true,
-  endOfLine: "lf",
-  plugins: ["prettier-plugin-tailwindcss"],
-  tailwindStylesheet: "./app/globals.css",
-};
-
-export default config;