fix: add TypeScript project references, mirroring MetaMask/core

[ulissesferreira]

Explanation

Status: yarn lint:tsc now passes with 0 errors from a clean state ✅ (plain per-package tsc --noEmit / yarn typecheck has one remaining, separate caveat — see below).

Third option for comparison alongside #167 and #169, modeled on MetaMask/core's pattern (e.g. packages/profile-metrics-controller/tsconfig.json and its tsconfig.build.json).

• bitcoin-wallet-snap, solana-wallet-snap, and tron-wallet-snap each get "references": [{ "path": "../snap-networks-utils" }] in their tsconfig.json (their only workspace dependency).
• The root tsconfig.json lists every snap package alongside snap-networks-utils, matching core's root config.
• A full tsc --build lint-graph (tsconfig.packages.lint.json, per-package tsconfig.lint.json, root tsconfig.lint.json, "lint:tsc" wired as the first step of yarn lint), mirroring MetaMask/core's incremental repo-wide typechecking setup exactly.
• The missing piece, now added: an explicit @metamask/snap-networks-utils/* subpath entry in the shared tsconfig.packages.json paths map (TypeScript paths patterns only allow one *, mirroring Core's own @metamask/json-rpc-engine/v2 subpath entry), baseUrl: "./" added to tron-wallet-snap and stellar-wallet-snap (the two packages that didn't have it — every other package, and every package in Core, sets this), and expanded include in the four affected tsconfig.lint.json files to cover snap.manifest.json/JSON test fixtures (required by --build mode's stricter file-listing rule, TS6307).

How this got here (history, kept for the record)

Earlier revisions of this PR were deliberately scoped to "references only, change nothing else," to test in isolation whether references alone fixes the resolution problem #167/#169 address. It doesn't — confirmed empirically both with plain tsc --noEmit and with a full clean-state yarn lint:tsc run, which failed with ~70 "Cannot find module @metamask/snap-networks-utils" errors + 13 TS6307 file-inclusion errors. That confirmed references alone gives you (a) correct tsc --build ordering/incrementality and (b) editor "go to definition" to source, but does not change how a bare @metamask/* specifier resolves — that still needs a paths mapping to source, exactly like #167/#169 add.

Adding that paths mapping directly (matching Core's exact declaring-relative form, "@metamask/*": ["../*/src"], reinterpreted per-package via each package's own baseUrl) is what actually closes the gap — yarn lint:tsc now builds snap-networks-utils first (in correct topological order, per the references graph) and every consumer resolves it from source, with 0 errors.

Remaining caveat: plain tsc --noEmit (yarn typecheck)

Running tsc --noEmit directly on bitcoin-wallet-snap, solana-wallet-snap, or tron-wallet-snap (the three packages with a references entry) still fails with TS6305 Output file '...index.d.ts' has not been built from source file '...index.ts', even after this fix. This is not a config gap fixable by matching Core more closely — it's inherent to combining references (to a composite: true project) with a bare --noEmit invocation: TypeScript's project-reference redirect logic requires the referenced project to actually have been built first, and only tsc --build (not --noEmit) builds dependencies in order before checking the dependent. Confirmed by testing both composite: false on the consumer (no change) and removing references entirely (error disappears, replaced by the expected TS6307 file-listing error instead). yarn typecheck (workspaces foreach ... exec tsc --noEmit) will keep hitting this for the three referenced packages unless it's changed to invoke tsc --build instead — out of scope for this PR, called out for visibility.

Unrelated pre-existing issues found while testing

• tron-wallet-snap/stellar-wallet-snap previously showed Cannot find module '@metamask/superstruct'/'@metamask/utils' from a snaps-registry path in earlier testing on this branch — re-verified from a clean worktree and that package/path doesn't actually exist in this repo; see "Clean-install verification" for the corrected finding (10 unrelated pre-existing type errors elsewhere instead).
• yarn typecheck is not wired into any CI workflow today.

Validation

• yarn lint:tsc (tsc --build tsconfig.lint.json): passes with 0 errors, from a clean state (no dist, no .tsbuildinfo, no .tsc-lint-cache).
• yarn build:types: passes, unaffected.
• yarn changelog:validate: passes.
• tsc --noEmit for sample-snap, snap-networks-utils, stellar-wallet-snap: passes with 0 errors.
• tsc --noEmit for bitcoin-wallet-snap, solana-wallet-snap, tron-wallet-snap: fails with TS6305 — see "Remaining caveat" above; this is a references + --noEmit limitation, not a resolution bug.
• yarn lint:eslint: not verified in this sandbox due to an environment memory limit (Node heap OOM building the full ESLint TS program graph) unrelated to this change; a single-file spot-check passed.

Pros and Cons

Pros:

• Now actually fixes resolution for the tsc --build path, while also gaining what references alone provided: correct tsc --build ordering/incrementality and editor "go to definition" to source.
• Closest to industry/Core convention — this is now genuinely "what Core does," not just its references half.
• The lint-graph work is real, working groundwork for incremental repo-wide typechecking in CI, if the team wants that later (this repo runs no yarn typecheck/lint:tsc in CI today).
• Diff stayed small: 7 files, ~35 lines, for the fix itself.

Cons:

• Plain tsc --noEmit (yarn typecheck) still fails for the three packages with a references entry — fixing that would mean changing yarn typecheck to use tsc --build semantics, which is out of scope here.
• Adds more surface area than fix: resolve workspace MetaMask packages from the monorepo root #167/fix: restate workspace @metamask/* paths per package with local baseUrl #169 (six tsconfig.lint.json files, a root lint config, a new lint:tsc script) to get to a working state.
• Requires understanding a genuinely subtle TypeScript interaction (composite projects + references + cross-project paths + --build vs --noEmit) to maintain correctly going forward.

Clean-install verification

Re-verified from a genuinely fresh worktree — no node_modules, no packages/*/dist, no .tsc-lint-cache anywhere — with only yarn install run (no yarn build), before the paths-mapping fix:

• 73× TS2307 "Cannot find module @metamask/snap-networks-utils..." (69 via /logger, 4 bare) — matches the previously documented ~70.
• 13× TS6307 file-inclusion errors — exact match to previously documented ~13.
• Correction: the previously-cited "~18 pre-existing snaps-registry errors" don't hold up — no snaps-registry package exists in this repo/branch. Instead, 10 other pre-existing, unrelated type errors (5× TS7006, 2× TS2769, 2× TS2345, 1× TS7019) in solana-wallet-snap/tron-wallet-snap, landing at a similar total (96 vs. ~101).

After the paths-mapping fix (this same clean-state methodology, re-run locally): yarn lint:tsc exits 0 with 0 errors.

References

• Alternative to fix: resolve workspace MetaMask packages from the monorepo root #167, fix: restate workspace @metamask/* paths per package with local baseUrl #169
• Pattern based on MetaMask/core
• Compared side-by-side with fix: resolve workspace MetaMask packages from the monorepo root #167 and fix: restate workspace @metamask/* paths per package with local baseUrl #169

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them