Maven – Linting files

Linting files

Using the lint goal will analyze your C4 source files against a set of linting rules and report any violation.

It is useful to ensure than your source files are following a set of rules for maintainability, consistency and so on, as while these cannot be viewed as syntax errors, they can harm your project.

It should be seen as an automated way to help into bringing some homogeneity around the code within a project team.

You can pick which rules you want to enable/disable among a set of predefined built-in rules, but you can also write your own, and use them as long as they are imported in the classpath (class files, JARs, etc.).

Below are some examples of configurations with explanations. You can find more about the lint goal there.

Disabling built-in rules

Every built-in rules has a isActivated property that allows you to disable a rule that would not be useful to your setup.

The following configuration snippet disables the aliasesShouldBeListedInDictionary rule:

<build>
    <plugins>
        <plugin>
            <groupId>org.thewonderlemming.c4plantuml</groupId>
            <artifactId>c4plantuml-maven-plugin</artifactId>
            <version>1.0.0-RC1</version>
            <executions>
                <execution>
                    <id>linting-c4-files</id>
                    <goals>
                        <goal>lint</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <aliasesShouldBeListedInDictionary>
                                <isActivated>false</isActivated>
                            </aliasesShouldBeListedInDictionary>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Please refer to the built-in rules page to get a list of the rules properties names.

Failing the build on linting errors

By the default, the lint goal will ignore encountered syntax errors, but you can configure it to fail the build instead:

<build>
    <plugins>
        <plugin>
            <groupId>org.thewonderlemming.c4plantuml</groupId>
            <artifactId>c4plantuml-maven-plugin</artifactId>
            <version>1.0.0-RC1</version>
            <executions>
                <execution>
                    <id>linting-c4-files</id>
                    <goals>
                        <goal>lint</goal>
                    </goals>
                    <configuration>
                        <failOnLintErrors>false</failOnLintErrors>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Using custom rules

You can of course write your own rules and use them within your project without publishing them to public Maven repositories such as Central or MvnRepository.

Please refer to the dedicated documentation page on how to do that. We’ll focus here on providing parameters to your custom rules.

To avoid putting any hard constrains on designing your own rules, we use a java.util.Properties object to hold the rules configuration.

Imagine the following use case:

You have a rule that inspects the entities descriptions and names against a keyword list to find any sensitive information, and that your rule needs a to report the results to a distant service.

Let’s say that your rule would require the following properties:

checkSensitiveInfo.reportUrl: URL of the remote service to report to
checkSensitiveInfo.environment.authenticationToken: name of the environment property that contains the authentication token to use with the remote service

You could find yourself with the following configuration snippet in order to customize and run your rule:

<build>
    <plugins>
        <plugin>
            <groupId>org.thewonderlemming.c4plantuml</groupId>
            <artifactId>c4plantuml-maven-plugin</artifactId>
            <version>1.0.0-RC1</version>
            <executions>
                <execution>
                    <id>linting-c4-files</id>
                    <goals>
                        <goal>lint</goal>
                    </goals>
                    <configuration>
                        <customRules>
                            <property>
                                <name>checkSensitiveInfo.reportUrl</name>
                                <value>https://compliance-checks.internal/report</value>
                            </property>
                            <property>
                                <name>checkSensitiveInfo.environment.authenticationToken</name>
                                <value>REPORT_AUTH_TOKEN</value>
                            </property>
                        </customRules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

It is advised to qualify your properties names (here we used checkSensitiveInfo) in order to avoid collisions with other rules as your rule set will keep growing.