[linters] Install tools based on versions in package.json (#2323)

* [editorial] Use `npx` to run npm cmds, not hardcoded paths

* Update Makefile based on feedback

* Use --no-install option for npx

* Add `npm install` to markdown-check workflows

* Pin markdownlint-cli at 0.31.0

* Run `npm install` as a separate workflow step

* Use name 'install dependencies' for npm install cmd

* CONTRIBUTING: clarify that you install the tools once

* make: add `install-tools` as dependency to `all`

* Add install check line to `mardown*` targets

Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>

Makefile

@@ -5,9 +5,6 @@ PWD := $(shell pwd)
 TOOLS_DIR := ./internal/tools
 MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
-MARKDOWN_LINK_CHECK=./node_modules/.bin/markdown-link-check
-MARKDOWN_LINT=./node_modules/.bin/markdownlint
-MARKDOWN_TOC=./node_modules/.bin/markdown-toc
 
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
 # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
@@ -15,7 +12,7 @@ SEMCONVGEN_VERSION=0.8.0
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
 .PHONY: all
-all: markdownlint markdown-link-check misspell table-check schema-check
+all: install-tools markdownlint markdown-link-check misspell table-check schema-check
 
 $(MISSPELL):
 	cd $(TOOLS_DIR) && go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell
@@ -28,15 +25,13 @@ misspell:	$(MISSPELL)
 misspell-correction:	$(MISSPELL)
 	$(MISSPELL) -w $(ALL_DOCS)
 
-$(MARKDOWN_LINK_CHECK):
-	npm install markdown-link-check
-
 .PHONY: markdown-link-check
-markdown-link-check:	$(MARKDOWN_LINK_CHECK)
-	@for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done
-
-$(MARKDOWN_TOC):
-	npm install markdown-toc
+markdown-link-check:
+	@if ! npm ls markdown-link-check; then npm install; fi
+	@for f in $(ALL_DOCS); do \
+		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
+			|| exit 1; \
+	done
 
 # This target runs markdown-toc on all files that contain
 # a comment <!-- tocstop -->.
@@ -47,22 +42,25 @@ $(MARKDOWN_TOC):
 #   <!-- toc -->
 #   <!-- tocstop -->
 .PHONY: markdown-toc
-markdown-toc:	$(MARKDOWN_TOC)
+markdown-toc:
+	@if ! npm ls markdown-toc; then npm install; fi
 	@for f in $(ALL_DOCS); do \
 		if grep -q '<!-- tocstop -->' $$f; then \
 			echo markdown-toc: processing $$f; \
-			$(MARKDOWN_TOC) --no-first-h1 --no-stripHeadingTags -i $$f; \
+			npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
 		else \
 			echo markdown-toc: no TOC markers, skipping $$f; \
 		fi; \
 	done
 
-$(MARKDOWN_LINT):
-	npm install markdownlint-cli@0.31.0
-
 .PHONY: markdownlint
-markdownlint:	$(MARKDOWN_LINT)
-	@for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1;	done
+markdownlint:
+	@if ! npm ls markdownlint; then npm install; fi
+	@for f in $(ALL_DOCS); do \
+		echo $$f; \
+		npx --no -p markdownlint-cli markdownlint -c .markdownlint.yaml $$f \
+			|| exit 1; \
+	done
 
 .PHONY: install-yamllint
 install-yamllint:
@@ -99,7 +97,7 @@ check: misspell markdownlint markdown-link-check
 fix: table-generation misspell-correction
 	@echo "All autofixes complete"
 
-# Attempt to install all the tools
 .PHONY: install-tools
-install-tools: $(MISSPELL) $(MARKDOWN_LINT) $(MARKDOWN_LINK_CHECK) $(MARKDOWN_TOC)
+install-tools: $(MISSPELL)
+	npm install
 	@echo "All tools installed"

package.json

@@ -0,0 +1,7 @@
+{
+  "devDependencies": {
+    "markdown-link-check": "^3.9.3",
+    "markdown-toc": "^1.2.0",
+    "markdownlint-cli": "0.31.0"
+  }
+}