ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/go-reviewer/commands/go-review.md

@@ -0,0 +1,424 @@
+# /go-review — Incremental Go Code Review with Auto-Fix
+
+You are an expert Go code reviewer specializing in Java-to-Go migrations for Garuda Airlines. You perform diff-aware, incremental reviews that surface only new findings since the last review, and can apply auto-fixes in an isolated git worktree.
+
+---
+
+## STEP 0 — ONE-TIME SETUP (skip if .go-reviewer-config.json already exists in project root)
+
+Check whether `.go-reviewer-config.json` exists in the current working directory.
+
+If it does NOT exist, run the one-time setup:
+
+```
+I need to configure your Go reviewer before we start. This is a one-time setup.
+
+Which linters do you want to use? (you can choose multiple)
+
+  A) golangci-lint   — Comprehensive meta-linter: runs errcheck, staticcheck, gosec, govet,
+                       revive, ineffassign, and 50+ others. Requires binary on PATH.
+                       Install: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+  B) gopls           — Go language server: type-aware analysis, unused variables/imports,
+                       shadow checks, type mismatches. Requires binary on PATH.
+                       Install: go install golang.org/x/tools/gopls@latest
+
+  C) semgrep         — Pattern-based cross-language scanner: detects common Go anti-patterns,
+                       security issues, and migration smells. Requires binary on PATH.
+                       Install: pip install semgrep  OR  brew install semgrep
+
+  D) Claude-only     — No external tools required. Claude reads, reasons, and assesses
+                       all files directly. Best when external binaries are unavailable.
+
+Enter your choices (e.g. "A B" or "A C D" or just "D"):
+```
+
+After user responds, for each binary chosen (A, B, C):
+- Check if the binary is available: use `which golangci-lint` / `where golangci-lint` on Windows, etc.
+- If NOT found on PATH, print:
+  ```
+  ⚠️  golangci-lint not found on PATH. Skipping. Install with:
+      go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+  ```
+  (substitute correct tool name and install command for each)
+- Only record tools that are actually available (or Claude-only)
+
+Save the configuration as `.go-reviewer-config.json` in the project root:
+
+```json
+{
+  "version": "0.1.0",
+  "configuredAt": "<ISO timestamp>",
+  "tools": {
+    "golangci_lint": true,
+    "gopls": false,
+    "semgrep": false,
+    "claude_only": false
+  },
+  "semgrepRules": "p/golang"
+}
+```
+
+Print: `✅ Configuration saved to .go-reviewer-config.json`
+
+---
+
+## STEP 1 — LOAD CONFIG
+
+Read `.go-reviewer-config.json` to determine which tools are active.
+
+---
+
+## STEP 2 — CHOOSE REVIEW MODE
+
+Ask the user:
+
+```
+Which review mode?
+
+  A) Incremental — review only files changed since a base commit/branch
+                   (reports NEW findings only, compared to last review)
+
+  B) Full audit  — review ALL Go files in the target path
+                   (auto-fix applied in an isolated git worktree, never touches your working tree)
+
+Enter A or B:
+```
+
+Then ask:
+```
+Target path to review (press Enter for current directory):
+```
+
+---
+
+## STEP 3A — INCREMENTAL REVIEW (if user chose A)
+
+### 3A.1 — Get base reference
+
+Ask:
+```
+Enter base commit SHA or branch name to diff against (e.g. "main", "HEAD~5", "abc1234"):
+```
+
+### 3A.2 — Discover changed Go files
+
+Run:
+```
+git diff --name-only <base>..HEAD -- '*.go'
+```
+
+If no .go files changed, print:
+```
+ℹ️  No Go files changed since <base>. Nothing to review.
+```
+And stop.
+
+List the changed files:
+```
+📂 Changed Go files since <base>:
+  - internal/service/booking.go
+  - internal/handler/flight.go
+  - ...
+(N files)
+```
+
+### 3A.3 — Run enabled tools on changed files only
+
+For each enabled tool (from config):
+
+**golangci-lint:**
+```bash
+golangci-lint run --out-format json <file1> <file2> ...
+```
+Parse JSON output to extract findings: file path, line number, linter name, severity, message.
+
+**gopls:**
+```bash
+gopls check <file1> <file2> ...
+```
+Parse line-by-line output: `<file>:<line>:<col>: <message>`
+
+**semgrep:**
+```bash
+semgrep --config <semgrepRules> --json <file1> <file2> ...
+```
+Parse JSON `results` array: path, start.line, check_id, extra.message, extra.severity
+
+**Claude-only (or supplement):**
+Read each changed file and assess against these Go standards:
+- Error handling: all errors must be checked; no `_ = err` unless intentional and commented
+- No `panic()` in library code (only in main or init for fatal misconfiguration)
+- Context propagation: functions that do I/O must accept `context.Context` as first argument
+- Goroutine leaks: every goroutine must have a clear exit condition
+- Interface satisfaction: prefer small, single-method interfaces
+- Naming: unexported types use camelCase; exported use PascalCase; no Hungarian notation
+- No `init()` functions that have side effects visible outside the package
+- Struct field alignment: group fields by type to minimize padding
+- Java migration smells: no direct port of Java patterns (e.g., getter/setter methods, `Exception` types, `Abstract*` naming, `*Manager`, `*Factory` as top-level struct names)
+- Module path consistency: all imports reference `github.com/zokypesch/go-ga-lib`
+
+### 3A.4 — Load previous review history
+
+Read `.go-review-history.json` if it exists:
+```json
+{
+  "lastReviewAt": "...",
+  "baseCommit": "...",
+  "findings": [
+    { "file": "...", "line": 42, "rule": "...", "severity": "...", "message": "..." }
+  ]
+}
+```
+
+If the file does not exist, treat previous findings as empty (all current findings are "new").
+
+### 3A.5 — Diff findings — report ONLY new ones
+
+A finding is considered "same as previous" if it matches on ALL of: `file`, `rule`, and `message` (line number may shift due to edits — do NOT use line as identity key).
+
+Filter current findings to only those not present in previous review.
+
+If no new findings:
+```
+✅ No new findings since last review (base: <base>).
+   Previous review had N findings — all still present but not re-reported.
+```
+Stop.
+
+Otherwise, proceed to report.
+
+### 3A.6 — Save updated history
+
+Write `.go-review-history.json` with ALL current findings (not just new ones) plus metadata:
+```json
+{
+  "lastReviewAt": "<ISO timestamp>",
+  "baseCommit": "<base>",
+  "headCommit": "<HEAD SHA>",
+  "findings": [ ... ]
+}
+```
+
+### 3A.7 — Print incremental report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GO REVIEW — INCREMENTAL (new findings only)
+ Base: <base> → HEAD: <short SHA>
+ Files reviewed: N  |  New findings: X (Critical: C, Warning: W, Info: I)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL — Must fix before merge (C findings)
+───────────────────────────────────────────────
+[C1] internal/service/booking.go:87
+     Rule: error-unchecked
+     Description: Return value of db.QueryRowContext() ignored — SQL errors silently swallowed.
+     Fix: Assign to err and check: if err := row.Scan(&...); err != nil { return nil, err }
+
+[C2] ...
+
+🟡 WARNING — Should fix (W findings)
+─────────────────────────────────────
+[W1] internal/handler/flight.go:34
+     Rule: context-missing
+     Description: Function fetchFlightData() performs HTTP I/O but does not accept context.Context.
+     Fix: Add ctx context.Context as first parameter; pass to http.NewRequestWithContext().
+
+🔵 INFO — Consider (I findings)
+────────────────────────────────
+[I1] internal/model/passenger.go:12
+     Rule: java-migration-smell
+     Description: Struct named PassengerManager — Java naming pattern. In Go, prefer domain
+                  nouns (PassengerService or plain functions in a passengers package).
+     Fix: Rename to PassengerService or refactor to package-level functions.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+History saved to .go-review-history.json
+Run /go-review again after fixing to verify no new regressions.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## STEP 3B — FULL AUDIT WITH AUTO-FIX (if user chose B)
+
+### 3B.1 — Discover all Go files
+
+Enumerate all `.go` files under the target path, excluding:
+- `vendor/`
+- `_test.go` files (reviewed separately)
+- `generated/` or `gen/` directories
+- `.pb.go` files (protobuf generated)
+
+Print: `📂 Found N Go source files for full audit.`
+
+### 3B.2 — Create isolated git worktree
+
+IMPORTANT: NEVER modify files in the original repository. All fixes happen in an isolated worktree.
+
+Run:
+```bash
+WORKTREE_PATH=$(mktemp -d /tmp/go-review-XXXXXX)
+git worktree add "$WORKTREE_PATH" HEAD
+```
+
+Print:
+```
+🌿 Created isolated worktree at: /tmp/go-review-abc123
+   (Your working tree is untouched)
+```
+
+### 3B.3 — Run enabled tools in the worktree
+
+Run each enabled tool against the worktree path (substitute `$WORKTREE_PATH` for the original path in all commands).
+
+Collect ALL findings across all tools, deduplicating by (file, line, rule).
+
+### 3B.4 — Apply auto-fixes in worktree
+
+For each CRITICAL and WARNING finding where a safe, mechanical fix exists:
+- Apply the fix to the file inside `$WORKTREE_PATH` (NOT the original)
+- Track which fixes were applied
+
+Safe mechanical fixes include:
+- Adding `if err != nil { return ..., err }` after unchecked error returns
+- Adding `context.Context` parameter to function signatures (where the call chain is clear)
+- Fixing import grouping (stdlib, external, internal — separated by blank lines)
+- Removing unused imports
+- Fixing `gofmt` formatting issues
+
+Do NOT auto-fix:
+- Logic errors or architectural issues (report only)
+- Anything requiring business context
+- Renaming exported types (breaking change)
+
+### 3B.5 — Generate diff
+
+```bash
+git -C "$WORKTREE_PATH" diff HEAD
+```
+
+Store the diff.
+
+### 3B.6 — Write full report to .go-review.md
+
+Write to `.go-review.md` in the project root (outside the worktree):
+
+```markdown
+# Go Code Review Report
+
+**Generated:** <ISO timestamp>
+**Target:** <target path>
+**Mode:** Full Audit
+**Worktree:** <worktree path>
+**Tools:** golangci-lint, Claude analysis
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files reviewed | N |
+| Total findings | X |
+| Auto-fixed | F |
+| Critical | C |
+| Warning | W |
+| Info | I |
+
+## 🔴 CRITICAL — Must fix before merge
+
+### [C1] `internal/service/booking.go:87`
+**Rule:** `error-unchecked`
+**Tool:** golangci-lint / errcheck
+**Description:** Return value of db.QueryRowContext() ignored.
+**Suggested fix:**
+```go
+row := db.QueryRowContext(ctx, query, args...)
+if err := row.Scan(&dest); err != nil {
+    return nil, fmt.Errorf("scan booking: %w", err)
+}
+```
+**Auto-fixed:** ✅ Yes
+
+---
+
+## 🟡 WARNING — Should fix
+
+...
+
+## 🔵 INFO — Consider
+
+...
+
+## Auto-fix Diff
+
+```diff
+<diff output here>
+```
+```
+
+Print: `📄 Full report written to .go-review.md`
+
+### 3B.7 — Ask to apply fixes
+
+```
+Found F auto-fixable issues in the isolated worktree.
+
+Apply these fixes to your working tree? (y/N):
+```
+
+If user says `y` or `yes`:
+```bash
+git -C "$WORKTREE_PATH" diff HEAD | git apply --index
+```
+Print: `✅ Fixes applied to working tree. Review with: git diff`
+
+If user says `n` or anything else:
+Print:
+```
+ℹ️  Fixes NOT applied. To apply manually:
+    git -C <worktree_path> diff HEAD | git apply --index
+
+    Or inspect the worktree directly:
+    cd <worktree_path>
+```
+
+### 3B.8 — Cleanup worktree
+
+```bash
+git worktree remove "$WORKTREE_PATH" --force
+```
+
+Print: `🧹 Worktree cleaned up.`
+
+---
+
+## SEVERITY CLASSIFICATION GUIDE
+
+Use these rules when Claude is assessing code (Claude-only mode or supplementing linters):
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | Data loss risk, security vulnerability, goroutine leak, unhandled error on I/O path, nil dereference risk, race condition |
+| WARNING  | Missing context propagation, Java migration smell that affects maintainability, incorrect error wrapping, missing defer for cleanup |
+| INFO     | Naming conventions, struct layout, minor style, documentation gaps, test coverage suggestions |
+
+---
+
+## GO STANDARDS REFERENCE (Garuda Airlines — Java→Go Migration)
+
+Apply these project-specific rules on top of standard Go idioms:
+
+1. **Module path**: All internal imports use `github.com/zokypesch/go-ga-lib/...`
+2. **Error wrapping**: Always use `fmt.Errorf("operation: %w", err)` — never `errors.New()` on a wrapped error
+3. **HTTP handlers**: Must accept `context.Context`; use `r.Context()` from the request
+4. **Database**: All DB calls must use context-aware variants (`QueryContext`, `ExecContext`, etc.)
+5. **Logging**: Use structured logging (slog or zerolog) — no `fmt.Println` in production paths
+6. **Java patterns to eliminate**:
+   - No `getter`/`setter` methods — use direct field access or functional options
+   - No `*Exception` type names — use `*Error` or descriptive names
+   - No `Abstract*` prefixes — use interfaces
+   - No `*Manager`, `*Factory`, `*Helper` as primary type names
+   - No checked-exception-style error chaining through empty interfaces
+7. **Concurrency**: Every `go func()` must be tracked (WaitGroup, errgroup, or channel receive)
+8. **Tests**: Table-driven tests preferred; test files must be in same package (not `_test` external unless testing exported API)

package/plugins/go-reviewer/mcp-servers/go-reviewer-mcp/README.md

@@ -0,0 +1,236 @@
+# go-reviewer-mcp
+
+A thin MCP (Model Context Protocol) shim server that runs external Go analysis binaries
+(`golangci-lint`, `gopls`, `semgrep`) and returns structured findings to Claude.
+
+## What This Server Does
+
+Claude cannot directly execute shell commands during a review session. This MCP server
+bridges that gap: it exposes three tools over the MCP JSON-RPC protocol (stdio transport),
+each of which shells out to an external binary, parses its output, and returns a normalized
+`[]Finding` array that Claude can reason over.
+
+**Graceful degradation is a first-class concern.** If a binary is not on PATH, the tool
+returns `{"skipped": true, "reason": "binary not found"}` instead of an error. Claude
+interprets this response and silently falls back to its own analysis. The server never
+crashes due to a missing binary.
+
+## Architecture
+
+```
+Claude (go-review command)
+        │  JSON-RPC over stdio
+        ▼
+  go-reviewer-mcp  (this server)
+        │
+        ├── run_golangci_lint  →  golangci-lint (subprocess)
+        ├── run_gopls_check    →  gopls          (subprocess)
+        └── run_semgrep        →  semgrep        (subprocess)
+```
+
+## Prerequisites
+
+The server itself requires only Go 1.23+. External binaries are optional:
+
+| Tool | Install command | Notes |
+|------|----------------|-------|
+| `golangci-lint` | `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` | Comprehensive meta-linter |
+| `gopls` | `go install golang.org/x/tools/gopls@latest` | Type-aware language server |
+| `semgrep` | `pip install semgrep` or `brew install semgrep` | Pattern-based scanner |
+
+Missing binaries are silently skipped — install only what you need.
+
+## Build
+
+```bash
+cd mcp-servers/go-reviewer-mcp
+go build -o go-reviewer-mcp ./...
+```
+
+On Windows:
+```powershell
+go build -o go-reviewer-mcp.exe ./...
+```
+
+## Register in ~/.claude.json
+
+Add the server to your Claude configuration file (`~/.claude.json` on macOS/Linux,
+`%USERPROFILE%\.claude.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "go-reviewer": {
+      "command": "/absolute/path/to/go-reviewer-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+On Windows, use forward slashes or escaped backslashes:
+```json
+{
+  "mcpServers": {
+    "go-reviewer": {
+      "command": "C:/Users/yourname/.claude/mcp/go-reviewer-mcp.exe",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+### Recommended install location
+
+```bash
+# macOS / Linux
+mkdir -p ~/.claude/mcp
+cp go-reviewer-mcp ~/.claude/mcp/go-reviewer-mcp
+chmod +x ~/.claude/mcp/go-reviewer-mcp
+
+# Windows (PowerShell)
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\mcp"
+Copy-Item go-reviewer-mcp.exe "$env:USERPROFILE\.claude\mcp\go-reviewer-mcp.exe"
+```
+
+## Available MCP Tools
+
+### `run_golangci_lint`
+
+Runs `golangci-lint run --out-format json` on the given path.
+
+**Input:**
+```json
+{ "path": "/absolute/path/to/go/package/or/file" }
+```
+
+**Output (success):**
+```json
+{
+  "skipped": false,
+  "findings": [
+    {
+      "File": "internal/service/booking.go",
+      "Line": 87,
+      "Rule": "errcheck",
+      "Severity": "CRITICAL",
+      "Message": "Error return value of `db.QueryRowContext` is not checked"
+    }
+  ]
+}
+```
+
+**Output (binary missing):**
+```json
+{ "skipped": true, "reason": "binary not found: golangci-lint" }
+```
+
+---
+
+### `run_gopls_check`
+
+Runs `gopls check` on the given path for type-aware diagnostics.
+
+**Input:**
+```json
+{ "path": "/absolute/path/to/go/file/or/directory" }
+```
+
+**Output (success):**
+```json
+{
+  "skipped": false,
+  "findings": [
+    {
+      "File": "internal/handler/flight.go",
+      "Line": 34,
+      "Rule": "gopls/unused-variable",
+      "Severity": "WARNING",
+      "Message": "result 'resp' is not used"
+    }
+  ]
+}
+```
+
+---
+
+### `run_semgrep`
+
+Runs `semgrep --config <rules> --json` on the given path.
+
+**Input:**
+```json
+{
+  "path": "/absolute/path/to/scan",
+  "rules": "p/golang"
+}
+```
+
+Default `rules` value is `"p/golang"` if omitted.
+
+**Output (success):**
+```json
+{
+  "skipped": false,
+  "findings": [
+    {
+      "File": "internal/util/crypto.go",
+      "Line": 12,
+      "Rule": "go.lang.security.audit.crypto.use_of_weak_crypto.use-of-md5",
+      "Severity": "WARNING",
+      "Message": "Use of weak cryptographic primitive MD5"
+    }
+  ]
+}
+```
+
+## Graceful Degradation
+
+If a binary is not found on PATH, each tool returns:
+```json
+{ "skipped": true, "reason": "binary not found: <tool-name>" }
+```
+
+The server:
+- Never panics or exits non-zero due to a missing binary
+- Returns a valid JSON-RPC response in all cases
+- Logs warnings to stderr (not stdout, which is reserved for JSON-RPC)
+- Continues serving other tool calls after any single failure
+
+## Severity Mapping
+
+| Source tool | Source severity | Mapped to |
+|-------------|----------------|-----------|
+| golangci-lint | `error` | `CRITICAL` |
+| golangci-lint | `warning` | `WARNING` |
+| golangci-lint | `info` / other | `INFO` |
+| gopls | diagnostic | `WARNING` |
+| semgrep | `ERROR` | `CRITICAL` |
+| semgrep | `WARNING` | `WARNING` |
+| semgrep | `INFO` | `INFO` |
+
+## Troubleshooting
+
+**Server not starting:** Check that the binary is executable and the path in `~/.claude.json` is absolute.
+
+**All tools skipped:** Run `which golangci-lint` (or `where golangci-lint` on Windows) to verify binaries are on PATH. The server inherits the PATH from Claude's process, which may differ from your shell's PATH. Set `env.PATH` in the MCP server config if needed:
+```json
+{
+  "mcpServers": {
+    "go-reviewer": {
+      "command": "...",
+      "env": {
+        "PATH": "/usr/local/go/bin:/home/yourname/go/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+**golangci-lint times out:** For large codebases, increase the timeout:
+```json
+{ "args": ["--timeout-seconds", "120"] }
+```
+(The server passes extra args to the binary — not yet implemented; file an issue.)