stack/docs/quality-rails-status.md

# Quality Rails Status

## Installation Date

2026-01-30

## Current Status: **STRICT ENFORCEMENT ACTIVE** ✅

Quality Rails is now **FULLY ENFORCING** code quality on all commits. Any commit that touches a package with violations will be blocked until that package is cleaned up.

## What's Installed

### ✅ Pre-Commit Hooks (.husky/) - ACTIVE

- Runs lint-staged on every commit
- **BLOCKS commits** with lint errors or warnings in affected packages
- **BLOCKS commits** with type errors in affected packages
- Auto-formats code with Prettier before linting

### ✅ Enhanced ESLint Rules

Added to `packages/config/eslint/base.js`:

- `@typescript-eslint/no-explicit-any: "error"` - Block any types
- `@typescript-eslint/explicit-function-return-type: "warn"` - Require return types
- `@typescript-eslint/explicit-module-boundary-types: "error"` - Export type safety
- `eslint-plugin-security` - SQL injection, XSS detection
- Promise/async safety rules
- Code quality improvements

### ✅ CI/CD Pipeline (.woodpecker.yml)

Ready to use (not yet configured in CI system):

- npm audit (dependency security)
- eslint (code quality)
- tsc (type checking)
- vitest (tests + 80% coverage threshold)
- build (compilation)

### ✅ Dependencies Added

- husky@9.1.7 - Git hook management
- lint-staged@16.2.7 - Staged file checking
- eslint-plugin-security@3.0.1 - Security vulnerability detection

## Current Violations

**Total violations found: 1,226** (1,121 errors, 105 warnings)

### Breakdown by Category:

- **Explicit `any` types**: ~400+ violations
- **Unsafe member access**: ~300+ violations
- **Missing return types**: ~200+ violations
- **Code quality issues**: ~105 violations
- **Formatting issues**: ~200+ violations

### Most Common Violations:

1. `@typescript-eslint/no-explicit-any` - Unexpected any types
2. `@typescript-eslint/no-unsafe-member-access` - Unsafe any usage
3. `@typescript-eslint/no-unsafe-assignment` - Unsafe any assignment
4. `prettier/prettier` - Formatting inconsistencies
5. `@typescript-eslint/prefer-nullish-coalescing` - Use ?? instead of ||

## Roadmap to Full Enforcement

### Phase 1: Fix Existing Violations (Current)

**Goal**: Reduce violations to zero

**Priority order**:

1. Security issues (if any from eslint-plugin-security)
2. Explicit `any` types → Replace with proper types
3. Unsafe member access → Add type guards
4. Missing return types → Add explicit types
5. Code quality warnings → Refactor where beneficial

**Approach**:

```bash
# Run lint to see all violations
pnpm turbo run lint

# Fix auto-fixable issues first
pnpm turbo run lint:fix

# Then manually fix remaining issues package by package
pnpm turbo run lint --filter=@mosaic/api
```

**Estimated effort**: 20-40 hours (depending on thoroughness)

### Phase 2: Enable Strict Pre-Commit Enforcement

Once violations are at zero, update `.lintstagedrc.mjs`:

```javascript
export default {
  "**/*.{ts,tsx}": (filenames) => {
    const packages = [
      ...new Set(
        filenames.map((f) => {
          const match = f.match(/^(apps|packages)\/([^/]+)\//);
          return match ? `@mosaic/${match[2]}` : null;
        })
      ),
    ].filter(Boolean);

    if (packages.length === 0) return [];

    // STRICT ENFORCEMENT - blocks commits with violations
    return packages.map(
      (pkg) => `pnpm turbo run lint typecheck --filter=@mosaic/${pkg} -- --max-warnings=0`
    );
  },

  "**/*.{js,jsx,ts,tsx,json,md,yml,yaml}": ["prettier --write"],
};
```

### Phase 3: Enable CI/CD Enforcement

Configure Woodpecker CI (or GitHub Actions) to run `.woodpecker.yml` pipeline on every PR.

This will block PRs that:

- Have dependency vulnerabilities (npm audit)
- Don't pass linting (eslint)
- Don't pass type checking (tsc)
- Have test failures or <80% coverage
- Don't build successfully

## Testing Enforcement

### Test that pre-commit hooks work:

```bash
# Create a file with violations
echo 'export function bad(x: any) { return x; }' > test.ts
git add test.ts
git commit -m "test"
# Should be BLOCKED once strict enforcement is enabled
```

### Test that CI enforcement works:

```bash
# Push a branch with violations
# CI should fail the build
```

## Benefits Once Fully Enabled

Based on Quality Rails validation of 50 real production issues:

| Issue Category      | Current Status       | After Full Enforcement        |
| ------------------- | -------------------- | ----------------------------- |
| Hardcoded passwords | Possible             | ✅ BLOCKED by git-secrets     |
| SQL injection       | Possible             | ✅ BLOCKED by security plugin |
| Type safety (`any`) | **1,121 violations** | ✅ BLOCKED by no-explicit-any |
| Silent failures     | Partial protection   | ⚠️ Partially blocked          |
| Test coverage gaps  | Not enforced         | ✅ BLOCKED by 80% threshold   |
| Build failures      | Not enforced         | ✅ BLOCKED by pre-commit tsc  |
| Dependency CVEs     | Not enforced         | ✅ BLOCKED by npm audit       |

**Expected impact: ~70% of quality issues prevented mechanically**

## Notes

### git-secrets (Optional)

The pre-commit hook tries to run `git-secrets` but falls back gracefully if not installed.

To install git-secrets for secret scanning:

```bash
# Install git-secrets (platform-specific)
# Then configure patterns:
git secrets --add 'password\s*=\s*["\'].*["\']'
git secrets --add 'api[_-]?key\s*=\s*["\'].*["\']'
```

### Turbo Caching

Turbo caches lint and typecheck results, so repeated runs are fast. Only changed packages are re-checked.

### IDE Integration

ESLint rules are enforced in VSCode/other IDEs automatically. Developers will see errors in real-time before committing.

## Questions?

- See quality-rails documentation: `~/src/quality-rails/`
- See PHILOSOPHY.md for why mechanical enforcement matters
- Check existing issues for progress on fixing violations