bringing all commands console experience together

things were out of sync, now they are all aligned.

cmd/build_results.go

@@ -4,6 +4,7 @@ import (
 	"github.com/daveshanley/vacuum/model"
 	"github.com/daveshanley/vacuum/motor"
 	"github.com/daveshanley/vacuum/rulesets"
+	"github.com/pterm/pterm"
 	"io/ioutil"
 )
 
@@ -29,6 +30,8 @@ func BuildResults(rulesetFlag string, specBytes []byte) (*model.RuleResultSet, *
 		}
 	}
 
+	pterm.Info.Printf("Linting against %d rules: %s\n", len(selectedRS.Rules), selectedRS.DocumentationURI)
+
 	ruleset := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
 		RuleSet: selectedRS,
 		Spec:    specBytes,

cmd/generate_ruleset.go

@@ -17,10 +17,12 @@ import (
 func GetGenerateRulesetCommand() *cobra.Command {
 
 	cmd := &cobra.Command{
-		Use:     "generate-ruleset",
-		Short:   "Generate a vacuum RuleSet",
-		Long:    "Generate a YAML ruleset containing 'all', or 'recommended' rules",
-		Example: "vacuum generate-ruleset recommended | all <ruleset-output-name>",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Use:           "generate-ruleset",
+		Short:         "Generate a vacuum RuleSet",
+		Long:          "Generate a YAML ruleset containing 'all', or 'recommended' rules",
+		Example:       "vacuum generate-ruleset recommended | all <ruleset-output-name>",
 		RunE: func(cmd *cobra.Command, args []string) error {
 
 			PrintBanner()
@@ -67,7 +69,7 @@ func GetGenerateRulesetCommand() *cobra.Command {
 			json.Unmarshal(encoded, &encodedMap)
 			selectedRuleSet.RuleDefinitions = encodedMap
 
-			pterm.Info.Printf("Generating RuleSet rules: %s\n\n%s\n", args[0], selectedRuleSet.Description)
+			pterm.Info.Printf("Generating RuleSet rules: %s", selectedRuleSet.DocumentationURI)
 			pterm.Println()
 
 			yamlBytes, _ := yaml.Marshal(selectedRuleSet)
@@ -82,7 +84,7 @@ func GetGenerateRulesetCommand() *cobra.Command {
 				return err
 			}
 
-			pterm.Info.Printf("RuleSet generated for '%s', written to '%s'\n", args[0], reportOutputName)
+			pterm.Success.Printf("RuleSet generated for '%s', written to '%s'\n", args[0], reportOutputName)
 			pterm.Println()
 
 			return nil

cmd/html_report.go

@@ -22,9 +22,11 @@ import (
 func GetHTMLReportCommand() *cobra.Command {
 
 	return &cobra.Command{
-		Use:   "html-report",
-		Short: "Generate an HTML report (Work In Progress)",
-		Long: "Generate an interactive and useful HTML report (this is not ready yet). Default output " +
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Use:           "html-report",
+		Short:         "Generate an HTML report of a linting run",
+		Long: "Generate an interactive and useful HTML report. Default output " +
 			"filename is 'report.html' located in the working directory.",
 		Example: "vacuum html-report <my-awesome-spec.yaml> <report.html>",
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -91,7 +93,7 @@ func GetHTMLReportCommand() *cobra.Command {
 				return err
 			}
 
-			pterm.Info.Printf("HTML Report generated for '%s', written to '%s'\n", args[0], reportOutput)
+			pterm.Success.Printf("HTML Report generated for '%s', written to '%s'\n", args[0], reportOutput)
 			pterm.Println()
 
 			fi, _ := os.Stat(args[0])

cmd/lint.go

@@ -20,9 +20,11 @@ import (
 func GetLintCommand() *cobra.Command {
 
 	cmd := &cobra.Command{
-		Use:   "lint",
-		Short: "lint an OpenAPI specification",
-		Long:  `lint an OpenAPI specification, the output of the response will be in the terminal`,
+		SilenceErrors: true,
+		SilenceUsage:  true,
+		Use:           "lint",
+		Short:         "Lint an OpenAPI specification",
+		Long:          `Lint an OpenAPI specification, the output of the response will be in the terminal`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 
 			detailsFlag, _ := cmd.Flags().GetBool("details")
@@ -81,11 +83,7 @@ func GetLintCommand() *cobra.Command {
 				}
 			}
 
-			if !silent {
-				pterm.Info.Printf("Running vacuum against spec '%s' against %d rules: %s\n\n%s\n", args[0],
-					len(selectedRS.Rules), selectedRS.DocumentationURI, selectedRS.Description)
-				pterm.Println()
-			}
+			pterm.Info.Printf("Linting against %d rules: %s\n", len(selectedRS.Rules), selectedRS.DocumentationURI)
 
 			result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
 				RuleSet: selectedRS,

cmd/root.go

@@ -18,14 +18,16 @@ var (
 	Date    string
 
 	rootCmd = &cobra.Command{
-		Use:   "vacuum lint <your-openapi-file.yaml>",
-		Short: "vacuum is a very, very fast OpenAPI linter",
-		Long:  `vacuum is a very, very fast OpenAPI linter. It will suck all the lint off your spec in milliseconds`,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Use:           "vacuum lint <your-openapi-file.yaml>",
+		Short:         "vacuum is a very fast OpenAPI linter",
+		Long:          `vacuum is a very fast OpenAPI linter. It will suck all the lint off your spec in milliseconds`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 
 			PrintBanner()
 
-			pterm.Println("To see something useful, try 'vacuum lint <my-openapi-spec.yaml>'")
+			pterm.Println(">> Welcome! To lint something, try 'vacuum lint <my-openapi-spec.yaml>'")
 
 			pterm.Println()
 

cmd/spectral_report.go

@@ -19,8 +19,10 @@ import (
 func GetSpectralReportCommand() *cobra.Command {
 
 	return &cobra.Command{
-		Use:   "spectral-report",
-		Short: "Generate a Spectral compatible JSON report",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Use:           "spectral-report",
+		Short:         "Generate a Spectral compatible JSON report",
 		Long: "Generate a JSON report using the same model as Spectral. Default output " +
 			"filename is 'vacuum-spectral-report.json' located in the working directory.",
 		Example: "vacuum report my-awesome-spec.yaml <vacuum-spectral-report.json>",
@@ -79,9 +81,7 @@ func GetSpectralReportCommand() *cobra.Command {
 				}
 			}
 
-			pterm.Info.Printf("Running vacuum against spec '%s' against %d rules: %s\n\n%s\n", args[0],
-				len(selectedRS.Rules), selectedRS.DocumentationURI, selectedRS.Description)
-			pterm.Println()
+			pterm.Info.Printf("Linting against %d rules: %s\n", len(selectedRS.Rules), selectedRS.DocumentationURI)
 
 			ruleset := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
 				RuleSet: selectedRS,
@@ -106,7 +106,7 @@ func GetSpectralReportCommand() *cobra.Command {
 				return err
 			}
 
-			pterm.Info.Printf("Report generated for '%s', written to '%s'\n", args[0], reportOutput)
+			pterm.Success.Printf("Report generated for '%s', written to '%s'\n", args[0], reportOutput)
 			pterm.Println()
 
 			fi, _ := os.Stat(args[0])

cmd/vacuum_report.go

@@ -24,8 +24,10 @@ import (
 func GetVacuumReportCommand() *cobra.Command {
 
 	cmd := &cobra.Command{
-		Use:   "report",
-		Short: "Generate a vacuum report",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Use:           "report",
+		Short:         "Generate a vacuum sealed, replayable report",
 		Long: "Generate a full report of a linting run. This can be used as a result set, or can be used to replay a linting run. " +
 			"the default filename is 'vacuum-report-MM-DD-YY-HH_MM_SS.json' located in the working directory.",
 		Example: "vacuum report <my-awesome-spec.yaml> <report-prefix>",
@@ -87,9 +89,7 @@ func GetVacuumReportCommand() *cobra.Command {
 				}
 			}
 
-			pterm.Info.Printf("Running vacuum against spec '%s' against %d rules: %s\n\n%s\n", args[0],
-				len(selectedRS.Rules), selectedRS.DocumentationURI, selectedRS.Description)
-			pterm.Println()
+			pterm.Info.Printf("Linting against %d rules: %s\n", len(selectedRS.Rules), selectedRS.DocumentationURI)
 
 			ruleset := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
 				RuleSet: selectedRS,
@@ -147,7 +147,7 @@ func GetVacuumReportCommand() *cobra.Command {
 				return err
 			}
 
-			pterm.Info.Printf("Report generated for '%s', written to '%s'\n", args[0], reportOutputName)
+			pterm.Success.Printf("Report generated for '%s', written to '%s'\n", args[0], reportOutputName)
 			pterm.Println()
 
 			fi, _ := os.Stat(args[0])

rulesets/examples/custom-ruleset.yaml

@@ -1,4 +1,5 @@
 extends: [[spectral:oas, off]]
+documentationUrl: https://quobix.com/vacuum/rulesets/custom-rulesets
 rules:
   check-title-is-exactly-this:
     description: Check the title of the spec is exactly, 'this specific thing'

rulesets/rulesets.go

@@ -137,7 +137,8 @@ func (rsm ruleSetsModel) GenerateOpenAPIRecommendedRuleSet() *RuleSet {
 	// copy.
 	modifiedRS := *rsm.openAPIRuleSet
 	modifiedRS.Rules = filtered
-	modifiedRS.Description = "Recommended rules that should always be run on a specification."
+	modifiedRS.DocumentationURI = "https://quobix.com/vacuum/rulesets/recommended"
+	modifiedRS.Description = "Recommended rules for a high quality specification."
 	return &modifiedRS
 }
 
@@ -146,7 +147,7 @@ func (rsm ruleSetsModel) GenerateRuleSetFromSuppliedRuleSet(ruleset *RuleSet) *R
 	extends := ruleset.GetExtendsValue()
 
 	rs := &RuleSet{
-		DocumentationURI: "https://quobix.com/vacuum/rulesets",
+		DocumentationURI: ruleset.DocumentationURI,
 		Formats:          ruleset.Formats,
 		Extends:          ruleset.Extends,
 		Description:      ruleset.Description,
@@ -157,22 +158,26 @@ func (rsm ruleSetsModel) GenerateRuleSetFromSuppliedRuleSet(ruleset *RuleSet) *R
 	// default and explicitly recommended
 	if extends[SpectralOpenAPI] == SpectralRecommended || extends[SpectralOpenAPI] == SpectralOpenAPI {
 		rs = rsm.GenerateOpenAPIRecommendedRuleSet()
-		rs.DocumentationURI = "https://quobix.com/vacuum/rulesets/recommended"
 	}
 
 	// all rules
 	if extends[SpectralOpenAPI] == SpectralAll {
 		rs = rsm.openAPIRuleSet
-		rs.DocumentationURI = "https://quobix.com/vacuum/rulesets/all"
 	}
 
 	// no rules!
 	if extends[SpectralOpenAPI] == SpectralOff {
-		rs.DocumentationURI = "https://quobix.com/vacuum/rulesets/off"
+		if rs.DocumentationURI == "" {
+			rs.DocumentationURI = "https://quobix.com/vacuum/rulesets/no-rules"
+		}
 		rs.Rules = make(map[string]*model.Rule)
 		rs.Description = fmt.Sprintf("All disabled ruleset, processing %d supplied rules", len(rs.RuleDefinitions))
 	}
 
+	if ruleset.DocumentationURI == "" {
+		ruleset.DocumentationURI = "https://quobix.com/vacuum/rulesets/understanding"
+	}
+
 	// make sure the map is never nil.
 	if rs.Rules == nil {
 		rs.Rules = make(map[string]*model.Rule)