ProjectGuard

KO | EN

gitlite — search

#hacktoberfest #ai #llm #go #android #machine-learning #docker #java #cli #kubernetes #awesome-list #mcp #openai #open-source

(★ 76)

Protect your project against undesired dependencies across different modules.

ProjectGuard Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ProjectGuard

A Gradle plugin that acts as a powerful gatekeeper for your project's dependencies. It helps you enforce architectural rules, prevent unwanted dependencies, and keep your module graph clean and maintainable as your project scales.

[![Maven Central](https://img.shields.io/maven-central/v/com.rubensousa.projectguard/projectguard-gradle-plugin.svg)](https://github.com/rubensousa/ProjectGuard/releases)
![Plugin](https://img.shields.io/badge/gradle-plugin-green)
![Report](https://img.shields.io/badge/Kotlin-white?logo=Kotlin)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/rubensousa/ProjectGuard/push.yml?label=Build)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![AndroidWeekly](https://androidweekly.net/issues/issue-716/badge)](https://androidweekly.net/issues/issue-716)

![ProjectGuard Module Report](https://raw.githubusercontent.com/rubensousa/ProjectGuard/main/example_report_modules.png)

![ProjectGuard Graph Report](https://raw.githubusercontent.com/rubensousa/ProjectGuard/main/example_report_graph.png)

## Why ProjectGuard?

As projects grow, so does the complexity of their module graph. Without clear rules, you can accidentally introduce dependencies that violate your app's architecture or agreed conventions:

- A `:domain` module might depend on another `:legacy` module, making it hard to fully switch away from tech debt.
- An `:impl` module might depend on another `:impl` module, instead of an `:api` or `:domain` one.
- A third-party dependency your team agreed to migrate away from might be added by mistake to a new module.

ProjectGuard protects your project's architecture by enforcing dependency rules that can be checked automatically in your CI/CD setup.

## Key Features

- **Simple DSL:** Configure all your rules in a single block in your gradle configuration
- **Control external libraries:** Leverage Gradle's version catalogs (`libs`) for compile-time safety and IDE autocompletion.
- **Dependency usage reports:** Generate a detailed HTML report that clearly shows all dependency violations, making them easy to identify and fix.
- **CI/CD Integration:** Fail your build when a rule is violated, ensuring that no problematic dependencies make it into your main branch.
- **Baseline Support:** Don't want to fix all existing violations at once? Create a baseline file to ignore them and focus on preventing new issues.
- **Mermaid graph for visualization:** Check your dependency graph for each module of your project

## Setup

1. **Add the following to your `versions.toml`**:

```
    [plugins]
    projectguard = { id = "com.rubensousa.projectguard", version = "see github for latest release" }
    ```

2. **Add the plugin to your root `build.gradle.kts`:**

```kotlin
    // Top-level build.gradle.kts
    plugins {
        alias(libs.plugins.projectguard) apply true
    }
    ```

2.  **Configure your dependency rules:**

```kotlin
    projectGuard {
        // Your configuration goes here. See the examples below!
    }
    ```

## How-to

### Decide when you want to validate the rules

```kotlin
projectGuard {
    options {
        // Default behavior: no immediate validation checks.
        // Use `./gradlew projectGuardAggregateCheck` manually
        lifecycleTask = null
        
        // This will validate the rules during the assemble lifecycle task
        lifecycleTask = LifecycleTask.ASSEMBLE

// This will validate the rules during the check lifecycle task
        lifecycleTask = LifecycleTask.CHECK
    }
}
```

### `guard`

Denies a set of dependencies for any module that matches the provided path.

```kotlin
projectGuard {
    // Deny any module in the `:data` layer from depending on any module in the `:legacy` layer.
    guard(":data") {
        deny(":legacy")
    }

// You can also deny specific dependencies from version catalogs
    guard(":domain") {
        deny(libs.androidx.compose)
    }
}
```

### `restrictModule`

Prevents all dependencies in a module except the ones in the allow list.

```kotlin
projectGuard {
    // Domain modules should only depend on other domain modules and specific libraries.
    restrictModule(":domain") {
        reason("Domain modules have restricted dependencies")
        allow(":domain") // Allow depending on other :domain modules
        allow(libs.junit) // Allow JUnit for testing
    }
    restrictModule(":feature") {
        allow(":domain")
        allowExternalLibraries()
    }
}
```

### `restrictDependency`

Restricts which modules are allowed to depend on a specific dependency. 
This is useful for preventing the use of specific libraries in new modules.

```kotlin
projectGuard {
    // Only allow legacy modules to depend on other legacy modules.
    restrictDependency(":legacy") {
        reason("Legacy modules should no longer be used in new code.")
        allow(":legacy")
    }

// Prevent the use of Mockk in favor of fakes, with a few exceptions.
    restrictDependency(libs.mockk) {
        reason("Fakes should be used instead of mocks.")
        allow(":feature:a") // This feature requires mockk to test platform code.
    }
}
```

### Rules

You can re-use a set of rules across multiple configurations:

```kotlin
projectGuard {
    val legacyConsumers = restrictDependencyRule {
        allow(":legacy")
        allow(":old-feature")
    }
    restrictDependency(":legacy") {
        applyRule(legacyConsumers)
    }
    restrictDependency(libs.mockk) {
        applyRule(legacyConsumers)
    }
}
```

## Tasks

- `./gradlew projectGuardAggregateCheck`: Runs the dependency analysis on the entire project and generates a html report under `rootProject/build/reports/projectguard/index.html`.
- `./gradlew projectGuardCheck`: Runs the dependency analysis on individual modules and generates a html report under `module/build/reports/projectguard/index.html`.
- `./gradlew projectGuardBaseline`: Creates a `projectguard-baseline.yml` file with all current restrictions. This allows you to start enforcing rules on new code without having to fix all existing issues first.

## Report configuration options

```kotlin
projectGuard {
    report {
        // Default is false. When true, libraries are displayed in the dependency graph section
        showLibrariesInGraph = true
    }
}
```

## License

Copyright 2026 Rúben Sousa
    
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

ProjectGuard

ProjectGuard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ProjectGuard

ProjectGuard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README