@aaronshaf/ger 1.2.11 → 2.0.0

package/docs/adr/0009-file-size-limits.md

@@ -0,0 +1,82 @@
+# ADR 0009: Enforce File Size Limits
+
+## Status
+
+Accepted
+
+## Context
+
+Large files are harder to maintain, test, and understand. We need limits to encourage modular code.
+
+## Decision
+
+Enforce file size limits in pre-commit hooks:
+- **Warning** at 500 lines
+- **Error** (block commit) at 700 lines
+
+## Rationale
+
+- **Maintainability**: Smaller files are easier to understand
+- **Single responsibility**: Large files often do too much
+- **Code review**: Easier to review smaller, focused files
+- **Testing**: Smaller modules are easier to test in isolation
+
+## Consequences
+
+### Positive
+- Encourages modular architecture
+- Easier code reviews
+- Better test coverage (smaller units)
+- Faster navigation in IDE
+
+### Negative
+- May need refactoring for legitimate large files
+- Arbitrary thresholds may not fit all cases
+- Some complex modules genuinely need more code
+
+## Exclusions
+
+The following are excluded from size checks:
+- `node_modules/`
+- `tmp/`
+- Generated files
+- Test fixture files
+
+## Implementation
+
+```typescript
+// scripts/check-file-size.ts
+import { glob } from 'glob'
+
+const WARN_THRESHOLD = 500
+const ERROR_THRESHOLD = 700
+
+const files = await glob('src/**/*.ts')
+
+for (const file of files) {
+  const content = await Bun.file(file).text()
+  const lines = content.split('\n').length
+
+  if (lines > ERROR_THRESHOLD) {
+    console.error(`ERROR: ${file} has ${lines} lines (max: ${ERROR_THRESHOLD})`)
+    process.exit(1)
+  } else if (lines > WARN_THRESHOLD) {
+    console.warn(`WARN: ${file} has ${lines} lines (consider refactoring)`)
+  }
+}
+```
+
+## Current Large Files
+
+Files approaching limits (as of v0.3.5):
+- `src/cli/commands/show.ts` (~400 lines) - display formatting
+- `src/cli/commands/comment.ts` (~300 lines) - batch processing
+- `src/cli/commands/checkout.ts` (~300 lines) - patchset handling
+
+## Refactoring Strategies
+
+When files approach limits:
+1. Extract utility functions to `src/utils/`
+2. Split formatters into separate modules
+3. Move constants to dedicated files
+4. Extract sub-commands to separate files

package/docs/adr/0010-llm-friendly-xml-output.md

@@ -0,0 +1,93 @@
+# ADR 0010: LLM-Friendly XML Output
+
+## Status
+
+Accepted
+
+## Context
+
+We want to integrate with AI tools (Claude, GPT, etc.) for automated code review and analysis. LLMs work better with structured, parseable output.
+
+## Decision
+
+Add `--xml` flag to all major commands that outputs structured XML with CDATA wrapping for special characters.
+
+## Rationale
+
+- **LLM consumption**: XML is well-understood by language models
+- **Structured data**: Clear field separation vs prose
+- **CDATA safety**: Handles special characters without escaping issues
+- **Composability**: Pipe output to AI tools directly
+- **Human readable**: XML is also readable by humans when needed
+
+## Consequences
+
+### Positive
+- AI tools can parse output reliably
+- Pipe directly to `llm`, `claude`, etc.
+- Clear data boundaries
+- No escaping ambiguity with CDATA
+
+### Negative
+- Verbose output
+- Two code paths (text and XML)
+- CDATA has its own edge cases
+
+## Implementation
+
+```typescript
+// --xml flag on commands
+program
+  .command('show [change-id]')
+  .option('--xml', 'Output as XML for LLM consumption')
+  .action((changeId, options) => {
+    if (options.xml) {
+      outputXml(change)
+    } else {
+      outputPretty(change)
+    }
+  })
+```
+
+## CDATA Sanitization
+
+```typescript
+// src/utils/shell-safety.ts
+export function sanitizeCDATA(text: string): string {
+  // CDATA cannot contain "]]>" - split and rejoin
+  return text.replace(/]]>/g, ']]]]><![CDATA[>')
+}
+
+export function wrapCDATA(text: string): string {
+  return `<![CDATA[${sanitizeCDATA(text)}]]>`
+}
+```
+
+## Example Output
+
+```xml
+<change>
+  <number>12345</number>
+  <project>canvas-lms</project>
+  <subject><![CDATA[Fix login bug with special chars <>&]]></subject>
+  <diff><![CDATA[
+--- a/file.ts
++++ b/file.ts
+@@ -1,3 +1,4 @@
++import { something } from 'somewhere'
+  ]]></diff>
+</change>
+```
+
+## Integration Examples
+
+```bash
+# Pipe to Claude for review
+ger show 12345 --xml | claude "Review this change"
+
+# Pipe to llm tool
+ger diff 12345 --xml | llm "Summarize changes"
+
+# Batch review with comment posting
+llm "Review this diff" < <(ger diff 12345 --xml) | ger comment 12345
+```

package/docs/adr/0011-ai-tool-strategy-pattern.md

@@ -0,0 +1,102 @@
+# ADR 0011: AI Tool Strategy Pattern
+
+## Status
+
+Accepted
+
+## Context
+
+We want to support AI-powered code review, but don't want to hard-code a single AI tool. Users may have different tools installed.
+
+## Decision
+
+Implement a strategy pattern for AI tools with auto-detection.
+
+## Rationale
+
+- **No vendor lock-in**: Support multiple AI tools
+- **User choice**: Users can specify preferred tool
+- **Future-proof**: Easy to add new tools
+- **Graceful fallback**: Try tools in priority order
+
+## Supported Tools
+
+| Tool | Command | Priority |
+|------|---------|----------|
+| Claude CLI | `claude` | 1 (highest) |
+| llm | `llm` | 2 |
+| opencode | `opencode` | 3 |
+| Gemini | `gemini` | 4 |
+
+## Consequences
+
+### Positive
+- Works with whatever AI tool user has
+- Easy to add new strategies
+- Configurable default via config file
+- Graceful degradation
+
+### Negative
+- Must maintain multiple integrations
+- Tool-specific output parsing
+- Version compatibility concerns
+
+## Implementation
+
+```typescript
+// src/services/review-strategy.ts
+interface ReviewStrategy {
+  name: string
+  isAvailable(): Promise<boolean>
+  executeReview(prompt: string, diff: string): Promise<string>
+}
+
+const strategies: ReviewStrategy[] = [
+  claudeStrategy,
+  llmStrategy,
+  opencodeStrategy,
+  geminiStrategy,
+]
+
+export const findAvailableStrategy = async (): Promise<ReviewStrategy | null> => {
+  for (const strategy of strategies) {
+    if (await strategy.isAvailable()) {
+      return strategy
+    }
+  }
+  return null
+}
+```
+
+## Configuration
+
+```json
+// ~/.ger/config.json
+{
+  "host": "https://gerrit.example.com",
+  "username": "user",
+  "password": "token",
+  "aiTool": "claude",        // explicit tool choice
+  "aiAutoDetect": true       // or auto-detect
+}
+```
+
+## Response Extraction
+
+AI tools may wrap responses in tags:
+
+```typescript
+const extractResponse = (output: string): string => {
+  // Try to extract from <response> tags
+  const match = output.match(/<response>([\s\S]*?)<\/response>/)
+  return match ? match[1].trim() : output.trim()
+}
+```
+
+## Multi-Stage Review
+
+The `review` command uses two stages:
+1. **Inline comments**: Line-specific feedback
+2. **Overall review**: High-level assessment
+
+Each stage uses the same strategy but different prompts from `src/prompts/`.

package/docs/adr/0012-build-status-message-parsing.md

@@ -0,0 +1,94 @@
+# ADR 0012: Build Status via Message Parsing
+
+## Status
+
+Accepted
+
+## Context
+
+We need to report CI/CD build status for changes. Gerrit doesn't have a standard build status API - different instances configure CI differently.
+
+## Decision
+
+Parse change messages for build status patterns rather than relying on specific labels or plugins.
+
+## Rationale
+
+- **Universal**: Works with any Gerrit instance
+- **No plugin dependency**: Doesn't require specific CI integration
+- **Flexible**: Patterns can be adjusted per instance
+- **Observable**: Same info visible in Gerrit UI
+
+## Detected States
+
+| State | Detection Pattern |
+|-------|-------------------|
+| `pending` | No build-related messages yet |
+| `running` | "Build Started" message found |
+| `success` | "Verified +1" after build messages |
+| `failure` | "Verified -1" after build messages |
+| `not_found` | Change doesn't exist |
+
+## Consequences
+
+### Positive
+- Works out of box with most Gerrit setups
+- No additional configuration needed
+- Same logic users apply mentally
+
+### Negative
+- Pattern matching can have false positives
+- Doesn't work with non-standard CI messages
+- Can't get detailed build logs
+
+## Implementation
+
+```typescript
+// src/cli/commands/build-status.ts
+const detectBuildState = (messages: ChangeMessage[]): BuildState => {
+  const sorted = [...messages].sort((a, b) =>
+    new Date(a.date).getTime() - new Date(b.date).getTime()
+  )
+
+  let buildStarted = false
+  let lastVerified: number | null = null
+
+  for (const msg of sorted) {
+    if (msg.message.includes('Build Started')) {
+      buildStarted = true
+    }
+    const verifiedMatch = msg.message.match(/Verified([+-]\d)/)
+    if (verifiedMatch) {
+      lastVerified = parseInt(verifiedMatch[1])
+    }
+  }
+
+  if (lastVerified === 1) return 'success'
+  if (lastVerified === -1) return 'failure'
+  if (buildStarted) return 'running'
+  return 'pending'
+}
+```
+
+## Watch Mode
+
+```bash
+# Poll until terminal state
+ger build-status 12345 --watch --interval 30 --timeout 1800
+
+# Exit codes for CI pipelines
+# 0: completed (any state, like gh run watch)
+# 1: failure (only with --exit-status)
+# 2: timeout
+# 3: API error
+```
+
+## JSON Output
+
+```json
+{
+  "changeId": "12345",
+  "state": "running",
+  "lastMessage": "Build Started: https://jenkins.example.com/job/123"
+}
+```

package/docs/adr/0013-git-subprocess-integration.md

@@ -0,0 +1,98 @@
+# ADR 0013: Git Subprocess Integration
+
+## Status
+
+Accepted
+
+## Context
+
+We need to interact with Git for checkout, push, commit-msg hooks, and detecting Change-IDs. Options considered:
+
+1. **isomorphic-git** - Pure JS Git implementation
+2. **simple-git** - Node.js Git wrapper
+3. **nodegit** - libgit2 bindings
+4. **Subprocess spawning** - Shell out to git
+
+## Decision
+
+Shell out to the `git` command via `Bun.spawn()` rather than using a library.
+
+## Rationale
+
+- **No dependency**: Git is already installed on dev machines
+- **Full feature support**: All git features available
+- **Worktree support**: Libraries often struggle with worktrees
+- **Familiar output**: Same output as manual git commands
+- **No native bindings**: Avoid node-gyp/native module issues
+
+## Consequences
+
+### Positive
+- Zero additional dependencies for Git
+- Works with any Git version
+- Full worktree support out of box
+- Same behavior as command line
+
+### Negative
+- Error handling is string parsing
+- Platform-specific edge cases
+- Subprocess overhead per call
+- Security: must sanitize inputs
+
+## Implementation
+
+```typescript
+// src/utils/git-commit.ts
+export const runGit = async (args: string[]): Promise<{ stdout: string; stderr: string }> => {
+  const proc = Bun.spawn(['git', ...args], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+
+  const stdout = await new Response(proc.stdout).text()
+  const stderr = await new Response(proc.stderr).text()
+  const exitCode = await proc.exited
+
+  if (exitCode !== 0) {
+    throw new GitError({ message: stderr.trim(), exitCode })
+  }
+
+  return { stdout: stdout.trim(), stderr: stderr.trim() }
+}
+```
+
+## Security Considerations
+
+```typescript
+// Validate ref names to prevent injection
+const isValidRefName = (ref: string): boolean => {
+  // Git ref naming rules
+  return /^[a-zA-Z0-9_\-/.]+$/.test(ref) &&
+    !ref.includes('..') &&
+    !ref.startsWith('-')
+}
+
+// Use array args, not shell string
+// GOOD: spawn(['git', 'checkout', branchName])
+// BAD:  spawn(`git checkout ${branchName}`, { shell: true })
+```
+
+## Worktree Detection
+
+```typescript
+// Handles both regular repos and worktrees
+export const getGitDir = async (): Promise<string> => {
+  const { stdout } = await runGit(['rev-parse', '--git-dir'])
+  return path.resolve(stdout)
+}
+```
+
+## Change-ID Extraction
+
+```typescript
+export const extractChangeIdFromHead = async (): Promise<string | null> => {
+  const { stdout } = await runGit(['log', '-1', '--format=%b'])
+  const match = stdout.match(/Change-Id: (I[0-9a-f]{40})/)
+  return match ? match[1] : null
+}
+```

package/docs/adr/0014-group-management-support.md

@@ -0,0 +1,95 @@
+# ADR 0014: Group Management Support
+
+## Status
+
+Accepted
+
+## Context
+
+Gerrit uses groups for access control and reviewer assignment. Large teams need to manage groups and add them as reviewers efficiently.
+
+## Decision
+
+Implement full group management commands: `groups`, `groups-show`, `groups-members`.
+
+## Rationale
+
+- **Team workflows**: Add entire teams as reviewers at once
+- **Discovery**: Find groups by name, owner, project
+- **Visibility**: See group membership without Gerrit UI
+- **Automation**: Script group-based reviewer assignment
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `groups` | List groups with filtering |
+| `groups-show <id>` | Detailed group information |
+| `groups-members <id>` | List group members |
+| `add-reviewer --group` | Add group as reviewer |
+
+## Consequences
+
+### Positive
+- Efficient team reviewer management
+- Discoverable group information
+- Scriptable group operations
+- Consistent with other ger commands
+
+### Negative
+- Additional API endpoints to maintain
+- Group permissions can be complex
+- LDAP groups may have sync delays
+
+## Implementation
+
+```typescript
+// List groups with filters
+export const listGroups = (options: GroupListOptions) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    const params = new URLSearchParams()
+
+    if (options.pattern) params.set('m', options.pattern)
+    if (options.owned) params.set('owned', '')
+    if (options.project) params.set('p', options.project)
+    if (options.user) params.set('user', options.user)
+
+    return yield* api.listGroups(params)
+  })
+```
+
+## Filtering Options
+
+```bash
+# Filter by name pattern
+ger groups --pattern "team-*"
+
+# Groups I own
+ger groups --owned
+
+# Groups with access to project
+ger groups --project canvas-lms
+
+# Groups a user belongs to
+ger groups --user john.doe
+```
+
+## Add Group as Reviewer
+
+```bash
+# Add group to change
+ger add-reviewer 12345 --group frontend-team
+
+# Add as CC instead of reviewer
+ger add-reviewer 12345 --group frontend-team --cc
+```
+
+## API Endpoints
+
+```
+GET /a/groups/                    # List groups
+GET /a/groups/{id}                # Group info
+GET /a/groups/{id}/detail         # Detailed info with members
+GET /a/groups/{id}/members        # Member list
+```

package/docs/adr/0015-batch-comment-processing.md

@@ -0,0 +1,111 @@
+# ADR 0015: Batch Comment Processing
+
+## Status
+
+Accepted
+
+## Context
+
+AI tools generate multiple inline comments at once. We need to post them efficiently rather than one-by-one.
+
+## Decision
+
+Accept JSON array input for bulk inline comments with schema validation.
+
+## Rationale
+
+- **AI integration**: AI tools output structured comment lists
+- **Efficiency**: Single API call for multiple comments
+- **Validation**: Schema ensures correct format before posting
+- **Features**: Support ranges, sides, resolution state
+
+## Comment Schema
+
+```typescript
+interface InlineComment {
+  file: string           // File path
+  line?: number          // Single line
+  range?: {              // Or line range
+    start_line: number
+    end_line: number
+    start_character?: number
+    end_character?: number
+  }
+  message: string        // Comment text
+  side?: 'PARENT' | 'REVISION'  // Which side of diff
+  unresolved?: boolean   // Mark as unresolved
+}
+```
+
+## Consequences
+
+### Positive
+- One API call for many comments
+- Full Gerrit comment features
+- Piped input from AI tools
+- Schema validation catches errors early
+
+### Negative
+- JSON format is verbose
+- Must handle malformed input gracefully
+- Range calculations can be complex
+
+## Implementation
+
+```typescript
+// src/cli/commands/comment.ts
+export const postBatchComments = (changeId: string, comments: InlineComment[]) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+
+    // Group by file
+    const byFile: Record<string, CommentInput[]> = {}
+    for (const comment of comments) {
+      const input: CommentInput = {
+        message: comment.message,
+        line: comment.line,
+        range: comment.range,
+        side: comment.side,
+        unresolved: comment.unresolved ?? true,
+      }
+      byFile[comment.file] ??= []
+      byFile[comment.file].push(input)
+    }
+
+    // Post all at once
+    yield* api.postReview(changeId, { comments: byFile })
+  })
+```
+
+## Usage Examples
+
+```bash
+# From file
+cat comments.json | ger comment 12345
+
+# From AI tool
+llm "Review this diff, output JSON comments" < diff.txt | ger comment 12345
+
+# Inline JSON
+echo '[{"file":"src/index.ts","line":42,"message":"Consider null check"}]' | ger comment 12345
+```
+
+## Validation
+
+```typescript
+const InlineCommentSchema = Schema.Struct({
+  file: Schema.String,
+  line: Schema.optional(Schema.Number),
+  range: Schema.optional(Schema.Struct({
+    start_line: Schema.Number,
+    end_line: Schema.Number,
+    start_character: Schema.optional(Schema.Number),
+    end_character: Schema.optional(Schema.Number),
+  })),
+  message: Schema.String,
+  side: Schema.optional(Schema.Literal('PARENT', 'REVISION')),
+  unresolved: Schema.optional(Schema.Boolean),
+})
+
+const CommentsArraySchema = Schema.Array(InlineCommentSchema)
+```