Add root-file setting. (#83)

Add a new optional `Root File` setting to control the FASTBuild root `fbuild.bff` file. The root file normally does not need to be specified in the settings because it is detected automatically when it is in a parent directory. But it is necessary to set when invoking FASTBuild with the `-config <path>` command line option, which overrides the root file.

For example, if you have the following files and run FASTBuild with `fbuild -config <workspace_root>/Projects/fbuild.bff`:
```
<workspace_root>/Projects/fbuild.bff
<workspace_root>/Projects/HelloWorld/HelloWorld.bff
<workspace_root>/External/MSVC/MSVC.bff
```
In this example, `MSVC.bff` by default cannot find the root `fbuild.bff`. So it is necessary to use the `Root File` setting to manually specify the root.

This new setting is the first that the user can set to an invalid value (an invalid path). Handle that by adding settings validation and output of settings-error diagnostics.

This is also the first time that changing a setting can invalidate already-evaluated data. So clear the cached results when the settings change.

Now that getting the root file relies on settings, which arrives async, various other functions need to also become async.

Fixes #82.

Author: harrisont

CHANGELOG.md

@@ -1,3 +1,17 @@
+# v0.16.0
+
+## New Features
+
+* ([#82](https://github.com/harrisont/fastbuild-vscode/issues/82)) Add a new optional `Root File` setting to control the FASTBuild root `fbuild.bff` file. The root file normally does not need to be specified in the settings because it is detected automatically when it is in a parent directory. But it is necessary to set when invoking FASTBuild with the `-config <path>` command line option, which overrides the root file.
+
+For example, if you have the following files and run FASTBuild with `fbuild -config <workspace_root>/Projects/fbuild.bff`:
+```
+<workspace_root>/Projects/fbuild.bff
+<workspace_root>/Projects/HelloWorld/HelloWorld.bff
+<workspace_root>/External/MSVC/MSVC.bff
+```
+In this example, `MSVC.bff` by default cannot find the root `fbuild.bff`. So it is necessary to use the `Root File` setting to manually specify the root.
+
 # v0.15.0
 
 ## New Features

package.json

@@ -2,7 +2,7 @@
 	"name": "fastbuild-support",
 	"displayName": "FASTBuild Support",
 	"description": "FASTBuild language support. Includes go-to definition, find references, variable evaluation, syntax errors, etc.",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"preview": true,
 	"publisher": "HarrisonT",
 	"author": {
@@ -52,7 +52,23 @@
 			"type": "object",
 			"title": "FASTBuild",
 			"properties": {
+				"fastbuild.inputDebounceDelay": {
+					"order": 0,
+					"scope": "window",
+					"type": "number",
+					"minimum": 0,
+					"default": 500,
+					"description": "Delay, in milliseconds, after changing a document before re-evaluating it. A lower value can result in faster feedback, but too low of a value will result in high resource usage when typing quickly."
+				},
+				"fastbuild.rootFile": {
+					"order": 1,
+					"scope": "window",
+					"type": "string",
+					"default": "",
+					"markdownDescription": "Optional absolute path to the root `fbuild.bff` file. Set when running FASTBuild with the `-config <path>` command line option. The root is automatically found when it is in a parent directory, so it is not necessary to specify in that case."
+				},
 				"fastbuild.trace.server": {
+					"order": 2,
 					"scope": "window",
 					"type": "string",
 					"enum": [
@@ -69,17 +85,11 @@
 					"description": "[Extension debugging] Traces the communication between the extension and the language server."
 				},
 				"fastbuild.logPerformanceMetrics": {
+					"order": 3,
 					"scope": "window",
 					"type": "boolean",
 					"default": false,
 					"description": "[Extension debugging] Log performance metrics."
-				},
-				"fastbuild.inputDebounceDelay": {
-					"scope": "window",
-					"type": "number",
-					"minimum": 0,
-					"default": 500,
-					"description": "Delay, in milliseconds, after changing a document before re-evaluating it. A lower value can result in faster feedback, but too low of a value will result in high resource usage when typing quickly."
 				}
 			}
 		}

server/src/features/diagnosticProvider.ts

@@ -20,6 +20,10 @@ import {
     InternalEvaluationError,
 } from '../evaluator';
 
+import {
+    SettingsError
+} from '../settings';
+
 const SOURCE_NAME = 'FASTBuild';
 
 type UriStr = string;
@@ -52,14 +56,24 @@ function convertErrorRelatedInformation(info: ErrorRelatedInformation): Diagnost
     };
 }
 
+// The settings are not a URI that we know, so just use a made-up URI.
+const SETTINGS_URI = "Settings";
+
 export class DiagnosticProvider {
     hasDiagnosticRelatedInformationCapability = false;
     readonly _documentRootToDocumentsWithDiagnosticsMap = new Map<UriStr, Set<UriStr>>();
 
+    setSettingsErrorDiagnostic(errors: SettingsError[], connection: Connection): void {
+        const range: Range = Range.create(0, 0, 0, 0);
+        const relatedInformation: DiagnosticRelatedInformation[] = [];
+        const diagnostics = errors.map(error => createDiagnosticError(error.message, range, relatedInformation));
+        connection.sendDiagnostics({ uri: SETTINGS_URI, diagnostics });
+    }
+
     setParseErrorDiagnostic(rootUri: UriStr, error: ParseError, connection: Connection): void {
         const relatedInformation: DiagnosticRelatedInformation[] = [];
         const diagnostic = createDiagnosticError(error.message, error.range, relatedInformation);
-        this._setDiagnostic(rootUri, error.fileUri, [diagnostic], connection);
+        this._setFileDiagnostic(rootUri, error.fileUri, [diagnostic], connection);
     }
 
     setEvaluationErrorDiagnostic(rootUri: UriStr, errors: EvaluationError[], connection: Connection): void {
@@ -82,7 +96,7 @@ export class DiagnosticProvider {
         }
 
         for (const [uri, diagnostics] of uriToDiagnostics) {
-            this._setDiagnostic(rootUri, uri, diagnostics, connection);
+            this._setFileDiagnostic(rootUri, uri, diagnostics, connection);
         }
     }
 
@@ -92,10 +106,10 @@ export class DiagnosticProvider {
         const message = `Internal error: ${error.stack ?? error.message}`;
         const relatedInformation: DiagnosticRelatedInformation[] = [];
         const diagnostic = createDiagnosticError(message, Range.create(0, 0, 0, 0), relatedInformation);
-        this._setDiagnostic(rootUri, uri, [diagnostic], connection);
+        this._setFileDiagnostic(rootUri, uri, [diagnostic], connection);
     }
 
-    private _setDiagnostic(rootUri: UriStr, uri: UriStr, diagnostics: Diagnostic[], connection: Connection): void {
+    private _setFileDiagnostic(rootUri: UriStr, uri: UriStr, diagnostics: Diagnostic[], connection: Connection): void {
         const publishDiagnosticsParams: PublishDiagnosticsParams = { uri, diagnostics };
         connection.sendDiagnostics(publishDiagnosticsParams);
         const documentsForRoot = this._documentRootToDocumentsWithDiagnosticsMap.get(rootUri);
@@ -107,13 +121,19 @@ export class DiagnosticProvider {
     }
 
     clearDiagnostics(connection: Connection): void {
+        this.clearSettingsDiagnostics(connection);
+
         for (const documentsForRoot of this._documentRootToDocumentsWithDiagnosticsMap.values()) {
             for (const uri of documentsForRoot) {
                 connection.sendDiagnostics({ uri, diagnostics: [] });
             }
         }
     }
 
+    clearSettingsDiagnostics(connection: Connection): void {
+        connection.sendDiagnostics({ uri: SETTINGS_URI, diagnostics: [] });
+    }
+
     clearDiagnosticsForRoot(rootUri: UriStr, connection: Connection): void {
         const documentsForRoot = this._documentRootToDocumentsWithDiagnosticsMap.get(rootUri);
         if (documentsForRoot === undefined) {