java-functional-lsp

A Java Language Server that provides three things in one:

1. Full Java language support — completions, hover, go-to-definition, compile errors, missing imports — by proxying Eclipse jdtls under the hood
2. 17 functional programming rules — catches anti-patterns and suggests Vavr/Lombok/Spring alternatives, all before compilation
3. Code actions (quick fixes) — automated refactoring via LSP textDocument/codeAction, with machine-readable diagnostic metadata for AI agents

Designed for teams using Vavr, Lombok, and Spring with a functional-first approach.

What it checks

Java language (via jdtls)

When jdtls is installed, the server proxies all standard Java language features:

• Compile errors and warnings
• Missing imports and unresolved symbols
• Type mismatches
• Completions, hover, go-to-definition, find references

Install jdtls separately: brew install jdtls (requires JDK 21+). The server auto-detects a Java 21+ installation even when the IDE's project SDK is older (e.g., Java 8) by probing JDTLS_JAVA_HOME, JAVA_HOME, /usr/libexec/java_home -v 21+ (macOS), and java on PATH. Without jdtls, the server runs in standalone mode — the 17 custom rules still work, but you won't get compile errors or completions.

Functional programming rules

Install

# Homebrew
brew install aviadshiber/tap/java-functional-lsp

# pip
pip install java-functional-lsp

# From source
pip install git+https://github.com/aviadshiber/java-functional-lsp.git

# Optional: install jdtls for full Java language support (see above)
brew install jdtls

Requirements:

• Python 3.10+ (for the LSP server)
• JDK 21+ (only if using jdtls — jdtls 1.57+ requires JDK 21 as its runtime, but can analyze Java 8+ source code)

IDE Setup

VS Code

Install the extension from a .vsix file (download from releases):

# Download and install
gh release download --repo aviadshiber/java-functional-lsp --pattern "*.vsix" --dir /tmp
code --install-extension /tmp/java-functional-lsp-*.vsix

Or build from source:

cd editors/vscode
npm install && npm run compile
npx vsce package
code --install-extension java-functional-lsp-*.vsix

The extension is a thin launcher — it just starts the java-functional-lsp binary for .java files. Updating rules only requires upgrading the LSP binary (brew upgrade java-functional-lsp or pip install --upgrade java-functional-lsp). The VSIX itself rarely needs updating.

Configure the binary path in settings if needed (javaFunctionalLsp.serverPath). See editors/vscode/README.md for details.

IntelliJ IDEA

Use the LSP4IJ plugin (works on Community & Ultimate):

1. Install LSP4IJ from the JetBrains Marketplace
2. Settings → Languages & Frameworks → Language Servers → +
3. Set Command: java-functional-lsp, then in Mappings → File name patterns add *.java with Language Id java

The server automatically detects JetBrains IDEs and disables the jdtls proxy (IntelliJ provides native Java support). To force-enable jdtls, set JAVA_FUNCTIONAL_LSP_JDTLS=on in the server command environment.

See editors/intellij/README.md for detailed instructions.

Claude Code

Step 1: Enable LSP support (required, one-time):

Add lspServers to ~/.claude/settings.json (the plugin handles this automatically — only needed for manual setup):

{
  "lspServers": {
    "java-functional": {
      "command": "java-functional-lsp",
      "extensionToLanguage": { ".java": "java" }
    }
  }
}

Step 2: Install the plugin:

claude plugin add https://github.com/aviadshiber/java-functional-lsp.git

This registers the LSP server, adds auto-install hooks, a PostToolUse hook that lints every .java file after Edit/Write and feeds the violations back to Claude as context (plus a reminder hook on Read), and the /lint-java command.

Manual hook setup (without the plugin) — add the lint hook to ~/.claude/settings.json, pointing at a checkout of this repo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/java-functional-lsp/hooks/post_tool_lint.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The hook is failure-safe: it only fires on .java files, lints just the edited file (well under 2s), stays silent when the file is clean, and always exits 0 so a linter problem can never break the editing session.

Or manually add to your Claude Code config:

{
  "lspServers": {
    "java-functional": {
      "command": "java-functional-lsp",
      "extensionToLanguage": { ".java": "java" }
    }
  }
}

Alternative: project-level .lsp.json — instead of installing the plugin or editing global config, add a .lsp.json file at your project root:

{
  "java-functional": {
    "command": "java-functional-lsp",
    "extensionToLanguage": { ".java": "java" }
  }
}

This is useful for CI environments, containers, or ensuring all team members get the LSP server without individual setup. The java-functional-lsp binary must still be installed (pip install java-functional-lsp or brew install aviadshiber/tap/java-functional-lsp).

Step 3: Nudge Claude to prefer LSP (recommended):

Add to ~/.claude/rules/code-intelligence.md:

# Code Intelligence

Prefer LSP over Grep/Glob/Read for code navigation:
- goToDefinition / goToImplementation to jump to source
- findReferences to see all usages across the codebase
- hover for type info without reading the file

After writing or editing code, check LSP diagnostics before
moving on. Fix any type errors or missing imports immediately.

Troubleshooting:

Other Editors

Any LSP client that supports stdio transport can use this server. Point it to the java-functional-lsp command for java files.

Configuration

Create .java-functional-lsp.json in your project root to customize rules:

{
  "excludes": ["**/generated/**", "**/vendor/**"],
  "sourceLevel": 17,
  "rules": {
    "null-literal-arg": "warning",
    "throw-statement": "info",
    "imperative-loop": "hint",
    "mutable-dto": "off"
  }
}

Options:

• excludes — glob patterns for files/directories to skip entirely (supports ** for multi-segment wildcards)
• rules — per-rule severity: error, warning (default), info, hint, off
• sourceLevel — the project's Java language/source level, as an int (e.g. 17) or version string ("17", legacy "1.8"). Also accepted as javaVersion. Defaults to 8 if unset, so existing configs are unaffected. Currently only changes the mutable-dto recommendation (see below); higher source levels unlock more rewrite targets over time (records, sealed types, pattern matching, text blocks).
• suppressJdtlsPatterns — list of regex patterns to suppress jdtls diagnostics (see below)

Spring-aware behavior:

• throw-statement, catch-rethrow, and try-catch-to-monadic are automatically suppressed inside @Bean methods
• mutable-dto suggests @ConstructorBinding instead of @Value when the class has @ConfigurationProperties

Source-level-aware behavior:

• mutable-dto recommends a record instead of @Value once sourceLevel is 16 or higher (records became final/non-preview in JDK 16) — a plain immutable DTO is simpler as a built-in record with no Lombok dependency. It still calls out @Value as the fallback when the class needs @With/@Builder/@Jacksonized, is used as a facade, or relies on AOP proxying (records are final and can't be proxied). Below sourceLevel 16 (including the default), the message and quick fix are unchanged — @Value only.

Inline suppression with @SuppressWarnings:

// Suppress a specific rule on a method
@SuppressWarnings("java-functional-lsp:null-return")
public String findUser() { return null; }  // no diagnostic

// Suppress multiple rules
@SuppressWarnings({"java-functional-lsp:null-return", "java-functional-lsp:throw-statement"})
public String findUser() { ... }

// Suppress all java-functional-lsp rules
@SuppressWarnings("java-functional-lsp")
public String legacyMethod() { ... }

Works on classes, methods, constructors, fields, and local variables. Suppression applies to the annotated scope — a class-level annotation suppresses all methods within it.

Lombok support

Projects using Lombok need the Lombok Java agent for jdtls to process @Builder, @Value, @Data, @Slf4j, and other annotations. Without it, jdtls reports false "method undefined" errors for generated methods.

The server auto-discovers lombok.jar from these locations (first match wins):

1. Project config — add to .java-functional-lsp.json:

   { "lombok": "/path/to/lombok.jar" }
   

2. Environment variable — LOMBOK_JAR=/path/to/lombok.jar
3. Maven cache — auto-discovered from ~/.m2/repository/org/projectlombok/lombok/
4. Dedicated directory — ~/.jdtls-libs/lombok.jar

If Lombok is used in your project but the jar isn't found, the server logs a warning.

jdtls settings

The server sends Maven/Gradle settings to jdtls at startup via initializationOptions.settings. Defaults are optimized for Maven monorepos (Maven enabled, Gradle disabled, build artifact exclusions). Override via .java-functional-lsp.json:

{
  "jdtls": {
    "settings": {
      "java": {
        "import": {
          "maven": { "enabled": true },
          "gradle": { "enabled": true },
          "exclusions": ["**/node_modules/**", "**/target/**"]
        },
        "configuration": { "updateBuildConfiguration": "automatic" },
        "maven": { "downloadSources": true }
      }
    }
  }
}

Custom settings fully replace the defaults (no merge). See the jdtls Preferences reference for all available keys.

jdtls cache

The jdtls Eclipse workspace index is cached in ~/.cache/jdtls-data/. Warm starts (~10-20s) reuse this cache; cold starts (60-120s) rebuild from scratch. The cache is automatically invalidated when jdtls or Java is upgraded, but not when java-functional-lsp is upgraded — our Python code changes don't affect the Eclipse index.

To force a clean rebuild: rm -rf ~/.cache/jdtls-data/

Dependencies on modules in other Maven groups

To keep jdtls fast and within its heap, the server imports only the Maven group of the file you open (its tightest parent pom with <modules>), plus up to 5 more groups as you navigate. A module in that group can depend on a reactor module in another group. m2e then looks that dependency up in the local Maven repository at the reactor's version, often a ${revision} default that is never installed. Every symbol from that module then shows as a false error: "cannot be resolved", "is undefined for the type", or "The hierarchy of the type X is inconsistent" (#110). The server fixes this by importing the missing modules itself, only as far as the open file needs. (v0.14.0 imported every module any pom reported missing. On a large monorepo that cascaded through the transitive closure to 60 modules, 3 GB of jdtls heap, and 30 s timeouts on every request.)

How it works (v0.14.1):

1. Demand. An open .java file whose jdtls diagnostics hold #110-class errors (unresolved import or type, "undefined for the type", "hierarchy … inconsistent", "indirectly referenced from required .class files", "must override or implement a supertype method") starts the process for its module. Other open files, and files you never opened, never trigger an import.
2. Fresh diagnostics only. jdtls does not re-check a file that is already open when its classpath changes, so its errors can be minutes old. The server waits until jdtls is build-idle: no open language/progressReport task (indexing / "Searching…" tasks are ignored) and no progress event for 10 s. It then sends java.project.refreshDiagnostics for up to 3 demand files, most recently opened first, one at a time. Only the publish that answers that refresh counts, and only if the document still has the same content.
3. Frontier. The candidates come from the reactor index, which is built once per session from the modules reachable from the reactor root through <modules> (all profiles). They are the in-repo <dependencies> (compile, provided, runtime) of the demand module and of every module imported so far, including those inherited from in-repo parent poms. dependencyManagement is ignored. For a file under src/test, the demand module's test-scope and test-jar dependencies are included too.
4. Candidates = frontier ∩ m2e markers. A frontier module is imported only if m2e reports it missing on some pom ([Offline / ]Missing artifact g:a:type[:classifier]:version). The marker is the proof that no installed jar resolves it. A test-jar edge only matches a test-jar/tests marker. Candidates keep their declaration order, and high fan-in "hub" modules go last.
5. One round. Up to 8 candidates are added as one didChangeWorkspaceFolders event. The server waits for build-idle (at most 90 s) and refreshes the demand files again. If the fresh diagnostics are clean, it stops. If they are not, it runs the next round. Before deciding round k, it waits (at most 30 s) until the modules imported in round k−1 have published their own pom markers. A large module group's build can outlast one 90 s wait (measured: a 95-module/127-project group on products), so a still-busy jdtls does not stop the phase at once — the wait retries (up to 6 attempts, up to 10 minutes total) and the round resumes as soon as jdtls next reports build-idle. Only once that busy budget is exhausted does the phase stop with jdtls-busy.
6. Stop. Every stop is logged once and sent to the client once as a window/logMessage. Opening a file in a module that had no demand before starts the process again, unless a session limit (budget, rounds, wall clock, refresh cap) was reached. A stop of jdtls-busy or no-fresh-diagnostics before anything was imported lets the same module try again on its next demand; the same warning twice in a row is logged at DEBUG and not sent again.

If you later open a file in a group that contains one of these modules, the group folder replaces the module folder in the same workspace change. That module folder is never re-added.

Configuration (the repository config can only lower a limit; the environment can raise it up to the hard maximum):

The remaining limits are fixed: 8 modules per round, a 5-minute import wall clock per session (counted only while imports run: from a round-1 import to its stop, excluding refresh time and the idle time between sessions of demand), 3 refreshes per round (a session cap of 3 × (rounds + 1) × 2, i.e. 42 with the default 6 rounds, so the rounds limit fires first), a 20 s refresh timeout with one retry, a 90 s build-idle wait per attempt, and up to 6 attempts (10 minutes total) before a busy jdtls gives up on a round.

Stop reasons (jdtls: dependency-module import stopped (<reason>)):

Limits:

• Stale local installs are not detected. If an old build of the sibling is installed at the same version in your local repository, m2e resolves the dependency from that jar and reports nothing. You then see the installed version's API, not the source, and the import stops with no-candidates(owner-has-jar). Run mvn install for that module again, or delete it from the local repository (~/.m2/repository/<group path>/<artifactId>/<version>).
• Maven only. Gradle projects are unchanged.
• Index bounds. The index skips poms larger than 1 MB, poms with <!DOCTYPE/<!ENTITY declarations (in any encoding), symlinked poms, modules outside the reactor root, coordinates with characters other than letters, digits, _, . and - (such as ${revision}; ${project.groupId} and ${project.parent.groupId} in a dependency are resolved), and any groupId:artifactId declared by two directories. It reads at most 5000 poms, for at most 10 s.
• Not persisted. jdtls 1.61 does not keep folders added this way across a restart, so each session starts from zero. The server keeps its own record in ~/.cache/jdtls-data/<hash>.deps.json, and the budget counts only this session's imports.

Troubleshooting (the server log is its stderr, as captured by your LSP client):

• jdtls: pom.xml errors changed for <pom>: … Missing artifact g:a:… means m2e could not resolve that dependency. It is logged at INFO for modules with an open file, and at DEBUG for imported dependency modules.
• jdtls: reactor index of <root>: N modules from M poms means the index was built. (truncated) means it hit a bound.
• jdtls: dependency round k: frontier F, candidates C, deferred D, round took Ts, refresh clean|errors|failed, …; importing K dependency module(s) (used/budget): g:a (path), … is logged once per round.
• jdtls: dependency-module import stopped (<reason>): … gives the reason (table above). A session summary follows when jdtls stops.
• If the errors stay and nothing was imported, the artifact is not a module of this reactor (check the <modules> path that should reach it), or it is a real external artifact missing from your repository.
• m2e caches failed lookups in *.lastUpdated files in the local repository. The jdtls workspace of a module lives in ~/.cache/jdtls-data/<hash>/, where <hash> is the directory named in the jdtls subprocess started (pid=…, data=…) log line. If errors persist after the module is imported, stop the editor, delete that directory (and its <hash>.deps.json), and reopen. v0.14.1 changed the workspace key, so workspaces bloated by v0.14.0 are not reused, and the LRU eviction removes them.

Fresh jdtls diagnostics after edits

jdtls re-validates a file 0.4–2.4s after the last edit to any file, and its results carry no document version. So after an edit, java-functional-lsp holds back jdtls diagnostics for that file until jdtls publishes again, rather than re-sending the previous edit's results as if they were current (#109):

With Claude Code two more things happen:

• The plugin's PostToolUse hook waits for fresh results. Claude Code attaches diagnostics as soon as its PostToolUse hooks finish, without waiting for the server (anthropics/claude-code#93321). The server records when it last published final diagnostics for each file, and hooks/post_tool_lint.py waits until that is newer than the edit (at most JAVA_FUNCTIONAL_LSP_HOOK_WAIT seconds, default 3, max 4), so jdtls's result for the edit arrives in the same tool result. The markers live in a private per-user temp directory and contain only a timestamp.
• jdtls gets a didSave after each edit. Claude Code writes the file itself; when the edited buffer matches the file on disk, the server forwards a didSave. Without it, jdtls can re-check dependent files against the old version of the edited one (e.g. a caller keeps reporting a constructor's old arity) and never correct them.

If jdtls doesn't publish in time (3s after the last edit, stretched when jdtls is slow, 10s at most), the last known jdtls diagnostics are used. Files whose module is still being imported, and files matched by java.diagnostic.filter, are never held. While you edit the same file in quick succession, its diagnostics update only once the burst settles.

Environment variables:

The log reports jdtls freshness: released=… too_early=… timeout=… late_correction=… every 100 decisions and when jdtls stops. Repeated timeout lines mean jdtls is slow or stuck on that module. A growing late_correction count means jdtls results were released too early.

Suppressing jdtls diagnostics

For project-specific jdtls false positives (e.g., annotation processor methods, MapStruct mappers), use suppressJdtlsPatterns to add custom regex filters:

{
  "suppressJdtlsPatterns": [
    "The method \\w+Mapper\\(\\) is undefined",
    "cannot be resolved to a type"
  ]
}

Each entry is a regex matched against jdtls diagnostic messages. Invalid patterns are skipped with a warning.

Code actions (quick fixes)

The server provides LSP code actions (textDocument/codeAction) that automatically refactor code. When your editor shows a diagnostic with a lightbulb icon, clicking it applies the fix:

Quick fixes automatically add the required Vavr import if it's not already present. Disable auto-import with "autoImportVavr": false in config ("autoImportLombok": false for the Lombok import added by the mutable-dto fix).

Agent mode (AI integration)

Every diagnostic includes a machine-readable data payload designed for AI agents like Claude Code:

{
  "code": "frozen-mutation",
  "message": "Runtime Exception Risk: Mutating a frozen structure...",
  "data": {
    "fixType": "REPLACE_WITH_VAVR_LIST",
    "targetLibrary": "io.vavr.collection.List",
    "rationale": "Runtime mutation of List.of() causes UnsupportedOperationException. Use Vavr for safe, persistent immutability.",
    "recommendedApi": ".append / .appendAll / .update / .remove (returns a new persistent collection)",
    "suggestedSnippet": "list = list.append(\"c\");  // returns a new persistent collection"
  }
}

This lets agents confidently apply fixes without guessing libraries or patterns — the fixType tells them what to do, targetLibrary tells them which dependency, and rationale tells them why. recommendedApi names the exact method on the target library (e.g. Vavr Option uses forEach, not ifPresent) and suggestedSnippet is a paste-able fix built from the real AST variable names.

Agent mode configuration in .java-functional-lsp.json:

{
  "autoImportVavr": true,
  "strictPurity": true
}

Note: The machine-readable data payload is always included in diagnostics when available — no configuration needed.

How it works

The server has two layers:

• Custom rules — uses tree-sitter with the Java grammar for sub-millisecond AST analysis (~0.4ms per file). No compiler or classpath needed — runs on raw source files.
• Java language features — proxies Eclipse jdtls for compile errors, completions, hover, go-to-definition, and references. Diagnostics from both layers are merged and published together.

The server speaks the Language Server Protocol (LSP) via stdio, making it compatible with any LSP client.

Development

# Clone and setup
git clone https://github.com/aviadshiber/java-functional-lsp.git
cd java-functional-lsp
uv sync
git config core.hooksPath .githooks

# Run checks
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/
uv run pytest

Git hooks in .githooks/ enforce quality automatically:

• pre-commit — runs lint, format, type check, and tests before each commit
• pre-push — blocks direct pushes to main (use feature branches + PRs)

See CONTRIBUTING.md for full guidelines.

License

MIT