hardhat 3.1.10 → 3.1.11

package/src/internal/cli/telemetry/sentry/vendor/integrations/contextlines.ts

@@ -1,15 +1,15 @@
 /* eslint-disable -- This file is vendored from https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/contextlines.ts */
 
-import { createReadStream } from 'node:fs';
-import { createInterface } from 'node:readline';
-import type { Event, IntegrationFn, StackFrame } from '@sentry/core';
-import { LRUMap, defineIntegration, logger, snipLine } from '@sentry/core';
-import { DEBUG_BUILD } from '../debug-build.js';
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import type { Event, IntegrationFn, StackFrame } from "@sentry/core";
+import { LRUMap, defineIntegration, logger, snipLine } from "@sentry/core";
+import { DEBUG_BUILD } from "../debug-build.js";
 
 const LRU_FILE_CONTENTS_CACHE = new LRUMap<string, Record<number, string>>(10);
 const LRU_FILE_CONTENTS_FS_READ_FAILED = new LRUMap<string, 1>(20);
 const DEFAULT_LINES_OF_CONTEXT = 7;
-const INTEGRATION_NAME = 'ContextLines';
+const INTEGRATION_NAME = "ContextLines";
 // Determines the upper bound of lineno/colno that we will attempt to read. Large colno values are likely to be
 // minified code while large lineno values are likely to be bundled code.
 // Exported for testing purposes.
@@ -36,7 +36,11 @@ export function resetFileContentCache(): void {
 /**
  * Get or init map value
  */
-function emplace<T extends LRUMap<K, V>, K extends string, V>(map: T, key: K, contents: V): V {
+function emplace<T extends LRUMap<K, V>, K extends string, V>(
+  map: T,
+  key: K,
+  contents: V,
+): V {
   const value = map.get(key);
 
   if (value === undefined) {
@@ -49,18 +53,18 @@ function emplace<T extends LRUMap<K, V>, K extends string, V>(map: T, key: K, co
 
 /**
  * Determines if context lines should be skipped for a file.
- * - .min.(mjs|cjs|js) files are and not useful since they dont point to the original source
+ * - .min.(mjs|cjs|js) files are and not useful since they don't point to the original source
  * - node: prefixed modules are part of the runtime and cannot be resolved to a file
  * - data: skip json, wasm and inline js https://nodejs.org/api/esm.html#data-imports
  */
 function shouldSkipContextLinesForFile(path: string): boolean {
   // Test the most common prefix and extension first. These are the ones we
   // are most likely to see in user applications and are the ones we can break out of first.
-  if (path.startsWith('node:')) return true;
-  if (path.endsWith('.min.js')) return true;
-  if (path.endsWith('.min.cjs')) return true;
-  if (path.endsWith('.min.mjs')) return true;
-  if (path.startsWith('data:')) return true;
+  if (path.startsWith("node:")) return true;
+  if (path.endsWith(".min.js")) return true;
+  if (path.endsWith(".min.cjs")) return true;
+  if (path.endsWith(".min.mjs")) return true;
+  if (path.startsWith("data:")) return true;
   return false;
 }
 
@@ -68,14 +72,19 @@ function shouldSkipContextLinesForFile(path: string): boolean {
  * Determines if we should skip contextlines based off the max lineno and colno values.
  */
 function shouldSkipContextLinesForFrame(frame: StackFrame): boolean {
-  if (frame.lineno !== undefined && frame.lineno > MAX_CONTEXTLINES_LINENO) return true;
-  if (frame.colno !== undefined && frame.colno > MAX_CONTEXTLINES_COLNO) return true;
+  if (frame.lineno !== undefined && frame.lineno > MAX_CONTEXTLINES_LINENO)
+    return true;
+  if (frame.colno !== undefined && frame.colno > MAX_CONTEXTLINES_COLNO)
+    return true;
   return false;
 }
 /**
  * Checks if we have all the contents that we need in the cache.
  */
-function rangeExistsInContentCache(file: string, range: ReadlineRange): boolean {
+function rangeExistsInContentCache(
+  file: string,
+  range: ReadlineRange,
+): boolean {
   const contents = LRU_FILE_CONTENTS_CACHE.get(file);
   if (contents === undefined) return false;
 
@@ -92,7 +101,10 @@ function rangeExistsInContentCache(file: string, range: ReadlineRange): boolean
  * Creates contiguous ranges of lines to read from a file. In the case where context lines overlap,
  * the ranges are merged to create a single range.
  */
-function makeLineReaderRanges(lines: number[], linecontext: number): ReadlineRange[] {
+function makeLineReaderRanges(
+  lines: number[],
+  linecontext: number,
+): ReadlineRange[] {
   if (!lines.length) {
     return [];
   }
@@ -100,7 +112,7 @@ function makeLineReaderRanges(lines: number[], linecontext: number): ReadlineRan
   let i = 0;
   const line = lines[0];
 
-  if (typeof line !== 'number') {
+  if (typeof line !== "number") {
     return [];
   }
 
@@ -115,7 +127,7 @@ function makeLineReaderRanges(lines: number[], linecontext: number): ReadlineRan
 
     // If the next line falls into the current range, extend the current range to lineno + linecontext.
     const next = lines[i + 1];
-    if (typeof next !== 'number') {
+    if (typeof next !== "number") {
       break;
     }
     if (next <= current[1]) {
@@ -134,13 +146,17 @@ function makeLineReaderRanges(lines: number[], linecontext: number): ReadlineRan
 /**
  * Extracts lines from a file and stores them in a cache.
  */
-function getContextLinesFromFile(path: string, ranges: ReadlineRange[], output: Record<number, string>): Promise<void> {
+function getContextLinesFromFile(
+  path: string,
+  ranges: ReadlineRange[],
+  output: Record<number, string>,
+): Promise<void> {
   return new Promise((resolve, _reject) => {
     // It is important *not* to have any async code between createInterface and the 'line' event listener
     // as it will cause the 'line' event to
     // be emitted before the listener is attached.
     const stream = createReadStream(path);
-    const lineReaded = createInterface({
+    const lineRead = createInterface({
       input: stream,
     });
 
@@ -170,18 +186,18 @@ function getContextLinesFromFile(path: string, ranges: ReadlineRange[], output:
       // Mark file path as failed to read and prevent multiple read attempts.
       LRU_FILE_CONTENTS_FS_READ_FAILED.set(path, 1);
       DEBUG_BUILD && logger.error(`Failed to read file: ${path}. Error: ${e}`);
-      lineReaded.close();
-      lineReaded.removeAllListeners();
+      lineRead.close();
+      lineRead.removeAllListeners();
       destroyStreamAndResolve();
     }
 
     // We need to handle the error event to prevent the process from crashing in < Node 16
     // https://github.com/nodejs/node/pull/31603
-    stream.on('error', onStreamError);
-    lineReaded.on('error', onStreamError);
-    lineReaded.on('close', destroyStreamAndResolve);
+    stream.on("error", onStreamError);
+    lineRead.on("error", onStreamError);
+    lineRead.on("close", destroyStreamAndResolve);
 
-    lineReaded.on('line', line => {
+    lineRead.on("line", (line) => {
       lineNumber++;
       if (lineNumber < rangeStart) return;
 
@@ -191,16 +207,16 @@ function getContextLinesFromFile(path: string, ranges: ReadlineRange[], output:
       if (lineNumber >= rangeEnd) {
         if (currentRangeIndex === ranges.length - 1) {
           // We need to close the file stream and remove listeners, else the reader will continue to run our listener;
-          lineReaded.close();
-          lineReaded.removeAllListeners();
+          lineRead.close();
+          lineRead.removeAllListeners();
           return;
         }
         currentRangeIndex++;
         const range = ranges[currentRangeIndex];
         if (range === undefined) {
           // This should never happen as it means we have a bug in the context.
-          lineReaded.close();
-          lineReaded.removeAllListeners();
+          lineRead.close();
+          lineRead.removeAllListeners();
           return;
         }
         rangeStart = range[0];
@@ -217,7 +233,10 @@ function getContextLinesFromFile(path: string, ranges: ReadlineRange[], output:
  * failing reads from happening.
  */
 
-async function addSourceContext(event: Event, contextLines: number): Promise<Event> {
+async function addSourceContext(
+  event: Event,
+  contextLines: number,
+): Promise<Event> {
   // keep a lookup map of which files we've already enqueued to read,
   // so we don't enqueue the same file multiple times which would cause multiple i/o reads
   const filesToLines: Record<string, number[]> = {};
@@ -236,8 +255,8 @@ async function addSourceContext(event: Event, contextLines: number): Promise<Eve
 
         if (
           !frame ||
-          typeof filename !== 'string' ||
-          typeof frame.lineno !== 'number' ||
+          typeof filename !== "string" ||
+          typeof frame.lineno !== "number" ||
           shouldSkipContextLinesForFile(filename) ||
           shouldSkipContextLinesForFrame(frame)
         ) {
@@ -258,7 +277,7 @@ async function addSourceContext(event: Event, contextLines: number): Promise<Eve
 
   const readlinePromises: Promise<void>[] = [];
   for (const file of files) {
-    // If we failed to read this before, dont try reading it again.
+    // If we failed to read this before, don't try reading it again.
     if (LRU_FILE_CONTENTS_FS_READ_FAILED.get(file)) {
       continue;
     }
@@ -272,7 +291,7 @@ async function addSourceContext(event: Event, contextLines: number): Promise<Eve
     filesToLineRanges.sort((a, b) => a - b);
     // Check if the contents are already in the cache and if we can avoid reading the file again.
     const ranges = makeLineReaderRanges(filesToLineRanges, contextLines);
-    if (ranges.every(r => rangeExistsInContentCache(file, r))) {
+    if (ranges.every((r) => rangeExistsInContentCache(file, r))) {
       continue;
     }
 
@@ -282,15 +301,25 @@ async function addSourceContext(event: Event, contextLines: number): Promise<Eve
 
   // The promise rejections are caught in order to prevent them from short circuiting Promise.all
   await Promise.all(readlinePromises).catch(() => {
-    DEBUG_BUILD && logger.log('Failed to read one or more source files and resolve context lines');
+    DEBUG_BUILD &&
+      logger.log(
+        "Failed to read one or more source files and resolve context lines",
+      );
   });
 
   // Perform the same loop as above, but this time we can assume all files are in the cache
   // and attempt to add source context to frames.
   if (contextLines > 0 && event.exception?.values) {
     for (const exception of event.exception.values) {
-      if (exception.stacktrace?.frames && exception.stacktrace.frames.length > 0) {
-        addSourceContextToFrames(exception.stacktrace.frames, contextLines, LRU_FILE_CONTENTS_CACHE);
+      if (
+        exception.stacktrace?.frames &&
+        exception.stacktrace.frames.length > 0
+      ) {
+        addSourceContextToFrames(
+          exception.stacktrace.frames,
+          contextLines,
+          LRU_FILE_CONTENTS_CACHE,
+        );
       }
     }
   }
@@ -307,7 +336,11 @@ function addSourceContextToFrames(
 ): void {
   for (const frame of frames) {
     // Only add context if we have a filename and it hasn't already been added
-    if (frame.filename && frame.context_line === undefined && typeof frame.lineno === 'number') {
+    if (
+      frame.filename &&
+      frame.context_line === undefined &&
+      typeof frame.lineno === "number"
+    ) {
       const contents = cache.get(frame.filename);
       if (contents === undefined) {
         continue;
@@ -340,29 +373,34 @@ export function addContextToFrame(
   // When there is no line number in the frame, attaching context is nonsensical and will even break grouping.
   // We already check for lineno before calling this, but since StackFrame lineno ism optional, we check it again.
   if (frame.lineno === undefined || contents === undefined) {
-    DEBUG_BUILD && logger.error('Cannot resolve context for frame with no lineno or file contents');
+    DEBUG_BUILD &&
+      logger.error(
+        "Cannot resolve context for frame with no lineno or file contents",
+      );
     return;
   }
 
   frame.pre_context = [];
   for (let i = makeRangeStart(lineno, contextLines); i < lineno; i++) {
-    // We always expect the start context as line numbers cannot be negative. If we dont find a line, then
+    // We always expect the start context as line numbers cannot be negative. If we don't find a line, then
     // something went wrong somewhere. Clear the context and return without adding any linecontext.
     const line = contents[i];
     if (line === undefined) {
       clearLineContext(frame);
-      DEBUG_BUILD && logger.error(`Could not find line ${i} in file ${frame.filename}`);
+      DEBUG_BUILD &&
+        logger.error(`Could not find line ${i} in file ${frame.filename}`);
       return;
     }
 
     frame.pre_context.push(line);
   }
 
-  // We should always have the context line. If we dont, something went wrong, so we clear the context and return
+  // We should always have the context line. If we don't, something went wrong, so we clear the context and return
   // without adding any linecontext.
   if (contents[lineno] === undefined) {
     clearLineContext(frame);
-    DEBUG_BUILD && logger.error(`Could not find line ${lineno} in file ${frame.filename}`);
+    DEBUG_BUILD &&
+      logger.error(`Could not find line ${lineno} in file ${frame.filename}`);
     return;
   }
 
@@ -371,7 +409,7 @@ export function addContextToFrame(
   const end = makeRangeEnd(lineno, contextLines);
   frame.post_context = [];
   for (let i = lineno + 1; i <= end; i++) {
-    // Since we dont track when the file ends, we cant clear the context if we dont find a line as it could
+    // Since we don't track when the file ends, we cant clear the context if we don't find a line as it could
     // just be that we reached the end of the file.
     const line = contents[i];
     if (line === undefined) {
@@ -393,13 +431,21 @@ function makeRangeEnd(line: number, linecontext: number): number {
   return line + linecontext;
 }
 // Determine start and end indices for context range (inclusive);
-function makeContextRange(line: number, linecontext: number): [start: number, end: number] {
+function makeContextRange(
+  line: number,
+  linecontext: number,
+): [start: number, end: number] {
   return [makeRangeStart(line, linecontext), makeRangeEnd(line, linecontext)];
 }
 
 /** Exported only for tests, as a type-safe variant. */
-export const _contextLinesIntegration: any = ((options: ContextLinesOptions = {}) => {
-  const contextLines = options.frameContextLines !== undefined ? options.frameContextLines : DEFAULT_LINES_OF_CONTEXT;
+export const _contextLinesIntegration: any = ((
+  options: ContextLinesOptions = {},
+) => {
+  const contextLines =
+    options.frameContextLines !== undefined
+      ? options.frameContextLines
+      : DEFAULT_LINES_OF_CONTEXT;
 
   return {
     name: INTEGRATION_NAME,
@@ -412,4 +458,6 @@ export const _contextLinesIntegration: any = ((options: ContextLinesOptions = {}
 /**
  * Capture the lines before and after the frame's context.
  */
-export const contextLinesIntegration: any = defineIntegration(_contextLinesIntegration);
+export const contextLinesIntegration: any = defineIntegration(
+  _contextLinesIntegration,
+);

package/src/internal/core/user-interruptions.ts

@@ -121,7 +121,7 @@ async function defaultRequestSecretInput(
 
       assertHardhatInvariant(
         rlAsAny.output !== undefined,
-        "Espected readline output to be defined",
+        "Expected readline output to be defined",
       );
 
       // We show the initial message as is

package/src/types/artifacts.ts

@@ -1,4 +1,5 @@
 import type { SolidityBuildInfo } from "./solidity/solidity-artifacts.js";
+import type { NonNeverKeys } from "./utils.js";
 
 /**
  * A map of bare contract names and fully qualified contract names to their
@@ -17,6 +18,37 @@ export type GetArtifactByName<ContractNameT extends string> =
     ? ArtifactMap[ContractNameT]
     : Artifact;
 
+/**
+ * A type that represents the contract names (bare and fully qualified) of all
+ * the artifacts that have been built in a project. This enables the
+ * autocomplete of the TS Language Server to list the actual contracts, without
+ * leading to a compilation error for general strings, so it doesn't fail
+ * before `hardhat build` is run.
+ *
+ * This is meant to be used in functions like this:
+ * @example
+ * ```
+ * function doSomething<ContractNameT extends ArtifactContractNames>(
+ *   contractName: ContractNameT,
+ *   ...
+ * ): DoSomethingReturnType<ContractNameT> {
+ * }
+ */
+export type ArtifactContractNames = keyof ArtifactMap extends never
+  ? string
+  : NonNeverKeys<ArtifactMap>;
+
+/**
+ * A type that represents a string that should match an artifact contract name,
+ * but it doesn't fail if the string is not a contract name. It's mostly used
+ * to offer autocompletion.
+ *
+ * @see {@link ArtifactContractNames}
+ */
+export type StringWithArtifactContractNamesAutocompletion =
+  | ArtifactContractNames
+  | (string & {});
+
 /**
  * The ArtifactManager is responsible for reading and writing artifacts from
  * the Hardhat build system.
@@ -28,13 +60,18 @@ export interface ArtifactManager {
    * @param contractNameOrFullyQualifiedName The name of the contract.
    *   It can be a contract bare contract name (e.g. "Token") if it's
    *   unique in your project, or a fully qualified contract name
-   *   (e.g. "contract/token.sol:Token") otherwise.
+   *   (e.g. "contract/token.sol:Token") otherwise. TypeScript's language server
+   *   autocompletes the names of the contracts that have already been built. If
+   *   your contract name isn't in the list, you can still use it, and/or run
+   *   `hardhat build` to get it in the list.
    *
    * @throws Throws an error if a non-unique contract name is used,
    *   indicating which fully qualified names can be used instead.
    * @throws Throws an error if the artifact doesn't exist.
    */
-  readArtifact<ContractNameT extends string>(
+  readArtifact<
+    ContractNameT extends StringWithArtifactContractNamesAutocompletion,
+  >(
     contractNameOrFullyQualifiedName: ContractNameT,
   ): Promise<GetArtifactByName<ContractNameT>>;
 
@@ -239,7 +276,7 @@ export interface LinkReferences {
  * is the id of the AST node that represents the variable.
  */
 export interface ImmutableReferences {
-  [immuatableId: string]: Array<{ start: number; length: number }>;
+  [immutableId: string]: Array<{ start: number; length: number }>;
 }
 
 /**

package/src/types/hre.ts

@@ -15,7 +15,7 @@ export interface HardhatRuntimeEnvironment {
     readonly hardhat: string;
     readonly edr: string;
   };
-  // These fields are defined using module agumentation despite being part of
+  // These fields are defined using module augmentation despite being part of
   // Hardhat's core:
   // readonly hooks: HookManager;
   // readonly tasks: TaskManager;

package/src/types/network.ts

@@ -10,7 +10,7 @@ import type { EthereumProvider } from "./providers.js";
 export type ChainType = GenericChainType | "l1" | "op";
 
 /**
- * The most generic chanin type.
+ * The most generic chain type.
  */
 export type GenericChainType = "generic";
 

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

@@ -72,7 +72,7 @@ export type RunCompilationJobOptions = Pick<
  */
 export interface CompileBuildInfoOptions {
   /**
-   * If `true`, this option foces the build system to recompile the build info,
+   * If `true`, this option forces the build system to recompile the build info,
    * even if its output is cached.
    */
   force?: boolean;
@@ -84,26 +84,70 @@ export interface CompileBuildInfoOptions {
 }
 
 export enum CompilationJobCreationErrorReason {
-  NO_COMPATIBLE_SOLC_VERSION_FOUND = "NO_COMPATIBLE_SOLC_VERSION_FOUND",
+  /**
+   * The root file's own pragmas are incompatible with all configured compilers.
+   */
   NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT = "NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT",
-  INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION = "INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION",
+
+  /**
+   * A dependency's own pragmas are incompatible with all configured compilers.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY = "NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY",
+
+  /**
+   * Root and a transitive import path have contradictory pragmas (invalid range / empty intersection).
+   */
   IMPORT_OF_INCOMPATIBLE_FILE = "IMPORT_OF_INCOMPATIBLE_FILE",
+
+  /**
+   * Root and a transitive import path have a valid range but no configured compiler satisfies it.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH = "NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH",
+
+  /**
+   * The override version doesn't satisfy the root file's own pragmas.
+   */
+  INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION = "INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION",
+
+  /**
+   * A dependency's pragmas are incompatible with the override version.
+   */
+  OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY = "OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY",
+
+  /**
+   * Generic fallback — no single compiler works for root + all dependencies.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_FOUND = "NO_COMPATIBLE_SOLC_VERSION_FOUND",
 }
 
 export interface BaseCompilationJobCreationError {
+  success: false;
   buildProfile: string;
   rootFilePath: string;
   formattedReason: string;
 }
 
-export interface CompilationJobCreationErrorNoCompatibleSolcVersionFound
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionWithRoot
   extends BaseCompilationJobCreationError {
   reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT;
 }
 
-export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionWithDependency
   extends BaseCompilationJobCreationError {
-  reason: CompilationJobCreationErrorReason.INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION;
+  reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY;
+  incompatibleImportPath: string[];
+}
+
+export interface CompilationJobCreationErrorImportOfIncompatibleFile
+  extends BaseCompilationJobCreationError {
+  reason: CompilationJobCreationErrorReason.IMPORT_OF_INCOMPATIBLE_FILE;
+  incompatibleImportPath: string[];
+}
+
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionForTransitiveImportPath
+  extends BaseCompilationJobCreationError {
+  reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH;
+  incompatibleImportPath: string[];
 }
 
 export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
@@ -111,24 +155,25 @@ export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
   reason: CompilationJobCreationErrorReason.INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION;
 }
 
-export interface CompilationJobCreationErrorIportOfIncompatibleFile
+export interface CompilationJobCreationErrorOverriddenSolcVersionIncompatibleWithDependency
   extends BaseCompilationJobCreationError {
-  reason: CompilationJobCreationErrorReason.IMPORT_OF_INCOMPATIBLE_FILE;
-  // The path of absolute files imported, starting from the root, that take you
-  // to the first file with an incompatible version pragma.
+  reason: CompilationJobCreationErrorReason.OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY;
   incompatibleImportPath: string[];
 }
 
-export interface NoCompatibleSolcVersionFound
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionFound
   extends BaseCompilationJobCreationError {
   reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_FOUND;
 }
 
 export type CompilationJobCreationError =
-  | CompilationJobCreationErrorNoCompatibleSolcVersionFound
-  | CompilationJobCreationErrorIportOfIncompatibleFile
+  | CompilationJobCreationErrorNoCompatibleSolcVersionWithRoot
+  | CompilationJobCreationErrorNoCompatibleSolcVersionWithDependency
+  | CompilationJobCreationErrorImportOfIncompatibleFile
+  | CompilationJobCreationErrorNoCompatibleSolcVersionForTransitiveImportPath
   | CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
-  | NoCompatibleSolcVersionFound;
+  | CompilationJobCreationErrorOverriddenSolcVersionIncompatibleWithDependency
+  | CompilationJobCreationErrorNoCompatibleSolcVersionFound;
 
 /**
  * The restult of building a file.
@@ -174,6 +219,11 @@ export interface CacheHitInfo {
  * The keys in the maps of this interface are Root File Paths, which means either absolute paths or `npm:<package>/<file>` URIs.
  */
 export interface GetCompilationJobsResult {
+  /**
+   * A flag to distinguish between a successful and a failed result.
+   */
+  success: true;
+
   /**
    * Map from root file path to compilation job for files that need compilation.
    */
@@ -239,12 +289,23 @@ export interface SolidityBuildSystem {
    * @param options The options to use when building the files.
    * @returns An `Map` of the files to their build results, or an error if
    * there was a problem when trying to create the necessary compilation jobs.
+   * @see `isSuccessfulBuildResult` to check if the build result is successful.
    */
   build(
     rootFilePaths: string[],
     options?: BuildOptions,
   ): Promise<CompilationJobCreationError | Map<string, FileBuildResult>>;
 
+  /**
+   * Returns true if the given build result is successful.
+   *
+   * @param buildResult Result of the `build` method.
+   * @returns True if the build result is successful.
+   */
+  isSuccessfulBuildResult(
+    buildResult: CompilationJobCreationError | Map<string, FileBuildResult>,
+  ): buildResult is Map<string, FileBuildResult>;
+
   /**
    * Returns the CompilationJobs that would be used to build the provided files.
    *

package/src/types/solidity/resolved-file.ts

@@ -3,7 +3,7 @@
  */
 export interface ResolvedNpmPackage {
   /**
-   * The name of the package, potentially scopde.
+   * The name of the package, potentially scoped.
    */
   name: string;
 
@@ -103,7 +103,7 @@ export interface NpmPackageResolvedFile {
 }
 
 /**
- * The resolult of resolving a file or import using a Resolver.
+ * The result of resolving a file or import using a Resolver.
  */
 export type ResolvedFile = ProjectResolvedFile | NpmPackageResolvedFile;
 

package/src/types/tasks.ts

@@ -5,6 +5,8 @@ import type {
   PositionalArgumentDefinition,
 } from "./arguments.js";
 import type { HardhatRuntimeEnvironment } from "./hre.js";
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in JSDoc {@link} */
+import type { Result } from "./utils.js";
 
 // We add the TaskManager to the HRE with a module augmentation to avoid
 // introducing a circular dependency that would look like this:
@@ -209,6 +211,10 @@ export interface NewTaskDefinitionBuilder<
    *
    * This method cannot be used together with {@link setInlineAction} on the same
    * task. Use one or the other.
+   *
+   * Task actions may return a {@link Result} to signal success or failure.
+   * If a task returns a failed `Result`, the CLI will set the process exit code
+   * to 1.
    */
   setAction(
     action: LazyActionObject<NewTaskActionFunction<TaskArgumentsT>>,
@@ -225,6 +231,10 @@ export interface NewTaskDefinitionBuilder<
    *
    * This method cannot be used together with {@link setAction} on the same
    * task. Use one or the other.
+   *
+   * Task actions may return a {@link Result} to signal success or failure.
+   * If a task returns a failed `Result`, the CLI will set the process exit code
+   * to 1.
    */
   setInlineAction(
     inlineAction: NewTaskActionFunction<TaskArgumentsT>,

package/src/types/test.ts

@@ -5,3 +5,15 @@ export interface HardhatTestUserConfig {}
 /* eslint-disable-next-line @typescript-eslint/no-empty-interface -- Empty
 interface allow plugins to extend the Test configuration for Hardhat. */
 export interface HardhatTestConfig {}
+
+/**
+ * Summary of a test run, containing counts of test outcomes and optional
+ * failure output.
+ */
+export interface TestSummary {
+  failed: number;
+  passed: number;
+  skipped: number;
+  todo: number;
+  failureOutput?: string;
+}