bootstrap/tools/codex/README.md

# Codex CLI Review Scripts

AI-powered code review and security review scripts using OpenAI's Codex CLI.

These scripts provide **independent** code analysis separate from Claude sessions, giving you a second AI perspective on code changes to catch issues that might be missed.

## Prerequisites

```bash
# Install Codex CLI
npm i -g @openai/codex

# Verify installation
codex --version

# Authenticate (first run)
codex  # Will prompt for ChatGPT account or API key

# Verify jq is installed (for JSON processing)
jq --version
```

## Scripts

### `codex-code-review.sh`
General code quality review focusing on:
- **Correctness** — logic errors, edge cases, error handling
- **Code Quality** — complexity, duplication, naming, dead code
- **Testing** — coverage, test quality
- **Performance** — N+1 queries, blocking operations, resource cleanup
- **Dependencies** — deprecated packages
- **Documentation** — comments, public API docs

**Output:** Structured JSON with findings categorized as `blocker`, `should-fix`, or `suggestion`.

### `codex-security-review.sh`
Security vulnerability review focusing on:
- **OWASP Top 10** — injection, broken auth, XSS, CSRF, SSRF, etc.
- **Secrets Detection** — hardcoded credentials, API keys, tokens
- **Injection Flaws** — SQL, NoSQL, OS command, LDAP
- **Auth/Authz Gaps** — missing checks, privilege escalation, IDOR
- **Data Exposure** — logging sensitive data, information disclosure
- **Supply Chain** — vulnerable dependencies, typosquatting

**Output:** Structured JSON with findings categorized as `critical`, `high`, `medium`, or `low` with CWE IDs and OWASP categories.

## Usage

### Review Uncommitted Changes

```bash
# Code review
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted

# Security review
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
```

### Review a Pull Request

```bash
# Review and post findings as a PR comment
~/.config/mosaic/tools/codex/codex-code-review.sh -n 42

# Security review and post to PR
~/.config/mosaic/tools/codex/codex-security-review.sh -n 42
```

### Review Against Base Branch

```bash
# Code review changes vs main
~/.config/mosaic/tools/codex/codex-code-review.sh -b main

# Security review changes vs develop
~/.config/mosaic/tools/codex/codex-security-review.sh -b develop
```

### Review a Specific Commit

```bash
~/.config/mosaic/tools/codex/codex-code-review.sh -c abc123f
~/.config/mosaic/tools/codex/codex-security-review.sh -c abc123f
```

### Save Results to File

```bash
# Save JSON output
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted -o review-results.json
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted -o security-results.json
```

## Options

Both scripts support the same options:

| Option | Description |
|--------|-------------|
| `-n, --pr <number>` | PR number (auto-enables posting to PR) |
| `-b, --base <branch>` | Base branch to diff against (default: main) |
| `-c, --commit <sha>` | Review a specific commit |
| `-o, --output <path>` | Write JSON results to file |
| `--post-to-pr` | Post findings as PR comment (requires -n) |
| `--uncommitted` | Review uncommitted changes (staged + unstaged + untracked) |
| `-h, --help` | Show help |

## Woodpecker CI Integration

Automated PR reviews in CI pipelines.

### Setup

1. **Copy the pipeline template to your repo:**
   ```bash
   cp ~/.config/mosaic/tools/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
   ```

2. **Copy the schemas directory:**
   ```bash
   cp -r ~/.config/mosaic/tools/codex/schemas your-repo/.woodpecker/
   ```

3. **Add Codex API key to Woodpecker:**
   - Go to your repo in Woodpecker CI
   - Settings → Secrets
   - Add secret: `codex_api_key` with your OpenAI API key

4. **Commit and push:**
   ```bash
   cd your-repo
   git add .woodpecker/
   git commit -m "feat: Add Codex AI review pipeline"
   git push
   ```

### Pipeline Behavior

- **Triggers on:** Pull requests
- **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

## Output Format

### Code Review JSON

```json
{
  "summary": "Overall assessment...",
  "verdict": "approve|request-changes|comment",
  "confidence": 0.85,
  "findings": [
    {
      "severity": "blocker",
      "title": "SQL injection vulnerability",
      "file": "src/api/users.ts",
      "line_start": 42,
      "line_end": 45,
      "description": "User input directly interpolated into SQL query",
      "suggestion": "Use parameterized queries"
    }
  ],
  "stats": {
    "files_reviewed": 5,
    "blockers": 1,
    "should_fix": 3,
    "suggestions": 8
  }
}
```

### Security Review JSON

```json
{
  "summary": "Security assessment...",
  "risk_level": "high",
  "confidence": 0.90,
  "findings": [
    {
      "severity": "high",
      "title": "Hardcoded API key",
      "file": "src/config.ts",
      "line_start": 10,
      "description": "API key hardcoded in source",
      "cwe_id": "CWE-798",
      "owasp_category": "A02:2021-Cryptographic Failures",
      "remediation": "Move to environment variables or secrets manager"
    }
  ],
  "stats": {
    "files_reviewed": 5,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 3
  }
}
```

## Platform Support

Works with both **GitHub** and **Gitea** via the shared `~/.config/mosaic/tools/git/` infrastructure:
- Auto-detects platform from git remote
- Posts PR comments using `gh` (GitHub) or `tea` (Gitea)
- Unified interface across both platforms

## Architecture

```
codex-code-review.sh
codex-security-review.sh
    ↓
common.sh
    ↓ sources
../git/detect-platform.sh  (platform detection)
../git/pr-review.sh        (post PR comments)
    ↓ uses
gh (GitHub) or tea (Gitea)
```

## Troubleshooting

### "codex: command not found"
```bash
npm i -g @openai/codex
```

### "jq: command not found"
```bash
# Arch Linux
sudo pacman -S jq

# Debian/Ubuntu
sudo apt install jq
```

### "Error: Not inside a git repository"
Run the script from inside a git repository.

### "No changes found to review"
The specified mode (--uncommitted, --base, etc.) found no changes to review.

### "Codex produced no output"
Check your Codex API key and authentication:
```bash
codex  # Re-authenticate if needed
```

## Model Configuration

By default, scripts use the model configured in `~/.codex/config.toml`:
- **Model:** `gpt-5.3-codex` (recommended for code review)
- **Reasoning effort:** `high`

For best results, use `gpt-5.2-codex` or newer for strongest review accuracy.

## See Also

- `~/.config/mosaic/guides/CODE-REVIEW.md` — Manual code review checklist
- `~/.config/mosaic/tools/git/` — Git helper scripts (issue/PR management)
- OpenAI Codex CLI docs: https://developers.openai.com/codex/cli/