Language Server (jaxlint[lsp])

jaxlint ships an optional diagnostics-only language server for editors that speak LSP over stdio. This is v1 scope: publish diagnostics from the same rules as jaxlint check (performance sensors, doc sections, MathJax). Formatting, code actions, completions, and HLO analysis are out of scope for the server.

Install

The server depends on Pygls (pulled in by the lsp extra):

uv sync --extra lsp
# or when installing the package
pip install 'jaxlint[lsp]'

Run

• jaxlint-lsp — console script from [project.scripts] (same as python -m jaxlint.lsp).

• python -m jaxlint.lsp — module entrypoint.

Wire your editor to launch one of the above with stdio transport. There is no TCP or socket mode in this release.

Environment & lifecycle

Environment variable

Variable	Meaning	Default
JAXLINT_LSP_DEBOUNCE_MS	Milliseconds to debounce textDocument/didChange before running diagnostics on the buffer	200. Set to 0 to disable debounce and use the same sequential, immediate republish path as pre-debounce releases.

No other JAXLINT_* environment variables are read by the server (as of 0.1.0a1).

Lifecycle (not configurable via env)

Topic	Behaviour
textDocument/didOpen	Diagnostics run immediately (no debounce).
textDocument/didChange	Debounced by JAXLINT_LSP_DEBOUNCE_MS; superseded runs are cancelled via a generation guard.
textDocument/didClose	Publishes empty diagnostics for the URI and cancels any pending debounced work so editor squiggles clear.
URIs	file:// only; other schemes yield empty diagnostics (same as unsupported files).

Diagnostics, sync, and configuration

Topic	Detail
Diagnostics	In-memory lint of the open buffer; results are published as LSP diagnostics.
Document sync	Full text sync (TextDocumentSyncKind.Full).
Configuration	Resolved with load_config(path.parent) from the file path — same discovery as the CLI (jaxlint.toml then pyproject.toml in each ancestor; native [jaxlint] or legacy [tool.jaxlint] in jaxlint.toml, [tool.jaxlint] only in pyproject.toml).
Disk cache	Not used. The LSP path calls diagnostics_for_python_source with explicit source text and a LintConfig; there is no cache read/write in the server.
CLI overrides	There is no --select / --ignore equivalent in the server; rule selection comes from config only.

Library hook

For tests or custom tooling, use jaxlint.core.diagnostics_for_python_source: same diagnostics as run_checks for a given path and source string, sorted and without touching the on-disk cache. See Library usage.

See also

• CLI reference — terminal workflow and jaxlint check flags (including cache and overrides the LSP does not expose).