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

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::debug_info::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,17 @@ impl MermaidArgs {
         }
 
         for hugr in package.modules {
+            let mmd_fmt = if self.debug_info {
+                hugr.mermaid_format()
+                    .with_node_labels(NodeLabel::MetadataKey(DEBUGINFO_META_KEY.to_string()))
+            } 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/core.rs

@@ -86,6 +86,10 @@ impl Node {
     pub(crate) fn into_portgraph(self) -> portgraph::NodeIndex {
         self.index
     }
+
+    pub(crate) fn from_portgraph(index: portgraph::NodeIndex) -> Self {
+        Self { index }
+    }
 }
 
 impl Port {

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

@@ -179,6 +179,8 @@ pub enum NodeLabel<N: HugrNode = Node> {
     /// Display the node index as a number.
     #[default]
     Numeric,
+    /// Display the node index and JSON metadata for a given key.
+    MetadataKey(String),
     /// Display the labels corresponding to the node indices.
     Custom(HashMap<N, String>),
 }
@@ -196,6 +198,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 +214,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 +227,30 @@ pub(in crate::hugr) fn node_style<'a>(
                 NodeStyle::boxed(node_name(h, n))
             }
         }),
+        NodeLabel::MetadataKey(label) => Box::new(move |n| {
+            let metadata = serde_json::to_string(
+                h.get_metadata_any(Node::from_portgraph(n), label.clone())
+                    .unwrap_or(&serde_json::Value::Null),
+            )
+            .expect("Could not render JSON metadata");
+            // mermaid renderer in portgraph does not like double quotes or newlines
+            let metadata_clean = metadata.replace('\n', " ").replace('"', "\'");
+
+            if Some(n) == entrypoint {
+                NodeStyle::boxed(format!(
+                    "{} <{}>",
+                    numeric_label(h, n, true),
+                    metadata_clean
+                ))
+                .with_attrs(entrypoint_style.clone())
+            } else {
+                NodeStyle::boxed(format!(
+                    "{} <{}>",
+                    numeric_label(h, n, false),
+                    metadata_clean
+                ))
+            }
+        }),
         NodeLabel::Custom(labels) => Box::new(move |n| {
             if Some(n) == entrypoint {
                 NodeStyle::boxed(format!(

hugr-core/src/metadata.rs

@@ -22,6 +22,7 @@
 //! let payload = hugr.get_metadata::<SomeMetadata>(hugr.module_root());
 //! assert_eq!(payload, Some("payload"));
 //! ```
+pub mod debug_info;
 //
 // When adding new metadata keys, they should be re-exported by the python bindings.
 // See hugr-py/rust/metadata.rs

hugr-core/src/metadata/debug_info.rs

@@ -0,0 +1,112 @@
+#![allow(missing_docs)]
+
+use std::any::type_name;
+use std::fmt;
+
+use crate::metadata::Metadata;
+use crate::{HugrView, Node};
+use serde::{
+    Deserialize, Serialize,
+    de::{DeserializeOwned, Deserializer, Error as DeError, Visitor},
+};
+use serde_json::{Error as JsonError, Value as JsonValue};
+use thiserror::Error;
+
+pub const DEBUGINFO_META_KEY: &str = "core.debug_info";
+
+/// Visitor and wrapper function passed as "deserialize_with" attribute
+/// in order to deserialize a usize from a string using serde_json
+struct JsonStrToIntVisitor;
+
+impl<'de> Visitor<'de> for JsonStrToIntVisitor {
+    type Value = usize;
+
+    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+        formatter.write_str("a usize or a string convertible with str::parse<usize>()")
+    }
+
+    fn visit_str<E: DeError>(self, s: &str) -> Result<Self::Value, E> {
+        s.parse::<usize>().map_err(E::custom)
+    }
+
+    fn visit_u64<E: DeError>(self, x: u64) -> Result<Self::Value, E> {
+        x.try_into().map_err(E::custom)
+    }
+}
+
+fn deserialize_usize_str<'de, D: Deserializer<'de>>(deserializer: D) -> Result<usize, D::Error> {
+    deserializer.deserialize_any(JsonStrToIntVisitor)
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct CompileUnitRecord {
+    pub directory: String,
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub filename: usize,
+    pub file_table: Vec<String>,
+}
+
+impl Metadata for CompileUnitRecord {
+    type Type<'hugr> = CompileUnitRecord;
+    const KEY: &'static str = DEBUGINFO_META_KEY;
+}
+
+#[derive(Debug, Error)]
+pub enum DebugInfoError {
+    /// There is a specific required mapping between HUGR nodes and debug record types,
+    /// if present
+    #[error("Debug metadata does not deserialize to {0}: {1}\n{2}")]
+    DRTypeMismatchError(&'static str, JsonError, JsonValue),
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct SubprogramRecord {
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub file: usize,
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub line_no: usize,
+    // TODO
+    //scope: Option<ScopeRecord>,
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub scope_line: usize,
+}
+
+impl Metadata for SubprogramRecord {
+    type Type<'hugr> = SubprogramRecord;
+    const KEY: &'static str = DEBUGINFO_META_KEY;
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct LocationRecord {
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub column: usize,
+    #[serde(deserialize_with = "deserialize_usize_str")]
+    pub line_no: usize,
+}
+
+impl Metadata for LocationRecord {
+    type Type<'hugr> = LocationRecord;
+    const KEY: &'static str = DEBUGINFO_META_KEY;
+}
+
+/// Inspect the debug metadata attached to the HUGR node.
+///
+/// If there is no debug metadata, return Ok(None). If it is present but does not
+/// deserialize into `T`, return DRTypeMismatchError. Otherwise, return the deserialized
+/// Some(`T`).
+pub fn try_get_debug_meta<
+    'h,
+    H: HugrView<Node = Node>,
+    T: Metadata<Type<'h> = T> + DeserializeOwned,
+>(
+    hugr: &'h H,
+    node: Node,
+) -> Result<Option<T>, DebugInfoError> {
+    if let Some(json) = hugr.get_metadata_any(node, DEBUGINFO_META_KEY) {
+        serde_json::from_value::<T>(json.clone())
+            .map_err(|e| DebugInfoError::DRTypeMismatchError(type_name::<T>(), e, json.clone()))
+            .map(|debug_record| Some(debug_record))
+    } else {
+        Ok(None)
+    }
+}

hugr-llvm/Cargo.toml

@@ -37,9 +37,11 @@ insta = { workspace = true, optional = true }
 rstest = { workspace = true, optional = true }
 portgraph = { workspace = true, optional = true }
 derive_more = { workspace = true, features = ["debug"] }
+rand = "0.10.1"
 
 [dev-dependencies]
 hugr-llvm = { "path" = ".", features = ["test-utils"] }
+serde_json.workspace = true
 
 [build-dependencies]
 cc = "1.2.57"