Skip to content

Add Java main-method gutter debugging for JDTLS and Metals - #330

Merged
tartarughina merged 2 commits into
zed-extensions:mainfrom
fwrq41251:feat/metals-main-debug-locator
Nov 17, 2026
Merged

tartarughina merged 2 commits into
zed-extensions:mainfrom
fwrq41251:feat/metals-main-debug-locator

Conversation

@fwrq41251

@fwrq41251 fwrq41251 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Java main-method gutter actions currently expose Run without a Debug counterpart. Add a shared Java task locator with configuration mappings for the Java (JDTLS) and Metals debug adapters, so either setup can debug a main method without .zed/debug.json.

Refs #329. This covers main methods; test locators remain separate.

Changes

  • Register [debug_locators.java] and identify the built-in java-main task with ZED_JAVA_RUNNABLE=main. Runnable recognition is independent of the selected adapter.
  • For Java, generate a launch scenario containing mainFile: "$ZED_FILE" and a class hint from ZED_JAVA_MAIN_CLASS, supplied by the built-in task as $ZED_CUSTOM_java_class_name. Zed substitutes the captured class name before launch. At launch, resolve entries in that file through vscode.java.resolveMainMethod, select the matching class, retain its fully qualified name and project identity, and call vscode.java.buildWorkspace before the existing classpath resolution and session startup. Only build success code 1 permits launch.
  • Allow vscode.java.buildWorkspace up to five minutes through the native LSP proxy while retaining the five-second timeout for other requests. Timeout errors report the actual duration, and timed-out requests are still cancelled.
  • For Metals, generate the existing file-discovery launch configuration using path: "$ZED_FILE" and runType: "runOrTestFile"; its adapter handles discovery and session preparation.
  • Keep gutter discovery free of LSP requests, session startup, and shell-task execution. Forward task environment overrides without the locator metadata. Unmarked tasks, test tasks, and unsupported adapters produce no scenario.
  • Document both setups and custom-task opt-in. Add mainFile to the Java configuration schema. Existing manual configurations without mainFile retain their launch behavior.

For JDTLS, the built-in gutter action selects the clicked class even when the file contains multiple main classes. With mainFile, the class hint can be simple or fully qualified; the resolved entry supplies the fully qualified class and project used for building and launching. Custom tasks without a class hint continue to use file discovery. Missing or still-ambiguous entries stop the launch rather than choosing an arbitrary entry. A manual configuration can combine mainFile, mainClass, and projectName to disambiguate. The resolved project prevents same-named classes in different modules from being selected by a workspace-wide class-name lookup.

Validation

  • cargo test -p zed_java: 106 tests passed, including ten locator tests and twelve tests for file-based launch preparation. Coverage includes adapter selection, task filtering, environment forwarding and metadata removal, deferred class variables, same-file main-class selection with and without a package, exact fully qualified names, project ambiguity, file URI encoding, project identity, missing entries, build status codes, and LSP failures.
  • cargo clippy -p zed_java --all-targets -- -D warnings
  • cargo fmt --all --check, git diff --check, and JSON schema syntax validation.
  • Release build for wasm32-wasip2.

The following validation was completed before the review follow-up:

  • cargo test -p java-lsp-proxy: 58 tests passed. Coverage exercises the real HTTP handler with a build completing after six seconds, verifies ordinary requests still time out and send cancellation after five seconds, and checks that only the matching execute-command request gets the longer timeout.
  • cargo clippy -p java-lsp-proxy --all-targets -- -D warnings
  • Release builds for wasm32-wasip1 and wasm32-wasip2.
  • Interactive verification in Zed 1.28.1 without .zed/debug.json, using a two-module Maven fixture with example.Main in both modules and an additional main class in the first module:
    • JDTLS 1.63.0 with Java Debug 0.53.2: gutter Debug actions launched both modules and stopped at each module's correct source breakpoint, with distinct local variable values and output.
    • After changing the second module's source without manually compiling, JDTLS debugging showed the updated value at the breakpoint and in output.
    • Introducing a compilation error stopped the JDTLS launch with build status 2; fixing it allowed debugging again.
    • Metals regression: with JDTLS disabled, the gutter action launched the second module, stopped at the correct breakpoint, and showed the updated value.

The new same-file class-selection behavior has automated coverage; it has not been exercised in a new interactive Zed session. Metals verification used the existing Java-enabled Scala extension 0.2.5 installation and local Metals snapshot/proxy setup. This PR does not add Java registration to metals-zed or change its proxy. Gradle and other Metals/build-server combinations were not exercised interactively.

@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: zhou.cong 周 聰-SaaS.
This is most likely caused by a git client misconfiguration; please make sure to:

  1. check if your git client is configured with an email to sign commits git config --list | grep email
  2. If not, set it up using git config --global user.email email@example.com
  3. Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from a1b3d9d to b902a69 Compare November 16, 2026 00:20
@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

We require contributors to sign our Contributor License Agreement, and we don't have @fwrq41251 on file. You can sign our CLA at https://zed.dev/cla. Once you've signed, post a comment here that says '@cla-bot check'.

@fwrq41251 fwrq41251 changed the title Add Metals gutter debugging for Java main methods Add Java main-method debug locator with Metals support Nov 16, 2026
@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: zhou.cong 周 聰-SaaS.
This is most likely caused by a git client misconfiguration; please make sure to:

  1. check if your git client is configured with an email to sign commits git config --list | grep email
  2. If not, set it up using git config --global user.email email@example.com
  3. Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from 064ecfe to b94b801 Compare November 16, 2026 00:34
@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

We require contributors to sign our Contributor License Agreement, and we don't have @fwrq41251 on file. You can sign our CLA at https://zed.dev/cla. Once you've signed, post a comment here that says '@cla-bot check'.

@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from b94b801 to 1d219a5 Compare November 16, 2026 01:07
@fwrq41251 fwrq41251 changed the title Add Java main-method debug locator with Metals support Add Java main-method gutter debugging for JDTLS and Metals Nov 16, 2026
@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

We require contributors to sign our Contributor License Agreement, and we don't have @fwrq41251 on file. You can sign our CLA at https://zed.dev/cla. Once you've signed, post a comment here that says '@cla-bot check'.

@fwrq41251

Copy link
Copy Markdown
Contributor Author

@cla-bot check

@cla-bot cla-bot Bot added the cla-signed label Nov 16, 2026
@cla-bot

cla-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

The cla-bot has been summoned, and re-checked this pull request!

@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from 1d219a5 to c10b9a7 Compare November 16, 2026 01:30
Comment thread debug_adapter_schemas/Java.json Outdated
},
"mainFile": {
"type": "string",
"description": "The absolute path to a Java source file, or $ZED_FILE. Resolves the main class and project from this file and builds before launch. Use mainClass and projectName to disambiguate multiple entries."

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cannot $ZED_FILE be rephrased into current focused file? Stating just $ZED_FILE might confuse the most.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the schema description to explain that $ZED_FILE refers to the currently focused Java source file, while keeping the variable spelling available for users writing a configuration.

Comment thread src/debug_locator.rs Outdated
resolved_label: String,
debug_adapter_name: &str,
) -> Option<zed::DebugScenario> {
if locator_name != "java" {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could there be an instance where locator is different from java?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is only one registered locator in this extension, java, so the extra name check is redundant here. Removed the check and the helper's locator_name parameter; the required extension callback argument is now _locator_name.

Comment thread src/debugger.rs Resolved
Comment thread src/debugger.rs
Comment on lines +97 to +98
return Err(format!(
"Multiple Java main methods found in {main_file}; specify mainClass and projectName in .zed/debug.json"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we do something to decrease attrition here? Does the task provide a way to retrieve where the locator has been used to infer the correct main class?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the runnable query already captures the class name. The built-in main task now carries it as ZED_JAVA_MAIN_CLASS=$ZED_CUSTOM_java_class_name, and the locator copies that hint into the JDTLS scenario's mainClass. It stays as a template until Zed substitutes the task variables before launch.

The JDTLS launch path then resolves candidates within mainFile, filters by that class, and retains the resolved fully qualified name and project. This selects the clicked class when one file has multiple main classes, without requiring .zed/debug.json. The file scopes the simple class name, so no package concatenation is necessary, including for the default package.

Added coverage for same-file selection, default-package classes, fully qualified name matching, and remaining project ambiguity. Custom tasks without a hint still use file discovery; ambiguous results still fail explicitly. The Metals mapping continues to use its existing file-discovery path. The new selection has automated coverage, but I have not repeated the interactive Zed run for this follow-up.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks good, thanks

@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from c10b9a7 to 6711cd9 Compare November 17, 2026 00:52
@tartarughina

Copy link
Copy Markdown
Collaborator

@fwrq41251 I don't see the changes you talked about in the comments' followups. Remember to push the new commit to reflect what you described.

@fwrq41251

Copy link
Copy Markdown
Contributor Author

The changes are in the current head 6711cd9d2. I amended and force-pushed at 2026-11-17 00:52 UTC (see the commit's committer date), right before my replies — so the commit still shows Nov 16 as its author date, which is why it looks unchanged.

  • src/java.rs: dap_locator_create_scenario now takes _locator_name; the name check is gone
  • src/debug_locator.rs: no locator_name parameter remains
  • debug_adapter_schemas/Java.json: mainFile.description now says "currently focused Java source file"

You may need to reload or use "View changes since last review" — the threads show the hunks from before the force-push. Sorry for the extra trip; I'll push follow-ups as separate commits from now on.

@tartarughina

Copy link
Copy Markdown
Collaborator

@fwrq41251 let's avoid amending commits, it breaks the natural review flow and reviewing from the phone gets tougher 😅

- Carry the clicked class name from the gutter task as
  ZED_JAVA_MAIN_CLASS and filter JDTLS entries by it, accepting a
  simple or fully-qualified name. Keep project ambiguity an explicit
  error.
- Drop the redundant locator-name parameter and check.
- Clarify the mainFile/mainClass schema and README wording.
- Cover same-file selection, non-matching suffixes and packages, and
  ambiguous projects with tests.
@fwrq41251
fwrq41251 force-pushed the feat/metals-main-debug-locator branch from 6711cd9 to c86eafd Compare November 17, 2026 14:02
@fwrq41251

fwrq41251 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

@tartarughina Thanks, understood. Split the branch into two commits: c10b9a7 is the original feature commit, and c86eafd contains the follow-up changes. The tree is unchanged, so the second commit is the only new delta. Sorry for the one-time force-push needed to restore the split.

@tartarughina

Copy link
Copy Markdown
Collaborator

@fwrq41251 I've tested the extension after the latest changes and everything work as expected. Looking forward to the next PR to include tests as well.

@tartarughina
tartarughina merged commit 09153f5 into zed-extensions:main Nov 17, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants