xianwen-pre-commit

name	xianwen-pre-commit
description	Local CI gate before commit/push. Runs the same checks as GitHub Actions CI: cargo fmt, clippy, cargo test (server), vue-tsc type check, vite build (web-client). MUST run before any commit or push to prevent CI failures. Use PROACTIVELY before every commit/push.

Xianwen Pre-Commit Local CI Gate

Run the exact same checks that GitHub Actions CI performs, locally, before any commit or push. This prevents the #1 recurring issue across 999+ sessions: CI failure after push.

When to Trigger

MANDATORY before:

• git commit
• git push
• Any deploy operation
• Creating a release tag

Check Pipeline

Execute checks in order. Stop on first failure — fix before proceeding.

Phase 1: Detect Changed Files

Determine which checks to run based on what changed:

# Get list of changed files (staged + unstaged)
git diff --name-only HEAD
git diff --name-only --cached

• Files under server/ → run Server checks
• Files under web-client/ → run Web Client checks
• Files under both → run ALL checks
• If unsure → run ALL checks

Phase 2: Server Checks (Rust)

Run in order — each step must pass before the next:

2a. Format Check

cd server && cargo fmt --check

If fails: Run cargo fmt to auto-fix, then re-stage the formatted files.

2b. Clippy Lint

cd server && cargo clippy -- -D warnings

If fails: Fix all warnings. Common issues:

• Unused imports → remove them
• Unused variables → prefix with _ or remove
• Missing error handling → add proper .map_err() or ?
• Type mismatch → fix the types

Note: Clippy requires DATABASE_URL for SQLx compile-time checks. If not available locally, use offline mode:

cd server && cargo clippy --features sqlx/offline -- -D warnings

2c. Tests

cd server && cargo test

If fails: Fix the failing tests. Do NOT skip tests.

Phase 3: Web Client Checks (Vue/TypeScript)

3a. Type Check + Build

cd web-client && pnpm run build:web

This runs vue-tsc -b && vite build --mode web which performs:

1. Full TypeScript type checking across all .vue and .ts files
2. Vite production build (catches import errors, missing modules)

Common failures and fixes:

Error	Fix
TS2305: has no exported member	Add missing export to the source module
TS2307: Cannot find module	Check import path, add missing type file
TS2339: Property does not exist	Fix type definition or add type assertion
TS18048: possibly undefined	Add null check or optional chaining
TS2345: Argument type mismatch	Fix the type to match expected signature
Vite chunk/import error	Check circular dependencies

3b. Frontend Tests (if exist)

cd web-client && pnpm test

Phase 4: Cross-cutting Checks

4a. No Secrets Leaked

# Check for hardcoded secrets in staged files
git diff --cached --diff-filter=ACM | grep -iE '(password|secret|api_key|token|private_key)\s*[:=]' | grep -v '\.example\|test\|mock\|TODO\|FIXME'

4b. No Debug Leftovers

# Check for console.log / dbg! / println! in staged files
git diff --cached --diff-filter=ACM -- '*.ts' '*.vue' | grep -E '^\+.*console\.(log|debug|warn)\(' | grep -v '// keep'
git diff --cached --diff-filter=ACM -- '*.rs' | grep -E '^\+.*(dbg!|println!)' | grep -v '// keep'

4c. Migration File Present

If any server/src/models/ or server/src/db/ files changed with schema modifications:

• Verify a corresponding migration exists in server/migrations/
• Migration filename format: YYYYMMDDHHMMSS_description.sql

Output Format

Report results clearly:

═══════════════════════════════════════
  Xianwen Pre-Commit CI Gate
═══════════════════════════════════════

  [1/6] cargo fmt --check    ✅ PASS
  [2/6] cargo clippy          ✅ PASS
  [3/6] cargo test            ✅ PASS
  [4/6] pnpm build:web        ✅ PASS
  [5/6] secret scan           ✅ PASS
  [6/6] debug cleanup         ⚠️  2 console.log found (non-blocking)

═══════════════════════════════════════
  Result: ✅ ALL CHECKS PASSED
  Safe to commit and push.
═══════════════════════════════════════

Or on failure:

═══════════════════════════════════════
  Result: ❌ FAILED at step [2/6] cargo clippy
  Fix the errors above before committing.
═══════════════════════════════════════

Auto-Fix Mode

When a check fails, offer to auto-fix when possible:

• cargo fmt → auto-fixable, run it and re-stage
• cargo clippy → some fixes available via cargo clippy --fix
• TypeScript errors → must be fixed manually
• Debug leftovers → offer to remove them

Skip Rules

NEVER skip checks. Historical data shows:

• 30+ sessions were spent fixing CI failures that could have been caught locally
• The most common failure: vue-tsc type errors after backend model changes
• Second most common: missing exports after refactoring stores

If a check genuinely cannot run locally (e.g., no local PostgreSQL for integration tests), document why and note the risk.