Documentation

Plugin Audit
Contraintes, métriques et formats de rapport.

Référence complète du plugin d'audit HexaGlue : options de configuration, contraintes vérifiées, métriques calculées et formats de rapport.

Installation

Ajouter le plugin d'audit

<plugin>
    <groupId>io.hexaglue</groupId>
    <artifactId>hexaglue-maven-plugin</artifactId>
    <version>6.1.1</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>com.acme.shop</basePackage>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-audit</artifactId>
            <version>3.1.1</version>
        </dependency>
    </dependencies>
</plugin>

L'audit s'exécute automatiquement lors de la phase verify (mvn verify). Le rapport est généré dans target/hexaglue/reports/audit/.

Trois éléments clés dans cette configuration :

<extensions>true</extensions> : active le binding automatique aux phases Maven. Les goals HexaGlue se déclenchent sans configuration supplémentaire lors de mvn compile ou mvn verify.
<basePackage> : package racine à analyser. Seules les classes de ce package et de ses sous-packages sont classifiées par HexaGlue.
Le plugin d'audit est déclaré comme <dependency> du plugin Maven, pas du projet. HexaGlue découvre automatiquement les plugins via le mécanisme Java ServiceLoader : il suffit de les ajouter ici pour qu'ils soient actifs.

Les projets utilisant Lombok sont pris en charge nativement depuis HexaGlue 6.0.0 : le delombok est injecté automatiquement avant l'analyse, aucune configuration spéciale n'est nécessaire côté plugin.

Rapport d'audit HexaGlue : vue d'ensemble du rapport HTML généré pour sample-basic avec verdict 76/100, grade C, inventaire architectural et métriques — Vue d'ensemble d'un rapport d'audit HexaGlue (sample-basic, score 76/C)

Configuration

Options Maven

La configuration de l'audit se fait via les paramètres <configuration> du plugin Maven dans le pom.xml.
Ces paramètres contrôlent le comportement du build (échec sur violations) et l'emplacement des rapports générés.
Le paramètre skip peut aussi être passé en ligne de commande via -Dhexaglue.skip=true.

Option	Type	Défaut	Description
`basePackage`	string	(requis)	Package racine à analyser pour les violations DDD et hexagonales
`errorOnBlocker`	boolean	`true`	Les violations BLOCKER comptent comme erreurs d'audit
`errorOnCritical`	boolean	`false`	Les violations CRITICAL comptent comme erreurs d'audit
`failOnError`	boolean	`true`	Fait échouer le build Maven quand des erreurs d'audit existent
`failOnUnclassified`	boolean	`false`	Fait échouer le build si des types restent non classifiés après l'analyse
`reportDirectory`	string	`${project.build.directory}/hexaglue/reports`	Répertoire de sortie pour les rapports d'audit
`skip`	boolean	`false`	Désactive complètement l'audit (configurable via `-Dhexaglue.skip=true`)
`tolerantResolution`	boolean	`false`	Active la résolution tolérante des types non résolus. Utile pour les projets utilisant des annotation processors (MapStruct, Immutables) dont le code généré n'est pas encore sur le classpath (configurable via `-Dhexaglue.tolerantResolution=true`)
`validationReportPath`	string	`${project.build.directory}/hexaglue/reports/validation/validation-report.md`	Chemin du rapport de validation Markdown (goal `validate` uniquement)

<plugin>
    <groupId>io.hexaglue</groupId>
    <artifactId>hexaglue-maven-plugin</artifactId>
    <version>6.1.1</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>com.acme.shop</basePackage>
        <failOnError>true</failOnError>
        <errorOnBlocker>true</errorOnBlocker>
        <errorOnCritical>false</errorOnCritical>
        <reportDirectory>${project.build.directory}/hexaglue/reports</reportDirectory>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-audit</artifactId>
            <version>3.1.1</version>
        </dependency>
    </dependencies>
</plugin>

mvn clean verify -Dhexaglue.skip=true

Configuration

Options YAML

Le fichier hexaglue.yaml, placé à la racine du projet (à côté du pom.xml), centralise la configuration de HexaGlue et de tous ses plugins.
Les options ci-dessous se configurent dans la section plugins.io.hexaglue.plugin.audit: du fichier YAML.
Les 3 propriétés de failure (failOnError, errorOnBlocker, errorOnCritical) sont unifiées entre Maven et YAML. Précédence : Maven POM / -D > YAML > defaults.

Option	Type	Défaut	Description
`failOnError`	boolean	`true`	Fait échouer le build Maven quand des erreurs d'audit existent
`errorOnBlocker`	boolean	`true`	Les violations BLOCKER comptent comme erreurs d'audit
`errorOnCritical`	boolean	`false`	Les violations CRITICAL comptent comme erreurs d'audit
`generateDocs`	boolean	`false`	Active la génération des diagrammes Mermaid dans un répertoire séparé

plugins:
  io.hexaglue.plugin.audit:
    errorOnBlocker: true         # Défaut
    errorOnCritical: false       # Défaut
    generateDocs: false          # Défaut

Contraintes

Contraintes DDD

Ces contraintes vérifient la conformité de votre modèle de domaine aux principes DDD.

ID	Nom	Sévérité	Description
`ddd:entity-identity`	Identité des entités	CRITICAL	Les entités doivent avoir un champ d'identité stable qui les distingue des autres instances.
`ddd:value-object-immutable`	Immuabilité des VO	CRITICAL	Les value objects doivent être immuables pour garantir la thread-safety et la sémantique de valeur.
`ddd:aggregate-cycle`	Cycles entre agrégats	BLOCKER	Les agrégats doivent être des unités indépendantes. Les dépendances circulaires indiquent un mauvais découpage.
`ddd:aggregate-repository`	Repository par agrégat	MAJOR	Chaque agrégat doit avoir une interface repository dédiée pour les opérations de persistance.
`ddd:aggregate-boundary`	Frontières d'agrégat	MAJOR	Les entités d'un agrégat ne doivent être accessibles que via la racine, jamais directement de l'extérieur.
`ddd:aggregate-consistency`	Cohérence d'agrégat	MAJOR	Frontières claires : chaque entité appartient à un seul agrégat, maximum 7 entités par agrégat.
`ddd:domain-purity`	Pureté du domaine	MAJOR	Les types du domaine ne doivent pas dépendre de frameworks, bases de données ou détails d'infrastructure.
`ddd:event-naming`	Nommage des événements	MINOR	Les événements de domaine doivent utiliser le passé (ex: `OrderPlaced`, `UserCreated`).

Contraintes

Contraintes d'architecture hexagonale

Ces contraintes vérifient l'isolation des couches et le respect des patterns hexagonaux.

ID	Nom	Sévérité	Description
`hexagonal:dependency-direction`	Direction des dépendances	BLOCKER	Les dépendances doivent pointer vers le domaine. Le domaine reste indépendant et testable.
`hexagonal:port-interface`	Ports = interfaces	CRITICAL	Les ports définissent des frontières et doivent être des interfaces pour respecter l'inversion de dépendance.
`hexagonal:dependency-inversion`	Inversion de dépendance	CRITICAL	L'application doit dépendre d'abstractions (interfaces) et non de classes concrètes d'infrastructure.
`hexagonal:layer-isolation`	Isolation des couches	MAJOR	Le domaine ne dépend de rien, l'application dépend uniquement du domaine, l'infrastructure peut dépendre des deux.
`hexagonal:port-direction`	Direction des ports	MAJOR	Les ports DRIVING (entrants) sont implémentés par les services applicatifs. Les ports DRIVEN (sortants) sont implémentés par les adapters.
`hexagonal:port-coverage`	Couverture des ports	MAJOR	Tous les ports doivent avoir au moins un adapter qui les implémente.
`hexagonal:application-purity`	Pureté applicative	MAJOR	Les services applicatifs ne doivent pas importer d'annotations de framework (`@Service`, `@Transactional`).

Sévérités

Niveaux de sévérité

Chaque contrainte a un niveau de sévérité qui détermine son impact sur le build Maven.
Les deux niveaux les plus élevés (BLOCKER et CRITICAL) peuvent faire échouer la compilation, ce qui garantit que les violations graves sont corrigées avant le déploiement.

Niveau	Impact sur le build	Usage
BLOCKER	Build échoue immédiatement, non contournable	Violations architecturales fondamentales (cycles, direction des dépendances)
CRITICAL	Build échoue si `errorOnCritical: true`	Violations DDD sérieuses (VO mutables, entités sans identité)
MAJOR	Avertissement, le build continue	Problèmes architecturaux significatifs (agrégat sans repository)
MINOR	Information, faible priorité	Bonnes pratiques (nommage des événements, taille des agrégats)

Métriques

Métriques calculées

L'audit calcule 20 métriques de qualité architecturale regroupées en 5 familles. Chaque métrique a un seuil d'alerte configurable.

Métrique	Unité	Seuil d'alerte	Ce qu'elle mesure
DDD et Domaine
`domain.coverage`	%	< 30%	Proportion des types classifiés dans la couche domaine
`domain.purity`	%	< 100%	Proportion des types du domaine sans dépendance d'infrastructure
`ddd.value.object.ratio`	%	< 40%	Ratio de value objects par rapport aux types du domaine (entités + VO)
`ddd.event.coverage`	%	< 50%	Proportion des agrégats émettant au moins un événement de domaine
`ddd.aggregate.coupling`	deps/agrégat	> 3	Nombre moyen de dépendances inter-agrégats
Agrégats
`aggregate.avgSize`	méthodes	> 20	Nombre moyen de méthodes par aggregate root
`aggregate.boundary`	%	< 80%	Proportion des entités encapsulées dans leur agrégat
`aggregate.repository.coverage`	%	< 100%	Proportion des agrégats ayant un port repository
`aggregate.coupling.efferent`	ratio	> 0.7	Instabilité moyenne des packages (couplage efférent)
Architecture hexagonale
`hexagonal.adapter.independence`	%	< 80%	Indépendance des adapters entre eux (REST ne dépend pas de JPA)
Qualité du code
`code.boilerplate.ratio`	%	> 50%	Proportion de code boilerplate (getters, setters, equals) dans le domaine
`code.complexity.average`	complexité	> 10	Complexité cyclomatique moyenne des méthodes du domaine
Modularité et structure
`architecture.propagation.cost`	%	> 35%	Coût de propagation : impact moyen d'un changement sur le système
`architecture.cyclicity.relative`	%	> 5%	Proportion de types impliqués dans des cycles de dépendances
`architecture.dependency.depth`	niveaux	> 7	Profondeur maximale de la chaîne de dépendances
`architecture.fan.out.max`	dépendances	> 20	Dépendances sortantes du type le plus couplé
`architecture.modularity.q`	Q	< 0.3	Modularité de Newman-Girvan (> 0.3 = bonne structure communautaire)
`architecture.mmi`	score	< 50	Index de maturité modulaire de Lilienthal (0-100)
`architecture.visibility.average`	%	> 70%	Visibilité relative moyenne : ratio de types publics par package
`architecture.cohesion.relational`	ratio	hors 1.5 – 4.0	Cohésion relationnelle H : dépendances internes par package

La métrique domain.purity détecte les imports d'infrastructure dans le domaine : JPA (javax.persistence, jakarta.persistence), Spring (org.springframework), Hibernate, Jackson, JDBC, SDKs cloud (AWS, Azure, GCP), messaging (Kafka, RabbitMQ), et les frameworks web/validation.

Rapport d'audit HexaGlue : tableau KPI montrant les 5 dimensions (DDD, hexagonal, dépendances, couplage, cohésion) avec poids, scores et seuils colorés — KPI Table : les 5 dimensions du score avec statuts On Target / At Risk / Below Target

Rapports

Formats de sortie

L'audit produit un rapport dans 3 formats de fichier, générés par défaut à chaque exécution.
La sortie console (avec couleurs ANSI) est toujours active en complément. Les fichiers sont générés dans target/hexaglue/reports/audit/.

Format	Fichier	Usage
JSON	`target/hexaglue/reports/audit/audit-report.json`	Consommation programmatique, intégration avec des outils CI/CD
HTML	`target/hexaglue/reports/audit/audit-report.html`	Consultation web, rapport partageable avec CSS intégré
Markdown	`target/hexaglue/reports/audit/AUDIT-REPORT.md`	Versionnage Git, intégration GitHub, documentation
Console	(sortie standard)	Affichage terminal avec couleurs ANSI (toujours actif)

15 contraintes, 20 métriques, un rapport.
Configurez l'audit en quelques lignes.

Voyez les résultats de l'audit sur un projet réel ou explorez les contraintes et métriques disponibles.

Interpréter un rapport d'audit Se faire accompagner

Plugin AuditContraintes, métriques et formats de rapport.