feat: enrich diagnostics for AI-agent autofix (Closes #74)

[aviadshiber]

Summary

Addresses all 5 suggestions in #74 to make java-functional-lsp diagnostics self-describing enough for an AI coding agent to autofix on the first try.

• DiagnosticData gets two new optional fields: recommended_api (library-agnostic API hint, e.g. "forEach (NOT ifPresent — Vavr Option)") and suggested_snippet (concrete fix using real AST variable names). Serialised to the LSP wire as recommendedApi / suggestedSnippet. Existing payloads stay backward-compatible.
• Per-rule snippet builders read variable names, types, and expressions from the AST so the snippet is paste-able. Example: if (myOpt.isDefined()) return myOpt.get(); else return "fallback"; now produces a snippet that references myOpt and "fallback" literally.
• impure-method refined: distinguishes IO side-effects (Try) from throw side-effects (Either) with different messages, different target_library, and different recommended_api. Diagnostic range now points at the offending statement instead of the method declaration (issue AI agent UX: richer diagnostic data for automated fix generation #74 fix: release-drafter permissions and bump to v7 #5).
• Quick-fix coverage extended (issue AI agent UX: richer diagnostic data for automated fix generation #74 deps: bump hatchling from 1.28.0 to 1.29.0 #3): imperative-option-unwrap, mutable-dto, field-injection now have registered fix generators. Each bails safely when the AST shape isn't trivially rewritable.

Files touched

Area	Files
Data model + wire serialization	analyzers/base.py, server.py
Per-rule data builders	analyzers/{mutation,functional,exception,spring,null}_checker.py
New quick-fixes	fixes.py
Tests	tests/test_{fixes,mutation_checker,functional_checker,exception_checker,spring_checker,server}.py

Test plan

• uv run pytest tests/ — 659 passed (17 new), 7 skipped (jdtls-only).
• uv run ruff check src/ tests/ — clean.
• uv run mypy src/ — clean.
• Manual smoke test in a Java client: confirm recommendedApi / suggestedSnippet appear in Diagnostic.data JSON for at least imperative-option-unwrap and impure-method.
• Manual quick-fix test: open if (opt.isDefined()) return opt.get(); else return "x"; — confirm the Convert-to-Option-map code action applies cleanly.
• Verify impure-method on a throw-only method points at the throw line and produces the "exceptions" message variant.

https://claude.ai/code/session_01Sp1TuWErAKym7CJ8n9pdrq

---

Generated by Claude Code

[aviadshiber]

@claude review with ensemble (with majority vote)

[aviadshiber]

Ensemble review of #88 (majority vote, 3 independent reviewers)

Blockers (single reviewer, but type/correctness-fatal)

1. fix_imperative_option_unwrap allows else-less if — src/java_functional_lsp/fixes.py:1056-1067. When the if has no else, the rewrite emits return opt.map(it -> it); which returns Option<T> instead of T, breaking the method's return type. Require alternative is not None or bail.
2. fix_field_injection produces uncompilable code — src/java_functional_lsp/fixes.py:1149-1185. The WorkspaceEdit removes @Autowired and adds final but never synthesises/updates a constructor, leaving an uninitialised final field. Per the docstring this is acknowledged, but the _FIX_TITLES entry promises "+ constructor injection". Either synthesise the constructor or remove the entry from _FIX_REGISTRY and rely solely on the suggested_snippet. (R2 blocker, R3 major: "rename or remove from registry".)

Major (≥2 reviewers agreed)

3. Hardcoded class name "Foo" in _build_field_injection_data snippet — src/java_functional_lsp/analyzers/spring_checker.py:50-62. Snippet says public Foo(final ... ) for every class. Walk to find_ancestor(field_decl, "class_declaration") and use its identifier. (R1, R2, R3.)
4. Non-paste-able placeholders in suggested_snippet strings — mutation_checker.py:48 (@Value\npublic class Foo { ... }), spring_checker.py:31-36 (public Foo foo() { return new Foo(); }), mutation_checker.py imperative-option-unwrap ({ /* use value */ }). The { ... } / (...) placeholders won't compile if pasted verbatim. Either rebuild from AST or rename the field to make example-only semantics clear. (R2 major, R3 minor.)
5. Degenerate null-check-to-monadic snippet — src/java_functional_lsp/analyzers/functional_checker.py:71-79. Option.of(x).map(v -> v).getOrElse(null) is an identity map with an always-null default, re-introducing the very null we flagged. Either omit suggested_snippet for this rule or build a real lambda body from the if-then return expression text. (R1 major, R2 minor.)
6. fix_mutable_dto is unsafe in two scenarios — src/java_functional_lsp/fixes.py:1078-1119. (a) Diagnostic message explicitly says "Use @ConstructorBinding instead of @Data/@Setter for @ConfigurationProperties classes" (mutation_checker.py:139-141), but the fix rewrites to @Value anyway — should bail when sibling @ConfigurationProperties is present. (b) Blanket rewrite of @Setter is unsafe — @Setter users typically have explicit setters/non-final fields; @Value makes the class final and strips setters. Restrict to @Data or also bail when explicit setter methods exist. (R1 + R2.)

Minor (≥2 reviewers agreed)

7. autoImportVavr flag gates a Lombok import — src/java_functional_lsp/fixes.py:1098. Users who disable Vavr auto-import (but still want Lombok auto-import) lose import lombok.Value;. Use a separate flag or always import for Lombok. (R1 + R2.)
8. data: dict[str, str] | None annotation too narrow — src/java_functional_lsp/server.py:305. Future non-string fields (numbers, bools, lists) will silently mis-type. Use dict[str, Any] | None to mirror the LSP Diagnostic.data shape. (R1 + R3.)

Minor (single-reviewer, worth flagging)

9. Static snippets in null_checker.py ignore the AST (R2) — inconsistent with the PR's "real variable names from the AST" goal (R3 mentions the same inconsistency from the architecture side).
10. Multi-declarator field handling — _build_field_injection_data reads only the first variable_declarator, so private Bar a, b; snippets only a (R1).
11. fix_mutable_dto doesn't verify grandparent.type == "class_declaration" before rewriting — if invoked with a wider diagnostic range, may rewrite an unrelated annotation (R1).
12. _classify_side_effect returns str rather than Literal["throw", "io"] (R3) — typos in the discriminator would silently fall through to the IO branch.
13. fix_field_injection annotation-removal trims only a single space — tab-separated @Autowired\tprivate ... leaves a stray tab (R1, R2).
14. No e2e test for recommendedApi/suggestedSnippet on the wire — only unit-level _to_lsp_diagnostic checks exist (R2). CONTRIBUTING.md:48 also lists only the original three DiagnosticData fields (R2).

What did NOT come up as a concern

• The serialization gate (if diag.data.recommended_api is not None) is correctly implemented — verified by test_to_lsp_diagnostic_omits_optional_fields_when_none.
• The removed _is_side_effect_invocation/_is_side_effect_statement class methods have no external callers; fixes.py uses the module-level is_side_effect_invocation.
• The _FIX_TITLES ↔ _FIX_REGISTRY import-time assertion still holds with 7 entries.

Suggested triage

I'd treat #1, #2, #4, #5 as ship-blockers (one produces broken Java, one is misleading enough to mislead the agents this PR aims to help) and address them in follow-up commits on this branch. #3, #6 are easy AST lookups. The rest is fair game for follow-up issues.

Let me know which subset to fix here vs split into follow-ups.

---

Generated by Claude Code

[aviadshiber]

Suggested release notes for v0.11.0

The release-drafter created a draft labeled v0.10.1 (default patch bump) because no enhancement/feature/rule label was set on this PR. To publish as v0.11.0, edit the draft at https://github.com/aviadshiber/java-functional-lsp/releases (top of the list) — change the tag to v0.11.0, replace the body with the markdown below, and click Publish release. That fires publish.yml on release: published → PyPI.

---

Tag: v0.11.0 (targets main, commit d321341)

Title: v0.11.0 — AI-agent diagnostic enrichment (Closes #74)

Body:

## What's Changed

`DiagnosticData` now carries two optional fields — `recommendedApi` and `suggestedSnippet` — that flow through to the LSP wire so AI coding agents (e.g. Claude Code) can produce correct fixes on the first try without re-deriving Vavr/Lombok APIs or variable names.

### Highlights
- **AST-aware snippets**: per-rule builders pull real variable names, types, and return expressions from the AST so snippets are paste-able. Example for `if (myOpt.isDefined()) return myOpt.get(); else return "fallback";` produces `return myOpt.map(it -> it).getOrElse("fallback");`.
- **`impure-method` discriminates IO vs throw**: distinct messages, distinct `target_library` (Try vs Either), distinct `fix_type` (`EXTRACT_PURE_LOGIC_IO` / `_THROW`); diagnostic now points at the offending statement, not the method declaration.
- **New quick-fixes**: `imperative-option-unwrap`, `mutable-dto`. `field-injection` ships richer diagnostic + snippet but no quick-fix (constructor synthesis would risk clobbering existing user code).
- **`KNOWN_RULES` symmetry check** at server import time catches typos in `_FIX_TITLES` that reference non-existent rule codes.
- **New `autoImportLombok` config flag** (defaults true) so users can disable Vavr auto-import without losing Lombok auto-import (or vice versa).

### Test plan
- 90 new tests including end-to-end wire assertion that `recommendedApi`/`suggestedSnippet` reach the client.
- `ruff format/check` + `mypy --strict` clean.

### Commits
- feat: enrich diagnostics for AI-agent autofix (Closes #74) (#88)

**Full Changelog**: https://github.com/aviadshiber/java-functional-lsp/compare/v0.10.0...v0.11.0

---

For future PRs: adding the enhancement or feature label before merging will cause release-drafter to resolve a minor bump automatically (per .github/release-drafter.yml: version-resolver.minor).

---

Generated by Claude Code