# Woodpecker CI Configuration for Mosaic Stack

## Codex AI Review Pipeline

This directory contains the Codex AI review pipeline configuration for automated code and security reviews on pull requests.

### Setup

1. **Add Codex API key to Woodpecker:**
   - Go to mosaic-stack repo at `https://ci.mosaicstack.dev`
   - Settings → Secrets
   - Add secret: `codex_api_key` with your OpenAI API key

2. **Enable the pipeline:**
   - The `codex-review.yml` pipeline will automatically run on all PRs
   - The main `.woodpecker.yml` handles primary CI tasks
   - This codex pipeline is independent and focused solely on reviews

### What Gets Reviewed

**Code Review (`code-review` step):**

- Correctness — logic errors, edge cases, error handling
- Code Quality — complexity, duplication, naming
- Testing — coverage, test quality
- Performance — N+1 queries, blocking ops
- Dependencies — deprecated packages
- Documentation — comments, API docs

**Security Review (`security-review` step):**

- OWASP Top 10 vulnerabilities
- Hardcoded secrets/credentials
- Injection flaws (SQL, NoSQL, OS command)
- XSS, CSRF, SSRF
- Auth/authz gaps
- Data exposure in logs

### Pipeline Behavior

- **Triggers:** Every pull request
- **Runs:** Code review + Security review in parallel
- **Fails if:**
  - Code review finds **blockers**
  - Security review finds **critical** or **high** severity issues
- **Outputs:** Structured JSON results in CI logs

### Local Testing

Test the review scripts locally before pushing:

```bash
# Code review of uncommitted changes
~/.claude/scripts/codex/codex-code-review.sh --uncommitted

# Security review of uncommitted changes
~/.claude/scripts/codex/codex-security-review.sh --uncommitted

# Code review against main branch
~/.claude/scripts/codex/codex-code-review.sh -b main

# Security review and save JSON
~/.claude/scripts/codex/codex-security-review.sh -b main -o security.json
```

### Schema Files

The `schemas/` directory contains JSON schemas that enforce structured output from Codex:

- `code-review-schema.json` — Defines output for code quality reviews
- `security-review-schema.json` — Defines output for security reviews

These schemas ensure consistent, machine-readable findings that the CI pipeline can parse and fail on.

### Integration with Main Pipeline

The main `.woodpecker.yml` in the repo root handles:

- Type checking (TypeScript)
- Linting (ESLint)
- Unit tests (Vitest)
- Integration tests (Playwright)
- Docker image builds

This `codex-review.yml` is independent and focuses solely on:

- AI-powered code quality review
- AI-powered security vulnerability scanning

Both pipelines run in parallel on PRs.

### Troubleshooting

**Pipeline fails with "codex: command not found"**

- Check that the node image in `codex-review.yml` matches a version with npm
- Current: `node:22-slim`

**Pipeline fails with auth errors**

- Verify `codex_api_key` secret is set in Woodpecker
- Test the key locally: `CODEX_API_KEY=<key> codex exec "test"`

**Pipeline passes but should fail**

- Check the failure conditions in `codex-review.yml`
- Current thresholds: blockers, critical, or high findings

## Files

| File                                  | Purpose                                |
| ------------------------------------- | -------------------------------------- |
| `codex-review.yml`                    | Codex AI review pipeline configuration |
| `schemas/code-review-schema.json`     | Code review output schema              |
| `schemas/security-review-schema.json` | Security review output schema          |
| `README.md`                           | This file                              |

## Parent CI Pipeline

The main `.woodpecker.yml` is located at the repository root and handles all build/test tasks.