@mrclrchtr/supi-lsp 10.0.0 → 11.0.0

package/README.md

@@ -20,7 +20,81 @@ npm install @mrclrchtr/supi-lsp
 
 ## Language-server support
 
-The runtime starts an installed server when the project contains a matching file type and, where configured, a root marker. Some built-in servers use extension-based discovery without a root marker. Built-in command names must be on `PATH`; a configured absolute command path is also supported. This table describes diagnostic support, not the full semantic feature set. A push server can still provide hover, definitions, references, symbols, and refactors.
+SuPi provides 13 built-in server definitions. All are enabled unless `lsp.servers.<key>.enabled` is `false`. Install the language servers yourself; SuPi does not download or install them. Built-in commands must be on `PATH`; a configured absolute command path is also supported. Code Intelligence starts the runtime only for trusted projects.
+
+### Built-in route matrix
+
+This matrix describes the default routing configuration, not a live test or a guarantee of every semantic feature. File suffixes are matched without case sensitivity. The configuration stores `fileTypes` without the leading dot.
+
+| Language / config key | Default command and arguments | File extensions | Root markers for automatic discovery |
+|---|---|---|---|
+| TypeScript / JavaScript — `typescript` | `typescript-language-server --stdio` | `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` | `tsconfig.json`, `jsconfig.json`, `package.json` |
+| Python — `python` | `pyright-langserver --stdio` | `.py`, `.pyi` | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `pyrightconfig.json` |
+| Rust — `rust` | `rust-analyzer` | `.rs` | `Cargo.toml` |
+| Go — `go` | `gopls serve` | `.go`, `.mod` | `go.mod`, `go.sum` |
+| C / C++ — `c` | `clangd --background-index` | `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++` | `compile_commands.json`, `CMakeLists.txt`, `.clangd`, `Makefile` |
+| Ruby — `ruby` | `ruby-lsp` | `.rb`, `.erb`, `.gemspec` | `Gemfile`, `.ruby-version` |
+| Java — `java` | `jdtls` | `.java` | `pom.xml`, `build.gradle` |
+| Kotlin — `kotlin` | `kotlin-lsp --stdio` | `.kt`, `.kts` | `build.gradle.kts`, `pom.xml` |
+| Bash / shell — `bash` | `bash-language-server start` | `.sh`, `.bash`, `.zsh`, `.ksh` | None; matching-file scan |
+| HTML — `html` | `vscode-html-language-server --stdio` | `.html`, `.htm`, `.xhtml` | `package.json` |
+| SQL — `sql` | `sql-language-server up --method stdio` | `.sql` | None; matching-file scan |
+| R — `r` | `R --slave -e 'languageserver::run()'` | `.r` | `DESCRIPTION`, `renv.lock`, `.Rprofile` |
+| LaTeX / BibTeX — `latex` | `texlab` | `.tex`, `.bib` | None; matching-file scan |
+
+- Automatic discovery checks installed commands, then root markers or matching files for routes without markers. A marker can detect a route without a matching source file. Exact file requests can start compatible routes lazily. Automatic path exclusions still apply to discovery.
+- `cpp` is a configuration alias for `c`, not a separate server. R also requires the R `languageserver` package. Each route has one default command; SuPi does not try alternative server binaries.
+- Root markers are not file routes. For example, `go.sum` can identify a Go project, but `.sum` and `.work` are not built-in Go file types.
+- `.mod`, `.erb`, and `.bib` have LSP routes but no bundled AST grammar. The built-in Texlab route excludes `.sty` and `.cls`, although [Tree-sitter supports them](../supi-tree-sitter/README.md#language-support-matrix). Texlab document IDs are `latex` for `.tex` and `bibtex` for `.bib`.
+- Unlisted file types have no built-in route. [Custom server configuration](#custom-server-configuration) can add routes or replace commands, arguments, file types, and root markers. This does not add AST support.
+
+Sources: [built-in definitions](src/config/defaults.json), [configuration and suffix matching](src/config/config.ts), and [automatic discovery](src/session/scanner.ts). Regression tests cover [configuration and representative routes](__tests__/unit/config.test.ts) and [discovery](__tests__/unit/scanner.test.ts).
+
+### Semantic feature limits
+
+A configured route is not a ready server. Features depend on the active server, its project state, and its negotiated capabilities. Use `code_health` or `/supi-ci-status` from Code Intelligence to inspect the current state.
+
+| Feature | SuPi support and requirement |
+|---|---|
+| Hover, definitions, references, implementations, document/workspace symbols | Supported through the server's corresponding LSP methods; availability and coverage differ by server. |
+| Diagnostics | Native pull, the eligible TypeScript request adapter, or ambient push. Push observation alone cannot confirm that a file is clean. See the diagnostic policy below. |
+| `rename_symbol` | Requires server rename support and validated text edits; uses `prepareRename` when advertised. |
+| `update_imports` / `delete_dead_code` | Requires matching `source.organizeImports` / `source.removeUnused` code actions that produce validated text edits. |
+| `extract_function` / `extract_variable` | Unavailable for all languages: standard LSP code actions do not provide a safe exact extraction-name contract. |
+
+The [operation-support model](src/config/operation-support.ts) separates server advertisement from SuPi planning limits. A server can advertise an action that SuPi cannot safely turn into a plan.
+
+### Reference-server acceptance
+
+The [Code Intelligence acceptance suite](../supi-code-intelligence/__tests__/acceptance/language-baseline-harness.ts) exercises public tools against real servers for TypeScript, JavaScript, Python, Java, Go, Rust, C, and C++. Its [pinned Linux/macOS configuration](../../scripts/language-baseline/pins.json) is separate from the built-in route matrix. Qualification remains pending until both pinned CI jobs pass. Missing test prerequisites are failures, not skipped passes.
+
+Pyright remains the default Python server, but the audited server lacks implementation lookup. The acceptance suite uses an explicit `lsp.servers.python.command: "basedpyright-langserver"` override with `args: ["--stdio"]`. This does not change existing user configurations or create a fallback. Basedpyright uses its own settings namespace and diagnostic defaults; see the [configuration example](../supi-code-intelligence/README.md#reference-server-verification).
+
+JDTLS acceptance uses a compatible pinned JDK and isolated writable `-data` and `-configuration` directories. Keep test workspaces separate from personal JDTLS state. The [capability baseline](../../docs/conventions/code-language-baseline.md) defines the operation and evidence requirements.
+
+### Java startup and project JDKs
+
+The JDK that starts JDTLS can differ from the JDK that builds your project. Set a compatible server runtime through the Java route without changing the shell or project compiler:
+
+```json
+{
+  "lsp": {
+    "servers": {
+      "java": {
+        "env": { "JAVA_HOME": "/path/to/compatible-server-jdk" }
+      }
+    }
+  }
+}
+```
+
+Use the [pinned acceptance JDK](../../scripts/language-baseline/pins.json) for the reference combination. Do not rely only on the launcher's minimum-version check: bundled Eclipse components can require a newer Java execution environment. If startup exits before `initialize`, inspect the Eclipse configuration log for an unresolved `osgi.ee` / `JavaSE` requirement. An empty stderr tail does not establish that the JDK is compatible.
+
+For concurrent workspaces or isolated checks, pass separate writable `-data` and `-configuration` directories. Do not share a JDTLS data directory between processes. Restart or reload to establish a new runtime settings snapshot after changing the route configuration. SuPi does not select or install a JDK automatically.
+
+### Historical diagnostic audit
+
+The following table describes diagnostic support, not the full semantic feature set. A push server can still provide hover, definitions, references, symbols, and refactors.
 
 The table is a historical initialize-handshake audit performed on 2026-08-21 against the locally installed server versions. It is not a current retest. The TypeScript row also records a separate issue 407 adapter verification on 2026-09-13. That verification did not retest the other server binaries; their audit versions and statuses remain historical. The handshake is authoritative and can report a different mode after an upgrade; treat rows marked `unverified` as unknown until a probe confirms them. Pull-capability facts come from the official LSP specification (pull diagnostics are a 3.17 feature; 3.18 is the current specification at microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification).
 
@@ -77,7 +151,9 @@ Refresh and file collection share synchronization, evidence-revision, deadline,
 
 Caller cancellation or deadline stops only that caller's wait. Explicit diagnostic requests use an owned transport lifetime: supersession drops queued jobs and stops future adapter phases but does not cancel an active protocol request. The route stays occupied until actual settlement or connection disposal. The owner timeout attempts protocol cancellation but does not prove that the backend stopped. The owner bound is at least 30 seconds (or a larger collection budget). A result from an obsolete document generation is discarded. Ordinary semantic requests still pass caller cancellation to the protocol transport.
 
-If another request first opens a document during an active semantic or diagnostic request, the client can synchronize and repeat the request once. The retry retains the caller's original signal and deadline. Content, workspace, close, and lifecycle changes still reject stale results. A diagnostic retry collects new request evidence; it does not promote an old cache. This retry is not route recovery. A second enrollment during the retry still rejects the result. Semantic failure reasons state whether the retry failed or was exhausted. The `semantic-request.enrollment-retry` debug event records retry start and outcome with the public call's opaque operation ID, when supplied. A completed RPC alone does not establish accepted semantic evidence.
+If another request first opens a document during an active semantic or diagnostic request, the client can synchronize and repeat the request once. The retry retains the caller's original signal and deadline. Content, workspace, close, and lifecycle changes still reject stale results. A diagnostic retry collects new request evidence; it does not promote an old cache. This retry is not route recovery. A second enrollment during the retry still rejects the result. Semantic failure reasons state whether the retry failed or was exhausted. The bounded `request.retry` debug event records the retry reason and outcome with the public call's opaque operation ID, when supplied. A completed RPC alone does not establish accepted semantic evidence.
+
+A read-only semantic request can also retry once after an LSP `ContentModified` error (`-32801`). This retry shares the same one-retry budget as enrollment; it does not add another try. The client keeps the original request parameters and checks changes from the first failed input revision. It runs the full input sync before retry and checks current inputs before it accepts a result. An enrollment is still the only input change that can permit a retry. A content, workspace, close, lifecycle, or retirement change blocks it. Client replacement, caller cancellation, and a deadline also block retry. The post-request check rejects a result if inputs change while that attempt runs. This error-code retry applies only to read-only semantic requests. Diagnostics, rename, code actions, and refactors keep the default policy and do not retry `ContentModified`. See the [LSP 3.17 message-ordering rule](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#messageOrdering), the [retry guard](src/client/client-request-enrollment.ts), and the [client query path](src/client/client.ts).
 
 Diagnostic collection does not close and reopen a document to obtain confirmation. It does not send a no-op `didChange` for that purpose. Refresh retains unchanged documents and their current server state, and resynchronizes changed or invalidated documents. A client restart may reopen tracked documents to restore client state; that is recovery, not diagnostic confirmation.
 
@@ -127,6 +203,12 @@ An exact semantic request can still route an excluded file when a compatible ser
 
 Tsconfig and jsconfig filtering applies only to TypeScript and JavaScript-family files (`.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, and `.cjs`). Other-language diagnostics are not filtered by a nearby TypeScript or JavaScript project config. Automatic path exclusions and configured diagnostic suppression still apply. A single-file health result omits the `Tsconfig` coverage line for other languages.
 
+### C-family document languages
+
+The Code Intelligence workspace host can pass ordered, trusted-project [file associations](../supi-code-intelligence/README.md#cc-file-associations). The same snapshot selects the AST grammar and the LSP document language ID. A `.h` file can use `cpp` while retaining the existing `clangd` route. Associations do not change server commands, add suffixes, or establish compiler flags.
+
+Direct library callers can supply a validated `fileAssociations` resolver through `LspRuntimeController` options. Without that option, the existing suffix-based document language IDs remain unchanged. The caller owns configuration trust.
+
 ### Custom server configuration
 
 A custom server needs a command and at least one file type. Advanced server settings are JSON objects. They replace inherited settings as a whole; `initializationOptions` remains a separate initialize value:
@@ -180,6 +262,10 @@ it and otherwise uses direct standard rename. Standard LSP does not provide
 a safe exact extraction-name contract, so `extract_function` and `extract_variable`
 plans report a SuPi planning limitation instead of selecting a generated name.
 
+Rename responses that need additional document state can trigger one bounded discovery/enrollment retry. SuPi validates edit shape and canonical mutation paths, enrolls at most 64 affected files on the same route, and requests fresh edits. The first response is not a plan. Numeric versions must still match. A null version for an open document requires verified synchronized-content evidence; the plan retains the request fingerprint and client version. Missing snapshots, changed inputs, a larger follow-up edit set, and unsafe edits remain unavailable. Planning and apply revalidate these preconditions; no version is discarded to make an edit fit.
+
+Explicit maintenance retires routes whose project roots are confirmed missing or no longer directories. Retirement shuts down the route, clears its failure/recovery state, and prevents pending work from restoring it. Permission errors do not establish removal. Other routes and the workspace runtime owner remain active. Passive inventory reads do not perform this cleanup.
+
 Clients, `LspManager`, and the default runtime implementation remain internal.
 
 ## Runtime split

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/picomatch/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017-present, Jon Schlinkert.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.