feat: add PR comment for scope check failures

Updates the PR scope check CI to post a comment on the pull request when the scope validation fails.

The comment details:
- If the PR title format is incorrect (missing scope).
- Which scopes are missing from the PR title based on changed files.

This provides immediate feedback to the PR author, making it easier to correct the PR title.

Also ensures README.md is correctly created and updated with this new behavior.

Author: google-labs-jules[bot]

.github/workflows/check_pr_scope.yml

@@ -7,6 +7,8 @@ on:
 jobs:
   check_scope:
     runs-on: ubuntu-latest
+    outputs: # Define outputs for the job
+      outcome: ${{ steps.check_scope_step.outcome }}
     steps:
       - uses: actions/checkout@v3
         with:
@@ -25,6 +27,7 @@ jobs:
           echo "EOF" >> $GITHUB_OUTPUT
 
       - name: Check PR scope
+        id: check_scope_step # Add id to this step
         run: |
           pr_title="${{ steps.pr_title.outputs.title }}"
           changed_files="${{ steps.changed_files.outputs.files }}"
@@ -40,7 +43,10 @@ jobs:
           pr_scopes=($(for scope in "${pr_scopes[@]}"; do echo "$scope" | xargs; done))
 
           if [ ${#pr_scopes[@]} -eq 0 ] && [[ "$pr_scopes_str" != "*" ]]; then
-            echo "::error::PR title does not contain a valid scope."
+            error_message="PR title does not contain a valid scope. Please use the format 'type(scope): message' or 'type(*): message'."
+            echo "::error::$error_message"
+            comment_body="**Scope Check Failed!** 🚨\n\n${error_message}\n\nExample: \`feat(my-scope): add new feature\` or \`fix(*): resolve an issue\`."
+            echo "comment_body=$comment_body" >> $GITHUB_ENV
             exit 1
           fi
           echo "PR Scopes: ${pr_scopes[@]}"
@@ -107,7 +113,38 @@ jobs:
 
           if [ ${#missing_scopes[@]} -gt 0 ]; then
             echo "::error::PR title scopes do not cover all changed files. Missing scopes for: ${missing_scopes[@]}"
+            # Prepare message for PR comment
+            comment_body="**Scope Check Failed!** 🚨\n\nPR title scopes do not cover all changed files.\n\n"
+            comment_body+="Missing required scopes in PR title: \`${missing_scopes[@]}\`\n\n"
+            comment_body+="Please update your PR title to include these scopes. For example: \`type(${pr_scopes_str:+${pr_scopes_str},}${missing_scopes[@]}): your message\` or \`type(*): your message\` if a wildcard is appropriate.\n\n"
+            comment_body+="<details><summary>Details</summary>\n"
+            comment_body+="PR Title Scopes: \`${pr_scopes[@]}\`\n"
+            comment_body+="Required Scopes from changed files: \`${required_scopes[@]}\`\n"
+            comment_body+="Changed Files:\n"
+            comment_body+="\`\`\`\n${changed_files}\n\`\`\`\n"
+            comment_body+="</details>"
+
+            echo "comment_body=$comment_body" >> $GITHUB_ENV
             exit 1
           else
             echo "PR title scopes are valid."
           fi
+  comment_on_pr:
+    if: failure() && needs.check_scope.outputs.outcome == 'failure'
+    needs: check_scope
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Comment on PR
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const body = `${process.env.comment_body}`;
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });

README.md

@@ -0,0 +1,83 @@
+# PR Scope Check CI
+
+This repository contains a GitHub Actions workflow that checks if the scope in a Pull Request (PR) title matches the files changed in the PR.
+
+## Purpose
+
+The primary goal of this CI is to enforce conventional commit message guidelines, specifically ensuring that the scope defined in the PR title accurately reflects the parts of the codebase being modified. This helps in:
+
+-   Improving the clarity and traceability of changes.
+-   Automating changelog generation.
+-   Making it easier to understand the impact of a PR at a glance.
+
+## How it Works
+
+The CI performs the following steps:
+
+1.  **Extracts PR Title Scope**: It parses the PR title to find the scope(s) defined within the parentheses, e.g., `type(scope1,scope2): message`.
+    -   Multiple scopes can be comma-separated.
+    -   A wildcard scope `(*)` is also permitted, which will allow changes in any scope.
+2.  **Determines Required Scopes from Changed Files**: It analyzes the paths of the files modified in the PR.
+3.  **Matches Scopes against Rules**: It uses a set of rules defined in `scope-rules.json` to map changed file paths to their corresponding scopes.
+    -   `config/{any_dir}/...` maps to the `{any_dir}` as scope.
+    -   `scripts/{any_dir}/...` maps to the `{any_dir}` as scope.
+    -   `data/{any_dir}/...` maps to the `{any_dir}` as scope.
+    -   `.github/...` maps to `github` scope.
+    -   Other files map to `dotfiles` scope.
+4.  **Validates PR Title Scopes**: It checks if the scopes extracted from the PR title cover all the scopes determined from the changed files.
+    -   If the PR title uses a wildcard `*`, the check automatically passes.
+    -   If there's a mismatch (e.g., a required scope is not listed in the PR title, or the PR title has no scope when one is required), the CI job will fail, and a comment will be posted on the PR detailing the issue.
+
+## Configuration
+
+### Scope Rules (`scope-rules.json`)
+
+The mapping between file paths and their scopes is defined in the `scope-rules.json` file in the root of the repository.
+
+The file contains an array of rule objects, each with a `pattern` (regex) and a `scope` (string). The `scope` can use capture groups from the regex (e.g., `$1`).
+
+**Example `scope-rules.json`:**
+
+```json
+{
+  "rules": [
+    {
+      "pattern": "^config/(.+)/.*",
+      "scope": "$1"
+    },
+    {
+      "pattern": "^scripts/(.+)/.*",
+      "scope": "$1"
+    },
+    {
+      "pattern": "^data/(.+)/.*",
+      "scope": "$1"
+    },
+    {
+      "pattern": "^\\.github/.*",
+      "scope": "github"
+    },
+    {
+      "pattern": ".*",
+      "scope": "dotfiles"
+    }
+  ]
+}
+```
+
+Rules are evaluated in the order they are defined. The first rule that matches a file path determines its scope. The last rule `(.*)` acts as a catch-all for files not matching any preceding rules.
+
+### GitHub Actions Workflow
+
+The CI is implemented as a GitHub Actions workflow defined in `.github/workflows/check_pr_scope.yml`. It triggers on `pull_request` events (`opened`, `synchronize`, `reopened`, `edited`).
+
+No special setup is required beyond having this workflow file and the `scope-rules.json` in the repository.
+
+## Troubleshooting
+
+-   **CI Failure with PR Comment**: If the CI fails, it will post a comment on your PR explaining the reason.
+    -   **"PR title does not contain a valid scope."**: Ensure your PR title follows the format `type(scope): message`. If no specific scope applies, but changes are made, consider if `dotfiles` or another general scope is appropriate, or use `type(*): message`. The comment will provide examples.
+    -   **"PR title scopes do not cover all changed files. Missing scopes for: [scope_list]"**: Your PR title is missing one or more scopes that correspond to the files you've changed. Add the missing scopes to your PR title (e.g., `fix(scopeA,scopeB): resolve issues`). The comment will list the missing scopes and suggest how to update the title.
+-   **"No matching scope rule for file: [filepath]"**: This is a warning output in the CI logs (not a PR comment). While it doesn't fail the CI, it indicates that a changed file didn't match any specific rule in `scope-rules.json` and wasn't assigned a scope. This might mean a new rule needs to be added to `scope-rules.json` or the default "dotfiles" scope (if it's the last rule) is being applied implicitly. If the file should have a specific scope, update the rules.
+
+This provides a good overview for users of the repository.