feat(debug-files): add print-sources command

docs/src/content/docs/contributing.md

@@ -58,7 +58,7 @@ cli/
 │   │   ├── code-mappings/# upload
 │   │   ├── dart-symbol-map/# upload
 │   │   ├── dashboard/   # add, create, delete, edit, list, restore, revisions, view
-│   │   ├── debug-files/ # bundle-jvm, bundle-sources, check
+│   │   ├── debug-files/ # bundle-jvm, bundle-sources, check, print-sources
 │   │   ├── event/       # list, send, view
 │   │   ├── issue/       # archive, events, explain, list, merge, plan, resolve, unresolve, view
 │   │   ├── local/       # run, serve

docs/src/fragments/commands/debug-files.md

@@ -9,6 +9,10 @@ sentry debug-files check ./libexample.so
 sentry debug-files check MyApp.dSYM/Contents/Resources/DWARF/MyApp
 sentry debug-files check ./app.pdb --json
 
+# List the source files a debug file references (and whether they're available)
+sentry debug-files print-sources ./libexample.so
+sentry debug-files print-sources ./app.pdb --json
+
 # Bundle a debug file's referenced source files (run on the build machine)
 sentry debug-files bundle-sources ./libexample.so
 sentry debug-files bundle-sources ./app.pdb --output ./app.src.zip
@@ -25,12 +29,16 @@ sentry debug-files bundle-jvm --output ./out --debug-id <uuid> --json ./src
 
 ## Important Notes
 
-- `check`, `bundle-sources`, and `bundle-jvm` are **local-only** — they make no
-  network requests. They parse object files in-process (Mach-O/dSYM, ELF,
-  PE/PDB, Portable PDB, WebAssembly, Breakpad, source bundles) via a bundled
-  `symbolic` WASM module.
+- `check`, `print-sources`, `bundle-sources`, and `bundle-jvm` are **local-only**
+  — they make no network requests. They parse object files in-process
+  (Mach-O/dSYM, ELF, PE/PDB, Portable PDB, WebAssembly, Breakpad, source bundles)
+  via a bundled `symbolic` WASM module.
 - `check` exits non-zero if the file is not usable for symbolication (no debug
   id or no useful features).
+- `print-sources` lists the source files each object references, reporting for
+  each whether the source is embedded in the debug file, available via a source
+  link, or present on the local disk. It is a read-only preview of what
+  `bundle-sources` would collect and always exits zero on a parseable file.
 - `bundle-sources` reads source files from the paths recorded in the debug info,
   so it is normally run on the build machine right after compiling. Referenced
   files that are not present locally are skipped; it exits non-zero (writing

package.json

@@ -16,7 +16,7 @@
     "@sentry/core": "10.50.0",
     "@sentry/node-core": "10.50.0",
     "@sentry/sqlish": "^1.0.1",
-    "@sentry/symbolic": "13.4.0",
+    "@sentry/symbolic": "13.5.0",
     "@spotlightjs/spotlight": "^4.11.7",
     "@stricli/auto-complete": "^1.2.8",
     "@stricli/core": "1.2.7",

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -411,8 +411,9 @@ Work with Dart/Flutter symbol maps
 Work with debug information files
 
 - `sentry debug-files check <path>` — Inspect a debug information file
-- `sentry debug-files bundle-jvm <path>` — Create a JVM source bundle for source context
+- `sentry debug-files print-sources <path>` — List the source files a debug file references
 - `sentry debug-files bundle-sources <path>` — Bundle a debug file's source files for source context
+- `sentry debug-files bundle-jvm <path>` — Create a JVM source bundle for source context
 
 → Full flags and examples: `references/debug-files.md`
 

plugins/sentry-cli/skills/sentry-cli/references/debug-files.md

@@ -15,14 +15,9 @@ Work with debug information files
 
 Inspect a debug information file
 
-### `sentry debug-files bundle-jvm <path>`
+### `sentry debug-files print-sources <path>`
 
-Create a JVM source bundle for source context
-
-**Flags:**
-- `-o, --output <value> - Output directory for the bundle ZIP`
-- `-d, --debug-id <value> - Debug ID (UUID) to stamp on the bundle`
-- `-e, --exclude <value>... - Additional directory names to exclude (repeatable)`
+List the source files a debug file references
 
 ### `sentry debug-files bundle-sources <path>`
 
@@ -31,6 +26,15 @@ Bundle a debug file's source files for source context
 **Flags:**
 - `-o, --output <value> - Output path for the source bundle ZIP (default: <path>.src.zip)`
 
+### `sentry debug-files bundle-jvm <path>`
+
+Create a JVM source bundle for source context
+
+**Flags:**
+- `-o, --output <value> - Output directory for the bundle ZIP`
+- `-d, --debug-id <value> - Debug ID (UUID) to stamp on the bundle`
+- `-e, --exclude <value>... - Additional directory names to exclude (repeatable)`
+
 **Examples:**
 
 ```bash
@@ -39,6 +43,10 @@ sentry debug-files check ./libexample.so
 sentry debug-files check MyApp.dSYM/Contents/Resources/DWARF/MyApp
 sentry debug-files check ./app.pdb --json
 
+# List the source files a debug file references (and whether they're available)
+sentry debug-files print-sources ./libexample.so
+sentry debug-files print-sources ./app.pdb --json
+
 # Bundle a debug file's referenced source files (run on the build machine)
 sentry debug-files bundle-sources ./libexample.so
 sentry debug-files bundle-sources ./app.pdb --output ./app.src.zip

src/commands/debug-files/index.ts

@@ -8,12 +8,14 @@ import { buildRouteMap } from "../../lib/route-map.js";
 import { bundleJvmCommand } from "./bundle-jvm.js";
 import { bundleSourcesCommand } from "./bundle-sources.js";
 import { checkCommand } from "./check.js";
+import { printSourcesCommand } from "./print-sources.js";
 
 export const debugFilesRoute = buildRouteMap({
   routes: {
     check: checkCommand,
-    "bundle-jvm": bundleJvmCommand,
+    "print-sources": printSourcesCommand,
     "bundle-sources": bundleSourcesCommand,
+    "bundle-jvm": bundleJvmCommand,
   },
   docs: {
     brief: "Work with debug information files",

src/commands/debug-files/print-sources.ts

@@ -0,0 +1,209 @@
+/**
+ * sentry debug-files print-sources <path>
+ *
+ * List the source files referenced by a debug information file (Mach-O/dSYM,
+ * ELF, PE/PDB, Portable PDB, Breakpad, source bundles). For each referenced
+ * file it reports whether the source is embedded, available via a source link,
+ * or present on the local disk.
+ *
+ * This mirrors the legacy `sentry-cli difutil print-sources` and complements
+ * `bundle-sources`. Local-only — no API calls. Parsing happens in-process via
+ * the bundled `symbolic` WASM module (see `src/lib/dif/`).
+ */
+
+import { existsSync } from "node:fs";
+import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
+import {
+  type DifSourcesInfo,
+  listSources,
+  selectBundledObject,
+} from "../../lib/dif/index.js";
+import { ValidationError } from "../../lib/errors.js";
+import {
+  colorTag,
+  renderMarkdown,
+  safeCodeSpan,
+} from "../../lib/formatters/markdown.js";
+import { CommandOutput } from "../../lib/formatters/output.js";
+import { logger } from "../../lib/logger.js";
+import { readDebugFile } from "./read-file.js";
+
+const USAGE_HINT = "sentry debug-files print-sources <path>";
+
+const log = logger.withTag("debug-files.print-sources");
+
+/** A referenced source file augmented with local-disk availability. */
+type PrintSourcesFile = DifSourcesInfo["objects"][number]["files"][number] & {
+  /** Whether the file exists on the local disk; `null` when embedded or linked. */
+  availableLocally: boolean | null;
+};
+
+/** Per-object referenced sources for the command output. */
+type PrintSourcesObject = {
+  debugId: string;
+  fileFormat: string;
+  /**
+   * Whether this object carries debug info. Exposed so `--json` consumers can
+   * apply the same `selectBundledObject` rule `bundle-sources` uses to pick the
+   * single slice it bundles.
+   */
+  hasDebugInfo: boolean;
+  /** Error message if enumerating this object's sources failed, else `null`. */
+  enumerationError: string | null;
+  files: PrintSourcesFile[];
+};
+
+/** Structured result yielded by the command (and serialized to JSON). */
+type PrintSourcesResult = {
+  path: string;
+  objects: PrintSourcesObject[];
+};
+
+/** Short, human-readable description of where a referenced source lives. */
+function describeSource(file: PrintSourcesFile): string {
+  if (file.url !== null) {
+    return colorTag("muted", `source link: ${file.url}`);
+  }
+  if (file.resolved) {
+    return colorTag("muted", "embedded");
+  }
+  if (file.availableLocally) {
+    return colorTag("muted", "not embedded, available locally");
+  }
+  return colorTag("muted", "not embedded, not available locally");
+}
+
+/** Human formatter: one section per object, listing each referenced source. */
+function formatPrintSources(data: PrintSourcesResult): string {
+  if (data.objects.length === 0) {
+    return renderMarkdown(colorTag("muted", "No objects found in the file."));
+  }
+
+  const sections = data.objects.map((object) => {
+    const header = `${object.fileFormat} ${safeCodeSpan(object.debugId)}`;
+    if (object.enumerationError !== null) {
+      return `${header} — ${colorTag("muted", `could not read sources: ${object.enumerationError}`)}`;
+    }
+    if (object.files.length === 0) {
+      return `${header} — ${colorTag("muted", "no referenced sources")}`;
+    }
+    const lines = object.files.map(
+      (file) => `- ${safeCodeSpan(file.path)} — ${describeSource(file)}`
+    );
+    const count = object.files.length;
+    return `${header} — ${count} source file${count === 1 ? "" : "s"}:\n\n${lines.join("\n")}`;
+  });
+
+  return renderMarkdown(sections.join("\n\n"));
+}
+
+export const printSourcesCommand = buildCommand({
+  // Local-only: parses + enumerates in-process, no API calls.
+  auth: false,
+  docs: {
+    brief: "List the source files a debug file references",
+    fullDescription:
+      "List the source files referenced by a debug information file. For each " +
+      "referenced file it reports whether the source is embedded in the file, " +
+      "available via a source link, or present on the local disk — useful for " +
+      "checking what `bundle-sources` would include. Supports Mach-O/dSYM, " +
+      "ELF, PE/PDB, Portable PDB, and Breakpad.\n\n" +
+      "The format is auto-detected. This command is local-only and makes no " +
+      "network requests.\n\n" +
+      "Usage:\n" +
+      "  sentry debug-files print-sources ./libexample.so\n" +
+      "  sentry debug-files print-sources ./app.pdb --json",
+  },
+  output: {
+    human: formatPrintSources,
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          brief: "Path to the debug information file",
+          parse: String,
+          placeholder: "path",
+        },
+      ],
+    },
+    flags: {},
+  },
+  async *func(
+    this: SentryContext,
+    _flags: Record<string, never>,
+    path: string
+  ) {
+    const content = await readDebugFile(path);
+
+    let info: DifSourcesInfo;
+    try {
+      info = listSources(new Uint8Array(content));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new ValidationError(
+        `'${path}' is not a recognized debug information file: ${msg}`,
+        "path"
+      );
+    }
+
+    const objects: PrintSourcesObject[] = info.objects.map((object) => ({
+      debugId: object.debugId,
+      fileFormat: object.fileFormat,
+      hasDebugInfo: object.hasDebugInfo,
+      enumerationError: object.enumerationError,
+      files: object.files.map((file) => ({
+        ...file,
+        // Local availability only matters for files that aren't embedded/linked.
+        availableLocally: file.resolved ? null : existsSync(file.path),
+      })),
+    }));
+
+    // Surface objects whose source enumeration failed: their empty file list is
+    // a degraded result, not a genuine "no sources" — warn so it isn't read as
+    // the latter (the command still exits zero since the file itself parsed).
+    const failed = objects.filter((object) => object.enumerationError !== null);
+    for (const object of failed) {
+      log.warn(
+        `Could not enumerate sources for ${object.debugId} in '${path}': ${object.enumerationError}`
+      );
+    }
+
+    // All slices are listed for inspection, but `bundle-sources` only bundles
+    // one of them. Warn (mirroring `bundle-sources`) so the preview does not
+    // imply every listed source would end up in the bundle.
+    const bundled = selectBundledObject(info.objects);
+    if (info.objects.length > 1 && bundled) {
+      log.warn(
+        `'${path}' contains ${info.objects.length} objects; ` +
+          `\`bundle-sources\` would bundle sources for ${bundled.debugId} only. ` +
+          "Other slices are not included."
+      );
+    }
+
+    yield new CommandOutput<PrintSourcesResult>({ path, objects });
+
+    if (objects.length === 0) {
+      return { hint: `No objects found in '${path}'. Try: ${USAGE_HINT}` };
+    }
+    const total = objects.reduce((sum, object) => sum + object.files.length, 0);
+    if (total === 0) {
+      // If any slice failed to enumerate, "no sources" is not a safe
+      // conclusion — even when other slices genuinely reference none — so the
+      // hint must not contradict the per-slice enumeration warnings.
+      if (failed.length > 0) {
+        return {
+          hint: `Could not read referenced sources from '${path}'. Re-run with --log-level=debug for details.`,
+        };
+      }
+      return {
+        hint: `No referenced sources found in '${path}'. Try: ${USAGE_HINT}`,
+      };
+    }
+    return {
+      hint: `Bundle these into a source bundle with: sentry debug-files bundle-sources ${path}`,
+    };
+  },
+});