Merge pull request #492 from aeisenberg/aeisenberg/ast-viewer

Add the AST Viewer

Author: aeisenberg

extensions/ql-vscode/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Add the AST Viewer to inspect the QL AST of a source file in a database. Currently, only available for C/C++ sources.
 - Fix error with choosing qlpack search path.
 - Add the AST Viewer to inspect the QL AST of a source file in a database. Currently, only available for C/C++ sources.
 - Fix pagination when there are no results.

extensions/ql-vscode/media/dark/clear-all.svg

@@ -25,13 +25,15 @@
     "onLanguage:ql",
     "onView:codeQLDatabases",
     "onView:codeQLQueryHistory",
+    "onView:codeQLAstViewer",
     "onView:test-explorer",
     "onCommand:codeQL.checkForUpdatesToCLI",
     "onCommand:codeQLDatabases.chooseDatabaseFolder",
     "onCommand:codeQLDatabases.chooseDatabaseArchive",
     "onCommand:codeQLDatabases.chooseDatabaseInternet",
     "onCommand:codeQLDatabases.chooseDatabaseLgtm",
     "onCommand:codeQL.setCurrentDatabase",
+    "onCommand:codeQL.viewAst",
     "onCommand:codeQL.chooseDatabaseFolder",
     "onCommand:codeQL.chooseDatabaseArchive",
     "onCommand:codeQL.chooseDatabaseInternet",
@@ -218,6 +220,10 @@
         "command": "codeQL.setCurrentDatabase",
         "title": "CodeQL: Set Current Database"
       },
+      {
+        "command": "codeQL.viewAst",
+        "title": "CodeQL: View AST"
+      },
       {
         "command": "codeQL.upgradeCurrentDatabase",
         "title": "CodeQL: Upgrade Current Database"
@@ -333,6 +339,18 @@
       {
         "command": "codeQLTests.acceptOutput",
         "title": "CodeQL: Accept Test Output"
+      },
+      {
+        "command": "codeQLAstViewer.gotoCode",
+        "title": "Go To Code"
+      },
+      {
+        "command": "codeQLAstViewer.clear",
+        "title": "Clear AST",
+        "icon": {
+          "light": "media/light/clear-all.svg",
+          "dark": "media/dark/clear-all.svg"
+        }
       }
     ],
     "menus": {
@@ -366,6 +384,11 @@
           "command": "codeQLDatabases.chooseDatabaseLgtm",
           "when": "view == codeQLDatabases",
           "group": "navigation"
+        },
+        {
+          "command": "codeQLAstViewer.clear",
+          "when": "view == codeQLAstViewer && config.codeQL.experimentalAstViewer == true",
+          "group": "navigation"
         }
       ],
       "view/item/context": [
@@ -446,6 +469,11 @@
           "group": "9_qlCommands",
           "when": "resourceScheme == codeql-zip-archive || explorerResourceIsFolder || resourceExtname == .zip"
         },
+        {
+          "command": "codeQL.viewAst",
+          "group": "9_qlCommands",
+          "when": "resourceScheme == codeql-zip-archive && config.codeQL.experimentalAstViewer == true"
+        },
         {
           "command": "codeQL.runQueries",
           "group": "9_qlCommands"
@@ -468,6 +496,10 @@
           "command": "codeQL.setCurrentDatabase",
           "when": "false"
         },
+        {
+          "command": "codeQL.viewAst",
+          "when": "resourceScheme == codeql-zip-archive"
+        },
         {
           "command": "codeQLDatabases.setCurrentDatabase",
           "when": "false"
@@ -543,6 +575,14 @@
         {
           "command": "codeQLQueryHistory.compareWith",
           "when": "false"
+        },
+        {
+          "command": "codeQLAstViewer.gotoCode",
+          "when": "false"
+        },
+        {
+          "command": "codeQLAstViewer.clear",
+          "when": "false"
         }
       ],
       "editor/context": [
@@ -574,9 +614,25 @@
         {
           "id": "codeQLQueryHistory",
           "name": "Query History"
+        },
+        {
+          "id": "codeQLAstViewer",
+          "name": "AST Viewer",
+          "when": "config.codeQL.experimentalAstViewer == true"
         }
       ]
-    }
+    },
+    "viewsWelcome": [
+      {
+        "view": "codeQLAstViewer",
+        "contents": "Run the 'CodeQL: View AST' command on an open source file from a Code QL database.\n[View AST](command:codeQL.viewAst)",
+        "when": "config.codeQL.experimentalAstViewer == true"
+      },
+      {
+        "view": "codeQLQueryHistory",
+        "contents": "Run the 'CodeQL: Run Query' command on QL query.\n[Run Query](command:codeQL.runQuery)"
+      }
+    ]
   },
   "scripts": {
     "build": "gulp",

extensions/ql-vscode/media/light/clear-all.svg

@@ -0,0 +1,102 @@
+import * as vscode from 'vscode';
+
+import { DatabaseItem } from './databases';
+import { UrlValue, BqrsId } from './bqrs-cli-types';
+import fileRangeFromURI from './contextual/fileRangeFromURI';
+import { showLocation } from './interface-utils';
+
+export interface AstItem {
+  id: BqrsId;
+  label?: string;
+  location?: UrlValue;
+  parent: AstItem | RootAstItem;
+  children: AstItem[];
+  order: number;
+}
+
+export type RootAstItem = Omit<AstItem, 'parent'>;
+
+class AstViewerDataProvider implements vscode.TreeDataProvider<AstItem | RootAstItem> {
+
+  public roots: RootAstItem[] = [];
+  public db: DatabaseItem | undefined;
+
+  private _onDidChangeTreeData =
+    new vscode.EventEmitter<AstItem | undefined>();
+  readonly onDidChangeTreeData: vscode.Event<AstItem | undefined> =
+    this._onDidChangeTreeData.event;
+
+  constructor() {
+    vscode.commands.registerCommand('codeQLAstViewer.gotoCode',
+      async (location: UrlValue, db: DatabaseItem) => {
+        if (location) {
+          await showLocation(fileRangeFromURI(location, db));
+        }
+      });
+    }
+
+  refresh(): void {
+    this._onDidChangeTreeData.fire();
+  }
+  getChildren(item?: AstItem): vscode.ProviderResult<(AstItem | RootAstItem)[]> {
+    const children = item ? item.children : this.roots;
+    return children.sort((c1, c2) => (c1.order - c2.order));
+  }
+
+  getParent(item: AstItem): vscode.ProviderResult<AstItem> {
+    return item.parent as AstItem;
+  }
+
+  getTreeItem(item: AstItem): vscode.TreeItem {
+    const line = typeof item.location === 'string'
+      ? item.location
+      : item.location?.startLine;
+
+    const state = item.children.length
+      ? vscode.TreeItemCollapsibleState.Collapsed
+      : vscode.TreeItemCollapsibleState.None;
+    const treeItem = new vscode.TreeItem(item.label || '', state);
+    treeItem.description = line ? `Line ${line}` : '';
+    treeItem.id = String(item.id);
+    treeItem.tooltip = `${treeItem.description} ${treeItem.label}`;
+    treeItem.command = {
+      command: 'codeQLAstViewer.gotoCode',
+      title: 'Go To Code',
+      tooltip: `Go To ${item.location}`,
+      arguments: [item.location, this.db]
+    };
+    return treeItem;
+  }
+}
+
+export class AstViewer {
+  private treeView: vscode.TreeView<AstItem | RootAstItem>;
+  private treeDataProvider: AstViewerDataProvider;
+
+  constructor() {
+    this.treeDataProvider = new AstViewerDataProvider();
+    this.treeView = vscode.window.createTreeView('codeQLAstViewer', {
+      treeDataProvider: this.treeDataProvider,
+      showCollapseAll: true
+    });
+
+    vscode.commands.registerCommand('codeQLAstViewer.clear', () => {
+      this.clear();
+    });
+  }
+
+  updateRoots(roots: RootAstItem[], db: DatabaseItem, fileName: string) {
+    this.treeDataProvider.roots = roots;
+    this.treeDataProvider.db = db;
+    this.treeDataProvider.refresh();
+    this.treeView.message = `AST for ${fileName}`;
+    this.treeView.reveal(roots[0], { focus: true });
+  }
+
+  private clear() {
+    this.treeDataProvider.roots = [];
+    this.treeDataProvider.db = undefined;
+    this.treeDataProvider.refresh();
+    this.treeView.message = undefined;
+  }
+}

extensions/ql-vscode/package.json

@@ -53,9 +53,12 @@ export interface BQRSInfo {
   'result-sets': ResultSetSchema[];
 }
 
+export type BqrsId = number;
+
 export interface EntityValue {
   url?: UrlValue;
   label?: string;
+  id?: BqrsId;
 }
 
 export interface LineColumnLocation {

extensions/ql-vscode/src/astViewer.ts

@@ -93,6 +93,18 @@ export interface TestCompleted {
   expected: string;
 }
 
+/**
+ * Optional arguments for the `bqrsDecode` function
+ */
+interface BqrsDecodeOptions {
+  /** How many results to get. */
+  pageSize?: number;
+  /** The 0-based index of the first result to get. */
+  offset?: number;
+  /** The entity names to retrieve from the bqrs file. Default is url, string */
+  entities?: string[];
+}
+
 /**
  * This class manages a cli server started by `codeql execute cli-server` to
  * run commands without the overhead of starting a new java
@@ -494,12 +506,16 @@ export class CodeQLCliServer implements Disposable {
   * Gets the results from a bqrs.
   * @param bqrsPath The path to the bqrs.
   * @param resultSet The result set to get.
-  * @param pageSize How many results to get.
-  * @param offset The 0-based index of the first result to get.
+  * @param options Optional BqrsDecodeOptions arguments
   */
-  async bqrsDecode(bqrsPath: string, resultSet: string, pageSize?: number, offset?: number): Promise<DecodedBqrsChunk> {
+  async bqrsDecode(
+    bqrsPath: string,
+    resultSet: string,
+    { pageSize, offset, entities = ['url', 'string'] }: BqrsDecodeOptions = {}
+  ): Promise<DecodedBqrsChunk> {
+
     const subcommandArgs = [
-      '--entities=url,string',
+      `--entities=${entities.join(',')}`,
       '--result-set', resultSet,
     ].concat(
       pageSize ? ['--rows', pageSize.toString()] : []

extensions/ql-vscode/src/bqrs-cli-types.ts

@@ -209,3 +209,15 @@ export class QueryHistoryConfigListener extends ConfigListener implements QueryH
     return QUERY_HISTORY_FORMAT_SETTING.getValue<string>();
   }
 }
+
+// Enable experimental features
+
+/**
+ * Any settings below are deliberately not in package.json so that
+ * they do not appear in the settings ui in vscode itself. If users
+ * want to enable experimental features, they can add them directly in
+ * their vscode settings json file.
+ */
+
+/* Advanced setting: used to enable the AST Viewer. */
+export const EXPERIMENTAL_AST_VIEWER = new Setting('experimentalAstViewer', ROOT_SETTING);