fix(check-node): align with CDK Node.js versions support policy (#4865)

Align with the CDK support policy for Node.js versions (https://docs.aws.amazon.com/cdk/v2/guide/node-versions.html)

Previously `@jsii/check-node` would support Node.js versions until their EOL date. We would also warn users 30 days before the EOL. With our updated Node.js versions support policy, we will support Node.js versions usually for 6 months after the EOL.

This change reflects this new policy. We now warn users in the extended support timeframe, but not anymore before the EOL.

Also adds Node.js 24.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

Author: mrgrain

.github/workflows/main.yml

@@ -232,6 +232,13 @@ jobs:
             node: '22' # EOL 2027-04-30
             os: ubuntu-latest
             python: '3.9'
+          - title: 'Node 24'
+            java: '8'
+            dotnet: '6.0.x'
+            go: '1.18'
+            node: '22' # EOL 2028-04-30
+            os: ubuntu-latest
+            python: '3.9'
           # Test alternate .NETs
           - title: '.NET 7.0'
             java: '8'

CONTRIBUTING.md

@@ -20,6 +20,7 @@ our own CI/CD: the ["superchain" image][superchain] from.
 [superchain]: https://github.com/aws/jsii-superchain
 
 Once built locally, you can launch a shell from your root project directory in a self-removing container like so:  
+
 ```bash
 # runs the built container, creates a volume mount to /project inside the container
 docker run --rm -it -v "$(pwd)":/project -w /project jsii/superchain:local
@@ -31,7 +32,7 @@ The following tools need to be installed to develop on JSII locally. We recommen
 using the docker image from the above section, but if you wish to, you can install
 in your development environment.
 
-- [Node `18.0.0`] or later
+- [Node `20.0.0`] or later
 - [Yarn `1.19.1`] or later
 - An OpenJDK-8 distribution (e.g: [Oracle's OpenJDK8], [Amazon Corretto 8])
   - [`maven >= 3.0.5`](https://maven.apache.org)

gh-pages/partials/node-support-table.md

@@ -5,6 +5,7 @@
     | `^18.0.0` | :white_check_mark: Supported | `2025-04-30` |
     | `^20.0.0` | :white_check_mark: Supported | `2026-04-30` |
     | `^22.0.0` | :white_check_mark: Supported | `2027-04-30` |
+    | `^24.0.0` | :white_check_mark: Supported | `2028-04-30` |
 
     ??? question "Status Definitions"
         - **:white_check_mark: Supported**: Long Term Support (LTS) releases  (those with an even major version) are

packages/@jsii/check-node/src/constants.test.ts

@@ -1,33 +1,37 @@
 import { NodeRelease } from './constants';
 
-test('supported release', () => {
-  const endOfLife = new Date(Date.now() + 31 * 86_400_000);
-  const subject = new NodeRelease(42, { endOfLife });
+describe('before EOL', () => {
+  test('supported release', () => {
+    const endOfLife = new Date(Date.now() + 31 * 86_400_000);
+    const subject = new NodeRelease(42, { endOfLife });
 
-  expect(subject).toMatchObject({
-    deprecated: false,
-    endOfLife: false,
-    endOfLifeDate: endOfLife,
-    untested: false,
-    supported: true,
-    supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    expect(subject).toMatchObject({
+      supported: true,
+      deprecated: false,
+      endOfLife: false,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: datePlusMonth(endOfLife, 6),
+      untested: false,
+      supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    });
   });
-});
 
-test('supported release with range', () => {
-  const endOfLife = new Date(Date.now() + 31 * 86_400_000);
-  const subject = new NodeRelease(42, {
-    endOfLife,
-    supportedRange: '^42.1337.0',
-  });
+  test('supported release with range', () => {
+    const endOfLife = new Date(Date.now() + 31 * 86_400_000);
+    const subject = new NodeRelease(42, {
+      endOfLife,
+      supportedRange: '^42.1337.0',
+    });
 
-  expect(subject).toMatchObject({
-    deprecated: false,
-    endOfLife: false,
-    endOfLifeDate: endOfLife,
-    untested: false,
-    supported: true,
-    supportedRange: expect.objectContaining({ raw: '^42.1337.0' }),
+    expect(subject).toMatchObject({
+      deprecated: false,
+      endOfLife: false,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: datePlusMonth(endOfLife, 6),
+      untested: false,
+      supported: true,
+      supportedRange: expect.objectContaining({ raw: '^42.1337.0' }),
+    });
   });
 });
 
@@ -36,39 +40,88 @@ test('untested release', () => {
   const subject = new NodeRelease(42, { endOfLife, untested: true });
 
   expect(subject).toMatchObject({
+    supported: false,
     deprecated: false,
     endOfLife: false,
     endOfLifeDate: endOfLife,
+    endOfJsiiSupportDate: datePlusMonth(endOfLife, 6),
     untested: true,
-    supported: false,
     supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
   });
 });
 
-test('deprecated release', () => {
-  const endOfLife = new Date(Date.now() + 25 * 86_400_000);
-  const subject = new NodeRelease(42, { endOfLife });
+describe('deprecated', () => {
+  test('after EOL, before EOS', () => {
+    const endOfLife = new Date(Date.now() - 30 * 86_400_000);
+    const endOfJsiiSupport = new Date(Date.now() + 30 * 86_400_000);
+    const subject = new NodeRelease(42, {
+      endOfLife,
+      endOfJsiiSupport,
+    });
 
-  expect(subject).toMatchObject({
-    deprecated: true,
-    endOfLife: false,
-    endOfLifeDate: endOfLife,
-    untested: false,
-    supported: true,
-    supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    expect(subject).toMatchObject({
+      supported: true,
+      deprecated: true,
+      endOfLife: true,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: endOfJsiiSupport,
+      untested: false,
+      supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    });
+  });
+
+  test('Within default EOS time', () => {
+    const endOfLife = new Date(Date.now() - 30 * 86_400_000);
+    const subject = new NodeRelease(42, { endOfLife });
+
+    expect(subject).toMatchObject({
+      supported: true,
+      deprecated: true,
+      endOfLife: true,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: datePlusMonth(endOfLife, 6),
+      untested: false,
+      supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    });
   });
 });
 
-test('EOL release', () => {
-  const endOfLife = new Date();
-  const subject = new NodeRelease(42, { endOfLife });
+describe('EOS', () => {
+  test('EOS release', () => {
+    const endOfLife = new Date(Date.now() - 30 * 86_400_000);
+    const endOfJsiiSupport = new Date(Date.now() - 10 * 86_400_000);
+    const subject = new NodeRelease(42, {
+      endOfLife,
+      endOfJsiiSupport,
+    });
 
-  expect(subject).toMatchObject({
-    deprecated: false,
-    endOfLife: true,
-    endOfLifeDate: endOfLife,
-    untested: false,
-    supported: false,
-    supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    expect(subject).toMatchObject({
+      supported: false,
+      endOfLife: true,
+      deprecated: false,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: endOfJsiiSupport,
+      untested: false,
+      supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    });
+  });
+
+  test('EOS default time frame', () => {
+    const endOfLife = new Date(Date.now() - 200 * 86_400_000);
+    const subject = new NodeRelease(42, { endOfLife });
+
+    expect(subject).toMatchObject({
+      supported: false,
+      endOfLife: true,
+      deprecated: false,
+      endOfLifeDate: endOfLife,
+      endOfJsiiSupportDate: datePlusMonth(endOfLife, 6),
+      untested: false,
+      supportedRange: expect.objectContaining({ raw: '^42.0.0' }),
+    });
   });
 });
+
+function datePlusMonth(date: Date, months: number): Date {
+  return new Date(date.getFullYear(), date.getMonth() + months, date.getDate());
+}

packages/@jsii/check-node/src/constants.ts

@@ -10,18 +10,21 @@ const ONE_DAY_IN_MILLISECONDS = 86_400_000;
  */
 export class NodeRelease {
   /**
-   * How long before enf-of-life do we start warning customers? Expressed in
-   * milliseconds to make it easier to deal with JS dates.
+   * How long after end-of-life do we continue to support a node version.
    */
-  private static readonly DEPRECATION_WINDOW_MS = 30 * ONE_DAY_IN_MILLISECONDS;
+  private static readonly DEFAULT_EXTENDED_SUPPORT_MONTHS = 6;
 
   /**
    * All registered node releases.
    */
   public static readonly ALL_RELEASES: readonly NodeRelease[] = [
     // Historical releases (not relevant at time of writing this as they're all EOL now...)
     ...([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] as const).map(
-      (majorVersion) => new NodeRelease(majorVersion, { endOfLife: true }),
+      (majorVersion) =>
+        new NodeRelease(majorVersion, {
+          endOfLife: new Date('2018-01-01'),
+          untested: true,
+        }),
     ),
 
     // Past end-of-life releases
@@ -46,11 +49,16 @@ export class NodeRelease {
     }),
     new NodeRelease(19, { endOfLife: new Date('2023-06-01'), untested: true }),
     new NodeRelease(21, { endOfLife: new Date('2024-06-01'), untested: true }),
+    new NodeRelease(23, { endOfLife: new Date('2025-06-01'), untested: true }),
 
     // Currently active releases (as of last edit to this file...)
-    new NodeRelease(18, { endOfLife: new Date('2025-04-30') }),
+    new NodeRelease(18, {
+      endOfLife: new Date('2025-04-30'),
+      endOfJsiiSupport: new Date('2025-11-30'),
+    }),
     new NodeRelease(20, { endOfLife: new Date('2026-04-30') }),
     new NodeRelease(22, { endOfLife: new Date('2027-04-30') }),
+    new NodeRelease(24, { endOfLife: new Date('2028-04-30') }),
 
     // Future (planned releases)
   ];
@@ -88,21 +96,33 @@ export class NodeRelease {
 
   /**
    * The date on which this release range starts to be considered end-of-life.
-   * May be `undefined` for "ancient" releases (before Node 12).
+   * Defaults to a pre-CDK date for "ancient" releases (before Node 12).
    */
-  public readonly endOfLifeDate: Date | undefined;
+  public readonly endOfLifeDate: Date;
 
   /**
-   * Determines whether this release is currently considered end-of-life.
+   * Determines whether this release has reached end of support for jsii.
+   * This is usually longer then endOfLife;
    */
-  public readonly endOfLife: boolean;
+  public readonly endOfJsiiSupportDate: Date;
 
   /**
    * Determines whether this release is within the deprecation window ahead of
    * it's end-of-life date.
    */
   public readonly deprecated: boolean;
 
+  /**
+   * Determines whether this release has reached end-of-life.
+   */
+  public readonly endOfLife: boolean;
+
+  /**
+   * Determines whether this major version line is currently "in support",
+   * meaning it is not end-of-life or within our extended support time frame.
+   */
+  public readonly supported: boolean;
+
   /**
    * If `true` denotes that this version of node has not been added to the test
    * matrix yet. This is used when adding not-yet-released versions of node that
@@ -119,51 +139,45 @@ export class NodeRelease {
    */
   public readonly supportedRange: Range;
 
-  /**
-   * Determines whether this major version line is currently "in support",
-   * meaning it is not end-of-life nor pending.
-   */
-  public readonly supported: boolean;
-
-  /** @internal visible for testing */
-  public constructor(
-    majorVersion: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11,
-    opts: { endOfLife: true },
-  );
   /** @internal visible for testing */
   public constructor(
     majorVersion: number,
     opts: {
       endOfLife: Date;
-      untested?: boolean;
-      supportedRange?: string;
-    },
-  );
-  /** @internal visible for testing */
-  public constructor(
-    majorVersion: number,
-    opts: {
-      endOfLife: Date | true;
+      endOfJsiiSupport?: Date;
       untested?: boolean;
       supportedRange?: string;
     },
   ) {
-    this.majorVersion = majorVersion;
-    this.endOfLifeDate = opts.endOfLife === true ? undefined : opts.endOfLife;
     this.untested = opts.untested ?? false;
+    this.majorVersion = majorVersion;
     this.supportedRange = new Range(
       opts.supportedRange ?? `^${majorVersion}.0.0`,
     );
 
+    this.endOfLifeDate = opts.endOfLife;
     this.endOfLife =
-      opts.endOfLife === true || opts.endOfLife.getTime() <= Date.now();
-    this.deprecated =
-      !this.endOfLife &&
-      opts.endOfLife !== true &&
-      opts.endOfLife.getTime() - NodeRelease.DEPRECATION_WINDOW_MS <=
-        Date.now();
-
-    this.supported = !this.untested && !this.endOfLife;
+      opts.endOfLife.getTime() + ONE_DAY_IN_MILLISECONDS <= Date.now();
+
+    // jsii EOS defaults to 6 months after EOL
+    this.endOfJsiiSupportDate =
+      opts.endOfJsiiSupport ??
+      new Date(
+        this.endOfLifeDate.getFullYear(),
+        this.endOfLifeDate.getMonth() +
+          NodeRelease.DEFAULT_EXTENDED_SUPPORT_MONTHS,
+        this.endOfLifeDate.getDate(),
+      );
+
+    const endOfJsiiSupport =
+      this.endOfJsiiSupportDate.getTime() + ONE_DAY_IN_MILLISECONDS <=
+      Date.now();
+
+    // We deprecate (warn) from EOL to jsii EOS
+    this.deprecated = this.endOfLife && !endOfJsiiSupport;
+
+    // All tested and not EOS versions are supported
+    this.supported = !this.untested && !endOfJsiiSupport;
   }
 
   public toString(): string {