Merge pull request #10376 from hvitved/ruby/no-ast-by-default

Ruby: Do not expose AST layer through `ruby.qll`

Author: hvitved

.github/workflows/ruby-build.yml

@@ -197,7 +197,7 @@ jobs:
       - name: Prepare test files
         shell: bash
         run: |
-          echo "import ruby select count(File f)" > "test.ql"
+          echo "import codeql.ruby.AST select count(File f)" > "test.ql"
           echo "| 4 |" > "test.expected"
           echo 'name: sample-tests
           version: 0.0.0

docs/codeql/codeql-language-guides/basic-query-for-ruby-code.rst

@@ -36,7 +36,7 @@ Running the query
 
    .. code-block:: ql
 
-      import ruby
+      import codeql.ruby.AST
 
       from IfExpr ifexpr
       where
@@ -80,7 +80,7 @@ After the initial ``import`` statement, this simple query comprises three parts
 +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
 | Query part                                                    | Purpose                                                                                                           | Details                                                                                                                |
 +===============================================================+===================================================================================================================+========================================================================================================================+
-| ``import ruby``                                               | Imports the standard CodeQL libraries for Ruby.                                                                   | Every query begins with one or more ``import`` statements.                                                             |
+| ``import codeql.ruby.AST``                                    | Imports the standard CodeQL AST libraries for Ruby.                                                                   | Every query begins with one or more ``import`` statements.                                                         |
 +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
 | ``from IfExpr ifexpr``                                        | Defines the variables for the query.                                                                              | We use: an ``IfExpr`` variable for ``if`` expressions.                                                                 |
 |                                                               | Declarations are of the form:                                                                                     |                                                                                                                        |

docs/codeql/codeql-language-guides/codeql-library-for-ruby.rst

@@ -18,7 +18,7 @@ library by beginning your query with:
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
 The CodeQL libraries model various aspects of Ruby code, depending on the type of query you want to write.
 For example the abstract syntax tree (AST) library is used for locating program elements, to match syntactic
@@ -138,7 +138,7 @@ The following example lists all methods in the class `ApiController`:
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from ClassDeclaration m
    where m.getName() = "ApiController"
@@ -223,7 +223,7 @@ Example
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from Method m
    where m.getName() = "show"
@@ -274,7 +274,7 @@ The following example finds all literals that are returned by a `return` stateme
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from ReturnStmt return, Literal lit
    where lit.getParent() = return 
@@ -421,7 +421,7 @@ The following example finds "chained assignments" (of the form ``A=B=C``):
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
    
    from Assignment op
    where op.getRightOperand() instanceof Assignment
@@ -460,7 +460,7 @@ The following example finds all method calls to a method called `delete`.
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from MethodCall call
    where call.getMethodName() = "delete"
@@ -517,7 +517,7 @@ The following example finds `if`-expressions that are missing a `then` branch.
 
 .. code-block:: ql
    
-   import ruby
+   import codeql.ruby.AST
 
    from IfExpr expr
    where not exists(expr.getThen())
@@ -559,7 +559,7 @@ The following example finds all class variables in the class `StaticController`:
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from ClassDeclaration cd, ClassVariable v
    where
@@ -612,7 +612,7 @@ The following example finds writes to class variables in the class `StaticContro
 
 .. code-block:: ql
 
-   import ruby
+   import codeql.ruby.AST
 
    from ClassVariableWriteAccess write, ClassDeclaration cd, ClassVariable v
    where

ruby/ql/examples/snippets/emptythen.ql

@@ -11,7 +11,7 @@
  *       statement
  */
 
-import ruby
+import codeql.ruby.AST
 
 from IfExpr i
 where not exists(i.getThen().getAChild())

ruby/ql/lib/Customizations.qll

@@ -9,4 +9,3 @@
  * to model frameworks that are not covered by the standard library.
  */
 
-import ruby

ruby/ql/lib/change-notes/2022-09-14-ruby-qll.md

@@ -0,0 +1,4 @@
+---
+category: breaking
+---
+* `import ruby` no longer brings the standard Ruby AST library into scope; it instead brings a module `Ast` into scope, which must be imported. Alternatively, it is also possible to import `codeql.ruby.AST`.

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

@@ -17,6 +17,7 @@ private import ast.internal.AST
 private import ast.internal.Scope
 private import ast.internal.Synthesis
 private import ast.internal.TreeSitter
+private import Customizations
 
 cached
 private module Cached {

ruby/ql/lib/codeql/ruby/ApiGraphs.qll

@@ -6,7 +6,7 @@
  * directed and labeled; they specify how the components represented by nodes relate to each other.
  */
 
-private import ruby
+private import codeql.ruby.AST
 private import codeql.ruby.DataFlow
 private import codeql.ruby.typetracking.TypeTracker
 private import codeql.ruby.ast.internal.Module

ruby/ql/lib/codeql/ruby/CFG.qll

@@ -1,5 +1,6 @@
 /** Provides classes representing the control flow graph. */
 
+import codeql.Locations
 import controlflow.ControlFlowGraph
 import controlflow.CfgNodes as CfgNodes
 import controlflow.BasicBlocks

ruby/ql/lib/codeql/ruby/DataFlow.qll

@@ -1,3 +1,10 @@
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+
+import codeql.Locations
+
 /**
  * Provides classes for performing local (intra-procedural) and
  * global (inter-procedural) data flow analyses.