[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>

.github/workflows/checks.yaml

@@ -13,6 +13,9 @@ jobs:
     - name: check out code
       uses: actions/checkout@v2
 
+    - name: install dependencies
+      run: npm install
+
     - name: run markdownlint
       run: make markdownlint
 
@@ -36,6 +39,9 @@ jobs:
     - name: check out code
       uses: actions/checkout@v2
 
+    - name: install dependencies
+      run: npm install
+
     - name: run markdown-link-check
       run: make markdown-link-check
 
@@ -45,6 +51,9 @@ jobs:
     - name: check out code
       uses: actions/checkout@v2
 
+    - name: install dependencies
+      run: npm install
+
     - name: run markdown-toc
       run: make markdown-toc
 

CONTRIBUTING.md

@@ -42,7 +42,13 @@ one that is needlessly restrictive and complex.
 ### Consistency Checks
 
 The Specification has a number of tools it uses to check things like style,
-spelling and link validity. You can run all of these locally via:
+spelling and link validity. Before using the tools, run:
+
+```bash
+npm install
+```
+
+You can perform all checks locally using this command:
 
 ```bash
 make check
@@ -92,11 +98,10 @@ wide. There are tools that can do it for you effectively. Please submit proposal
 to include your editor settings required to enable this behavior so the out of
 the box settings for this repository will be consistent.
 
-To check for style violations, use
+To check for style violations, run:
 
 ```bash
-make install-markdownlint # install markdownlint if not installed
-make markdownlint # run at the root of the repo
+make markdownlint
 ```
 
 To fix style violations, follow the
@@ -109,14 +114,15 @@ you can also use the `fixAll` command of the
 
 In addition, please make sure to clean up typos before you submit the change.
 
-To check for typos, use
+To check for typos, run the following command:
 
 ```bash
-# Golang is needed for the misspell tool.
-make install-misspell
 make misspell
 ```
 
+> **NOTE**: The `misspell` make target will also fetch and build the tool if
+> necessary. You'll need [Go](https://go.dev) to build the spellchecker.
+
 To quickly fix typos, use
 
 ```bash

Makefile

@@ -5,17 +5,14 @@ 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!
 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"
+  }
+}