Skip to content
enofexPublic

About

Taikai is an extension of the popular ArchUnit library, offering a comprehensive suite of predefined rules and checks tailored for various technologies.🌟 Star if you like it!

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

283 stars

Watchers

7 watching

Forks

Latest commit

Β 

History

681 Commits

Folders and files

Repository files navigation

Taikai

Taikai extends the capabilities of the popular ArchUnit library by offering a comprehensive suite of predefined rules tailored for various technologies. It simplifies the enforcement of architectural constraints and best practices in your codebase, ensuring consistency and quality across your projects.

Maven Usage

Add Taikai as a dependency in your pom.xml:

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

Replace ${taikai.version} with the appropriate version defined in your project. ArchUnit comes along transitively, so you do not need to declare it yourself.

Gradle Usage

Add Taikai as a dependency in your build.gradle file:

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

Replace ${taikaiVersion} with the appropriate version defined in your project. ArchUnit comes along transitively, so you do not need to declare it yourself.

Kotlin/JVM

Use com.enofex:taikai-kotlin for Kotlin-aware architecture rules and a receiver DSL. The original Java API also works from Kotlin tests. See the Kotlin manual and the runnable Spring Kotlin demo.

import com.enofex.taikai.kotlin.functionsShouldNotExceedMaxParameters
import com.enofex.taikai.kotlin.taikai

taikai {
    namespace("com.company.project")
    spring { services { it.namesShouldEndWithService() } }
    kotlin {
        classesShouldBeDataClasses(".*Response")
        dataClassesShouldBeImmutable()
    }
    metrics { functionsShouldNotExceedMaxParameters(4) }
}.checkAll()

JUnit Example Test

Here's an example demonstrating the usage of some Taikai rules with JUnit. Customize rules as needed using TaikaiRule.of(). The runnable Spring Java demo shows a complete application with its architecture tests.

@Test
void architecture() {
  Taikai.builder()
      .namespace("com.company.project")
      .java(java -> java
          .noUsageOfDeprecatedAPIs()
          .methodsShouldNotDeclareGenericExceptions()
          .utilityClassesShouldBeFinalAndHavePrivateConstructor()
          .imports(imports -> imports
              .shouldHaveNoCycles()
              .shouldNotImport(ImportPatterns.shaded()))
          .naming(naming -> naming
              .classesShouldNotMatch(".*Impl")
              .methodsShouldNotMatch("^(foo$|bar$).*")
              .fieldsShouldNotMatch(".*(List|Set|Map)$")
              .fieldsShouldMatch(FieldCriteria.ofType("com.company.project.Matcher"), "matcher")
              .constantsShouldFollowConventions()
              .enumConstantsShouldFollowConventions()
              .interfacesShouldNotHavePrefixI()))
      .logging(logging -> logging
          .loggersShouldFollowConventions(Logger.class, "logger", List.of(PRIVATE, FINAL)))
      .test(test -> test
          .junit(junit -> junit
              .classesShouldNotBeAnnotatedWithDisabled()
              .methodsShouldNotBeAnnotatedWithDisabled()))
      .jpa(jpa -> jpa
          .entities(entities -> entities
              .shouldBePackagePrivate()
              .idsShouldNotBeOfType(ClassCriteria.type(UUID.class))
              .shouldHaveFieldAnnotatedWithVersion()
              .fieldsShouldNotBeOfType(
                  ClassCriteria.type(Date.class).or(ClassCriteria.assignableTo(Date.class))
                      .or(ClassCriteria.type(Calendar.class))
                      .or(ClassCriteria.assignableTo(Calendar.class)))
              .namesShouldMatch(".+Entity")))
      .metrics(metrics -> metrics
          .classesShouldNotExceedMaxInheritanceDepth(3)
          .classesShouldNotExceedMaxDependencies(20))
      .spring(spring -> spring
          .noAutowiredFields()
          .noSelfInvocationOfProxiedMethods()
          .boot(boot -> boot
              .applicationClassShouldResideInPackage("com.company.project"))
          .configurations(configuration -> configuration
              .namesShouldEndWithConfiguration())
          .controllers(controllers -> controllers
              .shouldBeAnnotatedWithRestController()
              .namesShouldEndWithController()
              .shouldNotDependOnOtherControllers()
              .shouldNotDependOnRepositories()
              .shouldBePackagePrivate())
          .services(services -> services
              .shouldBeAnnotatedWithService()
              .shouldNotDependOnControllers()
              .namesShouldEndWithService())
          .repositories(repositories -> repositories
              .shouldBeAnnotatedWithRepository()
              .shouldNotDependOnServices()
              .namesShouldEndWithRepository())
          .transactional(transactional -> transactional
              .methodsShouldBePublic()
              .shouldNotBeSelfInvoked()
              .shouldNotBeUsedInControllers()))
      .addRule(TaikaiRule.of(...)) // Add custom ArchUnit rule here
      .build()
      .checkAll();
}

One Test per Rule

Return dynamicTests() from a JUnit @TestFactory to see every rule as its own test in the IDE and in test reports:

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

Custom Checks

A TaikaiCheck checks what ArchUnit cannot see, such as files in the project directory, resources or the classpath. Ship checks in a library, or use predefined ones such as com.enofex.taikai.checks.RequiredFilesCheck, register them in META-INF/services/com.enofex.taikai.checks.spi.TaikaiCheck, and discover them:

Taikai.builder()
    .namespace("com.company.project")
    .discoverChecks(checks -> checks
        .configure(RequiredFilesCheck.class, RequiredFilesCheck.files(
            "README.md", "LICENSE", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md")))
    .build()
    .checkAll();

Custom Exports

A TaikaiExport exports the configuration, for example into a file. Exports are registered like checks, in META-INF/services/com.enofex.taikai.exports.spi.TaikaiExport, and run with export(). The predefined com.enofex.taikai.exports.AgentsMarkdownExport writes the rules as Markdown for coding agents, to reference from AGENTS.md or CLAUDE.md:

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

The predefined com.enofex.taikai.exports.SarifExport writes the rule violations as a SARIF report, for example with SarifExport.file("target/taikai.sarif"), with the file and line of each violation.

User Guide

Explore the complete documentation for comprehensive information on all available rules.

Contributing

Interested in contributing? Check out our Contribution Guidelines for details on how to get involved. Note that we expect everyone to follow the Code of Conduct.

What You Will Need

  • Git
  • Java 17 or higher

Get the Source Code

Clone the repository

git clone git@github.com:enofex/taikai.git
cd taikai

Build the Code

To compile, test and build

./mvnw clean package -B

Backers

The Open Source Community



Website

Visit the Taikai Website for general information and documentation.

Support Taikai

If Taikai helps you build better software, consider supporting its development.

Your sponsorship helps maintain the project, improve existing features and develop new capabilities.

Become a sponsor ❀️

About

Taikai is an extension of the popular ArchUnit library, offering a comprehensive suite of predefined rules and checks tailored for various technologies.🌟 Star if you like it!

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

283 stars

Watchers

7 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages