Adds Kotlin (beta) content

subatoi · subatoi · commit 24c413fbf98e · 2022-11-22T18:33:24.000Z
diff --git a/docs/codeql/codeql-cli/creating-codeql-databases.rst b/docs/codeql/codeql-cli/creating-codeql-databases.rst
@@ -168,7 +168,9 @@ generate a database, therefore the build method must be available to the CLI.
 Detecting the build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The CodeQL CLI includes autobuilders for C/C++, C#, Go, and Java code. CodeQL
+.. include:: ../reusables/kotlin-beta-note.rst
+
+The CodeQL CLI includes autobuilders for C/C++, C#, Go, Java and Kotlin code. CodeQL
 autobuilders allow you to build projects for compiled languages without
 specifying any build commands. When an autobuilder is invoked, CodeQL examines
 the source for evidence of a build system and attempts to run the optimal set of
diff --git a/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst b/docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst
@@ -30,7 +30,7 @@ You can then use the CodeQL CLI to publish your pack to share with others. For m
 Viewing CodeQL packs and their dependencies in Visual Studio Code
 -----------------------------------------------------------------
 To download a CodeQL pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette.
-You can download all the core CodeQL query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java, enter ``codeql/java-queries``.
+You can download all the core CodeQL query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java or Kotlin, enter ``codeql/java-queries``.
 
 Whether you have downloaded a CodeQL pack or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on.
 
diff --git a/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst b/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst
@@ -7,6 +7,8 @@ CodeQL has a large selection of classes for representing the abstract syntax tre
 
 .. include:: ../reusables/abstract-syntax-tree.rst
 
+.. include:: ../reusables/kotlin-java-differences.rst
+
 Statement classes
 -----------------
 
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst
@@ -5,6 +5,8 @@ Analyzing data flow in Java
 
 You can use CodeQL to track the flow of data through a Java program to its use. 
 
+.. include:: ../reusables/kotlin-java-differences.rst
+
 About this article
 ------------------
 
diff --git a/docs/codeql/codeql-language-guides/codeql-for-java.rst b/docs/codeql/codeql-language-guides/codeql-for-java.rst
@@ -1,9 +1,17 @@
 .. _codeql-for-java:
 
-CodeQL for Java
-===============
+CodeQL for Java and Kotlin
+==========================
 
-Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java codebases.
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java and Kotlin codebases.
+
+.. include:: ../reusables/kotlin-beta-note.rst
+
+.. include:: ../reusables/kotlin-java-differences.rst
+
+.. pull-quote:: Enabling Kotlin support
+
+   To enable Kotlin support, you should enable `java` as a language.
 
 .. toctree::
    :hidden:
diff --git a/docs/codeql/codeql-overview/system-requirements.rst b/docs/codeql/codeql-overview/system-requirements.rst
@@ -11,6 +11,8 @@ Supported platforms
 #######################
 
 .. include:: ../support/reusables/platforms.rst
+    
+.. include:: ../reusables/kotlin-beta-note.rst
 
 Additional software requirements
 ################################
diff --git a/docs/codeql/query-help/codeql-cwe-coverage.rst b/docs/codeql/query-help/codeql-cwe-coverage.rst
@@ -3,6 +3,8 @@ CodeQL CWE coverage
 
 You can view the full coverage of MITRE's Common Weakness Enumeration (CWE) or coverage by language for the latest release of CodeQL.
 
+.. include:: ../reusables/kotlin-beta-note.rst
+
 About CWEs
 ##########
 
diff --git a/docs/codeql/query-help/index.rst b/docs/codeql/query-help/index.rst
@@ -6,11 +6,13 @@ View the query help for the queries included in the ``code-scanning``, ``securit
 - :doc:`CodeQL query help for C and C++ <cpp>`
 - :doc:`CodeQL query help for C# <csharp>`
 - :doc:`CodeQL query help for Go <go>`
-- :doc:`CodeQL query help for Java <java>`
+- :doc:`CodeQL query help for Java and Kotlin <java>`
 - :doc:`CodeQL query help for JavaScript <javascript>`
 - :doc:`CodeQL query help for Python <python>`
 - :doc:`CodeQL query help for Ruby <ruby>`
 
+.. include:: ../reusables/kotlin-beta-note.rst
+
 .. pull-quote:: Information
 
    Each query help article includes: 
diff --git a/docs/codeql/reusables/extractors.rst b/docs/codeql/reusables/extractors.rst
@@ -10,7 +10,7 @@
      - ``csharp``
    * - Go
      - ``go``
-   * - Java 
+   * - Java/Kotlin
      - ``java``
    * - JavaScript/TypeScript
      - ``javascript``
diff --git a/docs/codeql/reusables/kotlin-beta-note.rst b/docs/codeql/reusables/kotlin-beta-note.rst
@@ -0,0 +1,4 @@
+  .. pull-quote:: Note
+
+     CodeQL analysis for Kotlin is currently in beta. During the beta, analysis of Kotlin code, 
+     and the accompanying documentation, will not be as comprehensive as for other languages.
diff --git a/docs/codeql/reusables/kotlin-java-differences.rst b/docs/codeql/reusables/kotlin-java-differences.rst
@@ -0,0 +1,18 @@
+Writing CodeQL queries in Kotlin versus Java
+--------------------------------------------
+
+When writing Kotlin-specific elements (such as a `WhenExpr`) you’ll need to use Kotlin-specific CodeQL classes, but writing queries for Kotlin and Java is largely the same. The two make use of the same libraries such as DataFlow, TaintTracking, or SSA, and the same classes such as `MethodAccess` or `Class`. 
+
+There are however some important cases where writing queries for Kotlin can produce surprising results compared to writing Java queries, as CodeQL works with the JVM bytecode representation of the source code. 
+
+Be careful when trying to model code elements that don’t exist in Java, such as `NotNullExpr (expr!!)`, because they could interact in unexpected ways with common predicates. For example, `MethodAccess.getQualifier()` gets a `NotNullExpr `instead of a `VarAccess`` in the following Kotlin code:
+
+`someVar!!.someMethodCall()`
+
+In that specific case, you can use the predicate `Expr.getUnderlyingExpr()`. This goes directly to the underlying `VarAccess`` to produce a more similar behavior to that in Java.
+
+Nullable elements (`?`) can also produce unexpected behavior. To avoid a `NullPointerException`, Kotlin may inline calls like `expr.toString()` to `String.valueOf(expr)` when `expr` is nullable. Make sure that you write CodeQL around the extracted code, and do not directly modify the source code in the codebase.
+
+Another example is that if-else expressions are translated into `WhenExprs` in CodeQL, instead of the more typical `IfStmt` in Java.
+
+In general, you can debug these issues with the AST (you can use the `CodeQL: View AST`` command from Visual Studio Code’s CodeQL extension, or run the `PrintAst.ql`` query) and checking what exactly CodeQL is extracting from your code.
diff --git a/docs/codeql/support/reusables/frameworks.rst b/docs/codeql/support/reusables/frameworks.rst
@@ -93,9 +93,11 @@ and the CodeQL library pack ``codeql/go-all`` (`changelog <https://github.com/gi
    `yaml <https://gopkg.in/yaml.v3>`_, Serialization
    `zap <https://go.uber.org/zap>`_, Logging library
 
-Java built-in support
+Java and Kotlin built-in support
 ==================================
 
+.. include:: ../reusables/kotlin-beta-note.rst
+
 Provided by the current versions of the
 CodeQL query pack ``codeql/java-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/java/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/java/ql/src>`__)
 and the CodeQL library pack ``codeql/java-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/java/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/java/ql/lib>`__).
