stack/docs/quality-rails-status.md

Quality Rails Status

Installation Date

2026-01-30

Current Status: INSTALLED - PARTIAL ENFORCEMENT

Quality Rails has been successfully installed but is currently in formatting-only mode due to existing codebase violations.

What's Installed

✅ Pre-Commit Hooks (.husky/)

• Runs lint-staged on every commit
• Currently only enforces Prettier formatting
• Ready to enable full enforcement once violations are fixed

✅ 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:

# 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:

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:

# 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:

# 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:

# 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