refactor: update Makefile organization; update DEVELOPING.md instructions (#1212)

DEVELOPING.md

@@ -6,11 +6,38 @@ In order to test and develop in this repo you will need the following dependenci
 - docker
 - make
 
-After cloning do the following:
+After cloning the following step can help you get setup:
 1. run `make bootstrap` to download go mod dependencies, create the `/.tmp` dir, and download helper utilities.
-2. run `make` to run linting, tests, and other verifications to make certain everything is working alright.
+2. run `make` to view the selection of developer commands in the Makefile
+3. run `make build` to build the release snapshot binaries and packages
+4. for an even quicker start you can run `go run cmd/syft/main.go` to print the syft help.
+	- this command `go run cmd/syft/main.go alpine:latest` will compile and run syft against `alpine:latest`
+5. view the README or syft help output for more output options
 
-Checkout `make help` to see what other actions you can take.
+#### Make output
+```
+all                      Run all linux-based checks (linting, license check, unit, integration, and linux compare tests)
+benchmark                Run benchmark tests and compare against the baseline (if available)
+bootstrap                Download and install all tooling dependencies (+ prep tooling in the ./tmp dir)
+build                    Build release snapshot binaries and packages
+check-licenses           Ensure transitive dependencies are compliant with the current license policy
+clean-test-image-cache   Clean test image cache
+clean                    Remove previous builds, result reports, and test cache
+cli                      Run CLI tests
+compare-linux            Run compare tests on build snapshot binaries and packages (Linux)
+compare-mac              Run compare tests on build snapshot binaries and packages (Mac)
+generate-json-schema     Generate a new json schema
+generate-license-list    Generate an updated spdx license list
+help                     Display this help
+integration              Run integration tests
+lint-fix                 Auto-format all source code + run golangci lint fixers
+lint                     Run gofmt + golangci lint checks
+show-test-image-cache    Show all docker and image tar cache
+show-test-snapshots      Show all test snapshots
+snapshot-with-signing    Build snapshot release binaries and packages (with dummy signing)
+test                     Run all tests (currently unit, integration, linux compare, and cli tests)
+unit                     Run unit tests (with coverage)
+```
 
 The main make tasks for common static analysis and testing are `lint`, `lint-fix`, `unit`, `integration`, and `cli`.
 
@@ -176,4 +203,4 @@ TODO: outline:
 - source.Source
 - file.Resolvers
 - logger abstraction 
-- events / bus abstraction 
+- events / bus abstraction 

Makefile

@@ -1,19 +1,16 @@
 BIN = syft
+VERSION=$(shell git describe --dirty --always --tags)
 TEMPDIR = ./.tmp
-RESULTSDIR = test/results
+
-COVER_REPORT = $(RESULTSDIR)/unit-coverage-details.txt
+# commands and versions
-COVER_TOTAL = $(RESULTSDIR)/unit-coverage-summary.txt
+LINTCMD = $(TEMPDIR)/golangci-lint run --tests=false --timeout=5m --config .golangci.yaml
-LINTCMD = $(TEMPDIR)/golangci-lint run --tests=false --timeout=4m --config .golangci.yaml
 GOIMPORTS_CMD = $(TEMPDIR)/gosimports -local github.com/anchore
 RELEASE_CMD=$(TEMPDIR)/goreleaser release --rm-dist
 SNAPSHOT_CMD=$(RELEASE_CMD) --skip-publish --snapshot
-VERSION=$(shell git describe --dirty --always --tags)
-COMPARE_TEST_IMAGE = centos:8.2.2004
-COMPARE_DIR = ./test/compare
 GOLANGCILINT_VERSION = v1.49.0
+GOSIMPORTS_VERSION = v0.3.1
 BOUNCER_VERSION = v0.4.0
 CHRONICLE_VERSION = v0.4.1
-GOSIMPORTS_VERSION = v0.3.1
 GORELEASER_VERSION = v1.11.2
 YAJSV_VERSION = v1.4.0
 COSIGN_VERSION = v1.12.0
@@ -28,6 +25,12 @@ RESET := $(shell tput -T linux sgr0)
 TITLE := $(BOLD)$(PURPLE)
 SUCCESS := $(BOLD)$(GREEN)
 
+# test variables
+RESULTSDIR = test/results
+COMPARE_DIR = ./test/compare
+COMPARE_TEST_IMAGE = centos:8.2.2004
+COVER_REPORT = $(RESULTSDIR)/unit-coverage-details.txt
+COVER_TOTAL = $(RESULTSDIR)/unit-coverage-summary.txt
 # the quality gate lower threshold for unit test total % coverage (by function statements)
 COVERAGE_THRESHOLD := 62
 
@@ -43,7 +46,6 @@ OS=$(shell uname | tr '[:upper:]' '[:lower:]')
 SNAPSHOT_BIN=$(realpath $(shell pwd)/$(SNAPSHOTDIR)/$(OS)-build_$(OS)_amd64_v1/$(BIN))
 
 ## Variable assertions
-
 ifndef TEMPDIR
 	$(error TEMPDIR is not set)
 endif
@@ -84,6 +86,9 @@ define safe_rm_rf_children
 	bash -c 'test -z "$(1)" && false || rm -rf $(1)/*'
 endef
 
+## Default Task
+.DEFAULT_GOAL:=help
+
 ## Tasks
 
 .PHONY: all
@@ -93,10 +98,6 @@ all: clean static-analysis test ## Run all linux-based checks (linting, license
 .PHONY: test
 test: unit validate-cyclonedx-schema integration benchmark compare-linux cli ## Run all tests (currently unit, integration, linux compare, and cli tests)
 
-.PHONY: help
-help:
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(BOLD)$(CYAN)%-25s$(RESET)%s\n", $$1, $$2}'
-
 .PHONY: ci-bootstrap
 ci-bootstrap:
 	DEBIAN_FRONTEND=noninteractive sudo apt update && sudo -E apt install -y bc jq libxml2-utils
@@ -128,7 +129,7 @@ bootstrap-go:
 	go mod download
 
 .PHONY: bootstrap
-bootstrap: $(RESULTSDIR) bootstrap-go bootstrap-tools ## Download and install all go dependencies (+ prep tooling in the ./tmp dir)
+bootstrap: $(RESULTSDIR) bootstrap-go bootstrap-tools ## Download and install all tooling dependencies (+ prep tooling in the ./tmp dir)
 	$(call title,Bootstrapping dependencies)
 
 .PHONY: static-analysis
@@ -350,7 +351,7 @@ CHANGELOG.md:
 	$(TEMPDIR)/chronicle -vv > CHANGELOG.md
 
 .PHONY: release
-release: clean-dist CHANGELOG.md  ## Build and publish final binaries and packages. Intended to be run only on macOS.
+release: clean-dist CHANGELOG.md
 	$(call title,Publishing release artifacts)
 
 	# create a config with the dist dir overridden
@@ -404,14 +405,16 @@ clean-dist: clean-changelog
 clean-changelog:
 	rm -f CHANGELOG.md
 
-clean-test-image-cache: clean-test-image-tar-cache clean-test-image-docker-cache
+clean-test-image-cache: clean-test-image-tar-cache clean-test-image-docker-cache ## Clean test image cache
 
 .PHONY: clear-test-image-tar-cache
-clean-test-image-tar-cache: ## Delete all test cache (built docker image tars)
+clean-test-image-tar-cache:
+	## Delete all test cache (built docker image tars)
 	find . -type f -wholename "**/test-fixtures/cache/stereoscope-fixture-*.tar" -delete
 
 .PHONY: clear-test-image-docker-cache
-clean-test-image-docker-cache: ## Purge all test docker images
+clean-test-image-docker-cache:
+	## Purge all test docker images
 	docker images --format '{{.ID}} {{.Repository}}' | grep stereoscope-fixture- | awk '{print $$1}' | uniq | xargs -r docker rmi --force
 
 .PHONY: show-test-image-cache
@@ -426,3 +429,7 @@ show-test-image-cache: ## Show all docker and image tar cache
 show-test-snapshots: ## Show all test snapshots
 	$(call title,Test snapshots)
 	@find . -type f -wholename "**/test-fixtures/snapshot/*" | sort
+
+.PHONY: help
+help:  ## Display this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(BOLD)$(CYAN)%-25s$(RESET)%s\n", $$1, $$2}'