Include custom query help in analysis results

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [UNRELEASED]
 
 - The `init` step of the Action now supports `ram` and `threads` inputs to limit resource use of CodeQL extractors. These inputs also serve as defaults to the subsequent `analyze` step, which finalizes the database and executes queries. [#738](https://github.com/github/codeql-action/pull/738)
+- When used with CodeQL 2.7.1 or above, the Action now includes custom query help in the analysis results uploaded to GitHub code scanning, if available. To add help text for a custom query, create a Markdown file next to the `.ql` file containing the query, using the same base name but the file extension `.md`. [#804](https://github.com/github/codeql-action/pull/804)
 
 ## 1.0.21 - 28 Oct 2021
 

src/codeql.test.ts

@@ -1,8 +1,10 @@
 import * as path from "path";
 
+import * as toolrunner from "@actions/exec/lib/toolrunner";
 import * as toolcache from "@actions/tool-cache";
 import test from "ava";
 import nock from "nock";
+import * as sinon from "sinon";
 
 import * as codeql from "./codeql";
 import * as defaults from "./defaults.json";
@@ -400,3 +402,36 @@ test("getCodeQLActionRepository", (t) => {
   const repoEnv = codeql.getCodeQLActionRepository(logger);
   t.deepEqual(repoEnv, "xxx/yyy");
 });
+
+test("databaseInterpretResults() does not set --sarif-add-query-help for 2.7.0", async (t) => {
+  const runnerConstructorStub = stubToolRunnerConstructor();
+  const codeqlObject = await codeql.getCodeQLForTesting();
+  sinon.stub(codeqlObject, "getVersion").resolves("2.7.0");
+  await codeqlObject.databaseInterpretResults("", [], "", "", "", "");
+  t.false(
+    runnerConstructorStub.firstCall.args[1].includes("--sarif-add-query-help"),
+    "--sarif-add-query-help should be absent, but it is present"
+  );
+});
+
+test("databaseInterpretResults() sets --sarif-add-query-help for 2.7.1", async (t) => {
+  const runnerConstructorStub = stubToolRunnerConstructor();
+  const codeqlObject = await codeql.getCodeQLForTesting();
+  sinon.stub(codeqlObject, "getVersion").resolves("2.7.1");
+  await codeqlObject.databaseInterpretResults("", [], "", "", "", "");
+  t.true(
+    runnerConstructorStub.firstCall.args[1].includes("--sarif-add-query-help"),
+    "--sarif-add-query-help should be present, but it is absent"
+  );
+});
+
+function stubToolRunnerConstructor(): sinon.SinonStub<
+  any[],
+  toolrunner.ToolRunner
+> {
+  const runnerObjectStub = sinon.createStubInstance(toolrunner.ToolRunner);
+  runnerObjectStub.exec.resolves(0);
+  const runnerConstructorStub = sinon.stub(toolrunner, "ToolRunner");
+  runnerConstructorStub.returns(runnerObjectStub);
+  return runnerConstructorStub;
+}

src/codeql.ts

@@ -213,6 +213,7 @@ const CODEQL_VERSION_METRICS = "2.5.5";
 const CODEQL_VERSION_GROUP_RULES = "2.5.5";
 const CODEQL_VERSION_SARIF_GROUP = "2.5.3";
 export const CODEQL_VERSION_COUNTS_LINES = "2.6.2";
+const CODEQL_VERSION_CUSTOM_QUERY_HELP = "2.7.1";
 
 /**
  * Version above which we use the CLI's indirect build tracing and
@@ -599,6 +600,15 @@ export function getCachedCodeQL(): CodeQL {
   return cachedCodeQL;
 }
 
+/**
+ * Get a real, newly created CodeQL instance for testing. The instance refers to
+ * a non-existent placeholder codeql command, so tests that use this function
+ * should also stub the toolrunner.ToolRunner constructor.
+ */
+export async function getCodeQLForTesting(): Promise<CodeQL> {
+  return getCodeQLForCmd("codeql-for-testing", false);
+}
+
 async function getCodeQLForCmd(
   cmd: string,
   checkVersion: boolean
@@ -875,6 +885,8 @@ async function getCodeQLForCmd(
         codeqlArgs.push("--print-metrics-summary");
       if (await util.codeQlVersionAbove(this, CODEQL_VERSION_GROUP_RULES))
         codeqlArgs.push("--sarif-group-rules-by-pack");
+      if (await util.codeQlVersionAbove(this, CODEQL_VERSION_CUSTOM_QUERY_HELP))
+        codeqlArgs.push("--sarif-add-query-help");
       if (
         automationDetailsId !== undefined &&
         (await util.codeQlVersionAbove(this, CODEQL_VERSION_SARIF_GROUP))