Skip to content

Commit 2092609

Browse files
homeofehomeofe
committed
feat: initial implementation - diff reader, parser, prompt builder, CI
0 parents  commit 2092609

23 files changed

Lines changed: 5419 additions & 0 deletions

‎.ai/handoff/CONVENTIONS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# CONVENTIONS.md - commitprompt Coding Conventions
2+
3+
## Language and Style
4+
- All code, comments, and documentation in English
5+
- No em dashes anywhere - use commas, hyphens, or colons instead
6+
- TypeScript strict mode, NodeNext module resolution
7+
- Named exports from all modules (no default exports)
8+
- JSDoc comments on all exported functions
9+
10+
## Module Structure
11+
- 4 modules: diff-reader, diff-parser, prompt-builder, index (CLI)
12+
- Each module has a single responsibility
13+
- Import with `.js` extension (NodeNext ESM requirement):
14+
`import { parseDiff } from './diff-parser.js';`
15+
16+
## Testing
17+
- Jest with ts-jest/presets/default-esm
18+
- Tests in `src/__tests__/`
19+
- Test files use real fixture diffs from `src/fixtures/` via `readFileSync`
20+
- No hardcoded diff strings in tests
21+
- Describe blocks per fixture or mode, not per function
22+
23+
## Git
24+
- Conventional commits: `feat(scope): description`
25+
- No direct commits to main - use feature branches
26+
- CI must pass before merge
27+
28+
## Error Handling
29+
- User-facing errors: plain language, actionable ("Run `git add` first...")
30+
- Internal errors: include original message for debugging
31+
- Never silently swallow errors that affect output correctness
32+
33+
## Naming
34+
- changeType values: feat, fix, docs, refactor, test, chore, ci (no perf in parser)
35+
- Mode values: commit, pr, changelog
36+
- File naming: kebab-case for source files, camelCase for variables/functions

‎.ai/handoff/DASHBOARD.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# DASHBOARD.md - commitprompt Build Health
2+
3+
| Check | Status | Detail |
4+
| ------------- | --------- | ----------------------------------------------- |
5+
| TypeScript | OK | Strict mode, NodeNext modules, zero errors |
6+
| Tests | 42/42 | diff-parser (14), prompt-builder (12), integration (16) |
7+
| CI | Live | github.com/homeofe/commitprompt/actions |
8+
| npm publish | Pending | Needs human `npm login` |
9+
| E2E | Verified | src/fixtures/e2e-output.txt |
10+
11+
## Test Suite Breakdown
12+
13+
### diff-parser.test.ts (14 tests)
14+
- bugfix.diff: file detection, addition/deletion counts, isNew flag
15+
- new-feature.diff: test file detection, changeType='test'
16+
- docs-only.diff: changeType='docs', file detection, counts
17+
- multi-file.diff: CI file detection, changeType='ci', isNew flag, counts
18+
19+
### prompt-builder.test.ts (12 tests)
20+
- commit mode: header, file names, sections, order, counts, trimming
21+
- pr mode: header, file names, instructions, no-cross-contamination
22+
- changelog mode: header, file names, instructions, no-cross-contamination
23+
24+
### integration.test.ts (16 tests)
25+
- bugfix.diff -> commit: full pipeline, diff content in summary
26+
- new-feature.diff -> pr: PR structure, changeType verification
27+
- docs-only.diff -> changelog: changelog structure, changeType verification
28+
- multi-file.diff -> commit: CI file in prompt, all sections present

‎.ai/handoff/LOG.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# LOG.md - commitprompt Build History
2+
3+
## 2026-02-21 - Initial Implementation (AAHP auto)
4+
5+
### What was built
6+
- `src/diff-reader.ts`: reads staged diff via `git diff --staged` or from a file;
7+
smart-trims diffs longer than 120 lines, keeping file headers and hunk headers
8+
- `src/diff-parser.ts`: parses raw git diff into structured ParsedDiff:
9+
file paths, per-file +/- counts, isNew/isDeleted flags, total counts, changeType
10+
Heuristics for changeType: docs, test, ci, feat, refactor, fix, with sensible fallback
11+
- `src/prompt-builder.ts`: builds mode-specific prompts with 4 sections:
12+
header, changed files, diff summary (trimmed), mode instructions
13+
- `src/index.ts`: commander CLI with --mode, --diff, --staged, --context flags
14+
- 3 test suites, 42 tests total, all using real fixture diffs from failprompt
15+
- GitHub Actions CI workflow
16+
- AAHP handoff files
17+
18+
### Why
19+
commitprompt is a companion tool to failprompt (github.com/homeofe/failprompt).
20+
Where failprompt turns CI failure logs into AI prompts, commitprompt turns staged
21+
git diffs into AI prompts for commit messages, PR descriptions, and changelogs.
22+
23+
### Decisions made
24+
- Used real fixture diffs from failprompt codebase (TypeScript bugfix, test expansion,
25+
docs update, CI workflow addition) to ensure tests reflect real-world patterns
26+
- Smart diff trimming preserves file headers and hunk markers so LLMs get context
27+
even when diffs are truncated
28+
- changeType detection uses path-based heuristics (docs, test, ci keywords) before
29+
falling back to structural analysis (all-new vs deletion-heavy vs default feat)
30+
- Blank addition/deletion lines (just `+` or `-`) are counted as they represent
31+
real empty lines added/removed in the diff
32+
33+
### E2E verified
34+
Ran against a real staged change (echo to README.md), verified all 3 modes produce
35+
valid structured prompts. Output saved in src/fixtures/e2e-output.txt.

‎.ai/handoff/NEXT_ACTIONS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# NEXT_ACTIONS.md - commitprompt
2+
3+
## Priority Order
4+
5+
### 1. npm publish (MEDIUM - human required)
6+
- Run `npm login` as Emre
7+
- Run `npm publish` from project root
8+
- Verify at npmjs.com/package/commitprompt
9+
- After publish: update STATUS.md
10+
11+
### 2. --context flag enhancement (LOW)
12+
- Currently reads package.json name
13+
- Extend to read first paragraph of README.md
14+
- Include in prompt header as context block
15+
16+
### 3. ESLint setup (LOW)
17+
- Add eslint with typescript-eslint
18+
- Add `npm run lint` to CI
19+
- Enforce no-em-dash rule via custom lint rule
20+
21+
### 4. GitLab CI support (LOW)
22+
- Add `.gitlab-ci.yml` template
23+
- Mirror the GitHub Actions workflow
24+
25+
### 5. Shell autocomplete (OPTIONAL)
26+
- Add `commitprompt completion` command via commander
27+
- Support bash/zsh/fish
28+
29+
## Completed
30+
31+
- [x] Initial implementation: diff reader, parser, prompt builder, CLI
32+
- [x] 42/42 tests passing using real fixtures
33+
- [x] GitHub Actions CI live
34+
- [x] E2E test verified (output in src/fixtures/e2e-output.txt)
35+
- [x] AAHP handoff files created

‎.ai/handoff/STATUS.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# STATUS.md - commitprompt
2+
3+
Last updated: 2026-02-21
4+
5+
## Build Health
6+
7+
| Check | Status | Notes |
8+
| ------------ | --------- | ---------------------------------------------- |
9+
| `tsc` | (Verified) Clean | Strict mode, NodeNext, zero errors |
10+
| `npm test` | (Verified) 42/42 | 3 suites: diff-parser, prompt-builder, integration |
11+
| GitHub CI | (Verified) Live | `.github/workflows/ci.yml` on main |
12+
| npm publish | (Assumed) Pending | Needs `npm login` (human action) |
13+
14+
## What Exists
15+
16+
- `src/diff-reader.ts` - reads diff from git or file, smart-trims long diffs
17+
- `src/diff-parser.ts` - parses diff into structured data, detects change type
18+
- `src/prompt-builder.ts` - builds mode-specific prompts (commit, pr, changelog)
19+
- `src/index.ts` - CLI entrypoint with commander
20+
- `src/__tests__/diff-parser.test.ts` - parser tests using real fixtures
21+
- `src/__tests__/prompt-builder.test.ts` - builder tests using real fixtures
22+
- `src/__tests__/integration.test.ts` - end-to-end tests using real fixtures
23+
- `src/fixtures/*.diff` - real diffs from github.com/homeofe/failprompt
24+
- `.github/workflows/ci.yml` - GitHub Actions CI
25+
- `README.md` - installation and usage docs
26+
27+
## Verified Behaviors
28+
29+
- Reads staged diff via `git diff --staged`
30+
- Reads diff from file via `--diff path`
31+
- Outputs structured AI prompt for commit, PR, or changelog modes
32+
- Smart-trims diffs longer than 120 lines
33+
- Detects change type: feat, fix, docs, refactor, test, chore, ci
34+
- Friendly error if nothing staged
35+
36+
## Known Gaps
37+
38+
| Gap | Severity | Notes |
39+
| ----------- | -------- | ------------------------------------- |
40+
| npm publish | MEDIUM | Needs `npm login` from Emre |
41+
| --context | LOW | Flag exists, reads package.json name |
42+
| ESLint | LOW | Optional, nice to have |

‎.ai/handoff/TRUST.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# TRUST.md - commitprompt Trust Levels
2+
3+
## Trust Matrix
4+
5+
| Component | Trust Level | Basis |
6+
| ---------------------- | ----------- | ----------------------------------------- |
7+
| diff-reader.ts | (Verified) | Unit-tested implicitly via integration tests |
8+
| diff-parser.ts | (Verified) | 14 direct tests on real fixture diffs |
9+
| prompt-builder.ts | (Verified) | 12 direct tests on parsed real diffs |
10+
| index.ts (CLI) | (Verified) | E2E test on real staged change |
11+
| changeType heuristics | (Assumed) | Works on 4 fixtures; edge cases not exhaustive |
12+
| trimDiff logic | (Verified) | Tested with small maxLines in prompt-builder test |
13+
| git diff --staged read | (Verified) | E2E test confirmed real git output works |
14+
| npm publish readiness | (Assumed) | package.json publishConfig correct, not yet published |
15+
16+
## Risk Areas
17+
18+
- changeType heuristics: path-based detection can misclassify mixed-purpose changes
19+
(e.g., a refactor that also touches test files). The heuristic checks all files,
20+
so if even one non-test file is present, it won't classify as 'test'.
21+
22+
- Smart trimming: current implementation may cut through the middle of a hunk.
23+
This is acceptable as a UX tradeoff - the user can always pass `--diff` for full context.
24+
25+
- git not found: error message assumes the user knows what git is. Acceptable for
26+
a developer tool.
27+
28+
## What Has Been Tested Against Real Data
29+
30+
- All 4 fixtures from failprompt (TypeScript bugfix, test expansion, docs update, CI addition)
31+
- E2E on a real staged change to README.md
32+
- All 3 prompt modes (commit, pr, changelog)

‎.github/workflows/ci.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: ["**"]
6+
pull_request:
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Setup Node.js
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: "20"
18+
cache: "npm"
19+
20+
- name: Install dependencies
21+
run: npm ci
22+
23+
- name: Type check
24+
run: npx tsc --noEmit
25+
26+
- name: Run tests
27+
run: npm test

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
dist/
3+
*.log
4+
.env

‎README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# commitprompt
2+
3+
Turn your `git diff --staged` into a ready-to-paste AI prompt for commit messages, PR descriptions, and changelogs.
4+
5+
## Installation
6+
7+
```bash
8+
npm install -g commitprompt
9+
```
10+
11+
Or use without installing:
12+
13+
```bash
14+
npx commitprompt
15+
```
16+
17+
## Usage
18+
19+
### Commit message (default)
20+
21+
```bash
22+
git add src/my-fix.ts
23+
commitprompt
24+
# Prints a structured prompt - paste it into ChatGPT, Claude, or any LLM
25+
```
26+
27+
### PR description
28+
29+
```bash
30+
git add .
31+
commitprompt --mode pr
32+
```
33+
34+
### Changelog entry
35+
36+
```bash
37+
commitprompt --mode changelog
38+
```
39+
40+
### Read diff from a file
41+
42+
```bash
43+
commitprompt --diff path/to/change.diff
44+
commitprompt --diff path/to/change.diff --mode pr
45+
```
46+
47+
## How it works
48+
49+
1. **Reads** your staged diff (via `git diff --staged`) or a diff file
50+
2. **Parses** the diff: extracts changed files with +/- counts, detects change type (feat, fix, docs, test, ci...)
51+
3. **Builds** a structured prompt with file list, diff summary, and mode-specific instructions - ready to paste into any LLM
52+
53+
## Output example
54+
55+
```
56+
# Commit Message Request
57+
58+
## Changed Files
59+
- src/error-extractor.ts (+50 -14)
60+
61+
## Diff Summary
62+
\`\`\`diff
63+
diff --git a/src/error-extractor.ts b/src/error-extractor.ts
64+
...
65+
\`\`\`
66+
67+
## Instructions
68+
Write a conventional commit message for these changes.
69+
Format: <type>(<scope>): <description>
70+
Types: feat, fix, docs, refactor, test, chore, ci, perf
71+
Keep the subject line under 72 characters.
72+
If the change is complex, add a body paragraph explaining WHY (not WHAT).
73+
```
74+
75+
## Options
76+
77+
| Flag | Description | Default |
78+
| ---- | ----------- | ------- |
79+
| `--mode <commit\|pr\|changelog>` | Output format | `commit` |
80+
| `--diff <path>` | Read diff from file instead of git | - |
81+
| `--staged` | Explicit staged diff (same as default) | - |
82+
| `--context` | Include package.json name in output | - |
83+
84+
## AAHP case study
85+
86+
This tool was built using the [AAHP (AI-to-AI Handoff Protocol)](https://github.com/homeofe/AAHP).
87+
88+
Its sibling project [failprompt](https://github.com/homeofe/failprompt) does the same thing for CI failure logs: turn GitHub Actions errors into structured AI prompts for debugging.
89+
90+
Both tools follow the same 4-module pattern: reader, parser, builder, CLI.
91+
92+
## License
93+
94+
MIT

0 commit comments

Comments
 (0)