[lucasbraum]

What and why

The react pack's ground truth (#45) scored check at 4% precision / 1% recall on breaking findings: check did not move @types/react or react-dom with react, compiled almost none of the monorepos' files, and called every type-surface change at a site the compiler never saw "breaking". This fixes the engine, in five steps, with pack test react on #45 as the acceptance test.

1. Companions. @types/<pkg> moves with <pkg> by name, to the release that types the target (newest at the target's major.minor, else its major, src/check/types-release.ts; prepare diffs the types at that version). A package whose release at the target's own version asks for the target (react-dom 19.0.0 peer-requires react ^19.0.0) is released in lockstep and moves too, even when its installed copy would accept the target. The closure is transitive (@types/react-dom follows react-dom, which follows react), every workspace's dependencies are candidates (the root's hoisted @types/react serves the app that declares react), and the plan is carried by every report of the package and kept by the merged entry. check react 18 → 19 moves react, react-dom, @types/react and @types/react-dom together, and fix installs them together. A workspace that only peer-depends on a package (excalidraw's packages/excalidraw) resolved it through its types and then looked for the runtime copy in its own node_modules alone; it now finds the hoisted copy, as Node does.

2. Compile coverage. Why most files were not compiled, found and fixed:

   • workspace packages declared workspace:* under Yarn Berry (lockfile 0.0.0-use.local) and npm were never mapped to their source, and the bundled compiler does not resolve a main pointing at a .ts file from node_modules: the declared specifier is now what the engine reads, hoisted links are found from ancestor node_modules, and the mapping follows the linked packages' own links (@tldraw/editor → @tldraw/utils);
   • a scoped program dropped the tsconfig's ambient .d.ts files (vite-env.d.ts, css.d.ts), so every *.module.css import failed; they are added;
   • the bundled compiler is TypeScript 6, whose defaults for unset options differ from TypeScript 5's (strict on, no automatic @types, modern target/module/resolution, interop on): a repository on TypeScript 5 is now read with TypeScript 5's defaults made explicit (src/adapters/typescript/legacy-options.ts). excalidraw's packages/excalidraw went from 4,212 baseline errors (missing jest globals under strict) to 15.

   Every analyzed package prints compiled N of M files in K workspaces; skipped: <reason (count)>, and the verdict says types partly verified: ... instead of compiled against <version> when not every file was (CompileSignal.coverage, PackageReport.compile.coverage, src/check/verdict.ts).

3. Breaking means confirmed, in every tier. confirmBreaking (was confirmGeneric) runs for the verified tier too: a finding is breaking only with evidence (compiler, runtime probe, module format, removed export, or the pack's own detect). Unconfirmed surface changes are "possible impact": counted apart in the row (✗ 3 breaking, 17 possible), listed under their own line in the package section, never counted as breaking. Packs keep their rules.

4. One finding for a root cause that is one edit. Two new anchors, marked anchorOnly (one site, the diagnostics as evidence; fix, the plan, sitesOf and pack test count one):

   • a compiler option: when the target drops the global JSX namespace and the workspace's "jsx": "preserve"/"react" reads it (no jsxImportSource), the TS7026/TS2602 diagnostics are anchored at the jsx line of the tsconfig that sets it, through extends (src/adapters/typescript/config-cause.ts);
   • a repository parameter: an argument (TS2345) or JSX attribute (TS2322) rejected at a parameter or prop declared in the repository with a type from outside it, when two or more sites trip it (parameterCause in cause.ts): usePassThroughWheelEvents(ref: RefObject<HTMLElement>) in packages/editor, tripped at eleven call sites across tldraw's packages once useRef returns RefObject<HTMLElement | null>, is one finding at the parameter, under its repository path.

   A pack rule claims an anchor when it claims most of the errors under it (ruleFor).

5. Ground truth of feat(packs): react 18 → 19 candidate pack (pack test fails, draft) #45. The only expectation change: tldraw's 1,745 JSX element diagnostics in apps/dotcom/client are one site, at the "jsx" line of its tsconfig (pushed to feat(packs): react 18 → 19 candidate pack (pack test fails, draft) #45 as 3180034, with verification.json recorded from this engine). What the compile showed while doing it: those errors come from two copies of the React types. tldraw's lockfile after its own upgrade still keeps @types/react 18.3.23 for a dependency pinned to 16 || 17 || 18, beside @types/react 19; with one copy (what the overlay links) "jsx": "preserve" resolves element types through the UMD React namespace and nothing errors. check does not model the package manager keeping a nested copy, so it does not predict that site (the one global-jsx-namespace false negative left in tldraw at the tsconfig). The config-cause anchor fires when the namespace really is gone from the program.

How it was verified

pnpm uptide pack test <pack> before (main + #45) and after (this branch + #45), same machine, same ground-truth cache.

pack	before: breaking precision / recall	after
react (#45)	4% / 1% (477 FP, 20 TP, 1854 FN); react-dom, @types/react, @types/react-dom left behind	88% / 64% (11 FP, 83 TP, 46 FN); all three moved, plus next-mdx-remote-client in tldraw
zod	100% / 71% (PASS, verified)	100% / 71% (PASS, verified), identical
stripe	100% / 90% (PASS, verified; 18 TP, 2 FN over 3 repositories)	100% / 90% (PASS, verified), identical
ai	100% / 36% (PASS, verified)	100% / 36% (PASS, verified), identical

react, per rule, after: removed-react-dom 100%/100% (18), use-ref-argument 100%/80%, ref-callback-return, mutable-ref-object, props-with-ref 100%/100%, element-props-unknown 100%/60%, ref-object-nullable 91%/37%, global-jsx-namespace 100%/36%. The 11 breaking false positives left are listed one by one below.

Storefront, before and after (check zod stripe on fixtures/repos/storefront, built CLI, main vs this branch): the rows, rules and counts are identical; the only difference is the coverage line under each package. The README sample is updated with those two lines, and the tier table now says that breaking means confirmed in both tiers and what "possible impact" is. There is no site/ on main.

zod   28 breaking · compiled against 4.6.5: 28 new type errors
  compiled 11 of 11 files in 2 workspaces
  ✗ New error API (required_error → error)   24 sites          auto-fixable
  ...
stripe   4 breaking · compiled against 23.0.0: 4 new type errors
  compiled 7 of 7 files in 1 workspace
  ✗ Test fixture casts widened                   renewal.test.ts:7   auto-fixable

A package with possible impact prints, under its rules:

  ? possible impact: 17 sites in 9 files   the types changed where this code uses them; nothing confirmed that it breaks, so these are not counted as breaking
    ? RefObject#current changed type   12 sites   needs the agent (LLM)

The 11 remaining react false positives (breaking, pack test react after; for #45, not fixed here):

1. packages/excalidraw/components/ButtonIconSelect.tsx:52, IconPicker.tsx:140, JSONExportDialog.tsx:90, LayerUI.tsx:346, MobileMenu.tsx:92, Stats/index.tsx:231 (6): TS2322 Type 'Element' is not assignable to type 'ReactNode' at a JSX child. The same error the ground truth expects a few lines away in each file (ButtonIconSelect.tsx:40, IconPicker.tsx:117/221, JSONExportDialog.tsx:45, LayerUI.tsx:332/352, MobileMenu.tsx:76-146, Stats/index.tsx:188): the truth was drafted with the repository's TypeScript 4.9, which reports it at the element's first line, and the bundled TypeScript 6 reports it at the offending child. A line-tolerant match, or re-drafting the truth with the same compiler, resolves these.
2. dev-docs/src/components/Homepage/index.tsx:52: the same TS2322 in dev-docs, where the truth lists only line 1 (the import React the upgrade removed).
3. examples/excalidraw/with-script-in-browser/index.tsx:16: createRoot(rootElement), react-dom's createRoot container parameter changed; the example's one file cannot resolve @excalidraw/excalidraw (unbuilt dist), so the compiler skipped it and the finding stands on the companion's diff plus the runtime probe. The truth has no site in that example.
4. apps/examples/src/examples/custom-components/CustomComponentsExample.tsx:11 and packages/tldraw/src/lib/canvas/TldrawSelectionForeground.tsx:59: useTransform(rSvg, ...), TS2345 RefObject<SVGSVGElement | null> not assignable to the hook's RefObject<HTMLElement | SVGElement>. The truth expects the parameter (packages/editor/src/lib/hooks/useTransform.ts:6), which check also reports where two sites in one workspace trip it; these two workspaces each trip it once, and the ≥2 rule is per workspace compile. Clustering across workspaces resolves them.
5. apps/docs/components/content/index.tsx:18: TS2307 Cannot find module 'next-mdx-remote-client/rsc' after the companion move of next-mdx-remote-client 1.1.2 → 2.1.12 (the version the upgrade also chose). A real break of the companion, reported under react; the truth lists react's sites only.

CI and stripe's third repository. nextjs/saas-starter pins pnpm@12.10.1. It failed to install here only because this machine runs pnpm through a corepack shim (corepack 0.34 looks for bin/pnpm.cjs, which pnpm 12 no longer ships). The Packs job installs pnpm with pnpm/action-setup, not corepack, and pack test sets npm_config_manage_package_manager_versions; run that way here, pnpm 10 switches itself to 12.10.1 and the repository installs ("Done in 58s using pnpm v10.28.0"), after which stripe scores 100% / 90% over all three repositories, before and after. CI should not hit the problem; if it does, the Packs job log will show the same MODULE_NOT_FOUND for bin/pnpm.cjs.

Coverage, from check react with the built CLI:

• excalidraw: compiled 355 of 356 files in 5 workspaces; skipped: most files cannot resolve their imports at the installed version (1) (before: 4 of 5 files cannot resolve their imports ... compile signal skipped, packages/excalidraw not analyzed at all);
• tldraw, apps/dotcom/client: compiled 164 of 164 files in 1 workspace (before: 130 of 163 files cannot resolve their imports);
• supabase/supabase (fixtures/corpus.json, react 19.2.6 → 19.3.0): list output byte-identical to main; check react prints compiled 1109 of 1110 files in 12 workspaces; skipped: most files cannot resolve their imports at the installed version (1) and ↑ upgrades with @types/react 19.2.14 → 19.3.0, @types/react-dom 19.2.3 → 19.3.0, react-dom 19.2.6 → 19.3.0. apps/studio is over the memory budget on this machine with main and with this branch alike; apps/www (449 files) is analyzed now, where main left it out, and reports 64 compiler-confirmed TS2322 sites against @types/react 19.3.0's SVG props. Main reported 0 breaking · compiled against 19.3.0: 0 new type errors for the same upgrade with that workspace unanalyzed.
• tldraw, whole repository, built CLI: compiled 616 of 616 files in 18 workspaces, 2m42s (before: 7m, most workspaces skipped).

pnpm lint, pnpm typecheck, pnpm test pass (core 895, cli 346). New tests: companions (react 18 → 19, lockstep, workspace visibility), types-release, legacy-options, config-cause, parameter cause (cause.test.ts), anchor-only clusters (anchor.test.ts, unattributed.test.ts), verdict coverage, workspace-source (hoisted, transitive), readInstalled (workspace:* under Yarn Berry), CLI possible-impact and coverage lines.

Known limits, said plainly:

• the engine thread briefly ran out of heap on tldraw and supabase while this was being built: gathering every workspace's manifests for the companion plan loaded a program per workspace; manifests are now read from disk (d82a922) and both repositories run through the built CLI again.
• a parameter cause clusters per workspace compile; the same parameter tripped once in each of two workspaces stays two sites.
• check links one copy of a target's types; an install that keeps a nested older copy (tldraw's @types/react 18 beside 19) is not modeled.

Checklist

• Tests for the change (a bug fix starts with a failing test)
• pnpm lint && pnpm typecheck && pnpm test pass
• README and docs updated if behavior changed (docs/architecture.md, docs/cli.md, README sample and tier table)
• Changeset added if a user would notice (pnpm changeset): minor, "What changed in check"
• No new dependency, or it was agreed in an issue
• No private code, names or paths in fixtures, tests or docs
• The rules in CONTRIBUTING.md ("Rules that do not bend") still hold

🤖 Generated with Claude Code

https://claude.ai/code/session_018u9b3Pp5H68DdYZGp5Qg1U