feat: new RC011 testing for usage example updates (#231)

* feat: new RC011 testing for usage example updates

* chore: re-trigger

* fix: add missing orb name parameter

* fix: backwards syntax

* fix: formatting

* chore: format document

* fix: resolve RC011 errors

* fix: incorrect RC check

* chore: wording

* fix: wording

* feat: make parameter optional

* chore: wording

.circleci/config.yml

@@ -19,6 +19,7 @@ workflows:
       - orb-tools-alpha/pack:
           filters: *filters
       - orb-tools-alpha/review:
+          orb_name: orb-tools-alpha
           filters: *filters
       - shellcheck/check:
           filters: *filters

.circleci/test-deploy.yml

@@ -14,6 +14,7 @@ workflows:
       - orb-tools-alpha/pack:
           filters: *filters
       - orb-tools-alpha/review:
+          orb_name: <orb name>
           filters: *filters
       - orb-tools-alpha/publish:
           name: publish_dev_test

src/examples/step1_lint-pack.yml

@@ -24,6 +24,7 @@ usage:
               tags:
                 only: /.*/
         - orb-tools/review:
+            orb_name: <orb name>
             filters:
               tags:
                 only: /.*/

src/jobs/review.yml

@@ -14,6 +14,12 @@ parameters:
     description: Path to the orb source. Path must be absolute or relative to the working directory.
     type: string
     default: src
+  orb_name:
+    type: string
+    default: ""
+    description: |
+      The reference name of the orb to be injected in the config, no namespace or version number. e.g. "orb-tools".
+      This is required for RC011. RC011 will be skipped if this is not set.
   max_command_length:
     description: |
       The maximum length of a command (RC009).
@@ -46,6 +52,7 @@ steps:
         ORB_VAL_MAX_COMMAND_LENGTH: <<parameters.max_command_length>>
         ORB_VAL_REVIEW_BATS_FILE: <<include(scripts/review.bats)>>
         ORB_VAL_SOURCE_DIR: << parameters.source_dir >>
+        ORB_VAL_ORB_NAME: <<parameters.orb_name>>
       command: <<include(scripts/review.sh)>>
   - store_test_results:
       path: /tmp/orb_dev_kit/review/

src/scripts/review.bats

@@ -1,7 +1,7 @@
 setup() {
-    ORB_DEFAULT_SRC_DIR="./src/"
-    ORB_SOURCE_DIR=${ORB_VAL_SOURCE_DIR:-$ORB_DEFAULT_SRC_DIR}
-		ORB_SOURCE_DIR=${ORB_SOURCE_DIR%/}
+	ORB_DEFAULT_SRC_DIR="./src/"
+	ORB_SOURCE_DIR=${ORB_VAL_SOURCE_DIR:-$ORB_DEFAULT_SRC_DIR}
+	ORB_SOURCE_DIR=${ORB_SOURCE_DIR%/}
 	IFS="," read -ra SKIPPED_REVIEW_CHECKS <<<"${ORB_VAL_RC_EXCLUDE}"
 }
 
@@ -202,11 +202,11 @@ setup() {
 			exit 1
 		fi
 
-        # Check if the file has parameters, if not skip counting.
-        HAS_PARAMETERS=$(yq 'has("parameters")' "$i")
-        if [[ "$HAS_PARAMETERS" == "false" ]]; then
-            continue
-        fi
+		# Check if the file has parameters, if not skip counting.
+		HAS_PARAMETERS=$(yq 'has("parameters")' "$i")
+		if [[ "$HAS_PARAMETERS" == "false" ]]; then
+			continue
+		fi
 
 		# Check parameter keys on component for snake_case
 		ORB_COMPONENT_PARAMETERS_COUNT=$(yq '.parameters | keys | .[]' "$i")
@@ -221,3 +221,46 @@ setup() {
 
 	done
 }
+
+@test "RC011: Ensure usage examples showcase current major version of the orb." {
+	if [[ "${SKIPPED_REVIEW_CHECKS[*]}" =~ "RC011" ]]; then
+		skip
+	fi
+
+	if [[ -z "$ORB_VAL_ORB_NAME" ]]; then
+		echo "Orb name not set. Skipping usage example check."
+		skip
+	fi
+
+	if [[ -z "$CIRCLE_TAG" ]]; then
+		echo "No tag detected. Skipping usage example check."
+		skip
+	fi
+
+	if [[ ! "$CIRCLE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+		echo "Non-production tag detected. Skipping usage example check."
+		skip
+	fi
+
+	CURRENT_MAJOR_VERSION=$(echo "${CIRCLE_TAG#v}" | cut -d '.' -f 1)
+
+	for i in $(find "${ORB_SOURCE_DIR}/examples" -name "*.yml" -type f); do
+		ORB_REF_STRING=$(yq ".usage.orbs[\"${ORB_VAL_ORB_NAME}\"]" "$i")
+		ORB_REF_VERSION_STRING=$(echo "$ORB_REF_STRING" | cut -d '@' -f 2)
+		ORB_REF_MAJOR_VERSION=$(echo "$ORB_REF_VERSION_STRING" | cut -d '.' -f 1)
+
+		if [[ "$ORB_REF_MAJOR_VERSION" != "$CURRENT_MAJOR_VERSION" ]]; then
+			echo "File: \"${i}\""
+			echo "Usage example Orb version: \"${ORB_REF_VERSION_STRING}\""
+			echo "Current major version: \"${CURRENT_MAJOR_VERSION}\""
+			echo "Usage examples should showcase at least the current major version of the orb."
+			echo ""
+			echo "Steps to resolve:"
+			echo "  1. Delete the release and tag from your git repository which triggered this pipeline."
+			echo "  2. Update all of the orb usage examples to ensure they match the next major version of the orb."
+			echo "  3. Re-tag and release the orb to re-trigger the pipeline"
+
+			exit 1
+		fi
+	done
+}