CodeQL documentation

Basic query for Ruby code

Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.

For information about installing the CodeQL extension for Visual Studio code, see “Installing CodeQL for Visual Studio Code.”

About the query

The query we’re going to run performs a basic search of the code for if expressions that are redundant, in the sense that they have an empty then branch. For example, code such as:

if error
  # Handle the error

Finding a CodeQL database to experiment with

Before you start writing queries for Ruby code, you need a CodeQL database to run them against. The simplest way to do this is to download a database for a repository that uses Ruby directly from GitHub.com.

  1. In Visual Studio Code, click the QL icon Icon for the CodeQL extension. in the left sidebar to display the CodeQL extension.
  2. Click From GitHub or the GitHub logo Icon for the CodeQL extension option to download a CodeQL database from GitHub. at the top of the CodeQL extension to open an entry field.
  3. Copy the URL for the repository into the field and press the keyboard Enter key. For example, https://github.com/discourse/discourse.
  4. Optionally, if the repository has more than one CodeQL database available, select ruby to download the database created from the Ruby code.

Information about the download progress for the database is shown in the bottom right corner of Visual Studio Code. When the download is complete, the database is shown with a check mark in the Databases section of the CodeQL extension (see screenshot below).

Running a quick query

The CodeQL extension for Visual Studio Code adds several CodeQL: commands to the command palette including Quick Query, which you can use to run a query without any set up.

  1. From the command palette in Visual Studio Code, select CodeQL: Quick Query.

  2. After a moment, a new tab quick-query.ql is opened, ready for you to write a query for your currently selected CodeQL database (here a ruby database). If you are prompted to reload your workspace as a multi-folder workspace to allow Quick queries, accept or create a new workspace using the starter workflow.

    image-quick-query

  1. In the quick query tab, delete the content and paste in the following query.

    import codeql.ruby.AST
    
    from IfExpr ifexpr
    where
    not exists(ifexpr.getThen())
    select ifexpr, "This 'if' expression is redundant."
    
  1. Save the query in its default location (a temporary “Quick Queries” directory under the workspace for GitHub.vscode-codeql/quick-queries).

  2. Right-click in the query tab and select CodeQL: Run Query on Selected Database. (Alternatively, run the command from the Command Palette.)

    The query will take a few moments to return results. When the query completes, the results are displayed in a CodeQL Query Results view, next to the main editor view.

    The query results are listed in two columns, corresponding to the expressions in the select clause of the query. The first column corresponds to the expression ifexpr and is linked to the location in the source code of the project where ifexpr occurs. The second column is the alert message.

../../_images/basic-ruby-query-results-1.png

If any matching code is found, click a link in the ifexpr column to open the file and highlight the matching if statement.

../../_images/basic-ruby-query-results-2.png

Note

If you want to move your experimental query somewhere more permanent, you need to move the whole Quick Queries directory. The directory is a CodeQL pack with a qlpack.yml file that defines the content as queries for Ruby CodeQL databases. For more information about CodeQL packs, see “Managing CodeQL query packs and library packs.”

About the query structure

After the initial import statement, this simple query comprises three parts that serve similar purposes to the FROM, WHERE, and SELECT parts of an SQL query.

Query part Purpose Details
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. Declarations are of the form: <type> <variable name> We use: an IfExpr variable for if expressions.
where not exists(ifexpr.getThen()) Defines a condition on the variables.

ifexpr.getThen(): gets the then branch of the if expression.

exists(...): requires that there is a matching element, in this case a then branch.

select ifexpr, "This 'if' expression is redundant."

Defines what to report for each match.

select statements for queries that are used to find instances of poor coding practice are always in the form: select <program element>, "<alert message>"

Reports the resulting if expression with a string that explains the problem.

Extend the query

Query writing is an inherently iterative process. You write a simple query and then, when you run it, you discover examples that you had not previously considered, or opportunities for improvement.

Remove false positive results

Browsing the results of our basic query shows that it could be improved. Among the results you are likely to find examples of if statements with an else branch, where an empty then branch does serve a purpose. For example:

if option == "-verbose"
  # nothing to do - handled earlier
else
  error "unrecognized option"

In this case, identifying the if statement with the empty then branch as redundant is a false positive. One solution to this is to modify the query to select if statements where both the then and else branches are missing.

To exclude if statements that have an else branch:

  1. Add the following to the where clause:

    and not exists(ifstmt.getElse())
    

    The where clause is now:

    where
       not exists(ifexpr.getThen()) and
       not exists(ifexpr.getElse())
    
  2. Re-run the query.

    There are now fewer results because if expressions with an else branch are no longer included.

  • © GitHub, Inc.
  • Terms
  • Privacy