@regardio/dev 2.6.2 → 2.7.0

package/docs/en/standards/testing.md

@@ -97,27 +97,45 @@ Schema tests run against a real Postgres so policies and triggers behave as they
 
 ## Coverage
 
-Library packages hold a floor around 80% for statements, branches, functions, and lines. The floor is a minimum, not a target — the goal is meaningful tests, not arithmetic.
+Library packages hold a floor of 80% for statements, branches, functions, and lines. The floor is a minimum, not a target — the goal is meaningful tests, not arithmetic.
 
-Enforced at:
+## Branch quality gates
 
-- Local development — `pnpm test`
-- Release preparation — `ship-staging`
-- CI — GitHub Actions
+Different branches carry different promises, and the gates match those promises.
+
+| Branch | Gate | What runs |
+|--------|------|-----------|
+| `main` | commit | lint, typecheck |
+| `staging` | CI | lint, typecheck, test, coverage |
+| `production` | CI + ship | lint, typecheck, test, coverage |
+| `feature/*` | none | — |
+| `hotfix/*` | none | — |
+
+**`main` is the development branch.** Commits to `main` must be syntactically sound — lint and typecheck pass — but tests and coverage are not required to succeed. Work in progress lives here.
+
+**`staging` and `production` promise correctness.** The full QA chain runs before anything lands there. The ship commands enforce this before merging, and CI enforces it again on push.
+
+**Feature and hotfix branches are free.** Commit at will. The gate is applied when the branch merges into its target — feature → main applies main's gate, hotfix → production applies production's gate.
+
+Coverage is enforced at:
+
+- `pnpm report` — fails locally if coverage drops below the floor (run before shipping)
+- `ship:staging` and `ship:production` — run the full quality suite before merging
+- CI on `staging` and `production` — re-runs the suite on push
 
 ## Quality gates
 
-Before a package publishes:
+Before a package ships to `staging` or `production`:
 
 1. Build succeeds
 2. Type check passes
-3. Coverage meets the floor
-4. Tests pass — no skipped or failing
+3. Tests pass — no skipped or failing
+4. Coverage meets the floor
 
 ## Continuous integration
 
-- Pre-commit hooks run linting (Biome)
-- CI runs build, typecheck, and the test suite with coverage
+- Pre-commit hooks run lint (Biome, markdownlint) and typecheck on staged files
+- CI on `staging` and `production` runs the full suite including coverage
 - Release workflow blocks publishing on any failure
 
 ## Test maintenance

package/docs/en/tools/husky.md

@@ -27,6 +27,24 @@ Husky configures itself through the `prepare` script:
 
 This runs after `pnpm install` and sets up the `.husky` directory.
 
+Copy the hook templates from `@regardio/dev`:
+
+```bash
+mkdir -p .husky
+cp node_modules/@regardio/dev/templates/husky/pre-commit .husky/pre-commit
+cp node_modules/@regardio/dev/templates/husky/commit-msg .husky/commit-msg
+cp node_modules/@regardio/dev/templates/husky/pre-push .husky/pre-push
+chmod +x .husky/pre-commit .husky/commit-msg .husky/pre-push
+```
+
+## What the hooks enforce
+
+The pre-commit hook enforces **syntax correctness**, not behavioural correctness. The distinction is intentional and matches the branch model:
+
+- **`main`** is the development branch. Commits to `main` must pass lint and typecheck, but tests and coverage are not required. Work in progress belongs here.
+- **`staging` and `production`** promise correctness. The full QA chain (typecheck, test, coverage) runs on every push to those branches via the `pre-push` hook, and again inside the `ship:*` commands as a second gate.
+- **`feature/*` and `hotfix/*`** branches carry no gate. Commit freely — the gate applies when merging into the target branch.
+
 ## Hooks
 
 ### `commit-msg`
@@ -35,25 +53,83 @@ Validates commit messages against the conventional-commit format:
 
 ```bash
 #!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-commitlint --edit $1
+pnpm exec commitlint --edit "$1"
 ```
 
-### `pre-commit` (optional)
+### `pre-push`
 
-Runs linting before a commit lands:
+Branch-aware: runs typecheck on every branch except `feature/*` and `hotfix/*`; runs the full QA chain before any push to `staging` or `production`.
 
 ```bash
 #!/bin/sh
-pnpm lint
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no push gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac
 ```
 
+### `pre-commit`
+
+Branch-aware: lints staged files and runs typecheck; full QA on `staging`/`production` commits.
+
+```bash
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no commit gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACMR)"
+[ -z "$STAGED_FILES" ] && exit 0
+
+STAGED_BIOME_FILES="$(echo "$STAGED_FILES" | grep -E '\.(cjs|cts|js|jsx|mjs|mts|ts|tsx|json|jsonc)$' || true)"
+STAGED_MD_FILES="$(echo "$STAGED_FILES" | grep -E '\.(md|mdoc|mdx)$' | grep -v 'CHANGELOG\.md' || true)"
+
+if [ -n "$STAGED_BIOME_FILES" ]; then
+  echo "$STAGED_BIOME_FILES" | xargs pnpm exec biome check --no-errors-on-unmatched
+fi
+if [ -n "$STAGED_MD_FILES" ]; then
+  echo "$STAGED_MD_FILES" | xargs pnpm exec markdownlint-cli2 --config .markdownlint-cli2.jsonc
+fi
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac
+```
+
+`--if-present` means repos that don't define a given script skip that step silently.
+
 ## Bypassing hooks
 
-In the rare case where a hook truly has to be skipped:
+In the rare case where a hook truly has to be skipped, `--no-verify` works for both commit and push:
 
 ```bash
 git commit --no-verify -m "emergency fix"
+git push --no-verify origin main
 ```
 
 Use sparingly. A bypass that becomes habit stops being a bypass.
@@ -82,4 +158,6 @@ chmod +x .husky/*
 
 - [Commitlint](./commitlint.md) — commit-message validation
 - [Biome](./biome.md) — linting and formatting
+- [Release Workflow](./releases.md) — how branches, ship commands, and CI enforce quality gates
+- [Testing](../standards/testing.md) — branch gate model explained
 - [Husky Documentation](https://typicode.github.io/husky/)

package/docs/en/tools/releases.md

@@ -143,7 +143,28 @@ pnpm ship:hotfix finish
 
 ## Adoption
 
-### 1. Add ship scripts to `package.json`
+### 1. Set up Husky hooks
+
+```bash
+mkdir -p .husky
+cp node_modules/@regardio/dev/templates/husky/pre-commit .husky/pre-commit
+cp node_modules/@regardio/dev/templates/husky/commit-msg .husky/commit-msg
+chmod +x .husky/pre-commit .husky/commit-msg
+```
+
+Add the `prepare` script so Husky installs itself after `pnpm install`:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky"
+  }
+}
+```
+
+The `pre-commit` template is branch-aware: feature and hotfix branches commit freely, `main` enforces lint and typecheck, and `staging`/`production` enforce the full QA chain. See [Husky](./husky.md) for details.
+
+### 2. Add ship scripts to `package.json`
 
 ```json
 {
@@ -210,12 +231,22 @@ CI publishes subsequent versions; the very first one requires a local publish be
 
 ## Quality Gates
 
-Every ship command enforces the same gates before any commit or merge:
+Gates differ by branch. The ship commands enforce the appropriate gate before any merge.
+
+| Context | What runs |
+|---------|-----------|
+| Commit to `main` (pre-commit hook) | lint, typecheck |
+| Commit to `feature/*` or `hotfix/*` | nothing |
+| `ship:staging` / `ship:production` / `ship:hotfix finish` | build, typecheck, test, coverage |
+| CI on `staging` / `production` | build, typecheck, test, coverage |
+
+Ship commands run:
 
 ```bash
 pnpm build      # Must succeed
 pnpm typecheck  # Must succeed
 pnpm test       # Must succeed
+pnpm report     # Coverage must meet the floor
 ```
 
 ## Publishing vs Non-Publishing Repos

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.6.2",
+  "version": "2.7.0",
   "private": false,
   "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
@@ -74,10 +74,10 @@
   ],
   "devDependencies": {
     "@total-typescript/ts-reset": "0.6.1",
-    "@types/node": "25.6.2",
-    "@vitest/coverage-v8": "4.1.5",
+    "@types/node": "25.7.0",
+    "@vitest/coverage-v8": "4.1.6",
     "tsdown": "0.22.0",
-    "vitest": "4.1.5"
+    "vitest": "4.1.6"
   },
   "peerDependencies": {
     "@biomejs/biome": ">=2",

package/templates/husky/commit-msg

@@ -0,0 +1,2 @@
+#!/bin/sh
+pnpm exec commitlint --edit "$1"

package/templates/husky/pre-commit

@@ -0,0 +1,32 @@
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no commit gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACMR)"
+[ -z "$STAGED_FILES" ] && exit 0
+
+STAGED_BIOME_FILES="$(echo "$STAGED_FILES" | grep -E '\.(cjs|cts|js|jsx|mjs|mts|ts|tsx|json|jsonc)$' || true)"
+STAGED_MD_FILES="$(echo "$STAGED_FILES" | grep -E '\.(md|mdoc|mdx)$' | grep -v 'CHANGELOG\.md' || true)"
+
+if [ -n "$STAGED_BIOME_FILES" ]; then
+  echo "$STAGED_BIOME_FILES" | xargs pnpm exec biome check --no-errors-on-unmatched
+fi
+if [ -n "$STAGED_MD_FILES" ]; then
+  echo "$STAGED_MD_FILES" | xargs pnpm exec markdownlint-cli2 --config .markdownlint-cli2.jsonc
+fi
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac

package/templates/husky/pre-push

@@ -0,0 +1,19 @@
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no push gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac