Updated workflow for publishing documentation

cowwoc · Jan 1, 2025 · 7fc7f1f · 7fc7f1f
1 parent baaf4d1
commit 7fc7f1f
Show file tree

Hide file tree

Showing 9 changed files with 93 additions and 68 deletions.
diff --git a/.github/workflows/deploy_to_npm.yml b/.github/workflows/deploy_to_npm.yml
@@ -6,15 +6,15 @@ concurrency:
   cancel-in-progress: true
 permissions:
   contents: write
+  pages: write
   id-token: write
 
 jobs:
   open-release:
     name: Open release
     runs-on: ubuntu-latest
     outputs:
-      INITIAL_MASTER_POSITION: ${{ steps.create-tag.outputs.INITIAL_MASTER_POSITION }}
-      INITIAL_GH_PAGES_POSITION: ${{ steps.create-tag.outputs.INITIAL_GH_PAGES_POSITION }}
+      INITIAL_MAIN_POSITION: ${{ steps.create-tag.outputs.INITIAL_MAIN_POSITION }}
       TAG: ${{ steps.create-tag.outputs.TAG }}
       VERSION: ${{ steps.create-tag.outputs.VERSION }}
     steps:
@@ -37,7 +37,7 @@ jobs:
       - name: Create tag
         id: create-tag
         run: |
-          echo "INITIAL_MASTER_POSITION=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          echo "INITIAL_MAIN_POSITION=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           VERSION=${{ steps.parse-version.outputs.current-version }}
           TAG=release-${VERSION}
           echo "TAG=${TAG}" >> "$GITHUB_OUTPUT"
@@ -91,6 +91,43 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Generate documentation
+        run: |
+          VERSION=${{ needs.open-release.outputs.VERSION }}
+          rm -rf "docs/api/${VERSION}"
+          mkdir --parents "docs/api/${VERSION}"
+          mv target/apidocs/* "docs/api/${VERSION}"
+
+      - name: Commit documentation
+        run: |
+          git checkout ${{ github.ref_name }} -f
+          git add "docs/api/${{ needs.open-release.outputs.VERSION }}"
+          git commit -m "Committing documentation for version ${{ needs.open-release.outputs.VERSION }}"
+          git push
+
+  document:
+    name: Document
+    needs: deploy
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "docs/api"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+
       - name: Publish documentation
         run: |
           git checkout gh-pages -f
@@ -104,7 +141,7 @@ jobs:
   # Cleanup on failure: https://stackoverflow.com/a/74562058/14731
   on-failure:
     name: On failure
-    needs: [ open-release, deploy ]
+    needs: [ open-release, deploy, document ]
     runs-on: ubuntu-latest
     if: ${{ failure() || cancelled() }}
     steps:
@@ -130,12 +167,12 @@ jobs:
         with:
           cache: pnpm
 
-      - name: Restore the master ref to its original position
-        if: needs.open-release.outputs.INITIAL_MASTER_POSITION != ''
+      - name: Restore the main ref to its original position
+        if: needs.open-release.outputs.INITIAL_MAIN_POSITION != ''
         run: |
           CURRENT_REF_POSITION=$(git rev-parse HEAD)
-          if [ "${CURRENT_REF_POSITION}" != "${{ needs.open-release.outputs.INITIAL_MASTER_POSITION }}" ]; then
-            git reset --hard ${{ needs.open-release.outputs.INITIAL_MASTER_POSITION }}
+          if [ "${CURRENT_REF_POSITION}" != "${{ needs.open-release.outputs.INITIAL_MAIN_POSITION }}" ]; then
+            git reset --hard ${{ needs.open-release.outputs.INITIAL_MAIN_POSITION }}
             if [ "${{ github.ref_type }}" == "tag" ]; then
               git ${{ github.ref_type }} -f ${{ github.ref_name }}
             fi
@@ -145,16 +182,4 @@ jobs:
       - name: Delete tag
         if: needs.open-release.outputs.TAG != ''
         run: |
-          git push --delete origin ${{ needs.open-release.outputs.TAG }}
-
-      - name: Restore the gh-pages ref to its original position
-        if: needs.open-release.outputs.INITIAL_GH_PAGES_POSITION != ''
-        run: |
-          CURRENT_REF_POSITION=$(git rev-parse HEAD)
-          if [ "${CURRENT_REF_POSITION}" != "${{ needs.open-release.outputs.INITIAL_GH_PAGES_POSITION }}" ]; then
-            git reset --hard ${{ needs.open-release.outputs.INITIAL_GH_PAGES_POSITION }}
-            if [ "${{ github.ref_type }}" == "tag" ]; then
-              git ${{ github.ref_type }} -f ${{ github.ref_name }}
-            fi
-            git push -f origin ${{ github.ref_name }}
-          fi
+          git push --delete origin ${{ needs.open-release.outputs.TAG }}
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 [![npm version](https://badge.fury.io/js/%40cowwoc%2Frequirements.svg)](https://badge.fury.io/js/%40cowwoc%2Frequirements)
 [![build-status](https://github.com/cowwoc/requirements.js/workflows/Build/badge.svg)](https://github.com/cowwoc/requirements.js/actions?query=workflow%3ABuild)
 
-# <img src="https://raw.githubusercontent.com/cowwoc/requirements.js/release-4.0.8/docs/checklist.svg?sanitize=true" width=64 height=64 alt="checklist"> Requirements API
+# <img src="https://raw.githubusercontent.com/cowwoc/requirements.js/release-4.0.9/docs/checklist.svg?sanitize=true" width=64 height=64 alt="checklist"> Requirements API
 
-[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.js/4.0.9/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/Changelog.md)
 [![java](https://img.shields.io/badge/other%20languages-java-457FD5.svg)](../../../requirements.java)
 
@@ -18,13 +18,13 @@ A [fluent API](https://en.m.wikipedia.org/docs/Fluent_interface) for enforcing
 To get started, add this dependency:
 
 ```shell
-npm install --save @cowwoc/[email protected].8
+npm install --save @cowwoc/[email protected].9
 ```
 
 or [pnpm](https://pnpm.io/):
 
 ```shell
-pnpm add @cowwoc/[email protected].8
+pnpm add @cowwoc/[email protected].9
 ```
 
 ## Usage Example
@@ -147,32 +147,32 @@ Designed for discovery using your favorite IDE's auto-complete feature.
 The main entry points are:
 
 * `requireThat(value, name)` for method preconditions.
-  * [requireThat(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThat.html)
-  * [requireThatArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatArray.html)
-  * [requireThatBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatBoolean.html)
-  * [requireThatMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatMap.html)
-  * [requireThatNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatNumber.html)
-  * [requireThatSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatSet.html)
-  * [requireThatString(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.requireThatString.html)
+  * [requireThat(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThat.html)
+  * [requireThatArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatArray.html)
+  * [requireThatBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatBoolean.html)
+  * [requireThatMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatMap.html)
+  * [requireThatNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatNumber.html)
+  * [requireThatSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatSet.html)
+  * [requireThatString(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.requireThatString.html)
 * `assertThat(value, name)` for [class invariants, method postconditions and private methods](docs/Features.md#assertion-support).
-  * [assertThat(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThat.html)
-  * [assertThatArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatArray.html)
-  * [assertThatBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatBoolean.html)
-  * [assertThatMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatMap.html)
-  * [assertThatNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatNumber.html)
-  * [assertThatSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatSet.html)
-  * [assertThatString(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.assertThatString.html)
+  * [assertThat(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThat.html)
+  * [assertThatArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatArray.html)
+  * [assertThatBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatBoolean.html)
+  * [assertThatMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatMap.html)
+  * [assertThatNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatNumber.html)
+  * [assertThatSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatSet.html)
+  * [assertThatString(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.assertThatString.html)
 * `checkIf(value, name)` for multiple failures and customized error handling.
-  * [checkIf(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIf.html)
-  * [checkIfArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfArray.html)
-  * [checkIfBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfBoolean.html)
-  * [checkIfMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfMap.html)
-  * [checkIfNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfNumber.html)
-  * [checkIfSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfSet.html)
-  * [checkIfString(value, name)](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/functions/DefaultJavascriptValidators.checkIfString.html)
+  * [checkIf(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIf.html)
+  * [checkIfArray(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfArray.html)
+  * [checkIfBoolean(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfBoolean.html)
+  * [checkIfMap(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfMap.html)
+  * [checkIfNumber(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfNumber.html)
+  * [checkIfSet(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfSet.html)
+  * [checkIfString(value, name)](https://cowwoc.github.io/requirements.js/4.0.9/functions/DefaultJavascriptValidators.checkIfString.html)
 
 
-See the [API documentation](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/) for more details.
+See the [API documentation](https://cowwoc.github.io/requirements.js/4.0.9/) for more details.
 
 ## Best practices
 

diff --git a/docs/Features.md b/docs/Features.md
@@ -99,7 +99,7 @@ requireThat(nameToAge, "nameToAge").
 ## String diff
 
 When
-a [String comparison](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/ObjectVerifier.html#isEqualTo)
+a [String comparison](https://cowwoc.github.io/requirements.js/4.0.9/interfaces/DefaultJavascriptValidators._internal_.ValidatorComponent.html#isEqualTo)
 fails, the library outputs a diff of the values being compared.
 
 Depending on the terminal capability, you will see a [textual](Textual_Diff.md) or a colored diff.

diff --git a/docs/String_Diff.md b/docs/String_Diff.md
@@ -1,5 +1,5 @@
 When
-a [String comparison](https://cowwoc.github.io/requirements.js/4.0.8/docs/api/ObjectVerifier.html#isEqualTo)
+a [String comparison](https://cowwoc.github.io/requirements.js/4.0.9/interfaces/DefaultJavascriptValidators._internal_.ValidatorComponent.html#isEqualTo)
 fails, the library outputs a [diff](https://en.wikipedia.org/wiki/Diff) of the values being compared.
 
 Depending on the terminal capability, you will see a [Textual](Textual_Diff.md) or [Colored](Colored_Diff.md)

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@cowwoc/requirements",
-	"version": "4.0.8",
+	"version": "4.0.9",
 	"keywords": [
 		"preconditions",
 		"postconditions",

diff --git a/src/DefaultJavascriptValidators.mts b/src/DefaultJavascriptValidators.mts
@@ -44,7 +44,7 @@ const DELEGATE = new JavascriptValidatorsImpl(MainApplicationScope.INSTANCE, Con
  * @typeParam T - the type the value
  * @param value - the value
  * @param name - the name of the value
- * @returns a verifier
+ * @returns a validator for the value
  * @throws TypeError  if `name` is `undefined` or `null`
  * @throws RangeError if `name` is empty
  */
@@ -62,7 +62,7 @@ function requireThatNumber<T extends number | undefined | null>
  * @typeParam T - the type the value
  * @param value - the value
  * @param name - the name of the value
- * @returns a verifier
+ * @returns a validator for the value
  * @throws TypeError  if `name` is `undefined` or `null`
  * @throws RangeError if `name` is empty
  */

diff --git a/src/internal/validator/JavascriptValidatorsImpl.mts b/src/internal/validator/JavascriptValidatorsImpl.mts
@@ -97,7 +97,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam T - the type the value
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -116,7 +116,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam T - the type the value
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -136,7 +136,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam E - the type elements in the array
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -156,7 +156,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam E - the type elements in the set
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -177,7 +177,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam V - the type of values in the map
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -196,7 +196,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam T - the type the value
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */
@@ -215,7 +215,7 @@ class JavascriptValidatorsImpl extends AbstractValidators<JavascriptValidators>
 	 * @typeParam T - the type the value
 	 * @param value - the value
 	 * @param name - the name of the value
-	 * @returns a verifier
+	 * @returns a validator for the value
 	 * @throws TypeError  if `name` is `undefined` or `null`
 	 * @throws RangeError if `name` is empty
 	 */

diff --git a/src/internal/validator/Terminal.mts b/src/internal/validator/Terminal.mts
@@ -96,7 +96,7 @@ Actual: ${String(chalk.level)}`);
 	}
 
 	/**
-	 * Indicates that verifiers should output the best encoding supported by the terminal.
+	 * Indicates that validators should output the best encoding supported by the terminal.
 	 *
 	 * @see Terminal.setEncoding
 	 */

diff --git a/src/validator/component/ValidatorComponent.mts b/src/validator/component/ValidatorComponent.mts
@@ -33,7 +33,7 @@ interface ValidatorComponent<T>
 	 * Returns the value that is being validated.
 	 *
 	 * @returns the value
-	 * @throws RangeError if the value is invalid (e.g. due to dereferencing a property of a `null` object)
+	 * @throws RangeError if the value is invalid (e.g. due to dereferencing a property of a `null` value)
 	 */
 	getValue(): T;
 
@@ -42,7 +42,7 @@ interface ValidatorComponent<T>
 	 *
 	 * @param defaultValue - the fallback value to use if the value is invalid
 	 * @returns the validated value, or `defaultValue` if the value is invalid (e.g. due to dereferencing a
-	 *   property of a `null` object)
+	 *   property of a `null` value)
 	 */
 	getValueOrDefault(defaultValue: T): T;
 
@@ -178,7 +178,7 @@ interface ValidatorComponent<T>
 	isNotNull(): UnknownValidator<NonNullable<T>>;
 
 	/**
-	 * Ensures that the object is an instance of a class.
+	 * Ensures that the value is an instance of a class.
 	 *
 	 * @typeParam U - the desired class
 	 * @param expected - the desired class
@@ -198,7 +198,7 @@ interface ValidatorComponent<T>
 	isType(expected: Type): this;
 
 	/**
-	 * Ensures that the object is not an instance of a class.
+	 * Ensures that the value is not an instance of a class.
 	 *
 	 * @param unwanted - the unwanted class
 	 * @returns this
@@ -208,7 +208,7 @@ interface ValidatorComponent<T>
 	isNotInstanceOf<U extends object>(unwanted: ClassConstructor<U>): this;
 
 	/**
-	 * Ensures that the object is equal to `expected`.
+	 * Ensures that the value is equal to `expected`.
 	 *
 	 * @param expected - the expected value
 	 * @returns this
@@ -219,7 +219,7 @@ interface ValidatorComponent<T>
 	isEqualTo(expected: unknown): this;
 
 	/**
-	 * Ensures that the object is equal to `expected`.
+	 * Ensures that the value is equal to `expected`.
 	 *
 	 * @param expected - the expected value
 	 * @param name     - the name of the expected value
@@ -241,7 +241,7 @@ interface ValidatorComponent<T>
 	isEqualTo(expected: unknown, name: string): this;
 
 	/**
-	 * Ensures that the object is not equal to `unwanted`.
+	 * Ensures that the value is not equal to `unwanted`.
 	 *
 	 * @param unwanted - the unwanted value
 	 * @returns this
@@ -252,7 +252,7 @@ interface ValidatorComponent<T>
 	isNotEqualTo(unwanted: unknown): this;
 
 	/**
-	 * Ensures that the object is not equal to `unwanted`.
+	 * Ensures that the value is not equal to `unwanted`.
 	 *
 	 * @param unwanted - the unwanted value
 	 * @param name     - the name of the other value
-Original file line number
+Diff line change
@@ Expand Up / @@ -96,7 +96,7 @@ Actual: ${String(chalk.level)}`); @@
     	}
     	/**
-    	 * Indicates that verifiers should output the best encoding supported by the terminal.
+    	 * Indicates that validators should output the best encoding supported by the terminal.
     	 *
     	 * @see Terminal.setEncoding
     	 */
@@ Expand Down @@