Repo selection mode enhancements (#54)

- Make the selection mode used by git-xargs explicit in the report
- Add more explicit error handling when all --repo or STDIN repos are
malformed
- These changes should make it easier to grok what git-xargs is doing
and why when it comes to --github-org being preferred, or user-supplied
inputs being malformed

Author: zackproser

printer/printer.go

@@ -39,6 +39,9 @@ func PrintRepoReport(allEvents []types.AnnotatedEvent, runReport *types.RunRepor
 	fmt.Println()
 	fmt.Println(runReport.Command)
 	fmt.Println()
+	fmt.Println("REPO SELECTION METHOD USED FOR THIS RUN - (see README.md for more information)")
+	fmt.Println()
+	fmt.Println(runReport.SelectionMode)
 
 	// If the user selected repos via a flat file, print a table showing which repos they were
 	if len(runReport.FileProvidedRepos) > 0 {

repository/select-repos.go

@@ -71,38 +71,54 @@ func selectReposViaInput(config *config.GitXargsConfig) (*RepoSelection, error)
 		AllowedRepos:           []*types.AllowedRepo{},
 		GithubOrganizationName: config.GithubOrg,
 	}
-
 	switch getPreferredOrderOfRepoSelections(config) {
 	case ExplicitReposOnCommandLine:
-		allowedRepos, err := selectReposViaRepoFlag(config.RepoSlice)
+		config.Stats.SetSelectionMode(string(ExplicitReposOnCommandLine))
+
+		allowedRepos, malformedRepos, err := selectReposViaRepoFlag(config.RepoSlice)
 		if err != nil {
 			return def, err
 		}
+
+		trackMalformedUserSuppliedRepoNames(config, malformedRepos)
+
 		return &RepoSelection{
 			SelectionType:          ExplicitReposOnCommandLine,
 			AllowedRepos:           allowedRepos,
 			GithubOrganizationName: "",
 		}, nil
 
 	case ReposFilePath:
+
+		config.Stats.SetSelectionMode(string(ReposFilePath))
+
 		allowedRepos, err := io.ProcessAllowedRepos(config.ReposFile)
 		if err != nil {
 			return def, err
 		}
+
 		return &RepoSelection{
 			SelectionType:          ReposFilePath,
 			AllowedRepos:           allowedRepos,
 			GithubOrganizationName: "",
 		}, nil
 
 	case GithubOrganization:
+
+		config.Stats.SetSelectionMode(string(GithubOrganization))
+
 		return def, nil
 
 	case ReposViaStdIn:
-		allowedRepos, err := selectReposViaRepoFlag(config.RepoFromStdIn)
+		config.Stats.SetSelectionMode(string(ReposViaStdIn))
+
+		allowedRepos, malformedRepos, err := selectReposViaRepoFlag(config.RepoFromStdIn)
 		if err != nil {
 			return def, err
 		}
+
+		trackMalformedUserSuppliedRepoNames(config, malformedRepos)
+
 		return &RepoSelection{
 			SelectionType:          ReposViaStdIn,
 			AllowedRepos:           allowedRepos,
@@ -114,23 +130,40 @@ func selectReposViaInput(config *config.GitXargsConfig) (*RepoSelection, error)
 	}
 }
 
+// trackMalformedUserSuppliedRepoNames will add any malformed repositories supplied by the user via --repo or STDIN
+// to the final report, explaining that the repos could not be used as supplied (usually due to missing org prefix)
+func trackMalformedUserSuppliedRepoNames(config *config.GitXargsConfig, malformedRepos []string) {
+	// If any repos supplied via --repo flags were not parsed successfully, probably because they were malformed,
+	// then add them to the final run report so the operator understands why they were not processed
+	for _, m := range malformedRepos {
+		mr := &github.Repository{
+			Name: github.String(m),
+		}
+		config.Stats.TrackSingle(stats.RepoFlagSuppliedRepoMalformed, mr)
+	}
+}
+
 // selectReposViaRepoFlag converts the string slice of repo flags provided via stdin or by invocations of the --repo
 // flag into the internal representation of AllowedRepo that we use prior to fetching the corresponding repo from
 // GitHub
-func selectReposViaRepoFlag(inputRepos []string) ([]*types.AllowedRepo, error) {
+func selectReposViaRepoFlag(inputRepos []string) ([]*types.AllowedRepo, []string, error) {
 	var allowedRepos []*types.AllowedRepo
+	var malformedRepos []string
 
 	for _, repoInput := range inputRepos {
 		allowedRepo := util.ConvertStringToAllowedRepo(repoInput)
 		if allowedRepo != nil {
 			allowedRepos = append(allowedRepos, allowedRepo)
+		} else {
+			malformedRepos = append(malformedRepos, repoInput)
 		}
 	}
+
 	if len(allowedRepos) < 1 {
-		return allowedRepos, errors.WithStackTrace(types.NoRepoSelectionsMadeErr{})
+		return allowedRepos, malformedRepos, errors.WithStackTrace(types.NoRepoFlagTargetsValid{})
 	}
 
-	return allowedRepos, nil
+	return allowedRepos, malformedRepos, nil
 }
 
 // fetchUserProvidedReposViaGithub converts repos provided as strings, already validated as being well-formed, into GitHub API repo objects that can be further processed

stats/stats.go

@@ -66,6 +66,8 @@ const (
 	BranchRemotePullFailed types.Event = "branch-remote-pull-failed"
 	// BranchRemoteDidntExistYet denotes a repo whose specified branch didn't exist remotely yet and so was just created locally to begin with
 	BranchRemoteDidntExistYet types.Event = "branch-remote-didnt-exist-yet"
+	// RepoFlagSuppliedRepoMalformed denotes a repo passed via the --repo flag that was malformed (perhaps missing it's Github org prefix) and therefore unprocessable
+	RepoFlagSuppliedRepoMalformed types.Event = "repo-flag-supplied-repo-malformed"
 )
 
 var allEvents = []types.AnnotatedEvent{
@@ -94,10 +96,12 @@ var allEvents = []types.AnnotatedEvent{
 	{Event: DirectCommitsPushedToRemoteBranch, Description: "Repos whose changes were pushed directly to the remote branch because --skip-pull-requests was passed"},
 	{Event: BranchRemotePullFailed, Description: "Repos whose remote branches could not be successfully pulled"},
 	{Event: BranchRemoteDidntExistYet, Description: "Repos whose specified branches did not exist on the remote, and so were first created locally"},
+	{Event: RepoFlagSuppliedRepoMalformed, Description: "Repos passed via the --repo flag that were malformed (missing their Github org prefix?) and therefore unprocessable"},
 }
 
 // RunStats will be a stats-tracker class that keeps score of which repos were touched, which were considered for update, which had branches made, PRs made, which were missing workflows or contexts, or had out of date workflows syntax values, etc
 type RunStats struct {
+	selectionMode         string
 	repos                 map[types.Event][]*github.Repository
 	skippedArchivedRepos  map[types.Event][]*github.Repository
 	pulls                 map[string]string
@@ -128,6 +132,16 @@ func NewStatsTracker() *RunStats {
 	return t
 }
 
+// SetSelectionMode accepts a string representing the method by which repos were selected for this run - in order to print a human-legible description in the final report
+func (r *RunStats) SetSelectionMode(mode string) {
+	r.selectionMode = mode
+}
+
+// GetSelectionMode returns the currently set repo selection method
+func (r *RunStats) GetSelectionMode() string {
+	return r.selectionMode
+}
+
 // GetTotalRunSeconds returns the total time it took, in seconds, to run all the selected commands against all the targeted repos
 func (r *RunStats) GetTotalRunSeconds() int {
 	s := time.Since(r.startTime).Seconds()
@@ -223,6 +237,7 @@ func (r *RunStats) GenerateRunReport() *types.RunReport {
 		Repos:          r.GetRepos(),
 		SkippedRepos:   r.GetSkippedArchivedRepos(),
 		Command:        r.command,
+		SelectionMode:  r.selectionMode,
 		RuntimeSeconds: r.GetTotalRunSeconds(), FileProvidedRepos: r.GetFileProvidedRepos(),
 		PullRequests: r.GetPullRequests(),
 	}

types/types.go

@@ -19,6 +19,7 @@ type RunReport struct {
 	Repos             map[Event][]*github.Repository
 	SkippedRepos      map[Event][]*github.Repository
 	Command           []string
+	SelectionMode     string
 	RuntimeSeconds    int
 	FileProvidedRepos []*AllowedRepo
 	PullRequests      map[string]string
@@ -60,6 +61,12 @@ func (NoRepoSelectionsMadeErr) Error() string {
 	return fmt.Sprint("You must target some repos for processing either via stdin or by providing one of the --github-org, --repos, or --repo flags")
 }
 
+type NoRepoFlagTargetsValid struct{}
+
+func (NoRepoFlagTargetsValid) Error() string {
+	return fmt.Sprint("None of the repos specified via the --repo flag are valid. Please double-check you have included the Github org prefix for each - e.g. --repo gruntwork-io/git-xargs")
+}
+
 type NoBranchNameErr struct{}
 
 func (NoBranchNameErr) Error() string {