Add LSP auto-detect and setup guide

Author: haasonsaas

.diffscope.yml.example

@@ -15,7 +15,7 @@ smart_review_summary: true   # Include AI-generated PR summary in smart-review o
 smart_review_diagram: false  # Generate a Mermaid diagram in smart-review output
 symbol_index: true           # Build repo symbol index for cross-file context (respects .gitignore)
 symbol_index_provider: regex # regex | lsp
-symbol_index_lsp_command: rust-analyzer
+symbol_index_lsp_command: rust-analyzer # optional; omit to auto-detect
 symbol_index_lsp_languages:
   rs: rust
 # For TypeScript (example):

README.md

@@ -223,7 +223,7 @@ exclude_patterns:
   - "**/__pycache__/**"
 ```
 
-Set `symbol_index_provider: lsp` to use a language server; it falls back to regex indexing if the LSP binary is missing. Configure `symbol_index_lsp_languages` and `symbol_index_lsp_command` to match your server (for example, `typescript-language-server --stdio` with `ts`/`tsx` language IDs).
+Set `symbol_index_provider: lsp` to use a language server; it falls back to regex indexing if the LSP binary is missing. Configure `symbol_index_lsp_languages` and `symbol_index_lsp_command` to match your server (for example, `typescript-language-server --stdio` with `ts`/`tsx` language IDs). If you omit `symbol_index_lsp_command`, diffscope will try to auto-detect a server based on installed binaries and the file types in your repo.
 
 ### LSP Symbol Index Examples (All Common Languages)
 
@@ -300,18 +300,7 @@ symbol_index_lsp_languages:
 
 ### LSP Setup Notes (Install + Command)
 
-Use your package manager if you already have one. These are the minimal install commands and the server command to set in `symbol_index_lsp_command`.
-
-- rust-analyzer: `rustup component add rust-analyzer` and (recommended) `rustup component add rust-src`; command: `rust-analyzer`.
-- TypeScript/JavaScript (typescript-language-server): `npm install -g typescript-language-server typescript`; command: `typescript-language-server --stdio`.
-- Python (python-lsp-server/pylsp): `pip install "python-lsp-server[all]"` (or `python-lsp-server`); command: `pylsp`.
-- Go (gopls): `go install golang.org/x/tools/gopls@latest`; command: `gopls`.
-- Java (Eclipse JDT LS): use the distribution’s wrapper `bin/jdtls` with `-configuration` and `-data` arguments.
-- Kotlin (Kotlin LSP): `brew install JetBrains/utils/kotlin-lsp` or use the standalone zip; command: `kotlin-lsp` (or `kotlin-lsp.sh`, see its `--help` for stdio options).
-- C/C++ (clangd): install via your package manager (e.g., `brew install llvm` or `apt-get install clangd-12`); command: `clangd`.
-- C# (csharp-ls): `dotnet tool install --global csharp-ls`; command: `csharp-ls`.
-- Ruby (solargraph): `gem install solargraph`; command: `solargraph stdio`.
-- PHP (Phpactor): install Phpactor (e.g., download the PHAR or install via composer); command: `phpactor language-server`.
+For detailed install commands, OS-specific package manager options, and troubleshooting, see `docs/lsp.md`.
 
 ## Plugin Development
 

docs/lsp.md

@@ -0,0 +1,74 @@
+# LSP Setup and Troubleshooting
+
+This guide covers installation options, recommended commands, and common pitfalls when using the LSP-backed symbol indexer.
+
+## Auto-detection
+
+If `symbol_index_provider: lsp` and `symbol_index_lsp_command` is not set, diffscope will try to auto-detect a server by:
+- scanning repository file extensions (honoring ignore rules), and
+- selecting the first available server that matches your configured `symbol_index_lsp_languages`.
+
+If it picks the wrong server, set `symbol_index_lsp_command` explicitly.
+
+## Package Manager Matrix (brew/apt/choco)
+
+Use these when you prefer OS-level packages. If a cell says "manual", use the language-specific install section below.
+
+| Server | macOS (brew) | Ubuntu/Debian (apt) | Windows (choco) |
+| --- | --- | --- | --- |
+| rust-analyzer | `brew install rust-analyzer` | `rustup component add rust-analyzer` | `rustup component add rust-analyzer` |
+| clangd | `brew install llvm` | `sudo apt-get install clangd-12` | `choco install llvm` |
+| kotlin-lsp | `brew install JetBrains/utils/kotlin-lsp` | manual (zip) | manual (zip) |
+| Eclipse JDT LS | manual (zip) | manual (zip) | manual (zip) |
+
+## Language-specific Installers (cross-platform)
+
+Set `symbol_index_lsp_command` to the command shown after installation.
+
+- Rust (rust-analyzer)
+  - Install: `rustup component add rust-analyzer`
+  - Optional: `rustup component add rust-src`
+  - Command: `rust-analyzer`
+- TypeScript / JavaScript (typescript-language-server)
+  - Install: `npm install -g typescript-language-server typescript`
+  - Command: `typescript-language-server --stdio`
+- Python (python-lsp-server / pylsp)
+  - Install: `pip install "python-lsp-server[all]"` (or `python-lsp-server`)
+  - Command: `pylsp`
+- Go (gopls)
+  - Install: `go install golang.org/x/tools/gopls@latest`
+  - Command: `gopls`
+- C# (csharp-ls)
+  - Install: `dotnet tool install --global csharp-ls`
+  - Command: `csharp-ls`
+- Ruby (solargraph)
+  - Install: `gem install solargraph`
+  - Command: `solargraph stdio`
+- PHP (Phpactor)
+  - Install (PHAR): `curl -Lo phpactor.phar https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar`
+  - Then: `chmod a+x phpactor.phar` and `mv phpactor.phar ~/.local/bin/phpactor`
+  - Command: `phpactor language-server`
+
+## Manual Installers
+
+### Kotlin LSP
+
+If you didn't use Homebrew:
+1. Download the standalone zip from the Kotlin LSP Releases page.
+2. `chmod +x $KOTLIN_LSP_DIR/kotlin-lsp.sh`
+3. Symlink it: `ln -s $KOTLIN_LSP_DIR/kotlin-lsp.sh $HOME/.local/bin/kotlin-lsp`
+
+### Eclipse JDT LS
+
+Download and extract a milestone or snapshot build. You can run the wrapper:
+
+```
+bin/jdtls -configuration /path/to/config -data /path/to/workspace
+```
+
+## Troubleshooting
+
+- Auto-detect chose the wrong server: set `symbol_index_lsp_command` explicitly.
+- LSP binary not found: check PATH or use an absolute path in `symbol_index_lsp_command`.
+- Server expects stdio: use the `--stdio` form when required (e.g., TypeScript, Solargraph).
+- JDT LS needs a unique `-data` directory per workspace; configure a stable path.

src/core/symbol_index.rs

@@ -3,7 +3,8 @@ use ignore::WalkBuilder;
 use once_cell::sync::Lazy;
 use regex::Regex;
 use serde_json::{json, Value};
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
+use std::env;
 use std::fs;
 use std::io::{BufRead, BufReader, Read, Write};
 use std::path::{Path, PathBuf};
@@ -22,7 +23,90 @@ pub struct SymbolIndex {
     files_indexed: usize,
 }
 
+struct LspServerOption {
+    command: &'static str,
+    program: &'static str,
+    extensions: &'static [&'static str],
+}
+
+const LSP_DETECT_MAX_FILES: usize = 2000;
+
+const LSP_SERVER_OPTIONS: &[LspServerOption] = &[
+    LspServerOption {
+        command: "rust-analyzer",
+        program: "rust-analyzer",
+        extensions: &["rs"],
+    },
+    LspServerOption {
+        command: "typescript-language-server --stdio",
+        program: "typescript-language-server",
+        extensions: &["ts", "tsx", "js", "jsx"],
+    },
+    LspServerOption {
+        command: "pylsp",
+        program: "pylsp",
+        extensions: &["py", "pyi"],
+    },
+    LspServerOption {
+        command: "gopls",
+        program: "gopls",
+        extensions: &["go"],
+    },
+    LspServerOption {
+        command: "jdtls",
+        program: "jdtls",
+        extensions: &["java"],
+    },
+    LspServerOption {
+        command: "kotlin-lsp",
+        program: "kotlin-lsp",
+        extensions: &["kt"],
+    },
+    LspServerOption {
+        command: "clangd",
+        program: "clangd",
+        extensions: &["c", "h", "cc", "cpp", "cxx", "hpp"],
+    },
+    LspServerOption {
+        command: "csharp-ls",
+        program: "csharp-ls",
+        extensions: &["cs"],
+    },
+    LspServerOption {
+        command: "solargraph stdio",
+        program: "solargraph",
+        extensions: &["rb"],
+    },
+    LspServerOption {
+        command: "phpactor language-server",
+        program: "phpactor",
+        extensions: &["php"],
+    },
+];
+
 impl SymbolIndex {
+    pub fn detect_lsp_command<F>(
+        repo_root: &Path,
+        max_files: usize,
+        lsp_languages: &HashMap<String, String>,
+        should_exclude: F,
+    ) -> Option<String>
+    where
+        F: Fn(&PathBuf) -> bool,
+    {
+        if max_files == 0 {
+            return None;
+        }
+        let enabled_extensions = normalized_extension_set(lsp_languages);
+        let extension_counts = collect_extension_counts(
+            repo_root,
+            max_files.min(LSP_DETECT_MAX_FILES),
+            &enabled_extensions,
+            should_exclude,
+        );
+        choose_lsp_command(&extension_counts, &enabled_extensions)
+    }
+
     pub fn build<F>(
         repo_root: &Path,
         max_files: usize,
@@ -255,6 +339,150 @@ impl SymbolIndex {
     }
 }
 
+fn normalized_extension_set(lsp_languages: &HashMap<String, String>) -> HashSet<String> {
+    lsp_languages
+        .keys()
+        .filter(|ext| !ext.trim().is_empty())
+        .map(|ext| ext.trim().to_ascii_lowercase())
+        .collect()
+}
+
+fn collect_extension_counts<F>(
+    repo_root: &Path,
+    max_files: usize,
+    enabled_extensions: &HashSet<String>,
+    should_exclude: F,
+) -> HashMap<String, usize>
+where
+    F: Fn(&PathBuf) -> bool,
+{
+    let walker = WalkBuilder::new(repo_root)
+        .hidden(true)
+        .ignore(true)
+        .git_ignore(true)
+        .git_exclude(true)
+        .git_global(true)
+        .build();
+
+    let mut counts = HashMap::new();
+    let mut files_seen = 0usize;
+
+    for entry in walker.flatten() {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+
+        let relative = path
+            .strip_prefix(repo_root)
+            .map(|p| p.to_path_buf())
+            .unwrap_or_else(|_| path.to_path_buf());
+        if should_exclude(&relative) {
+            continue;
+        }
+
+        files_seen += 1;
+        if files_seen > max_files {
+            break;
+        }
+
+        let extension = match path.extension().and_then(|ext| ext.to_str()) {
+            Some(ext) => ext.trim().to_ascii_lowercase(),
+            None => continue,
+        };
+        if extension.is_empty() {
+            continue;
+        }
+        if !enabled_extensions.is_empty() && !enabled_extensions.contains(&extension) {
+            continue;
+        }
+
+        *counts.entry(extension).or_insert(0) += 1;
+    }
+
+    counts
+}
+
+fn choose_lsp_command(
+    extension_counts: &HashMap<String, usize>,
+    enabled_extensions: &HashSet<String>,
+) -> Option<String> {
+    let mut best_command: Option<&'static str> = None;
+    let mut best_score = 0usize;
+
+    for option in LSP_SERVER_OPTIONS {
+        if !is_program_available(option.program) {
+            continue;
+        }
+
+        let score: usize = option
+            .extensions
+            .iter()
+            .filter(|ext| {
+                let ext: &str = *ext;
+                enabled_extensions.is_empty() || enabled_extensions.contains::<str>(ext)
+            })
+            .filter_map(|ext| {
+                let ext: &str = *ext;
+                extension_counts.get::<str>(ext)
+            })
+            .sum();
+
+        if score > best_score {
+            best_score = score;
+            best_command = Some(option.command);
+        }
+    }
+
+    best_command.map(|command| command.to_string())
+}
+
+fn is_program_available(program: &str) -> bool {
+    if program.trim().is_empty() {
+        return false;
+    }
+
+    let program_path = Path::new(program);
+    if program_path.components().count() > 1 {
+        return program_path.is_file();
+    }
+
+    let path_var = match env::var_os("PATH") {
+        Some(path) => path,
+        None => return false,
+    };
+
+    for path in env::split_paths(&path_var) {
+        if program_exists_in_dir(&path, program) {
+            return true;
+        }
+    }
+
+    false
+}
+
+fn program_exists_in_dir(dir: &Path, program: &str) -> bool {
+    let candidate = dir.join(program);
+    if candidate.is_file() {
+        return true;
+    }
+
+    if cfg!(windows) && Path::new(program).extension().is_none() {
+        let pathext = env::var_os("PATHEXT").unwrap_or_else(|| ".EXE;.CMD;.BAT;.COM".into());
+        for ext in pathext.to_string_lossy().split(';') {
+            if ext.is_empty() {
+                continue;
+            }
+            let candidate = dir.join(format!("{}{}", program, ext));
+            if candidate.is_file() {
+                return true;
+            }
+        }
+    }
+
+    false
+}
+
 static SYMBOL_PATTERNS: Lazy<HashMap<&'static str, Vec<Regex>>> = Lazy::new(|| {
     let mut map = HashMap::new();