Add Javadocs for graph builders, Java 25 fixtures, and HTML report helpers; remove stale parser configuration documentation

Author: coderabbitai[bot]

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

@@ -21,6 +21,7 @@
  */
 public final class Java25ParserFactory {
 
+    /** Prevents instantiation of this utility class. */
     private Java25ParserFactory() {
         // Utility class
     }

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

@@ -39,6 +39,7 @@
 @Slf4j
 public class JavaSourceFileGraphBuilder implements SourceFileGraphBuilder {
 
+    /** Builds dependency graphs and metrics from the Java files under the supplied repository path. */
     @Override
     public CodebaseGraphDTO buildGraph(String repositoryPath, String repositoryRoot, GraphBuilderConfig config)
             throws IOException {
@@ -102,11 +103,6 @@ public CodebaseGraphDTO buildGraph(String repositoryPath, String repositoryRoot,
      * the Java 25 parser on its own whenever the runtime is 25+ and
      * {@code rewrite-java-25} is on the classpath.
      *
-     * <p>The {@code config} parameter is retained for API stability but no
-     * longer influences parser selection (the former force-flag escape hatch
-     * was removed together with the reflection-based loading; parser selection
-     * is now entirely runtime-driven).
-     *
      * <p>Note: JEP 238 shadowing applies only to classes loaded from a jar.
      * In exploded-directory classpaths (e.g. unit tests against
      * {@code target/classes}) the base factory variant answers even on
@@ -120,6 +116,7 @@ static JavaParser createJavaParser() {
         });
     }
 
+    /** Finalizes collected metrics and assembles the Java codebase graph result. */
     static CodebaseGraphDTO finalizeDto(
             Graph<String, DefaultWeightedEdge> classReferencesGraph,
             Graph<String, DefaultWeightedEdge> packageReferencesGraph,
@@ -153,6 +150,7 @@ static CodebaseGraphDTO finalizeDto(
                 getMethodDisharmonies(detector, metrics));
     }
 
+    /** Removes graph vertices whose packages were not discovered in the analyzed codebase. */
     static void removeClassesNotInCodebase(
             Set<String> packagesInCodebase, Graph<String, DefaultWeightedEdge> classReferencesGraph) {
         Set<String> classesToRemove = new HashSet<>();
@@ -164,6 +162,7 @@ static void removeClassesNotInCodebase(
         classReferencesGraph.removeAllVertices(classesToRemove);
     }
 
+    /** Removes package vertices that were not discovered in the analyzed codebase. */
     static void removePackagesNotInCodebase(
             Set<String> packagesInCodebase, Graph<String, DefaultWeightedEdge> packageReferencesGraph) {
         Set<String> packagesToRemove = new HashSet<>();
@@ -175,6 +174,7 @@ static void removePackagesNotInCodebase(
         packageReferencesGraph.removeAllVertices(packagesToRemove);
     }
 
+    /** Returns the package portion of a fully qualified class name. */
     static String getPackage(String fqn) {
         if (!fqn.contains(".")) {
             return "";
@@ -183,6 +183,7 @@ static String getPackage(String fqn) {
         return fqn.substring(0, lastIndex);
     }
 
+    /** Collects all method-level disharmonies detected for the supplied metrics. */
     private static List<MethodDisharmony> getMethodDisharmonies(
             DisharmonyDetector detector, Collection<ClassMetrics> metrics) {
         List<MethodDisharmony> methodDisharmonies = new ArrayList<>();
@@ -194,6 +195,7 @@ private static List<MethodDisharmony> getMethodDisharmonies(
         return methodDisharmonies;
     }
 
+    /** Collects class-level disharmonies, including Kotlin-specific findings when applicable. */
     static List<ClassDisharmony> getClassDisharmonies(
             DisharmonyDetector detector, Collection<ClassMetrics> metrics, boolean hasKotlinMetrics) {
         List<ClassDisharmony> classDisharmonies = new ArrayList<>();

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

@@ -22,6 +22,7 @@ public final class Java25ParserFactory {
     // annotation processing so the extra compile execution stays minimal.
     private static final Logger log = LoggerFactory.getLogger(Java25ParserFactory.class);
 
+    /** Prevents instantiation of this utility class. */
     private Java25ParserFactory() {
         // Utility class
     }

codebase-graph-builder/src/test/resources/java25SrcDirectory/com/example/java25/FlexibleConstructorBody.java

@@ -9,6 +9,11 @@ public class FlexibleConstructorBody {
 
     private final int value;
 
+    /**
+     * Creates an instance after validating the constructor argument before delegation.
+     *
+     * @param raw the non-negative value to retain
+     */
     public FlexibleConstructorBody(int raw) {
         if (raw < 0) {
             throw new IllegalArgumentException("value must not be negative");
@@ -18,6 +23,7 @@ public FlexibleConstructorBody(int raw) {
         this.value = raw;
     }
 
+    /** Returns the value supplied at construction time. */
     public int getValue() {
         return value;
     }

report/src/main/java/org/hjug/refactorfirst/report/SimpleHtmlReport.java

@@ -419,12 +419,14 @@ public StringBuilder generateReport(
         return stringBuilder;
     }
 
+    /** Reads the repository's remote URL from the project Git metadata. */
     static String getRepoUrl(String projectBaseDir) throws Exception {
         try (GitLogReader glr = new GitLogReader(new File(projectBaseDir))) {
             return glr.getRepoUrl();
         }
     }
 
+    /** Builds the report navigation menu for the available graphs, findings, and cycles. */
     StringBuilder createMenu(
             List<DisharmonySpec> disharmonySpecs,
             Map<String, List<RankedDisharmony>> rankedDisharmoniesByAnchor,
@@ -478,10 +480,13 @@ StringBuilder createMenu(
         return menu;
     }
 
+    /** Extension hook for adding a class-map entry to the navigation menu. */
     void renderClassMapMenu(StringBuilder stringBuilder) {}
 
+    /** Extension hook for adding a package-map entry to the navigation menu. */
     void renderPackageMapMenu(StringBuilder stringBuilder) {}
 
+    /** Renders the class-cycle summary and the largest cycle's details. */
     private String renderCycles(List<RankedCycle> rankedCycles, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         StringBuilder stringBuilder = new StringBuilder();
         stringBuilder.append(renderClassCycleSummary(rankedCycles));
@@ -494,6 +499,7 @@ private String renderCycles(List<RankedCycle> rankedCycles, String repoUrl, Code
         return stringBuilder.toString();
     }
 
+    /** Renders the prioritized class relationships whose removal breaks cycles. */
     private String renderClassEdgeDisharmonies(
             List<RankedDisharmony> classRelationshipDisharmonies,
             List<RankedDisharmony> packageRelationshipDisharmonies,
@@ -548,6 +554,7 @@ private String renderClassEdgeDisharmonies(
         return stringBuilder.toString();
     }
 
+    /** Renders the prioritized package relationships whose removal breaks cycles. */
     private String renderPackageEdgeDisharmonies(
             List<RankedDisharmony> edgeDisharmonies, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         StringBuilder stringBuilder = new StringBuilder();
@@ -599,6 +606,7 @@ private String renderPackageEdgeDisharmonies(
         return stringBuilder.toString();
     }
 
+    /** Returns column headings for the class-relationship table. */
     private String[] getClassRelationshipDisharmonyTableHeadings() {
         return new String[] {
             "Class Relationship",
@@ -610,6 +618,7 @@ private String[] getClassRelationshipDisharmonyTableHeadings() {
         };
     }
 
+    /** Returns column headings for the package-relationship table. */
     private String[] getPackageRelationshipDisharmonyTableHeadings() {
         return new String[] {
             "Package Relationship",
@@ -656,6 +665,7 @@ String[] getPackageRelationshipDisharmony(
         };
     }
 
+    /** Renders summary rows for the ranked class cycles. */
     private String renderClassCycleSummary(List<RankedCycle> rankedCycles) {
         StringBuilder stringBuilder = new StringBuilder();
 
@@ -704,6 +714,7 @@ String renderClassEdge(DefaultWeightedEdge edge) {
                 .toString();
     }
 
+    /** Renders a weighted class edge with repository links and removal markers. */
     private String renderClassEdge(DefaultWeightedEdge edge, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         StringBuilder edgesToCut = new StringBuilder();
         String[] vertexes = extractVertexes(edge);
@@ -730,6 +741,7 @@ private String renderClassEdge(DefaultWeightedEdge edge, String repoUrl, Codebas
                 .toString();
     }
 
+    /** Renders a weighted package edge with removal markers. */
     private String renderPackageEdge(DefaultWeightedEdge edge, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         StringBuilder edgesToCut = new StringBuilder();
         String[] vertexes = extractVertexes(edge);
@@ -756,6 +768,7 @@ private String renderPackageEdge(DefaultWeightedEdge edge, String repoUrl, Codeb
                 .toString();
     }
 
+    /** Links a class label to its source file when a source-path mapping is available. */
     String hyperlinkClass(String className, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         String path = codebaseGraphDTO.getClassToSourceFilePathMapping().get(className);
         if (path == null || path.isBlank()) {
@@ -783,6 +796,7 @@ static String escapeHtmlAttribute(String value) {
         return escapeHtmlLabel(value).replace("\"", "&quot;").replace("'", "&#39;");
     }
 
+    /** Returns column headings for the class-cycle summary table. */
     private String[] getClassCycleSummaryTableHeadings() {
         return new String[] {"Cycle Name", "Priority", "Class Count", "Relationship Count"};
     }
@@ -798,6 +812,7 @@ String[] getRankedCycleSummaryData(RankedCycle rankedCycle) {
         };
     }
 
+    /** Renders the visualization and relationship table for one class cycle. */
     private String renderSingleCycle(RankedCycle cycle, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         StringBuilder stringBuilder = new StringBuilder();
 
@@ -878,18 +893,22 @@ private String renderSingleCycle(RankedCycle cycle, String repoUrl, CodebaseGrap
         return stringBuilder.toString();
     }
 
+    /** Extension hook for rendering class-graph visuals. */
     public String renderClassGraphVisuals(String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         return ""; // empty on purpose
     }
 
+    /** Extension hook for rendering package-graph visuals. */
     public String renderPackageGraphVisuals(String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         return ""; // empty on purpose
     }
 
+    /** Extension hook for rendering a class-cycle visualization. */
     public String renderClassCycleVisuals(RankedCycle cycle, String repoUrl, CodebaseGraphDTO codebaseGraphDTO) {
         return ""; // empty on purpose
     }
 
+    /** Renders a table cell, right-aligning numeric and date-like values. */
     String drawTableCell(String rowData) {
         if (isNumber(rowData) || isDateTime(rowData)) {
             return "<td align=\"right\">" + rowData + "</td>\n";
@@ -898,30 +917,37 @@ String drawTableCell(String rowData) {
         }
     }
 
+    /** Reports whether a table value is a signed integer or decimal number. */
     boolean isNumber(String rowData) {
         return rowData.matches("-?\\d+(\\.\\d+)?");
     }
 
+    /** Reports whether a table value uses the localized date-time delimiter. */
     boolean isDateTime(String rowData) {
         return rowData.contains(", ");
     }
 
+    /** Extension hook for rendering the HTML title element. */
     public String printTitle(String projectName, String projectVersion) {
         return ""; // empty on purpose
     }
 
+    /** Extension hook for rendering additional HTML head content. */
     public String printHead() {
         return ""; // empty on purpose
     }
 
+    /** Extension hook for rendering script elements. */
     String printScripts() {
         return ""; // empty on purpose
     }
 
+    /** Returns the opening body tag used by the report page. */
     public String printOpenBodyTag() {
         return "  <body class=\"composite\">\n";
     }
 
+    /** Returns the opening banner and breadcrumb markup. */
     public String printBreadcrumbs() {
         return """
                     <div id="banner">
@@ -931,6 +957,7 @@ public String printBreadcrumbs() {
                 """;
     }
 
+    /** Renders the project heading with links to RefactorFirst and the analyzed repository. */
     public String printProjectHeader(String projectName, String projectVersion, String projectBaseDir)
             throws Exception {
         String repoUrl = getRepoUrl(projectBaseDir);
@@ -945,6 +972,7 @@ public String printProjectHeader(String projectName, String projectVersion, Stri
                 + projectVersion + "</a></h1>\n";
     }
 
+    /** Renders the report footer with the current publication timestamp. */
     public String printProjectFooter() {
         return "      <div class=\"clear\">\n" + "        <hr/>\n" + "      </div>\n"
                 + "<span id=\"publishDate\">Last Published: "
@@ -953,6 +981,7 @@ public String printProjectFooter() {
                 + "        <hr/>\n" + "      </div>\n" + "</span>";
     }
 
+    /** Renders links for common RefactorFirst GitHub actions. */
     String renderGithubButtons() {
         return """
                 <div align="center">
@@ -965,6 +994,7 @@ String renderGithubButtons() {
                 </div>""";
     }
 
+    /** Returns the base filename for the generated report. */
     String getOutputName() {
         // This report will generate simple-report.html when invoked in a project with `mvn site`
         return "refactor-first-report";
@@ -1099,6 +1129,7 @@ public String renderDisharmonyInfo(
         return sb.toString();
     }
 
+    /** Removes package qualifiers and verbose generic bounds from a method signature. */
     String getSimpleMethodSignature(String sig) {
         if (sig == null) {
             return null;
@@ -1149,6 +1180,7 @@ String getSimpleMethodSignature(String sig) {
     // upWaitQueue(com.tonikelope.megabasterd.Transference) ↔
     // TransferenceManager.downWaitQueue(com.tonikelope.megabasterd.Transference)
     // should become upWaitQueue(Transference) ↔ TransferenceManager.downWaitQueue(Transference)
+    /** Simplifies fully qualified parameter types in a duplication-partner description. */
     String simplifyDuplicatePartners(String duplicationPartners) {
         if (duplicationPartners == null) {
             return null;
@@ -1175,10 +1207,12 @@ String simplifyDuplicatePartners(String duplicationPartners) {
         return String.join(" ↔ ", simplifiedParts);
     }
 
+    /** Extension hook for rendering a chart for one disharmony category. */
     String renderDisharmonyChart(String anchorId, String title, List<RankedDisharmony> ranked, int maxPriority) {
         return ""; // empty on purpose; overridden in HtmlReport
     }
 
+    /** Returns the simple class name from a fully qualified class name. */
     String getClassName(String fqn) {
         // handle no package
         if (!fqn.contains(".")) {
@@ -1189,6 +1223,7 @@ String getClassName(String fqn) {
         return fqn.substring(lastIndex + 1);
     }
 
+    /** Extracts the source and target vertex labels from an edge's string representation. */
     static String[] extractVertexes(DefaultWeightedEdge edge) {
         return edge.toString().replace("(", "").replace(")", "").split(":");
     }
@@ -1201,6 +1236,7 @@ static final class DisharmonySpec {
         final String problem;
         final String solution;
 
+        /** Creates the display metadata for one supported disharmony category. */
         DisharmonySpec(
                 String type, String anchorId, String title, boolean methodLevel, String problem, String solution) {
             this.type = type;
@@ -1211,26 +1247,32 @@ static final class DisharmonySpec {
             this.solution = solution;
         }
 
+        /** Returns the disharmony type identifier. */
         String type() {
             return type;
         }
 
+        /** Returns the HTML anchor identifier. */
         String anchorId() {
             return anchorId;
         }
 
+        /** Returns the display title. */
         String title() {
             return title;
         }
 
+        /** Reports whether the disharmony describes methods rather than classes. */
         boolean methodLevel() {
             return methodLevel;
         }
 
+        /** Returns the problem description. */
         String problem() {
             return problem;
         }
 
+        /** Returns the recommended remediation. */
         String solution() {
             return solution;
         }