feat(hugr-llvm)!: Add support for emitting debug locations

Cargo.toml

@@ -56,6 +56,7 @@ num-rational = "0.4.1"
 pastey = "0.2.1"
 proptest = "1.11.0"
 proptest-derive = "0.8.0"
+rand = "0.10.1"
 regex = "1.12.3"
 regex-syntax = "0.8.9"
 rstest = "0.26.1"

hugr-cli/src/mermaid.rs

@@ -7,6 +7,8 @@ use anyhow::Result;
 use clap::Parser;
 use clio::Output;
 use hugr::HugrView;
+use hugr::hugr::views::render::NodeLabel;
+use hugr::metadata::DEBUGINFO_META_KEY;
 use hugr::package::PackageValidationError;
 
 /// Dump the standard extensions.
@@ -26,6 +28,16 @@ pub struct MermaidArgs {
         help = "Validate before rendering, includes extension inference."
     )]
     pub validate: bool,
+
+    /// Print debug metadata.
+    #[arg(
+        short = 'D',
+        long,
+        help = "Print debug info attached to nodes if it exists. For rendering purposes, \
+                we replace double quotes with single quotes and newlines with spaces."
+    )]
+    pub debug_info: bool,
+
     /// Output file '-' for stdout
     #[clap(long, short, value_parser, default_value = "-")]
     output: Output,
@@ -64,10 +76,19 @@ impl MermaidArgs {
         }
 
         for hugr in package.modules {
+            let mmd_fmt = if self.debug_info {
+                hugr.mermaid_format()
+                    .with_node_labels(NodeLabel::MetadataValues {
+                        print_keys: [DEBUGINFO_META_KEY.to_string()].into(),
+                    })
+            } else {
+                hugr.mermaid_format()
+            };
+
             if let Some(ref mut writer) = output_override {
-                writeln!(writer, "{}", hugr.mermaid_string())?;
+                writeln!(writer, "{}", mmd_fmt.finish())?;
             } else {
-                writeln!(self.output, "{}", hugr.mermaid_string())?;
+                writeln!(self.output, "{}", mmd_fmt.finish())?;
             }
         }
         Ok(())

hugr-core/src/hugr/views.rs

@@ -13,6 +13,7 @@ mod tests;
 
 use ::petgraph::visit as pv;
 use serde::de::Deserialize;
+use std::any::type_name;
 use std::borrow::Cow;
 use std::collections::HashMap;
 
@@ -30,7 +31,7 @@ use crate::core::HugrNode;
 use crate::extension::ExtensionRegistry;
 use crate::hugr::internal::{DefaultPGNodeMap, PortgraphNodeMap};
 use crate::hugr::views::syn_edge::SynEdgeWrapper;
-use crate::metadata::{Metadata, RawMetadataValue};
+use crate::metadata::{Metadata, MetadataError, RawMetadataValue};
 use crate::ops::{OpParent, OpTag, OpTrait, OpType, handle::NodeHandle};
 use crate::types::{EdgeKind, PolyFuncType, Signature, Type};
 use crate::{Direction, IncomingPort, OutgoingPort, Port};
@@ -112,6 +113,31 @@ pub trait HugrView: HugrInternals {
             .and_then(|value| <<M as Metadata>::Type<'_> as Deserialize>::deserialize(value).ok())
     }
 
+    /// Returns the metadata associated with a node, differentiating between a missing and
+    /// invalid payload.
+    ///
+    /// If there is no metadata found with a key matching `M::KEY` or `M::ALIASES`, returns Ok(None)
+    /// If metadata is present but it does not deserialize into M, return Err
+    /// Otherwise, return Ok(Some(metadata)).
+    #[inline]
+    fn try_get_metadata<M: Metadata>(
+        &self,
+        node: Self::Node,
+    ) -> Result<Option<<M as Metadata>::Type<'_>>, MetadataError> {
+        if let Some(raw_value) = std::iter::once(<M as Metadata>::KEY)
+            .chain(<M as Metadata>::ALIASES.iter().copied())
+            .find_map(|key| self.get_metadata_any(node, key))
+        {
+            <<M as Metadata>::Type<'_> as Deserialize>::deserialize(raw_value)
+                .map_err(|json_err| {
+                    MetadataError::MetadataDeserializationError(type_name::<M>(), json_err)
+                })
+                .map(Some)
+        } else {
+            Ok(None)
+        }
+    }
+
     /// Returns a metadata entry associated with a node and a string key.
     ///
     /// When possible, prefer using the type-safe accessor [`HugrView::get_metadata`] instead.

hugr-core/src/hugr/views/render.rs

@@ -1,6 +1,7 @@
 //! Helper methods to compute the node/edge/port style when rendering a HUGR
 //! into dot or mermaid format.
 
+use itertools::Itertools;
 use std::collections::HashMap;
 
 use portgraph::render::{EdgeStyle, NodeStyle, PortStyle, PresentationStyle};
@@ -179,6 +180,12 @@ pub enum NodeLabel<N: HugrNode = Node> {
     /// Display the node index as a number.
     #[default]
     Numeric,
+    /// Display the numeric node index and a list of metadata keys and their JSON values.
+    /// Prints "null" if a key is not present on a node.
+    MetadataValues {
+        /// List of metadata keys to display
+        print_keys: Vec<String>,
+    },
     /// Display the labels corresponding to the node indices.
     Custom(HashMap<N, String>),
 }
@@ -196,6 +203,14 @@ pub(in crate::hugr) fn node_style<'a>(
         }
     }
 
+    fn numeric_label(h: &Hugr, n: NodeIndex, is_entry: bool) -> String {
+        if is_entry {
+            format!("({}) [**{}**]", n.index(), node_name(h, n))
+        } else {
+            format!("({}) {}", n.index(), node_name(h, n))
+        }
+    }
+
     let mut entrypoint_style = PresentationStyle::default();
     entrypoint_style.stroke = Some("#832561".to_string());
     entrypoint_style.stroke_width = Some("3px".to_string());
@@ -204,18 +219,9 @@ pub(in crate::hugr) fn node_style<'a>(
     match formatter.node_labels {
         NodeLabel::Numeric => Box::new(move |n| {
             if Some(n) == entrypoint {
-                NodeStyle::boxed(format!(
-                    "({ni}) [**{name}**]",
-                    ni = n.index(),
-                    name = node_name(h, n)
-                ))
-                .with_attrs(entrypoint_style.clone())
+                NodeStyle::boxed(numeric_label(h, n, true)).with_attrs(entrypoint_style.clone())
             } else {
-                NodeStyle::boxed(format!(
-                    "({ni}) {name}",
-                    ni = n.index(),
-                    name = node_name(h, n)
-                ))
+                NodeStyle::boxed(numeric_label(h, n, false))
             }
         }),
         NodeLabel::None => Box::new(move |n| {
@@ -226,6 +232,32 @@ pub(in crate::hugr) fn node_style<'a>(
                 NodeStyle::boxed(node_name(h, n))
             }
         }),
+        NodeLabel::MetadataValues { print_keys } => Box::new(move |n| {
+            let kv_str = print_keys
+                .iter()
+                .filter_map(|key| {
+                    h.get_metadata_any(n.into(), key).map(|json_value| {
+                        format!(
+                            "{key}={}",
+                            serde_json::to_string(json_value)
+                                .expect("JSON metadata should be serializable")
+                                // the mermaid renderer in portgraph generates verbose escapes
+                                // for double quotes and newlines, so we replace them with
+                                // single quotes and spaces
+                                .replace('\n', " ")
+                                .replace('"', "\'")
+                        )
+                    })
+                })
+                .join("; ");
+
+            if Some(n) == entrypoint {
+                NodeStyle::boxed(format!("{}; {kv_str}", numeric_label(h, n, true)))
+                    .with_attrs(entrypoint_style.clone())
+            } else {
+                NodeStyle::boxed(format!("{}; {kv_str}", numeric_label(h, n, false)))
+            }
+        }),
         NodeLabel::Custom(labels) => Box::new(move |n| {
             if Some(n) == entrypoint {
                 NodeStyle::boxed(format!(

hugr-core/src/metadata.rs

@@ -22,6 +22,16 @@
 //! let payload = hugr.get_metadata::<SomeMetadata>(hugr.module_root());
 //! assert_eq!(payload, Some("payload"));
 //! ```
+
+/// Definitions of the HUGR debug info metadata types
+pub mod debug_info;
+
+use thiserror::Error;
+
+#[doc(inline)]
+pub use self::debug_info::{
+    CompileUnitRecord, DEBUGINFO_META_KEY, DebugRecordKind, LocationRecord, SubprogramRecord,
+};
 //
 // When adding new metadata keys, they should be re-exported by the python bindings.
 // See hugr-py/rust/metadata.rs
@@ -73,3 +83,12 @@ impl Metadata for HugrUsedExtensions {
     type Type<'hugr> = Vec<crate::envelope::description::ExtensionDesc>;
     const KEY: &'static str = "core.used_extensions";
 }
+
+/// Errors related to metadata
+#[derive(Error, Debug)]
+pub enum MetadataError {
+    /// Returned by `try_get_metadata` if the metadata present at the requested key
+    /// cannot be deserialized into the expected type.
+    #[error("Metadata value does not deserialize to {0}: {1}")]
+    MetadataDeserializationError(&'static str, serde_json::Error),
+}