feat: Static checking of Port direction (#614)

* Add fallible methods Port::as_{incoming,outgoing} to convert to
{Incoming/Outgoing}Port
* IncomingPort/OutgoingPort convert to Port (infallibly i.e. Into/From}
* Parameterize many omni-directional methods by `impl Into<Port>`;
require caller to do fallible conversions first + explicitly
* Add HugrView::node_{inputs,outputs} and
HugrView::linked_{inputs,outputs} preserving directionality
* Unidirectional methods/structs take (Into)IncomingPort/OutgoingPort
e.g. Wire, SimpleReplacement, InsertIdentity

BREAKING CHANGE: Port::(try_)new_{incom,outgo}ing gone - use
Port::as_{incom,outgo}ing and {Incom,Outgo}ingPort::{into,from}

---------

Co-authored-by: Agustin Borgna <agustin.borgna@quantinuum.com>

src/builder/build_traits.rs

@@ -3,7 +3,7 @@ use crate::hugr::validate::InterGraphEdgeError;
 use crate::hugr::views::HugrView;
 use crate::hugr::{NodeMetadata, ValidationError};
 use crate::ops::{self, LeafOp, OpTrait, OpType};
-use crate::{IncomingPort, Node, OutgoingPort, Port};
+use crate::{IncomingPort, Node, OutgoingPort};
 
 use std::iter;
 
@@ -369,7 +369,7 @@ pub trait Dataflow: Container {
                 input_extensions,
             ),
             // Constant wire from the constant value node
-            vec![Wire::new(const_node, Port::new_outgoing(0))],
+            vec![Wire::new(const_node, OutgoingPort::from(0))],
         )?;
 
         Ok(load_n.out_wire(0))
@@ -659,12 +659,12 @@ fn wire_up_inputs<T: Dataflow + ?Sized>(
 fn wire_up<T: Dataflow + ?Sized>(
     data_builder: &mut T,
     src: Node,
-    src_port: impl TryInto<OutgoingPort>,
+    src_port: impl Into<OutgoingPort>,
     dst: Node,
-    dst_port: impl TryInto<IncomingPort>,
+    dst_port: impl Into<IncomingPort>,
 ) -> Result<bool, BuildError> {
-    let src_port = Port::try_new_outgoing(src_port)?;
-    let dst_port = Port::try_new_incoming(dst_port)?;
+    let src_port = src_port.into();
+    let dst_port = dst_port.into();
     let base = data_builder.hugr_mut();
 
     let src_parent = base.get_parent(src);
@@ -676,9 +676,9 @@ fn wire_up<T: Dataflow + ?Sized>(
             if !typ.copyable() {
                 let val_err: ValidationError = InterGraphEdgeError::NonCopyableData {
                     from: src,
-                    from_offset: src_port,
+                    from_offset: src_port.into(),
                     to: dst,
-                    to_offset: dst_port,
+                    to_offset: dst_port.into(),
                     ty: EdgeKind::Value(typ),
                 }
                 .into();
@@ -694,9 +694,9 @@ fn wire_up<T: Dataflow + ?Sized>(
             else {
                 let val_err: ValidationError = InterGraphEdgeError::NoRelation {
                     from: src,
-                    from_offset: src_port,
+                    from_offset: src_port.into(),
                     to: dst,
-                    to_offset: dst_port,
+                    to_offset: dst_port.into(),
                 }
                 .into();
                 return Err(val_err.into());

src/builder/handle.rs

@@ -1,13 +1,8 @@
 //! Handles to nodes in HUGR used during the building phase.
 //!
-use crate::{
-    ops::{
-        handle::{BasicBlockID, CaseID, DfgID, FuncID, NodeHandle, TailLoopID},
-        OpTag,
-    },
-    Port,
-};
-use crate::{Node, Wire};
+use crate::ops::handle::{BasicBlockID, CaseID, DfgID, FuncID, NodeHandle, TailLoopID};
+use crate::ops::OpTag;
+use crate::{Node, OutgoingPort, Wire};
 
 use itertools::Itertools;
 use std::iter::FusedIterator;
@@ -64,7 +59,7 @@ impl<T: NodeHandle> BuildHandle<T> {
     /// Retrieve a [`Wire`] corresponding to the given offset.
     /// Does not check whether such a wire is valid for this node.
     pub fn out_wire(&self, offset: usize) -> Wire {
-        Wire::new(self.node(), Port::new_outgoing(offset))
+        Wire::new(self.node(), OutgoingPort::from(offset))
     }
 
     #[inline]
@@ -124,14 +119,12 @@ impl Iterator for Outputs {
     fn next(&mut self) -> Option<Self::Item> {
         self.range
             .next()
-            .map(|offset| Wire::new(self.node, Port::new_outgoing(offset)))
+            .map(|offset| Wire::new(self.node, OutgoingPort::from(offset)))
     }
 
     #[inline]
     fn nth(&mut self, n: usize) -> Option<Self::Item> {
-        self.range
-            .nth(n)
-            .map(|offset| Wire::new(self.node, Port::new_outgoing(offset)))
+        self.range.nth(n).map(|offset| Wire::new(self.node, offset))
     }
 
     #[inline]
@@ -157,7 +150,7 @@ impl DoubleEndedIterator for Outputs {
     fn next_back(&mut self) -> Option<Self::Item> {
         self.range
             .next_back()
-            .map(|offset| Wire::new(self.node, Port::new_outgoing(offset)))
+            .map(|offset| Wire::new(self.node, offset))
     }
 }
 

src/core.rs

@@ -69,7 +69,7 @@ pub type Direction = portgraph::Direction;
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 /// A DataFlow wire, defined by a Value-kind output port of a node
 // Stores node and offset to output port
-pub struct Wire(Node, usize);
+pub struct Wire(Node, OutgoingPort);
 
 impl Node {
     /// Returns the node as a portgraph `NodeIndex`.
@@ -88,29 +88,29 @@ impl Port {
         }
     }
 
-    /// Creates a new incoming port.
+    /// Converts to an [IncomingPort] if this port is one; else fails with
+    /// [HugrError::InvalidPortDirection]
     #[inline]
-    pub fn new_incoming(port: impl Into<IncomingPort>) -> Self {
-        Self::try_new_incoming(port).unwrap()
-    }
-
-    /// Creates a new outgoing port.
-    #[inline]
-    pub fn new_outgoing(port: impl Into<OutgoingPort>) -> Self {
-        Self::try_new_outgoing(port).unwrap()
+    pub fn as_incoming(&self) -> Result<IncomingPort, HugrError> {
+        match self.direction() {
+            Direction::Incoming => Ok(IncomingPort {
+                index: self.index() as u16,
+            }),
+            dir @ Direction::Outgoing => Err(HugrError::InvalidPortDirection(dir)),
+        }
     }
 
-    /// Creates a new incoming port.
+    /// Converts to an [OutgoingPort] if this port is one; else fails with
+    /// [HugrError::InvalidPortDirection]
     #[inline]
-    pub fn try_new_incoming(port: impl TryInto<IncomingPort>) -> Result<Self, HugrError> {
-        let Ok(port) = port.try_into() else {
-            return Err(HugrError::InvalidPortDirection(Direction::Outgoing));
-        };
-        Ok(Self {
-            offset: portgraph::PortOffset::new_incoming(port.index()),
-        })
+    pub fn as_outgoing(&self) -> Result<OutgoingPort, HugrError> {
+        match self.direction() {
+            Direction::Outgoing => Ok(OutgoingPort {
+                index: self.index() as u16,
+            }),
+            dir @ Direction::Incoming => Err(HugrError::InvalidPortDirection(dir)),
+        }
     }
-
     /// Creates a new outgoing port.
     #[inline]
     pub fn try_new_outgoing(port: impl TryInto<OutgoingPort>) -> Result<Self, HugrError> {
@@ -181,28 +181,18 @@ impl From<usize> for OutgoingPort {
     }
 }
 
-impl TryFrom<Port> for IncomingPort {
-    type Error = HugrError;
-    #[inline(always)]
-    fn try_from(port: Port) -> Result<Self, Self::Error> {
-        match port.direction() {
-            Direction::Incoming => Ok(Self {
-                index: port.index() as u16,
-            }),
-            dir @ Direction::Outgoing => Err(HugrError::InvalidPortDirection(dir)),
+impl From<IncomingPort> for Port {
+    fn from(value: IncomingPort) -> Self {
+        Self {
+            offset: portgraph::PortOffset::new_incoming(value.index()),
         }
     }
 }
 
-impl TryFrom<Port> for OutgoingPort {
-    type Error = HugrError;
-    #[inline(always)]
-    fn try_from(port: Port) -> Result<Self, Self::Error> {
-        match port.direction() {
-            Direction::Outgoing => Ok(Self {
-                index: port.index() as u16,
-            }),
-            dir @ Direction::Incoming => Err(HugrError::InvalidPortDirection(dir)),
+impl From<OutgoingPort> for Port {
+    fn from(value: OutgoingPort) -> Self {
+        Self {
+            offset: portgraph::PortOffset::new_outgoing(value.index()),
         }
     }
 }
@@ -216,8 +206,8 @@ impl NodeIndex for Node {
 impl Wire {
     /// Create a new wire from a node and a port.
     #[inline]
-    pub fn new(node: Node, port: impl TryInto<OutgoingPort>) -> Self {
-        Self(node, Port::try_new_outgoing(port).unwrap().index())
+    pub fn new(node: Node, port: impl Into<OutgoingPort>) -> Self {
+        Self(node, port.into())
     }
 
     /// The node that this wire is connected to.
@@ -228,8 +218,8 @@ impl Wire {
 
     /// The output port that this wire is connected to.
     #[inline]
-    pub fn source(&self) -> Port {
-        Port::new_outgoing(self.1)
+    pub fn source(&self) -> OutgoingPort {
+        self.1
     }
 }
 

src/hugr/hugrmut.rs

@@ -108,9 +108,9 @@ pub trait HugrMut: HugrMutInternals {
     fn connect(
         &mut self,
         src: Node,
-        src_port: impl TryInto<OutgoingPort>,
+        src_port: impl Into<OutgoingPort>,
         dst: Node,
-        dst_port: impl TryInto<IncomingPort>,
+        dst_port: impl Into<IncomingPort>,
     ) -> Result<(), HugrError> {
         self.valid_node(src)?;
         self.valid_node(dst)?;
@@ -121,7 +121,7 @@ pub trait HugrMut: HugrMutInternals {
     ///
     /// The port is left in place.
     #[inline]
-    fn disconnect(&mut self, node: Node, port: Port) -> Result<(), HugrError> {
+    fn disconnect(&mut self, node: Node, port: impl Into<Port>) -> Result<(), HugrError> {
         self.valid_node(node)?;
         self.hugr_mut().disconnect(node, port)
     }
@@ -134,7 +134,11 @@ pub trait HugrMut: HugrMutInternals {
     ///
     /// [`OpTrait::other_input`]: crate::ops::OpTrait::other_input
     /// [`OpTrait::other_output`]: crate::ops::OpTrait::other_output
-    fn add_other_edge(&mut self, src: Node, dst: Node) -> Result<(Port, Port), HugrError> {
+    fn add_other_edge(
+        &mut self,
+        src: Node,
+        dst: Node,
+    ) -> Result<(OutgoingPort, IncomingPort), HugrError> {
         self.valid_node(src)?;
         self.valid_node(dst)?;
         self.hugr_mut().add_other_edge(src, dst)
@@ -247,20 +251,21 @@ impl<T: RootTagged<RootHandle = Node> + AsMut<Hugr>> HugrMut for T {
     fn connect(
         &mut self,
         src: Node,
-        src_port: impl TryInto<OutgoingPort>,
+        src_port: impl Into<OutgoingPort>,
         dst: Node,
-        dst_port: impl TryInto<IncomingPort>,
+        dst_port: impl Into<IncomingPort>,
     ) -> Result<(), HugrError> {
         self.as_mut().graph.link_nodes(
             src.pg_index(),
-            Port::try_new_outgoing(src_port)?.index(),
+            src_port.into().index(),
             dst.pg_index(),
-            Port::try_new_incoming(dst_port)?.index(),
+            dst_port.into().index(),
         )?;
         Ok(())
     }
 
-    fn disconnect(&mut self, node: Node, port: Port) -> Result<(), HugrError> {
+    fn disconnect(&mut self, node: Node, port: impl Into<Port>) -> Result<(), HugrError> {
+        let port = port.into();
         let offset = port.pg_offset();
         let port = self
             .as_mut()
@@ -274,15 +279,21 @@ impl<T: RootTagged<RootHandle = Node> + AsMut<Hugr>> HugrMut for T {
         Ok(())
     }
 
-    fn add_other_edge(&mut self, src: Node, dst: Node) -> Result<(Port, Port), HugrError> {
-        let src_port: Port = self
+    fn add_other_edge(
+        &mut self,
+        src: Node,
+        dst: Node,
+    ) -> Result<(OutgoingPort, IncomingPort), HugrError> {
+        let src_port = self
             .get_optype(src)
             .other_port_index(Direction::Outgoing)
-            .expect("Source operation has no non-dataflow outgoing edges");
-        let dst_port: Port = self
+            .expect("Source operation has no non-dataflow outgoing edges")
+            .as_outgoing()?;
+        let dst_port = self
             .get_optype(dst)
             .other_port_index(Direction::Incoming)
-            .expect("Destination operation has no non-dataflow incoming edges");
+            .expect("Destination operation has no non-dataflow incoming edges")
+            .as_incoming()?;
         self.connect(src, src_port, dst, dst_port)?;
         Ok((src_port, dst_port))
     }

src/hugr/rewrite/insert_identity.rs

@@ -5,7 +5,7 @@ use std::iter;
 use crate::hugr::{HugrMut, Node};
 use crate::ops::{LeafOp, OpTag, OpTrait};
 use crate::types::EdgeKind;
-use crate::{Direction, HugrView, Port};
+use crate::{HugrView, IncomingPort};
 
 use super::Rewrite;
 
@@ -18,12 +18,12 @@ pub struct IdentityInsertion {
     /// The node following the identity to be inserted.
     pub post_node: Node,
     /// The port following the identity to be inserted.
-    pub post_port: Port,
+    pub post_port: IncomingPort,
 }
 
 impl IdentityInsertion {
     /// Create a new [`IdentityInsertion`] specification.
-    pub fn new(post_node: Node, post_port: Port) -> Self {
+    pub fn new(post_node: Node, post_port: IncomingPort) -> Self {
         Self {
             post_node,
             post_port,
@@ -43,10 +43,6 @@ pub enum IdentityInsertionError {
     /// Invalid port kind.
     #[error("post_port has invalid kind {0:?}. Must be Value.")]
     InvalidPortKind(Option<EdgeKind>),
-
-    /// Must be input port.
-    #[error("post_port is an output port, must be input.")]
-    PortIsOutput,
 }
 
 impl Rewrite for IdentityInsertion {
@@ -71,17 +67,13 @@ impl Rewrite for IdentityInsertion {
         unimplemented!()
     }
     fn apply(self, h: &mut impl HugrMut) -> Result<Self::ApplyResult, IdentityInsertionError> {
-        if self.post_port.direction() != Direction::Incoming {
-            return Err(IdentityInsertionError::PortIsOutput);
-        }
-
         let kind = h.get_optype(self.post_node).port_kind(self.post_port);
         let Some(EdgeKind::Value(ty)) = kind else {
             return Err(IdentityInsertionError::InvalidPortKind(kind));
         };
 
         let (pre_node, pre_port) = h
-            .linked_ports(self.post_node, self.post_port)
+            .linked_outputs(self.post_node, self.post_port)
             .exactly_one()
             .ok()
             .expect("Value kind input can only have one connection.");
@@ -155,11 +147,6 @@ mod tests {
 
         let final_node = tail.node();
 
-        let final_node_output = h.node_outputs(final_node).next().unwrap();
-        let rw = IdentityInsertion::new(final_node, final_node_output);
-        let apply_result = h.apply_rewrite(rw);
-        assert_eq!(apply_result, Err(IdentityInsertionError::PortIsOutput));
-
         let final_node_input = h.node_inputs(final_node).next().unwrap();
 
         let rw = IdentityInsertion::new(final_node, final_node_input);

src/hugr/rewrite/outline_cfg.rs

@@ -158,7 +158,7 @@ impl Rewrite for OutlineCfg {
 
         // 3. Entry edges. Change any edges into entry_block from outside, to target new_block
         let preds: Vec<_> = h
-            .linked_ports(entry, h.node_inputs(entry).exactly_one().ok().unwrap())
+            .linked_outputs(entry, h.node_inputs(entry).exactly_one().ok().unwrap())
             .collect();
         for (pred, br) in preds {
             if !self.blocks.contains(&pred) {