@firefoxic/utils 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,7 +16,7 @@ pnpm add -D @firefoxic/utils
16
16
 
17
17
  ### `getProjectRoot`
18
18
 
19
- Your action should set the `REPO_NAME` environment variable to the step you want. If your action works with pull requests, you should also add two lines (which are marked below with a special comment) to use the `PR_NUMBER` variable. For example:
19
+ Your action should set the `REPO_NAME` environment variable to the step you want. If your action works with pull requests, you should also add two lines (which are marked below with a special comment) to use the `PR_NUMBER` variable. For example:
20
20
 
21
21
  ```yaml
22
22
  jobs:
@@ -40,7 +40,7 @@ jobs:
40
40
  target-folder: ${{ github.event.pull_request.number }} # For PR action
41
41
  ```
42
42
 
43
- Than you can get the path to the project root when deploying to GitHub Pages, for example in `vite.config.js`:
43
+ Than you can get the path to the project root when deploying to GitHub Pages, for example in `vite.config.js`:
44
44
 
45
45
  ```js
46
46
  import { defineConfig } from "vite"
@@ -92,9 +92,9 @@ jobs:
92
92
 
93
93
  ### `get-node-matrix`
94
94
 
95
- A CLI utility that reads the `engines.node` field from the project's `package.json` and prints the minimum Node.js versions (as a JSON array) for use in a GitHub Actions matrix. When running in a GitHub Actions environment, it also appends `node_versions=...` to the file pointed to by `GITHUB_OUTPUT`.
95
+ A CLI utility that reads the `engines.node` field from the project's `package.json` and prints the minimum Node.js versions (as a JSON array) for use in a GitHub Actions matrix. When running in a GitHub Actions environment, it also appends `node_versions=...` to the file pointed to by `GITHUB_OUTPUT`.
96
96
 
97
- Use it in the `discover` job of your workflow:
97
+ Use it in the `discover` job of your workflow:
98
98
 
99
99
  ```yaml
100
100
  jobs:
@@ -127,7 +127,11 @@ jobs:
127
127
  - run: make verify
128
128
  ```
129
129
 
130
- The utility resolves the project's `package.json` from the current working directory (walking up the directory tree), or from the `npm_package_json` environment variable when run through an npm/pnpm script.
130
+ The utility resolves the project's `package.json` from the current working directory (walking up the directory tree), or from the `npm_package_json` environment variable when run through an npm/pnpm script.
131
+
132
+ By default it reads `engines.node` from the calling project's own `package.json`. Pass `--dependencies <package>` (or `--dependencies=<package>`, or the short form `-d <package>`) to also read it from dependencies — for example `--dependencies stylelint` to take the Node.js versions required by `stylelint` when it is installed as a dependency. Multiple packages can be passed as a comma-separated list: `--dependencies "stylelint,postcss"`. Versions from the project and all specified dependencies are merged into a single deduplicated list, keeping only the lowest version in each major line (e.g. `22.18.0` over `22.22.2`). If `engines.node` is missing everywhere, the utility fails with an error.
133
+
134
+ Pass `--help` or `-h` to show the CLI help message.
131
135
 
132
136
  [license-url]: https://github.com/firefoxic/utils/blob/main/LICENSE.md
133
137
  [license-image]: https://img.shields.io/badge/License-MIT-limegreen.svg
@@ -29,18 +29,128 @@ function resolvePackageJsonPath() {
29
29
  }
30
30
  throw new Error(`Project package.json not found`);
31
31
  }
32
- let packageJson = JSON.parse(readFileSync(resolvePackageJsonPath(), `utf8`));
33
- let range = packageJson.engines?.node;
34
- if (!range)
35
- throw new Error(`Project package.json does not specify engines.node`);
36
- let versions = range.split(`||`).map((part) => {
37
- let version = part.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/u);
38
- if (!version)
39
- throw new Error(`Cannot resolve minimum Node.js version: ${part}`);
40
- return `${version[1]}.${version[2] ?? 0}.${version[3] ?? 0}`;
41
- });
42
- let output = JSON.stringify([...new Set(versions)]);
43
- if (process.env.GITHUB_OUTPUT) {
44
- appendFileSync(process.env.GITHUB_OUTPUT, `node_versions=${output}\n`);
32
+ function printHelp() {
33
+ process.stdout.write(`
34
+ Usage:
35
+ get-node-matrix [options]
36
+
37
+ Description:
38
+ Reads the engines.node field from package.json files
39
+ and prints the minimum Node.js versions as a JSON array
40
+ for use in a GitHub Actions matrix.
41
+ When running in GitHub Actions, the result is also appended
42
+ to the file pointed to by GITHUB_OUTPUT as node_versions=...
43
+
44
+ Options:
45
+ -d, --dependencies <packages>
46
+ Also read engines.node from the specified dependencies.
47
+ Multiple packages can be passed as a comma-separated list.
48
+ -h, --help
49
+ Show this help message and exit.
50
+
51
+ Examples:
52
+ get-node-matrix
53
+ get-node-matrix --dependencies stylelint
54
+ get-node-matrix -d "stylelint,postcss"
55
+ pnpm dlx --package @firefoxic/utils get-node-matrix -d stylelint
56
+
57
+ `);
58
+ process.exit(0);
59
+ }
60
+ function parseArgs() {
61
+ let dependencies = [];
62
+ for (let i = 2; i < process.argv.length; i += 1) {
63
+ let arg = process.argv[i];
64
+ if (!arg)
65
+ continue;
66
+ if (arg === `--help` || arg === `-h`)
67
+ printHelp();
68
+ if (arg === `--dependencies` || arg === `-d`) {
69
+ if (i + 1 >= process.argv.length)
70
+ throw new Error(`--dependencies requires a list of package names`);
71
+ i += 1;
72
+ let next = process.argv[i];
73
+ if (!next)
74
+ throw new Error(`--dependencies requires a list of package names`);
75
+ dependencies = dependencies.concat(parseDependencyList(next));
76
+ }
77
+ else if (arg.startsWith(`--dependencies=`) || arg.startsWith(`-d=`)) {
78
+ let prefix = arg.startsWith(`--dependencies=`) ? `--dependencies=` : `-d=`;
79
+ dependencies = dependencies.concat(parseDependencyList(arg.slice(prefix.length)));
80
+ }
81
+ }
82
+ return { dependencies };
83
+ }
84
+ function parseDependencyList(value) {
85
+ return value
86
+ .split(`,`)
87
+ .map((item) => item.trim())
88
+ .filter((item) => item.length > 0);
89
+ }
90
+ function parseVersionTuple(version) {
91
+ let parts = version.split(`.`);
92
+ return [
93
+ Number(parts[0]),
94
+ Number(parts[1]),
95
+ Number(parts[2]),
96
+ ];
45
97
  }
98
+ function readNodeRange(packageJsonPath) {
99
+ let packageJson;
100
+ try {
101
+ packageJson = JSON.parse(readFileSync(packageJsonPath, `utf8`));
102
+ }
103
+ catch {
104
+ // Dependency package.json missing or unreadable — skip it.
105
+ return undefined;
106
+ }
107
+ let range = packageJson.engines?.node;
108
+ if (!range)
109
+ return undefined;
110
+ return range.split(`||`).map((part) => {
111
+ let version = part.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/u);
112
+ if (!version)
113
+ throw new Error(`Cannot resolve minimum Node.js version: ${part}`);
114
+ return `${version[1]}.${version[2] ?? 0}.${version[3] ?? 0}`;
115
+ });
116
+ }
117
+ let { dependencies } = parseArgs();
118
+ let projectPackageJsonPath = resolvePackageJsonPath();
119
+ let projectRoot = path.dirname(projectPackageJsonPath);
120
+ let versions = [];
121
+ // Always include versions from the calling project itself.
122
+ let projectVersions = readNodeRange(projectPackageJsonPath);
123
+ if (projectVersions)
124
+ versions = versions.concat(projectVersions);
125
+ // Include versions from each specified dependency.
126
+ for (let dependency of dependencies) {
127
+ let dependencyVersions = readNodeRange(path.resolve(projectRoot, `node_modules`, dependency, `package.json`));
128
+ if (dependencyVersions)
129
+ versions = versions.concat(dependencyVersions);
130
+ }
131
+ let uniqueVersions = [...new Set(versions)];
132
+ // Keep only the lowest version in each major line (e.g. 22.18.0 over 22.22.2).
133
+ let byMajor = new Map();
134
+ for (let version of uniqueVersions) {
135
+ let [major, minor, patch] = parseVersionTuple(version);
136
+ let current = byMajor.get(major);
137
+ if (!current
138
+ || minor < current.tuple[1]
139
+ || (minor === current.tuple[1] && patch < current.tuple[2]))
140
+ byMajor.set(major, { version, tuple: [major, minor, patch] });
141
+ }
142
+ let outputVersions = [...byMajor.values()]
143
+ .toSorted((a, b) => {
144
+ if (a.tuple[0] !== b.tuple[0])
145
+ return a.tuple[0] - b.tuple[0];
146
+ if (a.tuple[1] !== b.tuple[1])
147
+ return a.tuple[1] - b.tuple[1];
148
+ return a.tuple[2] - b.tuple[2];
149
+ })
150
+ .map((entry) => entry.version);
151
+ if (outputVersions.length === 0)
152
+ throw new Error(`No engines.node found in the project package.json or any of the specified dependencies`);
153
+ let output = JSON.stringify(outputVersions);
154
+ if (process.env.GITHUB_OUTPUT)
155
+ appendFileSync(process.env.GITHUB_OUTPUT, `node_versions=${output}\n`);
46
156
  console.info(`Node.js matrix: ${output}`);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@firefoxic/utils",
3
3
  "description": "Collection of useful utilities for JavaScript and Node.js.",
4
- "version": "2.2.0",
4
+ "version": "2.3.0",
5
5
  "license": "MIT",
6
6
  "author": {
7
7
  "name": "Sergey Artemov",
@@ -16,10 +16,11 @@
16
16
  "url": "git+https://github.com/firefoxic/utils.git"
17
17
  },
18
18
  "type": "module",
19
+ "types": "./dist/index.d.ts",
19
20
  "exports": {
20
21
  ".": {
21
- "import": "./dist/index.js",
22
- "types": "./dist/index.d.ts"
22
+ "types": "./dist/index.d.ts",
23
+ "import": "./dist/index.js"
23
24
  },
24
25
  "./package.json": "./package.json"
25
26
  },
@@ -40,16 +41,16 @@
40
41
  },
41
42
  "packageManager": {
42
43
  "name": "pnpm",
43
- "version": ">=12.19",
44
+ "version": ">=12.22",
44
45
  "onFail": "download"
45
46
  }
46
47
  },
47
48
  "devDependencies": {
48
- "@firefoxic/oxlint-config": "~0.6",
49
+ "@firefoxic/oxlint-config": "~0.7",
49
50
  "@types/node": "^26",
50
51
  "@vitest/coverage-v8": "^5",
51
52
  "oxlint": "^1",
52
- "tsrs": "^0.25.0-ts7",
53
+ "tsrs": "latest",
53
54
  "vitest": "^5"
54
55
  },
55
56
  "keywords": [