Stirling-PDF/buildSrc

Dependency license overrides

The backend dependency license report is generated by the com.github.jk1.dependency-license-report Gradle plugin. Most license information is read from dependency POM files, manifests, or packaged license files. Some artifacts do not publish license metadata in a form the plugin can detect, even though the artifact has a known license.

This directory contains the build logic used to provide narrowly scoped fallback license metadata for those artifacts.

Files

• build.gradle makes version 3.1.4 of the license report plugin available to the custom build logic. The root build applies that plugin without a second version declaration so both use the same classpath.
• src/main/groovy/stirling/software/gradle/ModuleLicenseOverrideFilter.groovy implements the plugin's DependencyFilter interface.
• ../app/license-overrides.json contains the actual module-specific fallback values.
• ../app/allowed-licenses.json defines which detected or supplied licenses are accepted by checkLicense.

How it works

The root build.gradle passes app/license-overrides.json to ModuleLicenseOverrideFilter:

filters = [new ModuleLicenseOverrideFilter(moduleLicenseOverridesFile)]

For every dependency discovered by the license plugin, the filter builds an identifier in this format:

group:artifact:version

The filter applies a populated override only when both conditions are true:

1. The complete identifier, including the version, exists in app/license-overrides.json.
2. The plugin did not discover a non-empty license name for that dependency.

When both conditions match, the filter adds the configured license as fallback manifest metadata. The normal report renderer and checkLicense then consume that metadata in the same way as metadata discovered from the dependency itself.

An override never replaces a license that the plugin already detected. Updating a dependency also does not silently reuse the override because a different version produces a different identifier.

Overrides are temporary fallbacks, not a permanent license catalog. If the plugin starts detecting the original license for an overridden module, the filter automatically removes that exact entry from app/license-overrides.json and logs the cleanup. When the overridden version is no longer resolved, a newer resolved version takes its place: if it declares a license, the stale entry is removed; otherwise the entry moves to the new exact version and its values are cleared for re-verification. An already populated entry for the new version is preserved. If no higher version is resolved, the unused override is removed instead.

Because the report aggregates several projects and configurations, multiple versions of the same group:artifact can be present at once. An override is retained whenever its exact version is still resolved. Only when that exact version is absent may the filter treat a higher version as an update; version ordering then follows Gradle's own dependency version comparator. Overrides for dependency versions that are no longer resolved and have no higher replacement are deleted automatically.

The filter also records every resolved dependency without detected license metadata that has no override yet. It writes a placeholder with null values for name, url, and projectUrl. Placeholders deliberately do not affect the generated report until name is filled in. This makes new missing metadata visible in the source-controlled override file instead of only in a generated report. Review and fill or remove every new placeholder before committing the resulting JSON.

Adding an override

First verify the license from an authoritative source such as the upstream repository, the published artifact metadata, or the license file shipped inside the artifact. Do not infer a license from the organization name or from a related artifact.

Add an entry to app/license-overrides.json:

{
  "com.example:example-library:1.2.3": {
    "name": "Apache License, Version 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0",
    "projectUrl": "https://github.com/example/example-library/tree/0123456789abcdef0123456789abcdef01234567"
  }
}

The key must contain the exact resolved version. name must be non-empty for the override to be applied. url should point to the canonical license text. projectUrl must point to the immutable Git tree for the exact module version, using the commit hash at which that version was introduced:

https://github.com/<owner>/<repository>/tree/<full-commit-hash>

Do not use the repository's default branch or another moving URL. See the existing entries in app/license-overrides.json for concrete examples.

If the license name is not already accepted, add a suitably narrow rule to app/allowed-licenses.json. Adding an override and allowing a license are separate operations:

• license-overrides.json supplies missing metadata for a specific artifact version.
• allowed-licenses.json defines the policy enforced by checkLicense.

Updating a dependency

When an overridden dependency changes version:

1. Verify the license for the new version again.
2. Run the license report so the filter can move the old key or add a placeholder for the new full group:artifact:version key.
3. Re-verify and fill the license values and the version's immutable Git-tree projectUrl; moved values are intentionally cleared because a license conclusion for one release is not assumed for another.
4. Regenerate and inspect the report.

If the new artifact publishes usable license metadata, no override is necessary. The next license report or license check removes the old entry from app/license-overrides.json automatically. The file must contain only overrides that are still needed.

Verification

Run the filter unit tests:

.\gradlew.bat -p buildSrc test

The tests use com.example:example-library versions 1.4 and 1.7 to cover the missing metadata fallback, placeholder creation, version migration, preservation of a populated newer override, automatic cleanup after license metadata appears, exact-version matching, and concurrent resolved versions. They also verify removal when a dependency version disappears. A separate 1.9 to 1.11.0 case verifies numeric Gradle version ordering.

Run the normal backend license workflow from the repository root:

task backend:licenses:generate

Then inspect:

• build/reports/dependency-license/index.json for the rendered module, version, license name, and URL.
• build/reports/dependency-license/dependencies-without-allowed-license.json when checkLicense reports a policy failure.

Also run the backend quality gate after changing the filter or its build wiring:

task backend:check

The override JSON is registered as an input of generateLicenseReport and checkLicensePreparation, so changing the file invalidates the corresponding Gradle task outputs.

What not to do

• Do not use an unversioned key. It cannot match the filter and would make the intended scope ambiguous.
• Do not use an override to replace valid license metadata published by a dependency.
• Do not add an empty license to allowed-licenses.json merely to silence checkLicense; that would still leave the generated report without useful license information.
• Do not exclude a dependency from the report solely because it is transitive. Runtime transitive dependencies are still distributed components and their licenses remain relevant.
• Do not edit generated files under build/reports/dependency-license or the copied static license report by hand.