feat: resolve classpath from pom.xml and build.gradle via //DEPS

[maxandersen]

Experimental: build-file classpath resolution

This is an experiment — I'd like feedback on whether this is useful and worth keeping.

What it does

You can now pass a Maven or Gradle build file as a dependency. JBang shells out to the build tool, grabs the runtime classpath, caches it, and adds the entries to your script's classpath.

In source:

//DEPS pom.xml
//DEPS build.gradle
//DEPS ^pom.xml

From the command line:

jbang run --deps pom.xml app.java
jbang run --deps ^pom.xml src/main/java/app.java

The ^ prefix means "walk upward from the script location and use the nearest matching file." So ^pom.xml inside src/main/java/app.java finds the pom.xml three directories up.

How it works

• For Maven: runs mvn dependency:build-classpath (prefers mvnw when present)
• For Gradle: injects a tiny init script that prints sourceSets.main.runtimeClasspath (prefers gradlew)
• Caches the result keyed by build file path + size + timestamp; --fresh forces re-resolution
• Build files flow through //DEPS naturally — they're not GAVs and not source files, so they get their own handling in the existing source-dependency loop

Questions I'd like input on

1. Is this useful? The idea is that if you're writing a quick script inside an existing Maven/Gradle project, you get all the project's dependencies without listing them again.

2. Should the ^ (upward search) syntax be a general thing? Right now ^pom.xml and ^build.gradle are the only supported forms. But should ^my-utils.java also work — finding the nearest matching source file by walking up? That could be handy for shared utility files in monorepos, but it's also a different feature and might deserve its own discussion.

3. Build tool execution runs arbitrary code. Maven plugins and Gradle build scripts can do anything. This is opt-in (you explicitly write //DEPS pom.xml), but worth calling out. Should there be a trust prompt?

Changes

• BuildSystemClassPaths.java — new helper that detects build files, shells out, caches results
• ProjectBuilder.java — intercepts build-file refs in the source-dependency loop and in CLI --deps
• TestBuildSystemClassPaths.java — tests with fake mvnw scripts
• running.adoc — documents the feature as experimental

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• ai-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 16df3b82-55be-4349-85ef-aafa944f88a5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cebaa]

Thanks @maxandersen!

1. Definitely very useful to keep things DRY
2. Looks like it would be a nice feature. It probably depends on how much it would complicate the code base. Probably best discussed separately. However, it really would be useful to allow something like //SOURCES ^src/main/java/**/*.java or //SOURCES ^target/classes as it's likely other classes from the same project may need to be used from the script
3. I feel //DEPS ^pom.xml is explicit enough. There's a chance you can git clone someone else's repo and add a //DEPS ^pom.xml in a script inside it, but seems like a stretch to guard against that. It could be //DEPS-POTENTIALLY-DANGEROUS ^pom.xml if you prefer, but seems unnecessary (especially since //DEPS <whatever dep> is also potentially dangerous as that dep can do anything as well)

[cebaa]

@maxandersen any objections to merging this so it gets pulled into the next release?

[maxandersen]

Yeah it's a biy too simplistic yet. Ie. ^ shouldn't be needed - and only be there if want to search "upward".

And also need to review the lookup of the right build command and handle failure.

Have you used it and four it useful?

[cebaa]

Yeah I have one big (maven / pom.xml) project with some jbang scripts embedded. I've been using it daily since I picked up this PR a month and a half ago.

I'm not doing anything complicated, just picking deps from the parent pom.xml and some classes from the project as well, but no issues so far. I feel it's a nice improvement, though I'm sure others will find other use cases after you merge it and it becomes generally available.

I want to say I'm pretty impressed by jbang so far. It just works, it's fast, it gets out of the way. It is a very refreshing experience, so thanks for that!

[maxandersen]

Superseded by #2657, which extends this to sbt and Mill, refactors the four strategies behind a BuildSystem interface, adds a filesystem cache, fixes CLI --deps path resolution, rejects the feature for remote scripts up front, and ships real integration tests (via mise) plus fixtures for each supported tool. Closing this one is fine — all the review threads here are addressed in the new PR's description under "What changed vs #2597".

[maxandersen]

@cebaa please try out #2657 and let me know how it works for you.