Pacmon

Dependency notes for Java and Kotlin

A pom.xml or a Gradle build file says which version of a library a service uses. It does not say that the Jackson modules have to move together, that the service is held on an older line until a migration lands, or which integration tests show an upgrade is safe. An XML comment or a // line has room for a phrase, not for that history.

Pacmon keeps a note for each dependency beside its build file — .pacmon/maven/DEPENDENCY-NOTES.md for Maven, .pacmon/gradle/DEPENDENCY-NOTES.md for Gradle — and shows it on the dependency in the editor. Gradle builds in the Groovy and the Kotlin DSL are both read.

What Pacmon reads

Maven

Pacmon reads the <dependencies> of the project and its profiles, not <dependencyManagement> or plugin dependencies. Parent POMs are not read.

Gradle

Pacmon reads module coordinates and libs.* aliases in a dependencies block, not plugins, constraints, project(…), files(…) or catalog bundles. The script is never run, so a dependency added by code is not seen.

Pacmon never runs Maven or Gradle, and it does not resolve parent POMs, BOMs or libs.versions.toml. A note belongs to the dependency as the build file writes it.

Example

<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
  </dependency>
  <dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.18.2</version>
  </dependency>
</dependencies>

.pacmon/maven/DEPENDENCY-NOTES.md:

## com.fasterxml.jackson.core:jackson-databind

JSON for the REST API and the Kafka payloads. Upgrade every Jackson artifact together.

### Agent notes

- purpose: JSON mapping for the REST API and the Kafka message payloads
- bump-with: com.fasterxml.jackson.datatype:jackson-datatype-jsr310
- verify: `mvn -pl api test` and the contract tests (`mvn -Pcontract verify`)
- verified: 2.18.2

In a Gradle build, a version-catalog alias is a note key of its own:

dependencies {
    implementation("org.slf4j:slf4j-api:2.0.16")
    testImplementation(libs.junit.jupiter)
}

Its sections in .pacmon/gradle/DEPENDENCY-NOTES.md are ## libs.junit.jupiter and ## org.slf4j:slf4j-api.

For AI coding agents

An agent reads a dependency's section before it adds, upgrades or removes it. bump-with: lists the artifacts that have to move with it, and verify: the Maven or Gradle tasks to run afterwards. See the rules agents follow.