Document PageRank tie-breaking and package relationship test helpers with Javadoc

Author: coderabbitai[bot]

graph-algorithms/src/main/java/org/hjug/feedback/arc/pageRank/PageRankFAS.java

@@ -137,6 +137,7 @@ private E selectHighestScoredEdge(Map<LineVertex<V, E>, Double> pageRankScores)
         return best != null ? best.getOriginalEdge() : null;
     }
 
+    /** Returns whether the candidate precedes the incumbent in canonical source/target order. */
     private boolean isCanonicallyBefore(LineVertex<V, E> candidate, LineVertex<V, E> incumbent) {
         return lineVertexOrder().compare(candidate, incumbent) < 0;
     }

graph-algorithms/src/test/java/org/hjug/feedback/arc/pageRank/PageRankFASDeterminismTest.java

@@ -43,6 +43,7 @@ private Graph<String, DefaultEdge> createFeedbackPackageScc() {
         return graph;
     }
 
+    /** Copies the graph topology with fresh edges so each run can remove edges independently. */
     private Graph<String, DefaultEdge> copyGraph(Graph<String, DefaultEdge> original) {
         Graph<String, DefaultEdge> copy = new DefaultDirectedGraph<>(DefaultEdge.class);
         original.vertexSet().forEach(copy::addVertex);
@@ -52,6 +53,7 @@ private Graph<String, DefaultEdge> copyGraph(Graph<String, DefaultEdge> original
         return copy;
     }
 
+    /** Converts edges to sorted source/target keys for comparison across graph copies. */
     private Set<String> edgeKeys(Graph<String, DefaultEdge> graph, Set<DefaultEdge> edges) {
         Set<String> keys = new TreeSet<>();
         for (DefaultEdge edge : edges) {
@@ -60,6 +62,7 @@ private Set<String> edgeKeys(Graph<String, DefaultEdge> graph, Set<DefaultEdge>
         return keys;
     }
 
+    /** Verifies repeated runs select the same edges and break both cycles in the package SCC. */
     @DisplayName("computeFeedbackArcSet selects the same edges on every run for the feedback package SCC")
     @Test
     void computeFeedbackArcSet_isDeterministicAcrossRuns() {
@@ -94,6 +97,7 @@ void computeFeedbackArcSet_isDeterministicAcrossRuns() {
                 "Removing the feedback arc set must leave the graph acyclic");
     }
 
+    /** Verifies repeatable feedback arc selection and cycle removal in a larger symmetric graph. */
     @DisplayName("computeFeedbackArcSet is deterministic for a graph with parallel tie candidates")
     @Test
     void computeFeedbackArcSet_isDeterministicForLargerTiedGraph() {
@@ -134,6 +138,7 @@ void computeFeedbackArcSet_isDeterministicForLargerTiedGraph() {
                 "Removing the feedback arc set must leave the graph acyclic");
     }
 
+    /** Verifies edge insertion order does not change feedback arc selection for overlapping cycles. */
     @DisplayName("computeFeedbackArcSet is independent of the order edges were added to the graph")
     @Test
     void computeFeedbackArcSet_isDeterministicAcrossEdgeInsertionOrders() {

report/src/test/java/org/hjug/refactorfirst/report/PackageRelationshipClassEdgeCycleCountTest.java

@@ -51,12 +51,14 @@ private Graph<String, DefaultWeightedEdge> createClassGraph() {
         return classGraph;
     }
 
+    /** Creates a DTO mock with no source paths so relationships render without file links. */
     private CodebaseGraphDTO mockDto() {
         CodebaseGraphDTO dto = Mockito.mock(CodebaseGraphDTO.class);
         Mockito.when(dto.getClassToSourceFilePathMapping()).thenReturn(new HashMap<>());
         return dto;
     }
 
+    /** Verifies nested relationships count detected class cycles even outside the feedback arc set. */
     @DisplayName("nested class relationships report their real class-cycle membership, not a defaulted zero")
     @Test
     void buildClassRelationshipsToBreakPackage_reportsActualCycleMembership() throws Exception {

report/src/test/java/org/hjug/refactorfirst/report/PackageRelationshipClassEdgeOrderTest.java

@@ -69,12 +69,14 @@ private Set<DefaultWeightedEdge> newSetInOrder(Collection<DefaultWeightedEdge> e
         return new HashSet<>(rotated);
     }
 
+    /** Injects a graph fixture into a field declared by the shared HTML report base class. */
     private void setField(Object target, String fieldName, Object value) throws Exception {
         Field field = SimpleHtmlReport.class.getDeclaredField(fieldName);
         field.setAccessible(true);
         field.set(target, value);
     }
 
+    /** Maps the package edge to its class edges in a DTO mock with no source file paths. */
     private CodebaseGraphDTO mockDto(DefaultWeightedEdge packageEdge, Set<DefaultWeightedEdge> classEdges) {
         CodebaseGraphDTO dto = Mockito.mock(CodebaseGraphDTO.class);
         Map<DefaultWeightedEdge, Set<DefaultWeightedEdge>> relationships = new HashMap<>();
@@ -84,6 +86,7 @@ private CodebaseGraphDTO mockDto(DefaultWeightedEdge packageEdge, Set<DefaultWei
         return dto;
     }
 
+    /** Creates a ranked package-edge fixture with priority, cycle count and effort rank set to one. */
     private RankedDisharmony mockRankedDisharmony(DefaultWeightedEdge packageEdge) {
         RankedDisharmony edgeInfo = Mockito.mock(RankedDisharmony.class);
         Mockito.when(edgeInfo.getEdge()).thenReturn(packageEdge);
@@ -113,6 +116,7 @@ private List<ClassRelationshipDTO> buildJsonList(JsonGenerator generator, Codeba
                 dto.getClassRelationshipsInPackageRelationship().get(packageEdge), REPO_URL, dto);
     }
 
+    /** Verifies HTML and JSON use the same source/target order across class-edge set insertions. */
     @DisplayName(
             "class relationships behind a package edge render in the same deterministic order regardless of set insertion order")
     @Test
@@ -187,6 +191,7 @@ void classRelationshipsToBreakPackage_areOrderedDeterministically() throws Excep
                 "HTML class-relationship cell must list the same edges in the same order as the JSON report");
     }
 
+    /** Extracts the final name segment from a fully qualified class name for expected HTML labels. */
     private static String simpleName(String fqn) {
         return fqn.substring(fqn.lastIndexOf('.') + 1);
     }