mirror of
https://github.com/hohn/codeql-info.git
synced 2025-12-16 20:53:04 +01:00
1131 lines
193 KiB
HTML
1131 lines
193 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>CodeQL library for JavaScript — CodeQL</title>
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=93459777" />
|
||
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
|
||
<script src="../_static/doctools.js?v=888ff710"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<link rel="icon" href="../_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="next" title="CodeQL library for TypeScript" href="codeql-library-for-typescript.html" />
|
||
<link rel="prev" title="Basic query for JavaScript code" href="basic-query-for-javascript-code.html" />
|
||
|
||
<title>CodeQL docs</title>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/primer.css" type="text/css" />
|
||
|
||
|
||
</head><body>
|
||
<header class="Header">
|
||
<div class="Header-item--full">
|
||
<a href="https://codeql.github.com/docs" class="Header-link f2 d-flex flex-items-center">
|
||
<!-- <%= octicon "mark-github", class: "mr-2", height: 32 %> -->
|
||
<svg height="32" class="octicon octicon-mark-github mr-2" viewBox="0 0 16 16" version="1.1" width="32"
|
||
aria-hidden="true">
|
||
<path fill-rule="evenodd"
|
||
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">
|
||
</path>
|
||
</svg>
|
||
<span class="hide-sm">CodeQL documentation</span>
|
||
</a>
|
||
</div>
|
||
<div class="Header-item hide-sm hide-md">
|
||
<script src="https://addsearch.com/js/?key=93b4d287e2fc079a4089412b669785d5&categories=!0xhelp.semmle.com,0xcodeql.github.com,1xdocs,1xcodeql-standard-libraries,1xcodeql-query-help"></script>
|
||
</div>
|
||
<div class="Header-item">
|
||
|
||
<details class="dropdown details-reset details-overlay d-inline-block">
|
||
<summary class="btn bg-gray-dark text-white border" aria-haspopup="true">
|
||
CodeQL resources
|
||
<div class="dropdown-caret"></div>
|
||
</summary>
|
||
|
||
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-overview">CodeQL overview</a></li>
|
||
<li class="dropdown-divider" role="separator"></li>
|
||
<div class="dropdown-header">
|
||
CodeQL tools
|
||
</div>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-for-visual-studio-code">CodeQL for VS Code</a>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-cli">CodeQL CLI</a>
|
||
</li>
|
||
<li class="dropdown-divider" role="separator"></li>
|
||
<div class="dropdown-header">
|
||
CodeQL guides
|
||
</div>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/writing-codeql-queries">Writing CodeQL queries</a></li>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-language-guides">CodeQL language guides</a>
|
||
<li class="dropdown-divider" role="separator"></li>
|
||
<div class="dropdown-header">
|
||
Reference docs
|
||
</div>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/docs/ql-language-reference/">QL language
|
||
reference</a>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-standard-libraries">CodeQL
|
||
standard-libraries</a>
|
||
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-query-help">CodeQL
|
||
query help</a>
|
||
<li class="dropdown-divider" role="separator"></li>
|
||
<div class="dropdown-header">
|
||
Source files
|
||
</div>
|
||
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
|
||
</ul>
|
||
</details>
|
||
|
||
</div>
|
||
|
||
</header>
|
||
<main class="bg-gray-light clearfix">
|
||
<nav class="SideNav position-sticky top-0 col-lg-3 col-md-3 float-left p-4 hide-sm hide-md overflow-y-auto">
|
||
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="../codeql-overview/index.html">CodeQL overview</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="../codeql-for-visual-studio-code/index.html">CodeQL for Visual Studio Code</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="../codeql-cli/index.html">CodeQL CLI</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="../writing-codeql-queries/index.html">Writing CodeQL queries</a></li>
|
||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">CodeQL language guides</a><ul class="current">
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-cpp.html">CodeQL for C and C++</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-csharp.html">CodeQL for C#</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-go.html">CodeQL for Go</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-java.html">CodeQL for Java</a></li>
|
||
<li class="toctree-l2 current"><a class="reference internal" href="codeql-for-javascript.html">CodeQL for JavaScript</a><ul class="current">
|
||
<li class="toctree-l3"><a class="reference internal" href="basic-query-for-javascript-code.html">Basic query for JavaScript code</a></li>
|
||
<li class="toctree-l3 current"><a class="current reference internal" href="#">CodeQL library for JavaScript</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="codeql-library-for-typescript.html">CodeQL library for TypeScript</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="analyzing-data-flow-in-javascript-and-typescript.html">Analyzing data flow in JavaScript and TypeScript</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="using-flow-labels-for-precise-data-flow-analysis.html">Using flow labels for precise data flow analysis</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="specifying-additional-remote-flow-sources-for-javascript.html">Specifying additional remote flow sources for JavaScript</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="using-type-tracking-for-api-modeling.html">Using type tracking for API modeling</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs.html">Abstract syntax tree classes for working with JavaScript and TypeScript programs</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="data-flow-cheat-sheet-for-javascript.html">Data flow cheat sheet for JavaScript</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-python.html">CodeQL for Python</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="codeql-for-ruby.html">CodeQL for Ruby</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="../ql-language-reference/index.html">QL language reference</a></li>
|
||
</ul>
|
||
|
||
|
||
</nav>
|
||
|
||
|
||
<div class="body col-sm-12 col-md-9 col-lg-9 float-left border-left">
|
||
|
||
<div class="hide-lg hide-xl px-4 pt-4">
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<ul>
|
||
<li class="nav-item nav-item-0"><a href="../contents.html">CodeQL</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="index.html"
|
||
>CodeQL language guides</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="codeql-for-javascript.html"
|
||
accesskey="U">CodeQL for JavaScript</a> »</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<article class="p-4 col-lg-10 col-md-10 col-sm-12">
|
||
|
||
<section id="codeql-library-for-javascript">
|
||
<span id="id1"></span><h1>CodeQL library for JavaScript<a class="headerlink" href="#codeql-library-for-javascript" title="Link to this heading">¶</a></h1>
|
||
<p>When you’re analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.</p>
|
||
<section id="overview">
|
||
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
|
||
<p>There is an extensive CodeQL library for analyzing JavaScript code. The classes in this library present the data from a CodeQL database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.</p>
|
||
<p>The library is implemented as a set of QL modules, that is, files with the extension <code class="docutils literal notranslate"><span class="pre">.qll</span></code>. The module <code class="docutils literal notranslate"><span class="pre">javascript.qll</span></code> imports most other standard library modules, so you can include the complete library by beginning your query with:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
</pre></div>
|
||
</div>
|
||
<p>The rest of this tutorial briefly summarizes the most important classes and predicates provided by this library, including references to the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/">detailed API documentation</a> where applicable.</p>
|
||
</section>
|
||
<section id="introducing-the-library">
|
||
<h2>Introducing the library<a class="headerlink" href="#introducing-the-library" title="Link to this heading">¶</a></h2>
|
||
<p>The CodeQL library for JavaScript presents information about JavaScript source code at different levels:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>Textual</strong> — classes that represent source code as unstructured text files</p></li>
|
||
<li><p><strong>Lexical</strong> — classes that represent source code as a series of tokens and comments</p></li>
|
||
<li><p><strong>Syntactic</strong> — classes that represent source code as an abstract syntax tree</p></li>
|
||
<li><p><strong>Name binding</strong> — classes that represent scopes and variables</p></li>
|
||
<li><p><strong>Control flow</strong> — classes that represent the flow of control during execution</p></li>
|
||
<li><p><strong>Data flow</strong> — classes that you can use to reason about data flow in JavaScript source code</p></li>
|
||
<li><p><strong>Type inference</strong> — classes that you can use to approximate types for JavaScript expressions and variables</p></li>
|
||
<li><p><strong>Call graph</strong> — classes that represent the caller-callee relationship between functions</p></li>
|
||
<li><p><strong>Inter-procedural data flow</strong> — classes that you can use to define inter-procedural data flow and taint tracking analyses</p></li>
|
||
<li><p><strong>Frameworks</strong> — classes that represent source code entities that have a special meaning to JavaScript tools and frameworks</p></li>
|
||
</ul>
|
||
<p>Note that representations above the textual level (for example the lexical representation or the flow graphs) are only available for JavaScript code that does not contain fatal syntax errors. For code with such errors, the only information available is at the textual level, as well as information about the errors themselves.</p>
|
||
<p>Additionally, there is library support for working with HTML documents, JSON, and YAML data, JSDoc comments, and regular expressions.</p>
|
||
<section id="textual-level">
|
||
<h3>Textual level<a class="headerlink" href="#textual-level" title="Link to this heading">¶</a></h3>
|
||
<p>At its most basic level, a JavaScript code base can simply be viewed as a collection of files organized into folders, where each file is composed of zero or more lines of text.</p>
|
||
<p>Note that the textual content of a program is not included in the CodeQL database unless you specifically request it during extraction. In particular, databases on LGTM (also known as “snapshots”) do not normally include textual information.</p>
|
||
<section id="files-and-folders">
|
||
<h4>Files and folders<a class="headerlink" href="#files-and-folders" title="Link to this heading">¶</a></h4>
|
||
<p>In the CodeQL libraries, files are represented as entities of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$File.html">File</a>, and folders as entities of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Folder.html">Folder</a>, both of which are subclasses of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Container.html">Container</a>.</p>
|
||
<p>Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Container.html">Container</a> provides the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getParentContainer()</span></code> returns the parent folder of the file or folder.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getAFile()</span></code> returns a file within the folder.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getAFolder()</span></code> returns a folder nested within the folder.</p></li>
|
||
</ul>
|
||
<p>Note that while <code class="docutils literal notranslate"><span class="pre">getAFile</span></code> and <code class="docutils literal notranslate"><span class="pre">getAFolder</span></code> are declared on class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Container.html">Container</a>, they currently only have results for <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Folder.html">Folder</a>s.</p>
|
||
<p>Both files and folders have paths, which can be accessed by the predicate <code class="docutils literal notranslate"><span class="pre">Container.getAbsolutePath()</span></code>. For example, if <code class="docutils literal notranslate"><span class="pre">f</span></code> represents a file with the path <code class="docutils literal notranslate"><span class="pre">/home/user/project/src/index.js</span></code>, then <code class="docutils literal notranslate"><span class="pre">f.getAbsolutePath()</span></code> evaluates to the string <code class="docutils literal notranslate"><span class="pre">"/home/user/project/src/index.js"</span></code>, while <code class="docutils literal notranslate"><span class="pre">f.getParentContainer().getAbsolutePath()</span></code> returns <code class="docutils literal notranslate"><span class="pre">"/home/user/project/src"</span></code>.</p>
|
||
<p>These paths are absolute file system paths. If you want to obtain the path of a file relative to the source location in the CodeQL database, use <code class="docutils literal notranslate"><span class="pre">Container.getRelativePath()</span></code> instead. Note, however, that a database may contain files that are not located underneath the source location; for such files, <code class="docutils literal notranslate"><span class="pre">getRelativePath()</span></code> will not return anything.</p>
|
||
<p>The following member predicates of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Container.html">Container</a> provide more information about the name of a file or folder:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getBaseName()</span></code> returns the base name of a file or folder, not including its parent folder, but including its extension. In the above example, <code class="docutils literal notranslate"><span class="pre">f.getBaseName()</span></code> would return the string <code class="docutils literal notranslate"><span class="pre">"index.js"</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getStem()</span></code> is similar to <code class="docutils literal notranslate"><span class="pre">Container.getBaseName()</span></code>, but it does <em>not</em> include the file extension; so <code class="docutils literal notranslate"><span class="pre">f.getStem()</span></code> returns <code class="docutils literal notranslate"><span class="pre">"index"</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Container.getExtension()</span></code> returns the file extension, not including the dot; so <code class="docutils literal notranslate"><span class="pre">f.getExtension()</span></code> returns <code class="docutils literal notranslate"><span class="pre">"js"</span></code>.</p></li>
|
||
</ul>
|
||
<p>For example, the following query computes, for each folder, the number of JavaScript files (that is, files with extension <code class="docutils literal notranslate"><span class="pre">js</span></code>) contained in the folder:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from Folder d
|
||
select d.getRelativePath(), count(File f | f = d.getAFile() and f.getExtension() = "js")
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/1506075865985/">See this in the query console on LGTM.com</a>. When you run the query on most projects, the results include folders that contain files with a <code class="docutils literal notranslate"><span class="pre">js</span></code> extension and folders that don’t.</p>
|
||
</section>
|
||
<section id="locations">
|
||
<h4>Locations<a class="headerlink" href="#locations" title="Link to this heading">¶</a></h4>
|
||
<p>Most entities in a CodeQL database have an associated source location. Locations are identified by five pieces of information: a file, a start line, a start column, an end line, and an end column. Line and column counts are 1-based (so the first character of a file is at line 1, column 1), and the end position is inclusive.</p>
|
||
<p>All entities associated with a source location belong to the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Locatable.html">Locatable</a>. The location itself is modeled by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Location.html">Location</a> and can be accessed through the member predicate <code class="docutils literal notranslate"><span class="pre">Locatable.getLocation()</span></code>. The <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Location.html">Location</a> class provides the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Location.getFile()</span></code>, <code class="docutils literal notranslate"><span class="pre">Location.getStartLine()</span></code>, <code class="docutils literal notranslate"><span class="pre">Location.getStartColumn()</span></code>, <code class="docutils literal notranslate"><span class="pre">Location.getEndLine()</span></code>, <code class="docutils literal notranslate"><span class="pre">Location.getEndColumn()</span></code> return detailed information about the location.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Location.getNumLines()</span></code> returns the number of (whole or partial) lines covered by the location.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Location.startsBefore(Location)</span></code> and <code class="docutils literal notranslate"><span class="pre">Location.endsAfter(Location)</span></code> determine whether one location starts before or ends after another location.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Location.contains(Location)</span></code> indicates whether one location completely contains another location; <code class="docutils literal notranslate"><span class="pre">l1.contains(l2)</span></code> holds if, and only if, <code class="docutils literal notranslate"><span class="pre">l1.startsBefore(l2)</span></code> and <code class="docutils literal notranslate"><span class="pre">l1.endsAfter(l2)</span></code>.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="lines">
|
||
<h4>Lines<a class="headerlink" href="#lines" title="Link to this heading">¶</a></h4>
|
||
<p>Lines of text in files are represented by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Lines.qll/type.Lines$Line.html">Line</a>. This class offers the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Line.getText()</span></code> returns the text of the line, excluding any terminating newline characters.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Line.getTerminator()</span></code> returns the terminator character(s) of the line. The last line in a file may not have any terminator characters, in which case this predicate does not return anything; otherwise it returns either the two-character string <code class="docutils literal notranslate"><span class="pre">"\r\n"</span></code> (carriage-return followed by newline), or one of the one-character strings <code class="docutils literal notranslate"><span class="pre">"\n"</span></code> (newline), <code class="docutils literal notranslate"><span class="pre">"\r"</span></code> (carriage-return), <code class="docutils literal notranslate"><span class="pre">"\u2028"</span></code> (Unicode character LINE SEPARATOR), <code class="docutils literal notranslate"><span class="pre">"\u2029"</span></code> (Unicode character PARAGRAPH SEPARATOR).</p></li>
|
||
</ul>
|
||
<p>Note that, as mentioned above, the textual representation of the program is not included in the CodeQL database by default.</p>
|
||
</section>
|
||
</section>
|
||
<section id="lexical-level">
|
||
<h3>Lexical level<a class="headerlink" href="#lexical-level" title="Link to this heading">¶</a></h3>
|
||
<p>A slightly more structured view of a JavaScript program is provided by the classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$Token.html">Token</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$Comment.html">Comment</a>, which represent tokens and comments, respectively.</p>
|
||
<section id="tokens">
|
||
<h4>Tokens<a class="headerlink" href="#tokens" title="Link to this heading">¶</a></h4>
|
||
<p>The most important member predicates of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$Token.html">Token</a> are as follows:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Token.getValue()</span></code> returns the source text of the token.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Token.getIndex()</span></code> returns the index of the token within its enclosing script.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Token.getNextToken()</span></code> and <code class="docutils literal notranslate"><span class="pre">Token.getPreviousToken()</span></code> navigate between tokens.</p></li>
|
||
</ul>
|
||
<p>The <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$Token.html">Token</a> class has nine subclasses, each representing a particular kind of token:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$EOFToken.html">EOFToken</a>: a marker token representing the end of a script</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$NullLiteralToken.html">NullLiteralToken</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$BooleanLiteralToken.html">BooleanLiteralToken</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$NumericLiteralToken.html">NumericLiteralToken</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$StringLiteralToken.html">StringLiteralToken</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$RegularExpressionToken.html">RegularExpressionToken</a>: different kinds of literals</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$IdentifierToken.html">IdentifierToken</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$KeywordToken.html">KeywordToken</a>: identifiers and keywords (including reserved words) respectively</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$PunctuatorToken.html">PunctuatorToken</a>: operators and other punctuation symbols</p></li>
|
||
</ul>
|
||
<p>As an example of a query operating entirely on the lexical level, consider the following query, which finds consecutive comma tokens arising from an omitted element in an array expression:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
class CommaToken extends PunctuatorToken {
|
||
CommaToken() {
|
||
getValue() = ","
|
||
}
|
||
}
|
||
|
||
from CommaToken comma
|
||
where comma.getNextToken() instanceof CommaToken
|
||
select comma, "Omitted array elements are bad style."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/659662177/">See this in the query console on LGTM.com</a>. If the query returns no results, this pattern isn’t used in the projects that you analyzed.</p>
|
||
<p>You can use predicate <code class="docutils literal notranslate"><span class="pre">Locatable.getFirstToken()</span></code> and <code class="docutils literal notranslate"><span class="pre">Locatable.getLastToken()</span></code> to access the first and last token (if any) belonging to an element with a source location.</p>
|
||
</section>
|
||
<section id="comments">
|
||
<h4>Comments<a class="headerlink" href="#comments" title="Link to this heading">¶</a></h4>
|
||
<p>The class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$Comment.html">Comment</a> and its subclasses represent the different kinds of comments that can occur in JavaScript programs:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$Comment.html">Comment</a>: any comment</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$LineComment.html">LineComment</a>: a single-line comment terminated by an end-of-line character</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$SlashSlashComment.html">SlashSlashComment</a>: a plain JavaScript single-line comment starting with <code class="docutils literal notranslate"><span class="pre">//</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$HtmlLineComment.html">HtmlLineComment</a>: a (non-standard) HTML comment</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$HtmlCommentStart.html">HtmlCommentStart</a>: an HTML comment starting with <code class="docutils literal notranslate"><span class="pre"><!--</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$HtmlCommentEnd.html">HtmlCommentEnd</a>: an HTML comment ending with <code class="docutils literal notranslate"><span class="pre">--></span></code></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$BlockComment.html">BlockComment</a>: a block comment potentially spanning multiple lines</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$SlashStarComment.html">SlashStarComment</a>: a plain JavaScript block comment surrounded with <code class="docutils literal notranslate"><span class="pre">/*...*/</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$DocComment.html">DocComment</a>: a documentation block comment surrounded with <code class="docutils literal notranslate"><span class="pre">/**...*/</span></code></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The most important member predicates are as follows:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Comment.getText()</span></code> returns the source text of the comment, not including delimiters.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Comment.getLine(i)</span></code> returns the <code class="docutils literal notranslate"><span class="pre">i</span></code>th line of text within the comment (0-based).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Comment.getNumLines()</span></code> returns the number of lines in the comment.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Comment.getNextToken()</span></code> returns the token immediately following a comment. Note that such a token always exists: if a comment appears at the end of a file, its following token is an <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Tokens.qll/type.Tokens$EOFToken.html">EOFToken</a>.</p></li>
|
||
</ul>
|
||
<p>As an example of a query using only lexical information, consider the following query for finding HTML comments, which are not a standard ECMAScript feature and should be avoided:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from HtmlLineComment c
|
||
select c, "Do not use HTML comments."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/686330023/">See this in the query console on LGTM.com</a>. When we ran this query on the <em>mozilla/pdf.js</em> project in LGTM.com, we found three HTML comments.</p>
|
||
</section>
|
||
</section>
|
||
<section id="syntactic-level">
|
||
<h3>Syntactic level<a class="headerlink" href="#syntactic-level" title="Link to this heading">¶</a></h3>
|
||
<p>The majority of classes in the JavaScript library is concerned with representing a JavaScript program as a collection of <a class="reference external" href="https://en.wikipedia.org/wiki/Abstract_syntax_tree">abstract syntax trees</a> (ASTs).</p>
|
||
<p>The class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ASTNode.html">ASTNode</a> contains all entities representing nodes in the abstract syntax trees and defines generic tree traversal predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ASTNode.getChild(i)</span></code>: returns the <code class="docutils literal notranslate"><span class="pre">i</span></code>th child of this AST node.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ASTNode.getAChild()</span></code>: returns any child of this AST node.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ASTNode.getParent()</span></code>: returns the parent node of this AST node, if any.</p></li>
|
||
</ul>
|
||
<blockquote class="pull-quote">
|
||
<div><p>Note</p>
|
||
<p>These predicates should only be used to perform generic AST traversal. To access children of specific AST node types, the specialized predicates introduced below should be used instead. In particular, queries should not rely on the numeric indices of child nodes relative to their parent nodes: these are considered an implementation detail that may change between versions of the library.</p>
|
||
</div></blockquote>
|
||
<section id="top-levels">
|
||
<h4>Top-levels<a class="headerlink" href="#top-levels" title="Link to this heading">¶</a></h4>
|
||
<p>From a syntactic point of view, each JavaScript program is composed of one or more top-level code blocks (or <em>top-levels</em> for short), which are blocks of JavaScript code that do not belong to a larger code block. Top-levels are represented by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a> and its subclasses:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a></p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$Script.html">Script</a>: a stand-alone file or HTML <code class="docutils literal notranslate"><span class="pre"><script></span></code> element</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ExternalScript.html">ExternalScript</a>: a stand-alone JavaScript file</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$InlineScript.html">InlineScript</a>: code embedded inline in an HTML <code class="docutils literal notranslate"><span class="pre"><script></span></code> tag</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$CodeInAttribute.html">CodeInAttribute</a>: a code block originating from an HTML attribute value</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$EventHandlerCode.html">EventHandlerCode</a>: code from an event handler attribute such as <code class="docutils literal notranslate"><span class="pre">onload</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$JavaScriptURL.html">JavaScriptURL</a>: code from a URL with the <code class="docutils literal notranslate"><span class="pre">javascript:</span></code> scheme</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$Externs.html">Externs</a>: a JavaScript file containing <a class="reference external" href="https://developers.google.com/closure/compiler/docs/externs-and-exports">externs</a> definitions</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Every <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a> class is contained in a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$File.html">File</a> class, but a single <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$File.html">File</a> may contain more than one <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a>. To go from a <code class="docutils literal notranslate"><span class="pre">TopLevel</span> <span class="pre">tl</span></code> to its <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$File.html">File</a>, use <code class="docutils literal notranslate"><span class="pre">tl.getFile()</span></code>; conversely, for a <code class="docutils literal notranslate"><span class="pre">File</span> <span class="pre">f</span></code>, predicate <code class="docutils literal notranslate"><span class="pre">f.getATopLevel()</span></code> returns a top-level contained in <code class="docutils literal notranslate"><span class="pre">f</span></code>. For every AST node, predicate <code class="docutils literal notranslate"><span class="pre">ASTNode.getTopLevel()</span></code> can be used to find the top-level it belongs to.</p>
|
||
<p>The <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a> class additionally provides the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">TopLevel.getNumberOfLines()</span></code> returns the total number of lines (including code, comments and whitespace) in the top-level.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">TopLevel.getNumberOfLinesOfCode()</span></code> returns the number of lines of code, that is, lines that contain at least one token.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">TopLevel.getNumberOfLinesOfComments()</span></code> returns the number of lines containing or belonging to a comment.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">TopLevel.isMinified()</span></code> determines whether the top-level contains minified code, using a heuristic based on the average number of statements per line.</p></li>
|
||
</ul>
|
||
<blockquote class="pull-quote">
|
||
<div><p>Note</p>
|
||
<p>By default, LGTM filters out alerts in minified top-levels, since they are often hard to interpret. When writing your own queries in the LGTM query console, this filtering is <em>not</em> done automatically, so you may want to explicitly add a condition of the form <code class="docutils literal notranslate"><span class="pre">and</span> <span class="pre">not</span> <span class="pre">e.getTopLevel().isMinified()</span></code> or similar to your query to exclude results in minified code.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
<section id="statements-and-expressions">
|
||
<h4>Statements and expressions<a class="headerlink" href="#statements-and-expressions" title="Link to this heading">¶</a></h4>
|
||
<p>The most important subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ASTNode.html">ASTNode</a> besides <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$TopLevel.html">TopLevel</a> are <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>, which, together with their subclasses, represent statements and expressions, respectively. This section briefly discusses some of the more important classes and predicates. For a full reference of all the subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> and their API, see
|
||
<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/module.Stmt.html">Stmt.qll</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/module.Expr.html">Expr.qll</a>.</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a>: use <code class="docutils literal notranslate"><span class="pre">Stmt.getContainer()</span></code> to access the innermost function or top-level in which the statement is contained.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ControlStmt.html">ControlStmt</a>: a statement that controls the execution of other statements, that is, a conditional, loop, <code class="docutils literal notranslate"><span class="pre">try</span></code> or <code class="docutils literal notranslate"><span class="pre">with</span></code> statement; use <code class="docutils literal notranslate"><span class="pre">ControlStmt.getAControlledStmt()</span></code> to access the statements that it controls.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$IfStmt.html">IfStmt</a>: an <code class="docutils literal notranslate"><span class="pre">if</span></code> statement; use <code class="docutils literal notranslate"><span class="pre">IfStmt.getCondition()</span></code>, <code class="docutils literal notranslate"><span class="pre">IfStmt.getThen()</span></code> and <code class="docutils literal notranslate"><span class="pre">IfStmt.getElse()</span></code> to access its condition expression, “then” branch and “else” branch, respectively.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$LoopStmt.html">LoopStmt</a>: a loop; use <code class="docutils literal notranslate"><span class="pre">Loop.getBody()</span></code> and <code class="docutils literal notranslate"><span class="pre">Loop.getTest()</span></code> to access its body and its test expression, respectively.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$WhileStmt.html">WhileStmt</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$DoWhileStmt.html">DoWhileStmt</a>: a “while” or “do-while” loop, respectively.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ForStmt.html">ForStmt</a>: a “for” statement; use <code class="docutils literal notranslate"><span class="pre">ForStmt.getInit()</span></code> and <code class="docutils literal notranslate"><span class="pre">ForStmt.getUpdate()</span></code> to access the init and update expressions, respectively.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$EnhancedForLoop.html">EnhancedForLoop</a>: a “for-in” or “for-of” loop; use <code class="docutils literal notranslate"><span class="pre">EnhancedForLoop.getIterator()</span></code> to access the loop iterator (which may be a expression or variable declaration), and <code class="docutils literal notranslate"><span class="pre">EnhancedForLoop.getIterationDomain()</span></code> to access the expression being iterated over.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ForInStmt.html">ForInStmt</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ForOfStmt.html">ForOfStmt</a>: a “for-in” or “for-of” loop, respectively.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$WithStmt.html">WithStmt</a>: a “with” statement; use <code class="docutils literal notranslate"><span class="pre">WithStmt.getExpr()</span></code> and <code class="docutils literal notranslate"><span class="pre">WithStmt.getBody()</span></code> to access the controlling expression and the body of the with statement, respectively.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$SwitchStmt.html">SwitchStmt</a>: a switch statement; use <code class="docutils literal notranslate"><span class="pre">SwitchStmt.getExpr()</span></code> to access the expression on which the statement switches; use <code class="docutils literal notranslate"><span class="pre">SwitchStmt.getCase(int)</span></code> and <code class="docutils literal notranslate"><span class="pre">SwitchStmt.getACase()</span></code> to access individual switch cases; each case is modeled by an entity of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Case.html">Case</a>, whose member predicates <code class="docutils literal notranslate"><span class="pre">Case.getExpr()</span></code> and <code class="docutils literal notranslate"><span class="pre">Case.getBodyStmt(int)</span></code> provide access to the expression checked by the switch case (which is undefined for <code class="docutils literal notranslate"><span class="pre">default</span></code>), and its body.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$TryStmt.html">TryStmt</a>: a “try” statement; use <code class="docutils literal notranslate"><span class="pre">TryStmt.getBody()</span></code>, <code class="docutils literal notranslate"><span class="pre">TryStmt.getCatchClause()</span></code> and <code class="docutils literal notranslate"><span class="pre">TryStmt.getFinally</span></code> to access its body, “catch” clause and “finally” block, respectively.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$BlockStmt.html">BlockStmt</a>: a block of statements; use <code class="docutils literal notranslate"><span class="pre">BlockStmt.getStmt(int)</span></code> to access the individual statements in the block.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ExprStmt.html">ExprStmt</a>: an expression statement; use <code class="docutils literal notranslate"><span class="pre">ExprStmt.getExpr()</span></code> to access the expression itself.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$JumpStmt.html">JumpStmt</a>: a statement that disrupts structured control flow, that is, one of <code class="docutils literal notranslate"><span class="pre">break</span></code>, <code class="docutils literal notranslate"><span class="pre">continue</span></code>, <code class="docutils literal notranslate"><span class="pre">return</span></code> and <code class="docutils literal notranslate"><span class="pre">throw</span></code>; use predicate <code class="docutils literal notranslate"><span class="pre">JumpStmt.getTarget()</span></code> to determine the target of the jump, which is either a statement or (for <code class="docutils literal notranslate"><span class="pre">return</span></code> and uncaught <code class="docutils literal notranslate"><span class="pre">throw</span></code> statements) the enclosing function.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$BreakStmt.html">BreakStmt</a>: a “break” statement; use <code class="docutils literal notranslate"><span class="pre">BreakStmt.getLabel()</span></code> to access its (optional) target label.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ContinueStmt.html">ContinueStmt</a>: a “continue” statement; use <code class="docutils literal notranslate"><span class="pre">ContinueStmt.getLabel()</span></code> to access its (optional) target label.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ReturnStmt.html">ReturnStmt</a>: a “return” statement; use <code class="docutils literal notranslate"><span class="pre">ReturnStmt.getExpr()</span></code> to access its (optional) result expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ThrowStmt.html">ThrowStmt</a>: a “throw” statement; use <code class="docutils literal notranslate"><span class="pre">ThrowStmt.getExpr()</span></code> to access its thrown expression.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$FunctionDeclStmt.html">FunctionDeclStmt</a>: a function declaration statement; see below for available member predicates.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassDeclStmt.html">ClassDeclStmt</a>: a class declaration statement; see below for available member predicates.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$DeclStmt.html">DeclStmt</a>: a declaration statement containing one or more declarators which can be accessed by predicate <code class="docutils literal notranslate"><span class="pre">DeclStmt.getDeclarator(int)</span></code>.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$VarDeclStmt.html">VarDeclStmt</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ConstDeclStmt.html">ConstDeclStmt</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$LetStmt.html">LetStmt</a>: a <code class="docutils literal notranslate"><span class="pre">var</span></code>, <code class="docutils literal notranslate"><span class="pre">const</span></code> or <code class="docutils literal notranslate"><span class="pre">let</span></code> declaration statement.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>: use <code class="docutils literal notranslate"><span class="pre">Expr.getEnclosingStmt()</span></code> to obtain the innermost statement to which this expression belongs; <code class="docutils literal notranslate"><span class="pre">Expr.isPure()</span></code> determines whether the expression is side-effect-free.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Identifier.html">Identifier</a>: an identifier; use <code class="docutils literal notranslate"><span class="pre">Identifier.getName()</span></code> to obtain its name.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Literal.html">Literal</a>: a literal value; use <code class="docutils literal notranslate"><span class="pre">Literal.getValue()</span></code> to obtain a string representation of its value, and <code class="docutils literal notranslate"><span class="pre">Literal.getRawValue()</span></code> to obtain its raw source text (including surrounding quotes for string literals).</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$NullLiteral.html">NullLiteral</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$BooleanLiteral.html">BooleanLiteral</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$NumberLiteral.html">NumberLiteral</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$StringLiteral.html">StringLiteral</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$RegExpLiteral.html">RegExpLiteral</a>: different kinds of literals.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ThisExpr.html">ThisExpr</a>: a “this” expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$SuperExpr.html">SuperExpr</a>: a “super” expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ArrayExpr.html">ArrayExpr</a>: an array expression; use <code class="docutils literal notranslate"><span class="pre">ArrayExpr.getElement(i)</span></code> to obtain the <code class="docutils literal notranslate"><span class="pre">i</span></code>th element expression, and <code class="docutils literal notranslate"><span class="pre">ArrayExpr.elementIsOmitted(i)</span></code> to check whether the <code class="docutils literal notranslate"><span class="pre">i</span></code>th element is omitted.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ObjectExpr.html">ObjectExpr</a>: an object expression; use <code class="docutils literal notranslate"><span class="pre">ObjectExpr.getProperty(i)</span></code> to obtain the <code class="docutils literal notranslate"><span class="pre">i</span></code>th property in the object expression; properties are modeled by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Property.html">Property</a>, which is described in more detail below.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$FunctionExpr.html">FunctionExpr</a>: a function expression; see below for available member predicates.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ArrowFunctionExpr.html">ArrowFunctionExpr</a>: an ECMAScript 2015-style arrow function expression; see below for available member predicates.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassExpr.html">ClassExpr</a>: a class expression; see below for available member predicates.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ParExpr.html">ParExpr</a>: a parenthesized expression; use <code class="docutils literal notranslate"><span class="pre">ParExpr.getExpression()</span></code> to obtain the operand expression; for any expression, <code class="docutils literal notranslate"><span class="pre">Expr.stripParens()</span></code> can be used to recursively strip off any parentheses</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$SeqExpr.html">SeqExpr</a>: a sequence of two or more expressions connected by the comma operator; use <code class="docutils literal notranslate"><span class="pre">SeqExpr.getOperand(i)</span></code> to obtain the <code class="docutils literal notranslate"><span class="pre">i</span></code>th sub-expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ConditionalExpr.html">ConditionalExpr</a>: a ternary conditional expression; member predicates <code class="docutils literal notranslate"><span class="pre">ConditionalExpr.getCondition()</span></code>, <code class="docutils literal notranslate"><span class="pre">ConditionalExpr.getConsequent()</span></code> and <code class="docutils literal notranslate"><span class="pre">ConditionalExpr.getAlternate()</span></code> provide access to the condition expression, the “then” expression and the “else” expression, respectively.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$InvokeExpr.html">InvokeExpr</a>: a function call or a “new” expression; use <code class="docutils literal notranslate"><span class="pre">InvokeExpr.getCallee()</span></code> to obtain the expression specifying the function to be called, and <code class="docutils literal notranslate"><span class="pre">InvokeExpr.getArgument(i)</span></code> to obtain the <code class="docutils literal notranslate"><span class="pre">i</span></code>th argument expression.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$CallExpr.html">CallExpr</a>: a function call.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$NewExpr.html">NewExpr</a>: a “new” expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$MethodCallExpr.html">MethodCallExpr</a>: a function call whose callee expression is a property access; use <code class="docutils literal notranslate"><span class="pre">MethodCallExpr.getReceiver</span></code> to access the receiver expression of the method call, and <code class="docutils literal notranslate"><span class="pre">MethodCallExpr.getMethodName()</span></code> to get the method name (if it can be determined statically).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropAccess.html">PropAccess</a>: a property access, that is, either a “dot” expression of the form <code class="docutils literal notranslate"><span class="pre">e.f</span></code> or an index expression of the form <code class="docutils literal notranslate"><span class="pre">e[p]</span></code>; use <code class="docutils literal notranslate"><span class="pre">PropAccess.getBase()</span></code> to obtain the base expression on which the property is accessed (<code class="docutils literal notranslate"><span class="pre">e</span></code> in the example), and <code class="docutils literal notranslate"><span class="pre">PropAccess.getPropertyName()</span></code> to determine the name of the accessed property; if the name cannot be statically determined, <code class="docutils literal notranslate"><span class="pre">getPropertyName()</span></code> does not return any value.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$DotExpr.html">DotExpr</a>: a “dot” expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$IndexExpr.html">IndexExpr</a>: an index expression (also known as computed property access).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$UnaryExpr.html">UnaryExpr</a>: a unary expression; use <code class="docutils literal notranslate"><span class="pre">UnaryExpr.getOperand()</span></code> to obtain the operand expression.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$NegExpr.html">NegExpr</a> (“-“), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PlusExpr.html">PlusExpr</a> (“+”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LogNotExpr.html">LogNotExpr</a> (“!”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$BitNotExpr.html">BitNotExpr</a> (“~”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$TypeofExpr.html">TypeofExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$VoidExpr.html">VoidExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$DeleteExpr.html">DeleteExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$SpreadElement.html">SpreadElement</a> (”…”): various types of unary expressions.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$BinaryExpr.html">BinaryExpr</a>: a binary expression; use <code class="docutils literal notranslate"><span class="pre">BinaryExpr.getLeftOperand()</span></code> and <code class="docutils literal notranslate"><span class="pre">BinaryExpr.getRightOperand()</span></code> to access the operand expressions.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Comparison.html">Comparison</a>: any comparison expression.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$EqualityTest.html">EqualityTest</a>: any equality or inequality test.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$EqExpr.html">EqExpr</a> (“==”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$NEqExpr.html">NEqExpr</a> (“!=”): non-strict equality and inequality tests.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$StrictEqExpr.html">StrictEqExpr</a> (“===”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$StrictNEqExpr.html">StrictNEqExpr</a> (“!==”): strict equality and inequality tests.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LTExpr.html">LTExpr</a> (“<”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LEExpr.html">LEExpr</a> (“<=”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$GTExpr.html">GTExpr</a> (“>”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$GEExpr.html">GEExpr</a> (“>=”): numeric comparisons.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LShiftExpr.html">LShiftExpr</a> (“<<”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$RShiftExpr.html">RShiftExpr</a> (“>>”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$URShiftExpr.html">URShiftExpr</a> (“>>>”): shift operators.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AddExpr.html">AddExpr</a> (“+”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$SubExpr.html">SubExpr</a> (“-“), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$MulExpr.html">MulExpr</a> (“*”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$DivExpr.html">DivExpr</a> (“/”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ModExpr.html">ModExpr</a> (“%”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ExpExpr.html">ExpExpr</a> (“**”): arithmetic operators.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$BitOrExpr.html">BitOrExpr</a> (“|”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$XOrExpr.html">XOrExpr</a> (“^”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$BitAndExpr.html">BitAndExpr</a> (”&”): bitwise operators.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$InExpr.html">InExpr</a>: an <code class="docutils literal notranslate"><span class="pre">in</span></code> test.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$InstanceofExpr.html">InstanceofExpr</a>: an <code class="docutils literal notranslate"><span class="pre">instanceof</span></code> test.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LogAndExpr.html">LogAndExpr</a> (”&&”), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$LogOrExpr.html">LogOrExpr</a> (“||”): short-circuiting logical operators.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Assignment.html">Assignment</a>: assignment expressions, either simple or compound; use <code class="docutils literal notranslate"><span class="pre">Assignment.getLhs()</span></code> and <code class="docutils literal notranslate"><span class="pre">Assignment.getRhs()</span></code> to access the left- and right-hand side, respectively.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignExpr.html">AssignExpr</a>: a simple assignment expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$CompoundAssignExpr.html">CompoundAssignExpr</a>: a compound assignment expression.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignAddExpr.html">AssignAddExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignSubExpr.html">AssignSubExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignMulExpr.html">AssignMulExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignDivExpr.html">AssignDivExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignModExpr.html">AssignModExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignLShiftExpr.html">AssignLShiftExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignRShiftExpr.html">AssignRShiftExpr</a>,
|
||
<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignURShiftExpr.html">AssignURShiftExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignOrExpr.html">AssignOrExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignXOrExpr.html">AssignXOrExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignAndExpr.html">AssignAndExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AssignExpExpr.html">AssignExpExpr</a>: different kinds of compound assignment expressions.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$UpdateExpr.html">UpdateExpr</a>: an increment or decrement expression; use <code class="docutils literal notranslate"><span class="pre">UpdateExpr.getOperand()</span></code> to obtain the operand expression.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PreIncExpr.html">PreIncExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PostIncExpr.html">PostIncExpr</a>: an increment expression.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PreDecExpr.html">PreDecExpr</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PostDecExpr.html">PostDecExpr</a>: a decrement expression.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$YieldExpr.html">YieldExpr</a>: a “yield” expression; use <code class="docutils literal notranslate"><span class="pre">YieldExpr.getOperand()</span></code> to access the (optional) operand expression; use <code class="docutils literal notranslate"><span class="pre">YieldExpr.isDelegating()</span></code> to check whether this is a delegating <code class="docutils literal notranslate"><span class="pre">yield*</span></code>.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Templates.qll/type.Templates$TemplateLiteral.html">TemplateLiteral</a>: an ECMAScript 2015 template literal; <code class="docutils literal notranslate"><span class="pre">TemplateLiteral.getElement(i)</span></code> returns the <code class="docutils literal notranslate"><span class="pre">i</span></code>th element of the template, which may either be an interpolated expression or a constant template element.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Templates.qll/type.Templates$TaggedTemplateExpr.html">TaggedTemplateExpr</a>: an ECMAScript 2015 tagged template literal; use <code class="docutils literal notranslate"><span class="pre">TaggedTemplateExpr.getTag()</span></code> to access the tagging expression, and <code class="docutils literal notranslate"><span class="pre">TaggedTemplateExpr.getTemplate()</span></code> to access the template literal being tagged.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Templates.qll/type.Templates$TemplateElement.html">TemplateElement</a>: a constant template element; as for literals, use <code class="docutils literal notranslate"><span class="pre">TemplateElement.getValue()</span></code> to obtain the value of the element, and <code class="docutils literal notranslate"><span class="pre">TemplateElement.getRawValue()</span></code> for its raw value</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$AwaitExpr.html">AwaitExpr</a>: an “await” expression; use <code class="docutils literal notranslate"><span class="pre">AwaitExpr.getOperand()</span></code> to access the operand expression.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> share a common superclass <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ExprOrStmt.html">ExprOrStmt</a> which is useful for queries that should operate either on statements or on expressions, but not on any other AST nodes.</p>
|
||
<p>As an example of how to use expression AST nodes, here is a query that finds expressions of the form <code class="docutils literal notranslate"><span class="pre">e</span> <span class="pre">+</span> <span class="pre">f</span> <span class="pre">>></span> <span class="pre">g</span></code>; such expressions should be rewritten as <code class="docutils literal notranslate"><span class="pre">(e</span> <span class="pre">+</span> <span class="pre">f)</span> <span class="pre">>></span> <span class="pre">g</span></code> to clarify operator precedence:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from ShiftExpr shift, AddExpr add
|
||
where add = shift.getAnOperand()
|
||
select add, "This expression should be bracketed to clarify precedence rules."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/690010024/">See this in the query console on LGTM.com</a>. When we ran this query on the <em>meteor/meteor</em> project in LGTM.com, we found many results where precedence could be clarified using brackets.</p>
|
||
</section>
|
||
<section id="functions">
|
||
<h4>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h4>
|
||
<p>JavaScript provides several ways of defining functions: in ECMAScript 5, there are function declaration statements and function expressions, and ECMAScript 2015 adds arrow function expressions. These different syntactic forms are represented by the classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$FunctionDeclStmt.html">FunctionDeclStmt</a> (a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a>), <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$FunctionExpr.html">FunctionExpr</a> (a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>) and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ArrowFunctionExpr.html">ArrowFunctionExpr</a> (also a subclass of
|
||
<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>), respectively. All three are subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Functions.qll/type.Functions$Function.html">Function</a>, which provides common member predicates for accessing function parameters or the function body:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Function.getId()</span></code> returns the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Identifier.html">Identifier</a> naming the function, which may not be defined for function expressions.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Function.getParameter(i)</span></code> and <code class="docutils literal notranslate"><span class="pre">Function.getAParameter()</span></code> access the <code class="docutils literal notranslate"><span class="pre">i</span></code>th parameter or any parameter, respectively; parameters are modeled by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Parameter.html">Parameter</a>, which is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$BindingPattern.html">BindingPattern</a> (see below).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Function.getBody()</span></code> returns the body of the function, which is usually a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a>, but may be an <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> for arrow function expressions and legacy <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Archive/Web/JavaScript/Expression_closures">expression closures</a>.</p></li>
|
||
</ul>
|
||
<p>As an example, here is a query that finds all expression closures:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from FunctionExpr fe
|
||
where fe.getBody() instanceof Expr
|
||
select fe, "Use arrow expressions instead of expression closures."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/668510056/">See this in the query console on LGTM.com</a>. None of the LGTM.com demo projects uses expression closures, but you may find this query gets results on other projects.</p>
|
||
<p>As another example, this query finds functions that have two parameters that bind the same variable:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from Function fun, Parameter p, Parameter q, int i, int j
|
||
where p = fun.getParameter(i) and
|
||
q = fun.getParameter(j) and
|
||
i < j and
|
||
p.getAVariable() = q.getAVariable()
|
||
select fun, "This function has two parameters that bind the same variable."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/673860037/">See this in the query console on LGTM.com</a>. None of the LGTM.com demo projects has functions where two parameters bind the same variable.</p>
|
||
</section>
|
||
<section id="classes">
|
||
<h4>Classes<a class="headerlink" href="#classes" title="Link to this heading">¶</a></h4>
|
||
<p>Classes can be defined either by class declaration statements, represented by the CodeQL class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassDeclStmt.html">ClassDeclStmt</a> (which is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a>), or by class expressions, represented by the CodeQL class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassExpr.html">ClassExpr</a> (which is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>). Both of these classes are also subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassDefinition.html">ClassDefinition</a>, which provides common member predicates for accessing the name of a class, its superclass, and its body:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getIdentifier()</span></code> returns the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Identifier.html">Identifier</a> naming the function, which may not be defined for class expressions.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getSuperClass()</span></code> returns the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> specifying the superclass, which may not be defined.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getMember(n)</span></code> returns the definition of member <code class="docutils literal notranslate"><span class="pre">n</span></code> of this class.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getMethod(n)</span></code> restricts <code class="docutils literal notranslate"><span class="pre">ClassDefinition.getMember(n)</span></code> to methods (as opposed to fields).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getField(n)</span></code> restricts <code class="docutils literal notranslate"><span class="pre">ClassDefinition.getMember(n)</span></code> to fields (as opposed to methods).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ClassDefinition.getConstructor()</span></code> gets the constructor of this class, possibly a synthetic default constructor.</p></li>
|
||
</ul>
|
||
<p>Note that class fields are not a standard language feature yet, so details of their representation may change.</p>
|
||
<p>Method definitions are represented by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$MethodDefinition.html">MethodDefinition</a>, which (like its counterpart <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$FieldDefinition.html">FieldDefinition</a> for fields) is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$MemberDefinition.html">MemberDefinition</a>. That class provides the following important member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MemberDefinition.isStatic()</span></code>: holds if this is a static member.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MemberDefinition.isComputed()</span></code>: holds if the name of this member is computed at runtime.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MemberDefinition.getName()</span></code>: gets the name of this member if it can be determined statically.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MemberDefinition.getInit()</span></code>: gets the initializer of this field; for methods, the initializer is a function expressions, for fields it may be an arbitrary expression, and may be undefined.</p></li>
|
||
</ul>
|
||
<p>There are three classes for modeling special methods: <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ConstructorDefinition.html">ConstructorDefinition</a> models constructors, while <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$GetterMethodDefinition.html">GetterMethodDefinition</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$SetterMethodDefinition.html">SetterMethodDefinition</a> model getter and setter methods, respectively.</p>
|
||
</section>
|
||
<section id="declarations-and-binding-patterns">
|
||
<h4>Declarations and binding patterns<a class="headerlink" href="#declarations-and-binding-patterns" title="Link to this heading">¶</a></h4>
|
||
<p>Variables are declared by declaration statements (class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$DeclStmt.html">DeclStmt</a>), which come in three flavors: <code class="docutils literal notranslate"><span class="pre">var</span></code> statements (represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$VarDeclStmt.html">VarDeclStmt</a>), <code class="docutils literal notranslate"><span class="pre">const</span></code> statements (represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$ConstDeclStmt.html">ConstDeclStmt</a>), and <code class="docutils literal notranslate"><span class="pre">let</span></code> statements (represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$LetStmt.html">LetStmt</a>). Every declaration statement has one or more declarators, represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VariableDeclarator.html">VariableDeclarator</a>.</p>
|
||
<p>Each declarator consists of a binding pattern, returned by predicate <code class="docutils literal notranslate"><span class="pre">VariableDeclarator.getBindingPattern()</span></code>, and an optional initializing expression, returned by <code class="docutils literal notranslate"><span class="pre">VariableDeclarator.getInit()</span></code>.</p>
|
||
<p>Often, the binding pattern is a simple identifier, as in <code class="docutils literal notranslate"><span class="pre">var</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">42</span></code>. In ECMAScript 2015 and later, however, it can also be a more complex destructuring pattern, as in <code class="docutils literal notranslate"><span class="pre">var</span> <span class="pre">[x,</span> <span class="pre">y]</span> <span class="pre">=</span> <span class="pre">arr</span></code>.</p>
|
||
<p>The various kinds of binding patterns are represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$BindingPattern.html">BindingPattern</a> and its subclasses:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarRef.html">VarRef</a>: a simple identifier in an l-value position, for example the <code class="docutils literal notranslate"><span class="pre">x</span></code> in <code class="docutils literal notranslate"><span class="pre">var</span> <span class="pre">x</span></code> or in <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">42</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Parameter.html">Parameter</a>: a function or catch clause parameter</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$ArrayPattern.html">ArrayPattern</a>: an array pattern, for example, the left-hand side of <code class="docutils literal notranslate"><span class="pre">[x,</span> <span class="pre">y]</span> <span class="pre">=</span> <span class="pre">arr</span></code></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$ObjectPattern.html">ObjectPattern</a>: an object pattern, for example, the left-hand side of <code class="docutils literal notranslate"><span class="pre">{x,</span> <span class="pre">y:</span> <span class="pre">z}</span> <span class="pre">=</span> <span class="pre">o</span></code></p></li>
|
||
</ul>
|
||
<p>Here is an example of a query to find declaration statements that declare the same variable more than once, excluding results in minified code:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from DeclStmt ds, VariableDeclarator d1, VariableDeclarator d2, Variable v, int i, int j
|
||
where d1 = ds.getDecl(i) and
|
||
d2 = ds.getDecl(j) and
|
||
i < j and
|
||
v = d1.getBindingPattern().getAVariable() and
|
||
v = d2.getBindingPattern().getAVariable() and
|
||
not ds.getTopLevel().isMinified()
|
||
select ds, "Variable " + v.getName() + " is declared both $@ and $@.", d1, "here", d2, "here"
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/668700496/">See this in the query console on LGTM.com</a>. This is not a common problem, so you may not find any results in your own projects. The <em>angular/angular.js</em> project on LGTM.com has one instance of this problem at the time of writing.</p>
|
||
<blockquote>
|
||
<div><p>Notice the use of <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">...</span> <span class="pre">isMinified()</span></code> here and in the next few queries. This excludes any results found in minified code. If you delete <code class="docutils literal notranslate"><span class="pre">and</span> <span class="pre">not</span> <span class="pre">ds.getTopLevel().isMinified()</span></code> and re-run the query, two results in minified code in the <em>meteor/meteor</em> project are reported.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
<section id="properties">
|
||
<h4>Properties<a class="headerlink" href="#properties" title="Link to this heading">¶</a></h4>
|
||
<p>Properties in object literals are represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Property.html">Property</a>, which is also a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ASTNode.html">ASTNode</a>, but neither of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> nor of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a>.</p>
|
||
<p>Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Property.html">Property</a> has two subclasses <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$ValueProperty.html">ValueProperty</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropertyAccessor.html">PropertyAccessor</a>, which represent, respectively, normal value properties and getter/setter properties. Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropertyAccessor.html">PropertyAccessor</a>, in turn, has two subclasses <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropertyGetter.html">PropertyGetter</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropertySetter.html">PropertySetter</a> representing getters and setters, respectively.</p>
|
||
<p>The predicates <code class="docutils literal notranslate"><span class="pre">Property.getName()</span></code> and <code class="docutils literal notranslate"><span class="pre">Property.getInit()</span></code> provide access to the defined property’s name and its initial value. For <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$PropertyAccessor.html">PropertyAccessor</a> and its subclasses, <code class="docutils literal notranslate"><span class="pre">getInit()</span></code> is overloaded to return the getter/setter function.</p>
|
||
<p>As an example of a query involving properties, consider the following query that flags object expressions containing two identically named properties, excluding results in minified code:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from ObjectExpr oe, Property p1, Property p2, int i, int j
|
||
where p1 = oe.getProperty(i) and
|
||
p2 = oe.getProperty(j) and
|
||
i < j and
|
||
p1.getName() = p2.getName() and
|
||
not oe.getTopLevel().isMinified()
|
||
select oe, "Property " + p1.getName() + " is defined both $@ and $@.", p1, "here", p2, "here"
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/660700064/">See this in the query console on LGTM.com</a>. Many projects have a few instances of object expressions with two identically named properties.</p>
|
||
</section>
|
||
<section id="modules">
|
||
<h4>Modules<a class="headerlink" href="#modules" title="Link to this heading">¶</a></h4>
|
||
<p>The JavaScript library has support for working with ECMAScript 2015 modules, as well as legacy CommonJS modules (still commonly employed by Node.js code bases) and AMD-style modules. The classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/ES2015Modules.qll/type.ES2015Modules$ES2015Module.html">ES2015Module</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$NodeModule.html">NodeModule</a>, and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AMD.qll/type.AMD$AmdModule.html">AMDModule</a> represent these three types of modules, and all three extend the common superclass <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Modules.qll/type.Modules$Module.html">Module</a>.</p>
|
||
<p>The most important member predicates defined by <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Modules.qll/type.Modules$Module.html">Module</a> are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Module.getName()</span></code>: gets the name of the module, which is just the stem (that is, the basename without extension) of the enclosing file.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Module.getAnImportedModule()</span></code>: gets another module that is imported (through <code class="docutils literal notranslate"><span class="pre">import</span></code> or <code class="docutils literal notranslate"><span class="pre">require</span></code>) by this module.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Module.getAnExportedSymbol()</span></code>: gets the name of a symbol that this module exports.</p></li>
|
||
</ul>
|
||
<p>Moreover, there is a class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Modules.qll/type.Modules$Import.html">Import</a> that models both ECMAScript 2015-style <code class="docutils literal notranslate"><span class="pre">import</span></code> declarations and CommonJS/AMD-style <code class="docutils literal notranslate"><span class="pre">require</span></code> calls; its member predicate <code class="docutils literal notranslate"><span class="pre">Import.getImportedModule</span></code> provides access to the module the import refers to, if it can be determined statically.</p>
|
||
</section>
|
||
</section>
|
||
<section id="name-binding">
|
||
<h3>Name binding<a class="headerlink" href="#name-binding" title="Link to this heading">¶</a></h3>
|
||
<p>Name binding is modeled in the JavaScript libraries using four concepts: <em>scopes</em>, <em>variables</em>, <em>variable declarations</em>, and <em>variable accesses</em>, represented by the classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Scope.html">Scope</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Variable.html">Variable</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarDecl.html">VarDecl</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarAccess.html">VarAccess</a>, respectively.</p>
|
||
<section id="scopes">
|
||
<h4>Scopes<a class="headerlink" href="#scopes" title="Link to this heading">¶</a></h4>
|
||
<p>In ECMAScript 5, there are three kinds of scopes: the global scope (one per program), function scopes (one per function), and catch clause scopes (one per <code class="docutils literal notranslate"><span class="pre">catch</span></code> clause). These three kinds of scopes are represented by the classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$GlobalScope.html">GlobalScope</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$FunctionScope.html">FunctionScope</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$CatchScope.html">CatchScope</a>. ECMAScript 2015 adds block scopes for <code class="docutils literal notranslate"><span class="pre">let</span></code>-bound variables, which are also represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Scope.html">Scope</a>, class expression scopes (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Classes.qll/type.Classes$ClassExprScope.html">ClassExprScope</a>),
|
||
and module scopes (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$ModuleScope.html">ModuleScope</a>).</p>
|
||
<p>Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Scope.html">Scope</a> provides the following API:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Scope.getScopeElement()</span></code> returns the AST node inducing this scope; undefined for <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$GlobalScope.html">GlobalScope</a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Scope.getOuterScope()</span></code> returns the lexically enclosing scope of this scope.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Scope.getAnInnerScope()</span></code> returns a scope lexically nested inside this scope.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Scope.getVariable(name)</span></code>, <code class="docutils literal notranslate"><span class="pre">Scope.getAVariable()</span></code> return a variable declared (implicitly or explicitly) in this scope.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="variables">
|
||
<h4>Variables<a class="headerlink" href="#variables" title="Link to this heading">¶</a></h4>
|
||
<p>The <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Variable.html">Variable</a> class models all variables in a JavaScript program, including global variables, local variables, and parameters (both of functions and <code class="docutils literal notranslate"><span class="pre">catch</span></code> clauses), whether explicitly declared or not.</p>
|
||
<p>It is important not to confuse variables and their declarations: local variables may have more than one declaration, while global variables and the implicitly declared local <code class="docutils literal notranslate"><span class="pre">arguments</span></code> variable need not have a declaration at all.</p>
|
||
</section>
|
||
<section id="variable-declarations-and-accesses">
|
||
<h4>Variable declarations and accesses<a class="headerlink" href="#variable-declarations-and-accesses" title="Link to this heading">¶</a></h4>
|
||
<p>Variables may be declared by variable declarators, by function declaration statements and expressions, by class declaration statements or expressions, or by parameters of functions and <code class="docutils literal notranslate"><span class="pre">catch</span></code> clauses. While these declarations differ in their syntactic form, in each case there is an identifier naming the declared variable. We consider that identifier to be the declaration proper, and assign it the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarDecl.html">VarDecl</a>. Identifiers that reference a variable, on the other hand, are given the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarAccess.html">VarAccess</a>.</p>
|
||
<p>The most important predicates involving variables, their declarations, and their accesses are as follows:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.getName()</span></code>, <code class="docutils literal notranslate"><span class="pre">VarDecl.getName()</span></code>, <code class="docutils literal notranslate"><span class="pre">VarAccess.getName()</span></code> return the name of the variable.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.getScope()</span></code> returns the scope to which the variable belongs.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.isGlobal()</span></code>, <code class="docutils literal notranslate"><span class="pre">Variable.isLocal()</span></code>, <code class="docutils literal notranslate"><span class="pre">Variable.isParameter()</span></code> determine whether the variable is a global variable, a local variable, or a parameter variable, respectively.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.getAnAccess()</span></code> maps a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Variable.html">Variable</a> to all <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarAccess.html">VarAccess</a>es that refer to it.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.getADeclaration()</span></code> maps a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$Variable.html">Variable</a> to all <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Variables.qll/type.Variables$VarDecl.html">VarDecl</a>s that declare it (of which there may be none, one, or more than one).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">Variable.isCaptured()</span></code> determines whether the variable is ever accessed in a scope that is lexically nested within the scope where it is declared.</p></li>
|
||
</ul>
|
||
<p>As an example, consider the following query which finds distinct function declarations that declare the same variable, that is, two conflicting function declarations within the same scope (again excluding minified code):</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from FunctionDeclStmt f, FunctionDeclStmt g
|
||
where f != g and f.getVariable() = g.getVariable() and
|
||
not f.getTopLevel().isMinified() and
|
||
not g.getTopLevel().isMinified()
|
||
select f, g
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/667290067/">See this in the query console on LGTM.com</a>. Some projects declare conflicting functions of the same name and rely on platform-specific behavior to disambiguate the two declarations.</p>
|
||
</section>
|
||
</section>
|
||
<section id="control-flow">
|
||
<h3>Control flow<a class="headerlink" href="#control-flow" title="Link to this heading">¶</a></h3>
|
||
<p>A different program representation in terms of intraprocedural control flow graphs (CFGs) is provided by the classes in library <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/module.CFG.html">CFG.qll</a>.</p>
|
||
<p>Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a> represents a single node in the control flow graph, which is either an expression, a statement, or a synthetic control flow node. Note that <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Stmt.qll/type.Stmt$Stmt.html">Stmt</a> do not inherit from <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a> at the CodeQL level, although their entity types are compatible, so you can explicitly cast from one to the other if you need to map between the AST-based and the CFG-based program representations.</p>
|
||
<p>There are two kinds of synthetic control flow nodes: entry nodes (class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowEntryNode.html">ControlFlowEntryNode</a>), which represent the beginning of a top-level or function, and exit nodes (class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowExitNode.html">ControlFlowExitNode</a>), which represent their end. They do not correspond to any AST nodes, but simply serve as the unique entry point and exit point of a control flow graph. Entry and exit nodes can be accessed through the predicates <code class="docutils literal notranslate"><span class="pre">StmtContainer.getEntry()</span></code> and <code class="docutils literal notranslate"><span class="pre">StmtContainer.getExit()</span></code>.</p>
|
||
<p>Most, but not all, top-levels and functions have another distinguished CFG node, the <em>start node</em>. This is the CFG node at which execution begins. Unlike the entry node, which is a synthetic construct, the start node corresponds to an actual program element: for top-levels, it is the first CFG node of the first statement; for functions, it is the CFG node corresponding to their first parameter or, if there are no parameters, the first CFG node of the body. Empty top-levels do not have a start node.</p>
|
||
<p>For most purposes, using start nodes is preferable to using entry nodes.</p>
|
||
<p>The structure of the control flow graph is reflected in the member predicates of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a>:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ControlFlowNode.getASuccessor()</span></code> returns a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a> that is a successor of this <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a> in the control flow graph.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ControlFlowNode.getAPredecessor()</span></code> is the inverse of <code class="docutils literal notranslate"><span class="pre">getASuccessor()</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ControlFlowNode.isBranch()</span></code> determines whether this node has more than one successor.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ControlFlowNode.isJoin()</span></code> determines whether this node has more than one predecessor.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ControlFlowNode.isStart()</span></code> determines whether this node is a start node.</p></li>
|
||
</ul>
|
||
<p>Many control-flow-based analyses are phrased in terms of <a class="reference external" href="https://en.wikipedia.org/wiki/Basic_block">basic blocks</a> rather than single control flow nodes, where a basic block is a maximal sequence of control flow nodes without branches or joins. The class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/BasicBlocks.qll/type.BasicBlocks$BasicBlock.html">BasicBlock</a> from <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/BasicBlocks.qll/module.BasicBlocks.html">BasicBlocks.qll</a> represents all such basic blocks. Similar to <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/CFG.qll/type.CFG$ControlFlowNode.html">ControlFlowNode</a>, it provides member predicates <code class="docutils literal notranslate"><span class="pre">getASuccessor()</span></code> and <code class="docutils literal notranslate"><span class="pre">getAPredecessor()</span></code> to navigate the control flow graph at the level of basic blocks, and member predicates <code class="docutils literal notranslate"><span class="pre">getANode()</span></code>, <code class="docutils literal notranslate"><span class="pre">getNode(int)</span></code>, <code class="docutils literal notranslate"><span class="pre">getFirstNode()</span></code> and <code class="docutils literal notranslate"><span class="pre">getLastNode()</span></code> to access individual control flow nodes within a basic block. The predicate
|
||
<code class="docutils literal notranslate"><span class="pre">Function.getEntryBB()</span></code> returns the entry basic block in a function, that is, the basic block containing the function’s entry node. Similarly, <code class="docutils literal notranslate"><span class="pre">Function.getStartBB()</span></code> provides access to the start basic block, which contains the function’s start node. As for CFG nodes, <code class="docutils literal notranslate"><span class="pre">getStartBB()</span></code> should normally be preferred over <code class="docutils literal notranslate"><span class="pre">getEntryBB()</span></code>.</p>
|
||
<p>As an example of an analysis using basic blocks, <code class="docutils literal notranslate"><span class="pre">BasicBlock.isLiveAtEntry(v,</span> <span class="pre">u)</span></code> determines whether variable <code class="docutils literal notranslate"><span class="pre">v</span></code> is <a class="reference external" href="https://en.wikipedia.org/wiki/Live_variable_analysis">live</a> at the entry of the given basic block, and if so binds <code class="docutils literal notranslate"><span class="pre">u</span></code> to a use of <code class="docutils literal notranslate"><span class="pre">v</span></code> that refers to its value at the entry. We can use it to find global variables that are used in a function where they are not live (that is, every read of the variable is preceded by a write), suggesting that the variable was meant to be declared as a local variable instead:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from Function f, GlobalVariable gv
|
||
where gv.getAnAccess().getEnclosingFunction() = f and
|
||
not f.getStartBB().isLiveAtEntry(gv, _)
|
||
select f, "This function uses " + gv + " like a local variable."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/686320048/">See this in the query console on LGTM.com</a>. Many projects have some variables which look as if they were intended to be local.</p>
|
||
</section>
|
||
<section id="data-flow">
|
||
<h3>Data flow<a class="headerlink" href="#data-flow" title="Link to this heading">¶</a></h3>
|
||
<section id="definitions-and-uses">
|
||
<h4>Definitions and uses<a class="headerlink" href="#definitions-and-uses" title="Link to this heading">¶</a></h4>
|
||
<p>Library <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/DefUse.qll/module.DefUse.html">DefUse.qll</a> provides classes and predicates to determine <a class="reference external" href="https://en.wikipedia.org/wiki/Use-define_chain">def-use</a> relationships between definitions and uses of variables.</p>
|
||
<p>Classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/DefUse.qll/type.DefUse$VarDef.html">VarDef</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/DefUse.qll/type.DefUse$VarUse.html">VarUse</a> contain all expressions that define and use a variable, respectively. For the former, you can use predicate <code class="docutils literal notranslate"><span class="pre">VarDef.getAVariable()</span></code> to find out which variables are defined by a given variable definition (recall that destructuring assignments in ECMAScript 2015 define several variables at the same time). Similarly, predicate <code class="docutils literal notranslate"><span class="pre">VarUse.getVariable()</span></code> returns the (single) variable being accessed by a variable use.</p>
|
||
<p>The def-use information itself is provided by predicate <code class="docutils literal notranslate"><span class="pre">VarUse.getADef()</span></code>, that connects a use of a variable to a definition of the same variable, where the definition may reach the use.</p>
|
||
<p>As an example, the following query finds definitions of local variables that are not used anywhere; that is, the variable is either not referenced at all after the definition, or its value is overwritten:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from VarDef def, LocalVariable v
|
||
where v = def.getAVariable() and
|
||
not exists (VarUse use | def = use.getADef())
|
||
select def, "Dead store of local variable."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/2086440429/">See this in the query console on LGTM.com</a>. Many projects have some examples of useless assignments to local variables.</p>
|
||
</section>
|
||
<section id="ssa">
|
||
<h4>SSA<a class="headerlink" href="#ssa" title="Link to this heading">¶</a></h4>
|
||
<p>A more fine-grained representation of a program’s data flow based on <a class="reference external" href="https://en.wikipedia.org/wiki/Static_single_assignment_form">Static Simple Assignment Form (SSA)</a> is provided by the library <code class="docutils literal notranslate"><span class="pre">semmle.javascript.SSA</span></code>.</p>
|
||
<p>In SSA form, each use of a local variable has exactly one (SSA) definition that reaches it. SSA definitions are represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaDefinition.html">SsaDefinition</a>. They are not AST nodes, since not every SSA definition corresponds to an explicit element in the source code.</p>
|
||
<p>Altogether, there are five kinds of SSA definitions:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Explicit definitions (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaExplicitDefinition.html">SsaExplicitDefinition</a>): these simply wrap a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/DefUse.qll/type.DefUse$VarDef.html">VarDef</a>, that is, a definition like <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">1</span></code> appearing explicitly in the source code.</p></li>
|
||
<li><p>Implicit initializations (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaImplicitInit.html">SsaImplicitInit</a>): these represent the implicit initialization of local variables with <code class="docutils literal notranslate"><span class="pre">undefined</span></code> at the beginning of their scope.</p></li>
|
||
<li><p>Phi nodes (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaPhiNode.html">SsaPhiNode</a>): these are pseudo-definitions that merge two or more SSA definitions where necessary; see the Wikipedia page linked to above for an explanation.</p></li>
|
||
<li><p>Variable captures (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaVariableCapture.html">SsaVariableCapture</a>): these are pseudo-definitions appearing at places in the code where the value of a captured variable may change without there being an explicit assignment, for example due to a function call.</p></li>
|
||
<li><p>Refinement nodes (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/SSA.qll/type.SSA$SsaRefinementNode.html">SsaRefinementNode</a>): these are pseudo-definitions appearing at places in the code where something becomes known about a variable; for example, a conditional <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">(x</span> <span class="pre">===</span> <span class="pre">null)</span></code> induces a refinement node at the beginning of its “then” branch recording the fact that <code class="docutils literal notranslate"><span class="pre">x</span></code> is known to be <code class="docutils literal notranslate"><span class="pre">null</span></code> there. (In the literature, these are sometimes known as “pi nodes.”)</p></li>
|
||
</ol>
|
||
</section>
|
||
<section id="data-flow-nodes">
|
||
<h4>Data flow nodes<a class="headerlink" href="#data-flow-nodes" title="Link to this heading">¶</a></h4>
|
||
<p>Moving beyond just variable definitions and uses, library <code class="docutils literal notranslate"><span class="pre">semmle.javascript.dataflow.DataFlow</span></code> provides a representation of the program as a data flow graph. Its nodes are values of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/DataFlow.qll/type.DataFlow$DataFlow$Node.html">DataFlow::Node</a>, which has two subclasses <code class="docutils literal notranslate"><span class="pre">ValueNode</span></code> and <code class="docutils literal notranslate"><span class="pre">SsaDefinitionNode</span></code>. Nodes of the former kind wrap an expression or a statement that is considered to produce a value (specifically, a function or class declaration statement, or a TypeScript namespace or enum declaration). Nodes of the latter kind wrap SSA definitions.</p>
|
||
<p>You can use the predicate <code class="docutils literal notranslate"><span class="pre">DataFlow::valueNode</span></code> to convert an expression, function or class into its corresponding <code class="docutils literal notranslate"><span class="pre">ValueNode</span></code>, and similarly <code class="docutils literal notranslate"><span class="pre">DataFlow::ssaDefinitionNode</span></code> to map an SSA definition to its corresponding <code class="docutils literal notranslate"><span class="pre">SsaDefinitionNode</span></code>.</p>
|
||
<p>There is also an auxiliary predicate <code class="docutils literal notranslate"><span class="pre">DataFlow::parameterNode</span></code> that maps a parameter to its corresponding data flow node. (This is really just a convenience wrapper around <code class="docutils literal notranslate"><span class="pre">DataFlow::ssaDefinitionNode</span></code>, since parameters are also considered to be SSA definitions.)</p>
|
||
<p>Going in the other direction, there is a predicate <code class="docutils literal notranslate"><span class="pre">ValueNode.getAstNode()</span></code> for mapping from <code class="docutils literal notranslate"><span class="pre">ValueNode</span></code>s to <code class="docutils literal notranslate"><span class="pre">ASTNode</span></code>s, and <code class="docutils literal notranslate"><span class="pre">SsaDefinitionNode.getSsaVariable()</span></code> for mapping from <code class="docutils literal notranslate"><span class="pre">SsaDefinitionNode</span></code>s to <code class="docutils literal notranslate"><span class="pre">SsaVariable</span></code>s. There is also a utility predicate <code class="docutils literal notranslate"><span class="pre">Node.asExpr()</span></code> that gets the underlying expression for a <code class="docutils literal notranslate"><span class="pre">ValueNode</span></code>, and is undefined for all nodes that do not correspond to an expression. (Note in particular that this predicate is not defined for <code class="docutils literal notranslate"><span class="pre">ValueNode</span></code>s wrapping function or class declaration statements!)</p>
|
||
<p>You can use the predicate <code class="docutils literal notranslate"><span class="pre">DataFlow::Node.getAPredecessor()</span></code> to find other data flow nodes from which values may flow into this node, and <code class="docutils literal notranslate"><span class="pre">getASuccessor</span></code> for the other direction.</p>
|
||
<p>For example, here is a query that finds all invocations of a method called <code class="docutils literal notranslate"><span class="pre">send</span></code> on a value that comes from a parameter named <code class="docutils literal notranslate"><span class="pre">res</span></code>, indicating that it is perhaps sending an HTTP response:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from SimpleParameter res, DataFlow::Node resNode, MethodCallExpr send
|
||
where res.getName() = "res" and
|
||
resNode = DataFlow::parameterNode(res) and
|
||
resNode.getASuccessor+() = DataFlow::valueNode(send.getReceiver()) and
|
||
send.getMethodName() = "send"
|
||
select send
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/1506058347056/">See this in the query console on LGTM.com</a>. The query finds HTTP response sends in the <a class="reference external" href="https://lgtm.com/projects/g/ampproject/amphtml">AMP HTML</a> project.</p>
|
||
<p>Note that the data flow modeling in this library is intraprocedural, that is, flow across function calls and returns is <em>not</em> modeled. Likewise, flow through object properties and global variables is not modeled.</p>
|
||
</section>
|
||
</section>
|
||
<section id="type-inference">
|
||
<h3>Type inference<a class="headerlink" href="#type-inference" title="Link to this heading">¶</a></h3>
|
||
<p>The library <code class="docutils literal notranslate"><span class="pre">semmle.javascript.dataflow.TypeInference</span></code> implements a simple type inference for JavaScript based on intraprocedural, heap-insensitive flow analysis. Basically, the inference algorithm approximates the possible concrete runtime values of variables and expressions as sets of abstract values (represented by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/AbstractValues.qll/type.AbstractValues$AbstractValue.html">AbstractValue</a>), each of which stands for a set of concrete values.</p>
|
||
<p>For example, there is an abstract value representing all non-zero numbers, and another representing all non-empty strings except for those that can be converted to a number. Both of these abstract values are fairly coarse approximations that represent very large sets of concrete values.</p>
|
||
<p>Other abstract values are more precise, to the point where they represent single concrete values: for example, there is an abstract value representing the concrete <code class="docutils literal notranslate"><span class="pre">null</span></code> value, and another representing the number zero.</p>
|
||
<p>There is a special group of abstract values called <em>indefinite</em> abstract values that represent all concrete values. The analysis uses these to handle expressions for which it cannot infer a more precise value, such as function parameters (as mentioned above, the analysis is intraprocedural and hence does not model argument passing) or property reads (the analysis does not model property values either).</p>
|
||
<p>Each indefinite abstract value is associated with a string value describing the cause of imprecision. In the above examples, the indefinite value for the parameter would have cause <code class="docutils literal notranslate"><span class="pre">"call"</span></code>, while the indefinite value for the property would have cause <code class="docutils literal notranslate"><span class="pre">"heap"</span></code>.</p>
|
||
<p>To check whether an abstract value is indefinite, you can use the <code class="docutils literal notranslate"><span class="pre">isIndefinite</span></code> member predicate. Its single argument describes the cause of imprecision.</p>
|
||
<p>Each abstract value has one or more associated types (CodeQL class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/InferredTypes.qll/type.InferredTypes$InferredType.html">InferredType</a> corresponding roughly to the type tags computed by the <code class="docutils literal notranslate"><span class="pre">typeof</span></code> operator. The types are <code class="docutils literal notranslate"><span class="pre">null</span></code>, <code class="docutils literal notranslate"><span class="pre">undefined</span></code>, <code class="docutils literal notranslate"><span class="pre">boolean</span></code>, <code class="docutils literal notranslate"><span class="pre">number</span></code>, <code class="docutils literal notranslate"><span class="pre">string</span></code>, <code class="docutils literal notranslate"><span class="pre">function</span></code>, <code class="docutils literal notranslate"><span class="pre">class</span></code>, <code class="docutils literal notranslate"><span class="pre">date</span></code> and <code class="docutils literal notranslate"><span class="pre">object</span></code>.</p>
|
||
<p>To access the results of the type inference, use class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/TypeInference.qll/type.TypeInference$AnalyzedNode.html">DataFlow::AnalyzedNode</a>: any <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/DataFlow.qll/type.DataFlow$DataFlow$Node.html">DataFlow::Node</a> can be cast to this class, and additionally there is a convenience predicate <code class="docutils literal notranslate"><span class="pre">Expr::analyze</span></code> that maps expressions directly to their corresponding <code class="docutils literal notranslate"><span class="pre">AnalyzedNode</span></code>s.</p>
|
||
<p>Once you have an <code class="docutils literal notranslate"><span class="pre">AnalyzedNode</span></code>, you can use predicate <code class="docutils literal notranslate"><span class="pre">AnalyzedNode.getAValue()</span></code> to access the abstract values inferred for it, and <code class="docutils literal notranslate"><span class="pre">getAType()</span></code> to get the inferred types.</p>
|
||
<p>For example, here is a query that looks for <code class="docutils literal notranslate"><span class="pre">null</span></code> checks on expressions that cannot, in fact, be null:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from StrictEqualityTest eq, DataFlow::AnalyzedNode nd, NullLiteral null
|
||
where eq.hasOperands(nd.asExpr(), null) and
|
||
not nd.getAValue().isIndefinite(_) and
|
||
not nd.getAValue() instanceof AbstractNull
|
||
select eq, "Spurious null check."
|
||
</pre></div>
|
||
</div>
|
||
<p>To paraphrase, the query looks for equality tests <code class="docutils literal notranslate"><span class="pre">eq</span></code> where one operand is a <code class="docutils literal notranslate"><span class="pre">null</span></code> literal and the other some expression that we convert to an <code class="docutils literal notranslate"><span class="pre">AnalyzedNode</span></code>. If the type inference results for that node are precise (that is, none of the inferred values is indefinite) and (the abstract representation of) <code class="docutils literal notranslate"><span class="pre">null</span></code> is not among them, we flag <code class="docutils literal notranslate"><span class="pre">eq</span></code>.</p>
|
||
<p>You can add custom type inference rules by defining new subclasses of <code class="docutils literal notranslate"><span class="pre">DataFlow::AnalyzedNode</span></code> and overriding <code class="docutils literal notranslate"><span class="pre">getAValue</span></code>. You can also introduce new abstract values by extending the abstract class <code class="docutils literal notranslate"><span class="pre">CustomAbstractValueTag</span></code>, which is a subclass of <code class="docutils literal notranslate"><span class="pre">string</span></code>: each string belonging to that class induces a corresponding abstract value of type <code class="docutils literal notranslate"><span class="pre">CustomAbstractValue</span></code>. You can use the predicate <code class="docutils literal notranslate"><span class="pre">CustomAbstractValue.getTag()</span></code> to map from the abstract value to its tag. By implementing the abstract predicates of class <code class="docutils literal notranslate"><span class="pre">CustomAbstractValueTag</span></code> you can define the semantics of your custom abstract values, such as what primitive value they coerce to and what type they have.</p>
|
||
</section>
|
||
<section id="call-graph">
|
||
<h3>Call graph<a class="headerlink" href="#call-graph" title="Link to this heading">¶</a></h3>
|
||
<p>The JavaScript library implements a simple <a class="reference external" href="https://en.wikipedia.org/wiki/Call_graph">call graph</a> construction algorithm to statically approximate the possible call targets of function calls and <code class="docutils literal notranslate"><span class="pre">new</span></code> expressions. Due to the dynamically typed nature of JavaScript and its support for higher-order functions and reflective language features, building static call graphs is quite difficult. Simple call graph algorithms tend to be incomplete, that is, they often fail to resolve all possible call targets. More sophisticated algorithms can suffer from the opposite problem of imprecision, that is, they may infer many spurious call targets.</p>
|
||
<p>The call graph is represented by the member predicate <code class="docutils literal notranslate"><span class="pre">getACallee()</span></code> of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/dataflow/Nodes.qll/type.Nodes$InvokeNode.html">DataFlow::InvokeNode</a>, which computes possible callees of the given invocation, that is, functions that may at runtime be invoked by this expression.</p>
|
||
<p>Furthermore, there are three member predicates that indicate the quality of the callee information for this invocation:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::InvokeNode.isImprecise()</span></code>: holds for invocations where the call graph builder might infer spurious call targets.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::InvokeNode.isIncomplete()</span></code>: holds for invocations where the call graph builder might fail to infer possible call targets.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">DataFlow::InvokeNode.isUncertain()</span></code>: holds if either <code class="docutils literal notranslate"><span class="pre">isImprecise()</span></code> or <code class="docutils literal notranslate"><span class="pre">isIncomplete()</span></code> holds.</p></li>
|
||
</ul>
|
||
<p>As an example of a call-graph-based query, here is a query to find invocations for which the call graph builder could not find any callees, despite the analysis being complete for this invocation:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from DataFlow::InvokeNode invk
|
||
where not invk.isIncomplete() and
|
||
not exists(invk.getACallee())
|
||
select invk, "Unable to find a callee for this invocation."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/3260345690335671362/">See this in the query console on LGTM.com</a></p>
|
||
</section>
|
||
<section id="inter-procedural-data-flow">
|
||
<h3>Inter-procedural data flow<a class="headerlink" href="#inter-procedural-data-flow" title="Link to this heading">¶</a></h3>
|
||
<p>The data flow graph-based analyses described so far are all intraprocedural: they do not take flow from function arguments to parameters or from a <code class="docutils literal notranslate"><span class="pre">return</span></code> to the function’s caller into account. The data flow library also provides a framework for constructing custom inter-procedural analyses.</p>
|
||
<p>We distinguish here between data flow proper, and <em>taint tracking</em>: the latter not only considers value-preserving flow (such as from variable definitions to uses), but also cases where one value influences (“taints”) another without determining it entirely. For example, in the assignment <code class="docutils literal notranslate"><span class="pre">s2</span> <span class="pre">=</span> <span class="pre">s1.substring(i)</span></code>, the value of <code class="docutils literal notranslate"><span class="pre">s1</span></code> influences the value of <code class="docutils literal notranslate"><span class="pre">s2</span></code>, because <code class="docutils literal notranslate"><span class="pre">s2</span></code> is assigned a substring of <code class="docutils literal notranslate"><span class="pre">s1</span></code>. In general, <code class="docutils literal notranslate"><span class="pre">s2</span></code> will not be assigned <code class="docutils literal notranslate"><span class="pre">s1</span></code> itself, so there is no data flow from <code class="docutils literal notranslate"><span class="pre">s1</span></code> to <code class="docutils literal notranslate"><span class="pre">s2</span></code>, but <code class="docutils literal notranslate"><span class="pre">s1</span></code> still taints <code class="docutils literal notranslate"><span class="pre">s2</span></code>.</p>
|
||
<p>The simplest way of implementing an interprocedural data flow analysis is to extend either class <code class="docutils literal notranslate"><span class="pre">DataFlow::TrackedNode</span></code> or <code class="docutils literal notranslate"><span class="pre">DataFlow::TrackedExpr</span></code>. The former is a subclass of <code class="docutils literal notranslate"><span class="pre">DataFlow::Node</span></code>, the latter of <code class="docutils literal notranslate"><span class="pre">Expr</span></code>, and extending them ensures that the newly added values are tracked interprocedurally. You can use the predicate <code class="docutils literal notranslate"><span class="pre">flowsTo</span></code> to find out which nodes/expressions the tracked value flows to.</p>
|
||
<p>For example, suppose that we are developing an analysis to find hard-coded passwords. We might start by writing a simple query that looks for string constants flowing into variables named <code class="docutils literal notranslate"><span class="pre">"password"</span></code>. To do this, we can extend <code class="docutils literal notranslate"><span class="pre">TrackedExpr</span></code> to track all constant strings, <code class="docutils literal notranslate"><span class="pre">flowsTo</span></code> to find cases where such a string flows into a (SSA) definition of a password variable:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
class TrackedStringLiteral extends DataFlow::TrackedNode {
|
||
TrackedStringLiteral() {
|
||
this.asExpr() instanceof ConstantString
|
||
}
|
||
}
|
||
|
||
from TrackedStringLiteral source, DataFlow::Node sink, SsaExplicitDefinition def
|
||
where source.flowsTo(sink) and sink = DataFlow::ssaDefinitionNode(def) and
|
||
def.getSourceVariable().getName().toLowerCase() = "password"
|
||
select sink
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that <code class="docutils literal notranslate"><span class="pre">TrackedNode</span></code> and <code class="docutils literal notranslate"><span class="pre">TrackedExpr</span></code> do not restrict the set of “sinks” for the inter-procedural flow analysis, tracking flow into any expression that they might flow to. This can be expensive for large code bases, and is often unnecessary, since usually you are only interested in flow to a particular set of sinks. For example, the above query only looks for flow into assignments to password variables.</p>
|
||
<p>This is a particular instance of a general pattern, whereby we want to specify a data flow or taint analysis in terms of its <em>sources</em> (where flow starts), <em>sinks</em> (where it should be tracked), and <em>barriers</em> or <em>sanitizers</em> (where flow is interrupted). The example does not include any sanitizers, but they are very common in security analyses: for example, an analysis that tracks the flow of untrusted user input into, say, a SQL query has to keep track of code that validates the input, thereby making it safe to use. Such a validation step is an example of a sanitizer.</p>
|
||
<p>The classes <code class="docutils literal notranslate"><span class="pre">DataFlow::Configuration</span></code> and <code class="docutils literal notranslate"><span class="pre">TaintTracking::Configuration</span></code> allow specifying a data flow or taint analysis, respectively, by overriding the following predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">isSource(DataFlow::Node</span> <span class="pre">nd)</span></code> selects all nodes <code class="docutils literal notranslate"><span class="pre">nd</span></code> from where flow tracking starts.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">isSink(DataFlow::Node</span> <span class="pre">nd)</span></code> selects all nodes <code class="docutils literal notranslate"><span class="pre">nd</span></code> to which the flow is tracked.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">isBarrier(DataFlow::Node</span> <span class="pre">nd)</span></code> selects all nodes <code class="docutils literal notranslate"><span class="pre">nd</span></code> that act as a barrier for data flow; <code class="docutils literal notranslate"><span class="pre">isSanitizer</span></code> is the corresponding predicate for taint tracking configurations.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">isBarrierEdge(DataFlow::Node</span> <span class="pre">src,</span> <span class="pre">DataFlow::Node</span> <span class="pre">trg)</span></code> is a variant of <code class="docutils literal notranslate"><span class="pre">isBarrier(nd)</span></code> that allows specifying barrier <em>edges</em> in addition to barrier nodes; again, <code class="docutils literal notranslate"><span class="pre">isSanitizerEdge</span></code> is the corresponding predicate for taint tracking;</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">isAdditionalFlowStep(DataFlow::Node</span> <span class="pre">src,</span> <span class="pre">DataFlow::Node</span> <span class="pre">trg)</span></code> allows specifying custom additional flow steps for this analysis; <code class="docutils literal notranslate"><span class="pre">isAdditionalTaintStep</span></code> is the corresponding predicate for taint tracking configurations.</p></li>
|
||
</ul>
|
||
<p>Since for technical reasons both <code class="docutils literal notranslate"><span class="pre">Configuration</span></code> classes are subtypes of <code class="docutils literal notranslate"><span class="pre">string</span></code>, you have to choose a unique name for each flow configuration and equate <code class="docutils literal notranslate"><span class="pre">this</span></code> with it in the characteristic predicate (as in the example below).</p>
|
||
<p>The predicate <code class="docutils literal notranslate"><span class="pre">Configuration.hasFlow</span></code> performs the actual flow tracking, starting at a source and looking for flow to a sink that does not pass through a barrier node or edge.</p>
|
||
<p>To continue with our above example, we can phrase it as a data flow configuration as follows:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>class PasswordTracker extends DataFlow::Configuration {
|
||
PasswordTracker() {
|
||
// unique identifier for this configuration
|
||
this = "PasswordTracker"
|
||
}
|
||
|
||
override predicate isSource(DataFlow::Node nd) {
|
||
nd.asExpr() instanceof StringLiteral
|
||
}
|
||
|
||
override predicate isSink(DataFlow::Node nd) {
|
||
passwordVarAssign(_, nd)
|
||
}
|
||
|
||
predicate passwordVarAssign(Variable v, DataFlow::Node nd) {
|
||
exists (SsaExplicitDefinition def |
|
||
nd = DataFlow::ssaDefinitionNode(def) and
|
||
def.getSourceVariable() = v and
|
||
v.getName().toLowerCase() = "password"
|
||
)
|
||
}
|
||
}
|
||
</pre></div>
|
||
</div>
|
||
<p>Now we can rephrase our query to use <code class="docutils literal notranslate"><span class="pre">Configuration.hasFlow</span></code>:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>from PasswordTracker pt, DataFlow::Node source, DataFlow::Node sink, Variable v
|
||
where pt.hasFlow(source, sink) and pt.passwordVarAssign(v, sink)
|
||
select sink, "Password variable " + v + " is assigned a constant string."
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that while analyses implemented in this way are inter-procedural in that they track flow and taint across function calls and returns, flow through global variables is not tracked. Flow through object properties is only tracked in limited cases, for example through properties of object literals or CommonJS <code class="docutils literal notranslate"><span class="pre">module</span></code> and <code class="docutils literal notranslate"><span class="pre">exports</span></code> objects.</p>
|
||
</section>
|
||
<section id="syntax-errors">
|
||
<h3>Syntax errors<a class="headerlink" href="#syntax-errors" title="Link to this heading">¶</a></h3>
|
||
<p>JavaScript code that contains syntax errors cannot usually be analyzed. For such code, the lexical and syntactic representations are not available, and hence no name binding information, call graph or control and data flow. All that is available in this case is a value of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html">JSParseError</a> representing the syntax error. It provides information about the syntax error location (<a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html">JSParseError</a> is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Locatable.html">Locatable</a>) and the error message through predicate <code class="docutils literal notranslate"><span class="pre">JSParseError.getMessage</span></code>.</p>
|
||
<p>Note that for some very simple syntax errors the parser can recover and continue parsing. If this happens, lexical and syntactic information is available in addition to the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Errors.qll/type.Errors$JSParseError.html">JSParseError</a> values representing the (recoverable) syntax errors encountered during parsing.</p>
|
||
</section>
|
||
<section id="frameworks">
|
||
<h3>Frameworks<a class="headerlink" href="#frameworks" title="Link to this heading">¶</a></h3>
|
||
<section id="angularjs">
|
||
<h4>AngularJS<a class="headerlink" href="#angularjs" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.frameworks.AngularJS</span></code> library provides support for working with <a class="reference external" href="https://angularjs.org/">AngularJS (Angular 1.x)</a> code. Its most important classes are:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/AngularJSCore.qll/type.AngularJSCore$AngularModule.html">AngularJS::AngularModule</a>: an Angular module</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/ServiceDefinitions.qll/type.ServiceDefinitions$DirectiveDefinition.html">AngularJS::DirectiveDefinition</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/ServiceDefinitions.qll/type.ServiceDefinitions$FactoryRecipeDefinition.html">AngularJS::FactoryRecipeDefinition</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/ServiceDefinitions.qll/type.ServiceDefinitions$FilterDefinition.html">AngularJS::FilterDefinition</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/ServiceDefinitions.qll/type.ServiceDefinitions$ControllerDefinition.html">AngularJS::ControllerDefinition</a>: a definition of a directive, service, filter or controller, respectively</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/AngularJS/DependencyInjections.qll/type.DependencyInjections$InjectableFunction.html">AngularJS::InjectableFunction</a>: a function that is subject to dependency injection</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="http-framework-libraries">
|
||
<h4>HTTP framework libraries<a class="headerlink" href="#http-framework-libraries" title="Link to this heading">¶</a></h4>
|
||
<p>The library <code class="docutils literal notranslate"><span class="pre">semmle.javacript.frameworks.HTTP</span></code> provides classes modeling common concepts from various HTTP frameworks.</p>
|
||
<p>Currently supported frameworks are <a class="reference external" href="https://expressjs.com/">Express</a>, the standard Node.js <code class="docutils literal notranslate"><span class="pre">http</span></code> and <code class="docutils literal notranslate"><span class="pre">https</span></code> modules, <a class="reference external" href="https://github.com/senchalabs/connect">Connect</a>, <a class="reference external" href="https://koajs.com">Koa</a>, <a class="reference external" href="https://hapi.dev/">Hapi</a> and <a class="reference external" href="http://restify.com/">Restify</a>.</p>
|
||
<p>The most important classes include (all in module <code class="docutils literal notranslate"><span class="pre">HTTP</span></code>):</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ServerDefinition</span></code>: an expression that creates a new HTTP server.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">RouteHandler</span></code>: a callback for handling an HTTP request.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">RequestExpr</span></code>: an expression that may contain an HTTP request object.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ResponseExpr</span></code>: an expression that may contain an HTTP response object.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">HeaderDefinition</span></code>: an expression that sets one or more HTTP response headers.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">CookieDefinition</span></code>: an expression that sets a cookie in an HTTP response.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">RequestInputAccess</span></code>: an expression that accesses user-controlled request data.</p></li>
|
||
</ul>
|
||
<p>For each framework library, there is a corresponding CodeQL library (for example <code class="docutils literal notranslate"><span class="pre">semmle.javacript.frameworks.Express</span></code>) that instantiates the above classes for that framework and adds framework-specific classes.</p>
|
||
</section>
|
||
<section id="node-js">
|
||
<h4>Node.js<a class="headerlink" href="#node-js" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.NodeJS</span></code> library provides support for working with <a class="reference external" href="http://nodejs.org/">Node.js</a> modules through the following classes:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$NodeModule.html">NodeModule</a>: a top-level that defines a Node.js module; see the section on <a class="reference external" href="#modules">Modules</a> for more information.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NodeJS.qll/type.NodeJS$Require.html">Require</a>: a call to the special <code class="docutils literal notranslate"><span class="pre">require</span></code> function that imports a module.</p></li>
|
||
</ul>
|
||
<p>As an example of the use of these classes, here is a query that counts for every module how many other modules it imports:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from NodeModule m
|
||
select m, count(m.getAnImportedModule())
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/659662207/">See this in the query console on LGTM.com</a>. When you analyze a project, for each module you can see how many other modules it imports.</p>
|
||
</section>
|
||
<section id="npm">
|
||
<h4>NPM<a class="headerlink" href="#npm" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.NPM</span></code> library provides support for working with <a class="reference external" href="https://www.npmjs.com/">NPM</a> packages through the following classes:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$PackageJSON.html">PackageJSON</a>: a <code class="docutils literal notranslate"><span class="pre">package.json</span></code> file describing an NPM package; various getter predicates are available for accessing detailed information about the package, which are described in the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/module.NPM.html">online API documentation</a>.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$BugTrackerInfo.html">BugTrackerInfo</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$ContributorInfo.html">ContributorInfo</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$RepositoryInfo.html">RepositoryInfo</a>: these classes model parts of the <code class="docutils literal notranslate"><span class="pre">package.json</span></code> file providing information on bug tracking systems, contributors and repositories.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$PackageDependencies.html">PackageDependencies</a>: models the dependencies of an NPM package; the predicate <code class="docutils literal notranslate"><span class="pre">PackageDependencies.getADependency(pkg,</span> <span class="pre">v)</span></code> binds <code class="docutils literal notranslate"><span class="pre">pkg</span></code> to the name and <code class="docutils literal notranslate"><span class="pre">v</span></code> to the version of a package required by a <code class="docutils literal notranslate"><span class="pre">package.json</span></code> file.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/NPM.qll/type.NPM$NPMPackage.html">NPMPackage</a>: a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Files.qll/type.Files$Folder.html">Folder</a> that models an NPM package; important member predicates include:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">NPMPackage.getPackageName()</span></code> returns the name of this package.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">NPMPackage.getPackageJSON()</span></code> returns the <code class="docutils literal notranslate"><span class="pre">package.json</span></code> file for this package.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">NPMPackage.getNodeModulesFolder()</span></code> returns the <code class="docutils literal notranslate"><span class="pre">node_modules</span></code> folder for this package.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">NPMPackage.getAModule()</span></code> returns a Node.js module belonging to this package (not including modules in the <code class="docutils literal notranslate"><span class="pre">node_modules</span></code> folder).</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>As an example of the use of these classes, here is a query that identifies unused dependencies, that is, module dependencies that are listed in the <code class="docutils literal notranslate"><span class="pre">package.json</span></code> file, but which are not imported by any <code class="docutils literal notranslate"><span class="pre">require</span></code> call:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from NPMPackage pkg, PackageDependencies deps, string name
|
||
where deps = pkg.getPackageJSON().getDependencies() and
|
||
deps.getADependency(name, _) and
|
||
not exists (Require req | req.getTopLevel() = pkg.getAModule() | name = req.getImportedPath().getValue())
|
||
select deps, "Unused dependency '" + name + "'."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/666680077/">See this in the query console on LGTM.com</a>. It is not uncommon for projects to have some unused dependencies.</p>
|
||
</section>
|
||
<section id="react">
|
||
<h4>React<a class="headerlink" href="#react" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.frameworks.React</span></code> library provides support for working with <a class="reference external" href="https://reactjs.org/">React</a> code through the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/frameworks/React.qll/type.React$ReactComponent.html">ReactComponent</a> class, which models a React component defined either in the functional style or the class-based style (both ECMAScript 2015 classes and old-style <code class="docutils literal notranslate"><span class="pre">React.createClass</span></code> classes are supported).</p>
|
||
</section>
|
||
<section id="databases">
|
||
<h4>Databases<a class="headerlink" href="#databases" title="Link to this heading">¶</a></h4>
|
||
<p>The class <code class="docutils literal notranslate"><span class="pre">SQL::SqlString</span></code> represents an expression that is interpreted as a SQL command. Currently, we model SQL commands issued through the following npm packages:
|
||
<a class="reference external" href="https://www.npmjs.com/package/mysql">mysql</a>, <a class="reference external" href="https://www.npmjs.com/package/pg">pg</a>, <a class="reference external" href="https://www.npmjs.com/package/pg-pool">pg-pool</a>, <a class="reference external" href="https://www.npmjs.com/package/sqlite3">sqlite3</a>, <a class="reference external" href="https://www.npmjs.com/package/mssql">mssql</a> and <a class="reference external" href="https://www.npmjs.com/package/sequelize">sequelize</a>.</p>
|
||
<p>Similarly, the class <code class="docutils literal notranslate"><span class="pre">NoSQL::Query</span></code> represents an expression that is interpreted as a NoSQL query by the <code class="docutils literal notranslate"><span class="pre">mongodb</span></code> or <code class="docutils literal notranslate"><span class="pre">mongoose</span></code> package.</p>
|
||
<p>Finally, the class <code class="docutils literal notranslate"><span class="pre">DatabaseAccess</span></code> contains all data flow nodes that perform a database access using any of the packages above.</p>
|
||
<p>For example, here is a query to find SQL queries that use string concatenation (instead of a templating-based solution, which is usually safer):</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from SQL::SqlString ss
|
||
where ss instanceof AddExpr
|
||
select ss, "Use templating instead of string concatenation."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/1506076336224/">See this in the query console on LGTM.com</a>, showing two (benign) results on <a class="reference external" href="https://lgtm.com/projects/g/strongloop/strong-arc/">strong-arc</a>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="miscellaneous">
|
||
<h3>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Link to this heading">¶</a></h3>
|
||
<section id="externs">
|
||
<h4>Externs<a class="headerlink" href="#externs" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.Externs</span></code> library provides support for working with <a class="reference external" href="https://developers.google.com/closure/compiler/docs/api-tutorial3">externs</a> through the following classes:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalDecl.html">ExternalDecl</a>: common superclass modeling all different kinds of externs declarations; it defines two member predicates:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ExternalDecl.getQualifiedName()</span></code> returns the fully qualified name of the declared entity.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ExternalDecl.getName()</span></code> returns the unqualified name of the declared entity.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalTypedef.html">ExternalTypedef</a>: a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalDecl.html">ExternalDecl</a> representing type declarations; unlike other externs declarations, such declarations do not declare a function or object that is present at runtime, but simply introduce an alias for a type.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalVarDecl.html">ExternalVarDecl</a>: a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalDecl.html">ExternalDecl</a> representing a variable or function declaration; it defines two member predicates:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ExternalVarDecl.getInit()</span></code> returns the initializer associated with this declaration, if any; this can either be a <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Functions.qll/type.Functions$Function.html">Function</a> or an <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ExternalVarDecl.getDocumentation()</span></code> returns the JSDoc comment associated with this declaration.</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Variables and functions declared in an externs file are either globals (represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalGlobalDecl.html">ExternalGlobalDecl</a>), or members (represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalMemberDecl.html">ExternalMemberDecl</a>).</p>
|
||
<p>Members are further subdivided into static members (class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalStaticMemberDecl.html">ExternalStaticMemberDecl</a>) and instance members (class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/type.Externs$ExternalInstanceMemberDecl.html">ExternalInstanceMemberDecl</a>).</p>
|
||
<p>For more details on these and other classes representing externs, see <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Externs.qll/module.Externs.html">the API documentation</a>.</p>
|
||
</section>
|
||
<section id="html">
|
||
<h4>HTML<a class="headerlink" href="#html" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.HTML</span></code> library provides support for working with HTML documents. They are represented as a tree of <code class="docutils literal notranslate"><span class="pre">HTML::Element</span></code> nodes, each of which may have zero or more attributes represented by class <code class="docutils literal notranslate"><span class="pre">HTML::Attribute</span></code>.</p>
|
||
<p>Similar to the abstract syntax tree representation, <code class="docutils literal notranslate"><span class="pre">HTML::Element</span></code> has member predicates <code class="docutils literal notranslate"><span class="pre">getChild(i)</span></code> and <code class="docutils literal notranslate"><span class="pre">getParent()</span></code> to navigate from an element to its <code class="docutils literal notranslate"><span class="pre">i</span></code>th child element and its parent element, respectively. Use predicate <code class="docutils literal notranslate"><span class="pre">HTML::Element.getAttribute(i)</span></code> to get the <code class="docutils literal notranslate"><span class="pre">i</span></code>th attribute of the element, and <code class="docutils literal notranslate"><span class="pre">HTML::Element.getAttributeByName(n)</span></code> to get the attribute with name <code class="docutils literal notranslate"><span class="pre">n</span></code>.</p>
|
||
<p>For <code class="docutils literal notranslate"><span class="pre">HTML::Attribute</span></code>, predicates <code class="docutils literal notranslate"><span class="pre">getName()</span></code> and <code class="docutils literal notranslate"><span class="pre">getValue()</span></code> provide access to the attribute’s name and value, respectively.</p>
|
||
<p>Both <code class="docutils literal notranslate"><span class="pre">HTML::Element</span></code> and <code class="docutils literal notranslate"><span class="pre">HTML::Attribute</span></code> have a predicate <code class="docutils literal notranslate"><span class="pre">getRoot()</span></code> that gets the root <code class="docutils literal notranslate"><span class="pre">HTML::Element</span></code> of the document to which they belong.</p>
|
||
</section>
|
||
<section id="jsdoc">
|
||
<h4>JSDoc<a class="headerlink" href="#jsdoc" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.JSDoc</span></code> library provides support for working with <a class="reference external" href="https://jsdoc.app/">JSDoc comments</a>. Documentation comments are parsed into an abstract syntax tree representation closely following the format employed by the <a class="reference external" href="https://github.com/eslint/doctrine">Doctrine</a> JSDoc parser.</p>
|
||
<p>A JSDoc comment as a whole is represented by an entity of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDoc.html">JSDoc</a>, while individual tags are represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDocTag.html">JSDocTag</a>. Important member predicates of these two classes include:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDoc.getDescription()</span></code> returns the descriptive header of the JSDoc comment, if any.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDoc.getComment()</span></code> maps the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDoc.html">JSDoc</a> entity to its underlying <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Comments.qll/type.Comments$Comment.html">Comment</a> entity.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDocTag.getATag()</span></code> returns a tag in this JSDoc comment.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDocTag.getTitle()</span></code> returns the title of his tag; for instance, an <code class="docutils literal notranslate"><span class="pre">@param</span></code> tag has title <code class="docutils literal notranslate"><span class="pre">"param"</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDocTag.getName()</span></code> returns the name of the parameter or variable documented by this tag.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDocTag.getType()</span></code> returns the type of the parameter or variable documented by this tag.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSDocTag.getDescription()</span></code> returns the description associated with this tag.</p></li>
|
||
</ul>
|
||
<p>Types in JSDoc comments are represented by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDocTypeExpr.html">JSDocTypeExpr</a> and its subclasses, which again represent type expressions as abstract syntax trees. Examples of type expressions are <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDocAnyTypeExpr.html">JSDocAnyTypeExpr</a>, representing the “any” type <code class="docutils literal notranslate"><span class="pre">*</span></code>, or <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/type.JSDoc$JSDocNullTypeExpr.html">JSDocNullTypeExpr</a>, representing the null type.</p>
|
||
<p>As an example, here is a query that finds <code class="docutils literal notranslate"><span class="pre">@param</span></code> tags that do not specify the name of the documented parameter:</p>
|
||
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import javascript
|
||
|
||
from JSDocTag t
|
||
where t.getTitle() = "param" and
|
||
not exists(t.getName())
|
||
select t, "@param tag is missing name."
|
||
</pre></div>
|
||
</div>
|
||
<p>➤ <a class="reference external" href="https://lgtm.com/query/673060054/">See this in the query console on LGTM.com</a>. Of the LGTM.com demo projects analyzed, only <em>Semantic-Org/Semantic-UI</em> has an example where the <code class="docutils literal notranslate"><span class="pre">@param</span></code> tag omits the name.</p>
|
||
<p>For full details on these and other classes representing JSDoc comments and type expressions, see <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSDoc.qll/module.JSDoc.html">the API documentation</a>.</p>
|
||
</section>
|
||
<section id="jsx">
|
||
<h4>JSX<a class="headerlink" href="#jsx" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.JSX</span></code> library provides support for working with <a class="reference external" href="https://reactjs.org/docs/jsx-in-depth.html">JSX code</a>.</p>
|
||
<p>Similar to the representation of HTML documents, JSX fragments are modeled as a tree of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSX.qll/type.JSX$JSXElement.html">JSXElement</a>s, each of which may have zero or more <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSX.qll/type.JSX$JSXAttribute.html">JSXAttribute</a>s.</p>
|
||
<p>However, unlike HTML, JSX is interleaved with JavaScript, hence <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSX.qll/type.JSX$JSXElement.html">JSXElement</a> is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Expr.qll/type.Expr$Expr.html">Expr</a>. Like <code class="docutils literal notranslate"><span class="pre">HTML::Element</span></code>, it has predicates <code class="docutils literal notranslate"><span class="pre">getAttribute(i)</span></code> and <code class="docutils literal notranslate"><span class="pre">getAttributeByName(n)</span></code> to look up attributes of a JSX element. Its body elements can be accessed by predicate <code class="docutils literal notranslate"><span class="pre">getABodyElement()</span></code>; note that the results of this predicate are arbitrary expressions, which may either be further <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSX.qll/type.JSX$JSXElement.html">JSXElement</a>s, or other expressions that are interpolated into the body of the outer element.</p>
|
||
<p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSX.qll/type.JSX$JSXAttribute.html">JSXAttribute</a>, again not unlike <code class="docutils literal notranslate"><span class="pre">HTML::Attribute</span></code>, has predicates <code class="docutils literal notranslate"><span class="pre">getName()</span></code> and <code class="docutils literal notranslate"><span class="pre">getValue()</span></code> to access the attribute name and value.</p>
|
||
</section>
|
||
<section id="json">
|
||
<h4>JSON<a class="headerlink" href="#json" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.JSON</span></code> library provides support for working with <a class="reference external" href="http://json.org/">JSON</a> files that were processed by the JavaScript extractor when building the CodeQL database.</p>
|
||
<p>JSON files are modeled as trees of JSON values. Each JSON value is represented by an entity of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONValue.html">JSONValue</a>, which provides the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSONValue.getParent()</span></code> returns the JSON object or array in which this value occurs.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">JSONValue.getChild(i)</span></code> returns the <code class="docutils literal notranslate"><span class="pre">i</span></code>th child of this JSON object or array.</p></li>
|
||
</ul>
|
||
<p>Note that <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONValue.html">JSONValue</a> is a subclass of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Locatable.html">Locatable</a>, so the usual member predicates of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Locations.qll/type.Locations$Locatable.html">Locatable</a> can be used to determine the file in which a JSON value appears, and its location within that file.</p>
|
||
<p>Class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONValue.html">JSONValue</a> has the following subclasses:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONPrimitiveValue.html">JSONPrimitiveValue</a>: a JSON-encoded primitive value; use <code class="docutils literal notranslate"><span class="pre">JSONPrimitiveValue.getValue()</span></code> to obtain a string representation of the value.</p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONNull.html">JSONNull</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONBoolean.html">JSONBoolean</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONNumber.html">JSONNumber</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONString.html">JSONString</a>: subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONPrimitiveValue.html">JSONPrimitiveValue</a> representing the various kinds of primitive values.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONArray.html">JSONArray</a>: a JSON-encoded array; use <code class="docutils literal notranslate"><span class="pre">JSONArray.getElementValue(i)</span></code> to access the <code class="docutils literal notranslate"><span class="pre">i</span></code>th element of the array.</p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/JSON.qll/type.JSON$JSONObject.html">JSONObject</a>: a JSON-encoded object; use <code class="docutils literal notranslate"><span class="pre">JSONObject.getValue(n)</span></code> to access the value of property <code class="docutils literal notranslate"><span class="pre">n</span></code> of the object.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="regular-expressions">
|
||
<h4>Regular expressions<a class="headerlink" href="#regular-expressions" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.Regexp</span></code> library provides support for working with regular expression literals. The syntactic structure of regular expression literals is represented as an abstract syntax tree of regular expression terms, modeled by the class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Regexp.qll/type.Regexp$RegExpTerm.html">RegExpTerm</a>. Similar to <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$ASTNode.html">ASTNode</a>, class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Regexp.qll/type.Regexp$RegExpTerm.html">RegExpTerm</a> provides member predicates <code class="docutils literal notranslate"><span class="pre">getParent()</span></code> and <code class="docutils literal notranslate"><span class="pre">getChild(i)</span></code> to navigate the structure of the syntax tree.</p>
|
||
<p>Various subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Regexp.qll/type.Regexp$RegExpTerm.html">RegExpTerm</a> model different kinds of regular expression constructs and operators; see <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/Regexp.qll/module.Regexp.html">the API documentation</a> for details.</p>
|
||
</section>
|
||
<section id="yaml">
|
||
<h4>YAML<a class="headerlink" href="#yaml" title="Link to this heading">¶</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">semmle.javascript.YAML</span></code> library provides support for working with <a class="reference external" href="https://yaml.org/">YAML</a> files that were processed by the JavaScript extractor when building the CodeQL database.</p>
|
||
<p>YAML files are modeled as trees of YAML nodes. Each YAML node is represented by an entity of class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLNode.html">YAMLNode</a>, which provides, among others, the following member predicates:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YAMLNode.getParentNode()</span></code> returns the YAML collection in which this node is syntactically nested.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YAMLNode.getChildNode(i)</span></code> returns the <code class="docutils literal notranslate"><span class="pre">i</span></code>th child node of this node, <code class="docutils literal notranslate"><span class="pre">YAMLNode.getAChildNode()</span></code> returns any child node of this node.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YAMLNode.getTag()</span></code> returns the tag of this YAML node.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YAMLNode.getAnchor()</span></code> returns the anchor associated with this YAML node, if any.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YAMLNode.eval()</span></code> returns the <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLValue.html">YAMLValue</a> this YAML node evaluates to after resolving aliases and includes.</p></li>
|
||
</ul>
|
||
<p>The various kinds of scalar values available in YAML are represented by classes <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLInteger.html">YAMLInteger</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLFloat.html">YAMLFloat</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLTimestamp.html">YAMLTimestamp</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLBool.html">YAMLBool</a>, <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLNull.html">YAMLNull</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLString.html">YAMLString</a>. Their common superclass is <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLScalar.html">YAMLScalar</a>, which has a member predicate <code class="docutils literal notranslate"><span class="pre">getValue()</span></code> to obtain the value of a scalar as a
|
||
string.</p>
|
||
<p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLMapping.html">YAMLMapping</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLSequence.html">YAMLSequence</a> represent mappings and sequences, respectively, and are subclasses of <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLCollection.html">YAMLCollection</a>.</p>
|
||
<p>Alias nodes are represented by class <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLAliasNode.html">YAMLAliasNode</a>, while <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLMergeKey.html">YAMLMergeKey</a> and <a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/YAML.qll/type.YAML$YAMLInclude.html">YAMLInclude</a> represent merge keys and <code class="docutils literal notranslate"><span class="pre">!include</span></code> directives, respectively.</p>
|
||
<p>Predicate <code class="docutils literal notranslate"><span class="pre">YAMLMapping.maps(key,</span> <span class="pre">value)</span></code> models the key-value relation represented by a mapping, taking merge keys into account.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="further-reading">
|
||
<h2>Further reading<a class="headerlink" href="#further-reading" title="Link to this heading">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://github.com/github/codeql/tree/main/javascript/ql/src">CodeQL queries for JavaScript</a></p></li>
|
||
<li><p><a class="reference external" href="https://github.com/github/codeql/tree/main/javascript/ql/examples">Example queries for JavaScript</a></p></li>
|
||
<li><p><a class="reference external" href="https://codeql.github.com/codeql-standard-libraries/javascript/">CodeQL library reference for JavaScript</a></p></li>
|
||
</ul>
|
||
<ul class="simple">
|
||
<li><p>“<a class="reference internal" href="../ql-language-reference/index.html#ql-language-reference"><span class="std std-ref">QL language reference</span></a>”</p></li>
|
||
<li><p>“<a class="reference internal" href="../codeql-overview/codeql-tools.html#codeql-tools"><span class="std std-ref">CodeQL tools</span></a>”</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</article>
|
||
|
||
<!-- GitHub footer, with links to terms and privacy statement -->
|
||
<div class="px-3 px-md-6 f6 py-4 d-sm-flex flex-justify-between flex-row-reverse flex-items-center border-top">
|
||
<ul class="list-style-none d-flex flex-items-center mb-3 mb-sm-0 lh-condensed-ultra">
|
||
<li class="mr-3">
|
||
<a href="https://twitter.com/github" title="GitHub on Twitter" style="color: #959da5;">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 273.5 222.3" class="d-block" height="18">
|
||
<path
|
||
d="M273.5 26.3a109.77 109.77 0 0 1-32.2 8.8 56.07 56.07 0 0 0 24.7-31 113.39 113.39 0 0 1-35.7 13.6 56.1 56.1 0 0 0-97 38.4 54 54 0 0 0 1.5 12.8A159.68 159.68 0 0 1 19.1 10.3a56.12 56.12 0 0 0 17.4 74.9 56.06 56.06 0 0 1-25.4-7v.7a56.11 56.11 0 0 0 45 55 55.65 55.65 0 0 1-14.8 2 62.39 62.39 0 0 1-10.6-1 56.24 56.24 0 0 0 52.4 39 112.87 112.87 0 0 1-69.7 24 119 119 0 0 1-13.4-.8 158.83 158.83 0 0 0 86 25.2c103.2 0 159.6-85.5 159.6-159.6 0-2.4-.1-4.9-.2-7.3a114.25 114.25 0 0 0 28.1-29.1"
|
||
fill="currentColor"></path>
|
||
</svg>
|
||
</a>
|
||
</li>
|
||
<li class="mr-3">
|
||
<a href="https://www.facebook.com/GitHub" title="GitHub on Facebook" style="color: #959da5;">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 15.3 15.4" class="d-block" height="18">
|
||
<path
|
||
d="M14.5 0H.8a.88.88 0 0 0-.8.9v13.6a.88.88 0 0 0 .8.9h7.3v-6h-2V7.1h2V5.4a2.87 2.87 0 0 1 2.5-3.1h.5a10.87 10.87 0 0 1 1.8.1v2.1h-1.3c-1 0-1.1.5-1.1 1.1v1.5h2.3l-.3 2.3h-2v5.9h3.9a.88.88 0 0 0 .9-.8V.8a.86.86 0 0 0-.8-.8z"
|
||
fill="currentColor"></path>
|
||
</svg>
|
||
</a>
|
||
</li>
|
||
<li class="mr-3">
|
||
<a href="https://www.youtube.com/github" title="GitHub on YouTube" style="color: #959da5;">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.17 13.6" class="d-block" height="16">
|
||
<path
|
||
d="M18.77 2.13A2.4 2.4 0 0 0 17.09.42C15.59 0 9.58 0 9.58 0a57.55 57.55 0 0 0-7.5.4A2.49 2.49 0 0 0 .39 2.13 26.27 26.27 0 0 0 0 6.8a26.15 26.15 0 0 0 .39 4.67 2.43 2.43 0 0 0 1.69 1.71c1.52.42 7.5.42 7.5.42a57.69 57.69 0 0 0 7.51-.4 2.4 2.4 0 0 0 1.68-1.71 25.63 25.63 0 0 0 .4-4.67 24 24 0 0 0-.4-4.69zM7.67 9.71V3.89l5 2.91z"
|
||
fill="currentColor"></path>
|
||
</svg>
|
||
</a>
|
||
</li>
|
||
<li class="mr-3 flex-self-start">
|
||
<a href="https://www.linkedin.com/company/github" title="GitHub on Linkedin" style="color: #959da5;">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19 18" class="d-block" height="18">
|
||
<path
|
||
d="M3.94 2A2 2 0 1 1 2 0a2 2 0 0 1 1.94 2zM4 5.48H0V18h4zm6.32 0H6.34V18h3.94v-6.57c0-3.66 4.77-4 4.77 0V18H19v-7.93c0-6.17-7.06-5.94-8.72-2.91z"
|
||
fill="currentColor"></path>
|
||
</svg>
|
||
</a>
|
||
</li>
|
||
<li>
|
||
<a href="https://github.com/github" title="GitHub's organization" style="color: #959da5;">
|
||
<svg version="1.1" width="20" height="20" viewBox="0 0 16 16" class="octicon octicon-mark-github"
|
||
aria-hidden="true">
|
||
<path fill-rule="evenodd"
|
||
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z">
|
||
</path>
|
||
</svg>
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
<ul class="list-style-none d-flex text-gray">
|
||
<li class="mr-3">©
|
||
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
|
||
<li class="mr-3"><a
|
||
href="https://docs.github.com/github/site-policy/github-terms-of-service"
|
||
class="link-gray">Terms </a></li>
|
||
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
|
||
class="link-gray">Privacy </a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</main>
|
||
|
||
<script type="text/javascript">
|
||
$(document).ready(function () {
|
||
$(".toggle > *").hide();
|
||
$(".toggle .name").show();
|
||
$(".toggle .name").click(function () {
|
||
$(this).parent().children().not(".name").toggle(400);
|
||
$(this).parent().children(".name").toggleClass("open");
|
||
})
|
||
});
|
||
</script>
|
||
|
||
</body>
|
||
</html> |