feat: add limited support for devEngines

Author: aduh95

sources/specUtils.ts

@@ -1,13 +1,16 @@
-import {UsageError}                            from 'clipanion';
-import fs                                      from 'fs';
-import path                                    from 'path';
-import semverValid                             from 'semver/functions/valid';
-
-import {PreparedPackageManagerInfo}            from './Engine';
-import * as debugUtils                         from './debugUtils';
-import {NodeError}                             from './nodeUtils';
-import * as nodeUtils                          from './nodeUtils';
-import {Descriptor, isSupportedPackageManager} from './types';
+import {UsageError}                      from 'clipanion';
+import fs                                from 'fs';
+import path                              from 'path';
+import semverSatisfies                   from 'semver/functions/satisfies';
+import semverValid                       from 'semver/functions/valid';
+import {parseEnv}                        from 'util';
+
+import type {PreparedPackageManagerInfo} from './Engine';
+import * as debugUtils                   from './debugUtils';
+import type {NodeError}                  from './nodeUtils';
+import * as nodeUtils                    from './nodeUtils';
+import {isSupportedPackageManager}       from './types';
+import type {LocalEnvFile, Descriptor}   from './types';
 
 const nodeModulesRegExp = /[\\/]node_modules[\\/](@[^\\/]*[\\/])?([^@\\/][^\\/]*)$/;
 
@@ -52,6 +55,43 @@ export function parseSpec(raw: unknown, source: string, {enforceExactVersion = t
   };
 }
 
+type CorepackPackageJSON = {
+  packageManager?: string;
+  devEngines?: { packageManager?: DevEngineDependency };
+};
+
+interface DevEngineDependency {
+  name: string;
+  version: string;
+}
+function parsePackageJSON(packageJSONContent: CorepackPackageJSON, localEnv?: LocalEnvFile) {
+  if (packageJSONContent.devEngines?.packageManager) {
+    const {packageManager} = packageJSONContent.devEngines;
+
+    if (Array.isArray(packageManager))
+      throw new UsageError(`Providing several package managers is currently not supported`);
+
+    let {version} = packageManager;
+    if (!version)
+      throw new UsageError(`Providing no version nor ranger for package manager is currently not supported`);
+
+    const localEnvKey = `COREPACK_DEV_ENGINES_${packageManager.name.toUpperCase()}`;
+    const localEnvVersion = localEnv?.[localEnvKey];
+    if (localEnvVersion) {
+      if (!semverSatisfies(localEnvVersion, version))
+        throw new UsageError(`Local env key ${localEnvKey} defines a value of ${localEnvVersion} which does not match the version defined in package.json devEngines.packageManager of ${version}`);
+
+      debugUtils.log(`Using ${localEnvVersion} defined in .corepack.env`);
+      version = localEnvVersion;
+    }
+
+
+    return `${packageManager.name}@${version}`;
+  }
+
+  return packageJSONContent.packageManager;
+}
+
 export async function setLocalPackageManager(cwd: string, info: PreparedPackageManagerInfo) {
   const lookup = await loadSpec(cwd);
 
@@ -84,6 +124,7 @@ export async function loadSpec(initialCwd: string): Promise<LoadSpecResult> {
   let selection: {
     data: any;
     manifestPath: string;
+    localEnv?: LocalEnvFile;
   } | null = null;
 
   while (nextCwd !== currCwd && (!selection || !selection.data.packageManager)) {
@@ -111,13 +152,24 @@ export async function loadSpec(initialCwd: string): Promise<LoadSpecResult> {
     if (typeof data !== `object` || data === null)
       throw new UsageError(`Invalid package.json in ${path.relative(initialCwd, manifestPath)}`);
 
-    selection = {data, manifestPath};
+    let localEnv: LocalEnvFile | undefined;
+    const envFilePath = path.join(currCwd, `.corepack.env`);
+    debugUtils.log(`Checking ${envFilePath}`);
+    try {
+      localEnv = parseEnv(await fs.promises.readFile(envFilePath, `utf8`)) as LocalEnvFile;
+    } catch (err) {
+      if ((err as NodeError)?.code !== `ENOENT`) {
+        throw err;
+      }
+    }
+
+    selection = {data, manifestPath, localEnv};
   }
 
   if (selection === null)
     return {type: `NoProject`, target: path.join(initialCwd, `package.json`)};
 
-  const rawPmSpec = selection.data.packageManager;
+  const rawPmSpec = parsePackageJSON(selection.data, selection.localEnv);
   if (typeof rawPmSpec === `undefined`)
     return {type: `NoSpec`, target: selection.manifestPath};
 

sources/types.ts

@@ -145,3 +145,5 @@ export interface Locator {
      */
   reference: string;
 }
+
+export type LocalEnvFile = Record<"COREPACK_ENABLE_AUTO_PIN" | "COREPACK_ENABLE_STRICT" | "COREPACK_INTEGRITY_KEYS" | "COREPACK_PACKAGE_MANAGER", string>;

tests/main.test.ts

@@ -150,6 +150,16 @@ for (const [name, version, expectedVersion = version.split(`+`, 1)[0]] of tested
         stderr: ``,
         stdout: `${expectedVersion}\n`,
       });
+
+      await xfs.writeJsonPromise(ppath.join(cwd, `package.json` as Filename), {
+        devEngines: {packageManager: {name, version}},
+      });
+
+      await expect(runCli(cwd, [name, `--version`])).resolves.toMatchObject({
+        exitCode: 0,
+        stderr: ``,
+        stdout: `${expectedVersion}\n`,
+      });
     });
   });
 }
@@ -231,6 +241,72 @@ it(`should ignore the packageManager field when found within a node_modules vend
   });
 });
 
+it(`should prefer devEngines to packageManager`, async () => {
+  await xfs.mktempPromise(async cwd => {
+    await xfs.writeJsonPromise(ppath.join(cwd, `package.json` as PortablePath), {
+      packageManager: `yarn@1.22.4`,
+      devEngines: {
+        packageManager: {
+          name: `yarn`,
+          version: `3.0.0-rc.2+sha224.f83f6d1cbfac10ba6b516a62ccd2a72ccd857aa6c514d1cd7185ec60`,
+        },
+      },
+    });
+
+    await expect(runCli(cwd, [`yarn`, `--version`])).resolves.toMatchObject({
+      exitCode: 0,
+      stderr: ``,
+      stdout: `3.0.0-rc.2\n`,
+    });
+  });
+});
+
+it(`should accept range in devEngines only if a specific version is provided in .corepack.env`, async () => {
+  await xfs.mktempPromise(async cwd => {
+    await xfs.writeJsonPromise(ppath.join(cwd, `package.json` as PortablePath), {
+      devEngines: {
+        packageManager: {
+          name: `pnpm`,
+          version: `6.x`,
+        },
+      },
+    });
+    await expect(runCli(cwd, [`pnpm`, `--version`])).resolves.toMatchObject({
+      exitCode: 1,
+      stderr: `Invalid package manager specification in package.json (pnpm@6.x); expected a semver version\n`,
+      stdout: ``,
+    });
+
+    await xfs.writeFilePromise(ppath.join(cwd, `.corepack.env` as PortablePath),
+      `COREPACK_DEV_ENGINES_PNPM=6.6.2+sha224.eb5c0acad3b0f40ecdaa2db9aa5a73134ad256e17e22d1419a2ab073\n`);
+    await expect(runCli(cwd, [`pnpm`, `--version`])).resolves.toMatchObject({
+      exitCode: 0,
+      stderr: ``,
+      stdout: `6.6.2\n`,
+    });
+  });
+});
+
+it(`should reject if range in devEngines does not match version provided in .corepack.env`, async () => {
+  await xfs.mktempPromise(async cwd => {
+    await xfs.writeJsonPromise(ppath.join(cwd, `package.json` as PortablePath), {
+      devEngines: {
+        packageManager: {
+          name: `pnpm`,
+          version: `10.x`,
+        },
+      },
+    });
+    await xfs.writeFilePromise(ppath.join(cwd, `.corepack.env` as PortablePath),
+      `COREPACK_DEV_ENGINES_PNPM=6.6.2+sha224.eb5c0acad3b0f40ecdaa2db9aa5a73134ad256e17e22d1419a2ab073\n`);
+    await expect(runCli(cwd, [`pnpm`, `--version`])).resolves.toMatchObject({
+      exitCode: 1,
+      stderr: `Local env key COREPACK_DEV_ENGINES_PNPM defines a value of 6.6.2+sha224.eb5c0acad3b0f40ecdaa2db9aa5a73134ad256e17e22d1419a2ab073 which does not match the version defined in package.json devEngines.packageManager of 10.x\n`,
+      stdout: ``,
+    });
+  });
+});
+
 it(`should use the closest matching packageManager field`, async () => {
   await xfs.mktempPromise(async cwd => {
     await xfs.mkdirPromise(ppath.join(cwd, `foo` as PortablePath), {recursive: true});