go-package-dependency

Important

This tool is experimental and provided as-is. Please use it at your own risk and discretion. The API and behavior may change without notice.

A command-line tool that generates Go dependency files based on architectural layer definitions in Markdown format.

Overview

go-package-dependency helps enforce clean architecture principles by automatically generating dependency.gen.go files that contain import declarations based on dependency relationships defined in a DEPENDENCY.md file. This ensures that your Go modules follow the intended architectural layers and dependency directions.

Features

• 📝 Markdown-driven: Define your architecture layers and dependencies in a simple DEPENDENCY.md file
• 🔄 Automatic generation: Creates dependency.gen.go files with appropriate import statements
• 🏗️ Clean architecture: Enforces dependency direction and prevents circular dependencies
• 🚀 Build-time validation: Dependency violations are caught during compilation
• 📦 Module-aware: Automatically detects Go module names from go.mod

Usage

go run github.com/handlename/go-package-dependency@latest <path-to-dependency-md>

or

go get -tool github.com/handlename/go-package-dependency@latest
go tool go-package-dependency <path-to-dependency-md>

Examples

# Generate dependency files from DEPENDENCY.md
go-package-dependency example/DEPENDENCY.md

# Show help
go-package-dependency --help

DEPENDENCY.md Format

The DEPENDENCY.md file should follow this structure:

# Dependencies

## Layers

Upper layers cannot depend on lower layers.

1. Domain layer
  - Implementation of core entities
2. Application layer
  - Business logic using objects from the domain layer
3. Presentation layer
  - UI and presentation logic
4. Infra layer
  - Gateway to the real world

## Packages in layers

Upper packages cannot depend on lower packages.

1. Domain layer
  - domain/entity
  - domain/valueobject
    - domain/service
2. Application layer
  - app/service
    - app/usecase
3. Presentation layer
  - api
  - cli
4. Infra layer
  - infra/database
  - infra/cache

Format Specification

Layers Section

• Define layer names and their responsibilities
• Use ordered points (1., 2., ...) for layer names
• Use indented bullet points ( -) for layer descriptions
• Lower layers depend on upper layers
• Upper layers cannot depend on lower layers

Packages in layers Section

• Define packages in each layer
• Use ordered points (1., 2., ...) for parent package names
• Use indented bullet points ( -, -, ...) for package paths
• Lower packages depend on upper packages in the same layer
• Upper packages cannot depend on lower packages
• Package paths are relative to the directory containing DEPENDENCY.md

Generated Files

For each layer with a defined package path, go-package-dependency generates a dependency.gen.go file containing:

// Code generated by go-package-dependency. DO NOT EDIT.

package usecase

import (
	_ "github.com/handlename/go-package-dependency/example/app/service"
	_ "github.com/handlename/go-package-dependency/example/domain/entity"
	_ "github.com/handlename/go-package-dependency/example/domain/service"
	_ "github.com/handlename/go-package-dependency/example/domain/valueobject"
)

Example Project Structure

example/
├── DEPENDENCY.md
├── go.mod
├── domain/
│   ├── entity/
│   │   └── dependency.gen.go
│   ├── valueobject/
│   │   └── dependency.gen.go
│   └── service/
│       └── dependency.gen.go
├── app/
│   ├── service/
│   │   └── dependency.gen.go
│   └── usecase/
│       └── dependency.gen.go
├── api/
│   └── dependency.gen.go
├── cli/
│   └── dependency.gen.go
└── infra/
    ├── database/
    │   └── dependency.gen.go
    └── cache/
        └── dependency.gen.go

Benefits

1. Enforced Architecture

• Compile-time validation: Dependency violations cause build failures
• Clear boundaries: Explicit layer definitions prevent architectural drift
• Documentation: DEPENDENCY.md serves as living architecture documentation

2. Clean Code

• Dependency direction: Ensures dependencies flow in the intended direction
• Circular dependency prevention: Go compiler catches circular imports
• Maintainability: Clear architectural boundaries improve code organization

3. Team Collaboration

• Shared understanding: Team members can easily understand the architecture
• Code reviews: Architectural violations are visible in pull requests
• Onboarding: New team members quickly grasp the project structure

Use Cases

• Clean Architecture: Implement Uncle Bob's Clean Architecture pattern
• Hexagonal Architecture: Enforce port-adapter pattern boundaries
• Layered Architecture: Maintain traditional N-tier architecture
• Domain-Driven Design: Separate domain, application, and infrastructure concerns

Configuration

Module Detection

go-package-dependency automatically detects your Go module name from the go.mod file in the same directory as your DEPENDENCY.md file.

Directory Structure

• Place DEPENDENCY.md in the root of your module or submodule
• Package paths in the layers section are relative to the DEPENDENCY.md location
• Each layer's directory must exist for the dependency file to be generated

Advanced Examples

Complex Dependency Chain

## Dependencies
- Infrastructure -> Interface -> Application -> Domain
- Shared -> Domain
- Shared -> Application
- Shared -> Interface

Multiple Packages Per Layer

## Layers
- Domain layer
  - domain/entity
  - domain/repository
  - domain/service
- Application layer
  - usecase/user
  - usecase/order

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

@handlename (Hiroaki NAGATA) w/ AI agent