format-commit 0.3.1 → 1.0.0

package/README.md

@@ -5,9 +5,9 @@
 [![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 commit message formatting.
+🚀 Lightweight CLI for consistent Git workflow & and optional AI support.
 
-Standardize your commit naming with basic rules, and guide your workflow through an automated script. No bloat, no complexity — just clean, consistent commits.
+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
 
@@ -20,22 +20,29 @@ npm i format-commit --save-dev
 Add to your `package.json` scripts:
 ```json
 "scripts": {
-  "commit": "format-commit"
+  "commit": "format-commit",
+  "branch": "format-commit --branch"
 }
 ```
 
 Then use:
 ```sh
-npm run commit
+npm run commit # to commit
+npm run branch # to create a branch
 ```
 
+### Global Installation
+
 Or install globally:
 ```sh
 npm i -g format-commit
 format-commit
+format-commit --branch
 ```
 
-On first use, format-commit will prompt you to configure your commit format and create a `commit-config.json` file.
+### Initial Setup
+
+On first use, format-commit will prompt you to configure your commit and branch formats, then create a `commit-config.json` file.
 
 To reconfigure later, run:
 ```sh
@@ -47,14 +54,45 @@ format-commit --config
 | 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` |
-| **types** | Allowed commit types (default: `feat`, `fix`, `core`, `test`, `config`, `doc`) |
-| **scopes** | Scopes for commit categorization (formats 5-8 only) |
+| **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 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 |
-| **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 |
+| **maxLength** | Maximum length required for the commit title and branch description |
+| **changeVersion** | Version change policy:<br>`never (ignore)` - Never change version, skip prompt (default)<br>`never (always ask)` - 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`) |
-| **stageAllChanges** | Auto-stage all changes before commit ⚠️ |
+
+### AI Suggestions
+
+| Property | Description |
+| :------- | :---------- |
+| **ai.enabled** | Enable AI commit title suggestions (default: `false`) |
+| **ai.provider** | AI provider:<br>`anthropic` (Claude)<br>`openai` (GPT)<br>`google` (Gemini) |
+| **ai.model** | Eg. `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 |
+
+When AI is enabled, format-commit will analyze your staged changes and suggest 4 complete 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:** Your AI provider API key is stored in a `.env` file (not versioned) and 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 |
 
 ## Contributing
 

package/lib/ai-service.js

@@ -0,0 +1,272 @@
+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 types = config.types.map(t => `${t.value} (${t.description})`).join(', ');
+  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}"
+- Available types: ${types}
+${scopes ? `- Available scopes: ${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 a commit suggestion */
+const validateSuggestion = (suggestion, config) => {
+  if (suggestion.length < config.minLength || suggestion.length > config.maxLength) {
+    return false;
+  }
+
+  // Check that the suggestion contains a valid type
+  const validTypes = config.types.map(t => t.value);
+  const hasValidType = validTypes.some(type => {
+    return suggestion.includes(type);
+  });
+
+  return hasValidType;
+};
+
+/** Generate commit title suggestions using AI */
+const generateCommitSuggestions = async (config, testMode) => {
+  try {
+    const diffData = getOptimizedGitDiff();
+    if (!diffData) {
+      return [];
+    }
+
+    const apiKey = envUtils.getEnvKey(config.ai.envPath, config.ai.envKeyName);
+    if (!apiKey) {
+      utils.log('AI API key not found in .env', 'warning');
+      return [];
+    }
+
+    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 !== 4) {
+      throw new Error('Invalid AI response format');
+    }
+
+    const validSuggestions = suggestions.filter(s => validateSuggestion(s, config));
+
+    if (validSuggestions.length < 4) {
+      utils.log('Some AI suggestions were invalid', 'warning');
+      return [];
+    }
+
+    return validSuggestions;
+
+  } catch (error) {
+    utils.log(`AI suggestion failed: ${error.message}`, 'warning');
+    return [];
+  }
+};
+
+export {
+  generateCommitSuggestions,
+};