Skip to content

Commit 8545e4f

Browse files
author
Matthew
committed
Merge branch 'feat/make-docs-tool-versions' into 'main'
feat(makefile): add tool version report to make docs target See merge request orgdocs/development-standards!10
2 parents 9fafb56 + c79e811 commit 8545e4f

5 files changed

Lines changed: 197 additions & 21 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,13 @@ jobs:
3131
steps:
3232
- name: Checkout repository
3333
uses: actions/checkout@v4
34+
with:
35+
fetch-depth: 0
3436

3537
- name: Run gitleaks
36-
uses: gitleaks/gitleaks-action@v2
37-
env:
38-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
38+
run: |
39+
docker run --rm \
40+
-v "$(pwd):/workspace" \
41+
-w /workspace \
42+
ghcr.io/devrail-dev/dev-toolchain:v1 \
43+
gitleaks detect --source . --report-format json --report-path /tmp/gitleaks-results.json

‎dev-toolchain/Makefile‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -425,6 +425,7 @@ _scan: _check-config
425425
_docs: _check-config
426426
@start_time=$$(date +%s%3N); \
427427
overall_exit=0; \
428+
generators=""; \
428429
modules=""; \
429430
if [ -n "$(HAS_TERRAFORM)" ]; then \
430431
tf_dirs=$$(find . -name '*.tf' -not -path './.git/*' -not -path './.terraform/*' 2>/dev/null | xargs -I{} dirname {} | sort -u); \
@@ -433,18 +434,74 @@ _docs: _check-config
433434
terraform-docs markdown table --output-file README.md "$$dir" || overall_exit=1; \
434435
modules="$${modules}\"$$dir\","; \
435436
done; \
437+
generators="$${generators}\"terraform-docs\","; \
436438
else \
437439
echo '{"level":"info","msg":"skipping terraform-docs: no .tf files found","language":"terraform"}' >&2; \
438440
fi; \
439441
fi; \
442+
mkdir -p .devrail-output; \
443+
_sep=""; \
444+
_tv() { _out=$$(eval "$$2" 2>&1 | grep -oE '[0-9]+\.[0-9]+[^ ]*' | head -1); \
445+
[ -z "$$_out" ] && _out="unknown"; \
446+
printf '%s"%s":"%s"' "$$_sep" "$$1" "$$_out"; _sep=","; }; \
447+
{ \
448+
printf '{"generated_at":"%s","tools":{' "$$(date -u +%Y-%m-%dT%H:%M:%SZ)"; \
449+
if [ -n "$(HAS_PYTHON)" ]; then \
450+
_tv ruff "ruff --version"; \
451+
_tv bandit "bandit --version"; \
452+
_tv mypy "mypy --version"; \
453+
_tv pytest "pytest --version"; \
454+
_tv semgrep "semgrep --version"; \
455+
fi; \
456+
if [ -n "$(HAS_BASH)" ]; then \
457+
_tv shellcheck "shellcheck --version"; \
458+
_tv shfmt "shfmt --version"; \
459+
_tv bats "bats --version"; \
460+
fi; \
461+
if [ -n "$(HAS_TERRAFORM)" ]; then \
462+
_tv terraform "terraform version"; \
463+
_tv tflint "tflint --version"; \
464+
_tv tfsec "tfsec --version"; \
465+
_tv checkov "checkov --version"; \
466+
_tv terraform-docs "terraform-docs --version"; \
467+
fi; \
468+
if [ -n "$(HAS_ANSIBLE)" ]; then \
469+
_tv ansible-lint "ansible-lint --version"; \
470+
_tv molecule "molecule --version"; \
471+
fi; \
472+
if [ -n "$(HAS_RUBY)" ]; then \
473+
_tv rubocop "rubocop --version"; \
474+
_tv reek "reek --version"; \
475+
_tv brakeman "brakeman --version"; \
476+
_tv bundler-audit "bundler-audit --version"; \
477+
_tv rspec "rspec --version"; \
478+
_tv srb "srb --version"; \
479+
fi; \
480+
if [ -n "$(HAS_GO)" ]; then \
481+
_tv go "go version"; \
482+
_tv golangci-lint "golangci-lint version"; \
483+
_tv gofumpt "gofumpt --version"; \
484+
_tv govulncheck "govulncheck -version"; \
485+
fi; \
486+
if [ -n "$(HAS_JAVASCRIPT)" ]; then \
487+
_tv node "node --version"; \
488+
_tv npm "npm --version"; \
489+
_tv eslint "eslint --version"; \
490+
_tv prettier "prettier --version"; \
491+
_tv tsc "tsc --version"; \
492+
_tv vitest "vitest --version"; \
493+
fi; \
494+
_tv trivy "trivy --version"; \
495+
_tv gitleaks "gitleaks version"; \
496+
printf '}}\n'; \
497+
} > .devrail-output/tool-versions.json; \
498+
generators="$${generators}\"tool-versions\","; \
440499
end_time=$$(date +%s%3N); \
441500
duration=$$((end_time - start_time)); \
442-
if [ -z "$(HAS_TERRAFORM)" ]; then \
443-
echo "{\"target\":\"docs\",\"status\":\"skip\",\"reason\":\"no docs targets configured\",\"duration_ms\":$$duration}"; \
444-
elif [ $$overall_exit -eq 0 ]; then \
445-
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
501+
if [ $$overall_exit -eq 0 ]; then \
502+
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
446503
else \
447-
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
504+
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
448505
fi; \
449506
exit $$overall_exit
450507

‎github-repo-template/Makefile‎

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -416,10 +416,11 @@ _scan: _check-config
416416
fi; \
417417
exit $$overall_exit
418418

419-
# --- _docs: documentation generation (Story 3.4) ---
419+
# --- _docs: documentation generation ---
420420
_docs: _check-config
421421
@start_time=$$(date +%s%3N); \
422422
overall_exit=0; \
423+
generators=""; \
423424
modules=""; \
424425
if [ -n "$(HAS_TERRAFORM)" ]; then \
425426
tf_dirs=$$(find . -name '*.tf' -not -path './.git/*' -not -path './.terraform/*' 2>/dev/null | xargs -I{} dirname {} | sort -u); \
@@ -428,18 +429,74 @@ _docs: _check-config
428429
terraform-docs markdown table --output-file README.md "$$dir" || overall_exit=1; \
429430
modules="$${modules}\"$$dir\","; \
430431
done; \
432+
generators="$${generators}\"terraform-docs\","; \
431433
else \
432434
echo '{"level":"info","msg":"skipping terraform-docs: no .tf files found","language":"terraform"}' >&2; \
433435
fi; \
434436
fi; \
437+
mkdir -p .devrail-output; \
438+
_sep=""; \
439+
_tv() { _out=$$(eval "$$2" 2>&1 | grep -oE '[0-9]+\.[0-9]+[^ ]*' | head -1); \
440+
[ -z "$$_out" ] && _out="unknown"; \
441+
printf '%s"%s":"%s"' "$$_sep" "$$1" "$$_out"; _sep=","; }; \
442+
{ \
443+
printf '{"generated_at":"%s","tools":{' "$$(date -u +%Y-%m-%dT%H:%M:%SZ)"; \
444+
if [ -n "$(HAS_PYTHON)" ]; then \
445+
_tv ruff "ruff --version"; \
446+
_tv bandit "bandit --version"; \
447+
_tv mypy "mypy --version"; \
448+
_tv pytest "pytest --version"; \
449+
_tv semgrep "semgrep --version"; \
450+
fi; \
451+
if [ -n "$(HAS_BASH)" ]; then \
452+
_tv shellcheck "shellcheck --version"; \
453+
_tv shfmt "shfmt --version"; \
454+
_tv bats "bats --version"; \
455+
fi; \
456+
if [ -n "$(HAS_TERRAFORM)" ]; then \
457+
_tv terraform "terraform version"; \
458+
_tv tflint "tflint --version"; \
459+
_tv tfsec "tfsec --version"; \
460+
_tv checkov "checkov --version"; \
461+
_tv terraform-docs "terraform-docs --version"; \
462+
fi; \
463+
if [ -n "$(HAS_ANSIBLE)" ]; then \
464+
_tv ansible-lint "ansible-lint --version"; \
465+
_tv molecule "molecule --version"; \
466+
fi; \
467+
if [ -n "$(HAS_RUBY)" ]; then \
468+
_tv rubocop "rubocop --version"; \
469+
_tv reek "reek --version"; \
470+
_tv brakeman "brakeman --version"; \
471+
_tv bundler-audit "bundler-audit --version"; \
472+
_tv rspec "rspec --version"; \
473+
_tv srb "srb --version"; \
474+
fi; \
475+
if [ -n "$(HAS_GO)" ]; then \
476+
_tv go "go version"; \
477+
_tv golangci-lint "golangci-lint version"; \
478+
_tv gofumpt "gofumpt --version"; \
479+
_tv govulncheck "govulncheck -version"; \
480+
fi; \
481+
if [ -n "$(HAS_JAVASCRIPT)" ]; then \
482+
_tv node "node --version"; \
483+
_tv npm "npm --version"; \
484+
_tv eslint "eslint --version"; \
485+
_tv prettier "prettier --version"; \
486+
_tv tsc "tsc --version"; \
487+
_tv vitest "vitest --version"; \
488+
fi; \
489+
_tv trivy "trivy --version"; \
490+
_tv gitleaks "gitleaks version"; \
491+
printf '}}\n'; \
492+
} > .devrail-output/tool-versions.json; \
493+
generators="$${generators}\"tool-versions\","; \
435494
end_time=$$(date +%s%3N); \
436495
duration=$$((end_time - start_time)); \
437-
if [ -z "$(HAS_TERRAFORM)" ]; then \
438-
echo "{\"target\":\"docs\",\"status\":\"skip\",\"reason\":\"no docs targets configured\",\"duration_ms\":$$duration}"; \
439-
elif [ $$overall_exit -eq 0 ]; then \
440-
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
496+
if [ $$overall_exit -eq 0 ]; then \
497+
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
441498
else \
442-
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
499+
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
443500
fi; \
444501
exit $$overall_exit
445502

‎gitlab-repo-template/Makefile‎

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -416,10 +416,11 @@ _scan: _check-config
416416
fi; \
417417
exit $$overall_exit
418418

419-
# --- _docs: documentation generation (Story 3.4) ---
419+
# --- _docs: documentation generation ---
420420
_docs: _check-config
421421
@start_time=$$(date +%s%3N); \
422422
overall_exit=0; \
423+
generators=""; \
423424
modules=""; \
424425
if [ -n "$(HAS_TERRAFORM)" ]; then \
425426
tf_dirs=$$(find . -name '*.tf' -not -path './.git/*' -not -path './.terraform/*' 2>/dev/null | xargs -I{} dirname {} | sort -u); \
@@ -428,18 +429,74 @@ _docs: _check-config
428429
terraform-docs markdown table --output-file README.md "$$dir" || overall_exit=1; \
429430
modules="$${modules}\"$$dir\","; \
430431
done; \
432+
generators="$${generators}\"terraform-docs\","; \
431433
else \
432434
echo '{"level":"info","msg":"skipping terraform-docs: no .tf files found","language":"terraform"}' >&2; \
433435
fi; \
434436
fi; \
437+
mkdir -p .devrail-output; \
438+
_sep=""; \
439+
_tv() { _out=$$(eval "$$2" 2>&1 | grep -oE '[0-9]+\.[0-9]+[^ ]*' | head -1); \
440+
[ -z "$$_out" ] && _out="unknown"; \
441+
printf '%s"%s":"%s"' "$$_sep" "$$1" "$$_out"; _sep=","; }; \
442+
{ \
443+
printf '{"generated_at":"%s","tools":{' "$$(date -u +%Y-%m-%dT%H:%M:%SZ)"; \
444+
if [ -n "$(HAS_PYTHON)" ]; then \
445+
_tv ruff "ruff --version"; \
446+
_tv bandit "bandit --version"; \
447+
_tv mypy "mypy --version"; \
448+
_tv pytest "pytest --version"; \
449+
_tv semgrep "semgrep --version"; \
450+
fi; \
451+
if [ -n "$(HAS_BASH)" ]; then \
452+
_tv shellcheck "shellcheck --version"; \
453+
_tv shfmt "shfmt --version"; \
454+
_tv bats "bats --version"; \
455+
fi; \
456+
if [ -n "$(HAS_TERRAFORM)" ]; then \
457+
_tv terraform "terraform version"; \
458+
_tv tflint "tflint --version"; \
459+
_tv tfsec "tfsec --version"; \
460+
_tv checkov "checkov --version"; \
461+
_tv terraform-docs "terraform-docs --version"; \
462+
fi; \
463+
if [ -n "$(HAS_ANSIBLE)" ]; then \
464+
_tv ansible-lint "ansible-lint --version"; \
465+
_tv molecule "molecule --version"; \
466+
fi; \
467+
if [ -n "$(HAS_RUBY)" ]; then \
468+
_tv rubocop "rubocop --version"; \
469+
_tv reek "reek --version"; \
470+
_tv brakeman "brakeman --version"; \
471+
_tv bundler-audit "bundler-audit --version"; \
472+
_tv rspec "rspec --version"; \
473+
_tv srb "srb --version"; \
474+
fi; \
475+
if [ -n "$(HAS_GO)" ]; then \
476+
_tv go "go version"; \
477+
_tv golangci-lint "golangci-lint version"; \
478+
_tv gofumpt "gofumpt --version"; \
479+
_tv govulncheck "govulncheck -version"; \
480+
fi; \
481+
if [ -n "$(HAS_JAVASCRIPT)" ]; then \
482+
_tv node "node --version"; \
483+
_tv npm "npm --version"; \
484+
_tv eslint "eslint --version"; \
485+
_tv prettier "prettier --version"; \
486+
_tv tsc "tsc --version"; \
487+
_tv vitest "vitest --version"; \
488+
fi; \
489+
_tv trivy "trivy --version"; \
490+
_tv gitleaks "gitleaks version"; \
491+
printf '}}\n'; \
492+
} > .devrail-output/tool-versions.json; \
493+
generators="$${generators}\"tool-versions\","; \
435494
end_time=$$(date +%s%3N); \
436495
duration=$$((end_time - start_time)); \
437-
if [ -z "$(HAS_TERRAFORM)" ]; then \
438-
echo "{\"target\":\"docs\",\"status\":\"skip\",\"reason\":\"no docs targets configured\",\"duration_ms\":$$duration}"; \
439-
elif [ $$overall_exit -eq 0 ]; then \
440-
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
496+
if [ $$overall_exit -eq 0 ]; then \
497+
echo "{\"target\":\"docs\",\"status\":\"pass\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
441498
else \
442-
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"modules\":[$${modules%,}]}"; \
499+
echo "{\"target\":\"docs\",\"status\":\"fail\",\"duration_ms\":$$duration,\"generators\":[$${generators%,}],\"modules\":[$${modules%,}]}"; \
443500
fi; \
444501
exit $$overall_exit
445502

‎standards/makefile-contract.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Runs universal scanners that apply to every project regardless of language. Dele
5959

6060
#### `docs`
6161

62-
Generates documentation. Delegates to the container where `_docs` executes documentation generators like `terraform-docs` for Terraform modules.
62+
Generates documentation. Delegates to the container where `_docs` executes documentation generators. Runs `terraform-docs` for Terraform modules and generates a tool version report (`.devrail-output/tool-versions.json`) listing the versions of all tools available for the declared languages.
6363

6464
#### `check`
6565

0 commit comments

Comments
 (0)