Add Javadoc for graph construction, cycle analysis, report rendering, and related tests

Author: coderabbitai[bot]

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/CompositeGraphBuilder.java

@@ -123,6 +123,16 @@ public CodebaseGraphDTO getCodebaseGraphDTO(
         return getCodebaseGraphDTO(repositoryPath, repositoryRoot, config);
     }
 
+    /**
+     * Combines Java and Kotlin graphs, source mappings, and disharmonies.
+     *
+     * <p>Shared edge weights are summed before unattributed vertices are reconciled,
+     * locations are hydrated, and package-to-class relationships are rebuilt.
+     *
+     * @param javaDto the Java analysis result
+     * @param kotlinDto the Kotlin analysis result
+     * @return the unified codebase graph
+     */
     static CodebaseGraphDTO merge(CodebaseGraphDTO javaDto, CodebaseGraphDTO kotlinDto) {
         Graph<VertexInfo, DefaultWeightedEdge> mergedClassGraph =
                 new DefaultDirectedWeightedGraph<>(DefaultWeightedEdge.class);
@@ -312,6 +322,10 @@ private static String simpleName(String fqn) {
         return lastDot >= 0 ? fqn.substring(lastDot + 1) : fqn;
     }
 
+    /**
+     * Redirects a fabricated vertex's edges to its canonical declaration, summing duplicate weights.
+     * Self-loops introduced by contraction are dropped, and new cross-package edges are recorded.
+     */
     private static void contractVertex(
             Graph<VertexInfo, DefaultWeightedEdge> classGraph,
             Graph<VertexInfo, DefaultWeightedEdge> packageGraph,
@@ -372,6 +386,7 @@ private static void contractVertex(
         classGraph.removeVertex(fabricatedVertex);
     }
 
+    /** Adds or increments a package edge when both class endpoints have distinct, nonempty packages. */
     private static void addPackageEdgeIfCrossPackage(
             Graph<VertexInfo, DefaultWeightedEdge> packageGraph, VertexInfo classSource, VertexInfo classTarget) {
         String pkgSource = packageName(classSource.getName());
@@ -400,6 +415,7 @@ private static String packageName(String fqn) {
         return lastDot >= 0 ? fqn.substring(0, lastDot) : "";
     }
 
+    /** Copies source vertices and edges into the target, adding weights for edges already present. */
     private static void mergeGraph(
             Graph<VertexInfo, DefaultWeightedEdge> source, Graph<VertexInfo, DefaultWeightedEdge> target) {
         // Add vertices
@@ -422,6 +438,7 @@ private static void mergeGraph(
         }
     }
 
+    /** Maps a source DTO's package-to-class relationships onto the corresponding merged graph edges. */
     private static void mergeClassRelationships(
             CodebaseGraphDTO dto,
             Graph<VertexInfo, DefaultWeightedEdge> sourceClassGraph,

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/GraphDependencyCollector.java

@@ -38,13 +38,26 @@ public class GraphDependencyCollector implements DependencyCollector {
     /** Registry of the VertexInfo instances created for each vertex name. */
     private final Map<String, VertexInfo> vertexRegistry = new HashMap<>();
 
+    /**
+     * Creates a dependency collector that writes into the supplied graphs.
+     *
+     * @param classReferencesGraph the graph receiving class dependencies
+     * @param packageReferencesGraph the graph receiving cross-package dependencies
+     */
     public GraphDependencyCollector(
             Graph<VertexInfo, DefaultWeightedEdge> classReferencesGraph,
             Graph<VertexInfo, DefaultWeightedEdge> packageReferencesGraph) {
         this.classReferencesGraph = classReferencesGraph;
         this.packageReferencesGraph = packageReferencesGraph;
     }
 
+    /**
+     * Adds or increments a class dependency and records its corresponding package relationship.
+     * Dependencies from a class to itself are ignored.
+     *
+     * @param fromClassFqn the fully qualified source class name
+     * @param toClassFqn the fully qualified target class name
+     */
     @Override
     public void addClassDependency(String fromClassFqn, String toClassFqn) {
         if (fromClassFqn.equals(toClassFqn)) {
@@ -78,6 +91,13 @@ public void addClassDependency(String fromClassFqn, String toClassFqn) {
         }
     }
 
+    /**
+     * Adds or increments the package dependency implied by two class names.
+     *
+     * @param fromClassFqn the fully qualified source class name
+     * @param toClassFqn the fully qualified target class name
+     * @return the package edge, or {@code null} for equal or empty endpoint packages
+     */
     @Override
     public DefaultWeightedEdge addPackageDependency(String fromClassFqn, String toClassFqn) {
         String fromPackageName = getPackageFromFqn(fromClassFqn);
@@ -128,6 +148,12 @@ private VertexInfo getOrCreateVertex(String name) {
         return vertexRegistry.computeIfAbsent(name, VertexInfo::forName);
     }
 
+    /**
+     * Records the raw source location reported by a visitor for later inspection.
+     *
+     * @param classFqn the fully qualified class name
+     * @param sourceFilePath the visitor-reported source location
+     */
     @Override
     public void recordClassLocation(String classFqn, String sourceFilePath) {
         // Capture the location reported during collection; repository-relative
@@ -140,6 +166,11 @@ public void registerPackage(String packageName) {
         packagesInCodebase.add(packageName);
     }
 
+    /**
+     * Registers a class vertex with its derived parent namespace, even if it has no dependencies.
+     *
+     * @param classFqn the fully qualified class name
+     */
     @Override
     public void registerClassVertex(String classFqn) {
         classReferencesGraph.addVertex(getOrCreateVertex(classFqn));

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/VertexInfo.java

@@ -32,6 +32,7 @@ public class VertexInfo {
     private final String parentNamespace;
     private String locationOnDisk;
 
+    /** Creates a vertex with the supplied identity and parent namespace, leaving its disk location unset. */
     private VertexInfo(String name, String parentNamespace) {
         this.name = name;
         this.parentNamespace = parentNamespace;
@@ -128,6 +129,12 @@ public String getParentNamespace() {
         return parentNamespace;
     }
 
+    /**
+     * Compares vertex names; parent namespaces and hydrated disk locations do not affect identity.
+     *
+     * @param o the object to compare
+     * @return whether the other object is a vertex with the same name
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) {
@@ -139,11 +146,21 @@ public boolean equals(Object o) {
         return name.equals(((VertexInfo) o).name);
     }
 
+    /**
+     * Returns a name-based hash that remains stable when the disk location is hydrated.
+     *
+     * @return the vertex name's hash code
+     */
     @Override
     public int hashCode() {
         return name.hashCode();
     }
 
+    /**
+     * Returns the vertex name for graph edge rendering.
+     *
+     * @return the fully qualified class name or package name
+     */
     @Override
     public String toString() {
         return name;

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/VertexInfoHydrator.java

@@ -21,6 +21,7 @@
  */
 public final class VertexInfoHydrator {
 
+    /** Prevents instantiation of this utility class. */
     private VertexInfoHydrator() {}
 
     /**
@@ -49,6 +50,13 @@ public static void hydrate(
         }
     }
 
+    /**
+     * Resolves a class source path, falling back to its outer Java class or enclosing Kotlin construct.
+     *
+     * @param fqn the fully qualified class name
+     * @param mapping the repository-relative class-to-source-file mapping
+     * @return the mapped source path, or {@code null} if neither the class nor its enclosing class is mapped
+     */
     private static String resolveClassLocation(String fqn, Map<String, String> mapping) {
         String direct = mapping.get(fqn);
         if (direct != null) {
@@ -135,6 +143,7 @@ private static String directMemberPackageName(String fqn) {
         return packageName;
     }
 
+    /** Returns the directory of the package's selected direct-member source file, or {@code null} if unmapped. */
     private static String resolvePackageLocation(String packageName, Map<String, String> packagePathIndex) {
         String memberPath = packagePathIndex.get(packageName);
         if (memberPath == null) {

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/graphbuilder/KotlinSourceFileGraphBuilder.java

@@ -36,6 +36,16 @@
 @Slf4j
 public class KotlinSourceFileGraphBuilder implements SourceFileGraphBuilder {
 
+    /**
+     * Builds dependency graphs and metrics from Kotlin source files, honoring configured test exclusions.
+     * Recoverable partial parse trees are visited before the resulting graph metadata is finalized.
+     *
+     * @param repositoryPath the source directory to scan
+     * @param repositoryRoot the repository root used to canonicalize source locations
+     * @param config the parser and source-exclusion settings
+     * @return the Kotlin codebase graph with hydrated vertex locations
+     * @throws IOException if source files cannot be read
+     */
     @Override
     public CodebaseGraphDTO buildGraph(String repositoryPath, String repositoryRoot, GraphBuilderConfig config)
             throws IOException {

codebase-graph-builder/src/main/java/org/hjug/graphbuilder/metrics/GraphMetricsCollector.java

@@ -30,12 +30,24 @@ public class GraphMetricsCollector implements DependencyCollector {
     /** Maps callee full-qualified method signature → set of caller class FQNs (CC). */
     private final Map<String, Set<String>> calleeToCallerClasses = new HashMap<>();
 
+    /**
+     * Creates a metrics collector backed by the supplied dependency graphs.
+     *
+     * @param classGraph the graph receiving class dependencies
+     * @param packageGraph the graph receiving package dependencies
+     */
     public GraphMetricsCollector(
             Graph<VertexInfo, DefaultWeightedEdge> classGraph, Graph<VertexInfo, DefaultWeightedEdge> packageGraph) {
         this.classGraph = classGraph;
         this.packageGraph = packageGraph;
     }
 
+    /**
+     * Adds or increments a class edge and records the target dependency in the source class metrics.
+     *
+     * @param fromClass the fully qualified source class name
+     * @param toClass the fully qualified target class name
+     */
     @Override
     public void addClassDependency(String fromClass, String toClass) {
         VertexInfo fromVertex = VertexInfo.forName(fromClass);
@@ -61,6 +73,13 @@ public void addClassDependency(String fromClass, String toClass) {
         getOrCreateClassMetrics(fromClass).addDependency(toClass);
     }
 
+    /**
+     * Adds or increments a dependency between the supplied package names.
+     *
+     * @param fromPackage the source package name
+     * @param toPackage the target package name
+     * @return the newly created or existing package edge
+     */
     @Override
     public DefaultWeightedEdge addPackageDependency(String fromPackage, String toPackage) {
         VertexInfo fromPackageVertex = VertexInfo.forName(fromPackage);
@@ -91,6 +110,11 @@ public void recordClassLocation(String classFqn, String sourceFilePath) {
         classToSourceFileMapping.put(classFqn, sourceFilePath);
     }
 
+    /**
+     * Ensures a package vertex exists even when no dependency edge has been recorded for it.
+     *
+     * @param packageName the package to register
+     */
     @Override
     public void registerPackage(String packageName) {
         VertexInfo packageVertex = VertexInfo.forName(packageName);
@@ -99,11 +123,21 @@ public void registerPackage(String packageName) {
         }
     }
 
+    /**
+     * Ensures a class vertex exists independently of its dependency edges.
+     *
+     * @param classFqn the fully qualified class name
+     */
     @Override
     public void registerClassVertex(String classFqn) {
         classGraph.addVertex(VertexInfo.forName(classFqn));
     }
 
+    /**
+     * Returns the names of all vertices currently present in the package graph.
+     *
+     * @return a set of package names
+     */
     public Set<String> getPackagesInCodebase() {
         return packageGraph.vertexSet().stream().map(VertexInfo::getName).collect(java.util.stream.Collectors.toSet());
     }

codebase-graph-builder/src/test/java/org/hjug/graphbuilder/CompositeGraphBuilderJavaOnlyTest.java

@@ -83,6 +83,7 @@ void analyzeKotlinSwitchHasBeenRemoved() {
                                 Arrays.stream(methods).map(Method::getName).toArray()));
     }
 
+    /** Verifies that the default configuration includes Kotlin declarations and their source mappings. */
     @DisplayName("Default config parses Kotlin sources unconditionally (.kt entries appear)")
     @Test
     void defaultConfigParsesKotlinSources() throws IOException {

codebase-graph-builder/src/test/java/org/hjug/graphbuilder/CompositeGraphBuilderTest.java

@@ -15,6 +15,7 @@
  */
 class CompositeGraphBuilderTest {
 
+    /** Verifies that a mixed source directory produces one graph containing Java and Kotlin dependencies. */
     @DisplayName("A directory with both Java and Kotlin source files produces a single graph with cross-language edges")
     @Test
     void parseMixedSourceDirectoryTest() throws IOException {
@@ -52,6 +53,7 @@ void parseMixedSourceDirectoryTest() throws IOException {
                 VertexInfo.forName("com.ideacrest.parser.mixedclasses.SharedTarget")));
     }
 
+    /** Verifies that cross-package Java references resolve to canonical Kotlin vertices and package edges. */
     @DisplayName("Cross-package Java-to-Kotlin reference is reconciled to the canonical Kotlin FQN")
     @Test
     void parseMixedSourceDirectoryCrossPackageTest() throws IOException {