feat(@angular/cli): handle string key/value pairs, e.g. --define

Author: jkrems

packages/angular/cli/BUILD.bazel

@@ -147,6 +147,7 @@ ts_library(
         "//packages/angular_devkit/schematics",
         "//packages/angular_devkit/schematics/testing",
         "@npm//@types/semver",
+        "@npm//@types/yargs",
     ],
 )
 

packages/angular/cli/src/command-builder/command-module.ts

@@ -26,7 +26,7 @@ import { considerSettingUpAutocompletion } from '../utilities/completion';
 import { AngularWorkspace } from '../utilities/config';
 import { memoize } from '../utilities/memoize';
 import { PackageManagerUtils } from '../utilities/package-manager';
-import { Option } from './utilities/json-schema';
+import { Option, addSchemaOptionsToCommand } from './utilities/json-schema';
 
 export type Options<T> = { [key in keyof T as CamelCaseKey<key>]: T[key] };
 
@@ -188,68 +188,16 @@ export abstract class CommandModule<T extends {} = {}> implements CommandModuleI
    * **Note:** This method should be called from the command bundler method.
    */
   protected addSchemaOptionsToCommand<T>(localYargs: Argv<T>, options: Option[]): Argv<T> {
-    const booleanOptionsWithNoPrefix = new Set<string>();
-
-    for (const option of options) {
-      const {
-        default: defaultVal,
-        positional,
-        deprecated,
-        description,
-        alias,
-        userAnalytics,
-        type,
-        hidden,
-        name,
-        choices,
-      } = option;
-
-      const sharedOptions: YargsOptions & PositionalOptions = {
-        alias,
-        hidden,
-        description,
-        deprecated,
-        choices,
-        // This should only be done when `--help` is used otherwise default will override options set in angular.json.
-        ...(this.context.args.options.help ? { default: defaultVal } : {}),
-      };
-
-      let dashedName = strings.dasherize(name);
-
-      // Handle options which have been defined in the schema with `no` prefix.
-      if (type === 'boolean' && dashedName.startsWith('no-')) {
-        dashedName = dashedName.slice(3);
-        booleanOptionsWithNoPrefix.add(dashedName);
-      }
-
-      if (positional === undefined) {
-        localYargs = localYargs.option(dashedName, {
-          type,
-          ...sharedOptions,
-        });
-      } else {
-        localYargs = localYargs.positional(dashedName, {
-          type: type === 'array' || type === 'count' ? 'string' : type,
-          ...sharedOptions,
-        });
-      }
-
-      // Record option of analytics.
-      if (userAnalytics !== undefined) {
-        this.optionsWithAnalytics.set(name, userAnalytics);
-      }
-    }
+    const optionsWithAnalytics = addSchemaOptionsToCommand(
+      localYargs,
+      options,
+      // This should only be done when `--help` is used otherwise default will override options set in angular.json.
+      /* includeDefaultValues= */ this.context.args.options.help,
+    );
 
-    // Handle options which have been defined in the schema with `no` prefix.
-    if (booleanOptionsWithNoPrefix.size) {
-      localYargs.middleware((options: Arguments) => {
-        for (const key of booleanOptionsWithNoPrefix) {
-          if (key in options) {
-            options[`no-${key}`] = !options[key];
-            delete options[key];
-          }
-        }
-      }, false);
+    // Record option of analytics.
+    for (const [name, userAnalytics] of optionsWithAnalytics) {
+      this.optionsWithAnalytics.set(name, userAnalytics);
     }
 
     return localYargs;

packages/angular/cli/src/command-builder/utilities/json-schema.ts

@@ -6,8 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { json } from '@angular-devkit/core';
-import yargs from 'yargs';
+import { json, strings } from '@angular-devkit/core';
+import yargs, { Arguments, Argv, PositionalOptions, Options as YargsOptions } from 'yargs';
 
 /**
  * An option description.
@@ -43,6 +43,75 @@ export interface Option extends yargs.Options {
    * If this is falsey, do not report this option.
    */
   userAnalytics?: string;
+
+  /**
+   * Type of the values in a key/value pair field.
+   */
+  itemValueType?: 'string';
+}
+
+/**
+ * Note: This is done in a middleware because of how coerce and check work in
+ * yargs: coerce cannot throw validation errors but check only receives the
+ * post-coerce values. Instead of building a brittle communication channel
+ * between those two functions, it's easier to do both inside a single middleware.
+ */
+function coerceToStringMap(dashedName: string, value: (string | undefined)[]) {
+  const stringMap: Record<string, string> = {};
+  for (const pair of value) {
+    // This happens when the flag isn't passed at all.
+    if (pair === undefined) {
+      continue;
+    }
+
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx === -1) {
+      // This error will be picked up later in the check() callback.
+      // We can't throw in coerce and checks only happen after coerce completed.
+      throw new Error(
+        `Invalid value for argument: ${dashedName}, Given: '${pair}', Expected key=value pair`,
+      );
+    }
+    const key = pair.slice(0, eqIdx);
+    const value = pair.slice(eqIdx + 1);
+    stringMap[key] = value;
+  }
+
+  return stringMap;
+}
+
+function stringMapMiddleware(optionNames: Set<string>) {
+  return (argv: Arguments) => {
+    for (const name of optionNames) {
+      if (name in argv) {
+        const value = argv[name];
+        const dashedName = strings.dasherize(name);
+        const newValue = coerceToStringMap(dashedName, value as (string | undefined)[]);
+        argv[name] = argv[dashedName] = newValue;
+      }
+    }
+  };
+}
+
+function isStringMap(node: json.JsonObject) {
+  if (node.properties) {
+    return false;
+  }
+  if (node.patternProperties) {
+    return false;
+  }
+  if (!json.isJsonObject(node.additionalProperties)) {
+    return false;
+  }
+
+  if (node.additionalProperties?.type !== 'string') {
+    return false;
+  }
+  if (node.additionalProperties?.enum) {
+    return false;
+  }
+
+  return true;
 }
 
 export async function parseJsonSchemaToOptions(
@@ -106,10 +175,13 @@ export async function parseJsonSchemaToOptions(
 
           return false;
 
+        case 'object':
+          return isStringMap(current);
+
         default:
           return false;
       }
-    }) as ('string' | 'number' | 'boolean' | 'array')[];
+    }) as ('string' | 'number' | 'boolean' | 'array' | 'object')[];
 
     if (types.length == 0) {
       // This means it's not usable on the command line. e.g. an Object.
@@ -150,7 +222,6 @@ export async function parseJsonSchemaToOptions(
       }
     }
 
-    const type = types[0];
     const $default = current.$default;
     const $defaultIndex =
       json.isJsonObject($default) && $default['$source'] == 'argv' ? $default['index'] : undefined;
@@ -182,16 +253,23 @@ export async function parseJsonSchemaToOptions(
     const option: Option = {
       name,
       description: '' + (current.description === undefined ? '' : current.description),
-      type,
       default: defaultValue,
       choices: enumValues.length ? enumValues : undefined,
-      required,
       alias,
       format,
       hidden,
       userAnalytics,
       deprecated,
       positional,
+      ...(types[0] === 'object'
+        ? {
+            type: 'array',
+            coerce: coerceToStringMap.bind(null, strings.dasherize(name)),
+            itemValueType: 'string',
+          }
+        : {
+            type: types[0],
+          }),
     };
 
     options.push(option);
@@ -211,3 +289,93 @@ export async function parseJsonSchemaToOptions(
     return a.name.localeCompare(b.name);
   });
 }
+
+/**
+ * Adds schema options to a command also this keeps track of options that are required for analytics.
+ * **Note:** This method should be called from the command bundler method.
+ *
+ * @returns A map from option name to analytics configuration.
+ */
+export function addSchemaOptionsToCommand<T>(
+  localYargs: Argv<T>,
+  options: Option[],
+  includeDefaultValues: boolean,
+): Map<string, string> {
+  const booleanOptionsWithNoPrefix = new Set<string>();
+  const keyValuePairOptions = new Set<string>();
+  const optionsWithAnalytics = new Map<string, string>();
+
+  for (const option of options) {
+    const {
+      default: defaultVal,
+      positional,
+      deprecated,
+      description,
+      alias,
+      userAnalytics,
+      type,
+      itemValueType,
+      hidden,
+      name,
+      choices,
+    } = option;
+
+    const sharedOptions: YargsOptions & PositionalOptions = {
+      alias,
+      hidden,
+      description,
+      deprecated,
+      choices,
+      // This should only be done when `--help` is used otherwise default will override options set in angular.json.
+      ...(includeDefaultValues ? { default: defaultVal } : {}),
+    };
+
+    let dashedName = strings.dasherize(name);
+
+    // Handle options which have been defined in the schema with `no` prefix.
+    if (type === 'boolean' && dashedName.startsWith('no-')) {
+      dashedName = dashedName.slice(3);
+      booleanOptionsWithNoPrefix.add(dashedName);
+    }
+
+    if (itemValueType) {
+      keyValuePairOptions.add(name);
+    }
+
+    if (positional === undefined) {
+      localYargs = localYargs.option(dashedName, {
+        array: itemValueType ? true : undefined,
+        type: itemValueType ?? type,
+        ...sharedOptions,
+      });
+    } else {
+      localYargs = localYargs.positional(dashedName, {
+        type: type === 'array' || type === 'count' ? 'string' : type,
+        ...sharedOptions,
+      });
+    }
+
+    // Record option of analytics.
+    if (userAnalytics !== undefined) {
+      optionsWithAnalytics.set(name, userAnalytics);
+    }
+  }
+
+  // Handle options which have been defined in the schema with `no` prefix.
+  if (booleanOptionsWithNoPrefix.size) {
+    localYargs.middleware((options: Arguments) => {
+      for (const key of booleanOptionsWithNoPrefix) {
+        if (key in options) {
+          options[`no-${key}`] = !options[key];
+          delete options[key];
+        }
+      }
+    }, false);
+  }
+
+  if (keyValuePairOptions.size) {
+    localYargs.middleware(stringMapMiddleware(keyValuePairOptions), true);
+  }
+
+  return optionsWithAnalytics;
+}