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)

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.

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

Codecov Report

❌ Patch coverage is 6.34921% with 59 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.52%. Comparing base (342d130) to head (39d5b18).
⚠️ Report is 45 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%	13 Missing ⚠️
src/profile-query/source-map.ts	0.00%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6229      +/-   ##
==========================================
- Coverage   83.65%   83.52%   -0.14%     
==========================================
  Files         348      350       +2     
  Lines       37339    37399      +60     
  Branches    10376    10394      +18     
==========================================
+ Hits        31237    31238       +1     
- Misses       5674     5733      +59     
  Partials      428      428

☔ 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.

fatadel · 2026-08-05T14:01:26Z

+      (result.type === 'sourcemap-ambiguous' ||
+        result.type === 'sourcemap-error')
+    ) {
+      process.exit(1);


console.log(formatOutput... then process.exit(1) can truncate stdout on a pipe, because when stdout is a pipe, Node's writes are async; process.exit drops anything still queued.

Fix: process.exitCode = 1; instead - the process still exits 1, but after the write drains.

fatadel · 2026-08-05T14:19:15Z

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


Maybe worth checking for presence of comma before splitting on it? Otherwise, the whole (potentially) megabytes of base64 would be returned in case of malformed source map url.

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?

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.

fatadel · 2026-08-05T15:15:11Z


 import { getThreadsKey } from 'firefox-profiler/profile-logic/profile-data';
 import type { Store } from '../types/store';
+import * as fs from 'fs';


Shouldn't this be at the very top of the import block? 🤔

fatadel · 2026-08-05T15:19:24Z

+
+  const sourceIndex = Number(match[1]);
+  if (
+    !Number.isInteger(sourceIndex) ||


Having this regex, we always have digits. So, Number() can't produce a non-integer or a negative. Thus, we can simplify the condition:

const sourceIndex = Number(match[1]); if (sourceIndex >= sourceCount) { throw new Error(`Unknown source ${sourceHandle}`); }

canova added 5 commits July 30, 2026 17:41

Document source maps in the profiler-cli guide

39d5b18

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 requested review from fatadel and mstange July 31, 2026 11:43

fatadel approved these changes Aug 5, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add the ability to apply source maps from the CLI - #6229

Add the ability to apply source maps from the CLI#6229
canova wants to merge 5 commits into
firefox-devtools:mainfrom
canova:sourcemap-cli

canova commented Jul 31, 2026 •

edited by github-actions Bot

Loading

Uh oh!

codecov Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

fatadel left a comment

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

fatadel Aug 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

fatadel Aug 5, 2026

Choose a reason for hiding this comment

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