feat(terraform_providers_lock): Fix logical issue in hook modes: Add check-lockfile-is-cross-platform and regenerate-lockfile-if-some-platform-missed modes. Last one is same as only-check-is-current-lockfile-cross-platform, which now is deprecated. Check README for more details (#950)

---------

Co-authored-by: George Yermulnik (Georgii Iermulnik) <yz@yz.kiev.ua>

Author: MaxymVlasov

README.md

@@ -759,26 +759,44 @@ To replicate functionality in `terraform_docs` hook:
 >   - --hook-config=--mode=always-regenerate-lockfile
 > ```
 >
-> Why? When v2.x will be introduced - the default mode will be changed, probably, to `only-check-is-current-lockfile-cross-platform`.
+> Why? When v2.x will be introduced - the default mode will be changed, probably, to `check-lockfile-is-cross-platform`.
 >
 > You can check available modes for hook below.
 > </details>
 
 
-1. The hook can work in a few different modes: `only-check-is-current-lockfile-cross-platform` with and without [terraform_validate hook](#terraform_validate) and `always-regenerate-lockfile` - only with terraform_validate hook.
+1. The hook can work in a few different modes:
 
-    * `only-check-is-current-lockfile-cross-platform` without terraform_validate - only checks that lockfile has all required SHAs for all providers already added to lockfile.
+    1. <details><summary><code>--mode=check-lockfile-is-cross-platform</code> (standalone)</summary>
+        Checks that lockfile has the same number of platform checksums (`h1:`) as requested by the hook configuration. It **does not** check whether these checksums are valid or that they match target platforms.
 
         ```yaml
         - id: terraform_providers_lock
           args:
-          - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
+          - --hook-config=--mode=check-lockfile-is-cross-platform
         ```
 
-    * `only-check-is-current-lockfile-cross-platform` with [terraform_validate hook](#terraform_validate) - make up-to-date lockfile by adding/removing providers and only then check that lockfile has all required SHAs.
+    </details>
+
+    2. <details><summary><code>--mode=regenerate-lockfile-if-some-platform-missed</code> (standalone)</summary>
+
+        Checks that lockfile has checksums (`h1:`) for all requested platforms for all providers tracked by the lockfile, and if any are missed - tries to add them (but could fail if `terraform init` wasn't run previously).
+
+
+        ```yaml
+        - id: terraform_providers_lock
+          args:
+          - --hook-config=--mode=regenerate-lockfile-if-some-platform-missed
+        ```
+
+    </details>
+
+    3. <details><summary><code>--mode=regenerate-lockfile-if-some-platform-missed</code> with <code>terraform_validate</code> hook</summary>
+
+        Regenerates lockfile for all required providers and checks that the lockfile tracks all required platform checksums (`h1:`) afterwards. If any are missed - adds them; superfluous providers are removed.
 
         > **Important**
-        > Next `terraform_validate` flag requires additional dependency to be installed: `jq`. Also, it could run another slow and time consuming command - `terraform init`
+        > The following [`terraform_validate`](#terraform_validate) hook's flag requires additional dependency to be installed: [`jq`](https://github.com/jqlang/jq). Also, it could run another slow and time consuming command - `terraform init`
 
         ```yaml
         - id: terraform_validate
@@ -787,10 +805,14 @@ To replicate functionality in `terraform_docs` hook:
 
         - id: terraform_providers_lock
           args:
-          - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
+          - --hook-config=--mode=regenerate-lockfile-if-some-platform-missed
         ```
 
-    * `always-regenerate-lockfile` only with [terraform_validate hook](#terraform_validate) - regenerate lockfile from scratch. Can be useful for upgrading providers in lockfile to latest versions
+    </details>
+
+    4. <details><summary><code>always-regenerate-lockfile</code> - meant to be used only along with <code>terraform_validate</code> hook</summary>
+
+        Regenerates lockfile from the scratch. May be useful for upgrading providers in the lockfile to the latest versions.
 
         ```yaml
         - id: terraform_validate
@@ -803,6 +825,8 @@ To replicate functionality in `terraform_docs` hook:
           - --hook-config=--mode=always-regenerate-lockfile
         ```
 
+    </details>
+
 2. `terraform_providers_lock` supports custom arguments:
 
     ```yaml

hooks/terraform_providers_lock.sh

@@ -101,9 +101,11 @@ function per_dir_hook_unique_part {
   local -a -r args=("$@")
 
   local platforms_count=0
+  local platforms_names=()
   for arg in "${args[@]}"; do
     if grep -Eq '^-platform=' <<< "$arg"; then
       platforms_count=$((platforms_count + 1))
+      platforms_names+=("${arg#*=}")
     fi
   done
 
@@ -121,44 +123,84 @@ function per_dir_hook_unique_part {
     key=${config[0]}
     value=${config[1]}
 
-    case $key in
+    case "$key" in
       --mode)
         if [ "$mode" ]; then
-          common::colorify "yellow" 'Invalid hook config. Make sure that you specify not more than one "--mode" flag'
+          common::colorify "yellow" 'Invalid hook config. Make sure that you specify not more than one "--mode" flag.'
           exit 1
         fi
         mode=$value
+
+        case "$mode" in
+          check-lockfile-is-cross-platform) ;;
+          regenerate-lockfile-if-some-platform-missed) ;;
+          always-regenerate-lockfile) ;;
+
+          only-check-is-current-lockfile-cross-platform)
+            common::colorify "yellow" "DEPRECATION NOTICE: Flag '--mode=only-check-is-current-lockfile-cross-platform' was renamed to '--mode=regenerate-lockfile-if-some-platform-missed' to better reflect its behavior.
+Please update your configuration."
+            mode="regenerate-lockfile-if-some-platform-missed"
+            ;;
+          *)
+            common::colorify "red" "Invalid hook config. Supported --mode values are:
+  - check-lockfile-is-cross-platform
+  - regenerate-lockfile-if-some-platform-missed
+  - always-regenerate-lockfile"
+            exit 1
+            ;;
+        esac
         ;;
     esac
   done
 
   # Available options:
-  #   only-check-is-current-lockfile-cross-platform (will be default)
+  #   check-lockfile-is-cross-platform (will be default in v2.0)
+  #   regenerate-lockfile-if-some-platform-missed
   #   always-regenerate-lockfile
   # TODO: Remove in 2.0
   if [ ! "$mode" ]; then
     common::colorify "yellow" "DEPRECATION NOTICE: We introduced '--mode' flag for this hook.
-Check migration instructions at https://github.com/antonbabenko/pre-commit-terraform#terraform_providers_lock
-"
+Check migration instructions at https://github.com/antonbabenko/pre-commit-terraform#terraform_providers_lock"
     common::terraform_init "$tf_path providers lock" "$dir_path" "$parallelism_disabled" "$tf_path" || {
       exit_code=$?
       return $exit_code
     }
   fi
 
-  if [ "$mode" == "only-check-is-current-lockfile-cross-platform" ] &&
-    lockfile_contains_all_needed_sha "$platforms_count"; then
+  case "$mode" in
+    "check-lockfile-is-cross-platform")
+      if lockfile_contains_all_needed_sha "$platforms_count"; then
+        exit 0
+      fi
 
-    exit 0
-  fi
+      common::colorify "red" "$dir_path/.terraform.lock.hcl missing some of required platforms.
+All required platforms: ${platforms_names[*]}"
+
+      exit 1
+      ;;
+    "regenerate-lockfile-if-some-platform-missed")
+      if lockfile_contains_all_needed_sha "$platforms_count"; then
+        exit 0
+      fi
+
+      common::colorify "yellow" "$dir_path/.terraform.lock.hcl missing some of required platforms.
+All required platforms: ${platforms_names[*]}"
+
+      ;;
+  esac
 
   #? Don't require `tf init` for providers, but required `tf init` for modules
   #? Mitigated by `function match_validate_errors` from terraform_validate hook
   # pass the arguments to hook
   "$tf_path" providers lock "${args[@]}"
 
-  # return exit code to common::per_dir_hook
   exit_code=$?
+  if [[ $exit_code -ne 0 ]]; then
+    common::colorify "red" "$dir_path run failed. Detailed error above.
+Most common issue is that required 'terraform init' command was likely not run before running this hook. It might be run for you automatically by 'terraform_validate' hook - see https://github.com/antonbabenko/pre-commit-terraform#terraform_validate for more details."
+  fi
+
+  # return exit code to common::per_dir_hook
   return $exit_code
 }