hardhat 3.5.1 → 3.7.0

package/src/internal/builtin-plugins/solidity/build-system/build-system.ts

@@ -29,6 +29,7 @@ import type {
   CompilerOutputError,
   DependencyGraph,
   SolidityBuildInfo,
+  ResolvedBuildOptions,
 } from "../../../../types/solidity.js";
 
 import os from "node:os";
@@ -277,13 +278,14 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
     rootFilePaths: string[],
     options?: BuildOptions,
   ): Promise<CompilationJobCreationError | Map<string, FileBuildResult>> {
-    const resolvedOptions: Required<BuildOptions> = {
+    const resolvedOptions: ResolvedBuildOptions = {
       buildProfile: DEFAULT_BUILD_PROFILE,
       concurrency: Math.max(os.cpus().length - 1, 1),
       force: false,
       isolated: false,
       quiet: false,
       scope: "contracts",
+      cleanupArtifacts: false,
       ...options,
     };
 
@@ -368,6 +370,8 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         ReadonlyMap<string, string[]>
       > = new Map();
 
+      let contractArtifactsAfterBuild: string[] | undefined;
+
       if (isSuccessfulBuild) {
         log("Emitting artifacts of successful build");
         await Promise.all(
@@ -397,6 +401,43 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         );
 
         await saveCache(this.#options.cachePath, this.#compileCache);
+
+        if (resolvedOptions.cleanupArtifacts) {
+          const paths = await this.cleanupArtifacts(rootFilePaths, {
+            scope: resolvedOptions.scope,
+          });
+
+          if (resolvedOptions.scope !== "tests") {
+            contractArtifactsAfterBuild = paths;
+          }
+        }
+
+        if (resolvedOptions.scope !== "tests") {
+          if (
+            await this.#hooks.hasHandlers(
+              "solidity",
+              "processArtifactsAfterSuccessfulBuild",
+            )
+          ) {
+            contractArtifactsAfterBuild ??=
+              await this.#getCurrentContractArtifactPaths();
+
+            if (!this.#options.solidityConfig.splitTestsCompilation) {
+              // In unified mode the contracts artifacts directory also contains
+              // test artifacts, so we must filter them out before invoking the
+              // processArtifactsAfterSuccessfulBuild hook.
+              contractArtifactsAfterBuild = await this.#filterOutTestArtifacts(
+                contractArtifactsAfterBuild,
+              );
+            }
+
+            await this.#hooks.runSequentialHandlers(
+              "solidity",
+              "processArtifactsAfterSuccessfulBuild",
+              [contractArtifactsAfterBuild, rootFilePaths, resolvedOptions],
+            );
+          }
+        }
       }
 
       spinner.stop();
@@ -415,10 +456,16 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
           "We emitted contract artifacts for all the jobs if the build was successful",
         );
 
-        const errors = await Promise.all(
-          (result.compilerOutput.errors ?? []).map((error) =>
-            this.remapCompilerError(result.compilationJob, error, true),
-          ),
+        const errors = await this.#hooks.runHandlerChain(
+          "solidity",
+          "getCompilationJobErrors",
+          [result.compilationJob, result.compilerOutput],
+          async (_context, nextCompilationJob, nextCompilerOutput) =>
+            await Promise.all(
+              (nextCompilerOutput.errors ?? []).map((error) =>
+                this.remapCompilerError(nextCompilationJob, error, true),
+              ),
+            ),
         );
 
         this.#printSolcErrorsAndWarnings(errors);
@@ -1064,7 +1111,7 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
   public async cleanupArtifacts(
     rootFilePaths: string[],
     options: { scope?: BuildScope } = {},
-  ): Promise<void> {
+  ): Promise<string[]> {
     const scope = options.scope ?? "contracts";
 
     this.#ensureSplitCompilationModeIfTestsScope(scope);
@@ -1191,6 +1238,77 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         async () => {},
       );
     }
+
+    return artifactPaths;
+  }
+
+  /**
+   * Returns every `.json` artifact under the contracts artifacts directory,
+   * excluding the project-wide top-level files (e.g. `artifacts.d.ts`) and
+   * the `build-info/` subtree.
+   *
+   * In unified mode, the returned list also contains test artifacts. Callers
+   * that need a contracts-only view should pass the result through
+   * `#filterOutTestArtifacts`.
+   */
+  async #getCurrentContractArtifactPaths(): Promise<string[]> {
+    const artifactsDirectory = await this.getArtifactsDirectory("contracts");
+    const buildInfosDir = path.join(artifactsDirectory, `build-info`);
+
+    const allArtifactFiles = await getAllFilesMatching(
+      artifactsDirectory,
+      (p) => {
+        // Ignore top level files (e.g. the project-wide artifacts.d.ts)
+        if (
+          p.indexOf(path.sep, artifactsDirectory.length + path.sep.length) ===
+          -1
+        ) {
+          return false;
+        }
+        return p.endsWith(".json");
+      },
+      (dir) => dir !== buildInfosDir,
+    );
+
+    return allArtifactFiles;
+  }
+
+  /**
+   * Returns `artifactPaths` with the test artifacts removed.
+   *
+   * This is only meaningful in unified mode, where contracts and tests share
+   * the same artifacts directory. The caller is responsible for ensuring that
+   * precondition.
+   *
+   * Each artifact's user source name is recovered from its path and classified
+   * via `getScope`. Results are cached per source name to avoid repeating the
+   * FS stat work for sibling artifacts. npm-style source names don't resolve
+   * to a real path inside the project, so `getScope` falls back to
+   * `"contracts"`, which is the intended outcome.
+   */
+  async #filterOutTestArtifacts(artifactPaths: string[]): Promise<string[]> {
+    const artifactsDirectory = await this.getArtifactsDirectory("contracts");
+    const scopeBySource = new Map<string, BuildScope>();
+    const contractArtifactPaths: string[] = [];
+
+    for (const artifactPath of artifactPaths) {
+      const userSourceName = toForwardSlash(
+        path.relative(artifactsDirectory, path.dirname(artifactPath)),
+      );
+
+      let scope = scopeBySource.get(userSourceName);
+      if (scope === undefined) {
+        const fsPath = path.resolve(this.#options.projectRoot, userSourceName);
+        scope = await this.getScope(fsPath);
+        scopeBySource.set(userSourceName, scope);
+      }
+
+      if (scope === "contracts") {
+        contractArtifactPaths.push(artifactPath);
+      }
+    }
+
+    return contractArtifactPaths;
   }
 
   public async compileBuildInfo(

package/src/internal/builtin-plugins/solidity/hook-handlers/hre.ts

@@ -114,7 +114,7 @@ class LazySolidityBuildSystem implements SolidityBuildSystem {
   public async cleanupArtifacts(
     rootFilePaths: string[],
     options: { scope?: BuildScope } = {},
-  ): Promise<void> {
+  ): Promise<string[]> {
     const buildSystem = await this.#getBuildSystem();
     return await buildSystem.cleanupArtifacts(rootFilePaths, options);
   }

package/src/internal/builtin-plugins/solidity/tasks/build.ts

@@ -186,6 +186,7 @@ async function runSolidityBuild({
       buildProfile,
       quiet,
       scope,
+      cleanupArtifacts: isFullBuild,
     },
   );
 
@@ -194,12 +195,6 @@ async function runSolidityBuild({
   // We use the result keys in case a hook added or removed root files
   const builtRootPaths = [...results.keys()];
 
-  if (isFullBuild) {
-    await solidity.cleanupArtifacts(builtRootPaths, {
-      scope,
-    });
-  }
-
   const preBuildRoots = new Set([...contractRootPaths, ...testRootPaths]);
   if (
     builtRootPaths.length === preBuildRoots.size &&

package/src/internal/builtin-plugins/solidity/type-extensions.ts

@@ -5,10 +5,13 @@ import type {
   FileBuildResult,
   SolidityBuildSystem,
 } from "../../../types/solidity/build-system.js";
+import type { CompilationJob } from "../../../types/solidity/compilation-job.js";
+import type { CompilerOutputError } from "../../../types/solidity/compiler-io.js";
 import type {
   Compiler,
   CompilerInput,
   CompilerOutput,
+  ResolvedBuildOptions,
 } from "../../../types/solidity.js";
 
 declare module "../../../types/config.js" {
@@ -359,6 +362,7 @@ declare module "../../../types/hooks.js" {
      * @param compilerConfig The compiler configuration to get a compiler for.
      * @param next A function to call the next handler for this hook.
      * @returns A Compiler instance.
+     * @deprecated This hook will soon be removed.
      */
     getCompiler: (
       context: HookContext,
@@ -377,6 +381,8 @@ declare module "../../../types/hooks.js" {
      * @param artifactPaths The file paths of artifacts that remain after cleanup.
      * @param next A function to call the next handler for this hook, or the
      * default implementation if no more handlers exist.
+     * @deprecated This hook will soon be removed. Use
+     * `processArtifactsAfterSuccessfulBuild` instead.
      */
     onCleanUpArtifacts: (
       context: HookContext,
@@ -402,6 +408,7 @@ declare module "../../../types/hooks.js" {
      * default implementation if no more handlers exist.
      *
      * @returns The modified file content.
+     * @deprecated This hook will soon be removed.
      */
     preprocessProjectFileBeforeBuilding(
       context: HookContext,
@@ -427,6 +434,7 @@ declare module "../../../types/hooks.js" {
      * default implementation if no more handlers exist.
      *
      * @returns The modified solc input.
+     * @deprecated This hook will soon be removed.
      */
     preprocessSolcInputBeforeBuilding(
       context: HookContext,
@@ -437,6 +445,9 @@ declare module "../../../types/hooks.js" {
       ) => Promise<CompilerInput>,
     ): Promise<CompilerInput>;
 
+    /**
+     * @deprecated This hook will soon be removed.
+     */
     readSourceFile: (
       context: HookContext,
       absolutePath: string,
@@ -482,6 +493,7 @@ declare module "../../../types/hooks.js" {
      * @param solcConfig The compiler configuration (version, type, etc.).
      * @param next A function to call the next handler for this hook, or the
      * default implementation if no more handlers exist.
+     * @deprecated This hook will soon be removed. Use `getCompilationJobErrors` instead.
      */
     invokeSolc(
       context: HookContext,
@@ -510,6 +522,7 @@ declare module "../../../types/hooks.js" {
      * @param next A function to get remappings from other sources (including default behavior).
      * @returns An array of remapping sources, each containing an array of remapping strings
      *   and the source path they came from.
+     * @deprecated This hook will soon be removed.
      */
     readNpmPackageRemappings: (
       context: HookContext,
@@ -523,5 +536,61 @@ declare module "../../../types/hooks.js" {
         nextPackagePath: string,
       ) => Promise<Array<{ remappings: string[]; source: string }>>,
     ) => Promise<Array<{ remappings: string[]; source: string }>>;
+
+    /**
+     * Sequential hook run when a solidity build finished successfully,
+     * and the artifacts are ready to be processed by a plugin.
+     *
+     * This hook is only run for the "contracts" scope, and never includes
+     * test artifacts in its parameters.
+     *
+     * @param context The hook context.
+     * @param artifactPaths All the contract artifact paths, including
+     * pre-existing ones.
+     * @param buildRootFilePaths The root file paths provided to the build,
+     * as absolute paths or `npm:<package-name>/<file-path>` identifiers. In
+     * unified mode this may include test files.
+     * @param buildOptions The resolved options used during the build, with
+     * the build system's defaults filled in for any field the caller didn't
+     * provide.
+     */
+    processArtifactsAfterSuccessfulBuild(
+      context: HookContext,
+      artifactPaths: readonly string[],
+      buildRootFilePaths: readonly string[],
+      buildOptions: Readonly<ResolvedBuildOptions>,
+    ): Promise<void>;
+
+    /**
+     * A hook run to get and potentially process the errors of the compiler
+     * output after it was run by the build system.
+     *
+     * This hook allows plugin authors to process the compiler output errors
+     * list before it's used by the build system to report them to the users,
+     * but it doesn't let plugins alter the logic that determines if a
+     * compilation job succeeded or failed.
+     *
+     * This hook must not mutate the parameters passed to `next`. Doing so can
+     * have unexpected behavior, and will eventually crash Hardhat.
+     *
+     * The recommended way to use this hook is to call `next` first, and then
+     * work with the returned list.
+     *
+     * @param context The hook context.
+     * @param compilationJob The compilation job run by the build system.
+     * @param compilerOutput The output returned by the compiler.
+     * @param next A function to call the next handler for this hook.
+     * @returns The processed compiler output error list.
+     */
+    getCompilationJobErrors(
+      context: HookContext,
+      compilationJob: Readonly<CompilationJob>,
+      compilerOutput: Readonly<CompilerOutput>,
+      next: (
+        nextContext: HookContext,
+        nextCompilationJob: Readonly<CompilationJob>,
+        nextCompilerOutput: Readonly<CompilerOutput>,
+      ) => Promise<CompilerOutputError[]>,
+    ): Promise<CompilerOutputError[]>;
   }
 }

package/src/internal/cli/help/utils.ts

@@ -7,6 +7,8 @@ import type { Task } from "../../../types/tasks.js";
 
 import { camelToKebabCase } from "@nomicfoundation/hardhat-utils/string";
 
+import { isArgumentRequired } from "../../core/tasks/utils.js";
+
 export const GLOBAL_NAME_PADDING = 6;
 
 interface ArgumentDescriptor {
@@ -84,11 +86,16 @@ export function parseOptions(task: Task): {
     });
   }
 
-  for (const { name, description, defaultValue } of task.positionalArguments) {
+  for (const {
+    name,
+    description,
+    defaultValue,
+    type,
+  } of task.positionalArguments) {
     positionalArguments.push({
       name,
       description: trimFullStop(description),
-      isRequired: defaultValue === undefined,
+      isRequired: isArgumentRequired(type, defaultValue),
       ...(defaultValue !== undefined && {
         defaultValue: Array.isArray(defaultValue)
           ? defaultValue.join(", ")

package/src/internal/cli/init/init.ts

@@ -14,11 +14,16 @@ import {
   copy,
   ensureDir,
   exists,
+  getAllFilesMatching,
   isDirectory,
   mkdir,
   readJsonFile,
+  remove,
+  symlink,
   writeJsonFile,
+  writeUtf8File,
 } from "@nomicfoundation/hardhat-utils/fs";
+import { findClosestPackageRoot } from "@nomicfoundation/hardhat-utils/package";
 import { resolveFromRoot } from "@nomicfoundation/hardhat-utils/path";
 import * as semver from "semver";
 
@@ -591,6 +596,10 @@ export async function copyProjectFiles(
     await copy(absoluteTemplatePath, absoluteWorkspacePath);
   }
 
+  await installSkills(workspace, template, force);
+  await createClaudeMd(workspace, force);
+  await createDotClaude(workspace);
+
   console.log(`✨ ${styleText("cyan", `Template files copied`)} ✨`);
 }
 
@@ -660,6 +669,133 @@ export async function copyProjectFilesNonInteractive(
       absoluteWorkspacePath,
     );
   }
+
+  await installSkills(workspace, template);
+  await createClaudeMd(workspace);
+  await createDotClaude(workspace);
+}
+
+/**
+ * Skills published from `packages/hardhat/skills/` and the npm package whose presence
+ * in a template's dependencies opts that template into installing the skill.
+ * Each skill is tied to exactly one package so they can be versioned and
+ * upgraded independently.
+ */
+const SKILL_PACKAGES: ReadonlyArray<{
+  packageName: string;
+  skillName: string;
+}> = [
+  { packageName: "hardhat", skillName: "hardhat" },
+  {
+    packageName: "@nomicfoundation/hardhat-toolbox-viem",
+    skillName: "hardhat-toolbox-viem",
+  },
+  {
+    packageName: "@nomicfoundation/hardhat-toolbox-mocha-ethers",
+    skillName: "hardhat-toolbox-mocha-ethers",
+  },
+];
+
+/**
+ * For agent-aware templates (those that ship an `AGENTS.md`), copies any
+ * skills from `packages/hardhat/skills/` whose corresponding package is a template
+ * dependency into `<workspace>/.agents/skills/<skill-name>/`.
+ */
+async function installSkills(
+  workspace: string,
+  template: Template,
+  force?: boolean,
+): Promise<void> {
+  if (!template.files.includes("AGENTS.md")) {
+    return;
+  }
+
+  const deps = {
+    ...template.packageJson.dependencies,
+    ...template.packageJson.devDependencies,
+  };
+  const relevantSkills = SKILL_PACKAGES.filter(
+    ({ packageName }) => deps[packageName] !== undefined,
+  );
+  if (relevantSkills.length === 0) {
+    return;
+  }
+
+  const hardhatPackageRoot = await findClosestPackageRoot(import.meta.url);
+  const skillsRoot = path.join(hardhatPackageRoot, "skills");
+
+  for (const { skillName } of relevantSkills) {
+    const skillSrcDir = path.join(skillsRoot, skillName);
+    const skillDestDir = path.join(workspace, ".agents", "skills", skillName);
+    const skillFiles = await getAllFilesMatching(skillSrcDir);
+    for (const file of skillFiles) {
+      const dest = path.join(skillDestDir, path.relative(skillSrcDir, file));
+      if (force !== true && (await exists(dest))) {
+        continue;
+      }
+      await ensureDir(path.dirname(dest));
+      await copy(file, dest);
+    }
+  }
+}
+
+/**
+ * Creates a `CLAUDE.md` file if an `AGENTS.md` file exists. Uses a symlink
+ * except on Windows, where a file is created that references `AGENTS.md`.
+ * Overwrites an existing `CLAUDE.md` only if `force` is true.
+ */
+async function createClaudeMd(
+  workspace: string,
+  force?: boolean,
+): Promise<void> {
+  const agentsMdPath = path.join(workspace, "AGENTS.md");
+  if (!(await exists(agentsMdPath))) {
+    return;
+  }
+
+  const claudeMdPath = path.join(workspace, "CLAUDE.md");
+  if (await exists(claudeMdPath, { followSymlinks: false })) {
+    if (force !== true) {
+      return;
+    }
+    await remove(claudeMdPath);
+  }
+
+  if (process.platform === "win32") {
+    await writeUtf8File(claudeMdPath, "@AGENTS.md\n");
+  } else {
+    await symlink("AGENTS.md", claudeMdPath);
+  }
+}
+
+/**
+ * Creates `.claude` if `.agents` exists. Uses a symlink except on Windows,
+ * where the whole directory is copied. Does nothing if `.claude` already
+ * exists; the `force` flag is intentionally not used here because
+ * overwriting depends on whether the existing `.claude` is a file, directory,
+ * or symlink, and on the OS, which is more complexity than is worthwhile.
+ */
+async function createDotClaude(workspace: string): Promise<void> {
+  const agentsDirPath = path.join(workspace, ".agents");
+  if (!(await exists(agentsDirPath))) {
+    return;
+  }
+
+  const claudeDirPath = path.join(workspace, ".claude");
+  if (await exists(claudeDirPath, { followSymlinks: false })) {
+    return;
+  }
+
+  if (process.platform === "win32") {
+    const agentsFiles = await getAllFilesMatching(agentsDirPath);
+    for (const file of agentsFiles) {
+      const dest = path.join(claudeDirPath, path.relative(agentsDirPath, file));
+      await ensureDir(path.dirname(dest));
+      await copy(file, dest);
+    }
+  } else {
+    await symlink(".agents", claudeDirPath);
+  }
 }
 
 /**

package/src/internal/cli/init/prompt.ts

@@ -22,7 +22,7 @@ export async function promptForHardhatVersion(): Promise<
       choices: [
         {
           name: "hardhat-3",
-          message: "Hardhat 3 Beta (recommended for new projects)",
+          message: "Hardhat 3 (recommended for new projects)",
           value: "hardhat-3",
         },
         {

package/src/internal/cli/main.ts

@@ -40,6 +40,7 @@ import { parseArgumentValue } from "../core/arguments.js";
 import { buildGlobalOptionDefinitions } from "../core/global-options.js";
 import { resolveProjectRoot } from "../core/hre.js";
 import { resolvePluginList } from "../core/plugins/resolve-plugin-list.js";
+import { isArgumentRequired } from "../core/tasks/utils.js";
 import { setGlobalHardhatRuntimeEnvironment } from "../global-hre-instance.js";
 import { createHardhatRuntimeEnvironment } from "../hre-initialization.js";
 
@@ -767,8 +768,9 @@ function validateRequiredArguments(
   taskArguments: TaskArguments,
 ) {
   const missingRequiredArgument = argumentDefinitions.find(
-    ({ defaultValue, name }) =>
-      defaultValue === undefined && taskArguments[name] === undefined,
+    ({ defaultValue, name, type }) =>
+      isArgumentRequired(type, defaultValue) &&
+      taskArguments[name] === undefined,
   );
 
   if (missingRequiredArgument === undefined) {

package/src/internal/core/tasks/resolved-task.ts

@@ -22,7 +22,7 @@ import { ensureError } from "@nomicfoundation/hardhat-utils/error";
 
 import { detectPluginNpmDependencyProblems } from "../plugins/detect-plugin-npm-dependency-problems.js";
 
-import { formatTaskId } from "./utils.js";
+import { formatTaskId, isArgumentRequired } from "./utils.js";
 import { validateTaskArgumentValue } from "./validations.js";
 
 export class ResolvedTask implements Task {
@@ -203,7 +203,10 @@ export class ResolvedTask implements Task {
     argument: PositionalArgumentDefinition,
     value: ArgumentValue | ArgumentValue[],
   ) {
-    if (argument.defaultValue === undefined && value === undefined) {
+    if (
+      isArgumentRequired(argument.type, argument.defaultValue) &&
+      value === undefined
+    ) {
       throw new HardhatError(
         HardhatError.ERRORS.CORE.TASK_DEFINITIONS.MISSING_VALUE_FOR_TASK_ARGUMENT,
         {

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

@@ -1,3 +1,5 @@
+import type { ArgumentType, ArgumentValue } from "../../../types/arguments.js";
+
 export function formatTaskId(taskId: string | string[]): string {
   if (typeof taskId === "string") {
     return taskId;
@@ -9,3 +11,14 @@ export function formatTaskId(taskId: string | string[]): string {
 export function getActorFragment(pluginId: string | undefined): string {
   return pluginId !== undefined ? `Plugin ${pluginId} is` : "You are";
 }
+
+export function isOptionalArgumentType(type: ArgumentType): boolean {
+  return type.endsWith("_WITHOUT_DEFAULT");
+}
+
+export function isArgumentRequired(
+  type: ArgumentType,
+  defaultValue: ArgumentValue | ArgumentValue[] | undefined,
+): boolean {
+  return defaultValue === undefined && !isOptionalArgumentType(type);
+}

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

@@ -19,7 +19,7 @@ import {
   validateArgumentValue,
 } from "../arguments.js";
 
-import { formatTaskId } from "./utils.js";
+import { isArgumentRequired, formatTaskId } from "./utils.js";
 
 export function validateId(id: string | string[]): void {
   if (id.length === 0) {
@@ -133,8 +133,8 @@ export function validatePositionalArgument(
 
   if (
     lastArg !== undefined &&
-    lastArg.defaultValue !== undefined &&
-    defaultValue === undefined
+    !isArgumentRequired(lastArg.type, lastArg.defaultValue) &&
+    isArgumentRequired(type, defaultValue)
   ) {
     throw new HardhatError(
       HardhatError.ERRORS.CORE.TASK_DEFINITIONS.REQUIRED_ARG_AFTER_OPTIONAL,

package/src/types/solidity/build-system.ts

@@ -52,18 +52,36 @@ export interface BuildOptions {
    * and produce separate compilation passes.
    */
   scope?: BuildScope;
+
+  /**
+   * If `true`, a clean up process is run after a successful build.
+   *
+   * The clean up deletes all the orphan artifacts that aren't reachable from
+   * the provided `rootFilePaths`.
+   *
+   * When building with `"contracts"` scope, it also updates the top-level
+   * `artifacts.d.ts`.
+   *
+   * Only use this option when the provided `rootFilePaths` represent the
+   * entire set of contracts for the scope you are using (i.e. not during
+   * partial builds). Otherwise, you'll delete artifacts generated in previous
+   * builds, despite their sources still being available.
+   */
+  cleanupArtifacts?: boolean;
 }
 
+/**
+ * The resolved BuildOptions used to run a build.
+ */
+export type ResolvedBuildOptions = Required<BuildOptions>;
+
 /**
  * The options of the `getCompilationJobs` method.
  *
  * Note that this option object includes a `quiet` property, as this process
  * may require downloading compilers, and potentially printing some output.
  */
-export type GetCompilationJobsOptions = Omit<
-  BuildOptions,
-  "removeUnusedArtifacts"
->;
+export type GetCompilationJobsOptions = Omit<BuildOptions, "cleanupArtifacts">;
 
 /**
  * The options of the `runCompilationJob` method.
@@ -434,11 +452,12 @@ export interface SolidityBuildSystem {
    *      used.
    *
    * @param rootFilePaths All the root files of the project.
+   * @returns The list of artifact paths that remain after the cleanup.
    */
   cleanupArtifacts(
     rootFilePaths: string[],
     options?: { scope?: BuildScope },
-  ): Promise<void>;
+  ): Promise<string[]>;
 
   /**
    * Compiles a build info, returning the output of the compilation, verbatim,