Add documentation around catalogers, UI elements, and the event bus (#143)

* add basic documentation for catalogers (with refactoring for simplification)

Signed-off-by: Alex Goodman <alex.goodman@anchore.com>

* add docs for catalog parsers, UI, and event bus

Signed-off-by: Alex Goodman <alex.goodman@anchore.com>

* update bus phrasing

Signed-off-by: Alex Goodman <alex.goodman@anchore.com>

syft/cataloger/javascript/cataloger.go

@@ -7,11 +7,13 @@ import (
 	"github.com/anchore/syft/syft/scope"
 )
 
+// Cataloger catalogs pkg.YarnPkg and pkg.NpmPkg Package Types defined in package-lock.json and yarn.lock files.
 type Cataloger struct {
 	cataloger common.GenericCataloger
 }
 
-func NewCataloger() *Cataloger {
+// New returns a new JavaScript cataloger object.
+func New() *Cataloger {
 	globParsers := map[string]common.ParserFn{
 		"**/package-lock.json": parsePackageLock,
 		"**/yarn.lock":         parseYarnLock,
@@ -22,14 +24,17 @@ func NewCataloger() *Cataloger {
 	}
 }
 
+// Name returns a string that uniquely describes this cataloger.
 func (a *Cataloger) Name() string {
-	return "npm-cataloger"
+	return "javascript-cataloger"
 }
 
+// SelectFiles returns a set of discovered Javascript ecosystem files from the user content source.
 func (a *Cataloger) SelectFiles(resolver scope.FileResolver) []file.Reference {
 	return a.cataloger.SelectFiles(resolver)
 }
 
+// Catalog returns the Packages indexed from all Javascript ecosystem files discovered.
 func (a *Cataloger) Catalog(contents map[file.Reference]string) ([]pkg.Package, error) {
 	return a.cataloger.Catalog(contents, a.Name())
 }

syft/cataloger/javascript/parse_package_lock.go

@@ -5,15 +5,21 @@ import (
 	"fmt"
 	"io"
 
+	"github.com/anchore/syft/syft/cataloger/common"
 	"github.com/anchore/syft/syft/pkg"
 )
 
+// integrity check
+var _ common.ParserFn = parsePackageLock
+
+// PackageLock represents a JavaScript package.lock json file
 type PackageLock struct {
 	Requires        bool `json:"requires"`
 	LockfileVersion int  `json:"lockfileVersion"`
-	Dependencies    Dependencies
+	Dependencies    map[string]Dependency
 }
 
+// Dependency represents a single package dependency listed in the package.lock json file
 type Dependency struct {
 	Version   string `json:"version"`
 	Resolved  string `json:"resolved"`
@@ -21,8 +27,7 @@ type Dependency struct {
 	Requires  map[string]string
 }
 
-type Dependencies map[string]Dependency
-
+// parsePackageLock parses a package.lock and returns the discovered JavaScript packages.
 func parsePackageLock(_ string, reader io.Reader) ([]pkg.Package, error) {
 	packages := make([]pkg.Package, 0)
 	dec := json.NewDecoder(reader)

syft/cataloger/javascript/parse_yarn_lock.go

@@ -8,9 +8,13 @@ import (
 	"strings"
 
 	"github.com/anchore/syft/internal/log"
+	"github.com/anchore/syft/syft/cataloger/common"
 	"github.com/anchore/syft/syft/pkg"
 )
 
+// integrity check
+var _ common.ParserFn = parseYarnLock
+
 var composedNameExp = regexp.MustCompile("^\"(@{1}[^@]+)")
 var simpleNameExp = regexp.MustCompile(`^[a-zA-Z\-]+@`)
 var versionExp = regexp.MustCompile(`^\W+(version)\W+`)