chore: Document functions (based on google style guide) (#317)

hooks/_common.sh

@@ -1,13 +1,29 @@
 #!/usr/bin/env bash
 set -eo pipefail
 
+#######################################################################
+# Init arguments parser
+# Arguments:
+#   script_dir - absolute path to hook dir location
+#######################################################################
 function common::initialize {
   local -r script_dir=$1
   # source getopt function
-  # shellcheck source=lib_getopt
+  # shellcheck source=../lib_getopt
   . "$script_dir/../lib_getopt"
 }
 
+#######################################################################
+# Parse args and filenames passed to script and populate respective
+# global variables with appropriate values
+# Globals (init and populate):
+#   ARGS (array) arguments that configure wrapped tool behavior
+#   HOOK_CONFIG (array) arguments that configure hook behavior
+#   FILES (array) filenames to check
+# Arguments:
+#   $@ (array) all specified in `hooks.[].args` in
+#     `.pre-commit-config.yaml` and filenames.
+#######################################################################
 function common::parse_cmdline {
   # common global arrays.
   # Populated via `common::parse_cmdline` and can be used inside hooks' functions
@@ -39,6 +55,17 @@ function common::parse_cmdline {
   done
 }
 
+#######################################################################
+# Hook execution boilerplate logic which is common to hooks, that run
+# on per dir basis.
+# 1. Because hook runs on whole dir, reduce file paths to uniq dir paths
+# 2. Run for each dir `per_dir_hook_unique_part`, on all paths
+# 2.1. If at least 1 check failed - change exit code to non-zero
+# 3. Complete hook execution and return exit code
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   files (array) filenames to check
+#######################################################################
 function common::per_dir_hook {
   local -r args="$1"
   shift 1
@@ -82,6 +109,16 @@ function common::per_dir_hook {
   exit $final_exit_code
 }
 
+#######################################################################
+# Colorize provided string and print it out to stdout
+# Environment variables:
+#   PRE_COMMIT_COLOR (string) If set to `never` - do not colorize output
+# Arguments:
+#   COLOR (string) Color name that will be used to colorize
+#   TEXT (string)
+# Outputs:
+#   Print out provided text to stdout
+#######################################################################
 function common::colorify {
   # shellcheck disable=SC2034
   local -r red="\e[0m\e[31m"

hooks/infracost_breakdown.sh

@@ -13,6 +13,18 @@ function main {
   infracost_breakdown_ "${HOOK_CONFIG[*]}" "${ARGS[*]}"
 }
 
+#######################################################################
+# Wrapper around `infracost breakdown` tool which checks and compares
+# infra cost based on provided hook_config
+# Environment variables:
+#   PRE_COMMIT_COLOR (string) If set to `never` - do not colorize output
+# Arguments:
+#   hook_config (string with array) arguments that configure hook behavior
+#   args (string with array) arguments that configure wrapped tool behavior
+# Outputs:
+#   Print out hook checks status (Passed/Failed), total monthly cost and
+#   diff, summary about infracost check (non-supported resources etc.)
+#######################################################################
 function infracost_breakdown_ {
   local -r hook_config="$1"
   local args

hooks/terraform_docs.sh

@@ -17,6 +17,14 @@ function main {
   terraform_docs_ "${HOOK_CONFIG[*]}" "$ARGS" "${FILES[@]}"
 }
 
+#######################################################################
+# Function which prepares hacks for old versions of `terraform` and
+# `terraform-docs` that them call `terraform_docs`
+# Arguments:
+#   hook_config (string with array) arguments that configure hook behavior
+#   args (string with array) arguments that configure wrapped tool behavior
+#   files (array) filenames to check
+#######################################################################
 function terraform_docs_ {
   local -r hook_config="$1"
   local -r args="$2"
@@ -61,6 +69,18 @@ function terraform_docs_ {
   fi
 }
 
+#######################################################################
+# Wrapper around `terraform-docs` tool that check and change/create
+# (depends on provided hook_config) terraform documentation in
+# markdown format
+# Arguments:
+#   terraform_docs_awk_file (string) filename where awk hack for old
+#     `terraform-docs` was written. Needed for TF 0.12+.
+#     Hack skipped when `terraform_docs_awk_file == "0"`
+#   hook_config (string with array) arguments that configure hook behavior
+#   args (string with array) arguments that configure wrapped tool behavior
+#   files (array) filenames to check
+#######################################################################
 function terraform_docs {
   local -r terraform_docs_awk_file="$1"
   local -r hook_config="$2"
@@ -183,6 +203,12 @@ function terraform_docs {
   done
 }
 
+#######################################################################
+# Function which creates file with `awk` hacks for old versions of
+# `terraform-docs`
+# Arguments:
+#   output_file (string) filename where hack will be written to
+#######################################################################
 function terraform_docs_awk {
   local -r output_file=$1
 

hooks/terraform_fmt.sh

@@ -13,6 +13,19 @@ function main {
   terraform_fmt_ "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Hook execution boilerplate logic which is common to hooks, that run
+# on per dir basis. Little bit extended than `common::per_dir_hook`
+# 1. Because hook runs on whole dir, reduce file paths to uniq dir paths
+# (unique) 1.1. Collect paths to *.tfvars files in a separate variable
+# 2. Run for each dir `per_dir_hook_unique_part`, on all paths
+# (unique) 2.1. Run `terraform fmt` on each *.tfvars file
+# 2.2. If at least 1 check failed - change exit code to non-zero
+# 3. Complete hook execution and return exit code
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   files (array) filenames to check
+#######################################################################
 function terraform_fmt_ {
   local -r args="$1"
   shift 1
@@ -72,8 +85,17 @@ function terraform_fmt_ {
 
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   local -r dir_path="$2"
 

hooks/terraform_providers_lock.sh

@@ -14,8 +14,17 @@ function main {
   common::per_dir_hook "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   local -r dir_path="$2"
 

hooks/terraform_tflint.sh

@@ -17,8 +17,17 @@ function main {
   common::per_dir_hook "$ARGS" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   local -r dir_path="$2"
 

hooks/terraform_tfsec.sh

@@ -16,8 +16,17 @@ function main {
   common::per_dir_hook "$ARGS" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   # shellcheck disable=SC2034 # Unused var.
   local -r dir_path="$2"

hooks/terraform_validate.sh

@@ -15,6 +15,19 @@ function main {
   terraform_validate_
 }
 
+#######################################################################
+# Parse args and filenames passed to script and populate respective
+# global variables with appropriate values
+# Globals (init and populate):
+#   ARGS (array) arguments that configure wrapped tool behavior
+#   INIT_ARGS (array) arguments to `terraform init` command
+#   ENVS (array) environment variables that will be used with
+#     `terraform` commands
+#   FILES (array) filenames to check
+# Arguments:
+#   $@ (array) all specified in `hooks.[].args` in
+#     `.pre-commit-config.yaml` and filenames.
+#######################################################################
 function parse_cmdline_ {
   declare argv
   argv=$(getopt -o e:i:a: --long envs:,init-args:,args: -- "$@") || return
@@ -46,6 +59,24 @@ function parse_cmdline_ {
   done
 }
 
+#######################################################################
+# Wrapper around `terraform validate` tool that checks if code is valid
+# 1. Export provided env var K/V pairs to environment
+# 2. Because hook runs on whole dir, reduce file paths to uniq dir paths
+# 3. In each dir that have *.tf files:
+# 3.1. Check if `.terraform` dir exists and if not - run `terraform init`
+# 3.2. Run `terraform validate`
+# 3.3. If at least 1 check failed - change exit code to non-zero
+# 4. Complete hook execution and return exit code
+# Globals:
+#   ARGS (array) arguments that configure wrapped tool behavior
+#   INIT_ARGS (array) arguments for `terraform init` command`
+#   ENVS (array) environment variables that will be used with
+#     `terraform` commands
+#   FILES (array) filenames to check
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function terraform_validate_ {
 
   # Setup environment variables

hooks/terragrunt_fmt.sh

@@ -13,8 +13,17 @@ function main {
   common::per_dir_hook "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   # shellcheck disable=SC2034 # Unused var.
   local -r dir_path="$2"

hooks/terragrunt_validate.sh

@@ -13,8 +13,17 @@ function main {
   common::per_dir_hook "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   # shellcheck disable=SC2034 # Unused var.
   local -r dir_path="$2"

hooks/terrascan.sh

@@ -13,8 +13,17 @@ function main {
   common::per_dir_hook "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Unique part of `common::per_dir_hook`. The function is executed in loop
+# on each provided dir path. Run wrapped tool with specified arguments
+# Arguments:
+#   args (string with array) arguments that configure wrapped tool behavior
+#   dir_path (string) PATH to dir relative to git repo root.
+#     Can be used in error logging
+# Outputs:
+#   If failed - print out hook checks status
+#######################################################################
 function per_dir_hook_unique_part {
-  # common logic located in common::per_dir_hook
   local -r args="$1"
   # shellcheck disable=SC2034 # Unused var.
   local -r dir_path="$2"