Add skuba migrate command to upgrade projects to Node.js 20

.changeset/real-oranges-rescue.md

@@ -0,0 +1,22 @@
+---
+'skuba': minor
+---
+
+format: Automatically upgrade projects to Node.js 20
+
+`skuba format` will now attempt to automatically upgrade projects to Node.js 20.
+It will look in the project root for Dockerfiles, `.nvmrc`, and Serverless files running Node.js 18 and try to
+upgrade them to Node.js 20.
+
+skuba might not be able to upgrade all projects, so please check your project for any files that skuba missed. It's
+possible that skuba will modify a file incorrectly, in which case please
+[open an issue](https://github.com/seek-oss/skuba/issues/new).
+
+If you cannot upgrade to Node.js 20, after upgrading skuba, you can run `skuba format` with the environment variable
+`SKIP_NODE_20_PATCH=true` to prevent skuba from upgrading to Node.js 20.
+This is required on the first run of `skuba format` after upgrading skuba only.
+
+Please read the [Node.js 20 release notes](https://nodejs.org/en/blog/announcements/v20-release-announce) alongside the
+skuba release notes.
+
+A future version of skuba will drop support for Node.js 18.

docs/cli/run.md

@@ -212,6 +212,6 @@ Execution should pause on the breakpoint until we hit `F5` or the `▶️` butto
 [`tsconfig-paths`]: https://github.com/dividab/tsconfig-paths
 [express]: https://expressjs.com/
 [fastify]: https://www.fastify.io/
-[http server]: https://nodejs.org/docs/latest-v18.x/api/http.html#class-httpserver
+[http server]: https://nodejs.org/docs/latest-v20.x/api/http.html#class-httpserver
 [koa]: https://koajs.com/
 [node.js options]: https://nodejs.org/en/docs/guides/debugging-getting-started/#command-line-options

package.json

@@ -85,6 +85,7 @@
     "eslint": "^8.11.0",
     "eslint-config-skuba": "3.1.0",
     "execa": "^5.0.0",
+    "fast-glob": "^3.3.2",
     "fdir": "^6.0.0",
     "fs-extra": "^11.0.0",
     "function-arguments": "^1.0.9",

scripts/package.ts

@@ -227,7 +227,7 @@ const main = async () => {
       'CONTRIBUTING.md',
       path.join('dist-docs', 'CONTRIBUTING.md'),
     ),
-    // `fs.promises.cp` is still experimental in Node.js 18.
+    // `fs.promises.cp` is still experimental in Node.js 20.
     copy('site', 'dist-docs'),
     copy('docs', path.join('dist-docs', 'docs')),
   ]);

src/cli/__snapshots__/format.int.test.ts.snap

@@ -16,6 +16,8 @@ Patch skipped: Upgrade Node.js Distroless Docker image to -debian12 variant - no
 
 Patch skipped: Add keepAliveTimeout to server listener - no listener file found
 
+Patch skipped: Upgrade Node.js to 20 - unable to find any Node.js <20 usage
+
 skuba update complete.
 
 Processed skuba lints in <random>s.
@@ -83,6 +85,8 @@ Patch skipped: Upgrade Node.js Distroless Docker image to -debian12 variant - no
 
 Patch skipped: Add keepAliveTimeout to server listener - no listener file found
 
+Patch skipped: Upgrade Node.js to 20 - unable to find any Node.js <20 usage
+
 skuba update complete.
 
 Processed skuba lints in <random>s.
@@ -143,6 +147,8 @@ Patch skipped: Upgrade Node.js Distroless Docker image to -debian12 variant - no
 
 Patch skipped: Add keepAliveTimeout to server listener - no listener file found
 
+Patch skipped: Upgrade Node.js to 20 - unable to find any Node.js <20 usage
+
 skuba update complete.
 
 Processed skuba lints in <random>s.
@@ -176,6 +182,8 @@ Patch skipped: Upgrade Node.js Distroless Docker image to -debian12 variant - no
 
 Patch skipped: Add keepAliveTimeout to server listener - no listener file found
 
+Patch skipped: Upgrade Node.js to 20 - unable to find any Node.js <20 usage
+
 skuba update complete.
 
 Processed skuba lints in <random>s.

src/cli/configure/upgrade/patches/7.3.1/index.ts

@@ -4,6 +4,7 @@ import { tryPatchRenovateConfig } from '../../../patchRenovateConfig';
 import { tryAddEmptyExports } from './addEmptyExports';
 import { tryPatchDockerfile } from './patchDockerfile';
 import { tryPatchServerListener } from './patchServerListener';
+import { tryUpgradeToNode20 } from './upgradeToNode20';
 
 export const patches: Patches = [
   {
@@ -23,4 +24,8 @@ export const patches: Patches = [
     apply: tryPatchServerListener,
     description: 'Add keepAliveTimeout to server listener',
   },
+  {
+    apply: tryUpgradeToNode20,
+    description: 'Upgrade Node.js to 20',
+  },
 ];

src/cli/configure/upgrade/patches/7.3.1/patchServerListener.test.ts

@@ -50,7 +50,7 @@ describe('patchServerListener', () => {
         });
 
         // Gantry ALB default idle timeout is 30 seconds
-        // https://nodejs.org/docs/latest-v18.x/api/http.html#serverkeepalivetimeout
+        // https://nodejs.org/docs/latest-v20.x/api/http.html#serverkeepalivetimeout
         // Node default is 5 seconds
         // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
         // AWS recommends setting an application timeout larger than the load balancer
@@ -72,7 +72,7 @@ describe('patchServerListener', () => {
           "src/listen.ts": "const listener = app.listen(config.port);
 
         // Gantry ALB default idle timeout is 30 seconds
-        // https://nodejs.org/docs/latest-v18.x/api/http.html#serverkeepalivetimeout
+        // https://nodejs.org/docs/latest-v20.x/api/http.html#serverkeepalivetimeout
         // Node default is 5 seconds
         // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
         // AWS recommends setting an application timeout larger than the load balancer

src/cli/configure/upgrade/patches/7.3.1/patchServerListener.ts

@@ -11,7 +11,7 @@ const SERVER_LISTENER_FILENAME = 'src/listen.ts';
 
 const KEEP_ALIVE_CODE = `
 // Gantry ALB default idle timeout is 30 seconds
-// https://nodejs.org/docs/latest-v18.x/api/http.html#serverkeepalivetimeout
+// https://nodejs.org/docs/latest-v20.x/api/http.html#serverkeepalivetimeout
 // Node default is 5 seconds
 // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
 // AWS recommends setting an application timeout larger than the load balancer

src/cli/configure/upgrade/patches/7.3.1/upgradeToNode20.test.ts

@@ -0,0 +1,147 @@
+import memfs, { vol } from 'memfs';
+
+import type { PatchReturnType } from '../..';
+
+import { tryUpgradeToNode20 } from './upgradeToNode20';
+
+jest.mock('fs-extra', () => memfs);
+jest.mock('fast-glob', () => ({
+  glob: (pat: any, opts: any) =>
+    jest.requireActual('fast-glob').glob(pat, { ...opts, fs: memfs }),
+}));
+
+const volToJson = () => vol.toJSON(process.cwd(), undefined, true);
+
+beforeEach(jest.clearAllMocks);
+beforeEach(() => vol.reset());
+
+const reason = 'unable to find any Node.js 20 usage';
+
+describe('tryUpgradeToNode20', () => {
+  const scenarios: Array<{
+    filesBefore: Record<string, string>;
+    filesAfter?: Record<string, string>;
+    result: PatchReturnType;
+    scenario: string;
+  }> = [
+    {
+      scenario: 'an empty project',
+      filesBefore: {},
+      result: { result: 'skip', reason },
+    },
+    {
+      scenario: 'several files to patch',
+      filesBefore: {
+        '.nvmrc': 'v18.1.2',
+        Dockerfile: 'FROM node:18.1.2\nRUN echo "hello"',
+        'Dockerfile.dev-deps':
+          'FROM --platform=linux/amd64 node:18-slim AS dev-deps\nRUN echo "hello"',
+        'serverless.yml':
+          'provider:\n  logRetentionInDays: 30\n  runtime: nodejs18.x\n  region: ap-southeast-2',
+        'serverless.melb.yaml':
+          'provider:\n  logRetentionInDays: 7\n  runtime: nodejs16.x\n  region: ap-southeast-4',
+      },
+      filesAfter: {
+        '.nvmrc': '20',
+        Dockerfile: 'FROM node:20\nRUN echo "hello"',
+        'Dockerfile.dev-deps':
+          'FROM --platform=linux/amd64 node:20-slim AS dev-deps\nRUN echo "hello"',
+        'serverless.yml':
+          'provider:\n  logRetentionInDays: 30\n  runtime: nodejs20.x\n  region: ap-southeast-2',
+        'serverless.melb.yaml':
+          'provider:\n  logRetentionInDays: 7\n  runtime: nodejs20.x\n  region: ap-southeast-4',
+      },
+      result: { result: 'apply' },
+    },
+    {
+      scenario: 'various node formats',
+      filesBefore: {
+        '.nvmrc': '18.3.4',
+        'Dockerfile.1': 'FROM node:18.1.2\nRUN echo "hello"',
+        'Dockerfile.2': 'FROM node:18\nRUN echo "hello"',
+        'Dockerfile.3': 'FROM node:18-slim\nRUN echo "hello"',
+        'Dockerfile.4': 'FROM node:18.1.2-slim\nRUN echo "hello"',
+        'Dockerfile.5':
+          'FROM --platform=linux/amd64 node:18.1.2 AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.6':
+          'FROM --platform=linux/amd64 node:18 AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.7':
+          'FROM --platform=linux/amd64 node:18-slim AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.8':
+          'FROM --platform=linux/amd64 node:18.1.2-slim AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.9':
+          'FROM gcr.io/distroless/nodejs18-debian12\nRUN echo "hello"',
+        'Dockerfile.10':
+          'FROM --platform=linux/amd64 gcr.io/distroless/nodejs18-debian12 AS dev-deps\nRUN echo "hello"',
+      },
+      filesAfter: {
+        '.nvmrc': '20',
+        'Dockerfile.1': 'FROM node:20\nRUN echo "hello"',
+        'Dockerfile.2': 'FROM node:20\nRUN echo "hello"',
+        'Dockerfile.3': 'FROM node:20-slim\nRUN echo "hello"',
+        'Dockerfile.4': 'FROM node:20-slim\nRUN echo "hello"',
+        'Dockerfile.5':
+          'FROM --platform=linux/amd64 node:20 AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.6':
+          'FROM --platform=linux/amd64 node:20 AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.7':
+          'FROM --platform=linux/amd64 node:20-slim AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.8':
+          'FROM --platform=linux/amd64 node:20-slim AS dev-deps\nRUN echo "hello"',
+        'Dockerfile.9':
+          'FROM gcr.io/distroless/nodejs20-debian12\nRUN echo "hello"',
+        'Dockerfile.10':
+          'FROM --platform=linux/amd64 gcr.io/distroless/nodejs20-debian12 AS dev-deps\nRUN echo "hello"',
+      },
+      result: { result: 'apply' },
+    },
+    {
+      scenario: 'already node 20',
+      filesBefore: {
+        '.nvmrc': '20',
+        Dockerfile: 'FROM node:20\nRUN echo "hello"',
+        'Dockerfile.dev-deps':
+          'FROM --platform=linux/amd64 node:20-slim AS dev-deps\nRUN echo "hello"',
+        'serverless.yml':
+          'provider:\n  logRetentionInDays: 30\n  runtime: nodejs20.x\n  region: ap-southeast-2',
+      },
+      result: { result: 'skip', reason },
+    },
+    {
+      scenario: 'not detectable',
+      filesBefore: {
+        '.nvmrc': 'lts/*',
+        Dockerfile: 'FROM node:latest\nRUN echo "hello"',
+      },
+      result: { result: 'skip', reason },
+    },
+  ];
+
+  describe('format mode', () => {
+    it.each(scenarios)(
+      'handles $scenario',
+      async ({ filesBefore, filesAfter, result: expected }) => {
+        vol.fromJSON(filesBefore, process.cwd());
+
+        const result = await tryUpgradeToNode20('format');
+
+        expect(result).toEqual(expected);
+        expect(volToJson()).toEqual(filesAfter ?? filesBefore);
+      },
+    );
+  });
+
+  describe('lint mode', () => {
+    it.each(scenarios)(
+      'handles $scenario',
+      async ({ filesBefore, result: expected }) => {
+        vol.fromJSON(filesBefore, process.cwd());
+
+        const result = await tryUpgradeToNode20('lint');
+
+        expect(result).toEqual(expected);
+        expect(volToJson()).toEqual(filesBefore); // no changes
+      },
+    );
+  });
+});

src/cli/configure/upgrade/patches/7.3.1/upgradeToNode20.ts

@@ -0,0 +1,103 @@
+import { inspect } from 'util';
+
+import { glob } from 'fast-glob';
+import fs from 'fs-extra';
+
+import type { PatchFunction, PatchReturnType } from '../..';
+import { log } from '../../../../../utils/logging';
+import { createDestinationFileReader } from '../../../analysis/project';
+
+type SubPatch = (
+  | { files: string; file?: never }
+  | { file: string; files?: never }
+) & {
+  test: RegExp;
+  replace: string;
+};
+
+const subPatches: SubPatch[] = [
+  { file: '.nvmrc', test: /^v?18.*/gm, replace: '20' },
+  {
+    files: 'Dockerfile*',
+    test: /^FROM(.*) node:18(\.[^- \n]+)?(-[^ \n]+)?( .+|)$/gm,
+    replace: 'FROM$1 node:20$3$4',
+  },
+  {
+    files: 'Dockerfile*',
+    test: /^FROM(.*) gcr.io\/distroless\/nodejs18-debian(.+)$/gm,
+    replace: 'FROM$1 gcr.io/distroless/nodejs20-debian$2',
+  },
+  {
+    files: 'serverless*.y*ml',
+    test: /nodejs(16|18).x/gm,
+    replace: 'nodejs20.x',
+  },
+  // TODO: CDK, CloudFormation?
+];
+
+const runSubPatch = async (
+  mode: 'format' | 'lint',
+  dir: string,
+  { file, files, test, replace }: SubPatch,
+): Promise<boolean> => {
+  const readFile = createDestinationFileReader(dir);
+  const paths = file ? [file] : await glob(files ?? [], { cwd: dir });
+
+  return (
+    await Promise.all(
+      paths.map(async (path) => {
+        const contents = await readFile(path);
+        if (!contents) {
+          return false;
+        }
+
+        const patched = contents.replaceAll(test, replace);
+        if (patched === contents) {
+          return false;
+        }
+
+        if (mode === 'format') {
+          await fs.promises.writeFile(path, patched);
+        }
+
+        return true;
+      }),
+    )
+  ).some((result) => result);
+};
+
+const upgradeToNode20 = async (
+  mode: 'format' | 'lint',
+  dir: string,
+): Promise<PatchReturnType> => {
+  const results = await Promise.all(
+    subPatches.map((subPatch) => runSubPatch(mode, dir, subPatch)),
+  );
+
+  return results.some((result) => result)
+    ? { result: 'apply' }
+    : { result: 'skip', reason: 'unable to find any Node.js <20 usage' };
+};
+
+export const tryUpgradeToNode20: PatchFunction = async (
+  mode: 'format' | 'lint',
+  dir = process.cwd(),
+) => {
+  if (process.env.SKIP_NODE_20_PATCH) {
+    log.warn(
+      'Skipping Node.js 20 patch due to SKIP_NODE_20_PATCH environment variable',
+    );
+
+    return {
+      result: 'apply', // because we don't want to try again
+    };
+  }
+
+  try {
+    return await upgradeToNode20(mode, dir);
+  } catch (err) {
+    log.warn('Failed to upgrade Node.js to 20');
+    log.subtle(inspect(err));
+    return { result: 'skip', reason: 'due to an error' };
+  }
+};

template/express-rest-api/src/listen.ts

@@ -16,7 +16,7 @@ const listener = app.listen(config.port, () => {
 });
 
 // Gantry ALB default idle timeout is 30 seconds
-// https://nodejs.org/docs/latest-v18.x/api/http.html#serverkeepalivetimeout
+// https://nodejs.org/docs/latest-v20.x/api/http.html#serverkeepalivetimeout
 // Node default is 5 seconds
 // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
 // AWS recommends setting an application timeout larger than the load balancer