feat: Reports

.github/README.md

@@ -0,0 +1,59 @@
+# GitHub Workflows Overview
+
+This repository contains several GitHub Actions workflows that automate various processes, including building, testing, versioning, and releasing your project. Below is an overview of each workflow and how they contribute to the release process.
+
+## Workflows
+
+### 1. `prepare-release.yml`
+
+This workflow is responsible for versioning and preparing releases based on pull request labels.
+
+- **Trigger**: Runs on pull request reviews that are approved.
+- **Version Bump**: Determines the version bump type (major, minor, patch) based on PR labels. If an `alpha` label is present, it creates a prerelease version.
+- **Versioning**: Uses `yarn version` to update the version in `package.json`.
+- **Outputs**: Provides the version type and alpha status for subsequent workflows.
+
+- **Alpha Versioning**: When a PR includes the `alpha` label, versions are created with an `-alpha.N` suffix (e.g., `1.2.3-alpha.1`, `1.2.3-alpha.2`). This continues until the alpha label is removed, at which point the version returns to standard semantic versioning.
+
+
+### 2. `build-test-report.yml`
+
+This workflow handles building, testing, and reporting.
+
+- **Trigger**: Runs on pull requests and pushes to the `main` branch.
+- **Build and Test**: Installs dependencies, builds the project, and runs tests.
+- **Reporting**: Uploads test results and coverage reports to Codecov.
+
+### 3. `naming-conventions.yml`
+
+This workflow ensures that pull request titles and labels follow specific conventions.
+
+- **Trigger**: Runs on various pull request events (opened, edited, labeled, etc.).
+- **Title Check**: Validates PR titles against the Conventional Commits specification.
+- **Label Check**: Ensures PRs have one of the required labels (major, minor, patch, no-release).
+- **Comments**: Adds or removes comments on PRs based on title and label validation results.
+
+### 4. `create-release.yml`
+
+This workflow creates a draft release on GitHub when a new version is detected in `package.json` on the `main` branch.
+
+- **Trigger**: Runs on pushes to the `main` branch.
+- **Version Check**: Verifies if the version in `package.json` has been updated.
+- **Draft Release**: Creates a draft release with the new version tag if the version check is successful.
+
+### 5. `publish-release.yml`
+
+This workflow handles the publishing of releases to NPM.
+
+- **Trigger**: Runs when a release is published on GitHub.
+- **Build and Publish**: Checks out the code, installs dependencies, builds the project, and publishes it to NPM.
+- **Provenance**: Uses `npm publish` with provenance for security.
+
+## Release Process
+
+1. **Versioning**: The `prepare-release.yml` workflow determines the version bump based on PR labels after a review has been approved. If a PR is labeled with `major`, `minor`, or `patch`, the version is updated accordingly. If labeled with `alpha`, a prerelease version is created.
+
+2. **Draft Release Creation**: The `create-release.yml` workflow creates a draft release if `package.json` contains a new version on the `main` branch.
+
+3. **Publishing**: When a release is published on GitHub (moved from draft to released), the `publish-release.yml` workflow is triggered. It builds the project and publishes it to NPM, ensuring the package is available for public use.
+

.github/ci-scripts/check-version-bump.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Get the current version from package.json
+current_version=$(node -p "require('./package.json').version")
+
+# Get the previous version from the last commit
+previous_version=$(git show HEAD~1:package.json | node -p "JSON.parse(require('fs').readFileSync(0, 'utf-8')).version")
+
+# Compare the versions
+if [ "$current_version" != "$previous_version" ]; then
+  echo "Version has been bumped from $previous_version to $current_version."
+  exit 0
+else
+  echo "Version has not been bumped."
+  exit 1
+fi

.github/ci-scripts/toggle-alpha.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Read the current version from package.json
+current_version=$(node -p "require('./package.json').version")
+
+# Check if version contains alpha
+if [[ "$current_version" == *"-alpha"* ]]; then
+  if [[ "$1" != "yes" ]]; then
+    # Remove alpha if present and "yes" is not passed
+    new_version="${current_version%%-alpha*}"
+  else
+    # Keep the current version if "yes" is passed
+    new_version="${current_version}"
+  fi
+elif [[ "$1" == "yes" ]]; then
+  # Add alpha if not present and "yes" was passed
+  new_version="${current_version}-alpha"
+else
+  # Keep current version if no alpha and no "yes" passed
+  new_version="${current_version}"
+fi
+
+# Update the package.json with the new version
+node -e "
+  let pkg = require('./package.json');
+  pkg.version = '$new_version';
+  require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
+"
+
+echo "Updated version to $new_version"

.github/workflows/build-test-report.yml

@@ -5,6 +5,9 @@ on:
   pull_request:
     branches:
       - main
+  push:
+    branches:
+      - main
 
 jobs:
   build-n-test:

.github/workflows/create-release.yml

@@ -0,0 +1,32 @@
+name: Release and Versioning
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Highly security sensitive. Do NOT add third party actions in this job
+    steps:    
+    - uses: actions/checkout@v4
+      with:       
+        fetch-depth: 2 # Need at least 2 commits to compare versions
+
+    - name: Check if version was bumped
+      id: version_check
+      run: |
+        ./.github/ci-scripts/check-version-bump.sh
+
+    - name: Create GitHub Release   
+      if: success() && steps.version_check.outcome == 'success'
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        VERSION=$(node -p "require('./package.json').version")
+        gh release create "v${VERSION}" \
+          --title "Release v${VERSION}" \
+          --generate-notes \
+          --prerelease \
+          --draft

.github/workflows/naming-conventions.yml

@@ -7,24 +7,24 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      pull-requests: read
     steps:
       - name: Check PR Title follows conventional commit naming
         id: check-pr-naming
         uses: amannn/action-semantic-pull-request@v5
-        continue-on-error: true
+        # continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           # https://www.conventionalcommits.org/en/v1.0.0/
-          ignoreLabels: |
-            skip-ci
           requireScope: false
-          wip: true
-          validateSingleCommit: false
 
       - uses: docker://agilepathway/pull-request-label-checker:v1.6.56
+        # continue-on-error: true
         # https://github.com/agilepathway/label-checker
         id: check-pr-labels
         with:
-          one_of: major,minor,patch,no-release
+          one_of: major,minor,patch,no-release,alpha
           repo_token: ${{ secrets.GITHUB_TOKEN }}
 
     outputs:
@@ -34,6 +34,7 @@ jobs:
 
   handle-comments:
     runs-on: ubuntu-latest
+    if: always()
     needs: title-n-label-check
     permissions:
       pull-requests: write
@@ -58,7 +59,7 @@ jobs:
         with:
           issue-number: ${{ github.event.pull_request.number }}
           comment-author: 'github-actions[bot]'
-          body-includes: PR must have at least one of the following labels
+          body-includes: PR must have ONLY one of the following labels
 
       - name: Add PR naming error comment
         id: pr-title-error
@@ -100,7 +101,8 @@ jobs:
           issue-number: ${{ github.event.pull_request.number }}
           comment-id: ${{ steps.find-label-comment.outputs.comment-id }}
           body: |
-            PR must have at least one of the following labels: major, minor, patch.
+            PR must have ONLY one of the following labels: major, minor, patch, no-release, alpha.
+            Check the logs for more details: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
           edit-mode: replace
         if: needs.title-n-label-check.outputs.labels_valid != 'success'
 

.github/workflows/prepare-release.yml

@@ -1,18 +1,31 @@
-name: Release and Versioning
+name: Package version bump
 on:
+  pull_request_review:
+    types: [submitted]  
   pull_request:
-    types: [closed]
-    branches:
-      - main
+    paths:
+      - '.github/workflows/prepare-release.yml'
 
 jobs:
-  get_version:
-    if: github.event.pull_request.merged == true
+  bump-version:
     runs-on: ubuntu-latest
+    if: github.event.review.state == 'approved'
+    permissions:
+      contents: write # Highly security sensitive. Do NOT add third party actions in this job
+      pull-requests: read
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref || github.ref_name }}          
+          fetch-depth: 0 # https://yarnpkg.com/features/release-workflow#caveat
 
-      - uses: actions/setup-node@v4
+      - name: Show current branch
+        run: |
+          echo "Current branch: $(git branch --show-current)"
+          echo "Current commit: $(git rev-parse HEAD)"
+          git log --oneline -5          
+
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af #@v4
         with:
           node-version: '20'
 
@@ -22,7 +35,7 @@ jobs:
       - name: Set Yarn version
         run: yarn set version 4.5.0
 
-      - name: Get version bump type from labels
+      - name: Check PR version labels
         id: bump
         run: |
           # Check for version type labels
@@ -39,6 +52,7 @@ jobs:
           # Check for alpha label
           if ${{ contains(github.event.pull_request.labels.*.name, 'alpha') }}; then
             echo "alpha=true" >> $GITHUB_OUTPUT
+            echo "type=prerelease" >> $GITHUB_OUTPUT
           else
             echo "alpha=false" >> $GITHUB_OUTPUT
           fi
@@ -47,55 +61,29 @@ jobs:
         id: cancel
         if: steps.bump.outputs.type == 'no-release'
         run: |
-          echo "No version bump required. Exiting successfully."
-          exit 0
-        continue-on-error: true
+          echo "::warning::No version bump required. Skipping release steps."
 
-      - name: Configure Git
-        if: steps.cancel.outcome == 'success'
-        run: |
-          git config --global user.name 'GitHub Action'
-          git config --global user.email '[email protected]'
-
-      - name: Bump version
-        if: steps.cancel.outcome == 'success'
+      - name: Toggle Alpha
+        if: steps.bump.outputs.type != 'no-release'
         run: |
           if [ "${{ steps.bump.outputs.alpha }}" == "true" ]; then
-            yarn version --${{ steps.bump.outputs.type }} --preid alpha
+            ./.github/ci-scripts/toggle-alpha.sh yes
           else
-            yarn version --${{ steps.bump.outputs.type }}
+            ./.github/ci-scripts/toggle-alpha.sh #remove alpha if present
           fi
 
+      - name: Bump version
+        if: steps.bump.outputs.type != 'no-release'
+        run: yarn version ${{ steps.bump.outputs.type }}
+
       - name: Push changes
-        if: steps.cancel.outcome == 'success'
+        if: steps.bump.outputs.type != 'no-release'     
         run: |
+          VERSION=$(node -p "require('./package.json').version")
+          git config user.name "GitHub Actions"
+          git config user.email "[email protected]"          
+          git add package.json
+          git commit -am "chore:Bump version to ${VERSION}"
           git push
-          git push --tags
-    outputs:
-      type: ${{ steps.bump.outputs.type }}
-      alpha: ${{ steps.bump.outputs.alpha }}
 
-  create-release:
-    needs: get_version
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    if: needs.get_version.outputs.type != 'no-release'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: main
-
-      - name: Create GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          if ${{ contains(github.event.pull_request.labels.*.name, 'alpha') }}; then
-            VERSION="${VERSION}-alpha"
-          fi
-          gh release create "v${VERSION}" \
-            --title "Release v${VERSION}" \
-            --generate-notes \
-            --prerelease \
-            --draft
+

.gitignore

@@ -12,16 +12,19 @@ dist
 
 # Yarn
 yarn-error.log
-.yarn
+.yarn/*
 !.yarn/releases
 !.yarn/plugins
 !.yarn/sdks
 !.yarn/versions
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
 
 .env
 
 # Tests and coverage
 coverage/
 test-results.xml
 .nyc_output
-report/
+report/

.mocharc

@@ -0,0 +1,10 @@
+{
+  "extension": [
+    "ts"
+  ],
+  "node-option": [
+    "experimental-specifier-resolution=node",
+    "loader=ts-node/esm"
+  ],
+  "spec": "src/**/*.test.ts"
+}