Skip to content

Commit 3404a3d

Browse files
SephyiSephyi
committed
style: improve table formatting in PRD for clarity and consistency
1 parent 3ee362f commit 3404a3d

1 file changed

Lines changed: 94 additions & 94 deletions

File tree

‎PRD.md‎

Lines changed: 94 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
4141

4242
### 2.1 Market Position
4343

44-
| Category | Key Players | CommitBee Advantage |
45-
|----------|------------|---------------------|
46-
| AI commit generators | opencommit (7.2K★), aicommits (8K★), aicommit2 | **Only tool with tree-sitter semantic analysis** |
47-
| Rust commit tools | rusty-commit, cocogitto, convco | Semantic analysis + AI generation (cocogitto/convco have no AI) |
48-
| IDE-integrated | GitHub Copilot, JetBrains AI | CLI-first, provider-agnostic, privacy-respecting |
44+
| Category | Key Players | CommitBee Advantage |
45+
| -------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
46+
| AI commit generators | opencommit (7.2K★), aicommits (8K★), aicommit2 | **Only tool with tree-sitter semantic analysis** |
47+
| Rust commit tools. | rusty-commit, cocogitto, convco | Semantic analysis + AI generation (cocogitto/convco have no AI) |
48+
| IDE-integrated | GitHub Copilot, JetBrains AI | CLI-first, provider-agnostic, privacy-respecting |
4949

5050
### 2.2 Unique Differentiators (No Competitor Has These)
5151

@@ -59,14 +59,14 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
5959

6060
### 2.3 Critical Gaps vs. Competitors
6161

62-
| Feature | Market Expectation | Current State |
63-
|---------|-------------------|---------------|
64-
| Cloud LLM providers (OpenAI, Anthropic) | Universal | Missing |
65-
| Git hook integration | Universal | Missing |
66-
| Shell completions | Expected for CLI tools | Missing |
67-
| Multiple message generation (pick from N) | Common (aicommits, aicommit2) | Missing |
68-
| Custom prompt/instruction files | Growing (Copilot, aicommit2) | Missing |
69-
| Unit/integration tests | Non-negotiable for quality | Zero tests |
62+
| Feature | Market Expectation | Current State |
63+
| -------------------------------------------------------------- | ----------------------------- | ------------- |
64+
| Cloud LLM providers (OpenAI, Anthropic) | Universal | Missing |
65+
| Git hook integration | Universal | Missing |
66+
| Shell completions | Expected for CLI tools | Missing |
67+
| Multiple message generation (pick from N) | Common (aicommits, aicommit2) | Missing |
68+
| Custom prompt/instruction files | Growing (Copilot, aicommit2) | Missing |
69+
| Unit/integration tests | Non-negotiable for quality. | Zero tests |
7070

7171
---
7272

@@ -78,14 +78,14 @@ The existing domain/services separation is solid. The pipeline (CLI -> Git -> An
7878

7979
#### Critical Issues
8080

81-
| Issue | Impact | Resolution |
82-
|-------|--------|------------|
83-
| Symbols extracted but never included in LLM prompt | Tree-sitter analysis is wasted computation | Include in prompt with fallback ladder |
84-
| `App::generate_commit()` is a 160-line untestable monolith | Cannot unit test any step of the pipeline | Decompose into testable methods |
85-
| No dependency injection | Services hard-wired, can't mock for tests | Trait abstractions for GitService, LlmProvider |
86-
| Synchronous `std::process::Command` in async runtime | Blocks tokio event loop on large repos | Use `tokio::process::Command` or `spawn_blocking` |
87-
| N+1 git process spawns (1 + N per file) | 50 files = 51 process spawns | Single `git diff --cached` parsed per-file |
88-
| UTF-8 panic in sanitizer (byte-index slicing) | Runtime crash on emoji/CJK in commit messages | Use `str::chars()` for safe truncation |
81+
| Issue | Impact | Resolution |
82+
| ------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
83+
| Symbols extracted but never included in LLM prompt | Tree-sitter analysis is wasted computation | Include in prompt with fallback ladder |
84+
| `App::generate_commit()` is a 160-line untestable monolith | Cannot unit test any step of the pipeline | Decompose into testable methods |
85+
| No dependency injection | Services hard-wired, can't mock for tests | Trait abstractions for GitService, LlmProvider |
86+
| Synchronous `std::process::Command` in async runtime | Blocks tokio event loop on large repos | Use `tokio::process::Command` or `spawn_blocking` |
87+
| N+1 git process spawns (1 + N per file) | 50 files = 51 process spawns | Single `git diff --cached` parsed per-file |
88+
| UTF-8 panic in sanitizer (byte-index slicing) | Runtime crash on emoji/CJK in commit messages | Use `str::chars()` for safe truncation |
8989

9090
#### Symbol Extraction Fallback Ladder
9191

@@ -100,31 +100,31 @@ Each tier produces progressively less useful context but ensures the pipeline ne
100100

101101
#### Dependency Cleanup
102102

103-
| Dependency | Action | Reason |
104-
|------------|--------|--------|
105-
| `anyhow` | **Remove** | Never imported anywhere |
106-
| `indicatif` | **Keep** (start using) | Declared but never used; needed for progress UX |
107-
| `once_cell` | **Replace** with `std::sync::LazyLock` | Stable since Rust 1.80, edition 2024 |
108-
| `async-trait` | **Replace** with native async traits | Stable in edition 2024 |
109-
| `futures` | **Replace** with `tokio-stream` `StreamExt` | Already a dependency |
110-
| `secrecy` | **Remove** until cloud providers implemented | Wraps unused API key field |
111-
| `tokio` `features=["full"]` | **Reduce** to `["rt-multi-thread", "macros", "signal", "sync"]` | Pulls unnecessary features |
103+
| Dependency | Action | Reason |
104+
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
105+
| `anyhow` | **Remove** | Never imported anywhere |
106+
| `indicatif` | **Keep** (start using) | Declared but never used; needed for progress UX |
107+
| `once_cell` | **Replace** with `std::sync::LazyLock` | Stable since Rust 1.80, edition 2024 |
108+
| `async-trait` | **Replace** with native async traits | Stable in edition 2024 |
109+
| `futures` | **Replace** with `tokio-stream` `StreamExt` | Already a dependency |
110+
| `secrecy` | **Remove** until cloud providers implemented | Wraps unused API key field |
111+
| `tokio` | **Reduce** to `["rt-multi-thread", "macros", "signal", "sync"]` | Pulls unnecessary features |
112112

113113
#### New Dependencies
114114

115-
| Dependency | Purpose | Priority |
116-
|------------|---------|----------|
117-
| `miette` | Rich diagnostic errors with help text, codes, suggestions | P0 |
118-
| `figment` | Hierarchical config (defaults < file < env < CLI) | P1 |
119-
| `tracing` + `tracing-subscriber` | Structured logging/diagnostics | P1 |
120-
| `clap_complete` | Shell completions generation | P1 |
121-
| `keyring` | Secure API key storage (macOS Keychain, etc.) | P1 |
122-
| `insta` | Snapshot testing | P0 (dev) |
123-
| `proptest` | Property-based testing | P1 (dev) |
115+
| Dependency | Purpose | Priority |
116+
| ----------------------------------- | --------------------------------------------------------- | -------- |
117+
| `miette` | Rich diagnostic errors with help text, codes, suggestions | P0 |
118+
| `figment` | Hierarchical config (defaults < file < env < CLI) | P1 |
119+
| `tracing` + `tracing-subscriber` | Structured logging/diagnostics | P1 |
120+
| `clap_complete` | Shell completions generation | P1 |
121+
| `keyring` | Secure API key storage (macOS Keychain, etc.) | P1 |
122+
| `insta` | Snapshot testing | P0 (dev) |
123+
| `proptest` | Property-based testing | P1 (dev) |
124124

125125
### 3.2 Target Architecture
126126

127-
```
127+
```bash
128128
commitbee
129129
├── src/
130130
│ ├── main.rs # Entry point (uses lib, not mod declarations)
@@ -320,11 +320,11 @@ These are bugs, panics, and missing foundations that must be fixed before any ne
320320
- **Acceptance**: Priority: CLI args > env vars > project config (`.commitbee.toml`) > user config > defaults. Error messages show which source provided which value.
321321
- **Platform-specific user config paths**:
322322

323-
| Platform | Config Path |
324-
|----------|------------|
325-
| macOS | `~/Library/Application Support/commitbee/config.toml` |
326-
| Linux | `~/.config/commitbee/config.toml` (XDG) |
327-
| Windows | `%APPDATA%\commitbee\config.toml` |
323+
| Platform | Config Path |
324+
| -------- | ----------------------------------------------------- |
325+
| macOS | `~/Library/Application Support/commitbee/config.toml` |
326+
| Linux | `~/.config/commitbee/config.toml` (XDG) |
327+
| Windows | `%APPDATA%\commitbee\config.toml` |
328328

329329
Use `dirs` crate for platform detection. Existing `~/.config/commitbee/config.toml` remains supported as a fallback on all platforms for backward compatibility.
330330

@@ -596,14 +596,14 @@ Every error must include:
596596

597597
Examples:
598598

599-
```
599+
```bash
600600
x Cannot connect to Ollama at http://localhost:11434
601601

602602
help: Is Ollama running? Start it with:
603603
ollama serve
604604
```
605605

606-
```
606+
```bash
607607
x No staged changes found
608608

609609
help: Stage your changes first:
@@ -627,7 +627,7 @@ x No staged changes found
627627

628628
### UX-004: CLI Design
629629

630-
```
630+
```bash
631631
commitbee [OPTIONS] # Generate and commit (default)
632632
commitbee --dry-run # Generate, print, don't commit
633633
commitbee --yes # Generate and auto-commit
@@ -671,14 +671,14 @@ Exact output behavior for key flags:
671671

672672
### TR-001: Unit Tests
673673

674-
| Module | Technique | Coverage Target |
675-
|--------|-----------|-----------------|
676-
| `CommitSanitizer` | Snapshot (insta) + proptest | All code paths + never-panic guarantee |
677-
| `DiffHunk::parse_from_diff` | Snapshot | Standard diffs, renames, binary, empty |
678-
| `safety::scan_for_secrets` | Unit + proptest | Each pattern + false positive tests |
679-
| `ContextBuilder` | Snapshot | Budget calculation, type inference, scope inference |
680-
| `FileCategory::from_path` | Unit | All categories, edge cases |
681-
| `CommitType` | Unit | Verify `ALL` matches enum variants |
674+
| Module | Technique | Coverage Target |
675+
| --------------------------- | --------------------------- | --------------------------------------------------- |
676+
| `CommitSanitizer` | Snapshot (insta) + proptest | All code paths + never-panic guarantee |
677+
| `DiffHunk::parse_from_diff` | Snapshot | Standard diffs, renames, binary, empty |
678+
| `safety::scan_for_secrets` | Unit + proptest | Each pattern + false positive tests |
679+
| `ContextBuilder` | Snapshot | Budget calculation, type inference, scope inference |
680+
| `FileCategory::from_path` | Unit | All categories, edge cases |
681+
| `CommitType` | Unit | Verify `ALL` matches enum variants |
682682

683683
#### Golden Semantic Fixtures
684684

@@ -694,18 +694,18 @@ These fixtures serve as regression tests for the tree-sitter analysis pipeline a
694694

695695
### TR-002: Integration Tests
696696

697-
| Scenario | Setup | Mock |
698-
|----------|-------|------|
699-
| Normal commit flow | tempfile git repo | wiremock Ollama |
700-
| Empty staging area | tempfile git repo | None |
701-
| Binary files mixed with text | tempfile git repo | wiremock Ollama |
702-
| Large diff (truncation) | tempfile git repo | wiremock Ollama |
703-
| Unicode file paths | tempfile git repo | wiremock Ollama |
704-
| LLM returns invalid JSON | tempfile git repo | wiremock Ollama |
705-
| LLM returns error mid-stream | tempfile git repo | wiremock Ollama |
706-
| Ollama not running | None | No mock (real connection refused) |
707-
| Secret detected | tempfile git repo | None |
708-
| Non-TTY mode | tempfile git repo + piped stdin | wiremock Ollama |
697+
| Scenario | Setup | Mock |
698+
| --------------------------------- | ---------------------------------- | ------------------------------------- |
699+
| Normal commit flow | tempfile git repo | wiremock Ollama |
700+
| Empty staging area | tempfile git repo | None |
701+
| Binary files mixed with text | tempfile git repo | wiremock Ollama |
702+
| Large diff (truncation) | tempfile git repo | wiremock Ollama |
703+
| Unicode file paths | tempfile git repo | wiremock Ollama |
704+
| LLM returns invalid JSON | tempfile git repo | wiremock Ollama |
705+
| LLM returns error mid-stream | tempfile git repo | wiremock Ollama |
706+
| Ollama not running | None | No mock (real connection refused) |
707+
| Secret detected | tempfile git repo | None |
708+
| Non-TTY mode | tempfile git repo + piped stdin | wiremock Ollama |
709709

710710
### TR-003: CLI Tests
711711

@@ -912,16 +912,16 @@ opt-level = "z" # or "s" — benchmark both
912912

913913
## 12. Success Metrics
914914

915-
| Metric | Target | How to Measure |
916-
|--------|--------|----------------|
917-
| Runtime panics | 0 | proptest + fuzzing, no `unwrap()` on user-facing paths |
918-
| Test coverage | > 80% on services/ | `cargo tarpaulin` |
919-
| CI green rate | > 99% | GitHub Actions dashboard |
920-
| Cold startup time | < 200ms | `hyperfine` in CI |
921-
| Binary size (default features) | < 15MB | CI artifact size tracking |
922-
| Commit message quality | > 80% "good enough" on first try | Manual evaluation on sample repos + `commitbee eval` harness |
923-
| Secret leak rate | 0 (no secrets sent to cloud LLMs) | Integration tests with known secret patterns |
924-
| MSRV | Rust 1.85 (edition 2024) | CI matrix build (stable + 1.85) |
915+
| Metric | Target | How to Measure |
916+
| ------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
917+
| Runtime panics | 0 | proptest + fuzzing, no `unwrap()` on user-facing paths |
918+
| Test coverage | > 80% on services/ | `cargo tarpaulin` |
919+
| CI green rate | > 99% | GitHub Actions dashboard |
920+
| Cold startup time | < 200ms | `hyperfine` in CI |
921+
| Binary size (default features) | < 15MB | CI artifact size tracking |
922+
| Commit message quality | > 80% "good enough" on first try | Manual evaluation on sample repos + `commitbee eval` harness |
923+
| Secret leak rate | 0 (no secrets sent to cloud LLMs) | Integration tests with known secret patterns |
924+
| MSRV | Rust 1.85 (edition 2024) | CI matrix build (stable + 1.85) |
925925

926926
---
927927

@@ -938,22 +938,22 @@ opt-level = "z" # or "s" — benchmark both
938938

939939
## Appendix A: Competitive Feature Matrix
940940

941-
| Feature | commitbee | opencommit | aicommits | aicommit2 | rusty-commit | cocogitto |
942-
|---------|-----------|------------|-----------|-----------|--------------|-----------|
943-
| **Tree-sitter AST** | **Yes** | No | No | No | No | No |
944-
| **Secret scanning** | **Yes** | No | No | No | No | No |
945-
| **Token budget** | **Yes** | No | No | No | No | N/A |
946-
| **Streaming** | **Yes** | No | No | No | No | N/A |
947-
| **Local LLM** | Yes | Yes | Yes | Yes | Yes | N/A |
948-
| **OpenAI** | Planned | Yes | Yes | Yes | Yes | N/A |
949-
| **Anthropic** | Planned | Yes | No | Yes | Yes | N/A |
950-
| **Git hooks** | Planned | Yes | Yes | No | Yes | Yes |
951-
| **Multi-generate** | Planned | Yes | Yes | No | No | No |
952-
| **Shell completions** | Planned | No | No | No | No | Yes |
953-
| **MCP server** | Planned | No | No | No | Yes | No |
954-
| **Changelog** | Future | No | No | No | No | Yes |
955-
| **Version bumping** | Future | No | No | No | No | Yes |
956-
| **Monorepo** | Future | No | No | No | No | Yes |
941+
| Feature | commitbee | opencommit | aicommits | aicommit2 | rusty-commit | cocogitto |
942+
| --------------------- | --------- | ---------- | --------- | --------- | ------------ | --------- |
943+
| **Tree-sitter AST** | **Yes** | No | No | No | No | No |
944+
| **Secret scanning** | **Yes** | No | No | No | No | No |
945+
| **Token budget** | **Yes** | No | No | No | No | N/A |
946+
| **Streaming** | **Yes** | No | No | No | No | N/A |
947+
| **Local LLM** | Yes | Yes | Yes | Yes | Yes | N/A |
948+
| **OpenAI** | Planned | Yes | Yes | Yes | Yes | N/A |
949+
| **Anthropic** | Planned | Yes | No | Yes | Yes | N/A |
950+
| **Git hooks** | Planned | Yes | Yes | No | Yes | Yes |
951+
| **Multi-generate** | Planned | Yes | Yes | No | No | No |
952+
| **Shell completions** | Planned | No | No | No | No | Yes |
953+
| **MCP server** | Planned | No | No | No | Yes | No |
954+
| **Changelog** | Future | No | No | No | No | Yes |
955+
| **Version bumping** | Future | No | No | No | No | Yes |
956+
| **Monorepo** | Future | No | No | No | No | Yes |
957957

958958
---
959959

0 commit comments

Comments
 (0)