refactor(@angular/cli): introspect yargs to generate JSON Help

alan-agius4 · alan-agius4 · commit 29c2b3a36041 · 2022-03-09T17:18:53.000+01:00
With this change we update yargs help method to output help in JSON format which is needed to generate the documents that are used to generate AIO man pages.
diff --git a/packages/angular/cli/lib/cli/command-runner.ts b/packages/angular/cli/lib/cli/command-runner.ts
@@ -27,7 +27,12 @@ import { TestCommandModule } from '../../commands/test/cli';
 import { UpdateCommandModule } from '../../commands/update/cli';
 import { VersionCommandModule } from '../../commands/version/cli';
 import { colors } from '../../utilities/color';
-import { CommandContext, CommandModuleError } from '../../utilities/command-builder/command-module';
+import {
+  CommandContext,
+  CommandModuleError,
+  CommandScope,
+} from '../../utilities/command-builder/command-module';
+import { jsonHelpUsage } from '../../utilities/command-builder/json-help';
 import { AngularWorkspace } from '../../utilities/config';
 
 const COMMANDS = [
@@ -63,8 +68,9 @@ export async function runCommand(
     $0,
     _: positional,
     help = false,
+    jsonHelp = false,
     ...rest
-  } = yargsParser(args, { boolean: ['help'], alias: { 'collection': 'c' } });
+  } = yargsParser(args, { boolean: ['help', 'json-help'], alias: { 'collection': 'c' } });
 
   const context: CommandContext = {
     workspace,
@@ -82,13 +88,27 @@ export async function runCommand(
 
   let localYargs = yargs(args);
   for (const CommandModule of COMMANDS) {
+    if (!jsonHelp) {
+      // Skip scope validation when running with '--json-help' since it's easier to generate the output for all commands this way.
+      const scope = CommandModule.scope;
+      if ((scope === CommandScope.In && !workspace) || (scope === CommandScope.Out && workspace)) {
+        continue;
+      }
+    }
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const commandModule = new CommandModule(context) as any;
+    const describe = jsonHelp ? commandModule.fullDescribe : commandModule.describe;
 
     localYargs = localYargs.command({
       command: commandModule.command,
       aliases: commandModule.aliases,
-      describe: commandModule.describe,
+      describe:
+        // We cannot add custom fields in help, such as long command description which is used in AIO.
+        // Therefore, we get around this by adding a complex object as a string which we later parse when geneerating the help files.
+        describe !== undefined && typeof describe === 'object'
+          ? JSON.stringify(describe)
+          : describe,
       deprecated: commandModule.deprecated,
       builder: (x) => commandModule.builder(x),
       handler: ({ _, $0, ...options }) => {
@@ -103,6 +123,11 @@ export async function runCommand(
     });
   }
 
+  if (jsonHelp) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (localYargs as any).getInternalMethods().getUsageInstance().help = () => jsonHelpUsage();
+  }
+
   await localYargs
     .scriptName('ng')
     // https://github.com/yargs/yargs/blob/main/docs/advanced.md#customizing-yargs-parser
diff --git a/packages/angular/cli/utilities/command-builder/command-module.ts b/packages/angular/cli/utilities/command-builder/command-module.ts
@@ -62,6 +62,7 @@ export interface CommandModuleImplementation<T extends {} = {}>
 export interface FullDescribe {
   describe?: string;
   longDescription?: string;
+  longDescriptionRelativePath?: string;
 }
 
 export abstract class CommandModule<T extends {} = {}> implements CommandModuleImplementation<T> {
@@ -86,9 +87,15 @@ export abstract class CommandModule<T extends {} = {}> implements CommandModuleI
       ? false
       : {
           describe: this.describe,
-          longDescription: this.longDescriptionPath
-            ? readFileSync(this.longDescriptionPath, 'utf8')
-            : undefined,
+          ...(this.longDescriptionPath
+            ? {
+                longDescriptionRelativePath: path.relative(
+                  path.join(__dirname, '../../../../'),
+                  this.longDescriptionPath,
+                ),
+                longDescription: readFileSync(this.longDescriptionPath, 'utf8'),
+              }
+            : {}),
         };
   }
 
diff --git a/packages/angular/cli/utilities/command-builder/json-help.ts b/packages/angular/cli/utilities/command-builder/json-help.ts
@@ -0,0 +1,145 @@
+/**
+ * @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 yargs from 'yargs';
+import { FullDescribe } from './command-module';
+
+export interface JsonHelp {
+  name: string;
+  description?: string;
+  command: string;
+  longDescription?: string;
+  longDescriptionRelativePath?: string;
+  options: JsonHelpOption[];
+  subcommands?: {
+    name: string;
+    description: string;
+    aliases: string[];
+    deprecated: string | boolean;
+  }[];
+}
+
+interface JsonHelpOption {
+  name: string;
+  type?: string;
+  deprecated: boolean | string;
+  aliases?: string[];
+  default?: string;
+  required?: boolean;
+  positional?: number;
+  enum?: string[];
+  description?: string;
+}
+
+export function jsonHelpUsage(): string {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const localYargs = yargs as any;
+  const {
+    deprecatedOptions,
+    alias: aliases,
+    array,
+    string,
+    boolean,
+    number,
+    choices,
+    demandedOptions,
+    default: defaultVal,
+    hiddenOptions = [],
+  } = localYargs.getOptions();
+
+  const internalMethods = localYargs.getInternalMethods();
+  const usageInstance = internalMethods.getUsageInstance();
+  const context = internalMethods.getContext();
+  const descriptions = usageInstance.getDescriptions();
+  const groups = localYargs.getGroups();
+  const positional = groups[usageInstance.getPositionalGroupName()] as string[] | undefined;
+
+  const hidden = new Set(hiddenOptions);
+  const normalizeOptions: JsonHelpOption[] = [];
+  const allAliases = new Set([...Object.values<string[]>(aliases).flat()]);
+
+  for (const [names, type] of [
+    [array, 'array'],
+    [string, 'string'],
+    [boolean, 'boolean'],
+    [number, 'number'],
+  ]) {
+    for (const name of names) {
+      if (allAliases.has(name) || hidden.has(name)) {
+        // Ignore hidden, aliases and already visited option.
+        continue;
+      }
+
+      const positionalIndex = positional?.indexOf(name) ?? -1;
+      const alias = aliases[name];
+
+      normalizeOptions.push({
+        name,
+        type,
+        deprecated: deprecatedOptions[name],
+        aliases: alias?.length > 0 ? alias : undefined,
+        default: defaultVal[name],
+        required: demandedOptions[name],
+        enum: choices[name],
+        description: descriptions[name]?.replace('__yargsString__:', ''),
+        positional: positionalIndex >= 0 ? positionalIndex : undefined,
+      });
+    }
+  }
+
+  // https://github.com/yargs/yargs/blob/00e4ebbe3acd438e73fdb101e75b4f879eb6d345/lib/usage.ts#L124
+  const subcommands = (
+    usageInstance.getCommands() as [
+      name: string,
+      description: string,
+      isDefault: boolean,
+      aliases: string[],
+      deprecated: string | boolean,
+    ][]
+  )
+    .map(([name, description, _, aliases, deprecated]) => ({
+      name: name.split(' ', 1)[0],
+      command: name,
+      description,
+      aliases,
+      deprecated,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const parseDescription = (rawDescription: string) => {
+    try {
+      const {
+        longDescription,
+        describe: description,
+        longDescriptionRelativePath,
+      } = JSON.parse(rawDescription) as FullDescribe;
+
+      return {
+        description,
+        longDescriptionRelativePath,
+        longDescription,
+      };
+    } catch {
+      return {
+        description: rawDescription,
+      };
+    }
+  };
+
+  const [command, rawDescription] = usageInstance.getUsage()[0] ?? [];
+
+  const output: JsonHelp = {
+    name: [...context.commands].pop(),
+    command: command?.replace('$0', localYargs['$0']),
+    ...parseDescription(rawDescription),
+    options: normalizeOptions.sort((a, b) => a.name.localeCompare(b.name)),
+    subcommands: subcommands.length ? subcommands : undefined,
+  };
+
+  return JSON.stringify(output, undefined, 2);
+}
diff --git a/scripts/json-help.ts b/scripts/json-help.ts
@@ -0,0 +1,93 @@
+/**
+ * @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 { logging } from '@angular-devkit/core';
+import { spawn } from 'child_process';
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import { JsonHelp } from 'packages/angular/cli/utilities/command-builder/json-help';
+import * as path from 'path';
+import { packages } from '../lib/packages';
+import create from './create';
+
+export default async function (opts = {}, logger: logging.Logger) {
+  logger.info('Creating temporary project...');
+  const newProjectTempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'angular-cli-create-'));
+  const newProjectName = 'help-project';
+  const newProjectRoot = path.join(newProjectTempRoot, newProjectName);
+  await create({ _: [newProjectName] }, logger.createChild('create'), newProjectTempRoot);
+
+  logger.info('Gathering JSON Help...');
+  const ngPath = path.join(newProjectRoot, 'node_modules/.bin/ng');
+  const helpOutputRoot = path.join(packages['@angular/cli'].dist, 'help');
+  await fs.mkdir(helpOutputRoot);
+
+  const runNgCommandJsonHelp = async (args: string[]) => {
+    const process = spawn(ngPath, [...args, '--json-help', '--help'], {
+      cwd: newProjectRoot,
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+
+    let result = '';
+    process.stdout.on('data', (data) => {
+      result += data.toString();
+    });
+
+    return new Promise<JsonHelp>((resolve, reject) => {
+      process
+        .on('close', (code) => {
+          if (code === 0) {
+            resolve(JSON.parse(result.trim()));
+          } else {
+            reject(
+              new Error(
+                `Command failed: ${ngPath} ${args.map((x) => JSON.stringify(x)).join(', ')}`,
+              ),
+            );
+          }
+        })
+        .on('error', (err) => reject(err));
+    });
+  };
+
+  const { subcommands: commands = [] } = await runNgCommandJsonHelp([]);
+  const commandsHelp = commands.map((command) =>
+    runNgCommandJsonHelp([command.name]).then((c) => ({
+      ...command,
+      ...c,
+    })),
+  );
+
+  for await (const command of commandsHelp) {
+    const commandName = command.name;
+    const commandOptionNames = new Set([...command.options.map(({ name }) => name)]);
+
+    const subCommandsHelp = command.subcommands?.map((subcommand) =>
+      runNgCommandJsonHelp([command.name, subcommand.name]).then((s) => ({
+        ...s,
+        ...subcommand,
+        // Filter options which are inherited from the parent command.
+        // Ex: `interactive` in `ng generate lib`.
+        options: s.options.filter((o) => !commandOptionNames.has(o.name)),
+      })),
+    );
+
+    const jsonOutput = JSON.stringify(
+      {
+        ...command,
+        subcommands: subCommandsHelp ? await Promise.all(subCommandsHelp) : undefined,
+      },
+      undefined,
+      2,
+    );
+
+    const filePath = path.join(helpOutputRoot, commandName + '.json');
+    await fs.writeFile(filePath, jsonOutput);
+    logger.info(filePath);
+  }
+}
diff --git a/scripts/snapshots.ts b/scripts/snapshots.ts
@@ -13,7 +13,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { PackageInfo, packages } from '../lib/packages';
 import build from './build-bazel';
-import create from './create';
+import jsonHelp from './json-help';
 
 // Added to the README.md of the snapshot. This is markdown.
 const readmeHeaderFn = (pkg: PackageInfo) => `
@@ -164,31 +164,12 @@ export default async function (opts: SnapshotsOptions, logger: logging.Logger) {
     _exec('git', ['config', '--global', 'push.default', 'simple'], {}, logger);
   }
 
-  // Creating a new project and reading the help.
-  logger.info('Creating temporary project...');
-  const newProjectTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'angular-cli-create-'));
-  const newProjectName = 'help-project';
-  const newProjectRoot = path.join(newProjectTempRoot, newProjectName);
-  await create({ _: [newProjectName] }, logger.createChild('create'), newProjectTempRoot);
+  await jsonHelp(undefined, logger);
 
   // Run build.
   logger.info('Building...');
   await build({ snapshot: true }, logger.createChild('build'));
 
-  logger.info('Gathering JSON Help...');
-  const ngPath = path.join(newProjectRoot, 'node_modules/.bin/ng');
-  const helpOutputRoot = path.join(packages['@angular/cli'].dist, 'help');
-  fs.mkdirSync(helpOutputRoot);
-  const commands = require('../packages/angular/cli/commands.json');
-  for (const commandName of Object.keys(commands)) {
-    const options = { cwd: newProjectRoot };
-    const childLogger = logger.createChild(commandName);
-    const stdout = _exec(ngPath, [commandName, '--help=json'], options, childLogger);
-    // Make sure the output is JSON before printing it, and format it as well.
-    const jsonOutput = JSON.stringify(JSON.parse(stdout.trim()), undefined, 2);
-    fs.writeFileSync(path.join(helpOutputRoot, commandName + '.json'), jsonOutput);
-  }
-
   if (!githubToken) {
     logger.info('No token given, skipping actual publishing...');
 
diff --git a/tests/legacy-cli/e2e/tests/commands/help/help-json.ts b/tests/legacy-cli/e2e/tests/commands/help/help-json.ts
