Merge pull request #19989 from github/nickrolfe/ruby-annotations

Ruby: add overlay annotations to AST/CFG/SSA layers

Author: nickrolfe

ql/ql/src/codeql/Locations.qll

@@ -1,4 +1,6 @@
 /** Provides classes for working with locations. */
+overlay[local]
+module;
 
 import files.FileSystem
 

ql/ql/src/codeql/files/FileSystem.qll

@@ -1,4 +1,6 @@
 /** Provides classes for working with files and folders. */
+overlay[local?]
+module;
 
 private import codeql_ql.ast.internal.TreeSitter
 private import codeql.Locations

ql/ql/src/codeql_ql/StructuredLogs.qll

@@ -1,3 +1,6 @@
+overlay[local]
+module;
+
 private import ql
 private import codeql_ql.ast.internal.TreeSitter
 private import experimental.RA
@@ -23,6 +26,7 @@ private float stringToTimestamp(string str) {
 }
 
 bindingset[s]
+overlay[global]
 private Predicate getPredicateFromPosition(string s) {
   exists(string r, string filepath, int startline | r = "(.*):(\\d+),(\\d+)-(\\d+),(\\d+)" |
     filepath = s.regexpCapture(r, 1) and
@@ -397,6 +401,7 @@ module KindPredicatesLog {
 
     string getPosition() { result = this.getString("position") }
 
+    overlay[global]
     Predicate getPredicate() { result = getPredicateFromPosition(this.getPosition()) }
 
     /**

ql/ql/src/codeql_ql/ast/internal/TreeSitter.qll

@@ -23,6 +23,7 @@ private predicate discardLocation(@location_default loc) {
   )
 }
 
+overlay[local]
 module QL {
   /** The base class for all AST nodes */
   class AstNode extends @ql_ast_node {
@@ -67,15 +68,13 @@ module QL {
   }
 
   /** Gets the file containing the given `node`. */
-  overlay[local]
   private @file getNodeFile(@ql_ast_node node) {
     exists(@location_default loc | ql_ast_node_location(node, loc) |
       locations_default(loc, result, _, _, _, _)
     )
   }
 
   /** Holds if `node` is in the `file` and is part of the overlay base database. */
-  overlay[local]
   private predicate discardableAstNode(@file file, @ql_ast_node node) {
     not isOverlay() and file = getNodeFile(node)
   }
@@ -1315,6 +1314,7 @@ module QL {
   }
 }
 
+overlay[local]
 module Dbscheme {
   /** The base class for all AST nodes */
   class AstNode extends @dbscheme_ast_node {
@@ -1359,15 +1359,13 @@ module Dbscheme {
   }
 
   /** Gets the file containing the given `node`. */
-  overlay[local]
   private @file getNodeFile(@dbscheme_ast_node node) {
     exists(@location_default loc | dbscheme_ast_node_location(node, loc) |
       locations_default(loc, result, _, _, _, _)
     )
   }
 
   /** Holds if `node` is in the `file` and is part of the overlay base database. */
-  overlay[local]
   private predicate discardableAstNode(@file file, @dbscheme_ast_node node) {
     not isOverlay() and file = getNodeFile(node)
   }
@@ -1673,6 +1671,7 @@ module Dbscheme {
   }
 }
 
+overlay[local]
 module Blame {
   /** The base class for all AST nodes */
   class AstNode extends @blame_ast_node {
@@ -1717,15 +1716,13 @@ module Blame {
   }
 
   /** Gets the file containing the given `node`. */
-  overlay[local]
   private @file getNodeFile(@blame_ast_node node) {
     exists(@location_default loc | blame_ast_node_location(node, loc) |
       locations_default(loc, result, _, _, _, _)
     )
   }
 
   /** Holds if `node` is in the `file` and is part of the overlay base database. */
-  overlay[local]
   private predicate discardableAstNode(@file file, @blame_ast_node node) {
     not isOverlay() and file = getNodeFile(node)
   }
@@ -1808,6 +1805,7 @@ module Blame {
   }
 }
 
+overlay[local]
 module JSON {
   /** The base class for all AST nodes */
   class AstNode extends @json_ast_node {
@@ -1852,15 +1850,13 @@ module JSON {
   }
 
   /** Gets the file containing the given `node`. */
-  overlay[local]
   private @file getNodeFile(@json_ast_node node) {
     exists(@location_default loc | json_ast_node_location(node, loc) |
       locations_default(loc, result, _, _, _, _)
     )
   }
 
   /** Holds if `node` is in the `file` and is part of the overlay base database. */
-  overlay[local]
   private predicate discardableAstNode(@file file, @json_ast_node node) {
     not isOverlay() and file = getNodeFile(node)
   }

ql/ql/src/experimental/RA.qll

@@ -1,6 +1,5 @@
-/**
- * Parses RA expressions.
- */
+overlay[local]
+module;
 
 /**
  * A predicate that contains RA.

ql/ql/src/queries/performance/LargeTupleSum.ql

@@ -6,6 +6,7 @@ import ql
 import codeql_ql.StructuredLogs
 import KindPredicatesLog
 
+overlay[local]
 module SumCounts implements Fold<int> {
   int base(PipeLineRun run) { result = sum(int i | | run.getCount(i)) }
 

ql/ql/test/experimental/raparser.ql

@@ -1,5 +1,6 @@
 import experimental.RA
 
+overlay[local]
 class TestPredicate extends string {
   TestPredicate() { this = "p1" }
 

ruby/ql/lib/change-notes/2025-07-09-overlay-local.md

@@ -0,0 +1,4 @@
+---
+category: breaking
+---
+* Most classes and predicates in the AST, SSA, and control-flow-graph libraries are now annotated with `overlay[local]`, in preparation for incremental analysis. This could result in compiler errors for custom queries if they extend these classes. To mitigate such errors, look for ways to restructure custom QL code so it doesn't depend on changing the behavior of standard-library classes.

ruby/ql/lib/codeql/Locations.qll

@@ -1,4 +1,6 @@
 /** Provides classes for working with locations. */
+overlay[local]
+module;
 
 import files.FileSystem
 

ruby/ql/lib/codeql/files/FileSystem.qll

@@ -1,4 +1,6 @@
 /** Provides classes for working with files and folders. */
+overlay[local]
+module;
 
 private import codeql.Locations
 private import codeql.util.FileSystem