Merge pull request #120 from JeremiahSanders/release/1.1.0

Release/1.1.0

.project-metadata.json

@@ -2,7 +2,7 @@
   "name": "cicee",
   "description": "Runs continuous integration workloads via docker-compose, locally or on a build server.",
   "title": "Continuous Integration Containerized Execution Environment (CICEE)",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "ciEnvironment": {
     "variables": [
       {

docs/use/ci-library.md

@@ -121,9 +121,18 @@ Once the CI library is loaded, the continuous integration execution environment
 
 All CI actions implicitly require this function to be executed. Its purpose is to provide a consistent execution environment for project-level activities. For example, by using a consistent `BUILD_PACKAGED_DIST` variable, CI actions creating an output zip file, NPM package, or APK can all place their artifacts in consistent locations.
 
+#### Initialization Overrides
+
+The following environment variables may be provided to override inferred configuration.
+
+* `PROJECT_METADATA` - Project metadata JSON file. Default: `${PROJECT_ROOT}/project-metadata.json` or `${PROJECT_ROOT}/package.json`
+* `PROJECT_ROOT` - Project root directory.
+
+#### Initialization Effect
+
 Expected environment available to all CI actions, after `ci-env-init` is executed:
 
-_Contextual_
+##### Contextual Environment Variables
 
 * `PROJECT_NAME` - Project name. By convention this should be in lower kebab case. I.e., multi-word-project-name. This will be used to pattern conventional output ths, e.g., as part of a zip archive file name.
 * `PROJECT_ROOT` - Project root directory.
@@ -136,7 +145,7 @@ _Contextual_
 * `CURRENT_GIT_BRANCH` - Current Git branch.
 * `CURRENT_GIT_HASH` - Current Git hash.
 
-_Configuration_
+##### Configuration Environment Variables
 
 The `CIENV_VARIABLES*` variables below are all derived from loading `.ciEnvironment.variables` JSON path from a project metadata file (if one exists) using `jq`.
 
@@ -145,7 +154,7 @@ The `CIENV_VARIABLES*` variables below are all derived from loading `.ciEnvironm
 * `CIENV_VARIABLES_REQUIRED` - Array of project-specific CI environment variable names which are marked required (by their .required JSON path property).
 * `CIENV_VARIABLES_SECRET` - Array of project-specific CI environment variable names which ARE marked secret (by their .secret JSON path property).
 
-_Conventional Output_
+##### Conventional Output Environment Variables
 
 * `BUILD_DOCS="${BUILD_ROOT}/docs"` - Project distributable documentation which would accompany packaged build output.
 * `BUILD_PACKAGED_DIST="${BUILD_ROOT}/dist"` - Project packaged build output. E.g., .NET NuGet packages, zip archives, AWS CDK cloud assemblies.
@@ -154,7 +163,7 @@ _Conventional Output_
 
 #### Initialization Workflow
 
-1. Initialize convention-based CI enviroment variables.
+1. Initialize convention-based CI environment variables.
 2. Attempt to load project metadata by convention.
     * Populates `PROJECT_NAME`, `PROJECT_TITLE`, and `PROJECT_VERSION` from JSON file. From "name", "title", and "version" properties, respectively.
     * Default location: `PROJECT_ROOT/project-metadata.json`

src/lib/ci/bash/actions/env.sh

@@ -24,6 +24,10 @@ set -o pipefail # Fail pipelines if any command errors, not just the last one.
 #   Design note: This function's name follows the CI workflow pattern because it is expected to be executed in a
 #                workflow entrypoint script.
 #
+# Optional initialization environment overrides:
+#   PROJECT_ROOT - Project root directory. Default: $(pwd)
+#   PROJECT_METADATA - Project metadata JSON file. Default: ${PROJECT_ROOT}/project-metadata.json | ${PROJECT_ROOT}/package.json
+#
 # Expected environment available to all CI actions, after ci-env-init is executed:
 #  - Contextual -
 #   PROJECT_NAME - Project name. By convention this should be in lower kebab case. I.e., multi-word-project-name. This will be used to pattern conventional output paths, e.g., as part of a zip archive file name.
@@ -46,7 +50,7 @@ set -o pipefail # Fail pipelines if any command errors, not just the last one.
 #   BUILD_UNPACKAGED_DIST="${BUILD_ROOT}/app" - Project unpackaged build output. E.g., processed output which might be further packaged or compressed before distribution. E.g., .NET DLLs, Java class files.
 #
 # Workflow:
-#   1 - Initialize convention-based CI enviroment variables.
+#   1 - Initialize convention-based CI environment variables.
 #   2 - Attempt to load project metadata by convention.
 #       Populates PROJECT_NAME, PROJECT_TITLE, and PROJECT_VERSION from JSON file. From "name", "title", and "version" properties, respectively.
 #       Default location: PROJECT_ROOT/project-metadata.json
@@ -76,6 +80,20 @@ function ci-env-init() {
     fi
   }
 
+  #----
+  # Find first file which exists.
+  #----
+  function __findFirstExistsFile() {
+    for fileName in "${@}"; do
+      if [[ -f "${fileName}" ]]; then
+        echo "${fileName}"
+        return 0
+      fi
+    done
+
+    return 1
+  }
+
   #----
   # Tries to source a project environment file.
   #----
@@ -215,13 +233,15 @@ function ci-env-init() {
       fi
     }
 
-    __loadMetadataFromFile "${PROJECT_ROOT}/project-metadata.json" ||
-      __loadMetadataFromFile "${PROJECT_ROOT}/.project-metadata.json" ||
-      __loadMetadataFromFile "${PROJECT_ROOT}/ci/project-metadata.json" ||
-      __loadMetadataFromFile "${PROJECT_ROOT}/ci/.project-metadata.json" ||
-      __loadMetadataFromFile "${PROJECT_ROOT}/package.json" ||
-      __loadMetadataFromFile "${PROJECT_ROOT}/src/package.json" ||
-      return 0
+    METADATA_FILE=$(
+      __findFirstExistsFile "${PROJECT_ROOT}/project-metadata.json" \
+        "${PROJECT_ROOT}/.project-metadata.json" \
+        "${PROJECT_ROOT}/ci/project-metadata.json" \
+        "${PROJECT_ROOT}/ci/.project-metadata.json" \
+        "${PROJECT_ROOT}/package.json" \
+        "${PROJECT_ROOT}/src/package.json"
+    )
+    __loadMetadataFromFile "${PROJECT_METADATA:-${METADATA_FILE}}" || return 0
   }
 
   #----