🔍 Hexagonal DDD Analyzer

🚀 Key Features

High Performance & Parallel Processing

• ⚡ Parallel file analysis with configurable concurrency
• 📊 Real-time progress reporting during analysis
• 🎯 CPU-aware defaults (automatically detects available cores)
• 🚦 Configurable limits to prevent resource exhaustion

Usage Examples:

# Fast parallel analysis (default: 4 concurrent files)
hex-ddd-analyzer analyze "src/**/*.ts"

# Maximum performance (8 concurrent files)
hex-ddd-analyzer analyze "src/**/*.ts" --max-concurrency 8

# Sequential processing for debugging
hex-ddd-analyzer analyze "src/**/*.ts" --disable-parallel

Comprehensive Console Output

• 📋 Summary at the beginning with key metrics
• 📈 Final summary at the end with quality progress bar
• 🎨 Color-coded severity levels (red/yellow/blue)
• 📂 Categorized violation breakdown (SOLID, DDD, Architecture, Security)

Enterprise Architecture Analysis

• 🏗️ Hexagonal Architecture validation
• 🎯 Domain-Driven Design (DDD) pattern detection
• 🛡️ SOLID Principles compliance checking
• 🔒 Security vulnerability detection
• 📏 Code quality metrics and thresholds

Front Matter

Название документа: Руководство пользователя Hexagonal DDD Analyzer
Версия: 1.0.0
Дата: 20 декабря 2025 года
Автор: Команда разработчиков Hexagonal DDD Analyzer
Организация: Независимый проект

История версий:

• v1.0.0 (20.12.2025): Первоначальный выпуск руководства пользователя.

Введение

Назначение документа

Настоящее руководство пользователя описывает статический анализатор Hexagonal DDD Analyzer, предназначенный для проверки соответствия кодовой базы TypeScript/Angular принципам гексагональной архитектуры и доменно-ориентированного проектирования (DDD). Документ предназначен для помощи разработчикам, архитекторам и командам обеспечения качества в поддержании высокого качества кода и архитектуры.

Область применения

Анализатор проверяет соответствие следующим аспектам:

• Принципы SOLID.
• Паттерны DDD (сущности, объекты значений, агрегаты, сервисы домена, репозитории).
• Гексагональная архитектура (разделение слоев, направление зависимостей, порты и адаптеры, CQRS).
• Безопасность и качество кода (управление конфигурацией, обнаружение чувствительных данных, анализ сложности кода, валидация соглашений именования).

Целевая аудитория

• Разработчики TypeScript/Angular с опытом работы в DDD и гексагональной архитектуре.
• Архитекторы программного обеспечения, отвечающие за поддержание архитектурных стандартов.
• Команды QA и DevOps, интегрирующие анализ в CI/CD пайплайны.
• Технические писатели и аудиторы, проверяющие соответствие документации стандартам.

Предварительные знания

Пользователи должны обладать:

• Базовыми знаниями TypeScript и Angular.
• Пониманием принципов DDD и гексагональной архитектуры.
• Опыт работы с командной строкой и инструментами статического анализа.

Ссылочные документы

• ISO/IEC/IEEE 26514: Systems and software engineering — Requirements for designers and developers of user documentation.
• Domain-Driven Design: Tackling Complexity in the Heart of Software (Eric Evans).
• Clean Architecture: A Craftsman's Guide to Software Structure and Design (Robert C. Martin).
• Hexagonal Architecture (Alistair Cockburn).

Концепция операций

Обзор функций системы

Hexagonal DDD Analyzer представляет собой инструмент командной строки, который анализирует исходный код TypeScript/Angular и выявляет нарушения архитектурных принципов. Система работает путем статического анализа AST (абстрактного синтаксического дерева) с использованием TypeScript Compiler API.

Типичные роли пользователей и сценарии использования

• Разработчик: Проверяет код перед коммитом, исправляет нарушения в реальном времени.
• Архитектор: Оценивает общее состояние архитектуры проекта, генерирует отчеты для стейкхолдеров.
• Команда QA: Интегрирует анализ в автоматизированные тесты и CI/CD пайплайны.
• DevOps-инженер: Настраивает автоматический анализ в конвейерах развертывания.

Операционная среда и ограничения

• Поддерживаемые платформы: Windows, macOS, Linux.
• Требования: Node.js 16+, npm или yarn.
• Ограничения: Анализирует только TypeScript-файлы, не поддерживает другие языки программирования.
• Производительность: Время анализа зависит от размера кодовой базы (рекомендуется < 1000 файлов за раз).

Установка и конфигурация

Системные требования

• Node.js версии 16.0 или выше.
• npm или yarn для управления пакетами.
• Минимум 512 MB оперативной памяти.
• Доступ к файловой системе для чтения исходного кода.

Шаги установки

1. Установите анализатор глобально:

   npm install -g hex-ddd-analyzer

2. Или установите как зависимость разработки:

   npm install --save-dev hex-ddd-analyzer

3. Проверьте установку:

   hex-ddd-analyzer --version

Конфигурация и начальная настройка

Создайте файл hex-ddd.config.json в корне проекта:

{
  "rules": {
    "enabled": ["srp", "dip", "layer-dependency", "entity"],
    "severity": {
      "dip": "error",
      "layer-dependency": "error"
    }
  },
  "layers": {
    "domain": ["**/domain/**", "**/core/**"],
    "application": ["**/application/**", "**/use-case/**"],
    "infrastructure": ["**/infrastructure/**", "**/adapter/**"],
    "presentation": ["**/presentation/**", "**/controller/**"]
  },
  "exclusions": {
    "files": ["**/node_modules/**", "**/*.test.ts"],
    "directories": ["dist", "build"]
  },
  "thresholds": {
    "maxComplexity": 10,
    "maxDependencies": 15
  }
}

Проверка после установки

Запустите тестовый анализ:

hex-ddd-analyzer analyze "**/*.ts" --dry-run

Ожидаемый результат: Вывод списка найденных файлов без выполнения полного анализа.

Процедуры

Обзор задач

Основные процедуры включают анализ кода, генерацию отчетов и управление конфигурацией.

Процедура: Выполнение базового анализа

Назначение: Анализировать все файлы TypeScript в текущем каталоге.

Предусловия:

• Установлен Hexagonal DDD Analyzer.
• Находится в корне проекта с TypeScript-файлами.
• Конфигурационный файл создан (опционально).

Шаги:

1. Откройте командную строку.
2. Перейдите в корень проекта.
3. Выполните команду: hex-ddd-analyzer analyze "**/*.ts".
4. Дождитесь завершения анализа.

Результат: Отчет с нарушениями, сгруппированными по файлам и категориям.

Примечания: Используйте --output json для структурированного вывода.

Процедура: Генерация JSON-отчета

Назначение: Создать машиночитаемый отчет для интеграции в CI/CD.

Предусловия:

• Выполнен анализ кода.

Шаги:

1. После анализа добавьте флаг: --output json > analysis.json.
2. Проверьте содержимое файла analysis.json.

Результат: JSON-файл с детальной информацией о нарушениях.

Процедура: Инициализация конфигурации

Назначение: Создать файл конфигурации по умолчанию.

Шаги:

1. Выполните: hex-ddd-analyzer init.
2. Отредактируйте созданный hex-ddd.config.json по необходимости.

Результат: Файл конфигурации готов к использованию.

Поиск и устранение неисправностей

Общие проблемы и решения

• Ошибка "Module not found": Убедитесь, что Node.js установлен корректно. Переустановите анализатор.
• Анализ не находит файлы: Проверьте glob-паттерны. Используйте hex-ddd-analyzer analyze "src/**/*.ts".
• Высокая сложность: Уменьшите порог в конфигурации или рефакторите код.
• Ложные срабатывания: Исключите файлы в разделе exclusions конфигурации.

Сообщения об ошибках

• DIP_VIOLATION: Нарушение принципа инверсии зависимостей. Решение: Используйте интерфейсы из доменного слоя.
• LAYER_DEPENDENCY: Неправильное направление зависимостей. Решение: Переместите код в соответствующий слой.

Контакты поддержки

Для технической поддержки обратитесь в репозиторий проекта на GitHub: [ссылка на issues].

Информация для удаления

Условия удаления

Удаление требуется при полном отказе от использования анализатора или миграции на другую систему.

Шаги удаления

1. Удалите глобальную установку: npm uninstall -g hex-ddd-analyzer.
2. Или удалите из зависимостей: npm uninstall hex-ddd-analyzer.
3. Удалите файлы конфигурации и отчеты вручную.

Очистка данных

• Удалите все сгенерированные отчеты и кэш.
• Нет пользовательских данных для миграции.

Приложения

Глоссарий

• DDD (Domain-Driven Design): Подход к разработке ПО, фокусирующийся на доменной модели.
• Гексагональная архитектура: Архитектурный паттерн с разделением на слои и порты/адаптеры.
• SOLID: Акроним принципов объектно-ориентированного дизайна.
• AST: Абстрактное синтаксическое дерево - структура представления кода.

Сокращения

• API: Application Programming Interface
• CI/CD: Continuous Integration/Continuous Deployment
• DIP: Dependency Inversion Principle
• SRP: Single Responsibility Principle

Указатель

• Анализ кода: см. Процедуры
• Конфигурация: см. Установка и конфигурация
• Отчеты: см. Процедуры
• Установка: см. Установка и конфигурация
• Удаление: см. Информация для удаления