How di-sukharev/opencommit works
Project Type & Purpose
• This is a TypeScript-based CLI tool (opencommit) plus a companion GitHub Action that auto-generates git commit messages via AI.
• The core functionality lives in a reusable “engine” layer that wraps HTTP calls to various LLM providers (OpenAI, Anthropic, Ollama, etc.), and a set of “commands” that expose that functionality to the CLI and Git hooks.
High-Level File Structure & Architectural Patterns
• src/cli.ts: the single entrypoint for the oco CLI.
• src/commands/*: each file is a subcommand (commit, config, hook management, commitlint integration).
• src/engine/*: adapter pattern—one engine per LLM provider, all implementing a common Engine interface.
• src/modules/commitlint: plugin/module that integrates @commitlint as an optional prompt module.
• src/utils: shared helper functions (git diff extraction, token counting, sleep, etc.).
• src/i18n: internationalization JSON files and loader.
• src/migrations: lightweight migration system for evolving the local/global config schema.
• src/github-action.ts: entrypoint for the GitHub Action.
• out/*.cjs & wasm: compiled artifacts distributed on npm.
Main Components
a. CLI Layer
• oco CLI entrypoint (src/cli.ts)
• Command dispatcher (maps CLI args to src/commands/*)
b. Command Modules
• Commit generation (commit.ts, generateCommitMessageFromGitDiff.ts)
• Config management (config.ts)
• Git hook install/uninstall (githook.ts, prepare-commit-msg-hook.ts)
• Commitlint adapter (modules/commitlint)
c. Engine Layer (Adapter Pattern)
• Abstract Engine interface (Engine.ts)
• Concrete providers (openAi.ts, anthropic.ts, azure.ts, flowise.ts, ollama.ts, etc.)
• HTTP client component to call external LLM APIs (configured via OCO_API_URL, custom headers)
d. Persistence & Configuration
• Local repo config (.env, .opencommitignore)
• Global config in ~/.opencommit (managed by migrations and utils)
e. Git Integration
• Git CLI (diff extraction, staging, commit API)
• Git hooks (prepare-commit-msg)
f. GitHub Action
• GitHub runner (actions/checkout + setup-node)
• github-action.ts: wraps the same engine/commands as the CLI but triggered on push
g. External Services
• LLM Providers (OpenAI, Anthropic, Ollama, Flowise, etc.)
• GitHub API (for action metadata & write permissions)
Component Relationships & Data Flow
• User → oco
→ CLI parses args → Dispatch to a Command Module →
• Reads git diff via utils/git.ts
• Loads config via migrations & utils
• Calls EngineManager → selects a provider → makes HTTP request → receives AI-generated commit message →
• Writes Git commit via git commit → optionally pushes
• User → git commit (with prepare-commit-msg hook)
→ Hook script calls into CLI layer to prefill commit message
• GitHub Action workflow
→ on.push → checkout → node runner → github-action.ts → invokes the same commit-improvement logic for all new commits → pushes back
Technologies & Frameworks
• Node.js + TypeScript
• esbuild for bundling
• Jest for unit & e2e tests
• Git (hooks & CLI)
• GitHub Actions
• HTTP to LLM endpoints
• i18n JSON files
Architectural Patterns & Design Principles
• Adapter pattern for engine providers (common interface, pluggable)
• Modular command architecture (each command encapsulates its own logic)
• Hexagonal / clean separation: CLI layer → application logic (commands) → domain (engine) → infrastructure (HTTP, Git)
• Migrations for evolving local/global config
• Plugin-style modules for optional features (commitlint)