✨ Preserve reusable gates across OpenQASM import and export

[burgholzer]

🤖 AI text below 🤖

Description

Preserve OpenQASM gate definitions as reusable QC functions and emit supported helpers as dependency-ordered OpenQASM gate declarations. Straight-line gates use the unitary-function contract; structured gate bodies remain private generic functions.

This PR is stacked on #2340. MLIR call-graph and SCC traversal provides callee-first export order, while the OpenQASM semantic analyzer rejects recursion before emission. Gate-expression export retains integer-to-float promotion, so expressions such as a converted loop index divided by two preserve floating-point semantics.

The exporter retains the current classical-register safeguards. Gate bodies cannot use mutable classical state; generic OpenQASM subroutines and a classical-reference call ABI are outside this change.

Codex implemented and tested the changes with independent OpenQASM/MLIR specialist review. Regressions cover a 100-function program, numeric loop expressions, strict reparsing, and QC ↔ QCO round trips.

Integrated-stack validation: release build; all 3,916 registered CTest cases with one expected skip; all 294 Qiskit translation tests; whole-file C++ lint and repository lint. Stub generation passed without tracked changes. Hosted CI is separate evidence and has not been claimed as passed.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

❌ Patch coverage is 91.20370% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../Dialect/QC/Translation/TranslateQCToOpenQASM3.cpp	90.6%	15 Missing ⚠️
...lib/Dialect/QC/Translation/OpenQASMToQCEmitter.cpp	90.6%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

This one also looks clean.
I placed a couple of restrictions on the supported functions that we may want to lift in a follow up, but I still think this is fine to go in as-is for now as it genuinely expands the scope of constructs we can support.

Functions with structured control flow are currently never marked as unitary even though we could likely allow some subset of control flow while still calling an operation unitary (for loops in particular could be easily supported).
In addition, the handling around a gate called main is maybe not fully ideal. We may be able to simplify the code a little bit by making stronger assumptions about the potential names for custom gates/functions.