@anizoptera/publish-clean 0.9.1 → 0.11.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.
Files changed (3) hide show
  1. package/README.md +326 -57
  2. package/dist/cli.js +48 -1384
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @anizoptera/publish-clean
2
2
 
3
- Publish npm packages with a clean `package.json` and checks for unwanted files,
4
- unresolved workspace dependencies and missing entry points.
3
+ Cleans and helps to publish npm packages properly with a clean `package.json` (no unnecessary entries),
4
+ verified `exports`, checks for unwanted files, unresolved workspace dependencies and missing entry points.
5
5
 
6
6
  [![npm version](https://img.shields.io/npm/v/@anizoptera/publish-clean?label=npm)](https://www.npmjs.com/package/@anizoptera/publish-clean)
7
7
  [![Signed provenance](https://img.shields.io/badge/provenance-signed-2ea44f?logo=npm&logoColor=white)](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
@@ -10,23 +10,133 @@ unresolved workspace dependencies and missing entry points.
10
10
  [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
11
11
  [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
12
12
 
13
+ **TL;DR** — pack once, clean and check *that* tarball, upload *those* bytes. It never repacks, so
14
+ what was verified is exactly what the registry stores and what provenance signs.
15
+
16
+ ```text
17
+ pnpm pack
18
+ │
19
+ ▼
20
+ rewrite package.json inside the tarball
21
+ │
22
+ ▼
23
+ re-read it from disk and check it
24
+ │
25
+ ├─▶ unrepaired, and it leaks
26
+ │ or breaks a consumer
27
+ │ └─▶ exit 1
28
+ │
29
+ └─▶ repaired, or only reported
30
+ └─▶ npm publish <that exact file>
31
+ ```
32
+
33
+ ```sh
34
+ pnpm exec publish-clean verify # all checks, uploads nothing
35
+ pnpm exec publish-clean --dry-run # checks, prints file list and manifest
36
+ pnpm exec publish-clean -- --provenance --access public # check, then publish
37
+ ```
38
+
39
+ | What you get | How |
40
+ | --- | --- |
41
+ | [Broken packages stop here](#what-it-checks) | Declared entry points that resolve to nothing, `exports` conditions in an order that loses a consumer its target, `require` branches resolving to ESM, names two filesystems read as one file, `bin` without a shebang, `workspace:`/`catalog:` specs left unresolved. |
42
+ | [Credential files can't ship](#a-packed-secret-is-already-leaked) | A packed `.env`, `.npmrc`, `.pem`/`.key`/keystore or SSH key aborts the run. No flag waives it, and it is not stripped for you: a stripped secret has still leaked and still needs rotating. Matched by file name, so a credential hardcoded inside your source is not caught. |
43
+ | [No dead weight](#dead-weight-ships-forever) | `devDependencies`, `files`, `packageManager`, workspace and catalog config, and tool config blocks (`jest`, `eslint`, `prettier`, `turbo`, …) leave the published manifest. So does the whole `scripts` block, unless it holds an install or `prepare` hook consumers actually run. Packed files nothing references are reported. |
44
+ | [Checked bytes = published bytes](#what-this-buys-for-provenance) | The manifest is rewritten inside pnpm's own tarball and that file is uploaded. A pipeline that repacks after checking signs bytes nothing verified. |
45
+ | [Rules measured, not guessed](#rules-are-measured-not-guessed) | Every rule and every tolerance was measured against thousands of installed published packages first. Equality alone on declared paths refused 373 of 5192; a fixed `exports` order refused 97 of 3674. |
46
+ | [Nothing new to trust](#install) | One JavaScript file, zero runtime dependencies. It runs on the path that handles your registry token, so a transitive package would be unaudited code next to a live credential. |
47
+ | [Check without publishing](#checking-every-pull-request) | `verify` gates pull requests and works on `private: true` packages. Exit 1 on failure, findings on stderr. |
48
+
49
+ It edits nothing outside the tarball, and fixes only what the packed files settle without guessing.
50
+ One run lists every defect instead of stopping at the first. What it repaired does not fail the run;
51
+ what it could not repair does. Every judgement call has a flag to waive it. A leaked credential
52
+ does not.
53
+
54
+ ## Why
55
+
56
+ Publishing is the one step you cannot take back. npm lets you unpublish within 72 hours only if no
57
+ other package depends on yours. After that you also need fewer than 300 weekly downloads and a
58
+ single maintainer. The version number is gone either way:
59
+ [npm's policy](https://docs.npmjs.com/policies/unpublish) is that "once `package@version` has been
60
+ used, you can never use it again". You fix a bad release by publishing another one.
61
+
62
+ The defects that reach consumers are the ones your own machine cannot show you:
63
+
64
+ | Defect | Your machine | Consumer installs | Consumer uses it |
65
+ | ------ | ------------ | ----------------- | ---------------- |
66
+ | Two packed names differing only in letter case | fine (case-sensitive disk) | **reports success** | file silently missing |
67
+ | `bin` file with no shebang | fine (you run `node file.js`) | fine | `exec format error` |
68
+ | Package imports itself through a subpath `exports` hides | fine (resolves by path in your repo) | fine | cannot resolve |
69
+ | `./Utils.js` imported as `./utils.js` | fine on macOS | fine | fails on Linux |
70
+ | `types` pointing at JavaScript with no `.d.ts` | fine | fine | every type silently `any` |
71
+ | `require` branch resolving to an ES module | fine (you use `import`) | fine | fails on older Node |
72
+
73
+ Green the whole way down. Nothing in the normal chain fails, so the first report comes from a
74
+ stranger, against a version you can no longer replace.
75
+
76
+ ### A packed secret is already leaked
77
+
78
+ The worst case is not a broken package. It is a `.env` or an `.npmrc` inside the tarball. By the
79
+ time anything notices, the key exists outside your machine: it was written into an archive, and if
80
+ the upload went through, into a registry that hands it to anyone who asks.
81
+
82
+ `publish-clean` refuses those outright. No flag waives it and `--strict` has nothing to add. It will
83
+ not strip the file for you either, though that is what most people expect: a stripped secret has
84
+ still leaked, and a clean-looking artifact is how it goes unrotated. The report says to rotate the
85
+ credential first, then narrow `files`.
86
+
87
+ ### Dead weight ships forever
88
+
89
+ The second cost is invisible to the only person who can fix it. You pay nothing for a bloated
90
+ package: you build it once. Everyone else pays, on every install, every CI run, every Docker layer.
91
+ Those bytes sit in every `node_modules` that ever resolved your package, and they cannot be taken
92
+ out of a version that is already published.
93
+
94
+ Nothing complains, because nothing is broken. A shipped `__tests__` directory installs fine. A jest
95
+ config block in `package.json` parses fine. Both are downloaded forever by people who will never
96
+ use them.
97
+
98
+ So waste here is a defect with a rule id and an exit code, not a matter of taste. The one thing this
99
+ tool will not do is drop a manifest field it does not recognise: breaking a stranger's build costs
100
+ more than the bytes do.
101
+
102
+ ### Rules are measured, not guessed
103
+
104
+ A checker that rejects a working package is worse than no checker. Its mistake and a real defect
105
+ look identical from the outside, and the only way to find out which you have is to publish anyway.
106
+ That is the step this tool exists to protect.
107
+
108
+ So no rule here is written from the spec alone. Each is measured against thousands of installed
109
+ packages first, and every tolerance exists because its absence refused a package that works.
110
+ Matching declared paths to packed names by equality refused 373 of 5192 packages: `vite`, `svelte`,
111
+ every `@types/*` package, every `@aws-sdk` client. Demanding a fixed order for `exports` conditions
112
+ refused 97 of 3674. After the tolerances those measurements forced, 14 remain, every one a real
113
+ defect.
114
+ [`docs/exports.md`](https://github.com/Anizoptera/publish-clean/blob/main/docs/exports.md) carries
115
+ the measurements and the specimens.
116
+
117
+ If it still refuses a package that works, that is a bug here. Report it.
118
+
119
+ ## What it does
120
+
13
121
  `publish-clean` removes `devDependencies`, workspace settings and tool config from the
14
122
  published manifest. Consumer fields and lifecycle helpers stay. Unknown fields are
15
123
  reported for review and kept unless you choose to remove them.
16
124
 
17
- It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then
18
- uploads it with npm. The checked bytes are the published bytes. Cleaning leaves your
19
- source files alone; your pack hooks still run and can change them.
125
+ It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then uploads it
126
+ with npm. Cleaning leaves your source files alone; your pack hooks still run and can change them.
20
127
 
21
- Preview, then publish:
128
+ Check, then publish:
22
129
 
23
130
  ```sh
24
- pnpm exec publish-clean --dry-run
131
+ pnpm exec publish-clean verify
25
132
  pnpm exec publish-clean -- --access public --tag latest --provenance
26
133
  ```
27
134
 
28
- Requires Node.js 22+, pnpm and npm. The CLI has no runtime dependencies. The publish
29
- command above needs [CI provenance setup](#publishing-a-public-package-from-ci).
135
+ `verify` runs every check and publishes nothing. It works on a `private: true` package, so
136
+ a package that never goes to a registry can still be checked by the rules it would face.
137
+
138
+ Requires Node.js 22+ and pnpm, plus npm to publish. The publish command above needs
139
+ [CI provenance setup](#publishing-a-public-package-from-ci).
30
140
 
31
141
  ## Install
32
142
 
@@ -37,9 +147,17 @@ command above needs [CI provenance setup](#publishing-a-public-package-from-ci).
37
147
  | npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
38
148
  | Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
39
149
 
40
- Both `pnpm` and `npm` must be on `PATH`, including in Bun, npm and Yarn projects and CI.
41
- The CLI is one JavaScript file with no runtime dependencies. pnpm and npm are separate
42
- requirements, not bundled dependencies.
150
+ Both `pnpm` and `npm` must be on `PATH` to publish, including in Bun, npm and Yarn projects
151
+ and CI. `pnpm` alone is enough to check one: `verify` and `--dry-run` stop before the upload,
152
+ so they never start npm. pnpm and npm are separate requirements, not bundled dependencies.
153
+
154
+ The CLI is one JavaScript file with no runtime dependencies, and that is deliberate: it sits on the
155
+ publish path and handles registry credentials, so any transitive package would be unaudited code
156
+ next to a live token.
157
+
158
+ pnpm 12 installs its native binary from its own install script, so install it with build scripts
159
+ allowed. Under Bun, which blocks them by default, list `pnpm` in `trustedDependencies`. Otherwise
160
+ pnpm's command stays a placeholder that this tool cannot start. pnpm 11 needs nothing special.
43
161
 
44
162
  For trusted publishing, use Node.js 22.14+ and npm 11.5.1+. Provenance requires a public
45
163
  package, a public source repository and a supported CI provider. See
@@ -64,7 +182,7 @@ artifact's hash.
64
182
  ## Package managers
65
183
 
66
184
  The CLI uses pnpm for workspace resolution and `publishConfig` overrides, and npm to upload the
67
- checked tarball. The [packer comparison](docs/why-pnpm-and-npm.md) explains the trade-offs.
185
+ checked tarball. The [packer comparison](https://github.com/Anizoptera/publish-clean/blob/main/docs/why-pnpm-and-npm.md) explains the trade-offs.
68
186
 
69
187
  Starting through another package manager prints an advisory on stderr. It does not change
70
188
  the packer or stop publication, and there is no option to suppress it.
@@ -117,7 +235,7 @@ steps:
117
235
  Use `--tag latest` for stable releases and `--tag next` for prereleases. npm defaults
118
236
  to `latest`, so omitting the tag can give ordinary installs a prerelease.
119
237
 
120
- For a new package name, follow the [first-publish setup](docs/first-publish.md).
238
+ For a new package name, follow the [first-publish setup](https://github.com/Anizoptera/publish-clean/blob/main/docs/first-publish.md).
121
239
 
122
240
  To block direct publication from your source directory, add this hook. Publishing a
123
241
  tarball does not run it:
@@ -130,6 +248,22 @@ tarball does not run it:
130
248
  }
131
249
  ```
132
250
 
251
+ ### Checking every pull request
252
+
253
+ `verify` needs no registry, no credentials and no npm, so it runs in ordinary PR CI next to your
254
+ tests:
255
+
256
+ ```yaml
257
+ - run: pnpm exec publish-clean verify
258
+ ```
259
+
260
+ A packaging defect then shows up in the change that caused it, instead of on release day with
261
+ everyone waiting. Most of what this tool finds is introduced by an edit to `package.json` or to the
262
+ file layout, so the PR that made the edit is where the answer is cheapest.
263
+
264
+ `--strict` is worth considering here even if you do not use it when publishing: a warning that fails
265
+ a PR costs a rerun, while the same warning at release costs a version number.
266
+
133
267
  ### Keeping your existing release tool
134
268
 
135
269
  If your release tool supports a custom upload command, use `publish-clean` there.
@@ -138,7 +272,7 @@ For a preview check only, add:
138
272
  ```json
139
273
  {
140
274
  "scripts": {
141
- "prepublishOnly": "publish-clean --guard-only"
275
+ "prepublishOnly": "publish-clean verify"
142
276
  }
143
277
  }
144
278
  ```
@@ -166,6 +300,19 @@ publish-clean -- --access restricted --tag latest
166
300
  Omit provenance for restricted packages. Leave `private: true` unset: it prohibits
167
301
  publication, even to a private registry.
168
302
 
303
+ ### Adding it to a package that already exists
304
+
305
+ A package published for years will usually report several findings the first time. You do not have
306
+ to clear them all before you can publish again.
307
+
308
+ Run `verify` first: it shows the whole list and cannot publish anything. Then decide per finding.
309
+ The judgement calls have opt-outs, one per rule, so you can disagree with one and keep shipping:
310
+ `--allow-suspicious` for development files you ship on purpose, `allowUnreferenced` for files
311
+ nothing imports by design, `--skip-file-check` for a package with no `files` array.
312
+
313
+ What has no opt-out is a leaked credential, a packed `node_modules` or `.git`, and a defect that
314
+ breaks a consumer. Those are the ones worth stopping for.
315
+
169
316
  ### Publishing one package out of a monorepo
170
317
 
171
318
  ```bash
@@ -184,7 +331,12 @@ flowchart TD
184
331
  E -->|all pass| G[npm publish this same tarball]
185
332
  ```
186
333
 
187
- `--dry-run` and `--guard-only` validate the artifact, but skip publication preflight.
334
+ Exit code is 0 when nothing stopped the run, 1 when something did, and 130 or 143 when a SIGINT or
335
+ SIGTERM cancelled it. A CI job can tell a real failure from a cancelled runner by that alone.
336
+ Findings and the verdict go to stderr; `--dry-run` prints the file list and the cleaned manifest on
337
+ stdout, so you can read one without the other.
338
+
339
+ `verify` and `--dry-run` validate the artifact, but skip publication preflight.
188
340
  Neither proves that registry access, credentials, provenance requirements or repository
189
341
  identity are correct. Pack hooks still run, including any network operations they perform.
190
342
 
@@ -204,34 +356,135 @@ and drop files the first pack included.
204
356
 
205
357
  Only `package/package.json` is replaced. Other archive entries retain their bytes,
206
358
  order and metadata, including pnpm's owner `0:0`, fixed timestamps and file modes.
207
- The reader resolves USTAR and PAX paths before checking files and rejects malformed or
208
- unsupported path metadata.
359
+ The reader resolves USTAR, PAX and GNU long-name paths before checking files and rejects
360
+ malformed or unsupported path metadata. A path too long for a plain tar name is stated by a
361
+ header in front of the entry it names, so every guard judges the path the archive actually
362
+ extracts to rather than the placeholder in the entry's own header.
209
363
 
210
364
  `pnpm pack` runs pack hooks, including `prepare` and `prepack`. npm runs no package
211
365
  lifecycle scripts when uploading a tarball, so those hooks cannot change the checked
212
366
  artifact during upload.
213
367
 
368
+ ### What this buys for provenance
369
+
370
+ npm builds a provenance attestation from the SHA-512 of the file it uploads. A pipeline that checks
371
+ one artifact and then repacks signs bytes that nothing verified, and the attestation still looks
372
+ perfectly valid. Uploading the checked file is what makes the signature cover what the checks
373
+ actually passed.
374
+
214
375
  ## What it checks
215
376
 
377
+ Every finding prints as `publish-clean [severity] rule-id at where`. The id in brackets below is
378
+ that id. Search this file for the one in your output.
379
+
380
+ Two rules cover the whole output:
381
+
382
+ - **`[warning]` never stops the run.** Wasted bytes, nothing a consumer can trip over. `--strict`
383
+ turns these into errors.
384
+ - **`[error]` stops the run, unless the finding says it was repaired.** A repair fixed the
385
+ published tarball, not your source, so it still prints as an error and you still have something
386
+ to fix. It does not stop the publish, because the artifact going up is correct. `--strict` never
387
+ changes that.
388
+
389
+ A leaked credential or a packed `node_modules`/`.git` always stops the run, and no flag waives it.
390
+ Every run ends with a verdict line, so a pass is never silent.
391
+
216
392
  Publication stops when:
217
393
 
218
394
  - the package is marked `private: true`
219
- - the working tree has uncommitted changes (`--no-git-checks` to allow it)
395
+ - the working tree has uncommitted changes (`--no-git-checks` to allow it). A directory under no
396
+ version control has no commit to differ from, so it warns and continues instead
220
397
  - the package has no non-empty `files` array (`--skip-file-check` to allow it)
221
398
  - the tarball contains a recognised test, CI, lockfile or `tsconfig` path
222
- (`--allow-suspicious` to allow it)
223
- - a filename matches the protected rules for environment files, npm credentials, Git
224
- internals, `node_modules` or key files; these checks cannot be disabled
399
+ (`--allow-suspicious` to allow it) [`suspicious-file`]
400
+ - a filename matches the protected rules for environment files, npm credentials [`secret-file`],
401
+ or Git internals, `node_modules`, and editor or coding-agent state (`.idea`, `.vscode`,
402
+ `.cursor`, `.windsurf`, `.junie`, `.claude`, `.codex`, `.gemini`, `.agent`, `.agents`, `.omc`,
403
+ `.aider*`) at any depth [`internal-file`]; these checks cannot be disabled
225
404
  - a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, or a local
226
- dependency points outside the shipped files
405
+ dependency points outside the shipped files [`monorepo-only-spec`]
227
406
  - a declared entry point cannot resolve against the shipped files; checks account for
228
- extension lookup, conditions and fallbacks, and allow unmatched `sideEffects` globs
407
+ extension lookup, conditions and fallbacks. A declared path no consumer can resolve — an object
408
+ `browser`, `sideEffects`, an internal `#` import, a `*` pattern matching no packed file — reports
409
+ and continues instead [`declared-path-inert`], and `--strict` refuses it
229
410
  - rewriting the manifest changed anything else in the tarball
230
411
  - GitHub trusted publishing or provenance is enabled, but the `repository` in your manifest
231
412
  is not the repository the workflow is running in
232
-
233
- File guards check paths, not file contents. They cannot detect a credential embedded
234
- in an otherwise allowed source file. See [the rules](src/artifact.ts).
413
+ - a `require` condition resolves to an ES module [`require-branch-is-esm`]. Node can require one
414
+ only from 20.19 and 22.12 onward, a consumer can switch that off, and top-level await fails on
415
+ every version. Point `require` at a CommonJS build, or add a `module-sync` branch
416
+ - a condition sits out of canonical order where reordering it would change what somebody resolves,
417
+ and a consumer really loses its target: a runtime-specific build shadowed by a generic one. The
418
+ tool will not guess here, so it reports and stops instead [`exports-condition-order-unsafe`]
419
+ - two packed names differ only in letter case or Unicode form [`packed-name-collision`]. They
420
+ collapse onto one path on macOS and Windows, which ignore both by default. Two files means one
421
+ silently overwrites the other and the install still reports success; a file colliding with a
422
+ directory means the install fails outright. Only a case-sensitive filesystem can produce the
423
+ pair, which is why the author never sees it
424
+ - a packed name Windows cannot create [`packed-name-unportable`]: a path component named after a
425
+ DOS device (`aux`, `con`, `nul`, `com1`…, with or without an extension), a character such as `:`
426
+ or `?`, a trailing dot or space. Declare `"os": ["!win32"]` if the package genuinely does not run
427
+ there and this stops applying. A path component over 255 bytes is refused regardless, because no
428
+ filesystem accepts one
429
+ - a `bin` file has no shebang [`bin-no-shebang`], or its shebang ends in CR
430
+ [`shebang-carriage-return`]. An installer symlinks the file and the command is executed directly,
431
+ so without that first line Linux and macOS fail with `exec format error` and npm has no
432
+ interpreter for its Windows shim. A trailing CR is invisible in an editor and makes the kernel
433
+ look for an interpreter literally named `node\r`. A `bin` file holding a NUL byte in its first
434
+ 512 bytes is exempt: it is a compiled binary
435
+ - a shipped file imports another by the wrong letter case [`import-case-mismatch`], so it works on
436
+ the author's macOS and fails on a consumer's Linux
437
+ - the package imports itself by name through a subpath its `exports` does not expose
438
+ [`self-import-not-exported`], which resolves for nobody, and looks fine in your own repository,
439
+ where it resolves by path
440
+ - the tarball holds a file nothing in the package reaches [`unreferenced-file`]: no entry point,
441
+ no import from a reached file, no script. Declare the ones that are deliberate:
442
+ `"publish-clean": { "allowUnreferenced": ["assets"] }`, matched as a prefix, so naming a directory
443
+ covers everything under it. This check only runs when the package has an `exports` field, because
444
+ that is what makes unlisted paths unimportable. Without it every shipped file is reachable and
445
+ none is dead.
446
+
447
+ A malformed registry URL [`registry-not-a-url`], or one carrying a password
448
+ [`registry-credentials`], also stops the run. Treat such a password as compromised: it is in your
449
+ `package.json` and was about to be published inside the tarball's manifest.
450
+
451
+ File guards match paths, not file contents. A credential hardcoded inside an otherwise allowed
452
+ source file is published and nothing here reports it.
453
+
454
+ ## What it repairs
455
+
456
+ An `exports` map is order-sensitive: a consumer activates a whole set of conditions at once and
457
+ takes the first key in that set, so the order you wrote picks the winner. `publish-clean`
458
+ flattens the map into the resolution it produces for every possible consumer, and rewrites it
459
+ only when the result is provably identical: dropping a `node` branch that repeats `default`
460
+ [`exports-inert-condition`], collapsing `{"default": "./x.js"}` [`exports-redundant-default`], and
461
+ putting keys that real resolvers require in a fixed order into it [`exports-condition-order`].
462
+ A branch no consumer reaches [`exports-unreachable-branch`], a consumer no branch serves
463
+ [`exports-unresolvable`] and a condition name no known runtime or bundler activates
464
+ [`exports-unknown-condition`] are reported, never guessed at. Every repair is
465
+ reported, lands only in the published manifest, and never touches your source. `--no-heal`, or
466
+ `"publish-clean": { "heal": false }`, reports without rewriting.
467
+
468
+ `types` is the one exception, and the only rewrite here that changes what somebody resolves. Only
469
+ a type checker activates it, so nothing that runs your package can tell the difference:
470
+
471
+ - a `types` branch pointing at JavaScript with no declaration file beside it is **removed**
472
+ [`types-branch-not-declarations`]. It promised an API the package does not carry, and a checker
473
+ was reading that JavaScript as your declarations and typing everything `any`.
474
+ - declarations hidden behind a key that leads a checker nowhere are **moved to the front**
475
+ [`types-branch-unreachable`], where every checker looks first.
476
+
477
+ Both print as errors — fix your source — and neither stops the publish, because the published
478
+ artifact is correct. Under `--no-heal` neither rewrite is applied, and then both defects stop it.
479
+
480
+ Anything the archive cannot settle is left exactly as you wrote it: a `types` target the package
481
+ does not ship is a missing file and keeps that report, and nothing is moved across a condition this
482
+ tool does not recognise, since a private name may be meant for a consumer configured to take it.
483
+
484
+ Still reported and left alone: anything inside a fallback array [`exports-fallback-array`], because
485
+ Bun resolves those differently from Node and Deno and no rewrite is safe for everyone, and any map
486
+ too large to enumerate [`exports-too-complex`]. [`docs/exports.md`](https://github.com/Anizoptera/publish-clean/blob/main/docs/exports.md) has
487
+ the measured condition sets behind these rules.
235
488
 
236
489
  ## What the cleaned manifest keeps
237
490
 
@@ -250,7 +503,8 @@ any helper script. Otherwise the development-only scripts block is removed.
250
503
  Unknown fields are kept and reported:
251
504
 
252
505
  ```
253
- publish-clean: these manifest fields are not recognised and are retained as-is:
506
+ publish-clean [warning] unrecognized-field at 1 manifest field
507
+ These manifest fields are not recognised and are retained as-is:
254
508
  "someToolConfig"
255
509
  Strip the ones consumers do not read, and acknowledge the ones they do:
256
510
  "publish-clean": { "devFields": ["someToolConfig"] }
@@ -259,7 +513,8 @@ Strip the ones consumers do not read, and acknowledge the ones they do:
259
513
 
260
514
  Unknown fields stay because removing an unfamiliar field can break a consumer's build.
261
515
  Use `devFields` to remove a field you know is development-only, or `keepFields` to suppress
262
- its report. Inspect the result with `--dry-run`.
516
+ its report. `--strict` promotes this warning to an error like any other. Inspect the result
517
+ with `--dry-run`.
263
518
 
264
519
  ## Options and config
265
520
 
@@ -285,8 +540,12 @@ boolean flags enable their setting. Pass per-release npm options, such as dist-t
285
540
 
286
541
  | Flag | `package.json` | What it does |
287
542
  | -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
543
+ | `verify [dir]` | - | Run every check and publish nothing. Works on a `private: true` package. |
544
+ | `--verify-only` | - | The `verify` subcommand, for scripts that can only pass flags. |
545
+ | `--strict` | - | Treat warnings as errors. Never makes an already-applied repair fatal. |
546
+ | `--no-heal` | `heal: false` | Report repairable `exports`/`imports` defects without repairing them. |
288
547
  | `--dry-run` | - | Validate a preview artifact and print its file list and cleaned `package.json`. |
289
- | `--guard-only` | - | Validate a preview artifact without the file list or manifest output. |
548
+ | `--guard-only` | - | Deprecated alias for `verify`; fails on a `private: true` package. |
290
549
  | `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
291
550
  | `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
292
551
  | `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
@@ -294,6 +553,8 @@ boolean flags enable their setting. Pass per-release npm options, such as dist-t
294
553
  | `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
295
554
  | - | `devFields` | Extra manifest fields to strip. |
296
555
  | - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
556
+ | - | `allowUnreferenced` | Shipped paths nothing imports, on purpose. Matched as a prefix, so a directory name covers everything under it. |
557
+ | - | [`validateArtifact`](#validate-the-final-artifact) | Run your checks on the cleaned tarball before copying or publishing it. |
297
558
  | `-h`, `--help` | - | Print usage, every flag, and the config keys. |
298
559
  | `-v`, `--version` | - | Print the installed version. |
299
560
 
@@ -312,7 +573,9 @@ Registry URLs must not contain usernames or passwords, including scoped destinat
312
573
  `skipFileCheck` waives the manifest's `files` requirement. `allowSuspicious` permits the
313
574
  listed development files. Neither disables the protected filename checks.
314
575
 
315
- Use `noGitChecks` for a build directory or another directory outside a Git repository.
576
+ Use `noGitChecks` to publish from a checkout whose working tree is dirty. A directory outside any
577
+ Git repository does not need it: there is no commit there for a tree to differ from, so the check
578
+ reports that it was skipped and the run continues.
316
579
 
317
580
  `devFields` refuses known consumer fields such as `exports`, `bin`, `engines` and dependency
318
581
  maps to prevent accidental removal.
@@ -320,11 +583,35 @@ maps to prevent accidental removal.
320
583
  Use `keepFields` for consumer fields the tool does not recognise, such as a VS Code
321
584
  extension's `contributes` and `publisher`. It suppresses reports; it does not restore stripped fields.
322
585
 
586
+ ### Validate the final artifact
587
+
588
+ Use `validateArtifact` to check what users will install, such as package imports or type declarations. Add the command to your `package.json`:
589
+
590
+ ```json
591
+ {
592
+ "publish-clean": {
593
+ "validateArtifact": ["node", "scripts/check-artifact.mjs"]
594
+ }
595
+ }
596
+ ```
597
+
598
+ This runs `node scripts/check-artifact.mjs /absolute/path/to/package.tgz` from your package directory. Read the tarball path from `process.argv.at(-1)`; configured arguments come before it.
599
+
600
+ The command runs once after built-in checks and before publication or a `--tarball-out` copy. It also runs in `verify` and `--dry-run` modes. The config is removed from the published manifest.
601
+
602
+ The first item must name an executable on `PATH` or by its path. Use `node` or `bun` to run scripts, including on Windows; `.cmd` shims are not supported. Arguments are passed literally, without a shell: no pipes, redirection or environment assignments. Relative paths start at your package directory.
603
+
604
+ Exit with code 0 to pass or a nonzero code to reject the package. A failed launch, failed check, or changed or deleted tarball stops publication and copying. Output is hidden on success and shown on failure, with a capture limit to bound memory use. Cancellation stops the command and its child processes before removing temporary files.
605
+
606
+ Your script runs with your permissions. Keep it read-only and wait for its child processes to finish; publish-clean does not sandbox it or protect other project files.
607
+
608
+ Check the supplied tarball. Packing again checks different bytes; calling publish-clean from the script runs the same hook again.
609
+
323
610
  ## What it does not do
324
611
 
325
612
  Use your release tool for versions, changelogs, tags and GitHub releases. Configure trusted
326
- publishing separately. `publish-clean` checks declared paths; it does not execute your
327
- package or validate its type declarations.
613
+ publishing separately. Built-in checks verify declared paths. To test package imports or
614
+ type declarations, supply a [validation command](#validate-the-final-artifact).
328
615
 
329
616
  Bundled `node_modules` are not allowed. pnpm may first reject `bundleDependencies` with:
330
617
 
@@ -352,7 +639,10 @@ difference between a preview check and publishing through this CLI.
352
639
 
353
640
  [`publint`](https://publint.dev) and
354
641
  [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
355
- check package entry points and TypeScript compatibility. Use them alongside this tool.
642
+ check package entry points and TypeScript compatibility. Run them alongside this tool. They only
643
+ report: they do not clean the manifest, repair anything, or publish. They also cover what this tool
644
+ deliberately leaves out of scope: type resolution and module-format analysis. Neither replaces the
645
+ other, and no check here is skipped on the grounds that publint reports it too.
356
646
 
357
647
  `npm publish --dry-run` previews npm's publication. It does not clean the manifest or apply
358
648
  this tool's protected filename rules.
@@ -377,30 +667,9 @@ bun install --frozen-lockfile
377
667
  bun run check
378
668
  ```
379
669
 
380
- [CONTRIBUTING.md](CONTRIBUTING.md) has the rest. Security problems go through private
381
- reporting, not public issues: see [SECURITY.md](SECURITY.md).
670
+ [CONTRIBUTING.md](https://github.com/Anizoptera/publish-clean/blob/main/CONTRIBUTING.md) has the rest. Security problems go through private
671
+ reporting, not public issues: see [SECURITY.md](https://github.com/Anizoptera/publish-clean/blob/main/SECURITY.md).
382
672
 
383
673
  ## License
384
674
 
385
675
  Apache-2.0. Copyright 2026 Anizoptera and Art Shendrik.
386
-
387
-
388
- ## Validate the final artifact
389
-
390
- Set `publish-clean.validateArtifact` to an executable and its arguments to check the exact cleaned tarball before retention or upload:
391
-
392
- ```json
393
- {
394
- "publish-clean": {
395
- "validateArtifact": ["node", "scripts/check-artifact.mjs"]
396
- }
397
- }
398
- ```
399
-
400
- The command runs once in the source package directory, with the absolute tarball path appended as its last argument. It runs in normal, `--dry-run` and `--guard-only` modes, after built-in artifact checks and before `--tarball-out` copies anything. The configuration is stripped from the published manifest.
401
-
402
- Use an executable, not a shell command or a Windows `.cmd` shim. Arguments remain literal; pipes, redirection and environment assignments are not interpreted. Relative script paths resolve from the package directory. The executable must be available in PATH or named by a path.
403
-
404
- The validator must finish successfully and leave the tarball bytes unchanged. A launch failure, nonzero exit, changed or missing artifact stops retention and publication. Successful output is quiet; failure output is reported, with captured output bounded to prevent runaway memory use. Cancellation stops the child process tree before temporary files are removed. The validator is trusted project code, not a sandbox: it must not leave background writers or modify other project files.
405
-
406
- Inspect the supplied archive directly. Do not invoke `publish-clean` or pack the package again inside the validator; that would recurse or validate different bytes.