hardhat 2.17.3 → 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

@@ -23,7 +23,10 @@ import { ERRORS, getErrorCode } from "../core/errors-list";
 import { isHardhatInstalledLocallyOrLinked } from "../core/execution-mode";
 import { getEnvHardhatArguments } from "../core/params/env-variables";
 import { HARDHAT_PARAM_DEFINITIONS } from "../core/params/hardhat-params";
-import { isCwdInsideProject } from "../core/project-structure";
+import {
+  getUserConfigPath,
+  isCwdInsideProject,
+} from "../core/project-structure";
 import { Environment } from "../core/runtime-environment";
 import { loadTsNode, willRunWithTypescript } from "../core/typescript-support";
 import { Reporter } from "../sentry/reporter";
@@ -124,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);
@@ -151,25 +151,45 @@ async function main() {
       return;
     }
 
-    if (hardhatArguments.config === undefined && !isCwdInsideProject()) {
+    // ATTENTION! DEPRECATED CODE!
+    // The command `npx hardhat`, when used to create a new Hardhat project, will be removed with Hardhat V3.
+    // It will become `npx hardhat init`.
+    // The code marked with the tag #INIT-DEP can be deleted after HarhatV3 is out.
+
+    // Create a new Hardhat project
+    if (scopeOrTaskName === "init") {
+      return await createNewProject();
+    }
+    // #INIT-DEP - START OF DEPRECATED CODE
+    else {
       if (
-        process.stdout.isTTY === true ||
-        process.env.HARDHAT_CREATE_JAVASCRIPT_PROJECT_WITH_DEFAULTS !==
-          undefined ||
-        process.env.HARDHAT_CREATE_TYPESCRIPT_PROJECT_WITH_DEFAULTS !==
-          undefined
+        scopeOrTaskName === undefined &&
+        hardhatArguments.config === undefined &&
+        !isCwdInsideProject()
       ) {
-        await createProject();
+        await createNewProject();
+
+        // Warning for Hardhat V3 deprecation
+        console.warn(
+          chalk.yellow.bold("\n\nDEPRECATION WARNING\n\n"),
+          chalk.yellow(
+            `Initializing a project with ${chalk.white.italic(
+              "npx hardhat"
+            )} is deprecated and will be removed in the future.\n`
+          ),
+          chalk.yellow(
+            `Please use ${chalk.white.italic("npx hardhat init")} instead.\n\n`
+          )
+        );
+
         return;
       }
+    }
+    // #INIT-DEP - END OF DEPRECATED CODE
 
-      // Many terminal emulators in windows fail to run the createProject()
-      // workflow, and don't present themselves as TTYs. If we are in this
-      // situation we throw a special error instructing the user to use WSL or
-      // powershell to initialize the project.
-      if (process.platform === "win32") {
-        throw new HardhatError(ERRORS.GENERAL.NOT_INSIDE_PROJECT_ON_WINDOWS);
-      }
+    // Tasks are only allowed inside a Hardhat project (except the init task)
+    if (hardhatArguments.config === undefined && !isCwdInsideProject()) {
+      throw new HardhatError(ERRORS.GENERAL.NOT_INSIDE_PROJECT);
     }
 
     if (
@@ -190,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;
@@ -229,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,
         });
@@ -266,6 +306,7 @@ async function main() {
       resolvedConfig,
       hardhatArguments,
       taskDefinitions,
+      scopesDefinitions,
       envExtenders,
       ctx.experimentalHardhatNetworkMessageTraceHooks,
       userConfig,
@@ -277,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();
 
@@ -377,6 +418,33 @@ async function main() {
   }
 }
 
+async function createNewProject() {
+  if (isCwdInsideProject()) {
+    throw new HardhatError(ERRORS.GENERAL.HARDHAT_PROJECT_ALREADY_CREATED, {
+      hardhatProjectRootPath: getUserConfigPath(),
+    });
+  }
+
+  if (
+    process.stdout.isTTY === true ||
+    process.env.HARDHAT_CREATE_JAVASCRIPT_PROJECT_WITH_DEFAULTS !== undefined ||
+    process.env.HARDHAT_CREATE_TYPESCRIPT_PROJECT_WITH_DEFAULTS !== undefined
+  ) {
+    await createProject();
+    return;
+  }
+
+  // Many terminal emulators in windows fail to run the createProject()
+  // workflow, and don't present themselves as TTYs. If we are in this
+  // situation we throw a special error instructing the user to use WSL or
+  // powershell to initialize the project.
+  if (process.platform === "win32") {
+    throw new HardhatError(ERRORS.GENERAL.NOT_INSIDE_PROJECT_ON_WINDOWS);
+  }
+
+  throw new HardhatError(ERRORS.GENERAL.NOT_IN_INTERACTIVE_SHELL);
+}
+
 main()
   .then(() => process.exit(process.exitCode))
   .catch((error) => {

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

@@ -288,6 +288,24 @@ To initialize the provider, make sure you first call \`.init()\` or any method t
 Please double check the file path.`,
       shouldBeReported: false,
     },
+    HARDHAT_PROJECT_ALREADY_CREATED: {
+      number: 23,
+      message:
+        "You are trying to initialize a project inside an existing Hardhat project. The path to the project's configuration file is:  %hardhatProjectRootPath%.",
+      title: "Hardhat project already created",
+      description: `Cannot create a new Hardhat project, the current folder is already associated with a project.`,
+      shouldBeReported: false,
+    },
+    NOT_IN_INTERACTIVE_SHELL: {
+      number: 24,
+      message:
+        "You are trying to initialize a project but you are not in an interactive shell.",
+      title: "Not inside an interactive shell",
+      description: `You are trying to initialize a project but you are not in an interactive shell.
+
+Please re-run the command inside an interactive shell.`,
+      shouldBeReported: false,
+    },
   },
   NETWORK: {
     CONFIG_NOT_FOUND: {
@@ -595,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.",
@@ -636,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.
 
@@ -738,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);