# Code Quality & Security Workflow

This document explains our **zero-compromise** approach to code quality and security.

## Philosophy

**We don't skip quality checks - we make them fast.**

- ✅ **Pre-commit**: Fast checks on staged files (< 5 seconds)
- ✅ **Manual**: Comprehensive checks before pushing
- ✅ **Dependabot**: Automated dependency updates (GitHub)

## Tools & Configuration

### 1. ESLint (JavaScript/TypeScript)
**Config**: `.dev-config/eslint.config.mjs`
**What**: Linting and code style enforcement
**When**: Pre-commit (staged files) + Manual (full project)

### 2. PHPCS (PHP Coding Standards)
**Config**: `.dev-config/phpcs.xml`
**What**: WordPress coding standards
**When**: Pre-commit (staged files) + Manual (full project)
**Auto-fix**: `phpcbf --standard=.dev-config/phpcs.xml [file]`

### 3. Psalm (PHP Static Analysis)
**Config**: `.dev-config/psalm.xml`
**What**: Type safety and bug detection
**When**: Pre-commit (incremental) + Manual (full analysis)

### 4. Trivy (Security Scanning)
**What**: Vulnerability detection in dependencies and code
**When**: Manual only (too slow for pre-commit)

### 5. Dependency Audit
**What**: NPM audit + Composer audit
**When**: Manual + Dependabot

## Workflow

### Step 1: Make Changes
```bash
# Edit files as normal
vim plugins/translate-press-zone/includes/class-foo.php
```

### Step 2: Commit (Automatic Fast Checks + Auto-Fix)
```bash
git add .
git commit -m "feat: add new feature"
```

**What happens** (AUTOMATIC):
1. 🔧 **Auto-fixes** formatting with ESLint
2. 🔧 **Auto-fixes** code style with PHPCBF
3. 📝 **Re-stages** fixed files automatically
4. ✅ Verifies types with Psalm (can't auto-fix)
5. ✅ Checks for secrets (can't auto-fix)
6. ⚠️ Warns about debug statements

**Result**: 
- **Formatting issues**: Fixed automatically! ✨
- **Type/logic errors**: Must fix manually (commit blocked)
- **Time**: ~3-5 seconds including auto-fix

**Why auto-fix by default?**
- Zero friction - just commit!
- Consistent formatting across team
- Fast - no manual formatting needed
- Safe - only fixes style, never logic

### Step 3: Before Pushing (Manual Comprehensive Checks)
```bash
./quality-check.sh
```

**What happens**:
- ✅ Full ESLint on all JS/TS
- ✅ TypeScript type checking
- ✅ Full PHPCS on all PHP
- ✅ Full Psalm static analysis
- ✅ Trivy security scan (HIGH/CRITICAL)
- ✅ NPM + Composer dependency audit

**Time**: ~30-60 seconds (thorough but acceptable)

**Auto-fix option**:
```bash
./quality-check.sh --fix
```

### Step 4: Push
```bash
git push origin main:master
```

### Step 5: After Pulling
```bash
git pull
# Post-merge hook reminds you to run:
./quality-check.sh
```

## Common Issues & Fixes

### ✅ Most Issues Auto-Fixed!
The pre-commit hook automatically fixes:
- ESLint formatting (spaces, semicolons, quotes, etc.)
- PHPCS code style (indentation, spacing, naming)

You don't need to do anything - just commit!

### Type Errors (Psalm) - Manual Fix Required
```bash
# Run to see specific errors
psalm -c .dev-config/psalm.xml --show-info=true

# Add type hints, fix docblocks, etc.
# Example:
/** @param string $foo */
public function bar($foo): void { }
```

### Hardcoded Secrets - Manual Fix Required
```bash
# ❌ Don't do this
$api_key = "sk_live_abc123xyz789";

# ✅ Do this instead
$api_key = getenv('API_KEY');

# Add to .env file (never commit .env!)
API_KEY=sk_live_abc123xyz789
```

### Security Vulnerabilities
```bash
# Update NPM packages
cd plugins/translate-press-zone/backend-app/admin-panel
npm audit fix

# Update Composer packages
cd plugins/translate-press-zone
composer update

# Re-run security scan
trivy fs --severity HIGH,CRITICAL .
```

## Performance Optimizations

### Pre-commit Hook (< 5 seconds)
- Only checks **staged files**
- **AUTO-FIXES** formatting (ESLint, PHPCBF)
- **Re-stages** fixed files automatically
- Uses **incremental mode** for Psalm
- **Parallel execution** where possible
- **Blocks commit** only for unfixable issues

### Full Check Script (~60 seconds)
- Comprehensive analysis
- No shortcuts
- Full security scanning
- Complete type checking

## Installation Requirements

### Required Tools
```bash
# Node.js tools (already in project)
npm install  # In admin-panel directory

# PHP tools
composer global require squizlabs/php_codesniffer
composer global require vimeo/psalm

# Security scanner (choose one)
# Option 1: Native install
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

# Option 2: Use Docker/Podman (script handles this automatically)
```

### Optional but Recommended
```bash
# PHP Code Beautifier (auto-fix for PHPCS)
# Already included with php_codesniffer above
```

## Why This Approach?

### ❌ Bad: Skipping Checks
- Bad code gets committed
- Security vulnerabilities slip through
- Technical debt accumulates
- Bugs reach production

### ✅ Good: Fast Incremental Checks
- Catch issues immediately
- No waiting
- No shortcuts on quality
- Maintain high standards

### ✅ Good: Comprehensive Manual Checks
- Full confidence before pushing
- Catch what incremental checks miss
- Security validation
- One-time wait before push (acceptable)

## Troubleshooting

### "Hook taking too long"
- Check if you're scanning `node_modules` or `vendor` (shouldn't be)
- Check `.dev-config` exclude patterns
- Run `./quality-check.sh` manually to identify slow check

### "Check keeps failing on same issue"
- Read error message carefully
- Use `--fix` flags when available
- Don't force commit with `--no-verify`!

### "Need to commit urgently"
- **Never** use `git commit --no-verify`
- Fix the actual issue (usually quick)
- If truly urgent, fix in next immediate commit

## GitHub Integration

### Dependabot
- ✅ **Enabled**: Automatic dependency updates
- ✅ **Free**: Works on free GitHub accounts
- ✅ **Secure**: Catches vulnerabilities early

### GitHub Actions
- ❌ **Disabled**: Causes errors on free accounts
- ✅ **Alternative**: Local `quality-check.sh` script

## Summary

| Check | Pre-commit | Manual Script | Tool |
|-------|------------|---------------|------|
| ESLint | ✅ Staged files | ✅ Full project | `npm run lint` |
| TypeScript | ❌ | ✅ Full project | `npm run type-check` |
| PHPCS | ✅ Staged files | ✅ Full project | `phpcs` |
| Psalm | ✅ Incremental | ✅ Full analysis | `psalm` |
| Trivy | ❌ | ✅ Full scan | `trivy` |
| Dependency Audit | ❌ | ✅ Full audit | `npm audit` + `composer audit` |

**Pre-commit**: < 5 seconds (no compromises on staged files)
**Manual**: ~60 seconds (comprehensive, run before push)
**Result**: High quality code, fast workflow ✅