---
trigger: glob
globs: >-
  .github/workflows/**/*.yml,lefthook.yml,package.json,eslint.config.ts,turbo.json,.npmrc
---
# Tooling & CI/CD

**"Hooks help developers, CI enforces quality"** - Fast local feedback, comprehensive remote validation.

## Performance Targets

- Pre-commit: <100ms (format only)
- Full check: <1s cached (Turbo)
- CI: <5min parallel (9 jobs)

## Git Hooks

```yaml
# ✓ Pre-commit: Format only (~50ms)
pre-commit:
  commands:
    lint-staged:
      run: npx lint-staged --config config/lint-staged-fix.config.mjs

# ✗ Never run tests/linting (too slow, CI's job)
pre-commit:
  commands:
    test:
      run: npm run test:run
```

**✅ Correct:** Prepare with CI-aware installation

```json
"prepare": "[ -n \"$CI\" ] || npx lefthook install"
```

**❌ Wrong:** Masks errors

```json
"prepare": "lefthook install || true"
```

**Lint-staged:** Format only, no linting (@config/lint-staged-fix.config.mjs)

## CI Configuration

### Parallel Jobs (Not Sequential)

```yaml
# ✓ 9 parallel jobs with clear names
jobs:
  format-check:
    name: Format Check (Prettier)
  eslint:
    name: Lint (ESLint)
  # ... 7 more jobs

# ✗ Sequential (slow)
jobs:
  quality:
    steps:
      - run: npm run format:check
      - run: npm run lint:check
```

### 4-Level Caching

```yaml
# 1. npm deps (auto via setup-node cache: "npm")
# 2. ESLint (.eslintcache, ~20-25s saved)
# 3. TypeScript (.build/*.tsbuildinfo, ~5-10s saved)
# 4. Turbo (.turbo, ~8s saved per build)
```

### React Router Types

```yaml
# ✓ Generate before linting
- run: npx react-router typegen
- run: npm run lint:check

# ✗ Missing types → "error typed value" failures
- run: npm run lint:check
```

**Why:** `.react-router/types` gitignored, must regenerate in CI

## Tool Configuration

### Prettier

**✅ Correct:** Use `format:check` script

```json
"format:check": "prettier --config config/.prettierrc --ignore-path config/.prettierignore --check ."
```

### Turbo

**✅ Correct:** Use npx (reliable in CI)

```json
"scripts": {
  "check": "npx turbo run quality:check"
}
```

**❌ Wrong:** Bare command (PATH issues)

```json
"check": "turbo run quality:check"
```

**❌ Wrong:** Recursive task names

```json
"check": "turbo run check"
```

### npm

```ini
# ✓ Strict but practical
engine-strict=true     # Enforce .nvmrc
save-exact=true        # No ^ or ~

# With package.json engines
"engines": { "node": ">=22.20.0" }  # Allow minor updates
```

## Quick Reference

### Tool Stack

- **Prettier** for formatting
- **ESLint** for linting (React, a11y, Tailwind, i18n)
- **Lefthook** not Husky (faster DX)
- **Turbo** for caching (495ms repeat runs)
- **dependency-cruiser** for architectural boundary enforcement

### Caching Priorities

1. npm deps (~30s) ⭐⭐⭐
2. ESLint (~20-25s) ⭐⭐⭐
3. TypeScript build info (~5-10s) ⭐⭐
4. Turbo builds (~8s) ⭐⭐

### Anti-patterns

❌ Tests/linting in pre-commit
❌ Pre-push hooks (CI handles it)
❌ Bare `turbo` command (use `npx`)
❌ Missing React Router type generation before ESLint

## Dependency Cruiser

**"Enforce architectural boundaries at CI time"** - Catch violations before they ship.

### Architectural Rules

| Rule                             | Purpose                                                |
| -------------------------------- | ------------------------------------------------------ |
| `no-circular`                    | Prevent circular dependencies                          |
| `no-server-code-in-client`       | Server modules (`.server.ts`) only in server contexts  |
| `no-routes-importing-routes`     | Routes shouldn't import other routes                   |
| `hooks-no-direct-db-access`      | Hooks use repositories/services, not database directly |
| `components-no-direct-db-access` | Components get data from loaders                       |
| `no-database-in-utils`           | Non-server utils should be pure                        |

### Quick Commands

```bash
# Check for violations
npm run deps:check

# Scans both app/ and database/ directories
```

Real config: @config/.dependency-cruiser.cjs

## Verification

```bash
# Local performance
npm run check  # Should be <1s cached

# Git hooks
git commit -m "test"  # Should be <2s total

# CI logs
# - Check job durations (<5min total)
# - Verify cache hits in logs
# - No "not found" errors
```

Real config: @.github/workflows/ci-deploy.yml, @lefthook.yml, @turbo.json