Fix all open issues: option-map-nullable rule (#69), PostToolUse lint hook (#70), AI-UX closure (#74)

[aviadshiber]

Summary

One PR addressing all three open issues, planned via parallel design passes per issue.

#69 — New rule: option-map-nullable

Detects Vavr Option chains where .map() can wrap a null mapper result as Some(null) (unlike java.util.Optional) and a chained .filter()/.map()/.forEach()/etc. then NPEs on the value — the exact bug from the DEV-219412 incident:

Option.of(metadata)
    .map(m -> m.get("author"))          // Map.get can return null -> Some(null)
    .filter(s -> !s.trim().isEmpty());  // NPE

Detection is deliberately conservative (three gates) to keep false positives at zero:

1. a value-consuming follower (filter, map, flatMap, forEach, peek, exists, forAll) is chained after .map(...) — terminal extractors like getOrElse are excluded
2. the receiver chain is rooted in a literal Option.of() / Option.ofOptional() (qualified io.vavr.control.Option.of also matched); bare variables and java.util.Optional never fire
3. the lambda body matches a known possibly-null shape: x.get(key) (Map.get / JsonNode.get). Zero-arg get() (Vavr/Supplier) and integer-index List.get(0) are excluded — all four Java integer-literal radixes (decimal/hex/octal/binary)

Severity: Warning. The data payload carries fixType: USE_FLATMAP_OPTION_OF and a paste-able snippet built from the real AST names, e.g. .flatMap(m -> Option.of(m.get("author"))). Broader heuristics from the issue (getters without @NonNull, @Nonnull analysis) are left as future work — tree-sitter has no type/annotation resolution across files.

#70 — PostToolUse hook: real-time linting on Edit/Write

New hooks/post_tool_lint.py, wired in hooks.json with matcher Edit|MultiEdit|Write:

• lints only the edited .java file (in-process import, single-file analysis ~ms; CLI fallback when the package isn't importable under the hook's python3)
• emits violations as hookSpecificOutput.additionalContext, so the agent actually sees them in context (plain stdout on PostToolUse is transcript-only)
• silent on clean files, diagnostics capped at 25, honors .java-functional-lsp.json excludes
• failure-safe: every path exits 0, with SIGALRM + subprocess timeouts — a linter problem can never break the editing session

The existing reminder hook is narrowed from Read|Edit|Write to Read: the new hook embeds its own fix instruction for edits, so keeping the reminder there would duplicate context. Flagging this as the one intentional behavior change — happy to revert the narrowing if you prefer zero change to the reminder.

Manual (non-plugin) install instructions added to README. A future strict mode could use decision: block / exit 2; left out as it would fight multi-step edits and the repo's non-blocking philosophy.

#74 — AI-agent UX (closure)

PR #88 already shipped the core of #74 (variant-aware impure-method messages + offending-line ranges, recommendedApi/suggestedSnippet payloads, imperative-option-unwrap and mutable-dto quick fixes — the tests cite the issue). This PR closes the remaining gaps:

• Snippet fidelity (sub-issue 2): imperative-option-unwrap's suggestedSnippet now derives the lambda body from the real then-branch expression — return opt.get().toUpperCase(); → .map(value -> value.toUpperCase()) instead of the value -> value placeholder, sharing the rewrite helper with the quick fix
• Doc drift: README/SKILL.md now show ✅ Quick Fix for mutable-dto and imperative-option-unwrap, document both code actions, the recommendedApi/suggestedSnippet data fields, and the previously-undocumented autoImportLombok config key
• Rule counts synced to 17 everywhere (vscode README still said 12)

Not included (follow-up candidates): a forEach quick fix for statement-shape unwraps, and a field-injection quick fix (intentionally unregistered in fixes.py — constructor synthesis risks clobbering user code).

Post-review hardening (ensemble review, commits 4–5)

A 7-angle ensemble review of this PR produced findings that were verified empirically before acting:

• Fixed (confirmed bug): octal/binary index literals (xs.get(010), xs.get(0b101)) falsely fired option-map-nullable — tree-sitter emits per-radix literal node types
• Fixed (majority-agreement refactor): consolidated the three copies of single-return extraction and the duplicated var.get() regex rewrite into shared base.py helpers (single_return_stmt, return_expr_node/text, single_return_expr_text, rewrite_var_get_call, rewrite_var_references); functional_checker, mutation_checker, and fixes.py now share one implementation. The shared rewrite also fixes two confirmed defects of the old copies: \b regex boundaries silently failing on $-prefixed Java identifiers, and no tolerance for whitespace around .get ()
• Refuted by measurement: the suggested gate reorder in option-map-nullable (lambda-shape check before chain walk) — benchmarked at ~3× slower (chain walks terminate after one step at a bare identifier in fluent code); the measured-cheapest order is documented in the gate comments
• Remaining follow-ups (single-agent suggestions, not blocking): single-pass collect_nodes_by_type for FunctionalChecker (the new rule costs ~64ms only on a pathological 307KB/2000-method file; negligible on real files), a cli.lint_file_for_hook() entry point, and a _NULLABLE_GETTER_METHODS config set

Closes #69, closes #70, closes #74.

Testing

• 36 new tests (rule, hooks, snippet fidelity, shared base helpers incl. $-identifier and whitespace regressions); full suite 716 passed, 7 skipped, coverage 84.58% (≥80% gate)
• ruff check, ruff format --check, mypy all clean
• CLI end-to-end: the issue Add rule: Option.map() producing Some(null) before .filter()/.trim() #69 reproduction case fires option-map-nullable at the .map token; the flatMap fix pattern stays silent
• CI green on all 14 checks (8-job test matrix, jdtls integration on ubuntu+macos, CodeQL)

https://claude.ai/code/session_018SmBpTQU3hqtw8EbWMcZ5M

---

Generated by Claude Code