centralize guides and rails under mosaic with runtime compatibility links

2026-02-17 11:39:52 -06:00
parent a1c2efef1c
commit 4eac2c76e6
85 changed files with 10785 additions and 0 deletions
--- a/rails/codex/README.md
+++ b/rails/codex/README.md
@@ -0,0 +1,265 @@
+# 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
+~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+
+# Security review
+~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+### Review a Pull Request
+
+```bash
+# Review and post findings as a PR comment
+~/.mosaic/rails/codex/codex-code-review.sh -n 42
+
+# Security review and post to PR
+~/.mosaic/rails/codex/codex-security-review.sh -n 42
+```
+
+### Review Against Base Branch
+
+```bash
+# Code review changes vs main
+~/.mosaic/rails/codex/codex-code-review.sh -b main
+
+# Security review changes vs develop
+~/.mosaic/rails/codex/codex-security-review.sh -b develop
+```
+
+### Review a Specific Commit
+
+```bash
+~/.mosaic/rails/codex/codex-code-review.sh -c abc123f
+~/.mosaic/rails/codex/codex-security-review.sh -c abc123f
+```
+
+### Save Results to File
+
+```bash
+# Save JSON output
+~/.mosaic/rails/codex/codex-code-review.sh --uncommitted -o review-results.json
+~/.mosaic/rails/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 ~/.mosaic/rails/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
+   ```
+
+2. **Copy the schemas directory:**
+   ```bash
+   cp -r ~/.mosaic/rails/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 `~/.mosaic/rails/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
+
+- `~/.mosaic/guides/code-review.md` — Manual code review checklist
+- `~/.mosaic/rails/git/` — Git helper scripts (issue/PR management)
+- OpenAI Codex CLI docs: https://developers.openai.com/codex/cli/