feat(bloat): graphviz .dot back-reference graphs (#463) (#468)

Closes #463.

Part 2 of #459: takes the `referenced_by` data shipped in #460 and
renders it as Graphviz `.dot` back-reference graphs. Three surfaces:

1. **`fbuild bloat graph <input> --symbol <S>`** — new CLI subcommand
   that walks the back-reference graph outward from one symbol and
   writes `.dot` to stdout or `-o <path>`. Reuses `fbuild symbols`'
   toolchain resolution (#428).
2. **Embedded `dot` blocks in `report.md`** — when `--output-dir` is
   given, the top-10 symbols each carry an inline fenced ```dot
   block under a `<details>` summary. AI-friendly: a fresh agent
   answers "what pulls in X?" from `report.md` alone, no extra
   fetches. `--no-graph` disables embedding.
3. **Sidecar `<output-dir>/graphs/*.dot`** — every symbol > 256 B
   gets a standalone file. Ranked + sanitized names
   (`0001_<symbol>.dot`) for ad-hoc `dot -Tsvg` rendering.

## Walker design

Pure module in `fbuild_core::symbol_analysis::graph`. BFS outward
from the root symbol's `referenced_by` list, then for each
referencing TU find every symbol defined there and merge their
back-references. Three termination predicates compose:

- **Adaptive (default):** stop when a branch leaves the root
  symbol's archive — the boundary where the symbol "escapes" its
  own library, which is what bloat analysts want.
- **Fan-out cap K=5:** per node, rank referencers by attributed
  flash bytes desc, keep top-K, collapse the rest into a
  `(… and N more)` super-node.
- **Hard depth cap N=4:** safety belt for adaptive.

Plus archive-level filters:
- `--collapse-archive libc.a,libgcc.a` (default) hides the libc
  internal-wrapper layer so non-libc callers stand out.
- `--exclude-archive ...` drops branches entirely.

## Rendering

- Nodes colored by archive group (FastLED yellow, ESP-IDF blue,
  mbedTLS purple, libc gray, app near-white).
- Node width sized by `log10(bytes)` so huge symbols stay big
  without dominating layout.
- Edges: `referencer -> referenced` (the "pull" direction).

## Tests

- `fbuild-core::symbol_analysis::graph::tests` (9): walker
  termination, fan-out overflow, exclude/collapse, .dot
  serialization, sanitization helpers.
- `fbuild-build::symbol_analyzer::tests` (4 new): markdown
  embedding, legacy path stays clean, sidecar file emission,
  sidecar disabled.
- `fbuild-cli::cli::graph_cmd::tests` (5): config parsing.

All 50+ symbol-analysis tests pass. clippy + fmt clean.

## CLI shape

Adds a new top-level `Bloat` subcommand parent for `graph`. The
existing `fbuild symbols` keeps its surface (still emits the same
report.json + report.md without graphs unless --output-dir is set;
embedded graphs are default-on when output-dir is given, off via
--no-graph). #434 can later add `Bloat::Report` as a sibling to
land the long-discussed `symbols` -> `bloat` rename without
disturbing this PR.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zackees

crates/fbuild-build/src/symbol_analyzer.rs

@@ -118,6 +118,46 @@ pub enum Commands {
         /// markdown report.
         #[arg(long, default_value = "25")]
         top: usize,
+        /// Skip embedded Graphviz `.dot` blocks in `report.md` and
+        /// don't write sidecar `graphs/*.dot` files. Use when a slim
+        /// report is preferred (e.g. CI bloat-budget gates that diff
+        /// only the JSON).
+        #[arg(long = "no-graph")]
+        no_graph: bool,
+        /// How many top symbols get an embedded back-reference graph
+        /// in `report.md` (default 10, capped by `--top`).
+        #[arg(long = "graph-top", default_value = "10")]
+        graph_top: usize,
+        /// Minimum size in bytes for a sidecar `.dot` file to be
+        /// written under `<output-dir>/graphs/`. Default 256 keeps
+        /// the per-symbol output to non-trivial contributors.
+        #[arg(long = "graph-min-bytes", default_value = "256")]
+        graph_min_bytes: u64,
+        /// Traversal depth: `adaptive` stops the first time a branch
+        /// leaves the root archive; `<N>` forces an exact hop count.
+        #[arg(long = "graph-depth", default_value = "adaptive")]
+        graph_depth: String,
+        /// Per-node fan-out cap (default 5). Excess referencers
+        /// collapse into a single `(… and N more)` super-node.
+        #[arg(long = "graph-fan-out", default_value = "5")]
+        graph_fan_out: usize,
+        /// Comma-separated archive list to collapse into per-archive
+        /// super-nodes. Default `libc.a,libgcc.a` hides the libc
+        /// internal-wrapper layer so non-libc callers stand out.
+        #[arg(long = "graph-collapse-archive", default_value = "libc.a,libgcc.a")]
+        graph_collapse_archive: String,
+        /// Comma-separated archive list to drop from the graph
+        /// entirely. Default empty.
+        #[arg(long = "graph-exclude-archive", default_value = "")]
+        graph_exclude_archive: String,
+    },
+    /// Bloat-related subcommands. Today this hosts `graph` (back-
+    /// reference Graphviz export, fbuild #463); when #434 lands the
+    /// report-rename, the existing `fbuild symbols` becomes
+    /// `fbuild bloat` and lives here as a sibling subcommand.
+    Bloat {
+        #[command(subcommand)]
+        cmd: BloatCmd,
     },
     /// Build firmware
     Build {
@@ -558,6 +598,61 @@ pub enum DaemonAction {
     },
 }
 
+/// Subcommands under `fbuild bloat`. The parent enum lives so future
+/// `bloat`-themed actions (report, diff, budget gate) cohabit cleanly;
+/// today only `graph` ships — see fbuild #463.
+#[derive(Subcommand)]
+pub enum BloatCmd {
+    /// Render a Graphviz `.dot` back-reference graph rooted at one
+    /// symbol. Walks the `referenced_by` data emitted by
+    /// `fbuild symbols` (#459) outward, applying cross-archive
+    /// termination + per-node fan-out caps + collapse-archive rules
+    /// so dense hubs like `printf` stay readable.
+    Graph {
+        /// ELF file OR project directory (same resolution as
+        /// `fbuild symbols`).
+        input: String,
+        /// Target symbol (mangled OR demangled — fbuild matches on
+        /// either).
+        #[arg(long, short = 's')]
+        symbol: String,
+        /// Path to the linker map (auto-detected if omitted).
+        #[arg(long)]
+        map: Option<String>,
+        /// Cross-toolchain `nm` (auto-resolved when omitted).
+        #[arg(long)]
+        nm: Option<String>,
+        /// Cross-toolchain `c++filt` (derived from `nm` stem when
+        /// omitted).
+        #[arg(long = "cppfilt")]
+        cppfilt: Option<String>,
+        /// Path to a `build_info.json` that carries toolchain paths.
+        #[arg(long = "build-info")]
+        build_info: Option<String>,
+        /// Output path for the `.dot` file. Defaults to stdout.
+        #[arg(short = 'o', long = "output")]
+        output: Option<String>,
+        /// Traversal depth: `adaptive` (default) or `<N>` for a fixed
+        /// hop count.
+        #[arg(long, default_value = "adaptive")]
+        depth: String,
+        /// Per-node fan-out cap (excess collapses into a `(… and N
+        /// more)` super-node).
+        #[arg(long = "fan-out", default_value = "5")]
+        fan_out: usize,
+        /// Hard cap on traversal depth (safety belt for adaptive).
+        #[arg(long = "max-depth", default_value = "4")]
+        max_depth: u32,
+        /// Comma-separated archive list to collapse into per-archive
+        /// super-nodes.
+        #[arg(long = "collapse-archive", default_value = "libc.a,libgcc.a")]
+        collapse_archive: String,
+        /// Comma-separated archive list to drop from the graph.
+        #[arg(long = "exclude-archive", default_value = "")]
+        exclude_archive: String,
+    },
+}
+
 /// Resolve project_dir: prefer the subcommand's value, fall back to the top-level positional arg,
 /// then default to ".".  This lets callers write either `fbuild build <dir>` or `fbuild <dir> build`.
 pub fn resolve_project_dir(
@@ -587,6 +682,8 @@ pub const KNOWN_SUBCOMMANDS: &[&str] = &[
     "lib-select",
     "compile-many",
     "ci",
+    "symbols",
+    "bloat",
 ];
 
 /// Rewrite `fbuild <dir> <subcommand> ...` → `fbuild <subcommand> <dir> ...`

crates/fbuild-cli/src/cli/args.rs

@@ -5,7 +5,7 @@ use clap::Parser;
 
 use crate::{daemon_client, lib_select, mcp};
 
-use super::args::{resolve_project_dir, rewrite_args, Cli, Commands};
+use super::args::{resolve_project_dir, rewrite_args, BloatCmd, Cli, Commands};
 use super::build::run_build;
 use super::clang_tools::{run_clang_tool, run_iwyu};
 use super::compile_many::{
@@ -14,6 +14,7 @@ use super::compile_many::{
 use super::daemon_cmd::run_daemon;
 use super::deploy::{run_deploy, run_monitor, run_test_emu};
 use super::device::run_device;
+use super::graph_cmd::run_bloat_graph;
 use super::lnk::run_lnk;
 use super::monitor_parse::parse_monitor_flags;
 use super::pio::{pio_build, pio_deploy, pio_monitor};
@@ -65,7 +66,59 @@ pub async fn async_main() {
             json,
             output_dir,
             top,
-        }) => run_symbols(input, map, nm, cppfilt, build_info, json, output_dir, top),
+            no_graph,
+            graph_top,
+            graph_min_bytes,
+            graph_depth,
+            graph_fan_out,
+            graph_collapse_archive,
+            graph_exclude_archive,
+        }) => run_symbols(
+            input,
+            map,
+            nm,
+            cppfilt,
+            build_info,
+            json,
+            output_dir,
+            top,
+            no_graph,
+            graph_top,
+            graph_min_bytes,
+            graph_depth,
+            graph_fan_out,
+            graph_collapse_archive,
+            graph_exclude_archive,
+        ),
+        Some(Commands::Bloat { cmd }) => match cmd {
+            BloatCmd::Graph {
+                input,
+                symbol,
+                map,
+                nm,
+                cppfilt,
+                build_info,
+                output,
+                depth,
+                fan_out,
+                max_depth,
+                collapse_archive,
+                exclude_archive,
+            } => run_bloat_graph(
+                input,
+                symbol,
+                map,
+                nm,
+                cppfilt,
+                build_info,
+                output,
+                depth,
+                fan_out,
+                max_depth,
+                collapse_archive,
+                exclude_archive,
+            ),
+        },
         Some(Commands::Build {
             project_dir,
             environment,

crates/fbuild-cli/src/cli/dispatch.rs

@@ -0,0 +1,180 @@
+//! `fbuild bloat graph` — render a back-reference graph for one
+//! symbol as Graphviz `.dot`.
+//!
+//! Consumes the same toolchain resolution as `fbuild symbols` (#428)
+//! so callers don't have to wire `--nm` / `--cppfilt` twice. Walks
+//! the symbol's transitive `referenced_by` data outward using the
+//! adaptive strategy documented in
+//! [`fbuild_core::symbol_analysis::graph`].
+//!
+//! Output goes either to `-o <path>` or stdout. The walker is pure
+//! (no I/O); this module is only the CLI glue.
+
+use std::path::PathBuf;
+
+use fbuild_build::symbol_analyzer::{
+    analyze_elf, default_map_path, discover_elf_in_project, AnalyzeConfig,
+};
+use fbuild_core::symbol_analysis::{BackrefGraph, GraphConfig, GraphDepth};
+use fbuild_core::{FbuildError, Result};
+
+use super::symbols_cmd::resolve_tool_paths_public;
+
+#[allow(clippy::too_many_arguments)]
+pub fn run_bloat_graph(
+    input: String,
+    symbol: String,
+    map: Option<String>,
+    nm: Option<String>,
+    cppfilt: Option<String>,
+    build_info: Option<String>,
+    output: Option<String>,
+    depth: String,
+    fan_out: usize,
+    max_depth: u32,
+    collapse_archive: String,
+    exclude_archive: String,
+) -> Result<()> {
+    let input_path = PathBuf::from(&input);
+    if !input_path.exists() {
+        return Err(FbuildError::BuildFailed(format!(
+            "input not found: {}",
+            input_path.display()
+        )));
+    }
+    let elf_path = if input_path.is_dir() {
+        discover_elf_in_project(&input_path).ok_or_else(|| {
+            FbuildError::BuildFailed(format!("no ELF found under {}", input_path.display()))
+        })?
+    } else {
+        input_path
+    };
+
+    let (nm_path, cppfilt_path) = resolve_tool_paths_public(
+        &elf_path,
+        nm.as_deref(),
+        cppfilt.as_deref(),
+        build_info.as_deref(),
+    )?;
+
+    let map_path_owned = map
+        .map(PathBuf::from)
+        .or_else(|| default_map_path(&elf_path));
+
+    let cfg = AnalyzeConfig {
+        elf_path: &elf_path,
+        map_path: map_path_owned.as_deref(),
+        nm_path: &nm_path,
+        cppfilt_path: cppfilt_path.as_deref(),
+    };
+    let report = analyze_elf(cfg)?;
+
+    let graph_config = parse_graph_config(
+        &depth,
+        fan_out,
+        max_depth,
+        &collapse_archive,
+        &exclude_archive,
+    )?;
+    let graph = BackrefGraph::build(&report, &symbol, &graph_config);
+    let dot = graph.to_dot();
+
+    match output {
+        Some(path) => {
+            std::fs::write(&path, &dot).map_err(|e| {
+                FbuildError::Io(std::io::Error::new(e.kind(), format!("write {path}: {e}")))
+            })?;
+            println!(
+                "Wrote back-reference graph for {symbol} to {path} ({} nodes, {} edges)",
+                graph.nodes.len(),
+                graph.edges.len()
+            );
+        }
+        None => {
+            print!("{dot}");
+        }
+    }
+    Ok(())
+}
+
+/// Parse the user-facing flag strings into a fully-populated
+/// [`GraphConfig`]. Public-ish helper because the report-embed path
+/// in `symbols_cmd.rs` parses the same flag shapes for the
+/// `--graph-*` set.
+pub fn parse_graph_config(
+    depth: &str,
+    fan_out: usize,
+    max_depth: u32,
+    collapse_archive: &str,
+    exclude_archive: &str,
+) -> Result<GraphConfig> {
+    let depth = match depth.trim().to_ascii_lowercase().as_str() {
+        "adaptive" | "auto" | "" => GraphDepth::Adaptive,
+        s => match s.parse::<u32>() {
+            Ok(n) => GraphDepth::Fixed(n),
+            Err(_) => {
+                return Err(FbuildError::BuildFailed(format!(
+                    "graph --depth: expected 'adaptive' or a non-negative \
+                     integer, got `{s}`"
+                )))
+            }
+        },
+    };
+    let collapse_archives: Vec<String> = split_archive_list(collapse_archive);
+    let exclude_archives: Vec<String> = split_archive_list(exclude_archive);
+    Ok(GraphConfig {
+        depth,
+        fan_out: fan_out.max(1),
+        max_depth: max_depth.max(1),
+        collapse_archives,
+        exclude_archives,
+    })
+}
+
+fn split_archive_list(s: &str) -> Vec<String> {
+    s.split(',')
+        .map(|x| x.trim())
+        .filter(|x| !x.is_empty())
+        .map(|x| x.to_string())
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_graph_config_adaptive_default() {
+        let c = parse_graph_config("adaptive", 5, 4, "libc.a,libgcc.a", "").unwrap();
+        assert!(matches!(c.depth, GraphDepth::Adaptive));
+        assert_eq!(c.fan_out, 5);
+        assert_eq!(c.max_depth, 4);
+        assert_eq!(c.collapse_archives, vec!["libc.a", "libgcc.a"]);
+        assert!(c.exclude_archives.is_empty());
+    }
+
+    #[test]
+    fn parse_graph_config_fixed_depth() {
+        let c = parse_graph_config("3", 5, 4, "", "").unwrap();
+        assert!(matches!(c.depth, GraphDepth::Fixed(3)));
+    }
+
+    #[test]
+    fn parse_graph_config_rejects_garbage_depth() {
+        let err = parse_graph_config("woof", 5, 4, "", "").unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("graph --depth"), "got: {msg}");
+    }
+
+    #[test]
+    fn split_archive_list_handles_spaces_and_empties() {
+        let v = split_archive_list("libc.a, libgcc.a ,, libm.a");
+        assert_eq!(v, vec!["libc.a", "libgcc.a", "libm.a"]);
+    }
+
+    #[test]
+    fn fan_out_zero_clamps_to_one() {
+        let c = parse_graph_config("adaptive", 0, 4, "", "").unwrap();
+        assert_eq!(c.fan_out, 1);
+    }
+}

crates/fbuild-cli/src/cli/graph_cmd.rs

@@ -17,6 +17,7 @@ pub mod daemon_cmd;
 pub mod deploy;
 pub mod device;
 pub mod dispatch;
+pub mod graph_cmd;
 pub mod lnk;
 pub mod monitor_parse;
 pub mod pio;