Add ExceptionList AST node for rescue clauses with 2+ exceptions

Author: Copilot

ruby/ql/lib/change-notes/2026-06-19-rescue-exception-list.md

@@ -0,0 +1,4 @@
+---
+category: breaking
+---
+* When a `rescue` clause has two or more exception types, the exceptions are no longer direct children of the `RescueClause` node. Instead, a new `ExceptionList` AST node wraps the exceptions. Use `RescueClause.getExceptions()` to get the `ExceptionList` node, and `ExceptionList.getException(int n)` to access the individual exceptions. For `rescue` clauses with zero or one exception, the behavior is unchanged and `RescueClause.getException(int n)` continues to work as before.

ruby/ql/lib/codeql/ruby/ast/Expr.qll

@@ -280,6 +280,37 @@ class Pair extends Expr instanceof PairImpl {
   final override string getAPrimaryQlClass() { result = "Pair" }
 }
 
+/**
+ * A list of exception types in a rescue clause. For example, the exception list
+ * `FirstError, SecondError` in:
+ * ```rb
+ * begin
+ *   do_something
+ * rescue FirstError, SecondError => e
+ *   handle_error(e)
+ * end
+ * ```
+ * This node is only present when there are two or more exceptions in the list.
+ */
+class ExceptionList extends Expr, TExceptionList {
+  private Ruby::Exceptions g;
+
+  ExceptionList() { this = TExceptionList(g) }
+
+  final override string getAPrimaryQlClass() { result = "ExceptionList" }
+
+  /** Gets the `n`th exception in this list. */
+  final Expr getException(int n) { toGenerated(result) = g.getChild(n) }
+
+  final override string toString() { result = "..., ..." }
+
+  final override AstNode getAChild(string pred) {
+    result = super.getAChild(pred)
+    or
+    pred = "getException" and result = this.getException(_)
+  }
+}
+
 /**
  * A rescue clause. For example:
  * ```rb
@@ -305,8 +336,16 @@ class RescueClause extends Expr, TRescueClause {
    *   handle_error(e)
    * end
    * ```
+   * When there are two or more exceptions, use `getExceptions()` to get the `ExceptionList` node.
    */
-  final Expr getException(int n) { toGenerated(result) = g.getExceptions().getChild(n) }
+  final Expr getException(int n) {
+    // 0 or 1 exception: no ExceptionList node, access directly
+    not exists(this.getExceptions()) and
+    toGenerated(result) = g.getExceptions().getChild(n)
+    or
+    // 2+ exceptions: delegate through ExceptionList
+    result = this.getExceptions().getException(n)
+  }
 
   /**
    * Gets an exception to match, if any. For example `FirstError` or `SecondError` in:
@@ -320,6 +359,19 @@ class RescueClause extends Expr, TRescueClause {
    */
   final Expr getAnException() { result = this.getException(_) }
 
+  /**
+   * Gets the exception list node when there are two or more exceptions to match. For example,
+   * the exception list `FirstError, SecondError` in:
+   * ```rb
+   * begin
+   *  do_something
+   * rescue FirstError, SecondError => e
+   *   handle_error(e)
+   * end
+   * ```
+   */
+  final ExceptionList getExceptions() { result = TExceptionList(g.getExceptions()) }
+
   /**
    * Gets the variable to which to assign the matched exception, if any.
    * For example `err` in:
@@ -343,8 +395,13 @@ class RescueClause extends Expr, TRescueClause {
   final override AstNode getAChild(string pred) {
     result = super.getAChild(pred)
     or
+    // For 0 or 1 exceptions, exceptions are direct children
+    not exists(this.getExceptions()) and
     pred = "getException" and result = this.getException(_)
     or
+    // For 2+ exceptions, the ExceptionList node is the direct child
+    pred = "getExceptions" and result = this.getExceptions()
+    or
     pred = "getVariableExpr" and result = this.getVariableExpr()
     or
     pred = "getBody" and result = this.getBody()

ruby/ql/lib/codeql/ruby/ast/internal/AST.qll

@@ -155,6 +155,7 @@ private module Cached {
     TEndBlock(Ruby::EndBlock g) or
     TEnsure(Ruby::Ensure g) or
     TEqExpr(Ruby::Binary g) { g instanceof @ruby_binary_equalequal } or
+    TExceptionList(Ruby::Exceptions g) { strictcount(g.getChild(_)) > 1 } or
     TExponentExprReal(Ruby::Binary g) { g instanceof @ruby_binary_starstar } or
     TExponentExprSynth(Ast::AstNode parent, int i) { mkSynthChild(ExponentExprKind(), parent, i) } or
     TFalseLiteral(Ruby::False g) or
@@ -375,7 +376,8 @@ private module Cached {
         TClassVariableAccessReal or TComplementExpr or TComplexLiteral or TDefinedExprReal or
         TDelimitedSymbolLiteral or TDestructuredLeftAssignment or TDestructuredParameter or
         TDivExprReal or TDo or TDoBlock or TElementReference or TElseReal or TElsif or TEmptyStmt or
-        TEncoding or TEndBlock or TEnsure or TEqExpr or TExponentExprReal or TFalseLiteral or
+        TEncoding or TEndBlock or TEnsure or TEqExpr or TExceptionList or TExponentExprReal or
+        TFalseLiteral or
         TFile or TFindPattern or TFloatLiteral or TForExpr or TForwardParameter or
         TForwardArgument or TGEExpr or TGTExpr or TGlobalVariableAccessReal or
         THashKeySymbolLiteral or THashLiteral or THashPattern or THashSplatExprReal or
@@ -475,6 +477,7 @@ private module Cached {
     n = TEndBlock(result) or
     n = TEnsure(result) or
     n = TEqExpr(result) or
+    n = TExceptionList(result) or
     n = TExponentExprReal(result) or
     n = TFalseLiteral(result) or
     n = TFile(result) or
@@ -765,7 +768,7 @@ class TExpr =
   TSelf or TArgumentList or TRescueClause or TRescueModifierExpr or TPair or TStringConcatenation or
       TCall or TBlockArgument or TConstantAccess or TControlExpr or TLiteral or TCallable or
       TVariableAccess or TStmtSequence or TOperation or TForwardArgument or TDestructuredLhsExpr or
-      TMatchPattern or TTestPattern;
+      TMatchPattern or TTestPattern or TExceptionList;
 
 class TSplatExpr = TSplatExprReal or TSplatExprSynth;
 

ruby/ql/test/library-tests/ast/Ast.expected

@@ -445,6 +445,16 @@ calls/calls.rb:
 #  255|     getEnsure: [StmtSequence] ensure ...
 #  255|       getStmt: [MethodCall] call to bar
 #  255|         getReceiver: [ConstantReadAccess] X
+#  257|   getStmt: [BeginExpr] begin ... 
+#  258|     getRescue: [RescueClause] rescue ...
+#  258|       getExceptions: [ExceptionList] ..., ...
+#  258|         getException: [MethodCall] call to foo
+#  258|           getReceiver: [SelfVariableAccess] self
+#  258|         getException: [MethodCall] call to bar
+#  258|           getReceiver: [ConstantReadAccess] X
+#  259|     getEnsure: [StmtSequence] ensure ...
+#  259|       getStmt: [MethodCall] call to baz
+#  259|         getReceiver: [SelfVariableAccess] self
 #  263|   getStmt: [RescueModifierExpr] ... rescue ...
 #  263|     getBody: [MethodCall] call to foo
 #  263|       getReceiver: [SelfVariableAccess] self