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