Merge 96f3c37ea4 into 65d868f8d4

* update documentation for lockfile

* Update adavance usage in README.md

* Documentation update

* Update lockfile documenation

* fix coplilot suggestion

README.md

@@ -16,9 +16,9 @@ This action provides the following functionality for GitHub Actions users:
 
 - Caching is now automatically enabled for npm projects when either the `devEngines.packageManager` field or the top-level `packageManager` field in `package.json` is set to `npm`. For other package managers, such as Yarn and pnpm, caching is disabled by default and must be configured manually using the `cache` input.
 
-- The `always-auth` input has been removed, as it is deprecated and will no longer be supported in future npm releases. To ensure your workflows continue to run without warnings or errors, please remove any references to `always-auth` from your configuration.  
+- The `always-auth` input has been removed, as it is deprecated and will no longer be supported in future npm releases. To ensure your workflows continue to run without warnings or errors, please remove any references to `always-auth` from your configuration.
 
-## Breaking changes in V5 
+## Breaking changes in V5
 
 - Enabled caching by default with package manager detection if no cache input is provided.
   > For workflows with elevated privileges or access to sensitive information, we recommend disabling automatic caching by setting `package-manager-cache: false` when caching is not needed for secure operation.
@@ -41,23 +41,23 @@ See [action.yml](action.yml)
     # Examples: 12.x, 10.15.1, >=10.15.0, lts/Hydrogen, 16-nightly, latest, node
     node-version: ''
 
-    # File containing the version Spec of the version to use.  Examples: package.json, .nvmrc, .node-version, .tool-versions.
+    # File containing the version Spec of the version to use.  Examples: package.json, mise.toml, .nvmrc, .node-version, .tool-versions.
-    # If node-version and node-version-file are both provided the action will use version from node-version. 
+    # If node-version and node-version-file are both provided the action will use version from node-version.
     node-version-file: ''
 
-    # Set this option if you want the action to check for the latest available version 
+    # Set this option if you want the action to check for the latest available version
     # that satisfies the version spec.
-    # It will only get affect for lts Nodejs versions (12.x, >=10.15.0, lts/Hydrogen). 
+    # It will only get affect for lts Nodejs versions (12.x, >=10.15.0, lts/Hydrogen).
     # Default: false
     check-latest: false
 
     # Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default.
-    # Default: ''. The action use system architecture by default 
+    # Default: ''. The action use system architecture by default
     architecture: ''
 
-    # Used to pull node distributions from https://github.com/actions/node-versions. 
+    # Used to pull node distributions from https://github.com/actions/node-versions.
-    # Since there's a default, this is typically not supplied by the user. 
+    # Since there's a default, this is typically not supplied by the user.
-    # When running this action on github.com, the default value is sufficient. 
+    # When running this action on github.com, the default value is sufficient.
     # When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
     #
     # We recommend using a service account with the least permissions necessary. Also
@@ -78,18 +78,18 @@ See [action.yml](action.yml)
     # default: true
     package-manager-cache: true
 
-    # Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc. 
+    # Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc.
-    # It will generate hash from the target file for primary key. It works only If cache is specified.  
+    # It will generate hash from the target file for primary key. It works only If cache is specified.
     # Supports wildcards or a list of file names for caching multiple dependencies.
     # Default: ''
     cache-dependency-path: ''
 
-    # Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file, 
+    # Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file,
     # and set up auth to read in from env.NODE_AUTH_TOKEN.
     # Default: ''
     registry-url: ''
 
-    # Optional scope for authenticating against scoped registries. 
+    # Optional scope for authenticating against scoped registries.
     # Will fall back to the repository owner when using the GitHub Packages registry (https://npm.pkg.github.com/).
     # Default: ''
     scope: ''
@@ -148,7 +148,7 @@ Since it will not be cached always, there is possibility of hitting rate limit w
 
 ### Checking in lockfiles
 
-It's **always** recommended to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide.
+It's **strongly recommended** to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide.
 
 ## Caching global packages data
 
@@ -249,6 +249,7 @@ If the runner is not able to access github.com, any Nodejs versions requested du
  - [Publishing to npmjs and GPR with npm](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-npm)
  - [Publishing to npmjs and GPR with yarn](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-yarn)
  - [Using private packages](docs/advanced-usage.md#use-private-packages)
+ - [Using private mirror](docs/advanced-usage.md#use-private-mirror)
 
 ## Recommended permissions
 

__tests__/main.test.ts

@@ -1,18 +1,18 @@
+import * as cache from '@actions/cache';
 import * as core from '@actions/core';
 import * as exec from '@actions/exec';
-import * as tc from '@actions/tool-cache';
-import * as cache from '@actions/cache';
 import * as io from '@actions/io';
+import * as tc from '@actions/tool-cache';
 
 import fs from 'fs';
-import path from 'path';
 import osm from 'os';
+import path from 'path';
 
 import each from 'jest-each';
 
+import OfficialBuilds from '../src/distributions/official_builds/official_builds';
 import * as main from '../src/main';
 import * as util from '../src/util';
-import OfficialBuilds from '../src/distributions/official_builds/official_builds';
 
 describe('main tests', () => {
   let inputs = {} as any;
@@ -94,22 +94,25 @@ describe('main tests', () => {
 
   describe('getNodeVersionFromFile', () => {
     each`
-      contents                                     | expected
+      contents                                                 | expected
-      ${'12'}                                      | ${'12'}
+      ${'12'}                                                  | ${'12'}
-      ${'12.3'}                                    | ${'12.3'}
+      ${'12.3'}                                                | ${'12.3'}
-      ${'12.3.4'}                                  | ${'12.3.4'}
+      ${'12.3.4'}                                              | ${'12.3.4'}
-      ${'v12.3.4'}                                 | ${'12.3.4'}
+      ${'v12.3.4'}                                             | ${'12.3.4'}
-      ${'lts/erbium'}                              | ${'lts/erbium'}
+      ${'lts/erbium'}                                          | ${'lts/erbium'}
-      ${'lts/*'}                                   | ${'lts/*'}
+      ${'lts/*'}                                               | ${'lts/*'}
-      ${'nodejs 12.3.4'}                           | ${'12.3.4'}
+      ${'nodejs 12.3.4'}                                       | ${'12.3.4'}
-      ${'ruby 2.3.4\nnodejs 12.3.4\npython 3.4.5'} | ${'12.3.4'}
+      ${'ruby 2.3.4\nnodejs 12.3.4\npython 3.4.5'}             | ${'12.3.4'}
-      ${''}                                        | ${''}
+      ${''}                                                    | ${''}
-      ${'unknown format'}                          | ${'unknown format'}
+      ${'unknown format'}                                      | ${'unknown format'}
-      ${'  14.1.0  '}                              | ${'14.1.0'}
+      ${'  14.1.0  '}                                          | ${'14.1.0'}
-      ${'{"volta": {"node": ">=14.0.0 <=17.0.0"}}'}| ${'>=14.0.0 <=17.0.0'}
+      ${'{"volta": {"node": ">=14.0.0 <=17.0.0"}}'}            | ${'>=14.0.0 <=17.0.0'}
-      ${'{"volta": {"extends": "./package.json"}}'}| ${'18.0.0'}
+      ${'{"volta": {"extends": "./package.json"}}'}            | ${'18.0.0'}
-      ${'{"engines": {"node": "17.0.0"}}'}         | ${'17.0.0'}
+      ${'{"engines": {"node": "17.0.0"}}'}                     | ${'17.0.0'}
-      ${'{}'}                                      | ${null}
+      ${'[tools]\ngo="latest"\nnode = "24.10"'}                | ${'24.10'}
+      ${'[tools]\nnode = { version = "22.20" }'}               | ${'22.20'}
+      ${'[tools]\nnode = { postinstall = "corepack enable" }'} | ${null}
+      ${'{}'}                                                  | ${null}
     `.it('parses "$contents"', ({contents, expected}) => {
       const existsSpy = jest.spyOn(fs, 'existsSync');
       existsSpy.mockImplementation(() => true);

docs/advanced-usage.md

@@ -1,6 +1,6 @@
 ## Working with lockfiles
 
-All supported package managers recommend that you **always** commit the lockfile, although implementations vary doing so generally provides the following benefits:
+Most supported package managers recommend that you **always** commit the lockfile, although implementations vary doing so generally provides the following benefits:
 
 - Enables faster installation for CI and production environments, due to being able to skip package resolution.
 - Describes a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
@@ -35,6 +35,25 @@ Ensure that `pnpm-lock.yaml` is always committed, when on CI pass `--frozen-lock
 - [Working with Git - Lockfiles](https://pnpm.io/git#lockfiles)
 - [Documentation of `--frozen-lockfile` option](https://pnpm.io/cli/install#--frozen-lockfile)
 
+### Running without a lockfile
+
+If you choose not to use a lockfile, you must ensure that **caching is disabled**. The `cache` feature relies on the lockfile to generate a unique key for the cache entry.
+
+To run without a lockfile:
+1. Do not set the `cache` input.
+2. If your `package.json` contains a `packageManager` field set to npm (or devEngines.packageManager), automatic caching is enabled by default. Override this by setting `package-manager-cache: false`.
+
+```yaml
+steps:
+- uses: actions/checkout@v6
+- uses: actions/setup-node@v6
+  with:
+    node-version: '24'
+    package-manager-cache: false # Explicitly disable caching if you don't have a lockfile
+- run: npm install
+- run: npm test
+```
+
 ## Check latest version
 
 The `check-latest` flag defaults to `false`. When set to `false`, the action will first check the local cache for a semver match. If unable to find a specific version in the cache, the action will attempt to download a version of Node.js. It will pull LTS versions from [node-versions releases](https://github.com/actions/node-versions/releases) and on miss or failure will fall back to the previous behavior of downloading directly from [node dist](https://nodejs.org/dist/). Use the default or set `check-latest` to `false` if you prefer stability and if you want to ensure a specific version of Node.js is always used.

package-lock.json

@@ -17,6 +17,7 @@
         "@actions/http-client": "^2.2.1",
         "@actions/io": "^1.0.2",
         "@actions/tool-cache": "^2.0.2",
+        "js-toml": "^1.0.2",
         "semver": "^7.6.3",
         "uuid": "^11.1.0"
       },
@@ -792,6 +793,18 @@
         "@babel/core": "^7.0.0-0"
       }
     },
+    "node_modules/@babel/runtime-corejs3": {
+      "version": "7.28.4",
+      "resolved": "https://registry.npmjs.org/@babel/runtime-corejs3/-/runtime-corejs3-7.28.4.tgz",
+      "integrity": "sha512-h7iEYiW4HebClDEhtvFObtPmIvrd1SSfpI9EhOeKk4CtIK/ngBWFpuhCzhdmRKtg71ylcue+9I6dv54XYO1epQ==",
+      "license": "MIT",
+      "dependencies": {
+        "core-js-pure": "^3.43.0"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/template": {
       "version": "7.27.0",
       "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.0.tgz",
@@ -857,6 +870,45 @@
       "integrity": "sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==",
       "dev": true
     },
+    "node_modules/@chevrotain/cst-dts-gen": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-11.0.3.tgz",
+      "integrity": "sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/gast": "11.0.3",
+        "@chevrotain/types": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
+    "node_modules/@chevrotain/gast": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-11.0.3.tgz",
+      "integrity": "sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/types": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
+    "node_modules/@chevrotain/regexp-to-ast": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-11.0.3.tgz",
+      "integrity": "sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@chevrotain/types": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.0.3.tgz",
+      "integrity": "sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@chevrotain/utils": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-11.0.3.tgz",
+      "integrity": "sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==",
+      "license": "Apache-2.0"
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz",
@@ -2407,6 +2459,20 @@
         "node": ">=10"
       }
     },
+    "node_modules/chevrotain": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz",
+      "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/cst-dts-gen": "11.0.3",
+        "@chevrotain/gast": "11.0.3",
+        "@chevrotain/regexp-to-ast": "11.0.3",
+        "@chevrotain/types": "11.0.3",
+        "@chevrotain/utils": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
     "node_modules/ci-info": {
       "version": "3.9.0",
       "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-3.9.0.tgz",
@@ -2498,6 +2564,17 @@
       "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
       "dev": true
     },
+    "node_modules/core-js-pure": {
+      "version": "3.46.0",
+      "resolved": "https://registry.npmjs.org/core-js-pure/-/core-js-pure-3.46.0.tgz",
+      "integrity": "sha512-NMCW30bHNofuhwLhYPt66OLOKTMbOhgTTatKVbaQC3KRHpTCiRIBYvtshr+NBYSnBxwAFhjW/RfJ0XbIjS16rw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/core-js"
+      }
+    },
     "node_modules/create-jest": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/create-jest/-/create-jest-29.7.0.tgz",
@@ -4315,6 +4392,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/js-toml": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/js-toml/-/js-toml-1.0.2.tgz",
+      "integrity": "sha512-/7IQ//bzn2a/5IDazPUNzlW7bsjxS51cxciYZDR+Z+3Le60yzT0YfI8KOWqTtBcZkXXVklhWd2OuGd8ZksB0wQ==",
+      "license": "MIT",
+      "dependencies": {
+        "chevrotain": "^11.0.3",
+        "xregexp": "^5.1.1"
+      }
+    },
     "node_modules/js-yaml": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
@@ -4437,6 +4524,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash-es": {
+      "version": "4.17.21",
+      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
+      "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
+      "license": "MIT"
+    },
     "node_modules/lodash.memoize": {
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz",
@@ -5750,6 +5843,15 @@
         "node": ">=4.0"
       }
     },
+    "node_modules/xregexp": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/xregexp/-/xregexp-5.1.2.tgz",
+      "integrity": "sha512-6hGgEMCGhqCTFEJbqmWrNIPqfpdirdGWkqshu7fFZddmTSfgv5Sn9D2SaKloR79s5VUiUlpwzg3CM3G6D3VIlw==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime-corejs3": "^7.26.9"
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",

package.json

@@ -36,6 +36,7 @@
     "@actions/http-client": "^2.2.1",
     "@actions/io": "^1.0.2",
     "@actions/tool-cache": "^2.0.2",
+    "js-toml": "^1.0.2",
     "semver": "^7.6.3",
     "uuid": "^11.1.0"
   },

src/util.ts

@@ -1,6 +1,7 @@
 import * as core from '@actions/core';
 import * as exec from '@actions/exec';
 import * as io from '@actions/io';
+import {load} from 'js-toml';
 
 import fs from 'fs';
 import path from 'path';
@@ -56,6 +57,26 @@ export function getNodeVersionFromFile(versionFilePath: string): string | null {
     core.info('Node version file is not JSON file');
   }
 
+  // Try parsing the file as a mise `mise.toml` file.
+  try {
+    const manifest: Record<string, any> = load(contents);
+    if (manifest?.tools?.node) {
+      const node = manifest.tools.node;
+
+      if (typeof node === 'object' && node?.version) {
+        return node.version;
+      }
+
+      if (typeof node === 'string') {
+        return node;
+      }
+
+      return null;
+    }
+  } catch {
+    core.info('Node version file is not TOML file');
+  }
+
   const found = contents.match(/^(?:node(js)?\s+)?v?(?<version>[^\s]+)$/m);
   return found?.groups?.version ?? contents.trim();
 }