Reorganize graph-decomposition passes into a folder and deduplicate shared helpers (#3010)

**Context:**
Reorg the `graph-decomposition`, `decompose-lowering` and `graph-solver`
src into a single `GraphDecomposition` folder, and extracts their shared
logic into a `DecompUtils.hpp` to remove duplications.

No functional change! this is a structural/cleanup PR.

**Possible Drawbacks:**
- `DecompUtils` is scoped to `GraphDecomposition`. `QuantumDialect.cpp`
and `RegisterDecompRuleResourcePass.cpp` also reference `target_gate`,
but they live in other passes/libs and I left them untouched to avoid
cross-lib dependency.

**Related GitHub Issues:**
#2977 (comment)

[sc-124463]

Author: maliasadi

mlir/lib/Quantum/Transforms/CMakeLists.txt

@@ -1,6 +1,6 @@
 set(LIBRARY_NAME quantum-transforms)
 
-add_subdirectory(DecompGraphSolver)
+add_subdirectory(GraphDecomposition/DecompGraphSolver)
 
 file(GLOB SRC
     AdjointLowering/AdjointLowering.cpp
@@ -10,7 +10,10 @@ file(GLOB SRC
     BufferizableOpInterfaceImpl.cpp
     CancelInversesPatterns.cpp
     ConversionPatterns.cpp
-    DecomposeLoweringPatterns.cpp
+    GraphDecomposition/DecompUtils.cpp
+    GraphDecomposition/DecomposeLoweringPatterns.cpp
+    GraphDecomposition/decompose_lowering.cpp
+    GraphDecomposition/graph_decomposition.cpp
     DisentangleCNOT.cpp
     DisentangleSWAP.cpp
     GridsynthPatterns.cpp
@@ -21,10 +24,8 @@ file(GLOB SRC
     SplitMultipleTapes.cpp
     cancel_inverses.cpp
     cp_global_buffers.cpp
-    decompose_lowering.cpp
     dynamic_one_shot.cpp
     emit_catalyst_pyface.cpp
-    graph_decomposition.cpp
     gridsynth.cpp
     ions_decompositions.cpp
     loop_boundary_optimization.cpp
@@ -64,5 +65,6 @@ target_include_directories(${LIBRARY_NAME} PUBLIC
     ${PROJECT_SOURCE_DIR}/include
     ${CMAKE_BINARY_DIR}/include
     AdjointLowering/
-    DecompGraphSolver/
+    GraphDecomposition/
+    GraphDecomposition/DecompGraphSolver/
 )

…nsforms/DecompGraphSolver/CMakeLists.txt …osition/DecompGraphSolver/CMakeLists.txtmlir/lib/Quantum/Transforms/DecompGraphSolver/CMakeLists.txt renamed to mlir/lib/Quantum/Transforms/GraphDecomposition/DecompGraphSolver/CMakeLists.txt mlir/lib/Quantum/Transforms/DecompGraphSolver/CMakeLists.txt renamed to mlir/lib/Quantum/Transforms/GraphDecomposition/DecompGraphSolver/CMakeLists.txt

@@ -0,0 +1,58 @@
+// Copyright 2026 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "DecompUtils.hpp"
+
+#include "mlir/IR/BuiltinAttributes.h"
+
+using namespace mlir;
+
+namespace catalyst {
+namespace quantum {
+namespace DecompUtils {
+
+bool isDecompositionFunction(func::FuncOp func) { return func->hasAttr(target_gate_attr_name); }
+
+StringRef getTargetGateName(func::FuncOp func)
+{
+    if (auto target_op_attr = func->getAttrOfType<StringAttr>(target_gate_attr_name)) {
+        return target_op_attr.getValue();
+    }
+    return StringRef{};
+}
+
+uint64_t getNumWires(func::FuncOp func)
+{
+    if (auto num_wires_attr = func->getAttrOfType<IntegerAttr>("num_wires")) {
+        return num_wires_attr.getValue().getZExtValue();
+    }
+    return 0;
+}
+
+bool isInDecompRule(Operation *op)
+{
+    while (auto parentOp = op->getParentOp()) {
+        if (auto funcOp = dyn_cast<func::FuncOp>(parentOp)) {
+            if (funcOp->hasAttr(target_gate_attr_name)) {
+                return true;
+            }
+        }
+        op = parentOp;
+    }
+    return false;
+}
+
+} // namespace DecompUtils
+} // namespace quantum
+} // namespace catalyst

…ansforms/DecompGraphSolver/DGBuilder.cpp …position/DecompGraphSolver/DGBuilder.cppmlir/lib/Quantum/Transforms/DecompGraphSolver/DGBuilder.cpp renamed to mlir/lib/Quantum/Transforms/GraphDecomposition/DecompGraphSolver/DGBuilder.cpp mlir/lib/Quantum/Transforms/DecompGraphSolver/DGBuilder.cpp renamed to mlir/lib/Quantum/Transforms/GraphDecomposition/DecompGraphSolver/DGBuilder.cpp

@@ -0,0 +1,55 @@
+// Copyright 2026 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <cstdint>
+
+#include "llvm/ADT/StringRef.h"
+#include "mlir/Dialect/Func/IR/FuncOps.h"
+#include "mlir/IR/Operation.h"
+
+namespace catalyst {
+namespace quantum {
+
+/**
+ * @brief Shared helpers for the graph-decomposition and decompose-lowering passes.
+ *
+ * A decomposition rule is a `func.func` carrying the `target_gate` attribute, naming the
+ * operator it decomposes. These utilities centralize the attribute names and the queries
+ * that identify such rules so the passes agree on a single definition.
+ */
+namespace DecompUtils {
+
+/// Attribute marking a `func.func` as a decomposition rule for the named target gate.
+inline constexpr llvm::StringRef target_gate_attr_name = "target_gate";
+
+/// Attribute holding the target gate set a circuit function should decompose into.
+inline constexpr llvm::StringRef decomp_gateset_attr_name = "decomp_gateset";
+
+/// True if @p func is a decomposition rule (i.e. carries the `target_gate` attribute).
+bool isDecompositionFunction(mlir::func::FuncOp func);
+
+/// The target gate a decomposition rule decomposes, or an empty ref if @p func is not a rule.
+llvm::StringRef getTargetGateName(mlir::func::FuncOp func);
+
+/// The `num_wires` attribute of @p func, or 0 if absent.
+uint64_t getNumWires(mlir::func::FuncOp func);
+
+/// True if @p op is nested inside a decomposition rule function.
+bool isInDecompRule(mlir::Operation *op);
+
+} // namespace DecompUtils
+} // namespace quantum
+} // namespace catalyst