feat(best_practice): add code quality scanning and commit message validation

- Implemented a code quality scanner that checks for common clean-code violations in Rust source files, including missing documentation, usage of `.unwrap()` in production code, and commented-out code. - Introduced a commit message validator that follows the Conventional Commits specification, ensuring proper formatting and providing suggestions for invalid messages. - Created a unified BestPracticeEngine to encapsulate the functionalities of skills, architecture audits, code quality checks, and commit message validation. - Added tests for both the code quality scanner and commit message validator to ensure reliability and correctness.
2026-07-21 07:21:22 +07:00
parent 55677dd671
commit 8ecc588a3e
20 changed files with 3449 additions and 0 deletions
@@ -0,0 +1,107 @@
+---
+name: push-flow-convention
+description: Enforce pre-commit/pre-push hooks, lint-staged checks, and semver version bump on every push
+---
+
+# Push Flow Convention
+
+Every repository MUST enforce the same pre-commit, pre-push, and versioning flow. No push lands without hooks, lint-staged, and a version bump.
+
+## Required Setup
+
+### 1. Lefthook (pre-commit + pre-push)
+
+> **Always use [Lefthook](https://lefthook.dev/) for git hooks. Never use husky.**
+
+Install once per repo:
+
+```bash
+pnpm add -D lefthook lint-staged
+pnpm exec lefthook install
+```
+
+Create `lefthook.yml` in project root:
+
+```yaml
+pre-commit:
+  commands:
+    lint-staged:
+      run: pnpm exec lint-staged
+
+pre-push:
+  commands:
+    lint-staged:
+      run: pnpm exec lint-staged --diff="origin/{push_remote_branch}...HEAD"
+    bump:
+      run: pnpm run bump
+```
+
+### 2. lint-staged
+
+Declared in `package.json`. Runs ONLY on staged files so commits stay fast.
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### 3. Version bump script
+
+`package.json` MUST expose a `bump` script used by `pre-push`:
+
+```json
+{
+  "scripts": {
+    "bump": "node scripts/bump-version.mjs"
+  }
+}
+```
+
+The script inspects the diff between the current branch and its upstream, applies the semver rule below, and writes the new version back to `package.json`. Commit the bump before pushing (amend the previous commit or create a `chore: adjust package.json version (bump)` commit — see `commit-convention`).
+
+## Semver Rules (applied on every push)
+
+The bump is based on the changes in the commits being pushed:
+
+| Change size / kind | Bump |
+|--------------------|------|
+| `< 5` changed files across pushed commits | **patch** (`x.y.Z`) |
+| `>= 5` changed files across pushed commits | **minor** (`x.Y.0`) |
+| New feature OR new behaviour (any `feat:` commit) | **major** (`X.0.0`) |
+
+Rules in order of precedence:
+1. If ANY commit being pushed is a `feat(...)` → **major** bump.
+2. Otherwise, count files changed (`git diff --name-only origin/<branch>...HEAD | wc -l`):
+   - fewer than 5 → **patch**
+   - 5 or more → **minor**
+
+The `feat` rule always wins — a new feature is always a major bump regardless of file count.
+
+## Non-negotiables
+
+1. NEVER push without pre-commit and pre-push hooks installed.
+2. NEVER bypass hooks with `--no-verify` — if a hook fails, fix the root cause.
+3. NEVER push without a version bump. Every push = new version.
+4. The bump commit MUST use the `chore: adjust package.json version (bump)` message (see `commit-convention`).
+5. lint-staged MUST run on every commit. A green lint-staged is a prerequisite for the commit to be created.
+6. If `pnpm` is not the package manager, substitute with `npm` or `yarn` but keep the same flow.
+
+## Quick verification checklist
+
+Before declaring the push flow set up, confirm:
+
+- [ ] `lefthook.yml` exists with `pre-commit` and `pre-push` hooks
+- [ ] `pnpm exec lefthook install` has been run (hooks registered in `.git/hooks/`)
+- [ ] `package.json` has a `lint-staged` block
+- [ ] `package.json` has a `bump` script
+- [ ] A dry-run commit triggers lint-staged
+- [ ] A dry-run push triggers the version bump