IntelliSense auto-analysis integration

* Reworked DeviceContext for fine grained event generation on settings change
* Added dedicated settings classes which allows for the latter
* Changed board manager and serial monitor to used the new fine grained events instead of the "something changed event" - which makes the code marginally more efficient
* Implemented an analysis manager which takes care of analysis requests generated by settings change events and makes sure that analysis builds don't interfere with regular builds
* Adapted the build infrastructure within ArduinoApp such that it allows for the above
* Removed the global build guard and moved it to ArduinoApp (there is a corner case though for programmer selection within extension.ts which I marked with a TODO
* Fixed some linting issues but did not lint most of the stuff committed here - this will be part of a later commit
* I left notes here and there where I saw things which should/could be improved/changed
* Removed the try/catch guards from the build invocations within extension.ts since exceptions are handled within the build function itself
* Changed the project setting parameter for the IntelliSense setup to reflect its workings better

Author: elektronikworkshop

misc/arduinoValidator.json

@@ -33,7 +33,7 @@
             "type": "string",
             "minLength": 1
         },
-        "disableIntelliSenseAutoGen": {
+        "intelliSenseGen": {
             "description": "Disable/enable the automatic generation of the IntelliSense configuration file (c_cpp_properties.json) for this project (overrides the global setting). When set to \"global\" the global extension settings will be used.",
             "type": "string",
             "default": "global",

src/arduino/arduino.ts

@@ -208,7 +208,7 @@ export class ArduinoContentProvider implements vscode.TextDocumentContentProvide
         } else {
             try {
                 // IS-REMOVE: to be removed completely when IntelliSense implementation is merged
-                //await ArduinoContext.arduinoApp.addLibPath(req.body.libraryPath);
+                // await ArduinoContext.arduinoApp.addLibPath(req.body.libraryPath);
                 await ArduinoContext.arduinoApp.includeLibrary(req.body.libraryPath);
                 return res.json({
                     status: "OK",

src/arduino/arduinoContentProvider.ts

@@ -73,7 +73,10 @@ export class BoardManager {
         this._boardConfigStatusBar.show();
 
         const dc = DeviceContext.getInstance();
-        dc.onDidChange(() => {
+        dc.onChangeBoard(() => {
+            this.updateStatusBar();
+        });
+        dc.onChangeConfiguration(() => {
             this.updateStatusBar();
         });
     }
@@ -124,7 +127,7 @@ export class BoardManager {
         dc.configuration = this._currentBoard.customConfig;
         this._boardConfigStatusBar.text = targetBoard.name;
         // IS-REMOVE: to be removed completely when IntelliSense implementation is merged
-        //this._arduinoApp.addLibPath(null);
+        // this._arduinoApp.addLibPath(null);
 
         this._onBoardTypeChanged.fire();
     }

src/arduino/boardManager.ts

@@ -1,3 +1,6 @@
+// Copyright (c) Elektronik Workshop. All rights reserved.
+// Licensed under the MIT license.
+
 import * as ccp from "cocopa";
 import * as path from "path";
 
@@ -23,7 +26,7 @@ export function isCompilerParserEnabled(dc?: DeviceContext) {
         dc = DeviceContext.getInstance();
     }
     const globalDisable = VscodeSettings.getInstance().disableIntelliSenseAutoGen;
-    const projectSetting = dc.disableIntelliSenseAutoGen;
+    const projectSetting = dc.intelliSenseGen;
     return projectSetting !== "disable" && !globalDisable ||
            projectSetting === "enable";
 }
@@ -93,6 +96,8 @@ function makeCompilerParserEngines(dc: DeviceContext) {
     const dotcpp = sketch.endsWith(".ino") ? ".cpp" : "";
     sketch = `-o\\s+\\S*${ccp.regExEscape(sketch)}${dotcpp}\\.o`;
 
+    // TODO: handle other architectures here
+    
     const matchPattern = [
         // make sure we're running g++
         /(?:^|-)g\+\+\s+/,
@@ -111,3 +116,192 @@ function makeCompilerParserEngines(dc: DeviceContext) {
     const gccParserEngine = new ccp.ParserGcc(matchPattern, dontMatchPattern);
     return [gccParserEngine];
 }
+
+/**
+ * Possible states of AnalysisManager's state machine.
+ */
+enum AnalysisState {
+    /**
+     * No analysis request pending.
+     */
+    Idle = "idle",
+    /**
+     * Analysis request pending. Waiting for the time out to expire or for
+     * another build to complete.
+     */
+    Waiting = "waiting",
+    /**
+     * Analysis in progress.
+     */
+    Analyzing = "analyzing",
+    /**
+     * Analysis in progress with yet another analysis request pending.
+     * As soon as the current analysis completes the manager will directly
+     * enter the Waiting state.
+     */
+    AnalyzingWaiting = "analyzing and waiting",
+}
+
+/**
+ * Events (edges) which cause state changes within AnalysisManager.
+ */
+enum AnalysisEvent {
+    /**
+     * The only external event. Requests an analysis to be run.
+     */
+    AnalysisRequest,
+    /**
+     * The internal wait timeout expired.
+     */
+    WaitTimeout,
+    /**
+     * The current analysis build finished.
+     */
+    AnalysisBuildDone,
+}
+
+/**
+ * This class manages analysis builds for the automatic IntelliSense
+ * configuration synthesis. Its primary purposes are:
+ * 
+ *  * delaying analysis requests caused by DeviceContext setting change
+ *      events such that multiple subsequent requests don't cause
+ *      multiple analysis builds
+ *  * make sure that an analysis request is postponed when another build
+ *      is currently in progress
+ *
+ * TODO: initialization sequence: make sure events generated
+ *   during initialization are not lost
+ *
+ * TODO: check time of c_cpp_properties.json and compare it with
+ * * arduino.json
+ * * main sketch file
+ * This way we can perhaps optimize this further. But be aware
+ * that settings events fire before their corresponding values
+ * are actually written to arduino.json -> time of arduino.json
+ * is outdated if no countermeasure is taken.
+ */
+export class AnalysisManager {
+
+    /** The manager's state. */
+    private _state: AnalysisState = AnalysisState.Idle;
+    /** A callback used by the manager to query if the build backend is busy. */
+    private _isBuilding: () => boolean;
+    /** A callback used by the manager to initiate an analysis build. */
+    private _doBuild: () => Promise<void>;
+    /** Timeout for the timeouts/delays in milliseconds. */
+    private _waitPeriodMs: number;
+    /** The internal timer used to implement the above timeouts and delays. */
+    private _timer: NodeJS.Timer;
+
+    /**
+     * Constructor.
+     * @param isBuilding Provide a callback which returns true if another build
+     * is currently in progress.
+     * @param doBuild Provide a callback which runs the analysis build.
+     * @param waitPeriodMs The delay the manger should wait for potential new
+     * analysis request. This delay is used as polling interval as well when
+     * checking for ongoing builds.
+     */
+    constructor(isBuilding:() => boolean,
+                doBuild: () => Promise<void>,
+                waitPeriodMs: number = 1000) {
+        this._isBuilding = isBuilding;
+        this._doBuild = doBuild;
+        this._waitPeriodMs = waitPeriodMs;
+    }
+
+    /**
+     * File an analysis request.
+     * The analysis will be delayed until no further requests are filed
+     * within a wait period or until any build in progress has terminated.
+     */
+    public async requestAnalysis() {
+        console.log("requesting analysis");
+        await this.update(AnalysisEvent.AnalysisRequest);
+    }
+
+    /**
+     * Update the manager's state machine.
+     * @param event The event which will cause the state transition.
+     * 
+     * Implementation note: asynchronous edge actions must be called after
+     * setting the new state since they don't return immediately. 
+     */
+    private async update(event: AnalysisEvent) {
+
+        switch (this._state) {
+
+            case AnalysisState.Idle:
+                if (event == AnalysisEvent.AnalysisRequest) {
+                    this._state = AnalysisState.Waiting;
+                    this.startWaitTimeout();
+                }
+                break;
+
+            case AnalysisState.Waiting:
+                if (event == AnalysisEvent.AnalysisRequest) {
+                    // every new request restarts timer
+                    this.startWaitTimeout();
+                } else if (event == AnalysisEvent.WaitTimeout) {
+                    if (this._isBuilding()) {
+                        // another build in progress, continue waiting
+                        this.startWaitTimeout();
+                    } else {
+                        // no other build in progress -> launch analysis
+                        this._state = AnalysisState.Analyzing;
+                        await this.startAnalysis();
+                    }
+                }
+                break;
+
+            case AnalysisState.Analyzing:
+                if (event == AnalysisEvent.AnalysisBuildDone) {
+                    this._state = AnalysisState.Idle;
+                } else if (event == AnalysisEvent.AnalysisRequest) {
+                    this._state = AnalysisState.AnalyzingWaiting;
+                }
+                break;
+
+            case AnalysisState.AnalyzingWaiting:
+                if (event == AnalysisEvent.AnalysisBuildDone) {
+                    // emulate the transition from idle to waiting
+                    // (we don't care if this adds an additional
+                    // timeout - event driven analysis is not time-
+                    // critical)
+                    this._state = AnalysisState.Idle;
+                    await this.update(AnalysisEvent.AnalysisRequest);
+                }
+                break;
+        }
+    }
+
+    /**
+     * Starts the wait timeout timer.
+     * If it's already running, the current timer is stopped and restarted.
+     * The timeout callback will then update the state machine.
+     */
+    private startWaitTimeout() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+        }
+        this._timer = setTimeout(() => {
+            this.update(AnalysisEvent.WaitTimeout);
+            this._timer = undefined;
+        }, this._waitPeriodMs);
+    }
+
+    /**
+     * Starts the analysis build.
+     * When done, the callback will update the state machine.
+     */
+    private async startAnalysis() {
+        await this._doBuild()
+        .then(() => {
+            this.update(AnalysisEvent.AnalysisBuildDone);
+        })
+        .catch((reason) => {
+            this.update(AnalysisEvent.AnalysisBuildDone);
+        });
+    }
+}

src/arduino/intellisense.ts

@@ -19,6 +19,8 @@ class ArduinoContext {
         this._arduinoApp = value;
     }
 
+    // TODO EW: This is redundant: the board manager is already part of
+    // the arduino app
     public get boardManager() {
         return this._boardManager;
     }
@@ -38,6 +40,10 @@ class ArduinoContext {
         return this._debuggerManager;
     }
 
+    // TODO EW: You don't have to initialize members to null
+    //  if they don't get a default value or aren't initialized
+    //  within a constructor they are "undefined" by default.
+    //  This makes comparing against null (above) superfluous.
     private _arduinoApp: ArduinoApp = null;
     private _debuggerManager: DebuggerManager = null;
     private _boardManager: BoardManager = null;

src/arduinoContext.ts

@@ -267,7 +267,7 @@ export function tryParseJSON(jsonString: string) {
         }
     } catch (ex) { }
 
-    return false;
+    return undefined;
 }
 
 export function isJunk(filename: string): boolean {