unified: Add facade AST

[asgerf]

This PR adds support for a "Facade AST" layer in the tree-sitter-extractor's QL generator, and a few other related tasks.

• Add facade AST support, as a way to augment generated classes with more members.
• Adds getA/getAn-getters for plural fields, so we can write getAnArgument() instead of getArgument(_).
• Adds a basic facade AST for unified to exercise the new feature a bit.
• Drive-by bugfix in local scoping which happened to come along with the AST refactoring.

Augmenting AST node classes

To augment an AST node, define a same-named class in the facade AST module, subclassing and shadowing the original class.

For example:

module FacadeAst {
  private import Ast as G
  import G

  // shadows the original Pattern class
  class Pattern extends G::Pattern {
    Pattern getEnclosingPattern() { ... } // extra hand-written member
  }
}

The facade module publicly imports the generated AST module, so any classes that have not been augmented will be exposed as-is.

Changes to the generated AST

In the generated AST, references to AST node classes now target the facade (which may resolve back to the generated AST itself, for classes that have not been augmented):

module Ast {
  private import FacadeAst as F

  class VariableDeclaration extends F::AstNode {
    F::Pattern getPattern() { ... } // Return type if F::Pattern so getEnclosingPattern is visible
    F::Expr getValue() { ... } // Resolve to the same as Expr since no facade for Expr exists yet
  }
  ...
}

Final aliases

This trick mentioned above was initially obstructed by the final aliases, making it impossible to augment a base class of another class. For example, the generated AST for AstNode was actually

private class AstNodeImpl { ... }
final class AstNode = AstNodeImpl

final class CallExpr extends AstNodeImpl { ... }

If we were to augment the AstNode class in the facade AST, the subclasses would not actually inherit its members, because they extend AstNodeImpl, which was private and could thus not be augmented.

To fix this, the layer of final aliases needs to happen after the facade AST, not in-between. There is now a separate module with all the final aliases:

module Ast {
  private import FacadeAst as F;

  class AstNode { ... }
  class Expr extends F::AstNode { ... }
  ...
}

module AstFinal {
  private import FacadeAst as F;

  final class AstNode = F::AstNode;
  final class Expr = F::Expr;
  ...
}

In unified we expose the AstFinal through unified.qll. For Ruby and QL4QL it doesn't really matter which one is exposed since the AST is hidden from end-users anyway.

[Copilot]

Pull request overview

Adds a façade layer for extending generated unified AST classes while preserving final public aliases.

Changes:

• Extends the AST generator with façade-aware imports, inheritance, and final aliases.
• Adds hand-written unified AST helpers for modifiers and enclosing patterns.
• Updates variable-binding tests and generator consumers.

Show a summary per file

File	Description
unified/scripts/create-extractor-pack.sh	Generates the internal AST library.
unified/ql/test/library-tests/variables/variables.ql	Adds ambiguity validation.
unified/ql/test/library-tests/variables/variables.expected	Records expected empty failure sets.
unified/ql/test/library-tests/variables/test.swift	Tests multi-pattern bindings.
unified/ql/test/library-tests/BasicTest/test.ql	Tests the public import.
unified/ql/lib/unified.qll	Exposes the final façade AST.
unified/ql/lib/codeql/unified/internal/Variables.qll	Uses generalized pattern traversal.
unified/ql/lib/codeql/unified/internal/FacadeAst.qll	Defines hand-written façade members.
unified/ql/lib/codeql/unified/internal/Ast.qll	Updates generated unified AST output.
unified/extractor/src/generator.rs	Enables façade generation.
shared/tree-sitter-extractor/src/node_types.rs	Makes type names cloneable.
shared/tree-sitter-extractor/src/generator/ql.rs	Adds private imports and façade types.
shared/tree-sitter-extractor/src/generator/ql_gen.rs	Generates façade-aware class hierarchies.
shared/tree-sitter-extractor/src/generator/mod.rs	Produces façade and final modules.
ruby/extractor/src/generator.rs	Selects non-façade generation.
ql/ql/src/codeql_ql/ast/internal/TreeSitter.qll	Updates generated QL AST output.
ql/extractor/src/generator.rs	Selects non-façade generation.

Review details

• Files reviewed: 16/18 changed files
• Comments generated: 0
• Review effort level: Medium

[github-advanced-security]

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[tausbn]

One minor comment, otherwise this looks good to me. 👍

[tausbn]

Maybe this ought to be upgraded to a named struct? It's not immediately obvious to me what the various parts of this tuple represent.

[asgerf]

Fair enough. Fixed in the next commit.