@serenematt/pin-exact-action 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SereneMatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# pin-exact-action
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps the Node version in your version file, `@types/node` and `engines.node` in sync, and fails CI when `package.json` dependencies are not pinned to exact versions.
+
+It is for apps, not libraries. Libraries should usually publish ranges so their users can dedupe.
+
+It complements `save-exact=true` in `.npmrc`, Renovate's `rangeStrategy: "pin"` and syncpack. Those write exact pins. This checks them in CI, together with the Node versions.
+
+## What it checks
+
+In the target directory:
+
+1. **Node version sync.** If a Node version source is found (see below):
+   - `@types/node` (in `dependencies` or `devDependencies`) has the same major as that Node version. No `@types/node` means no check.
+   - `engines.node` is required and must be exactly `>=<node version>`, for example `>=24.11.1`. Whitespace is ignored, so `>= 24.11.1` is fine. This is strict on purpose: the engines floor should be the version you actually run and test.
+2. **Exact pins.** Every entry in `dependencies`, `devDependencies` and `optionalDependencies` is an exact version. Each field is checked on its own, so a loose entry can't hide behind the same name in another field. Values in `overrides` (npm, nested objects too), `resolutions` (yarn) and `pnpm.overrides` are checked as well.
+
+What counts as exact:
+
+- A full semver version, using the [semver.org regex](https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string): `1.2.3`, `1.2.3-beta.1`, `1.0.0+b1`. Leading zeros like `01.2.3` fail.
+- An alias to an exact version: `npm:other@1.2.3`.
+- Local and monorepo protocols, which are not registry ranges: `workspace:`, `file:`, `link:`, `catalog:`.
+- In `overrides`, a `$name` reference to a direct dependency (that dependency is checked itself).
+
+Everything else fails: `^`, `~`, ranges, `*`, tags like `latest`, git and http URLs.
+
+`peerDependencies` are not checked. Ranges are correct there.
+
+All problems are printed, then it exits 1 once.
+
+## Node version sources
+
+Checked in this order. The first one that names a Node version wins, and the output names it:
+
+1. `.tool-versions` (`node` or `nodejs`)
+2. `mise.toml`, then `.mise.toml` (`[tools]` `node` or `nodejs`, a string or the first entry of an array)
+3. `.nvmrc`
+4. `.node-version`
+5. `package.json` `volta.node`
+6. `package.json` `devEngines.runtime` (object or array, the entry named `node`)
+
+A leading `v` is stripped. The version must be an exact `X.Y.Z`. Values like `lts/*`, `system` or `24` fail with an error naming the file.
+
+If there is no source, the Node checks are skipped with a note, and only pins are checked.
+
+## Output
+
+Locally, each problem is an `error: <file>: <message>` line. In GitHub Actions (`GITHUB_ACTIONS=true`), each one is an `::error file=<path>::<message>` annotation, with the path relative to the repository root.
+
+## GitHub Action
+
+```yaml
+- uses: actions/checkout@v6
+- uses: SereneMatt/pin-exact-action@v0
+  with:
+    working-directory: cloudflare
+```
+
+`working-directory` defaults to `.`. The action runs on the runner's built-in Node 24, so you don't need `actions/setup-node`.
+
+`@v0` works after the first release. You can also pin `@v0.1.0` or a commit SHA.
+
+## CLI
+
+```sh
+npx @serenematt/pin-exact-action --cwd cloudflare
+```
+
+`--cwd` defaults to `.`. Requires Node 20 or newer. No dependencies.
+
+## Release
+
+1. Bump `version` in `package.json` and commit.
+2. Tag it and push: `git tag vX.Y.Z && git push origin main vX.Y.Z`.
+3. Run the **Release** workflow on that tag: `gh workflow run release.yml --ref vX.Y.Z`. It checks the tag matches the version, runs CI, packs once and stages the tarball on npm. Then it creates the GitHub Release and moves the major tag (`v0`, `v1`, ...) to the release commit.
+4. Approve the staged version on npmjs.com (Staged Packages tab) or with `npm stage approve <stage-id>`.
+
+### Before the first release
+
+The workflow uses npm trusted publishing (OIDC) and staged publishing. There is no `NPM_TOKEN`. npm can only add a trusted publisher to a package that already exists, so publish the first version by hand:
+
+1. From your machine, logged in with 2FA: `npm publish --access public` (or `npm stage publish --access public` and approve it).
+2. On npmjs.com, open the package's Settings → Trusted publishing and add GitHub Actions: user `SereneMatt`, repository `pin-exact-action`, workflow `release.yml`, environment `npm`. Allow only `npm stage publish`.
+3. Run the Release workflow within 2 days. An unused trusted publisher configuration expires after that.
+4. Optional: in Settings → Publishing access, choose "Require two-factor authentication and disallow tokens".
+
+The first release published by hand has no GitHub Release or `v0` tag. Create them yourself, or let the next Release run do it.

package/action/index.js

@@ -0,0 +1,5 @@
+import { resolve } from 'node:path';
+import { run } from '../src/check.js';
+
+const workspace = process.env.GITHUB_WORKSPACE || process.cwd();
+process.exitCode = run(resolve(workspace, process.env['INPUT_WORKING-DIRECTORY'] || '.'));

package/action.yml

@@ -0,0 +1,14 @@
+name: Pin Exact
+description: Fail when package.json dependencies are not exact pins or the Node versions drift from your version file
+author: SereneMatt
+branding:
+  icon: lock
+  color: green
+inputs:
+  working-directory:
+    description: Directory containing package.json and the Node version file
+    required: false
+    default: .
+runs:
+  using: node24
+  main: action/index.js

package/bin/pin-exact-action.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { run } from '../src/check.js';
+
+let cwd;
+try {
+  ({ values: { cwd } } = parseArgs({ options: { cwd: { type: 'string', default: '.' } } }));
+} catch (error) {
+  console.log(`error: ${error.message}`);
+  process.exit(1);
+}
+
+process.exitCode = run(resolve(cwd));

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@serenematt/pin-exact-action",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Fail CI when package.json versions are not pinned or Node versions drift",
+  "type": "module",
+  "bin": {
+    "pin-exact-action": "bin/pin-exact-action.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action",
+    "action.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ci",
+    "github-action",
+    "dependencies",
+    "pin",
+    "exact-versions",
+    "tool-versions",
+    "node",
+    "engines"
+  ],
+  "author": "SereneMatt",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SereneMatt/pin-exact-action.git"
+  },
+  "homepage": "https://github.com/SereneMatt/pin-exact-action#readme",
+  "bugs": {
+    "url": "https://github.com/SereneMatt/pin-exact-action/issues"
+  }
+}

package/src/check.js

@@ -0,0 +1,150 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+// https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+const EXACT =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+// Not registry ranges: they point inside the repo or at a pnpm catalog.
+const LOCAL = /^(workspace|file|link|catalog):/;
+
+export const isExact = (version) => typeof version === 'string' && EXACT.test(version);
+
+export function isPinned(spec) {
+  if (typeof spec !== 'string') return false;
+  if (LOCAL.test(spec)) return true;
+  if (spec.startsWith('npm:')) return isExact(spec.slice(spec.lastIndexOf('@') + 1));
+  return isExact(spec);
+}
+
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8'));
+const readText = (file) => (existsSync(file) ? readFileSync(file, 'utf8') : null);
+const lines = (text) =>
+  text
+    .split('\n')
+    .map((line) => line.replace(/#.*/, '').trim())
+    .filter(Boolean);
+
+function fromToolVersions(text) {
+  for (const line of lines(text)) {
+    const [tool, version] = line.split(/\s+/);
+    if (tool === 'node' || tool === 'nodejs') return version ?? '';
+  }
+}
+
+function fromMise(text) {
+  let inTools = false;
+  for (const line of lines(text)) {
+    if (line.startsWith('[')) inTools = line === '[tools]';
+    const match = inTools && line.match(/^["']?(node|nodejs)["']?\s*=\s*(.*)$/);
+    if (match) return match[2].match(/^\[?\s*["']([^"']*)["']/)?.[1] ?? match[2];
+  }
+}
+
+function fromDevEngines(runtime) {
+  const entries = Array.isArray(runtime) ? runtime : [runtime];
+  const node = entries.find((entry) => entry?.name === 'node');
+  if (node) return String(node.version ?? '');
+}
+
+// Fixed order. The first source that names a Node version wins.
+function findNodeVersion(dir, pkg) {
+  const sources = [
+    ['.tool-versions', () => fromToolVersions(readText(join(dir, '.tool-versions')) ?? '')],
+    ['mise.toml', () => fromMise(readText(join(dir, 'mise.toml')) ?? '')],
+    ['.mise.toml', () => fromMise(readText(join(dir, '.mise.toml')) ?? '')],
+    ['.nvmrc', () => lines(readText(join(dir, '.nvmrc')) ?? '')[0]],
+    ['.node-version', () => lines(readText(join(dir, '.node-version')) ?? '')[0]],
+    ['package.json', () => pkg.volta?.node, 'volta.node'],
+    ['package.json', () => pkg.devEngines?.runtime && fromDevEngines(pkg.devEngines.runtime), 'devEngines.runtime'],
+  ];
+  for (const [file, read, label = file] of sources) {
+    const version = read();
+    if (version !== undefined) return { file, label, version: String(version).replace(/^v/, '') };
+  }
+}
+
+function overrideFindings(value, path, add) {
+  if (typeof value === 'object' && value !== null) {
+    for (const [key, nested] of Object.entries(value)) {
+      overrideFindings(nested, key === '.' ? path : `${path}.${key}`, add);
+    }
+  } else if (!(typeof value === 'string' && value.startsWith('$')) && !isPinned(value)) {
+    // `$name` points at the direct dependency's spec, which is checked on its own.
+    add(`${path}@${value}`);
+  }
+}
+
+// Returns { errors: [{ file, message }], notes: [string], node: { version, label } | null }.
+export function check(dir) {
+  const errors = [];
+  const notes = [];
+  const pkgFile = join(dir, 'package.json');
+  const error = (file, message) => errors.push({ file: join(dir, file), message });
+
+  let pkg;
+  try {
+    pkg = readJson(pkgFile);
+  } catch (err) {
+    errors.push({ file: pkgFile, message: `cannot read package.json: ${err.message}` });
+    return { errors, notes, node: null };
+  }
+
+  const loose = (entry) => error('package.json', `${entry} is not an exact version`);
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    for (const [name, spec] of Object.entries(pkg[field] ?? {})) {
+      if (!isPinned(spec)) loose(`${field}.${name}@${spec}`);
+    }
+  }
+  overrideFindings(pkg.overrides ?? {}, 'overrides', loose);
+  overrideFindings(pkg.resolutions ?? {}, 'resolutions', loose);
+  overrideFindings(pkg.pnpm?.overrides ?? {}, 'pnpm.overrides', loose);
+
+  const source = findNodeVersion(dir, pkg);
+  if (!source) {
+    notes.push('no Node version source found; skipped the @types/node and engines.node checks');
+    return { errors, notes, node: null };
+  }
+  const { file, label, version } = source;
+  if (!isExact(version)) {
+    error(file, `Node version "${version}" from ${label} is not exact; the Node checks need an exact X.Y.Z version`);
+    return { errors, notes, node: null };
+  }
+
+  const from = `(node ${version} from ${label})`;
+  const major = version.split('.')[0];
+  for (const field of ['dependencies', 'devDependencies']) {
+    const types = pkg[field]?.['@types/node'];
+    if (types === undefined) continue;
+    const typesMajor = String(types).slice(String(types).lastIndexOf('@') + 1).match(/\d+/)?.[0];
+    if (typesMajor !== major) {
+      error('package.json', `${field}.@types/node@${types} must have the same major as Node ${from}`);
+    }
+  }
+
+  const engines = pkg.engines?.node;
+  if (typeof engines !== 'string' || engines.replace(/\s+/g, '') !== `>=${version}`) {
+    error('package.json', `engines.node must be ">=${version}" ${from}, found ${JSON.stringify(engines ?? null)}`);
+  }
+
+  return { errors, notes, node: { version, label } };
+}
+
+const escapeData = (s) => s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+const escapeProperty = (s) => escapeData(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
+
+// Prints every finding, then returns the exit code.
+export function run(dir, { env = process.env, log = console.log } = {}) {
+  const { errors, notes, node } = check(dir);
+  const actions = env.GITHUB_ACTIONS === 'true';
+  const base = env.GITHUB_WORKSPACE || process.cwd();
+  const shown = (file) => relative(base, file).split('\\').join('/') || file;
+
+  for (const note of notes) log(actions ? `::notice::${escapeData(note)}` : `note: ${note}`);
+  for (const { file, message } of errors) {
+    log(actions ? `::error file=${escapeProperty(shown(file))}::${escapeData(message)}` : `error: ${shown(file)}: ${message}`);
+  }
+  if (errors.length) return 1;
+  log(`OK: ${shown(join(dir, 'package.json'))}${node ? ` (node ${node.version} from ${node.label})` : ''}`);
+  return 0;
+}