Updates to commitlint-github-utils largely to enhance the parser to better support different WIP formats

Author: danrivett

packages/commitlint-github-utils/@types/index.d.ts

@@ -1,6 +1,22 @@
 export interface Rules {
   issueNumberMissing: string;
   issueNumberFormat: string;
+  issueNumberDuplicate: string;
+
+  wipAllowed: string;
+
+  subjectEmpty: string;
+  subjectCase: string;
+  subjectFullStop: string;
+  subjectMinLength: string;
+  subjectMaxLength: string;
+  subjectSeparator: string;
+
+  typeCase: string;
+  typeEmpty: string;
+  typeEnum: string;
+  typeMaxLength: string;
+  typeMinLength: string;
 }
 
 export interface CommitlintGitHubConstants {
@@ -27,19 +43,44 @@ export type ParsedCommitMessage = {
   rawIssueNumbers?: string;
   isWip: boolean;
   type?: string;
+  subjectSeparator?: string;
   subject?: string;
   body: string[];
 };
 
-export type CommitParser = (unparsedCommitMessage: string, parserOptions?: ParserOptions) => ParsedCommitMessage;
+export const enum When {
+  ALWAYS = 'always',
+  NEVER = 'never',
+  IGNORED = 'ignored', // For when the rule doesn't vary based on the 'when' value passed in
+}
+
+// TODO: Remove once @commitlint/types is published
+export type TargetCaseType =
+  | 'camel-case'
+  | 'kebab-case'
+  | 'snake-case'
+  | 'pascal-case'
+  | 'start-case'
+  | 'upper-case'
+  | 'uppercase'
+  | 'sentence-case'
+  | 'sentencecase'
+  | 'lower-case'
+  | 'lowercase'
+  | 'lowerCase';
+
+export type WipHandledResult = {
+  isWipValidated: boolean;
+  when?: When;
+};
 
 export interface CommitlintGitHubUtils {
-  parseCommitMessage: CommitParser;
   commitlintGitHubConstants: CommitlintGitHubConstants;
-}
 
-export const commitlintGitHubConstants: CommitlintGitHubConstants;
-export const parseCommitMessage: CommitParser;
+  parseCommitMessage(unparsedCommitMessage: string, parserOptions?: ParserOptions): ParsedCommitMessage;
+  isNegated(when?: string): boolean;
+  handleWipCommits(commitMessage: ParsedCommitMessage, whenPassedIn?: When): WipHandledResult;
+}
 
 declare const commitlintGitHubUtils: CommitlintGitHubUtils;
 export default commitlintGitHubUtils;

packages/commitlint-github-utils/src/commitlintGitHubConstants.ts

@@ -1,15 +1,39 @@
 export const GITHUB_RULES = {
   issueNumberMissing: 'github-issue-number-missing',
   issueNumberFormat: 'github-issue-number-format',
-  typeOrWip: 'github-type-or-wip',
-  subjectCase: 'github-subject-case',
+  issueNumberDuplicate: 'github-issue-number-duplicate',
+
+  wipAllowed: 'wip-allowed',
+
+  // The following should match the base rule strings in @commitlint/rules:
+
+  subjectEmpty: 'subject-empty',
+  subjectCase: 'subject-case',
+  subjectFullStop: 'subject-full-stop',
+  subjectMinLength: 'subject-min-length',
+  subjectMaxLength: 'subject-max-length',
+  subjectSeparator: 'subject-separator',
+
+  typeEmpty: 'type-empty',
+  typeCase: 'type-case',
+  typeEnum: 'type-enum',
+  typeMaxLength: 'type-max-length',
+  typeMinLength: 'type-min-length',
 };
 
 export const ISSUE_NUMBER_PREFIX = '#';
 export const ISSUE_NUMBERS_SEPARATOR = ',';
 export const ISSUE_NUMBER_PATTERN = /^#(?<issueNumber>\d+)$/;
-export const ISSUE_NUMBERS_PATTERN = /^\((?<issues>.*?)\) (?:(?<type>.+?):)?(?<description>.*)/;
-export const WIP_WITHOUT_ISSUE_NUMBER_PATTERN = /^WIP:(?<description>.*)/;
+
+// Exclude matching 'WIP' as the start of a description using a negative look-ahead
+// Instead should match WIP_WITH_JUST_ISSUE_NUMBERS_PATTERN below
+export const ISSUE_NUMBERS_PATTERN = /^\((?<issues>.*?)\)(?: (?<type>.+?):)?(?!\s*WIP)(?<description>.*)/;
+
+// Allow WIPs to avoid specifying issue number as should only exist on feature branches which are per issue
+// Allow either 'WIP: ...', 'WIP - ...', 'WIP2', 'WIP 2', 'WIP 2: ...', 'WIP 2 - ...' etc.
+export const WIP_WITHOUT_ISSUE_NUMBER_PATTERN = /^WIP(?:\s*\d+)?(?:(?:\.|:|(?:\s*-))(?<description>.*))?$/;
+export const WIP_WITH_JUST_ISSUE_NUMBERS_PATTERN = /^\((?<issues>.*?)\) WIP\b/;
+export const SUBJECT_PATTERN = /^(?<subjectSeparator>\s*)?(?<subject>.*)/;
 export const WIP_TYPE = 'WIP';
 export const TYPE_SEPARATOR = ':';
 export const COMMIT_DESCRIPTION_SEPARATOR = '\n';

packages/commitlint-github-utils/src/handleWipCommits.ts

@@ -0,0 +1,25 @@
+import { ParsedCommitMessage, When, WipHandledResult } from '../@types';
+
+/**
+ * Handles short-circuiting WIP commits to immediately return as valid. Previsouly it also converted the if the when passed in
+ * when we had custom When values to allow rules to be configured to only be applicable to non-WIPs (e.g. NON_WIPS_ALWAYS, NON_WIPS_NEVER).
+ * However commitlint currently restricts When values in the top-level configuration to just 'always' and 'never' and rejects configuration
+ * with any other value.
+ *
+ * Therefore we have stripped out support for custom When values until a time when they may be supported (or not):
+ * See: https://github.com/conventional-changelog/commitlint/issues/1003
+ *
+ * @param commitMessage the parsed commit message
+ * @param whenPassedIn the When passed in
+ * @returns { isWipValidated: true } if the When given only applies to non-WIP commits and the commit is a WIP;
+ * or { isWipValidated: false, when } with the When to apply to the non-WIP, see description above.
+ */
+function handleWipCommits(commitMessage: ParsedCommitMessage, when?: When): WipHandledResult {
+  if (commitMessage.isWip) {
+    return { isWipValidated: true };
+  }
+
+  return { isWipValidated: false, when };
+}
+
+export default handleWipCommits;

packages/commitlint-github-utils/src/index.ts

@@ -1,11 +1,15 @@
+import { CommitlintGitHubUtils, When } from '../@types';
 import * as commitlintGitHubConstants from './commitlintGitHubConstants';
 import parseCommitMessage from './parseCommitMessage';
-import { CommitlintGitHubUtils } from '../@types';
+import handleWipCommits from './handleWipCommits';
+
+const isNegated = (when?: When): boolean => when === When.NEVER;
 
 const commitlintGitHubUtils: CommitlintGitHubUtils = {
   commitlintGitHubConstants,
   parseCommitMessage,
+  isNegated,
+  handleWipCommits,
 };
 
-export { commitlintGitHubConstants, parseCommitMessage };
 export default commitlintGitHubUtils;

packages/commitlint-github-utils/src/parseCommitMessage.ts

@@ -1,28 +1,30 @@
-import { CommitParser, ParsedCommitMessage } from '../@types';
+import { ParsedCommitMessage } from '../@types';
 import {
   ISSUE_NUMBER_PATTERN,
   ISSUE_NUMBERS_PATTERN,
   WIP_WITHOUT_ISSUE_NUMBER_PATTERN,
+  WIP_WITH_JUST_ISSUE_NUMBERS_PATTERN,
+  SUBJECT_PATTERN,
   ISSUE_NUMBERS_SEPARATOR,
   WIP_TYPE,
   COMMIT_DESCRIPTION_SEPARATOR,
 } from './commitlintGitHubConstants';
 
-const parseRegex = (stringToParse: string, regex: RegExp): { [key: string]: string } | undefined => {
+function parseRegex(stringToParse: string, regex: RegExp): { [key: string]: string } | undefined {
   return regex.exec(stringToParse)?.groups;
-};
+}
 
-const parseIssue = (issueString: string): number => {
+function parseIssue(issueString: string): number {
   const groupsMatched = ISSUE_NUMBER_PATTERN.exec(issueString.trim())?.groups;
 
   if (groupsMatched) {
     return parseInt(groupsMatched.issueNumber, 10);
   }
 
   return -1;
-};
+}
 
-const parseIssues = (issuesString: string): number[] => {
+function parseIssues(issuesString: string): number[] {
   if (!issuesString) {
     return [];
   }
@@ -37,44 +39,66 @@ const parseIssues = (issuesString: string): number[] => {
 
   // Otherwise return an empty array
   return [];
-};
+}
 
-const parseDescription = (groups: { [key: string]: string }): [string, string[]] => {
+function parseDescription(groups: { [key: string]: string }): [string, string, string[]] {
   const descriptionLines = groups.description.split(COMMIT_DESCRIPTION_SEPARATOR);
 
-  const subject = descriptionLines[0].trim();
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const subjectGroups = parseRegex(descriptionLines[0], SUBJECT_PATTERN)!;
+
+  const { subjectSeparator } = subjectGroups;
+  const subject = subjectGroups.subject.trim(); // trims any trailing whitespace
   const body = descriptionLines.slice(1);
 
-  return [subject, body];
-};
+  return [subjectSeparator, subject, body];
+}
 
-const parseCommitMessage: CommitParser = (rawCommitMessage: string): ParsedCommitMessage => {
+function parseCommitMessage(rawCommitMessage: string): ParsedCommitMessage {
   let issueNumbers: number[] = [];
   let rawIssueNumbers: string | undefined;
   let type: string | undefined;
   let isWip = false;
+  let subjectSeparator: string | undefined;
   let subject: string | undefined;
   let body: string[] = [];
 
   const issueNumbersWithPossibleTypeGroups = parseRegex(rawCommitMessage, ISSUE_NUMBERS_PATTERN);
 
   if (issueNumbersWithPossibleTypeGroups) {
-    // console.log(`description: '${issueNumbersWithPossibleTypeGroups.description}'; raw: ${rawCommitMessage}`);
     rawIssueNumbers = issueNumbersWithPossibleTypeGroups.issues.trim();
     issueNumbers = parseIssues(rawIssueNumbers);
 
     // eslint-disable-next-line prefer-destructuring
     type = issueNumbersWithPossibleTypeGroups.type;
     isWip = type === WIP_TYPE;
 
-    [subject, body] = parseDescription(issueNumbersWithPossibleTypeGroups);
+    // Clear the type as WIP is not a valid type and can't easily be added since types are validated to be lowercase (WIP is the exception)
+    if (isWip) {
+      type = undefined;
+    }
+
+    [subjectSeparator, subject, body] = parseDescription(issueNumbersWithPossibleTypeGroups);
   } else {
+    // As well as WIP commits with a description
     const wipCommitGroups = parseRegex(rawCommitMessage, WIP_WITHOUT_ISSUE_NUMBER_PATTERN);
+
     if (wipCommitGroups) {
       isWip = true;
-      type = WIP_TYPE;
 
-      [subject, body] = parseDescription(wipCommitGroups);
+      // WIP Commits may not have a description but may just be WIP placeholder commits such as 'WIP', 'WIP 2' etc., so guard the parsing
+      if (wipCommitGroups.description) {
+        [subjectSeparator, subject, body] = parseDescription(wipCommitGroups);
+      }
+    } else {
+      const wipWithIssueNumbersGroups = parseRegex(rawCommitMessage, WIP_WITH_JUST_ISSUE_NUMBERS_PATTERN);
+
+      if (wipWithIssueNumbersGroups) {
+        isWip = true;
+
+        rawIssueNumbers = wipWithIssueNumbersGroups.issues.trim();
+        issueNumbers = parseIssues(rawIssueNumbers);
+      }
     }
   }
 
@@ -83,9 +107,10 @@ const parseCommitMessage: CommitParser = (rawCommitMessage: string): ParsedCommi
     rawIssueNumbers,
     isWip,
     type,
+    subjectSeparator,
     subject,
     body,
   };
-};
+}
 
 export default parseCommitMessage;

packages/commitlint-github-utils/src/tests/handleWipCommits.test.ts

@@ -0,0 +1,34 @@
+import handleWipCommits from '../handleWipCommits';
+import { ParsedCommitMessage, When } from '../../@types';
+
+const WIP_COMMIT: ParsedCommitMessage = {
+  issueNumbers: [],
+  isWip: true,
+  body: [],
+  subject: 'My WIP Commit',
+};
+
+const NON_WIP_COMMIT: ParsedCommitMessage = {
+  issueNumbers: [],
+  isWip: false,
+  body: [],
+  subject: 'My Non-WIP Commit',
+};
+
+describe('handleWipCommits', () => {
+  it('should return validated when passed a WIP Commit regardless of the "When" clause', () => {
+    expect(handleWipCommits(WIP_COMMIT, When.ALWAYS).isWipValidated).toBe(true);
+    expect(handleWipCommits(WIP_COMMIT, When.NEVER).isWipValidated).toBe(true);
+  });
+
+  it('should return not validated when passed a non-WIP Commit regardless of the "When" clause', () => {
+    expect(handleWipCommits(NON_WIP_COMMIT, When.ALWAYS).isWipValidated).toBe(false);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NEVER).isWipValidated).toBe(false);
+  });
+
+  it('should return the When passed in when passed a non-WIP Commit regardless of the "When" clause', () => {
+    expect(handleWipCommits(NON_WIP_COMMIT, When.ALWAYS).when).toBe(When.ALWAYS);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NEVER).when).toBe(When.NEVER);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.IGNORED).when).toBe(When.IGNORED);
+  });
+});

packages/commitlint-github-utils/src/tests/index.test.ts

@@ -1,8 +1,21 @@
-import { commitlintGitHubConstants, parseCommitMessage } from '../index';
+import utils from '../index';
 
 describe('commitlintPluginGitHub', () => {
   it('should return a expected exports', () => {
-    expect(commitlintGitHubConstants).not.toBeNull();
-    expect(parseCommitMessage).not.toBeNull();
+    expect(utils).not.toBeNull();
+    expect(utils.commitlintGitHubConstants).not.toBeNull();
+    expect(utils.parseCommitMessage).toBeInstanceOf(Function);
+    expect(utils.handleWipCommits).toBeInstanceOf(Function);
+    expect(utils.isNegated).toBeInstanceOf(Function);
+  });
+});
+
+describe('isNegated', () => {
+  it('should return true for "never"', () => {
+    expect(utils.isNegated('never')).toBe(true);
+  });
+
+  it('should return false for "always"', () => {
+    expect(utils.isNegated('always')).toBe(false);
   });
 });