Adding support for two new 'When' values: 'always-in-non-wips' and 'never-in-non-wips' to allow rules to be configured for just non-WIPs.

This new functionality currently cannot be used since commitlint prevents custom 'When' values in its top-level linter, but the work had already been done so checking this in in case in future this changes.

I created a GitHub Issue asking about that possibility: conventional-changelog/commitlint#1003.

Author: danrivett

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

@@ -22,16 +22,16 @@ const supportedTypes = [
 
 export const commitlintConfigGitHub: CommitlintConfigGitHub = {
   rules: {
-    [commitlintGitHubRules.issueNumberMissing]: [2, When.NEVER],
+    [commitlintGitHubRules.issueNumberMissing]: [2, When.NON_WIPS_NEVER],
     [commitlintGitHubRules.issueNumberFormat]: [2, When.ALWAYS],
     [commitlintGitHubRules.issueNumberDuplicate]: [2, When.NEVER],
 
     [commitlintGitHubRules.wipAllowed]: [2, When.ALWAYS],
 
-    [commitlintGitHubRules.subjectEmpty]: [2, When.NEVER],
+    [commitlintGitHubRules.subjectEmpty]: [2, When.NON_WIPS_NEVER],
     [commitlintGitHubRules.subjectSeparator]: [2, When.ALWAYS],
-    [commitlintGitHubRules.subjectCase]: [2, When.ALWAYS, 'sentence-case'],
-    [commitlintGitHubRules.subjectFullStop]: [1, When.ALWAYS], // Warning only
+    [commitlintGitHubRules.subjectCase]: [2, When.NON_WIPS_ALWAYS, 'sentence-case'],
+    [commitlintGitHubRules.subjectFullStop]: [1, When.NON_WIPS_ALWAYS], // Warning only
 
     [commitlintGitHubRules.typeCase]: [2, When.ALWAYS, 'lower-case'],
     [commitlintGitHubRules.typeEnum]: [2, When.ALWAYS, supportedTypes],

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

@@ -52,6 +52,8 @@ export const enum When {
   ALWAYS = 'always',
   NEVER = 'never',
   IGNORED = 'ignored', // For when the rule doesn't vary based on the 'when' value passed in
+  NON_WIPS_ALWAYS = 'always-in-non-wips',
+  NON_WIPS_NEVER = 'never-in-non-wips',
 }
 
 // TODO: Remove once @commitlint/types is published

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

@@ -1,22 +1,32 @@
 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
+ * Handles both short-circuiting WIP commits to return as valid if the whenPassedIn is only applicable to non-WIPs (e.g. NON_WIPS_ALWAYS, NON_WIPS_NEVER).
+ * Also handles converting those Whens if the commit isn't a WIP, and so returns NEVER when given NON_WIPS_NEVER or ALWAYS otherwise.
+ * This is so that standard rules can use the standard When values and not deal with NON_WIPS_* When values.
  *
  * @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 };
+function handleWipCommits(commitMessage: ParsedCommitMessage, whenPassedIn?: When): WipHandledResult {
+  let when = whenPassedIn;
+
+  // Handle the non-wips 'when' if specified as it is custom and not intended to be passed to a base rule resolver
+  if (when === When.NON_WIPS_ALWAYS || when === When.NON_WIPS_NEVER) {
+    // If the commit is a WIP commit we don't validate as requested not to by the When
+    if (commitMessage.isWip) {
+      return { isWipValidated: true };
+    }
+
+    // Otherwise the commit the commit isn't a WIP so we just need to convert the non-wips 'when'
+    // to the corresponding standard 'when' for the baseResolver to understand.
+    if (when === When.NON_WIPS_ALWAYS) {
+      when = When.ALWAYS;
+    } else {
+      when = When.NEVER;
+    }
   }
 
   return { isWipValidated: false, when };

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

@@ -16,17 +16,32 @@ const NON_WIP_COMMIT: ParsedCommitMessage = {
 };
 
 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 validated when passed a WIP Commit and the "When" clause is only for non-WIPs', () => {
+    expect(handleWipCommits(WIP_COMMIT, When.NON_WIPS_ALWAYS).isWipValidated).toBe(true);
+    expect(handleWipCommits(WIP_COMMIT, When.NON_WIPS_NEVER).isWipValidated).toBe(true);
   });
 
-  it('should return not validated when passed a non-WIP Commit regardless of the "When" clause', () => {
+  it('should return not validated when passed a non-WIP Commit and the "When" clause is only for non-WIPs', () => {
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NON_WIPS_ALWAYS).isWipValidated).toBe(false);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NON_WIPS_NEVER).isWipValidated).toBe(false);
+  });
+
+  it('should return not validated when passed a WIP and non-WIP Commits and the "When" clause is not just for non-WIPs', () => {
+    expect(handleWipCommits(WIP_COMMIT, When.ALWAYS).isWipValidated).toBe(false);
+    expect(handleWipCommits(WIP_COMMIT, When.NEVER).isWipValidated).toBe(false);
+    expect(handleWipCommits(WIP_COMMIT, When.IGNORED).isWipValidated).toBe(false);
+
     expect(handleWipCommits(NON_WIP_COMMIT, When.ALWAYS).isWipValidated).toBe(false);
     expect(handleWipCommits(NON_WIP_COMMIT, When.NEVER).isWipValidated).toBe(false);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.IGNORED).isWipValidated).toBe(false);
+  });
+
+  it('should return the corresponding "standard" When when passed a non-WIP Commit and the "When" clause is only for non-WIPs', () => {
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NON_WIPS_ALWAYS).when).toBe(When.ALWAYS);
+    expect(handleWipCommits(NON_WIP_COMMIT, When.NON_WIPS_NEVER).when).toBe(When.NEVER);
   });
 
-  it('should return the When passed in when passed a non-WIP Commit regardless of the "When" clause', () => {
+  it('should return the existing "standard" When when passed a non-WIP Commit and the "When" clause is already standard', () => {
     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-plugin-github-rules/src/rules/githubIssueNumbers/isCorrectFormat.ts

@@ -7,11 +7,6 @@ const githubIssueNumberFormatRuleResolver: RuleResolver<void> = parsed => {
 
   const commitMessage = utils.parseCommitMessage(rawCommitMessage);
 
-  // We short circuit and return true for WIP commits since we don't valdiate those
-  if (commitMessage.isWip) {
-    return [true];
-  }
-
   const issueNumbersValid = commitMessage.rawIssueNumbers == null || commitMessage.issueNumbers.length > 0;
 
   return [

packages/commitlint-plugin-github-rules/src/rules/githubIssueNumbers/isDuplicate.ts

@@ -9,11 +9,6 @@ const githubIssueNumberDuplicateRuleResolver: RuleResolver<void> = parsed => {
 
   const commitMessage = utils.parseCommitMessage(rawCommitMessage);
 
-  // We short circuit and return true for WIP commits since we don't valdiate those
-  if (commitMessage.isWip) {
-    return [true];
-  }
-
   const issueNumbersValid = commitMessage.rawIssueNumbers == null || isNoDuplicates(commitMessage.issueNumbers);
 
   return [issueNumbersValid, 'the commit message duplicate issue numbers referenced in the commit message prefix.'];

packages/commitlint-plugin-github-rules/src/rules/githubIssueNumbers/isMissing.ts

@@ -8,23 +8,34 @@ const githubIssueNumberMissingRuleResolver: RuleResolver<boolean> = (parsed, whe
 
   const commitMessage = utils.parseCommitMessage(rawCommitMessage);
 
-  // We short circuit and return true for WIP commits since we don't valdiate those
-  if (commitMessage.isWip) {
+  const issueNumbersFound = commitMessage.rawIssueNumbers != null;
+
+  // If we're only required to validate non-WIPs and the commit is a WIP then just return true
+  if (commitMessage.isWip && (when === When.NON_WIPS_ALWAYS || when === When.NON_WIPS_NEVER)) {
     return [true];
   }
 
-  const issueNumbersFound = commitMessage.rawIssueNumbers != null;
-
   // First check for the standard case where no issue numbers are found and it is required to never be missing
-  if (!issueNumbersFound && when === When.NEVER) {
+  if (!issueNumbersFound && (when === When.NEVER || when === When.NON_WIPS_NEVER)) {
+    if (commitMessage.isWip) {
+      return [
+        false,
+        'the WIP commit message must start with the associated GitHub issue number in parentheses followed by space. For example: (#42) WIP: My git commit message.',
+      ];
+    }
+
     return [
       false,
       'the commit message must start with the associated GitHub issue number in parentheses followed by space. For example: (#42) My git commit message.',
     ];
   }
 
   // Next check the odd case of when issue numbers are found but it was required to always be missing
-  if (issueNumbersFound && when === When.ALWAYS) {
+  if (issueNumbersFound && (when === When.ALWAYS || when === When.NON_WIPS_ALWAYS)) {
+    if (commitMessage.isWip) {
+      return [false, 'the WIP commit message must NOT start with the associated GitHub issue number in parentheses.'];
+    }
+
     return [false, 'the commit message must NOT start with the associated GitHub issue number in parentheses.'];
   }
 

packages/commitlint-plugin-github-rules/src/rules/githubIssueNumbers/tests/isCorrectFormat.test.ts

@@ -11,11 +11,14 @@ describe('githubIssueNumberFormatRuleResolver', () => {
   it('should always return an error response if an empty commit message is provided', () => {
     expect(parse(When.ALWAYS, '')[0]).toEqual(false);
     expect(parse(When.NEVER, '')[0]).toEqual(false);
+    expect(parse(When.NON_WIPS_ALWAYS, '')[0]).toEqual(false);
+    expect(parse(When.NON_WIPS_NEVER, '')[0]).toEqual(false);
   });
 
   it('should return a success response if one issue number is specified', () => {
     expect(parse(When.ALWAYS, '(#1) my commit message')[0]).toEqual(true);
     expect(parse(When.ALWAYS, '(#1) chore: my commit message')[0]).toEqual(true);
+    expect(parse(When.ALWAYS, '(#1) WIP: my commit message')[0]).toEqual(true);
   });
 
   it('should return a success response if multiple issue numbers are specified', () => {
@@ -24,44 +27,40 @@ describe('githubIssueNumberFormatRuleResolver', () => {
 
     expect(parse(When.ALWAYS, '(#1, #2) chore: my commit message')[0]).toEqual(true);
     expect(parse(When.ALWAYS, '(#1,#2) chore: my commit message')[0]).toEqual(true);
+
+    expect(parse(When.ALWAYS, '(#1, #2) WIP: my commit message')[0]).toEqual(true);
+    expect(parse(When.ALWAYS, '(#1,#2) WIP: my commit message')[0]).toEqual(true);
   });
 
   it('should return a success response if no issue numbers are specified (as nothing to validate)', () => {
     expect(parse(When.ALWAYS, 'my commit message')[0]).toEqual(true);
     expect(parse(When.ALWAYS, 'chore: my commit message')[0]).toEqual(true);
+    expect(parse(When.ALWAYS, 'WIP: my commit message')[0]).toEqual(true);
   });
 
   it('should return an error response if not in correct format', () => {
     expect(parse(When.ALWAYS, '(1) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(1) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.ALWAYS, '(1) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.ALWAYS, '(bob) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(bob) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.ALWAYS, '(bob) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.ALWAYS, '(#bob) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(#bob) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.ALWAYS, '(#bob) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.ALWAYS, '(#1, #2bob) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(#1, #2bob) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.ALWAYS, '(#1, #2bob) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.ALWAYS, '(#1,#2bob) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(#1,#2bob) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.ALWAYS, '(#1,#2bob) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.ALWAYS, '(#1, #2 bob) my commit message')[0]).toEqual(false);
     expect(parse(When.ALWAYS, '(#1, #2 bob) chore: my commit message')[0]).toEqual(false);
-  });
-
-  it('should always return a success response for any WIP commit as rules are disabled for WIPs', () => {
-    expect(parse(When.ALWAYS, '(#1) WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, '(#1, #2) WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, '(#1,#2) WIP: my commit message')[0]).toEqual(true);
-
-    expect(parse(When.ALWAYS, 'WIP')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP2')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP2: My commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP 2: My commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP2 - My commit message')[0]).toEqual(true);
-    expect(parse(When.ALWAYS, 'WIP 2 - My commit message')[0]).toEqual(true);
+    expect(parse(When.ALWAYS, '(#1, #2 bob) WIP: my commit message')[0]).toEqual(false);
   });
 });

packages/commitlint-plugin-github-rules/src/rules/githubIssueNumbers/tests/isDuplicate.test.ts

@@ -11,46 +11,43 @@ describe('githubIssueNumberDuplicateRuleResolver', () => {
   it('should always return an error response if an empty commit message is provided', () => {
     expect(parse(When.ALWAYS, '')[0]).toEqual(false);
     expect(parse(When.NEVER, '')[0]).toEqual(false);
+    expect(parse(When.NON_WIPS_ALWAYS, '')[0]).toEqual(false);
+    expect(parse(When.NON_WIPS_NEVER, '')[0]).toEqual(false);
   });
 
   it('should return a success response if there are no duplicates', () => {
     expect(parse(When.NEVER, '(#1) my commit message')[0]).toEqual(true);
     expect(parse(When.NEVER, '(#1) chore: my commit message')[0]).toEqual(true);
+    expect(parse(When.NEVER, '(#1) WIP: my commit message')[0]).toEqual(true);
 
     expect(parse(When.NEVER, '(#1, #2) my commit message')[0]).toEqual(true);
     expect(parse(When.NEVER, '(#1,#2) my commit message')[0]).toEqual(true);
 
     expect(parse(When.NEVER, '(#123, #23) chore: my commit message')[0]).toEqual(true);
     expect(parse(When.NEVER, '(#123,#23) chore: my commit message')[0]).toEqual(true);
+
+    expect(parse(When.NEVER, '(#1, #2, #3, #4) WIP: my commit message')[0]).toEqual(true);
+    expect(parse(When.NEVER, '(#1,#2,#3,#4) WIP: my commit message')[0]).toEqual(true);
   });
 
   it('should return a success response if there are no issue numbers', () => {
+    expect(parse(When.NEVER, 'WIP: my commit message')[0]).toEqual(true);
     expect(parse(When.NEVER, 'my commit message')[0]).toEqual(true);
     expect(parse(When.NEVER, '() chore: my commit message')[0]).toEqual(true);
   });
 
   it('should return an error response if there is at least one duplicate', () => {
     expect(parse(When.NEVER, '(#123, #2, #123) my commit message')[0]).toEqual(false);
     expect(parse(When.NEVER, '(#1, #1) chore: my commit message')[0]).toEqual(false);
+    expect(parse(When.NEVER, '(#12, #12, #1) WIP: my commit message')[0]).toEqual(false);
 
     expect(parse(When.NEVER, '(#133, #133) my commit message')[0]).toEqual(false);
     expect(parse(When.NEVER, '(#122,#122) my commit message')[0]).toEqual(false);
 
     expect(parse(When.NEVER, '(#123, #123) chore: my commit message')[0]).toEqual(false);
     expect(parse(When.NEVER, '(#123,#123) chore: my commit message')[0]).toEqual(false);
-  });
 
-  it('should always return a success response for any WIP commit as rules are disabled for WIPs', () => {
-    expect(parse(When.NEVER, '(#1) WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, '(#1, #2) WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, '(#1,#2) WIP: my commit message')[0]).toEqual(true);
-
-    expect(parse(When.NEVER, 'WIP')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP2')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP: my commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP2: My commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP 2: My commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP2 - My commit message')[0]).toEqual(true);
-    expect(parse(When.NEVER, 'WIP 2 - My commit message')[0]).toEqual(true);
+    expect(parse(When.NEVER, '(#1, #2, #3, #2, #4) WIP: my commit message')[0]).toEqual(false);
+    expect(parse(When.NEVER, '(#1,#2,#3,#2,#4) WIP: my commit message')[0]).toEqual(false);
   });
 });