feat(dev-infra): create a wizard for building commit messages (#38457)

Creates a wizard to walk through creating a commit message in the correct
template for commit messages in Angular repositories.

PR Close #38457

dev-infra/commit-message/BUILD.bazel

@@ -4,6 +4,7 @@ load("@npm_bazel_typescript//:index.bzl", "ts_library")
 ts_library(
     name = "commit-message",
     srcs = [
+        "builder.ts",
         "cli.ts",
         "commit-message-draft.ts",
         "config.ts",
@@ -12,14 +13,17 @@ ts_library(
         "validate.ts",
         "validate-file.ts",
         "validate-range.ts",
+        "wizard.ts",
     ],
     module_name = "@angular/dev-infra-private/commit-message",
     visibility = ["//dev-infra:__subpackages__"],
     deps = [
         "//dev-infra/utils",
+        "@npm//@types/inquirer",
         "@npm//@types/node",
         "@npm//@types/shelljs",
         "@npm//@types/yargs",
+        "@npm//inquirer",
         "@npm//shelljs",
         "@npm//yargs",
     ],
@@ -29,6 +33,7 @@ ts_library(
     name = "test_lib",
     testonly = True,
     srcs = [
+        "builder.spec.ts",
         "parse.spec.ts",
         "validate.spec.ts",
     ],

dev-infra/commit-message/builder.spec.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as config from '../utils/config';
+import * as console from '../utils/console';
+
+import {buildCommitMessage} from './builder';
+
+
+describe('commit message building:', () => {
+  beforeEach(() => {
+    // stub logging calls to prevent noise in test log
+    spyOn(console, 'info').and.stub();
+    // provide a configuration for DevInfra when loaded
+    spyOn(config, 'getConfig').and.returnValue({
+      commitMessage: {
+        scopes: ['core'],
+      }
+    } as any);
+  });
+
+  it('creates a commit message with a scope', async () => {
+    buildPromptResponseSpies('fix', 'core', 'This is a summary');
+
+    expect(await buildCommitMessage()).toMatch(/^fix\(core\): This is a summary/);
+  });
+
+  it('creates a commit message without a scope', async () => {
+    buildPromptResponseSpies('build', false, 'This is a summary');
+
+    expect(await buildCommitMessage()).toMatch(/^build: This is a summary/);
+  });
+});
+
+
+/** Create spies to return the mocked selections from prompts. */
+function buildPromptResponseSpies(type: string, scope: string|false, summary: string) {
+  spyOn(console, 'promptAutocomplete')
+      .and.returnValues(Promise.resolve(type), Promise.resolve(scope));
+  spyOn(console, 'promptInput').and.returnValue(Promise.resolve(summary));
+}

dev-infra/commit-message/builder.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {ListChoiceOptions} from 'inquirer';
+
+import {info, promptAutocomplete, promptInput} from '../utils/console';
+
+import {COMMIT_TYPES, CommitType, getCommitMessageConfig, ScopeRequirement} from './config';
+
+/** Validate commit message at the provided file path. */
+export async function buildCommitMessage() {
+  // TODO(josephperrott): Add support for skipping wizard with local untracked config file
+  // TODO(josephperrott): Add default commit message information/commenting into generated messages
+  info('Just a few questions to start building the commit message!');
+
+  /** The commit message type. */
+  const type = await promptForCommitMessageType();
+  /** The commit message scope. */
+  const scope = await promptForCommitMessageScopeForType(type);
+  /** The commit message summary. */
+  const summary = await promptForCommitMessageSummary();
+
+  return `${type.name}${scope ? '(' + scope + ')' : ''}: ${summary}\n\n`;
+}
+
+/** Prompts in the terminal for the commit message's type. */
+async function promptForCommitMessageType(): Promise<CommitType> {
+  info('The type of change in the commit. Allows a reader to know the effect of the change,');
+  info('whether it brings a new feature, adds additional testing, documents the `project, etc.');
+
+  /** List of commit type options for the autocomplete prompt. */
+  const typeOptions: ListChoiceOptions[] =
+      Object.values(COMMIT_TYPES).map(({description, name}) => {
+        return {
+          name: `${name} - ${description}`,
+          value: name,
+          short: name,
+        };
+      });
+  /** The key of a commit message type, selected by the user via prompt. */
+  const typeName = await promptAutocomplete('Select a type for the commit:', typeOptions);
+
+  return COMMIT_TYPES[typeName];
+}
+
+/** Prompts in the terminal for the commit message's scope. */
+async function promptForCommitMessageScopeForType(type: CommitType): Promise<string|false> {
+  // If the commit type's scope requirement is forbidden, return early.
+  if (type.scope === ScopeRequirement.Forbidden) {
+    info(`Skipping scope selection as the '${type.name}' type does not allow scopes`);
+    return false;
+  }
+  /** Commit message configuration */
+  const config = getCommitMessageConfig();
+
+  info('The area of the repository the changes in this commit most affects.');
+  return await promptAutocomplete(
+      'Select a scope for the commit:', config.commitMessage.scopes,
+      type.scope === ScopeRequirement.Optional ? '<no scope>' : '');
+}
+
+/** Prompts in the terminal for the commit message's summary. */
+async function promptForCommitMessageSummary(): Promise<string> {
+  info('Provide a short summary of what the changes in the commit do');
+  return await promptInput('Provide a short summary of the commit');
+}

dev-infra/commit-message/cli.ts

@@ -12,6 +12,7 @@ import {info} from '../utils/console';
 import {restoreCommitMessage} from './restore-commit-message';
 import {validateFile} from './validate-file';
 import {validateCommitRange} from './validate-range';
+import {runWizard} from './wizard';
 
 /** Build the parser for the commit-message commands. */
 export function buildCommitMessageParser(localYargs: yargs.Argv) {
@@ -41,6 +42,23 @@ export function buildCommitMessageParser(localYargs: yargs.Argv) {
           args => {
             restoreCommitMessage(args['file-env-variable'][0], args['file-env-variable'][1] as any);
           })
+      .command(
+          'wizard <filePath> [source] [commitSha]', '', ((args: any) => {
+            return args
+                .positional(
+                    'filePath',
+                    {description: 'The file path to write the generated commit message into'})
+                .positional('source', {
+                  choices: ['message', 'template', 'merge', 'squash', 'commit'],
+                  description: 'The source of the commit message as described here: ' +
+                      'https://git-scm.com/docs/githooks#_prepare_commit_msg'
+                })
+                .positional(
+                    'commitSha', {description: 'The commit sha if source is set to `commit`'});
+          }),
+          async (args: any) => {
+            await runWizard(args);
+          })
       .command(
           'pre-commit-validate', 'Validate the most recent commit message', {
             'file': {

dev-infra/commit-message/config.ts

@@ -39,36 +39,56 @@ export enum ScopeRequirement {
 
 /** A commit type */
 export interface CommitType {
+  description: string;
+  name: string;
   scope: ScopeRequirement;
 }
 
 /** The valid commit types for Angular commit messages. */
 export const COMMIT_TYPES: {[key: string]: CommitType} = {
   build: {
+    name: 'build',
+    description: 'Changes to local repository build system and tooling',
     scope: ScopeRequirement.Forbidden,
   },
   ci: {
+    name: 'ci',
+    description: 'Changes to CI configuration and CI specific tooling',
     scope: ScopeRequirement.Forbidden,
   },
   docs: {
+    name: 'docs',
+    description: 'Changes which exclusively affects documentation.',
     scope: ScopeRequirement.Optional,
   },
   feat: {
+    name: 'feat',
+    description: 'Creates a new feature',
     scope: ScopeRequirement.Required,
   },
   fix: {
+    name: 'fix',
+    description: 'Fixes a previously discovered failure/bug',
     scope: ScopeRequirement.Required,
   },
   perf: {
+    name: 'perf',
+    description: 'Improves performance without any change in functionality or API',
     scope: ScopeRequirement.Required,
   },
   refactor: {
+    name: 'refactor',
+    description: 'Refactor without any change in functionality or API (includes style changes)',
     scope: ScopeRequirement.Required,
   },
   release: {
+    name: 'release',
+    description: 'A release point in the repository',
     scope: ScopeRequirement.Forbidden,
   },
   test: {
+    name: 'test',
+    description: 'Improvements or corrections made to the project\'s test suite',
     scope: ScopeRequirement.Required,
   },
 };

dev-infra/commit-message/wizard.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {writeFileSync} from 'fs';
+
+import {info} from '../utils/console';
+
+import {buildCommitMessage} from './builder';
+
+/**
+ * The source triggering the git commit message creation.
+ * As described in: https://git-scm.com/docs/githooks#_prepare_commit_msg
+ */
+export type PrepareCommitMsgHookSource = 'message'|'template'|'merge'|'squash'|'commit';
+
+/** The default commit message used if the wizard does not procude a commit message. */
+const defaultCommitMessage = `<type>(<scope>): <summary>
+
+# <Describe the motivation behind this change - explain WHY you are making this change. Wrap all
+#  lines at 100 characters.>\n\n`;
+
+export async function runWizard(
+    args: {filePath: string, source?: PrepareCommitMsgHookSource, commitSha?: string}) {
+  // TODO(josephperrott): Add support for skipping wizard with local untracked config file
+
+  if (args.source !== undefined) {
+    info(`Skipping commit message wizard due because the commit was created via '${
+        args.source}' source`);
+    process.exitCode = 0;
+    return;
+  }
+
+  // Set the default commit message to be updated if the user cancels out of the wizard in progress
+  writeFileSync(args.filePath, defaultCommitMessage);
+
+  /** The generated commit message. */
+  const commitMessage = await buildCommitMessage();
+  writeFileSync(args.filePath, commitMessage);
+}