address comments

Author: lmondada

hugr-core/src/core.rs

@@ -7,7 +7,7 @@ pub use itertools::Either;
 use derive_more::From;
 use itertools::Either::{Left, Right};
 
-use crate::hugr::HugrError;
+use crate::{HugrView, hugr::HugrError};
 
 /// A handle to a node in the HUGR.
 #[derive(
@@ -219,17 +219,55 @@ impl<N: HugrNode> Wire<N> {
         Self(node, port.into())
     }
 
-    /// The node that this wire is connected to.
+    /// Create a new wire from a node and a port that is connected to the wire.
+    ///
+    /// If `port` is an incoming port, the wire is traversed to find the unique
+    /// outgoing port that is connected to the wire. Otherwise, this is
+    /// equivalent to constructing a wire using [`Wire::new`].
+    ///
+    /// ## Panics
+    ///
+    /// This will panic if the wire is not connected to a unique outgoing port.
+    #[inline]
+    pub fn from_connected_port(
+        node: N,
+        port: impl Into<Port>,
+        hugr: &impl HugrView<Node = N>,
+    ) -> Self {
+        let (node, outgoing) = match port.into().as_directed() {
+            Either::Left(incoming) => hugr
+                .single_linked_output(node, incoming)
+                .expect("invalid dfg port"),
+            Either::Right(outgoing) => (node, outgoing),
+        };
+        Self::new(node, outgoing)
+    }
+
+    /// The node of the unique outgoing port that the wire is connected to.
     #[inline]
     pub fn node(&self) -> N {
         self.0
     }
 
-    /// The output port that this wire is connected to.
+    /// The unique outgoing port that the wire is connected to.
     #[inline]
     pub fn source(&self) -> OutgoingPort {
         self.1
     }
+
+    /// Get all ports connected to the wire.
+    ///
+    /// Return a chained iterator of the unique outgoing port, followed by all
+    /// incoming ports connected to the wire.
+    pub fn all_connected_ports<'h, H: HugrView<Node = N>>(
+        &self,
+        hugr: &'h H,
+    ) -> impl Iterator<Item = (N, Port)> + use<'h, N, H> {
+        let node = self.node();
+        let out_port = self.source();
+
+        std::iter::once((node, out_port.into())).chain(hugr.linked_ports(node, out_port))
+    }
 }
 
 impl<N: HugrNode> std::fmt::Display for Wire<N> {

hugr-persistent/src/persistent_hugr.rs

@@ -489,6 +489,7 @@ impl<R> PersistentHugr<R> {
             .unique()
     }
 
+    /// Get the child commit that deletes `node`.
     pub(crate) fn find_deleting_commit(
         &self,
         node @ PatchNode(commit_id, _): PatchNode,
@@ -500,6 +501,12 @@ impl<R> PersistentHugr<R> {
         })
     }
 
+    /// Convert a node ID specific to a commit HUGR into a patch node in the
+    /// [`PersistentHugr`].
+    pub(crate) fn to_persistent_node(&self, node: Node, commit_id: CommitId) -> PatchNode {
+        PatchNode(commit_id, node)
+    }
+
     /// Check if a patch node is in the PersistentHugr, that is, it belongs to
     /// a commit in the state space and is not deleted by any child commit.
     pub fn contains_node(&self, PatchNode(commit_id, node): PatchNode) -> bool {

hugr-persistent/src/state_space.rs

@@ -308,10 +308,12 @@ impl<R> CommitStateSpace<R> {
 
     /// Get the boundary inputs linked to `(node, port)` in `child`.
     ///
+    /// `child` should be a child commit of the owner of `node`.
+    ///
     /// ## Panics
     ///
-    /// Panics if `(node, port)` is not a boundary edge, or if `child` is not
-    /// a valid commit ID.
+    /// Panics if `(node, port)` is not a boundary edge, if `child` is not
+    /// a valid commit ID or if it is the base commit.
     pub(crate) fn linked_child_inputs(
         &self,
         node: PatchNode,
@@ -336,6 +338,9 @@ impl<R> CommitStateSpace<R> {
 
     /// Get the single boundary output linked to `(node, port)` in `child`.
     ///
+    /// `child` should be a child commit of the owner of `node` (or `None` will
+    /// be returned).
+    ///
     /// ## Panics
     ///
     /// Panics if `child` is not a valid commit ID.
@@ -346,7 +351,7 @@ impl<R> CommitStateSpace<R> {
         child: CommitId,
     ) -> Option<(PatchNode, OutgoingPort)> {
         let parent_hugrs = ParentsView::from_commit(child, self);
-        let repl = self.replacement(child).expect("valid child commit");
+        let repl = self.replacement(child)?;
         match repl.linked_replacement_output((node, port), &parent_hugrs)? {
             BoundaryPort::Host(patch_node, port) => (patch_node, port),
             BoundaryPort::Replacement(node, port) => (PatchNode(child, node), port),
@@ -356,6 +361,8 @@ impl<R> CommitStateSpace<R> {
 
     /// Get the boundary ports linked to `(node, port)` in `child`.
     ///
+    /// `child` should be a child commit of the owner of `node`.
+    ///
     /// See [`Self::linked_child_inputs`] and [`Self::linked_child_output`] for
     /// more details.
     pub(crate) fn linked_child_ports(