snippet-pastebin/docs/QUALITY_CI_CD_INDEX.md

# Quality CI/CD Implementation Index

## Overview

This index provides a complete guide to the CI/CD quality check system implemented for the snippet-pastebin project.

## Quick Links

### Getting Started
- **New to quality checks?** Start with [QUALITY_SETUP_QUICK_START.md](./QUALITY_SETUP_QUICK_START.md) (5 minutes)
- **Need complete reference?** Read [QUALITY_CI_CD_SETUP.md](./QUALITY_CI_CD_SETUP.md) (comprehensive)

### Key Files

#### Configuration
- `.quality/gates.json` - Quality thresholds and fail conditions
- `.qualityrc.json` - Detailed quality validator rules
- `package.json` - npm scripts for quality checks

#### Workflows
- `.github/workflows/quality-check.yml` - GitHub Actions automation
- `scripts/pre-commit-quality-check.sh` - Local pre-commit validation
- `scripts/generate-badge.sh` - Quality badge generation

#### Documentation
- `docs/QUALITY_CI_CD_SETUP.md` - Full technical documentation
- `docs/QUALITY_SETUP_QUICK_START.md` - Quick start guide
- `docs/QUALITY_CI_CD_INDEX.md` - This file

## Implementation Summary

### What Was Implemented

1. **GitHub Actions Workflow** (175 lines)
   - Automated quality checks on push and pull requests
   - Runs tests, validates code quality, checks security
   - Generates reports and posts results to PRs
   - Enforces quality gate (≥85% score required)

2. **Pre-commit Hook** (155 lines)
   - Validates code locally before commit
   - Provides instant feedback to developers
   - Shows component scores and trends
   - Can be bypassed with `--no-verify` flag

3. **Quality Gate Configuration** (47 lines)
   - Defines minimum quality standards
   - Sets score thresholds for each component
   - Configures fail conditions
   - Enables trend tracking

4. **Badge Generation** (118 lines)
   - Creates SVG quality badge
   - Color-coded by score range
   - Shows trend indicator
   - Embeds in README for visibility

5. **npm Scripts** (4 commands added)
   - `npm run quality-check` - Quick check
   - `npm run quality-check:json` - JSON report
   - `npm run quality-check:html` - HTML report
   - `npm run quality-check:verbose` - Detailed output

### Quality Thresholds

| Component | Minimum Score |
|-----------|---------------|
| Overall | 85% |
| Code Quality | 80% |
| Test Coverage | 70% |
| Architecture | 80% |
| Security | 85% |

### Grade Mapping

| Score | Grade | Status |
|-------|-------|--------|
| 95-100 | A+ | Excellent |
| 90-94 | A | Very Good |
| 85-89 | B+ | Good |
| 80-84 | B | Satisfactory |
| 70-79 | C | Acceptable |
| 60-69 | D | Poor |
| <60 | F | Fail |

## Common Tasks

### Install & Setup (5 minutes)

```bash
# Install pre-commit hook
cp scripts/pre-commit-quality-check.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Verify installation
.git/hooks/pre-commit
```

### Run Quality Checks Locally

```bash
# Quick check with console output
npm run quality-check

# Generate detailed HTML report
npm run quality-check:html
open .quality/report.html

# Verbose mode for debugging
npm run quality-check:verbose

# JSON report for scripts/automation
npm run quality-check:json
cat .quality/report.json | jq .
```

### Before Committing

```bash
# Make your changes
npm test
npm run lint:fix

# Check quality
npm run quality-check

# If passing, commit (pre-commit hook runs automatically)
git add .
git commit -m "Your message"

# If failing, fix issues and retry
npm run quality-check:verbose  # See detailed report
# Fix issues...
npm run quality-check          # Verify pass
git commit -m "Fix quality issues"
```

### Bypass Checks (Use Carefully)

```bash
# Skip pre-commit hook (NOT recommended)
git commit --no-verify

# Note: GitHub Actions will still validate on push/PR
# and can block merge if quality gate not met
```

## Workflow Stages

### Stage 1: Local Development (Pre-commit)
- Developer makes code changes
- Runs `git commit`
- Pre-commit hook automatically runs quality check
- If pass: commit proceeds
- If fail: commit blocked (can use --no-verify to override)

### Stage 2: GitHub Push
- Code pushed to main/develop or PR created
- GitHub Actions workflow automatically triggered
- Runs all quality checks
- Generates reports and badge

### Stage 3: PR Review
- Quality results posted to PR comment
- Reviewers can see score and metrics
- Can block merge if quality gate not met (if configured)

## Reports Generated

### Local Reports
- `.quality/pre-commit-report.json` - Latest pre-commit check
- `.quality/report.json` - Latest full check (JSON format)
- `.quality/report.html` - Latest full check (HTML format, most detailed)
- `.quality/badge.svg` - Current quality badge

### GitHub Actions Artifacts
- `quality-reports/` - All reports (30-day retention)
- `coverage-report/` - Coverage data (7-day retention)

### History
- `.quality/history.json` - Last 10 runs for trend analysis

## Troubleshooting

### Pre-commit Hook Not Running
```bash
# Check hook exists
ls -l .git/hooks/pre-commit

# Make executable
chmod +x .git/hooks/pre-commit

# Test manually
.git/hooks/pre-commit
```

### Quality Check Takes Too Long
- Analyze what's slow: `npm run quality-check:verbose`
- Consider skipping non-critical checks locally
- Full checks still run in GitHub Actions CI

### GitHub Actions Failing But Local Passes
```bash
# Match CI environment locally
nvm install 18 && nvm use 18
npm ci --legacy-peer-deps

# Run same commands
npm test -- --coverage
bash quality-check.sh
```

### Badge Not Updating
```bash
# Regenerate badge
bash scripts/generate-badge.sh

# Verify report exists
ls -l .quality/report.json

# Clear git cache if needed
git rm --cached .quality/badge.svg
git add .quality/badge.svg
```

## Advanced Configuration

### Adjust Quality Thresholds
Edit `.quality/gates.json` to change minimum scores:
```json
{
  "minOverallScore": 80,    # Lowered from 85
  "minTestCoverage": 65,    # Lowered from 70
  ...
}
```

### Exclude Files from Analysis
Edit `.qualityrc.json` `excludePaths`:
```json
{
  "excludePaths": [
    "node_modules/**",
    "dist/**",
    "src/legacy/**"  # Add your exclusions
  ]
}
```

### Custom Complexity Rules
Edit `.qualityrc.json` `codeQuality.complexity`:
```json
{
  "codeQuality": {
    "complexity": {
      "max": 20,      # Increase max allowed
      "warning": 15   # Adjust warning level
    }
  }
}
```

## Integration with Tools

### GitHub Branch Protection
Configure in repository settings:
1. Go to Settings > Branches > main
2. Enable "Require status checks to pass"
3. Select "Quality Validation" check
4. Enable "Require branches to be up to date"

### VS Code Integration
Add to `.vscode/tasks.json`:
```json
{
  "tasks": [
    {
      "label": "Quality Check",
      "type": "shell",
      "command": "npm",
      "args": ["run", "quality-check"],
      "group": {"kind": "test", "isDefault": true}
    }
  ]
}
```

### Slack Notifications
Add step to `.github/workflows/quality-check.yml`:
```yaml
- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v1.24.0
```

## Performance Impact

### Local Development
- Pre-commit hook: 5-10 seconds
- Full quality check: 10-15 seconds
- Can be optimized by skipping checks

### CI/CD Pipeline
- Adds 2-3 minutes to workflow
- Minimal artifact storage cost
- No blocking impact on deployment

## Quality Score Components

### Code Quality (30% weight)
Measures:
- Cyclomatic complexity (functions shouldn't exceed max=15)
- Code duplication (max 5%)
- Linting errors (max 3, warnings max 15)

### Test Coverage (35% weight, highest)
Measures:
- Line coverage (min 80%)
- Branch coverage (min 75%)
- Function coverage (min 80%)
- Statement coverage (min 80%)

### Architecture (20% weight)
Measures:
- Component size (max 500 lines)
- Circular dependencies (not allowed)
- Design pattern compliance
- React best practices

### Security (15% weight)
Measures:
- Known vulnerabilities (max 2 high, 0 critical)
- Secret detection
- Dangerous pattern detection
- Input validation checks

## Best Practices

### For Developers
1. Always run quality check before committing
2. Fix issues locally rather than bypassing checks
3. Review detailed HTML report for insights
4. Keep complexity low with focused functions
5. Write tests as you code (improves coverage)

### For Team Leads
1. Monitor quality trends over time
2. Investigate sudden score drops
3. Adjust thresholds by team consensus
4. Include quality metrics in retrospectives
5. Celebrate quality improvements

### For DevOps/CI
1. Review GitHub Actions logs for failures
2. Monitor artifact storage usage
3. Update Node version if needed
4. Configure Slack notifications
5. Set up quality dashboard if available

## Monitoring & Analytics

### View Quality History
```bash
# Last 10 runs
jq '.[-10:]' .quality/history.json

# Average score over time
jq 'map(.overall.score) | add / length' .quality/history.json

# Trend analysis
jq '[.[0].overall.score, .[-1].overall.score]' .quality/history.json
```

### Set Up Alerts
Configure in `.quality/gates.json` trend settings:
- Alert if score drops >5%
- Alert if critical issues introduced
- Alert if coverage drops significantly

## Documentation Files

| File | Purpose | Length | Audience |
|------|---------|--------|----------|
| QUALITY_SETUP_QUICK_START.md | 5-minute setup | 241 lines | New users |
| QUALITY_CI_CD_SETUP.md | Complete reference | 736 lines | Developers, DevOps |
| QUALITY_CI_CD_INDEX.md | Navigation & summary | This file | Everyone |

## Next Steps

### Immediate (Today)
1. Read [QUALITY_SETUP_QUICK_START.md](./QUALITY_SETUP_QUICK_START.md)
2. Install pre-commit hook
3. Run first quality check

### Short Term (This Week)
1. Review GitHub Actions workflow
2. Configure branch protection (if needed)
3. Share setup with team
4. Address any quality issues

### Long Term (Ongoing)
1. Monitor quality trends
2. Adjust thresholds based on team velocity
3. Integrate with project dashboards
4. Build quality culture in team

## FAQ

**Q: Can I commit code that fails quality check?**
A: Use `git commit --no-verify` to bypass the pre-commit hook, but GitHub Actions will still check your PR and can block merge.

**Q: What if quality threshold is too high?**
A: Discuss with team and adjust in `.quality/gates.json`, but consider fixing underlying quality issues first.

**Q: Does this slow down my workflow?**
A: Pre-commit check adds 5-10 seconds. Much faster than fixing issues in code review!

**Q: How do I exclude legacy code?**
A: Add paths to `excludePaths` in `.qualityrc.json` to exclude old code.

**Q: Can I see trends over time?**
A: Yes! Reports include trend charts and `.quality/history.json` tracks last 10 runs.

**Q: What if GitHub Actions fails but local passes?**
A: Usually environment difference (Node version, dependencies). See troubleshooting section.

## Support

For issues:
1. Check [QUALITY_CI_CD_SETUP.md](./QUALITY_CI_CD_SETUP.md) troubleshooting section
2. Review GitHub Actions logs
3. Check badge generation script output
4. Review pre-commit hook output locally

For questions:
1. See documentation files
2. Check configuration files with comments
3. Review workflow YAML comments
4. Check script header comments

## Version History

- **v1.0.0** (2025-01-20) - Initial implementation
  - GitHub Actions workflow
  - Pre-commit hook
  - Quality gates configuration
  - Badge generation
  - Complete documentation

## Related Files

- Configuration: `.qualityrc.json`, `.quality/gates.json`
- Workflows: `.github/workflows/quality-check.yml`
- Scripts: `scripts/pre-commit-quality-check.sh`, `scripts/generate-badge.sh`
- Reports: `.quality/`, `coverage/`

---

**Last Updated:** 2025-01-20
**Status:** Production Ready
**Tests:** All 2462 passing
**Documentation:** Complete