Guardrails / Collectors

Gradle build

The Gradle build in the project directory: its settings and manifest, every included project, the wrapper and the distribution it pins, the version catalog, and every dependency the build files declare or the lock files resolve, with the versions its platforms supply.

Facts key	gradle
Version	v1
Script	gradle.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
projectDir	Directory holding the project, relative to the directory the CLI runs in.	.	GUARDRAIL_INPUT_PROJECTDIR

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["gradle"]
}

gradle = guardrail.facts("gradle")

Facts

The document gradle collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
directory	The projectDir input, as the guardrail configured it.
exists	Whether that directory is there. Nothing else is collected when it is not, and the collector collects nothing at all when the directory holds no Gradle build, meaning no settings file, no manifest and no version catalog.
settings	Settings file found (settings.gradle.kts or settings.gradle), or null.
manifest	Root manifest found (build.gradle.kts or build.gradle), or null.
sources	The build files that were there to read, in the order they are read.
versionCatalog	Every entry under [versions] in gradle/libs.versions.toml, by name. Empty when there is no catalog.
wrapper.script	Whether gradlew is committed.
wrapper.properties	Path of the wrapper properties file, or null when it is not committed.
wrapper.distributionUrl	The distribution the wrapper pins, or null when it declares none.
wrapper.distributionSha256Sum	Checksum the wrapper properties pin the distribution to, or null when they pin none, in which case the wrapper trusts whatever the distribution URL serves.
wrapper.version	Gradle version named by that URL, or null when it names none.
projects	The root project followed by every project the settings file includes.
projects[].path	Gradle path of the project, : for the root.
projects[].directory	Directory holding it, relative to projectDir.
projects[].manifest	Manifest found in that directory, or null.
dependencies	Every dependency the root project and every included project takes on, split by whether the build declares it. A commented out line is not one, and neither is a project(":x") dependency, a constraints entry or a catalog alias the catalog does not declare.
dependencies.direct	Every dependency a build file declares, in the order the files declare them.
dependencies.direct[].path	group:name of the dependency.
dependencies.direct[].version	Version, taken from the lock file when one resolves it and from a declared platform when the declaration states none. null when nothing in the files resolves one, such as an interpolated variable or a catalog alias declaring no version.
dependencies.direct[].scopes	Every configuration it is declared in, followed by every configuration a lock file resolves it for. The two are different vocabularies: implementation is declarable, runtimeClasspath is resolvable, and a dependency declared and locked carries both.
dependencies.direct[].source	Build file declaring it, relative to projectDir.
dependencies.direct[].platform	Present and true only when it is declared as platform(...) or enforcedPlatform(...), meaning it is a BOM supplying versions rather than code.
dependencies.direct[].managedBy	Present only when the version came from a platform, and then the group:name:version of that platform. The BOM is not in the repository, so it is never read: a platform is matched to a dependency by group, most specific first, and the version taken is the platform's own. Treat a version carrying a managedBy as a hint rather than a fact. It is wrong wherever the BOM does not publish one version line for the whole group, and it is set even on a coordinate the BOM never lists but whose group happens to sit under the platform's. A platform declared in the root manifest supplies versions to every included project, one declared anywhere else only to the project declaring it.
dependencies.transitive	Every dependency a lock file resolves that the project's own build file does not declare, meaning another dependency pulled it in. Empty when the build locks nothing, which lockfiles is how you tell apart from a build that pulls nothing in.
dependencies.transitive[].path	group:name of the dependency.
dependencies.transitive[].version	Version the lock file resolves.
dependencies.transitive[].scopes	Every configuration the lock file resolves it for.
dependencies.transitive[].source	Lock file resolving it, relative to projectDir.
lockfiles	Every dependency lock file that was read, relative to projectDir.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by gradle collector:

{
  "directory": ".",
  "exists": true,
  "settings": "settings.gradle.kts",
  "manifest": "build.gradle.kts",
  "sources": [
    "build.gradle.kts",
    "gradle/libs.versions.toml"
  ],
  "versionCatalog": {
    "kotlin": "2.1.0",
    "junit": "5.11.0"
  },
  "wrapper": {
    "script": true,
    "properties": "gradle/wrapper/gradle-wrapper.properties",
    "distributionUrl": "https://services.gradle.org/distributions/gradle-8.14-bin.zip",
    "distributionSha256Sum": null,
    "version": "8.14"
  },
  "projects": [
    {
      "path": ":",
      "directory": ".",
      "manifest": "build.gradle.kts"
    },
    {
      "path": ":service",
      "directory": "service",
      "manifest": "build.gradle.kts"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "path": "org.http4k:http4k-bom",
        "version": "6.57.2.0",
        "scopes": [
          "implementation"
        ],
        "source": "build.gradle.kts",
        "platform": true
      },
      {
        "path": "org.http4k:http4k-core",
        "version": "6.57.2.0",
        "scopes": [
          "implementation"
        ],
        "source": "build.gradle.kts",
        "managedBy": "org.http4k:http4k-bom:6.57.2.0"
      },
      {
        "path": "org.slf4j:slf4j-api",
        "version": "2.0.13",
        "scopes": [
          "implementation",
          "compileClasspath",
          "runtimeClasspath"
        ],
        "source": "build.gradle.kts"
      },
      {
        "path": "org.junit.jupiter:junit-jupiter",
        "version": "5.11.0",
        "scopes": [
          "testImplementation"
        ],
        "source": "build.gradle.kts"
      },
      {
        "path": "com.google.guava:guava",
        "version": "33.2.0-jre",
        "scopes": [
          "implementation"
        ],
        "source": "service/build.gradle.kts"
      }
    ],
    "transitive": [
      {
        "path": "ch.qos.logback:logback-classic",
        "version": "1.5.6",
        "scopes": [
          "runtimeClasspath"
        ],
        "source": "gradle.lockfile"
      }
    ]
  },
  "lockfiles": [
    "gradle.lockfile"
  ]
}

Collected for

Guardrail	Category	Inputs
build/gradle-version-floor	build	projectDir
build/wrapper-distribution-verified	build	projectDir
kotlin/build-manifest	kotlin	projectDir
kotlin/dependencies-locked	kotlin	projectDir
kotlin/gradle-wrapper	kotlin	projectDir

All collectors