Add analyze command

[mscottford]

NOTE: This issue is still in a draft state. Its contents will likely change as new commands are identified as part of the pipeline.

analyze

The primary user-facing command. This command will delegate to other freshli commands to accomplish its work. It will manage work queues to enable parallelization.

freshli [global options] analyze [command options] <repo url>|<local dir>

What this command does?

With no options specified, performs analysis locally, and then sends the results to the Freshli web app so that the results can be viewed at at URL that will be provided in the command output.

Global Options

• --cache-dir <path>
  • the location where the freshli command will write temporary files as part of it’s processing
  • default value: $HOME/.freshli

Command Options

• --git-path
  • Path to the git binary
  • default value: git
• --branch <name>
  • The branch to checkout after cloning the repository
  • If the option is not specified, then no checkout command will be issued. The remote server’s default branch will be used instead.
• --commit-history (this might be moved to the "build later" category per Determine if commit history logic has been implemented as described in analyze #188)
  • Analyzes only the points in time when files have changed in the commit history. This can be combined with --history-invertal to make sure that every commit is included in the result set. If --history-interval is not used, then only the values from each commit will be present in the output, meaning that the data will show the metrics at the time that the files were changed, but will not show how the metrics changed between commits.
• --history-interval <duration> (this might be moved to the "build later" category per Determine if history interval logic has been implemented as described in analyze #187)
  • As the analyze command moves backwards in time through the history of the project, what time interval should it use to determine the points in time that are sampled
  • default value: 1m
  • valid values: /\d+[ymwd]?/
    • y suffix – specifies duration in years
    • m suffix – specifies duration in months
    • w suffix – specifies duration in weeks
    • d suffix – specifies duration in days
    • If no suffix is provided, then the duration is assumed to be a number of months
  • When walking backward in time the following approach will be taken: given current time T, subtract the smallest amount of time to produce time T' such that T' when be an even interval of the specified duration suffix.
    • Example:
      • Assume
        • T = 2022-02-01 23:11:43Z
        • Interval duration — 1d
        • Timezone offset — -04:00
        • Then T' would be set to 2022-02-01 00:00:00-04:00
        • The value of T' would be decremented by one calendar day until the earliest commit date is reached
• --workers — the number of worker processes that should be running at any given time. This defaults to twice the number of CPU cores.

Running this command will dispatch a StartAnalysisActivity. Additionally, this command will be responsible for adjusting the number of application engine workers to match the provided value of the --workers parameter.

Tasks:

• Add Cucumber/Aruba-based acceptance tests for this command
• Implement handling analyze command
  • Adjust number of workers (this could be considered a nice to have if it turns out to be difficult)
  • Pass command line parameters to StartAnalysisActivity (all except --workers should be passed in)
• Remove the following commands
  • git checkout-history
  • git compute-history
  • git clone
  • compute-libyear
• Write results to freshli-web database
  • TBD columns