git-commit-guard 0.20.1__tar.gz → 0.22.0__tar.gz

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/.github/workflows/lint-commits.yml

@@ -22,6 +22,6 @@ jobs:
           key: nltk-averaged-perceptron-tagger-punkt
       - name: Lint commits
         # yamllint disable-line rule:line-length
-        uses: benner/commit-guard@cab0d35c41a3f99fc5f61895f491d0ce3f5aff1c  # v0.20.0
+        uses: benner/commit-guard@22a3b0fdb044e874250fc6525ff0905b20fa3a62  # v0.21.0
         with:
           range: origin/${{ github.base_ref }}..HEAD

git_commit_guard-0.22.0/.github/workflows/lint-md.yml

@@ -0,0 +1,68 @@
+---
+name: Lint Markdown
+on:  # yamllint disable-line rule:truthy
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  lint-md:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout code
+        # yamllint disable-line rule:line-length
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Lint Markdown files with reviewdog
+        # yamllint disable-line rule:line-length
+        uses: reviewdog/action-markdownlint@3667398db9118d7e78f7a63d10e26ce454ba5f58  # v0.26.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review
+          level: info
+          fail_level: any
+  lint-md-rumdl:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout code
+        # yamllint disable-line rule:line-length
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        # yamllint disable-line rule:line-length
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
+        with:
+          enable-cache: false
+      - name: Set up reviewdog
+        # yamllint disable-line rule:line-length
+        uses: reviewdog/action-setup@d8a7baabd7f3e8544ee4dbde3ee41d0011c3a93f  # ratchet:reviewdog/action-setup@v1
+      - name: Lint Markdown files with rumdl via reviewdog
+        env:
+          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |-
+          uvx rumdl check . --output-format json-lines > rumdl.jsonl || true
+          jq -c '
+            {
+              source: {name: "rumdl"},
+              severity: (.severity | ascii_upcase),
+              message: .message,
+              location: {
+                path: .file,
+                range: {start: {line: .line, column: .column}}
+              },
+              code: {value: .rule}
+            }
+          ' rumdl.jsonl \
+            | reviewdog \
+                -f=rdjsonl \
+                -name=rumdl \
+                -reporter=github-pr-review \
+                -filter-mode=added \
+                -fail-level=any

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/.github/workflows/release.yml

@@ -18,9 +18,6 @@ jobs:
         with:
           persist-credentials: false
           fetch-depth: 0
-      - name: Set up Python
-        # yamllint disable-line rule:line-length
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
       - name: Set up uv
         # yamllint disable-line rule:line-length
         uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-commit-guard
-Version: 0.20.1
+Version: 0.22.0
 Summary: Opinionated conventional commit message linter with imperative mood detection
 Project-URL: Homepage, https://github.com/benner/commit-guard
 Project-URL: Repository, https://github.com/benner/commit-guard
@@ -21,19 +21,35 @@ Description-Content-Type: text/markdown
 
 # commit-guard
 
+<!-- markdownlint-disable MD013 -->
+[![PyPI version](https://img.shields.io/pypi/v/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![CI](https://github.com/benner/commit-guard/actions/workflows/test.yml/badge.svg)](https://github.com/benner/commit-guard/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
+<!-- markdownlint-restore -->
+
 Opinionated conventional commit message linter with imperative mood detection.
 
-Unlike regular expression only tools, commit-guard uses
-NLP (nltk POS tagging) to verify that commit descriptions start with an
-imperative verb.
+## Why commit-guard?
+
+* **NLP imperative detection.** Descriptions must start with an imperative
+  verb, verified via nltk POS tagging — not a hand-coded regex of "bad"
+  words.
+* **Signature verification without a local keyring.** Resolves the commit
+  author via the GitHub API and verifies GPG/SSH against their published
+  `.gpg`/`.keys` — no per-runner key management.
+* **Strict by default.** Subject format, body, trailers, `Signed-off-by`,
+  and signature all enforced out of the box; opt out with `--disable`.
 
 ## Example
 
 ```bash
 $ commit-guard
   ✗ [subject] subject does not match 'type(scope): description': WIP
-  ✗ [signed-off] missing 'Signed-off-by' trailer
-  ✗ [signature] commit is not signed (GPG/SSH)
+  ✗ [signed-off] missing 'Signed-off-by' trailer — use 'git commit -s'
+  ✗ [signature] signature could not be verified — commit may be
+                unsigned, or signed with a key not uploaded as a
+                Signing key on https://github.com/settings/keys
 ```
 
 ## Installation
@@ -94,12 +110,12 @@ commit-guard --disable body,signed-off,signature
 Available checks:
 
 * `subject` - Format matches `type(scope): description`, valid type,
-    lowercase start, no trailing `.` `!` `?` or space, max 72 chars
+  lowercase start, no trailing `.` `!` `?` or space, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
 * `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature via the GitHub Commits API or
-    public key lookup
+  public key lookup
 
 ### Subject length
 
@@ -235,8 +251,10 @@ The `signature` check verifies the commit without any local keyring setup:
    `{username}@users.noreply.github.com`) — no API call needed.
 3. If neither of the above resolves a username, fall back to searching GitHub
    by the commit author's email.
-4. Fetch the resolved user's public keys from `github.com/{username}.gpg` and
-   `github.com/{username}.keys`.
+4. Fetch the resolved user's public keys from `github.com/{username}.gpg`
+   (GPG) and the `/users/{username}/ssh_signing_keys` API (SSH keys tagged
+   with the **Signing key** role). Auth-only SSH keys are deliberately not
+   accepted — this mirrors GitHub's "Verified" badge semantics.
 5. Try GPG verification: import the fetched key into a temporary keyring and
    run `git verify-commit`.
 6. Try SSH verification: write a temporary `allowed_signers` file and run
@@ -247,7 +265,9 @@ If the author cannot be resolved via either method, or the GitHub API is
 unreachable, the check fails with a clear error.
 
 For private repositories, set `GITHUB_TOKEN` or `GH_TOKEN` so the Commits API
-can authenticate.
+can authenticate. The official GitHub Action wires the workflow's automatic
+token via the `github-token` input, so no manual `env:` is required; override
+with a PAT only for cross-repo lookups.
 
 ### Configuration file
 
@@ -296,7 +316,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.20.1
+- uses: benner/commit-guard@v0.22.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -380,7 +400,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.20.1
+  - uses: benner/commit-guard@v0.22.0
 ```
 
 Check all commits in a pull request:
@@ -396,7 +416,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -404,7 +424,7 @@ jobs:
 Check a specific commit SHA (mirrors the positional CLI argument):
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           rev: ${{ github.sha }}
 ```
@@ -422,7 +442,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -442,7 +462,7 @@ jobs:
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -458,7 +478,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.22.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/README.md

@@ -1,18 +1,34 @@
 # commit-guard
 
+<!-- markdownlint-disable MD013 -->
+[![PyPI version](https://img.shields.io/pypi/v/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![CI](https://github.com/benner/commit-guard/actions/workflows/test.yml/badge.svg)](https://github.com/benner/commit-guard/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
+<!-- markdownlint-restore -->
+
 Opinionated conventional commit message linter with imperative mood detection.
 
-Unlike regular expression only tools, commit-guard uses
-NLP (nltk POS tagging) to verify that commit descriptions start with an
-imperative verb.
+## Why commit-guard?
+
+* **NLP imperative detection.** Descriptions must start with an imperative
+  verb, verified via nltk POS tagging — not a hand-coded regex of "bad"
+  words.
+* **Signature verification without a local keyring.** Resolves the commit
+  author via the GitHub API and verifies GPG/SSH against their published
+  `.gpg`/`.keys` — no per-runner key management.
+* **Strict by default.** Subject format, body, trailers, `Signed-off-by`,
+  and signature all enforced out of the box; opt out with `--disable`.
 
 ## Example
 
 ```bash
 $ commit-guard
   ✗ [subject] subject does not match 'type(scope): description': WIP
-  ✗ [signed-off] missing 'Signed-off-by' trailer
-  ✗ [signature] commit is not signed (GPG/SSH)
+  ✗ [signed-off] missing 'Signed-off-by' trailer — use 'git commit -s'
+  ✗ [signature] signature could not be verified — commit may be
+                unsigned, or signed with a key not uploaded as a
+                Signing key on https://github.com/settings/keys
 ```
 
 ## Installation
@@ -73,12 +89,12 @@ commit-guard --disable body,signed-off,signature
 Available checks:
 
 * `subject` - Format matches `type(scope): description`, valid type,
-    lowercase start, no trailing `.` `!` `?` or space, max 72 chars
+  lowercase start, no trailing `.` `!` `?` or space, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
 * `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature via the GitHub Commits API or
-    public key lookup
+  public key lookup
 
 ### Subject length
 
@@ -214,8 +230,10 @@ The `signature` check verifies the commit without any local keyring setup:
    `{username}@users.noreply.github.com`) — no API call needed.
 3. If neither of the above resolves a username, fall back to searching GitHub
    by the commit author's email.
-4. Fetch the resolved user's public keys from `github.com/{username}.gpg` and
-   `github.com/{username}.keys`.
+4. Fetch the resolved user's public keys from `github.com/{username}.gpg`
+   (GPG) and the `/users/{username}/ssh_signing_keys` API (SSH keys tagged
+   with the **Signing key** role). Auth-only SSH keys are deliberately not
+   accepted — this mirrors GitHub's "Verified" badge semantics.
 5. Try GPG verification: import the fetched key into a temporary keyring and
    run `git verify-commit`.
 6. Try SSH verification: write a temporary `allowed_signers` file and run
@@ -226,7 +244,9 @@ If the author cannot be resolved via either method, or the GitHub API is
 unreachable, the check fails with a clear error.
 
 For private repositories, set `GITHUB_TOKEN` or `GH_TOKEN` so the Commits API
-can authenticate.
+can authenticate. The official GitHub Action wires the workflow's automatic
+token via the `github-token` input, so no manual `env:` is required; override
+with a PAT only for cross-repo lookups.
 
 ### Configuration file
 
@@ -275,7 +295,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.20.1
+- uses: benner/commit-guard@v0.22.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -359,7 +379,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.20.1
+  - uses: benner/commit-guard@v0.22.0
 ```
 
 Check all commits in a pull request:
@@ -375,7 +395,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -383,7 +403,7 @@ jobs:
 Check a specific commit SHA (mirrors the positional CLI argument):
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           rev: ${{ github.sha }}
 ```
@@ -401,7 +421,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -421,7 +441,7 @@ jobs:
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -437,7 +457,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.22.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/action.yml

@@ -39,7 +39,8 @@ inputs:
     required: false
     default: 'false'
   no-trailing-chars:
-    description: Forbidden trailing characters, comma-separated (default '.', '!', '?', ' ')
+    description: Forbidden trailing characters, comma-separated (default '.', '!',
+      '?', ' ')
     required: false
   allow-empty:
     description: Exit 0 when --range yields no commits
@@ -58,9 +59,15 @@ inputs:
   output-file:
     description: Write JSONL results to this file path (text still goes to stdout)
     required: false
+  github-token:
+    description: GitHub token for Commits API access (signature check). Defaults to
+      the workflow's automatic token; override with a PAT for cross-repo lookups.
+    required: false
+    default: ${{ github.token }}
 outputs:
   output-file:
-    description: Path to the JSONL output file (set only when output-file input is provided)
+    description: Path to the JSONL output file (set only when output-file input is
+      provided)
     value: ${{ steps.run.outputs.output-file }}
 runs:
   using: composite
@@ -76,6 +83,7 @@ runs:
     - name: Run commit-guard
       id: run
       env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
         CG_REV: ${{ inputs.rev }}
         CG_RANGE: ${{ inputs.range }}
         CG_ENABLE: ${{ inputs.enable }}

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/docs/index.html

@@ -115,7 +115,7 @@
       .hero-terminal pre {
         margin: 0;
         font-size: 0.95rem;
-        width: 64ch;
+        width: 80ch;
         height: 12em;
         overflow: hidden;
       }
@@ -291,12 +291,12 @@
         <h1>commit-guard</h1>
         <p>Conventional commit linting with imperative mood detection.</p>
         <div class="hero-terminal">
-          <pre><code id="hero-code">$ commit-guard --range origin/main..HEAD
-<span class="c-dim">abc1234</span> feat: add user authentication
-  <span class="c-green">✓</span> all checks passed
-<span class="c-dim">def5678</span> wip: still working
-  <span class="c-red">✗</span> <span class="c-dim">[subject]</span> unknown type: wip
-  <span class="c-red">✗</span> <span class="c-dim">[body]</span> missing body</code></pre>
+          <pre><code id="hero-code">$ commit-guard
+  <span class="c-red">✗</span> <span class="c-dim">[subject]</span> subject does not match 'type(scope): description': WIP
+  <span class="c-red">✗</span> <span class="c-dim">[signed-off]</span> missing 'Signed-off-by' trailer — use 'git commit -s'
+  <span class="c-red">✗</span> <span class="c-dim">[signature]</span> signature could not be verified — commit may be
+                unsigned, or signed with a key not uploaded as a
+                Signing key on https://github.com/settings/keys</code></pre>
         </div>
         <div class="hero-dots">
           <button class="hero-dot" data-i="0"></button>
@@ -305,6 +305,28 @@
         </div>
       </section>
 
+      <section id="why">
+        <h2>Why commit-guard? <a href="#why" class="anchor">#</a></h2>
+        <ul>
+          <li>
+            <strong>NLP imperative detection.</strong> Descriptions must start
+            with an imperative verb, verified via nltk POS tagging — not a
+            hand-coded regex of "bad" words.
+          </li>
+          <li>
+            <strong>Signature verification without a local keyring.</strong>
+            Resolves the commit author via the GitHub API and verifies GPG/SSH
+            against their published <code>.gpg</code>/<code>.keys</code> — no
+            per-runner key management.
+          </li>
+          <li>
+            <strong>Strict by default.</strong> Subject format, body, trailers,
+            <code>Signed-off-by</code>, and signature all enforced out of the
+            box; opt out with <code>--disable</code>.
+          </li>
+        </ul>
+      </section>
+
       <section id="install">
         <h2>Install <a href="#install" class="anchor">#</a></h2>
         <div class="install-tabs">
@@ -444,8 +466,11 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
           <li>If neither of the above resolves a username, fall back to
             searching GitHub by the commit author's email.</li>
           <li>Fetch the resolved user's public keys from
-            <code>github.com/{username}.gpg</code> and
-            <code>github.com/{username}.keys</code>.</li>
+            <code>github.com/{username}.gpg</code> (GPG) and
+            <code>/users/{username}/ssh_signing_keys</code> (SSH keys tagged
+            with the <strong>Signing key</strong> role). Auth-only SSH keys
+            are deliberately not accepted — this mirrors GitHub's
+            &ldquo;Verified&rdquo; badge semantics.</li>
           <li>Try GPG verification using a temporary keyring.</li>
           <li>Try SSH verification using a temporary <code>allowed_signers</code> file.</li>
           <li>Pass if any key verifies; fail if none do.</li>
@@ -454,7 +479,10 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
           If the author cannot be resolved via either method, or the GitHub API
           is unreachable, the check fails with a clear error. For private
           repositories, set <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code>
-          so the Commits API can authenticate. Disable the
+          so the Commits API can authenticate. The official GitHub Action wires
+          the workflow's automatic token via the <code>github-token</code>
+          input, so no manual <code>env:</code> is required; override with a
+          PAT only for cross-repo lookups. Disable the
           <code>signature</code> check if GitHub API access is unavailable:
         </p>
         <pre><code class="language-bash">commit-guard --disable signature</code></pre>
@@ -538,13 +566,13 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.22.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature</code></pre>
 
         <p>Check a specific commit SHA:</p>
-        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.20.1
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.22.0
         with:
           rev: ${{ github.sha }}</code></pre>
 
@@ -563,7 +591,7 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
           When <code>output-file</code> is set the action exposes the path as
           a step output, making JSONL results available to subsequent steps:
         </p>
-        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.20.1
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.22.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -576,7 +604,7 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
         <p>Add to <code>.pre-commit-config.yaml</code>:</p>
         <pre><code class="language-yaml">repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.22.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature</code></pre>
@@ -596,16 +624,16 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
       const EXAMPLES = [
         [
           ["$ commit-guard\n  ", null],
-          ["✗", "c-red"], [" [subject]", "c-dim"], [" unknown type: wip\n  ", null],
-          ["✗", "c-red"], [" [body]",    "c-dim"], [" missing body\n  ", null],
-          ["✗", "c-red"], [" [imperative]", "c-dim"], [" got 'added', want imperative verb", null],
+          ["✗", "c-red"], [" [subject]", "c-dim"], [" subject does not match 'type(scope): description': WIP\n  ", null],
+          ["✗", "c-red"], [" [signed-off]", "c-dim"], [" missing 'Signed-off-by' trailer — use 'git commit -s'\n  ", null],
+          ["✗", "c-red"], [" [signature]", "c-dim"], [" signature could not be verified — commit may be\n                unsigned, or signed with a key not uploaded as a\n                Signing key on https://github.com/settings/keys", null],
         ],
         [
           ["$ commit-guard --range origin/main..HEAD\n", null],
           ["abc1234", "c-dim"], [" feat: add user authentication\n  ", null],
           ["✓", "c-green"], [" all checks passed\n", null],
-          ["def5678", "c-dim"], [" wip: still working\n  ", null],
-          ["✗", "c-red"], [" [subject]", "c-dim"], [" unknown type: wip\n  ", null],
+          ["def5678", "c-dim"], [" chore: added logging\n  ", null],
+          ["✗", "c-red"], [" [imperative]", "c-dim"], [" expected imperative verb, got 'added' (non-imperative suffix)\n  ", null],
           ["✗", "c-red"], [" [body]",    "c-dim"], [" missing body", null],
         ],
         [

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/src/git_commit_guard/__init__.py

@@ -11,6 +11,7 @@ import urllib.request
 from argparse import ArgumentParser
 from dataclasses import dataclass, field
 from enum import StrEnum
+from http import HTTPStatus
 from pathlib import Path
 
 import nltk
@@ -150,6 +151,12 @@ def _download_if_missing(resource):
         nltk.download(resource.rsplit("/", maxsplit=1)[-1], quiet=True)
 
 
+def _format_allowed_hint(allowed, kind):
+    if len(allowed) <= len(TYPES):
+        return f"(allowed: {', '.join(sorted(allowed))})"
+    return f"(see configured {kind})"
+
+
 def _strip_comments(message):
     return "\n".join(
         line for line in message.split("\n") if not line.lstrip().startswith("#")
@@ -177,13 +184,16 @@ def check_subject(  # noqa: PLR0913 Too many arguments in function definition (9
         return None
 
     if m.group("type") not in allowed_types:
-        result.error(f"unknown type: {m.group('type')}", check=Check.SUBJECT)
+        bad_type = m.group("type")
+        hint = _format_allowed_hint(allowed_types, "types")
+        result.error(f"unknown type: {bad_type} {hint}", check=Check.SUBJECT)
 
     scope = m.group("scope")
     if require_scope and scope is None:
         result.error("scope is required", check=Check.SUBJECT)
     if allowed_scopes and scope is not None and scope not in allowed_scopes:
-        result.error(f"unknown scope: {scope}", check=Check.SUBJECT)
+        hint = _format_allowed_hint(allowed_scopes, "scopes")
+        result.error(f"unknown scope: {scope} {hint}", check=Check.SUBJECT)
 
     desc = m.group("desc")
     if require_lowercase and desc[0].isupper():
@@ -248,7 +258,10 @@ def check_body(lines, result):
 
 def check_signed_off(message, result):
     if not SIGNED_OFF_RE.search(message):
-        result.error("missing 'Signed-off-by' trailer", check=Check.SIGNED_OFF)
+        result.error(
+            "missing 'Signed-off-by' trailer — use 'git commit -s'",
+            check=Check.SIGNED_OFF,
+        )
 
 
 def check_subject_pattern(subject, pattern, result):
@@ -323,9 +336,21 @@ def _fetch_url(url):
         return resp.read().decode()
 
 
+def _fetch_github_signing_keys(username):
+    url = f"https://api.github.com/users/{username}/ssh_signing_keys"
+    headers = {"Accept": "application/vnd.github+json"}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(url, headers=headers)  # noqa: S310 Audit URL open for permitted schemes
+    with urllib.request.urlopen(req, timeout=_git_timeout()) as resp:  # noqa: S310 Audit URL open for permitted schemes
+        data = json.loads(resp.read())
+    return "\n".join(item["key"] for item in data)
+
+
 def _fetch_github_keys(username):
     gpg = _fetch_url(f"https://github.com/{username}.gpg")
-    ssh = _fetch_url(f"https://github.com/{username}.keys")
+    ssh = _fetch_github_signing_keys(username)
     return gpg.strip(), ssh.strip()
 
 
@@ -387,22 +412,46 @@ def _verify_ssh(rev, email, ssh_text):
         Path(signers_path).unlink(missing_ok=True)
 
 
+def _resolve_github_username(rev, email):
+    username = None
+    commits_api_404 = False
+    remote = _get_github_remote_info()
+    if remote:
+        owner, repo = remote
+        try:
+            username = _fetch_github_commit_author(owner, repo, rev)
+        except urllib.error.HTTPError as e:
+            if e.code == HTTPStatus.NOT_FOUND:
+                commits_api_404 = True
+            elif e.code in (HTTPStatus.UNAUTHORIZED, HTTPStatus.FORBIDDEN):
+                raise
+        except (urllib.error.URLError, TimeoutError):
+            pass
+    if username is None:
+        username = _parse_noreply_username(email)
+    if username is None:
+        username = _fetch_github_username(email)
+    return username, commits_api_404
+
+
+def _author_not_found_message(commits_api_404):
+    had_token = bool(os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN"))
+    if commits_api_404 and not had_token:
+        return (
+            "commit author not found on GitHub — if the repo is private, "
+            "set GITHUB_TOKEN in the workflow step "
+            "(env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }})"
+        )
+    return "commit author not found on GitHub — cannot verify signature"
+
+
 def check_signature(rev, result):
     try:
         email = _get_author_email(rev)
-        username = None
-        remote = _get_github_remote_info()
-        if remote:
-            owner, repo = remote
-            with contextlib.suppress(urllib.error.URLError, TimeoutError):
-                username = _fetch_github_commit_author(owner, repo, rev)
-        if username is None:
-            username = _parse_noreply_username(email)
-        if username is None:
-            username = _fetch_github_username(email)
+        username, commits_api_404 = _resolve_github_username(rev, email)
         if username is None:
             result.error(
-                "commit author not found on GitHub — cannot verify signature",
+                _author_not_found_message(commits_api_404),
                 check=Check.SIGNATURE,
             )
             return
@@ -413,12 +462,35 @@ def check_signature(rev, result):
         if _verify_ssh(rev, email, ssh_text):
             result.info("signature type: SSH", check=Check.SIGNATURE)
             return
-        result.error("commit is not signed (GPG/SSH)", check=Check.SIGNATURE)
+        result.error(
+            "signature could not be verified — commit may be unsigned, "
+            "or signed with a key not uploaded as a Signing key on "
+            "https://github.com/settings/keys",
+            check=Check.SIGNATURE,
+        )
     except subprocess.TimeoutExpired:
         result.error(
             "git operation timed out — cannot verify signature",
             check=Check.SIGNATURE,
         )
+    except urllib.error.HTTPError as e:
+        if e.code == HTTPStatus.UNAUTHORIZED:
+            result.error(
+                "GitHub API rejected token (HTTP 401) — "
+                "GITHUB_TOKEN may be invalid or expired",
+                check=Check.SIGNATURE,
+            )
+        elif e.code == HTTPStatus.FORBIDDEN:
+            result.error(
+                "GitHub API forbidden (HTTP 403) — GITHUB_TOKEN may lack "
+                "'repo' scope, or you are unauthenticated and rate-limited",
+                check=Check.SIGNATURE,
+            )
+        else:
+            result.error(
+                f"GitHub API error (HTTP {e.code}) — cannot verify signature",
+                check=Check.SIGNATURE,
+            )
     except (urllib.error.URLError, TimeoutError):
         result.error(
             "GitHub API unreachable — cannot verify signature",

{git_commit_guard-0.20.1 → git_commit_guard-0.22.0}/tests/test_git_commit_guard.py

@@ -17,6 +17,7 @@ from git_commit_guard import (
     _ensure_nltk_data,
     _fetch_github_commit_author,
     _fetch_github_keys,
+    _fetch_github_signing_keys,
     _fetch_github_username,
     _fetch_url,
     _get_author_email,
@@ -124,6 +125,25 @@ class TestCheckSubject:
         check_subject("unknown: add thing", r)
         assert not r.ok
 
+    def test_unknown_type_with_default_lists_all_allowed(self):
+        r = Result()
+        check_subject("unknown: add thing", r)
+        assert any(
+            "allowed: " in m and "feat" in m and "fix" in m for _, _, m in r.errors
+        )
+
+    def test_unknown_type_with_smaller_set_lists_them(self):
+        r = Result()
+        check_subject("foo: add thing", r, allowed_types=frozenset({"feat", "fix"}))
+        assert any("allowed: feat, fix" in m for _, _, m in r.errors)
+
+    def test_unknown_type_with_larger_than_default_points_at_config(self):
+        r = Result()
+        oversized = frozenset({f"t{i}" for i in range(20)})
+        check_subject("foo: add thing", r, allowed_types=oversized)
+        assert any("see configured types" in m for _, _, m in r.errors)
+        assert not any("allowed:" in m for _, _, m in r.errors)
+
     def test_uppercase_description(self):
         r = Result()
         check_subject("fix: Add token", r)
@@ -184,6 +204,22 @@ class TestCheckSubject:
         check_subject("fix(api): add token", r, allowed_scopes=frozenset(["auth"]))
         assert not r.ok
 
+    def test_unknown_scope_with_small_set_lists_them(self):
+        r = Result()
+        check_subject(
+            "fix(api): add token",
+            r,
+            allowed_scopes=frozenset({"auth", "db"}),
+        )
+        assert any("allowed: auth, db" in m for _, _, m in r.errors)
+
+    def test_unknown_scope_with_larger_than_default_points_at_config(self):
+        r = Result()
+        oversized = frozenset({f"s{i}" for i in range(20)})
+        check_subject("fix(foo): add token", r, allowed_scopes=oversized)
+        assert any("see configured scopes" in m for _, _, m in r.errors)
+        assert not any("allowed:" in m for _, _, m in r.errors)
+
     def test_no_scope_with_allowlist_passes(self):
         r = Result()
         check_subject("fix: add token", r, allowed_scopes=frozenset(["auth"]))
@@ -325,6 +361,11 @@ class TestCheckSignedOff:
         check_signed_off("fix: add thing\n\nbody", r)
         assert not r.ok
 
+    def test_missing_message_hints_at_git_commit_dash_s(self):
+        r = Result()
+        check_signed_off("fix: add thing\n\nbody", r)
+        assert any("git commit -s" in m for _, _, m in r.errors)
+
     def test_malformed_no_email(self):
         r = Result()
         check_signed_off("fix: add thing\n\nSigned-off-by: John Doe", r)
@@ -695,10 +736,69 @@ class TestFetchGithubCommitAuthor:
         assert captured[0].get_header("Authorization") == "Bearer ghtoken"
 
 
+class TestFetchGithubSigningKeys:
+    def _mock_response(self, data):
+        mock_resp = MagicMock()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_resp.read.return_value = json.dumps(data).encode()
+        return mock_resp
+
+    def test_returns_keys_joined_by_newline(self):
+        resp = self._mock_response(
+            [{"key": "ssh-ed25519 AAAA"}, {"key": "ssh-rsa BBBB"}]
+        )
+        with patch("git_commit_guard.urllib.request.urlopen", return_value=resp):
+            assert (
+                _fetch_github_signing_keys("testuser")
+                == "ssh-ed25519 AAAA\nssh-rsa BBBB"
+            )
+
+    def test_empty_list_returns_empty_string(self):
+        resp = self._mock_response([])
+        with patch("git_commit_guard.urllib.request.urlopen", return_value=resp):
+            assert _fetch_github_signing_keys("testuser") == ""
+
+    def test_github_token_sent_in_header(self):
+        resp = self._mock_response([])
+        captured = []
+
+        def mock_urlopen(req, **_):
+            captured.append(req)
+            return resp
+
+        with (
+            patch("git_commit_guard.urllib.request.urlopen", side_effect=mock_urlopen),
+            patch.dict("os.environ", {"GITHUB_TOKEN": "mytoken"}, clear=False),
+        ):
+            _fetch_github_signing_keys("testuser")
+        assert captured[0].get_header("Authorization") == "Bearer mytoken"
+
+    def test_gh_token_used_when_github_token_absent(self):
+        resp = self._mock_response([])
+        captured = []
+
+        def mock_urlopen(req, **_):
+            captured.append(req)
+            return resp
+
+        env = {k: v for k, v in os.environ.items() if k != "GITHUB_TOKEN"}
+        env["GH_TOKEN"] = "ghtoken"  # noqa: S105 Possible hardcoded password assigned to: "GH_TOKEN"
+        with (
+            patch("git_commit_guard.urllib.request.urlopen", side_effect=mock_urlopen),
+            patch.dict("os.environ", env, clear=True),
+        ):
+            _fetch_github_signing_keys("testuser")
+        assert captured[0].get_header("Authorization") == "Bearer ghtoken"
+
+
 class TestFetchGithubKeys:
     def test_returns_gpg_and_ssh(self):
-        with patch(
-            "git_commit_guard._fetch_url", side_effect=["GPG KEY\n", "SSH KEY\n"]
+        with (
+            patch("git_commit_guard._fetch_url", return_value="GPG KEY\n"),
+            patch(
+                "git_commit_guard._fetch_github_signing_keys", return_value="SSH KEY\n"
+            ),
         ):
             gpg, ssh = _fetch_github_keys("testuser")
         assert gpg == "GPG KEY"
@@ -816,6 +916,157 @@ class TestCheckSignature:
         assert not r.ok
         assert any("not found on GitHub" in msg for _, _, msg in r.errors)
 
+    def test_commits_api_404_without_token_hints_at_token(self):
+        r = Result()
+        env = {
+            k: v for k, v in os.environ.items() if k not in ("GITHUB_TOKEN", "GH_TOKEN")
+        }
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=404, msg="Not Found", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value=None),
+            patch.dict("os.environ", env, clear=True),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("set GITHUB_TOKEN" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_404_with_token_keeps_generic_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=404, msg="Not Found", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value=None),
+            patch.dict("os.environ", {"GITHUB_TOKEN": "x"}, clear=False),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert not any("set GITHUB_TOKEN" in msg for _, _, msg in r.errors)
+        assert any("cannot verify signature" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_non_404_http_error_falls_through(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=500, msg="Server Error", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value="emailuser"),
+            patch("git_commit_guard._fetch_github_keys", return_value=("GPG KEY", "")),
+            patch("git_commit_guard._verify_gpg", return_value=True),
+        ):
+            check_signature("abc123", r)
+        assert r.ok
+
+    def test_commits_api_401_surfaces_token_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=401, msg="Unauthorized", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("rejected token (HTTP 401)" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_403_surfaces_token_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=403, msg="Forbidden", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("forbidden (HTTP 403)" in msg for _, _, msg in r.errors)
+
+    def test_search_api_403_surfaces_rate_limit_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="corp@example.com"
+            ),
+            patch("git_commit_guard._get_github_remote_info", return_value=None),
+            patch(
+                "git_commit_guard._fetch_github_username",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=403, msg="Forbidden", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("forbidden (HTTP 403)" in msg for _, _, msg in r.errors)
+
+    def test_other_http_error_uses_generic_http_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="corp@example.com"
+            ),
+            patch("git_commit_guard._get_github_remote_info", return_value=None),
+            patch(
+                "git_commit_guard._fetch_github_username",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=500, msg="Server Error", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("GitHub API error (HTTP 500)" in msg for _, _, msg in r.errors)
+
     def test_url_error_fails(self):
         r = Result()
         with patch(

git_commit_guard-0.20.1/.github/workflows/lint-md.yml

@@ -1,26 +0,0 @@
----
-name: Lint Markdown
-on:  # yamllint disable-line rule:truthy
-  pull_request:
-permissions:
-  contents: read
-jobs:
-  lint-md:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
-    steps:
-      - name: Checkout code
-        # yamllint disable-line rule:line-length
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - name: Lint Markdown files with reviewdog
-        # yamllint disable-line rule:line-length
-        uses: reviewdog/action-markdownlint@3667398db9118d7e78f7a63d10e26ce454ba5f58  # v0.26.2
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          reporter: github-pr-review
-          level: info
-          fail_level: any