feat(commitlint): enhance prompt templates for commit message generation

The commit message generation process has been improved by introducing
new prompt templates that provide clearer guidelines and structure for
creating commit messages. This includes a more detailed system prompt
that outlines the requirements and conventions, as well as user prompts
that specify the expected output format. These changes aim to enhance
the accuracy and consistency of generated commit messages, ensuring
they adhere to the specified commitlint rules and conventions.

Author: cometjc

src/modules/commitlint/prompts.ts

@@ -11,7 +11,13 @@ import {
 
 import { getConfig } from '../../commands/config';
 import { i18n, I18nLocals } from '../../i18n';
-import { IDENTITY, INIT_DIFF_PROMPT, getConsistencyContent } from '../../prompts';
+import {
+  INIT_DIFF_PROMPT,
+  getConsistencyContent,
+  getSharedGuidelines,
+  SharedGuidelines,
+  getCommitStructure
+} from '../../prompts';
 
 const config = getConfig();
 const translation = i18n[(config.OCO_LANGUAGE as I18nLocals) || 'en'];
@@ -197,20 +203,71 @@ export const inferPromptsFromCommitlintConfig = (
     .filter((prompt) => prompt !== null) as string[];
 };
 
-/**
- * Breaking down commit message structure for conventional commit, and mapping bits with
- * ubiquitous language from @commitlint.
- * While gpt-4 does this on it self, gpt-3.5 can't map this on his own atm.
- */
-const STRUCTURE_OF_COMMIT = config.OCO_OMIT_SCOPE
-  ? `
-- Header of commit is composed of type and subject: <type-of-commit>: <subject-of-commit>
-- Description of commit is composed of body and footer (optional): <body-of-commit>\n<footer(s)-of-commit>`
-  : `
-- Header of commit is composed of type, scope, subject: <type-of-commit>(<scope-of-commit>): <subject-of-commit>
-- Description of commit is composed of body and footer (optional): <body-of-commit>\n<footer(s)-of-commit>`;
-
-// Prompt to generate LLM-readable rules based on @commitlint rules.
+const SYSTEM_PROMPT_TEMPLATE = (language: string) => {
+  const guidelines: SharedGuidelines = getSharedGuidelines(language, true, false);
+
+  return `${guidelines.missionBase} and maintains the style of the reference message.
+
+Here are the specific requirements and conventions that should be strictly followed:
+
+Message Structure:
+${getCommitStructure(guidelines.headerFormat)}
+
+${guidelines.guidelinesSection}
+
+Commit Rules:
+\${rules}
+
+Additional Requirements:
+\${requirements}
+
+Output Format:
+- Generate a single commit message that:
+  1. Follows all commitlint rules above
+  2. Maintains the style and features of the reference message
+  3. Follows the specific requirements above
+- The message should be a complete, valid commit message that would pass commitlint validation
+- Do not include any JSON formatting or additional text
+- The message should be ready to use as a git commit message`;
+};
+
+const INIT_MAIN_SYSTEM_TEMPLATE = (language: string) => {
+  const guidelines: SharedGuidelines = getSharedGuidelines(language, true, true);
+
+  return `${guidelines.missionBase}
+
+Message Structure:
+${getCommitStructure(guidelines.headerFormat)}
+
+${guidelines.guidelinesSection}
+
+Commit Rules:
+\${rules}`;
+};
+
+const USER_PROMPT_TEMPLATE = `Example Git Diff is to follow:
+\`\`\`
+\${gitDiff}
+\`\`\`
+
+Reference Message Style:
+\${referenceStyle}`;
+
+interface PromptTemplateVars {
+  rules: string;
+  requirements: string;
+  referenceStyle: string;
+  gitDiff: string;
+}
+
+const replaceTemplateVars = (template: string, vars: PromptTemplateVars): string => {
+  return template
+    .replace(/\${rules}/g, vars.rules)
+    .replace(/\${requirements}/g, vars.requirements)
+    .replace(/\${referenceStyle}/g, vars.referenceStyle)
+    .replace(/\${gitDiff}/g, vars.gitDiff);
+};
+
 const GEN_COMMITLINT_CONSISTENCY_PROMPT = (
   prompts: string[]
 ): OpenAI.Chat.Completions.ChatCompletionMessageParam[] => {
@@ -230,76 +287,49 @@ const GEN_COMMITLINT_CONSISTENCY_PROMPT = (
       : '- Do not use emoji'
   ].join('\n');
 
-  return [
-    {
-      role: 'system',
-      content: `${IDENTITY} Your mission is to create a clean and comprehensive commit message that follows both the commitlint rules and maintains the style of the reference message.
-
-Here are the specific requirements and conventions that should be strictly followed:
-
-Commit Message Conventions:
-- The commit message consists of three parts: Header, Body, and Footer.
-- Header:
-  - Format: ${config.OCO_OMIT_SCOPE ? '`<type>: <subject>`' : '`<type>(<scope>): <subject>`'}
-- ${prompts.join('\n- ')}
+  const rules = prompts.map(p => `- ${p}`).join('\n');
 
-${dynamicRequirements}
-
-Reference Message Style:
-${defaultContent}
+  const templateVars: PromptTemplateVars = {
+    rules,
+    requirements: dynamicRequirements,
+    referenceStyle: defaultContent,
+    gitDiff: String(INIT_DIFF_PROMPT.content || '')
+  };
 
-Output Format:
-- Generate a single commit message that:
-  1. Follows all commitlint rules above
-  2. Maintains the style and features of the reference message
-  3. Follows the specific requirements above
-- The message should be a complete, valid commit message that would pass commitlint validation
-- Do not include any JSON formatting or additional text
-- The message should be ready to use as a git commit message
+  const systemContent = replaceTemplateVars(
+    SYSTEM_PROMPT_TEMPLATE(translation.localLanguage),
+    templateVars
+  );
 
-Example Git Diff is to follow:`
-    },
-    INIT_DIFF_PROMPT
+  return [
+    { role: 'system', content: systemContent },
+    {
+      role: 'user',
+      content: replaceTemplateVars(USER_PROMPT_TEMPLATE, templateVars)
+    }
   ];
 };
 
-/**
- * Prompt to have LLM generate a message using @commitlint rules.
- *
- * @param language
- * @param prompts
- * @returns
- */
 const INIT_MAIN_PROMPT = (
   language: string,
   prompts: string[]
-): OpenAI.Chat.Completions.ChatCompletionMessageParam => ({
-  role: 'system',
-  content: `${IDENTITY} Your mission is to create clean and comprehensive commit messages in the given @commitlint convention and explain WHAT were the changes ${config.OCO_WHY ? 'and WHY the changes were done' : ''
-    }. I'll send you an output of 'git diff --staged' command, and you convert it into a commit message.
-${config.OCO_EMOJI
-      ? 'Use GitMoji convention to preface the commit.'
-      : 'Do not preface the commit with anything.'
-    }
-${config.OCO_DESCRIPTION
-      ? 'Add a short description of WHY the changes are done after the commit message. Don\'t start it with "This commit", just describe the changes.'
-      : "Don't add any descriptions to the commit, only commit message."
-    }
-Use the present tense. Use ${language} to answer.
-${config.OCO_ONE_LINE_COMMIT
-      ? 'Craft a concise commit message that encapsulates all changes made, with an emphasis on the primary updates. If the modifications share a common theme or scope, mention it succinctly; otherwise, leave the scope out to maintain focus. The goal is to provide a clear and unified overview of the changes in a one single message, without diverging into a list of commit per file change.'
-      : ''
-    }
-${config.OCO_OMIT_SCOPE
-      ? 'Do not include a scope in the commit message format. Use the format: <type>: <subject>'
-      : ''
-    }
-You will strictly follow the following conventions to generate the content of the commit message:
-- ${prompts.join('\n- ')}
-`
-});
+): OpenAI.Chat.Completions.ChatCompletionMessageParam => {
+  const rules = prompts.map(p => `- ${p}`).join('\n');
+
+  const templateVars: PromptTemplateVars = {
+    rules,
+    requirements: '',
+    referenceStyle: '',
+    gitDiff: ''
+  };
+
+  return {
+    role: 'system',
+    content: replaceTemplateVars(INIT_MAIN_SYSTEM_TEMPLATE(language), templateVars)
+  };
+};
 
 export const commitlintPrompts = {
   INIT_MAIN_PROMPT,
   GEN_COMMITLINT_CONSISTENCY_PROMPT
-};
+};

src/prompts.ts

@@ -11,9 +11,16 @@ import { removeConventionalCommitWord } from './utils/removeConventionalCommitWo
 const config = getConfig();
 const translation = i18n[(config.OCO_LANGUAGE as I18nLocals) || 'en'];
 
-export const IDENTITY =
-  'You are to act as an author of a commit message in git.';
 
+
+
+export interface SharedGuidelines {
+  missionBase: string;
+  guidelinesSection: string;
+  headerFormat: string;
+}
+
+// Internal constants
 const GITMOJI_HELP = `Use GitMoji convention to preface the commit. Here are some help to choose the right emoji (emoji, description): 
 🐛, Fix a bug; 
 ✨, Introduce new features; 
@@ -94,6 +101,7 @@ const FULL_GITMOJI_SPEC = `${GITMOJI_HELP}
 const CONVENTIONAL_COMMIT_KEYWORDS =
   'Do not preface the commit with anything, except for the conventional commit keywords: fix, feat, build, chore, ci, docs, style, refactor, perf, test.';
 
+// Internal helper functions
 const getCommitConvention = (fullGitMojiSpec: boolean) =>
   config.OCO_EMOJI
     ? fullGitMojiSpec
@@ -116,41 +124,77 @@ const getScopeInstruction = () =>
     ? 'Do not include a scope in the commit message format. Use the format: <type>: <subject>'
     : '';
 
-/**
- * Get the context of the user input
- * @param extraArgs - The arguments passed to the command line
- * @example
- *  $ oco -- This is a context used to generate the commit message
- * @returns - The context of the user input
- */
 const userInputCodeContext = (context: string) => {
   if (context !== '' && context !== ' ') {
     return `Additional context provided by the user: <context>${context}</context>\nConsider this context when generating the commit message, incorporating relevant information when appropriate.`;
   }
   return '';
 };
 
+const IDENTITY = 'You are to act as an author of a commit message in git.';
+
+const getMissionStatement = (commitConvention: string, includeWhy = true) =>
+  `${IDENTITY} Your mission is to create clean and comprehensive commit messages as per the ${commitConvention}${includeWhy ? ' and explain WHAT were the changes and mainly WHY the changes were done' : ''}.`;
+
+const getGeneralGuidelines = (language: string) =>
+  `Use the present tense. Lines must not be longer than 74 characters. Use ${language} for the commit message.`;
+
+const getCommitConventionName = (fullGitMojiSpec: boolean) =>
+  fullGitMojiSpec ? 'GitMoji specification' : 'Conventional Commit Convention';
+
+/**
+ * Breaking down commit message structure for conventional commit, and mapping bits with
+ * ubiquitous language from @commitlint.
+ * While gpt-4 does this on it self, gpt-3.5 can't map this on his own atm.
+ */
+export const getHeaderFormat = () =>
+  config.OCO_OMIT_SCOPE ? '`<type>: <subject>`' : '`<type>(<scope>): <subject>`';
+
+export const getHeaderParts = () =>
+  config.OCO_OMIT_SCOPE
+    ? ['type', 'subject']
+    : ['type', 'scope', 'subject'];
+
+export const getCommitStructure = (headerFormat: string) => {
+  const headerParts = getHeaderParts();
+
+  return `
+- Header of commit is composed of ${headerParts.join(', ')}: ${headerFormat}
+- Description of commit is composed of body and footer (optional): <body-of-commit>\n<footer(s)-of-commit>`;
+};
+
+// Public function that encapsulates all the guidelines
+export const getSharedGuidelines = (language: string, useFullGitMojiSpec = false, includeWhy = true): SharedGuidelines => {
+  const commitConvention = getCommitConventionName(useFullGitMojiSpec);
+  const missionBase = getMissionStatement(commitConvention, includeWhy);
+  const headerFormat = getHeaderFormat();
+
+  const guidelinesSection = `Commit Message Guidelines:
+${getCommitConvention(useFullGitMojiSpec)}
+${getDescriptionInstruction()}
+${getOneLineCommitInstruction()}
+${getScopeInstruction()}
+${getGeneralGuidelines(language)}`;
+
+  return {
+    missionBase,
+    guidelinesSection,
+    headerFormat
+  };
+};
+
+const DIFF_INSTRUCTION = "I'll send you an output of 'git diff --staged' command, and you are to convert it into a commit message.";
 const INIT_MAIN_PROMPT = (
   language: string,
   fullGitMojiSpec: boolean,
   context: string
 ): OpenAI.Chat.Completions.ChatCompletionMessageParam => ({
   role: 'system',
   content: (() => {
-    const commitConvention = fullGitMojiSpec
-      ? 'GitMoji specification'
-      : 'Conventional Commit Convention';
-    const missionStatement = `${IDENTITY} Your mission is to create clean and comprehensive commit messages as per the ${commitConvention} and explain WHAT were the changes and mainly WHY the changes were done.`;
-    const diffInstruction =
-      "I'll send you an output of 'git diff --staged' command, and you are to convert it into a commit message.";
-    const conventionGuidelines = getCommitConvention(fullGitMojiSpec);
-    const descriptionGuideline = getDescriptionInstruction();
-    const oneLineCommitGuideline = getOneLineCommitInstruction();
-    const scopeInstruction = getScopeInstruction();
-    const generalGuidelines = `Use the present tense. Lines must not be longer than 74 characters. Use ${language} for the commit message.`;
+    const guidelines = getSharedGuidelines(language, fullGitMojiSpec, true);
     const userInputContext = userInputCodeContext(context);
 
-    return `${missionStatement}\n${diffInstruction}\n${conventionGuidelines}\n${descriptionGuideline}\n${oneLineCommitGuideline}\n${scopeInstruction}\n${generalGuidelines}\n${userInputContext}`;
+    return `${guidelines.missionBase}\n${DIFF_INSTRUCTION}\n${guidelines.guidelinesSection}\n${userInputContext}`;
   })()
 });