Merge pull request #58 from slosive/cleanup-sourcecode

Small codebase cleanup

Author: tfadeyi

README.md

@@ -19,9 +19,9 @@
 
 <p align="center">
 <strong>[<a href="https://slotalk.fadey.io/docs/intro">Docs</a>]</strong>
-<strong>[<a href="#Try-it!">Try it!</a>]</strong>
-<strong>[<a href="#Install">Install</a>]</strong>
-<strong>[<a href="#Get-Started">Get Started</a>]</strong>
+<strong>[<a href="#try-it">Try it!</a>]</strong>
+<strong>[<a href="#-install">Install</a>]</strong>
+<strong>[<a href="#-get-started">Get Started</a>]</strong>
 </p>
 
 > ⚠ The tool is still not ready for real production use yet.
@@ -40,6 +40,18 @@ SLOscribe can be used in tandem with the [Sloth CLI](https://github.com/slok/slo
 * [Go](https://go.dev/doc/install)
 * [Nix](https://zero-to-nix.com/start/install) (optional)
 
+## 🔽 Install
+
+The SLOscribe CLI can be installed easily via the installation script.
+
+```shell
+curl -sfL https://raw.githubusercontent.com/slosive/sloscribe/main/install.sh | sh -
+```
+
+This will install the required binary for your machine (Linux/Mac only).
+
+For other ways of installing the tool please check the [installation guide](https://slotalk.fadey.io/docs/category/installation).
+
 ## 📚 Basic example - Generate Prometheus alert groups from code annotations
 
 This example shows how sloth's comments can be added next to the prometheus metrics defined in a `metrics.go` file.
@@ -54,7 +66,7 @@ This example shows how sloth's comments can be added next to the prometheus metr
         // @sloth.slo description 95% of logins to the chat-gpt app should be successful.
         // @sloth.alerting name ChatGPTAvailability
         metricTenantLogins = prometheus.NewCounter(
-            prometheus.GaugeOpts{
+            prometheus.CounterOpts{
                 Namespace: "chatgpt",
                 Subsystem: "auth0",
                 Name:      "tenant_login_operations_total",
@@ -303,18 +315,6 @@ groups:
 
 </details>
 
-## 🔽 Install
-
-The SLOscribe CLI can be installed easily via the installation script.
-
-```shell
-curl -sfL https://raw.githubusercontent.com/slosive/sloscribe/main/install.sh | sh -
-```
-
-This will install the required binary for your machine (Linux/Mac only).
-
-For other ways of installing the tool please check the [installation guide](https://slotalk.fadey.io/docs/category/installation).
-
 ## 🚀 Get Started
 
 1. Add comments to your source code. See [Declarative Comments](https://slotalk.fadey.io/docs/category/sloth-annotations).
@@ -342,14 +342,14 @@ Usage:
   sloscribe init [flags]
 
 Flags:
-      --dirs strings     Comma separated list of directories to be parses by the tool (default [...])
-  -f, --file string            Target file to parse. example: ./metrics.go
-      --format strings         Output format (yaml,json). (default [yaml])
-  -h, --help                   help for init
-      --lang string            Language of the source files. (go) (default "go")
-      --services strings       Comma separated list of service names. These will select the output service specifications returned by the tool.
-      --specification string   The name of the specification the tool should parse the source file for, example: sloth or sloth-k8s. (default "sloth")
-      --to-file                Print the generated specifications to file, under ./slo_definitions.
+      --dirs strings               Comma separated list of directories to be recursively parsed by the tool (default [/home/jetstack-oluwole/go/src/github.com/slosive/sloscribe])
+  -f, --file string                Source code file to parse for annotations. Example: ./metrics.go
+      --format strings             Format of the output returned by the tool. Available: yaml, json. (default [yaml])
+  -h, --help                       help for init
+      --lang string                Target source code language. Available: go. (default "go")
+      --service-selector strings   Comma separated list of service specification names. These will select the output service specifications returned by the tool. Example: --service-selector app1,app3 
+      --specification string       The SLO specification the tool should parse the source file for. Available: sloth, sloth-k8s. (default "sloth")
+      --to-file                    Tells the tool to save the generated specifications to file, under ./slo_definitions.
 
 Global Flags:
       --log-level string   Only log messages with the given severity or above. One of: [none, debug, info, warn], errors will always be printed (default "info")

cmd/init.go

@@ -78,13 +78,13 @@ func specInitCmd(common *commonoptions.Options) *cobra.Command {
 				options.SourceContent(inputReader),
 				options.Include(opts.IncludedDirs...))
 			if err != nil {
-				logger.Error(err, "Parser initialization")
+				logger.Error(err, "Parser initialization error, please try again")
 				return err
 			}
 
 			services, err := parser.Parse(cmd.Context())
 			if err != nil {
-				logger.Error(err, "Parser parsing error")
+				logger.Error(err, "Parsing error, please try again")
 				return err
 			}
 
@@ -100,45 +100,41 @@ func specInitCmd(common *commonoptions.Options) *cobra.Command {
 
 				service, ok := services[serviceName]
 				if !ok {
-					err := errors.Errorf("selected service %q was not found in the parser output", serviceName)
-					logger.Warn(err, "")
+					logger.Warn(errors.Errorf("selected service specification %q was not found in the parser output", serviceName), "")
 				} else {
 					selectedServices[serviceName] = service
 				}
 			}
 
 			// Only print to file if the user has selected the to-file option
 			if opts.ToFile {
-				logger.Info("Generating specifications files in output directory ✍🏿", "directory", generate.DefaultServiceDefinitionDir)
+				logger.Info("Generating service specification(s) files in output directory", "directory", generate.DefaultServiceDefinitionDir)
 				if outputKubernetes {
-					if err := generate.WriteK8Specifications(nil, []byte(header), selectedServices, true, ".", opts.Formats...); err != nil {
-						logger.Error(err, "Generating specification file error")
-						return err
-					}
+					err = generate.WriteK8Specifications(nil, []byte(header), selectedServices, true, ".", opts.Formats...)
 				} else {
-					if err := generate.WriteSpecifications(nil, []byte(header), selectedServices, true, ".", opts.Formats...); err != nil {
-						logger.Error(err, "Generating specification file error")
-						return err
-					}
+					err = generate.WriteSpecifications(nil, []byte(header), selectedServices, true, ".", opts.Formats...)
+				}
+				if err != nil {
+					logger.Error(err, "Error generating specification file for the parsed service, please try again")
+					return err
 				}
 				return nil
 			}
 
-			logger.Info("Printing result specification to stdout ✍🏿")
+			logger.Info("Printing parsed service specification(s) ✍🏿")
 			writer := cmd.OutOrStdout()
 
 			// Print the specification(s) to stout or file
 			if outputKubernetes {
-				if err := generate.WriteK8Specifications(writer, []byte(header), selectedServices, false, "", opts.Formats...); err != nil {
-					logger.Error(err, "Writing specification to stdout error")
-					return err
-				}
+				err = generate.WriteK8Specifications(writer, []byte(header), selectedServices, false, "", opts.Formats...)
 			} else {
-				if err := generate.WriteSpecifications(writer, []byte(header), selectedServices, false, "", opts.Formats...); err != nil {
-					logger.Error(err, "Writing specification to stdout error")
-					return err
-				}
+				err = generate.WriteSpecifications(writer, []byte(header), selectedServices, false, "", opts.Formats...)
 			}
+			if err != nil {
+				logger.Error(err, "Error printing service specification(s) to standard output")
+				return err
+			}
+
 			return nil
 		},
 	}

cmd/options/common/README.md

@@ -17,7 +17,7 @@ Package common contains the different common options across the different comman
 
 
 <a name="Options"></a>
-## type [Options](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L15-L18>)
+## type [Options](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L14-L17>)
 
 Options is the list of options/flag available to the application, plus the clients needed by the application to function.
 
@@ -29,7 +29,7 @@ type Options struct {
 ```
 
 <a name="New"></a>
-### func [New](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L22>)
+### func [New](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L21>)
 
 ```go
 func New() *Options
@@ -38,7 +38,7 @@ func New() *Options
 New creates a new instance of the application's options
 
 <a name="Options.Complete"></a>
-### func \(\*Options\) [Complete](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L33>)
+### func \(\*Options\) [Complete](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L32>)
 
 ```go
 func (o *Options) Complete() error
@@ -47,7 +47,7 @@ func (o *Options) Complete() error
 Complete initialises the components needed for the application to function given the options
 
 <a name="Options.Prepare"></a>
-### func \(\*Options\) [Prepare](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L27>)
+### func \(\*Options\) [Prepare](<https://github.com/slosive/sloscribe/blob/main/cmd/options/common/options.go#L26>)
 
 ```go
 func (o *Options) Prepare(cmd *cobra.Command) *Options

cmd/options/common/options.go

@@ -6,7 +6,6 @@ import (
 	"github.com/slosive/sloscribe/internal/logging"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
-	goaloe "github.com/tfadeyi/go-aloe"
 )
 
 type (
@@ -38,9 +37,7 @@ func (o *Options) Complete() error {
 		// @aloe summary The log level passed to the --log-level flag is not supported.
 		// @aloe details The log level passed to the --log-level flag is not currently supported by the tool.
 		// The following are supported: none, debug, info(default), warn.
-		err = goaloe.DefaultOrDie().Error(
-			multierr.Append(err, errors.Errorf("invalid log-level %q was passed to --log-level flag", o.LogLevel)),
-			"invalid_log_level")
+		err = multierr.Append(err, errors.Errorf("invalid log-level %q was passed to --log-level flag", o.LogLevel))
 	}
 	return err
 }

cmd/options/init/README.md

@@ -17,7 +17,7 @@ Package spec contains the different options present under the spec generation co
 
 
 <a name="Options"></a>
-## type [Options](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L19-L29>)
+## type [Options](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L18-L28>)
 
 Options is the list of options/flag available to the application, plus the clients needed by the application to function.
 
@@ -36,7 +36,7 @@ type Options struct {
 ```
 
 <a name="New"></a>
-### func [New](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L33>)
+### func [New](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L32>)
 
 ```go
 func New(c *common.Options) *Options
@@ -45,7 +45,7 @@ func New(c *common.Options) *Options
 New creates a new instance of the application's options
 
 <a name="Options.Complete"></a>
-### func \(\*Options\) [Complete](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L46>)
+### func \(\*Options\) [Complete](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L45>)
 
 ```go
 func (o *Options) Complete() error
@@ -54,7 +54,7 @@ func (o *Options) Complete() error
 Complete initialises the components needed for the application to function given the options
 
 <a name="Options.Prepare"></a>
-### func \(\*Options\) [Prepare](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L40>)
+### func \(\*Options\) [Prepare](<https://github.com/slosive/sloscribe/blob/main/cmd/options/init/options.go#L39>)
 
 ```go
 func (o *Options) Prepare(cmd *cobra.Command) *Options

cmd/options/init/options.go

@@ -10,7 +10,6 @@ import (
 	"github.com/slosive/sloscribe/internal/parser/lang"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
-	goaloe "github.com/tfadeyi/go-aloe"
 )
 
 type (
@@ -52,9 +51,7 @@ func (o *Options) Complete() error {
 	// The following are the supported languages: yaml(default), json.
 	for _, format := range o.Formats {
 		if ok := generate.IsValidOutputFormat(format); !ok {
-			err = goaloe.DefaultOrDie().Error(
-				multierr.Append(err, errors.Errorf("invalid format %q was passed to --format flag", format)),
-				"unsupported_output_format")
+			err = multierr.Append(err, errors.Errorf("invalid format %q was passed to --format flag", format))
 		}
 	}
 
@@ -64,9 +61,7 @@ func (o *Options) Complete() error {
 	// @aloe details The source language passed to the --lang flag is not currently supported by the tool.
 	// The following are the supported languages: go, wasm(experimental).
 	if ok := lang.IsSupportedLanguage(o.SourceLanguage); !ok {
-		err = goaloe.DefaultOrDie().Error(
-			multierr.Append(err, errors.Errorf("unsupported language %q was passed to --lang flag", o.SourceLanguage)),
-			"unsupported_language")
+		err = multierr.Append(err, errors.Errorf("unsupported language %q was passed to --lang flag", o.SourceLanguage))
 	}
 	return err
 }
@@ -84,43 +79,43 @@ func (o *Options) addAppFlags(fs *pflag.FlagSet) {
 		&o.IncludedDirs,
 		"dirs",
 		[]string{getWorkingDirOrDie()},
-		"Comma separated list of directories to be parses by the tool",
+		"Comma separated list of directories to be recursively parsed by the tool",
 	)
 	fs.StringSliceVar(
 		&o.Formats,
 		"format",
 		[]string{"yaml"},
-		"Output format (yaml,json).",
+		"Format of the output returned by the tool. Available: yaml, json.",
 	)
 	fs.StringVar(
 		(*string)(&o.SourceLanguage),
 		"lang",
 		"go",
-		"Language of the source files. (go)",
+		"Target source code language. Available: go.",
 	)
 	fs.StringVarP(
 		&o.Source,
 		"file",
 		"f",
 		"",
-		"Target file to parse. example: ./metrics.go",
+		"Source code file to parse for annotations. Example: ./metrics.go",
 	)
 	fs.BoolVar(
 		&o.ToFile,
 		"to-file",
 		false,
-		"Print the generated specifications to file, under ./slo_definitions.",
+		"Tells the tool to save the generated specifications to file, under ./slo_definitions.",
 	)
 	fs.StringSliceVar(
 		&o.Services,
-		"services",
+		"service-selector",
 		[]string{},
-		"Comma separated list of service names. These will select the output service specifications returned by the tool.",
+		"Comma separated list of service specification names. These will select the output service specifications returned by the tool. Example: --service-selector app1,app3 ",
 	)
 	fs.StringVar(
 		&o.Target,
 		"specification",
 		"sloth",
-		"The name of the specification the tool should parse the source file for, example: sloth or sloth-k8s.",
+		"The SLO specification the tool should parse the source file for. Available: sloth, sloth-k8s.",
 	)
 }

go.mod

@@ -12,7 +12,6 @@ require (
 	github.com/spf13/cobra v1.7.0
 	github.com/spf13/pflag v1.0.5
 	github.com/stretchr/testify v1.8.4
-	github.com/tfadeyi/go-aloe v0.0.2
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.27.3
 	sigs.k8s.io/yaml v1.3.0
@@ -27,7 +26,6 @@ require (
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.7 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rogpeppe/go-internal v1.10.0 // indirect
 	golang.org/x/net v0.8.0 // indirect

go.sum

@@ -38,8 +38,6 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
-github.com/pelletier/go-toml/v2 v2.0.7 h1:muncTPStnKRos5dpVKULv2FVd4bMOhNePj9CjgDb8Us=
-github.com/pelletier/go-toml/v2 v2.0.7/go.mod h1:eumQOmlWiOPt5WriQQqoM5y18pDHwha2N+QD+EUNTek=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
@@ -52,16 +50,9 @@ github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRM
 github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
 github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/tfadeyi/go-aloe v0.0.2 h1:3zKDn2Bg2pDL2ES8CIHL6TCV8hTUlamjoNY5aWjmQtA=
-github.com/tfadeyi/go-aloe v0.0.2/go.mod h1:iowd4nC94VHlcq3vebbcGX/8DMkC5oa7iGPPbBwbAf0=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -100,7 +91,6 @@ gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 k8s.io/apimachinery v0.27.3 h1:Ubye8oBufD04l9QnNtW05idcOe9Z3GQN8+7PqmuVcUM=