feat: Export the portgraph hierarchy in HugrInternals (#2057)

Currently external packages can query the hugr's portgraph, but they
cannot access the associated hierarchy.

This non-breaking change adds a default-implemented method to
`HugrInternals` that returns it. It returns a `Cow` instead of a
straight reference, that can be used for more exotic hugr wrappers.

See the `base_hugr` refactoring issue for more discussion:
#1926

We don't expose a mutable ref, modifications can be done via
`HugrMutInternals` methods.

Author: aborgna-q

hugr-core/src/hugr/internal.rs

@@ -32,6 +32,13 @@ pub trait HugrInternals {
     /// Returns a reference to the underlying portgraph.
     fn portgraph(&self) -> Self::Portgraph<'_>;
 
+    /// Returns the portgraph [Hierarchy](portgraph::Hierarchy) of the graph
+    /// returned by [`HugrInternals::portgraph`].
+    #[inline]
+    fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy> {
+        Cow::Borrowed(&self.base_hugr().hierarchy)
+    }
+
     /// Returns the Hugr at the base of a chain of views.
     fn base_hugr(&self) -> &Hugr;
 
@@ -58,6 +65,11 @@ impl HugrInternals for Hugr {
         &self.graph
     }
 
+    #[inline]
+    fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy> {
+        Cow::Borrowed(&self.hierarchy)
+    }
+
     #[inline]
     fn base_hugr(&self) -> &Hugr {
         self
@@ -87,6 +99,7 @@ impl<T: HugrInternals> HugrInternals for &T {
     delegate! {
         to (**self) {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;
@@ -105,6 +118,7 @@ impl<T: HugrInternals> HugrInternals for &mut T {
     delegate! {
         to (**self) {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;
@@ -123,6 +137,7 @@ impl<T: HugrInternals> HugrInternals for Rc<T> {
     delegate! {
         to (**self) {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;
@@ -141,6 +156,7 @@ impl<T: HugrInternals> HugrInternals for Arc<T> {
     delegate! {
         to (**self) {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;
@@ -159,6 +175,7 @@ impl<T: HugrInternals> HugrInternals for Box<T> {
     delegate! {
         to (**self) {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;
@@ -177,6 +194,7 @@ impl<T: HugrInternals + ToOwned> HugrInternals for Cow<'_, T> {
     delegate! {
         to self.as_ref() {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Self::Node;
             fn get_pg_index(&self, node: Self::Node) -> portgraph::NodeIndex;

hugr-core/src/hugr/validate.rs

@@ -19,6 +19,7 @@ use crate::types::type_param::TypeParam;
 use crate::types::EdgeKind;
 use crate::{Direction, Hugr, Node, Port};
 
+use super::internal::HugrInternals;
 use super::views::{HierarchyView, HugrView, SiblingGraph};
 use super::ExtensionError;
 
@@ -104,7 +105,7 @@ impl<'a> ValidationContext<'a> {
     /// Check the validity of the HUGR.
     pub fn validate(&mut self) -> Result<(), ValidationError> {
         // Root node must be a root in the hierarchy.
-        if !self.hugr.hierarchy.is_root(self.hugr.root) {
+        if !self.hugr.hierarchy().is_root(self.hugr.root) {
             return Err(ValidationError::RootNotRoot {
                 node: self.hugr.root(),
             });
@@ -315,7 +316,7 @@ impl<'a> ValidationContext<'a> {
     fn validate_children(&self, node: Node, op_type: &OpType) -> Result<(), ValidationError> {
         let flags = op_type.validity_flags();
 
-        if self.hugr.hierarchy.child_count(node.pg_index()) > 0 {
+        if self.hugr.hierarchy().child_count(node.pg_index()) > 0 {
             if flags.allowed_children.is_empty() {
                 return Err(ValidationError::NonContainerWithChildren {
                     node,
@@ -362,7 +363,7 @@ impl<'a> ValidationContext<'a> {
 
             // Additional validations running over the edges of the contained graph
             if let Some(edge_check) = flags.edge_check {
-                for source in self.hugr.hierarchy.children(node.pg_index()) {
+                for source in self.hugr.hierarchy().children(node.pg_index()) {
                     for target in self.hugr.graph.output_neighbours(source) {
                         if self.hugr.hierarchy.parent(target) != Some(node.pg_index()) {
                             continue;

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

@@ -169,7 +169,6 @@ where
         &self.graph
     }
 
-    #[inline]
     fn base_hugr(&self) -> &Hugr {
         self.hugr
     }

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

@@ -1,3 +1,4 @@
+use std::borrow::Cow;
 use std::marker::PhantomData;
 
 use delegate::delegate;
@@ -58,6 +59,7 @@ impl<H: AsRef<Hugr>, Root> HugrInternals for RootChecked<H, Root> {
     delegate! {
         to self.as_ref() {
             fn portgraph(&self) -> Self::Portgraph<'_>;
+            fn hierarchy(&self) -> Cow<'_, portgraph::Hierarchy>;
             fn base_hugr(&self) -> &Hugr;
             fn root_node(&self) -> Node;
             fn get_pg_index(&self, node: Node) -> portgraph::NodeIndex;