[#1715] Add RepoSense CLI Wizard Walkthrough

[sikai00]

Fixes #1715 This PR is co-authored with @MarcusTXK.

Proposed commit message

For a new user trying to get into RepoSense, the command line arguments
may be hard and intimidating to navigate and takes some effort to 
reference from the user guide. If a new user wants to try out RepoSense
(instead of immediately putting it to actual use), he may be put off 
by the effort needed for entry.

Let's implement a RepoSense CLI wizard. This makes it easier for a 
new user to understand how a run of RepoSense may work, understand 
some of the flags we have, and eases the learning curve required 
to use RepoSense.

Co-authored-by: Marcus Tang <[email protected]>
Co-authored-by: Si Kai <[email protected]>

Other information

How to test

Pull from the PR branch and run reposense with the flag --init.

Overview of the wizard implementation

The wizard is implemented using a discrete event simulator (DES) style. This allows us to avoid long if-else conditions for the prompting logic, as each prompt can invoke another prompt simply by creating it and adding it into the queue.

└── wizard/
    ├── prompts/
    │   ├── Prompt.java
    │   ├── OptionalPrompt.java
    │   └── ...
    ├── WizardRunner.java
    ├── Wizard.java
    ├── BasicWizard.java
    └── InputBuilder.java

The WizardRunner.java acts as the simulator and takes in Wizard.java (implemented under BasicWizard.java, so as to allow for different future Wizards). WizardRunner.java maintains a Deque of Prompt, which is initially supplemented by a concrete implementation of Wizard.java.

Each Prompt.java may be used to add a config flag and its argument via InputBuilder.java by calling WizardRunner::buildInput(Scanner sc). At the end when no other prompts exist in the deque, the method ends. The complete input string is created when WizardRunner::getBuiltInput() and subsequently used when WizardRunner::run() is finally called. In a similar sense to that of the current systemtest, the string is directly passed into RepoSense::main to produce the expected output and behavior.

Each concrete implementation of Prompt.java can return even more prompts to the Deque, so a Prompt is able to define the next Prompt that should be run. This is particularly useful in this example case where we ask the user a yes-or-no question if they want to indicate the start date for analysis, we can follow that up with a Prompt to get the date or choose to simply move on.

OptionalPrompt

OptionalPrompt is an abstract subclass of Prompt, as there were many Prompt that required a yes-or-no-to-have question, then requiring a follow-up Prompt should the user answer yes. The follow-up is provided through the optionallyRun method defined only in OptionalPrompt, such that the WizardRunner sees no difference between an OptionalPrompt and a regular Prompt.

Possible future improvements

Below are some possible future improvements that were not included in the interest of time and to ensure a minimal viable product.

1. Currently, errors are only detected when we pass the completed input string to RepoSense::main. If a user were to mistype an input, they will have to go through the trouble of re-entering all the inputs. We can have better error prompts such that in the case of an invalid input, we can immediately correct and re-prompt, avoiding having to make the user go through the whole setup again just to correct an erroneous input.

[chan-j-d]

Some quick comments before reviewing:

• Should probably add the command to test somewhere in the PR itself
• The commit message's final line should be a short call to action. Something like 'Let's implement a setup walkthrough wizard'. The additional reasoning can be moved into the explanation portion of the commit message

[github-actions[bot]]

Hi, We are going to mark this PR as stale because it has been inactive for the past 30 days. If no further activity occurs within the following 7 days, it will be automatically closed so that others can take up the issue. If you are still working on this PR, please make a follow-up commit within 7 days and leave a comment to remove the stale label. Do let us know if you are stuck so that we can help you!'

[github-actions[bot]]

This PR was closed because it has been marked as stale for 7 days with no activity. Feel free to reopen this PR if you would like to continue working on it.