Repository navigation
Description
Goal
Characterize the existing Python/settings boundary before refactoring it. Add a small, meaningful set of shared JSON fixtures, regression tests for observable settings behavior and retained dictionary references, and a real Python language-server stdio smoke test.
This is S2 of the incremental architecture roadmap. It is a test-first, behavior-preserving PR, not the settings redesign. Another agent should be able to implement this issue without access to the original architecture discussion.
Why this matters
This repository is source-integrated into Black, Flake8, Pylint, isort and Mypy. TypeScript resolves settings and sends initializationOptions; Python merges/routes them through ToolServer. Future work will introduce typed definitions, an activation facade and smaller Python services. We first need executable evidence that those changes do not alter any extension's behavior.
The current unit tests are valuable, but python/tests/test_server.py constructs a mocked LanguageServer, and many tests mock URI conversion. They do not prove that a real initialize request reaches ToolServer through pygls, preserves the payload, and completes shutdown/exit over stdio.
Compatibility means each extension retains its own behavior, not that all tools acquire identical defaults or policies.
Current implementation: read these first
Architecture inspection baseline: c65562665144edac11709581cab67c3935696f75. Check the current branch before implementing; the following links are pinned so the observed behavior is reproducible.
| Area | Source |
|---|---|
Settings payload shape (IBaseSettings, IInitOptions) |
typescript/src/types.ts, lines 15-31 |
| Workspace/global settings producers and different fallback contexts | typescript/src/settings.ts, lines 168-278 |
| Actual initialization-options construction | typescript/src/server.ts, around lines 278-282 |
ToolServerConfig, default merging, workspace registration and document/path routing |
python/vscode_common_python_lsp/server.py, lines 33-242 |
| Document-specific CWD substitution | server.py, lines 244-303 |
apply_settings, handle_shutdown, handle_exit |
server.py, lines 479-524 |
| Existing tests to extend instead of duplicating | python/tests/test_server.py, typescript/tests/settings.test.ts |
| Existing runners and checks | noxfile.py, typescript/package.json |
Important observations to preserve:
- The wire shape is
{ "settings": [...], "globalSettings": {...} }. Extra extension-specific keys exist. - Defaults have three layers: extension
package.jsoncontributions, TypeScript scope-specific fallbacks, and Python missing-value fallbacks. Do not flatten these layers. - With no effective setting, TS workspace
importStrategyfalls back touseBundled, TS global settings fall back tofromEnvironment, and Python's missing value falls back touseBundled. These are different contexts, not an instruction to make the values identical. - TS workspace entries carry workspace URIs, but the global settings producer currently sets
workspaceto the plainprocess.cwd()path. Do not silently normalize that field into a URI. - Python
get_global_defaults()projects common keys plus configured tool-specific keys. An unknown global key is retained inglobal_settings, but is not automatically copied into every workspace. Unknown keys sent on an individual workspace are retained there. - Merging is shallow: a provided nested object replaces the default object rather than recursively merging it.
hardcoded_settingsoverrides client globals when computing defaults; do not assume it also overrides a value explicitly present on a workspace.apply_settings()updates the top-level dictionaries in place. Repeated helper calls accumulate/update state rather than implicitly clearing it.- A matching document/path lookup returns the stored workspace settings. Out-of-workspace path lookup and document lookup have different fallback behavior; preserve it.
- There is one server with multiple settings entries, not one server per root.
Deliverable 1: a small shared settings-fixture corpus
Use JSON fixtures that can be consumed by both TypeScript and Python tests. A reasonable location is python/tests/fixtures/settings/; adjust if a simpler existing convention fits. Keep fixture metadata separate from the actual initializationOptions object.
Use temporary directories, Path.as_uri()/the existing URI utilities, and explicit test-only placeholders for machine-specific paths. Do not hardcode a Windows user path or assume POSIX filesystem paths work on Windows.
At least one representative fixture must be exercised by both the TS settings producer and the Python consumer. Use the same on-disk fixture, not two copies that can drift. These remain independent test runners: do not require pytest to build/run Node or the TS suite to launch Python.
Cover a focused selection of cases:
- A normal workspace payload with common fields and an extension-specific nested setting.
- No initialization options, and absent/null/empty
settings, using current CWD/global fallback behavior. - Missing values versus explicit empty arrays,
false, empty strings and representativenullvalues where the current boundary encounters them. Do not convert these all into "missing". If a particular input is currently rejected, do not broaden support in this PR. - Global defaults versus explicit workspace overrides, including the scope-specific
importStrategyfallbacks and shallow object replacement. - Unknown keys at workspace and global scope, preserving their different propagation behavior.
- Nested/multiple workspace roots and a virtual URI without a filesystem path. Use real URI/path conversion for the integration cases.
- One staged CWD-substitution example: host variables resolved by TS, document variables deferred to Python, including fallback when no document is available.
Prefer table-driven extensions to existing tests over recreating every existing assertion in a new test suite.
Example fixture and expected observations
The placeholders below are test substitutions, not new production variable syntax:
{
"globalSettings": {
"args": ["--global"],
"interpreter": ["__PYTHON__"],
"importStrategy": "fromEnvironment",
"severity": {"E": "Warning"},
"unknownGlobal": {"keep": true}
},
"settings": [
{
"workspace": "__ROOT_URI__",
"cwd": "__ROOT_FS__",
"args": [],
"path": [],
"interpreter": [],
"extensionOption": {"enabled": false}
}
]
}For a test ToolServerConfig with default_settings={"severity": {"E": "Error", "W": "Warning"}}, assert:
- Workspace
argsandinterpreterstay[]; they do not regain the global values. - Workspace
importStrategybecomesfromEnvironmentbecause it was omitted in this deliberately partial input. Separately test that a normal TS-produced workspace contains its own fallback. - Workspace
severityis exactly{"E": "Warning"}: do not retain"W"via a new deep merge. extensionOptionsurvives on that workspace.unknownGlobalsurvives inglobal_settings, but is not silently projected into the workspace.workspaceFSis the currently normalized local path derived from__ROOT_URI__.
This partial legacy-input fixture need not itself be emitted verbatim by the normal TS producer. Add a full producer-compatible case for the shared TS/Python assertion.
Deliverable 2: protect settings-reference behavior
Consumers can retain aliases to tool.workspace_settings and tool.global_settings. Add a focused regression case around actual application/update behavior:
workspaces = tool.workspace_settings
globals_ = tool.global_settings
tool.apply_settings(first_initialize_params)
tool.apply_settings(second_initialize_params)
assert tool.workspace_settings is workspaces
assert tool.global_settings is globals_
# Assert the aliases see updated values and currently retained entries.Use real InitializeParams where practical. The repeated calls above exercise the helper in-process; do not send a second LSP initialize request to an already initialized server.
Do not impose a new identity guarantee on each individual workspace value: the existing updater replaces those entries. Also characterize the existing matched-lookup behavior, where the returned settings are the stored object rather than a detached copy.
Deliverable 3: real LSP-over-stdio smoke coverage
Add a tiny test-only Python server fixture that creates a real ToolServer/pygls server and registers initialize, shutdown and exit handlers in the same pattern as consumers. Start it with sys.executable, not a guessed python command.
The test should:
- Send a correctly framed
initializerequest containing a representative fixture. - Receive the matching successful response, and send
initialized. - Verify that the real handler applied the settings. A test-fixture-only request such as
test/settingsmay expose the resulting dictionaries for assertions; do not add this endpoint to production code. - Send
shutdown, read its response, sendexit, and assert bounded successful process termination.
Illustrative request bodies (the harness must add real Content-Length headers and use UTF-8 byte lengths):
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"processId": null,
"rootUri": "__ROOT_URI__",
"capabilities": {},
"initializationOptions": {
"globalSettings": {"importStrategy": "fromEnvironment"},
"settings": [
{"workspace": "__ROOT_URI__", "cwd": "__ROOT_FS__", "args": []}
]
}
}
}{"jsonrpc":"2.0","method":"initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"test/settings","params":{}}
{"jsonrpc":"2.0","id":3,"method":"shutdown","params":null}
{"jsonrpc":"2.0","method":"exit","params":null}Harness requirements:
- Read framed messages and match response IDs; tolerate legitimate interleaved notifications instead of assuming the next message is the desired response.
- Use bounded waits, capture useful stderr on failure, and always clean up/reap the child in
finally. No arbitrary sleeps or Windows-incompatibleselect()on subprocess pipes. - Verify stdout remains protocol-only, and prevent stderr pipe backpressure from hanging the test.
- Ensure both parent and child import this checkout. An unrelated editable installation elsewhere on a developer machine must not accidentally become the tested runtime.
- Do not snapshot the entire pygls capability response or metadata version; assert the stable behavior under this repository's control.
- Require no VS Code extension host, installed formatter/linter, network access, tool subprocess, or optional daemon.
This is the public language-server LSP stdio boundary, not the private tool-worker protocol in jsonrpc.py.
Suggested implementation order
- Read the pinned/current implementation and existing tests; identify gaps instead of duplicating covered cases.
- Add the small fixture corpus and Python characterization cases.
- Exercise a producer-compatible fixture from TS, preserving existing payload shape.
- Add top-level dictionary-alias and matched-lookup regression coverage.
- Add the fixture server and bounded real-stdio smoke test.
- Run targeted tests, then the existing full validation relevant to changed files; summarize any intentional omissions in the PR.
Validation and acceptance criteria
Use the existing sessions and scripts; no new test framework is needed:
python -m nox -s tests
python -m nox -s lint
npm --prefix .\typescript test
npm --prefix .\typescript run build
npm --prefix .\typescript run lintFor a quicker direct Python run, make sure the checkout is installed/editable in the active environment or explicitly bind PYTHONPATH to the checkout's python directory. The subprocess fixture must retain that binding.
- New cases pass against the current implementation without changing production semantics.
- At least one on-disk settings fixture is checked by both TS and Python.
- The real stdio test proves settings application and the initialize/initialized/shutdown/exit sequence, not merely successful process startup.
- Existing Python and TypeScript tests remain green.
- Tests are deterministic on the existing Python CI matrix: Windows/Linux, Python 3.10-3.14. Follow
.nvmrcfor TS validation. - Relevant lint/build checks pass; no unrelated formatting or dependency-lockfile churn.
- A deliberate regression to payload keys, merge precedence, empty-value handling or dictionary replacement would fail an appropriate new test.
Reference baseline from the architecture assessment: 333 Python tests passed, 2 skipped; 145 TypeScript tests passed. Do not hardcode those counts into tests or assume an unchanged count on a newer branch.
Explicit non-goals
- No new wire-version field, strict schema validator, code generation, typed-settings redesign, or changed serialized structure.
- No default normalization across extensions/scopes, automatic derivation of restart-trigger keys, or changing treatment of unknown fields.
- No activation facade, client restart/debounce changes, formatter lifecycle redesign, or new server-per-root behavior.
- No executor/process-manager redesign, RPC concurrency fix, exit-code propagation change, timeout normalization, or dependency upgrades.
- No directory moves, consumer migrations, packaged VSIX/extension-host harness, or broad consumer canary infrastructure; those are later roadmap items.
- No workflow changes from S1. S1 enables the existing TS tests in PR/push CI; it was implemented separately at the time this issue was drafted.
- No cleanup of the 14 pre-existing TypeScript formatting failures.
Related context: #49 (singleton/multi-root architecture) and #70 (partial multi-root settings). Characterize current relevant behavior without expanding S2 into fixes for those issues.
Activity
test: characterize settings contract and real stdio lifecycle (S2) (m…