feat: Provide error messages as outputs.error_message (#194)

.github/workflows/lint-pr-title-preview-outputErrorMessage

@@ -0,0 +1,44 @@
+name: "Lint PR title preview (current branch, outputErrorMessage)"
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+      - run: yarn install
+      - run: yarn build
+      - uses: ./
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: marocchino/sticky-pull-request-comment@v2
+        # When the previous steps fails, the workflow would stop. By adding this
+        # condition you can continue the execution with the populated error message.
+        if: always()
+        with:
+          header: pr-title-lint-error
+          message: |
+            Hey there and thank you for opening this pull request! 👋🏼
+
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+
+            Details:
+
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:   
+          header: pr-title-lint-error
+          delete: true

README.md

@@ -113,6 +113,62 @@ There are two events that can be used as triggers for this action, each with dif
 1. [`pull_request_target`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target): This allows the action to be used in a fork-based workflow, where e.g. you want to accept pull requests in a public repository. In this case, the configuration from the main branch of your repository will be used for the check. This means that you need to have this configuration in the main branch for the action to run at all (e.g. it won't run within a PR that adds the action initially). Also if you change the configuration in a PR, the changes will not be reflected for the current PR – only subsequent ones after the changes are in the main branch.
 2. [`pull_request`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request): This configuration uses the latest configuration that is available in the current branch. It will only work if the branch is based in the repository itself. If this configuration is used and a pull request from a fork is opened, you'll encounter an error as the GitHub token environment parameter is not available. This option is viable if all contributors have write access to the repository.
 
+## Outputs
+
+In case the validation fails, this action will populate the `error_message` ouput.
+
+[An output can be used in other steps](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs), for example to comment the error message onto the pull request.
+
+<details>
+<summary>Example</summary>
+
+```yml
+name: "Lint PR"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v4
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: marocchino/sticky-pull-request-comment@v2
+        # When the previous steps fails, the workflow would stop. By adding this
+        # condition you can continue the execution with the populated error message.
+        if: always()
+        with:
+          header: pr-title-lint-error
+          message: |
+            Hey there and thank you for opening this pull request! 👋🏼
+            
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+
+            Details:
+            
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:   
+          header: pr-title-lint-error
+          delete: true
+```
+
+</details>
+
 ## Legacy configuration
 
 When using "Squash and merge" on a PR with only one commit, GitHub will suggest using that commit message instead of the PR title for the merge commit and it's easy to commit this by mistake. To help out in this situation this action supports two configuration options. However, [GitHub has introduced an option to streamline this behaviour](https://github.blog/changelog/2022-05-11-default-to-pr-titles-for-squash-merge-commit-messages/), so using that instead should be preferred.

src/validatePrTitle.js

@@ -1,3 +1,4 @@
+const core = require('@actions/core');
 const conventionalCommitsConfig = require('conventional-changelog-conventionalcommits');
 const conventionalCommitTypes = require('conventional-commit-types');
 const parser = require('conventional-commits-parser').sync;
@@ -52,30 +53,29 @@ module.exports = async function validatePrTitle(
   }
 
   if (!result.type) {
-    throw new Error(
+    raiseError(
       `No release type found in pull request title "${prTitle}". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/\n\n${printAvailableTypes()}`
     );
   }
 
   if (!result.subject) {
-    throw new Error(`No subject found in pull request title "${prTitle}".`);
+    raiseError(`No subject found in pull request title "${prTitle}".`);
   }
 
   if (!types.includes(result.type)) {
-    throw new Error(
+    raiseError(
       `Unknown release type "${
         result.type
       }" found in pull request title "${prTitle}". \n\n${printAvailableTypes()}`
     );
   }
 
   if (requireScope && !result.scope) {
-    let msg = `No scope found in pull request title "${prTitle}".`;
+    let message = `No scope found in pull request title "${prTitle}".`;
     if (scopes) {
-      msg += ` Use one of the available scopes: ${scopes.join(', ')}.`;
+      message += ` Use one of the available scopes: ${scopes.join(', ')}.`;
     }
-
-    throw new Error(msg);
+    raiseError(message);
   }
 
   const givenScopes = result.scope
@@ -84,7 +84,7 @@ module.exports = async function validatePrTitle(
 
   const unknownScopes = givenScopes ? givenScopes.filter(isUnknownScope) : [];
   if (scopes && unknownScopes.length > 0) {
-    throw new Error(
+    raiseError(
       `Unknown ${
         unknownScopes.length > 1 ? 'scopes' : 'scope'
       } "${unknownScopes.join(
@@ -99,7 +99,7 @@ module.exports = async function validatePrTitle(
     ? givenScopes.filter(isDisallowedScope)
     : [];
   if (disallowScopes && disallowedScopes.length > 0) {
-    throw new Error(
+    raiseError(
       `Disallowed ${
         disallowedScopes.length === 1 ? 'scope was' : 'scopes were'
       } found: ${disallowScopes.join(', ')}`
@@ -113,8 +113,7 @@ module.exports = async function validatePrTitle(
         title: prTitle
       });
     }
-
-    throw new Error(message);
+    raiseError(message);
   }
 
   if (subjectPattern) {
@@ -133,4 +132,10 @@ module.exports = async function validatePrTitle(
       );
     }
   }
+
+  function raiseError(message) {
+    core.setOutput('error_message', message);
+
+    throw new Error(message);
+  }
 };