chore(cli): rename cli-args-gen into user-input-gen (aws#32821)

This PR does not change CLI functionality because we are not using `CliArguments` yet. This PR includes the following related changes:

- `CliArguments` are renamed `UserInput` to reflect what the schema represents -- they are options available to be specified via CLI options or `cdk.json`.
- the tool previously known as `cli-arg-gen` is now named `user-input-gen` to reflect this change.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

aws-cdk.code-workspace

@@ -31,7 +31,7 @@
         "name": "aws-custom-resource-sdk-adapter",
         "rootPath": "packages/@aws-cdk/aws-custom-resource-sdk-adapter"
       },
-      { "name": "cli-args-gen", "rootPath": "tools/@aws-cdk/cli-args-gen" }
+      { "name": "user-input-gen", "rootPath": "tools/@aws-cdk/user-input-gen" }
     ]
   },
   "extensions": {

lerna.json

@@ -10,7 +10,7 @@
     "packages/@aws-cdk-testing/*",
     "packages/@aws-cdk/*/lambda-packages/*",
     "tools/@aws-cdk/cdk-build-tools",
-    "tools/@aws-cdk/cli-args-gen",
+    "tools/@aws-cdk/user-input-gen",
     "tools/@aws-cdk/cdk-release",
     "tools/@aws-cdk/node-bundle",
     "tools/@aws-cdk/pkglint",

package.json

@@ -77,7 +77,7 @@
       "packages/@aws-cdk-testing/*",
       "packages/@aws-cdk/*/lambda-packages/*",
       "tools/@aws-cdk/cdk-build-tools",
-      "tools/@aws-cdk/cli-args-gen",
+      "tools/@aws-cdk/user-input-gen",
       "tools/@aws-cdk/cdk-release",
       "tools/@aws-cdk/node-bundle",
       "tools/@aws-cdk/pkglint",

packages/aws-cdk/CONTRIBUTING.md

@@ -1,21 +1,21 @@
 ## CLI Commands
 
 All CDK CLI Commands are defined in `lib/config.ts`. This file is translated
-into a valid `yargs` configuration by `bin/cli-args-gen`, which is generated by `@aws-cdk/cli-args-gen`.
+into a valid `yargs` configuration by `bin/user-input-gen`, which is generated by `@aws-cdk/user-input-gen`.
 The `yargs` configuration is generated into the function `parseCommandLineArguments()`,
 in `lib/parse-command-line-arguments.ts`, and is checked into git for readability and
 inspectability; do not edit this file by hand, as every subsequent `yarn build` will
 overwrite any manual edits. If you need to leverage a `yargs` feature not used by
-the CLI, you must add support for it to `@aws-cdk/cli-args-gen`.
+the CLI, you must add support for it to `@aws-cdk/user-input-gen`.
 
-Note that `bin/cli-args-gen` is executed by `ts-node`, which allows `config.ts` to
+Note that `bin/user-input-gen` is executed by `ts-node`, which allows `config.ts` to
 reference functions and other identifiers defined in the CLI before the CLI is
 built.
 
 ### Dynamic Values
 
 Some values, such as the user's platform, cannot be computed at build time.
-Some commands depend on these values, and thus `cli-args-gen` must generate the
+Some commands depend on these values, and thus `user-input-gen` must generate the
 code to compute these values at build time.
 
 The only way to do this today is to reference a parameter with `DynamicValue.fromParameter`.

packages/aws-cdk/jest.config.js

@@ -19,8 +19,8 @@ const config = {
         "<rootDir>/lib/api/aws-auth/sdk.ts",
         // Files generated by cli-args-gen
         "<rootDir>/lib/parse-command-line-arguments.ts",
-        "<rootDir>/lib/cli-arguments.ts",
-        "<rootDir>/lib/convert-to-cli-args.ts",
+        "<rootDir>/lib/user-input.ts",
+        "<rootDir>/lib/convert-to-user-input.ts",
     ],
 
     // We have many tests here that commonly time out

packages/aws-cdk/lib/config.ts

@@ -1,5 +1,5 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
-import { CliHelpers, type CliConfig } from '@aws-cdk/cli-args-gen';
+import { CliHelpers, type CliConfig } from '@aws-cdk/user-input-gen';
 import { StackActivityProgress } from './api/util/cloudformation/stack-activity-monitor';
 import { MIGRATE_SUPPORTED_LANGUAGES } from './commands/migrate';
 import { RequireApproval } from './diff';
@@ -8,8 +8,11 @@ import { availableInitLanguages } from './init';
 export const YARGS_HELPERS = new CliHelpers('./util/yargs-helpers');
 
 /**
- * Source of truth for all CDK CLI commands. `cli-args-gen` translates this into the `yargs` definition
- * in `lib/parse-command-line-arguments.ts`.
+ * Source of truth for all CDK CLI commands. `user-input-gen` translates this into:
+ *
+ * - the `yargs` definition in `lib/parse-command-line-arguments.ts`.
+ * - the `UserInput` type in `lib/user-input.ts`.
+ * - the `convertXxxToUserInput` functions in `lib/convert-to-user-input.ts`.
  */
 export async function makeConfig(): Promise<CliConfig> {
   return {

packages/aws-cdk/lib/convert-to-cli-args.ts → packages/aws-cdk/lib/convert-to-user-input.ts

@@ -3,11 +3,11 @@
 // Do not edit by hand; all changes will be overwritten at build time from the config file.
 // -------------------------------------------------------------------------------------------
 /* eslint-disable @stylistic/max-len */
-import { CliArguments, GlobalOptions } from './cli-arguments';
 import { Command } from './settings';
+import { UserInput, GlobalOptions } from './user-input';
 
 // @ts-ignore TS6133
-export function convertYargsToCliArgs(args: any): CliArguments {
+export function convertYargsToUserInput(args: any): UserInput {
   const globalOptions: GlobalOptions = {
     app: args.app,
     build: args.build,
@@ -250,17 +250,17 @@ export function convertYargsToCliArgs(args: any): CliArguments {
       commandOptions = {};
       break;
   }
-  const cliArguments: CliArguments = {
+  const userInput: UserInput = {
     _: args._[0],
     globalOptions,
     [args._[0]]: commandOptions,
   };
 
-  return cliArguments;
+  return userInput;
 }
 
 // @ts-ignore TS6133
-export function convertConfigToCliArgs(config: any): CliArguments {
+export function convertConfigToUserInput(config: any): UserInput {
   const globalOptions: GlobalOptions = {
     app: config.app,
     build: config.build,
@@ -428,7 +428,7 @@ export function convertConfigToCliArgs(config: any): CliArguments {
     browser: config.docs?.browser,
   };
   const doctorOptions = {};
-  const cliArguments: CliArguments = {
+  const userInput: UserInput = {
     globalOptions,
     list: listOptions,
     synthesize: synthesizeOptions,
@@ -450,5 +450,5 @@ export function convertConfigToCliArgs(config: any): CliArguments {
     doctor: doctorOptions,
   };
 
-  return cliArguments;
+  return userInput;
 }

packages/aws-cdk/lib/cli-arguments.ts → packages/aws-cdk/lib/user-input.ts

@@ -6,11 +6,11 @@
 import { Command } from './settings';
 
 /**
- * The structure of the CLI configuration, generated from packages/aws-cdk/lib/config.ts
+ * The structure of the user input -- either CLI options or cdk.json -- generated from packages/aws-cdk/lib/config.ts
  *
  * @struct
  */
-export interface CliArguments {
+export interface UserInput {
   /**
    * The CLI command name
    */

packages/aws-cdk/package.json

@@ -7,7 +7,7 @@
   },
   "scripts": {
     "build": "cdk-build",
-    "cli-args-gen": "ts-node --preferTsExts scripts/cli-args-gen.ts",
+    "user-input-gen": "ts-node --preferTsExts scripts/user-input-gen.ts",
     "watch": "cdk-watch",
     "lint": "cdk-lint",
     "pkglint": "pkglint -f",
@@ -29,7 +29,7 @@
   },
   "cdk-build": {
     "pre": [
-      "yarn cli-args-gen"
+      "yarn user-input-gen"
     ],
     "post": [
       "cp ../../node_modules/cdk-from-cfn/index_bg.wasm ./lib/",
@@ -70,7 +70,7 @@
     "@aws-cdk/cdk-build-tools": "0.0.0",
     "@aws-cdk/cli-plugin-contract": "0.0.0",
     "@aws-cdk/pkglint": "0.0.0",
-    "@aws-cdk/cli-args-gen": "0.0.0",
+    "@aws-cdk/user-input-gen": "0.0.0",
     "@octokit/rest": "^18.12.0",
     "@types/archiver": "^5.3.4",
     "@types/fs-extra": "^9.0.13",

packages/aws-cdk/scripts/user-input-gen

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('./user-input-gen.js');

packages/aws-cdk/scripts/user-input-gen.ts

@@ -0,0 +1,16 @@
+import * as fs from 'fs';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { renderYargs, renderUserInputType, renderUserInputFuncs } from '@aws-cdk/user-input-gen';
+import { makeConfig, YARGS_HELPERS } from '../lib/config';
+
+async function main() {
+  const config = await makeConfig();
+  fs.writeFileSync('./lib/parse-command-line-arguments.ts', await renderYargs(config, YARGS_HELPERS));
+  fs.writeFileSync('./lib/user-input.ts', await renderUserInputType(config));
+  fs.writeFileSync('./lib/convert-to-user-input.ts', await renderUserInputFuncs(config));
+}
+
+main().then(() => {
+}).catch((e) => {
+  throw e;
+});

packages/aws-cdk/test/cli-arguments.test.ts

@@ -1,11 +1,11 @@
-import { convertConfigToCliArgs, convertYargsToCliArgs } from '../lib/convert-to-cli-args';
+import { convertConfigToUserInput, convertYargsToUserInput } from '../lib/convert-to-user-input';
 import { parseCommandLineArguments } from '../lib/parse-command-line-arguments';
 
 describe('yargs', () => {
   test('yargs object can be converted to cli arguments', async () => {
     const input = await parseCommandLineArguments(['deploy', '-R', '-v', '--ci']);
 
-    const result = convertYargsToCliArgs(input);
+    const result = convertYargsToUserInput(input);
 
     expect(result).toEqual({
       _: 'deploy',
@@ -70,7 +70,7 @@ describe('yargs', () => {
   test('positional argument is correctly passed through -- variadic', async () => {
     const input = await parseCommandLineArguments(['deploy', 'stack1', 'stack2', '-R', '-v', '--ci']);
 
-    const result = convertYargsToCliArgs(input);
+    const result = convertYargsToUserInput(input);
 
     expect(result).toEqual({
       _: 'deploy',
@@ -84,7 +84,7 @@ describe('yargs', () => {
   test('positional argument is correctly passed through -- single', async () => {
     const input = await parseCommandLineArguments(['acknowledge', 'id1', '-v', '--ci']);
 
-    const result = convertYargsToCliArgs(input);
+    const result = convertYargsToUserInput(input);
 
     expect(result).toEqual({
       _: 'acknowledge',
@@ -109,7 +109,7 @@ describe('config', () => {
       },
     };
 
-    const result = convertConfigToCliArgs(input);
+    const result = convertConfigToUserInput(input);
 
     expect(result).toEqual({
       globalOptions: expect.objectContaining({

tools/@aws-cdk/cli-args-gen/README.md → tools/@aws-cdk/user-input-gen/README.md

@@ -1,16 +1,16 @@
-# cli-args-gen
+# user-input-gen
 
 Generates CDK CLI configurations from the source of truth in `packages/aws-cdk/lib/config.ts`.
 Currently generates the following files:
 
 - `packages/aws-cdk/lib/parse-command-line-arguments.ts`: `yargs` config.
-- `packages/aws-cdk-lib/cli-arguments.ts`: strongly typed `CliArguments` interface.
-- `packages/aws-cdk-lib/convert-to-cli-args.ts`: converts the `any` returned by `yargs` to `CliArguments`.
+- `packages/aws-cdk/lib/user-input.ts`: strongly typed `UserInput` interface.
+- `packages/aws-cdk/lib/convert-to-user-inpu.ts`: converts input from the CLI or `cdk.json` into `UserInput`.
 
 ## Usage
 
 ```ts
-import { renderYargs } from '@aws-cdk/cli-args-gen';
+import { renderYargs } from '@aws-cdk/user-input-gen';
 
 declare const config: CliConfig;
 

tools/@aws-cdk/cli-args-gen/lib/cli-args-function-gen.ts → tools/@aws-cdk/user-input-gen/lib/convert-to-user-input-gen.ts

@@ -7,33 +7,32 @@ import { CliAction, CliConfig } from './yargs-types';
 const CLI_ARG_NAME = 'args';
 const CONFIG_ARG_NAME = 'config';
 
-export async function renderCliArgsFunc(config: CliConfig): Promise<string> {
+export async function renderUserInputFuncs(config: CliConfig): Promise<string> {
   const scope = new Module('aws-cdk');
 
   scope.documentation.push( '-------------------------------------------------------------------------------------------');
   scope.documentation.push('GENERATED FROM packages/aws-cdk/lib/config.ts.');
   scope.documentation.push('Do not edit by hand; all changes will be overwritten at build time from the config file.');
   scope.documentation.push('-------------------------------------------------------------------------------------------');
 
-  scope.addImport(new SelectiveModuleImport(scope, './cli-arguments', ['CliArguments', 'GlobalOptions']));
-  const cliArgType = Type.fromName(scope, 'CliArguments');
-
   scope.addImport(new SelectiveModuleImport(scope, './settings', ['Command']));
+  scope.addImport(new SelectiveModuleImport(scope, './user-input', ['UserInput', 'GlobalOptions']));
+  const userInputType = Type.fromName(scope, 'UserInput');
 
-  const createCliArguments = new FreeFunction(scope, {
-    name: 'convertYargsToCliArgs',
+  const convertYargsToUserInput = new FreeFunction(scope, {
+    name: 'convertYargsToUserInput',
     export: true,
-    returnType: cliArgType,
+    returnType: userInputType,
     parameters: [
       { name: 'args', type: Type.ANY },
     ],
   });
-  createCliArguments.addBody(code.expr.directCode(buildCliArgsFunction(config)));
+  convertYargsToUserInput.addBody(code.expr.directCode(buildYargsToUserInputFunction(config)));
 
   const createConfigArguments = new FreeFunction(scope, {
-    name: 'convertConfigToCliArgs',
+    name: 'convertConfigToUserInput',
     export: true,
-    returnType: cliArgType,
+    returnType: userInputType,
     parameters: [
       { name: 'config', type: Type.ANY },
     ],
@@ -52,14 +51,14 @@ export async function renderCliArgsFunc(config: CliConfig): Promise<string> {
   });
 }
 
-function buildCliArgsFunction(config: CliConfig): string {
+function buildYargsToUserInputFunction(config: CliConfig): string {
   const globalOptions = buildGlobalOptions(config, CLI_ARG_NAME);
   const commandSwitch = buildCommandSwitch(config, CLI_ARG_NAME);
-  const cliArgs = buildCliArgs(CLI_ARG_NAME);
+  const userInput = buildUserInput(CLI_ARG_NAME);
   return [
     globalOptions,
     commandSwitch,
-    cliArgs,
+    userInput,
   ].join('\n');
 }
 
@@ -85,7 +84,7 @@ function buildGlobalOptions(config: CliConfig, argName: string): string {
 }
 
 function buildCommandsList(config: CliConfig, argName: string): string {
-  const commandOptions = [];
+  const commandOptions: string[] = [];
   // Note: we are intentionally not including aliases for the default options that can be
   // specified via `cdk.json`. These options must be specified by the command name
   // i.e. acknowledge rather than ack.
@@ -140,27 +139,27 @@ function buildPositionalArguments(arg: { name: string; variadic: boolean }, argN
   return `${arg.name}: ${argName}.${arg.name}`;
 }
 
-function buildCliArgs(argName: string): string {
+function buildUserInput(argName: string): string {
   return [
-    'const cliArguments: CliArguments = {',
+    'const userInput: UserInput = {',
     `_: ${argName}._[0],`,
     'globalOptions,',
     `[${argName}._[0]]: commandOptions`,
     '}',
     '',
-    'return cliArguments',
+    'return userInput',
   ].join('\n');
 }
 
 function buildConfigArgs(config: CliConfig): string {
   return [
-    'const cliArguments: CliArguments = {',
+    'const userInput: UserInput = {',
     'globalOptions,',
     ...(Object.keys(config.commands).map((commandName) => {
       return `'${commandName}': ${kebabToCamelCase(commandName)}Options,`;
     })),
     '}',
     '',
-    'return cliArguments',
+    'return userInput',
   ].join('\n');
 }

tools/@aws-cdk/user-input-gen/lib/index.ts

@@ -0,0 +1,4 @@
+export * from './yargs-gen';
+export * from './yargs-types';
+export * from './user-input-gen';
+export * from './convert-to-user-input-gen';