format-commit 0.4.0 → 1.0.1

package/README.md

@@ -1,13 +1,12 @@
 # format-commit
 
-[![npm version](https://badge.fury.io/js/format-commit.svg)](https://badge.fury.io/js/format-commit)
 [![Node.js Version](https://img.shields.io/node/v/format-commit.svg)](https://nodejs.org/)
 [![npm downloads](https://img.shields.io/npm/dm/format-commit.svg)](https://www.npmjs.com/package/format-commit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-🚀 Lightweight CLI for consistent Git workflow formatting.
+Lightweight CLI for consistent Git workflow & and optional AI support.
 
-Standardize your commit messages and branch naming with configurable rules, and guide your development workflow through automated scripts. No bloat, no complexity — just clean, consistent Git practices.
+Standardize your commit messages and branch naming with configurable rules, and guide your development workflow through automated scripts. No bloat, no complexity - just clean, consistent Git practices. Feel free to let AI suggest commit titles for you in the expected format.
 
 ## Installation
 
@@ -25,7 +24,7 @@ Add to your `package.json` scripts:
 }
 ```
 
-Then use:
+And use:
 ```sh
 npm run commit # to commit
 npm run branch # to create a branch
@@ -42,34 +41,111 @@ format-commit --branch
 
 ### Initial Setup
 
-On first use, format-commit will prompt you to configure your commit and branch formats, then create a `commit-config.json` file.
+On first use, format-commit will prompt you to configure your commit and branch.
 
-To reconfigure later, run:
+If you want to reconfigure later from scratch, run:
 ```sh
 format-commit --config
 ```
 
 ## Configuration
 
-| Property | Description |
-| :------- | :---------- |
-| **format** | Commit title format:<br>1 - `(type) Name` / 2 - `(type) name`<br>3 - `type: Name` / 4 - `type: name`<br>5 - `type(scope) Name` / 6 - `type(scope) name`<br>7 - `type(scope): Name` / 8 - `type(scope): name` |
-| **branchFormat** | Branch naming format:<br>1 - `type/description`<br>2 - `type/scope/description` |
-| **types** | Allowed commit and branch types (default: `feat`, `fix`, `core`, `test`, `config`, `doc`) |
-| **scopes** | Scopes for commit/branch categorization (used in formats 5-8 for commits, format 2 for branches) |
-| **minLength** | Minimum length required for the commit title |
-| **maxLength** | Maximum length required for the commit title and branch description |
-| **changeVersion** | Version change policy:<br>`never` - Always prompt for version change<br>`only on release branch` - Only release branch commits require version change<br>`always` - All commits require version change |
-| **releaseBranch** | Main/release branch name (used if changeVersion = `only on release branch`) |
-| **showAllVersionTypes** | Show all version types or only main ones (`major`/`minor`/`patch`/`custom`) |
+All configuration is stored in the `commit-config.json` file. Here is the list of all options.
+
+`format`
+
+Commit title format:
+- 1: `(type) Name` / 2: `(type) name`
+- 3: `type: Name` / 4: `type: name`
+- 5: `type(scope) Name` / 6: `type(scope) name`
+- 7: `type(scope): Name` / 8: `type(scope): name`
+
+`branchFormat`
+
+Branch naming format:
+- 1: `type/description`
+- 2: `type/scope/description`
+
+`types`
+
+Allowed commit and branch types (default: `feat`, `fix`, `core`, `test`, `config`, `doc`)
+
+`scopes`
+
+Scopes for commit and branch categorization (used in formats 5-8 for commits, format 2 for branches)
+
+`minLength`
+
+Minimum length required for the commit title.
+
+`maxLength`
+
+Maximum length required for the commit title and branch description.
+
+`changeVersion`
+
+Version change policy:
+- `never (ignore)`: Never change version, skip prompt (default)
+- `never (always ask)`: Always prompt for version change
+- `only on release branch`: Only release branch commits require version change
+- `always`: All commits require version change
+
+`releaseBranch`
+
+Main/release branch name (used if changeVersion = `only on release branch`)
+
+`showAllVersionTypes`
+
+Show all version types or only main ones (`major`/`minor`/`patch`/`custom`)
+
+`ai.enabled`
+
+Enable AI commit title suggestions (default: `false`)
+
+`ai.provider`
+
+AI provider:
+- `anthropic` (Claude)
+- `openai` (GPT)
+- `google` (Gemini)
+
+`ai.model`
+
+Model identifier (e.g., `claude-haiku-4-5` or `gpt-4o-mini`)
+
+`ai.envPath`
+
+Path to .env file containing the AI provider API key (e.g., `.env`)
+
+`ai.envKeyName`
+
+Name of the environment variable for the API key (e.g., `OPENAI_API_KEY`)
+
+`ai.largeDiffTokenThreshold`
+
+Number of tokens from which not to use AI automatically.
+
+### AI Suggestions
+
+When AI is enabled, your staged changes will be processed by the defined AI to suggest commit titles that:
+- Follow your configured format and naming conventions
+- Automatically select appropriate types and scopes
+- Respect your min/max length constraints
+- Describe the actual changes in your code
+
+You can either:
+- Choose one of the 4 AI suggestions for quick commits (and can edit it)
+- Select "Custom" to enter commit details manually (classic flow)
+
+**Security:** AI provider API key is stored in a `.env` file automatically added to `.gitignore`.
 
 ## CLI Options
 
-| Option | Description |
-| :----- | :---------- |
-| `--config` / `-c` | Generate or update configuration file |
-| `--branch` / `-b` | Create a new standardized branch |
-| `--test` / `-t` | Test mode - preview without executing Git commands |
+| Short | Long | Description |
+| :---- | :--- | :---------- |
+| `-c` | `--config` | Generate or update configuration file |
+| `-b` | `--branch` | Create a new standardized branch |
+| `-t` | `--test` | Test mode - preview without executing Git commands |
 
 ## Contributing
 

package/lib/ai-service.js

@@ -0,0 +1,289 @@
+import { execSync } from 'child_process';
+import prompts from 'prompts';
+import * as envUtils from './env-utils.js';
+import * as utils from './utils.js';
+
+
+/* global fetch */
+
+const AI_SYSTEM_PROMPT = 'You are a commit message generator. You MUST respond with ONLY a JSON array. NO explanations. NO markdown. NO additional text whatsoever.';
+
+/** Get optimized git diff */
+const getOptimizedGitDiff = () => {
+  try {
+    const stats = execSync('git diff --cached --stat', { encoding: 'utf-8' });
+    const diff = execSync(
+      'git diff --cached --no-color --unified=1 -- . ":(exclude)package-lock.json" ":(exclude)*.lock" ":(exclude)*.min.*"',
+      { encoding: 'utf-8', maxBuffer: 1024 * 500 }
+    );
+
+    if (!stats.trim() && !diff.trim()) {
+      return null;
+    }
+
+    const lines = diff.split('\n').slice(0, 500).join('\n');
+    return { stats, diff: lines };
+  } catch {
+    utils.log('Error getting git diff', 'error');
+    return null;
+  }
+};
+
+/** Build AI prompt */
+const buildPrompt = (diffData, config) => {
+  const typesList = config.types.map(t => t.value).join(', ');
+  const types = config.types.map(t => `${t.value} (${t.description})`).join(', ');
+  const scopesList = config.scopes ? config.scopes.map(s => s.value).join(', ') : null;
+  const scopes = config.scopes
+    ? config.scopes.map(s => `${s.value} (${s.description})`).join(', ')
+    : null;
+
+  let formatInstruction = '';
+  switch (config.format) {
+    case 1:
+      formatInstruction = 'Format: (type) Title with first letter capitalized';
+      break;
+    case 2:
+      formatInstruction = 'Format: (type) title in lowercase';
+      break;
+    case 3:
+      formatInstruction = 'Format: type: Title with first letter capitalized';
+      break;
+    case 4:
+      formatInstruction = 'Format: type: title in lowercase';
+      break;
+    case 5:
+      formatInstruction = 'Format: type(scope) Title with first letter capitalized';
+      break;
+    case 6:
+      formatInstruction = 'Format: type(scope) title in lowercase';
+      break;
+    case 7:
+      formatInstruction = 'Format: type(scope): Title with first letter capitalized';
+      break;
+    case 8:
+      formatInstruction = 'Format: type(scope): title in lowercase';
+      break;
+  }
+
+  const exampleTitle = utils.formatCommitTitle(
+    config.types[0].value,
+    'example change description',
+    config.format,
+    config.scopes?.[0]?.value
+  );
+
+  return `You must analyze git changes and return ONLY a valid JSON array. NO explanations, NO markdown, NO additional text.
+
+Git diff stats:
+${diffData.stats}
+
+Git diff:
+${diffData.diff}
+
+STRICT REQUIREMENTS:
+- ${formatInstruction}
+- Example format: "${exampleTitle}"
+- ONLY use these types (NO others): ${typesList}
+- Type descriptions: ${types}
+${scopes ? `- ONLY use these scopes (NO others): ${scopesList}\n- Scope descriptions: ${scopes}` : '- No scopes - DO NOT include scope in output'}
+- Length: ${config.minLength}-${config.maxLength} chars per title
+- Return exactly 4 different commit titles
+- Output MUST be a raw JSON array with NO text before or after
+
+YOUR RESPONSE MUST BE EXACTLY THIS FORMAT (no other text):
+["title 1", "title 2", "title 3", "title 4"]`;
+};
+
+/** Call Anthropic API */
+const callAnthropicAPI = async (prompt, apiKey, model) => {
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: model,
+      max_tokens: 200,
+      system: AI_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Anthropic API error: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  return data.content[0].text;
+};
+
+/** Call OpenAI API */
+const callOpenAIAPI = async (prompt, apiKey, model) => {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: model,
+      max_tokens: 200,
+      messages: [
+        {
+          role: 'system',
+          content: AI_SYSTEM_PROMPT,
+        },
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`OpenAI API error: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  return data.choices[0].message.content;
+};
+
+/** Call Google Gemini API */
+const callGeminiAPI = async (prompt, apiKey, model) => {
+  const response = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': apiKey,
+      },
+      body: JSON.stringify({
+        system_instruction: { parts: [{ text: AI_SYSTEM_PROMPT }] },
+        contents: [{ parts: [{ text: prompt }] }],
+      }),
+    }
+  );
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Gemini API error: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  return data.candidates[0].content.parts[0].text;
+};
+
+/** Validate and normalize AI suggestion */
+const validateAndNormalizeSuggestion = (suggestion, config) => {
+  const result = utils.parseAndNormalizeCommitTitle(suggestion, config);
+
+  // Returns null if invalid format/type/scope/length
+  if (result.error) {
+    return null;
+  }
+  const lengthCheck = utils.validCommitTitle(result.normalized, config.minLength, config.maxLength);
+  if (lengthCheck !== true) {
+    return null;
+  }
+
+  // Returns normalized title (auto-corrected case)
+  return result.normalized;
+};
+
+/** Generate commit title suggestions using AI */
+const generateCommitSuggestions = async (config, testMode) => {
+  const diffData = getOptimizedGitDiff();
+  if (!diffData) {
+    return [];
+  }
+
+  const apiKey = envUtils.getEnvKey(config.ai.envPath, config.ai.envKeyName);
+  if (!apiKey) {
+    throw new Error('AI API key not found in .env');
+  }
+
+  const prompt = buildPrompt(diffData, config);
+  const estimatedTokens = Math.ceil(prompt.length / 4);
+  const threshold = config.ai.largeDiffTokenThreshold || 20000;
+
+  if (estimatedTokens > threshold) {
+    const { confirm } = await prompts({
+      type: 'confirm',
+      name: 'confirm',
+      message: `Large diff detected (~${estimatedTokens} tokens). Generate AI suggestions?`,
+      initial: false,
+    });
+    if (!confirm) {
+      return [];
+    }
+  }
+
+  let responseText;
+  if (config.ai.provider === 'anthropic') {
+    responseText = await callAnthropicAPI(prompt, apiKey, config.ai.model);
+  } else if (config.ai.provider === 'openai') {
+    responseText = await callOpenAIAPI(prompt, apiKey, config.ai.model);
+  } else if (config.ai.provider === 'google') {
+    responseText = await callGeminiAPI(prompt, apiKey, config.ai.model);
+  } else {
+    throw new Error(`Unknown AI provider: ${config.ai.provider}`);
+  }
+
+  const jsonMatch = responseText.match(/\[[\s\S]*\]/);
+  if (!jsonMatch) {
+    if (testMode) {
+      utils.log(responseText, 'warning');
+    }
+    throw new Error('No JSON array found in AI response');
+  }
+
+  const suggestions = JSON.parse(jsonMatch[0]);
+
+  if (!Array.isArray(suggestions) || !suggestions.length) {
+    if (testMode) {
+      utils.log(responseText, 'warning');
+    }
+    throw new Error('Invalid AI response format');
+  }
+
+  // Validate and normalize each suggestion
+  const validationResults = suggestions.map(s => ({
+    original: s,
+    normalized: validateAndNormalizeSuggestion(s, config)
+  }));
+
+  // Log rejected suggestions in test mode
+  if (testMode) {
+    validationResults.forEach(({ original, normalized }) => {
+      if (normalized === null) {
+        utils.log(`rejected: "${original}"`, 'warning');
+      }
+    });
+  }
+
+  const validSuggestions = validationResults
+    .filter(({ normalized }) => normalized !== null)
+    .map(({ normalized }) => normalized);
+
+  if (validSuggestions.length === 0) {
+    throw new Error('All AI suggestions were invalid');
+  }
+
+  return validSuggestions;
+};
+
+export {
+  generateCommitSuggestions,
+};