Merge pull request #249 from github/erb-lib

Add codeql_ruby.ast.Erb library

Author: alexrford

ql/lib/codeql/Locations.qll

@@ -50,4 +50,12 @@ class Location extends @location {
       filepath = f.getAbsolutePath()
     )
   }
+
+  /** Holds if this location starts strictly before the specified location. */
+  pragma[inline]
+  predicate strictlyBefore(Location other) {
+    this.getStartLine() < other.getStartLine()
+    or
+    this.getStartLine() = other.getStartLine() and this.getStartColumn() < other.getStartColumn()
+  }
 }

ql/lib/codeql/ruby/AST.qll

@@ -2,6 +2,7 @@ import codeql.Locations
 import ast.Call
 import ast.Control
 import ast.Constant
+import ast.Erb
 import ast.Expr
 import ast.Literal
 import ast.Method

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

@@ -0,0 +1,267 @@
+private import codeql.Locations
+private import codeql.ruby.AST
+private import internal.Erb
+private import internal.TreeSitter
+
+/**
+ * A node in the ERB abstract syntax tree. This class is the base class for all
+ * ERB elements.
+ */
+class ErbAstNode extends TAstNode {
+  /** Gets a textual representation of this node. */
+  cached
+  string toString() { none() }
+
+  /** Gets the location of this node. */
+  Location getLocation() { result = getLocation(this) }
+
+  /**
+   * Gets the name of a primary CodeQL class to which this node belongs.
+   *
+   * This predicate always has a result. If no primary class can be
+   * determined, the result is `"???"`. If multiple primary classes match,
+   * this predicate can have multiple results.
+   */
+  string getAPrimaryQlClass() { result = "???" }
+}
+
+/**
+ * An ERB template. This can contain multiple directives to be executed when
+ * the template is compiled.
+ */
+class ErbTemplate extends TTemplate, ErbAstNode {
+  private Erb::Template g;
+
+  ErbTemplate() { this = TTemplate(g) }
+
+  override string toString() { result = "erb template" }
+
+  final override string getAPrimaryQlClass() { result = "ErbTemplate" }
+
+  ErbAstNode getAChildNode() { toGenerated(result) = g.getChild(_) }
+}
+
+// Truncate the token string value to 32 char max
+bindingset[val]
+private string displayToken(string val) {
+  val.length() <= 32 and result = val
+  or
+  val.length() > 32 and result = val.prefix(29) + "..."
+}
+
+/**
+ * An ERB token. This could be embedded code, a comment, or arbitrary text.
+ */
+class ErbToken extends TTokenNode, ErbAstNode {
+  override string toString() { result = displayToken(this.getValue()) }
+
+  /** Gets the string value of this token. */
+  string getValue() { exists(Erb::Token g | this = fromGenerated(g) | result = g.getValue()) }
+
+  override string getAPrimaryQlClass() { result = "ErbToken" }
+}
+
+/**
+ * An ERB token appearing within a comment directive.
+ */
+class ErbComment extends ErbToken {
+  private Erb::Comment g;
+
+  ErbComment() { this = TComment(g) }
+
+  override string getValue() { result = g.getValue() }
+
+  final override string getAPrimaryQlClass() { result = "ErbComment" }
+}
+
+/**
+ * An ERB token appearing within a code directive. This will typically be
+ * interpreted as Ruby code or a GraphQL query, depending on context.
+ */
+class ErbCode extends ErbToken {
+  private Erb::Code g;
+
+  ErbCode() { this = TCode(g) }
+
+  override string getValue() { result = g.getValue() }
+
+  final override string getAPrimaryQlClass() { result = "ErbCode" }
+}
+
+bindingset[line, col]
+private predicate locationIncludesPosition(Location loc, int line, int col) {
+  // position between start and end line, exclusive
+  line > loc.getStartLine() and
+  line < loc.getEndLine()
+  or
+  // position on start line, multi line location
+  line = loc.getStartLine() and
+  not loc.getStartLine() = loc.getEndLine() and
+  col >= loc.getStartColumn()
+  or
+  // position on end line, multi line location
+  line = loc.getEndLine() and
+  not loc.getStartLine() = loc.getEndLine() and
+  col <= loc.getEndColumn()
+  or
+  // single line location, position between start and end column
+  line = loc.getStartLine() and
+  loc.getStartLine() = loc.getEndLine() and
+  col >= loc.getStartColumn() and
+  col <= loc.getEndColumn()
+}
+
+/**
+ * A directive in an ERB template.
+ */
+class ErbDirective extends TDirectiveNode, ErbAstNode {
+  private predicate containsStartOf(Location loc) {
+    loc.getFile() = this.getLocation().getFile() and
+    locationIncludesPosition(this.getLocation(), loc.getStartLine(), loc.getStartColumn())
+  }
+
+  private predicate containsStmtStart(Stmt s) {
+    this.containsStartOf(s.getLocation()) and
+    // `Toplevel` statements are not contained within individual directives,
+    // though their start location may appear within a directive location
+    not s instanceof Toplevel
+  }
+
+  /**
+   * Gets a statement that starts in directive that is not a child of any other
+   * statement starting in this directive.
+   */
+  Stmt getAChildStmt() {
+    this.containsStmtStart(result) and
+    not this.containsStmtStart(result.getParent())
+  }
+
+  /**
+   * Gets the last child statement in this directive.
+   * See `getAChildStmt` for more details.
+   */
+  Stmt getTerminalStmt() {
+    result = this.getAChildStmt() and
+    forall(Stmt s | s = this.getAChildStmt() and not s = result |
+      s.getLocation().strictlyBefore(result.getLocation())
+    )
+  }
+
+  /** Gets the child token of this directive. */
+  ErbToken getToken() {
+    exists(Erb::Directive g | this = fromGenerated(g) | toGenerated(result) = g.getChild())
+  }
+
+  override string toString() { result = "erb directive" }
+
+  override string getAPrimaryQlClass() { result = "ErbDirective" }
+}
+
+/**
+ * A comment directive in an ERB template.
+ * ```erb
+ * <%#= 2 + 2 %>
+ * <%# for x in xs do %>
+ * ```
+ */
+class ErbCommentDirective extends ErbDirective {
+  private Erb::CommentDirective g;
+
+  ErbCommentDirective() { this = TCommentDirective(g) }
+
+  override ErbComment getToken() { toGenerated(result) = g.getChild() }
+
+  final override string toString() { result = "<%#" + this.getToken().toString() + "%>" }
+
+  final override string getAPrimaryQlClass() { result = "ErbCommentDirective" }
+}
+
+/**
+ * A GraphQL directive in an ERB template.
+ * ```erb
+ * <%graphql
+ *   fragment Foo on Bar {
+ *     some {
+ *       queryText
+ *       moreProperties
+ *     }
+ *   }
+ * %>
+ * ```
+ */
+class ErbGraphqlDirective extends ErbDirective {
+  private Erb::GraphqlDirective g;
+
+  ErbGraphqlDirective() { this = TGraphqlDirective(g) }
+
+  override ErbCode getToken() { toGenerated(result) = g.getChild() }
+
+  final override string toString() { result = "<%graphql" + this.getToken().toString() + "%>" }
+
+  final override string getAPrimaryQlClass() { result = "ErbGraphqlDirective" }
+}
+
+/**
+ * An output directive in an ERB template.
+ * ```erb
+ * <%=
+ *   fragment Foo on Bar {
+ *     some {
+ *       queryText
+ *       moreProperties
+ *     }
+ *   }
+ * %>
+ * ```
+ */
+class ErbOutputDirective extends ErbDirective {
+  private Erb::OutputDirective g;
+
+  ErbOutputDirective() { this = TOutputDirective(g) }
+
+  override ErbCode getToken() { toGenerated(result) = g.getChild() }
+
+  final override string toString() { result = "<%=" + this.getToken().toString() + "%>" }
+
+  final override string getAPrimaryQlClass() { result = "ErbOutputDirective" }
+}
+
+/**
+ * An execution directive in an ERB template.
+ * This code will be executed as Ruby, but not rendered.
+ * ```erb
+ * <% books = author.books
+ *    for book in books do %>
+ * ```
+ */
+class ErbExecutionDirective extends ErbDirective {
+  private Erb::Directive g;
+
+  ErbExecutionDirective() { this = TDirective(g) }
+
+  final override string toString() { result = "<%" + this.getToken().toString() + "%>" }
+
+  final override string getAPrimaryQlClass() { result = "ErbExecutionDirective" }
+}
+
+/**
+ * A `File` containing an Embedded Ruby template.
+ * This is typically a file containing snippets of Ruby code that can be
+ * evaluated to create a compiled version of the file.
+ */
+class ErbFile extends File {
+  private ErbTemplate template;
+
+  ErbFile() { this = template.getLocation().getFile() }
+
+  /**
+   * Holds if the file represents a partial to be rendered in the context of
+   * another template.
+   */
+  predicate isPartial() { this.getStem().charAt(0) = "_" }
+
+  /**
+   * Gets the erb template contained within this file.
+   */
+  ErbTemplate getTemplate() { result = template }
+}

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

@@ -0,0 +1,43 @@
+import codeql.Locations
+private import TreeSitter
+private import codeql.ruby.ast.Erb
+
+cached
+private module Cached {
+  cached
+  newtype TAstNode =
+    TCommentDirective(Erb::CommentDirective g) or
+    TDirective(Erb::Directive g) or
+    TGraphqlDirective(Erb::GraphqlDirective g) or
+    TOutputDirective(Erb::OutputDirective g) or
+    TTemplate(Erb::Template g) or
+    TToken(Erb::Token g) or
+    TComment(Erb::Comment g) or
+    TCode(Erb::Code g)
+
+  /**
+   * Gets the underlying TreeSitter entity for a given erb AST node.
+   */
+  cached
+  Erb::AstNode toGenerated(ErbAstNode n) {
+    n = TCommentDirective(result) or
+    n = TDirective(result) or
+    n = TGraphqlDirective(result) or
+    n = TOutputDirective(result) or
+    n = TTemplate(result) or
+    n = TToken(result) or
+    n = TComment(result) or
+    n = TCode(result)
+  }
+
+  cached
+  Location getLocation(ErbAstNode n) { result = toGenerated(n).getLocation() }
+}
+
+import Cached
+
+TAstNode fromGenerated(Erb::AstNode n) { n = toGenerated(result) }
+
+class TDirectiveNode = TCommentDirective or TDirective or TGraphqlDirective or TOutputDirective;
+
+class TTokenNode = TToken or TComment or TCode;

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

@@ -100,14 +100,6 @@ private predicate scopeAssigns(Scope::Range scope, string name, Ruby::Identifier
   scope = scopeOf(i)
 }
 
-/** Holds if location `one` starts strictly before location `two` */
-pragma[inline]
-private predicate strictlyBefore(Location one, Location two) {
-  one.getStartLine() < two.getStartLine()
-  or
-  one.getStartLine() = two.getStartLine() and one.getStartColumn() < two.getStartColumn()
-}
-
 cached
 private module Cached {
   cached
@@ -296,7 +288,7 @@ private module Cached {
       name = access.getValue()
     |
       variable.getDeclaringScope() = scopeOf(access) and
-      not strictlyBefore(access.getLocation(), variable.getLocation()) and
+      not access.getLocation().strictlyBefore(variable.getLocation()) and
       // In case of overlapping parameter names, later parameters should not
       // be considered accesses to the first parameter
       if parameterAssignment(_, _, access)
@@ -366,7 +358,7 @@ private predicate inherits(Scope::Range scope, string name, Scope::Range outer)
       or
       exists(Ruby::Identifier i |
         scopeAssigns(outer, name, i) and
-        strictlyBefore(i.getLocation(), scope.getLocation())
+        i.getLocation().strictlyBefore(scope.getLocation())
       )
     )
     or

ql/lib/codeql/ruby/frameworks/ActionController.qll

@@ -68,8 +68,7 @@ class ActionControllerActionMethod extends Method, HTTP::Server::RequestHandler:
    * corresponding template file at
    * `<sourcePrefix>app/views/<subpath>/<method_name>.html.erb`.
    */
-  // TODO: result should be `ErbFile`
-  File getDefaultTemplateFile() {
+  ErbFile getDefaultTemplateFile() {
     controllerTemplatesFolder(this.getControllerClass(), result.getParentContainer()) and
     result.getBaseName() = this.getName() + ".html.erb"
   }
@@ -194,8 +193,7 @@ class ActionControllerHelperMethod extends Method {
  * mapped to a controller class in `app/controllers/foo/bar/baz_controller.rb`,
  * if such a controller class exists.
  */
-// TODO: parameter should be `ErbFile`
-ActionControllerControllerClass getAssociatedControllerClass(File f) {
+ActionControllerControllerClass getAssociatedControllerClass(ErbFile f) {
   controllerTemplatesFolder(result, f.getParentContainer())
 }