hardhat 3.0.0-next.2 → 3.0.0-next.20

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

@@ -1,4 +1,18 @@
-import type { Remapping, Resolver } from "./types.js";
+import type {
+  Resolver,
+  RemappedNpmPackagesGraphJson,
+  Remapping,
+  ResolvedNpmUserRemapping,
+  ResolvedUserRemapping,
+  Result,
+} from "./types.js";
+import type {
+  ImportResolutionError,
+  NpmRootResolutionError,
+  ProjectRootResolutionError,
+  ResolvedFileReference,
+  UserRemappingReference,
+} from "../../../../../types/solidity/errors.js";
 import type {
   ResolvedNpmPackage,
   ResolvedFile,
@@ -9,1591 +23,1122 @@ import type {
 
 import path from "node:path";
 
-import {
-  HardhatError,
-  assertHardhatInvariant,
-} from "@nomicfoundation/hardhat-errors";
-import { ensureError } from "@nomicfoundation/hardhat-utils/error";
-import {
-  FileNotFoundError,
-  exists,
-  getFileTrueCase,
-  readJsonFile,
-  readUtf8File,
-} from "@nomicfoundation/hardhat-utils/fs";
-import {
-  findClosestPackageJson,
-  findDependencyPackageJson,
-} from "@nomicfoundation/hardhat-utils/package";
-import { shortenPath } from "@nomicfoundation/hardhat-utils/path";
+import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import { exists } from "@nomicfoundation/hardhat-utils/fs";
 import { analyze } from "@nomicfoundation/solidity-analyzer";
-import * as resolve from "resolve.exports";
 
+import {
+  ImportResolutionErrorType,
+  RootResolutionErrorType,
+} from "../../../../../types/solidity/errors.js";
 import { ResolvedFileType } from "../../../../../types/solidity/resolved-file.js";
 import { AsyncMutex } from "../../../../core/async-mutex.js";
-import {
-  NpmPackageResolvedFileImplementation,
-  ProjectResolvedFileImplementation,
-} from "../resolved-file.js";
 
+import { parseNpmDirectImport } from "./npm-module-parsing.js";
 import {
-  applyValidRemapping,
-  parseRemappingString,
-  selectBestRemapping,
-} from "./remappings.js";
-
-// Things to note:
-//  - This resolver assumes that the root of the project is the folder with the
-//    closest package.json to the config file.
-//  - Each file system file is resolved to a single ResolvedFile, with a unique
-//    source name.
-//  - Files within the project have their relative path as their source name.
-//  - Files within npm packages have source names that start with `npm/` and
-//    contain the package name and version. e.g. `npm/package@1.2.3/path.sol`.
-//  - Files within npm packages that are part of a monorepo are resolved like
-//    npm pacakges, but with the version `local`.
-//  - This resolver fails if an import has a casing different from that of the
-//    file system.
-//  - We do not allow users to remap the imports present in files within npm
-//    packages, by forbidding user remappings with context and starting with
-//    `npm/`.
-//  - We do allow users to remap imports of non-npm files, including remmapping
-//    them into npm packages.
-//  - Every import in an npm file is either relative or remapped by a remapping
-//    generated by the resolver.
-//  - A direct import (i.e. not relative) is considered to be local within the
-//    the project/package if it is a bare file name (not in a directory), or if
-//    the first directory exists in the project/package.
-//  - The direct import "hardhat/console.sol" is a special case and it is never
-//    considered to be local. And we only remap `hardhat/console.sol`.
-//  - Local imports within the project may be remapped by user remappings, but
-//    not by the resolver.
-//  - Imports into npm packages are always remapped, if not by the user, by the
-//    resolver.
-//  - Direct local improts within npm package are always remapped by the
-//    resolver.
-
-/**
- * A user remapping, parsed, and with its npm package resolved, if any.
- */
-interface ResolvedUserRemapping {
-  rawFormat: string;
-  context: string;
-  prefix: string;
-  target: string;
-  targetNpmPackage?: ResolvedNpmPackage;
-}
+  isResolvedUserRemapping,
+  RemappedNpmPackagesGraphImplementation,
+} from "./remapped-npm-packages-graph.js";
+import { applyValidRemapping, formatRemapping } from "./remappings.js";
+import {
+  fsPathToSourceNamePath,
+  sourceNamePathJoin,
+  sourceNamePathToFsPath,
+} from "./source-name-utils.js";
+import { UserRemappingType } from "./types.js";
+import {
+  PathValidationErrorType,
+  resolveSubpathWithPackageExports,
+  validateFsPath,
+} from "./utils.js";
 
-/**
- * A sentinel value that represents the root of the Hardhat project.
- */
-const PROJECT_ROOT_SENTINEL: unique symbol = Symbol();
+const NPM_PACKAGES_WITH_SIMULATED_PACKAGE_EXPORTS = new Set(["forge-std"]);
 
 export class ResolverImplementation implements Resolver {
   readonly #projectRoot: string;
-  readonly #userRemappings: ResolvedUserRemapping[];
+  readonly #npmPackageGraph: RemappedNpmPackagesGraphImplementation;
+  readonly #hhProjectPackage: ResolvedNpmPackage;
+  readonly #readUtf8File: (absPath: string) => Promise<string>;
 
   /**
    * IMPORTANT: This mutex must be acquired before writing to any of the mutable
-   * fields of this class. We do this by using the mutex in the public methods,
-   * which don't call each other.
-   */
-  readonly #mutex = new AsyncMutex();
-
-  /**
-   * A map of all the npm dependencies used in the project, and their
-   * dependencies.
+   * fields of this class.
    *
-   * This is more complex than you may expect, as we have to handle:
-   *
-   *   - The Hardhat project itself, which is treated differently than npm
-   *     packages, and is represented by the value `PROJECT_ROOT_SENTINEL`.
-   *   - The case where a package is installed with a different name than the
-   *     package's name in its `package.json`. We refer to the name with which
-   *     the package is installed as the "installation name".
-   *   - Imports from monorepo packages into the Hardhat project.
+   * We do this by using the mutex in the public methods, which don't call each
+   * other.
    */
-  readonly #dependencyMaps: Map<
-    ResolvedNpmPackage | typeof PROJECT_ROOT_SENTINEL,
-    Map<
-      string, // The installation-name of the package that is being imported
-      ResolvedNpmPackage | typeof PROJECT_ROOT_SENTINEL // The package imported with that name
-    >
-  > = new Map();
+  readonly #mutex = new AsyncMutex();
 
   /**
-   * A map of all the prefixes that an npm package needs to set as remappings
-   * to avoid being affected by a user remapping.
-   *
-   * For example, if a package `foo` has an import `import "dep/File.sol";`,
-   * and the user remaps `dep/=nope/`, it could break `foo`'s import.
-   *
-   * To avoid this situation we set all the prefixes that `foo` needs unaffected
-   * by the user remapping, with a higher precedence than user remappings.
-   */
-  readonly #localPrefixesByPackage: Map<ResolvedNpmPackage, Set<string>> =
+   * We use this map to ensure that we only resolve each file once.
+   **/
+  readonly #resolvedFileByInputSourceName: Map<string, ResolvedFile> =
     new Map();
 
   /**
-   * We use this map to ensure that we only resolve each file once.
-   **/
-  readonly #resolvedFileBySourceName: Map<string, ResolvedFile> = new Map();
+   * A fake `<root>.sol` file that we use to resolve npm roots using
+   * the same logic we use for imports.
+   */
+  readonly #fakeRootFile: ProjectResolvedFile;
 
   /**
-   * Creates a new Resolver.
+   * Creates a new resolver.
    *
    * @param projectRoot The absolute path to the Hardhat project root.
-   * @param userRemappingStrings The remappings provided by the user.
+   * @param readUtf8File A function that reads a UTF-8 file.
+   * @returns The resolver or the user remapping errors found.
    */
   public static async create(
     projectRoot: string,
-    userRemappingStrings: string[],
+    readUtf8File: (absPath: string) => Promise<string>,
   ): Promise<Resolver> {
-    const userRemappings = await Promise.all(
-      userRemappingStrings.map((remappingString) =>
-        validateAndResolveUserRemapping(projectRoot, remappingString),
-      ),
-    );
+    const map =
+      await RemappedNpmPackagesGraphImplementation.create(projectRoot);
 
-    return new ResolverImplementation(projectRoot, userRemappings);
+    return new ResolverImplementation(projectRoot, map, readUtf8File);
   }
 
   private constructor(
     projectRoot: string,
-    userRemappings: ResolvedUserRemapping[],
+    npmPackagesGraph: RemappedNpmPackagesGraphImplementation,
+    readUtf8File: (absPath: string) => Promise<string>,
   ) {
     this.#projectRoot = projectRoot;
-    this.#userRemappings = userRemappings;
-    this.#dependencyMaps.set(PROJECT_ROOT_SENTINEL, new Map());
+    this.#npmPackageGraph = npmPackagesGraph;
+    this.#hhProjectPackage = npmPackagesGraph.getHardhatProjectPackage();
+    this.#readUtf8File = readUtf8File;
+
+    const fakeRootFileName = "<fake-root-do-not-use>.sol";
+    this.#fakeRootFile = {
+      type: ResolvedFileType.PROJECT_FILE,
+      inputSourceName: sourceNamePathJoin(
+        this.#hhProjectPackage.inputSourceNameRoot,
+        fakeRootFileName,
+      ),
+      fsPath: path.join(this.#projectRoot, fakeRootFileName),
+      content: {
+        importPaths: [],
+        text: "",
+        versionPragmas: [],
+      },
+      package: this.#hhProjectPackage,
+    };
   }
 
   public async resolveProjectFile(
     absoluteFilePath: string,
-  ): Promise<ProjectResolvedFile> {
+  ): Promise<Result<ProjectResolvedFile, ProjectRootResolutionError>> {
     return this.#mutex.exclusiveRun(async () => {
-      if (!absoluteFilePath.startsWith(this.#projectRoot)) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVING_INCORRECT_FILE_AS_PROJECT_FILE,
-          {
-            file: shortenPath(absoluteFilePath),
-          },
-        );
-      }
+      return this.#resolveProjectFile(absoluteFilePath);
+    });
+  }
 
-      const relativeFilePath = path.relative(
-        this.#projectRoot,
-        absoluteFilePath,
-      );
+  public async resolveNpmDependencyFileAsRoot(
+    npmModule: string,
+  ): Promise<
+    Result<
+      { file: NpmPackageResolvedFile; remapping?: ResolvedNpmUserRemapping },
+      NpmRootResolutionError
+    >
+  > {
+    return this.#mutex.exclusiveRun(async () => {
+      return this.#resolveNpmDependencyFileAsRoot(npmModule);
+    });
+  }
 
-      // We first check if the file has already been resolved.
-      //
-      // Note that it may have received the right path, but with the wrong
-      // casing. We don't care at this point, as it would just mean a cache
-      // miss, and we proceed to get the right casing in that case.
-      //
-      // However, as most of the time these absolute paths are read from the file
-      // system, they'd have the right casing in general.
-      //
-      // If we need to fetch the right casing, we'd have to recheck the cache,
-      // to avoid re-resolving the file.
-      let sourceName = fsPathToSourceNamePath(relativeFilePath);
-      const existing = this.#resolvedFileBySourceName.get(sourceName);
-
-      if (existing !== undefined) {
-        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a ProjectResolvedFile */
-        return existing as ProjectResolvedFile;
-      }
+  public async resolveImport(
+    from: ResolvedFile,
+    importPath: string,
+  ): Promise<
+    Result<
+      { file: ResolvedFile; remapping?: Remapping | ResolvedUserRemapping },
+      ImportResolutionError
+    >
+  > {
+    return this.#mutex.exclusiveRun(async () =>
+      this.#resolveImport(from, importPath),
+    );
+  }
 
-      let trueCaseFsPath: string;
-      try {
-        trueCaseFsPath = await getFileTrueCase(
-          this.#projectRoot,
-          relativeFilePath,
-        );
-      } catch (error) {
-        ensureError(error, FileNotFoundError);
+  async #resolveProjectFile(
+    absoluteFilePath: string,
+  ): Promise<Result<ProjectResolvedFile, ProjectRootResolutionError>> {
+    if (!absoluteFilePath.startsWith(this.#projectRoot)) {
+      return {
+        success: false,
+        error: {
+          type: RootResolutionErrorType.PROJECT_ROOT_FILE_NOT_IN_PROJECT,
+          absoluteFilePath,
+        },
+      };
+    }
 
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVING_NONEXISTENT_PROJECT_FILE,
-          { file: shortenPath(absoluteFilePath) },
-          error,
-        );
-      }
+    const relativeFilePath = path.relative(this.#projectRoot, absoluteFilePath);
 
-      // Now that we have the correct casing, we "fix" the source name.
-      sourceName = fsPathToSourceNamePath(trueCaseFsPath);
+    // We first check if the file has already been resolved.
+    //
+    // Note that it may have received the right path, but with the wrong
+    // casing. We don't care at this point, as it would just mean a cache
+    // miss, and we proceed to get the right casing in that case.
+    //
+    // However, as most of the time these absolute paths are read from the file
+    // system, they'd have the right casing in general.
+    //
+    // If we need to fetch the right casing, we'd have to recheck the cache,
+    // to avoid re-resolving the file.
+    let inputSourceName = sourceNamePathJoin(
+      this.#hhProjectPackage.inputSourceNameRoot,
+      fsPathToSourceNamePath(relativeFilePath),
+    );
 
-      // Maybe it was already resolved, so we need to check with the right
-      // casing
-      const resolvedWithTheRightCasing =
-        this.#resolvedFileBySourceName.get(sourceName);
-      if (resolvedWithTheRightCasing !== undefined) {
-        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      -- If it was, it's a ProjectResolvedFile */
-        return resolvedWithTheRightCasing as ProjectResolvedFile;
-      }
+    const existing = this.#resolvedFileByInputSourceName.get(inputSourceName);
 
-      const fsPathWithTheRightCasing = path.join(
-        this.#projectRoot,
-        trueCaseFsPath,
-      );
+    if (existing !== undefined) {
+      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
+        The cache is type-unsafe, but we are sure this is a ProjectResolvedFile
+        because of how its input source name is created */
+      const existingProjectResolvedFile = existing as ProjectResolvedFile;
+
+      return {
+        success: true,
+        value: existingProjectResolvedFile,
+      };
+    }
 
-      const resolvedFile: ProjectResolvedFile =
-        new ProjectResolvedFileImplementation({
-          sourceName,
-          fsPath: fsPathWithTheRightCasing,
-          content: await readFileContent(fsPathWithTheRightCasing),
-        });
+    if (relativeFilePath.startsWith("node_modules" + path.sep)) {
+      return {
+        success: false,
+        error: {
+          type: RootResolutionErrorType.PROJECT_ROOT_FILE_IN_NODE_MODULES,
+          absoluteFilePath,
+        },
+      };
+    }
 
-      this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
+    const pathValidation = await validateFsPath(
+      this.#projectRoot,
+      relativeFilePath,
+    );
 
-      return resolvedFile;
-    });
-  }
+    let realCasingRelativePath = relativeFilePath;
+    if (pathValidation.success === false) {
+      if (pathValidation.error.type === PathValidationErrorType.DOESNT_EXIST) {
+        return {
+          success: false,
+          error: {
+            type: RootResolutionErrorType.PROJECT_ROOT_FILE_DOESNT_EXIST,
+            absoluteFilePath,
+          },
+        };
+      }
 
-  public async resolveNpmDependencyFileAsRoot(
-    npmModule: string,
-  ): Promise<NpmPackageResolvedFile> {
-    return this.#mutex.exclusiveRun(async () => {
-      const parsedNpmModule = this.#parseNpmDirectImport(npmModule);
+      // Now that we have the correct casing, we "fix" the input source name.
+      realCasingRelativePath = pathValidation.error.correctCasing;
+      inputSourceName = sourceNamePathJoin(
+        this.#hhProjectPackage.inputSourceNameRoot,
+        fsPathToSourceNamePath(realCasingRelativePath),
+      );
+    }
 
-      if (parsedNpmModule === undefined) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVE_NPM_FILE_WITH_INVALID_FORMAT,
-          { module: npmModule },
-        );
-      }
+    // Maybe it was already resolved, so we need to check with the right
+    // casing
+    const resolvedWithTheRightCasing =
+      this.#resolvedFileByInputSourceName.get(inputSourceName);
+    if (resolvedWithTheRightCasing !== undefined) {
+      const resolvedWithTheRightCasingProjectResolvedFile =
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          -- Same as above, we know it's a project file because of its input
+          source name */
+        resolvedWithTheRightCasing as ProjectResolvedFile;
+
+      return {
+        success: true,
+        value: resolvedWithTheRightCasingProjectResolvedFile,
+      };
+    }
 
-      if (await this.#isDirectImportLocal(this.#projectRoot, npmModule)) {
-        const directory =
-          this.#getDirectImportLocalDesambiguationPrefix(npmModule);
+    const fsPathWithTheRightCasing = path.join(
+      this.#projectRoot,
+      realCasingRelativePath,
+    );
 
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVE_NPM_FILE_CLASHES_WITH_LOCAL_FILES,
-          {
-            module: npmModule,
-            directory,
-          },
-        );
-      }
+    const resolvedFile = await this.#buildResolvedFile({
+      npmPackage: this.#hhProjectPackage,
+      fsPath: fsPathWithTheRightCasing,
+      inputSourceName,
+    });
 
-      const modulePackageName = parsedNpmModule.package;
+    this.#resolvedFileByInputSourceName.set(inputSourceName, resolvedFile);
 
-      const npmPackage = await this.#resolveNpmPackage({
-        from: PROJECT_ROOT_SENTINEL,
-        packageName: modulePackageName,
-      });
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
+      We know it's a project file, because we created it. */
+    const resolvedFileAsProjectFile = resolvedFile as ProjectResolvedFile;
 
-      assertHardhatInvariant(
-        npmPackage !== PROJECT_ROOT_SENTINEL,
-        "Resolving a local file as if it were an npm module",
-      );
+    return {
+      success: true,
+      value: resolvedFileAsProjectFile,
+    };
+  }
 
-      const subpath = parsedNpmModule.subpath;
-      const resolvedSubpath = resolveSubpath(npmPackage, subpath);
+  public toJSON(): {
+    resolvedFileBySourceName: Record<string, ResolvedFile>;
+    remappedNpmPackagesGraph: RemappedNpmPackagesGraphJson;
+  } {
+    return {
+      resolvedFileBySourceName: Object.fromEntries(
+        this.#resolvedFileByInputSourceName.entries(),
+      ),
+      remappedNpmPackagesGraph: this.#npmPackageGraph.toJSON(),
+    };
+  }
 
-      const relativeFsPath = sourceNamePathToFsPath(resolvedSubpath);
-      let trueCaseFsPath: string;
-      try {
-        trueCaseFsPath = await getFileTrueCase(
-          npmPackage.rootFsPath,
-          relativeFsPath,
-        );
-      } catch (error) {
-        ensureError(error, FileNotFoundError);
+  async #resolveNpmDependencyFileAsRoot(
+    npmModule: string,
+  ): Promise<
+    Result<
+      { file: NpmPackageResolvedFile; remapping?: ResolvedNpmUserRemapping },
+      NpmRootResolutionError
+    >
+  > {
+    // We want to be sure that the resolution of npm root files is treated
+    // exactly like imports, so we use a fake root file and resolve the
+    // npmModule as if it were a directImport inside of it.
+    //
+    // NOTE: As we use a public method here, we don't acquire the mutex,
+    // but we don't modify the state in this method itself.
+    const parsedNpmModule = parseNpmDirectImport(npmModule);
+
+    if (parsedNpmModule === undefined) {
+      return {
+        success: false,
+        error: {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_NAME_WITH_INVALID_FORMAT,
+          npmModule,
+        },
+      };
+    }
 
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVE_NON_EXISTENT_NPM_ROOT,
-          { module: npmModule },
-          error,
-        );
-      }
+    const result = await this.#resolveImport(this.#fakeRootFile, npmModule);
 
-      if (relativeFsPath !== trueCaseFsPath) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.RESOLVE_WRONG_CASING_NPM_ROOT,
-          { module: npmModule },
-        );
-      }
+    if (result.success === false) {
+      return {
+        success: false,
+        error: this.#importResolutionErrorToNpmRootResolutionError(
+          npmModule,
+          result.error,
+        ),
+      };
+    }
 
-      const sourceName = sourceNamePathJoin(
-        npmPackageToRootSourceName(npmPackage.name, npmPackage.version),
-        // We use the subpath (pre-resolution) to create source names
-        subpath,
-      );
+    const resolvedFile = result.value.file;
 
-      const resolved = this.#resolvedFileBySourceName.get(sourceName);
+    assertHardhatInvariant(
+      result.value.remapping !== undefined,
+      "We must have a remapping here, becase we either resolved though a user remapping, or npm",
+    );
 
-      if (resolved !== undefined) {
-        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      -- If it was, it's a ProjectResolvedFile */
-        return resolved as NpmPackageResolvedFile;
-      }
+    // If resolving this fake import results in using a user remapping, we
+    // need to return it.
+    //
+    // If instead, if using a generated remapping for that import, we don't
+    // return it, as this is not a real import.
+    const remapping = isResolvedUserRemapping(result.value.remapping)
+      ? result.value.remapping
+      : undefined;
+
+    // This could happen due to a user remapping
+    if (resolvedFile.type !== ResolvedFileType.NPM_PACKAGE_FILE) {
+      assertHardhatInvariant(
+        remapping !== undefined,
+        "Expected user remapping to be present if the import resolved to a local file",
+      );
 
-      const fsPath = path.join(npmPackage.rootFsPath, trueCaseFsPath);
+      return {
+        success: false,
+        error: {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_RESOLVES_TO_PROJECT_FILE,
+          npmModule,
+          userRemapping: {
+            originalUserRemapping: remapping.originalFormat,
+            actualUserRemapping: formatRemapping(remapping),
+            remappingSource: remapping.source,
+          },
+          resolvedFileFsPath: resolvedFile.fsPath,
+        },
+      };
+    }
 
-      const resolvedFile: NpmPackageResolvedFile =
-        new NpmPackageResolvedFileImplementation({
-          sourceName,
-          fsPath,
-          content: await readFileContent(fsPath),
-          package: npmPackage,
-        });
+    // By this point, we know if that we have a user remapping, it's into an
+    // npm package, because otherwise we would have returned an error.
+    // We need to do this invariant assertion here, because otherwise TS will
+    // complain.
+    let remappingReuslt: ResolvedNpmUserRemapping | undefined;
+    if (remapping !== undefined) {
+      assertHardhatInvariant(
+        remapping.type === UserRemappingType.NPM,
+        "If we have a user remapping, it must be a npm remapping",
+      );
 
-      this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
+      remappingReuslt = remapping;
+    }
 
-      return resolvedFile;
-    });
+    return {
+      success: true,
+      value: {
+        file: resolvedFile,
+        remapping: remappingReuslt,
+      },
+    };
   }
 
-  public async resolveImport(
+  async #resolveImport(
     from: ResolvedFile,
     importPath: string,
-  ): Promise<ResolvedFile> {
-    return this.#mutex.exclusiveRun(async () => {
-      let directImport = importPath;
+  ): Promise<
+    Result<
+      {
+        file: ResolvedFile;
+        remapping?: Remapping | ResolvedUserRemapping;
+      },
+      ImportResolutionError
+    >
+  > {
+    // Imports shouldn't include windows separators
+    if (importPath.includes("\\")) {
+      return {
+        success: false,
+        error: {
+          type: ImportResolutionErrorType.IMPORT_WITH_WINDOWS_PATH_SEPARATORS,
+          fromFsPath: from.fsPath,
+          importPath,
+        },
+      };
+    }
 
-      if (path.sep !== "/" && importPath.includes(path.sep)) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.IMPORT_PATH_WITH_WINDOWS_SEPARATOR,
-          {
+    const isRelativeImport =
+      importPath.startsWith("./") || importPath.startsWith("../");
+
+    const directImport = isRelativeImport
+      ? sourceNamePathJoin(path.dirname(from.inputSourceName), importPath)
+      : importPath;
+
+    if (isRelativeImport) {
+      // If the import is relative, it shouldn't leave its package
+      if (!directImport.startsWith(from.package.inputSourceNameRoot)) {
+        return {
+          success: false,
+          error: {
+            type: ImportResolutionErrorType.ILLEGAL_RELATIVE_IMPORT,
+            fromFsPath: from.fsPath,
             importPath,
-            from: shortenPath(from.fsPath),
           },
-        );
+        };
       }
 
-      if (importPath.startsWith("./") || importPath.startsWith("../")) {
-        directImport = sourceNamePathJoin(
-          path.dirname(from.sourceName),
-          importPath,
-        );
-
-        if (from.type === ResolvedFileType.NPM_PACKAGE_FILE) {
-          if (!directImport.startsWith(from.package.rootSourceName)) {
-            throw new HardhatError(
-              HardhatError.ERRORS.SOLIDITY.ILLEGAL_PACKAGE_IMPORT,
-              {
-                importPath,
-                from: shortenPath(from.fsPath),
-              },
-            );
-          }
-        } else {
-          if (directImport.startsWith("../")) {
-            throw new HardhatError(
-              HardhatError.ERRORS.SOLIDITY.ILEGALL_PROJECT_IMPORT,
-              {
-                importPath,
-                from: shortenPath(from.fsPath),
-              },
-            );
-          }
-        }
+      // It also shouldn't get into its package's node_modules
+      if (
+        directImport.startsWith(
+          sourceNamePathJoin(from.package.inputSourceNameRoot, "node_modules"),
+        )
+      ) {
+        return {
+          success: false,
+          error: {
+            type: ImportResolutionErrorType.RELATIVE_IMPORT_INTO_NODE_MODULES,
+            fromFsPath: from.fsPath,
+            importPath,
+          },
+        };
       }
+    }
 
-      switch (from.type) {
-        case ResolvedFileType.PROJECT_FILE:
-          return this.#resolveImportFromProjectFile({
-            from,
-            importPath,
-            directImport,
-          });
+    // Now, we get the best user remapping, if there's any.
+    const bestUserRemappingResult =
+      await this.#npmPackageGraph.selectBestUserRemapping(from, directImport);
 
-        case ResolvedFileType.NPM_PACKAGE_FILE:
-          return this.#resolveImportFromNpmPackageFile({
-            from,
+    if (bestUserRemappingResult.success === false) {
+      return {
+        success: false,
+        error: {
+          type: ImportResolutionErrorType.IMPORT_WITH_REMAPPING_ERRORS,
+          fromFsPath: from.fsPath,
+          importPath,
+          remappingErrors: bestUserRemappingResult.error,
+        },
+      };
+    }
+
+    const bestUserRemapping = bestUserRemappingResult.value;
+
+    if (isRelativeImport) {
+      // Relative imports should be resolved based on the file system, so
+      // they should not be affected by user remapping.
+      if (bestUserRemapping !== undefined) {
+        return {
+          success: false,
+          error: {
+            type: ImportResolutionErrorType.RELATIVE_IMPORT_CLASHES_WITH_USER_REMAPPING,
+            fromFsPath: from.fsPath,
             importPath,
             directImport,
-          });
+            userRemapping: this.#buildUserRemappingReference({
+              userRemapping: bestUserRemapping,
+            }),
+          },
+        };
       }
-    });
-  }
 
-  public getRemappings(): Remapping[] {
-    const userRemappings = this.#userRemappings.map((remapping) => ({
-      context: remapping.context,
-      prefix: remapping.prefix,
-      target: remapping.target,
-    }));
-
-    const remappings: Remapping[] = [];
-
-    for (const [
-      thePackage,
-      dependenciesMap,
-    ] of this.#dependencyMaps.entries()) {
-      let context: string;
-
-      if (thePackage === PROJECT_ROOT_SENTINEL) {
-        context = "";
-      } else {
-        context = thePackage.rootSourceName;
+      return this.#resolveRelativeImport({
+        from,
+        importPath,
+        directImport,
+      });
+    } else {
+      if (bestUserRemapping !== undefined) {
+        // If the import isn't relative, and there's a user remapping, we
+        // prioritize that.
+        return this.#resolveUserRemappedImport({
+          from,
+          importPath,
+          directImport,
+          remapping: bestUserRemapping,
+        });
       }
 
-      for (const [importedPackage, dependency] of dependenciesMap.entries()) {
-        // As `hardhat/console.sol` is always resolved through npm, even if the
-        // `hardhat/` folder exists in the root of the package/project, we
-        // only remap that file.
-        //
-        // We should revisit this if we exported more solidity files in the
-        // hardhat package in the future.
-        //
-        // Also note that we are using the importedPackageName here, and not
-        // the dependency's name, and that's because we always resolve 'hardhat'
-        // as the hh package itself. If someone installs another package as
-        // "hardhat", it may break.
-        if (
-          dependency !== PROJECT_ROOT_SENTINEL &&
-          importedPackage === "hardhat"
-        ) {
-          const prefix = importedPackage + "/console.sol";
-          const target = dependency.rootSourceName + "console.sol";
-
-          remappings.push({ context, prefix, target });
-        } else {
-          const prefix = importedPackage + "/";
-
-          const target =
-            dependency === PROJECT_ROOT_SENTINEL
-              ? ""
-              : dependency.rootSourceName;
-
-          // If a dependency is being remapped by the user using the same
-          // prefix, we don't want to override it, as it can cause problems
-          // when a file from that dependency is also treated as a root.
-          //
-          // For example, if the user sets this remapping
-          // "forge-std/=npm/forge-std@1.9.4/src/" and for some reason also
-          // compiles "forge-std/src/Test.sol" as a root.
-          //
-          // Without this check, we would have two remappings in the solc input:
-          //    "forge-std/=npm/forge-std@1.9.4/src/"
-          //    "forge-std/=npm/forge-std@1.9.4/"
-          // and the latter would win, leading to a compilation error.
-          if (thePackage === PROJECT_ROOT_SENTINEL) {
-            if (this.#userRemappings.some((r) => r.prefix === prefix)) {
-              continue;
-            }
-          }
-
-          remappings.push({ context, prefix, target });
-        }
+      // Otherwise it should be resolved through npm
+      const npmResolutionResult = await this.#resolveImportThroughNpm({
+        from,
+        importPath,
+        directImport,
+      });
+
+      if (npmResolutionResult.success === true) {
+        return { success: true, value: npmResolutionResult.value };
       }
-    }
 
-    // TODO: Always order this in a consistent way
-    for (const [packageSourceName, prefixes] of this.#localPrefixesByPackage) {
-      for (const prefix of prefixes) {
-        remappings.push({
-          context: packageSourceName.rootSourceName,
-          prefix,
-          target: packageSourceName.rootSourceName + prefix,
+      // If the npm resolution fails because the package was not installed, or
+      // because the import was invalid, we try to detect if the user was
+      // trying to use a direct import (i.e. not relative) to import a local
+      // file.
+      //
+      // We do this to improve the error message that we generate, and suggest
+      // a user remapping if they insist on using direct imports.
+      if (
+        npmResolutionResult.error.type ===
+          ImportResolutionErrorType.IMPORT_OF_UNINSTALLED_PACKAGE ||
+        npmResolutionResult.error.type ===
+          ImportResolutionErrorType.IMPORT_WITH_INVALID_NPM_SYNTAX
+      ) {
+        const improvedError = await this.#tryToGenerateDirectLocalImportError({
+          from,
+          importPath,
         });
+
+        if (improvedError !== undefined) {
+          return {
+            success: false,
+            error: improvedError,
+          };
+        }
       }
-    }
 
-    // We sort the remappings acording to the remappings selection rules, plus
-    // the targets, which shouldn't be needed.
-    remappings
-      .sort((a, b) => a.target.localeCompare(b.target))
-      .sort((a, b) => a.target.length - b.target.length)
-      .sort((a, b) => a.prefix.localeCompare(b.prefix))
-      .sort((a, b) => a.prefix.length - b.prefix.length)
-      .sort((a, b) => a.context.localeCompare(b.context))
-      .sort((a, b) => a.context.length - b.context.length);
-
-    return [...userRemappings, ...remappings];
+      return npmResolutionResult;
+    }
   }
 
-  // >>>>>>>>>> BEGIN SECTION: Import resolution selection
-  //
-  // The private methods in this section are in charge of selecting which import
-  // resolution technique to use, but they don't create any ResolvedFile.
-  //
-  // These techniques are:
-  //  1. Resolving an import to a project file
-  //  2. Resolving an import remapped by the user into an npm package
-  //  3. Resolving an import from an npm package to one of its own files with a
-  //     relative import
-  //  4. Resolving an import from an npm package to one of its own files with a
-  //     direct import — This case is different from 3, as without especial care
-  //     it could be affected by one of the user remappings.
-  //  5. Resolving an import to a different npm package using our own remappings
-
-  /**
-   * Resolves an import from a project file.
-   *
-   * This method applies the user remappings, if necessary, and uses the
-   * appropriate resolution technique.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths,
-   * but before applying any remapping.
-   */
-  async #resolveImportFromProjectFile({
+  async #resolveRelativeImport({
     from,
     importPath,
     directImport,
   }: {
-    from: ProjectResolvedFile;
-    directImport: string;
+    from: ResolvedFile;
     importPath: string;
-  }): Promise<ResolvedFile> {
-    const bestUserRemapping = selectBestRemapping(
-      from.sourceName,
-      directImport,
-      this.#userRemappings,
-    );
+    directImport: string;
+  }): Promise<Result<{ file: ResolvedFile }, ImportResolutionError>> {
+    const inputSourceName = directImport;
 
-    if (bestUserRemapping !== undefined) {
-      return this.#resolveUserRemappedImportFromProjectFile({
-        from,
-        importPath,
-        directImport,
-        remapping: bestUserRemapping,
-      });
+    const existing = this.#resolvedFileByInputSourceName.get(inputSourceName);
+    if (existing !== undefined) {
+      return { success: true, value: { file: existing } };
     }
 
-    if (await this.#isDirectImportLocal(this.#projectRoot, directImport)) {
-      return this.#resolveImportToProjectFile({
-        from,
-        importPath,
-        fsPathWithinTheProject: sourceNamePathToFsPath(directImport),
-      });
-    }
+    const relativeSourceNamePath = this.#getRelativeSourceNamePath({
+      npmPackage: from.package,
+      fileInputSourceName: inputSourceName,
+    });
 
-    return this.#resolveImportThroughNpm({
+    const relativeFsPath = sourceNamePathToFsPath(relativeSourceNamePath);
+
+    return this.#commonImportResolution({
       from,
       importPath,
-      directImport,
+      npmPackage: from.package,
+      inputSourceName,
+      relativeFsPathWithinPackage: relativeFsPath,
+      subpath: relativeSourceNamePath,
     });
   }
 
   /**
-   * Resolves an import from a project file that is affected by a user
-   * remapping.
-   *
-   * Note that this method must only be called with the best user remapping
-   * applicable to the import, as defined by solc. Otherwise, it's behavior will
-   * be misleading.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths,
-   * but before applying any remapping.
-   * @param remapping The user remapping that will be applied.
+   * Resolves a user remapped import.
+   * @returns The resolved file, or an error. If successful, the remapping is
+   * always present, and of type `ResolvedUserRemapping`.
    */
-  async #resolveUserRemappedImportFromProjectFile({
+  async #resolveUserRemappedImport({
     from,
     importPath,
     directImport,
     remapping,
   }: {
-    from: ProjectResolvedFile;
+    from: ResolvedFile;
     importPath: string;
     directImport: string;
     remapping: ResolvedUserRemapping;
-  }): Promise<ResolvedFile> {
+  }): Promise<
+    Result<
+      { file: ResolvedFile; remapping?: Remapping | ResolvedUserRemapping },
+      ImportResolutionError
+    >
+  > {
     const remappedDirectImport = applyValidRemapping(directImport, remapping);
 
-    // Special case, where a user remapping's target is an npm pacakge
-    if (remapping.targetNpmPackage !== undefined) {
-      return this.#resolveImportToNpmPackageRemappedByUser({
-        from,
-        importPath,
-        directImport: remappedDirectImport,
-        remapping: {
-          // This weird syntax is because TS doesn't realize that
-          // bestUserRemapping is Required<ResolvedUserRemapping> here
-          ...remapping,
-          targetNpmPackage: remapping.targetNpmPackage,
-        },
-      });
+    const inputSourceName = remappedDirectImport;
+    const existing =
+      this.#resolvedFileByInputSourceName.get(remappedDirectImport);
+    if (existing !== undefined) {
+      return { success: true, value: { file: existing, remapping } };
     }
 
-    if (
-      !(await this.#isDirectImportLocal(
-        this.#projectRoot,
-        remappedDirectImport,
-      ))
-    ) {
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.ILLEGAL_PROJECT_IMPORT_AFTER_REMAPPING,
-        {
-          importPath,
-          from: shortenPath(from.fsPath),
-          remapping: remapping.rawFormat,
-          remappedDirectImport,
-        },
-      );
-    }
+    const fromNpmPackage =
+      from.type === ResolvedFileType.NPM_PACKAGE_FILE
+        ? from.package
+        : this.#hhProjectPackage;
+
+    // We get the npm package that's the target of the remapping. If none
+    // is present, that's because it's remapping to a local file, so it's
+    // the fromNpmPackage.
+    const targetNpmPackage =
+      remapping.type === UserRemappingType.NPM
+        ? remapping.targetNpmPackage.package
+        : fromNpmPackage;
+
+    // A user remapping is created based on the fs path in the package, so
+    // we can get the relative path based on the input source name root of the
+    // target package.
+    const relativeSourceNamePath = this.#getRelativeSourceNamePath({
+      npmPackage: targetNpmPackage,
+      fileInputSourceName: inputSourceName,
+    });
 
-    return this.#resolveImportToProjectFile({
+    const relativeFsPath = sourceNamePathToFsPath(relativeSourceNamePath);
+
+    return this.#commonImportResolution({
       from,
       importPath,
-      fsPathWithinTheProject: sourceNamePathToFsPath(remappedDirectImport),
+      npmPackage: targetNpmPackage,
+      inputSourceName,
+      relativeFsPathWithinPackage: relativeFsPath,
+      subpath: relativeSourceNamePath,
+      userRemapping: remapping,
     });
   }
 
   /**
-   * Resolves an import from an npm file.
-   *
-   * This method does not apply any remapping that may be present in the npm
-   * package.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths,
-   * but without applying any remapping.
+   * Resolves an import through npm.
+   * @returns The resolved file, or an error. If successful, the remapping is
+   * always present.
    */
-  async #resolveImportFromNpmPackageFile({
+  async #resolveImportThroughNpm({
     from,
     importPath,
     directImport,
   }: {
-    from: NpmPackageResolvedFile;
-    directImport: string;
+    from: ResolvedFile;
     importPath: string;
-  }): Promise<ResolvedFile> {
-    // If we wanted to apply its own remappings, this would be the place.
-    // Initially we won't support it.
-    if (directImport.startsWith(from.package.rootSourceName)) {
-      return this.#resolveRelativeImportFromNpmPackage({
-        from,
-        importPath,
-        directImport,
-      });
+    directImport: string;
+  }): Promise<
+    Result<
+      { file: ResolvedFile; remapping?: Remapping | ResolvedUserRemapping },
+      ImportResolutionError
+    >
+  > {
+    const parsedDirectImport = parseNpmDirectImport(directImport);
+
+    if (parsedDirectImport === undefined) {
+      return {
+        success: false,
+        error: {
+          type: ImportResolutionErrorType.IMPORT_WITH_INVALID_NPM_SYNTAX,
+          fromFsPath: from.fsPath,
+          importPath,
+        },
+      };
+    }
+
+    const fromNpmPackage =
+      from.type === ResolvedFileType.NPM_PACKAGE_FILE
+        ? from.package
+        : this.#hhProjectPackage;
+
+    const installationName = parsedDirectImport.package;
+
+    const dependencyResolution =
+      await this.#npmPackageGraph.resolveDependencyByInstallationName(
+        fromNpmPackage,
+        installationName,
+      );
+
+    if (dependencyResolution === undefined) {
+      return {
+        success: false,
+        error: {
+          type: ImportResolutionErrorType.IMPORT_OF_UNINSTALLED_PACKAGE,
+          fromFsPath: from.fsPath,
+          importPath,
+          installationName: parsedDirectImport.package,
+        },
+      };
     }
 
-    // This was already a direct import, and may be to the same package.
-    // As we allow this imports in the local project files, we should also allow
-    // them on npm packages. If we don't projects won't be easily distributable
-    // through npm, even if they don't use remappings.
+    const dependency = dependencyResolution.package;
+
+    const subpath = parsedDirectImport.subpath;
+
+    let resolvedSubpath: string | undefined;
     if (
-      await this.#isDirectImportLocal(from.package.rootFsPath, directImport)
+      dependency.exports !== undefined ||
+      NPM_PACKAGES_WITH_SIMULATED_PACKAGE_EXPORTS.has(dependency.name)
     ) {
-      const resolvedFile = await this.#resolveLocalImportFromNpmPackage({
-        from,
-        importPath,
-        directImport,
-      });
+      const dependencyWithPackageExports = {
+        ...dependency,
+        exports: dependency.exports ?? {
+          "./*.sol": "./src/*.sol",
+        },
+      };
 
-      let prefixesNeededByPackage = this.#localPrefixesByPackage.get(
-        from.package,
+      const pathResolutionResult = resolveSubpathWithPackageExports(
+        dependencyWithPackageExports,
+        subpath,
       );
 
-      if (prefixesNeededByPackage === undefined) {
-        prefixesNeededByPackage = new Set();
-        this.#localPrefixesByPackage.set(from.package, prefixesNeededByPackage);
+      if (pathResolutionResult.success === false) {
+        return {
+          success: false,
+          error: {
+            type: ImportResolutionErrorType.IMPORT_OF_NON_EXPORTED_NPM_FILE,
+            fromFsPath: from.fsPath,
+            importPath,
+            ...this.#buildResolvedFileReference({
+              npmPackage: dependency,
+              subpath,
+            }),
+          },
+        };
       }
 
-      prefixesNeededByPackage.add(
-        this.#getDirectImportLocalDesambiguationPrefix(directImport),
-      );
-
-      return resolvedFile;
+      resolvedSubpath = pathResolutionResult.value;
     }
 
-    return this.#resolveImportThroughNpm({
-      from,
-      importPath,
-      directImport,
-    });
-  }
+    const inputSourceName = sourceNamePathJoin(
+      dependency.inputSourceNameRoot,
+      resolvedSubpath ?? subpath,
+    );
 
-  /**
-   * This method resolves an import that has to go through the npm resolution
-   * process and selects the appropriate technique to resolve it.
-   *
-   * This method does not apply nor define any remapping, but it populates the
-   * `#dependencyMaps` with dependencies that each package uses, so that we can
-   * create all the necessary remappings at the end of the resolution process.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths,
-   * but without applying any remapping.
-   */
-  async #resolveImportThroughNpm({
-    from,
-    importPath,
-    directImport,
-  }: {
-    from: ResolvedFile;
-    importPath: string;
-    directImport: string;
-  }): Promise<ResolvedFile> {
-    const parsedDirectImport = this.#parseNpmDirectImport(directImport);
+    // There are two types of remappings that we may use for npm imports.
+    //
+    // One is a generic remapping from fromNpmPackage to dependency using
+    // installationName.
+    //
+    // The other one, while more verbose, is a remapping specifically from
+    // forNpmPackage into inputSourceName, using directImport.
+    //
+    // We use the second one when applying package.exports, and it changes the
+    // subpath of the file.
+    const remapping =
+      resolvedSubpath !== undefined && resolvedSubpath !== subpath
+        ? await this.#npmPackageGraph.generateRemappingIntoNpmFile(
+            fromNpmPackage,
+            directImport,
+            inputSourceName,
+          )
+        : dependencyResolution.generatedRemapping;
 
-    if (parsedDirectImport === undefined) {
-      throw new HardhatError(HardhatError.ERRORS.SOLIDITY.INVALID_NPM_IMPORT, {
-        importPath,
-        from: shortenPath(from.fsPath),
-      });
+    const existing = this.#resolvedFileByInputSourceName.get(inputSourceName);
+    if (existing !== undefined) {
+      return {
+        success: true,
+        value: {
+          file: existing,
+          remapping,
+        },
+      };
     }
 
-    const dependency = await this.#resolveNpmPackageForImport({
-      from,
-      importPath,
-      importPackageName: parsedDirectImport.package,
-    });
-
-    if (dependency === PROJECT_ROOT_SENTINEL) {
-      return this.#resolveImportToProjectFile({
-        from,
-        importPath,
-        // If we import a file through npm and end up in the Hardhat project,
-        // we are going to remap the importPackageName to "", so that the path
-        // section of the parsed direct import should be the relative path.
-        fsPathWithinTheProject: sourceNamePathToFsPath(
-          parsedDirectImport.subpath,
-        ),
-      });
-    }
+    const relativePath = resolvedSubpath ?? subpath;
+    const relativeFsPathWithinPackage = sourceNamePathToFsPath(relativePath);
 
-    return this.#resolveImportToNpmPackage({
+    return this.#commonImportResolution({
       from,
       importPath,
-      importedPackage: dependency,
-      subpath: parsedDirectImport.subpath,
+      npmPackage: dependency,
+      inputSourceName,
+      relativeFsPathWithinPackage,
+      subpath,
+      generatedRemapping: remapping,
+      packageExportsResolvedSubpath: resolvedSubpath,
     });
   }
 
-  // >>>>>>>>>> END SECTION: Import resolution selection
-
-  // >>>>>>>>>> BEGIN SECTION: Import resolution techniques
-  //
-  // The private methods in this section implement the different import
-  // import resolution techniques, which have been explained in the previous
-  // section.
-
   /**
-   * This method implements the import resolution technique number 1: Importing
-   * a file that is within the project. Note that this method applies both to
-   * imports from project files as well as imports from npm packages that may
-   * have the project as a dependency.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param pathWithinTheProject The path within the project to import, after
-   * normalizing relative paths, applying user remappings and/or stripping the
-   * npm package name.
+   * Once the other methods selected which file to import, the rest of the logic
+   * is shared in this method.
    */
-  async #resolveImportToProjectFile({
+  async #commonImportResolution({
     from,
     importPath,
-    fsPathWithinTheProject,
+    npmPackage,
+    inputSourceName,
+    relativeFsPathWithinPackage,
+    subpath,
+    userRemapping,
+    generatedRemapping,
+    packageExportsResolvedSubpath,
   }: {
     from: ResolvedFile;
     importPath: string;
-    fsPathWithinTheProject: string;
-  }): Promise<ProjectResolvedFile> {
-    const sourceName = fsPathToSourceNamePath(fsPathWithinTheProject);
-    const existing = this.#resolvedFileBySourceName.get(sourceName);
-    if (existing !== undefined) {
-      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a ProjectResolvedFile */
-      return existing as ProjectResolvedFile;
-    }
-
-    // This is a project file, so if it was imported from a local file, this
-    // is the direct import, without any remapping or necessary consideration.
-    // If this was imported from an npm package, we are remapping the package
-    // name of the import to "", so that the direct import is also the same as
-    // the relative path.
-    await this.#validateExistanceAndCasingOfImport({
-      from,
-      importPath,
-      relativeFsPathToValidate: fsPathWithinTheProject,
-      absoluteFsPathToValidateFrom: this.#projectRoot,
-    });
-
-    const fsPath = path.join(this.#projectRoot, fsPathWithinTheProject);
-
-    const resolvedFile: ProjectResolvedFile =
-      new ProjectResolvedFileImplementation({
-        sourceName,
-        fsPath,
-        content: await readFileContent(fsPath),
-      });
-
-    this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
-
-    return resolvedFile;
-  }
-
-  /**
-   * This method implements the import resolution technique number 2: A project
-   * file has an import that should be resolved to a file in an npm package due
-   * to a user remapping.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths,
-   * and applying the user remapping.
-   * @param remapping The remapping that was applied.
-   */
-  async #resolveImportToNpmPackageRemappedByUser({
-    from,
-    importPath,
-    directImport,
-    remapping,
-  }: {
-    from: ProjectResolvedFile;
-    importPath: string;
-    directImport: string;
-    remapping: Required<ResolvedUserRemapping>;
-  }): Promise<NpmPackageResolvedFile> {
-    const sourceName = directImport;
-    const existing = this.#resolvedFileBySourceName.get(sourceName);
-    if (existing !== undefined) {
-      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a NpmPackageResolvedFile */
-      return existing as NpmPackageResolvedFile;
-    }
-
-    const subpath = path.relative(
-      remapping.targetNpmPackage.rootSourceName,
-      directImport,
+    npmPackage: ResolvedNpmPackage;
+    inputSourceName: string;
+    relativeFsPathWithinPackage: string;
+    subpath: string;
+    userRemapping?: ResolvedUserRemapping;
+    generatedRemapping?: Remapping;
+    packageExportsResolvedSubpath?: string;
+  }): Promise<
+    Result<
+      { file: ResolvedFile; remapping?: Remapping | ResolvedUserRemapping },
+      ImportResolutionError
+    >
+  > {
+    const pathValidation = await validateFsPath(
+      npmPackage.rootFsPath,
+      relativeFsPathWithinPackage,
     );
-    const resolvedSubpath = resolveSubpath(remapping.targetNpmPackage, subpath);
 
-    // We don't add the dependency to `this.#dependencyMaps` because we
-    // don't need a new remapping for this package, as it's already
-    // remapped by the user.
+    if (pathValidation.success === false) {
+      if (pathValidation.error.type === PathValidationErrorType.DOESNT_EXIST) {
+        return {
+          success: false,
+          error: {
+            type: ImportResolutionErrorType.IMPORT_DOESNT_EXIST,
+            fromFsPath: from.fsPath,
+            importPath,
+            ...this.#buildResolvedFileReference({
+              npmPackage,
+              subpath,
+              userRemapping,
+              packageExportsResolvedSubpath,
+            }),
+          },
+        };
+      }
 
-    await this.#validateExistanceAndCasingOfImport({
-      from,
-      importPath,
-      relativeFsPathToValidate: sourceNamePathToFsPath(resolvedSubpath),
-      absoluteFsPathToValidateFrom: remapping.targetNpmPackage.rootFsPath,
-      usingPackageExports: remapping.targetNpmPackage.exports !== undefined,
-    });
+      return {
+        success: false,
+        error: {
+          type: ImportResolutionErrorType.IMPORT_INVALID_CASING,
+          fromFsPath: from.fsPath,
+          importPath,
+          ...this.#buildResolvedFileReference({
+            npmPackage,
+            subpath,
+            userRemapping,
+            packageExportsResolvedSubpath,
+          }),
+          correctCasing: fsPathToSourceNamePath(
+            pathValidation.error.correctCasing,
+          ),
+        },
+      };
+    }
 
     const fsPath = path.join(
-      remapping.targetNpmPackage.rootFsPath,
-      resolvedSubpath,
+      npmPackage.rootFsPath,
+      relativeFsPathWithinPackage,
     );
 
-    const resolvedFile: NpmPackageResolvedFile =
-      new NpmPackageResolvedFileImplementation({
-        sourceName,
-        fsPath,
-        content: await readFileContent(fsPath),
-        package: remapping.targetNpmPackage,
-      });
+    const resolvedFile = await this.#buildResolvedFile({
+      npmPackage,
+      fsPath,
+      inputSourceName,
+    });
 
-    this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
+    this.#resolvedFileByInputSourceName.set(inputSourceName, resolvedFile);
 
-    return resolvedFile;
+    return {
+      success: true,
+      value: {
+        file: resolvedFile,
+        // We only call this function with one of the two, but userRemappings
+        // have priority in general, so writing it this way is safer.
+        remapping: userRemapping ?? generatedRemapping,
+      },
+    };
   }
 
-  /**
-   * This method implements the import resolution technique number 3: A file
-   * from an npm package is importing another file from the same package with a
-   * relative import.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths.
-   * It must start with the package's root source name.
-   */
-  async #resolveRelativeImportFromNpmPackage({
+  async #tryToGenerateDirectLocalImportError({
     from,
     importPath,
-    directImport,
   }: {
-    from: NpmPackageResolvedFile;
-    directImport: string;
+    from: ResolvedFile;
     importPath: string;
-  }): Promise<NpmPackageResolvedFile> {
-    const sourceName = directImport;
-    const existing = this.#resolvedFileBySourceName.get(sourceName);
-    if (existing !== undefined) {
-      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a NpmPackageResolvedFile */
-      return existing as NpmPackageResolvedFile;
+  }): Promise<ImportResolutionError | undefined> {
+    let baseDir = path.dirname(from.fsPath);
+    const firstDir = importPath.substring(0, importPath.indexOf("/"));
+    // If there's no directory separator, or the import is just a directory
+    // we don't suggest a remapping
+    if (firstDir === "" || firstDir.length === importPath.length - 1) {
+      return undefined;
     }
 
-    const relativePath = sourceNamePathToFsPath(
-      path.relative(from.package.rootSourceName, directImport),
-    );
+    while (baseDir.startsWith(from.package.rootFsPath)) {
+      const firstDirPath = path.join(baseDir, firstDir);
 
-    await this.#validateExistanceAndCasingOfImport({
-      from,
-      importPath,
-      relativeFsPathToValidate: relativePath,
-      absoluteFsPathToValidateFrom: from.package.rootFsPath,
-    });
-
-    const filePath = path.join(from.package.rootFsPath, relativePath);
+      if (await exists(firstDirPath)) {
+        const baseDirSourceName = fsPathToSourceNamePath(
+          path.relative(from.package.rootFsPath, baseDir),
+        );
 
-    const resolvedFile: NpmPackageResolvedFile =
-      new NpmPackageResolvedFileImplementation({
-        sourceName,
-        fsPath: filePath,
-        content: await readFileContent(filePath),
-        package: from.package,
-      });
+        const context =
+          from.package === this.#hhProjectPackage
+            ? baseDirSourceName !== ""
+              ? baseDirSourceName + "/"
+              : ""
+            : sourceNamePathJoin(
+                from.package.inputSourceNameRoot,
+                baseDirSourceName + "/",
+              );
+
+        const prefix = firstDir + "/";
+
+        const target =
+          from.package === this.#hhProjectPackage
+            ? prefix
+            : sourceNamePathJoin(from.package.inputSourceNameRoot, prefix);
+
+        return {
+          type: ImportResolutionErrorType.DIRECT_IMPORT_TO_LOCAL_FILE,
+          fromFsPath: from.fsPath,
+          importPath,
+          suggestedRemapping: formatRemapping({
+            context,
+            prefix,
+            target,
+          }),
+        };
+      }
 
-    this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
+      baseDir = path.dirname(baseDir);
+    }
 
-    return resolvedFile;
+    return undefined;
   }
 
-  /**
-   * This method implements the import resolution technique number 4: A file
-   * from an npm package is importing another file from the same package with a
-   * direct import.
-   *
-   * For example, a file `node_modules/foo/File.sol` imports
-   * `node_modules/foo/bar/File2.sol` with the direct import `bar/File2.sol`.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param directImport The direct import path, after resolving relative paths.
-   * The direct import must be considered local within the package, according to
-   * the rules of the `#isDirectImportLocal` method.
-   */
-  async #resolveLocalImportFromNpmPackage({
-    from,
-    importPath,
-    directImport,
+  async #buildResolvedFile({
+    inputSourceName,
+    fsPath,
+    npmPackage,
   }: {
-    from: NpmPackageResolvedFile;
-    directImport: string;
-    importPath: string;
-  }): Promise<NpmPackageResolvedFile> {
-    const sourceName = from.package.rootSourceName + directImport;
-    const existing = this.#resolvedFileBySourceName.get(sourceName);
-    if (existing !== undefined) {
-      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a NpmPackageResolvedFile */
-      return existing as NpmPackageResolvedFile;
-    }
-
-    const relativeFsPath = sourceNamePathToFsPath(directImport);
-
-    await this.#validateExistanceAndCasingOfImport({
-      from,
-      importPath,
-      relativeFsPathToValidate: relativeFsPath,
-      absoluteFsPathToValidateFrom: from.package.rootFsPath,
-    });
-
-    const fsPath = path.join(from.package.rootFsPath, relativeFsPath);
-
-    const resolvedFile: NpmPackageResolvedFile =
-      new NpmPackageResolvedFileImplementation({
-        sourceName,
-        fsPath,
-        content: await readFileContent(fsPath),
-        package: from.package,
-      });
-
-    this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
-
-    return resolvedFile;
+    inputSourceName: string;
+    fsPath: string;
+    npmPackage: ResolvedNpmPackage;
+  }): Promise<ResolvedFile> {
+    const content = await this.#readFileContent({ absolutePath: fsPath });
+
+    return {
+      type:
+        npmPackage === this.#hhProjectPackage
+          ? ResolvedFileType.PROJECT_FILE
+          : ResolvedFileType.NPM_PACKAGE_FILE,
+      inputSourceName,
+      fsPath,
+      content,
+      package: npmPackage,
+    };
   }
 
-  /**
-   * This method implements the import resolution technique number 5: A file,
-   * within the project or from an npm pacakge, is importing a file from a
-   * different npm package.
-   *
-   * Note: This is not meant to support imports into the Hardhat project.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param importedPackage The NpmPackage that is being imported.
-   * @param subpath The path to the file to import, within the
-   * package. That means, after parsing the direct import, and stripping the
-   * package part, before resolving package exports.
-   */
-  async #resolveImportToNpmPackage({
-    from,
-    importPath,
-    importedPackage,
+  #buildResolvedFileReference({
+    npmPackage: targetNpmPackage,
     subpath,
+    userRemapping,
+    packageExportsResolvedSubpath,
   }: {
-    from: ResolvedFile;
-    importPath: string;
-    importedPackage: ResolvedNpmPackage;
+    npmPackage: ResolvedNpmPackage;
     subpath: string;
-  }): Promise<NpmPackageResolvedFile> {
-    const sourceName = importedPackage.rootSourceName + subpath;
-
-    const existing = this.#resolvedFileBySourceName.get(sourceName);
-    if (existing !== undefined) {
-      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
-      The cache is type-unsafe, but we are sure this is a NpmPackageResolvedFile */
-      return existing as NpmPackageResolvedFile;
-    }
-
-    // We use the subpath (pre-resolution) to create source names
-    const resolvedSubpath = resolveSubpath(importedPackage, subpath);
-
-    await this.#validateExistanceAndCasingOfImport({
-      from,
-      importPath,
-      relativeFsPathToValidate: sourceNamePathToFsPath(resolvedSubpath),
-      absoluteFsPathToValidateFrom: importedPackage.rootFsPath,
-      usingPackageExports: importedPackage.exports !== undefined,
-    });
-
-    const fsPath = path.join(importedPackage.rootFsPath, resolvedSubpath);
-
-    const resolvedFile: NpmPackageResolvedFile =
-      new NpmPackageResolvedFileImplementation({
-        sourceName,
-        fsPath,
-        content: await readFileContent(fsPath),
-        package: importedPackage,
-      });
-
-    this.#resolvedFileBySourceName.set(sourceName, resolvedFile);
-
-    return resolvedFile;
+    userRemapping?: ResolvedUserRemapping;
+    packageExportsResolvedSubpath?: string;
+  }): ResolvedFileReference {
+    return {
+      resolvedFileType:
+        targetNpmPackage === this.#hhProjectPackage
+          ? ResolvedFileType.PROJECT_FILE
+          : ResolvedFileType.NPM_PACKAGE_FILE,
+      npmPackage: {
+        name: targetNpmPackage.name,
+        version: targetNpmPackage.version,
+        rootFsPath: targetNpmPackage.rootFsPath,
+      },
+      userRemapping:
+        userRemapping === undefined
+          ? undefined
+          : this.#buildUserRemappingReference({ userRemapping }),
+      subpath,
+      packageExportsResolvedSubpath,
+    };
   }
 
-  // >>>>>>>>>> END SECTION: Import resolution techniques
-
-  /**
-   * Resolves an npm package as a dependency of another one.
-   *
-   * @param from The package to resolve the dependency from.
-   * @param packageName The name of the package that should be resolved as a
-   * dependency.
-   * @returns A ResolvedNpmPackage or PROJECT_ROOT_SENTINEL.
-   */
-  async #resolveNpmPackage({
-    from,
-    packageName,
+  #buildUserRemappingReference({
+    userRemapping,
   }: {
-    from: ResolvedNpmPackage | typeof PROJECT_ROOT_SENTINEL;
-    packageName: string;
-  }): Promise<ResolvedNpmPackage | typeof PROJECT_ROOT_SENTINEL> {
-    let dependenciesMap = this.#dependencyMaps.get(from);
-    if (dependenciesMap === undefined) {
-      dependenciesMap = new Map();
-      this.#dependencyMaps.set(from, dependenciesMap);
-    }
-
-    const dependency = dependenciesMap.get(packageName);
-    if (dependency !== undefined) {
-      return dependency;
-    }
-
-    const baseResolutionDirectory =
-      from === PROJECT_ROOT_SENTINEL ? this.#projectRoot : from.rootFsPath;
-
-    // TODO: This is a quick fix for Hardhat's own package.json, for the alpha
-    // release. We should find a better way to handle this.
-    // We also need to figure out a way to test this inside the monorepo,
-    // without the package `hardhat` in the top-level `node_modules` folder
-    // interfering with the resolution.
-
-    const packageJsonPath =
-      packageName === "hardhat"
-        ? await findClosestPackageJson(import.meta.dirname)
-        : await findDependencyPackageJson(baseResolutionDirectory, packageName);
-
-    if (packageJsonPath === undefined) {
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.NPM_DEPEDNDENCY_NOT_INSTALLED,
-        {
-          from:
-            from === PROJECT_ROOT_SENTINEL
-              ? "your project"
-              : `"${shortenPath(from.rootFsPath)}"`,
-          packageName,
-        },
-      );
-    }
-
-    if (isPackageJsonFromProject(packageJsonPath, this.#projectRoot)) {
-      dependenciesMap.set(packageName, PROJECT_ROOT_SENTINEL);
-      return PROJECT_ROOT_SENTINEL;
-    }
-
-    const packageJson = await readJsonFile<{
-      name: string;
-      version: string;
-      exports?: resolve.Exports;
-    }>(packageJsonPath);
-
-    const name = packageJson.name;
-    const version = isPackageJsonFromMonorepo(
-      packageJsonPath,
-      this.#projectRoot,
-    )
-      ? "local"
-      : packageJson.version;
-
-    const npmPackage: ResolvedNpmPackage = {
-      name,
-      version,
-      exports: packageJson.exports,
-      rootFsPath: path.dirname(packageJsonPath),
-      rootSourceName: npmPackageToRootSourceName(name, version),
+    userRemapping: ResolvedUserRemapping;
+  }): UserRemappingReference {
+    return {
+      originalUserRemapping: userRemapping.originalFormat,
+      actualUserRemapping: formatRemapping(userRemapping),
+      remappingSource: userRemapping.source,
     };
-
-    dependenciesMap.set(packageName, npmPackage);
-    return npmPackage;
   }
 
   /**
-   * Resolves the npm package imported by the importPath in the from file.
-   *
-   * @param from The file from which the import is being resolved.
-   * @param importPath The import path, as written in the source code.
-   * @param importPackageName The name of the package to import, as present in
-   * the importPath, and not necessarily the name of the package in the
-   * package.json.
-   * @returns A ResolvedNpmPackage or PROJECT_ROOT_SENTINEL.
+   * Returns the relative input source name from the npmPackage's input source name root.
+   * @param nmpPackage The package
+   * @param fileInputSourceName The file's input source name.
    */
-  async #resolveNpmPackageForImport({
-    from,
-    importPath,
-    importPackageName,
+  #getRelativeSourceNamePath({
+    npmPackage: nmpPackage,
+    fileInputSourceName,
   }: {
-    from: ResolvedFile;
-    importPath: string;
-    importPackageName: string;
-  }): Promise<ResolvedNpmPackage | typeof PROJECT_ROOT_SENTINEL> {
-    try {
-      return await this.#resolveNpmPackage({
-        from:
-          from.type === ResolvedFileType.PROJECT_FILE
-            ? PROJECT_ROOT_SENTINEL
-            : from.package,
-        packageName: importPackageName,
-      });
-    } catch (error) {
-      ensureError(error);
+    npmPackage: ResolvedNpmPackage;
+    fileInputSourceName: string;
+  }) {
+    return fileInputSourceName.substring(
+      nmpPackage.inputSourceNameRoot.length + 1,
+    );
+  }
 
-      if (
-        HardhatError.isHardhatError(
-          error,
-          HardhatError.ERRORS.SOLIDITY.NPM_DEPEDNDENCY_NOT_INSTALLED,
-        )
-      ) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.IMPORTED_NPM_DEPENDENCY_NOT_INSTALLED,
-          {
-            from: shortenPath(from.fsPath),
-            importPath,
-          },
-          error,
+  #importResolutionErrorToNpmRootResolutionError(
+    npmModule: string,
+    error: ImportResolutionError,
+  ): NpmRootResolutionError {
+    switch (error.type) {
+      /* c8 ignore start */
+      case ImportResolutionErrorType.ILLEGAL_RELATIVE_IMPORT: {
+        assertHardhatInvariant(
+          false,
+          "This could not happen, as we validated that the module name is a valid npm module",
         );
       }
-
-      throw error;
-    }
-  }
-
-  /**
-   * This method returns true if a direct import should be considered an import
-   * to a local file when evaluated in the context of the Hardhat project.
-   */
-  async #isDirectImportLocal(
-    projectOrPackageRootFsPath: string,
-    directImport: string,
-  ): Promise<boolean> {
-    if (directImport === "hardhat/console.sol") {
-      return false;
-    }
-
-    const slash = directImport.indexOf("/");
-
-    // If it's a file in the root directory
-    if (slash === -1) {
-      return true;
-    }
-
-    const firstDirectory = directImport.substring(0, slash);
-
-    // TODO: Cache this?
-    return exists(path.join(projectOrPackageRootFsPath, firstDirectory));
-  }
-
-  /**
-   * Returns the prefix used to desambiguate a directImport by
-   * #isDirectImportLocal to determine if its local.
-   *
-   * For example, the prefix for `foo/bar/File.sol`, this returns `foo/`.
-   *
-   * NOTE: This method does not support `hardhat/console.sol`, as that's a
-   * special case, which is never considered local.
-   */
-  #getDirectImportLocalDesambiguationPrefix(directImport: string): string {
-    const slash = directImport.indexOf("/");
-
-    // If it's a file in the root directory
-    if (slash === -1) {
-      return directImport;
-    }
-
-    const firstDirectory = directImport.substring(0, slash + 1);
-
-    return firstDirectory;
-  }
-
-  /**
-   * This is an utility method that validates the existance and casing of an
-   * imported file as part of the different resolution techniques.
-   *
-   * `from` and `importPath` are used to provide a user-friendly error message,
-   * but the actual validation is done using `relativePathToValidate` and
-   * `absolutePathToValidateFrom`.
-   *
-   * @param from The file with the import.
-   * @param importPath The import path, as written in the source code.
-   * @param relativePathToValidate The relative path to validate its existance.
-   * @param absolutePathToValidateFrom The absolute path from in which the
-   * relative path is.
-   * @param usingPackageExports Whether the import is using package exports,
-   * which controls which kind of error is thrown.
-   */
-  async #validateExistanceAndCasingOfImport({
-    from,
-    importPath,
-    relativeFsPathToValidate,
-    absoluteFsPathToValidateFrom,
-    usingPackageExports,
-  }: {
-    from: ResolvedFile;
-    importPath: string;
-    relativeFsPathToValidate: string;
-    absoluteFsPathToValidateFrom: string;
-    usingPackageExports?: boolean;
-  }) {
-    let trueCaseFsPath: string;
-    try {
-      trueCaseFsPath = await getFileTrueCase(
-        absoluteFsPathToValidateFrom,
-        relativeFsPathToValidate,
-      );
-    } catch (error) {
-      ensureError(error, FileNotFoundError);
-
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.IMPORTED_FILE_DOESNT_EXIST,
-        { importPath, from: shortenPath(from.fsPath) },
-        error,
-      );
-    }
-
-    if (relativeFsPathToValidate !== trueCaseFsPath) {
-      // If we are using package exports, we need to throw a special error,
-      // as we can't compute the correct casing.
-      if (usingPackageExports === true) {
-        throw new HardhatError(
-          HardhatError.ERRORS.SOLIDITY.IMPORTED_PACKAGE_EXPORTS_FILE_WITH_INCORRECT_CASING,
-          {
-            importPath,
-            from: shortenPath(from.fsPath),
-          },
+      case ImportResolutionErrorType.RELATIVE_IMPORT_CLASHES_WITH_USER_REMAPPING: {
+        assertHardhatInvariant(
+          false,
+          "This should never happen: An npm root file must not be a relative import",
         );
       }
-
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.IMPORTED_FILE_WITH_INCORRECT_CASING,
-        {
-          importPath,
-          from: shortenPath(from.fsPath),
-          correctCasing: fsPathToSourceNamePath(trueCaseFsPath),
-        },
-      );
-    }
-  }
-
-  /**
-   * Parses a direct import as if it were an npm import, returning `undefined`
-   * if the format is invalid.
-   *
-   * Note: The returned subpath is not an fs path, and always use path.posix.sep
-   */
-  #parseNpmDirectImport(directImport: string):
-    | {
-        package: string;
-        subpath: string;
+      /* c8 ignore end */
+      case ImportResolutionErrorType.IMPORT_WITH_INVALID_NPM_SYNTAX:
+      case ImportResolutionErrorType.IMPORT_WITH_WINDOWS_PATH_SEPARATORS:
+      case ImportResolutionErrorType.RELATIVE_IMPORT_INTO_NODE_MODULES: {
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_NAME_WITH_INVALID_FORMAT,
+          npmModule,
+        };
       }
-    | undefined {
-    // NOTE: We assume usage of path.posix.sep in the direct import
-    const directImportPattern =
-      /^(?<package>(?:@[a-z0-9-~._]+\/)?[a-z0-9-~][a-z0-9-~._]*)\/(?<path>.*)$/;
-
-    const match = directImportPattern.exec(directImport);
-
-    if (match === null) {
-      return undefined;
-    }
-
-    assertHardhatInvariant(
-      match.groups !== undefined,
-      "Groups should be defined because they are part of the pattern",
-    );
-
-    return { package: match.groups.package, subpath: match.groups.path };
-  }
-}
-
-async function validateAndResolveUserRemapping(
-  projectRoot: string,
-  remappingString: string,
-): Promise<ResolvedUserRemapping> {
-  const remapping = parseRemappingString(remappingString);
-
-  if (remapping === undefined) {
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.REMAPPING_WITH_INVALID_SYNTAX,
-      {
-        remapping: remappingString,
-      },
-    );
-  }
-
-  if (remapping.context.startsWith("npm/")) {
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.USER_REMAPPING_WITH_NPM_CONTEXT,
-      { remapping: remappingString },
-    );
-  }
-
-  if (!remapping.target.startsWith("npm/")) {
-    return { ...remapping, rawFormat: remappingString };
-  }
-
-  const parsed = parseNpmRemappingTarget(remapping.target);
-
-  if (parsed === undefined) {
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.REMAPPING_WITH_INVALID_SYNTAX,
-      { remapping: remappingString },
-    );
-  }
-
-  const { packageName, packageVersion } = parsed;
-
-  const dependencyPackageJsonPath = await findDependencyPackageJson(
-    projectRoot,
-    packageName,
-  );
-
-  if (dependencyPackageJsonPath === undefined) {
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.REMAPPING_TO_UNINSTALLED_PACKAGE,
-      { remapping: remappingString, package: packageName },
-    );
-  }
-
-  if (isPackageJsonFromMonorepo(dependencyPackageJsonPath, projectRoot)) {
-    if (packageVersion !== "local") {
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.REMAPPING_NPM_PACKAGE_AS_MONOREPO,
-        {
-          remapping: remappingString,
-          pacakge: packageName,
-          version: packageVersion,
-        },
-      );
-    }
-  }
+      case ImportResolutionErrorType.IMPORT_DOESNT_EXIST: {
+        assertHardhatInvariant(
+          error.npmPackage !== undefined,
+          "We should have a npm package if the import doesn't exist, as we know are doing an npm import",
+        );
 
-  if (isPackageJsonFromProject(dependencyPackageJsonPath, projectRoot)) {
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.REMAPPING_HARDHAT_PROJECT_AS_MONOREPO_PACKAGE,
-      { remapping: remappingString, package: packageName },
-    );
-  }
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_DOESNT_EXIST_WITHIN_ITS_PACKAGE,
+          npmModule,
+          userRemapping: error.userRemapping,
+          npmPackage: error.npmPackage,
+          resolvedFileType: error.resolvedFileType,
+          subpath: error.subpath,
+          packageExportsResolvedSubpath: error.packageExportsResolvedSubpath,
+        };
+      }
+      case ImportResolutionErrorType.IMPORT_INVALID_CASING: {
+        assertHardhatInvariant(
+          error.npmPackage !== undefined,
+          "We should have a npm package if the import doesn't exist, as we know are doing an npm import",
+        );
 
-  const npmPackage: ResolvedNpmPackage = {
-    name: packageName,
-    version: packageVersion,
-    rootFsPath: path.dirname(dependencyPackageJsonPath),
-    rootSourceName: npmPackageToRootSourceName(packageName, packageVersion),
-  };
-
-  if (isPackageJsonFromNpmPackage(dependencyPackageJsonPath)) {
-    const dependencyPackageJson = await readJsonFile<{
-      version: string;
-      exports: resolve.Exports;
-    }>(dependencyPackageJsonPath);
-
-    if (dependencyPackageJson.version !== packageVersion) {
-      throw new HardhatError(
-        HardhatError.ERRORS.SOLIDITY.REMAPPING_INCORRECT_VERSION,
-        {
-          remapping: remappingString,
-          package: packageName,
-          expectedVersion: packageVersion,
-          actualVersion: dependencyPackageJson.version,
-        },
-      );
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_WITH_INCORRRECT_CASING,
+          npmModule,
+          correctCasing: error.correctCasing,
+          userRemapping: error.userRemapping,
+          npmPackage: error.npmPackage,
+          resolvedFileType: error.resolvedFileType,
+          subpath: error.subpath,
+          packageExportsResolvedSubpath: error.packageExportsResolvedSubpath,
+        };
+      }
+      case ImportResolutionErrorType.IMPORT_OF_UNINSTALLED_PACKAGE: {
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_OF_UNINSTALLED_PACKAGE,
+          npmModule,
+          installationName: error.installationName,
+        };
+      }
+      case ImportResolutionErrorType.IMPORT_WITH_REMAPPING_ERRORS: {
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_RESOLUTION_WITH_REMAPPING_ERRORS,
+          npmModule,
+          remappingErrors: error.remappingErrors,
+        };
+      }
+      case ImportResolutionErrorType.IMPORT_OF_NON_EXPORTED_NPM_FILE: {
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_NON_EXPORTED_FILE,
+          npmModule,
+          userRemapping: error.userRemapping,
+          npmPackage: error.npmPackage,
+          resolvedFileType: error.resolvedFileType,
+          subpath: error.subpath,
+          packageExportsResolvedSubpath: error.packageExportsResolvedSubpath,
+        };
+      }
+      case ImportResolutionErrorType.DIRECT_IMPORT_TO_LOCAL_FILE: {
+        return {
+          type: RootResolutionErrorType.NPM_ROOT_FILE_RESOLVES_TO_PROJECT_FILE,
+          npmModule,
+          userRemapping: undefined,
+          resolvedFileFsPath: path.join(
+            this.#hhProjectPackage.rootFsPath,
+            npmModule,
+          ),
+        };
+      }
     }
-
-    npmPackage.exports = dependencyPackageJson.exports;
   }
 
-  return {
-    ...remapping,
-    targetNpmPackage: npmPackage,
-    rawFormat: remappingString,
-  };
-}
-
-function parseNpmRemappingTarget(remappingTarget: string):
-  | {
-      packageName: string;
-      packageVersion: string;
-    }
-  | undefined {
-  const npmTargetPattern =
-    /^npm\/(?<package>(?:@[a-z0-9-~._]+\/)?[a-z0-9-~][a-z0-9-~._]*)@(?<version>local|\d+\.\d+\.\d+)\//;
-
-  const match = npmTargetPattern.exec(remappingTarget);
-
-  if (match === null) {
-    return undefined;
-  }
-
-  assertHardhatInvariant(
-    match.groups !== undefined,
-    "Groups should be defined because they are part of the pattern",
-  );
-
-  return {
-    packageName: match.groups.package,
-    packageVersion: match.groups.version,
-  };
-}
-
-function npmPackageToRootSourceName(name: string, version: string): string {
-  return `npm/${name}@${version}/`;
-}
-
-function isPackageJsonFromMonorepo(
-  packageJsonFsPath: string,
-  projectRoot: string,
-): boolean {
-  return (
-    !packageJsonFsPath.includes("node_modules") &&
-    !packageJsonFsPath.startsWith(projectRoot)
-  );
-}
-
-function isPackageJsonFromProject(
-  packageJsonFsPath: string,
-  projectRoot: string,
-): boolean {
-  return (
-    !packageJsonFsPath.includes("node_modules") &&
-    packageJsonFsPath.startsWith(projectRoot)
-  );
-}
-
-function isPackageJsonFromNpmPackage(packageJsonFsPath: string): boolean {
-  return packageJsonFsPath.includes("node_modules");
-}
-
-/**
- * Transforms an fs path into a sourceName or import path, by normalizing their
- * path separators to /.
- *
- * Note that source
- *
- * Note: This function is exported for testing purposes, but it's not meant to
- * be used outside of the resolver.
- */
-export function fsPathToSourceNamePath(fsPath: string): string {
-  if (path.sep === "/") {
-    return fsPath;
-  }
-
-  return fsPath.replace(/\\/g, "/");
-}
-
-/**
- * Transforms a sourceName or import path into an fs path, by normalizing their
- * path separators to /.
- *
- * Note: This function is exported for testing purposes, but it's not meant to
- * be used outside of the resolver.
- */
-export function sourceNamePathToFsPath(sourceNamePath: string): string {
-  if (path.sep === "/") {
-    return sourceNamePath;
-  }
-
-  return sourceNamePath.replace(/\//g, "\\");
-}
-
-/**
- * The equivalent of path.join but for sourceName or import paths, not fs paths.
- */
-function sourceNamePathJoin(...parts: string[]): string {
-  return fsPathToSourceNamePath(path.join(...parts));
-}
-
-/**
- * Reads and analyzes the file at the given absolute path.
- */
-async function readFileContent(absolutePath: string): Promise<FileContent> {
-  const text = await readUtf8File(absolutePath);
-  const { imports, versionPragmas } = analyze(text);
-
-  return {
-    text,
-    importPaths: imports,
-    versionPragmas,
-  };
-}
-
-/**
- * Resolves a subpath for a given package, when it uses package#exports
- * @param npmPackage
- * @param subpath
- * @returns
- */
-function resolveSubpath(
-  npmPackage: ResolvedNpmPackage,
-  subpath: string,
-): string {
-  if (npmPackage.exports === undefined) {
-    return subpath;
-  }
-  try {
-    // As we are resolving Solidity files, the conditions don't really apply,
-    // and Solidity package authors don't use them either.
-    //
-    // We use `resolve.exports` with the appropiate options so that it only
-    // takes the `"default"` condition into account.
-    const resolveOutput = resolve.exports(npmPackage, subpath, {
-      browser: false,
-      conditions: [],
-      require: false,
-      unsafe: true,
-    });
-
-    assertHardhatInvariant(
-      resolveOutput !== undefined,
-      "resolve.exports should always return a result when package.exports exist",
-    );
-
-    const resolvedSubpath = resolveOutput[0].slice(2); // skip the leading './'
-
-    return resolvedSubpath.replace(/\/|\\/g, path.sep); // use fs path separator
-  } catch (error) {
-    ensureError(error, Error);
-
-    throw new HardhatError(
-      HardhatError.ERRORS.SOLIDITY.RESOLVE_NOT_EXPORTED_NPM_FILE,
-      { module: `${npmPackage.name}/${subpath}` },
-      error,
-    );
+  /**
+   * Reads and analyzes the file at the given absolute path.
+   */
+  async #readFileContent({
+    absolutePath,
+  }: {
+    absolutePath: string;
+  }): Promise<FileContent> {
+    const text = await this.#readUtf8File(absolutePath);
+    const { imports, versionPragmas } = analyze(text);
+
+    return {
+      text,
+      importPaths: imports,
+      versionPragmas,
+    };
   }
 }