feat(check): remove deprecated @types stubs instead of upgrading them (UPT-54)

[lucasbraum]

What and why

UPT-54: a deprecated @types stub is now removed instead of upgraded.

Before this, upgrading ioredis 4 → 5 moved @types/ioredis 4.28.10 to 5.0.0. That release is the stub DefinitelyTyped publishes once a package ships its own types. It declares nothing, and npm marks it deprecated. Two things went wrong:

• check gave up on the package: not analyzed: @types/ioredis@5.0.0: no type declarations in the target, cannot diff. Stripe 7 → 23 did the same with @types/stripe@8.0.417.
• fix would have installed the stub.

This builds on #142 and does not change it. A new step, check/removed.ts next to check/required.ts, runs after the release group and before required moves.

When a @types companion is removed. Both of these must hold:

• npm's deprecated field is set on the @types release the plan would move to. For stripe, only 8.0.417 carries it, so the plan reads the field on the release it picks.
• The target's own manifest declares types: types, typings, or a types condition anywhere in exports.

Either one alone keeps today's upgrade. A registry that cannot answer also keeps the upgrade.

Where the data comes from.

• deprecated comes from the abbreviated packument the planner already reads. No new request.
• ownTypes comes from the full per-version manifest that metadata already fetches. Its cache key moves from metadata- to manifest- so old entries without the field are not trusted.

What the user sees. The plan gets removals, and the report gets companionRemovals, kept apart from companions:

• check: − removed: @types/ioredis, ioredis 5 ships its own types npm deprecates its new release as a stub; was 4.28.10. This line shows even on a row where nothing breaks.
• The PR body gets its own section:

  Removed:
  
  - `@types/ioredis`, ioredis 5 ships its own types
  

check diffs against the package's own types. When the plan removes the stub, the target side of the diff is the package's own declarations, labeled "types via @types/ioredis 4.28.10 → ioredis 5.4.1's own types". The baseline is still the installed @types release. This is what makes the stripe case analyzable at all.

fix.

• Takes the entry out of every workspace that installs it (dependencies, devDependencies, optionalDependencies). A peerDependencies declaration is a promise to consumers and stays.
• Does it in the same single install.
• Commit message: chore: upgrade ioredis to 5.4.1, remove @types/ioredis.

The install scope guard allows exactly that removal (lock-guard.ts, a new removed argument):

• An importer's edge to the stub may disappear, never appear or change.
• A lock entry only the stub reached may be deleted, never added or changed.
• An outside dependent's edge into that subtree is still compared, so a shared @types/node cannot vanish under another package.
• upgradeInstall builds both graphs with the removed names among the targets, so importer declarations of them are not compared as metadata.

How it was verified

Failing tests first (the commit test(check): …). Twelve tests fail on main's code and pass here. The "upgrades as before" cases pass on both, as they should.

• check/removed.test.ts, modeled on npm's real releases:
  • ioredis 4.28.5 → 5.4.1 removes @types/ioredis 4.28.10.
  • stripe 7.15.0 → 18.0.0 removes @types/stripe 7.13.25: the plan would reach 8.0.417, the deprecated one.
  • The upgrade is kept when the release is not deprecated (stripe 8.0.0 → @types/stripe 8.0.416), when the target ships no types, and when nothing can say whether it does.
• fix/managers/removed-scope.test.ts, for npm, pnpm and Yarn:
  • The planned removal is allowed, and so is @types/node going with it, since only the stub reached it.
  • The same removal is refused when the plan did not make it.
  • The stub moving to 5.0.0 instead of going is refused.
  • Anything else moving next to the removal is refused.
  • On main's guard, the "allowed" case fails for all three managers.
• fix/generic.test.ts: one install with remove: ['@types/paint'], the manifest entry gone, the commit message, and the PR body section.
• fetch/npm-fetcher.test.ts: ownTypes from types, typings and a types export, and the deprecated message kept in manifests.
• format-check.test.ts: the removal line on a breaking row and on a safe row.

Real runs on synthetic repositories. Each is a single src/index.ts against the real npm registry, installed with scripts off. They are throwaway fixtures, not public repositories.

• ioredis ^4.28.5 with @types/ioredis ^4.28.10, before: not analyzed: @types/ioredis@5.0.0: no type declarations in the target, cannot diff. After:

  ioredis   not analyzed: no pack yet · compiled against 6.0.0: 0 new type errors
  

  The JSON report has companionRemovals: [{ name: "@types/ioredis", from: "4.28.10", reason: "ioredis 6 ships its own types" }] and typesVia: "@types/ioredis 4.28.10 → ioredis 6.0.0's own types".
• stripe ^7.15.0 with @types/stripe ^7.13.25, before: not analyzed: @types/stripe@8.0.417: no type declarations in the target, cannot diff. After:

  stripe   1 breaking · compiled against 23.0.0: 1 new type error
    ✗ apiVersion no longer matches the SDK   index.ts:4   needs the agent (LLM)
    − removed: @types/stripe, stripe 23 ships its own types   npm deprecates its new release as a stub; was 7.13.25
  

• The real install and guard, with npm 11. I called upgradeInstall directly; fix itself stops earlier on these packless repositories without an LLM.
  • ioredis → 5.4.1, removing @types/ioredis, is allowed. The lockfile lost @types/ioredis, @types/node and undici-types, which only the stub reached, and tsc passes against ioredis 5.4.1's own types.
  • stripe → 18.0.0, removing @types/stripe, is allowed. tsc then reports exactly the apiVersion error check predicted.
  • The same removals, with the guard not told, are refused: Install changed resolutions outside ioredis's dependency subtree: lockfile metadata/importers; importer . resolutions; node_modules/@types/ioredis (removed, was 4.28.10); ….

Re-scored every registered pack, against main 0881185 and this branch. Same truth, --offline after one packs:fetch, scripts off. Every repository's result is byte-identical on both sides: no pack repository has a deprecated stub in its plan.

Pack	Breaking P / R (tp fp fn), main → branch	Overall P / R	Gate
ai	100% / 82% (9 0 2) → same	100% / 89% → same	PASS → PASS
lucide-react	100% / 100% (11 0 0) → same	100% / 100% → same	PASS → PASS
next	100% / 85% (11 0 2) → same	100% / 80% → same	PASS → PASS
react	100% / 69% (89 0 40) → same	94% / 70% → same	PASS → PASS
react-router	100% / 88% (14 0 2) → same	5% / 89% → same	FAIL → FAIL ¹
@sentry/browser	100% / 100% (3 0 0) → same	100% / 100% → same	PASS → PASS
@sentry/nextjs	100% / 100% (6 0 0) → same	100% / 100% → same	FAIL → FAIL ¹
@sentry/react	n/a (0 0 0) → same	→ same	FAIL → FAIL ¹
stripe	100% / 90% (18 0 2) → same	100% / 90% → same	verified → verified ²
vitest	100% / 50% (16 0 16) → same	0% / 50% → same	PASS → PASS
zod	100% / 74% (59 0 21) → same	100% / 80% → same	verified → verified ²

Breaking precision does not drop for any pack.

¹ These fail the same way on both sides because one truth repository each could not be fetched here: Arize-ai/phoenix, xdoubleu/tools.xdoubleu.com and owine/youth-activity-scheduler. Each truth entry has a directory, and packs:fetch reads the repository root's package.json before honoring it (ENOENT …/package.json). That is already the case on main and is outside this PR. unkeyed/unkey logs the same fetch error but was already in the cache and scored.

² Scored with fixtures/repos/storefront installed (pnpm install --ignore-scripts --frozen-lockfile in it, on both sides). Without it, both sides fail stripe and zod the same way: has no node_modules.

Repository checks:

• pnpm lint: only the warning and info that were already there.
• pnpm typecheck passes.
• Tests, per package: core 1,737 passed / 31 skipped; CLI 456 passed.
  • In the parallel pnpm test run, CLI smoke tests (reports container startup failure…, still fails a missing denylist…) and four assisted.test.ts tests hit their timeouts under load. Each passes when run on its own, here and on main.

Checklist

• Tests for the change (a bug fix starts with a failing test)
• pnpm lint && pnpm typecheck && pnpm test pass (see the timeout note above)
• README and docs updated if behavior changed (docs/architecture.md Companions and Types via @types, README one sentence)
• Changeset added if a user would notice (.changeset/types-stub-removal.md, minor)
• No new dependency, or it was agreed in an issue
• No private code, names or paths in fixtures, tests or docs (synthetic registries and lockfiles modeled on npm's public releases)
• The rules in CONTRIBUTING.md ("Rules that do not bend") still hold (check runs no repository code; installs with scripts off; nothing is removed that the plan does not name)

Not in this PR:

• pack test does not report removals. A truth with entry that upgraded to a stub would read as "check leaves it"; no current truth has one.
• In check's terminal output, a row where nothing breaks still hides its release-group companions and feat(check): plan what the target version requires; report a major as a blocker (UPT-50) #142's blockers (it now shows removals). That predates this PR.

🤖 Generated with Claude Code