Add comments to interfaces.ts and databases-ui.ts

Also, small refactoring of the vscodeMessageHandler.

Author: aeisenberg

extensions/ql-vscode/CHANGELOG.md

@@ -4,12 +4,11 @@
 
 - Add friendly welcome message when the databases view is empty.
 - Add open query, open results, and remove query commands in the query history view title bar.
-- Max number of simultaneous queries launchable by runQueries command is now configurable by changing the codeQL.runningQueries.maxQueries setting.
+- Max number of simultaneous queries launchable by runQueries command is now configurable by changing the `codeQL.runningQueries.maxQueries` setting.
 - Fix sorting of results. Some pages of results would have the wrong sort order and columns.
 - Remember previous sort order when reloading query results.
 - Fix proper escaping of backslashes in SARIF message strings.
 - Allow setting `codeQL.runningQueries.numberOfThreads` and `codeQL.runningTests.numberOfThreads` to 0, (which is interpreted as 'use one thread per core on the machine').
-- Clear the problems view of all Code QL problems when a database is removed.
 - Clear the problems view of all CodeQL query results when a database is removed.
 
 ## 1.3.3 - 16 September 2020

extensions/ql-vscode/src/databases-ui.ts

@@ -103,6 +103,9 @@ class DatabaseTreeDataProvider extends DisposableObject
   private handleDidChangeDatabaseItem = (event: DatabaseChangedEvent): void => {
     // Note that events from the databse manager are instances of DatabaseChangedEvent
     // and events fired by the UI are instances of DatabaseItem
+
+    // When event.item is undefined, then the entire tree is refreshed.
+    // When event.item is a db item, then only that item is refreshed.
     this._onDidChangeTreeData.fire(event.item);
   };
 

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

@@ -86,6 +86,10 @@ export interface ResultsUpdatingMsg {
   t: 'resultsUpdating';
 }
 
+/**
+ * Message to set the initial state of the results view with a new
+ * query.
+ */
 export interface SetStateMsg {
   t: 'setState';
   resultsPath: string;
@@ -109,6 +113,10 @@ export interface SetStateMsg {
   parsedResultSets: ParsedResultSets;
 }
 
+/**
+ * Message indicating that the results view should display interpreted
+ * results.
+ */
 export interface ShowInterpretedPageMsg {
   t: 'showInterpretedPage';
   interpretation: Interpretation;
@@ -127,17 +135,27 @@ export interface NavigatePathMsg {
   direction: number;
 }
 
+/**
+ * A message indicating that the results view should untoggle the
+ * "Show results in Problems view" checkbox.
+ */
 export interface UntoggleShowProblemsMsg {
   t: 'untoggleShowProblems';
 }
 
+/**
+ * A message sent into the results view.
+ */
 export type IntoResultsViewMsg =
   | ResultsUpdatingMsg
   | SetStateMsg
   | ShowInterpretedPageMsg
   | NavigatePathMsg
   | UntoggleShowProblemsMsg;
 
+/**
+ * A message sent from the results view.
+ */
 export type FromResultsViewMsg =
   | ViewSourceFileMsg
   | ToggleDiagnostics
@@ -146,12 +164,21 @@ export type FromResultsViewMsg =
   | ResultViewLoaded
   | ChangePage;
 
+/**
+ * Message from the results view to open a database source
+ * file at the provided location.
+ */
 export interface ViewSourceFileMsg {
   t: 'viewSourceFile';
   loc: ResolvableLocationValue;
   databaseUri: string;
 }
 
+
+/**
+ * Message from the results view to toggle the display of
+ * query diagnostics.
+ */
 interface ToggleDiagnostics {
   t: 'toggleDiagnostics';
   databaseUri: string;
@@ -161,10 +188,18 @@ interface ToggleDiagnostics {
   kind?: string;
 }
 
+/**
+ * Message from the results view to signal that loading the results
+ * is complete.
+ */
 interface ResultViewLoaded {
   t: 'resultViewLoaded';
 }
 
+/**
+ * Message from the results view to signal a request to change the
+ * page.
+ */
 interface ChangePage {
   t: 'changePage';
   pageNumber: number; // 0-indexed, displayed to the user as 1-indexed
@@ -188,6 +223,9 @@ export interface InterpretedResultsSortState {
   sortDirection: SortDirection;
 }
 
+/**
+ * Message from the results view to request a sorting change.
+ */
 interface ChangeRawResultsSortMsg {
   t: 'changeSort';
   resultSetName: string;
@@ -198,6 +236,9 @@ interface ChangeRawResultsSortMsg {
   sortState?: RawResultsSortState;
 }
 
+/**
+ * Message from the results view to request a sorting change in interpreted results.
+ */
 interface ChangeInterpretedResultsSortMsg {
   t: 'changeInterpretedSort';
   /**
@@ -207,28 +248,43 @@ interface ChangeInterpretedResultsSortMsg {
   sortState?: InterpretedResultsSortState;
 }
 
+/**
+ * Message from the compare view to the extension.
+ */
 export type FromCompareViewMessage =
   | CompareViewLoadedMessage
   | ChangeCompareMessage
   | ViewSourceFileMsg
   | OpenQueryMessage;
 
+/**
+ * Message from the compare view to signal the completion of loading results.
+ */
 interface CompareViewLoadedMessage {
   t: 'compareViewLoaded';
 }
 
+/**
+ * Message from the compare view to request opening a query.
+ */
 export interface OpenQueryMessage {
   readonly t: 'openQuery';
   readonly kind: 'from' | 'to';
 }
 
+/**
+ * Message from the compare view to request changing the result set to compare.
+ */
 interface ChangeCompareMessage {
   t: 'changeCompare';
   newResultSetName: string;
 }
 
 export type ToCompareViewMessage = SetComparisonsMessage;
 
+/**
+ * Message to the compare view that specifies the query results to compare.
+ */
 export interface SetComparisonsMessage {
   readonly t: 'setComparisons';
   readonly stats: {

extensions/ql-vscode/src/view/result-tables.tsx

@@ -110,7 +110,7 @@ export class ResultTables
     };
   }
 
-  untoggleProbemsView() {
+  untoggleProblemsView() {
     this.setState({
       problemsViewSelected: false
     });
@@ -286,11 +286,7 @@ export class ResultTables
   // TODO: Duplicated from results.tsx consider a way to
   // avoid this duplication
   componentDidMount(): void {
-    this.vscodeMessageHandler = (evt) =>
-      evt.origin === window.origin
-        ? this.handleMessage(evt.data as IntoResultsViewMsg)
-        : console.error(`Invalid event origin ${evt.origin}`);
-
+    this.vscodeMessageHandler = this.vscodeMessageHandler.bind(this);
     window.addEventListener('message', this.vscodeMessageHandler);
   }
 
@@ -300,9 +296,11 @@ export class ResultTables
     }
   }
 
-  private vscodeMessageHandler:
-    | ((ev: MessageEvent) => void)
-    | undefined = undefined;
+  private vscodeMessageHandler(evt: MessageEvent) {
+    evt.origin === window.origin
+      ? this.handleMessage(evt.data as IntoResultsViewMsg)
+      : console.error(`Invalid event origin ${evt.origin}`);
+  }
 }
 
 class ResultTable extends React.Component<ResultTableProps, {}> {

extensions/ql-vscode/src/view/results.tsx

@@ -287,11 +287,7 @@ class App extends React.Component<{}, ResultsViewState> {
   }
 
   componentDidMount(): void {
-    this.vscodeMessageHandler = (evt) =>
-      evt.origin === window.origin
-        ? this.handleMessage(evt.data as IntoResultsViewMsg)
-        : console.error(`Invalid event origin ${evt.origin}`);
-
+    this.vscodeMessageHandler = this.vscodeMessageHandler.bind(this);
     window.addEventListener('message', this.vscodeMessageHandler);
   }
 
@@ -301,9 +297,11 @@ class App extends React.Component<{}, ResultsViewState> {
     }
   }
 
-  private vscodeMessageHandler:
-    | ((ev: MessageEvent) => void)
-    | undefined = undefined;
+  private vscodeMessageHandler(evt: MessageEvent) {
+    evt.origin === window.origin
+      ? this.handleMessage(evt.data as IntoResultsViewMsg)
+      : console.error(`Invalid event origin ${evt.origin}`);
+  }
 }
 
 Rdom.render(<App />, document.getElementById('root'));

extensions/ql-vscode/src/vscode-tests/no-workspace/databases.test.ts

@@ -27,17 +27,18 @@ describe('databases', () => {
 
   it('should fire events when adding and removing a db item', () => {
     const mockDbItem = {
-      databaseUri: 'file:/abc',
+      databaseUri: { path: 'file:/abc' },
+      name: 'abc',
       getPersistedState() {
-        return this.databaseUri;
+        return this.name;
       }
     };
     const spy = sinon.spy();
     databaseManager.onDidChangeDatabaseItem(spy);
     (databaseManager as any).addDatabaseItem(mockDbItem);
 
     expect((databaseManager as any)._databaseItems).to.deep.eq([mockDbItem]);
-    expect(updateSpy).to.have.been.calledWith('databaseList', ['file:/abc']);
+    expect(updateSpy).to.have.been.calledWith('databaseList', ['abc']);
     expect(spy).to.have.been.calledWith({
       item: undefined,
       kind: DatabaseEventKind.Add
@@ -66,13 +67,14 @@ describe('databases', () => {
     const spy = sinon.spy();
     databaseManager.onDidChangeDatabaseItem(spy);
     (databaseManager as any).addDatabaseItem(mockDbItem);
+    sinon.restore();
 
     databaseManager.renameDatabaseItem(mockDbItem as unknown as DatabaseItem, 'new name');
 
     expect(mockDbItem.name).to.eq('new name');
     expect(updateSpy).to.have.been.calledWith('databaseList', ['new name']);
     expect(spy).to.have.been.calledWith({
-      item: undefined,
+      item: mockDbItem,
       kind: DatabaseEventKind.Rename
     });
   });