[patchstackdave]

Tests the published package against real consumers, and corrects two defects in what it publishes.

Stacked on #189 until that merges; the rebase is noted at the end.

What the check covers

Every other test in this repository exercises the source, or dist/ from within the repository. Neither reaches the questions a consumer's build asks, because the tarball's metadata answers them: which file an exports condition resolves to, which declarations TypeScript reads beside it, whether files omits something, whether the bin runs as the shim npm installs. A defect there leaves the suite green while nothing can import the package.

scripts/compat-matrix.mjs packs a tarball and installs it into isolated consumer projects, one per consumption path:

shape	holds open
esm-js	ESM import
cjs-js	CommonJS require
esm-ts	ESM TypeScript compilation
cjs-ts	CommonJS TypeScript compilation
cjs-ts-no-node-types	the public declarations compile without @types/node
cli	the installed bin runs
encapsulation	nothing outside exports resolves

It runs the same way locally (npm run test:consumers) and in CI across npm, pnpm, Yarn Classic, Yarn Berry and Bun at exact versions, with a Windows job for the .cmd launcher. The Node 18/20/22/24 matrix is unchanged.

Two corrections to what is published

Types are per-condition. exports routes import to dist/index.d.ts and require to dist/index.d.cts, with default last. TypeScript reads the declarations beside the condition it resolved: an ESM .d.ts under require tells it the target is an ES module, and it refuses the require with TS1479 even though the runtime works. ./protect now ships a .d.cts for the same reason.

The public declarations no longer name NodeJS.ProcessEnv. @types/node is not a dependency of this package, so nothing in its public surface may require it; an EnvLike alias describes the environment structurally. process.env satisfies it, and so does a plain object.

Controls

Each shape asserts a positive before asserting an absence. encapsulation resolves the public root first and fails if that does not work — otherwise every assertion in it is an expected failure and the case passes when the package is absent.

cjs-ts-no-node-types is the only TypeScript fixture without @types/node installed, which is what makes it able to hold that constraint.

A packaging test asserts that every file the export map names is inside files and present after a build. A map can name a path the build does not produce, and that surfaces as "cannot find module" in a consumer's project.

Windows

execFileSync creates a process directly and a batch file is not an executable image, so the interpreter is invoked explicitly: cmd /d /s /c "<line>" with windowsVerbatimArguments. /s strips exactly the outermost quote pair; the verbatim flag stops Node re-escaping a correct line.

The command word is quoted only when it is a path. A bare name must not be: npm is npm.cmd, resolved through PATH and PATHEXT, and its shim locates its own installation with %~dp0. Arguments are always quoted, because Windows temp and workspace paths contain spaces.

Managers

Exact versions — npm 11.6.0, pnpm 9.15.4, Yarn 1.22.22, Yarn 4.18.0, Bun 1.2.21 — and the version on PATH is printed before any fixture runs. Berry comes from @yarnpkg/cli-dist, which is the distribution carrying the yarn binary at 4.x; the yarn package on npm stops at 2.x. Berry treats a fixture as its own project only when a yarn.lock is present, so the script writes an empty one; that is harmless under Classic.

Build order

CI builds before it tests. Several tests assert against dist/, and one returns early and green when it is absent, so the check that the built edge bundle carries no static Node-builtin import was not being made.

Verified

All seven shapes pass locally under npm 11.6.0, Yarn Classic 1.22.22, Yarn Berry 4.18.0 and Bun. Full suite 1710 passed, 7 skipped. Windows is exercised by CI only.

Rebase

This branch carries #189's commits, so the two do not have separate review or rollback boundaries. Once #189 merges, this is rebuilt from the new main with only its own three commits and the matrix rerun.

🤖 Generated with Claude Code

[coderbuds]

Comprehensive consumer packaging validation with clear, well-documented tests and CI integration.

🎯 Quality: 77% Good · 📦 Size: Large — consider splitting if possible

🛡️ Standards: no pre-flight fit check ran for this change — wire assess-change-fit into your coding agents to catch size before opening.

📈 This month: Your 147th PR — above team average · Averaging Good

_{See how your team is trending →}

[patchstackdave]

/review