feat(sql): expose CTE scope to relation planners

[geoffreyclaude]

Which issue does this PR close?

• Closes RelationPlannerContext exposes no CTE scope, so extension relation planners silently shadow CTEs #24460.

Rationale for this change

RelationPlanner extensions run before DataFusion's built-in CTE lookup. That ordering is useful, but it leaves a name-based extension unable to tell that DataFusion would resolve a same-named relation as a CTE. Both plans can be valid, so the mistake is silent: the user asks for the CTE and gets the extension relation instead.

Downstream projects have had to rebuild this context themselves. For example, GlossQL collects CTE names in a pre-pass. Its comment captures the rough edge nicely: because the extension cannot ask DataFusion about the current scope, a CTE declared only inside one subquery may have to be treated as visible everywhere.

DataFusion already has the precise, lexical CTE scope while it plans the query. This PR makes that information available to the extension that needs it.

What changes are included in this PR?

• Add RelationPlannerContext::get_cte(&TableReference), with a default None implementation so existing custom context implementations remain source-compatible.
• Route the concrete relation-planner context and DataFusion's built-in fallback through one shared CTE lookup.
• Mirror DataFusion's existing string-key lookup, including its current behavior for qualified references and quoted dotted CTE names with the same rendering. Opting in therefore does not introduce a second, subtly different resolution rule.
• Document the opt-in pattern for ordinary name-based planners: recognize the relation first, check the current CTE scope only for non-function relations, and return RelationPlanning::Original so planning continues through the remaining planner chain.

The lookup remains opt-in. Every ordinary name-based planner in a chain should perform the check to preserve DataFusion's built-in CTE resolution, while planners with deliberately reserved names or custom syntax can keep their existing precedence.

Are these changes tested?

Yes. The integration tests cover:

• ordinary CTE precedence over a virtual relation;
• lexical scope for a CTE inside a nested query;
• agreement between extension and built-in lookup for qualified and quoted dotted names;
• a same-named table-function call with arguments; and
• a later reserved-name planner still intercepting after an ordinary planner defers.

I also ran cargo fmt --all, the required all-target/all-feature Clippy command with warnings denied, the focused relation-planner tests, the documentation Prettier check, and the required extended workspace test suite.

Are there any user-facing changes?

This adds a small public API for relation-planner authors. It is source-compatible because the trait method has a default implementation. Existing planners keep their current behavior until they opt into the CTE check; planners that do opt in can preserve DataFusion's existing CTE resolution without re-parsing the statement or approximating lexical scope.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 76.92308% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.58%. Comparing base (4d3e79e) to head (a70e61a).
⚠️ Report is 28 commits behind head on main.

Files with missing lines	Patch %	Lines
datafusion/expr/src/planner.rs	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #24755      +/-   ##
==========================================
+ Coverage   81.48%   81.58%   +0.09%     
==========================================
  Files        1122     1123       +1     
  Lines      404248   406621    +2373     
  Branches   404248   406621    +2373     
==========================================
+ Hits       329390   331726    +2336     
+ Misses      55547    55455      -92     
- Partials    19311    19440     +129     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[geoffreyclaude]

@phas02 would you mind reviewing this PR?

[phas02]

Looks good from a requirements point of view, exactly what we wanted. The implementation in DataFusion and rust is simple and low risk.