cargo-unit: per-unit panic-freedom check via relocation scan (#309)

Adds an opt-in `--deny-panics` policy check to cargo-unit that fails a
build when a workspace function can reach a panic. Refs #307.

## Approach

Detection is relocation-based. rustc lowers a panic call to a relocation
whose target is an undefined panic sink (`core::panicking::*`, plus the
`unwrap_failed` / `expect_failed` cold helpers that `unwrap`/`expect`
route through, confirmed against the relocations rustc emits at
opt-level 0 and 3). The new `scan-panics` subcommand reads symbols and
relocations with the `object` crate and attributes each panic call to
its containing function, with no disassembler and no demangler, so one
path covers ELF and Mach-O.

To cover generics, the scan reads the relocatable objects of every
workspace unit, not just library rlibs. A generic carries no relocation
in its defining rlib because it is codegened where it is monomorphized;
the bin or test object that instantiates it does carry the relocation,
and the symbol keeps the defining crate's mangled token. Each unit
therefore gets a `panic-objects` derivation (a recompile with `--emit
obj`, mirroring the clippy units), and findings are scoped to the whole
workspace crate set so a library generic monomorphized inside another
unit is attributed back to its crate.

This was the deliberate design after ruling out the naive alternative: a
trivial clean std binary already carries ~36 `panicking` symbols from
std's runtime, so a whole-artifact symbol grep is always-red for std
code. Relocation attribution scoped to the workspace crate set is the
signal that actually means "this workspace's code can panic."

## What it does

- `--deny-panics` renders `policyChecks.panicFreedom`: one scan
derivation per workspace unit, joined under one aggregate, so a touched
unit only re-scans itself.
- Each scan runs `nix-cargo-unit scan-panics --crate-name ...` over the
unit's `panic-objects` derivation, scoped to the workspace crate set.
- The scanner is the `cargoUnit` package, threaded through a new
`cargoUnit` template argument and asserted non-null, so enabling the
policy without wiring the scanner fails loudly instead of silently
passing.

## Validation

- 45 Rust tests pass (hermetic scanner tests synthesize objects via
`object::write`, no rustc dependency), clippy clean, fmt clean,
generated Nix parses.
- End-to-end on real crates: `unwrap`/`expect`/indexing are flagged with
their exact entrypoints; a generic `pub fn first<T>(xs:&[T])->T{xs[3]}`
invisible in its own rlib is caught via a consumer's objects and
attributed to its defining crate; a clean crate and a crate with its own
`panicking` module both pass.

## Known limitations (documented in code)

- Best-effort, not a soundness proof. The residual gap is a public
generic that no workspace bin/test ever instantiates (never codegened
anywhere here, and also unreachable from the workspace's own
entrypoints). The sound successor is call-graph reachability over the
linked, monomorphized binary (what `findpanics` does).
- The panic-sink catalog is curated; a panic routed through some other
std/alloc cold path is missed until its symbol is added.
- The `ix.cargoUnit.buildWorkspace` `policy` toggle that passes
`cargoUnit` and sets `--deny-panics` lives in the `ix` repo and is the
remaining integration step before this runs in a real workspace.

Author: andrewgazelka

Cargo.lock

@@ -56,6 +56,11 @@ loro = "1.12"
 ndarray = "0.16"
 nix-web-monitor-parser = { path = "packages/nix-web-monitor/parser" }
 numpy = "0.28"
+object = { version = "0.37", default-features = false, features = [
+  "read",
+  "write",
+  "std",
+] }
 parking_lot = "0.12"
 pty-process = { version = "0.4", features = ["async"] }
 pyo3 = { version = "0.28", features = ["abi3-py311"] }

Cargo.toml

@@ -256,7 +256,8 @@ let
         toolchainId
       ]
       ++ lib.optional args.contentAddressed "--content-addressed"
-      ++ lib.optional args.policy.denyUnusedCrateDependencies "--deny-unused-crate-dependencies";
+      ++ lib.optional args.policy.denyUnusedCrateDependencies "--deny-unused-crate-dependencies"
+      ++ lib.optional args.policy.denyPanics "--deny-panics";
     in
     pkgs.runCommand "cargo-units.nix"
       {
@@ -372,6 +373,9 @@ let
           rustToolchain
           ;
         inherit workspaceRoot;
+        # Scanner for the opt-in panic-freedom policy. The rendered check
+        # asserts this is non-null when `policy.denyPanics` is set.
+        cargoUnit = nixCargoUnit;
         extraNativeBuildInputs = args.nativeBuildInputs ++ rust.nativeBuildInputsForPolicy args.policy;
         # `clippy-driver` ships in the clippy package; `rustToolchain` only
         # guarantees rustc + cargo. Adding the resolved clippy package keeps

lib/cargo-unit.nix

@@ -23,6 +23,9 @@ let
 
   defaultPolicy = {
     denyUnusedCrateDependencies = true;
+    # Opt-in: scans each unit's objects for functions that can reach a panic.
+    # Off by default because it is a best-effort gate, not a soundness proof.
+    denyPanics = false;
     cargoAudit = {
       enable = false;
       db = defaultRustsecAdvisoryDb;
@@ -63,6 +66,7 @@ let
     {
       denyUnusedCrateDependencies =
         rawPolicy.denyUnusedCrateDependencies or defaultPolicy.denyUnusedCrateDependencies;
+      denyPanics = rawPolicy.denyPanics or defaultPolicy.denyPanics;
       cargoAudit = {
         enable = cargoAudit.enable or defaultPolicy.cargoAudit.enable;
         db = cargoAudit.db or defaultPolicy.cargoAudit.db;

lib/rust.nix

@@ -13,6 +13,7 @@ workspace = true
 askama = { workspace = true, default-features = false, features = ["derive", "std"] }
 clap = { workspace = true, features = ["derive"] }
 color-eyre.workspace = true
+object.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
 sha2.workspace = true

packages/nix-cargo-unit/Cargo.toml

@@ -1,5 +1,6 @@
 mod hash;
 mod model;
+mod panic_scan;
 mod render;
 mod shell;
 
@@ -28,6 +29,24 @@ enum Command {
 
     /// Render generated Nix from Cargo unit-graph JSON on stdin.
     Render(RenderArgs),
+
+    /// Scan compiled rlib artifacts for functions that can reach a panic.
+    ScanPanics(ScanPanicsArgs),
+}
+
+#[derive(Debug, clap::Args)]
+struct ScanPanicsArgs {
+    /// Workspace crate (Cargo target name) whose functions findings are scoped
+    /// to. Repeat for the full workspace set so a library generic monomorphized
+    /// in another unit's object is still attributed. Omit to report every
+    /// panic-reaching function.
+    #[arg(long = "crate-name", value_name = "NAME")]
+    crate_names: Vec<String>,
+
+    /// Rlib or object artifacts, or directories to scan. Directories are
+    /// searched for `*.rlib` and `*.o` recursively.
+    #[arg(required = true, value_name = "PATH")]
+    paths: Vec<PathBuf>,
 }
 
 #[derive(Debug, clap::Args)]
@@ -62,6 +81,11 @@ struct RenderArgs {
     /// Collect and fail builds on dependencies unused across all local package units.
     #[arg(long)]
     deny_unused_crate_dependencies: bool,
+
+    /// Emit a per-unit panic-freedom policy check that scans each local unit's
+    /// compiled artifact for reachable panic machinery and fails if any is found.
+    #[arg(long)]
+    deny_panics: bool,
 }
 
 fn merge(args: MergeArgs) -> color_eyre::Result<()> {
@@ -103,6 +127,7 @@ fn render(args: RenderArgs) -> color_eyre::Result<()> {
             content_addressed: args.content_addressed,
             toolchain_id: args.toolchain_id,
             deny_unused_crate_dependencies: args.deny_unused_crate_dependencies,
+            deny_panics: args.deny_panics,
         },
     )
     .wrap_err("rendering Cargo unit graph as Nix")?;
@@ -111,11 +136,52 @@ fn render(args: RenderArgs) -> color_eyre::Result<()> {
     Ok(())
 }
 
+fn scan_panics(args: ScanPanicsArgs) -> color_eyre::Result<()> {
+    let ScanPanicsArgs { crate_names, paths } = args;
+    let artifacts = panic_scan::collect_artifacts(&paths)?;
+    // Fail closed: a panic gate that finds nothing to inspect must error, not
+    // report success, or a wrong path or empty object set would pass open.
+    if artifacts.is_empty() {
+        color_eyre::eyre::bail!(
+            "cargo-unit panic-freedom: no .rlib or .o artifacts found under {}",
+            paths
+                .iter()
+                .map(|path| path.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ")
+        );
+    }
+    let crate_tokens: Vec<String> = crate_names
+        .iter()
+        .map(|name| panic_scan::crate_token(name))
+        .collect();
+    let findings = panic_scan::scan_paths(&artifacts, &crate_tokens)?;
+
+    if findings.is_empty() {
+        return Ok(());
+    }
+
+    let scope = if crate_names.is_empty() {
+        String::new()
+    } else {
+        format!(" in {}", crate_names.join(", "))
+    };
+    eprintln!(
+        "error: cargo-unit panic-freedom: {} function(s){scope} can reach panic machinery",
+        findings.len()
+    );
+    for finding in &findings {
+        eprintln!("  {} -> {}", finding.function, finding.panic_entrypoint);
+    }
+    std::process::exit(1);
+}
+
 fn main() -> color_eyre::Result<()> {
     color_eyre::install()?;
 
     match Cli::parse().command {
         Command::Merge(args) => merge(args),
         Command::Render(args) => render(args),
+        Command::ScanPanics(args) => scan_panics(args),
     }
 }