[#2308] Add blurbs for charts (#2350)

Add support for chart blurbs

RepoSense currently only supports repository and author blurbs.
Adding chart blurbs allows developers to include more details in
the chart views.

Co-authored-by: CYX22222003 <e1155533@u.nus.edu>
Co-authored-by: CHEN YIXUN <138369841+CYX22222003@users.noreply.github.com>

Author: JoanneHing

config/chart-blurbs.md

@@ -0,0 +1,2 @@
+https://github.com/reposense/testrepo-Alpha/tree/master|nbriannl
+Test for chart-blurbs.md

docs/ug/chart-blurbs.md

@@ -0,0 +1,5 @@
+https://github.com/reposense/testrepo-Alpha/tree/master|author1
+I contributed to this repository by adding a new feature to the project.
+<!--chart-->------------------------------------
+https://github.com/reposense/testrepo-Beta/tree/master|author2
+I contributed to this repository by fixing a bug in the project.

docs/ug/configFiles.md

@@ -291,3 +291,14 @@ This file allows you to specify blurbs for authors. These blurbs will be display
 * Sample: [author-blurbs.md](https://github.com/reposense/RepoSense/blob/master/docs/ug/author-blurbs.md)
 </div>
 
+### `chart-blurbs.md`
+<div id="section-chart-blurbs">
+
+This file allow you to specify blurbs for specific charts. These blurbs will be displayed with the charts.
+
+**Format**:
+* First line in section: Link to the repository branch|Author's Git Host ID. (Note the `|` between repository's link and author's Git Host ID)
+* Second line onwards: Blurb content.
+* Delimiter: `<!--chart-->`. Everything on the line after the delimiter will be ignored.
+* Sample: [chart-blurbs.md](https://github.com/reposense/RepoSense/blob/master/docs/ug/chart-blurbs.md))
+</div>

docs/ug/customizingReports.md

@@ -109,7 +109,7 @@ Do note that the width of the title is bound by the width of the left panel.
 
 For more information on how to use Markdown, see the [Markdown Guide](https://www.markdownguide.org/).
 
-#### Add blurbs for branches or authors
+#### Add blurbs for branches, authors or charts
 A blurb can be added for a repository or author by creating the respective blurb markdown files in the config directory.
 - For a repository:
   - Create a file titled `repo-blurbs.md` in the config directory. The format of the file is given below:
@@ -119,6 +119,9 @@ A blurb can be added for a repository or author by creating the respective blurb
   - Create a file titled `author-blurbs.md` in the config directory. The format of the file is given below:
     {{ embed("Appendix: **Config files format**", "configFiles.md#section-author-blurbs") }}
   - The blurbs will be visible when grouping by `Author`.
+- For a chart:
+  - Create a file titled `chart-blurbs.md` in the config directory. The format of the file is given below:
+    {{ embed("Appendix: **Config files format**", "configFiles.md#section-chart-blurbs") }}
 
 Specifying the config directory can be done as follows:
 {{ embed("Appendix: **CLI syntax reference → `config` flag**", "cli.md#section-config") }}

docs/ug/reportConfig.md

@@ -9,7 +9,7 @@ pageNav: 3
 
 <h1 class="display-4"><md>{{ title }}</md></h1>
 
-RepoSense allows you to easily showcase your coding portfolio by generating visualization reports of your contributions across different repositories. 
+RepoSense allows you to easily showcase your coding portfolio by generating visualization reports of your contributions across different repositories.
 This guide will help you set up your first RepoSense report using the `report-config.yaml` file.
 
 ## What is `report-config.yaml`?

src/main/java/reposense/RepoSense.java

@@ -10,6 +10,7 @@
 import net.sourceforge.argparse4j.helper.HelpScreenException;
 import reposense.git.GitConfig;
 import reposense.model.AuthorBlurbMap;
+import reposense.model.ChartBlurbMap;
 import reposense.model.CliArguments;
 import reposense.model.RepoBlurbMap;
 import reposense.model.RepoConfiguration;
@@ -48,6 +49,7 @@ public static void main(String[] args) {
             ReportConfiguration reportConfig = new ReportConfiguration();
             RepoBlurbMap repoBlurbMap = new RepoBlurbMap();
             AuthorBlurbMap authorBlurbMap = new AuthorBlurbMap();
+            ChartBlurbMap chartBlurbMap = new ChartBlurbMap();
 
             if (cliArguments.isViewModeOnly()) {
                 ReportServer.startServer(SERVER_PORT_NUMBER, cliArguments.getReportDirectoryPath().toAbsolutePath());
@@ -58,6 +60,7 @@ public static void main(String[] args) {
             reportConfig = cliArguments.getReportConfiguration();
             repoBlurbMap = cliArguments.mergeWithReportConfigRepoBlurbMap();
             authorBlurbMap = cliArguments.getAuthorBlurbMap();
+            chartBlurbMap = cliArguments.getChartBlurbMap();
 
             RepoConfiguration.setFormatsToRepoConfigs(configs, cliArguments.getFormats());
             RepoConfiguration.setDatesToRepoConfigs(configs, cliArguments.getSinceDate(), cliArguments.getUntilDate());
@@ -80,7 +83,7 @@ public static void main(String[] args) {
 
             ReportGenerator reportGenerator = new ReportGenerator();
             List<Path> reportFoldersAndFiles = reportGenerator.generateReposReport(configs,
-                    cliArguments, reportConfig, repoBlurbMap, authorBlurbMap);
+                    cliArguments, reportConfig, repoBlurbMap, authorBlurbMap, chartBlurbMap);
 
             FileUtil.handleZipFilesAndFolders(reportFoldersAndFiles, cliArguments.getOutputFilePath().toAbsolutePath(),
                     cliArguments.isOnlyTextRefreshed(), ".json");

src/main/java/reposense/model/ChartBlurbMap.java

@@ -0,0 +1,11 @@
+package reposense.model;
+
+/**
+ * Represents the mapping between the charts to the associated blurb.
+ */
+public class ChartBlurbMap extends AbstractBlurbMap {
+
+    public ChartBlurbMap() {
+        super();
+    }
+}

src/main/java/reposense/model/CliArguments.java

@@ -55,6 +55,7 @@ public class CliArguments {
     private ReportConfiguration reportConfiguration;
     private RepoBlurbMap repoBlurbMap;
     private AuthorBlurbMap authorBlurbMap;
+    private ChartBlurbMap chartBlurbMap;
 
     /**
      * Constructs a {@code CliArguments} object without any parameters.
@@ -165,6 +166,10 @@ public AuthorBlurbMap getAuthorBlurbMap() {
         return authorBlurbMap;
     }
 
+    public ChartBlurbMap getChartBlurbMap() {
+        return chartBlurbMap;
+    }
+
     /**
      * Merges the {@code blurbMap} from the blurbs file with the blurb map in {@code reportConfiguration}.
      *
@@ -244,6 +249,7 @@ public boolean equals(Object other) {
                 && Objects.equals(this.reportConfigFilePath, otherCliArguments.reportConfigFilePath)
                 && Objects.equals(this.repoBlurbMap, otherCliArguments.repoBlurbMap)
                 && Objects.equals(this.authorBlurbMap, otherCliArguments.authorBlurbMap)
+                && Objects.equals(this.chartBlurbMap, otherCliArguments.chartBlurbMap)
                 && this.isAuthorshipAnalyzed == otherCliArguments.isAuthorshipAnalyzed
                 && Objects.equals(this.originalityThreshold, otherCliArguments.originalityThreshold)
                 && this.isPortfolio == otherCliArguments.isPortfolio
@@ -518,6 +524,14 @@ public Builder authorBlurbMap(AuthorBlurbMap authorBlurbMap) {
             return this;
         }
 
+        /**
+         * Adds the {@code chartBlurbMap} to CliArguments.
+         */
+        public Builder chartBlurbMap(ChartBlurbMap chartBlurbMap) {
+            this.cliArguments.chartBlurbMap = chartBlurbMap;
+            return this;
+        }
+
         /**
          * Adds the {@code isPortfolio} to CLIArguments.
          *

src/main/java/reposense/parser/ArgsParser.java

@@ -26,6 +26,7 @@
 import net.sourceforge.argparse4j.inf.Namespace;
 import reposense.RepoSense;
 import reposense.model.AuthorBlurbMap;
+import reposense.model.ChartBlurbMap;
 import reposense.model.CliArguments;
 import reposense.model.FileType;
 import reposense.model.RepoBlurbMap;
@@ -345,6 +346,7 @@ public static CliArguments parse(String[] args) throws HelpScreenException, Pars
         addReportConfigToBuilder(cliArgumentsBuilder, results);
         addRepoBlurbMapToBuilder(cliArgumentsBuilder, results);
         addAuthorBlurbMapToBuilder(cliArgumentsBuilder, results);
+        addChartBlurbMapToBuilder(cliArgumentsBuilder, results);
         addAnalysisDatesToBuilder(cliArgumentsBuilder, results);
 
         boolean isViewModeOnly = reportFolderPath != null
@@ -390,7 +392,7 @@ private static void addReportConfigToBuilder(CliArguments.Builder builder, Names
     }
 
     /**
-     * Adds the repoblurbMap field to the given {@code builder}.
+     * Adds the repoBlurbMap field to the given {@code builder}.
      *
      * @param builder Builder to be supplied with the reportConfig field.
      * @param results Parsed results of the user-supplied CLI arguments.
@@ -415,7 +417,7 @@ private static void addRepoBlurbMapToBuilder(CliArguments.Builder builder, Names
     }
 
     /**
-     * Adds the authorblurbMap field to the given {@code builder}.
+     * Adds the authorBlurbMap field to the given {@code builder}.
      *
      * @param builder Builder to be supplied with the reportConfig field.
      * @param results Parsed results of the user-supplied CLI arguments.
@@ -439,6 +441,31 @@ private static void addAuthorBlurbMapToBuilder(CliArguments.Builder builder, Nam
         builder.authorBlurbMap(authorBlurbMap);
     }
 
+    /**
+     * Adds the chartBlurbMap field to the given {@code builder}.
+     *
+     * @param builder Builder to be supplied with the reportConfig field.
+     * @param results Parsed results of the user-supplied CLI arguments.
+     */
+    private static void addChartBlurbMapToBuilder(CliArguments.Builder builder, Namespace results) {
+        ChartBlurbMap chartBlurbMap = new ChartBlurbMap();
+        Path configFolderPath = results.get(CONFIG_FLAGS[0]);
+
+        // Blurbs are parsed regardless
+        Path blurbConfigPath = configFolderPath.resolve(ChartBlurbMarkdownParser.DEFAULT_BLURB_FILENAME);
+
+        try {
+            chartBlurbMap = new ChartBlurbMarkdownParser(blurbConfigPath).parse();
+        } catch (InvalidMarkdownException ex) {
+            logger.warning(String.format(MESSAGE_INVALID_MARKDOWN_BLURBS, ex.getMessage()));
+        } catch (IOException ioe) {
+            // IOException thrown as blurbs.md is not found.
+            // Ignore exception as the file is optional.
+        }
+
+        builder.chartBlurbMap(chartBlurbMap);
+    }
+
     /**
      * Adds the sinceDate and untilDate fields for analysis to the given {@code builder}.
      *

src/main/java/reposense/parser/ChartBlurbMarkdownParser.java

@@ -0,0 +1,97 @@
+package reposense.parser;
+
+import java.io.FileNotFoundException;
+import java.net.MalformedURLException;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.regex.Pattern;
+
+import reposense.model.ChartBlurbMap;
+import reposense.parser.exceptions.InvalidMarkdownException;
+
+/**
+ * Parses the Markdown file and retrieves the mappings from (repoURL|authorGitId) to blurbs from the blurbs
+ * configuration file.
+ */
+public class ChartBlurbMarkdownParser extends BlurbMarkdownParser<ChartBlurbMap, String> {
+    public static final Pattern DELIMITER = Pattern.compile("<!--chart-->(.*)");
+    public static final String DEFAULT_BLURB_FILENAME = "chart-blurbs.md";
+
+    public ChartBlurbMarkdownParser(Path markdownPath) throws FileNotFoundException {
+        super(markdownPath, DELIMITER, DEFAULT_BLURB_FILENAME);
+    }
+
+    @Override
+    protected ChartBlurbMap createBlurbMap() {
+        return new ChartBlurbMap();
+    }
+
+    @Override
+    protected KeyRecord<String> extractKey(List<String> lines, int position) throws InvalidMarkdownException {
+        // Extract the key (repoURL|authorGitId)
+        String key = "";
+
+        while (key.length() == 0) {
+
+            if (position >= lines.size()) {
+                return null;
+            }
+
+            // Skip delimiter lines
+            if (DELIMITER.matcher(lines.get(position)).matches()) {
+                position++;
+                continue;
+            }
+
+            key = lines.get(position++).strip();
+        }
+
+        // Validate the key
+        if (!isValidKey(key)) {
+            throw new InvalidMarkdownException("Invalid key format: " + key);
+        }
+
+        return new KeyRecord<>(key, position);
+    }
+
+    /**
+     * Validates the key (repoURL|authorGitId) format.
+     * The repoURL should be a valid URL and the authorGitId should be present.
+     *
+     * @param key The key to validate.
+     * @return true if the key is valid, false otherwise.
+     * @throws InvalidMarkdownException if the key format is invalid.
+     */
+    private boolean isValidKey(String key) throws InvalidMarkdownException {
+        String[] parts = key.split("\\|");
+
+        // Check if the key has exactly 2 parts (repoURL and authorGitId)
+        if (parts.length != 2) {
+            return false;
+        }
+
+        String repoUrl = parts[0].strip();
+        String authorGitId = parts[1].strip();
+
+        // Check if the repoURL is a valid URL
+        if (repoUrl.isEmpty() || authorGitId.isEmpty()) {
+            return false;
+        }
+
+        // Validate the repoURL format
+        // Adapted from https://www.baeldung.com/java-validate-url
+        try {
+            new URL(repoUrl).toURI();
+            return true;
+        } catch (MalformedURLException | URISyntaxException e) {
+            return false;
+        }
+    }
+
+    @Override
+    protected void addRecord(ChartBlurbMap blurbMap, String key, String blurb) {
+        blurbMap.withRecord(key, blurb);
+    }
+}