Merge pull request #11502 from github/felicitymay-8441-detective

LGTM deprecation: Update QL detective tutorials

Author: felicitymay

docs/codeql/reusables/setup-to-run-tutorials.rst

@@ -0,0 +1 @@
+For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."

docs/codeql/writing-codeql-queries/catch-the-fire-starter.rst

@@ -105,7 +105,7 @@ Now try applying ``isAllowedIn(string region)`` to a person ``p``. If ``p`` is n
 
 You know that the fire starters live in the south *and* that they must have been able to travel to the north. Write a query to find the possible suspects. You could also extend the ``select`` clause to list the age of the suspects. That way you can clearly see that all the children have been excluded from the list.
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/2551838470440192723/>`__
+➤ `Check your answer <#exercise-1>`__
 
 You can now continue to gather more clues and find out which of your suspects started the fire...
 
@@ -142,11 +142,73 @@ The predicate ``isBald`` is defined to take a ``Person``, so it can also take a
 
 You can now write a query to select the bald southerners who are allowed into the north.
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/2572701606358725253/>`__
+➤ `Check your answer <#exercise-2>`__
 
 You have found the two fire starters! They are arrested and the villagers are once again impressed with your work.
 
 Further reading
 ---------------
 
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+--------------
+
+Answers
+-------
+
+In these answers, we use ``/*`` and ``*/`` to label the different parts of the query. Any text surrounded by ``/*`` and ``*/`` is not evaluated as part of the QL code, but is treated as a *comment*.
+
+Exercise 1
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   import tutorial
+
+   predicate isSouthern(Person p) { p.getLocation() = "south" }
+
+   class Southerner extends Person {
+   /* the characteristic predicate */
+   Southerner() { isSouthern(this) }
+   }
+
+   class Child extends Person {
+   /* the characteristic predicate */
+   Child() { this.getAge() < 10 }
+
+   /* a member predicate */
+   override predicate isAllowedIn(string region) { region = this.getLocation() }
+   }
+
+   from Southerner s
+   where s.isAllowedIn("north")
+   select s, s.getAge()
+
+Exercise 2
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   import tutorial
+
+   predicate isSouthern(Person p) { p.getLocation() = "south" }
+
+   class Southerner extends Person {
+   /* the characteristic predicate */
+   Southerner() { isSouthern(this) }
+   }
+
+   class Child extends Person {
+   /* the characteristic predicate */
+   Child() { this.getAge() < 10 }
+
+   /* a member predicate */
+   override predicate isAllowedIn(string region) { region = this.getLocation() }
+   }
+
+   predicate isBald(Person p) { not exists(string c | p.getHairColor() = c) }
+
+   from Southerner s
+   where s.isAllowedIn("north") and isBald(s)
+   select s
+

docs/codeql/writing-codeql-queries/cross-the-river.rst

@@ -260,21 +260,34 @@ Alternative solutions
 
 Here are some more example queries that solve the river crossing puzzle:
 
-  #. This query uses a modified ``path`` variable to describe the resulting path in
-     more detail.
+.. container:: toggle
 
-     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/659603593702729237/>`__
+   .. container:: name
 
-  #. This query models the man and the cargo items in a different way, using an 
-     :ref:`abstract <abstract>`
-     class and predicate. It also displays the resulting path in a more visual way.
+      *Show/hide example query - modified path*
 
-     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/1025323464423811143/>`__
+   .. literalinclude:: river-answer-1-path.ql
+      :language: ql
 
-  #. This query introduces :ref:`algebraic datatypes <algebraic-datatypes>`
-     to model the situation, instead of defining everything as a subclass of ``string``.
 
-     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__
+.. container:: toggle
+
+   .. container:: name
+
+      *Show/hide example query - abstract class*
+
+   .. literalinclude:: river-answer-2-abstract-class.ql
+      :language: ql
+
+
+.. container:: toggle
+
+   .. container:: name
+
+      *Show/hide example query - datatypes*
+
+   .. literalinclude:: river-answer-3-datatypes.ql
+      :language: ql
 
 Further reading
 ---------------

docs/codeql/writing-codeql-queries/crown-the-rightful-heir.rst

@@ -129,7 +129,7 @@ Here is one way to define ``relativeOf()``:
 
 Don't forget to use the predicate ``isDeceased()`` to find relatives that are still alive.
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/6710025057257064639/>`__
+➤ `Check your answer <#exercise-1>`__
 
 Select the true heir
 --------------------
@@ -142,7 +142,7 @@ To decide who should inherit the king's fortune, the villagers carefully read th
 
 As your final challenge, define a predicate ``hasCriminalRecord`` so that ``hasCriminalRecord(p)`` holds if ``p`` is any of the criminals you unmasked earlier (in the ":doc:`Find the thief <find-the-thief>`" and ":doc:`Catch the fire starter <catch-the-fire-starter>`" tutorials).
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/1820692755164273290/>`__
+➤ `Check your answer <#exercise-2>`__
 
 Experimental explorations
 -------------------------
@@ -164,3 +164,47 @@ Further reading
 ---------------
 
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+--------------
+
+Answers
+-------
+
+In these answers, we use ``/*`` and ``*/`` to label the different parts of the query. Any text surrounded by ``/*`` and ``*/`` is not evaluated as part of the QL code, but is treated as a *comment*.
+
+Exercise 1
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   import tutorial
+
+   Person relativeOf(Person p) { parentOf*(result) = parentOf*(p) }
+
+   from Person p
+   where
+   not p.isDeceased() and
+   p = relativeOf("King Basil")
+   select p
+
+Exercise 2
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   import tutorial
+
+   Person relativeOf(Person p) { parentOf*(result) = parentOf*(p) }
+
+   predicate hasCriminalRecord(Person p) {
+   p = "Hester" or
+   p = "Hugh" or
+   p = "Charlie"
+   }
+
+   from Person p
+   where
+   not p.isDeceased() and
+   p = relativeOf("King Basil") and
+   not hasCriminalRecord(p)
+   select p

docs/codeql/writing-codeql-queries/find-the-thief.rst

@@ -50,9 +50,7 @@ You start asking some creative questions and making notes of the answers so you
 
 There is too much information to search through by hand, so you decide to use your newly acquired QL skills to help you with your investigation...
 
-#. Open the `query console on LGTM.com <https://lgtm.com/query>`__ to get started.
-#. Select a language and a demo project. For this tutorial, any language and project will do.
-#. Delete the default code ``import <language> select "hello world"``.
+.. include:: ../reusables/setup-to-run-tutorials.rst
 
 QL libraries
 ------------
@@ -209,13 +207,7 @@ Hints
 
 Once you have finished, you will have a list of possible suspects. One of those people must be the thief!
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/1505743955992/>`__
-
-.. pull-quote::
-
-   Note
-
-   In the answer, we used ``/*`` and ``*/`` to label the different parts of the query. Any text surrounded by ``/*`` and ``*/`` is not evaluated as part of the QL code, but is just a *comment*.
+➤ `Check your answer <#exercise-1>`__
 
 You are getting closer to solving the mystery! Unfortunately, you still have quite a long list of suspects... To find out which of your suspects is the thief, you must gather more information and refine your query in the next step.
 
@@ -291,9 +283,59 @@ You can now translate the remaining questions into QL:
 
 Have you found the thief?
 
-➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/1505744186085/>`__
+➤ `Check your answer <#exercise-2>`__
 
 Further reading
 ---------------
 
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+
+--------------
+
+Answers
+-------
+
+In these answers, we use ``/*`` and ``*/`` to label the different parts of the query. Any text surrounded by ``/*`` and ``*/`` is not evaluated as part of the QL code, but is treated as a *comment*.
+
+Exercise 1
+^^^^^^^^^^
+
+.. code-block:: ql
+
+   import tutorial
+
+   from Person t
+   where
+   /* 1 */ t.getHeight() > 150 and
+   /* 2 */ not t.getHairColor() = "blond" and
+   /* 3 */ exists (string c | t.getHairColor() = c) and
+   /* 4 */ not t.getAge() < 30 and
+   /* 5 */ t.getLocation() = "east" and
+   /* 6 */ (t.getHairColor() = "black" or t.getHairColor() = "brown") and
+   /* 7 */ not (t.getHeight() > 180 and t.getHeight() < 190) and
+   /* 8 */ exists(Person p | p.getAge() > t.getAge())
+   select t
+
+Exercise 2
+^^^^^^^^^^
+
+.. code-block:: ql
+
+   import tutorial
+
+   from Person t
+   where
+   /* 1 */ t.getHeight() > 150 and
+   /* 2 */ not t.getHairColor() = "blond" and
+   /* 3 */ exists (string c | t.getHairColor() = c) and
+   /* 4 */ not t.getAge() < 30 and
+   /* 5 */ t.getLocation() = "east" and
+   /* 6 */ (t.getHairColor() = "black" or t.getHairColor() = "brown") and
+   /* 7 */ not (t.getHeight() > 180 and t.getHeight() < 190) and
+   /* 8 */ exists(Person p | p.getAge() > t.getAge()) and
+   /* 9 */ not t = max(Person p | | p order by p.getHeight()) and
+   /* 10 */ t.getHeight() < avg(float i | exists(Person p | p.getHeight() = i) | i) and
+   /* 11 */ t = max(Person p | p.getLocation() = "east" | p order by p.getAge())
+   select "The thief is " + t + "!"
+