@aaronshaf/ger 1.2.11 → 2.0.0

package/docs/adr/0016-flexible-change-identifiers.md

@@ -0,0 +1,94 @@
+# ADR 0016: Flexible Change Identifiers
+
+## Status
+
+Accepted
+
+## Context
+
+Gerrit changes can be identified by numeric ID (12345) or Change-ID (I1234567890abcdef...). Users may have either and shouldn't need to convert.
+
+## Decision
+
+Accept both numeric change IDs and full Change-IDs in all commands.
+
+## Rationale
+
+- **User convenience**: No mental mapping required
+- **Copy-paste friendly**: Works with whatever user has
+- **Gerrit API compatible**: API accepts both formats
+- **Auto-detection**: Can detect from HEAD commit
+
+## Identifier Formats
+
+| Format | Example | Regex |
+|--------|---------|-------|
+| Numeric | `12345` | `/^\d+$/` |
+| Change-ID | `If5a3ae8cb5a107e187447802358417f311d0c4b1` | `/^I[0-9a-f]{40}$/` |
+| Full triplet | `project~branch~Change-Id` | Complex |
+
+## Consequences
+
+### Positive
+- Works with URLs, commits, or manual entry
+- No conversion needed
+- Matches Gerrit web UI behavior
+
+### Negative
+- Validation logic in every command
+- API may need to handle both
+- Error messages need to cover both formats
+
+## Implementation
+
+```typescript
+// src/utils/change-id.ts
+export const isChangeNumber = (id: string): boolean =>
+  /^\d+$/.test(id)
+
+export const isChangeId = (id: string): boolean =>
+  /^I[0-9a-f]{40}$/i.test(id)
+
+export const normalizeChangeIdentifier = (input: string): string => {
+  // Already valid
+  if (isChangeNumber(input) || isChangeId(input)) {
+    return input
+  }
+
+  // Try to extract from URL
+  const urlMatch = input.match(/\/c\/[^/]+\/\+\/(\d+)/)
+  if (urlMatch) return urlMatch[1]
+
+  // Try to extract Change-ID from text
+  const cidMatch = input.match(/(I[0-9a-f]{40})/i)
+  if (cidMatch) return cidMatch[1]
+
+  throw new Error(`Invalid change identifier: ${input}`)
+}
+```
+
+## Auto-Detection from Git
+
+```typescript
+export const detectChangeFromHead = async (): Promise<string | null> => {
+  try {
+    const { stdout } = await runGit(['log', '-1', '--format=%b'])
+    const match = stdout.match(/Change-Id: (I[0-9a-f]{40})/i)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+```
+
+## Command Usage
+
+```bash
+# All equivalent
+ger show 12345
+ger show If5a3ae8cb5a107e187447802358417f311d0c4b1
+ger show https://gerrit.example.com/c/project/+/12345
+
+# Auto-detect from current commit
+ger show  # Uses Change-ID from HEAD
+```

package/docs/adr/0017-git-worktree-support.md

@@ -0,0 +1,102 @@
+# ADR 0017: Git Worktree Support
+
+## Status
+
+Accepted
+
+## Context
+
+Git worktrees allow multiple working directories for a single repository. Many developers use worktrees for parallel work on multiple changes.
+
+## Decision
+
+Fully support git worktrees in all git-related operations.
+
+## Rationale
+
+- **Common workflow**: Worktrees are popular for code review
+- **Parallel development**: Work on multiple changes simultaneously
+- **Clean separation**: Each worktree is isolated
+
+## Worktree Challenges
+
+1. `.git` is a file pointing to main repo, not a directory
+2. Hooks live in main repo's `.git/hooks`, not worktree
+3. `git rev-parse` behaves differently in worktrees
+4. Branch tracking differs between worktrees
+
+## Consequences
+
+### Positive
+- Works for developers using worktrees
+- No special configuration needed
+- Automatic detection of worktree context
+
+### Negative
+- More complex git detection logic
+- Hook installation must find main repo
+- Path resolution is more complex
+
+## Implementation
+
+```typescript
+// src/services/git-worktree.ts
+export const isWorktree = async (): Promise<boolean> => {
+  const gitDir = await runGit(['rev-parse', '--git-dir'])
+  const gitFile = Bun.file(path.join(process.cwd(), '.git'))
+
+  // In worktree, .git is a file, not directory
+  return await gitFile.exists() && !(await gitFile.stat()).isDirectory()
+}
+
+export const getMainGitDir = async (): Promise<string> => {
+  // Returns the main repo's .git directory, even in worktree
+  const { stdout } = await runGit(['rev-parse', '--git-common-dir'])
+  return path.resolve(stdout.trim())
+}
+
+export const getHooksDir = async (): Promise<string> => {
+  const mainGitDir = await getMainGitDir()
+  return path.join(mainGitDir, 'hooks')
+}
+```
+
+## Hook Installation
+
+```typescript
+// Install hook in main repo, not worktree
+export const installCommitHook = async (): Promise<void> => {
+  const hooksDir = await getHooksDir()
+  const hookPath = path.join(hooksDir, 'commit-msg')
+
+  // Check if already installed
+  if (await Bun.file(hookPath).exists()) {
+    return
+  }
+
+  // Download and install Gerrit hook
+  const hookContent = await fetchGerritHook()
+  await Bun.write(hookPath, hookContent, { mode: 0o755 })
+}
+```
+
+## Worktree Creation
+
+```typescript
+// ger checkout creates worktree for change review
+export const createReviewWorktree = async (changeId: string): Promise<string> => {
+  const worktreePath = `../review-${changeId}`
+  await runGit(['worktree', 'add', worktreePath])
+  return path.resolve(worktreePath)
+}
+```
+
+## Path Resolution
+
+```typescript
+// Always resolve to absolute paths
+export const resolveGitPath = async (relativePath: string): Promise<string> => {
+  const toplevel = await runGit(['rev-parse', '--show-toplevel'])
+  return path.resolve(toplevel.trim(), relativePath)
+}
+```

package/docs/adr/0018-auto-install-commit-hook.md

@@ -0,0 +1,103 @@
+# ADR 0018: Auto-Install Gerrit Commit-msg Hook
+
+## Status
+
+Accepted
+
+## Context
+
+Gerrit requires a Change-Id footer in commit messages. This is typically added by a commit-msg hook that must be installed manually.
+
+## Decision
+
+Auto-install the Gerrit commit-msg hook when pushing if not present.
+
+## Rationale
+
+- **Convenience**: Users don't need manual setup
+- **Error prevention**: Avoid "missing Change-Id" rejections
+- **Standard practice**: Same hook Gerrit provides
+- **Idempotent**: Safe to run multiple times
+
+## Consequences
+
+### Positive
+- Just works out of the box
+- No manual hook installation
+- Consistent Change-Id format
+- Reduces onboarding friction
+
+### Negative
+- Modifies user's git hooks
+- Hook download requires network
+- Must handle worktrees correctly
+
+## Implementation
+
+```typescript
+// src/services/commit-hook.ts
+export const ensureCommitHook = async (gerritHost: string): Promise<void> => {
+  const hooksDir = await getHooksDir()
+  const hookPath = path.join(hooksDir, 'commit-msg')
+
+  // Check if hook exists and is executable
+  try {
+    const stat = await Bun.file(hookPath).stat()
+    if (stat.mode & 0o111) {
+      return // Already installed and executable
+    }
+  } catch {
+    // Hook doesn't exist, continue to install
+  }
+
+  // Download from Gerrit
+  const hookUrl = `${gerritHost}/tools/hooks/commit-msg`
+  const response = await fetch(hookUrl)
+
+  if (!response.ok) {
+    throw new Error(`Failed to download commit-msg hook: ${response.status}`)
+  }
+
+  const hookContent = await response.text()
+
+  // Write with executable permissions
+  await Bun.write(hookPath, hookContent, { mode: 0o755 })
+
+  console.log(`Installed commit-msg hook to ${hookPath}`)
+}
+```
+
+## Hook Behavior
+
+The Gerrit commit-msg hook:
+1. Checks if Change-Id already exists in message
+2. If not, generates a unique Change-Id
+3. Appends `Change-Id: I...` to commit message
+4. Change-Id is SHA-1 based on tree, parent, author, committer
+
+## When to Install
+
+```typescript
+// Install before push operations
+export const pushCommand = (options: PushOptions) =>
+  Effect.gen(function* () {
+    const config = yield* ConfigService
+
+    // Ensure hook is installed before push
+    yield* Effect.tryPromise(() => ensureCommitHook(config.host))
+
+    // Proceed with push
+    yield* performPush(options)
+  })
+```
+
+## Manual Override
+
+Users can skip auto-install:
+```bash
+# Environment variable
+GERRIT_SKIP_HOOK=1 ger push
+
+# Or install their own hook
+# (ger won't overwrite existing executable hooks)
+```

package/docs/adr/0019-sdk-package-exports.md

@@ -0,0 +1,95 @@
+# ADR 0019: SDK Package Exports
+
+## Status
+
+Accepted
+
+## Context
+
+Beyond CLI usage, developers may want to use ger programmatically in their own tools, scripts, or automation.
+
+## Decision
+
+Export SDK modules for programmatic usage via package.json exports.
+
+## Rationale
+
+- **Reusability**: Build custom tools on top of ger
+- **Testing**: Import specific modules in tests
+- **Automation**: Script Gerrit operations
+- **Type safety**: Full TypeScript types included
+
+## Export Structure
+
+```json
+// package.json
+{
+  "name": "@aaronshaf/ger",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api/gerrit": "./src/api/gerrit.ts",
+    "./services/config": "./src/services/config.ts",
+    "./schemas/gerrit": "./src/schemas/gerrit.ts",
+    "./utils": "./src/utils/index.ts"
+  }
+}
+```
+
+## Consequences
+
+### Positive
+- Build custom integrations
+- Reuse validated schemas
+- Access type-safe API client
+- Import only what you need
+
+### Negative
+- More surface area to maintain
+- Breaking changes affect SDK users
+- Documentation burden
+
+## Usage Examples
+
+```typescript
+// Import API service
+import { GerritApiService, GerritApiServiceLive } from '@aaronshaf/ger'
+import { Effect } from 'effect'
+
+// Custom automation
+const myScript = Effect.gen(function* () {
+  const api = yield* GerritApiService
+  const changes = yield* api.listChanges('owner:self status:open')
+
+  for (const change of changes) {
+    console.log(`${change._number}: ${change.subject}`)
+  }
+})
+
+Effect.runPromise(
+  myScript.pipe(Effect.provide(GerritApiServiceLive))
+)
+```
+
+```typescript
+// Import schemas for validation
+import { ChangeInfo } from '@aaronshaf/ger/schemas/gerrit'
+import { Schema } from '@effect/schema'
+
+const validateChange = (data: unknown) =>
+  Schema.decodeUnknownSync(ChangeInfo)(data)
+```
+
+```typescript
+// Import utilities
+import { normalizeChangeIdentifier, extractChangeIdFromCommitMessage } from '@aaronshaf/ger/utils'
+
+const changeId = normalizeChangeIdentifier('https://gerrit.example.com/c/project/+/12345')
+```
+
+## API Documentation
+
+See EXAMPLES.md for detailed SDK usage patterns:
+- Effect-based API calls
+- Config service setup
+- Custom change processing
+- Batch operations

package/docs/adr/0020-code-coverage-enforcement.md

@@ -0,0 +1,105 @@
+# ADR 0020: Code Coverage Enforcement
+
+## Status
+
+Accepted
+
+## Context
+
+We need to ensure adequate test coverage without slowing down development. Options:
+
+1. **CI-only enforcement** - Check in pipeline, local commits unrestricted
+2. **Pre-commit enforcement** - Block commits below threshold
+3. **Pre-push enforcement** - Block push if coverage drops
+4. **Advisory only** - Report but don't enforce
+
+## Decision
+
+Enforce 80% code coverage threshold in pre-commit and pre-push hooks.
+
+## Rationale
+
+- **Quality gate**: Prevents untested code from entering codebase
+- **Fast feedback**: Know immediately if coverage dropped
+- **Prevents drift**: Coverage doesn't slowly degrade
+- **Meaningful threshold**: 80% balances coverage with practicality
+
+## Thresholds
+
+| Metric | Threshold |
+|--------|-----------|
+| Lines | 80% |
+| Functions | 80% |
+| Statements | 80% |
+| Branches | 80% |
+
+## Consequences
+
+### Positive
+- Consistent test coverage across codebase
+- Bugs caught before production
+- Documentation of behavior via tests
+- Confidence in refactoring
+
+### Negative
+- May slow commits when adding new code
+- Some code is hard to test (UI, edge cases)
+- Can encourage gaming metrics vs quality tests
+
+## Exclusions
+
+Excluded from coverage calculations:
+- `tmp/` - Temporary files
+- `scripts/` - Build scripts
+- `*.d.ts` - Type declarations
+- Test files themselves
+
+## Configuration
+
+```toml
+# bunfig.toml
+[test]
+coverage = true
+coverageThreshold = { line = 80, function = 80, statement = 80, branch = 80 }
+coverageSkipTestFiles = true
+```
+
+## Enforcement Script
+
+```typescript
+// scripts/check-coverage.ts
+import { $ } from 'bun'
+
+const result = await $`bun test --coverage`.json()
+
+const thresholds = {
+  line: 80,
+  function: 80,
+  statement: 80,
+  branch: 80,
+}
+
+let failed = false
+
+for (const [metric, threshold] of Object.entries(thresholds)) {
+  const actual = result.coverage[metric]
+  if (actual < threshold) {
+    console.error(`${metric} coverage ${actual}% < ${threshold}%`)
+    failed = true
+  }
+}
+
+if (failed) {
+  process.exit(1)
+}
+```
+
+## Bypassing (Emergency Only)
+
+```bash
+# Skip hooks entirely (discouraged)
+git commit --no-verify -m "Emergency fix"
+
+# Add to exclusion list temporarily
+# (requires PR review)
+```

package/docs/adr/0021-typescript-isolated-declarations.md

@@ -0,0 +1,83 @@
+# ADR 0021: TypeScript Isolated Declarations
+
+## Status
+
+Accepted
+
+## Context
+
+TypeScript 5.5+ introduced `isolatedDeclarations` which requires explicit return type annotations on exported functions. This improves declaration file generation.
+
+## Decision
+
+Enable `isolatedDeclarations: true` in tsconfig.json.
+
+## Rationale
+
+- **Faster builds**: Declaration files generated without full type-check
+- **Explicit types**: Forces documentation of public API
+- **Parallel builds**: Enables parallel .d.ts generation
+- **Better tooling**: IDEs understand types without inference
+
+## Consequences
+
+### Positive
+- Declaration files are accurate and fast to generate
+- Public API is self-documenting
+- Catches missing type annotations
+- Better for SDK consumers
+
+### Negative
+- More verbose code (explicit return types)
+- Learning curve for developers
+- Some Effect patterns require workarounds
+
+## Configuration
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+    "declaration": true,
+    "strict": true,
+    "noEmit": true
+  }
+}
+```
+
+## Code Changes Required
+
+```typescript
+// Before (inferred return type)
+export const getChange = (id: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    return yield* api.getChange(id)
+  })
+
+// After (explicit return type)
+export const getChange = (id: string): Effect.Effect<ChangeInfo, ApiError, GerritApiService> =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    return yield* api.getChange(id)
+  })
+```
+
+## Common Patterns
+
+```typescript
+// Simple functions - explicit return
+export const add = (a: number, b: number): number => a + b
+
+// Effect functions - full type signature
+export const fetchData = (): Effect.Effect<Data, ApiError, ApiService> =>
+  Effect.gen(function* () { ... })
+
+// Constants - as const for literal types
+export const STATUS_OPTIONS = ['NEW', 'MERGED', 'ABANDONED'] as const
+```
+
+## Enforcement
+
+TypeScript compiler enforces this automatically when enabled. Build fails if any exported function lacks explicit return type annotation.

package/docs/adr/0022-biome-oxlint-tooling.md

@@ -0,0 +1,124 @@
+# ADR 0022: Biome Formatter + oxlint Linter
+
+## Status
+
+Accepted
+
+## Context
+
+We need code formatting and linting tools. Options considered:
+
+1. **ESLint + Prettier** - Standard combo, highly configurable
+2. **Biome** - Fast, Rust-based formatter and linter
+3. **oxlint** - Ultra-fast Rust-based linter
+4. **deno fmt/lint** - Built into Deno, not Bun
+
+## Decision
+
+Use Biome for formatting and oxlint for linting.
+
+## Rationale
+
+- **Speed**: Both are Rust-based, extremely fast
+- **Compatibility**: Work well with Bun
+- **Simple config**: Less configuration than ESLint
+- **Modern defaults**: Sensible rules out of the box
+
+## Tool Responsibilities
+
+| Tool | Purpose |
+|------|---------|
+| Biome | Code formatting (spacing, line breaks, quotes) |
+| oxlint | Static analysis (errors, best practices) |
+
+## Consequences
+
+### Positive
+- Sub-second formatting on entire codebase
+- Near-instant linting
+- Fewer dependencies than ESLint ecosystem
+- Works in pre-commit without slowdown
+
+### Negative
+- Less mature than ESLint (fewer rules)
+- Smaller community
+- May miss some ESLint-specific rules
+
+## Biome Configuration
+
+```json
+// biome.json
+{
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "tab",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": false
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingComma": "all",
+      "semicolons": "asNeeded"
+    }
+  }
+}
+```
+
+## oxlint Configuration
+
+```json
+// .oxlintrc.json
+{
+  "rules": {
+    "no-unused-vars": "error",
+    "no-console": "warn",
+    "prefer-const": "error"
+  },
+  "ignorePatterns": [
+    "node_modules",
+    "tmp",
+    "*.d.ts"
+  ]
+}
+```
+
+## lint-staged Integration
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "*.ts": [
+      "biome format --write",
+      "oxlint"
+    ]
+  }
+}
+```
+
+## Scripts
+
+```json
+// package.json
+{
+  "scripts": {
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "oxlint .",
+    "check:all": "bun run format:check && bun run lint && bun run typecheck"
+  }
+}
+```
+
+## Performance Comparison
+
+| Tool | Time (100 files) |
+|------|------------------|
+| Prettier | ~2s |
+| Biome | ~50ms |
+| ESLint | ~5s |
+| oxlint | ~100ms |