@gfdelarue/testkit 0.3.0

package/dist/engines/managed-module-resolution.js

@@ -0,0 +1,697 @@
+import{inspectManagedNodeModuleResolutionPolicy as o}from"./managed-module-resolution-policy.js";export function createManagedNodeModuleResolution(e){const t=o(e),r={...t.direct};for(const[a,i]of Object.entries(t.packageExports)){const n=i.import??i.default??i.require;n!==null&&(r[a]=n)}return Object.freeze({aliases:Object.freeze(r),bootstrapSource:s(t),dependencyRoots:t.managedImporterRoots})}export function managedNodeModuleResolutionBootstrapSource(e){return createManagedNodeModuleResolution(e).bootstrapSource}function s(e){return`
+const fs = require("node:fs");
+const path = require("node:path");
+const { registerHooks } = require("node:module");
+const { fileURLToPath, pathToFileURL } = require("node:url");
+
+const POLICY = Object.freeze(${JSON.stringify(e)});
+const CONSUMER_ROOTS = Object.freeze(
+  POLICY.consumerRoots.map((root) => verifiedDirectory(root, "consumer root")),
+);
+const DIRECT = new Map(
+  Object.entries(POLICY.direct).map(([specifier, target]) => [
+    specifier,
+    verifiedFile(target, "direct module " + specifier),
+  ]),
+);
+const PACKAGE_ROOTS = verifyPackageRoots(POLICY.packageRoots, "native");
+const DIRECT_BRIDGE_ROOTS = Object.freeze(
+  POLICY.directBridgeRoots.map((root) =>
+    verifiedDirectory(root, "direct bridge root"),
+  ),
+);
+const PACKAGE_EXPORTS = new Map(
+  Object.entries(POLICY.packageExports).map(([specifier, targets]) => [
+    specifier,
+    Object.freeze({
+      default: verifiedOptionalFile(targets.default, specifier),
+      import: verifiedOptionalFile(targets.import, specifier),
+      require: verifiedOptionalFile(targets.require, specifier),
+    }),
+  ]),
+);
+const DEPENDENCY_ROOTS = Object.freeze(
+  POLICY.dependencyRoots.map((root) =>
+    verifiedDirectory(root, "managed dependency root"),
+  ),
+);
+const TRUSTED_IMPORTER_FILES = Object.freeze(POLICY.trustedImporterFiles);
+const TRUSTED_INTERNAL_ENTRYPOINTS = Object.freeze(
+  POLICY.trustedInternalEntrypoints.map((file) =>
+    verifiedFile(file, "trusted internal entrypoint"),
+  ),
+);
+const TRUSTED_INTERNAL_ROOTS = Object.freeze(
+  POLICY.trustedInternalRoots.map((root) =>
+    verifiedDirectory(root, "trusted internal root"),
+  ),
+);
+const VERIFIED_PROCESS_ENTRYPOINTS = Object.freeze(
+  POLICY.verifiedProcessEntrypoints.map((file) =>
+    verifiedFile(file, "process entrypoint"),
+  ),
+);
+const VERIFIED_PARENTLESS_PACKAGE_FILES = Object.freeze(
+  POLICY.verifiedParentlessPackageFiles.map((file) =>
+    verifiedFile(file, "parentless package file"),
+  ),
+);
+const STATE = Symbol.for(POLICY.stateSymbol);
+const identity = JSON.stringify(POLICY);
+const existing = globalThis[STATE];
+
+if (existing !== undefined) {
+  if (existing.identity !== identity)
+    throw new Error("Managed " + POLICY.engineLabel + " process attempted to install conflicting module-resolution hooks");
+} else {
+  // A pass-through load hook changes how Node composes this resolver with
+  // tools that register asynchronous loaders. Resolution is the complete
+  // policy here, so do not install a load hook that has no policy to enforce.
+  const hooks = registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const conditions = normalizedConditions(context.conditions);
+      const classified = classifyResolvedSpecifier(specifier, context.parentURL);
+      requireAllowedResolvedSpecifier(classified);
+      const logicalSpecifier = classified.logicalSpecifier ?? specifier;
+      const managedResolution = resolveManagedSpecifier(
+        logicalSpecifier,
+        conditions,
+        context.parentURL,
+      );
+      if (managedResolution !== null) return managedResolution;
+
+      const packageImportTarget = exactPackageImportTarget(
+        logicalSpecifier,
+        conditions,
+        context.parentURL,
+      );
+      if (packageImportTarget !== null) {
+        const managedPackageImportResolution = resolveManagedSpecifier(
+          packageImportTarget,
+          conditions,
+          context.parentURL,
+        );
+        if (managedPackageImportResolution !== null)
+          return managedPackageImportResolution;
+      }
+
+      const forbiddenPackage = forbiddenConsumerPackage(logicalSpecifier);
+      if (
+        forbiddenPackage !== null &&
+        !isManagedDependencyImporter(context.parentURL)
+      ) {
+        throw new Error(
+          POLICY.engineLabel +
+            " consumers may not import forbidden managed package " +
+            forbiddenPackage,
+        );
+      }
+      const resolved = nextResolve(specifier, context);
+      const resolvedClassification = classifyResolvedSpecifier(
+        resolved.url,
+        context.parentURL,
+      );
+      requireAllowedResolvedSpecifier(resolvedClassification);
+      if (resolvedClassification.logicalSpecifier !== null) {
+        const redirected = resolveManagedSpecifier(
+          resolvedClassification.logicalSpecifier,
+          conditions,
+          context.parentURL,
+        );
+        if (redirected !== null) return redirected;
+      }
+      return resolved;
+    },
+  });
+  Object.defineProperty(globalThis, STATE, {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze({ hooks, identity }),
+    writable: false,
+  });
+}
+
+function resolveManagedSpecifier(specifier, conditions, parentURL) {
+  const direct = DIRECT.get(specifier);
+  if (direct !== undefined)
+    return { shortCircuit: true, url: pathToFileURL(direct).href };
+
+  const packageName = matchingPackageName(specifier, PACKAGE_ROOTS);
+  if (packageName !== null) {
+    const targets = PACKAGE_EXPORTS.get(specifier);
+    if (targets === undefined)
+      throw new Error(
+        "Managed " +
+          POLICY.engineLabel +
+          " package does not support runtime subpath " +
+          specifier,
+      );
+    const target = selectedRuntimeExport(targets, conditions);
+    if (target === null)
+      throw new Error(
+        "Managed " +
+          POLICY.engineLabel +
+          " package export has no compatible runtime condition " +
+          specifier,
+      );
+    return { shortCircuit: true, url: pathToFileURL(target).href };
+  }
+
+  if (reservedPackageName(specifier) !== null)
+    throw new Error(
+      "Managed " +
+        POLICY.engineLabel +
+        " direct package does not support runtime subpath " +
+        specifier,
+    );
+  return null;
+}
+
+function exactPackageImportTarget(specifier, conditions, parentURL) {
+  if (
+    !specifier.startsWith("#") ||
+    specifier === "#" ||
+    specifier.startsWith("#/") ||
+    typeof parentURL !== "string" ||
+    !parentURL.startsWith("file:")
+  )
+    return null;
+  const manifest = nearestPackageManifest(fileURLToPath(parentURL));
+  if (manifest === null || !isObject(manifest.imports)) return null;
+  return selectedPackageImportTarget(manifest.imports[specifier], conditions);
+}
+
+function nearestPackageManifest(importerFile) {
+  let directory = path.dirname(importerFile);
+  while (true) {
+    const manifestFile = path.join(directory, "package.json");
+    if (fs.existsSync(manifestFile)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+        if (isObject(manifest)) return manifest;
+      } catch {}
+      return null;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function selectedPackageImportTarget(declaration, conditions) {
+  if (typeof declaration === "string")
+    return isBarePackageSpecifier(declaration) ? declaration : null;
+  if (Array.isArray(declaration)) {
+    for (const candidate of declaration) {
+      const selected = selectedPackageImportTarget(candidate, conditions);
+      if (selected !== null) return selected;
+    }
+    return null;
+  }
+  if (!isObject(declaration)) return null;
+  for (const [condition, candidate] of Object.entries(declaration)) {
+    if (condition !== "default" && !conditions.has(condition)) continue;
+    const selected = selectedPackageImportTarget(candidate, conditions);
+    if (selected !== null) return selected;
+  }
+  return null;
+}
+
+function isBarePackageSpecifier(specifier) {
+  return (
+    !specifier.startsWith(".") &&
+    !specifier.startsWith("/") &&
+    !specifier.startsWith("#") &&
+    !specifier.startsWith("file:") &&
+    !path.isAbsolute(specifier)
+  );
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+
+function requireAllowedResolvedSpecifier(classified) {
+  if (classified.blocked === "forbidden")
+    throw new Error(
+      POLICY.engineLabel +
+        " consumers may not import forbidden managed package " +
+        classified.packageName +
+        resolvedImportContext(classified),
+    );
+  if (classified.blocked === "unsupported")
+    throw new Error(
+      POLICY.engineLabel +
+        " consumers may not import managed package file outside exact public exports: " +
+        classified.packageName +
+        resolvedImportContext(classified),
+    );
+}
+
+function resolvedImportContext(classified) {
+  return (
+    " (resolved " +
+    classified.file +
+    " from " +
+    (classified.parentURL ?? "<entry>") +
+    ")"
+  );
+}
+
+function matchingPackageName(specifier, roots) {
+  for (const packageName of Object.keys(roots)) {
+    if (specifier === packageName || specifier.startsWith(packageName + "/"))
+      return packageName;
+  }
+  return null;
+}
+
+function reservedPackageName(specifier) {
+  for (const packageName of POLICY.reservedPackageNames) {
+    if (specifier === packageName || specifier.startsWith(packageName + "/"))
+      return packageName;
+  }
+  return null;
+}
+
+function forbiddenConsumerPackage(specifier) {
+  for (const prefix of POLICY.forbiddenConsumerPackagePrefixes) {
+    if (!specifier.startsWith(prefix)) continue;
+    const segment = specifier.slice(prefix.length).split("/", 1)[0];
+    if (segment.length > 0) return prefix + segment;
+  }
+  return null;
+}
+
+function classifyResolvedSpecifier(specifier, parentURL) {
+  if (typeof specifier !== "string") return unclassified();
+  const file = specifier.startsWith("file:")
+    ? fileURLToPath(specifier)
+    : path.isAbsolute(specifier)
+      ? specifier
+      : null;
+  if (file === null) return unclassified();
+  for (const candidate of resolvedFileCandidates(file)) {
+    const directSpecifier = exactDirectSpecifier(candidate);
+    if (directSpecifier !== null) {
+      return classifiedResult(
+        null,
+        candidate,
+        directSpecifier,
+        "direct bridge",
+        parentURL,
+      );
+    }
+    const bridgeClassification = classifyDirectBridge(candidate, parentURL);
+    if (bridgeClassification !== null) return bridgeClassification;
+    const internalClassification = classifyTrustedInternalRoot(
+      candidate,
+      parentURL,
+    );
+    if (internalClassification !== null) return internalClassification;
+    const classified = classifyPackageBoundaries(candidate, parentURL);
+    if (classified !== null) return classified;
+  }
+  return unclassified();
+}
+
+function exactDirectSpecifier(file) {
+  for (const [specifier, target] of DIRECT) {
+    if (sameFile(file, target)) return specifier;
+  }
+  return null;
+}
+
+function classifyDirectBridge(file, parentURL) {
+  if (!DIRECT_BRIDGE_ROOTS.some((root) => isPathWithin(root, file)))
+    return null;
+  const trustedEntrypoint =
+    isTrustedImporter(parentURL) && isTrustedInternalEntrypoint(file);
+  if (trustedEntrypoint || isManagedDependencyImporter(parentURL))
+    return classifiedResult(
+      null,
+      file,
+      null,
+      "direct bridge",
+      parentURL,
+    );
+  return classifiedResult(
+    "unsupported",
+    file,
+    null,
+    "direct bridge",
+    parentURL,
+  );
+}
+
+function classifyTrustedInternalRoot(file, parentURL) {
+  const root = TRUSTED_INTERNAL_ROOTS.find((candidate) =>
+    isPathWithin(candidate, file),
+  );
+  if (root === undefined) return null;
+  const trustedEntrypoint =
+    isTrustedImporter(parentURL) && isTrustedInternalEntrypoint(file);
+  return classifiedResult(
+    trustedEntrypoint || isManagedDependencyImporter(parentURL)
+      ? null
+      : "unsupported",
+    file,
+    null,
+    "root internal",
+    parentURL,
+  );
+}
+
+function unclassified() {
+  return {
+    blocked: null,
+    file: null,
+    logicalSpecifier: null,
+    packageName: null,
+    parentURL: null,
+  };
+}
+
+function resolvedFileCandidates(file) {
+  const resolved = path.resolve(file);
+  const candidates = [];
+  try {
+    const canonical = fs.realpathSync(file);
+    candidates.push(canonical);
+  } catch {}
+  if (!candidates.includes(resolved)) candidates.push(resolved);
+  return candidates;
+}
+
+function classifyPackageBoundaries(file, parentURL) {
+  const scanBoundary = containingScanBoundary(file);
+  let directory = path.dirname(file);
+  while (true) {
+    if (scanBoundary !== null && canonicalPath(directory) === scanBoundary)
+      return null;
+    const manifestFile = path.join(directory, "package.json");
+    if (fs.existsSync(manifestFile)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+      const packageName =
+        typeof manifest.name === "string" ? manifest.name : null;
+      if (packageName !== null && Object.hasOwn(PACKAGE_ROOTS, packageName))
+        return classifyPublicPackage(
+          file,
+          directory,
+          manifest.exports,
+          packageName,
+          PACKAGE_ROOTS[packageName],
+          parentURL,
+        );
+      if (
+        packageName !== null &&
+        POLICY.reservedPackageNames.includes(packageName)
+      ) {
+        const subpath = exactExportedSubpathForFile(
+          manifest.exports,
+          directory,
+          file,
+        );
+        return subpath === null
+          ? classifiedResult(
+              "unsupported",
+              file,
+              null,
+              packageName,
+              parentURL,
+            )
+          : classifiedResult(
+              null,
+              file,
+              packageName + (subpath === "." ? "" : subpath.slice(1)),
+              packageName,
+              parentURL,
+            );
+      }
+      const forbiddenPackage =
+        packageName === null ? null : forbiddenConsumerPackage(packageName);
+      if (forbiddenPackage !== null) {
+        const trustedManagedImport =
+          isManagedDependencyFile(file) &&
+          isManagedDependencyImporter(parentURL);
+        return classifiedResult(
+          trustedManagedImport ? null : "forbidden",
+          file,
+          null,
+          forbiddenPackage,
+          parentURL,
+        );
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function containingScanBoundary(file) {
+  const candidates = [...CONSUMER_ROOTS, ...DEPENDENCY_ROOTS].filter((root) =>
+    isPathWithin(root, file),
+  );
+  candidates.sort((left, right) => right.length - left.length);
+  return candidates[0] ?? null;
+}
+
+function classifyPublicPackage(
+  file,
+  candidateRoot,
+  exportsDeclaration,
+  packageName,
+  verifiedRoot,
+  parentURL,
+) {
+  const verifiedCandidate = canonicalPath(candidateRoot) === verifiedRoot;
+  if (
+    verifiedCandidate &&
+    (isManagedDependencyImporter(parentURL) ||
+      isVerifiedManagedProcessEntrypoint(file, parentURL) ||
+      isVerifiedParentlessPreload(file, parentURL))
+  ) {
+    return classifiedResult(null, file, null, packageName, parentURL);
+  }
+  const subpath = exactExportedSubpathForFile(
+    exportsDeclaration,
+    candidateRoot,
+    file,
+  );
+  if (subpath === null)
+    return classifiedResult(
+      "unsupported",
+      file,
+      null,
+      packageName,
+      parentURL,
+    );
+  return classifiedResult(
+    null,
+    file,
+    packageName + (subpath === "." ? "" : subpath.slice(1)),
+    packageName,
+    parentURL,
+  );
+}
+
+function classifiedResult(
+  blocked,
+  file,
+  logicalSpecifier,
+  packageName,
+  parentURL,
+) {
+  return { blocked, file, logicalSpecifier, packageName, parentURL };
+}
+
+function isVerifiedManagedProcessEntrypoint(file, parentURL) {
+  if (parentURL !== undefined || !isManagedDependencyFile(file)) return false;
+  const processEntrypoint = process.argv[1];
+  if (typeof processEntrypoint !== "string") return false;
+  const canonicalEntrypoint = canonicalPath(processEntrypoint);
+  return (
+    (VERIFIED_PROCESS_ENTRYPOINTS.includes(canonicalEntrypoint) ||
+      VERIFIED_PARENTLESS_PACKAGE_FILES.includes(canonicalEntrypoint)) &&
+    canonicalPath(file) === canonicalEntrypoint
+  );
+}
+
+function isVerifiedParentlessPreload(file, parentURL) {
+  if (parentURL !== undefined) return false;
+  const candidate = canonicalPath(file);
+  if (!VERIFIED_PARENTLESS_PACKAGE_FILES.includes(candidate)) return false;
+  for (let index = 0; index < process.execArgv.length; index += 1) {
+    const argument = process.execArgv[index];
+    if (argument === "--require" || argument === "-r") {
+      if (sameFileOption(process.execArgv[index + 1], candidate)) return true;
+      index += 1;
+      continue;
+    }
+    if (
+      argument.startsWith("--require=") &&
+      sameFileOption(argument.slice("--require=".length), candidate)
+    )
+      return true;
+  }
+  return false;
+}
+
+function sameFileOption(value, candidate) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  try {
+    const file = value.startsWith("file:") ? fileURLToPath(value) : value;
+    return path.isAbsolute(file) && sameFile(file, candidate);
+  } catch {
+    return false;
+  }
+}
+
+function isTrustedImporter(parentURL) {
+  if (typeof parentURL !== "string" || !parentURL.startsWith("file:"))
+    return false;
+  const importer = canonicalPath(fileURLToPath(parentURL));
+  return TRUSTED_IMPORTER_FILES.some(
+    (trusted) => canonicalPath(trusted) === importer,
+  );
+}
+
+function isTrustedInternalEntrypoint(file) {
+  const candidate = canonicalPath(file);
+  return TRUSTED_INTERNAL_ENTRYPOINTS.includes(candidate);
+}
+
+function isManagedDependencyImporter(parentURL) {
+  return typeof parentURL === "string" && parentURL.startsWith("file:")
+    ? isManagedDependencyFile(fileURLToPath(parentURL))
+    : false;
+}
+
+function isManagedDependencyFile(file) {
+  return resolvedFileCandidates(file).some((candidate) =>
+    [...POLICY.managedImporterRoots, ...DIRECT_BRIDGE_ROOTS, ...TRUSTED_INTERNAL_ROOTS].some(
+      (root) => isPathWithin(root, candidate),
+    ),
+  );
+}
+
+function exactExportedSubpathForFile(exportsDeclaration, packageRoot, file) {
+  if (exportsDeclaration === null || typeof exportsDeclaration !== "object")
+    return null;
+  for (const [subpath, declaration] of Object.entries(exportsDeclaration)) {
+    if (
+      (subpath !== "." && !subpath.startsWith("./")) ||
+      subpath.includes("*")
+    ) {
+      continue;
+    }
+    for (const target of allExportTargets(declaration)) {
+      if (
+        target.startsWith("./") &&
+        !target.includes("*") &&
+        sameFile(path.resolve(packageRoot, target), file)
+      ) {
+        return subpath;
+      }
+    }
+  }
+  return null;
+}
+
+function allExportTargets(declaration) {
+  if (typeof declaration === "string") return [declaration];
+  if (Array.isArray(declaration))
+    return declaration.flatMap(allExportTargets);
+  if (declaration === null || typeof declaration !== "object") return [];
+  return Object.values(declaration).flatMap(allExportTargets);
+}
+
+function selectedRuntimeExport(targets, conditions) {
+  if (conditions.has("require") && targets.require !== null)
+    return targets.require;
+  if (conditions.has("import") && targets.import !== null)
+    return targets.import;
+  return targets.default ?? targets.import ?? targets.require;
+}
+
+function normalizedConditions(conditions) {
+  if (
+    conditions === null ||
+    conditions === undefined ||
+    typeof conditions[Symbol.iterator] !== "function"
+  ) {
+    return new Set();
+  }
+  const active = new Set();
+  for (const condition of conditions) {
+    if (typeof condition === "string") active.add(condition);
+  }
+  return active;
+}
+
+function verifyPackageRoots(roots, kind) {
+  return Object.freeze(Object.fromEntries(
+    Object.entries(roots).map(([packageName, root]) => {
+      const canonical = canonicalPath(root);
+      const manifest = JSON.parse(
+        fs.readFileSync(path.join(canonical, "package.json"), "utf8"),
+      );
+      if (manifest.name !== packageName)
+        throw new Error(
+          "Managed " +
+            POLICY.engineLabel +
+            " " +
+            kind +
+            " package root identity is invalid: " +
+            packageName,
+        );
+      return [packageName, canonical];
+    }),
+  ));
+}
+
+function verifiedOptionalFile(file, label) {
+  return file === null ? null : verifiedFile(file, "package export " + label);
+}
+
+function verifiedDirectory(directory, label) {
+  const resolved = fs.realpathSync(directory);
+  if (!fs.statSync(resolved).isDirectory())
+    throw new Error(
+      "Managed " + POLICY.engineLabel + " " + label + " is not a directory",
+    );
+  return resolved;
+}
+
+function verifiedFile(file, label) {
+  const resolved = fs.realpathSync(file);
+  if (!fs.statSync(resolved).isFile())
+    throw new Error(
+      "Managed " + POLICY.engineLabel + " " + label + " is not a regular file",
+    );
+  return resolved;
+}
+
+function canonicalPath(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return path.resolve(file);
+  }
+}
+
+function sameFile(left, right) {
+  return canonicalPath(left) === canonicalPath(right);
+}
+
+function isPathWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(".." + path.sep) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  );
+}
+`}