test: characterize settings contract and real stdio lifecycle (S2)

CONTRIBUTING.md

@@ -18,6 +18,20 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 2. Make your changes and ensure they pass the existing tests and linting.
 3. Submit a pull request with a clear description of the changes.
 
+### Settings boundary tests
+
+The JSON corpus in `python/tests/fixtures/settings/` characterizes the existing
+initialization-options contract. Fixture metadata is separate from
+`initializationOptions`; `__ROOT_URI__`, `__ROOT_FS__`, `__CWD_FS__`, `__PYTHON__`
+and `__SEP__` are test-only substitutions, not supported settings variables.
+Python and TypeScript tests independently consume `producer.json`, including
+host-resolved CWD variables that Python finishes resolving per document.
+
+`python/tests/test_server_stdio.py` starts a test-only ToolServer over real LSP
+stdio and checks initialize/initialized/settings/shutdown/exit. It needs no tool
+installation, VS Code host or Node build. Repeated settings application is
+covered separately in-process, not by reinitializing a live LSP session.
+
 ## Versioning
 
 This project adheres to [Semantic Versioning (SemVer)](https://semver.org/).

python/tests/fixtures/settings/legacy-partial.json

@@ -0,0 +1,29 @@
+{
+  "description": "Partial client payload: explicit empty arrays, shallow defaults, unknown fields and hardcoded global defaults.",
+  "toolDefaults": {
+    "severity": { "E": "Error", "W": "Warning" }
+  },
+  "hardcodedSettings": {
+    "ignorePatterns": []
+  },
+  "initializationOptions": {
+    "globalSettings": {
+      "args": ["--global"],
+      "interpreter": ["__PYTHON__"],
+      "importStrategy": "fromEnvironment",
+      "severity": { "E": "Warning" },
+      "ignorePatterns": ["global/**"],
+      "unknownGlobal": { "keep": true }
+    },
+    "settings": [
+      {
+        "workspace": "__ROOT_URI__",
+        "cwd": "__ROOT_FS__",
+        "args": [],
+        "path": [],
+        "interpreter": [],
+        "extensionOption": { "enabled": false }
+      }
+    ]
+  }
+}

python/tests/fixtures/settings/producer.json

@@ -0,0 +1,54 @@
+{
+  "description": "Complete producer payload, with host variables resolved and document CWD variables deferred.",
+  "toolDefaults": {
+    "severity": { "E": "Error", "W": "Warning" },
+    "extensionOption": { "enabled": true, "label": "default" }
+  },
+  "configuration": {
+    "workspace": {
+      "cwd": "${workspaceFolder}__SEP__${relativeFileDirname}",
+      "args": [
+        "--label",
+        "café",
+        "--config",
+        "${workspaceFolder}__SEP__tool.toml"
+      ],
+      "path": [],
+      "interpreter": ["__PYTHON__"],
+      "severity": { "E": "Hint" },
+      "extensionOption": { "enabled": false }
+    },
+    "global": {
+      "args": ["--global"],
+      "interpreter": ["__PYTHON__"],
+      "severity": { "E": "Warning" },
+      "extensionOption": { "enabled": true, "label": "global" }
+    }
+  },
+  "initializationOptions": {
+    "settings": [
+      {
+        "cwd": "__ROOT_FS____SEP__${relativeFileDirname}",
+        "workspace": "__ROOT_URI__",
+        "args": ["--label", "café", "--config", "__ROOT_FS____SEP__tool.toml"],
+        "path": [],
+        "interpreter": ["__PYTHON__"],
+        "importStrategy": "useBundled",
+        "showNotifications": "off",
+        "severity": { "E": "Hint" },
+        "extensionOption": { "enabled": false }
+      }
+    ],
+    "globalSettings": {
+      "cwd": "__CWD_FS__",
+      "workspace": "__CWD_FS__",
+      "args": ["--global"],
+      "path": [],
+      "interpreter": ["__PYTHON__"],
+      "importStrategy": "fromEnvironment",
+      "showNotifications": "off",
+      "severity": { "E": "Warning" },
+      "extensionOption": { "enabled": true, "label": "global" }
+    }
+  }
+}

python/tests/fixtures/settings_server.py

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Test-only public LSP server; never invokes a formatter or linter."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+from typing import Any
+
+import lsprotocol.types as lsp
+
+import vscode_common_python_lsp.server as server_module
+from vscode_common_python_lsp.server import ToolServer, ToolServerConfig
+
+
+def main() -> None:
+    fixture_path = pathlib.Path(__file__).parent / "settings" / "producer.json"
+    fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+    tool = ToolServer(
+        ToolServerConfig(
+            tool_module="settings-fixture",
+            tool_display="Settings Fixture",
+            default_settings=fixture["toolDefaults"],
+        )
+    )
+    initialized_received = False
+
+    @tool.server.feature(lsp.INITIALIZE)
+    def initialize(params: lsp.InitializeParams) -> None:
+        tool.apply_settings(params)
+        tool.log_to_output("fixture initialize applied")
+
+    @tool.server.feature(lsp.INITIALIZED)
+    def initialized(_params: lsp.InitializedParams) -> None:
+        nonlocal initialized_received
+        initialized_received = True
+        tool.log_to_output("fixture initialized")
+
+    @tool.server.feature("test/settings")
+    def inspect_settings(_params: Any) -> dict[str, Any]:
+        return {
+            "settings": tool.workspace_settings,
+            "globalSettings": tool.global_settings,
+            "initialized": initialized_received,
+            "serverModule": server_module.__file__,
+        }
+
+    @tool.server.feature(lsp.SHUTDOWN)
+    def shutdown(_params: Any) -> None:
+        tool.handle_shutdown()
+        print("fixture shutdown complete", file=sys.stderr, flush=True)
+
+    @tool.server.feature(lsp.EXIT)
+    def exit_server(_params: Any) -> None:
+        tool.handle_exit()
+        print("fixture exit complete", file=sys.stderr, flush=True)
+
+    tool.server.start_io()
+
+
+if __name__ == "__main__":
+    main()

python/tests/settings_fixtures.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Load the on-disk settings contract shared with the TypeScript tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+from typing import Any
+
+
+def load_settings_fixture(name: str, root: pathlib.Path) -> dict[str, Any]:
+    """Expand test-only path placeholders without changing payload values."""
+    replacements = {
+        "__ROOT_URI__": root.as_uri(),
+        "__ROOT_FS__": str(root),
+        "__CWD_FS__": os.getcwd(),
+        "__PYTHON__": sys.executable,
+        "__SEP__": os.sep,
+    }
+
+    def expand(value: Any) -> Any:
+        if isinstance(value, str):
+            for token, replacement in replacements.items():
+                value = value.replace(token, replacement)
+            return value
+        if isinstance(value, list):
+            return [expand(item) for item in value]
+        if isinstance(value, dict):
+            return {key: expand(item) for key, item in value.items()}
+        return value
+
+    fixture_path = (
+        pathlib.Path(__file__).parent / "fixtures" / "settings" / f"{name}.json"
+    )
+    return expand(json.loads(fixture_path.read_text(encoding="utf-8")))