Add the ability to apply source maps from the CLI by canova · Pull Request #6229 · firefox-devtools/profiler

canova · 2026-07-31T11:43:23Z

This fixes #6196.

This PR adds 2 commands to the CLI so we can apply source maps from local files later:

pq sourcemap sources
pq sourcemap apply

sourcemap sources is used for determining which sources we can apply the source maps onto. and sourcemap apply is to apply that source map that we provide as an argument.

For example the output of sourcemap sources:

[Thread: t-20 (GeckoMain) | View: Full profile | Full: 6.572s]

Sources with source maps (4):
  src-61  https://profiler.firefox.com/index-XVVABR7J.js  (sourceMapURL: /index-XVVABR7J.js.map)
  src-65  https://profiler.firefox.com/chunk-JI4GYAEJ.js  (sourceMapURL: /chunk-JI4GYAEJ.js.map)
  src-66  https://profiler.firefox.com/chunk-FQS6JYWD.js  (sourceMapURL: /chunk-FQS6JYWD.js.map)
  src-70  https://profiler.firefox.com/chunk-FFESA2B5.js  (sourceMapURL: /chunk-FFESA2B5.js.map)

Then pq sourcemap apply <sourcemap-path> could optionally take --to <src-N> argument.
If it's not provided, we try to match the source map given to an existing source, if it matches, great, it's done. If it doesn't match, we show an error saying that the user has to provide the --to <src-N> by looking at the output of sourcemap sources. If that argument is provided, we automatically apply to that only.

For example:

$ pq sourcemap apply ./dist/index.js.map
The source map matches more than one source. Re-run with --to <src-N> to pick one:
  src-61  https://profiler.firefox.com/index-XVVABR7J.js  (sourceMapURL: /index-XVVABR7J.js.map)
  src-65  https://profiler.firefox.com/chunk-JI4GYAEJ.js  (sourceMapURL: /chunk-JI4GYAEJ.js.map)
  src-66  https://profiler.firefox.com/chunk-FQS6JYWD.js  (sourceMapURL: /chunk-FQS6JYWD.js.map)
  src-70  https://profiler.firefox.com/chunk-FFESA2B5.js  (sourceMapURL: /chunk-FFESA2B5.js.map)

And then:

$ pq sourcemap apply ./dist/index.js.map --to src-61
Applied source map to https://profiler.firefox.com/index-XVVABR7J.js (src-61). Re-run thread commands to see de-minified names.

Example profile to test:
https://share.firefox.dev/4fIRaUh
And this is the source map for the bundle: index-XVVABR7J.js.map.zip
(note you have to unzip it before using, apparently github doesn't allow uploading .map file extensions, so I had to zip it)

codecov · 2026-07-31T11:46:27Z

Codecov Report

❌ Patch coverage is 26.76056% with 52 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.58%. Comparing base (a62903b) to head (1d84c54).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
src/profile-query/index.ts	0.00%	39 Missing ⚠️
src/profile-query/source-handle.ts	0.00%	10 Missing ⚠️
src/profile-query/source-map.ts	80.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6229      +/-   ##
==========================================
- Coverage   83.69%   83.58%   -0.12%     
==========================================
  Files         348      350       +2     
  Lines       37433    37498      +65     
  Branches    10514    10539      +25     
==========================================
+ Hits        31330    31343      +13     
- Misses       5676     5728      +52     
  Partials      427      427

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

fatadel

Thanks for the work and sorry for the long review! I've left some comments but I think they are mostly minor ones.

fatadel · 2026-08-05T13:53:23Z

+    case 'sourcemap-ambiguous': {
+      const lines = result.candidates.map(formatSourceEntry);
+      return [
+        'The source map matches more than one source. Re-run with --to <src-N> to pick one:',


This is returned for both "matches several" and "matches nothing" leading to:

➜ profiler git:(sourcemap-cli) pq sourcemap apply ~/Downloads/mystery.js.map The source map matches more than one source. Re-run with --to <src-N> to pick one:

when in reality it does not match any.

Oh yeah, it looks like this is also an issue in the web frontend. I'll address that as a follow-up.

fatadel · 2026-08-05T14:20:55Z

+  return {
+    kind: 'inline',
+    mediaType: sourceMapURL.slice('data:'.length).split(',', 1)[0],
+    byteLength: sourceMapURL.length,


Should this probably exclude the prefix length?

Technically you're right, but I don't think we should do it here. This is already an approximation, so it doesn't have to be strictly accurate.

fatadel · 2026-08-05T14:25:44Z

+if (!existsSync(wasmUrl)) {
+  console.error(
+    `profiler-cli source map parser not found at ${fileURLToPath(wasmUrl)}.\n` +
+      `Without it, 'sourcemap apply' silently applies nothing.\n` +


Without it, 'sourcemap apply' fails with a symbolication error.\n would be more correct, because in that case it actually fails.

It actually doesn't fail and rather fails silently. But I don't think we should care about that case in the runtime of the cli, since it's mostly a packaging thing.

Added a SourceMapRunner type and an optional `run` argument to doSourceMapSymbolication through applySourceMapFile, to make the source map symbolication runner injectable. The default behavior stays as the Web Worker runner, but let's the non-browser callers inject a runner that calls the core logic directly, since the profiler-cli Node daemon has no Workers.

`ApplySourceMapFileResult` only carried the resolved bundle source's filename, which is all the web UI needs. Add the source table index alongside it, so callers that identify sources by index rather than by name can report which source the map landed on. A follow-up uses this to add "sourcemap" commands to profiler-cli, which refers to sources by "src-N" handles.

Lists the bundle sources that carry a `sourceMapURL` and are therefore eligible to have a `.map` applied to them -- the same set the web app's "Apply source map…" picker offers. Each gets a `src-N` handle, which is a direct index into `profile.shared.sources` and so is stable across sessions for the same profile, like `f-N`. Firefox stores an inline map's entire `data:` URL in the source table, so a "URL" can be megabytes of base64. Those are reported by media type and size instead, which keeps the payload out of both the text and `--json` output. The integration fixtures are pre-generated and committed because the profile builders are DOM-coupled and can't run in the node-env test process, so sourcemap-generator.ts regenerates them via a browser-env test. A follow-up adds "sourcemap apply", which consumes these handles.

Brings the web app's "Apply source map…" feature to profiler-cli, reusing the shared `applySourceMapFile` thunk. Since the CLI is one-shot, the web picker becomes a two-step flow: "sourcemap sources" lists the candidates, then "sourcemap apply <path> [--to src-N]" reads the .map on the daemon, auto-matches it to a source (or applies to the source given by --to) and re-symbolicates in place. Ambiguous matches and errors exit non-zero so scripts can branch on them. The daemon has no Web Worker, so it injects a runner that calls the symbolication core directly on the current thread. That core's `source-map` dependency reads its WASM parser from `path.join(__dirname, 'mappings.wasm')` at runtime, and esbuild does not bundle that file, so the build copies it next to the bundle and the publish check now fails if it is missing -- without it, "sourcemap apply" silently applies nothing. `--to` only accepts sources that carry a `sourceMapURL`, the same set the web picker offers. Applying a map to any other source would skip the auto-match step's `no-eligible-sources` guard and then de-minify nothing, which reads as a successful apply.

Adds a SOURCE MAPS section covering the sources -> apply flow and the --to disambiguation step, and lists src-N in the handle reference tables alongside t-N / f-N / c-N / ts-N.

canova

Thanks!

canova · 2026-08-10T13:06:34Z

+if (!existsSync(wasmUrl)) {
+  console.error(
+    `profiler-cli source map parser not found at ${fileURLToPath(wasmUrl)}.\n` +
+      `Without it, 'sourcemap apply' silently applies nothing.\n` +


It actually doesn't fail and rather fails silently. But I don't think we should care about that case in the runtime of the cli, since it's mostly a packaging thing.

canova · 2026-08-10T13:08:31Z

+  return {
+    kind: 'inline',
+    mediaType: sourceMapURL.slice('data:'.length).split(',', 1)[0],
+    byteLength: sourceMapURL.length,


Technically you're right, but I don't think we should do it here. This is already an approximation, so it doesn't have to be strictly accurate.

canova · 2026-08-10T13:10:49Z

+    case 'sourcemap-ambiguous': {
+      const lines = result.candidates.map(formatSourceEntry);
+      return [
+        'The source map matches more than one source. Re-run with --to <src-N> to pick one:',


Oh yeah, it looks like this is also an issue in the web frontend. I'll address that as a follow-up.

Changes: [fatadel] Create the Network track from the timeline-network schema display location (#6224) [Markus Stange] Only call `getRawFrameTableBuilderWithExistingContents` once per symbolication batch. (#6233) [fatadel] Improve discoverability of downloading a local profile (#6216) [Nazım Can Altınova] Handle the cli daemon startup failures more gracefully with better errors (#6241) [Nazım Can Altınova] Add the ability to apply source maps from the CLI (#6229) [Nazım Can Altınova] Handle Text and Log marker payloads with their marker schema (#6247) [Nazım Can Altınova] Bump the Gecko profile version to make sure that the Text and Log marker changes are picked up in the frontends (#6252) [fatadel] Deactivate a menu button as soon as its panel is dismissed (#6251) [Nazım Can Altınova] 🔃 Sync: l10n -> main (August 10, 2026) (#6253) [Nazım Can Altınova] Bump profiler-cli version to 0.8.0 (#6254) And special thanks to our localizers: de: Ger de: Michael Köhler el: George kitsoukakis en-CA: chutten en-CA: Saurabh en-GB: Ian Neal es-CL: ravmn fy-NL, nl: Fjoerfoks fr: Théo Chevalier fy-NL: Fjoerfoks ia: Melo46 it: Francesco Lodolo [:flod] nl: Fjoerfoks ru: michellemelsspam ru: Valery Ledovskoy tr: giray tr: Selim Şumlu zh-TW: Pin-guang Chen

canova requested review from fatadel and mstange July 31, 2026 11:43

fatadel approved these changes Aug 5, 2026

View reviewed changes

canova force-pushed the sourcemap-cli branch from 39d5b18 to 848f9ff Compare August 10, 2026 13:09

canova added 5 commits August 10, 2026 15:10

Document source maps in the profiler-cli guide

1d84c54

Adds a SOURCE MAPS section covering the sources -> apply flow and the --to disambiguation step, and lists src-N in the handle reference tables alongside t-N / f-N / c-N / ts-N.

canova force-pushed the sourcemap-cli branch from 848f9ff to 1d84c54 Compare August 10, 2026 13:10

canova commented Aug 10, 2026

View reviewed changes

canova enabled auto-merge August 10, 2026 13:11

canova merged commit 3c32b38 into firefox-devtools:main Aug 10, 2026
21 checks passed

canova mentioned this pull request Aug 10, 2026

Deploy August 10, 2026 #6255

Merged

Uh oh!

Conversation

canova commented Jul 31, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

fatadel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

canova left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

canova commented Jul 31, 2026 •

edited by github-actions Bot

Loading

codecov Bot commented Jul 31, 2026 •

edited

Loading