Thank you for your interest in contributing to lazycommit! This guide will help you get started with the development setup and contribution process.

• Prerequisites
• Setting up the project
• Development workflow
• Testing
• Code quality guidelines
• Contributing process
• Using & testing your changes
• Project structure

Before you begin, ensure you have the following installed:

• Node.js: Version 20 (as specified in .nvmrc)
• pnpm: Version 10.15.0 (as specified in package.json)
• nvm: For managing Node.js versions
• Git: For version control

git clone https://github.com/KartikLabhshetwar/lazycommit.git
cd lazycommit

Use nvm to use the appropriate Node.js version from .nvmrc:

nvm install
nvm use

Install the dependencies using pnpm:

pnpm install

Run the build script to compile TypeScript and bundle the project:

pnpm build

The package is bundled using pkgroll (Rollup). It infers the entry-points from package.json so there are no build configurations.

During development, you can use the watch flag (--watch, -w) to automatically rebuild the package on file changes:

pnpm build -w

Run TypeScript type checking:

pnpm type-check

Since pkgroll knows the entry-point is a binary (being in package.json#bin), it automatically adds the Node.js hashbang to the top of the file, and chmods it so it's executable.

You can run the distribution file in any directory:

./dist/cli.mjs

Or in non-UNIX environments, you can use Node.js to run the file:

node ./dist/cli.mjs

Testing requires passing in GROQ_API_KEY as an environment variable:

GROQ_API_KEY=<your GROQ key> pnpm test

You can still run tests that don't require GROQ_API_KEY but will not test the main functionality:

pnpm test

The project uses manten for testing. Tests are organized in the tests/ directory:

• tests/specs/cli/ - CLI command tests
• tests/specs/groq/ - Groq API integration tests
• tests/specs/config.ts - Configuration tests
• tests/specs/git-hook.ts - Git hook tests
• tests/fixtures/ - Test fixtures and sample diffs

The tests/fixtures/ directory contains sample git diffs for testing different commit scenarios:

• chore.diff - Chore commits
• new-feature.diff - New feature commits
• fix-nullpointer-exception.diff - Bug fix commits
• conventional-commits.diff - Conventional commit format
• And more...

• Use strict TypeScript configuration
• Follow the existing code style and patterns
• Ensure all functions have proper type annotations
• Use meaningful variable and function names

• Follow the existing code patterns in the project
• Keep functions focused and single-purpose
• Use descriptive variable names
• Avoid unnecessary comments (code should be self-documenting)
• Avoid unnecessary if/else statements

src/
├── cli.ts                    # Main CLI entry point
├── commands/                 # CLI commands
│   ├── config.ts            # Configuration management
│   ├── hook.ts              # Git hook management
│   ├── lazycommit.ts        # Main commit generation logic
│   └── prepare-commit-msg-hook.ts  # Git hook implementation
└── utils/                   # Utility functions
    ├── config.ts            # Configuration utilities
    ├── error.ts             # Error handling
    ├── fs.ts                # File system utilities
    ├── git.ts               # Git operations
    ├── groq.ts              # Groq API integration
    └── prompt.ts            # User prompts

Fork the repository on GitHub and clone your fork locally.

git checkout -b feature/your-feature-name

• Write your code following the project's style guidelines
• Add tests for new functionality
• Update documentation if needed
• Ensure all tests pass

# Run type checking
pnpm type-check

# Build the project
pnpm build

# Run tests (without API key)
pnpm test

# Run tests with API key (if you have one)
GROQ_API_KEY=<your-key> pnpm test

Use conventional commit messages:

git add .
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve issue with X"
# or
git commit -m "docs: update README"

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Let's say you made some changes in a fork/branch and you want to test it in a project. You can publish the package to a GitHub branch using git-publish:

Publish your current branch to a npm/* branch on your GitHub repository:

pnpm dlx git-publish

This will output something like:

✔ Successfully published branch! Install with command:
  → npm i 'KartikLabhshetwar/lazycommit#npm/develop'

Now, you can run the branch in your project:

pnpm dlx 'KartikLabhshetwar/lazycommit#npm/develop'

• src/cli.ts - Main CLI entry point using cleye
• src/commands/lazycommit.ts - Core commit message generation with smart grouping logic
• src/utils/groq.ts - Groq API integration with retry/fallback mechanisms
• src/utils/config.ts - Configuration management
• src/utils/git.ts - Git operations and file analysis utilities
• package.json - Project configuration and dependencies
• tsconfig.json - TypeScript configuration

• @clack/prompts - Interactive CLI prompts
• cleye - CLI framework
• groq-sdk - Groq API client
• execa - Process execution
• pkgroll - TypeScript bundler
• manten - Testing framework

1. TypeScript compilation
2. Bundling with pkgroll
3. Adding Node.js hashbang for executable
4. Output to dist/cli.mjs

• Smart file grouping: Automatically groups files by conventional commit types and scopes
• Token-safe AI integration: Uses compact git summaries instead of full diffs to avoid rate limits
• Retry mechanisms: Exponential backoff and model fallback for robust API handling
• Multi-commit workflow: Creates logical, atomic commits for large changes
• Enhanced file classification: Context-aware file type detection using git patterns

• Check existing Issues
• Create a new issue for bugs or feature requests
• Join discussions in pull requests

By contributing to lazycommit, you agree that your contributions will be licensed under the Apache-2.0 License.