hardhat 2.17.4 → 2.18.0

package/src/internal/cli/HelpPrinter.ts

@@ -2,6 +2,9 @@ import {
   HardhatParamDefinitions,
   ParamDefinition,
   ParamDefinitionsMap,
+  ScopeDefinition,
+  ScopesMap,
+  TaskDefinition,
   TasksMap,
 } from "../../types";
 import { HardhatError } from "../core/errors";
@@ -15,55 +18,69 @@ export class HelpPrinter {
     private readonly _executableName: string,
     private readonly _version: string,
     private readonly _hardhatParamDefinitions: HardhatParamDefinitions,
-    private readonly _tasks: TasksMap
+    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] <TASK> [TASK OPTIONS]\n`
+      `Usage: ${this._executableName} [GLOBAL OPTIONS] [SCOPE] <TASK> [TASK OPTIONS]\n`
     );
 
     console.log("GLOBAL OPTIONS:\n");
 
-    this._printParamDetails(this._hardhatParamDefinitions);
+    let length = this._printParamDetails(this._hardhatParamDefinitions);
 
     console.log("\n\nAVAILABLE TASKS:\n");
 
-    const tasksToShow: TasksMap = {};
-    for (const [taskName, taskDefinition] of Object.entries(this._tasks)) {
-      if (includeSubtasks || !taskDefinition.isSubtask) {
-        tasksToShow[taskName] = taskDefinition;
-      }
-    }
-
-    const nameLength = Object.keys(tasksToShow)
-      .map((n) => n.length)
-      .reduce((a, b) => Math.max(a, b), 0);
+    length = this._printTasks(this._tasks, includeSubtasks, length);
 
-    for (const name of Object.keys(tasksToShow).sort()) {
-      const { description = "" } = this._tasks[name];
+    if (Object.keys(this._scopes).length > 0) {
+      console.log("\n\nAVAILABLE TASK SCOPES:\n");
 
-      console.log(`  ${name.padEnd(nameLength)}\t${description}`);
+      this._printScopes(this._scopes, length);
     }
 
     console.log("");
 
     console.log(
-      `To get help for a specific task run: npx ${this._executableName} help [task]\n`
+      `To get help for a specific task run: npx ${this._executableName} help [SCOPE] <TASK>\n`
     );
   }
 
-  public printTaskHelp(taskName: string) {
-    const taskDefinition = this._tasks[taskName];
+  public printScopeHelp(
+    scopeDefinition: ScopeDefinition,
+    includeSubtasks = false
+  ) {
+    const name = scopeDefinition.name;
+    const description = scopeDefinition.description ?? "";
+
+    console.log(`${this._programName} version ${this._version}`);
 
-    if (taskDefinition === undefined) {
-      throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_TASK, {
-        task: taskName,
+    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,
@@ -78,8 +95,11 @@ export class HelpPrinter {
       positionalParamDefinitions
     );
 
+    const scope =
+      taskDefinition.scope !== undefined ? `${taskDefinition.scope} ` : "";
+
     console.log(
-      `Usage: ${this._executableName} [GLOBAL OPTIONS] ${name}${paramsList}${positionalParamsList}\n`
+      `Usage: ${this._executableName} [GLOBAL OPTIONS] ${scope}${name}${paramsList}${positionalParamsList}\n`
     );
 
     if (Object.keys(paramDefinitions).length > 0) {
@@ -103,6 +123,49 @@ export class HelpPrinter {
     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()}>`;
   }
@@ -162,7 +225,7 @@ export class HelpPrinter {
     return paramsList;
   }
 
-  private _printParamDetails(paramDefinitions: ParamDefinitionsMap) {
+  private _printParamDetails(paramDefinitions: ParamDefinitionsMap): number {
     const paramsNameLength = Object.keys(paramDefinitions)
       .map((n) => ArgumentsParser.paramNameToCLA(n).length)
       .reduce((a, b) => Math.max(a, b), 0);
@@ -185,6 +248,8 @@ export class HelpPrinter {
 
       console.log(msg);
     }
+
+    return paramsNameLength;
   }
 
   private _printPositionalParamDetails(

package/src/internal/cli/cli.ts

@@ -127,15 +127,12 @@ async function main() {
 
     const argumentsParser = new ArgumentsParser();
 
-    const {
-      hardhatArguments,
-      taskName: parsedTaskName,
-      unparsedCLAs,
-    } = argumentsParser.parseHardhatArguments(
-      HARDHAT_PARAM_DEFINITIONS,
-      envVariableArguments,
-      process.argv.slice(2)
-    );
+    const { hardhatArguments, scopeOrTaskName, allUnparsedCLAs } =
+      argumentsParser.parseHardhatArguments(
+        HARDHAT_PARAM_DEFINITIONS,
+        envVariableArguments,
+        process.argv.slice(2)
+      );
 
     if (hardhatArguments.verbose) {
       Reporter.setVerbose(true);
@@ -160,13 +157,13 @@ async function main() {
     // The code marked with the tag #INIT-DEP can be deleted after HarhatV3 is out.
 
     // Create a new Hardhat project
-    if (parsedTaskName === "init") {
+    if (scopeOrTaskName === "init") {
       return await createNewProject();
     }
     // #INIT-DEP - START OF DEPRECATED CODE
     else {
       if (
-        parsedTaskName === undefined &&
+        scopeOrTaskName === undefined &&
         hardhatArguments.config === undefined &&
         !isCwdInsideProject()
       ) {
@@ -213,21 +210,29 @@ async function main() {
       }
     }
 
-    let taskName = parsedTaskName ?? TASK_HELP;
-
-    const showEmptyConfigWarning = true;
-    const showSolidityConfigWarnings = taskName === TASK_COMPILE;
-
     const ctx = HardhatContext.createHardhatContext();
 
     const { resolvedConfig, userConfig } = loadConfigAndTasks(
       hardhatArguments,
       {
-        showEmptyConfigWarning,
-        showSolidityConfigWarnings,
+        showEmptyConfigWarning: true,
+        showSolidityConfigWarnings: scopeOrTaskName === TASK_COMPILE,
       }
     );
 
+    const envExtenders = ctx.environmentExtenders;
+    const providerExtenders = ctx.providerExtenders;
+    const taskDefinitions = ctx.tasksDSL.getTaskDefinitions();
+    const scopesDefinitions = ctx.tasksDSL.getScopesDefinitions();
+
+    // eslint-disable-next-line prefer-const
+    let { scopeName, taskName, unparsedCLAs } =
+      argumentsParser.parseScopeAndTaskNames(
+        allUnparsedCLAs,
+        taskDefinitions,
+        scopesDefinitions
+      );
+
     let telemetryConsent: boolean | undefined = hasConsentedTelemetry();
 
     const isHelpCommand = hardhatArguments.help || taskName === TASK_HELP;
@@ -252,22 +257,34 @@ async function main() {
       Reporter.setEnabled(true);
     }
 
-    const envExtenders = ctx.environmentExtenders;
-    const providerExtenders = ctx.providerExtenders;
-    const taskDefinitions = ctx.tasksDSL.getTaskDefinitions();
-
     const [abortAnalytics, hitPromise] = await analytics.sendTaskHit();
 
     let taskArguments: TaskArguments;
 
     // --help is a also special case
     if (hardhatArguments.help && taskName !== TASK_HELP) {
-      taskArguments = { task: taskName };
+      // we "move" the task and scope names to the task arguments,
+      // and run the help task
+      if (scopeName !== undefined) {
+        taskArguments = { scopeOrTask: scopeName, task: taskName };
+      } else {
+        taskArguments = { scopeOrTask: taskName };
+      }
       taskName = TASK_HELP;
+      scopeName = undefined;
     } else {
-      const taskDefinition = taskDefinitions[taskName];
+      const taskDefinition = ctx.tasksDSL.getTaskDefinition(
+        scopeName,
+        taskName
+      );
 
       if (taskDefinition === undefined) {
+        if (scopeName !== undefined) {
+          throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPED_TASK, {
+            scope: scopeName,
+            task: taskName,
+          });
+        }
         throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_TASK, {
           task: taskName,
         });
@@ -289,6 +306,7 @@ async function main() {
       resolvedConfig,
       hardhatArguments,
       taskDefinitions,
+      scopesDefinitions,
       envExtenders,
       ctx.experimentalHardhatNetworkMessageTraceHooks,
       userConfig,
@@ -300,7 +318,7 @@ async function main() {
     try {
       const timestampBeforeRun = new Date().getTime();
 
-      await env.run(taskName, taskArguments);
+      await env.run({ scope: scopeName, task: taskName }, taskArguments);
 
       const timestampAfterRun = new Date().getTime();
 

package/src/internal/core/config/config-env.ts

@@ -1,6 +1,7 @@
 import {
   ActionType,
   ConfigExtender,
+  ConfigurableScopeDefinition,
   ConfigurableTaskDefinition,
   EnvironmentExtender,
   ExperimentalHardhatNetworkMessageTraceHook,
@@ -116,6 +117,16 @@ export function subtask<TaskArgumentsT extends TaskArguments>(
 // Backwards compatibility alias
 export const internalTask = subtask;
 
+export function scope(
+  name: string,
+  description?: string
+): ConfigurableScopeDefinition {
+  const ctx = HardhatContext.getHardhatContext();
+  const dsl = ctx.tasksDSL;
+
+  return dsl.scope(name, description);
+}
+
 export const types = argumentTypes;
 
 /**

package/src/internal/core/errors-list.ts

@@ -613,8 +613,26 @@ Please double check your task definitions.`,
 What makes these types special is that they can be represented as strings, so you can write them down in the terminal.`,
       shouldBeReported: false,
     },
-    DEPRECATED_TRANSFORM_IMPORT_TASK: {
+    TASK_SCOPE_CLASH: {
       number: 213,
+      message:
+        "A clash was found while creating scope '%scopeName%', since a task with that name already exists.",
+      title: "Attempted to create a scope with a name already used by a task",
+      description: `You can't create a scope if a task with that name already exists.
+Please double check your task definitions.`,
+      shouldBeReported: false,
+    },
+    SCOPE_TASK_CLASH: {
+      number: 214,
+      message:
+        "A clash was found while creating task '%taskName%', since a scope with that name already exists.",
+      title: "Attempted to create a task with a name already used by a scope",
+      description: `You can't create a task if a scope with that name already exists.
+Please double check your task definitions.`,
+      shouldBeReported: false,
+    },
+    DEPRECATED_TRANSFORM_IMPORT_TASK: {
+      number: 215,
       title: "Use of deprecated remapping task",
       message:
         "Task TASK_COMPILE_TRANSFORM_IMPORT_NAME is deprecated. Please update your @nomicfoundation/hardhat-foundry plugin version.",
@@ -654,7 +672,7 @@ Please double check your arguments.`,
     },
     UNRECOGNIZED_TASK: {
       number: 303,
-      message: "Unrecognized task %task%",
+      message: "Unrecognized task '%task%'",
       title: "Unrecognized task",
       description: `Tried to run a nonexistent task.
 
@@ -756,6 +774,24 @@ This is not supported. Please run the help task to see the available options.`,
 This flag can only be used in typescript projects.`,
       shouldBeReported: false,
     },
+    UNRECOGNIZED_SCOPE: {
+      number: 314,
+      message: "Unrecognized scope '%scope%'",
+      title: "Unrecognized scope",
+      description: `Tried to run a task from a nonexistent scope.
+
+Please double check the scope of the task you are trying to run.`,
+      shouldBeReported: false,
+    },
+    UNRECOGNIZED_SCOPED_TASK: {
+      number: 315,
+      message: "Unrecognized task '%task%' under scope '%scope%'",
+      title: "Unrecognized scoped task",
+      description: `Tried to run a nonexistent scoped task.
+
+Please double check the name of the task you are trying to run.`,
+      shouldBeReported: false,
+    },
   },
   RESOLVER: {
     FILE_NOT_FOUND: {

package/src/internal/core/runtime-environment.ts

@@ -10,13 +10,14 @@ import {
   HardhatUserConfig,
   Network,
   ParamDefinition,
+  ProviderExtender,
   RunSuperFunction,
   RunTaskFunction,
   SubtaskArguments,
   TaskArguments,
   TaskDefinition,
   TasksMap,
-  ProviderExtender,
+  ScopesMap,
 } from "../../types";
 import { Artifacts } from "../artifacts";
 import { MessageTrace } from "../hardhat-network/stack-traces/message-trace";
@@ -34,6 +35,7 @@ import {
   createTaskProfile,
   TaskProfile,
 } from "./task-profiling";
+import { parseTaskIdentifier } from "./tasks/util";
 
 const log = debug("hardhat:core:hre");
 
@@ -65,6 +67,7 @@ export class Environment implements HardhatRuntimeEnvironment {
    * @param config The hardhat's config object.
    * @param hardhatArguments The parsed hardhat's arguments.
    * @param tasks A map of tasks.
+   * @param scopes A map of scopes.
    * @param environmentExtenders A list of environment extenders.
    * @param providerExtenders A list of provider extenders.
    */
@@ -72,6 +75,7 @@ export class Environment implements HardhatRuntimeEnvironment {
     public readonly config: HardhatConfig,
     public readonly hardhatArguments: HardhatArguments,
     public readonly tasks: TasksMap,
+    public readonly scopes: ScopesMap,
     environmentExtenders: EnvironmentExtender[] = [],
     experimentalHardhatNetworkMessageTraceHooks: ExperimentalHardhatNetworkMessageTraceHook[] = [],
     public readonly userConfig: HardhatUserConfig = {},
@@ -122,7 +126,7 @@ export class Environment implements HardhatRuntimeEnvironment {
   /**
    * Executes the task with the given name.
    *
-   * @param name The task's name.
+   * @param taskIdentifier The task or scoped task to be executed.
    * @param taskArguments A map of task's arguments.
    * @param subtaskArguments A map of subtasks to their arguments.
    *
@@ -130,18 +134,39 @@ export class Environment implements HardhatRuntimeEnvironment {
    * @returns a promise with the task's execution result.
    */
   public readonly run: RunTaskFunction = async (
-    name,
+    taskIdentifier,
     taskArguments = {},
     subtaskArguments = {},
     callerTaskProfile?: TaskProfile
   ) => {
-    const taskDefinition = this.tasks[name];
+    const { scope, task } = parseTaskIdentifier(taskIdentifier);
+
+    let taskDefinition;
+    if (scope === undefined) {
+      taskDefinition = this.tasks[task];
+      log("Running task %s", task);
+    } else {
+      const scopeDefinition = this.scopes[scope];
+      if (scopeDefinition === undefined) {
+        throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPE, {
+          scope,
+        });
+      }
 
-    log("Running task %s", name);
+      taskDefinition = scopeDefinition.tasks?.[task];
+      log("Running scoped task %s %s", scope, task);
+    }
 
     if (taskDefinition === undefined) {
+      if (scope !== undefined) {
+        throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPED_TASK, {
+          scope,
+          task,
+        });
+      }
+
       throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_TASK, {
-        task: name,
+        task,
       });
     }
 
@@ -153,7 +178,7 @@ export class Environment implements HardhatRuntimeEnvironment {
 
     let taskProfile: TaskProfile | undefined;
     if (this.hardhatArguments.flamegraph === true) {
-      taskProfile = createTaskProfile(name);
+      taskProfile = createTaskProfile(task);
 
       if (callerTaskProfile !== undefined) {
         callerTaskProfile.children.push(taskProfile);

package/src/internal/core/tasks/dsl.ts

@@ -1,14 +1,21 @@
 import {
   ActionType,
+  ScopeDefinition,
+  ScopesMap,
   TaskArguments,
   TaskDefinition,
+  TaskIdentifier,
   TasksMap,
 } from "../../../types";
+import { HardhatError, assertHardhatInvariant } from "../errors";
+import { ERRORS } from "../errors-list";
 
 import {
   OverriddenTaskDefinition,
+  SimpleScopeDefinition,
   SimpleTaskDefinition,
 } from "./task-definitions";
+import { parseTaskIdentifier } from "./util";
 
 /**
  * This class defines the DSL used in Hardhat config files
@@ -18,6 +25,7 @@ export class TasksDSL {
   public readonly internalTask = this.subtask;
 
   private readonly _tasks: TasksMap = {};
+  private readonly _scopes: ScopesMap = {};
 
   /**
    * Creates a task, overriding any previous task with the same name.
@@ -56,6 +64,8 @@ export class TasksDSL {
     descriptionOrAction?: string | ActionType<TaskArgumentsT>,
     action?: ActionType<TaskArgumentsT>
   ): TaskDefinition {
+    // if this function is updated, update the corresponding callback
+    // passed to `new SimpleScopeDefinition`
     return this._addTask(name, descriptionOrAction, action, false);
   }
 
@@ -96,9 +106,56 @@ export class TasksDSL {
     descriptionOrAction?: string | ActionType<TaskArgumentsT>,
     action?: ActionType<TaskArgumentsT>
   ): TaskDefinition {
+    // if this function is updated, update the corresponding callback
+    // passed to `new SimpleScopeDefinition`
     return this._addTask(name, descriptionOrAction, action, true);
   }
 
+  public scope(name: string, description?: string): ScopeDefinition {
+    if (this._tasks[name] !== undefined) {
+      throw new HardhatError(ERRORS.TASK_DEFINITIONS.TASK_SCOPE_CLASH, {
+        scopeName: name,
+      });
+    }
+
+    const scopeDefinition = this._scopes[name];
+
+    if (scopeDefinition !== undefined) {
+      // if the scope already exists, the only thing we might
+      // do is to update its description
+      if (description !== undefined) {
+        scopeDefinition.setDescription(description);
+      }
+
+      return scopeDefinition;
+    }
+
+    const scope = new SimpleScopeDefinition(
+      name,
+      description,
+      (taskName, descriptionOrAction, action) =>
+        // if this function is updated, update the dsl.task function too
+        this._addTask(
+          { scope: name, task: taskName },
+          descriptionOrAction,
+          action,
+          false
+        ),
+      (subtaskName, descriptionOrAction, action) =>
+        // if this function is updated, update the dsl.subtask function too
+        this._addTask(
+          { scope: name, task: subtaskName },
+          descriptionOrAction,
+          action,
+          true
+        )
+    );
+
+    this._scopes[name] = scope;
+
+    return scope;
+  }
+
   /**
    * Retrieves the task definitions.
    *
@@ -108,13 +165,41 @@ export class TasksDSL {
     return this._tasks;
   }
 
+  /**
+   * Retrieves the scoped task definitions.
+   *
+   * @returns The scoped tasks container.
+   */
+  public getScopesDefinitions(): ScopesMap {
+    return this._scopes;
+  }
+
+  public getTaskDefinition(
+    scope: string | undefined,
+    name: string
+  ): TaskDefinition | undefined {
+    if (scope === undefined) {
+      return this._tasks[name];
+    } else {
+      return this._scopes[scope]?.tasks?.[name];
+    }
+  }
+
   private _addTask<TaskArgumentsT extends TaskArguments>(
-    name: string,
+    taskIdentifier: TaskIdentifier,
     descriptionOrAction?: string | ActionType<TaskArgumentsT>,
     action?: ActionType<TaskArgumentsT>,
     isSubtask?: boolean
   ) {
-    const parentTaskDefinition = this._tasks[name];
+    const { scope, task } = parseTaskIdentifier(taskIdentifier);
+
+    if (scope === undefined && this._scopes[task] !== undefined) {
+      throw new HardhatError(ERRORS.TASK_DEFINITIONS.SCOPE_TASK_CLASH, {
+        taskName: task,
+      });
+    }
+
+    const parentTaskDefinition = this.getTaskDefinition(scope, task);
 
     let taskDefinition: TaskDefinition;
 
@@ -124,7 +209,7 @@ export class TasksDSL {
         isSubtask
       );
     } else {
-      taskDefinition = new SimpleTaskDefinition(name, isSubtask);
+      taskDefinition = new SimpleTaskDefinition(taskIdentifier, isSubtask);
     }
 
     if (descriptionOrAction instanceof Function) {
@@ -140,7 +225,17 @@ export class TasksDSL {
       taskDefinition.setAction(action);
     }
 
-    this._tasks[name] = taskDefinition;
+    if (scope === undefined) {
+      this._tasks[task] = taskDefinition;
+    } else {
+      const scopeDefinition = this._scopes[scope];
+      assertHardhatInvariant(
+        scopeDefinition !== undefined,
+        "It shouldn't be possible to create a task in a scope that doesn't exist"
+      );
+      scopeDefinition.tasks[task] = taskDefinition;
+    }
+
     return taskDefinition;
   }
 }