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 a CTE should win over a same-named table. Both plans can be valid, so the mistake is silent: the user asks for the CTE and gets the table 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.
• Connect DataFusion's concrete relation-planner context to the current PlannerContext CTE map.
• Preserve table identity: only a bare reference can match a CTE, so a quoted CTE named "foo.bar" cannot collide with the qualified table foo.bar.
• Document the opt-in pattern for name-based planners, including the important distinction that a CTE named numbers shadows numbers, but not a table-function call such as numbers(10).

The lookup remains opt-in. A planner with deliberately reserved names can keep intercepting them exactly as it does today.

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;
• quoted dotted names versus qualified table references; and
• a same-named table-function call with arguments.

I also ran cargo fmt --all, the required all-target/all-feature Clippy command with warnings denied, and the documentation Prettier check.

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 normal SQL shadowing without re-parsing the statement.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 62.50000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.48%. Comparing base (4d3e79e) to head (baa6bdc).

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.48%   -0.01%     
==========================================
  Files        1122     1122              
  Lines      404248   404256       +8     
  Branches   404248   404256       +8     
==========================================
+ Hits       329390   329391       +1     
- Misses      55547    55550       +3     
- Partials    19311    19315       +4     

☔ 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.