QuickEval

Author: Dave Bartolomeo

extensions/ql-vscode/package.json

@@ -494,6 +494,14 @@
         "command": "codeQL.getCurrentQuery",
         "title": "CodeQL: Get Current Query"
       },
+      {
+        "command": "codeQL.debug.quickEval",
+        "title": "CodeQL Debugger: Quick Evaluation"
+      },
+      {
+        "command": "codeQL.debug.quickEvalContextEditor",
+        "title": "CodeQL Debugger: Quick Evaluation"
+      },
       {
         "command": "codeQL.viewAst",
         "title": "CodeQL: View AST"
@@ -1092,6 +1100,14 @@
           "command": "codeQL.quickEvalContextEditor",
           "when": "false"
         },
+        {
+          "command": "codeQL.debug.quickEval",
+          "when": "config.codeQL.canary && editorLangId == ql"
+        },
+        {
+          "command": "codeQL.debug.quickEvalContextEditor",
+          "when": "false"
+        },
         {
           "command": "codeQL.openReferencedFile",
           "when": "resourceExtname == .qlref"
@@ -1394,6 +1410,10 @@
           "command": "codeQL.quickEvalContextEditor",
           "when": "editorLangId == ql"
         },
+        {
+          "command": "codeQL.debug.quickEvalContextEditor",
+          "when": "config.codeQL.canary && editorLangId == ql"
+        },
         {
           "command": "codeQL.openReferencedFileContextEditor",
           "when": "resourceExtname == .qlref"

extensions/ql-vscode/src/common/commands.ts

@@ -96,6 +96,13 @@ export type LocalQueryCommands = {
   "codeQL.quickEvalContextEditor": (uri: Uri) => Promise<void>;
   "codeQL.codeLensQuickEval": (uri: Uri, range: Range) => Promise<void>;
   "codeQL.quickQuery": () => Promise<void>;
+  "codeQL.getCurrentQuery": () => Promise<string>;
+};
+
+// Debugger commands
+export type DebuggerCommands = {
+  "codeQL.debug.quickEval": (uri: Uri) => Promise<void>;
+  "codeQL.debug.quickEvalContextEditor": (uri: Uri) => Promise<void>;
 };
 
 export type ResultsViewCommands = {
@@ -269,6 +276,7 @@ export type AllExtensionCommands = BaseCommands &
   ResultsViewCommands &
   QueryHistoryCommands &
   LocalDatabasesCommands &
+  DebuggerCommands &
   VariantAnalysisCommands &
   DatabasePanelCommands &
   AstCfgCommands &

extensions/ql-vscode/src/debugger/debug-configuration.ts

@@ -6,24 +6,38 @@ import {
 } from "vscode";
 import { getOnDiskWorkspaceFolders, showAndLogErrorMessage } from "../helpers";
 import { LocalQueries } from "../local-queries";
+import { getQuickEvalContext, validateQueryPath } from "../run-queries-shared";
+import * as CodeQLDebugProtocol from "./debug-protocol";
 
+/**
+ * The CodeQL launch arguments, as specified in "launch.json".
+ */
 interface QLDebugArgs {
-  query: string;
-  database: string;
-  additionalPacks: string[] | string;
-  extensionPacks: string[] | string;
+  query?: string;
+  database?: string;
+  additionalPacks?: string[] | string;
+  extensionPacks?: string[] | string;
+  quickEval?: boolean;
+  noDebug?: boolean;
 }
 
-type QLDebugConfiguration = DebugConfiguration & Partial<QLDebugArgs>;
-
-interface QLResolvedDebugArgs extends QLDebugArgs {
-  additionalPacks: string[];
-  extensionPacks: string[];
-}
+/**
+ * The debug configuration for a CodeQL configuration.
+ *
+ * This just combines `QLDebugArgs` with the standard debug configuration properties.
+ */
+type QLDebugConfiguration = DebugConfiguration & QLDebugArgs;
 
+/**
+ * A CodeQL debug configuration after all variables and defaults have been resolved. This is what
+ * is passed to the debug adapter via the `launch` request.
+ */
 export type QLResolvedDebugConfiguration = DebugConfiguration &
-  QLResolvedDebugArgs;
+  CodeQLDebugProtocol.LaunchConfig;
 
+/**
+ * Implementation of `DebugConfigurationProvider` for CodeQL.
+ */
 export class QLDebugConfigurationProvider
   implements DebugConfigurationProvider
 {
@@ -36,10 +50,12 @@ export class QLDebugConfigurationProvider
   ): DebugConfiguration {
     const qlConfiguration = <QLDebugConfiguration>debugConfiguration;
 
-    // Fill in defaults
+    // Fill in defaults for properties whose default value is a command invocation. VS Code will
+    // invoke any commands to fill in  actual values, then call
+    // `resolveDebugConfigurationWithSubstitutedVariables()`with the result.
     const resultConfiguration: QLDebugConfiguration = {
       ...qlConfiguration,
-      query: qlConfiguration.query ?? "${file}",
+      query: qlConfiguration.query ?? "${command:currentQuery}",
       database: qlConfiguration.database ?? "${command:currentDatabase}",
     };
 
@@ -83,12 +99,23 @@ export class QLDebugConfigurationProvider
         ? [qlConfiguration.extensionPacks]
         : qlConfiguration.extensionPacks;
 
+    const quickEval = qlConfiguration.quickEval ?? false;
+    validateQueryPath(qlConfiguration.query, quickEval);
+
+    const quickEvalContext = quickEval
+      ? await getQuickEvalContext(undefined)
+      : undefined;
+
     const resultConfiguration: QLResolvedDebugConfiguration = {
-      ...qlConfiguration,
+      name: qlConfiguration.name,
+      request: qlConfiguration.request,
+      type: qlConfiguration.type,
       query: qlConfiguration.query,
       database: qlConfiguration.database,
       additionalPacks,
       extensionPacks,
+      quickEvalPosition: quickEvalContext?.quickEvalPosition,
+      noDebug: qlConfiguration.noDebug ?? false,
     };
 
     return resultConfiguration;

extensions/ql-vscode/src/debugger/debug-protocol.ts

@@ -17,6 +17,9 @@ export interface EvaluationStartedEventBody {
   outputDir: string;
 }
 
+/**
+ * Custom event to provide additional information about a running evaluation.
+ */
 export interface EvaluationStartedEvent extends DebugProtocol.Event {
   event: "codeql-evaluation-started";
   body: EvaluationStartedEventBody;
@@ -28,6 +31,9 @@ export interface EvaluationCompletedEventBody {
   evaluationTime: number;
 }
 
+/**
+ * Custom event to provide additional information about a completed evaluation.
+ */
 export interface EvaluationCompletedEvent extends DebugProtocol.Event {
   event: "codeql-evaluation-completed";
   body: EvaluationCompletedEventBody;
@@ -61,10 +67,28 @@ export type AnyResponse = InitializeResponse;
 
 export type AnyProtocolMessage = AnyEvent | AnyRequest | AnyResponse;
 
-export interface LaunchRequestArguments
-  extends DebugProtocol.LaunchRequestArguments {
+export interface Position {
+  fileName: string;
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+}
+
+export interface LaunchConfig {
+  /** Full path to query (.ql) file. */
   query: string;
+  /** Full path to the database directory. */
   database: string;
+  /** Full paths to `--additional-packs` directories. */
   additionalPacks: string[];
+  /** Pack names of extension packs. */
   extensionPacks: string[];
+  /** Optional quick evaluation position. */
+  quickEvalPosition: Position | undefined;
+  /** Run the query without debugging it. */
+  noDebug: boolean;
 }
+
+export type LaunchRequestArguments = DebugProtocol.LaunchRequestArguments &
+  LaunchConfig;