Temporarily disable existing violations with baseline

Adding katachi to an existing project means that on the first run, undeclared files and directories come out as violations. The basic approach is to work through the reported paths one by one — adding them to the definition, moving them, or deleting them — but when there are a lot of them, you can’t clear them all right away.

baseline is a feature that temporarily suppresses existing violations, so that new violations fail the test.

Setting it up

1. Write baseline() in the definition

ProjectArchitecture.kt (excerpt)

val projectArchitecture: Architecture = architecture {
    // ...
    baseline()

    // ...
}

When you set baseline, by default the project root’s katachi-baseline.json is used as the baseline file.

2. Declare the baseline file itself with layout { }

The baseline file is also one of the project’s files, so unless it’s declared as a role, projectArchitecture.assert() will error out.

Following convention, prepare a role named "BaselineFile" and add it to your architecture definition.

val projectArchitecture = architecture {
    // ...
    "Tool".group {
      "Katachi".group {
        baselineFile()
      }
    }

    // ...
}

fun DeclarationContainerScope.baselineFile() = "BaselineFile" {
    title = "katachi Baseline file"
    summary = "A file for temporarily suppressing existing violations"
    description = "See: https://tbsten.github.io/katachi/guides/baseline/"
    layout {
        "katachi-baseline.json".file()
    }
}

Show moreShow less

3. Create the baseline file

Running the architecture test with -Dkatachi.baseline.update=true makes all violations pass instead of erroring, and writes them into the baseline file.

./gradlew :architecture-test:test -Dkatachi.baseline.update=true

It’s recommended to commit the created/updated file.

After you fix a tolerated violation

When you fix a violation that had been tolerated, the baseline file is left with a record of a violation that no longer exists. If left alone, a different file placed at the same path later would pass silently, so katachi reports these leftovers as [StaleBaselineEntry] and fails the test.

To remove fixed violations from the baseline file, run the architecture test again with -Dkatachi.baseline.prune=true.

./gradlew :architecture-test:test -Dkatachi.baseline.prune=true

prune only reduces the number of records. It never adds new violations to the baseline file (that is the job of -Dkatachi.baseline.update=true). Commit the baseline file again once its violations have gone down.

Summary

• baseline is a feature that records existing violations in the baseline file and temporarily suppresses them, so that only newly added violations, and entries still in the baseline file after they were fixed, fail the test.
• The baseline file is created and updated by running the architecture test with -Dkatachi.baseline.update=true. Commit the resulting file.
• When you fix a tolerated violation, the entries left in the baseline file fail the test as [StaleBaselineEntry]. -Dkatachi.baseline.prune=true removes the violations you have fixed.

Next steps

• Your first architecture definition … How to write your first definition, before tolerating any existing violations with a baseline.