git-commit-guard 0.12.0__tar.gz → 0.14.0__tar.gz

{git_commit_guard-0.12.0 → git_commit_guard-0.14.0}/.github/workflows/lint-commits.yml

@@ -7,8 +7,6 @@ permissions:
 jobs:
   lint-commits:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
       - name: Checkout code
         # yamllint disable-line rule:line-length
@@ -16,29 +14,15 @@ jobs:
         with:
           persist-credentials: false
           fetch-depth: 0
-      - name: Install Python
-        # yamllint disable-line rule:line-length
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-      - name: Install uv
-        # yamllint disable-line rule:line-length
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
-      - name: Install commit-guard
-        run: uv pip install --system .
       - name: Cache NLTK data
+        # yamllint disable-line rule:line-length
         uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7  # v5.0.4
         with:
           path: ~/nltk_data
           key: nltk-averaged-perceptron-tagger-punkt
       - name: Lint commits
-        env:
-          BASE_REF: ${{ github.base_ref }}
-        run: |-
-          commits=$(git log --no-merges --format="%H" "origin/$BASE_REF"..HEAD)
-          failed=0
-          for sha in $commits; do
-            echo "--- checking $sha ---"
-            commit-guard --disable signature "$sha" || failed=1
-          done
-          exit $failed
+        # yamllint disable-line rule:line-length
+        uses: benner/commit-guard@0f2660f0b4d0ea25b8524acfb459a35e544252cb  # v0.13.0
+        with:
+          range: origin/${{ github.base_ref }}..HEAD
+          disable: signature

{git_commit_guard-0.12.0 → git_commit_guard-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-commit-guard
-Version: 0.12.0
+Version: 0.14.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
@@ -147,12 +147,33 @@ commit-guard --require-scope
 commit-guard --scopes auth,api --require-scope
 ```
 
+### Required custom trailers
+
+Require arbitrary trailers to be present in the commit message. Multiple
+trailers can be specified as a comma-separated list:
+
+```bash
+commit-guard --require-trailer Closes
+commit-guard --require-trailer "Closes,Reviewed-by"
+```
+
+In `.commit-guard.toml`:
+
+```toml
+require-trailers = ["Closes", "Reviewed-by"]
+```
+
+Trailer matching is case-sensitive and requires at least one non-space
+character after the colon (e.g. `Closes: #42`). This check runs
+independently of `--enable`/`--disable`.
+
 ### Configuration file
 
 Place `.commit-guard.toml` in your project root (or any parent directory) to
 set defaults for `enable`, `disable`, `scopes`, `require-scope`, `types`,
-`max-subject-length`, and `min-description-length`. commit-guard searches
-upward from the working directory and uses the first file found.
+`max-subject-length`, `min-description-length`, and `require-trailers`.
+commit-guard searches upward from the working directory and uses the first
+file found.
 
 ```toml
 # .commit-guard.toml
@@ -162,6 +183,7 @@ require-scope = true
 types = ["feat", "fix", "chore", "wip"]
 max-subject-length = 100
 min-description-length = 10
+require-trailers = ["Closes", "Reviewed-by"]
 ```
 
 ```toml
@@ -170,8 +192,8 @@ enable = ["subject", "imperative"]
 ```
 
 CLI flags (`--enable`, `--disable`, `--scopes`, `--require-scope`, `--types`,
-`--max-subject-length`, `--min-description-length`) take full precedence and
-ignore config file values when provided.
+`--max-subject-length`, `--min-description-length`, `--require-trailer`) take
+full precedence and ignore config file values when provided.
 
 ### Checking a range of commits
 
@@ -202,6 +224,33 @@ misconfigured range specs in CI. Use `--allow-empty` to exit 0 instead:
 commit-guard --range origin/main..HEAD --allow-empty
 ```
 
+### Machine-readable output
+
+Use `--output jsonl` to emit one JSON line per commit to stdout instead of the
+default human-readable text on stderr:
+
+```bash
+commit-guard --range origin/main..HEAD --output jsonl
+```
+
+Each line is a JSON object:
+
+```json
+{
+  "sha": "abc1234...",
+  "subject": "feat: add thing",
+  "ok": false,
+  "results": [{"check": "body", "level": "error", "message": "missing body"}]
+}
+```
+
+`sha` is `null` when reading from a file or stdin. `results` is empty when all
+checks pass. Pipe to `jq` for filtering:
+
+```bash
+commit-guard --range origin/main..HEAD --output jsonl | jq 'select(.ok == false)'
+```
+
 ### GitHub Actions
 
 ```yaml
@@ -209,7 +258,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@vX.Y.Z
+  - uses: benner/commit-guard@v0.14.0
 ```
 
 Check all commits in a pull request:
@@ -225,7 +274,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@vX.Y.Z
+      - uses: benner/commit-guard@v0.14.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -243,12 +292,13 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@vX.Y.Z
+      - uses: benner/commit-guard@v0.14.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
           scopes: auth,api,db
           require-scope: 'true'
+          require-trailer: 'Closes,Reviewed-by'
           max-subject-length: '100'
           min-description-length: '10'
 ```
@@ -261,7 +311,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.1.0
+    rev: v0.14.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.12.0 → git_commit_guard-0.14.0}/README.md

@@ -126,12 +126,33 @@ commit-guard --require-scope
 commit-guard --scopes auth,api --require-scope
 ```
 
+### Required custom trailers
+
+Require arbitrary trailers to be present in the commit message. Multiple
+trailers can be specified as a comma-separated list:
+
+```bash
+commit-guard --require-trailer Closes
+commit-guard --require-trailer "Closes,Reviewed-by"
+```
+
+In `.commit-guard.toml`:
+
+```toml
+require-trailers = ["Closes", "Reviewed-by"]
+```
+
+Trailer matching is case-sensitive and requires at least one non-space
+character after the colon (e.g. `Closes: #42`). This check runs
+independently of `--enable`/`--disable`.
+
 ### Configuration file
 
 Place `.commit-guard.toml` in your project root (or any parent directory) to
 set defaults for `enable`, `disable`, `scopes`, `require-scope`, `types`,
-`max-subject-length`, and `min-description-length`. commit-guard searches
-upward from the working directory and uses the first file found.
+`max-subject-length`, `min-description-length`, and `require-trailers`.
+commit-guard searches upward from the working directory and uses the first
+file found.
 
 ```toml
 # .commit-guard.toml
@@ -141,6 +162,7 @@ require-scope = true
 types = ["feat", "fix", "chore", "wip"]
 max-subject-length = 100
 min-description-length = 10
+require-trailers = ["Closes", "Reviewed-by"]
 ```
 
 ```toml
@@ -149,8 +171,8 @@ enable = ["subject", "imperative"]
 ```
 
 CLI flags (`--enable`, `--disable`, `--scopes`, `--require-scope`, `--types`,
-`--max-subject-length`, `--min-description-length`) take full precedence and
-ignore config file values when provided.
+`--max-subject-length`, `--min-description-length`, `--require-trailer`) take
+full precedence and ignore config file values when provided.
 
 ### Checking a range of commits
 
@@ -181,6 +203,33 @@ misconfigured range specs in CI. Use `--allow-empty` to exit 0 instead:
 commit-guard --range origin/main..HEAD --allow-empty
 ```
 
+### Machine-readable output
+
+Use `--output jsonl` to emit one JSON line per commit to stdout instead of the
+default human-readable text on stderr:
+
+```bash
+commit-guard --range origin/main..HEAD --output jsonl
+```
+
+Each line is a JSON object:
+
+```json
+{
+  "sha": "abc1234...",
+  "subject": "feat: add thing",
+  "ok": false,
+  "results": [{"check": "body", "level": "error", "message": "missing body"}]
+}
+```
+
+`sha` is `null` when reading from a file or stdin. `results` is empty when all
+checks pass. Pipe to `jq` for filtering:
+
+```bash
+commit-guard --range origin/main..HEAD --output jsonl | jq 'select(.ok == false)'
+```
+
 ### GitHub Actions
 
 ```yaml
@@ -188,7 +237,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@vX.Y.Z
+  - uses: benner/commit-guard@v0.14.0
 ```
 
 Check all commits in a pull request:
@@ -204,7 +253,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@vX.Y.Z
+      - uses: benner/commit-guard@v0.14.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -222,12 +271,13 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@vX.Y.Z
+      - uses: benner/commit-guard@v0.14.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
           scopes: auth,api,db
           require-scope: 'true'
+          require-trailer: 'Closes,Reviewed-by'
           max-subject-length: '100'
           min-description-length: '10'
 ```
@@ -240,7 +290,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.1.0
+    rev: v0.14.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.12.0 → git_commit_guard-0.14.0}/src/git_commit_guard/__init__.py

@@ -1,3 +1,4 @@
+import json
 import re
 import subprocess
 import sys
@@ -53,6 +54,11 @@ class Check(StrEnum):
 ALL_CHECKS = frozenset(Check.__members__.values())
 
 
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSONL = "jsonl"
+
+
 def _load_config(start=None):
     start = start or Path.cwd()
     for directory in [start, *start.parents]:
@@ -87,18 +93,18 @@ PREFIXES = {
 class Result:
     errors: list = field(default_factory=list)
 
-    def error(self, msg):
-        self.errors.append((Level.ERROR, msg))
+    def error(self, msg, check=None):
+        self.errors.append((check, Level.ERROR, msg))
 
-    def warn(self, msg):
-        self.errors.append((Level.WARN, msg))
+    def warn(self, msg, check=None):
+        self.errors.append((check, Level.WARN, msg))
 
-    def info(self, msg):
-        self.errors.append((Level.INFO, msg))
+    def info(self, msg, check=None):
+        self.errors.append((check, Level.INFO, msg))
 
     @property
     def ok(self):
-        return not any(lvl == Level.ERROR for lvl, _ in self.errors)
+        return not any(lvl == Level.ERROR for _, lvl, _ in self.errors)
 
 
 def _ensure_nltk_data():
@@ -132,42 +138,55 @@ def check_subject(  # noqa: PLR0913 Too many arguments in function definition (7
 ):
     m = SUBJECT_RE.match(line)
     if not m:
-        result.error(f"subject does not match 'type(scope): description': {line}")
+        result.error(
+            f"subject does not match 'type(scope): description': {line}",
+            check=Check.SUBJECT,
+        )
         return None
 
     if m.group("type") not in allowed_types:
-        result.error(f"unknown type: {m.group('type')}")
+        result.error(f"unknown type: {m.group('type')}", check=Check.SUBJECT)
 
     scope = m.group("scope")
     if require_scope and scope is None:
-        result.error("scope is required")
+        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}")
+        result.error(f"unknown scope: {scope}", check=Check.SUBJECT)
 
     desc = m.group("desc")
     if desc[0].isupper():
-        result.error("description must not start with uppercase")
+        result.error("description must not start with uppercase", check=Check.SUBJECT)
     if desc.endswith("."):
-        result.error("description must not end with period")
+        result.error("description must not end with period", check=Check.SUBJECT)
     if len(line) > max_subject_length:
-        result.error(f"subject too long: {len(line)} > {max_subject_length}")
+        result.error(
+            f"subject too long: {len(line)} > {max_subject_length}", check=Check.SUBJECT
+        )
     if min_description_length > 0 and len(desc) < min_description_length:
-        result.error(f"description too short: {len(desc)} < {min_description_length}")
+        result.error(
+            f"description too short: {len(desc)} < {min_description_length}",
+            check=Check.SUBJECT,
+        )
     return desc
 
 
 def check_imperative(desc, result):
+    _ensure_nltk_data()
     tokens = nltk.word_tokenize(desc.lower())
     if not tokens:
         return
     first = tokens[0]
     if _NON_IMPERATIVE_SUFFIX_RE.search(first):
-        result.error(f"expected imperative verb, got '{first}' (non-imperative suffix)")
+        result.error(
+            f"expected imperative verb, got '{first}' (non-imperative suffix)",
+            check=Check.IMPERATIVE,
+        )
         return
     base = wordnet.morphy(first, wordnet.VERB)
     if base is not None and base != first:
         result.error(
-            f"expected imperative verb, got '{first}' (inflected form of '{base}')"
+            f"expected imperative verb, got '{first}' (inflected form of '{base}')",
+            check=Check.IMPERATIVE,
         )
         return
     tagged = nltk.pos_tag(["to", *tokens])
@@ -176,23 +195,31 @@ def check_imperative(desc, result):
             return
         result.error(
             f"expected imperative verb, got '{tagged[1][0]}' (POS={tagged[1][1]})",
+            check=Check.IMPERATIVE,
         )
 
 
 def check_body(lines, result):
     if len(lines) < 3:  # noqa: PLR2004
-        result.error("missing body")
+        result.error("missing body", check=Check.BODY)
         return
     if lines[1].strip():
-        result.error("missing blank line between subject and body")
+        result.error("missing blank line between subject and body", check=Check.BODY)
     body_lines = [ln for ln in lines[2:] if not _TRAILER_RE.match(ln)]
     if not any(ln.strip() for ln in body_lines):
-        result.error("missing body")
+        result.error("missing body", check=Check.BODY)
 
 
 def check_signed_off(message, result):
     if not SIGNED_OFF_RE.search(message):
-        result.error("missing 'Signed-off-by' trailer")
+        result.error("missing 'Signed-off-by' trailer", check=Check.SIGNED_OFF)
+
+
+def check_required_trailers(message, required, result):
+    for trailer in required:
+        pattern = re.compile(rf"^{re.escape(trailer)}:\s+\S", re.MULTILINE)
+        if not pattern.search(message):
+            result.error(f"missing required trailer: {trailer}")
 
 
 def check_signature(rev, result):
@@ -204,12 +231,12 @@ def check_signature(rev, result):
         timeout=GIT_TIMEOUT,
     )
     if proc.returncode != 0:
-        result.error("commit is not signed (GPG/SSH)")
+        result.error("commit is not signed (GPG/SSH)", check=Check.SIGNATURE)
         return
 
     output = proc.stderr.lower()
     sig_type = "SSH" if "ssh" in output else "GPG"
-    result.info(f"signature type: {sig_type}")
+    result.info(f"signature type: {sig_type}", check=Check.SIGNATURE)
 
 
 def _get_message(rev):
@@ -257,6 +284,8 @@ class Args:
     rev_range: str | None
     allow_empty: bool
     include_merges: bool
+    required_trailers: list
+    output: OutputFormat
 
 
 def _resolve_enabled(args, config, parser):
@@ -291,6 +320,14 @@ def _resolve_min_description_length(args, config):
     return 0
 
 
+def _resolve_required_trailers(args, config):
+    if args.require_trailer:
+        return [t.strip() for t in args.require_trailer.split(",")]
+    if config.get("require-trailers"):
+        return list(config["require-trailers"])
+    return []
+
+
 def _resolve_types(args, config):
     if args.types:
         return frozenset(t.strip() for t in args.types.split(","))
@@ -381,12 +418,23 @@ def _parse_args():
         default=False,
         help="exit 0 when --range yields no commits (default: exit 1)",
     )
+    parser.add_argument(
+        "--require-trailer",
+        metavar="TRAILER[,TRAILER,...]",
+        help="require these trailers in the commit message",
+    )
     parser.add_argument(
         "--include-merges",
         action="store_true",
         default=False,
         help="include merge commits when checking a range (default: excluded)",
     )
+    parser.add_argument(
+        "--output",
+        choices=[f.value for f in OutputFormat],
+        default=OutputFormat.TEXT,
+        help="output format: text (default) or jsonl",
+    )
     args = parser.parse_args()
     config = _load_config()
     enabled = _resolve_enabled(args, config, parser)
@@ -394,6 +442,7 @@ def _parse_args():
     allowed_types = _resolve_types(args, config)
     max_subject_length = _resolve_max_subject_length(args, config)
     min_description_length = _resolve_min_description_length(args, config)
+    required_trailers = _resolve_required_trailers(args, config)
 
     if args.allow_empty and not args.rev_range:
         parser.error("--allow-empty requires --range")
@@ -430,12 +479,29 @@ def _parse_args():
         rev_range=args.rev_range,
         allow_empty=args.allow_empty,
         include_merges=args.include_merges,
+        required_trailers=required_trailers,
+        output=OutputFormat(args.output),
     )
 
 
-def _report(result):
-    for level, msg in result.errors:
-        sys.stderr.write(f"  {PREFIXES[level]} {msg}\n")
+def _report_jsonl(result, sha, subject):
+    record = {
+        "sha": sha,
+        "subject": subject,
+        "ok": result.ok,
+        "results": [
+            {"check": check, "level": str(level), "message": msg}
+            for check, level, msg in result.errors
+        ],
+    }
+    sys.stdout.write(json.dumps(record) + "\n")
+    return 0 if result.ok else 1
+
+
+def _report_text(result):
+    for check, level, msg in result.errors:
+        prefix = f"[{check}] " if check else ""
+        sys.stderr.write(f"  {PREFIXES[level]} {prefix}{msg}\n")
 
     if result.ok:
         sys.stderr.write("  \033[32m✓\033[0m all checks passed\n")
@@ -466,6 +532,8 @@ def _run_checks(args, rev, message, result):
         check_body(lines, result)
     if Check.SIGNED_OFF in args.enabled:
         check_signed_off(message, result)
+    if args.required_trailers:
+        check_required_trailers(message, args.required_trailers, result)
     if Check.SIGNATURE in args.enabled and rev:
         check_signature(rev, result)
 
@@ -473,9 +541,6 @@ def _run_checks(args, rev, message, result):
 def main():
     args = _parse_args()
 
-    if Check.IMPERATIVE in args.enabled:
-        _ensure_nltk_data()
-
     if args.rev_range:
         revs = _get_range_revs(args.rev_range, include_merges=args.include_merges)
         if not revs:
@@ -484,13 +549,21 @@ def main():
         failed = False
         for rev in revs:
             message = _strip_comments(_get_message(rev))
-            sys.stderr.write(f"{rev[:7]} {message.split('\n')[0]}\n")
+            subject = message.split("\n")[0]
             result = Result()
             _run_checks(args, rev, message, result)
-            if _report(result) != 0:
-                failed = True
+            if args.output == OutputFormat.JSONL:
+                if _report_jsonl(result, rev, subject) != 0:
+                    failed = True
+            else:
+                sys.stderr.write(f"{rev[:7]} {subject}\n")
+                if _report_text(result) != 0:
+                    failed = True
         return 1 if failed else 0
 
+    subject = args.message.split("\n")[0]
     result = Result()
     _run_checks(args, args.rev, args.message, result)
-    return _report(result)
+    if args.output == OutputFormat.JSONL:
+        return _report_jsonl(result, args.rev, subject)
+    return _report_text(result)

{git_commit_guard-0.12.0 → git_commit_guard-0.14.0}/tests/test_git_commit_guard.py

@@ -1,3 +1,4 @@
+import json
 import subprocess
 from argparse import ArgumentParser, Namespace
 from unittest.mock import MagicMock, patch
@@ -15,13 +16,16 @@ from git_commit_guard import (
     _load_config,
     _parse_checks,
     _parse_config_checks,
-    _report,
+    _report_jsonl,
+    _report_text,
     _resolve_max_subject_length,
     _resolve_min_description_length,
+    _resolve_required_trailers,
     _resolve_types,
     _strip_comments,
     check_body,
     check_imperative,
+    check_required_trailers,
     check_signature,
     check_signed_off,
     check_subject,
@@ -171,7 +175,7 @@ class TestCheckSubject:
         r = Result()
         check_subject("fix: add x", r, min_description_length=6)
         assert not r.ok
-        assert any("description too short" in m for _, m in r.errors)
+        assert any("description too short" in m for _, _, m in r.errors)
 
     def test_min_description_length_exact_passes(self):
         r = Result()
@@ -273,6 +277,83 @@ class TestCheckSignedOff:
         assert not r.ok
 
 
+class TestCheckRequiredTrailers:
+    def test_present_passes(self):
+        r = Result()
+        check_required_trailers("fix: add x\n\nbody\n\nCloses: #42", ["Closes"], r)
+        assert r.ok
+
+    def test_missing_fails(self):
+        r = Result()
+        check_required_trailers("fix: add x\n\nbody", ["Closes"], r)
+        assert not r.ok
+        assert "missing required trailer: Closes" in r.errors[0][2]
+
+    def test_multiple_all_present_passes(self):
+        r = Result()
+        check_required_trailers(
+            "fix: add x\n\nbody\n\nCloses: #42\nReviewed-by: Jane",
+            ["Closes", "Reviewed-by"],
+            r,
+        )
+        assert r.ok
+
+    def test_multiple_one_missing_fails(self):
+        r = Result()
+        check_required_trailers(
+            "fix: add x\n\nbody\n\nCloses: #42",
+            ["Closes", "Reviewed-by"],
+            r,
+        )
+        assert not r.ok
+        assert any("Reviewed-by" in msg for _, _, msg in r.errors)
+
+    def test_case_sensitive(self):
+        r = Result()
+        check_required_trailers("fix: add x\n\nbody\n\ncloses: #42", ["Closes"], r)
+        assert not r.ok
+
+    def test_empty_required_list_always_passes(self):
+        r = Result()
+        check_required_trailers("fix: add x", [], r)
+        assert r.ok
+
+
+class TestResolveRequiredTrailers:
+    def test_defaults_to_empty(self):
+        assert _resolve_required_trailers(Namespace(require_trailer=None), {}) == []
+
+    def test_cli_flag_single(self):
+        result = _resolve_required_trailers(Namespace(require_trailer="Closes"), {})
+        assert result == ["Closes"]
+
+    def test_cli_flag_multiple(self):
+        result = _resolve_required_trailers(
+            Namespace(require_trailer="Closes,Reviewed-by"), {}
+        )
+        assert result == ["Closes", "Reviewed-by"]
+
+    def test_cli_flag_strips_spaces(self):
+        result = _resolve_required_trailers(
+            Namespace(require_trailer="Closes, Reviewed-by"), {}
+        )
+        assert result == ["Closes", "Reviewed-by"]
+
+    def test_config(self):
+        result = _resolve_required_trailers(
+            Namespace(require_trailer=None),
+            {"require-trailers": ["Closes", "Reviewed-by"]},
+        )
+        assert result == ["Closes", "Reviewed-by"]
+
+    def test_cli_overrides_config(self):
+        result = _resolve_required_trailers(
+            Namespace(require_trailer="Fixes"),
+            {"require-trailers": ["Closes"]},
+        )
+        assert result == ["Fixes"]
+
+
 class TestCheckImperative:
     def test_imperative_verb_passes(self):
         r = Result()
@@ -368,7 +449,7 @@ class TestCheckSignature:
         with patch("git_commit_guard.subprocess.run", return_value=proc):
             check_signature("abc123", r)
         assert r.ok
-        assert any("GPG" in msg for _, msg in r.errors)
+        assert any("GPG" in msg for _, _, msg in r.errors)
 
     def test_ssh_signed_commit(self):
         r = Result()
@@ -376,7 +457,7 @@ class TestCheckSignature:
         with patch("git_commit_guard.subprocess.run", return_value=proc):
             check_signature("abc123", r)
         assert r.ok
-        assert any("SSH" in msg for _, msg in r.errors)
+        assert any("SSH" in msg for _, _, msg in r.errors)
 
 
 class TestGetMessage:
@@ -525,27 +606,78 @@ class TestParseChecks:
 class TestReport:
     def test_all_passed(self, capsys):
         r = Result()
-        ret = _report(r)
+        ret = _report_text(r)
         assert ret == 0
         assert "all checks passed" in capsys.readouterr().err
 
     def test_with_error(self, capsys):
         r = Result()
         r.error("something broke")
-        ret = _report(r)
+        ret = _report_text(r)
         assert ret == 1
         assert "something broke" in capsys.readouterr().err
 
     def test_with_warning_returns_zero(self, capsys):
         r = Result()
         r.warn("heads up")
-        ret = _report(r)
+        ret = _report_text(r)
         assert ret == 0
         captured = capsys.readouterr().err
         assert "heads up" in captured
         assert "all checks passed" in captured
 
 
+class TestReportJsonl:
+    def test_ok_commit(self, capsys):
+        r = Result()
+        ret = _report_jsonl(r, "abc1234567890", "fix: add thing")
+        assert ret == 0
+        out = capsys.readouterr().out
+
+        data = json.loads(out)
+        assert data["sha"] == "abc1234567890"
+        assert data["subject"] == "fix: add thing"
+        assert data["ok"] is True
+        assert data["results"] == []
+
+    def test_failed_commit(self, capsys):
+        r = Result()
+        r.error("missing body", check="body")
+        ret = _report_jsonl(r, "abc1234567890", "fix: add thing")
+        assert ret == 1
+
+        data = json.loads(capsys.readouterr().out)
+        assert data["ok"] is False
+        assert len(data["results"]) == 1
+        assert data["results"][0] == {
+            "check": "body",
+            "level": "error",
+            "message": "missing body",
+        }
+
+    def test_null_sha(self, capsys):
+        r = Result()
+        ret = _report_jsonl(r, None, "fix: add thing")
+        assert ret == 0
+
+        data = json.loads(capsys.readouterr().out)
+        assert data["sha"] is None
+
+    def test_check_none_in_results(self, capsys):
+        r = Result()
+        r.error("missing required trailer: Closes")
+        _report_jsonl(r, "abc", "fix: add thing")
+
+        data = json.loads(capsys.readouterr().out)
+        assert data["results"][0]["check"] is None
+
+    def test_output_is_single_line(self, capsys):
+        r = Result()
+        _report_jsonl(r, "abc", "fix: add thing")
+        out = capsys.readouterr().out
+        assert out.count("\n") == 1
+
+
 _VALID_MSG = "fix: add thing\n\nbody text\n\nSigned-off-by: A User <a@b.com>"
 
 
@@ -1103,3 +1235,157 @@ class TestGetRangeRevs:
             pytest.raises(SystemExit, match="git error"),
         ):
             _get_range_revs("bogus")
+
+
+class TestRequireTrailerIntegration:
+    def test_require_trailer_flag_passes(self, tmp_path):
+        f = tmp_path / "msg"
+        f.write_text(
+            "fix: add thing\n\nbody\n\nCloses: #42\nSigned-off-by: A <a@b.com>"
+        )
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--require-trailer",
+            "Closes",
+        ]
+        with patch("sys.argv", argv):
+            assert main() == 0
+
+    def test_require_trailer_flag_fails(self, tmp_path):
+        f = tmp_path / "msg"
+        f.write_text("fix: add thing\n\nbody\n\nSigned-off-by: A <a@b.com>")
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--require-trailer",
+            "Closes",
+        ]
+        with patch("sys.argv", argv):
+            assert main() == 1
+
+    def test_require_trailer_multiple_passes(self, tmp_path):
+        f = tmp_path / "msg"
+        f.write_text(
+            "fix: add thing\n\nbody\n\n"
+            "Closes: #42\nReviewed-by: Jane\nSigned-off-by: A <a@b.com>"
+        )
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--require-trailer",
+            "Closes,Reviewed-by",
+        ]
+        with patch("sys.argv", argv):
+            assert main() == 0
+
+    def test_require_trailer_from_config(self, tmp_path):
+        f = tmp_path / "msg"
+        f.write_text("fix: add thing\n\nbody\n\nSigned-off-by: A <a@b.com>")
+        argv = ["cg", "--message-file", str(f), "--disable", "signature,imperative"]
+        with (
+            patch("sys.argv", argv),
+            patch(
+                "git_commit_guard._load_config",
+                return_value={"require-trailers": ["Closes"]},
+            ),
+        ):
+            assert main() == 1
+
+    def test_require_trailer_cli_overrides_config(self, tmp_path):
+        f = tmp_path / "msg"
+        f.write_text("fix: add thing\n\nbody\n\nFixes: #99\nSigned-off-by: A <a@b.com>")
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--require-trailer",
+            "Fixes",
+        ]
+        with (
+            patch("sys.argv", argv),
+            patch(
+                "git_commit_guard._load_config",
+                return_value={"require-trailers": ["Closes"]},
+            ),
+        ):
+            assert main() == 0
+
+
+class TestOutputJsonl:
+    def test_single_commit_ok(self, tmp_path, capsys):
+
+        f = tmp_path / "msg"
+        f.write_text(_VALID_MSG)
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--output",
+            "jsonl",
+        ]
+        with patch("sys.argv", argv):
+            assert main() == 0
+        data = json.loads(capsys.readouterr().out)
+        assert data["ok"] is True
+        assert data["subject"] == "fix: add thing"
+        assert data["sha"] is None
+
+    def test_single_commit_fail(self, tmp_path, capsys):
+
+        f = tmp_path / "msg"
+        f.write_text("fix: add thing")
+        argv = [
+            "cg",
+            "--message-file",
+            str(f),
+            "--disable",
+            "signature,imperative",
+            "--output",
+            "jsonl",
+        ]
+        with patch("sys.argv", argv):
+            assert main() == 1
+        data = json.loads(capsys.readouterr().out)
+        assert data["ok"] is False
+        assert any(r["check"] == "body" for r in data["results"])
+
+    def test_range_emits_one_line_per_commit(self, capsys):
+        revs = ["aaa", "bbb"]
+        messages = ["fix: add thing\n\nbody\n\nSigned-off-by: A <a@b.com>"] * len(revs)
+        with (
+            patch(
+                "sys.argv",
+                [
+                    "cg",
+                    "--range",
+                    "HEAD~2..HEAD",
+                    "--disable",
+                    "signature,imperative",
+                    "--output",
+                    "jsonl",
+                ],
+            ),
+            patch("git_commit_guard._get_range_revs", return_value=revs),
+            patch("git_commit_guard._get_message", side_effect=messages),
+        ):
+            assert main() == 0
+        lines = capsys.readouterr().out.strip().splitlines()
+        assert len(lines) == len(revs)
+        for line, rev in zip(lines, revs, strict=True):
+            data = json.loads(line)
+            assert data["sha"] == rev
+            assert data["ok"] is True