Normalize table usage reports (#11605)

* Add `Sources` column to JavaScript markdown report
* Add support for `GENERATE_TABLE_USAGE` env variable in Java report
* Bump Node.js version in Gradle to match Dockerfile
* Change report folder to `build/reports/tableusage`
* Fix spotless git hook not registering
* Move report classes to `org.hiero.mirror.common.tableusage` package
* Normalize report formats
* Rewrite Java CSV report to use Jackson's `CsvMapper`

Signed-off-by: Steven Sheehy <[email protected]>

Author: steven-sheehy

build.gradle.kts

@@ -21,7 +21,7 @@ extra.apply {
     set("jooq.version", "3.20.5") // Must match buildSrc/build.gradle.kts
     set("prometheus-client.version", "1.3.10") // Temporary until next Spring Boot
     set("mapStructVersion", "1.6.3")
-    set("nodeJsVersion", "22.14.0")
+    set("nodeJsVersion", "22.17.1")
     set("protobufVersion", "4.31.1")
     set("reactorGrpcVersion", "1.2.4")
     set("tomcat.version", "10.1.43") // Temporary until next Spring Boot

buildSrc/build.gradle.kts

@@ -43,4 +43,4 @@ val gitHook =
         commandLine("git", "config", "core.hookspath", "buildSrc/src/main/resources/hooks")
     }
 
-project.tasks.build { dependsOn(gitHook) }
+tasks.processResources { dependsOn(gitHook) }

common/build.gradle.kts

@@ -8,6 +8,7 @@ dependencies {
     val testClasses by configurations.registering
     annotationProcessor("jakarta.persistence:jakarta.persistence-api")
     api("com.fasterxml.jackson.core:jackson-databind")
+    api("com.fasterxml.jackson.dataformat:jackson-dataformat-csv")
     api("com.github.ben-manes.caffeine:caffeine")
     api("com.google.guava:guava")
     api("com.google.protobuf:protobuf-java")

common/src/test/java/org/hiero/mirror/common/GlobalTestSetup.java

@@ -2,9 +2,9 @@
 
 package org.hiero.mirror.common;
 
-import org.hiero.mirror.common.util.CsvGenerator;
-import org.hiero.mirror.common.util.MarkdownReportGenerator;
-import org.hiero.mirror.common.util.TestExecutionTracker;
+import org.hiero.mirror.common.tableusage.CsvReportGenerator;
+import org.hiero.mirror.common.tableusage.MarkdownReportGenerator;
+import org.hiero.mirror.common.tableusage.TestExecutionTracker;
 import org.junit.platform.engine.TestExecutionResult;
 import org.junit.platform.launcher.LauncherSession;
 import org.junit.platform.launcher.LauncherSessionListener;
@@ -48,7 +48,11 @@ public void executionFinished(TestIdentifier testIdentifier, TestExecutionResult
 
     @Override
     public void launcherSessionClosed(LauncherSession session) {
-        MarkdownReportGenerator.generateTableUsageReport();
-        CsvGenerator.generateTableUsageReport();
+        final var generateTableUsage = System.getenv().getOrDefault("GENERATE_TABLE_USAGE", "true");
+
+        if (Boolean.parseBoolean(generateTableUsage)) {
+            MarkdownReportGenerator.generateReport();
+            CsvReportGenerator.generateReport();
+        }
     }
 }

common/src/test/java/org/hiero/mirror/common/config/TableUsageReportTestConfiguration.java

@@ -4,6 +4,8 @@
 
 import jakarta.persistence.EntityManager;
 import org.hiero.mirror.common.filter.ApiTrackingFilter;
+import org.hiero.mirror.common.tableusage.TrackingRepositoryFactoryBean;
+import org.hiero.mirror.common.tableusage.TrackingRepositoryProxyPostProcessor;
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.context.annotation.Bean;
 import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

common/src/test/java/org/hiero/mirror/common/filter/ApiTrackingFilter.java

@@ -9,8 +9,8 @@
 import jakarta.servlet.ServletResponse;
 import jakarta.servlet.http.HttpServletRequest;
 import java.io.IOException;
-import org.hiero.mirror.common.util.EndpointContext;
-import org.hiero.mirror.common.util.EndpointNormalizer;
+import org.hiero.mirror.common.tableusage.EndpointContext;
+import org.hiero.mirror.common.tableusage.EndpointNormalizer;
 
 public final class ApiTrackingFilter implements Filter {
 

common/src/test/java/org/hiero/mirror/common/interceptor/RepositoryUsageInterceptor.java

@@ -2,7 +2,7 @@
 
 package org.hiero.mirror.common.interceptor;
 
-import static org.hiero.mirror.common.util.EndpointContext.UNKNOWN_ENDPOINT;
+import static org.hiero.mirror.common.tableusage.EndpointContext.UNKNOWN_ENDPOINT;
 
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.metamodel.EntityType;
@@ -15,31 +15,31 @@
 import org.aopalliance.intercept.MethodInterceptor;
 import org.aopalliance.intercept.MethodInvocation;
 import org.hibernate.query.spi.QueryImplementor;
+import org.hiero.mirror.common.tableusage.EndpointContext;
+import org.hiero.mirror.common.tableusage.SqlParsingUtil;
+import org.hiero.mirror.common.tableusage.TestExecutionTracker;
 import org.hiero.mirror.common.util.DomainUtils;
-import org.hiero.mirror.common.util.EndpointContext;
-import org.hiero.mirror.common.util.SqlParsingUtil;
-import org.hiero.mirror.common.util.TestExecutionTracker;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.core.RepositoryInformation;
 
 @CustomLog
 @RequiredArgsConstructor
 public class RepositoryUsageInterceptor implements MethodInterceptor {
+
     private static final Map<String, Map<String, Set<String>>> API_TABLE_QUERIES = new ConcurrentHashMap<>();
 
+    private final RepositoryInformation repositoryInformation;
+    private final EntityManager entityManager;
+
     public static Map<String, Map<String, Set<String>>> getApiTableQueries() {
         return API_TABLE_QUERIES;
     }
 
-    private final RepositoryInformation repositoryInformation;
-    private final EntityManager entityManager;
-
     /**
-     * Intercepts repository method invocation to track accessed database tables per API endpoint.
-     * Only tracks during test execution as determined by {@link TestExecutionTracker}.
-     * Extracts SQL queries either from native {@code @Query} annotations or Hibernate's query string,
-     * then parses table names from the SQL.
-     * Falls back to resolving the table name from the JPA entity metadata if no SQL found.
+     * Intercepts repository method invocation to track accessed database tables per API endpoint. Only tracks during
+     * test execution as determined by {@link TestExecutionTracker}. Extracts SQL queries either from native
+     * {@code @Query} annotations or Hibernate's query string, then parses table names from the SQL. Falls back to
+     * resolving the table name from the JPA entity metadata if no SQL found.
      *
      * @param invocation the method invocation context
      * @return the method invocation's original return value
@@ -83,8 +83,8 @@ public Object invoke(final MethodInvocation invocation) throws Throwable {
     }
 
     /**
-     * Resolves the JPA table name for the given entity class by querying the JPA metamodel.
-     * Converts the entity name to snake_case.
+     * Resolves the JPA table name for the given entity class by querying the JPA metamodel. Converts the entity name to
+     * snake_case.
      *
      * @param entityClass the JPA entity class
      * @return the resolved table name, or {@code "UNKNOWN_TABLE"} if not found
@@ -113,10 +113,9 @@ private String extractSqlFromQueryAnnotation(final Method method) {
     }
 
     /**
-     * Attempts to extract the SQL query string executed by the repository method invocation.
-     * First tries to get native SQL from {@link Query} annotation,
-     * then attempts to invoke the method and check if it returns a Hibernate {@link QueryImplementor}
-     * to obtain the query string.
+     * Attempts to extract the SQL query string executed by the repository method invocation. First tries to get native
+     * SQL from {@link Query} annotation, then attempts to invoke the method and check if it returns a Hibernate
+     * {@link QueryImplementor} to obtain the query string.
      *
      * @param invocation the method invocation context
      * @return the SQL query string if available, or {@code null} if not extractable

common/src/test/java/org/hiero/mirror/common/tableusage/CsvReportGenerator.java

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package org.hiero.mirror.common.tableusage;
+
+import com.fasterxml.jackson.dataformat.csv.CsvMapper;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import lombok.experimental.UtilityClass;
+import org.hiero.mirror.common.interceptor.RepositoryUsageInterceptor;
+
+@UtilityClass
+public final class CsvReportGenerator {
+
+    public static void generateReport() {
+        final var path = Paths.get("build", "reports", "tableusage", "table-usage.csv");
+        final var usageMap = RepositoryUsageInterceptor.getApiTableQueries();
+        final var csvMapper = CsvMapper.builder().build();
+        final var schema = csvMapper.schemaFor(TableUsage.class).withHeader().sortedBy("endpoint", "table", "source");
+        path.getParent().toFile().mkdirs();
+
+        try (final var writer = Files.newBufferedWriter(path)) {
+            var sequenceWriter =
+                    csvMapper.writerFor(TableUsage.class).with(schema).writeValues(writer);
+
+            for (final var entry : usageMap.entrySet()) {
+                final var endpoint = entry.getKey();
+
+                for (final var tableEntry : entry.getValue().entrySet()) {
+                    final var table = tableEntry.getKey();
+
+                    for (final var source : tableEntry.getValue()) {
+                        sequenceWriter.write(new TableUsage(endpoint, table, source));
+                    }
+                }
+            }
+        } catch (final IOException e) {
+            throw new UncheckedIOException(e);
+        }
+    }
+
+    private record TableUsage(String endpoint, String table, String source) {}
+}

common/src/test/java/org/hiero/mirror/common/util/EndpointContext.java renamed to common/src/test/java/org/hiero/mirror/common/tableusage/EndpointContext.java

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 
-package org.hiero.mirror.common.util;
+package org.hiero.mirror.common.tableusage;
 
 import lombok.experimental.UtilityClass;
 
 /**
  * Provides per-thread tracking of the current API endpoint context.
  * <p>
- * This class stores the logical endpoint (e.g., <code>/graphql</code>, <code>/importer</code>) associated
- * with the currently executing request or test, allowing downstream components such as interceptors,
- * instrumentation, or logging to access a consistent identifier for attribution purposes.
+ * This class stores the logical endpoint (e.g., <code>/graphql</code>, <code>/importer</code>) associated with the
+ * currently executing request or test, allowing downstream components such as interceptors, instrumentation, or logging
+ * to access a consistent identifier for attribution purposes.
  * </p>
  */
 @UtilityClass
@@ -20,14 +20,14 @@ public class EndpointContext {
 
     private static final ThreadLocal<String> CURRENT_ENDPOINT = new InheritableThreadLocal<>();
 
-    public static void setCurrentEndpoint(final String endpoint) {
-        CURRENT_ENDPOINT.set(endpoint);
-    }
-
     public static String getCurrentEndpoint() {
         return CURRENT_ENDPOINT.get();
     }
 
+    public static void setCurrentEndpoint(final String endpoint) {
+        CURRENT_ENDPOINT.set(endpoint);
+    }
+
     public static void clearCurrentEndpoint() {
         CURRENT_ENDPOINT.remove();
     }

common/src/test/java/org/hiero/mirror/common/util/EndpointNormalizer.java renamed to common/src/test/java/org/hiero/mirror/common/tableusage/EndpointNormalizer.java

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-package org.hiero.mirror.common.util;
+package org.hiero.mirror.common.tableusage;
 
 import java.util.Map;
 import java.util.regex.Pattern;