pr cleanup

plugins/codemodder-plugin-appscan/src/main/java/io/codemodder/providers/sarif/appscan/AppScanProvider.java

@@ -8,7 +8,7 @@
 import java.util.List;
 import java.util.Set;
 
-/** Provides codemods that act on AppSCan results. */
+/** Provides codemods that act on AppScan results. */
 public final class AppScanProvider implements CodemodProvider {
 
   @Override

plugins/codemodder-plugin-appscan/src/main/java/io/codemodder/providers/sarif/appscan/AppScanRuleSarif.java

@@ -21,11 +21,11 @@ final class AppScanRuleSarif implements RuleSarif {
   private final Path repositoryRoot;
   private final List<String> locations;
 
-  /** A map of a HCL SARIF "location" URIs mapped to their respective file paths. */
+  /** A map of a AppScan SARIF "location" URIs mapped to their respective file paths. */
   private final Map<Path, Set<Integer>> artifactLocationIndices;
 
   /**
-   * Creates an {@link AppScanRuleSarif} that has already done the work of mapping HCL SARIF
+   * Creates an {@link AppScanRuleSarif} that has already done the work of mapping AppScan SARIF
    * locations, which are strange combinations of class name and file path, into predictable paths.
    */
   public AppScanRuleSarif(
@@ -38,9 +38,9 @@ public AppScanRuleSarif(
         sarif.getRuns().get(0).getArtifacts().stream()
             .map(Artifact::getLocation)
             .map(ArtifactLocation::getUri)
-            .map(u -> u.substring(8))
+            .map(u -> u.substring(8)) // trim the file:/// of all results
             .toList();
-    Map<Path, Set<Integer>> artifactLocationIndices = new HashMap<>();
+    Map<Path, Set<Integer>> artifactLocationIndicesMap = new HashMap<>();
 
     for (int i = 0; i < locations.size(); i++) {
       final Integer index = i;
@@ -56,9 +56,9 @@ public AppScanRuleSarif(
 
       // add to the map if we found a matching file
       existingRealPath.ifPresent(
-          p -> artifactLocationIndices.computeIfAbsent(p, k -> new HashSet<>()).add(index));
+          p -> artifactLocationIndicesMap.computeIfAbsent(p, k -> new HashSet<>()).add(index));
     }
-    this.artifactLocationIndices = Map.copyOf(artifactLocationIndices);
+    this.artifactLocationIndices = Map.copyOf(artifactLocationIndicesMap);
   }
 
   private Optional<Path> findFileWithTrailingPath(final String path) throws IOException {
@@ -88,8 +88,8 @@ public List<Region> getRegionsFromResultsByRule(final Path path) {
   }
 
   /**
-   * This call receives an actual source file path, whereas the HCL results store a reference to a
-   * fully qualified class name plus ".java", e.g.:
+   * This call receives an actual source file path, whereas the AppScan results store a reference to
+   * a fully qualified class name plus ".java", e.g.:
    *
    * <pre>file:///org/owasp/webgoat/lessons/challenges/challenge5/Assignment5.java</pre>
    */
@@ -116,20 +116,29 @@ public List<Result> getResultsByLocationPath(final Path path) {
                 .toList());
   }
 
+  @Override
+  public String getDriver() {
+    return toolName;
+  }
+
+  /**
+   * This returns the raw SARIF. This SARIF, for Java, contains binary analysis results. These
+   * results may need a lot of massaging to act on.
+   */
   @Override
   public SarifSchema210 rawDocument() {
     return sarif;
   }
 
+  /**
+   * This returns the "ruleId" element, which has a value like "SA2813462719". The "message[text]"
+   * field has a more human-readable value like "SQL Injection". To stay aligned with other tools
+   * that use a more strict ID, we use the rule ID.
+   */
   @Override
   public String getRule() {
     return ruleId;
   }
 
-  @Override
-  public String getDriver() {
-    return toolName;
-  }
-
   static final String toolName = "HCL AppScan Static Analyzer";
 }

plugins/codemodder-plugin-appscan/src/test/java/io/codemodder/providers/sarif/appscan/AppScanRuleSarifFactoryTest.java

@@ -51,7 +51,7 @@ void it_parses_sarif_and_maps_java_locations(@TempDir final Path tmpDir) throws
     assertThat(ruleSarif.getDriver()).isEqualTo("HCL AppScan Static Analyzer");
     assertThat(ruleSarif.rawDocument()).isEqualTo(rawSarif);
 
-    // get the results for the file path (not the weird HCL thing) and confirm we have the right
+    // get the results for the file path (not the weird AppScan thing) and confirm we have the right
     // results
     List<Result> resultsForPath =
         ruleSarif.getResultsByLocationPath(actualAssignmentedJavaFilePath);