Adding in subject rules and tests.

Author: danrivett

packages/commitlint-plugin-github-rules/src/index.ts

@@ -5,13 +5,29 @@ import githubIssueNumberMissingRuleResolver from './rules/githubIssueNumbers/isM
 import githubIssueNumberFormatRuleResolver from './rules/githubIssueNumbers/isCorrectFormat';
 import githubIssueNumberDuplicateRuleResolver from './rules/githubIssueNumbers/isDuplicate';
 
+import {
+  subjectEmptyRuleResolver,
+  subjectCaseRuleResolver,
+  subjectFullStopRuleResolver,
+  subjectMinLengthRuleResolver,
+  subjectMaxLengthRuleResolver,
+  subjectSeparatorRuleResolver,
+} from './rules/subject';
+
 const commitlintGitHubRules = utils.commitlintGitHubConstants.GITHUB_RULES;
 
 export const commitlintPluginGitHub: CommitlintPluginGitHub = {
   rules: {
     [commitlintGitHubRules.issueNumberMissing]: githubIssueNumberMissingRuleResolver,
     [commitlintGitHubRules.issueNumberFormat]: githubIssueNumberFormatRuleResolver,
     [commitlintGitHubRules.issueNumberDuplicate]: githubIssueNumberDuplicateRuleResolver,
+
+    [commitlintGitHubRules.subjectEmpty]: subjectEmptyRuleResolver,
+    [commitlintGitHubRules.subjectCase]: subjectCaseRuleResolver,
+    [commitlintGitHubRules.subjectFullStop]: subjectFullStopRuleResolver,
+    [commitlintGitHubRules.subjectMinLength]: subjectMinLengthRuleResolver,
+    [commitlintGitHubRules.subjectMinLength]: subjectMaxLengthRuleResolver,
+    [commitlintGitHubRules.subjectSeparator]: subjectSeparatorRuleResolver,
   },
 };
 

packages/commitlint-plugin-github-rules/src/rules/subject/helpers.ts

@@ -0,0 +1,21 @@
+import { ParsedCommitMessage } from 'commitlint-github-utils';
+
+import { BaseParsedCommit, RuleResolverResult, RuleResolver } from '../../../@types';
+import resolveRuleUsingBaseResolver from '../utils/wrappedRuleResolver';
+
+// TODO Get rewire to work or some other solution to avoid exporting subjectAdapter and subjectRuleResolver for testing
+
+export function subjectAdapter(parsed: ParsedCommitMessage): BaseParsedCommit {
+  return { subject: parsed.subject };
+}
+
+export function subjectRuleResolver<T>(baseRuleResolver: RuleResolver<T>, defaultValue?: T): RuleResolver<T> {
+  return (parsed, when, valuePassedIn): RuleResolverResult => {
+    let value = valuePassedIn;
+    if (value == null) {
+      value = defaultValue;
+    }
+
+    return resolveRuleUsingBaseResolver(baseRuleResolver, subjectAdapter, parsed, when, value);
+  };
+}

packages/commitlint-plugin-github-rules/src/rules/subject/index.ts

@@ -0,0 +1,44 @@
+// FIXME: Temporarily disabling TypeScript checking on importing base rules
+// until @commitlint/rules exports index.d.ts which should be soon:
+// See: https://github.com/conventional-changelog/commitlint/issues/659
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-ignore
+// @ts-ignore
+import baseRules from '@commitlint/rules';
+// import { TargetCaseType } from '@commitlint/types'; // When it is published
+import { TargetCaseType } from 'commitlint-github-utils/@types';
+import utils from 'commitlint-github-utils';
+
+import { RuleResolver } from '../../../@types';
+import { subjectRuleResolver } from './helpers';
+
+import subjectSeparatorRuleResolver from './subjectSeparator';
+
+const commitlintGitHubRules = utils.commitlintGitHubConstants.GITHUB_RULES;
+
+// Delegate Subject Rules
+
+export const subjectEmptyRuleResolver: RuleResolver<unknown> = subjectRuleResolver(
+  baseRules[commitlintGitHubRules.subjectEmpty],
+);
+
+export const subjectCaseRuleResolver: RuleResolver<TargetCaseType | TargetCaseType[]> = subjectRuleResolver(
+  baseRules[commitlintGitHubRules.subjectCase],
+);
+
+export const subjectFullStopRuleResolver: RuleResolver<string> = subjectRuleResolver(
+  baseRules[commitlintGitHubRules.subjectFullStop],
+  '.',
+);
+
+export const subjectMinLengthRuleResolver: RuleResolver<number> = subjectRuleResolver(
+  baseRules[commitlintGitHubRules.subjectMinLength],
+);
+
+export const subjectMaxLengthRuleResolver: RuleResolver<number> = subjectRuleResolver(
+  baseRules[commitlintGitHubRules.subjectMaxLength],
+);
+
+// Custom Subject Rules
+
+export { subjectSeparatorRuleResolver };

packages/commitlint-plugin-github-rules/src/rules/subject/subjectSeparator.ts

@@ -0,0 +1,52 @@
+import { When, ParsedCommitMessage } from 'commitlint-github-utils/@types';
+import utils from 'commitlint-github-utils';
+
+import { RuleResolverResult, RuleResolver } from '../../../@types';
+
+// For now this is hardcoded because to support custom separators the parser in commitlint-github-utils
+// would need to be updated as use static regex patterns to parse commit messages
+const EXPECTED_SEPARATOR = ' ';
+
+const subjectSeparatorRuleResolver: RuleResolver<string> = (parsed, whenPassedIn): RuleResolverResult => {
+  const rawCommitMessage = parsed.raw;
+  if (!rawCommitMessage) return [false, 'Commit message should not be empty'];
+
+  const commitMessage = utils.parseCommitMessage(rawCommitMessage);
+
+  // We short circuit if the When requested is only for non-WIPs and the commit is a WIP
+  const wipHandledResult = utils.handleWipCommits(commitMessage, whenPassedIn);
+  if (wipHandledResult.isWipValidated) {
+    // In that case we just return true immediately
+    return [true];
+  }
+  // Otherwise we continue with validating the separator with the When returned
+  // as if it was passed a NON-WIPs one it has been converted to a standard ALWAYS or NEVER
+  // so validateSubjectSeparator() only needs to handle standard When values. See the docs on handleWipCommits() for more info
+
+  return validateSubjectSeparator(commitMessage, wipHandledResult.when);
+};
+
+function validateSubjectSeparator(commitMessage: ParsedCommitMessage, when: When = When.ALWAYS): RuleResolverResult {
+  const { subjectSeparator, subject } = commitMessage;
+
+  // If there is no subject defined (not an empty subject) then we have nothing to validate so we return true
+  if (subject === undefined) {
+    return [true];
+  }
+
+  // Negated instance doesn't make much sense but if negated then we validate there is NO separator of a particular type before the subject
+  if (utils.isNegated(when)) {
+    return [
+      subjectSeparator !== EXPECTED_SEPARATOR,
+      `the commit message has a separator '${EXPECTED_SEPARATOR}' before the subject which isn't allowed`,
+    ];
+  }
+
+  // But by default we validate that there IS a separator of a particular type before the subject
+  return [
+    subjectSeparator === EXPECTED_SEPARATOR,
+    `the commit message does not have a valid separator before the subject; expected: '${EXPECTED_SEPARATOR}'`,
+  ];
+}
+
+export default subjectSeparatorRuleResolver;

packages/commitlint-plugin-github-rules/src/rules/subject/tests/delegateRuleResolvers.whitebox.test.ts

@@ -0,0 +1,112 @@
+// See comment in subjectRuleResolvers.ts for why these checks are disabled:
+// eslint-disable-next-line @typescript-eslint/ban-ts-ignore
+// @ts-ignore
+import baseRules from '@commitlint/rules';
+import { When } from 'commitlint-github-utils/@types';
+import utils from 'commitlint-github-utils';
+
+import { BaseParsedCommit, RuleResolverResult, RuleResolver } from '../../../../@types';
+import { subjectAdapter } from '../helpers';
+import * as SubjectRuleResolvers from '..';
+
+import resolveRuleUsingBaseResolver from '../../utils/wrappedRuleResolver';
+
+// Mock the resolveRuleUsingBaseResolver so we can isolate our test to just the function-under-test: subjectRuleResolver
+jest.mock('../../utils/wrappedRuleResolver');
+
+const mockedResolveRuleUsingBaseResolver: jest.Mock<RuleResolverResult> = resolveRuleUsingBaseResolver as jest.Mock<
+  RuleResolverResult
+>;
+
+const commitlintGitHubRules = utils.commitlintGitHubConstants.GITHUB_RULES;
+
+const EXPECTED_PARSED: BaseParsedCommit = { raw: 'dummy-raw' };
+const EXPECTED_WHEN = When.NEVER;
+const EXPECTED_VALUE = 'dummy-value';
+
+function validateDelegateRuleResolver(
+  delegateRuleName: string,
+  subjectRuleResolver: RuleResolver<any>,
+  defaultValue?: string,
+): void {
+  // Given that the standard subject rule exists
+  const delegate = baseRules[delegateRuleName];
+  expect(delegate).toBeDefined();
+
+  // And that the wrapped subject rule under test exists
+  expect(subjectRuleResolver).toBeDefined();
+
+  // And we mock the base rule resolving function to return a mock response
+  const mockResult: RuleResolverResult = [true, delegateRuleName];
+  mockedResolveRuleUsingBaseResolver.mockClear();
+  mockedResolveRuleUsingBaseResolver.mockReturnValue(mockResult);
+
+  // Unless a default value was passed into this test, we will pass the placeholder EXPECTED_VALUE
+  // and expect that to be passed to the base rule resolving function
+  let valuePassedIn: string | null = EXPECTED_VALUE;
+  let expectedValue = valuePassedIn;
+
+  // Otherwise, if a default value is specified we'll won't pass a value in but expect the default value to be used instead
+  if (defaultValue) {
+    valuePassedIn = null;
+    expectedValue = defaultValue;
+  }
+
+  // When we call the subject rule under test
+  const result = subjectRuleResolver(EXPECTED_PARSED, EXPECTED_WHEN, valuePassedIn);
+
+  // Then we expect the mock response from the base rule resolving function to be returned
+  expect(result).toEqual(mockResult);
+
+  // And we expect the base rule resolving function with the correct arguments
+  expect(mockedResolveRuleUsingBaseResolver).toHaveBeenCalledWith(
+    delegate,
+    subjectAdapter,
+    EXPECTED_PARSED,
+    EXPECTED_WHEN,
+    expectedValue,
+  );
+
+  // The base rule resolving function itself is tested by wrappedRuleResolver.test.ts
+  // We also have black box tests in this directory
+}
+
+describe('delegate subject rule resolvers', () => {
+  it('subjectEmptyRuleResolver should delegate correctly for non-WIP commits only', () => {
+    validateDelegateRuleResolver(commitlintGitHubRules.subjectEmpty, SubjectRuleResolvers.subjectEmptyRuleResolver);
+  });
+
+  it('subjectCaseRuleResolver should delegate correctly for non-WIP commits only', () => {
+    validateDelegateRuleResolver(commitlintGitHubRules.subjectCase, SubjectRuleResolvers.subjectCaseRuleResolver);
+  });
+
+  it('subjectFullStopRuleResolver should delegate correctly for non-WIP commits only, using explicit value if passed', () => {
+    validateDelegateRuleResolver(
+      commitlintGitHubRules.subjectFullStop,
+      SubjectRuleResolvers.subjectFullStopRuleResolver,
+    );
+  });
+
+  it('subjectFullStopRuleResolver should delegate correctly for non-WIP commits only, defaulting to default value if no value passed', () => {
+    validateDelegateRuleResolver(
+      commitlintGitHubRules.subjectFullStop,
+      SubjectRuleResolvers.subjectFullStopRuleResolver,
+      // Verify default value is used when no explict value passed
+      '.',
+    );
+  });
+
+  it('subjectMinLengthRuleResolver should delegate correctly for non-WIP commits only', () => {
+    validateDelegateRuleResolver(
+      commitlintGitHubRules.subjectMinLength,
+      SubjectRuleResolvers.subjectMinLengthRuleResolver,
+    );
+  });
+
+  it('subjectMaxLengthRuleResolver should delegate correctly for non-WIP commits only', () => {
+    validateDelegateRuleResolver(
+      commitlintGitHubRules.subjectMaxLength,
+      SubjectRuleResolvers.subjectMaxLengthRuleResolver,
+    );
+  });
+});

packages/commitlint-plugin-github-rules/src/rules/subject/tests/helpers.test.ts

@@ -0,0 +1,67 @@
+import { ParsedCommitMessage, When } from 'commitlint-github-utils/@types';
+import { RuleResolver, RuleResolverResult, BaseParsedCommit } from '../../../../@types';
+import { subjectAdapter, subjectRuleResolver } from '../helpers';
+
+import resolveRuleUsingBaseResolver from '../../utils/wrappedRuleResolver';
+
+// Mock the resolveRuleUsingBaseResolver so we can isolate our test to just the function-under-test: subjectRuleResolver
+jest.mock('../../utils/wrappedRuleResolver');
+
+const mockedResolveRuleUsingBaseResolver: jest.Mock<RuleResolverResult> = resolveRuleUsingBaseResolver as jest.Mock<
+  RuleResolverResult
+>;
+
+const EXPECTED_PARSED: BaseParsedCommit = { raw: 'dummy-raw' };
+const EXPECTED_WHEN = When.NEVER;
+const EXPECTED_VALUE = 'dummy-value';
+
+const BASE_RESOLVER: RuleResolver<string> = jest.fn();
+const RESULT_FROM_BASE_RESOLVER: RuleResolverResult = [true, 'DUMMY_RESULT'];
+
+mockedResolveRuleUsingBaseResolver.mockReturnValue(RESULT_FROM_BASE_RESOLVER);
+
+describe('subjectAdapter', () => {
+  it('should return the subject from the ParsedCommitMessage', () => {
+    const subject = 'expected-subject';
+    const commit: ParsedCommitMessage = {
+      issueNumbers: [],
+      isWip: false,
+      body: [],
+      subject,
+    };
+
+    expect(subjectAdapter(commit)).toEqual({ subject });
+  });
+});
+
+describe('subjectRuleResolver', () => {
+  const defaultValue = 'default-value' as string;
+
+  const ruleResolverWithDefaultValue: RuleResolver<string> = subjectRuleResolver(BASE_RESOLVER, defaultValue);
+
+  it('should use the arguments passed, including value in when specified', () => {
+    expect(ruleResolverWithDefaultValue(EXPECTED_PARSED, EXPECTED_WHEN, EXPECTED_VALUE)).toEqual(
+      RESULT_FROM_BASE_RESOLVER,
+    );
+
+    expect(mockedResolveRuleUsingBaseResolver).toHaveBeenCalledWith(
+      BASE_RESOLVER,
+      subjectAdapter,
+      EXPECTED_PARSED,
+      EXPECTED_WHEN,
+      EXPECTED_VALUE,
+    );
+  });
+
+  it('should use the arguments passed with default value being used when value not specified', () => {
+    expect(ruleResolverWithDefaultValue(EXPECTED_PARSED, EXPECTED_WHEN, undefined)).toEqual(RESULT_FROM_BASE_RESOLVER);
+
+    expect(mockedResolveRuleUsingBaseResolver).toHaveBeenCalledWith(
+      BASE_RESOLVER,
+      subjectAdapter,
+      EXPECTED_PARSED,
+      EXPECTED_WHEN,
+      defaultValue,
+    );
+  });
+});