168 lines
4.9 KiB
Markdown
168 lines
4.9 KiB
Markdown
# 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.
|