format-commit 1.0.0 → 1.1.0

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 & and optional AI support.
+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. Feel free to let AI suggest commit titles for you in the expected format.
+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,39 +41,107 @@ 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 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:<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`) |
+All configuration is stored in the `commit-config.json` file. Here is the list of all options.
 
-### AI Suggestions
+**`format`**
+
+Commit title format:
+- 1: `(type) Description` / 2: `(type) description`
+- 3: `type: Description` / 4: `type: description`
+- 5: `type(scope) Description` / 6: `type(scope) description`
+- 7: `type(scope): Description` / 8: `type(scope): description`
+- "custom"
+
+**`customFormat`**
+
+Custom commit format pattern. Uses keywords `type`, `scope`, `description` and custom field(s) with `{field}` placeholders. Keywords are case-sensitive.
+
+Example: `{Issue ID} - type - scope - Description`.
+
+**`branchFormat`**
+
+Branch naming format:
+- 1: `type/description`
+- 2: `type/scope/description`
+- "custom"
+
+**`customBranchFormat`**
+
+Custom branch format pattern. Uses keywords `type`, `scope`, `description` and custom fields with `{field}` placeholders. Keywords are case-sensitive. Separators must be valid in Git branch names (no spaces, `~`, `^`, `:`, `?`, `*`, `[`, `\`, `..` or `//`). Dynamic parts (description, custom fields) are automatically sanitized to be branch-safe.
+
+Example: `type/{Issue ID}-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, or when a custom format includes the `scope` keyword)
+
+**`minLength`**
+
+Minimum length required for the commit title.
+
+**`maxLength`**
+
+Maximum length required for the commit title and branch description.
+
+**`changeVersion`**
 
-| 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 |
+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, format-commit will analyze your staged changes and suggest 4 complete commit titles that:
+When AI is enabled, your staged changes will be processed by the defined model to suggest commit titles that:
 - Follow your configured format and naming conventions
 - Automatically select appropriate types and scopes
 - Respect your min/max length constraints
@@ -84,15 +151,16 @@ 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`.
+**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` | Preview without executing Git commands |
+| `-d` | `--debug` | Display additional logs |
 
 ## Contributing
 

package/lib/ai-service.js

@@ -30,47 +30,48 @@ const getOptimizedGitDiff = () => {
 };
 
 /** Build AI prompt */
-const buildPrompt = (diffData, config) => {
-  const types = config.types.map(t => `${t.value} (${t.description})`).join(', ');
+const buildPrompt = (diffData, config, customFieldValues = {}) => {
+  const typesList = config.types.map(t => t.value).join(', ');
+  const types = config.types.map(t => `${t.value} is for ${t.description}`).join('\n   > ');
+  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(', ')
+    ? config.scopes.map(s => `${s.value} is for ${s.description}`).join('\n   > ')
     : 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',
+    'Description of changes',
     config.format,
-    config.scopes?.[0]?.value
+    config.scopes?.[0]?.value,
+    config.customFormat,
+    customFieldValues
   );
 
+  const formatHasScope = config.format === 'custom'
+    ? utils.customFormatHasScope(config.customFormat)
+    : config.format >= 5;
+
+  const changeable = formatHasScope ? 'type, scope and description' : 'type and description';
+  const scopeInstruction = formatHasScope ? `\n- ONLY use these scopes (do not invent one outside this list): ${scopesList}
+- Scope descriptions, to figure out which one to choose:\n   > ${scopes}` : '';
+
+  let template;
+  if (config.format === 'custom' && config.customFormat) {
+    const segments = utils.parseCustomFormat(config.customFormat);
+    template = segments.map(seg => {
+      if (seg.type === 'literal') { return seg.value; }
+      if (seg.type === 'field') { return customFieldValues[seg.label] || `{${seg.label}}`; }
+      if (seg.type === 'keyword') { return `<${seg.keyword}>`; }
+      return '';
+    }).join('');
+  } else {
+    template = utils.formatCommitTitle('<type>', '<description>', config.format, formatHasScope ? '<scope>' : undefined);
+  }
+
+  const formatInstruction = `- Format pattern: "${template}"
+- Example: "${exampleTitle}"
+- ONLY replace ${changeable} placeholders, keep everything else exactly as shown`;
+
   return `You must analyze git changes and return ONLY a valid JSON array. NO explanations, NO markdown, NO additional text.
 
 Git diff stats:
@@ -80,15 +81,16 @@ 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'}
+${formatInstruction}
+- ONLY use these types (do not invent one outside this list): ${typesList}
+- Type descriptions, to figure out which one to choose:\n   > ${types}${scopeInstruction}
 - 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
+- Output MUST be a raw JSON array
 
-YOUR RESPONSE MUST BE EXACTLY THIS FORMAT (no other text):
+If changes seem to concern very different things, suggest at least one title that attempts to be exhaustive on the most important points, using commas and/or "&". Avoid generic titles such as "Bug fixes and improvements".
+
+YOUR RESPONSE MUST BE EXACTLY THIS FORMAT (no other text before or after):
 ["title 1", "title 2", "title 3", "title 4"]`;
 };
 
@@ -182,89 +184,108 @@ const callGeminiAPI = async (prompt, apiKey, model) => {
   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);
-  });
+/** Validate and normalize AI suggestion */
+const validateAndNormalizeSuggestion = (suggestion, config, customFieldValues = {}) => {
+  const result = utils.parseAndNormalizeCommitTitle(suggestion, config, customFieldValues);
 
-  return hasValidType;
+  // 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) => {
-  try {
-    const diffData = getOptimizedGitDiff();
-    if (!diffData) {
-      return [];
-    }
+const generateCommitSuggestions = async (config, debugMode, customFieldValues = {}) => {
+  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 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 [];
-      }
-    }
+  const prompt = buildPrompt(diffData, config, customFieldValues);
+  const estimatedTokens = Math.ceil(prompt.length / 4);
+  const threshold = config.ai.largeDiffTokenThreshold || 20000;
 
-    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}`);
-    }
+  if (debugMode) {
+    utils.log('<`git diff`>\n\n' + prompt.slice(prompt.indexOf('STRICT REQUIREMENTS:')), 'debug');
+  }
 
-    const jsonMatch = responseText.match(/\[[\s\S]*\]/);
-    if (!jsonMatch) {
-      if (testMode) {
-        utils.log(responseText, 'warning');
-      }
-      throw new Error('No JSON array found in AI response');
+  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 [];
     }
+  }
 
-    const suggestions = JSON.parse(jsonMatch[0]);
+  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}`);
+  }
 
-    if (!Array.isArray(suggestions) || suggestions.length !== 4) {
-      throw new Error('Invalid AI response format');
+  const jsonMatch = responseText.match(/\[[\s\S]*\]/);
+  if (!jsonMatch) {
+    if (debugMode) {
+      utils.log(responseText, 'debug');
     }
+    throw new Error('No JSON array found in AI response');
+  }
 
-    const validSuggestions = suggestions.filter(s => validateSuggestion(s, config));
+  const suggestions = JSON.parse(jsonMatch[0]);
 
-    if (validSuggestions.length < 4) {
-      utils.log('Some AI suggestions were invalid', 'warning');
-      return [];
+  if (!Array.isArray(suggestions) || !suggestions.length) {
+    if (debugMode) {
+      utils.log(responseText, 'debug');
     }
+    throw new Error('Invalid AI response format');
+  }
 
-    return validSuggestions;
+  // Validate and normalize each suggestion
+  const validationResults = suggestions.map(s => ({
+    original: s,
+    normalized: validateAndNormalizeSuggestion(s, config, customFieldValues)
+  }));
+
+  // Log rejected suggestions in test mode
+  if (debugMode) {
+    validationResults.forEach(({ original, normalized }) => {
+      if (normalized === null) {
+        utils.log(`rejected: "${original}"`, 'debug');
+      }
+    });
+  }
 
-  } catch (error) {
-    utils.log(`AI suggestion failed: ${error.message}`, 'warning');
-    return [];
+  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 {