feat: Define pass application scopes

hugr-passes/src/composable.rs

@@ -6,6 +6,8 @@ use hugr_core::core::HugrNode;
 use hugr_core::hugr::{ValidationError, hugrmut::HugrMut};
 use itertools::Either;
 
+use crate::PassScope;
+
 /// An optimization pass that can be sequenced with another and/or wrapped
 /// e.g. by [`ValidatingPass`]
 pub trait ComposablePass<H: HugrMut>: Sized {
@@ -17,6 +19,18 @@ pub trait ComposablePass<H: HugrMut>: Sized {
     /// Run the pass on the given HUGR.
     fn run(&self, hugr: &mut H) -> Result<Self::Result, Self::Error>;
 
+    /// Set the scope configuration used to run the pass.
+    ///
+    /// See [`PassScope`] for more details.
+    ///
+    /// In `hugr 0.25.*`, this configuration is only a guidance, and may be
+    /// ignored by the pass.
+    ///
+    /// From `hugr >=0.26.0`, passes must respect the scope configuration.
+    //
+    // For hugr passes, this is tracked by <https://github.com/Quantinuum/hugr/issues/2771>
+    fn with_scope(self, scope: &PassScope) -> Self;
+
     /// Apply a function to the error type of this pass, returning a new
     /// [`ComposablePass`] that has the same result type.
     fn map_err<E2: Error>(
@@ -28,6 +42,10 @@ pub trait ComposablePass<H: HugrMut>: Sized {
 
     /// Returns a [`ComposablePass`] that does "`self` then `other`", so long as
     /// `other::Err` can be combined with ours.
+    ///
+    /// Composed passes may have different configured [`PassScope`]s. Use
+    /// [`ComposablePass::with_scope`] after the composition to override all the
+    /// scope configurations if needed.
     fn then<P: ComposablePass<H>, E: ErrorCombiner<Self::Error, P::Error>>(
         self,
         other: P,
@@ -48,6 +66,14 @@ pub trait ComposablePass<H: HugrMut>: Sized {
                 let res2 = self.1.run(hugr).map_err(E::from_second)?;
                 Ok((res1, res2))
             }
+
+            fn with_scope(self, scope: &PassScope) -> Self {
+                Self(
+                    self.0.with_scope(scope),
+                    self.1.with_scope(scope),
+                    PhantomData,
+                )
+            }
         }
 
         Sequence(self, other, PhantomData)
@@ -110,6 +136,10 @@ impl<P: ComposablePass<H>, H: HugrMut, E: Error, F: Fn(P::Error) -> E> Composabl
     fn run(&self, hugr: &mut H) -> Result<P::Result, Self::Error> {
         self.0.run(hugr).map_err(&self.1)
     }
+
+    fn with_scope(self, scope: &PassScope) -> Self {
+        Self(self.0.with_scope(scope), self.1, PhantomData)
+    }
 }
 
 // ValidatingPass ------------------------------
@@ -188,6 +218,10 @@ where
         })?;
         Ok(res)
     }
+
+    fn with_scope(self, scope: &PassScope) -> Self {
+        Self(self.0.with_scope(scope), self.1)
+    }
 }
 
 // IfThen ------------------------------
@@ -225,6 +259,14 @@ impl<
         res.then(|| self.1.run(hugr).map_err(ErrorCombiner::from_second))
             .transpose()
     }
+
+    fn with_scope(self, scope: &PassScope) -> Self {
+        Self(
+            self.0.with_scope(scope),
+            self.1.with_scope(scope),
+            PhantomData,
+        )
+    }
 }
 
 pub(crate) fn validate_if_test<P: ComposablePass<H>, H: HugrMut>(

hugr-passes/src/const_fold.rs

@@ -15,6 +15,7 @@ use hugr_core::{
 };
 use value_handle::ValueHandle;
 
+use crate::PassScope;
 use crate::dataflow::{
     ConstLoader, ConstLocation, DFContext, Machine, PartialValue, TailLoopTermination,
     partial_from_const,
@@ -186,6 +187,12 @@ impl<H: HugrMut<Node = Node> + 'static> ComposablePass<H> for ConstantFoldPass {
             })?;
         Ok(())
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 /// Exhaustively apply constant folding to a HUGR.

hugr-passes/src/dead_code.rs

@@ -6,7 +6,7 @@ use std::collections::{HashMap, HashSet, VecDeque};
 use std::fmt::{Debug, Display, Formatter};
 use std::sync::Arc;
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 /// Configuration for Dead Code Elimination pass
 #[derive(Clone)]
@@ -185,6 +185,12 @@ impl<H: HugrMut> ComposablePass<H> for DeadCodeElimPass<H> {
         }
         Ok(())
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 #[cfg(test)]
 mod test {

hugr-passes/src/dead_funcs.rs

@@ -10,6 +10,7 @@ use hugr_core::{
 };
 use petgraph::visit::{Dfs, Walker};
 
+use crate::PassScope;
 use crate::{
     ComposablePass,
     composable::{ValidatePassError, validate_if_test},
@@ -107,6 +108,12 @@ impl<H: HugrMut<Node = Node>> ComposablePass<H> for RemoveDeadFuncsPass {
         }
         Ok(())
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 /// Deletes from the Hugr any functions that are not used by either [`Call`] or

hugr-passes/src/inline_dfgs.rs

@@ -10,7 +10,7 @@ use hugr_core::{
 };
 use itertools::Itertools;
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 /// Inlines all DFG nodes nested below the entrypoint.
 ///
@@ -43,6 +43,12 @@ impl<H: HugrMut<Node = Node>> ComposablePass<H> for InlineDFGsPass {
         }
         Ok(())
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 #[cfg(test)]

hugr-passes/src/lib.rs

@@ -1,30 +1,36 @@
 //! Compilation passes acting on the HUGR program representation.
 
 pub mod composable;
-pub use composable::ComposablePass;
 pub mod const_fold;
 pub mod dataflow;
 pub mod dead_code;
-pub use dead_code::DeadCodeElimPass;
-mod dead_funcs;
-pub use dead_funcs::{RemoveDeadFuncsError, RemoveDeadFuncsPass, remove_dead_funcs};
 pub mod force_order;
-mod half_node;
 pub mod inline_dfgs;
 pub mod inline_funcs;
-pub use inline_funcs::inline_acyclic;
 pub mod lower;
-mod monomorphize;
+pub mod nest_cfgs;
+pub mod non_local;
 pub mod normalize_cfgs;
 pub mod redundant_order_edges;
+pub mod replace_types;
+pub mod scope;
 pub mod untuple;
 
-pub use monomorphize::{MonomorphizePass, mangle_name, monomorphize};
-pub mod replace_types;
-pub use replace_types::ReplaceTypes;
-pub mod nest_cfgs;
-pub mod non_local;
+mod dead_funcs;
+mod half_node;
+mod monomorphize;
+
+// Main pass interfaces
+pub use composable::ComposablePass;
+pub use scope::PassScope;
+
+// Pass re-exports
+pub use dead_code::DeadCodeElimPass;
+pub use dead_funcs::{RemoveDeadFuncsError, RemoveDeadFuncsPass, remove_dead_funcs};
 pub use force_order::{force_order, force_order_by_key};
+pub use inline_funcs::inline_acyclic;
 pub use lower::{lower_ops, replace_many_ops};
+pub use monomorphize::{MonomorphizePass, mangle_name, monomorphize};
 pub use non_local::{ensure_no_nonlocal_edges, nonlocal_edges};
+pub use replace_types::ReplaceTypes;
 pub use untuple::UntuplePass;

hugr-passes/src/monomorphize.rs

@@ -13,8 +13,8 @@ use hugr_core::{
 use hugr_core::hugr::{HugrView, OpType, hugrmut::HugrMut};
 use itertools::Itertools as _;
 
-use crate::ComposablePass;
 use crate::composable::{ValidatePassError, validate_if_test};
+use crate::{ComposablePass, PassScope};
 
 /// Replaces calls to polymorphic functions with calls to new monomorphic
 /// instantiations of the polymorphic ones.
@@ -211,6 +211,12 @@ impl<H: HugrMut<Node = Node>> ComposablePass<H> for MonomorphizePass {
         }
         Ok(())
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 /// Helper to create mangled representations of lists of [TypeArg]s.

hugr-passes/src/non_local.rs

@@ -8,7 +8,7 @@ use hugr_core::{
     types::{EdgeKind, Type},
 };
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 mod localize;
 use localize::ExtraSourceReqs;
@@ -30,6 +30,12 @@ impl<H: HugrMut> ComposablePass<H> for LocalizeEdges {
     fn run(&self, hugr: &mut H) -> Result<Self::Result, Self::Error> {
         remove_nonlocal_edges(hugr)
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 /// Returns an iterator over all non local edges in a Hugr beneath the entrypoint.

hugr-passes/src/normalize_cfgs.rs

@@ -18,7 +18,7 @@ use hugr_core::ops::{
 };
 use hugr_core::{Direction, Hugr, HugrView, Node, OutgoingPort, PortIndex};
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 /// Merge any basic blocks that are direct children of the specified [`CFG`]-entrypoint
 /// Hugr.
@@ -143,6 +143,12 @@ impl<H: HugrMut> ComposablePass<H> for NormalizeCFGPass<H::Node> {
         }
         Ok(results)
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 /// Normalize a CFG in a Hugr:

hugr-passes/src/redundant_order_edges.rs

@@ -10,7 +10,7 @@ use hugr_core::{HugrView, IncomingPort, Node, OutgoingPort};
 use itertools::Itertools;
 use petgraph::visit::Walker;
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 /// A pass for removing order edges in a Hugr region that are already implied by
 /// other order or dataflow dependencies.
@@ -185,6 +185,12 @@ impl<H: HugrMut<Node = Node>> ComposablePass<H> for RedundantOrderEdgesPass {
 
         Ok(result)
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 #[cfg(test)]

hugr-passes/src/replace_types.rs

@@ -25,7 +25,7 @@ use hugr_core::types::{
 };
 use hugr_core::{Direction, Hugr, HugrView, Node, PortIndex, Wire};
 
-use crate::ComposablePass;
+use crate::{ComposablePass, PassScope};
 
 mod linearize;
 pub use linearize::{CallbackHandler, DelegatingLinearizer, LinearizeError, Linearizer};
@@ -779,6 +779,12 @@ impl<H: HugrMut<Node = Node>> ComposablePass<H> for ReplaceTypes {
         }
         Ok(changed)
     }
+
+    fn with_scope(self, _scope: &PassScope) -> Self {
+        // TODO: Use the configured scope when running the pass.
+        // <https://github.com/Quantinuum/hugr/issues/2771>
+        self
+    }
 }
 
 pub mod handlers;