General refactoring and adding comments

There is no new behaviour added in this commit. Just some cleanup:

- Move some shared constants to the `helpers` module
- Add comments to some of the query related modules
- Some general formatting and tidying

Author: aeisenberg

extensions/ql-vscode/CHANGELOG.md

@@ -35,7 +35,7 @@
 - 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)
+- 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 [the CodeQL CLI docs](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)

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

@@ -8,7 +8,7 @@ import {
 } from 'vscode';
 import * as path from 'path';
 
-import { tmpDir } from '../run-queries';
+import { tmpDir } from '../helpers';
 import {
   FromCompareViewMessage,
   ToCompareViewMessage,

extensions/ql-vscode/src/config.ts

@@ -2,8 +2,7 @@ import { DisposableObject } from './pure/disposable-object';
 import { workspace, Event, EventEmitter, ConfigurationChangeEvent, ConfigurationTarget } from 'vscode';
 import { DistributionManager } from './distribution';
 import { logger } from './logging';
-
-const ONE_DAY_IN_MS = 24 * 60 * 60 * 1000;
+import { ONE_DAY_IN_MS } from './pure/helpers-pure';
 
 /** Helper class to look up a labelled (and possibly nested) setting. */
 export class Setting {
@@ -258,7 +257,7 @@ export class QueryHistoryConfigListener extends ConfigListener implements QueryH
   }
 
   /**
-   * The configuration value is in days, but return the value in milliseconds.
+   * The configuration value is in days, but return the value in milliseconds to make it easier to use.
    */
   public get ttlInMillis(): number {
     return (QUERY_HISTORY_TTL.getValue<number>() || 30) * ONE_DAY_IN_MS;

extensions/ql-vscode/src/databaseFetcher.ts

@@ -20,7 +20,7 @@ import {
   ProgressCallback,
 } from './commandRunner';
 import { logger } from './logging';
-import { tmpDir } from './run-queries';
+import { tmpDir } from './helpers';
 
 /**
  * Prompts a user to fetch a database from a remote location. Database is assumed to be an archive file.
@@ -434,7 +434,7 @@ function convertRawLgtmSlug(maybeSlug: string): string | undefined {
   }
   return;
 }
- 
+
 function extractProjectSlug(lgtmUrl: string): string | undefined {
   // Only matches the '/g/' provider (github)
   const re = new RegExp('https://lgtm.com/projects/g/(.*[^/])');

extensions/ql-vscode/src/extension.ts

@@ -54,7 +54,15 @@ import {
   GithubApiError,
   GithubRateLimitedError
 } from './distribution';
-import * as helpers from './helpers';
+import {
+  findLanguage,
+  tmpDirDisposal,
+  showBinaryChoiceDialog,
+  showAndLogErrorMessage,
+  showAndLogWarningMessage,
+  showAndLogInformationMessage,
+  showInformationMessageWithAction
+} from './helpers';
 import { assertNever } from './pure/helpers-pure';
 import { spawnIdeServer } from './ide-server';
 import { InterfaceManager } from './interface';
@@ -64,7 +72,7 @@ import { QueryHistoryManager } from './query-history';
 import { FullCompletedQueryInfo, FullQueryInfo } from './query-results';
 import * as qsClient from './queryserver-client';
 import { displayQuickQuery } from './quick-query';
-import { compileAndRunQueryAgainstDatabase, createInitialQueryInfo, tmpDirDisposal } from './run-queries';
+import { compileAndRunQueryAgainstDatabase, createInitialQueryInfo } from './run-queries';
 import { QLTestAdapterFactory } from './test-adapter';
 import { TestUIService } from './test-ui';
 import { CompareInterfaceManager } from './compare/compare-interface';
@@ -189,7 +197,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
   const shouldUpdateOnNextActivationKey = 'shouldUpdateOnNextActivation';
 
   registerErrorStubs([checkForUpdatesCommand], command => (async () => {
-    void helpers.showAndLogErrorMessage(`Can't execute ${command}: waiting to finish loading CodeQL CLI.`);
+    void showAndLogErrorMessage(`Can't execute ${command}: waiting to finish loading CodeQL CLI.`);
   }));
 
   interface DistributionUpdateConfig {
@@ -201,7 +209,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
   async function installOrUpdateDistributionWithProgressTitle(progressTitle: string, config: DistributionUpdateConfig): Promise<void> {
     const minSecondsSinceLastUpdateCheck = config.isUserInitiated ? 0 : 86400;
     const noUpdatesLoggingFunc = config.shouldDisplayMessageWhenNoUpdates ?
-      helpers.showAndLogInformationMessage : async (message: string) => void logger.log(message);
+      showAndLogInformationMessage : async (message: string) => void logger.log(message);
     const result = await distributionManager.checkForUpdatesToExtensionManagedDistribution(minSecondsSinceLastUpdateCheck);
 
     // We do want to auto update if there is no distribution at all
@@ -223,7 +231,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
           const updateAvailableMessage = `Version "${result.updatedRelease.name}" of the CodeQL CLI is now available. ` +
             'Do you wish to upgrade?';
           await ctx.globalState.update(shouldUpdateOnNextActivationKey, true);
-          if (await helpers.showInformationMessageWithAction(updateAvailableMessage, 'Restart and Upgrade')) {
+          if (await showInformationMessageWithAction(updateAvailableMessage, 'Restart and Upgrade')) {
             await commands.executeCommand('workbench.action.reloadWindow');
           }
         } else {
@@ -236,7 +244,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
             distributionManager.installExtensionManagedDistributionRelease(result.updatedRelease, progress));
 
           await ctx.globalState.update(shouldUpdateOnNextActivationKey, false);
-          void helpers.showAndLogInformationMessage(`CodeQL CLI updated to version "${result.updatedRelease.name}".`);
+          void showAndLogInformationMessage(`CodeQL CLI updated to version "${result.updatedRelease.name}".`);
         }
         break;
       default:
@@ -263,7 +271,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
       // Don't rethrow the exception, because if the config is changed, we want to be able to retry installing
       // or updating the distribution.
       const alertFunction = (codeQlInstalled && !config.isUserInitiated) ?
-        helpers.showAndLogWarningMessage : helpers.showAndLogErrorMessage;
+        showAndLogWarningMessage : showAndLogErrorMessage;
       const taskDescription = (willUpdateCodeQl ? 'update' :
         codeQlInstalled ? 'check for updates to' : 'install') + ' CodeQL CLI';
 
@@ -298,20 +306,20 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
           }
         })();
 
-        void helpers.showAndLogWarningMessage(
+        void showAndLogWarningMessage(
           `The current version of the CodeQL CLI (${result.version.raw}) ` +
           `is incompatible with this extension. ${fixGuidanceMessage}`
         );
         break;
       }
       case FindDistributionResultKind.UnknownCompatibilityDistribution:
-        void helpers.showAndLogWarningMessage(
+        void showAndLogWarningMessage(
           'Compatibility with the configured CodeQL CLI could not be determined. ' +
           'You may experience problems using the extension.'
         );
         break;
       case FindDistributionResultKind.NoDistribution:
-        void helpers.showAndLogErrorMessage('The CodeQL CLI could not be found.');
+        void showAndLogErrorMessage('The CodeQL CLI could not be found.');
         break;
       default:
         assertNever(result);
@@ -338,7 +346,7 @@ export async function activate(ctx: ExtensionContext): Promise<CodeQLExtensionIn
     } else if (distributionResult.kind === FindDistributionResultKind.NoDistribution) {
       registerErrorStubs([checkForUpdatesCommand], command => async () => {
         const installActionName = 'Install CodeQL CLI';
-        const chosenAction = await void helpers.showAndLogErrorMessage(`Can't execute ${command}: missing CodeQL CLI.`, {
+        const chosenAction = await void showAndLogErrorMessage(`Can't execute ${command}: missing CodeQL CLI.`, {
           items: [installActionName]
         });
         if (chosenAction === installActionName) {
@@ -477,7 +485,7 @@ async function activateWithInstalledDistribution(
     try {
       await cmpm.showResults(from, to);
     } catch (e) {
-      void helpers.showAndLogErrorMessage(e.message);
+      void showAndLogErrorMessage(e.message);
     }
   }
 
@@ -559,7 +567,7 @@ async function activateWithInstalledDistribution(
         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}` });
+        void showAndLogErrorMessage(errorMessage, { fullMessage: `${errorMessage}\n${err}` });
       }
     }
 
@@ -576,7 +584,7 @@ async function activateWithInstalledDistribution(
         const uri = Uri.file(resolved.resolvedPath);
         await window.showTextDocument(uri, { preview: false });
       } else {
-        void helpers.showAndLogErrorMessage(
+        void showAndLogErrorMessage(
           'Jumping from a .qlref file to the .ql file it references is not '
           + 'supported with the CLI version you are running.\n'
           + `Please upgrade your CLI to version ${CliVersionConstraint.CLI_VERSION_WITH_RESOLVE_QLREF
@@ -646,15 +654,15 @@ async function activateWithInstalledDistribution(
       ) => {
         let filteredDBs = dbm.databaseItems;
         if (filteredDBs.length === 0) {
-          void helpers.showAndLogErrorMessage('No databases found. Please add a suitable database to your workspace.');
+          void showAndLogErrorMessage('No databases found. Please add a suitable database to your workspace.');
           return;
         }
         // If possible, only show databases with the right language (otherwise show all databases).
-        const queryLanguage = await helpers.findLanguage(cliServer, uri);
+        const queryLanguage = await findLanguage(cliServer, uri);
         if (queryLanguage) {
           filteredDBs = dbm.databaseItems.filter(db => db.language === queryLanguage);
           if (filteredDBs.length === 0) {
-            void helpers.showAndLogErrorMessage(`No databases found for language ${queryLanguage}. Please add a suitable database to your workspace.`);
+            void showAndLogErrorMessage(`No databases found for language ${queryLanguage}. Please add a suitable database to your workspace.`);
             return;
           }
         }
@@ -686,12 +694,12 @@ async function activateWithInstalledDistribution(
           }
           if (skippedDatabases.length > 0) {
             void logger.log(`Errors:\n${errors.join('\n')}`);
-            void helpers.showAndLogWarningMessage(
+            void showAndLogWarningMessage(
               `The following databases were skipped:\n${skippedDatabases.join('\n')}.\nFor details about the errors, see the logs.`
             );
           }
         } else {
-          void helpers.showAndLogErrorMessage('No databases selected.');
+          void showAndLogErrorMessage('No databases selected.');
         }
       },
       {
@@ -718,7 +726,7 @@ async function activateWithInstalledDistribution(
         // files may be hidden from the user.
         if (dirFound) {
           const fileString = files.map(file => path.basename(file)).join(', ');
-          const res = await helpers.showBinaryChoiceDialog(
+          const res = await showBinaryChoiceDialog(
             `You are about to run ${files.length} queries: ${fileString} Do you want to continue?`
           );
           if (!res) {
@@ -882,7 +890,7 @@ async function activateWithInstalledDistribution(
       token: CancellationToken
     ) => {
       await qs.restartQueryServer(progress, token);
-      void helpers.showAndLogInformationMessage('CodeQL Query Server restarted.', {
+      void showAndLogInformationMessage('CodeQL Query Server restarted.', {
         outputLogger: queryServerLogger,
       });
     }, {
@@ -938,7 +946,7 @@ async function activateWithInstalledDistribution(
     commandRunner('codeQL.copyVersion', async () => {
       const text = `CodeQL extension version: ${extension?.packageJSON.version} \nCodeQL CLI version: ${await getCliVersion()} \nPlatform: ${os.platform()} ${os.arch()}`;
       await env.clipboard.writeText(text);
-      void helpers.showAndLogInformationMessage(text);
+      void showAndLogInformationMessage(text);
     }));
 
   const getCliVersion = async () => {
@@ -960,7 +968,7 @@ async function activateWithInstalledDistribution(
         const credentials = await Credentials.initialize(ctx);
         const octokit = await credentials.getOctokit();
         const userInfo = await octokit.users.getAuthenticated();
-        void helpers.showAndLogInformationMessage(`Authenticated to GitHub as user: ${userInfo.data.login}`);
+        void showAndLogInformationMessage(`Authenticated to GitHub as user: ${userInfo.data.login}`);
       }
     }));
 

extensions/ql-vscode/src/helpers.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs-extra';
 import * as glob from 'glob-promise';
 import * as yaml from 'js-yaml';
 import * as path from 'path';
+import * as tmp from 'tmp-promise';
 import {
   ExtensionContext,
   Uri,
@@ -14,6 +15,17 @@ import { UserCancellationException } from './commandRunner';
 import { logger } from './logging';
 import { QueryMetadata } from './pure/interface-types';
 
+// Shared temporary folder for the extension.
+export const tmpDir = tmp.dirSync({ prefix: 'queries_', keep: false, unsafeCleanup: true });
+export const upgradesTmpDir = path.join(tmpDir.name, 'upgrades');
+fs.ensureDirSync(upgradesTmpDir);
+
+export const tmpDirDisposal = {
+  dispose: () => {
+    tmpDir.removeCallback();
+  }
+};
+
 /**
  * Show an error message and log it to the console
  *

extensions/ql-vscode/src/interface.ts

@@ -14,7 +14,7 @@ import {
 import * as cli from './cli';
 import { CodeQLCliServer } from './cli';
 import { DatabaseEventKind, DatabaseItem, DatabaseManager } from './databases';
-import { showAndLogErrorMessage } from './helpers';
+import { showAndLogErrorMessage, tmpDir } from './helpers';
 import { assertNever } from './pure/helpers-pure';
 import {
   FromResultsViewMsg,
@@ -33,7 +33,7 @@ import { Logger } from './logging';
 import * as messages from './pure/messages';
 import { commandRunner } from './commandRunner';
 import { CompletedQueryInfo, interpretResults } from './query-results';
-import { QueryEvaluationInfo, tmpDir } from './run-queries';
+import { QueryEvaluationInfo } from './run-queries';
 import { parseSarifLocation, parseSarifPlainTextMessage } from './pure/sarif-utils';
 import {
   WebviewReveal,

extensions/ql-vscode/src/pure/helpers-pure.ts

@@ -29,3 +29,8 @@ export const asyncFilter = async function <T>(arr: T[], predicate: (arg0: T) =>
   const results = await Promise.all(arr.map(predicate));
   return arr.filter((_, index) => results[index]);
 };
+
+export const ONE_DAY_IN_MS = 24 * 60 * 60 * 1000;
+export const ONE_HOUR_IN_MS = 1000 * 60 * 60;
+export const TWO_HOURS_IN_MS = 1000 * 60 * 60 * 2;
+export const THREE_HOURS_IN_MS = 1000 * 60 * 60 * 3;

extensions/ql-vscode/src/query-history.ts

@@ -28,7 +28,7 @@ import { URLSearchParams } from 'url';
 import { QueryServerClient } from './queryserver-client';
 import { DisposableObject } from './pure/disposable-object';
 import { commandRunner } from './commandRunner';
-import { assertNever } from './pure/helpers-pure';
+import { assertNever, ONE_HOUR_IN_MS, TWO_HOURS_IN_MS } from './pure/helpers-pure';
 import { FullCompletedQueryInfo, FullQueryInfo, QueryStatus } from './query-results';
 import { DatabaseManager } from './databases';
 import { registerQueryHistoryScubber } from './query-history-scrubber';
@@ -83,8 +83,15 @@ export enum SortOrder {
   CountDesc = 'CountDesc',
 }
 
-const ONE_HOUR_IN_MS = 1000 * 60 * 60;
-const TWO_HOURS_IN_MS = 1000 * 60 * 60 * 2;
+/**
+ * Number of milliseconds two clicks have to arrive apart to be
+ * considered a double-click.
+ */
+const DOUBLE_CLICK_TIME = 500;
+
+const NO_QUERY_SELECTED = 'No query selected. Select a query history item you have already run and try again.';
+
+const WORKSPACE_QUERY_HISTORY_FILE = 'workspace-query-history.json';
 
 /**
  * Tree data provider for the query history view.
@@ -244,15 +251,6 @@ export class HistoryTreeDataProvider extends DisposableObject {
   }
 }
 
-/**
- * Number of milliseconds two clicks have to arrive apart to be
- * considered a double-click.
- */
-const DOUBLE_CLICK_TIME = 500;
-
-const NO_QUERY_SELECTED = 'No query selected. Select a query history item you have already run and try again.';
-
-const WORKSPACE_QUERY_HISTORY_FILE = 'workspace-query-history.json';
 export class QueryHistoryManager extends DisposableObject {
 
   treeDataProvider: HistoryTreeDataProvider;
@@ -742,7 +740,7 @@ export class QueryHistoryManager extends DisposableObject {
     }
 
     await this.tryOpenExternalFile(
-      await finalSingleItem.completedQuery.query.ensureCsvProduced(this.qs, this.dbm)
+      await finalSingleItem.completedQuery.query.ensureCsvAlerts(this.qs, this.dbm)
     );
   }
 

extensions/ql-vscode/src/query-results.ts

@@ -18,6 +18,14 @@ import { DatabaseInfo } from './pure/interface-types';
 import { showAndLogErrorMessage } from './helpers';
 import { asyncFilter } from './pure/helpers-pure';
 
+/**
+ * query-results.ts
+ * ----------------
+ *
+ * A collection of classes and functions that collectively
+ * manage query results.
+ */
+
 /**
  * A description of the information about a query
  * that is available before results are populated.