✨ 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!