Merge remote branch 'origin/master' into edge

Author: automatic-merge

.vscode/settings.json.tmpl

@@ -15,8 +15,6 @@
    "[ada]": {
       "editor.autoIndent": "none",
       "editor.formatOnType": true,
-      "editor.tabSize": 3,
-      "editor.detectIndentation": false,
       "showNotificationsOnErrors": true
    },
    "python.analysis.extraPaths": ["testsuite"],

CHANGELOG.md

@@ -5,6 +5,7 @@ section below it for the last release. -->
 ## \<next>
 
 * Add a setting `ada.showNotificationsOnErrors` to control whether VS Code should display error notifications for failing LSP requests.
+* Add support for a default `.als.json` workspace configuration file and a global `$XDG_CONFIG_HOME/als/config.json` user configuration file. See [settings.md](https://github.com/AdaCore/ada_language_server/blob/master/doc/settings.md) for more information.
 
 ## 26.0.202411173
 

doc/settings.md

@@ -2,17 +2,25 @@
 
 ## Configuration Sources
 
-The ALS can be given configuration settings in the following ways:
+The ALS loads configuration settings from different sources. All configuration sources are loaded in the following order:
 
-1. The `--config CONFIG_FILE` command line option, if specified.
+1. A global user configuration file `$XDG_CONFIG_HOME/als/config.json`, if it exists.
 
-2. The `initializationOptions` property of the `initialize` request, if specified.
+1. A workspace-specific `.als.json` file in the directory where ALS is spawned, if it exists.
 
-3. In `workspace/didChangeConfiguration` LSP notifications.
+   This is the prefered location to store project-specific settings that are tracked in version control and shared among developers.
 
-4. In the User, Remote or Workspace settings of Visual Studio Code, where each setting name is prefixed with `ada.`.
+1. The `--config CONFIG_FILE` file, if specified in the command line.
 
-If given, the configuration file must be a JSON file with the following structure:
+1. The `initializationOptions` property of the `initialize` request, if specified.
+
+1. In `workspace/didChangeConfiguration` LSP notifications, if specified.
+
+Each configuration source can contain a partial list of settings. Thus each
+configuration source can override individual settings while preserving
+previously loaded settings.
+
+Configuration files must be JSON files matching [this JSON schema](integration/vscode/ada/schemas/als-settings-schema.json). Roughly the structure looks like this:
 
 ```json
 {
@@ -57,6 +65,14 @@ Similarly, settings passed in `workspace/didChangeConfiguration` notifications s
 }
 ```
 
+## Base Configuration
+
+The *base configuration* is the one that ALS reaches after loading configuration files (i.e. global user configuration, workspace-specific `.als.json` file, and `--config` command line argument).
+
+After that the ALS may receive configuration changes through the `initialize` request, or the `workspace/didChangeConfiguration` notification. In those messages, if settings have the value `null`, ALS reverts their value to the base configuration. This allows clients to temporarily override settings, and revert them back in the same session.
+
+## Visual Studio Code
+
 In the context of Visual Studio Code, configuration settings can be set in the
 User, Remote or Workspace `settings.json` file or the [multi-root workspace
 file](https://code.visualstudio.com/docs/editor/multi-root-workspaces) by
@@ -73,6 +89,8 @@ prefixing each setting name with `ada.`, e.g.
 }
 ```
 
+These settings are sent to the ALS in the LSP `initialize` request, and then in `workspace/didChangeConfiguration` notifications if they get updated.
+
 ## Settings
 
 Settings taken into account only from the Ada & SPARK VS Code extension:
@@ -325,9 +343,33 @@ This option controls if the `textDocument/onTypeFormatting` request only indents
 it additionally tries to format the previous node. By default, this option is enabled, that is,
 `textDocument/onTypeFormatting` only indents new lines.
 
+In ALS config files, this setting must be specified in a nested form:
+
+```json
+{
+   "onTypeFormatting": {
+      "indentOnly": true
+   }
+}
+```
+
+Conversely, in VS Code this settings can be set without nesting:
+
+```json
+{
+   "ada.onTypeFormatting.indentOnly": true,
+}
+```
+
 ### useGnatformat
 
 This option controls the formatting provider for the `textDocument/formatting`,
 `textDocument/rangeFormatting` and `textDocument/onTypeFormatting` request. By default, this option
 is enabled and ALS uses GNATformat as its formatting provider. If disabled, GNATpp is used instead.
 
+### logThreshold
+
+Controls the maximum number of trace files preserved in the ALS log directory (which defaults to `~/.als`).
+When this threshold is reached, old trace files get deleted automatically.
+The default number of preserved trace files is `10`.
+See the documentation on [ALS Traces](doc/traces.md) for more information.

integration/vscode/ada/.vscode-test.mjs

@@ -35,7 +35,7 @@ if (process.env['MOCHA_GREP']) {
     baseMochaOptions.grep = process.env['MOCHA_GREP'];
 }
 
-const testsuites = ['general', 'gnattest', 'workspace_missing_dirs'];
+const testsuites = ['general', 'workspace_missing_dirs', 'dot-als-json'];
 
 export default defineConfig(
     testsuites.map((suiteName) => {
@@ -65,8 +65,8 @@ export default defineConfig(
 
         return {
             label: `Ada extension testsuite: ${suiteName}`,
-            files: `out/test/suite/${suiteName}/**/*.test.js`,
-            workspaceFolder: `./test/workspaces/${suiteName}`,
+            files: `out/test/${suiteName}/**/*.test.js`,
+            workspaceFolder: `./test/${suiteName}/ws`,
             mocha: mochaOptions,
             env: {
                 // When working remotely on Linux, it is necessary to have "Xvfb
@@ -87,5 +87,5 @@ export default defineConfig(
             // Use external installation if provided in the VSCODE env variable
             useInstallation: process.env.VSCODE ? { fromPath: process.env.VSCODE } : undefined,
         };
-    })
+    }),
 );

integration/vscode/ada/package.json

@@ -281,14 +281,14 @@
                     "ada.projectFile": {
                         "scope": "window",
                         "type": "string",
-                        "default": "",
+                        "default": null,
                         "description": "GPR project file (*.gpr) for this workspace.\n\nIt is recommended to set this to a relative path starting at the root of the workspace.",
                         "order": 0
                     },
                     "ada.scenarioVariables": {
                         "scope": "window",
                         "type": "object",
-                        "default": {},
+                        "default": null,
                         "description": "Scenario variables to apply to the GPR project file.\n\nThis value should be provided as an object where the property names are GPR scenario variables and the values are strings.",
                         "patternProperties": {
                             ".*": {
@@ -300,26 +300,26 @@
                     "ada.projectDiagnostics": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "description": "Controls whether or not the Ada Language Server should emit project diagnostics into the VS Code Problems view.\n\nNote: this setting is ignored if `ada.enableDiagnostics` is disabled and a workspace reload is necessary to refresh the diagnostics after modifying this setting."
                     },
                     "ada.defaultCharset": {
                         "scope": "window",
                         "type": "string",
-                        "default": "iso-8859-1",
+                        "default": null,
                         "description": "The character set that the Ada Language Server should use when reading files from disk."
                     },
                     "ada.relocateBuildTree": {
                         "scope": "window",
                         "type": "string",
-                        "default": "",
+                        "default": null,
                         "description": "The folder for out-of-tree build.",
                         "markdownDescription": "The path to a directory used for out-of-tree builds. This feature is related to the [--relocate-build-tree GPRbuild command line switch](https://docs.adacore.com/gprbuild-docs/html/gprbuild_ug/building_with_gprbuild.html#switches)."
                     },
                     "ada.rootDir": {
                         "scope": "window",
                         "type": "string",
-                        "default": "",
+                        "default": null,
                         "markdownDescription": "This setting must be used in conjunction with the `relocateBuildTree` setting.\n\nIt specifies the root directory for artifact relocation. It corresponds to the [--root-dir GPRbuild command line switch](https://docs.adacore.com/gprbuild-docs/html/gprbuild_ug/building_with_gprbuild.html#switches)."
                     }
                 }
@@ -332,13 +332,13 @@
                     "ada.useGnatformat": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "markdownDescription": "Enable GNATformat as the formatting provider for Ada source files."
                     },
                     "ada.onTypeFormatting.indentOnly": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "markdownDescription": "If the VS Code `editor.formatOnType` setting is enabled, the Ada Language Server will format Ada code while it is being typed in the editor, in particular when a new line is typed.\n\nThis setting controls whether formatting should only perform the indentation of the new line (true) or also format the previous line (false)."
                     }
                 }
@@ -364,7 +364,7 @@
                             "Default style, based on GNAT coding standard with some enhancements.",
                             "Documentation for the entities extracted from the comments before the entity declaration."
                         ],
-                        "default": "gnat",
+                        "default": null,
                         "description": "Controls the primary documentation style of entities."
                     },
                     "ada.displayMethodAncestryOnNavigation": {
@@ -382,43 +382,43 @@
                             "List overriding and/or overridden subprograms on declarations only.",
                             "Always list overriding and/or overridden subprograms when possible."
                         ],
-                        "default": "usage_and_abstract_only",
+                        "default": null,
                         "description": "Controls the policy for displaying overriding and overridden subprograms on navigation requests such as 'Go To Definition' or 'Go To Implementations'."
                     },
                     "ada.enableDiagnostics": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "description": "Controls whether or not the Ada Language Server should emit diagnostics into the VS Code Problems view."
                     },
                     "ada.foldComments": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "description": "Controls whether comments should be folded like code blocks."
                     },
                     "ada.namedNotationThreshold": {
                         "scope": "window",
                         "type": "integer",
-                        "default": 3,
+                        "default": null,
                         "description": "Defines the number of parameters/components beyond which named notation is used for completion snippets."
                     },
                     "ada.useCompletionSnippets": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": false,
+                        "default": null,
                         "description": "Enable snippets in completion results (e.g. subprogram calls)."
                     },
                     "ada.insertWithClauses": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": false,
+                        "default": null,
                         "description": "Enable insertion of missing with-clauses when accepting completion for invisible symbols."
                     },
                     "ada.renameInComments": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": false,
+                        "default": null,
                         "description": "Enable editing Ada comments to update references to an entity when it is being renamed."
                     }
                 }
@@ -430,13 +430,13 @@
                     "ada.enableIndexing": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "description": "Controls whether the Ada Language Server should index the source files immediately after loading a project.\n\nIf set to false, indexing will be deferred to the time when an action requiring the index is first performed, e.g. hovering over a referenced entity to get its documentation."
                     },
                     "ada.followSymlinks": {
                         "scope": "window",
                         "type": "boolean",
-                        "default": true,
+                        "default": null,
                         "description": "Controls the Ada Language Server normalizes the file paths received from the client."
                     },
                     "ada.trace.server": {
@@ -470,10 +470,22 @@
                         ],
                         "default": "off",
                         "description": "Traces the communication between VS Code and the GPR language server in the 'GPR Language Server' Output view."
+                    },
+                    "ada.logThreshold": {
+                        "scope": "window",
+                        "type": "integer",
+                        "default": null,
+                        "description": "Controls the maximum number of trace files preserved in the ALS log directory (which defaults to `~/.als`). When this threshold is reached, old trace files get deleted automatically. The default number of preserved trace files is `10`."
                     }
                 }
             }
         ],
+        "jsonValidation": [
+            {
+                "fileMatch": ".als.json",
+                "url": "./schemas/als-settings-schema.json"
+            }
+        ],
         "problemMatchers": [
             {
                 "name": "ada",