commiti 1.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55dfe17b32ed45b600920943c16b99f39b0acff0c9c66e516db63e6fa7a0debf
+  data.tar.gz: 9f70caaeef73f63211e93bd28ae2ae69236c0e777153c48a765066a0825e4e49
+SHA512:
+  metadata.gz: a627866611dcc0974b30a005814b38226833412a1789a57f4f3559c010849313731d361dd0d0e192722577e0f1353d8fa55c2bf9487c4d83bbe596e7d5a04e16
+  data.tar.gz: 0b8e9679be21a6f74ea419ffb4968f883fb564990eeab845c63f525190d459a151cebc17d2d852a3eba9f8293093107bd146e76cf37cae8087af88bd06f53e5e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Setoju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# Commiti
+
+AI-powered commit message and pull request description generator for Git repositories, using Google AI models.
+
+## What It Does
+
+Commiti helps you:
+
+- Generate conventional commit messages from staged changes.
+- Generate structured pull request descriptions from branch diffs.
+- Review and optionally edit generated commit messages before writing to Git history.
+- Open a prefilled PR/MR page in your browser for GitHub, GitLab, or GitBucket (no provider API token required).
+- Preserve semantic diff quality on large changes using file-aware clipping that keeps file headers and hunk markers.
+
+## Requirements
+
+- Ruby 3.2+
+- Git
+- Google AI API key
+- A Git repository as your working directory
+
+## Install Dependencies (from source)
+
+```bash
+bundle install
+```
+
+## CLI Usage
+
+```bash
+bundle exec ruby -Ilib bin/commiti [options]
+```
+
+Or after gem installation:
+
+```bash
+commiti [options]
+```
+
+## Configuration
+
+Commiti uses a single configuration approach: environment variables.
+
+Set variables in your shell, CI secret manager, or local `.env` file (in your project):
+
+```dotenv
+GOOGLE_API_KEY=your_google_ai_key
+
+# Optional overrides:
+# COMMITI_MODEL=gemma-4-31b-it
+# COMMITI_CANDIDATES=1
+# COMMITI_BASE_BRANCH=main
+# COMMITI_NO_COPY=false
+```
+
+`GEMINI_API_KEY` is also accepted as an alias for `GOOGLE_API_KEY`.
+
+You can copy `.env.example` as a starting point.
+
+Your API key is sent directly from your local process to Google's API.
+Commiti does not store it and does not proxy requests through any Commiti server.
+Never commit `.env` to git.
+
+### Options
+
+- `--type TYPE` where `TYPE` is `commit` or `pr` (default: `commit`)
+- `--base BRANCH` base branch for PR diff (default: `main`)
+- `--no-copy` print output only, skip clipboard copy
+- `--candidates N` generate `N` output candidates (`1`-`5`, default: `1`)
+- `-h`, `--help` show help
+
+## Commit Flow (`--type commit`)
+
+1. Shows `git status --short`.
+2. Asks for confirmation before staging (`git add -A`).
+3. Ensures there are staged changes.
+4. Reads staged diff and generates commit message candidate(s).
+   - If the AI draft misses a conventional commit prefix, Commiti auto-normalizes it to a valid conventional subject.
+5. If `--candidates` is greater than `1`, shows numbered candidates and asks you to select one.
+6. Shows selected message and asks: `Commit with this message? [y/e/N]`
+   - `y`: commit now
+   - `e`: open editor, then validate and re-confirm
+   - `N`: skip commit
+7. Writes commit with `git commit --file <tempfile>`.
+
+### Commit Message Validation
+
+- First line must use a conventional commit prefix (e.g. `feat:`, `fix:`).
+- First line must be 100 characters or fewer.
+
+### Why `--file` instead of `-m`
+
+Multi-line messages and special characters are safer with `git commit --file`, avoiding shell quoting edge cases.
+
+### Editor Selection
+
+Commit edit mode uses:
+
+1. `VISUAL`
+2. `EDITOR`
+3. Fallback: `notepad` on Windows, `vi` on non-Windows
+
+## PR Flow (`--type pr`)
+
+1. Reads branch diff: `git diff <base>...HEAD`.
+2. Generates PR description with these sections:
+   - `## Summary`
+   - `## Motivation`
+   - `## Changes Made`
+   - `## Testing Notes`
+3. Builds provider compare/MR URL with prefilled title/body using query params.
+  - GitHub/GitBucket: compare URL
+  - GitLab: new merge request URL
+   - If the URL would exceed safe browser/provider limits, Commiti drops description prefill automatically and keeps the shortest usable URL.
+4. Asks before opening browser.
+
+The tool opens a browser URL only. It does not call provider APIs.
+
+### Diff Context Protocol
+
+When a diff exceeds internal size limits, Commiti clips and summarizes using file-aware rules:
+
+- Keeps full `diff --git` file headers where possible.
+- Preserves `@@ ... @@` hunk headers before clipping hunk bodies.
+- Includes as many complete files/hunks as fit in the limit, then appends a clipping notice.
+- Summarizes large chunks asynchronously and in batches to reduce total LLM round trips.
+- Falls back to deterministic file-level summaries if model summarization times out.
+
+This improves semantic quality for AI generation compared with naive truncation.
+
+## Examples
+
+Generate commit message and commit interactively:
+
+```bash
+bundle exec ruby -Ilib bin/commiti --type commit
+```
+
+Generate multiple commit message candidates and pick one:
+
+```bash
+bundle exec ruby -Ilib bin/commiti --type commit --candidates 3
+```
+
+Generate PR description against `develop`:
+
+```bash
+bundle exec ruby -Ilib bin/commiti --type pr --base develop
+```
+
+Print only, do not copy to clipboard:
+
+```bash
+bundle exec ruby -Ilib bin/commiti --type pr --no-copy
+```
+
+## Implementation Overview
+
+Main entrypoint and flow orchestration:
+
+- `bin/commiti`: CLI parsing and flow dispatch
+- `lib/flows/base_flow.rb`: shared generation pipeline and quality checks
+- `lib/flows/commit_flow.rb`: commit-specific staging/edit/commit interactions
+- `lib/flows/pr_flow.rb`: PR-specific URL generation/open flow
+
+Core services:
+
+- `lib/services/git_reader.rb`
+  - `lib/services/git/git_reader.rb`: Reads staged diff and branch diff, applies file-aware clipping, provides recent commits helper.
+  - `lib/services/git/git_writer.rb`: Reads status/staged state, stages (`git add -A`), commits with message file (`git commit --file`), reads branch and origin remote.
+  - `lib/services/git/diff_parser.rb`: Parses diff blocks and derives change metadata.
+  - `lib/services/git/pr/pr_opener.rb`: Parses GitHub/GitLab/GitBucket remotes, builds provider-specific PR/MR URL, opens browser cross-platform.
+- `lib/services/google_client.rb`: Sends generation requests to Google Generative Language API.
+- `lib/services/diff_summarization/diff_summarizer.rb`: Orchestrates large-diff summarization and summary combine.
+  - `lib/services/diff_summarization/batch_runner.rb`: Runs asynchronous, batched per-file summarization jobs.
+  - `lib/services/diff_summarization/fallback_builder.rb`: Builds deterministic summaries when model summarization fails or times out.
+- `lib/services/helpers/config_loader.rb`: Loads configuration from environment variables.
+  - `lib/services/helpers/prompt_builder.rb`: Builds strict system/user prompts for commit and PR modes.
+  - `lib/services/helpers/interactive_prompt.rb`: Handles confirmation prompts, candidate selection, editor loop, and commit message validation.
+  - `lib/services/helpers/clipboard.rb`: Provides cross-platform clipboard support.
+  - `lib/services/helpers/spinner.rb`: Displays a spinner for long-running operations.
+- `lib/services/message_generator.rb`: Generates commit and PR messages with quality checks.
+- `lib/services/message_presenter.rb`: Presents generated messages to the user.
+- `lib/services/flow_context_builder.rb`: Builds the context for different Commiti flows.
+- `lib/services/git/commit/commit_staging.rb`: Handles staging changes for a commit.
+- `lib/services/git/commit/commit_execution.rb`: Executes the git commit command.
+
+Service loading:
+
+- `lib/commiti.rb` requires all service modules.
+
+## Error Handling
+
+The CLI reports user-friendly errors for common cases such as:
+
+- No changes/staged changes
+- Invalid or missing Git data
+- Google AI API connectivity/authentication failures
+- Summarization timeouts on large diffs (automatically falls back to a deterministic summary and continues)
+- Browser open failures
+
+## Notes
+
+- The default model is `gemma-4-31b-it` in `GoogleClient`.
+- PR browser URL body payloads are URL-encoded with `URI.encode_www_form`.
+- You can tune summarization worker concurrency with `DIFF_SUMMARY_WORKERS`.

data/bin/commiti

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'dotenv/load'
+require 'commiti'
+
+options = {
+  type: :commit
+}
+
+OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+
+    AI Commit - Powered by Google AI (#{Commiti::GoogleClient::DEFAULT_MODEL})
+    Usage: commiti [options]
+
+  BANNER
+
+  opts.on('--type TYPE', %i[commit pr], 'Message type: commit or pr (default: commit)') do |t|
+    options[:type] = t
+  end
+
+  opts.on('--base BRANCH', 'Base branch for PR diff (default: main)') do |b|
+    options[:base_branch] = b
+  end
+
+  opts.on('--no-copy', 'Print output only, skip clipboard copy') do
+    options[:no_copy] = true
+  end
+
+  opts.on('--candidates N', Integer, 'Number of output candidates to generate (1-5, default: 1)') do |n|
+    raise OptionParser::InvalidArgument, 'candidates must be between 1 and 5' unless n.between?(1, 5)
+
+    options[:candidates] = n
+  end
+
+  opts.on('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end.parse!
+
+begin
+  flow = if options[:type] == :pr
+           Commiti::Flows::PrFlow.new(options: options)
+         else
+           Commiti::Flows::CommitFlow.new(options: options)
+         end
+
+  flow.run
+rescue RuntimeError => e
+  puts "\nError: #{e.message}\n\n"
+  exit 1
+rescue SocketError, Errno::ECONNREFUSED
+  puts "\nError: Could not connect to Google AI API. Check network access and DNS resolution.\n\n"
+  exit 1
+rescue Net::OpenTimeout, Net::ReadTimeout
+  puts "\nError: Google AI request timed out while generating output. Try again or use a smaller diff.\n\n"
+  exit 1
+rescue StandardError => e
+  puts "\nError: Something went wrong (#{e.class}).\n\n"
+  exit 1
+end

data/lib/commiti.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'services/git/git_reader'
+require_relative 'services/git/git_writer'
+require_relative 'services/google_client'
+require_relative 'services/helpers/config_loader'
+require_relative 'services/git/diff_parser'
+require_relative 'services/diff_summarization/diff_summarizer'
+require_relative 'services/helpers/prompt_builder'
+require_relative 'services/helpers/interactive_prompt'
+require_relative 'services/git/pr/pr_opener'
+require_relative 'services/helpers/clipboard'
+require_relative 'services/helpers/spinner'
+require_relative 'services/flow_context_builder'
+require_relative 'services/message_generator'
+require_relative 'services/message_presenter'
+require_relative 'services/git/commit/commit_staging'
+require_relative 'services/git/commit/commit_execution'
+require_relative 'flows/base_flow'
+require_relative 'flows/commit_flow'
+require_relative 'flows/pr_flow'

data/lib/flows/base_flow.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Commiti
+  module Flows
+    class BaseFlow
+      def initialize(options:)
+        # Merge defaults/config file with CLI options (CLI options win)
+        @options = Commiti::ConfigLoader.load.merge(options || {})
+      end
+
+      def run
+        prepare!
+        diff = collect_diff
+        client = Commiti::GoogleClient.new(config: options)
+        selected_model = options[:model]
+        context = Commiti::FlowContextBuilder.build(
+          flow_type: flow_type,
+          diff: diff,
+          client: client,
+          run_stage: method(:run_stage),
+          model: selected_model
+        )
+        Commiti::MessagePresenter.print_summarization_notice(context[:summarized_result])
+
+        candidates = generate_candidates(
+          client: client,
+          prompt: context[:prompt],
+          diff_metadata: context[:diff_metadata],
+          model: selected_model
+        )
+        message = select_message(candidates)
+
+        maybe_copy_to_clipboard(message)
+        finalize(message)
+      end
+
+      private
+
+      attr_reader :options
+
+      def prepare!; end
+
+      def collect_diff
+        raise NotImplementedError, "#{self.class} must implement #collect_diff"
+      end
+
+      def flow_type
+        raise NotImplementedError, "#{self.class} must implement #flow_type"
+      end
+
+      def finalize(_message); end
+
+      def run_stage(message, &)
+        Commiti::Spinner.run(message, &)
+      end
+
+      def generate_with_quality_check(client:, prompt:, diff_metadata:, model:)
+        message_generator.generate_with_quality_check(
+          client: client,
+          prompt: prompt,
+          diff_metadata: diff_metadata,
+          model: model
+        )
+      end
+
+      def generate_candidates(client:, prompt:, diff_metadata:, model:)
+        count = options[:candidates].to_i
+        message_generator.generate_candidates(
+          client: client,
+          prompt: prompt,
+          diff_metadata: diff_metadata,
+          count: count,
+          model: model
+        )
+      end
+
+      def select_message(candidates)
+        Commiti::MessagePresenter.select_message(candidates)
+      end
+
+      def print_message(message)
+        Commiti::MessagePresenter.print_message(message)
+      end
+
+      def maybe_copy_to_clipboard(message)
+        Commiti::MessagePresenter.maybe_copy_to_clipboard(
+          message,
+          no_copy: options[:no_copy],
+          run_stage: method(:run_stage)
+        )
+      end
+
+      def message_generator
+        @message_generator ||= Commiti::MessageGenerator.new(flow_type: flow_type, run_stage: method(:run_stage))
+      end
+    end
+  end
+end

data/lib/flows/commit_flow.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Commiti
+  module Flows
+    class CommitFlow < BaseFlow
+      private
+
+      def flow_type
+        :commit
+      end
+
+      def prepare!
+        Commiti::CommitStaging.prepare(run_stage: method(:run_stage))
+      end
+
+      def collect_diff
+        run_stage('Collecting staged diff') { Commiti::GitReader.staged_diff }
+      end
+
+      def finalize(message)
+        Commiti::CommitExecution.maybe_commit(
+          message,
+          run_stage: method(:run_stage),
+          print_message: method(:print_message)
+        )
+      end
+    end
+  end
+end

data/lib/flows/pr_flow.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Commiti
+  module Flows
+    class PrFlow < BaseFlow
+      private
+
+      def flow_type
+        :pr
+      end
+
+      def collect_diff
+        run_stage("Collecting diff against #{options[:base_branch]}...HEAD") do
+          Commiti::GitReader.branch_diff(base_branch: options[:base_branch])
+        end
+      end
+
+      def finalize(message)
+        maybe_open_pr_page(message, options[:base_branch])
+      end
+
+      def maybe_open_pr_page(description, base_branch)
+        pr_url = run_stage('Preparing prefilled PR URL') do
+          head_branch = Commiti::GitWriter.current_branch
+          origin_url = Commiti::GitWriter.origin_url
+          title = Commiti::PrOpener.suggest_title(description, head_branch: head_branch)
+          Commiti::PrOpener.compare_url(
+            origin_url: origin_url,
+            base_branch: base_branch,
+            head_branch: head_branch,
+            title: title,
+            body: description
+          )
+        end
+
+        if Commiti::InteractivePrompt.ask_yes_no('Open prefilled PR page in browser now?', default: :no)
+          run_stage('Opening browser') { Commiti::PrOpener.open_in_browser(pr_url) }
+          puts "\nOpened PR page:\n#{pr_url}\n\n"
+        else
+          puts "\nPR URL:\n#{pr_url}\n\n"
+        end
+      end
+    end
+  end
+end

data/lib/services/diff_summarization/batch_runner.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Commiti
+  module DiffSummarizer
+    module BatchRunner
+      def summarize_chunks(chunks, client:, model:)
+        results = Array.new(chunks.length)
+        large_jobs = []
+
+        chunks.each_with_index do |chunk, index|
+          if chunk[:diff].bytesize > CHUNK_THRESHOLD
+            large_jobs << { index: index, chunk: chunk }
+          else
+            results[index] = format_chunk_summary(path: chunk[:path], summary: mechanical_summary(chunk[:diff]))
+          end
+        end
+
+        batched_jobs = build_batch_jobs(large_jobs)
+        run_async_summary_jobs(batched_jobs, results: results, client: client, model: model) unless batched_jobs.empty?
+        results
+      end
+
+      def run_async_summary_jobs(jobs, results:, client:, model:)
+        queue = Queue.new
+        jobs.each { |job| queue << job }
+
+        worker_count = summary_worker_count(jobs.length)
+        captured_errors = Queue.new
+
+        workers = Array.new(worker_count) do
+          Thread.new do
+            loop do
+              job = queue.pop(true)
+              process_batch_job(job, results: results, client: client, model: model)
+            rescue ThreadError
+              break
+            rescue StandardError => e
+              captured_errors << e
+              break
+            end
+          end
+        end
+
+        workers.each(&:join)
+        raise captured_errors.pop unless captured_errors.empty?
+      end
+
+      def process_batch_job(job, results:, client:, model:)
+        items = job[:items]
+        if items.length == 1
+          item = items.first
+          summary = summarize_single_chunk(item[:chunk], client: client, model: model)
+          results[item[:index]] = format_chunk_summary(path: item[:chunk][:path], summary: summary)
+          return
+        end
+
+        summaries = summarize_chunk_batch(items, client: client, model: model)
+        items.each do |item|
+          summary = summaries[item[:chunk][:path].to_s]
+          summary ||= summarize_single_chunk(item[:chunk], client: client, model: model)
+          results[item[:index]] = format_chunk_summary(path: item[:chunk][:path], summary: summary)
+        end
+      end
+
+      def build_batch_jobs(jobs)
+        batched = []
+        current = []
+        current_bytes = 0
+
+        jobs.each do |job|
+          chunk_bytes = job[:chunk][:diff].bytesize
+          should_split = !current.empty? && (
+            current.length >= MAX_BATCH_FILES ||
+            current_bytes + chunk_bytes > MAX_BATCH_BYTES
+          )
+
+          if should_split
+            batched << { items: current }
+            current = []
+            current_bytes = 0
+          end
+
+          current << job
+          current_bytes += chunk_bytes
+        end
+
+        batched << { items: current } unless current.empty?
+        batched
+      end
+
+      def summarize_single_chunk(chunk, client:, model:)
+        client.generate(
+          system: CHUNK_SYSTEM,
+          user: "Summarize these changes:\n\n``diff\n#{chunk[:diff]}\n``",
+          model: model,
+          timeout_seconds: 120,
+          open_timeout_seconds: 10
+        )
+      end
+
+      def summarize_chunk_batch(items, client:, model:)
+        user = +"Summarize the following file diffs:\n\n"
+        items.each do |item|
+          path = item[:chunk][:path]
+          diff = item[:chunk][:diff]
+          user << "### #{path}\n```diff\n#{diff}\n```\n\n"
+        end
+
+        output = client.generate(
+          system: BATCH_SYSTEM,
+          user: user.rstrip,
+          model: model,
+          timeout_seconds: 120,
+          open_timeout_seconds: 10
+        )
+
+        parse_batched_summary_output(output, expected_paths: items.map { |item| item[:chunk][:path].to_s })
+      end
+
+      def parse_batched_summary_output(output, expected_paths:)
+        sections = output.to_s.split(/^### /).map(&:strip).reject(&:empty?)
+        parsed = {}
+
+        sections.each do |section|
+          lines = section.lines
+          path = lines.first.to_s.strip
+          next unless expected_paths.include?(path)
+
+          summary = lines[1..].to_a.join.strip
+          parsed[path] = summary unless summary.empty?
+        end
+
+        parsed
+      end
+
+      def summary_worker_count(job_count)
+        configured = Integer(ENV.fetch('DIFF_SUMMARY_WORKERS', DEFAULT_SUMMARY_WORKERS))
+        configured.clamp(1, job_count)
+      rescue ArgumentError
+        DEFAULT_SUMMARY_WORKERS.clamp(1, job_count)
+      end
+
+      def format_chunk_summary(path:, summary:)
+        "### #{path}\n#{summary.to_s.strip}"
+      end
+    end
+  end
+end