archlint

🇬🇧 English version

Инструмент для построения архитектурных графов из исходного кода Go.

archlint позволяет автоматически извлекать и визуализировать архитектуру программных систем используя два типа графов:

• Структурный граф - статический анализ кода, показывающий все компоненты и связи
• Поведенческий граф - динамический анализ через трассировку, показывающий фактические потоки выполнения

Возможности

• ✅ Построение структурных графов из Go кода
• ✅ Генерация поведенческих графов из трассировок тестов
• ✅ Экспорт в формат DocHub YAML
• ✅ Автоматическая генерация sequence диаграмм PlantUML
• ✅ Поддержка wildcards для группировки компонентов

Contribution

Проект развивается через спецификации. Каждая фича или изменение описывается в спецификации, а реализация выполняется с помощью Claude Code.

git clone https://github.com/mshogin/archlint
cd archlint
make implement

make implement запускает Claude Code в интерактивном режиме с инструкцией по реализации спецификаций из specs/todo/. Claude Code возьмет спецификацию в работу, перенесет её в specs/inprogress/, закоммитит и запушит (чтобы уведомить остальных участников), а затем реализует описанные изменения.

Структура спецификаций:

specs/
├── todo/         # Спецификации, ожидающие реализации
├── inprogress/   # Спецификации в работе
└── done/         # Завершенные спецификации

Установка

Из исходников

git clone https://github.com/mshogin/archlint
cd archlint
make install

Установит archlint в $GOPATH/bin.

Сборка

make build

Бинарный файл будет создан в bin/archlint.

Использование

1. Построение структурного графа

Анализирует исходный код и строит граф всех компонентов (пакеты, типы, функции, методы) и их зависимостей.

archlint collect . -o architecture.yaml

Пример вывода:

Analyzing code: . (language: go)
Found components: 95
  - package: 5
  - struct: 23
  - function: 30
  - method: 21
  - external: 15
Found links: 129
✓ Graph saved to architecture.yaml

Структура графа:

components:
  cmd/archlint:
    title: main
    entity: package
  cmd/archlint.main:
    title: main
    entity: function
  internal/analyzer.GoAnalyzer:
    title: GoAnalyzer
    entity: struct

links:
  cmd/archlint:
    - to: cmd/archlint.main
      type: contains
  cmd/archlint.main:
    - to: internal/analyzer.NewGoAnalyzer
      type: calls

contexts:
  cmd:
    title: cmd
    location: Architecture/cmd
    components:
      - cmd/archlint
      - cmd/archlint.main

2. Построение поведенческого графа

Генерирует контексты из трассировок тестов, показывая фактические потоки выполнения.

Шаг 1: Добавьте трассировку в тесты:

import "github.com/mshogin/archlint/pkg/tracer"

func TestProcessOrder(t *testing.T) {
    trace := tracer.StartTrace("TestProcessOrder")
    defer func() {
        trace.Save("traces/test_process_order.json")
    }()

    // Трассируемая функция
    tracer.Enter("OrderService.ProcessOrder")
    result, err := service.ProcessOrder(order)
    tracer.Exit("OrderService.ProcessOrder", err)

    // проверки...
}

Шаг 2: Запустите тесты:

go test -v ./...

Шаг 3: Сгенерируйте контексты:

archlint trace ./traces -o contexts.yaml

Результат:

• contexts.yaml - контексты для DocHub
• *.puml - PlantUML sequence диаграммы для каждого теста

3. Использование Makefile

# Показать справку
make help

# Собрать проект
make build

# Построить граф для самого archlint
make collect

# Форматировать код
make fmt

# Запустить тесты
make test

# Очистить сгенерированные файлы
make clean

Структура проекта

archlint/
├── cmd/
│   └── archlint/          # CLI приложение
│       ├── main.go        # Точка входа
│       ├── collect.go     # команда collect
│       └── trace.go       # команда trace
├── internal/
│   ├── model/             # Модель графа
│   │   └── model.go       # Graph, Node, Edge, DocHub
│   └── analyzer/          # Анализаторы кода
│       └── go.go          # GoAnalyzer (AST парсинг)
├── pkg/
│   └── tracer/            # Библиотека трассировки
│       ├── trace.go       # Сбор трассировок
│       └── context_generator.go  # Генератор контекстов
├── go.mod
├── Makefile
└── README.md

Примеры

Анализ собственного проекта

archlint использует себя в качестве примера:

make collect

Результат: graph/architecture.yaml с полным графом проекта.

Интеграция с DocHub

Сгенерированные YAML файлы совместимы с DocHub:

# dochub.yaml
contexts:
  $imports:
    - architecture.yaml
    - contexts.yaml

Формат данных

Структурный граф

• Узлы (components): компоненты системы

  • package - Go пакеты
  • struct - структуры
  • interface - интерфейсы
  • function - функции
  • method - методы
  • external - внешние зависимости

• Ребра (links): связи между компонентами

  • contains - вложенность (пакет содержит тип)
  • calls - вызов функции/метода
  • uses - использование типа в поле
  • embeds - встраивание типа
  • import - импорт пакета

Поведенческий граф

• Trace: трассировка выполнения теста
  • test_name - имя теста
  • calls - последовательность вызовов
    • event: "enter" | "exit_success" | "exit_error"
    • function - имя функции
    • depth - уровень вложенности

Связь с aiarch

archlint содержит только функциональность построения графов из проекта aiarch.

Что НЕ включено в archlint:

• Валидация графов
• Метрики качества (fan-out, coupling и т.д.)
• Проверка архитектурных правил

Для валидации и метрик используйте aiarch.

Лицензия

MIT

Контакты

• GitHub: https://github.com/mshogin/archlint
• Связанный проект: https://github.com/mshogin/aiarch