Add "Preview Query Help" command

github · Nov 1, 2021 · 8a4b6fd · 8a4b6fd
1 parent 31dc11e
commit 8a4b6fd
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 0 deletions.
diff --git a/extensions/ql-vscode/package.json b/extensions/ql-vscode/package.json
@@ -46,6 +46,7 @@
     "onCommand:codeQL.setCurrentDatabase",
     "onCommand:codeQL.viewAst",
     "onCommand:codeQL.openReferencedFile",
+    "onCommand:codeQL.previewQueryHelp",
     "onCommand:codeQL.chooseDatabaseFolder",
     "onCommand:codeQL.chooseDatabaseArchive",
     "onCommand:codeQL.chooseDatabaseInternet",
@@ -295,6 +296,10 @@
         "command": "codeQL.openReferencedFile",
         "title": "CodeQL: Open Referenced File"
       },
+      {
+        "command": "codeQL.previewQueryHelp",
+        "title": "CodeQL: Preview Query Help File"
+      },
       {
         "command": "codeQL.quickQuery",
         "title": "CodeQL: Quick Query"
@@ -681,6 +686,11 @@
           "group": "9_qlCommands",
           "when": "view == codeQLQueryHistory"
         },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "group": "9_qlCommands",
+          "when": "resourceScheme == .qhelp"
+        },
         {
           "command": "codeQLTests.showOutputDifferences",
           "group": "qltest@1",
@@ -712,6 +722,11 @@
           "command": "codeQL.openReferencedFile",
           "group": "9_qlCommands",
           "when": "resourceExtname == .qlref"
+        },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "group": "9_qlCommands",
+          "when": "resourceExtname == .qhelp"
         }
       ],
       "commandPalette": [
@@ -743,6 +758,10 @@
           "command": "codeQL.openReferencedFile",
           "when": "resourceExtname == .qlref"
         },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "when": "resourceExtname == .qhelp"
+        },
         {
           "command": "codeQL.setCurrentDatabase",
           "when": "false"
@@ -900,6 +919,10 @@
         {
           "command": "codeQL.openReferencedFile",
           "when": "resourceExtname == .qlref"
+        },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "when": "resourceExtname == .qhelp"
         }
       ]
     },

diff --git a/extensions/ql-vscode/src/cli.ts b/extensions/ql-vscode/src/cli.ts
@@ -613,6 +613,21 @@ export class CodeQLCliServer implements Disposable {
 
     return await this.runCodeQlCliCommand(['database', 'unbundle'], subcommandArgs, `Extracting ${archivePath} to directory ${target}`);
   }
+
+  /**
+   * Uses a .qhelp file to generate Query Help documentation in a specified format.
+   * @param pathToQhelp The path to the .qhelp file
+   * @param format The format in which the query help should be generated {@link https://codeql.github.com/docs/codeql-cli/manual/generate-query-help/#cmdoption-codeql-generate-query-help-format}
+   * @param outputDirectory The output directory for the generated file
+   */
+  async generateQueryHelp(pathToQhelp:string, format: string, outputDirectory?: string): Promise<string> {
+    const subcommandArgs = [];
+    subcommandArgs.push('--format', format);
+    if(outputDirectory) subcommandArgs.push('--output', outputDirectory);
+    subcommandArgs.push(pathToQhelp);
+
+    return await this.runCodeQlCliCommand(['generate', 'query-help'], subcommandArgs, `Generating qhelp in ${format} format at ${outputDirectory}`);
+  }
 
   /**
   * Gets the results from a bqrs.

diff --git a/extensions/ql-vscode/src/extension.ts b/extensions/ql-vscode/src/extension.ts
@@ -16,6 +16,7 @@ import {
 import { LanguageClient } from 'vscode-languageclient';
 import * as os from 'os';
 import * as path from 'path';
+import * as tmp from 'tmp';
 import { testExplorerExtensionId, TestHub } from 'vscode-test-adapter-api';
 
 import { AstViewer } from './astViewer';
@@ -493,6 +494,29 @@ async function activateWithInstalledDistribution(
     }
   }
 
+  async function previewQueryHelp(
+    selectedQuery: Uri
+  ): Promise<void> {
+    const path = selectedQuery ? selectedQuery.path : window.activeTextEditor!.document.uri.fsPath;
+    if(path) {
+      // Create temporary directory
+      const tmpDir = tmp.dirSync();
+      // Get library name and query file name in the format 'libname/queryname.md
+      const mdFilePath = path.split('/').slice(-2).join('/').replace('.qhelp', '.md');
+      const absolutePathToMd = `${tmpDir.name}${mdFilePath}`;
+      const uri = Uri.file(absolutePathToMd);
+      try {
+        await cliServer.generateQueryHelp(path , 'markdown', absolutePathToMd);
+        await commands.executeCommand('markdown.showPreviewToSide', uri);
+      } catch (err) {
+        const errorMessage =  err.message.includes('Generating qhelp in markdown') ? (
+          `Could not generate markdown from ${path}: Bad formatting in .qhelp file.`
+        ) : `Could not open a preview of the generated file (${absolutePathToMd}).`;
+        void helpers.showAndLogErrorMessage(errorMessage);
+      }
+    }
+  }
+
   async function openReferencedFile(
     selectedQuery: Uri
   ): Promise<void> {
@@ -732,6 +756,13 @@ async function activateWithInstalledDistribution(
     )
   );
 
+  ctx.subscriptions.push(
+    commandRunner(
+      'codeQL.previewQueryHelp',
+      previewQueryHelp
+    )
+  );
+
   ctx.subscriptions.push(
     commandRunnerWithProgress('codeQL.restartQueryServer', async (
       progress: ProgressCallback,