Skip to content

build: add Checkstyle, SpotBugs and JaCoCo quality gates #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Zhoujie628 merged 2 commits into from
Sep 17, 2026
+329 −4
Merged

build: add Checkstyle, SpotBugs and JaCoCo quality gates #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f1358b
style: add JSpecify @NullMarked to match SDK null-safety contract
Zhoujie628 Sep 17, 2026
3b8ab4b
build: add Checkstyle, SpotBugs and JaCoCo quality gates
Zhoujie628 Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions config/checkstyle/checkstyle-suppressions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
"https://checkstyle.org/dtds/suppressions_1_2.dtd">

<!-- Existing-code suppressions; new code must pass. Clean these up over time. -->
<suppressions>
<!-- WireLogFormatter: deeply nested if-chains from protocol formatting -->
<suppress checks="NestedIfDepth"
files="WireLogFormatter\.java"/>

<!-- ExecutePsop builder-facing constructor carries the full option set -->
<suppress checks="ParameterNumber"
files="ExecutePsop\.java"/>

<!-- Utility classes with intentional public constructors (builder/entry-point API surface) -->
<suppress checks="HideUtilityClassConstructor"
files="FailureMapping\.java|LoadPsop\.java|ExecutePsop\.java"/>
<!-- Spring Boot entry-point class: implicit constructor is the standard pattern -->
<suppress checks="HideUtilityClassConstructor"
files="SpringWorkbenchApplication\.java"/>
</suppressions>
82 changes: 82 additions & 0 deletions config/checkstyle/checkstyle.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">

<!--
Pragmatic Checkstyle rules for the workflow engine.
Formatting (indent, line length, import order) is handled by Spotless;
this config focuses on naming, complexity, and structural checks.
-->
<module name="Checker">
<property name="charset" value="UTF-8"/>

<property name="severity" value="error"/>

<module name="SuppressionFilter">
<property name="file" value="${config_loc}/checkstyle-suppressions.xml"/>
<property name="optional" value="false"/>
</module>

<!-- File-level checks -->
<module name="FileTabCharacter">
<property name="eachLine" value="true"/>
</module>
<module name="NewlineAtEndOfFile"/>

<!-- TreeWalker: AST-based checks -->
<module name="TreeWalker">

<!-- Naming conventions (underscores allowed in method names: spec-section test cases) -->
<module name="TypeName"/>
<module name="MethodName">
<property name="format" value="^[a-z][a-zA-Z0-9_]*$"/>
</module>
<module name="MemberName"/>
<module name="ParameterName"/>
<module name="LocalVariableName"/>
<!-- Allow conventional lowercase names: log (SLF4J), mapper (Jackson) -->
<module name="ConstantName">
<property name="format" value="^log$|^mapper$|^cardMapper$|^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
</module>
<module name="PackageName">
<property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
</module>

<!-- Imports: unused/redundant are errors; star imports warned (cleanup ongoing) -->
<module name="UnusedImports"/>
<module name="RedundantImport"/>

<!-- Complexity (thresholds calibrated for existing codebase; tighten over time) -->
<module name="CyclomaticComplexity">
<property name="max" value="35"/>
</module>
<module name="MethodLength">
<property name="max" value="150"/>
</module>
<module name="ParameterNumber">
<property name="max" value="12"/>
</module>
<module name="NestedIfDepth">
<property name="max" value="3"/>
</module>
<module name="NestedTryDepth">
<property name="max" value="2"/>
</module>

<!-- Common bug patterns -->
<module name="EmptyCatchBlock">
<property name="exceptionVariableName" value="expected|ignore|ignored"/>
</module>
<module name="EqualsHashCode"/>
<module name="StringLiteralEquality"/>
<module name="ArrayTypeStyle"/>
<module name="OneStatementPerLine"/>

<!-- Design -->
<module name="HideUtilityClassConstructor"/>
<module name="InterfaceIsType"/>
<module name="MutableException"/>

</module>
</module>
91 changes: 91 additions & 0 deletions config/spotbugs/spotbugs-exclude.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
SpotBugs exclusion filter for the workflow engine.
These patterns are either intentional design choices or false positives
for this codebase's patterns. Clean up over time; new findings still block verify.
-->
<FindBugsFilter>
<!-- Returning/storing mutable collections in builders, records and config accessors is
the intended API surface; defensive copies are made at trust boundaries. -->
<Match>
<Or>
<Bug pattern="EI_EXPOSE_REP"/>
<Bug pattern="EI_EXPOSE_REP2"/>
<Bug pattern="EI_EXPOSE_REP2_EI_EXPOSE_REP2"/>
</Or>
</Match>

<!-- Java serialization is not used by this project. -->
<Match>
<Or>
<Bug pattern="SE_BAD_FIELD"/>
<Bug pattern="SE_NO_SERIALVERSIONID"/>
</Or>
</Match>

<!-- Throwing from constructors: no finalizers in this codebase, finalizer attack N/A. -->
<Match>
<Bug pattern="CT_CONSTRUCTOR_THROW"/>
</Match>

<!-- Single-use SecureRandom: fresh instance per AES-GCM IV is intentional and safe. -->
<Match>
<Bug pattern="DMI_RANDOM_USED_ONLY_ONCE"/>
</Match>

<!-- Duplicated branch bodies in normalization (kept for symmetry with sibling branches). -->
<Match>
<Bug pattern="DB_DUPLICATE_BRANCHES"/>
</Match>

<!-- CompletableFuture exception paths in WorkflowExecutor intentionally ignore
secondary failures when aggregating step results. -->
<Match>
<Bug pattern="DM_DEFAULT_ENCODING,DE_MIGHT_IGNORE"/>
</Match>

<!-- Generated fixtures and test code -->
<Match>
<Or>
<Class name="~.*Test.*"/>
<Class name="~.*Mock.*"/>
</Or>
</Match>

<!-- Vendor SDK adapter classes: the vendor API shape is out of our control. -->
<Match>
<Or>
<Class name="~.*OrderHttpClientAdapter.*"/>
<Class name="~.*OrderGatewayClientRuntime.*"/>
<Class name="~.*EastcomOrderByteBufWorkaround.*"/>
<Class name="~.*MockGatewayServer.*"/>
<Class name="~.*MockOrderHttpSessionClient.*"/>
</Or>
</Match>

<!-- Samples/demo code: accepted demo-quality items; review on next touch.
- Dead store in parseNegotiationContext (leftover context map)
- Vacuous instanceof in NotificationPolicy (defensive String check)
- NegotiationStrategy intentionally shadows the control interface name (sample mirror)
- Boolean-returning booleanParam helper may return null to signal "unset"
- handleLogin catches Exception broadly as the demo login boundary
- doPrivileged warning: SecurityManager is not used by this project -->
<Match>
<Or>
<Class name="~.*NegotiationBaseAgentExecutor.*"/>
<Class name="~.*NotificationPolicy.*"/>
<Class name="~.*examples.negotiation.NegotiationStrategy"/>
<Class name="~.*JdkHttpA2AServer.*"/>
<Class name="~.*A2ATInitialization.*"/>
</Or>
<Bug pattern="DP_CREATE_CLASSLOADER_INSIDE_DO_PRIVILEGED"/>
</Match>
<Match>
<Or>
<Class name="~.*NegotiationBaseAgentExecutor.*"/>
<Class name="~.*NotificationPolicy.*"/>
<Class name="~.*examples.negotiation.NegotiationStrategy"/>
<Class name="~.*JdkHttpA2AServer.*"/>
</Or>
</Match>
</FindBugsFilter>
81 changes: 80 additions & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,12 @@
<version>2.46.1</version>
<configuration>
<java>
<excludes>
<!-- google-java-format cannot parse package-info.java -->
<exclude>**/package-info.java</exclude>
</excludes>
<googleJavaFormat>
<version>1.22.0</version>
<version>1.24.0</version>
<style>GOOGLE</style>
</googleJavaFormat>
<removeUnusedImports/>
Expand All @@ -191,6 +195,81 @@
</execution>
</executions>
</plugin>

<!-- Checkstyle: naming, complexity, structural checks (formatting is Spotless) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.6.0</version>
<dependencies>
<dependency>
<groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
<version>10.20.0</version>
</dependency>
</dependencies>
<configuration>
<configLocation>${maven.multiModuleProjectDirectory}/config/checkstyle/checkstyle.xml</configLocation>
<propertyExpansion>config_loc=${maven.multiModuleProjectDirectory}/config/checkstyle</propertyExpansion>
<includeTestSourceDirectory>false</includeTestSourceDirectory>
<consoleOutput>true</consoleOutput>
<failOnViolation>true</failOnViolation>
</configuration>
<executions>
<execution>
<id>checkstyle-check</id>
<phase>validate</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- SpotBugs: bug pattern detection (null dereference, resource leaks, concurrency) -->
<plugin>
<groupId>com.github.spotbugs</groupId>
<artifactId>spotbugs-maven-plugin</artifactId>
<version>4.8.6.4</version>
<configuration>
<effort>Max</effort>
<threshold>Medium</threshold>
<excludeFilterFile>${maven.multiModuleProjectDirectory}/config/spotbugs/spotbugs-exclude.xml</excludeFilterFile>
<xmlOutput>true</xmlOutput>
</configuration>
<executions>
<execution>
<id>spotbugs-check</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- JaCoCo: test coverage reporting (no threshold enforcement) -->
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.12</version>
<executions>
<execution>
<id>jacoco-prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>jacoco-report</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>flatten-maven-plugin</artifactId>
Expand Down
6 changes: 6 additions & 0 deletions spring-boot-starter/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,12 @@
<version>${spring-boot.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.jspecify</groupId>
<artifactId>jspecify</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>

<build>
Expand Down
24 changes: 24 additions & 0 deletions spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
/*
* Copyright (c) 2026 Huawei Technologies Co., Ltd.
* All Rights Reserved.
*
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License. You may obtain
* a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/

/**
* Spring Boot auto-configuration for the A2A server side.
*/
@org.jspecify.annotations.NullMarked
package dev.openan.workflow.engine.spring;
7 changes: 7 additions & 0 deletions workflow-engine/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,13 @@
<version>${slf4j.version}</version>
<scope>test</scope>
</dependency>
<!-- Null-safety annotations matching the A2A SDK's JSpecify contract -->
<dependency>
<groupId>org.jspecify</groupId>
<artifactId>jspecify</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>

<build>
Expand Down
17 changes: 15 additions & 2 deletions ...w-engine/src/main/java/dev/openan/workflow/engine/client/DefaultWorkflowEngineClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,22 @@
import dev.openan.workflow.engine.control.EventCallback;
import dev.openan.workflow.engine.control.EventType;
import dev.openan.workflow.engine.control.NegotiationStrategy;
import dev.openan.workflow.engine.model.*;
import dev.openan.workflow.engine.model.BusinessFailure;
import dev.openan.workflow.engine.model.MessageContent;
import dev.openan.workflow.engine.model.NegotiationReply;
import dev.openan.workflow.engine.model.NegotiationRequest;
import dev.openan.workflow.engine.model.ReceivedMessage;
import dev.openan.workflow.engine.model.SendMessageResult;
import dev.openan.workflow.engine.model.TaskRequest;
import java.time.Duration;
import java.util.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.ExecutionException;
Expand Down
3 changes: 2 additions & 1 deletion workflow-engine/src/main/java/dev/openan/workflow/engine/client/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
Expand All @@ -21,4 +21,5 @@
* Protocol adaptation: transport runtimes, authentication, negotiation correlation, independent
* subscriptions, and wire observability. Content generation stays with the host.
*/
@org.jspecify.annotations.NullMarked
package dev.openan.workflow.engine.client;