@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/templates/packs/publishing/files/.changeset/README.md

@@ -0,0 +1,25 @@
+# Changesets
+
+A change to this package's user-visible behavior lands with a changeset: run
+`pnpm changeset`, pick the bump, and commit the generated file with the PR.
+Merging to the release branch opens (or updates) a
+`chore(release): version packages` PR; merging that publishes to npm. See
+`.github/workflows/release.yml`.
+
+This pack ships the `changeset`/`version:packages` scripts and the release
+workflow, but not the `@changesets/cli` package itself -- the wiring
+contract a pack installs through never edits `package.json`'s
+`dependencies`/`devDependencies` (see `templates/packs/README.md`). Add it
+by hand once, **before the first `pnpm verify`, not just before the first
+real release** -- both scripts reference the `changeset` binary, and
+`knip`'s unlisted-binaries check correctly fails until it actually resolves:
+
+```
+pnpm add -D @changesets/cli
+```
+
+`config.json`'s `changelog` is the plain built-in generator
+(`@changesets/cli/changelog`), which needs no further setup. Swap in
+`@changesets/changelog-github` (and its `repo` option) once this project's
+GitHub repository is known, for changelog entries that link back to the
+originating PR/commit.

package/templates/packs/publishing/files/.changeset/config.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main"
+}

package/templates/packs/publishing/files/.github/release-tools/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "release-tools",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Pins the exact npm version the release workflow's publish job installs, so the pin is verified by a committed lockfile's integrity hash rather than a bare version string in YAML.",
+  "dependencies": {
+    "npm": "12.2.0"
+  }
+}

package/templates/packs/publishing/files/.github/workflows/release.yml

@@ -0,0 +1,295 @@
+# SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+# SPDX-License-Identifier: NOASSERTION
+
+name: Release
+
+# What this does: on every push to `main`, this workflow either opens a PR
+# that bumps the package version and changelog, or -- once that PR has
+# merged -- packs and publishes the package to npm. It runs
+# [Changesets](https://github.com/changesets/changesets), the tool this
+# project uses to track pending releases (each PR that changes the
+# package's user-facing behavior adds a small Markdown file under
+# `.changeset/` describing the change and its version bump; this workflow
+# reads those files to decide what to do next).
+#
+# The flow, one job each:
+#   1. select-mode  reads the repo and decides: "version", "publish", or "none"
+#   2. version      opens or updates the "Version Packages" PR
+#   3. pack         builds, runs every gate, and packs the tarball
+#   4. publish      uploads that tarball to npm via trusted publishing
+#
+# "Trusted publishing" is npm's passwordless publish mechanism: instead of a
+# long-lived npm token stored as a secret, this workflow proves its identity
+# to npm via OIDC (OpenID Connect -- a short-lived, cryptographically signed
+# token GitHub Actions mints for the running job, which npm verifies against
+# the trusted-publisher config for this exact repo and workflow file). This
+# is the shape the changesets docs recommend for trusted publishing: the one
+# job that holds the OIDC token (`publish`, via `id-token: write`) never runs
+# build, test, or repo-script code -- it only runs the changesets CLI and the
+# pnpm shim below, with `--ignore-scripts`. `pack` holds nothing beyond
+# `contents: read`.
+#
+# "Staged" publish (vs. a "direct" one) means `npm stage publish` uploads the
+# tarball and creates the version, but it isn't installable yet until a
+# maintainer separately approves it with 2FA (`npm stage approve`) -- npm's
+# own stronger default over a direct `npm publish`, which would make the
+# version live immediately. "Provenance" is the signed, publicly verifiable
+# record npm attaches to a trusted-published package, linking it back to the
+# exact commit and workflow run that built it.
+#
+# npm trusted publishers are configured per package, against this exact file
+# name (`release.yml`, not a path) -- see this pack's adoptNotes for the
+# one-time setup this depends on.
+on:
+  push:
+    branches: [main]
+
+# Reset, then grant per job.
+permissions: {}
+
+# Releases must not be cancelled midway: a half-published release is worse
+# than a queued one.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  select-mode:
+    name: Select mode
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      mode: ${{ steps.select-mode.outputs.mode }}
+      publish-plan-artifact-id: ${{ steps.select-mode.outputs.publish-plan-artifact-id }}
+    permissions:
+      contents: read # actions/checkout
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      # `.node-version` is the single Node pin, so this file must never carry
+      # a literal version (see check-node-version.mjs). No package-manager
+      # cache anywhere in this file: a restored cache is an input an attacker
+      # can poison, and these jobs are the ones that publish.
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .node-version
+          package-manager-cache: false
+      - run: pnpm install --frozen-lockfile
+      - id: select-mode
+        uses: changesets/action/select-mode@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
+
+  version:
+    name: Open version PR
+    needs: select-mode
+    if: needs.select-mode.outputs.mode == 'version'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read # actions/checkout; see below for who does the actual writing
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .node-version
+          package-manager-cache: false
+      - run: pnpm install --frozen-lockfile
+      # If this project's branch protection requires status checks on every
+      # PR with no bypass actor, a PR opened with the default GITHUB_TOKEN
+      # never triggers `pull_request`-event workflows (GitHub's own
+      # anti-recursion rule) and could therefore never merge -- this mints a
+      # short-lived token from a GitHub App installed on this repo instead.
+      # See this pack's adoptNotes: if that's not this project's situation,
+      # drop this step and pass `github-token: ${{ secrets.GITHUB_TOKEN }}`
+      # to the version step below instead. The App needs only
+      # `contents: write` and `pull-requests: write`; its token auto-expires
+      # in an hour and this action revokes it when the job ends.
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          # Both created as repo secrets (`gh secret set`), not vars: the
+          # client ID isn't sensitive on its own, but keeping both next to
+          # each other avoids a second place to remember to update.
+          client-id: ${{ secrets.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - uses: changesets/action/version@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: pnpm version:packages
+          commit-message: "chore(release): version packages"
+          pr-title: "chore(release): version packages"
+
+  pack:
+    name: Verify and pack
+    needs: select-mode
+    if: needs.select-mode.outputs.mode == 'publish'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    outputs:
+      pack-dir-artifact-id: ${{ steps.pack.outputs.pack-dir-artifact-id }}
+    permissions:
+      contents: read # actions/checkout
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .node-version
+          package-manager-cache: false
+      - run: pnpm install --frozen-lockfile
+      # The whole gate, before a tarball exists. `pnpm verify` is one full
+      # run of every group, the same steps ci.yml spreads across its lanes.
+      - run: pnpm verify
+      # Deliberately not one of pnpm verify's own steps: package.json's
+      # version only changes in the version PR, so this check would fail
+      # every ordinary push between releases (the version it's checking is
+      # always the one already published) if it ran there. This is the one
+      # place "is this version about to collide with an already-published
+      # one" is the right question to ask -- right before packing it.
+      - run: node bin/check-publish-version.mjs
+      - id: pack
+        uses: changesets/action/pack@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
+        with:
+          publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }}
+
+  publish:
+    name: Publish to npm
+    needs: pack
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Gates the git tag, the GitHub Release, and `npm stage publish` behind a
+    # required reviewer -- without this, all three already exist by the time
+    # a maintainer even sees there's a staged version to approve with
+    # `npm stage approve`. The environment (created once, by hand, via
+    # `gh api` -- see this pack's adoptNotes) has no branch restriction
+    # beyond the release branch and no wait timer: it exists to require a
+    # person, not to add a delay.
+    environment: npm-publish
+    permissions:
+      contents: write # changesets/action/publish pushes tags and creates GitHub Releases
+      id-token: write # npm trusted publishing (OIDC) and provenance
+      attestations: write # actions/attest-build-provenance on the packed tarball
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .node-version
+          package-manager-cache: false
+      # Only the changesets CLI is needed here, not any package's lifecycle scripts.
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      # `npm stage publish` needs npm >= 11.15.0. The pinned npm (12.2.0)
+      # declares engines Node ^22.22.2 || ^24.15.0 || >=26. .node-version's
+      # `24` meets that on GitHub-hosted runners, whose cached 24.x is recent;
+      # a self-hosted runner with an older cached 24.x does not. Pinned to an
+      # exact version, not a range or `latest`: this job holds the OIDC token,
+      # and an unpinned package-manager install is exactly what OpenSSF
+      # Scorecard's Pinned-Dependencies check flags. `.github/release-tools/`
+      # pins the exact tarball via its committed lockfile's integrity hash, and
+      # `npm ci` verifies the install against it -- bumping the pin is then
+      # a normal reviewed PR (a lockfile diff), not a hand-edited version
+      # string.
+      - run: npm ci --ignore-scripts --prefix .github/release-tools
+      - run: echo "$GITHUB_WORKSPACE/.github/release-tools/node_modules/.bin" >> "$GITHUB_PATH"
+      # changesets publishes through `pnpm publish` in a pnpm-managed
+      # project, and pnpm 12's native publish is rejected by npmjs.com's OIDC
+      # exchange (403 "OIDC permission denied"). This puts a `pnpm` ahead of
+      # the real one that forwards everything except `publish`, which goes
+      # to `npm stage publish` instead (see bin/pnpm-publish-shim.mjs -- the
+      # trusted publisher only allows staged publishing, npm's own default
+      # since 2026-09-03; a direct `npm publish` gets the same 403 for a
+      # different reason). Remove both once pnpm's own publish authenticates.
+      - name: Route publish through the npm CLI
+        run: |
+          shim_dir="$RUNNER_TEMP/pnpm-shim"
+          mkdir -p "$shim_dir"
+          printf '#!/bin/sh\nexport PNPM_SHIM_DIR=%s\nexec node "%s/bin/pnpm-publish-shim.mjs" "$@"\n' \
+            "$shim_dir" "$GITHUB_WORKSPACE" > "$shim_dir/pnpm"
+          chmod +x "$shim_dir/pnpm"
+          echo "$shim_dir" >> "$GITHUB_PATH"
+      - uses: changesets/action/publish@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
+        id: publish
+        with:
+          pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
+      # npm provenance alone already meets most supply-chain "signed
+      # releases" criteria (a Sigstore-backed, OIDC-issued attestation with
+      # no long-lived key). These three steps add a second, independent
+      # proof on the GitHub Release itself: the exact tarball `pack` already
+      # built and tested, fetched back out of its own artifact (never
+      # rebuilt), attested, and attached. `if:` guards all three on
+      # `publish` actually having published -- `select-mode` only decides
+      # the job should run, not that a version was new.
+      # `continue-on-error: true` on all three: `npm stage publish` has
+      # already succeeded by this point, so a failure here (a transient
+      # download error, say) must never fail the whole job and leave a
+      # staged, tagged, unreleased version behind -- this block is
+      # best-effort supplementary evidence, the same status as the
+      # "List pending stages" step below.
+      - name: Fetch the packed tarball back out of the pack job's artifact
+        if: steps.publish.outputs.published == 'true'
+        continue-on-error: true
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          artifact-ids: ${{ needs.pack.outputs.pack-dir-artifact-id }}
+          path: .release-artifacts
+          merge-multiple: true
+      - name: Attest build provenance for the published tarball
+        if: steps.publish.outputs.published == 'true'
+        continue-on-error: true
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          # actions/attest-build-provenance's own glob support (not the
+          # shell's), so `**` resolves correctly regardless of `globstar`.
+          subject-path: .release-artifacts/**/*.tgz
+      - name: Attach the attested tarball to the GitHub Release
+        if: steps.publish.outputs.published == 'true'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # `changeset pack` writes into <outDir>/packages/*.tgz, not
+          # <outDir>/*.tgz -- found by path, not a bare shell glob the
+          # default (non-globstar) bash would pass through unexpanded on
+          # no match.
+          tarball="$(find .release-artifacts -name '*.tgz' -print -quit)"
+          if [ -z "$tarball" ]; then
+            echo "no packed tarball found under .release-artifacts/ -- skipping the release-asset upload" >&2
+            exit 0
+          fi
+          name="$(node -p "require('./package.json').name")"
+          version="$(node -p "require('./package.json').version")"
+          # changesets names the tag `v<version>` for a single-package
+          # repository (its "root" tool, which is what this baseline is: no
+          # `packages:` in pnpm-workspace.yaml) and `<name>@<version>` once
+          # the repository becomes a workspace. Upload to whichever one
+          # actually has a Release rather than guessing.
+          tag=""
+          for candidate in "v${version}" "${name}@${version}"; do
+            if gh release view "$candidate" --repo "${{ github.repository }}" >/dev/null 2>&1; then
+              tag="$candidate"
+              break
+            fi
+          done
+          if [ -z "$tag" ]; then
+            echo "cannot attach the tarball: no GitHub Release found for v${version} or ${name}@${version} -- failing this best-effort step" >&2
+            exit 1
+          fi
+          gh release upload "$tag" \
+            "$tarball" --clobber --repo "${{ github.repository }}"
+      # Staging succeeds unattended; going live needs a maintainer's 2FA
+      # (`npm stage approve <id>`, on the CLI or npmjs.com -- never
+      # automatable, by design). Best-effort convenience only: this job
+      # never logs in with a token (it publishes purely via the OIDC
+      # exchange scoped to the publish call itself), so `npm stage list` may
+      # print nothing useful -- `|| true` means that possibility never fails
+      # the job.
+      - name: List pending stages (best effort)
+        if: always()
+        run: npm stage list --package "$(node -p "require('./package.json').name")" || true

package/templates/packs/publishing/files/REUSE.toml

@@ -0,0 +1,28 @@
+# REUSE Software (https://reuse.software) annotations for files that cannot,
+# or by this project's own convention should not, carry an inline SPDX
+# header -- see bin/check-license-headers.mjs for the gate that gap-checks
+# this file's globs against that expectation.
+version = 1
+SPDX-PackageName = "__PROJECT_NAME__"
+
+# Data files, prose, and dotfiles with no comment syntax of their own to
+# carry a header in. SPDX-License-Identifier is left as NOASSERTION -- edit
+# both this block and bin/check-license-headers.mjs's headerLines() once
+# this project's actual license is decided (a LICENSE file, if one exists,
+# is the source of truth).
+[[annotations]]
+path = [
+  "**/*.json",
+  "**/*.md",
+  "pnpm-lock.yaml",
+  ".node-version",
+  ".npmrc",
+  ".gitignore",
+  ".prettierignore",
+  "LICENSE",
+  "REUSE.toml",
+  ".gitleaks.toml",
+  ".worktreeinclude",
+]
+SPDX-FileCopyrightText = "Copyright the __PROJECT_NAME__ contributors"
+SPDX-License-Identifier = "NOASSERTION"

package/templates/packs/publishing/files/bin/check-dts-deps.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the __PROJECT_NAME__ contributors
+// SPDX-License-Identifier: NOASSERTION
+
+/**
+ * Checks that every package a published `.d.ts` file imports by bare
+ * specifier is declared in `package.json`'s `dependencies` (or
+ * `peerDependencies`) -- not only `devDependencies`, and not left
+ * undeclared entirely. A type import from a `devDependencies`-only package
+ * type-checks fine inside this repo (the dev dependency is installed here)
+ * but breaks a consumer's own `tsc`, since npm never installs
+ * `devDependencies` for a package's dependents. `publint`/`attw` don't catch
+ * this specific case, which is why it's a separate gate.
+ *
+ * Also honors `/// <reference types="x" />` directives (a common way a
+ * `.d.ts` pulls in ambient types), which the plain import/export scan below
+ * would miss entirely since triple-slash directives are stripped as
+ * comments before that scan runs. `types="node"` is exempt: `@types/node`
+ * is a near-universal ambient dev convenience most consumers already carry
+ * on their own, not something this package should have to declare as a
+ * real dependency just because it uses a Node builtin type.
+ *
+ * A declared package satisfies either its own name or its `@types/<name>`
+ * counterpart (`@types/<scope>__<name>` for a scoped `@scope/<name>`) --
+ * many packages only ship (or only need) the `@types/*` package, not the
+ * runtime one.
+ *
+ * A no-op (`checked: 0`, exit 0), not a failure, when:
+ * - `package.json` has `private: true` (the baseline's own default) -- a
+ *   private package publishes no `.d.ts` files to anyone.
+ * - `dist/` does not exist yet (this step runs in the `build` verify group,
+ *   after the `build` step itself -- see bin/lib/verify-steps.mjs).
+ * - `dist/` exists but contains no `.d.ts`/`.d.mts`/`.d.cts` file -- if this
+ *   package is NOT private and really does mean to publish, this is worth a
+ *   second look (a build that emits nothing, or a `tsconfig`/`exports`
+ *   pointing declarations somewhere other than `dist/`), which the log
+ *   message below says explicitly rather than only "skipping".
+ */
+import process from "node:process";
+import { isBuiltin } from "node:module";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+const DTS_EXTENSIONS = new Set([".d.ts", ".d.mts", ".d.cts"]);
+
+function dtsExtensionOf(fileName) {
+  for (const ext of DTS_EXTENSIONS) {
+    if (fileName.endsWith(ext)) return ext;
+  }
+  return undefined;
+}
+
+/** Every `.d.ts`/`.d.mts`/`.d.cts` file under `dir`, recursively. */
+function listDtsFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listDtsFiles(full));
+    } else if (dtsExtensionOf(entry.name) !== undefined) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Every `/// <reference types="x" />` directive's `x`, extracted BEFORE
+ * comment-stripping (a triple-slash directive is syntactically a line
+ * comment, so it would otherwise vanish along with ordinary comments).
+ */
+function referenceTypeNamesIn(content) {
+  const names = new Set();
+  const pattern = /^\/\/\/\s*<reference\s+types\s*=\s*["']([^"']+)["']\s*\/>/gm;
+  for (const match of content.matchAll(pattern)) {
+    const name = match[1];
+    if (name !== undefined) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * A conservative comment strip: block comments unconditionally, and a line
+ * comment only when the `//` isn't immediately preceded by `:` (so a
+ * `"https://example.com"` string literal survives). Not a full tokenizer --
+ * `.d.ts` output is machine-generated by `tsc`, not hand-written prose, so
+ * this heuristic is proportionate to what actually shows up there.
+ */
+function stripComments(content) {
+  return content
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+/**
+ * Every bare-specifier import/export/`import()` target in `content` --
+ * a deliberately simple regex scan, not a TypeScript AST parse. A relative
+ * specifier (starting with `.` or `/`) is never a package dependency, so
+ * only a bare specifier is returned. `content` should already have comments
+ * stripped (see {@link stripComments}), or a specifier-shaped string inside
+ * a doc comment (an `@example` importing from some other package, say)
+ * would be flagged as a real dependency.
+ */
+function bareSpecifiersIn(content) {
+  const specifiers = new Set();
+  const pattern =
+    /(?:from|import)\s*\(?\s*["']([^"']+)["']|require\(\s*["']([^"']+)["']\s*\)/g;
+  for (const match of content.matchAll(pattern)) {
+    const specifier = match[1] ?? match[2];
+    if (
+      specifier !== undefined &&
+      !specifier.startsWith(".") &&
+      !specifier.startsWith("/")
+    ) {
+      specifiers.add(specifier);
+    }
+  }
+  return specifiers;
+}
+
+/** A bare specifier's package name: `@scope/name` keeps its scope, `name/sub/path` is trimmed to `name`. */
+export function packageNameOf(specifier) {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return parts.slice(0, 2).join("/");
+  }
+  return parts[0];
+}
+
+/** The `@types/*` package name that would satisfy a declared-dependency check for `packageName`. */
+function typesPackageNameFor(packageName) {
+  if (packageName.startsWith("@")) {
+    const scoped = packageName.slice(1).split("/");
+    return `@types/${scoped[0]}__${scoped[1] ?? ""}`;
+  }
+  return `@types/${packageName}`;
+}
+
+/**
+ * @param {Map<string, string>} dtsFiles path -> content
+ * @param {{ dependencies?: Record<string, string>, peerDependencies?: Record<string, string> }} pkg
+ * @returns {{ packageName: string, files: string[] }[]} every package name
+ * referenced by a `.d.ts` import (or `/// <reference types="..." />`) that
+ * isn't declared as a real dependency (by its own name or its `@types/*`
+ * counterpart), each with the file(s) that reference it.
+ */
+export function findUndeclaredTypeDeps(dtsFiles, pkg) {
+  const declared = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+  ]);
+  const byPackage = new Map();
+
+  const record = (path, packageName) => {
+    if (packageName === pkg.name) return;
+    if (isBuiltin(packageName)) return;
+    if (
+      declared.has(packageName) ||
+      declared.has(typesPackageNameFor(packageName))
+    )
+      return;
+    const files = byPackage.get(packageName) ?? [];
+    files.push(path);
+    byPackage.set(packageName, files);
+  };
+
+  for (const [path, rawContent] of dtsFiles) {
+    for (const referenceName of referenceTypeNamesIn(rawContent)) {
+      if (referenceName === "node") continue;
+      record(path, referenceName);
+    }
+    for (const specifier of bareSpecifiersIn(stripComments(rawContent))) {
+      record(path, packageNameOf(specifier));
+    }
+  }
+
+  return [...byPackage.entries()].map(([packageName, files]) => ({
+    packageName,
+    files,
+  }));
+}
+
+function main() {
+  const pkgPath = join(repoRoot, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+
+  if (pkg?.private === true) {
+    console.log("check-dts-deps: package.json is private -- skipping");
+    return;
+  }
+
+  const distDir = join(repoRoot, "dist");
+  const dtsPaths = listDtsFiles(distDir);
+  if (dtsPaths.length === 0) {
+    console.log(
+      "check-dts-deps: no dist/**/*.d.ts found -- skipping (if this package means to publish " +
+        'type declarations, check the build output path and package.json\'s "types"/"exports")',
+    );
+    return;
+  }
+
+  const dtsFiles = new Map(
+    dtsPaths.map((path) => [path, readFileSync(path, "utf8")]),
+  );
+  const undeclared = findUndeclaredTypeDeps(dtsFiles, pkg);
+
+  if (undeclared.length > 0) {
+    console.error(
+      `check-dts-deps: ${undeclared.length} package(s) are referenced by a published .d.ts file ` +
+        "but are not declared in dependencies/peerDependencies (a devDependencies-only or " +
+        "undeclared package breaks a consumer's own typecheck):",
+    );
+    for (const { packageName, files } of undeclared) {
+      console.error(`  ${packageName} (from ${files.join(", ")})`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    `check-dts-deps: ok -- checked ${dtsPaths.length} declaration file(s)`,
+  );
+}
+
+if (
+  process.argv[1] !== undefined &&
+  fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+) {
+  main();
+}