Taikai¶

1. Introduction¶

Taikai is an automated architecture testing tool for Java projects. It builds on ArchUnit and adds a large set of ready-made, fluently configurable architectural rules, so that enforcing conventions does not require writing ArchUnit predicates and conditions by hand.

A Taikai check is an ordinary unit test. It imports your compiled classes, evaluates every configured rule against them, and fails the build when a rule is violated.

class ArchitectureTest {

  @Test
  void architecture() {
    Taikai.builder()
        .namespace("com.company.project")
        .java(java -> java
            .noUsageOfDeprecatedAPIs()
            .fieldsShouldNotBePublic())
        .build()
        .checkAll();
  }
}

2. Requirements¶

ArchUnit is a regular (compile-scope) dependency of Taikai, so it arrives transitively and you do not need to declare it yourself. Taikai only relies on the stable ArchUnit core API, so a newer patch or minor ArchUnit release normally works unchanged. If you pin a different ArchUnit version in your own build, verify it after upgrading Taikai.

3. Installation¶

Taikai belongs on the test classpath only.

3.1 Maven¶

<dependency>
  <groupId>com.enofex</groupId>
  <artifactId>taikai</artifactId>
  <version>${taikai.version}</version>
  <scope>test</scope>
</dependency>

3.2 Gradle¶

testImplementation "com.enofex:taikai:${taikaiVersion}"

ArchUnit comes along transitively; no separate declaration is required.

4. Quick Start¶

The example below is a complete, runnable test. Every other code sample in this document is a fragment that plugs into this same skeleton (see Section 6).

import static com.tngtech.archunit.core.domain.JavaModifier.FINAL;
import static com.tngtech.archunit.core.domain.JavaModifier.PRIVATE;

import com.enofex.taikai.Taikai;
import com.enofex.taikai.java.ImportPatterns;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.slf4j.Logger;

class ArchitectureTest {

  @Test
  void architecture() {
    Taikai.builder()
        .namespace("com.company.project")
        .failOnEmpty(true)
        .java(java -> java
            .noUsageOfDeprecatedAPIs()
            .noUsageOfSystemOutOrErr()
            .fieldsShouldNotBePublic()
            .methodsShouldNotDeclareGenericExceptions()
            .utilityClassesShouldBeFinalAndHavePrivateConstructor()
            .imports(imports -> imports
                .shouldHaveNoCycles()
                .shouldNotImport(ImportPatterns.shaded()))
            .naming(naming -> naming
                .packagesShouldMatchDefault()
                .classesShouldNotMatch(".*Impl")
                .constantsShouldFollowConventions()
                .interfacesShouldNotHavePrefixI()))
        .logging(logging -> logging
            .loggersShouldFollowConventions(Logger.class, "logger", List.of(PRIVATE, FINAL)))
        .test(test -> test
            .junit(junit -> junit
                .classesShouldEndWithTest()
                .methodsShouldBePackagePrivate()
                .methodsShouldContainAssertionsOrVerifications()))
        .build()
        .checkAll();
  }
}

5. Core Concepts¶

5.1 Selecting Classes with a Namespace¶

namespace is the base package Taikai imports and analyzes.

Taikai.builder()
    .namespace("com.company.project")
    .build()
    .check();

If the namespace contains no classes to check, for example because it is misspelled, the rules check nothing and pass. Taikai does not fail in that case, but logs a warning through System.Logger before the rules run:

WARNING: Namespace com.compnay.project contains no production classes, so the rules for them check nothing. Is the namespace correct?

5.2 Selecting Classes Directly¶

Instead of a namespace you can hand Taikai an explicit set of JavaClasses, or a list of class literals.

JavaClasses classes = new ClassFileImporter()
    .importClasses(ClassToCheck.class);

Taikai.builder()
    .classes(classes)
    .build()
    .check();

Taikai.builder()
    .classes(ClassToCheck.class, AnotherClassToCheck.class)
    .build()
    .check();

5.3 Namespace Import Modes¶

Namespace.IMPORT controls whether test classes take part in a check.

Each rule group has a default mode, so in practice you rarely set this yourself:

Override it per rule through Configuration:

.java(java -> java
    .fieldsShouldNotBePublic(Configuration.of(Namespace.IMPORT.WITH_TESTS)))

5.4 Excluding Classes Globally¶

excludeClasses(...) removes classes from every rule. It accepts class literals or string patterns.

Supported string patterns:

• Fully qualified class name — com.company.project.foo.ClassToExclude
• Package wildcard (*) — classes directly in that package: com.company.project.foo.*
• Recursive package wildcard (..) — the package and all subpackages: com.company.project.internal..

Taikai.builder()
    .namespace("com.company.project")
    .excludeClasses(
        "com.company.project.foo.ClassToExclude",
        "com.company.project.bar.*",
        "com.company.project.internal..")
    .excludeClasses(GeneratedMapper.class, LegacyFacade.class)
    .build()
    .check();

excludeClasses(...) also accepts criteria, which can exclude classes by annotation or any other property instead of by name. A class matching any of the registered criteria is excluded. This is the typical way to skip generated code everywhere:

Taikai.builder()
    .namespace("com.company.project")
    .excludeClasses(ClassCriteria.inPackage("com.company.project.generated.."))
    .excludeClasses(ClassCriteria.annotatedWith(Legacy.class))
    .build()
    .check();

An exclusion that matches no class has no effect, typically because the class was renamed or deleted. Taikai logs a warning for such an exclusion, whether it is global or belongs to a single rule, so stale exclusions can be removed:

WARNING: Exclusion 'com.company.project.foo.ClassToExclude' matches no class, so it can be removed

To exclude classes from a single rule only, use Configuration instead.

5.5 Failing on Empty Rule Results¶

By default an ArchUnit rule that matches no classes passes silently. That hides typos in regexes and rules that quietly stopped applying after a refactoring. failOnEmpty(true) turns those into failures.

Taikai.builder()
    .namespace("com.company.project")
    .failOnEmpty(true)
    .build()
    .check();

The default is false. Turning it on is recommended for any long-lived configuration.

5.6 Running the Checks¶

All three methods evaluate every configured rule and custom check; they differ in how they report.

Taikai.builder()
    .namespace("com.company.project")
    .build()
    .check();      // fail fast

Taikai.builder()
    .namespace("com.company.project")
    .build()
    .checkAll();   // full report

Prefer checkAll() when introducing Taikai to an existing codebase, so you see the whole backlog in one run. check() gives a shorter, more focused failure once the codebase is clean.

dynamicTests() turns every rule into its own JUnit Jupiter test, named after the rule's description. The IDE and the test reports then show which rules pass and which fail, and a single rule can be rerun from the IDE. Return the stream from a @TestFactory method:

@DisplayName("Check architecture constraints")
@TestFactory
Stream<DynamicTest> architecture() {
  return Taikai.builder()
      .namespace("com.company.project")
      .java(java -> java
          .noUsageOfSystemOutOrErr()
          .fieldsShouldNotBePublic())
      .build()
      .dynamicTests();
}

Check architecture constraints
├─ ✔ Classes should not use System.out or System.err
└─ ✘ Fields should not be public unless they are static

5.7 Reading the Failure Report¶

check() propagates ArchUnit's own AssertionError for the first failing rule.

checkAll() produces an aggregated report with a violation count, a rule count, and the individual violations grouped per rule. Violated custom checks are counted separately, as in Found 3 Taikai violations for 1 rules and 1 checks!, and listed with Check: instead of Rule::

java.lang.AssertionError: Found 2 Taikai violations for 2 rules!

Rule: Classes should not use System.out or System.err
    Method com.company.project.OrderService.process() calls java.lang.System.out

Rule: Fields should not be public unless they are static
    Field total in class com.company.project.Order is public

The rule line is the rule's own description, which is also what you grep for when you want to find the configuration that produced a violation.

Detail lines that come from stock ArchUnit conditions end with the source file and line number, so they are one click away in an IDE:

Rule: Classes should not have names matching .*Service
    Class <com.company.project.OrderService> has name matching '.*Service' in (OrderService.java:0)

Rules built on Taikai's own conditions — among them noUsageOfSystemOutOrErr, fieldsShouldNotBePublic, classesShouldImplementHashCodeAndEquals and the logger rules — name the offending element without a location, as in the report above.

5.8 Per-Rule Configuration¶

Every rule method has an overload taking a TaikaiRule.Configuration. It overrides the global settings for that one rule: a different namespace, a different import mode, an explicit class set, or additional excluded classes.

Collection<T> accepts either String patterns or Class<?> literals, but not both in the same collection — the type is decided from the first element. The Namespace.IMPORT plus exclusions overload is the one exception: it takes Collection<String> only, so pass class names there rather than class literals.

// ONLY_TESTS - checks every test method
.test(test -> test
    .junit(junit -> junit
        .methodsShouldMatch("should.*")))

// WITHOUT_TESTS - silently checks nothing
.test(test -> test
    .junit(junit -> junit
        .methodsShouldMatch("should.*", Configuration.of(List.of("com.company.project.Legacy")))))

// ONLY_TESTS restored explicitly
.test(test -> test
    .junit(junit -> junit
        .methodsShouldMatch("should.*",
            Configuration.of(Namespace.IMPORT.ONLY_TESTS, List.of("com.company.project.Legacy")))))

.java(java -> java
    .imports(imports -> imports
        .shouldNotImport(ClassCriteria.inPackage("com.company.project.legacy.."),
            Configuration.of("com.company.project.different", Namespace.IMPORT.WITHOUT_TESTS))
        .shouldNotImport(lombok(),
            Configuration.of(Namespace.IMPORT.ONLY_TESTS))))

.spring(spring -> spring
    .noSelfInvocationOfProxiedMethods(
        Configuration.of(List.of(OrderService.class))))

5.9 Disabling a Rule Group¶

Every configurer implements disable(), which clears all rules registered on that configurer. This is mainly useful when a shared profile enables a group that a particular module must not run.

Taikai.builder()
    .namespace("com.company.project")
    .java(DEFAULT_JAVA_PROFILE)
    .spring(spring -> spring
        .controllers(controllers -> controllers
            .disable()))         // drop every controller rule the profile added
    .build()
    .checkAll();

Every rule group has disable(): java, imports, naming, logging, test, junit, spring, boot, properties, configurations, controllers, services, repositories, transactional, quarkus, resources, panache, ai, jpa, entities and metrics.

disable() cascades to nested configurers: java(...) also clears naming and imports, spring(...) clears all its sub-configurers, quarkus(...) clears resources, panache and ai, jpa(...) clears entities, and test(...) clears junit.

5.10 Modifying an Existing Configuration¶

toBuilder() returns a builder pre-populated from an existing Taikai instance, so a shared base configuration can be adapted per module.

Taikai base = Taikai.builder()
    .namespace("com.company.project")
    .excludeClasses("com.company.project.SomeClassToExclude")
    .failOnEmpty(true)
    .java(java -> java
        .fieldsShouldNotBePublic())
    .build();

Taikai adapted = base.toBuilder()
    .namespace("com.company.newproject")
    .excludeClasses("com.company.project.AnotherClassToExclude")
    .java(java -> java
        .classesShouldImplementHashCodeAndEquals()
        .finalClassesShouldNotHaveProtectedMembers())
    .build();

adapted.check();

toBuilder() copies the rules of the instance. They stay in the new configuration even if you call disable() on the new builder, which only removes the rules added through that builder. To drop a rule group per module, share a profile instead of a built instance.

5.11 Reusable Rule Profiles¶

A profile is a Customizer<T>, where T is a configurer type such as JavaConfigurer or TestConfigurer. It packages a set of rules that can be applied to many modules or repositories, and it can be combined with project-specific rules.

private static final Customizer<JavaConfigurer> DEFAULT_JAVA_PROFILE = java -> java
    .noUsageOf(Date.class)
    .fieldsShouldNotBePublic();

private static final Customizer<TestConfigurer> DEFAULT_TEST_PROFILE = test -> test
    .junit(junit -> junit
        .methodsShouldBePackagePrivate()
        .methodsShouldMatch("should.*")
        .methodsShouldContainAssertionsOrVerifications()
        .classesShouldBePackagePrivate(ClassCriteria.nameMatching(".*Test"))
        .classesShouldNotBeAnnotatedWithDisabled());

Taikai.builder()
    .namespace("com.company.project")
    .java(java -> {
      DEFAULT_JAVA_PROFILE.customize(java);                         // apply the profile
      java.classesShouldBeRecords(ClassCriteria.nameMatching(".*Dto"));  // plus a local rule
    })
    .test(DEFAULT_TEST_PROFILE)                                     // use the profile directly
    .build()
    .checkAll();

5.12 Adding Custom ArchUnit Rules¶

Anything Taikai does not cover can be expressed as a plain ArchUnit rule and registered with addRule or addRules. Custom rules participate in check() and checkAll() like built-in ones, and accept the same Configuration.

ArchRule rule = classes()
    .that().resideInAPackage("..domain..")
    .should().onlyBeAccessed().byAnyPackage("..domain..", "..application..");

Taikai.builder()
    .namespace("com.company.project")
    .addRule(TaikaiRule.of(rule))
    .addRule(TaikaiRule.of(rule, Configuration.of(Namespace.IMPORT.WITH_TESTS)))
    .addRules(List.of(TaikaiRule.of(rule), TaikaiRule.of(anotherRule)))
    .build()
    .checkAll();

5.13 Selecting with Criteria¶

Rules that apply to a selection of classes, fields or methods take an ArchUnit DescribedPredicate, so the selection can be expressed precisely and combined freely. The parameter type tells you which factory builds it:

Passing criteria of the wrong kind does not compile, so a FieldCriteria can never end up in a rule that selects methods.

Class criteria¶

ClassCriteria selects the classes a rule applies to. Rules that restrict sets of types, such as noUsageOf, shouldNotImport, methodsShouldNotReturnForClass or fieldsShouldNotBeOfType, take class criteria for those types too, and FieldCriteria.ofType(...) selects fields by class criteria on their type.

Combine criteria with .and(...) and .or(...), and negate them with DescribedPredicate.not(...). Any other ArchUnit class predicate works as well, for example JavaClass.Predicates.assignableTo(Repository.class).

.java(java -> java
    .classesShouldBeRecords(ClassCriteria.nameMatching(".*Dto")
        .and(ClassCriteria.inPackage("..api..")))
    .classesShouldBePackagePrivate(ClassCriteria.annotatedWith("jakarta.persistence.Entity")
        .or(ClassCriteria.inPackage("..internal..")))
    .noUsageOf(ClassCriteria.inPackage("..domain.."),
        ClassCriteria.inPackage("com.company.legacy..")))

The description of the criteria becomes part of the rule name shown in failure reports.

Class criteria can also exclude classes from every rule with excludeClasses(criteria), which also covers the rules that take no parameters, such as noUsageOfSystemOutOrErr() or fieldsShouldNotBePublic().

Field and method criteria¶

Rules that select fields or methods, such as fieldsShouldHaveModifiers or methodsShouldBeAnnotatedWith, take field or method criteria:

Every annotatedWith, type, assignableTo, implementing and ofType(Class) criterion also has an overload taking the fully qualified name as a String. Field and method criteria combine like class criteria, and with ArchUnit member predicates such as HasModifiers.Predicates.modifier(PUBLIC). This allows selections that no single rule variant offers:

.java(java -> java
    .fieldsShouldHaveModifiers(FieldCriteria.ofType(Logger.class), List.of(PRIVATE, STATIC, FINAL))
    .methodsShouldHaveModifiers(MethodCriteria.annotatedWith(GetMapping.class)
        .and(MethodCriteria.nameMatching("find.*")), List.of(PUBLIC)))

To select fields or methods by their declaring class, use the …ForClass variants, such as methodsShouldBeAnnotatedWithForClass or fieldsShouldHaveModifiersForClass, which take class criteria.

5.14 Custom Checks¶

Not every architecture or setup convention is visible in the compiled classes. A TaikaiCheck checks anything else a test run can see, such as files in the project directory, resources, or the classpath. Checks are shipped in a library, for example with the conventions of a whole company, and discovered with the Java ServiceLoader. They run after the rules and are part of check(), checkAll() and dynamicTests(), where each check becomes a test of its own.

public final class LicenseCheck implements TaikaiCheck {

  @Override
  public String description() {
    return "Project should have a LICENSE";
  }

  @Override
  public List<String> violations(CheckContext context) {
    return Files.exists(context.projectDirectory().resolve("LICENSE"))
        ? List.of()
        : List.of("LICENSE is missing in " + context.projectDirectory());
  }
}

TaikaiCheck and CheckContext are in the package com.enofex.taikai.checks.spi. A check returns one message per violation, or an empty list if it passes. Violations are reported like those of a rule, but labeled and counted as checks:

java.lang.AssertionError: Found 1 Taikai violations for 1 checks!

Check: Project should have a LICENSE
    LICENSE is missing in /home/dev/project

The CheckContext describes the project that is checked:

Registering and discovering checks¶

The library lists the fully qualified class names of its checks in the file META-INF/services/com.enofex.taikai.checks.spi.TaikaiCheck, one per line:

com.company.checks.LicenseCheck
com.company.checks.CodeownersCheck

A project that has the library on its test classpath runs these checks with discoverChecks():

Taikai.builder()
    .namespace("com.company.project")
    .discoverChecks()
    .build()
    .checkAll();

Discovery is opt-in, so adding a library never changes what a test checks on its own. The rules for discovered checks are:

• A check must be a public class with a public constructor without parameters.
• Checks are discovered when build() is called, and run sorted by their description, so that the order is the same in Maven, Gradle and the IDE.
• A check that throws an exception, fails an assertion or misses a class does not escape as an error of its own. The failure is reported as a violation of that check, like any other: checkAll() and dynamicTests() still run the other rules and checks, while check() stops there, as it does at every violation.

Predefined checks¶

Taikai ships ready-made checks for common project conventions, such as required or forbidden files, the Maven or Gradle Wrapper, or the Java version of the classes. They are documented in Section 14.

Configuring the checks¶

discoverChecks also takes a customizer for a ChecksConfigurer, in the same style as the rule configurers:

Taikai.builder()
    .namespace("com.company.project")
    .discoverChecks(checks -> checks
        .configure(RequiredFilesCheck.class, RequiredFilesCheck.files("README.md")) // settings
        .exclude(LicenseCheck.class))                                               // switch off
    .build()
    .checkAll();

discoverChecks() is the same as discoverChecks(checks -> {}). Calling discoverChecks several times customizes the same ChecksConfigurer, so the settings add up, and toBuilder() keeps them.

build() fails with a TaikaiException if a registered check cannot be loaded or instantiated, if exclude(...), configure(...) or context(...) names a check that is not registered, or if configure(...) or context(...) names an excluded check. A misspelled or outdated configuration therefore does not go unnoticed.

Configuring a single check¶

A check is created through its constructor without parameters, so a project cannot pass settings to it directly. Instead, the project configures the check by its class, and the check reads its configuration from the context. A check in a library can define its settings as a record and fall back to defaults when the project does not configure it:

public record ForbiddenDependencies(List<String> artifacts) {
}

public final class ForbiddenDependenciesCheck implements TaikaiCheck {

  private static final ForbiddenDependencies DEFAULTS =
      new ForbiddenDependencies(List.of("log4j:log4j"));

  @Override
  public String description() {
    return "Forbidden dependencies should not be on the classpath";
  }

  @Override
  public List<String> violations(CheckContext context) {
    List<String> forbidden = context.configuration(ForbiddenDependencies.class)
        .orElse(DEFAULTS)
        .artifacts();
    // ...
  }
}

The project configures the check:

Taikai.builder()
    .namespace("com.company.project")
    .discoverChecks(checks -> checks
        .configure(ForbiddenDependenciesCheck.class,
            new ForbiddenDependencies(List.of("log4j:log4j", "commons-logging"))))
    .build()
    .checkAll();

• Every check only sees its own configuration, so two checks can use the same type, such as List<String>, without getting each other's settings.
• A check has one configuration, typically a record with all its settings. Configuring a check again replaces its configuration.
• configuration(...) also accepts a supertype of the configured object. It throws an IllegalStateException if the check is configured with an object of another type, instead of silently falling back to the defaults.
• A check that cannot run without configuration uses requireConfiguration(...); a missing configuration is then reported as a violation of that check.

Changing the context¶

A context(...) function receives the context of a check, which already contains the configuration of the check, and returns the context the check gets instead. Extend ForwardingCheckContext from com.enofex.taikai.checks.spi to override only the methods you want to change; it forwards all others to the wrapped context:

.discoverChecks(checks -> checks
    .context(context -> new ForwardingCheckContext(context) {                      // every check
      @Override
      public ClassLoader classLoader() {
        return pluginClassLoader;
      }
    })
    .context(PomCheck.class, context -> new ForwardingCheckContext(context) {      // one check
      @Override
      public Path projectDirectory() {
        return super.projectDirectory().resolve("parent");
      }
    }))

The functions are applied in the order they are configured, each wrapping the result of the previous one; a function for a single check is skipped for all other checks. To give a function the last word, configure it last. A function can override every method of the context, including configuration(...), although configure(...) is the usual way to configure a check.

The functions are applied once per check and Taikai instance, and the resulting context is used by check(), checkAll() and dynamicTests() alike. Anything expensive, such as creating a class loader, belongs outside of the function. The context only changes what the checks see; checks are always discovered with the class loader of the test run.

5.15 Custom Exports¶

A TaikaiExport exports the configuration, for example its rules into a file that coding agents read. Exports work like custom checks: they are registered and discovered through the Java ServiceLoader, configured per export, and get an ExportContext with the project. They only run when export() is called, never with the rules and checks.

public final class RuleCountExport implements TaikaiExport {

  @Override
  public String description() {
    return "Number of rules";
  }

  @Override
  public void export(ExportContext context) {
    try {
      Files.writeString(context.projectDirectory().resolve("rules.txt"),
          context.rules().size() + " rules");
    } catch (IOException e) {
      throw new UncheckedIOException(e);
    }
  }
}

description() names the export in failure messages. If an export throws, export() stops and throws a TaikaiException that names the export, with the failure as its cause.

Registering and discovering exports¶

List the fully qualified class name of every export in src/test/resources/META-INF/services/com.enofex.taikai.exports.spi.TaikaiExport, or in src/main/resources/... of a library that ships exports:

com.enofex.taikai.exports.AgentsMarkdownExport
com.company.architecture.RuleCountExport

discoverExports() finds them when build() is called, and export() runs them sorted by their description:

Taikai.builder()
    .namespace("com.company.project")
    .java(java -> java.noUsageOfSystemOutOrErr())
    .discoverExports()
    .build()
    .export();

Like checks, an export must be a public class with a public constructor without parameters, and Taikai does not register its predefined exports itself, so that a new Taikai version never writes files on its own. exports() returns the discovered exports.

Predefined exports¶

The package com.enofex.taikai.exports contains the exports Taikai provides.

Configuring the exports¶

ExportsConfigurer excludes exports and configures them with their settings, like ChecksConfigurer. An export gets its settings with ExportContext.configuration(...) or requireConfiguration(...); other exports do not see them. build() fails if an excluded or configured export is not registered, or if a configured export is excluded.

.discoverExports(exports -> exports
    .configure(AgentsMarkdownExport.class, AgentsMarkdownExport.file("ARCHITECTURE.md"))
    .exclude(RuleCountExport.class))

ExportContext offers the same as CheckContext (the project directory, the namespace, the classes, the class loader and the configuration of the export), and in addition the configured rules with rules(). evaluate(rule) evaluates a rule as check() does, with the rule's own configuration, and returns the ArchUnit EvaluationResult with its violations instead of failing. The paths in the settings of an export are relative to the project directory.

Instructions for coding agents¶

Coding agents such as Claude Code or Codex read files like AGENTS.md or CLAUDE.md before they change code. AgentsMarkdownExport writes the description of every configured rule to the configured file, so agents know the rules before the architecture test fails:

Taikai.builder()
    .namespace("com.company.project")
    .java(java -> java
        .noUsageOfSystemOutOrErr()
        .fieldsShouldNotBePublic())
    .discoverExports(exports -> exports
        .configure(AgentsMarkdownExport.class, AgentsMarkdownExport.file("ARCHITECTURE.md")))
    .build()
    .export();

# Architecture Rules

The architecture test enforces these rules for `com.company.project`, so code that breaks one of them fails the build.

- Classes should not use System.out or System.err
- Fields should not be public unless they are static

The export replaces the whole file and creates missing parent directories. To keep instructions written by hand, export to a file of its own, as above, and reference it from AGENTS.md, or import it into CLAUDE.md with @ARCHITECTURE.md. The lines end with \n on every platform, so the file only changes when the rules change.

Reporting violations as SARIF¶

SarifExport evaluates the rules and writes their violations as a SARIF 2.1.0 report, with the file and line of each violation. The export writes the report even if there are violations, so the architecture test fails the build and the export runs in a test of its own:

@Test
void architecture() {
  taikai().checkAll();
}

@Test
void architectureReport() {
  taikai().export();
}

private static Taikai taikai() {
  return Taikai.builder()
      .namespace("com.company.project")
      .java(java -> java.noUsageOfSystemOutOrErr())
      .discoverExports(exports -> exports
          .configure(SarifExport.class, SarifExport.file("target/taikai.sarif")))
      .build();
}

The export finds the source file of a violation in the source directories src/main/java, src/main/kotlin, src/test/java and src/test/kotlin, by the package of its class, or by its file name if exactly one source file has that name. Other directories are configured with SarifExport.file("target/taikai.sarif").withSourceDirectories("src", "generated"). Violations without a line, such as of classes, point to the first line of their file. Code scanning on GitHub only shows violations with a location, so violations of a package, such as of the metrics rules, point to its package-info.java, or else to its first class by name, and violations of a cycle to one of its dependencies. Violations without a source file are reported without location. The level of a rule is error, warning or note for the ArchUnit priority HIGH, MEDIUM (the default) or LOW.

6. How to Read the Rule Reference¶

Sections 7 to 13 document every rule, and Section 14 the predefined checks. To keep them readable, examples are shown as fragments rather than complete tests. A fragment such as

.java(java -> java
    .classesShouldBeRecords(ClassCriteria.nameMatching(".*Dto")))

belongs inside the builder chain from Section 4:

Taikai.builder()
    .namespace("com.company.project")
    .java(java -> java
        .classesShouldBeRecords(ClassCriteria.nameMatching(".*Dto")))
    .build()
    .check();

Conventions used throughout the reference:

• Rules are fluent and chainable; each returns its configurer.
• Wherever a rule takes a single annotation or type, there are two overloads: one taking a Class<?> literal and one taking a fully qualified name as a String. The String form exists so you can reference types that are not on the test classpath. Only one form is shown per rule. Rules that take several annotations, such as classesShouldBeAnnotatedWithAll or noSelfInvocationOfProxiedMethods, take their fully qualified names only.
• Rules that apply to a selection of classes take a DescribedPredicate<? super JavaClass>, usually built with ClassCriteria, listed as classes. Rules that select fields or methods by name take FieldCriteria or MethodCriteria, listed as fields or methods.
• Every rule also has an overload with a trailing TaikaiRule.Configuration parameter (see 5.8). It is omitted from the signatures below.
• Collection<JavaModifier> parameters take ArchUnit's com.tngtech.archunit.core.domain.JavaModifier constants, for example List.of(PUBLIC, STATIC, FINAL).
• A regex must match the whole name, not merely occur inside it.
• For classes, a regex, including the one in ClassCriteria.nameMatching, is matched against the fully qualified name, so anchor it with a leading .*: .*Dto matches com.company.project.OrderDto, while Dto and [A-Z].* match nothing at all.
• For methods and fields, a regex, including the ones in FieldCriteria.nameMatching and MethodCriteria.nameMatching, is matched against the member's own name, without the declaring class: should.*, ^[A-Z][A-Z0-9_]*$.
• A packageIdentifier is not a regex but an ArchUnit package identifier, matched against the fully qualified name with * for one segment and .. for any number: com.company.project.., ..internal...
• An annotation matches whether it is placed directly on the class or member or inherited through another annotation, so a composed annotation such as @GetMapping counts as @RequestMapping. Only annotations kept in the class files can match, so RetentionPolicy.SOURCE annotations never do.
• Rules that check methods or fields ignore synthetic members generated by the compiler, which cannot be changed in source code: the $values() method of every enum, bridge methods of generic overrides with erased signatures, and fields such as $assertionsDisabled. Calls made by bridge methods do not count as self-invocations either.
• Likewise, rules that check classes themselves, such as their names, annotations, modifiers, fields or supertypes, ignore synthetic classes: the package-info class of an annotated package-info.java, and the class javac generates for a switch over an enum. Rules on dependencies and usages, such as noUsageOf or shouldNotImport, still check their code.

7. Java Rules¶

Default import mode: WITHOUT_TESTS.

Import and naming rules live in nested configurers, documented in 7.5 and 7.6.

7.1 Classes¶

classesShouldImplementHashCodeAndEquals¶

A class that overrides one of hashCode or equals must override both. Overriding only one breaks the contract and produces objects that misbehave in hash-based collections.

.java(java -> java
    .classesShouldImplementHashCodeAndEquals())

classesShouldResideInPackage¶

classesShouldResideInPackage(String packageIdentifier) classesShouldResideInPackage(DescribedPredicate<? super JavaClass> classes, String packageIdentifier)

With one argument, all imported classes must reside in the given package identifier, which supports the * and .. wildcards. With criteria, only the matching classes are constrained.

.java(java -> java
    .classesShouldResideInPackage("com.company.project..")
    .classesShouldResideInPackage(ClassCriteria.nameMatching(".*Utils"),
        "com.company.project.utils")
    .classesShouldResideInPackage(ClassCriteria.annotatedWith(Entity.class),
        "com.company.project.domain.."))

classesShouldResideOutsidePackage¶

classesShouldResideOutsidePackage(DescribedPredicate<? super JavaClass> classes, String packageIdentifier)

The inverse of the two-argument form above. Useful for keeping transport types out of the domain.

.java(java -> java
    .classesShouldResideOutsidePackage(ClassCriteria.nameMatching(".*Dto"),
        "com.company.project.domain..")
    .classesShouldResideOutsidePackage(ClassCriteria.annotatedWith(RestController.class),
        "com.company.project.domain.."))

classesShouldBeRecords¶

classesShouldBeRecords(DescribedPredicate<? super JavaClass> classes)

.java(java -> java
    .classesShouldBeRecords(ClassCriteria.nameMatching(".*Dto"))
    .classesShouldBeRecords(ClassCriteria.annotatedWith(ConfigurationProperties.class))
    .classesShouldBeRecords(ClassCriteria.nameMatching(".*Event")
        .and(ClassCriteria.inPackage("..events.."))))

classesShouldBeInterfaces¶

classesShouldBeInterfaces(DescribedPredicate<? super JavaClass> classes)

.java(java -> java
    .classesShouldBeInterfaces(ClassCriteria.nameMatching(".*Repository"))
    .classesShouldBeInterfaces(ClassCriteria.inPackage("..port..")))

classesShouldBeAssignableTo¶

classesShouldBeAssignableTo(DescribedPredicate<? super JavaClass> classes, Class<?> clazz)

Classes matching the criteria must be assignable to the type, whether by extending a class or implementing an interface.

.java(java -> java
    .classesShouldBeAssignableTo(ClassCriteria.nameMatching(".*Repository"), BaseRepository.class)
    .classesShouldBeAssignableTo(ClassCriteria.annotatedWith(Repository.class),
        BaseRepository.class))

classesShouldImplement¶

classesShouldImplement(DescribedPredicate<? super JavaClass> classes, Class<?> clazz)

Unlike classesShouldBeAssignableTo, an interface never satisfies this rule: the class itself must implement the interface, directly or through a superclass or another interface.

.java(java -> java
    .classesShouldImplement(ClassCriteria.nameMatching(".*Repository"), CrudRepository.class)
    .classesShouldImplement(ClassCriteria.annotatedWith(Repository.class), CrudRepository.class))

classesShouldHaveModifiers¶

classesShouldHaveModifiers(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> requiredModifiers)

.java(java -> java
    .classesShouldHaveModifiers(ClassCriteria.nameMatching(".*Config"), List.of(PUBLIC, FINAL))
    .classesShouldHaveModifiers(ClassCriteria.annotatedWith(PublicApi.class), List.of(PUBLIC)))

classesShouldNotHaveModifiers¶

classesShouldNotHaveModifiers(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> forbiddenModifiers)

.java(java -> java
    .classesShouldNotHaveModifiers(ClassCriteria.nameMatching(".*Internal"), List.of(PUBLIC))
    .classesShouldNotHaveModifiers(ClassCriteria.inPackage("..internal.."), List.of(PUBLIC))
    .classesShouldNotHaveModifiers(ClassCriteria.annotatedWith(InternalApi.class), List.of(PUBLIC)))

classesShouldBePackagePrivate¶

classesShouldBePackagePrivate(DescribedPredicate<? super JavaClass> classes)

Keeps module internals such as mappers hidden from other packages. With ClassCriteria.assignableTo, the subtypes are constrained but not the type itself, for example Spring Data repositories but not the Repository interface.

.java(java -> java
    .classesShouldBePackagePrivate(ClassCriteria.nameMatching(".*Mapper"))
    .classesShouldBePackagePrivate(
        ClassCriteria.assignableTo("org.springframework.data.repository.Repository"))
    .classesShouldBePackagePrivate(ClassCriteria.annotatedWith("jakarta.persistence.Entity")
        .or(ClassCriteria.inPackage("..internal.."))))

classesShouldBeAnnotatedWith¶

classesShouldBeAnnotatedWith(DescribedPredicate<? super JavaClass> classes, Class<? extends Annotation> annotationType)

.java(java -> java
    .classesShouldBeAnnotatedWith(ClassCriteria.nameMatching(".*Api"), PublicApi.class)
    .classesShouldBeAnnotatedWith(ClassCriteria.nameMatching(".*Api"),
        "com.company.project.PublicApi")
    .classesShouldBeAnnotatedWith(ClassCriteria.inPackage("..api.."), PublicApi.class))

classesShouldNotBeAnnotatedWith¶

classesShouldNotBeAnnotatedWith(DescribedPredicate<? super JavaClass> classes, Class<? extends Annotation> annotationType)

Selecting the classes by another annotation makes two annotations mutually exclusive.

.java(java -> java
    .classesShouldNotBeAnnotatedWith(ClassCriteria.annotatedWith(PublicApi.class),
        InternalApi.class)
    .classesShouldNotBeAnnotatedWith(ClassCriteria.nameMatching(".*Internal"), PublicApi.class)
    .classesShouldNotBeAnnotatedWith(ClassCriteria.inPackage("..internal.."), PublicApi.class))

classesShouldBeAnnotatedWithAll¶

classesShouldBeAnnotatedWithAll(DescribedPredicate<? super JavaClass> classes, Collection<String> requiredAnnotationTypes)

Classes matching the criteria must carry all the annotations in the collection, given as fully qualified annotation names.

.java(java -> java
    .classesShouldBeAnnotatedWithAll(ClassCriteria.nameMatching(".*Controller"),
        List.of(RestController.class.getName(), RequestMapping.class.getName()))
    .classesShouldBeAnnotatedWithAll(ClassCriteria.annotatedWith(RestController.class),
        List.of(RequestMapping.class.getName())))

classesShouldHaveField¶

classesShouldHaveField(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaField> requiredFields)

Classes matching the criteria must have at least one field matching the field criteria. Select the field by annotation, type or name with FieldCriteria, and combine criteria with .and(...) when a single field must satisfy all of them. The example requires an optimistic-locking @Version field in every entity, and a Long version in aggregates:

.java(java -> java
    .classesShouldHaveField(ClassCriteria.annotatedWith("jakarta.persistence.Entity"),
        FieldCriteria.annotatedWith("jakarta.persistence.Version"))
    .classesShouldHaveField(ClassCriteria.inPackage("..aggregate.."),
        FieldCriteria.annotatedWith("jakarta.persistence.Version")
            .and(FieldCriteria.ofType(Long.class))))

finalClassesShouldNotHaveProtectedMembers¶

A final class cannot be subclassed, so protected members are misleading and should be private or package-private.

.java(java -> java
    .finalClassesShouldNotHaveProtectedMembers())

utilityClassesShouldBeFinalAndHavePrivateConstructor¶

Classes whose methods are all static must be final and have only private constructors, so they can neither be extended nor instantiated.

A class declaring a main method is not treated as a utility class and is left alone entirely, so application entry points do not need a private constructor. Interfaces are not utility classes either, and neither are classes that extend a class other than Object, such as enums, records and exceptions with static factory methods.

.java(java -> java
    .utilityClassesShouldBeFinalAndHavePrivateConstructor())

7.2 Fields¶

fieldsShouldNotBePublic¶

No instance field may be public. Every static field is exempt, whether or not it is final, so a mutable public static field passes this rule. Combine it with fieldsShouldHaveModifiers if you also want constants pinned down:

.java(java -> java
    .fieldsShouldNotBePublic()
    .fieldsShouldHaveModifiers(FieldCriteria.nameMatching("^[A-Z][A-Z0-9_]*$"),
        List.of(STATIC, FINAL)))

fieldsShouldHaveModifiers¶

fieldsShouldHaveModifiers(DescribedPredicate<? super JavaField> fields, Collection<JavaModifier> requiredModifiers)

Fields matching the criteria, selected by name, annotation or type with FieldCriteria, must have all the modifiers. To select fields by their declaring class, use fieldsShouldHaveModifiersForClass.

.java(java -> java
    .fieldsShouldHaveModifiers(FieldCriteria.nameMatching("^[A-Z][A-Z0-9_]*$"),
        List.of(STATIC, FINAL))
    .fieldsShouldHaveModifiers(FieldCriteria.annotatedWith(Constant.class),
        List.of(PUBLIC, STATIC, FINAL)))

fieldsShouldNotHaveModifiers¶

fieldsShouldNotHaveModifiers(DescribedPredicate<? super JavaField> fields, Collection<JavaModifier> forbiddenModifiers)

.java(java -> java
    .fieldsShouldNotHaveModifiers(FieldCriteria.nameMatching(".*Cache"), List.of(PUBLIC))
    .fieldsShouldNotHaveModifiers(FieldCriteria.annotatedWith(Autowired.class), List.of(STATIC)))

fieldsShouldHaveModifiersForClass¶

fieldsShouldHaveModifiersForClass(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> requiredModifiers)

Selects fields by their declaring class, so every field of a matching class is constrained, for example to enforce constructor injection in services or encapsulated entities.

.java(java -> java
    .fieldsShouldHaveModifiersForClass(ClassCriteria.annotatedWith(Service.class),
        List.of(PRIVATE, FINAL))
    .fieldsShouldHaveModifiersForClass(ClassCriteria.annotatedWith("jakarta.persistence.Entity"),
        List.of(PRIVATE)))

fieldsShouldNotHaveModifiersForClass¶

fieldsShouldNotHaveModifiersForClass(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> forbiddenModifiers)

Fails for a field that has any of the given modifiers.

.java(java -> java
    .fieldsShouldNotHaveModifiersForClass(ClassCriteria.annotatedWith(RestController.class),
        List.of(STATIC)))

fieldsShouldNotBeOfType¶

fieldsShouldNotBeOfType(DescribedPredicate<? super JavaField> fields, DescribedPredicate<? super JavaClass> forbiddenTypes)

Like fieldsShouldNotBeOfTypeForClass, with the same checks and limitations, but the fields are selected with field criteria, for example by name or annotation. The example keeps entity identifiers away from UUID:

.java(java -> java
    .fieldsShouldNotBeOfType(FieldCriteria.annotatedWith("jakarta.persistence.Id"),
        ClassCriteria.type(UUID.class)))

fieldsShouldNotBeOfTypeForClass¶

fieldsShouldNotBeOfTypeForClass(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> forbiddenTypes)

Keeps types out of the fields of selected classes while allowing them to be used elsewhere, for example legacy date types in entities. ClassCriteria.type matches exactly the type, so combine it with ClassCriteria.assignableTo to ban subtypes such as java.sql.Timestamp as well:

.java(java -> java
    .fieldsShouldNotBeOfTypeForClass(ClassCriteria.annotatedWith("jakarta.persistence.Entity"),
        ClassCriteria.type(Date.class).or(ClassCriteria.assignableTo(Date.class))
            .or(ClassCriteria.type(Calendar.class))
            .or(ClassCriteria.assignableTo(Calendar.class))))

serialVersionUIDFieldsShouldBeStaticFinalLong¶

Fields named serialVersionUID must be declared static final long. Any other declaration is ignored by Java serialization and silently fails to pin the class version.

.java(java -> java
    .serialVersionUIDFieldsShouldBeStaticFinalLong())

7.3 Methods¶

methodsShouldNotDeclareGenericExceptions¶

Methods must not declare Exception or RuntimeException; use specific types instead.

.java(java -> java
    .methodsShouldNotDeclareGenericExceptions())

methodsShouldNotDeclareException¶

methodsShouldNotDeclareException(DescribedPredicate<? super JavaMethod> methods, Class<? extends Throwable> clazz) methodsShouldNotDeclareException(DescribedPredicate<? super JavaMethod> methods, DescribedPredicate<? super JavaClass> forbiddenTypes)

The member criteria select methods, usually by name with MethodCriteria.nameMatching. The second overload forbids every exception type that matches class criteria, such as all exceptions of a technical package.

.java(java -> java
    .methodsShouldNotDeclareException(MethodCriteria.nameMatching("should.*"),
        SpecificException.class)
    .methodsShouldNotDeclareException(MethodCriteria.nameMatching(".*"),
        ClassCriteria.inPackage("java.sql")))

methodsShouldNotDeclareExceptionForClass¶

methodsShouldNotDeclareExceptionForClass(DescribedPredicate<? super JavaClass> classes, Class<? extends Throwable> clazz) methodsShouldNotDeclareExceptionForClass(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> forbiddenTypes)

Selects methods by their declaring class rather than by name, so no method of a matching class may declare the exception type. The second overload forbids every exception type that matches the criteria.

.java(java -> java
    .methodsShouldNotDeclareExceptionForClass(ClassCriteria.annotatedWith(RestController.class),
        SQLException.class)
    .methodsShouldNotDeclareExceptionForClass(ClassCriteria.inPackage("..domain.."),
        ClassCriteria.inPackage("java.sql")))

methodsShouldNotReturn¶

methodsShouldNotReturn(DescribedPredicate<? super JavaMethod> methods, DescribedPredicate<? super JavaClass> forbiddenTypes)

Like methodsShouldNotReturnForClass, with the same checks and limitations, but the methods are selected with method criteria, for example by name or annotation.

.java(java -> java
    .methodsShouldNotReturn(MethodCriteria.nameMatching("find.*"),
        ClassCriteria.type(Optional.class)))

methodsShouldNotReturnForClass¶

methodsShouldNotReturnForClass(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> forbiddenTypes)

Keeps implementation types out of a layer's return signatures while allowing them to be used internally. Both class selectors can be created with com.enofex.taikai.ClassCriteria or supplied as ArchUnit predicates:

.java(java -> java
    .methodsShouldNotReturnForClass(
        ClassCriteria.inPackage("com.company.controller.."),
        ClassCriteria.annotatedWith("jakarta.persistence.Entity"))
    .methodsShouldNotReturnForClass(
        ClassCriteria.nameMatching(".*Controller"),
        ClassCriteria.inPackage("com.company.internal..")
            .or(ClassCriteria.inPackage("com.collaborator.client.."))))

See 5.13 for the available criteria and how to combine them.

The rule checks all methods declared in selected classes, including private methods. It checks the declared return type, nested generic arguments, wildcard and type-variable bounds, and array components. For example, banning entities rejects Entity, Entity[], List<Entity>, and ResponseEntity<List<Entity>>. It does not inspect fields, parameters, method bodies, or inherited methods declared in other classes. Types hidden by an erased signature such as Object or a raw List cannot be detected. A final Configuration parameter supports the usual customization.

methodsShouldReturn¶

methodsShouldReturn(DescribedPredicate<? super JavaMethod> methods, DescribedPredicate<? super JavaClass> requiredTypes)

Like methodsShouldReturnForClass, with the same checks and limitations, but the methods are selected with method criteria.

.java(java -> java
    .methodsShouldReturn(MethodCriteria.annotatedWith(GetMapping.class),
        ClassCriteria.nameMatching(".*DTO")))

methodsShouldReturnForClass¶

methodsShouldReturnForClass(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> requiredTypes)

Requires every method declared in the selected classes to have at least one matching type in its return signature. For example, require controllers to return objects whose class names end in DTO:

.java(java -> java
    .methodsShouldReturnForClass(ClassCriteria.nameMatching(".*Controller"),
        ClassCriteria.nameMatching(".*DTO")))

OrderDTO, OrderDTO[], List<OrderDTO>, and ResponseEntity<List<OrderDTO>> satisfy this rule. Nested generic arguments, wildcard and type-variable bounds, and array components are considered. String, Object, primitives, and void fail the DTO criterion. Both ClassCriteria.annotatedWith overloads and ClassCriteria.inPackage also work with this rule.

Matching one type satisfies the requirement even if the signature contains other types, such as Map<Entity, OrderDTO>. Combine methodsShouldReturnForClass with methodsShouldNotReturnForClass to prohibit entities or internal types as well. The same scope and limitations apply: all visibilities are checked, inherited declarations are excluded, and only declared types are inspected. A final Configuration parameter supports customization.

methodsShouldBeAnnotatedWith¶

methodsShouldBeAnnotatedWith(DescribedPredicate<? super JavaMethod> methods, Class<? extends Annotation> annotationType)

Every method matching the criteria, usually selected by name with MethodCriteria.nameMatching, must carry the annotation.

.java(java -> java
    .methodsShouldBeAnnotatedWith(MethodCriteria.nameMatching(".*Api"), PublicApi.class))

methodsShouldBeAnnotatedWithForClass¶

methodsShouldBeAnnotatedWithForClass(DescribedPredicate<? super JavaClass> classes, Class<? extends Annotation> annotationType)

Selects methods by their declaring class, so every method of a matching class must carry the annotation. Meta-annotations count, so in the example below @GetMapping satisfies @RequestMapping and every method of a Feign client must map to an endpoint.

.java(java -> java
    .methodsShouldBeAnnotatedWithForClass(ClassCriteria.annotatedWith(FeignClient.class),
        RequestMapping.class))

The rule checks methods of every visibility, including private and static helpers, so it suits classes whose methods all form an API, such as client interfaces. It does not suit controllers: their private helpers would have to carry the annotation too, for example a @PreAuthorize that Spring ignores on private methods. Select the endpoint methods by name with methodsShouldBeAnnotatedWith instead.

methodsShouldBeAnnotatedWithAll¶

methodsShouldBeAnnotatedWithAll(DescribedPredicate<? super JavaMethod> methods, Collection<String> requiredAnnotationTypes)

Methods matching the criteria must carry all the annotations in the collection, given as fully qualified annotation names. A classic use is Spring Data: @Modifying is only correct together with @Transactional and @Query.

.java(java -> java
    .methodsShouldBeAnnotatedWithAll(MethodCriteria.annotatedWith(Modifying.class),
        List.of(Transactional.class.getName(), Query.class.getName())))

methodsShouldBeAnnotatedWithAllForClass¶

methodsShouldBeAnnotatedWithAllForClass(DescribedPredicate<? super JavaClass> classes, Collection<String> requiredAnnotationTypes)

Every method declared in a matching class must carry all the annotations, given as fully qualified names.

.java(java -> java
    .methodsShouldBeAnnotatedWithAllForClass(ClassCriteria.annotatedWith(FeignClient.class),
        List.of(RequestMapping.class.getName())))

methodsShouldNotBeAnnotatedWith¶

methodsShouldNotBeAnnotatedWith(DescribedPredicate<? super JavaMethod> methods, Class<? extends Annotation> annotationType)

Selecting the methods by another annotation makes two annotations mutually exclusive.

.java(java -> java
    .methodsShouldNotBeAnnotatedWith(MethodCriteria.annotatedWith(PublicApi.class),
        InternalApi.class))

methodsShouldNotBeAnnotatedWithForClass¶

methodsShouldNotBeAnnotatedWithForClass(DescribedPredicate<? super JavaClass> classes, Class<? extends Annotation> annotationType)

No method declared in a matching class may carry the annotation.

.java(java -> java
    .methodsShouldNotBeAnnotatedWithForClass(ClassCriteria.annotatedWith(RestController.class),
        Transactional.class))

methodsShouldHaveModifiers¶

methodsShouldHaveModifiers(DescribedPredicate<? super JavaMethod> methods, Collection<JavaModifier> requiredModifiers)

Selects methods with method criteria, by method name or annotation.

.java(java -> java
    .methodsShouldHaveModifiers(MethodCriteria.nameMatching("create.*"), List.of(PUBLIC))
    .methodsShouldHaveModifiers(MethodCriteria.annotatedWith(Transactional.class),
        List.of(PUBLIC)))

methodsShouldNotHaveModifiers¶

methodsShouldNotHaveModifiers(DescribedPredicate<? super JavaMethod> methods, Collection<JavaModifier> forbiddenModifiers)

.java(java -> java
    .methodsShouldNotHaveModifiers(MethodCriteria.nameMatching("internal.*"), List.of(PUBLIC))
    .methodsShouldNotHaveModifiers(MethodCriteria.annotatedWith(Test.class), List.of(PUBLIC)))

methodsShouldHaveModifiersForClass¶

methodsShouldHaveModifiersForClass(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> requiredModifiers)

Selects methods by the declaring class, so every method of a matching class is constrained.

.java(java -> java
    .methodsShouldHaveModifiersForClass(ClassCriteria.nameMatching(".*Controller"), List.of(PUBLIC))
    .methodsShouldHaveModifiersForClass(ClassCriteria.annotatedWith(RestController.class),
        List.of(PUBLIC)))

methodsShouldNotHaveModifiersForClass¶

methodsShouldNotHaveModifiersForClass(DescribedPredicate<? super JavaClass> classes, Collection<JavaModifier> forbiddenModifiers)

.java(java -> java
    .methodsShouldNotHaveModifiersForClass(ClassCriteria.nameMatching(".*Internal"),
        List.of(PUBLIC))
    .methodsShouldNotHaveModifiersForClass(ClassCriteria.inPackage("..internal.."),
        List.of(PUBLIC)))

7.4 Usage Restrictions¶

noUsageOf¶

noUsageOf(Class<?> clazz) noUsageOf(DescribedPredicate<? super JavaClass> forbiddenTypes) noUsageOf(DescribedPredicate<? super JavaClass> classes, Class<?> clazz) noUsageOf(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> forbiddenTypes)

Forbids all usage of a type. With two arguments, the first one selects the classes to check, which lets you retire an API layer by layer, for example with ClassCriteria.inPackage(...). A type passed as Class or name is banned together with its subtypes; with forbiddenTypes, every type that matches the criteria is banned, for example a whole package. Classes that match forbiddenTypes themselves are not checked, so the classes of a banned package may still use each other.

.java(java -> java
    .noUsageOf(Date.class)
    .noUsageOf(ClassCriteria.inPackage("com.company.project.domain.."), Calendar.class)
    .noUsageOf("com.company.legacy.UnwantedClass")
    .noUsageOf(ClassCriteria.annotatedWith(Entity.class), Date.class)
    .noUsageOf(ClassCriteria.inPackage("com.company.legacy.."))
    .noUsageOf(ClassCriteria.inPackage("..domain.."),
        ClassCriteria.inPackage("org.springframework.web..")))

Use this rule to keep HTTP exceptions out of service and repository packages, including unchecked exceptions constructed without a throws declaration:

.java(java -> java
    .noUsageOf(ClassCriteria.inPackage("com.company.service.."),
        "org.springframework.web.server.ResponseStatusException")
    .noUsageOf(ClassCriteria.inPackage("com.company.repository.."),
        "org.springframework.web.server.ResponseStatusException"))

The restriction includes subclasses and bans every dependency on the exception: construction, declarations, catches, fields, and other references. It is a layer dependency rule, not an analysis of which exceptions might propagate from called methods. methodsShouldNotDeclareException only checks throws declarations and does not catch unchecked exceptions thrown without one.

noUsageOfDeprecatedAPIs¶

Nothing annotated @Deprecated may be used.

.java(java -> java
    .noUsageOfDeprecatedAPIs())

noUsageOfSystemOutOrErr¶

Forbids System.out and System.err in favor of a logging framework.

.java(java -> java
    .noUsageOfSystemOutOrErr())

7.5 Imports¶

Import rules live in the nested imports(...) configurer.

shouldHaveNoCycles¶

Fails on cyclic dependencies between the slices of your namespace. Each first-level subpackage forms one slice together with all its subpackages: for com.company.project, everything in com.company.project.order.. is one slice and everything in com.company.project.billing.. another. Cycles inside a slice, such as between order.api and order.internal, are not reported, and neither are cycles involving classes directly in com.company.project.

.java(java -> java
    .imports(imports -> imports
        .shouldHaveNoCycles()))

The rule needs a namespace, the global one or one given with Configuration.of(String namespace). It throws a TaikaiException if the classes are set directly without a namespace, and it reads the global namespace when java(...) is first configured, see 5.10.

shouldImport¶

shouldImport(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> requiredImports)

Classes matching the first criteria must import something matching the second.

.java(java -> java
    .imports(imports -> imports
        .shouldImport(ClassCriteria.nameMatching(".*Service"),
            ClassCriteria.nameMatching("com.company.project.BusinessException"))
        .shouldImport(ClassCriteria.annotatedWith(Service.class),
            ClassCriteria.nameMatching(".*BusinessException"))))

shouldNotImport¶

shouldNotImport(DescribedPredicate<? super JavaClass> forbiddenImports) shouldNotImport(DescribedPredicate<? super JavaClass> classes, DescribedPredicate<? super JavaClass> forbiddenImports)

With one argument, nothing may import classes matching the criteria; use ClassCriteria.inPackage(...) to ban a package. With two, only classes matching the first criteria are constrained. As with noUsageOf, classes that match the disallowed criteria themselves are not checked, so the classes of a banned package may still import each other.

.java(java -> java
    .imports(imports -> imports
        .shouldNotImport(ClassCriteria.inPackage("com.company.project.legacy.."))
        .shouldNotImport(ClassCriteria.nameMatching(".*Service"),
            ClassCriteria.nameMatching("com.company.project.SpecificException"))
        .shouldNotImport(ClassCriteria.annotatedWith(Deprecated.class))
        .shouldNotImport(ClassCriteria.inPackage("..domain.."),
            ClassCriteria.inPackage("org.springframework.web.."))))

A one-argument ban applies to every class outside the banned package, including the module that owns it. To keep a module's internal package private to that module, constrain only the classes outside the module:

.java(java -> java
    .imports(imports -> imports
        .shouldNotImport(
            DescribedPredicate.not(ClassCriteria.inPackage("com.company.project.order..")),
            ClassCriteria.inPackage("com.company.project.order.internal.."))))

Predefined import patterns¶

com.enofex.taikai.java.ImportPatterns provides criteria for packages that are commonly banned from production code or from a particular layer. Each one is ClassCriteria.inPackage(...) for the package identifier below, so they work anywhere criteria are accepted, such as shouldNotImport, noUsageOf, or excludeClasses.

import static com.enofex.taikai.java.ImportPatterns.lombok;
import static com.enofex.taikai.java.ImportPatterns.shaded;

.java(java -> java
    .imports(imports -> imports
        .shouldNotImport(lombok())
        .shouldNotImport(shaded())))

7.6 Naming¶

Naming rules live in the nested naming(...) configurer.

packagesShouldMatchDefault¶

Applies Taikai's default package convention, ^[a-z_]+(\.[a-z_][a-z0-9_]*)*$: lowercase segments, no digits in the first character of a segment, no camel case.

.java(java -> java
    .naming(naming -> naming
        .packagesShouldMatchDefault()))

packagesShouldMatch¶

packagesShouldMatch(String regex)

.java(java -> java
    .naming(naming -> naming
        .packagesShouldMatch("^com\\.company\\.project(\\.[a-z]+)*$")))

classesShouldMatch¶

classesShouldMatch(String regex) classesShouldMatch(DescribedPredicate<? super JavaClass> classes, String regex)

Remember that the regex is matched against the fully qualified name, so it has to cover the package too. The criteria overload restricts the rule to matching classes, for example annotated classes, implementations of an interface or subtypes of a class.

.java(java -> java
    .naming(naming -> naming
        .classesShouldMatch("com\\.company\\.project\\..*")
        .classesShouldMatch(ClassCriteria.inPackage("..web.."), ".*(Controller|Dto)")
        .classesShouldMatch(ClassCriteria.annotatedWith(Entity.class), ".*Entity")
        .classesShouldMatch(ClassCriteria.implementing(Configurer.class), ".*Configurer")
        .classesShouldMatch(ClassCriteria.assignableTo(AbstractConfigurer.class), ".*Configurer")))

classesShouldNotMatch¶

classesShouldNotMatch(String regex) classesShouldNotMatch(DescribedPredicate<? super JavaClass> classes, String regex)

.java(java -> java
    .naming(naming -> naming
        .classesShouldNotMatch(".*Impl")
        .classesShouldNotMatch(ClassCriteria.inPackage("..domain.."), ".*(Dto|Entity)")))

methodsShouldMatch¶

methodsShouldMatch(String regex) methodsShouldMatch(DescribedPredicate<? super JavaMethod> methods, String regex)

With one argument, all methods must match. The criteria overload restricts the rule to matching methods. Synthetic methods generated by the compiler are ignored.

.java(java -> java
    .naming(naming -> naming
        .methodsShouldMatch("[a-z][a-zA-Z0-9]*")
        .methodsShouldMatch(MethodCriteria.annotatedWith(Scheduled.class), "^scheduled[A-Z].*")))

methodsShouldNotMatch¶

methodsShouldNotMatch(String regex) methodsShouldNotMatch(DescribedPredicate<? super JavaMethod> methods, String regex)

With one argument, no method may match. The criteria overload restricts the rule to matching methods.

.java(java -> java
    .naming(naming -> naming
        .methodsShouldNotMatch("^(foo|bar).*")
        .methodsShouldNotMatch(MethodCriteria.annotatedWith(Test.class), "^test.*")))

methodsShouldMatchForClass¶

methodsShouldMatchForClass(DescribedPredicate<? super JavaClass> classes, String regex)

Selects methods by their declaring class, so every method of a matching class must have a name matching the regex. Synthetic methods generated by the compiler are ignored.

.java(java -> java
    .naming(naming -> naming
        .methodsShouldMatchForClass(ClassCriteria.annotatedWith(Repository.class),
            "(find|save|delete).*")))

methodsShouldNotMatchForClass¶

methodsShouldNotMatchForClass(DescribedPredicate<? super JavaClass> classes, String regex)

Selects methods by their declaring class, so no method of a matching class may have a name matching the regex. Synthetic methods generated by the compiler are ignored.

.java(java -> java
    .naming(naming -> naming
        .methodsShouldNotMatchForClass(ClassCriteria.annotatedWith(RestController.class), "get.*")))

fieldsShouldMatch¶

fieldsShouldMatch(String regex) fieldsShouldMatch(DescribedPredicate<? super JavaField> fields, String regex)

With one argument, all fields must match. Synthetic fields generated by the compiler are ignored. The criteria overload constrains the name of fields matching the criteria, for example by their declared type with FieldCriteria.ofType. The example below requires every field name to start with a letter and contain only letters, digits and underscores, every field of type Matcher to be named matcher, every field whose type is a repository to end with Repository, and every @Value field to be camel case.

.java(java -> java
    .naming(naming -> naming
        .fieldsShouldMatch("[A-Za-z][A-Za-z0-9_]*")
        .fieldsShouldMatch(FieldCriteria.ofType(Matcher.class), "matcher")
        .fieldsShouldMatch(FieldCriteria.ofType(ClassCriteria.annotatedWith(Repository.class)),
            ".*Repository")
        .fieldsShouldMatch(FieldCriteria.annotatedWith(Value.class), "^[a-z][a-zA-Z0-9]*$")))

To select fields by their declaring class instead, use fieldsShouldMatchForClass.

fieldsShouldNotMatch¶

fieldsShouldNotMatch(String regex) fieldsShouldNotMatch(DescribedPredicate<? super JavaField> fields, String regex)

With one argument, no field may match. The criteria overload restricts the rule to matching fields.

.java(java -> java
    .naming(naming -> naming
        .fieldsShouldNotMatch(".*(List|Set|Map)$")
        .fieldsShouldNotMatch(FieldCriteria.ofType(Logger.class), "^log$")))

fieldsShouldMatchForClass¶

fieldsShouldMatchForClass(DescribedPredicate<? super JavaClass> classes, String regex)

Selects fields by their declaring class, so every field of a matching class must have a name matching the regex. Unlike fieldsShouldMatch, the criteria select the class the field is declared in, not the field's type. Synthetic fields generated by the compiler are ignored.

.java(java -> java
    .naming(naming -> naming
        .fieldsShouldMatchForClass(ClassCriteria.annotatedWith("jakarta.persistence.Entity"),
            "[a-z][a-zA-Z0-9]*")))

fieldsShouldNotMatchForClass¶

fieldsShouldNotMatchForClass(DescribedPredicate<? super JavaClass> classes, String regex)

.java(java -> java
    .naming(naming -> naming
        .fieldsShouldNotMatchForClass(ClassCriteria.inPackage("..api.."), ".*(Entity|Dao)$")))

constantsShouldFollowConventions¶

constantsShouldFollowConventions() constantsShouldFollowConventions(Collection<String> excludedFields)

static final fields must match ^[A-Z][A-Z0-9_]*$. serialVersionUID is excluded by default. Passing a collection replaces that default exclusion list, so include serialVersionUID yourself if you still want it exempt.

.java(java -> java
    .naming(naming -> naming
        .constantsShouldFollowConventions()))

.java(java -> java
    .naming(naming -> naming
        .constantsShouldFollowConventions(List.of("serialVersionUID", "log"))))

enumConstantsShouldFollowConventions¶

Enum constants must match ^[A-Z][A-Z0-9_]*$.

.java(java -> java
    .naming(naming -> naming
        .enumConstantsShouldFollowConventions()))

booleanMethodsShouldStartWith¶

booleanMethodsShouldStartWith() booleanMethodsShouldStartWith(Collection<String> prefixes)

Methods returning boolean or Boolean must start with one of the given prefixes. The default set is is, has, can, should; passing a collection replaces it. A prefix has to be followed by an uppercase letter or nothing at all, so is and isValid pass but issue does not.

equals(Object), record component accessors and synthetic methods are exempt.