Vendor project shell libs

Vendor project shell libs so that they can be used within the project to
facilitate automated testing, etc. especially within the git-ps
lifecycle hooks.

skip_ticket_id_check

<!-- ps-id: 58c01cf6-182f-4572-b8d0-f35ca5b58bce -->

.git-ps/vendor/libs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Uptech Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.git-ps/vendor/libs/README.md

@@ -0,0 +1,44 @@
+# project-shell-libs
+
+Collection of various shell libs that we use with our various projects to facilate scripting, especially when creating git-ps-rs hooks.
+
+This collection includes the following libraries.
+
+* `ticket_id_verification.zsh` - facilitate verifying that a commit message contains a ticket identifier
+* `messaging.zsh` - facilitate semantically styled messaging, e.g. `good_msg()`, `warning_msg()`, `bad_msg()`
+* `lcov_test_coverage.zsh` - facilitate extracting test coverage values from `lcov.info` report
+* `git.zsh` - facilitate interacting with Git in various ways, e.g. `get_current_commit_sha()`, `get_uncommitted_files_count()`, etc.
+* `git_backend_test_coverage.zsh` - facilitate storing & syncing test coverage values in the Git repositories key/value store while also supporting evaluating test coverage relative to previous commits test coverage
+* `general.zsh` - general utilities, e.g. `exit_nonzero()` to exit non zero with a semantic message, `exit_if_cmd_missing()` abort with semantic message if requried command is missing, `current_git_commit_message_contains()` check if current Git commit contains a value
+* `fvm.zsh` - allow us to support FVM and non-FVM users by providing an `fvm` proxy function to handle both cases
+
+It also contains the following scripts to aid in debugging around the functionality of these libraries.
+
+* `echo_lcov_test_coverage` - prints out the current test coverage value obtained from the `lcov.info` report using `lcov_test_coverage.zsh`
+* `list_historic_code_coverage` - fetch code coverage data from Git repo, iterate over all the commits between HEAD and the SHA, the first and only argument, and show the code coverage for each commit
+* `show_commit_code_coverage` - obtains and prints test coverage for the given SHA using `git_backend_test_coverage.zsh`
+
+This repository also contains [Git Patch Stack - Hooks](https://book.git-ps.sh/tool/hooks.html) examples within the `hooks` folder.
+
+* `sample_flutter_integrate_post_push` - example `integrate_post_push` hook for a Flutter application
+* `sample_flutter_isolate_post_checkout` - example `isolate_post_checkout` hook for a Flutter application
+* `sample_ts_backend_integrate_post_push` - example `integrate_post_push` hook for a TypeScript Backend application
+* `sample_ts_backend_isolate_post_checkout` - example `isolate_post_checkout` hook for a TypeScript Backend application
+* `sample_ts_backend_isolate_post_cleanup` - example `isolate_post_cleanup` hook for a TypeScript Backend application
+* `sample_ts_library_isolate_post_checkout` - exmaple `isolate_post_checkout` hook for a TypeScript library
+
+## Initial Setup
+
+Run the following to initially setup the project shell library directory structure.
+
+```
+mkdir -p .git-ps/vendor
+```
+
+## Install/Update
+
+Run the following to install/update the project shell libraries and git-ps-rs hook examples.
+
+```
+rm -rf .git-ps/vendor/libs && git clone --depth 1 git@github.com:uptech/jumpstart_project_shell_libs.git .git-ps/vendor/libs && rm -rf .git-ps/vendor/libs/.git
+```

.git-ps/vendor/libs/echo_lcov_test_coverage

@@ -0,0 +1,14 @@
+#!/usr/bin/env zsh
+
+libs_path=${0:a:h}
+
+source "$libs_path/lcov_test_coverage.zsh"
+
+coverage=$(get_current_lcov_test_coverage)
+retval=$?
+if [ $retval -eq 0 ]; then
+  echo "Current Test Coverage: ${coverage}"
+else
+  echo "Failed to get current test coverage. ${coverage}"
+  exit 1
+fi

.git-ps/vendor/libs/fvm_patch.zsh

@@ -0,0 +1,17 @@
+
+# This is a patch to add the fvm function if fvm isn't found. This effectively
+# allows us to support fvm users and non-fvm users by the fvm() stub function
+# just proxying to the flutter command.
+
+# Patch for us non-fvm peasants
+if ! command -v fvm &> /dev/null
+then
+  fvm() {
+    # Starts with flutter
+    if [[ $@ == flutter* ]]; then
+      command $@
+    else
+      command echo "fvm is for flutter only"
+    fi
+  }
+fi

.git-ps/vendor/libs/general.zsh

@@ -0,0 +1,48 @@
+
+libs_path=${0:a:h}
+
+source "$libs_path/messaging.zsh"
+source "$libs_path/git.zsh"
+
+# Display the given <msg> as a failure message & exit the script with the
+# given <exit-code> if the provided <result-to-evaluate> is NOT 0.
+#
+# usage: exit_nonzero <result-to-evaluate> <msg> <exit-code>
+exit_nonzero() {
+  result_to_evaluate=$1
+  msg=$2
+  exit_code=$3
+  if [ $result_to_evaluate -ne 0 ]; then
+    bad_msg ${msg}
+    exit ${exit_code}
+  fi
+}
+
+current_git_commit_message_contains() {
+  keyword=$1
+  message=$(get_current_commit_message)
+  if [ $? -ne 0 ]; then
+    return 2
+  fi
+
+  grep_output=$(echo $message | grep $keyword)
+  if [ $? -ne 0 ]; then
+    return 1
+  fi
+
+  return 0
+}
+
+# Exit if the specified command is missing
+#
+# usage: exit_if_cmd_missing <cmd-name> <err-msg> <exit-code>
+exit_if_cmd_missing() {
+	cmd_name=$1
+	err_msg=$2
+	exit_code=$3
+	which_output=$(which $cmd_name)
+	if [ $? -ne 0 ]; then
+		echo $err_msg
+		exit $exit_code
+	fi
+}

.git-ps/vendor/libs/git.zsh

@@ -0,0 +1,55 @@
+
+# usage: get_uncommitted_files_count
+# $?: 0 on success, 1 on failure
+# stdout: on success, the number of uncommited files with changes
+get_uncommitted_files_count() {
+  count=`git status --porcelain=v1 2>/dev/null | wc -l`
+  if [ $? -ne 0 ]; then
+    return 1
+  fi
+  echo -n $count
+  return 0
+}
+
+# usage: get_current_commit_message
+# $?: 0 on success, 1 on failure
+# stdout: on success, the commit message
+get_current_commit_message() {
+  message=$(git --no-pager log -1 --pretty=%B)
+  if [ $? -ne 0 ]; then
+    echo $message
+    return 1
+  fi
+  echo $message
+  return 0
+}
+
+# usage: get_current_commit_sha
+# $?: return code, 0 = success, non-zero = failure
+# stdout: sha of current commmit when command is successful, message explaining error when not successful
+get_current_commit_sha() {
+  sha=$(git rev-parse HEAD)
+  retval=$?
+  if [ $retval -ne 0 ]; then
+    echo "failed to get current commit sha - git rev-parse HEAD exited with ${retval}"
+    return 1
+  fi
+  echo $sha
+  return 0
+}
+
+# usage: get_parent_commit_sha "<commit-sha>"
+# $?: return code, 0 = success, non-zero = failure
+# stdout: sha of current commmit when command is successful, message explaining error when not successful
+get_parent_commit_sha() {
+  current_sha=$1
+  parent_sha=$(git rev-parse ${current_sha}^)
+  retval=$?
+  if [ $retval -ne 0 ]; then
+    echo "failed to get parent commit sha - git rev-parse ${current_sha} exited with ${retval}"
+    return 1
+  fi
+
+  echo $parent_sha
+  return 0
+}