# Project Overview

Git commit message generator using AI via LiteLLM. Generates conventional commit messages with concise summaries (≤72 chars) and structured detail points from git diffs.

**Three operational modes:**
1. **Standard mode**: Single commit generation from staged/unstaged changes
2. **Compose mode**: AI-powered splitting of large changesets into multiple atomic commits
3. **Rewrite mode**: Batch rewriting of git history to conventional format

**Two-phase generation (standard mode):**
1. Analysis phase: Extract 0-6 detail points from diff using Sonnet/Opus
2. Summary phase: Generate commit summary from details using Haiku

# Commands

**Build:**
```bash
cargo build --release
cargo build --release --bin lgit  # Main binary only
```

**Run:**
```bash
# Standard mode
cargo run --release --bin lgit                              # Analyze & commit staged changes
cargo run --release --bin lgit -- --dry-run                 # Preview without committing
cargo run --release --bin lgit -- --mode=unstaged           # Analyze unstaged (no commit)
cargo run --release --bin lgit -- --mode=commit --target=HEAD~1  # Analyze specific commit
cargo run --release --bin lgit -- --copy                    # Copy message to clipboard
cargo run --release --bin lgit -- -m opus                   # Use Opus model
cargo run --release --bin lgit -- Fixed regression from PR #123  # Add context

# Compose mode - split large changesets into atomic commits
cargo run --release --bin lgit -- --compose                 # Execute compose
cargo run --release --bin lgit -- --compose --compose-preview  # Preview splits only
cargo run --release --bin lgit -- --compose --compose-max-commits 3  # Limit to 3 commits
cargo run --release --bin lgit -- --compose --compose-test-after-each  # Run tests after each
```

**Environment:**
- Expects LiteLLM server running at `http://localhost:4000/chat/completions`

**Testing:**
```bash
cargo test                                  # Run all unit tests
cargo test --lib                            # Library tests only
```

# Architecture

## Module Structure

**Core library** (`src/lib.rs`):
- `analysis` - Scope candidate extraction from git numstat
- `api` - OpenRouter/LiteLLM integration with function calling + retry logic
- `compose` - AI-powered commit splitting (NEW)
- `config` - Configuration loading, prompt template management
- `diff` - Smart diff truncation with priority scoring
- `error` - Error types with `thiserror`
- `git` - Git command wrappers (diff, stat, commit, history operations)
- `normalization` - Unicode normalization, commit message formatting
- `patch` - Hunk-level staging for compose mode (NEW)
- `templates` - Prompt template rendering with `tera`
- `types` - Type-safe commit types, scopes, summaries with validation
- `validation` - Commit message validation (past-tense verbs, length limits)
- `rewrite` - History rewrite orchestration

**Entry points:**
- `src/main.rs` - CLI routing to standard/compose/rewrite modes

## Core Workflows

**Standard Mode** (`src/main.rs:run_generation`):
1. `get_git_diff()` + `get_git_stat()` - Extract changes based on mode (staged/unstaged/commit)
2. `smart_truncate_diff()` - Truncate if >100KB with priority-based selection:
   - Priority: source files > config > tests > binaries > lock files
   - Preserve ALL file headers, truncate content proportionally
   - Keep context (first 15 + last 10 lines per file)
3. `extract_scope_candidates()` - Parse git numstat to identify changed modules/components
4. `generate_conventional_analysis()` - AI call with function calling schema:
   - Tool: `create_conventional_analysis`
   - Returns: `{type, scope?, body: [details], issue_refs: [...]}`
5. `generate_summary_from_analysis()` - AI call for summary generation:
   - Tool: `create_commit_summary`
   - Input: type + scope + detail points + stat
   - Returns: `{summary}` (≤72 chars)
6. `post_process_commit_message()` - Enforce capitalization, punctuation
7. `validate_commit_message()` - Check past-tense verbs, length limits
8. `git_commit()` - Create commit (unless dry-run)

**Compose Mode** (`src/compose.rs:run_compose_mode`):
1. Combine staged + unstaged diffs into single analysis
2. `analyze_for_compose()` - AI identifies logical commit groups:
   - Tool: `create_compose_analysis`
   - Returns: `{groups: [{changes: [{path, hunks}], type, scope?, rationale, dependencies}]}`
   - **CRITICAL**: Each group specifies file paths + hunk headers (e.g., `@@ -10,5 +10,7 @@`) or `["ALL"]`
3. `compute_dependency_order()` - Topological sort (Kahn's algorithm) to ensure working state
4. Display proposed splits, optionally stop (preview mode)
5. `execute_compose()` - For each group in dependency order:
   - Capture baseline diff once (against original HEAD)
   - `stage_group_changes()` - Hunk-aware staging:
     - If all hunks = `["ALL"]`: use `git add <files>`
     - Otherwise: extract specific hunks, `git apply --cached <patch>`
   - Generate commit message via standard flow
   - `git_commit()` + capture new HEAD hash
   - Optionally run tests

**Rewrite Mode** (`rewrite_history.py` + `src/rewrite.rs`):
1. `get_commit_list()` - Extract commit hashes via `git rev-list --reverse`
2. Parallel API calls to Haiku for message conversion
3. `rewrite_history()` - Rebuild history with `git commit-tree`:
   - Preserves trees, authors, dates, parent relationships
   - Updates messages only
   - Updates branch ref to new head

## Smart Truncation Strategy (`src/diff.rs`)

**Priority scoring** (higher = more important):
```rust
pub const PRIORITY_SOURCE: i32 = 100;    // .rs, .py, .js, .ts, etc.
pub const PRIORITY_CONFIG: i32 = 80;     // .toml, .yaml, .json, etc.
pub const PRIORITY_TEST: i32 = 60;       // test files
pub const PRIORITY_DOC: i32 = 40;        // .md files
pub const PRIORITY_BINARY: i32 = 20;     // images, etc.
```

**Excluded files** (never included in diff): `Cargo.lock`, `package-lock.json`, `yarn.lock`, etc.

**Truncation logic:**
1. Parse diff into `FileDiff` structs
2. Calculate total length, determine how much to trim
3. Show ALL file headers (crucial for context)
4. Distribute remaining space proportionally by priority
5. For each file: keep first 15 + last 10 lines, truncate middle
6. Annotate with `[... X lines omitted ...]`

## Hunk-Level Staging (`src/patch.rs`)

**Problem**: When multiple commit groups reference the same file, staging by whole file (`git add <file>`) commits all changes at once, leaving nothing for subsequent groups.

**Solution**: Extract specific hunks per group, apply with `git apply --cached`.

**Key functions:**
- `extract_file_diff()` - Isolate single file's diff from full diff
- `extract_hunks_for_file()` - Filter specific hunks by header matching
- `normalize_hunk_header()` - Compare hunks by line numbers (e.g., `-10,5 +10,7`)
- `create_patch_for_changes()` - Assemble multi-file patch from hunk selections
- `stage_group_changes()` - Route to `git add` (if all `["ALL"]`) or `git apply --cached` (partial)

**Important**: Baseline diff must be captured ONCE before any compose commits, so hunk headers remain stable across groups (lines 408-421 in `src/compose.rs`).

## Prompt Engineering

**Prompt versions**: V1 (default) vs V2 (behind `new_prompts` feature flag)
- Located in `prompts/analysis/` and `prompts/summary/`
- Rendered at runtime via `tera` templates
- Config setting: `analysis_prompt_variant` / `summary_prompt_variant`

**Validation retry**: Summary generation retries once on validation failure with constraint injection
- Validates: past-tense verb, no type repetition, type-file consistency heuristics
- Fallback: Uses first detail or heuristic if retry exhausted
- See `validate_summary_quality()` in `src/api/mod.rs:288-358`


## Type System (`src/types.rs`)

**Type-safe wrappers** with validation:
- `CommitType` - Validates against `[feat, fix, refactor, docs, test, chore, style, perf, build, ci, revert]`
- `Scope` - Validates lowercase alphanumeric, max 2 segments (e.g., `api/client`)
- `CommitSummary` - Enforces length limits (72 guideline, 96 soft, 128 hard), warns on uppercase/period

**Compose types**:
- `FileChange` - `{path: String, hunks: Vec<String>}` - Hunk headers or `["ALL"]`
- `ChangeGroup` - `{changes: Vec<FileChange>, commit_type, scope?, rationale, dependencies: Vec<usize>}`
- `ComposeAnalysis` - `{groups: Vec<ChangeGroup>, dependency_order: Vec<usize>}`

**Model name resolution** (`resolve_model_name()`):
- Short names: `sonnet` → `claude-sonnet-4.5`, `opus` → `claude-opus-4.1`, `haiku` → `claude-haiku-4-5`
- GPT: `gpt5` → `gpt-5`, `gpt5-mini` → `gpt-5-mini`
- Gemini: `gemini` → `gemini-2.5-pro`, `flash` → `gemini-2.5-flash`
- Pass-through for full names

## API Integration (`src/api/mod.rs`)

**Function calling schema**:
1. `create_conventional_analysis` - Detail extraction:
   ```json
   {
     "type": "feat|fix|refactor|...",
     "scope": "optional_scope",
     "body": ["detail 1.", "detail 2."],
     "issue_refs": ["#123", "#456"]
   }
   ```

2. `create_commit_summary` - Summary generation:
   ```json
   {
     "summary": "concise past-tense summary without period"
   }
   ```

3. `create_compose_analysis` - Compose grouping:
   ```json
   {
     "groups": [
       {
         "changes": [
           {"path": "src/foo.rs", "hunks": ["@@ -10,5 +10,7 @@"]},
           {"path": "src/bar.rs", "hunks": ["ALL"]}
         ],
         "type": "feat",
         "scope": "api",
         "rationale": "Added TLS support",
         "dependencies": []
       }
     ]
   }
   ```

**Retry logic** (`retry_api_call()`):
- Exponential backoff: 1s, 2s, 4s (default 3 retries)
- Retries on 5xx errors or transient failures
- Configurable: `max_retries`, `initial_backoff_ms` in config

**Fallback**: If AI calls fail, `fallback_summary()` generates heuristic summary from stat.

## Configuration (`~/.config/llm-git/config.toml`)

```toml
api_base_url = "http://localhost:4000"
analysis_model = "claude-sonnet-4.5"
summary_model = "claude-haiku-4-5-20251001"
temperature = 1.0

summary_guideline = 72        # Target length
summary_soft_limit = 96       # Triggers retry
summary_hard_limit = 128      # Absolute max

max_retries = 3
initial_backoff_ms = 1000
max_diff_length = 100000

wide_change_threshold = 0.50  # Omit scope if >50% of files changed

analysis_prompt_variant = "default"
summary_prompt_variant = "default"

exclude_old_message = false   # When true, git show omits original message
```

# Implementation Notes

**Dependencies:**
- `clap` - CLI parsing with derive macros
- `reqwest` (blocking) - HTTP client for OpenRouter API
- `serde` + `serde_json` - Serialization for function calling
- `arboard` - Clipboard support for `--copy`
- `tera` - Prompt template rendering
- `rust-embed` - Embed prompt files in binary
- `anyhow` + `thiserror` - Error handling
- `rayon` - Parallel processing in rewrite mode
- `chrono` - Timestamps for backup branches
- `parking_lot` - High-performance Mutex/RwLock (ALWAYS use over `std::sync`)

**Models:**
- Default: Sonnet 4.5 for analysis, Haiku 4.5 for summary
- Optional: Opus 4.1 via `-m opus` (more powerful, slower, expensive)
- Compose mode uses analysis model for both grouping + per-commit generation

**Validation rules:**
- Summary: ≤72 chars (guideline), ≤96 (soft limit), ≤128 (hard limit), past-tense verb, no trailing period
- Body: Past-tense verbs preferred, ends with periods
- Warns on present-tense usage but doesn't block
- Type-file consistency checks (e.g., >80% .md files but type != docs)

**Cost estimates:**
- Standard commit: ~$0.02-0.05 (Sonnet analysis + Haiku summary)
- Compose mode: ~$0.05-0.15 per group (multiple analysis + summary calls)
- Rewrite mode: ~$0.001/commit with Haiku (~$1-5 for 1000-5000 commits)

# Linting

Project uses comprehensive Clippy linting (see `Cargo.toml`):
- `all`, `pedantic`, `style`, `perf`, `correctness`, `suspicious`, `nursery` enabled
- `allow_attributes_without_reason = "warn"` - MUST provide reason for `#[allow(...)]`
- Many pragmatic allows for builder patterns, numeric casts, code organization
- **CRITICAL**: Always use `parking_lot::{Mutex, RwLock}` instead of `std::sync`

# Common Issues

**Compose mode empty commits**: Ensure AI returns hunk headers from diff, not fabricated. If model struggles, file may need `hunks: ["ALL"]` for entire file.

**Hunk extraction fails**: Check `extract_file_diff()` correctly parses `diff --git a/... b/...` headers. File path matching is sensitive to `a/` and `b/` prefixes.

**Validation retry loops**: If summary validation fails repeatedly, check `validate_summary_quality()` constraints aren't overly strict for edge cases.

**API timeouts**: Increase `timeout` in HTTP client (currently 120s) if large diffs take longer to process.

**Prompt changes not applied**: After editing `prompts/*.md`, rebuild to re-embed templates.
