ArchitectureTest.java

package com.stackrivet.app.architecture;

import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.domain.JavaMethod;
import com.tngtech.archunit.core.domain.JavaModifier;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.Set;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.methods;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noFields;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

/**
 * Architecture-boundary rules enforced via ArchUnit, run through the JUnit 5
 * Jupiter engine (not ArchUnit's own engine).
 * <p>
 * The earlier {@code @ArchTest} static-field style relied on
 * {@code archunit-junit5-engine}, which Surefire 3.5.3 does NOT auto-discover
 * alongside the Jupiter engine in this project's configuration — the result
 * was {@code Tests run: 0} for months, meaning every architecture rule
 * silently no-op'd. This rewrite uses plain {@code @Test} methods that
 * invoke {@code rule.check(classes)} directly, so the Jupiter engine
 * (which IS auto-discovered) reports real pass/fail counts.
 */
@DisplayName("Architecture boundaries · enforced via Jupiter")
class ArchitectureTest {

    private static JavaClasses CLASSES;

    @BeforeAll
    static void importClasses() {
        CLASSES = new ClassFileImporter()
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
                .importPackages("com.stackrivet");
    }

    @Test
    @DisplayName("module dependency graph is acyclic (no upward/cyclic deps)")
    void modules_are_acyclic() {
        // Closes the deep-review gap: cleanliness of the module graph previously rested on
        // POM hygiene + discipline alone, with no build-time guard. Slice = the first package
        // segment under com.stackrivet (security/system/audit/asset/...); none may form a cycle.
        ArchRule rule = slices().matching("com.stackrivet.(*)..")
                .should().beFreeOfCycles()
                .as("StackRivet modules must form an acyclic dependency graph")
                .because("a cycle between modules breaks the modular-monolith layering and independent buildability");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("a module's mapper package is only used within that module")
    void mappers_not_accessed_cross_module() {
        // governance §4.7: no business module may reach into another module's persistence
        // (..mapper..) package. Same-module service->mapper is allowed; cross-module is not.
        for (String module : Set.of("system", "asset", "generator", "audit", "task", "demo")) {
            ArchRule rule = noClasses()
                    .that().resideOutsideOfPackage("com.stackrivet." + module + "..")
                    .should().dependOnClassesThat().resideInAPackage("com.stackrivet." + module + "..mapper..")
                    .as(module + " mapper package must not be accessed from another module")
                    .because("cross-module persistence access bypasses the owning module's Service/transaction boundary")
                    .allowEmptyShould(true);
            rule.check(CLASSES);
        }
    }

    @Test
    @DisplayName("common must not depend on any business module")
    void common_is_leaf() {
        ArchRule rule = noClasses().that().resideInAPackage("com.stackrivet.common..")
                .should().dependOnClassesThat().resideInAnyPackage(
                        "com.stackrivet.security..",
                        "com.stackrivet.system..",
                        "com.stackrivet.audit..",
                        "com.stackrivet.asset..",
                        "com.stackrivet.generator..",
                        "com.stackrivet.importexport..",
                        "com.stackrivet.task..",
                        "com.stackrivet.observability..",
                        "com.stackrivet.plugin..",
                        "com.stackrivet.cli..",
                        "com.stackrivet.demo..",
                        "com.stackrivet.app.."
                )
                .as("stackrivet-common must not depend on any business module")
                .because("common is the leaf of the dependency graph; otherwise we have a cycle");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("data-scope decision core stays framework-free (no jsqlparser/mybatis/servlet)")
    void datascope_core_is_framework_free() {
        ArchRule rule = noClasses().that().resideInAPackage("com.stackrivet.common.datascope..")
                .should().dependOnClassesThat().resideInAnyPackage(
                        "net.sf.jsqlparser..",
                        "com.baomidou..",
                        "jakarta.servlet..",
                        "org.springframework.web..")
                .as("the data-scope decision core must be pure (ADR-0005)")
                .because("the scope->predicate Policy must be unit-testable without a DB or jsqlparser; "
                        + "jsqlparser translation lives in stackrivet-system");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("controllers must not call mappers directly")
    void controllers_skip_mapper() {
        ArchRule rule = noClasses().that().resideInAPackage("..controller..")
                .should().dependOnClassesThat().resideInAnyPackage("..mapper..", "..infrastructure.mapper..")
                .as("Controllers must not depend on Mappers directly")
                .because("Controllers go through Service; Mapper access from Controller bypasses transaction and audit boundaries");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("entities must not leak to controllers")
    void entities_stay_behind_services() {
        ArchRule rule = noClasses().that().resideInAPackage("..controller..")
                .should().dependOnClassesThat().haveSimpleNameEndingWith("Entity")
                .as("Controllers must not return Entity types")
                .because("Controllers expose DTO/VO; Entity leaking causes lazy-load and over-exposure issues");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("no field injection — only constructor injection allowed")
    void no_field_injection() {
        // Must target FIELDS, not classes: @Autowired has no @Target(TYPE), so
        // noClasses().beAnnotatedWith(@Autowired) can never match and silently always
        // passes. noFields() inspects the actual injection points — @Autowired on a
        // constructor (the project's convention) is a JavaConstructor, not a field, so
        // it is correctly allowed; only @Autowired fields trip this rule.
        ArchRule rule = noFields().should()
                .beAnnotatedWith("org.springframework.beans.factory.annotation.Autowired")
                .as("Field injection is discouraged; prefer constructor injection")
                .allowEmptyShould(true);
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("demo must not be depended on by core modules")
    void demo_isolation() {
        ArchRule rule = classes().that().resideInAPackage("com.stackrivet.demo..")
                .should().onlyHaveDependentClassesThat()
                .resideInAnyPackage("com.stackrivet.demo..", "com.stackrivet.app..")
                .as("stackrivet-demo must never be referenced by core modules")
                .because("Demo modules show patterns; they must not become a dependency of core")
                .allowEmptyShould(true);
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("audit module must not depend on any business module (leaf-only)")
    void audit_is_leaf() {
        ArchRule rule = noClasses().that().resideInAPackage("com.stackrivet.audit..")
                .should().dependOnClassesThat().resideInAnyPackage(
                        "com.stackrivet.system..",
                        "com.stackrivet.asset..",
                        "com.stackrivet.generator..",
                        "com.stackrivet.importexport..",
                        "com.stackrivet.task..",
                        "com.stackrivet.demo.."
                )
                .as("stackrivet-audit must not import business modules")
                .because("Audit decouples via SPI + Spring events + AOP package patterns; importing a business module breaks that design (add-audit-logs spec scenario)");
        rule.check(CLASSES);
    }

    @Test
    @DisplayName("security must not contain raw JDBC access to system tables")
    void security_uses_system_user_directory_spi() {
        ArchRule rule = noClasses().that().resideInAPackage("com.stackrivet.security..")
                .should().dependOnClassesThat().resideInAPackage("org.springframework.jdbc..")
                .as("stackrivet-security must consume SystemUserDirectory instead of raw JDBC")
                .because("security owns auth policy, while stackrivet-system owns sr_sys_* schema and SQL");
        rule.check(CLASSES);
    }

    /**
     * Closes deep-review §3.8 (P1) — until this rule shipped, every protected
     * endpoint had {@code @PreAuthorize} only because the team was disciplined.
     * A hurried PR could merge a new {@code @GetMapping} with no permission
     * gate and slip past code review. ArchUnit now blocks that at build time.
     *
     * <p>The rule is intentionally simple: <b>every public method annotated
     * with one of the six HTTP mapping annotations must also be annotated
     * with {@code @PreAuthorize}</b>, OR sit inside a controller listed below
     * as an explicitly-public surface. Today the only public controller is
     * {@code AuthController}; if a future public endpoint is added it must
     * be appended here as a conscious architectural decision.
     */
    @Test
    @DisplayName("every protected REST method must declare @PreAuthorize")
    void protected_endpoints_have_preauthorize() {
        // Controllers whose endpoints intentionally appear in
        // DefaultSecurityConfig.PUBLIC_PATHS and so do not declare per-method
        // authorities. Adding a class here is an architectural decision that
        // must be paired with a corresponding PUBLIC_PATHS allowlist entry.
        Set<String> publicControllerSimpleNames = Set.of(
                "AuthController"
        );

        Set<String> httpMappingAnnotations = Set.of(
                "org.springframework.web.bind.annotation.GetMapping",
                "org.springframework.web.bind.annotation.PostMapping",
                "org.springframework.web.bind.annotation.PutMapping",
                "org.springframework.web.bind.annotation.DeleteMapping",
                "org.springframework.web.bind.annotation.PatchMapping",
                "org.springframework.web.bind.annotation.RequestMapping"
        );

        DescribedPredicate<JavaMethod> isHttpEndpointInProtectedController =
                new DescribedPredicate<>("are HTTP endpoints in a protected controller") {
                    @Override
                    public boolean test(JavaMethod method) {
                        if (!method.getModifiers().contains(JavaModifier.PUBLIC)) return false;
                        JavaClass owner = method.getOwner();
                        if (publicControllerSimpleNames.contains(owner.getSimpleName())) return false;
                        boolean ownerIsRestController = owner.isAnnotatedWith(
                                "org.springframework.web.bind.annotation.RestController");
                        if (!ownerIsRestController) return false;
                        return method.getAnnotations().stream()
                                .anyMatch(a -> httpMappingAnnotations.contains(a.getRawType().getName()));
                    }
                };

        ArchRule rule = methods()
                .that(isHttpEndpointInProtectedController)
                .should().beAnnotatedWith("org.springframework.security.access.prepost.PreAuthorize")
                .as("Every HTTP-mapped method on a non-public @RestController must declare @PreAuthorize")
                .because("default-deny: missing @PreAuthorize on a protected endpoint leaks behind permission checks");
        rule.check(CLASSES);
    }
}