Validation: Add a published-dependency audit script

[manzoorwanijk]

What?

Follow up to #78882 (comment), where integrating a check against undeclared published dependencies was suggested.

Adds @mawesome/dependency-audit to tools/validation and exposes it as npm run lint:published-deps. The audit verifies that every bare import reachable in each package's published artifact — runtime JS and emitted .d.ts — is declared and resolvable from that package's own dependency ranges, never via root hoisting, a devDependency, or a workspace link.

This PR adds a script and its ignore config so the check can be run locally and evaluated; it also adds a CI gate. A companion PR (#79095) fixes everything the audit currently reports — until it lands, this PR doubles as a live demonstration of what the tool catches.

Why?

Missing published dependencies have been a recurring, hard-to-catch bug class (#74310, #74655, #78882): a module resolves at build time in the monorepo, but consumers installing the package from npm cannot resolve it. For type-surface gaps the failure is silent — with skipLibCheck: true the affected exports degrade to any. We had no protection against regressions, and as #78882 showed, new gaps keep being introduced.

On current trunk, npm run lint:published-deps reports 21 real findings across 12 packages (all fixed by #79095), for example:

@wordpress/components@34.0.0
  ✗ types      [undeclared]     @ariakit/react-core/utils/types  (build-types/card/card-divider/hook.d.ts)
@wordpress/react-i18n@4.47.0
  ✗ runtime    [undeclared]     react/jsx-runtime  (build/index.cjs)
@wordpress/editor@14.47.0
  ✗ types      [undeclared]     redux  (build-types/store/index.d.ts)
  ✗ types      [undeclared]     rememo  (build-types/store/selectors.d.ts)
@wordpress/interactivity@6.47.0
  ✗ types      [undeclared]     @preact/signals-core  (build-types/scopes.d.ts)

With #79095 merged (and this branch rebased), the audit runs clean and deterministically: 126 packages, 0 findings, 1 collapsed, 12 ignored, 8 notices (exit 0).

How?

• @mawesome/dependency-audit is added as a devDependency of the private @wordpress/validation-tools workspace (keeping it out of the root, per workspace conventions), with a dependency-audit script that audits packages/*.
• A root lint:published-deps script delegates to it, mirroring lint:lockfile/lint:tsconfig.
• tools/validation/dependency-audit.config.json documents every intentional suppression with the reason and the follow-up needed. The remaining ignores are: test-fixture imports in e2e-tests (scoped to that package's plugins/** path), the optional puppeteer-core/install / puppeteer-firefox imports in scripts, two libraries that ship no types and have no @types/* package (equivalent-key-map, moment-timezone's deep import), two ESM/CJS packaging mismatches to fix separately (edit-site-init→boot, interactivity-router→interactivity), and one temporary rule for @tannin/sprintf pending a tool release that resolves ESM-only types.
• --collapse-root-cause makes findings whose root cause is another audited package's packaging notice (currently: editor cannot resolve @wordpress/block-editor's types because block-editor does not expose them) report against the producer instead of failing every consumer.

Exit codes: 0 clean, 1 findings, 2 a package could not be audited — so the script is CI-ready once we decide to gate (intended follow-up, possibly after evaluating it on a few real PRs).

Testing Instructions

1. npm ci
2. npm run build (the audit reads the built artifacts)
3. npm run lint:published-deps — on this branch (current trunk) expect exit 1 with 21 findings, each carrying a remediation suggestion; after Packages: Fix the published dependency surface of npm packages #79095 merges and this branch rebases, expect exit 0 with 126 packages, 0 findings, 1 collapsed, 12 ignored, 8 notices, 3 skipped.
4. To see it catch a fresh regression once green: remove e.g. "redux" from packages/editor/package.json dependencies, run npm install && npm run lint:published-deps, and observe the undeclared finding reappear.

Testing Instructions for Keyboard

N/A — tooling only, no UI.

Screenshots or screencast

N/A.

Use of AI Tools

Used Claude Code to wire up the tool, run the audits, and author the ignore config. The diff was reviewed before submission.

[manzoorwanijk]

@aduth this is blocked until we have Node 24 via #72973. Meanwhile, I have done the package fixes in #79095

[aduth]

@manzoorwanijk If it were distributed as a GitHub Action, would that maybe be an option to isolate it enough to avoid that dependency on Node 24 ?

Or I guess even within this project, if we'd have an appetite to have some CI checks run on Node 24+ only. That means people may not be able to reliably run it locally, but this feels like a pretty rare and clear-enough output to signal from CI alone.

[manzoorwanijk]

I am instead widening the floor to add Node v20 support in the tool - manzoorwanijk/mawesome#48

I will remove the Node v20 support once Gutenberg migrates.

[github-actions]

Size Change: 0 B

Total Size: 8.05 MB

_{compressed-size-action}

[manzoorwanijk]

Here it is - working

https://github.com/WordPress/gutenberg/actions/runs/27293481108/job/80620011399?pr=79094

[github-actions]

Flaky tests detected in f58fee3.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27819792931
📝 Reported issues:

• [Flaky Test] does not dirty related template parts or navigation menus when rendered in the post editor #79294 in /test/e2e/specs/editor/blocks/navigation-passive-rendering.spec.js
• [Flaky Test] shows post-locked modal when document size limit is exceeded #78753 in /test/e2e/specs/editor/collaboration/http-only/collaboration-document-size-lock.spec.ts

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[aduth]

I think Windows compatibility should be confirmed, but otherwise this looks like it's in good shape 👍

[aduth]

I suppose I should get on that 😅

[manzoorwanijk]

@aduth while working on this PR, I noticed that if I do npm_config_min_release_age=0 npm install and commit the lockfile, then npm doesn't check for minimum release age for packages already in lockfile 🤷, and we have no check on CI to validate the lockfile. Though we have validate-package-lock.cjs, but it probably needs some improvement. The best way to do is git checkout trunk package-lock.json && npm install, which should fail due to minimum release age and we can also do a diff of the lockfile to ensure it's not in an inconsistent state.

There is also check-local-changes.cjs, which does some of it but not all.

[aduth]

@aduth while working on this PR, I noticed that if I do npm_config_min_release_age=0 npm install and commit the lockfile, then npm doesn't check for minimum release age for packages already in lockfile 🤷

Oh wow, so npm doesn't validate release age if the package update is already in the lockfile? That's rather concerning, since I've been trusting the release age behavior when running npm install in other peoples' branches 😬 I agree this would be good to try to preemptively detect in CI.

[manzoorwanijk]

Probably, the npm theory is that a poisoned dependency (inside the release age) shouldn't end up in lockfile because npm install <dep> should block it, but in our case, CI and may be many devs still use npm v10, which doesn't enforce it. So, we are all vulnerable to the attacks 😄

[aduth]

LGTM 👍 It's kinda slow (1m35s), and in reviewing the internal implementation I can see why with how it's TypeScript-analyzing the packed package in an isolated context, though I can also understand why it has to be that way vs. something more naive like just looking at import sources in the published files for things like the @types/react case you're trying to explicitly catch. So I think it's a worthwhile tradeoff.

[aduth]

You'd know better than I if this will work as intended, but flagging that you document --collapse-root-cause as applying for a "a multi-target run", and it's not clear to me if the changes from glob expansion to string glob (which in effect reduces arguments from multiple to one) will produce the result we expect.

[manzoorwanijk]

The global here results in a multi target run - i.e. multiple packages audited together.

[aduth]

Should this have been a peer dependency? Especially with TypeScript 7.0 being imminent, I wouldn't want us to have to be pulling multiple major versions of TypeScript if we can avoid it, and this is a pretty heavy dependency to put on downstream consumers (no dependencies, but 24MB installed).

[manzoorwanijk]

No, it’s needed as a runtime dependency because the package uses the programmatic API from TypeScript which tsgo doesn’t ship yet. It will be available from TS 7.1.

[aduth]

Your PR message says "This PR only adds the script and its ignore config so the check can be run locally and evaluated; it does not add a CI gate yet", but this is a CI gate, isn't it? Is that comment outdated?

[manzoorwanijk]

Yes, it’s stale.