feat: debug-files check — parse DIFs via @sentry/symbolic (WASM)

[BYK]

Summary

Adds sentry debug-files check — inspect a debug information file and print its debug id, code id, architecture, kind, and feature flags. Supports Mach-O/dSYM, ELF, PE/PDB, Portable PDB, WebAssembly, Breakpad, and source bundles.

Parsing is done in-process via @sentry/symbolic (the symbolic Rust crate compiled to WASM) — no native binary and no dependency on the legacy Rust sentry-cli.

$ sentry debug-files check /bin/ls
╭──────────┬──────────────────────────────────────────╮
│ Debug ID │ 0f13a5da-412a-fbf7-c866-2048f3294f3d     │
│ Code ID  │ daa5130f2a41f7fbc8662048f3294f3d439ca7ff │
│ Arch     │ x86_64                                   │
│ Format   │ elf                                      │
│ Kind     │ lib                                      │
│ Features │ symtab, unwind                           │
╰──────────┴──────────────────────────────────────────╯

How it works

@sentry/symbolic@13.3.0 (published from getsentry/symbolic#986) is a devDependency — the JS glue is bundled by esbuild, and the .wasm is loaded lazily on first use across all three runtime modes:

• SEA binary: the .wasm is embedded as a fossilize asset (build.ts copies it from node_modules/@sentry/symbolic into dist-build/); loaded via node:sea.getRawAsset().
• npm bundle: the .wasm is shipped as a sibling (bundle.ts copies it to dist/vendor/); loaded relative to the bundle.
• dev (tsx): resolved from the installed @sentry/symbolic package.

The @sentry/symbolic/symbolic_bg.wasm subpath is marked external so esbuild never tries to inline it; the runtime require.resolve is only reached in dev.

All three modes were validated locally (built and ran dist-bin/sentry-linux-x64 and dist/bin.cjs; both parse correctly).

Files

File	Purpose
src/lib/dif/index.ts	Typed API + dual-mode WASM loader over @sentry/symbolic
src/commands/debug-files/check.ts	The command (auto-detects format; non-zero exit when unusable)
script/build.ts / script/bundle.ts	Embed/ship the .wasm from node_modules/@sentry/symbolic
package.json	@sentry/symbolic devDependency + npm files entry

Testing

15 tests (9 dif lib + 6 command) using deterministic Breakpad text fixtures — no committed binaries, identical on every platform. Covers usable/unusable exit codes, error paths, --json, and a nil-debug-id format guard. Format/kind use the canonical lowercase .name() strings (elf, lib, breakpad) matching symbolic-cabi/Python.

Notes

• Depends on @sentry/symbolic@13.3.0 (already published).
• Follow-ups (separate PRs): debug-files find, default upload (metadata tier); source tier (bundle-sources/print-sources/upload --include-sources).

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1109/
Built to branch gh-pages at 2026-06-18 17:40 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 84.62%. Project has 5051 uncovered lines.
✅ Project coverage is 81.23%. Comparing base (base) to head (head).

Files with missing lines (2)

File	Patch %	Lines
src/commands/debug-files/check.ts	88.89%	⚠️ 5 Missing and 9 partials
src/lib/dif/index.ts	78.79%	⚠️ 7 Missing and 4 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.23%    81.23%        —%
==========================================
  Files          386       388        +2
  Lines        26831     26910       +79
  Branches     17427     17481       +54
==========================================
+ Hits         21795     21859       +64
- Misses        5036      5051       +15
- Partials      1810      1825       +15

---

Generated by Codecov Action

[BYK]

Holding this PR. Per the plan, we're publishing @sentry/symbolic from the symbolic repo first and will consume the published package here instead of shipping the committed src/lib/dif/vendor/ blob.

Blocked on: getsentry/symbolic#986 (adds the @sentry/symbolic npm package).

Once @sentry/symbolic is published, this PR will be reworked to:

• drop crates/dif-wasm/, script/build-dif-wasm.ts, and the committed src/lib/dif/vendor/ artifact
• depend on @sentry/symbolic (devDependency, bundled at build) and load its .wasm (SEA getRawAsset / dev+npm path)
• keep debug-files check and its tests unchanged

Marking as draft until then.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dbaa6c8. Configure here.}