Add lint-custom check to CI with first check that ensures docs have a link to an upstream API

Author: armsnyder

.github/workflows/pr-lint.yml

@@ -32,6 +32,7 @@ jobs:
           - lint-examples-tf
           - lint-examples-sh
           - lint-generated
+          - lint-custom
     steps:
       - uses: actions/setup-go@v2
         with:

.github/workflows/push.yml

@@ -44,6 +44,7 @@ jobs:
           - lint-examples-tf
           - lint-examples-sh
           - lint-generated
+          - lint-custom
     steps:
       - uses: actions/setup-go@v2
         with:

GNUmakefile

@@ -51,6 +51,9 @@ lint-generated: generate ## Check that "make generate" was called. Note this onl
 		exit 1; \
 	}
 
+lint-custom: ## Run custom checks and validations that do not fit into an existing lint framework.
+	@./scripts/lint-custom.sh
+
 apicovered: tool-apicovered ## Run an analysis tool to estimate the GitLab API coverage.
 	@$(GOBIN)/apicovered ./gitlab
 

scripts/lint-custom.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+
+# This script is run during the CI workflow in order to run additional custom checks and validations
+# that do not fit into an existing lint framework.
+#
+# This script uses GitHub workflow commands in order to add contextual error messages:
+#   https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message
+#
+# Usage:
+#   ./scripts/lint-custom.sh
+
+has_failure=''
+
+pattern="^\*\*Upstream API\*\*: \[.*\](.*)$"
+files_without_match="$(grep --recursive --files-without-match "$pattern" ./docs/resources ./docs/data-sources)"
+test -z "$files_without_match" || {
+    has_failure='true'
+    echo "$files_without_match" | xargs -I{} echo "::error file={}::Generated documentation file {} should reference an upstream GitLab API. Expected file to match regex \"$pattern\"."
+}
+
+# ^^^ Add new checks above this line ^^^
+
+test -z "$has_failure"