How arakiss/commitloom works
Project Type and Purpose
• CommitLoom is an open-source CLI tool written in Python.
• Purpose: Analyze staged Git changes, call an AI service (OpenAI API), generate structured commit messages, batch large changes, and track usage metrics.
• Key features: CLI front-end, core modules for analysis and batching, AI integration, local metrics storage, and Git operations.
High-Level Architectural Components
a. CLI Layer
• Entry point (commitloom/__main__.py)
• CLI handler (commitloom/cli/cli_handler.py)
• Console module for rich output (commitloom/cli/console.py)
b. Core Layer
• Analyzer (commitloom/core/analyzer.py): inspects diffs, complexity, binary files
• Batch processor (commitloom/core/batch.py): splits or groups changes
• Git wrapper (commitloom/core/git.py): interacts with local Git (staging, commits)
c. Service Layer
• AI service (commitloom/services/ai_service.py): builds prompts, calls OpenAI API
• Metrics service (commitloom/services/metrics.py): records token usage, cost, time, writes to local metrics store
d. Configuration
• Settings loader (commitloom/config/settings.py): reads environment variables, .env files, global config
e. External Systems
• Git CLI / repository (local file system)
• OpenAI API (external cloud service)
• Local metrics storage (filesystem under ~/.local/share/commitloom/metrics or configured path)
Component Relationships and Data Flow
1. User invokes loom or cl command → CLI Layer.
2. CLI handler loads settings from Configuration.
3. CLI invokes Core Analyzer to parse and classify staged changes.
4. Batch processor in Core decides whether to split into multiple commits.
5. Core uses Git wrapper to gather diffs and staging info.
6. Core sends data to AI Service, which:
• Formats prompt
• Sends HTTP request to OpenAI API
• Receives generated commit message
7. Core invokes Git wrapper to create the commit(s) with AI-generated message(s).
8. Metrics Service collects data (tokens, cost, time saved), writes to local metrics storage.
9. CLI Console displays results and metrics to the user.
Architectural Patterns and Principles
• Layered Architecture: clear separation between CLI, core logic, external services, and configuration.
• Single Responsibility: each module handles one concern (analysis, batching, Git ops, AI calls, metrics).
• Dependency Injection: core modules take service instances (AIService, MetricsService) rather than hardcoding.
• Configuration-over-convention: settings module centralizes environment and file-based config.
• Testability: modules are decoupled, enabling comprehensive unit tests.
Technologies, Frameworks, Libraries
• Python (typing, modules), PyPI distribution via pyproject.toml.
• Click or argparse for CLI (inferred from cli_handler signature).
• Requests or OpenAI Python SDK for API calls.
• Ruff and MyPy for linting and type checking.
• Git CLI or GitPython for repository operations.
• Local file system for metrics (YAML/JSON or SQLite).
• GitHub Actions workflows for CI/CD.