@versu/plugin-gradle - Gradle Adapter Plugin

Gradle adapter plugin for Versu. Provides first-class support for versioning Gradle projects (Groovy & Kotlin DSL) in monorepo environments with automatic dependency detection and cascading version updates.

Installation

With Core Library

npm install @versu/core @versu/plugin-gradle

With CLI

npm install -g @versu/cli @versu/plugin-gradle

With GitHub Action

The plugin is automatically included with the GitHub Action. No separate installation needed.

Features

✅ Multi-Module Support - Automatic detection of Gradle multi-module projects ✅ Dual DSL Support - Works with both Groovy and Kotlin DSL ✅ Centralized Versioning - All versions managed through root gradle.properties ✅ Dependency Detection - Automatic project dependency analysis ✅ SNAPSHOT Support - Optional -SNAPSHOT suffix for development builds ✅ Auto-Detection - Automatically detected when Gradle files are present

Usage

With @versu/core

import { VersuRunner } from '@versu/core';
import gradlePlugin from '@versu/plugin-gradle';

const runner = new VersuRunner({
  repoRoot: '/path/to/repository',
  plugins: [gradlePlugin],
  adapter: 'gradle', // Optional - auto-detected
});

const result = await runner.run();

With @versu/cli

The plugin is automatically loaded when installed globally:

npm install -g @versu/plugin-gradle
versu --adapter gradle

With @versu/action

- name: Install Gradle plugin
  run: npm install -g @versu/plugin-gradle

- name: Version modules
  uses: versuhq/versu@v0
  with:
    adapter: gradle

Project Structure

The Gradle adapter expects a specific project structure:

Required Files

• settings.gradle or settings.gradle.kts - Defines multi-module structure
• gradle.properties (root) - Contains all module versions

Version Management

All module versions must be declared in the root gradle.properties file:

# Root module version
version=1.0.0

# Submodule versions
core.version=2.1.0
api.version=1.5.0
utils.version=3.0.0

Version Property Naming

• Root module: Use version property
• Submodules: Use {moduleName}.version pattern
  • Module name is derived from settings.gradle(.kts) configuration
  • For module :core, use property core.version
  • For module :lib:utils, use property lib-utils.version (: replaced with -)

Example Project

myproject/
├── settings.gradle.kts
├── build.gradle.kts
├── gradle.properties          # All versions here
├── core/
│   └── build.gradle.kts
├── api/
│   └── build.gradle.kts
└── lib/
    └── utils/
        └── build.gradle.kts

settings.gradle.kts:

rootProject.name = "myproject"

include(":core")
include(":api")
include(":lib:utils")

gradle.properties:

version=1.0.0
core.version=2.1.0
api.version=1.5.0
lib-utils.version=3.0.0

Dependency Detection

The plugin automatically detects project dependencies using a custom Gradle init script. Dependencies are analyzed to determine version cascading when modules are updated.

Supported Dependency Types

• implementation
• api
• compileOnly
• runtimeOnly
• And other standard Gradle dependency configurations

Example

If api depends on core, and core gets a version bump, Versu will automatically cascade the change to api based on your dependency rules configuration.

Configuration

The Gradle plugin respects all Versu configuration options. See the core package documentation for details.

Gradle-Specific Options

When using the appendSnapshot option, the plugin adds -SNAPSHOT suffix to all versions:

const runner = new VersuRunner({
  repoRoot: '/path/to/repository',
  adapter: 'gradle',
  appendSnapshot: true, // Generates versions like 1.2.3-SNAPSHOT
});

Auto-Detection

The plugin automatically activates when any of these files are present in the repository root:

• build.gradle
• build.gradle.kts
• settings.gradle
• settings.gradle.kts

Plugin Architecture

The plugin implements the Versu plugin contract:

interface PluginContract {
  id: string;
  name: string;
  description: string;
  version: string;
  author: string | string[];
  adapters: AdapterPluginContract[];
}

Components

1. GradleAdapterIdentifier - Detects Gradle projects
2. GradleModuleDetector - Discovers modules and dependencies
3. GradleVersionUpdateStrategy - Updates versions in gradle.properties
4. GradleModuleSystemFactory - Orchestrates the components

Limitations

• Version Source: Only gradle.properties is supported for version management
• Module Location: All modules must be declared in settings.gradle(.kts)
• Version Format: Versions must follow semantic versioning (e.g., 1.2.3)

Development

Building

# From monorepo root
npm run build

# Or from plugin package
cd packages/plugin-gradle
npm run build

Testing

# From monorepo root
npm test

# Or from plugin package
cd packages/plugin-gradle
npm test
npm run test:coverage

Publishing

npm publish --workspace packages/plugin-gradle --access public

Related Packages

• @versu/core - Core library for programmatic usage
• @versu/cli - Command-line interface
• @versu/action - GitHub Actions integration

Requirements

• Node.js: >= 20
• Gradle: >= 6.0 (tested with Gradle 6.x - 8.x)
• Java: Required for running Gradle

License

MIT License - see LICENSE for details.