chore(contrib/docker/devops): improve make targets

more holistic and consistent tasks
improved documentation

Signed-off-by: Eric Swanson <ericis@users.noreply.github.com>

contrib/docker/devops/makefile

@@ -1,15 +1,39 @@
-docker_tag                  := backstage-make
-docker_name_prefix          := backstage-make
-frontend_port               := 3000
-frontend_host_port          := 3000
-backend_port                := 7000
-backend_host_port           := 7000
+# tag for the local docker image
+docker_tag := backstage-make
 
-now_date_time_tag            = `date +'%Y%m%d%H%M%S'`
-my_dir_path                  = $(dir $(CURDIR)/$(firstword $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))
-project_root_dir_path        = $(my_dir_path)/../../
+# prefix for running docker containers
+# this helps to quickly identify containers by name
+docker_name_prefix := backstage-make
+
+# post mappings from internal docker containers
+# to the host computer
+frontend_port      := 3000
+frontend_host_port := 3000
+backend_port       := 7000
+backend_host_port  := 7000
+
+# path to this "makefile"
+my_dir_path = $(dir $(CURDIR)/$(firstword $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))
+
+# the relative root of the project
+project_root_dir_path = $(my_dir_path)/../../../
+
+# dynamic tag to uniquely identify when the script was run
+# e.g. running docker images are tagged with this
+now_date_time_tag = `date +'%Y%m%d%H%M%S'`
+
+# prefix the name of docker containers
+# for easy identification
 docker_name_timestamp_prefix = $(docker_name_prefix)-$(now_date_time_tag)
 
+# `make` will execute this
+.DEFAULT_GOAL:=all
+
+# the projects end-to-end tasks execute the build prior to the tests
+.PHONY: all
+all: build check
+
+# build the docker container image
 .PHONY: container
 container:
 	@docker build \
@@ -17,10 +41,23 @@ container:
 		-f ./Dockerfile \
 		.
 
+# remove the docker container image from local
 .PHONY: rm-container
 rm-container:
 	@docker rmi -f $(docker_tag)
 
+# creates an interactive container session
+.PHONY: interactive
+interactive: container
+	@docker run --rm -it \
+		--name $(docker_name_timestamp_prefix)-$@ \
+		--network host \
+		-v $(project_root_dir_path):/app \
+		-w /app \
+		--entrypoint "/bin/ash" \
+		$(docker_tag)
+
+# clean the project
 .PHONY: clean
 clean: container
 	@docker run --rm -it \
@@ -32,6 +69,7 @@ clean: container
 		$(docker_tag) \
 		rm -rf node_modules
 
+# install dependencies
 .PHONY: install
 install: container
 	@docker run --rm -it \
@@ -43,8 +81,8 @@ install: container
 		$(docker_tag) \
 		yarn install
 
-.PHONY: tsc
-tsc: install
+.PHONY: build-typescript
+build-typescript: install
 	@docker run --rm -it \
 		--name $(docker_name_timestamp_prefix)-$@ \
 		--network host \
@@ -54,8 +92,9 @@ tsc: install
 		$(docker_tag) \
 		yarn tsc
 
+# build the project
 .PHONY: build
-build: tsc
+build: build-typescript
 	@docker run --rm -it \
 		--name $(docker_name_timestamp_prefix)-$@ \
 		--network host \
@@ -65,8 +104,22 @@ build: tsc
 		$(docker_tag) \
 		yarn build
 
-# "check" is a standard make target
-# using make's terminology instead of the project's
+# auto-format a document properly
+.PHONY: format-doc
+format-doc: install
+ifndef path
+	$(error Missing required "path" argument)
+endif
+	@docker run --rm -it \
+		--name $(docker_name_timestamp_prefix)-$@ \
+		--network host \
+		-v $(project_root_dir_path):/app \
+		-w /app \
+		--entrypoint "" \
+		$(docker_tag) \
+		yarn prettier --write $(path)
+
+# verify document formatting
 .PHONY: check-docs
 check-docs: install
 	@docker run --rm -it \
@@ -78,12 +131,33 @@ check-docs: install
 		$(docker_tag) \
 		yarn run lint:docs
 
-# check-docs alias
-.PHONY: lint-docs
-lint-docs: check-docs
+# analyze the code
+.PHONY: check-code
+check-code: install
+	@docker run --rm -it \
+		--name $(docker_name_timestamp_prefix)-$@ \
+		--network host \
+		-v $(project_root_dir_path):/app \
+		-w /app \
+		--entrypoint "" \
+		$(docker_tag) \
+		yarn run lint:all
 
-.PHONY: check-prettier
-check-prettier: install
+.PHONY: check-type-dependencies
+check-type-dependencies: install
+	@docker run --rm -it \
+		--name $(docker_name_timestamp_prefix)-$@ \
+		--network host \
+		-v $(project_root_dir_path):/app \
+		-w /app \
+		--entrypoint "" \
+		$(docker_tag) \
+		yarn run lint:type-deps
+
+# check is a standard target for make
+# so, prefixing with "check-"
+.PHONY: check-styles
+check-styles: install
 	@docker run --rm -it \
 		--name $(docker_name_timestamp_prefix)-$@ \
 		--network host \
@@ -93,12 +167,36 @@ check-prettier: install
 		$(docker_tag) \
 		yarn run prettier:check
 
+# execute all tests
+# BUG: failing tests
+# https://github.com/backstage/backstage/issues/5212
+.PHONY: check-tests
+check-tests: build
+	@docker run --rm -it \
+		--name $(docker_name_timestamp_prefix)-$@ \
+		--network host \
+		-v $(project_root_dir_path):/app \
+		-w /app \
+		--entrypoint "" \
+		$(docker_tag) \
+		yarn run test:all
+
+# convenience: dev alias
+.PHONY: test
+test: check-tests
+
+# check all the things
+# BUG: check-tests failing (see target comments)
+.PHONY: check
+check: check-code check-docs check-type-dependencies check-styles
+
+# run development instance
 # BUG: the frontend seems to run on "$(backend_port)" (7000 default).
 #      The documentation states "This is going to start two things, 
 #      the frontend (:3000) and the backend (:7000)."
 #      However, the frontend seems to end up running on 7000.
 .PHONY: dev
-dev:
+dev: build
 	@docker run --rm -it \
 		--name $(docker_name_timestamp_prefix)-$@ \
 		-p $(frontend_port):$(frontend_host_port) \
@@ -110,10 +208,10 @@ dev:
 		$(docker_tag) \
 		yarn dev
 
-# dev alias
+# convenience: dev alias
 .PHONY: start
 start: dev
 
-# dev alias
+# convenience: dev alias
 .PHONY: run
 run: dev