[#1715] Add RepoSense CLI Wizard Walkthrough

build.gradle

@@ -96,6 +96,7 @@ run {
     tasks.compileJava.mustRunAfter(zipReport)
     args System.getProperty('args', '').split()
     systemProperty "version", getRepoSenseVersion()
+    standardInput = System.in
 }
 
 checkstyle {

docs/_markbind/layouts/ug-sitenav.md

@@ -8,6 +8,7 @@
   {level: 2, name: "CLI syntax reference", link: "ug/cli.html"},
   {level: 2, name: "Config files format", link: "ug/configFiles.html"},
   {level: 2, name: "Using `@@author` tags", link: "ug/usingAuthorTags.html"},
+  {level: 2, name: "Using `--init` flag", link: "ug/usingInit.html"},
   {level: 2, name: "RepoSense with Netlify", link: "ug/withNetlify.html"},
   {level: 2, name: "RepoSense with GitHub Actions", link: "ug/withGithubActions.html"},
   {level: 2, name: "RepoSense with Travis", link: "ug/withTravis.html"},

docs/ug/cli.md

@@ -137,6 +137,20 @@ This flag overrides the `Ignore file size limit` field in the CSV config file.
 
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
+### `--init`
+
+**`--init`**: Launches the RepoSense CLI set-up wizard.
+* Example: `--init`
+
+<box type="info" seamless>
+
+* The wizard will run through the basic config flags in this order: `--since`, `--until`, `--view`, `--repos`.
+* This flag overrides all other flags and thus should be used on its own.
+* A guide of the steps performed by the wizard is located at [Appendix: Using --init flag](./usingInit.html).
+</box>
+
+<!-- ------------------------------------------------------------------------------------------------------ -->
+
 ### `--last-modified-date`, `-l`
 
 **`--last-modified-date`**: Specifies that the last modified date of each line of code should be added to `authorship.json`.
@@ -177,6 +191,8 @@ This flag overrides the `Ignore file size limit` field in the CSV config file.
 </box>
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
+<div id="section-repos">
+
 ### `--repo`, `--repos`, `-r`
 
 **`--repo REPO_LOCATION`**: Specifies which repositories to analyze.
@@ -190,6 +206,8 @@ This flag overrides the `Ignore file size limit` field in the CSV config file.
 
 Cannot be used with `--config`. This flag takes precedence over `--config`.
 </box>
+</div>
+
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
 ### `--shallow-cloning`, `-S`
@@ -206,6 +224,8 @@ Cannot be used with `--last-modified-date`. This may result in an incorrect last
 
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
+<div id="section-since">
+
 ### `--since`, `-s`
 
 **`--since START_DATE`**: Specifies the start date for the period to be analyzed.
@@ -220,6 +240,7 @@ Cannot be used with `--last-modified-date`. This may result in an incorrect last
 * If `d1` is specified as the start date (`--since d1` or `-s d1`), then the program will search for the earliest commit date of all repositories and use that as the start date.
 * If `d1` is specified together with `--period`, then the program will warn that the date range being analyzed may be incorrect.
 </box>
+</div>
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
 ### `--timezone`, `-t`
@@ -232,6 +253,8 @@ Cannot be used with `--last-modified-date`. This may result in an incorrect last
 
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
+<div id="section-until">
+
 ### `--until`, `-u`
 
 **`--until END_DATE`**: Specifies the end date of the analysis period.
@@ -244,6 +267,7 @@ Cannot be used with `--last-modified-date`. This may result in an incorrect last
 
 Note: If the end date is not specified, the date of generating the report will be taken as the end date.
 </box>
+</div>
 
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
@@ -258,10 +282,13 @@ Cannot be used with any other flags. This flag takes precedence over all other f
 </box>
 <!-- ------------------------------------------------------------------------------------------------------ -->
 
+<div id="section-view">
+
 ### `--view`, `-v`
 
 **`--view [REPORT_FOLDER]`**: Specifies that the report should be opened in the default browser.
 * Parameter: `REPORT_FOLDER` Optional. If specified, no analysis will be performed and the report specified by the argument will be opened.<br>
   Default: `./reposense-report`
 * Alias: `-v`
 * Example:`--view` or `-v`
+</div>

docs/ug/generatingReports.md

@@ -26,6 +26,8 @@ For other types of repositories, external links are disabled.
 
 <!-- ==================================================================================================== -->
 
+<div id="section-generating-reports-locally">
+
 ## Generating reports locally
 
 1. **Ensure you have the prerequisites**:
@@ -44,6 +46,12 @@ For other types of repositories, external links are disabled.
 
 **To learn how to generate a report using <tooltip content="e.g., generate a report for a different period, for specific file types, for specific authors, etc.">other settings</tooltip>**, head over to the [_**Customizing reports**_](customizingReports.html) section.
 
+**Alternatively**, you may also use the RepoSense CLI set-up wizard, which will take you through a basic configuration of RepoSense through the following command:
+  * `java -jar RepoSense.jar --init`
+
+A guide to explaining each step of the set-up wizard can also be found at [Appendix: Using --init flag](./usingInit.html), if you would like to follow along to better understand how to use RepoSense in the future.
+</div>
+
 <!-- ==================================================================================================== -->
 
 ## Generating reports remotely

docs/ug/usingInit.md

@@ -0,0 +1,74 @@
+{% set title = "Appendix: Using `--init` flag" %}
+<frontmatter>
+  title: "{{ title | safe }}"
+</frontmatter>
+
+{% from 'scripts/macros.njk' import embed, step with context %}
+
+<h1 class="display-4"><md>{{ title }}</md></h1>
+
+<div class="lead">
+
+The `--init` flag makes it easier for new users to get into using RepoSense, by guiding them step-by-step through a wizard with the most essential flags.
+</div>
+
+This guide serves to assist new users in understanding what the `--init` flag is doing, and eventually helps them understand how to use RepoSense without the `init` flag.
+
+If you have yet to do so, download the latest JAR file from our releases. The instructions are given below. You may ignore Step 3, as the `init` flag supersedes it.
+
+{{ embed("**Generating reports → Generating reports locally**", "generatingReports.md#section-generating-reports-locally") }}
+
+### Explanation of each step
+
+#### List of repository locations to be analyzed: `--repos`
+
+Upon using `java -jar RepoSense.java --init`, the wizard will ask for a list of repository locations, separated by spaces.
+
+This list of repository locations is necessary, as it will be the repositories analyzed by RepoSense at the end of the wizard.
+
+RepoSense accepts both remote Git repository HTTPS links, as well as paths to local Git repositories.
+
+Given below is the actual CLI flag being used. These embedded subsections will be given throughout this guide to help you pinpoint and locate it in your future references.
+
+{{ embed("**CLI syntax reference → `--repos`**", "cli.md#section-repos") }}
+
+<br>
+
+#### Start date of the analysis: `--since`
+
+The wizard will ask for the start date of the period of the analysis next.
+
+The start date, by default, will be one month before the current date. It is hence not necessary to include when you are using the CLI to run RepoSense, but it is likely that you will want to analyze a period with a different starting date.
+
+Given below is the actual CLI flag being used.
+
+{{ embed("**CLI syntax reference → `--since`**", "cli.md#section-since") }}
+
+#### Start date of the analysis: `--until`
+
+The wizard will ask for the until date of the period of the analysis next.
+
+The until date, by default, will be the current date. Again, it is not necessary to include when you are using the CLI to run RepoSense.
+
+Given below is the actual CLI flag being used.
+
+{{ embed("**CLI syntax reference → `--until`**", "cli.md#section-until") }}
+
+#### Viewing the report locally: `--view`
+
+The wizard will ask if you want to start a local server to view the report immediately after the report is generated. By indicating `Y`, a server will be started on your computer on port 9000, where the report can be viewed at http://localhost:9000/.
+
+This flag is used without any arguments in this basic wizard.
+
+Given below is the actual CLI flag being used.
+
+{{ embed("**CLI syntax reference → `--view`**", "cli.md#section-view") }}
+
+<br>
+
+### Conclusion
+
+At this stage, the `--init` wizard would have completed, and the generation of the RepoSense report is underway. It may take a few seconds to a few minutes, depending on the number of repositories entered, as well as your network speed.
+
+After the report generates, you may want to proceed to [Using reports](usingReports.html) in order to better understand the interface and how you can use the report generated by RepoSense. You may also want to take a closer look at the other config flags provided by RepoSense at [CLI syntax reference](cli.html) to understand what other features are available.
+

src/main/java/reposense/RepoSense.java

@@ -7,6 +7,7 @@
 import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Scanner;
 import java.util.logging.Level;
 import java.util.logging.LogManager;
 import java.util.logging.Logger;
@@ -23,6 +24,7 @@
 import reposense.model.RepoLocation;
 import reposense.model.ReportConfiguration;
 import reposense.model.ViewCliArguments;
+import reposense.model.WizardCliArguments;
 import reposense.parser.ArgsParser;
 import reposense.parser.AuthorConfigCsvParser;
 import reposense.parser.GroupConfigCsvParser;
@@ -36,6 +38,8 @@
 import reposense.system.ReportServer;
 import reposense.util.FileUtil;
 import reposense.util.TimeUtil;
+import reposense.wizard.BasicWizard;
+import reposense.wizard.WizardRunner;
 
 /**
  * The main RepoSense class.
@@ -68,6 +72,11 @@
                 reportConfig = ((ConfigCliArguments) cliArguments).getReportConfiguration();
             } else if (cliArguments instanceof LocationsCliArguments) {
                 configs = getRepoConfigurations((LocationsCliArguments) cliArguments);
+            } else if (cliArguments instanceof WizardCliArguments) {
+                WizardRunner wizardRunner = new WizardRunner(new BasicWizard());
+                wizardRunner.buildInput(new Scanner(System.in));
+                wizardRunner.run();
+                return;
             } else {
                 throw new AssertionError("CliArguments's subclass type is unhandled.");
             }

src/main/java/reposense/model/WizardCliArguments.java

@@ -0,0 +1,7 @@
+package reposense.model;
+
+/**
+ * Represents command line arguments user supplied when running the program with mandatory field -init.
+ */
+public class WizardCliArguments extends CliArguments {
+}

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

@@ -31,6 +31,7 @@
 import reposense.model.LocationsCliArguments;
 import reposense.model.ReportConfiguration;
 import reposense.model.ViewCliArguments;
+import reposense.model.WizardCliArguments;
 import reposense.system.LogsManager;
 import reposense.util.TimeUtil;
 
@@ -65,6 +66,8 @@
     public static final String[] CLONING_THREADS_FLAG = new String[] {"--cloning-threads"};
     public static final String[] ANALYSIS_THREADS_FLAG = new String[] {"--analysis-threads"};
 
+    public static final String[] CLI_WIZARD_FLAGS = new String[] {"--init"};
+
     public static final String[] TEST_MODE_FLAG = new String[] {"--test-mode"};
     public static final String[] FRESH_CLONING_FLAG = new String[] {"--fresh-cloning"};
 
@@ -239,6 +242,11 @@
                 .setDefault(DEFAULT_NUM_ANALYSIS_THREADS)
                 .help(FeatureControl.SUPPRESS);
 
+        parser.addArgument(CLI_WIZARD_FLAGS)
+                .dest(CLI_WIZARD_FLAGS[0])
+                .action(Arguments.storeTrue())
+                .help("Launches the RepoSense Command line wizard to walk through the basic setup.");
+
         // Testing flags
         argumentGroup.addArgument(TEST_MODE_FLAG)
                 .dest(TEST_MODE_FLAG[0])
@@ -283,6 +291,11 @@
             boolean shouldIncludeLastModifiedDate = results.get(LAST_MODIFIED_DATE_FLAGS[0]);
             boolean shouldPerformShallowCloning = results.get(SHALLOW_CLONING_FLAGS[0]);
             boolean shouldFindPreviousAuthors = results.get(FIND_PREVIOUS_AUTHORS_FLAGS[0]);
+            boolean isWizardCli = results.get(CLI_WIZARD_FLAGS[0]);
+
+            if (isWizardCli) {
+                return new WizardCliArguments();
+            }
 
             // Report config is ignored if --repos is provided
             if (locations == null) {

src/main/java/reposense/wizard/BasicWizard.java

@@ -0,0 +1,22 @@
+package reposense.wizard;
+
+import reposense.wizard.prompt.OptionalSincePrompt;
+import reposense.wizard.prompt.OptionalUntilPrompt;
+import reposense.wizard.prompt.Prompt;
+import reposense.wizard.prompt.RepoPrompt;
+import reposense.wizard.prompt.ViewPrompt;
+
+/**
+ * Represents a basic wizard run.
+ */
+public class BasicWizard extends Wizard {
+    private static final Prompt[] INITIAL_PROMPTS = new Prompt[] {
+            new RepoPrompt(),
+            new OptionalSincePrompt(),
+            new OptionalUntilPrompt(),
+            new ViewPrompt()
+    };
+    public BasicWizard() {
+        super(INITIAL_PROMPTS);
+    }
+}