integrate generalized quality-rails into mosaic bootstrap

2026-02-17 13:16:01 -06:00
parent 5ac015b177
commit e1c1ce2856
38 changed files with 1960 additions and 0 deletions
--- a/rails/quality/docs/CI-SETUP.md
+++ b/rails/quality/docs/CI-SETUP.md
@@ -0,0 +1,174 @@
+# CI/CD Configuration Guide
+
+Configure Woodpecker CI, GitHub Actions, or GitLab CI for quality enforcement.
+
+## Woodpecker CI
+
+Quality Rails includes `.woodpecker.yml` template.
+
+### Pipeline Stages
+
+1. **Install** - Dependencies
+2. **Security Audit** - npm audit for CVEs
+3. **Lint** - ESLint checks
+4. **Type Check** - TypeScript compilation
+5. **Test** - Jest with coverage thresholds
+6. **Build** - Production build
+
+### Configuration
+
+No additional configuration needed. Push to repository and Woodpecker runs automatically.
+
+### Blocking Merges
+
+Configure Woodpecker to block merges on pipeline failure:
+1. Repository Settings → Protected Branches
+2. Require Woodpecker pipeline to pass
+
+## GitHub Actions
+
+Copy from `templates/typescript-node/.github/workflows/quality.yml`:
+
+```yaml
+name: Quality Enforcement
+
+on: [push, pull_request]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm audit --audit-level=high
+      - run: npm run lint
+      - run: npm run type-check
+      - run: npm run test -- --coverage
+      - run: npm run build
+```
+
+### Blocking Merges
+
+1. Repository Settings → Branches → Branch protection rules
+2. Require status checks to pass: `quality`
+
+## GitLab CI
+
+Copy from `templates/typescript-node/.gitlab-ci.yml`:
+
+```yaml
+stages:
+  - install
+  - audit
+  - quality
+  - build
+
+install:
+  stage: install
+  script:
+    - npm ci
+
+audit:
+  stage: audit
+  script:
+    - npm audit --audit-level=high
+
+lint:
+  stage: quality
+  script:
+    - npm run lint
+
+typecheck:
+  stage: quality
+  script:
+    - npm run type-check
+
+test:
+  stage: quality
+  script:
+    - npm run test -- --coverage
+
+build:
+  stage: build
+  script:
+    - npm run build
+```
+
+## Coverage Enforcement
+
+Configure Jest coverage thresholds in `package.json`:
+
+```json
+{
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+CI will fail if coverage drops below threshold.
+
+## Security Scanning
+
+### npm audit
+
+Runs automatically in CI. Adjust sensitivity:
+
+```bash
+npm audit --audit-level=moderate  # Block moderate+
+npm audit --audit-level=high      # Block high+critical only
+npm audit --audit-level=critical  # Block critical only
+```
+
+### Snyk Integration
+
+Add to CI for additional security:
+
+```yaml
+- run: npx snyk test
+```
+
+Requires `SNYK_TOKEN` environment variable.
+
+## Notification Setup
+
+### Woodpecker
+
+Configure in Woodpecker UI:
+- Slack/Discord webhooks
+- Email notifications
+- Status badges
+
+### GitHub Actions
+
+Add notification step:
+
+```yaml
+- name: Notify on failure
+  if: failure()
+  run: |
+    curl -X POST $WEBHOOK_URL -d "Build failed"
+```
+
+## Troubleshooting
+
+**Pipeline fails but pre-commit passed:**
+- CI runs all packages, pre-commit only checks changed files
+- Fix issues in all packages, not just changed files
+
+**npm audit blocks on low-severity:**
+- Adjust `--audit-level` to `moderate` or `high`
+
+**Coverage threshold too strict:**
+- Lower thresholds in package.json
+- Add coverage exceptions for specific files