Merge pull request #51 from narumiruna/feat/pi-lsp-language-routing

feat(pi-lsp): route tools by language

Author: narumiruna

docs/implementation-notes/pi-lsp-parity-checklist.md

@@ -1,16 +1,30 @@
 # pi-lsp parity checklist
 
-`@narumitw/pi-lsp` keeps the public tool Interface from the now-deprecated `@narumitw/pi-biome-lsp` and `@narumitw/pi-python-lsp` packages while moving common LSP behavior into a shared runner Module.
+`@narumitw/pi-lsp` keeps Biome, ty, and Ruff behavior from the now-deprecated `@narumitw/pi-biome-lsp` and `@narumitw/pi-python-lsp` packages while exposing a smaller language/file-extension routed public tool interface.
 
 ## Tool names and parameters
 
-- [x] `biome_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
-- [x] `biome_lsp_format`: `path`, `root?`, `write?`.
-- [x] `biome_lsp_fix`: `path`, `root?`, `kind?`, `write?`; default kind `source.fixAll.biome`.
-- [x] `ty_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
-- [x] `ruff_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
-- [x] `ruff_lsp_format`: `path`, `root?`, `write?`.
-- [x] `ruff_lsp_fix`: `path`, `root?`, `kind?`, `write?`; default kind `source.fixAll.ruff`.
+- [x] `lsp_diagnostics`: `paths?`, `root?`, `limit?`, `language?`, `checker?`.
+  - [x] Biome-supported web/config diagnostics route to Biome.
+  - [x] Python `checker: "type"` diagnostics route to ty.
+  - [x] Python `checker: "lint"` diagnostics route to Ruff.
+  - [x] Python `checker: "all"` diagnostics route to both ty and Ruff.
+- [x] `lsp_format`: `path`, `root?`, `write?`, `language?`.
+  - [x] Biome-supported web/config files route to Biome.
+  - [x] Python `.py`/`.pyi` files route to Ruff.
+- [x] `lsp_fix`: `path`, `root?`, `kind?`, `write?`, `language?`.
+  - [x] Biome-supported web/config files route to Biome; default kind `source.fixAll.biome`.
+  - [x] Python `.py`/`.pyi` files route to Ruff; default kind `source.fixAll.ruff`.
+
+## Migration from deprecated public tool names
+
+- [x] `biome_lsp_diagnostics` maps to `lsp_diagnostics` with `language: "web"` when an override is needed.
+- [x] `biome_lsp_format` maps to `lsp_format` for a Biome-supported file.
+- [x] `biome_lsp_fix` maps to `lsp_fix` for a Biome-supported file.
+- [x] `ty_lsp_diagnostics` maps to `lsp_diagnostics` with `language: "python"`, `checker: "type"`.
+- [x] `ruff_lsp_diagnostics` maps to `lsp_diagnostics` with `language: "python"`, `checker: "lint"`.
+- [x] `ruff_lsp_format` maps to `lsp_format` for a Python file.
+- [x] `ruff_lsp_fix` maps to `lsp_fix` for a Python file.
 
 ## Server commands and environment variables
 
@@ -30,20 +44,22 @@
 ## LSP behavior
 
 - [x] Shared runner owns JSON-RPC framing, subprocess lifecycle, initialize/shutdown, file open/close, diagnostics, formatting, code actions, action resolution, and workspace edit application.
-- [x] Biome Adapter keeps dynamic registration capabilities, publish-diagnostics fallback, workspace-folder request handling, tab size 2, and tabs.
-- [x] ty Adapter keeps diagnostic requests without code actions, tab size 4, and spaces.
-- [x] Ruff Adapter keeps diagnostic requests, code actions, tab size 4, and spaces.
+- [x] Biome adapter keeps dynamic registration capabilities, publish-diagnostics fallback, workspace-folder request handling, tab size 2, and tabs.
+- [x] ty adapter keeps diagnostic requests without code actions, tab size 4, and spaces.
+- [x] Ruff adapter keeps diagnostic requests, code actions, tab size 4, and spaces.
+- [x] Route selection is centralized above the adapters and prevents ty from being selected for format/fix.
 
 ## Result shapes and messages
 
 - [x] Tool results still return `{ content: [{ type: "text", text }], details }`.
-- [x] Diagnostics details include `root`, `command`, `files`, and `summary`.
+- [x] Diagnostics details include root, selected routes, backend details, files, and summaries.
 - [x] Format/fix details include `path`, `uri`, `changed`, `write`, `edits`, and preview `text` when `write` is false.
 - [x] Fix details include `kind` and resolved `actions`.
 - [x] Missing-command errors preserve server-specific install guidance.
+- [x] Unsupported extensions and contradictory language overrides produce route errors that name supported language/file-extension classes.
 
 ## Documentation and compatibility
 
-- [x] `extensions/pi-lsp/README.md` documents tool-name compatibility, environment variables, and the deprecated status for the old packages.
+- [x] `extensions/pi-lsp/README.md` documents the three routed tools, environment variables, and migration from old tool names.
 - [x] Root `README.md`, `package.json`, and `justfile` include `pi-lsp` integration.
 - [x] `pi-biome-lsp` and `pi-python-lsp` now live under `extensions/deprecated/` and are excluded from active workspace scripts.

extensions/pi-lsp/README.md

@@ -2,18 +2,18 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-lsp)](https://www.npmjs.com/package/@narumitw/pi-lsp) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-lsp` is a native [Pi coding agent](https://pi.dev) extension that exposes Biome, ty, and Ruff language-server tools through one shared LSP runner Module.
+`@narumitw/pi-lsp` is a native [Pi coding agent](https://pi.dev) extension that exposes Biome, ty, and Ruff language-server behavior through language/file-extension routed Pi tools.
 
 It supersedes the older split packages `@narumitw/pi-biome-lsp` and `@narumitw/pi-python-lsp`, which now live under `extensions/deprecated/` and are excluded from active workspace scripts.
 
 ## ✨ Features
 
-- Runs `biome lsp-proxy` on demand for diagnostics, formatting, import organization, and source fixes.
-- Runs `ty server` on demand for Python type diagnostics.
-- Runs `ruff server` on demand for Python lint diagnostics, formatting, import organization, and source fixes.
+- Routes Biome-supported web/config files to `biome lsp-proxy` for diagnostics, formatting, import organization, and source fixes.
+- Routes Python `.py` and `.pyi` type diagnostics to `ty server`.
+- Routes Python `.py` and `.pyi` lint diagnostics, formatting, import organization, and source fixes to `ruff server`.
 - Uses one internal LSP runner for JSON-RPC framing, subprocess lifecycle, diagnostics, formatting, code actions, and workspace edit application.
-- Keeps Biome, ty, and Ruff behavior in small server Adapters.
-- Supports workspace roots, file limits, recursive file discovery, and write-or-preview edits.
+- Keeps Biome, ty, and Ruff behavior in small server adapters.
+- Supports workspace roots, file limits, recursive file discovery, language overrides, and write-or-preview edits.
 - Starts language servers only for tool calls, then shuts them down.
 - Shows statusline activity only while LSP tools are running.
 
@@ -37,17 +37,19 @@ pi -e ./extensions/pi-lsp
 
 ## ⚠️ Tool-name compatibility
 
-This package intentionally registers the same tool names as `@narumitw/pi-biome-lsp` and `@narumitw/pi-python-lsp`:
+This package now exposes three language/file-extension routed tools instead of the old backend-specific tool names:
 
-- `biome_lsp_diagnostics`
-- `biome_lsp_format`
-- `biome_lsp_fix`
-- `ty_lsp_diagnostics`
-- `ruff_lsp_diagnostics`
-- `ruff_lsp_format`
-- `ruff_lsp_fix`
+| Old tool | New call |
+| --- | --- |
+| `biome_lsp_diagnostics` | `lsp_diagnostics` with `language: "web"` when an override is needed |
+| `biome_lsp_format` | `lsp_format` for a Biome-supported file |
+| `biome_lsp_fix` | `lsp_fix` for a Biome-supported file |
+| `ty_lsp_diagnostics` | `lsp_diagnostics` with `language: "python"`, `checker: "type"` |
+| `ruff_lsp_diagnostics` | `lsp_diagnostics` with `language: "python"`, `checker: "lint"` |
+| `ruff_lsp_format` | `lsp_format` for a Python file |
+| `ruff_lsp_fix` | `lsp_fix` for a Python file |
 
-Avoid installing `@narumitw/pi-lsp` side by side with the older deprecated LSP packages unless you have verified how your Pi version handles duplicate tool names.
+Avoid installing `@narumitw/pi-lsp` side by side with the older deprecated LSP packages unless you have verified how your Pi version handles overlapping capabilities.
 
 ## ✅ Requirements
 
@@ -85,22 +87,61 @@ pi -e ./extensions/pi-lsp
 
 ## 🛠️ Pi tools
 
-### Biome
+### `lsp_diagnostics`
 
-- `biome_lsp_diagnostics` — start `biome lsp-proxy`, open supported files, and return diagnostics.
-- `biome_lsp_format` — compute or write formatting edits for one Biome-supported file.
-- `biome_lsp_fix` — compute or write source actions such as `source.fixAll.biome` or `source.organizeImports.biome`.
+Run diagnostics through language/file-extension routes.
 
-### Python
+Parameters:
 
-- `ty_lsp_diagnostics` — start `ty server`, open Python files, and return type diagnostics.
-- `ruff_lsp_diagnostics` — start `ruff server`, open Python files, and return lint diagnostics.
-- `ruff_lsp_format` — compute or write Ruff formatting edits for one Python file.
-- `ruff_lsp_fix` — compute or write Ruff source actions such as `source.fixAll.ruff` or `source.organizeImports.ruff`.
+- `paths?`: files or directories to check. Defaults to the workspace root.
+- `root?`: workspace root. Defaults to cwd.
+- `limit?`: maximum files to open per selected route.
+- `language?`: optional override, either `"web"` for Biome-supported web/config files or `"python"` for `.py`/`.pyi` files.
+- `checker?`: Python diagnostics checker, one of `"type"`, `"lint"`, or `"all"`. Defaults to `"all"`.
+
+Routes:
+
+- Biome-supported web/config files → Biome diagnostics.
+- Python `.py`/`.pyi` + `checker: "type"` → ty diagnostics.
+- Python `.py`/`.pyi` + `checker: "lint"` → Ruff diagnostics.
+- Python `.py`/`.pyi` + `checker: "all"` → both ty and Ruff diagnostics.
+
+### `lsp_format`
+
+Format one file through the route selected from its file extension.
+
+Parameters:
+
+- `path`: file to format.
+- `root?`: workspace root. Defaults to cwd.
+- `write?`: write formatted text back to the file. Defaults to false.
+- `language?`: optional route override, either `"web"` or `"python"`.
+
+Routes:
+
+- Biome-supported web/config files → Biome formatting.
+- Python `.py`/`.pyi` files → Ruff formatting.
+
+### `lsp_fix`
+
+Apply source fixes or import organization through the route selected from the file extension.
+
+Parameters:
+
+- `path`: file to fix.
+- `root?`: workspace root. Defaults to cwd.
+- `kind?`: source action kind. Defaults to the routed backend's fix-all action.
+- `write?`: write fixed text back to the file. Defaults to false.
+- `language?`: optional route override, either `"web"` or `"python"`.
+
+Routes:
+
+- Biome-supported web/config files → Biome source fixes such as `source.fixAll.biome` or `source.organizeImports.biome`.
+- Python `.py`/`.pyi` files → Ruff source fixes such as `source.fixAll.ruff` or `source.organizeImports.ruff`.
 
 ## 🚀 Examples
 
-Check a project subset with Biome diagnostics:
+Check a mixed project subset and run all applicable diagnostics:
 
 ```json
 {
@@ -109,25 +150,37 @@ Check a project subset with Biome diagnostics:
 }
 ```
 
-Format a TypeScript file with Biome:
+Check only Biome-supported web/config files:
 
 ```json
 {
-  "path": "src/index.ts",
-  "write": true
+  "language": "web",
+  "paths": ["extensions/pi-lsp/src"],
+  "limit": 100
 }
 ```
 
-Check a Python project with ty or Ruff diagnostics:
+Check Python type diagnostics only:
 
 ```json
 {
+  "language": "python",
+  "checker": "type",
   "paths": ["src", "tests"],
   "limit": 100
 }
 ```
 
-Organize Python imports with Ruff:
+Format a TypeScript file with the inferred Biome route:
+
+```json
+{
+  "path": "src/index.ts",
+  "write": true
+}
+```
+
+Organize Python imports with the inferred Ruff route:
 
 ```json
 {
@@ -157,6 +210,7 @@ extensions/pi-lsp/
 │   ├── files.ts
 │   ├── lsp-client.ts
 │   ├── pi-lsp.ts
+│   ├── routes.ts
 │   ├── runner.ts
 │   ├── text-edits.ts
 │   └── types.ts