Merge branch 'main' into aeisenberg/sorted-result-sets

extensions/ql-vscode/CHANGELOG.md

@@ -7,8 +7,10 @@
 - Fix a bug with importing large databases. Databases over 4GB can now be imported directly from LGTM or from a zip file. This functionality is only available when using CodeQL CLI version 2.6.0 or later. [#971](https://github.com/github/vscode-codeql/pull/971)
 - Replace certain control codes (`U+0000` - `U+001F`) with their corresponding control labels (`U+2400` - `U+241F`) in the results view. [#963](https://github.com/github/vscode-codeql/pull/963)
 - Allow case-insensitive project slugs for GitHub repositories when adding a CodeQL database from LGTM. [#978](https://github.com/github/vscode-codeql/pull/961)
+- Add a _CodeQL: Preview Query Help_ command to generate Markdown previews of `.qhelp` query help files. This command should only be run in trusted workspaces. See https://codeql.github.com/docs/codeql-cli/testing-query-help-files for more information about query help. [#988](https://github.com/github/vscode-codeql/pull/988)
 - Make "Open Referenced File" command accessible from the active editor menu. [#989](https://github.com/github/vscode-codeql/pull/989)
 - Fix a bug where result set names in the result set drop-down were disappearing when viewing a sorted table. [#1007](https://github.com/github/vscode-codeql/pull/1007)
+- Allow query result locations with 0 as the end column value. These are treated as the first column in the line. [#1002](https://github.com/github/vscode-codeql/pull/1002)
 
 ## 1.5.6 - 07 October 2021
 

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"
+      },
       {
         "command": "codeQL.quickQuery",
         "title": "CodeQL: Quick Query"
@@ -681,6 +686,11 @@
           "group": "9_qlCommands",
           "when": "view == codeQLQueryHistory"
         },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "group": "9_qlCommands",
+          "when": "view == codeQLQueryHistory && resourceScheme == .qhelp && isWorkspaceTrusted"
+        },
         {
           "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 && isWorkspaceTrusted"
         }
       ],
       "commandPalette": [
@@ -743,6 +758,10 @@
           "command": "codeQL.openReferencedFile",
           "when": "resourceExtname == .qlref"
         },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "when": "resourceExtname == .qhelp && isWorkspaceTrusted"
+        },
         {
           "command": "codeQL.setCurrentDatabase",
           "when": "false"
@@ -900,6 +919,10 @@
         {
           "command": "codeQL.openReferencedFile",
           "when": "resourceExtname == .qlref"
+        },
+        {
+          "command": "codeQL.previewQueryHelp",
+          "when": "resourceExtname == .qhelp && isWorkspaceTrusted"
         }
       ]
     },
@@ -993,7 +1016,7 @@
     "@types/gulp-sourcemaps": "0.0.32",
     "@types/js-yaml": "^3.12.5",
     "@types/jszip": "~3.1.6",
-    "@types/mocha": "^8.2.0",
+    "@types/mocha": "^9.0.0",
     "@types/node": "^12.14.1",
     "@types/node-fetch": "~2.5.2",
     "@types/proxyquire": "~1.3.28",
@@ -1026,8 +1049,8 @@
     "husky": "~4.2.5",
     "jsonc-parser": "^2.3.0",
     "lint-staged": "~10.2.2",
-    "mocha": "^8.2.1",
-    "mocha-sinon": "~2.1.0",
+    "mocha": "^9.1.3",
+    "mocha-sinon": "~2.1.2",
     "npm-run-all": "^4.1.5",
     "prettier": "~2.0.5",
     "proxyquire": "~2.1.3",

extensions/ql-vscode/src/cli.ts

@@ -621,6 +621,20 @@ 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, outputDirectory?: string): Promise<string> {
+    const subcommandArgs = ['--format=markdown'];
+    if(outputDirectory) subcommandArgs.push('--output', outputDirectory);
+    subcommandArgs.push(pathToQhelp);
+
+    return await this.runCodeQlCliCommand(['generate', 'query-help'], subcommandArgs, `Generating qhelp in markdown format at ${outputDirectory}`);
+  }
 
   /**
   * Gets the results from a bqrs.

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-promise';
 import { testExplorerExtensionId, TestHub } from 'vscode-test-adapter-api';
 
 import { AstViewer } from './astViewer';
@@ -493,6 +494,32 @@ async function activateWithInstalledDistribution(
     }
   }
 
+  const qhelpTmpDir = tmp.dirSync({ prefix: 'qhelp_', keep: false, unsafeCleanup: true });
+  ctx.subscriptions.push({ dispose: qhelpTmpDir.removeCallback });
+
+  async function previewQueryHelp(
+    selectedQuery: Uri
+  ): Promise<void> {
+    // selectedQuery is unpopulated when executing through the command palette
+    const pathToQhelp =  selectedQuery ? selectedQuery.fsPath : window.activeTextEditor?.document.uri.fsPath;
+    if(pathToQhelp) {
+      // Create temporary directory
+      const relativePathToMd = path.basename(pathToQhelp, '.qhelp') + '.md';
+      const absolutePathToMd = path.join(qhelpTmpDir.name, relativePathToMd);
+      const uri = Uri.file(absolutePathToMd);
+      try {
+        await cliServer.generateQueryHelp(pathToQhelp , absolutePathToMd);
+        await commands.executeCommand('markdown.showPreviewToSide', uri);
+      } catch (err) {
+        const errorMessage =  err.message.includes('Generating qhelp in markdown') ? (
+          `Could not generate markdown from ${pathToQhelp}: Bad formatting in .qhelp file.`
+        ) : `Could not open a preview of the generated file (${absolutePathToMd}).`;
+        void helpers.showAndLogErrorMessage(errorMessage, { fullMessage: `${errorMessage}\n${err}` });
+      }
+    }
+    
+  }
+
   async function openReferencedFile(
     selectedQuery: Uri
   ): Promise<void> {
@@ -746,6 +773,13 @@ async function activateWithInstalledDistribution(
     )
   );
 
+  ctx.subscriptions.push(
+    commandRunner(
+      'codeQL.previewQueryHelp',
+      previewQueryHelp
+    )
+  );
+
   ctx.subscriptions.push(
     commandRunnerWithProgress('codeQL.restartQueryServer', async (
       progress: ProgressCallback,

extensions/ql-vscode/src/interface-utils.ts

@@ -70,7 +70,7 @@ function resolveFivePartLocation(
     Math.max(0, loc.startLine - 1),
     Math.max(0, loc.startColumn - 1),
     Math.max(0, loc.endLine - 1),
-    Math.max(0, loc.endColumn)
+    Math.max(1, loc.endColumn)
   );
 
   return new Location(databaseItem.resolveSourceFile(loc.uri), range);

extensions/ql-vscode/src/pure/bqrs-utils.ts

@@ -83,8 +83,7 @@ export function isLineColumnLoc(loc: UrlValue): loc is LineColumnLocation {
     && 'startLine' in loc
     && 'startColumn' in loc
     && 'endLine' in loc
-    && 'endColumn' in loc
-    && loc.endColumn > 0;
+    && 'endColumn' in loc;
 }
 
 export function isWholeFileLoc(loc: UrlValue): loc is WholeFileLocation {

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "vscode-codeql",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {}
+}