hardhatjs 2.22.15

package/src/internal/cli/ArgumentsParser.ts

@@ -0,0 +1,358 @@
+import { TASK_HELP } from "../../builtin-tasks/task-names";
+import {
+  CLIArgumentType,
+  HardhatArguments,
+  HardhatParamDefinitions,
+  ParamDefinition,
+  ParamDefinitionsMap,
+  ScopesMap,
+  TaskArguments,
+  TaskDefinition,
+  TasksMap,
+} from "../../types";
+import { HardhatError } from "../core/errors";
+import { ERRORS } from "../core/errors-list";
+
+export class ArgumentsParser {
+  public static readonly PARAM_PREFIX = "--";
+
+  public static paramNameToCLA(paramName: string): string {
+    return (
+      ArgumentsParser.PARAM_PREFIX +
+      paramName
+        .split(/(?=[A-Z])/g)
+        .map((s) => s.toLowerCase())
+        .join("-")
+    );
+  }
+
+  public static cLAToParamName(cLA: string): string {
+    if (cLA.toLowerCase() !== cLA) {
+      throw new HardhatError(ERRORS.ARGUMENTS.PARAM_NAME_INVALID_CASING, {
+        param: cLA,
+      });
+    }
+
+    const parts = cLA
+      .slice(ArgumentsParser.PARAM_PREFIX.length)
+      .split("-")
+      .filter((x) => x.length > 0);
+
+    return (
+      parts[0] +
+      parts
+        .slice(1)
+        .map((s) => s[0].toUpperCase() + s.slice(1))
+        .join("")
+    );
+  }
+
+  public parseHardhatArguments(
+    hardhatParamDefinitions: HardhatParamDefinitions,
+    envVariableArguments: HardhatArguments,
+    rawCLAs: string[]
+  ): {
+    hardhatArguments: HardhatArguments;
+    scopeOrTaskName: string | undefined;
+    allUnparsedCLAs: string[];
+  } {
+    const hardhatArguments: Partial<HardhatArguments> = {};
+    let scopeOrTaskName: string | undefined;
+    const allUnparsedCLAs: string[] = [];
+
+    for (let i = 0; i < rawCLAs.length; i++) {
+      const arg = rawCLAs[i];
+
+      if (scopeOrTaskName === undefined) {
+        if (!this._hasCLAParamNameFormat(arg)) {
+          scopeOrTaskName = arg;
+          allUnparsedCLAs.push(arg);
+          continue;
+        }
+
+        if (!this._isCLAParamName(arg, hardhatParamDefinitions)) {
+          throw new HardhatError(
+            ERRORS.ARGUMENTS.UNRECOGNIZED_COMMAND_LINE_ARG,
+            { argument: arg }
+          );
+        }
+
+        i = this._parseArgumentAt(
+          rawCLAs,
+          i,
+          hardhatParamDefinitions,
+          hardhatArguments,
+          scopeOrTaskName
+        );
+      } else {
+        if (!this._isCLAParamName(arg, hardhatParamDefinitions)) {
+          allUnparsedCLAs.push(arg);
+          continue;
+        }
+
+        i = this._parseArgumentAt(
+          rawCLAs,
+          i,
+          hardhatParamDefinitions,
+          hardhatArguments,
+          scopeOrTaskName
+        );
+      }
+    }
+
+    return {
+      hardhatArguments: this._addHardhatDefaultArguments(
+        hardhatParamDefinitions,
+        envVariableArguments,
+        hardhatArguments
+      ),
+      scopeOrTaskName,
+      allUnparsedCLAs,
+    };
+  }
+
+  public parseScopeAndTaskNames(
+    allUnparsedCLAs: string[],
+    taskDefinitions: TasksMap,
+    scopeDefinitions: ScopesMap
+  ): {
+    scopeName?: string;
+    taskName: string;
+    unparsedCLAs: string[];
+  } {
+    const [firstCLA, secondCLA] = allUnparsedCLAs;
+
+    if (allUnparsedCLAs.length === 0) {
+      return {
+        taskName: TASK_HELP,
+        unparsedCLAs: [],
+      };
+    } else if (allUnparsedCLAs.length === 1) {
+      if (scopeDefinitions[firstCLA] !== undefined) {
+        // this is a bit of a hack, but it's the easiest way to print
+        // the help of a scope when no task is specified
+        return {
+          taskName: TASK_HELP,
+          unparsedCLAs: [firstCLA],
+        };
+      } else if (taskDefinitions[firstCLA] !== undefined) {
+        return {
+          taskName: firstCLA,
+          unparsedCLAs: allUnparsedCLAs.slice(1),
+        };
+      } else {
+        throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_TASK, {
+          task: firstCLA,
+        });
+      }
+    } else {
+      const scopeDefinition = scopeDefinitions[firstCLA];
+      if (scopeDefinition !== undefined) {
+        if (scopeDefinition.tasks[secondCLA] !== undefined) {
+          return {
+            scopeName: firstCLA,
+            taskName: secondCLA,
+            unparsedCLAs: allUnparsedCLAs.slice(2),
+          };
+        } else {
+          throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPED_TASK, {
+            scope: firstCLA,
+            task: secondCLA,
+          });
+        }
+      } else if (taskDefinitions[firstCLA] !== undefined) {
+        return {
+          taskName: firstCLA,
+          unparsedCLAs: allUnparsedCLAs.slice(1),
+        };
+      } else {
+        throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_TASK, {
+          task: firstCLA,
+        });
+      }
+    }
+  }
+
+  public parseTaskArguments(
+    taskDefinition: TaskDefinition,
+    rawCLAs: string[]
+  ): TaskArguments {
+    const { paramArguments, rawPositionalArguments } =
+      this._parseTaskParamArguments(taskDefinition, rawCLAs);
+
+    const positionalArguments = this._parsePositionalParamArgs(
+      rawPositionalArguments,
+      taskDefinition.positionalParamDefinitions
+    );
+
+    return { ...paramArguments, ...positionalArguments };
+  }
+
+  private _parseTaskParamArguments(
+    taskDefinition: TaskDefinition,
+    rawCLAs: string[]
+  ) {
+    const paramArguments = {};
+    const rawPositionalArguments: string[] = [];
+
+    for (let i = 0; i < rawCLAs.length; i++) {
+      const arg = rawCLAs[i];
+
+      if (!this._hasCLAParamNameFormat(arg)) {
+        rawPositionalArguments.push(arg);
+        continue;
+      }
+
+      if (!this._isCLAParamName(arg, taskDefinition.paramDefinitions)) {
+        throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_PARAM_NAME, {
+          param: arg,
+        });
+      }
+
+      i = this._parseArgumentAt(
+        rawCLAs,
+        i,
+        taskDefinition.paramDefinitions,
+        paramArguments,
+        taskDefinition.name
+      );
+    }
+
+    this._addTaskDefaultArguments(taskDefinition, paramArguments);
+
+    return { paramArguments, rawPositionalArguments };
+  }
+
+  private _addHardhatDefaultArguments(
+    hardhatParamDefinitions: HardhatParamDefinitions,
+    envVariableArguments: HardhatArguments,
+    hardhatArguments: Partial<HardhatArguments>
+  ): HardhatArguments {
+    return {
+      ...envVariableArguments,
+      ...hardhatArguments,
+    };
+  }
+
+  private _addTaskDefaultArguments(
+    taskDefinition: TaskDefinition,
+    taskArguments: TaskArguments
+  ) {
+    for (const paramName of Object.keys(taskDefinition.paramDefinitions)) {
+      const definition = taskDefinition.paramDefinitions[paramName];
+
+      if (taskArguments[paramName] !== undefined) {
+        continue;
+      }
+      if (!definition.isOptional) {
+        throw new HardhatError(ERRORS.ARGUMENTS.MISSING_TASK_ARGUMENT, {
+          param: ArgumentsParser.paramNameToCLA(paramName),
+          task: taskDefinition.name,
+        });
+      }
+
+      taskArguments[paramName] = definition.defaultValue;
+    }
+  }
+
+  private _isCLAParamName(str: string, paramDefinitions: ParamDefinitionsMap) {
+    if (!this._hasCLAParamNameFormat(str)) {
+      return false;
+    }
+
+    const name = ArgumentsParser.cLAToParamName(str);
+    return paramDefinitions[name] !== undefined;
+  }
+
+  private _hasCLAParamNameFormat(str: string) {
+    return str.startsWith(ArgumentsParser.PARAM_PREFIX);
+  }
+
+  private _parseArgumentAt(
+    rawCLAs: string[],
+    index: number,
+    paramDefinitions: ParamDefinitionsMap,
+    parsedArguments: TaskArguments,
+    scopeOrTaskName?: string
+  ) {
+    const claArg = rawCLAs[index];
+    const paramName = ArgumentsParser.cLAToParamName(claArg);
+    const definition = paramDefinitions[paramName];
+
+    if (parsedArguments[paramName] !== undefined) {
+      throw new HardhatError(ERRORS.ARGUMENTS.REPEATED_PARAM, {
+        param: claArg,
+      });
+    }
+
+    if (definition.isFlag) {
+      parsedArguments[paramName] = true;
+    } else {
+      index++;
+      const value = rawCLAs[index];
+
+      if (value === undefined) {
+        throw new HardhatError(ERRORS.ARGUMENTS.MISSING_TASK_ARGUMENT, {
+          param: ArgumentsParser.paramNameToCLA(paramName),
+          task: scopeOrTaskName ?? "help",
+        });
+      }
+
+      // We only parse the arguments of non-subtasks, and those only
+      // accept CLIArgumentTypes.
+      const type = definition.type as CLIArgumentType<any>;
+      parsedArguments[paramName] = type.parse(paramName, value);
+    }
+
+    return index;
+  }
+
+  private _parsePositionalParamArgs(
+    rawPositionalParamArgs: string[],
+    positionalParamDefinitions: Array<ParamDefinition<any>>
+  ): TaskArguments {
+    const args: TaskArguments = {};
+
+    for (let i = 0; i < positionalParamDefinitions.length; i++) {
+      const definition = positionalParamDefinitions[i];
+      // We only parse the arguments of non-subtasks, and those only
+      // accept CLIArgumentTypes.
+      const type = definition.type as CLIArgumentType<any>;
+
+      const rawArg = rawPositionalParamArgs[i];
+
+      if (rawArg === undefined) {
+        if (!definition.isOptional) {
+          throw new HardhatError(ERRORS.ARGUMENTS.MISSING_POSITIONAL_ARG, {
+            param: definition.name,
+          });
+        }
+
+        args[definition.name] = definition.defaultValue;
+      } else if (!definition.isVariadic) {
+        args[definition.name] = type.parse(definition.name, rawArg);
+      } else {
+        args[definition.name] = rawPositionalParamArgs
+          .slice(i)
+          .map((raw) => type.parse(definition.name, raw));
+      }
+    }
+
+    const lastDefinition =
+      positionalParamDefinitions[positionalParamDefinitions.length - 1];
+
+    const hasVariadicParam =
+      lastDefinition !== undefined && lastDefinition.isVariadic;
+
+    if (
+      !hasVariadicParam &&
+      rawPositionalParamArgs.length > positionalParamDefinitions.length
+    ) {
+      throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_POSITIONAL_ARG, {
+        argument: rawPositionalParamArgs[positionalParamDefinitions.length],
+      });
+    }
+
+    return args;
+  }
+}

package/src/internal/cli/HelpPrinter.ts

@@ -0,0 +1,278 @@
+import {
+  HardhatParamDefinitions,
+  ParamDefinition,
+  ParamDefinitionsMap,
+  ScopeDefinition,
+  ScopesMap,
+  TaskDefinition,
+  TasksMap,
+} from "../../types";
+import { HardhatError } from "../core/errors";
+import { ERRORS } from "../core/errors-list";
+
+import { ArgumentsParser } from "./ArgumentsParser";
+
+export class HelpPrinter {
+  constructor(
+    private readonly _programName: string,
+    private readonly _executableName: string,
+    private readonly _version: string,
+    private readonly _hardhatParamDefinitions: HardhatParamDefinitions,
+    private readonly _tasks: TasksMap,
+    private readonly _scopes: ScopesMap
+  ) {}
+
+  public printGlobalHelp(includeSubtasks = false) {
+    console.log(`${this._programName} version ${this._version}\n`);
+
+    console.log(
+      `Usage: ${this._executableName} [GLOBAL OPTIONS] [SCOPE] <TASK> [TASK OPTIONS]\n`
+    );
+
+    console.log("GLOBAL OPTIONS:\n");
+
+    let length = this._printParamDetails(this._hardhatParamDefinitions);
+
+    console.log("\n\nAVAILABLE TASKS:\n");
+
+    length = this._printTasks(this._tasks, includeSubtasks, length);
+
+    if (Object.keys(this._scopes).length > 0) {
+      console.log("\n\nAVAILABLE TASK SCOPES:\n");
+
+      this._printScopes(this._scopes, length);
+    }
+
+    console.log("");
+
+    console.log(
+      `To get help for a specific task run: npx ${this._executableName} help [SCOPE] <TASK>\n`
+    );
+  }
+
+  public printScopeHelp(
+    scopeDefinition: ScopeDefinition,
+    includeSubtasks = false
+  ) {
+    const name = scopeDefinition.name;
+    const description = scopeDefinition.description ?? "";
+
+    console.log(`${this._programName} version ${this._version}`);
+
+    console.log(
+      `\nUsage: hardhat [GLOBAL OPTIONS] ${name} <TASK> [TASK OPTIONS]`
+    );
+
+    console.log(`\nAVAILABLE TASKS:\n`);
+
+    if (this._scopes[name] === undefined) {
+      throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPE, {
+        scope: name,
+      });
+    }
+
+    this._printTasks(this._scopes[name].tasks, includeSubtasks);
+
+    console.log(`\n${name}: ${description}`);
+
+    console.log(
+      `\nFor global options help run: ${this._executableName} help\n`
+    );
+  }
+
+  public printTaskHelp(taskDefinition: TaskDefinition) {
+    const {
+      description = "",
+      name,
+      paramDefinitions,
+      positionalParamDefinitions,
+    } = taskDefinition;
+
+    console.log(`${this._programName} version ${this._version}\n`);
+
+    const paramsList = this._getParamsList(paramDefinitions);
+    const positionalParamsList = this._getPositionalParamsList(
+      positionalParamDefinitions
+    );
+
+    const scope =
+      taskDefinition.scope !== undefined ? `${taskDefinition.scope} ` : "";
+
+    console.log(
+      `Usage: ${this._executableName} [GLOBAL OPTIONS] ${scope}${name}${paramsList}${positionalParamsList}\n`
+    );
+
+    if (Object.keys(paramDefinitions).length > 0) {
+      console.log("OPTIONS:\n");
+
+      this._printParamDetails(paramDefinitions);
+
+      console.log("");
+    }
+
+    if (positionalParamDefinitions.length > 0) {
+      console.log("POSITIONAL ARGUMENTS:\n");
+
+      this._printPositionalParamDetails(positionalParamDefinitions);
+
+      console.log("");
+    }
+
+    console.log(`${name}: ${description}\n`);
+
+    console.log(`For global options help run: ${this._executableName} help\n`);
+  }
+
+  private _printTasks(
+    tasksMap: TasksMap,
+    includeSubtasks: boolean,
+    length: number = 0
+  ) {
+    const taskNameList = Object.entries(tasksMap)
+      .filter(
+        ([, taskDefinition]) => includeSubtasks || !taskDefinition.isSubtask
+      )
+      .map(([taskName]) => taskName)
+      .sort();
+
+    const nameLength = taskNameList
+      .map((n) => n.length)
+      .reduce((a, b) => Math.max(a, b), length);
+
+    for (const name of taskNameList) {
+      const { description = "" } = tasksMap[name];
+
+      console.log(`  ${name.padEnd(nameLength)}\t${description}`);
+    }
+
+    return nameLength;
+  }
+
+  private _printScopes(scopesMap: ScopesMap, length: number) {
+    const scopeNamesList = Object.entries(scopesMap)
+      .map(([scopeName]) => scopeName)
+      .sort();
+
+    const nameLength = scopeNamesList
+      .map((n) => n.length)
+      .reduce((a, b) => Math.max(a, b), length);
+
+    for (const name of scopeNamesList) {
+      const { description = "" } = scopesMap[name];
+
+      console.log(`  ${name.padEnd(nameLength)}\t${description}`);
+    }
+
+    return nameLength;
+  }
+
+  private _getParamValueDescription<T>(paramDefinition: ParamDefinition<T>) {
+    return `<${paramDefinition.type.name.toUpperCase()}>`;
+  }
+
+  private _getParamsList(paramDefinitions: ParamDefinitionsMap) {
+    let paramsList = "";
+
+    for (const name of Object.keys(paramDefinitions).sort()) {
+      const definition = paramDefinitions[name];
+      const { isFlag, isOptional } = definition;
+
+      paramsList += " ";
+
+      if (isOptional) {
+        paramsList += "[";
+      }
+
+      paramsList += `${ArgumentsParser.paramNameToCLA(name)}`;
+
+      if (!isFlag) {
+        paramsList += ` ${this._getParamValueDescription(definition)}`;
+      }
+
+      if (isOptional) {
+        paramsList += "]";
+      }
+    }
+
+    return paramsList;
+  }
+
+  private _getPositionalParamsList(
+    positionalParamDefinitions: Array<ParamDefinition<any>>
+  ) {
+    let paramsList = "";
+
+    for (const definition of positionalParamDefinitions) {
+      const { isOptional, isVariadic, name } = definition;
+
+      paramsList += " ";
+
+      if (isOptional) {
+        paramsList += "[";
+      }
+
+      if (isVariadic) {
+        paramsList += "...";
+      }
+
+      paramsList += name;
+
+      if (isOptional) {
+        paramsList += "]";
+      }
+    }
+
+    return paramsList;
+  }
+
+  private _printParamDetails(paramDefinitions: ParamDefinitionsMap): number {
+    const paramsNameLength = Object.keys(paramDefinitions)
+      .map((n) => ArgumentsParser.paramNameToCLA(n).length)
+      .reduce((a, b) => Math.max(a, b), 0);
+
+    for (const name of Object.keys(paramDefinitions).sort()) {
+      const { description, defaultValue, isOptional, isFlag } =
+        paramDefinitions[name];
+
+      let msg = `  ${ArgumentsParser.paramNameToCLA(name).padEnd(
+        paramsNameLength
+      )}\t`;
+
+      if (description !== undefined) {
+        msg += `${description} `;
+      }
+
+      if (isOptional && defaultValue !== undefined && !isFlag) {
+        msg += `(default: ${JSON.stringify(defaultValue)})`;
+      }
+
+      console.log(msg);
+    }
+
+    return paramsNameLength;
+  }
+
+  private _printPositionalParamDetails(
+    positionalParamDefinitions: Array<ParamDefinition<any>>
+  ) {
+    const paramsNameLength = positionalParamDefinitions
+      .map((d) => d.name.length)
+      .reduce((a, b) => Math.max(a, b), 0);
+
+    for (const definition of positionalParamDefinitions) {
+      const { name, description, isOptional, defaultValue } = definition;
+
+      let msg = `  ${name.padEnd(paramsNameLength)}\t`;
+
+      if (description !== undefined) {
+        msg += `${description} `;
+      }
+
+      if (isOptional && defaultValue !== undefined) {
+        msg += `(default: ${JSON.stringify(defaultValue)})`;
+      }
+
+      console.log(msg);
+    }
+  }
+}