stack/packages/mosaic/framework/tools/quality/README.md

# Quality Rails

Portable quality enforcement for TypeScript, Python, and Node.js projects.

## 🎯 What This Prevents

Based on real-world validation of 50 issues in a production codebase:

- ❌ Hardcoded passwords
- ❌ SQL injection vulnerabilities
- ❌ Type safety violations (`any` types)
- ❌ Missing test coverage
- ❌ Build failures
- ❌ Dependency vulnerabilities

**70% of these issues are prevented mechanically with quality-rails.**

## ⚡ Quick Start (Mosaic)

### New Project

```bash
# Apply template from Mosaic
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project

# Install dependencies
cd /path/to/project
npm install

# Initialize git hooks
npx husky install

# Verify enforcement is working
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/project
```

### Existing Project

```bash
# Same as above - works for new or existing projects
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
```

## 🛡️ What You Get

✅ **TypeScript strict mode** - All type checks enabled
✅ **ESLint blocking `any` types** - no-explicit-any: error
✅ **Pre-commit hooks** - Type check + lint + format before commit
✅ **Secret scanning (gitleaks)** - Block hardcoded passwords/API keys (pre-commit + CI)
✅ **CI/CD templates** - Woodpecker, GitHub Actions, GitLab
✅ **Test coverage enforcement** - 80% threshold
✅ **Security scanning** - npm audit, OWASP checks

## 📦 Available Templates

| Template            | Language   | Framework        | Status         |
| ------------------- | ---------- | ---------------- | -------------- |
| `typescript-node`   | TypeScript | Node.js          | ✅ Ready       |
| `typescript-nextjs` | TypeScript | Next.js          | ✅ Ready       |
| `monorepo`          | TypeScript | TurboRepo + pnpm | ✅ Ready       |
| `python`            | Python     | -                | 🚧 Coming Soon |

### Monorepo Template

Perfect for projects combining **Next.js frontend** + **NestJS backend** in one repository.

Features:

- 🎯 **Multi-package aware** - lint-staged only checks changed packages
- ⚡ **TurboRepo caching** - Faster builds and tests
- 🔀 **Parallel dev servers** - Run web + API simultaneously
- 📦 **pnpm workspaces** - Efficient dependency management
- 🛡️ **Package-specific rules** - Next.js and NestJS get appropriate ESLint configs

Example structure:

```
monorepo/
├── apps/
│   ├── web/    # Next.js frontend
│   └── api/    # NestJS backend
└── packages/
    ├── shared-types/
    ├── ui/
    └── config/
```

## 🧪 How It Works

### Pre-Commit (Local Enforcement)

```bash
# You try to commit code with a type error
git commit -m "Add feature"

# Quality rails blocks it:
❌ Type error: Type 'number' is not assignable to type 'string'
❌ ESLint: Unexpected any. Specify a different type.
✋ Commit blocked - fix errors and try again
```

### CI/CD (Remote Enforcement)

```yaml
# Woodpecker pipeline runs:
✓ gitleaks (secret scanning — parallel, no deps)
✓ npm audit (dependency security)
✓ eslint (code quality)
✓ tsc --noEmit (type checking)
✓ jest --coverage (tests + coverage)
✓ npm run build (compilation — gates on all above)
# If any step fails, merge is blocked
```

## 🎓 Philosophy

**Process compliance doesn't work.**

Instructing AI agents to "do code review" or "run tests" fails. They claim to follow processes but output quality doesn't match claims.

**Mechanical enforcement works.**

Quality rails don't ask agents to follow processes. They **block commits** that don't pass automated checks.

- Type errors? → **Commit blocked**
- Hardcoded secrets? → **Commit blocked**
- Test failures? → **Commit blocked**
- Missing coverage? → **Commit blocked**

This works for **any agent runtime** (Codex, Claude, OpenCode, Gemini, etc.) because enforcement is mechanical, not instructional.

[Read more: PHILOSOPHY.md](./PHILOSOPHY.md)

## 📖 Documentation

- [TypeScript Setup Guide](./docs/TYPESCRIPT-SETUP.md)
- [CI/CD Configuration](./docs/CI-SETUP.md)

## 🔧 Scripts

| Script                | Purpose                                   |
| --------------------- | ----------------------------------------- |
| `scripts/install.sh`  | Install template to project (Linux/Mac)   |
| `scripts/install.ps1` | Install template to project (Windows)     |
| `scripts/verify.sh`   | Verify enforcement is working (Linux/Mac) |
| `scripts/verify.ps1`  | Verify enforcement is working (Windows)   |

## 🚀 Roadmap

- [x] TypeScript/Node template
- [x] Pre-commit enforcement (husky + lint-staged)
- [x] CI/CD templates (Woodpecker, GitHub Actions)
- [x] Installation scripts
- [x] Verification testing
- [x] Next.js template
- [x] Monorepo template
- [ ] Python template
- [ ] Coverage visualization
- [ ] IDE integration (VSCode extension)

## 🤝 Contributing

Quality Rails is based on lessons learned from real production codebases. Contributions welcome!

## 📝 License

MIT License - See LICENSE file for details

## 🙏 Credits

Built to solve real problems discovered in AI-assisted development workflows.

Based on validation findings from a production patch milestone.