go-arch-lint

README

Linter used to enforce some good project structure and validate top level architecture (code layers)

Quick start

What exactly is project architecture?

You can imagine some simple architecture, for example classic onion part from "clean architecture":

And describe/declare it as semantic yaml linter config:

version: 3
workdir: internal
components:
  handler:    { in: handlers/* }           # wildcard one level
  service:    { in: services/** }          # wildcard many levels
  repository: { in: domain/*/repository }  # wildcard DDD repositories
  model:      { in: models }               # match exactly one package

commonComponents:
  - models

deps:
  handler:
    mayDependOn:
      - service
  service:
    mayDependOn:
      - repository

see config syntax for details.

And now linter will check all project code inside internal workdir and show warnings, when code violate this rules.

For best experience you can add linter into CI workflow

Example of broken code

Imagine some main.go, when we provide repository into handler and get some bad flow:

func main() {
  // ..
  repository := booksRepository.NewRepository()
  handler := booksHandler.NewHandler(
    service,
    repository, // !!!
  )
  // ..
}

Linter will easily found this issue:

Install/Run

Wia Docker

docker run --rm -v ${PWD}:/app fe3dback/go-arch-lint:latest-stable-release check --project-path /app

other docker tags and versions

From sources

It require go 1.20+

go install github.com/LazarenkoA/go-arch-lint@latest

go-arch-lint check --project-path ~/code/my-project
# or
cd ~/code/my-project
go-arch-lint check

Precompiled binaries

see on releases page

IDE plugin for autocompletion and other help

https://plugins.jetbrains.com/plugin/15423-goarchlint-file-support

Usage

How to add linter to existing project?

Adding a linter to a project takes several steps:

1. Current state of the project
2. Create a .go-arch-lint.yml file describing the ideal project architecture
3. Linter find some issues in the project. Don’t fix them right now, but “legalize” them by adding them to the config and marking todo with the label
4. In your free time, technical debt, etc. fix the code
5. After fixes, clean up config to target state

Execute

Usage:
  go-arch-lint check [flags]

Flags:
      --arch-file string      arch file path (default ".go-arch-lint.yml")
  -h, --help                  help for check
      --max-warnings int      max number of warnings to output (default 512)
      --project-path string   absolute path to project directory (where '.go-arch-lint.yml' is located) (default "./")

Global Flags:
      --json                   (alias for --output-type=json)
      --output-color           use ANSI colors in terminal output (default true)
      --output-json-one-line   format JSON as single line payload (without line breaks), only for json output type
      --output-type string     type of command output, variants: [ascii, json] (default "default")

This linter will return:

Status Code	Description
0	Project has correct architecture
1	Found warnings

How is working?

Linter will:

• match/mark go packages with components
• finds all dependencies between components
• build a dependency graph
• compares the actual (code) and desired (config) dependency graph
• if it got a non-empty DIFF, then project has some issues

Graph

Example config of this repository: .go-arch-lint.yml

You can generate dependencies graph with command graph:

go-arch-lint graph

See full graph documentation for details.

Pre-Commit

go-arch-lint can also be used as a pre-commit hook, acting before each commit is made.
This is useful to always check that your new code still respects your repo architecture, and to always update your graph SVG.

1. Install pre-commit from https://pre-commit.com/#install
2. Create a .pre-commit-config.yaml file at the root of your repository with the following content:

repos:
  - repo: https://github.com/LazarenkoA/go-arch-lint
    rev: master
    hooks:
      - id: go-arch-lint-check
      - id: go-arch-lint-graph
        args: ['--include-vendors=true', '--out=go-arch-lint-graph.svg']

1. If needed, add any flags you need in args.
2. Auto-update the config to the latest repos' versions by executing pre-commit autoupdate
3. Install with pre-commit install
4. Now you're all set! Try a commit, and see the logs (passing or failing).