git-commit-guard 0.13.0__tar.gz → 0.14.1__tar.gz

{git_commit_guard-0.13.0 → git_commit_guard-0.14.1}/.github/workflows/lint-commits.yml

@@ -22,7 +22,7 @@ jobs:
           key: nltk-averaged-perceptron-tagger-punkt
       - name: Lint commits
         # yamllint disable-line rule:line-length
-        uses: benner/commit-guard@cad366366cd6d2691f7c36ff5e7a9999279906dd  # v0.12.0
+        uses: benner/commit-guard@ccb4e549f589787e294199688f20b5cb5fcac1e1  # v0.14.0
         with:
           range: origin/${{ github.base_ref }}..HEAD
           disable: signature

{git_commit_guard-0.13.0 → git_commit_guard-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-commit-guard
-Version: 0.13.0
+Version: 0.14.1
 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
@@ -31,10 +31,9 @@ imperative verb.
 
 ```bash
 $ commit-guard
-✗ subject does not match 'type(scope): description':
-  Merge pull request #5 from fix/branch
-✗ missing 'Signed-off-by' trailer
-✗ commit is not signed (GPG/SSH)
+  ✗ [subject] subject does not match 'type(scope): description': WIP
+  ✗ [signed-off] missing 'Signed-off-by' trailer
+  ✗ [signature] commit is not signed (GPG/SSH)
 ```
 
 ## Installation
@@ -224,6 +223,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
@@ -231,7 +257,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.13.0
+  - uses: benner/commit-guard@v0.14.1
 ```
 
 Check all commits in a pull request:
@@ -247,7 +273,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.13.0
+      - uses: benner/commit-guard@v0.14.1
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -265,7 +291,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.13.0
+      - uses: benner/commit-guard@v0.14.1
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -284,7 +310,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.13.0
+    rev: v0.14.1
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.13.0 → git_commit_guard-0.14.1}/README.md

@@ -10,10 +10,9 @@ imperative verb.
 
 ```bash
 $ commit-guard
-✗ subject does not match 'type(scope): description':
-  Merge pull request #5 from fix/branch
-✗ missing 'Signed-off-by' trailer
-✗ commit is not signed (GPG/SSH)
+  ✗ [subject] subject does not match 'type(scope): description': WIP
+  ✗ [signed-off] missing 'Signed-off-by' trailer
+  ✗ [signature] commit is not signed (GPG/SSH)
 ```
 
 ## Installation
@@ -203,6 +202,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
@@ -210,7 +236,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.13.0
+  - uses: benner/commit-guard@v0.14.1
 ```
 
 Check all commits in a pull request:
@@ -226,7 +252,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.13.0
+      - uses: benner/commit-guard@v0.14.1
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -244,7 +270,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.13.0
+      - uses: benner/commit-guard@v0.14.1
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -263,7 +289,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.13.0
+    rev: v0.14.1
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.13.0 → git_commit_guard-0.14.1}/action.yml

@@ -42,6 +42,9 @@ inputs:
     description: Include merge commits when checking a range
     required: false
     default: 'false'
+  require-trailer:
+    description: Comma-separated list of required trailers (e.g. Closes,Reviewed-by)
+    required: false
 runs:
   using: composite
   steps:
@@ -66,6 +69,7 @@ runs:
         CG_MIN_DESCRIPTION_LENGTH: ${{ inputs.min-description-length }}
         CG_ALLOW_EMPTY: ${{ inputs.allow-empty }}
         CG_INCLUDE_MERGES: ${{ inputs.include-merges }}
+        CG_REQUIRE_TRAILER: ${{ inputs.require-trailer }}
       run: |
         ARGS=()
         [[ -n "$CG_REV" ]] && ARGS+=("$CG_REV")
@@ -81,5 +85,6 @@ runs:
             ARGS+=(--min-description-length "$CG_MIN_DESCRIPTION_LENGTH")
         [[ "$CG_ALLOW_EMPTY" == "true" ]] && ARGS+=(--allow-empty)
         [[ "$CG_INCLUDE_MERGES" == "true" ]] && ARGS+=(--include-merges)
+        [[ -n "$CG_REQUIRE_TRAILER" ]] && ARGS+=(--require-trailer "$CG_REQUIRE_TRAILER")
         commit-guard "${ARGS[@]}"
       shell: bash

{git_commit_guard-0.13.0 → git_commit_guard-0.14.1}/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,27 +138,35 @@ 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
 
 
@@ -163,12 +177,16 @@ def check_imperative(desc, result):
         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])
@@ -177,23 +195,24 @@ 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):
@@ -212,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):
@@ -266,6 +285,7 @@ class Args:
     allow_empty: bool
     include_merges: bool
     required_trailers: list
+    output: OutputFormat
 
 
 def _resolve_enabled(args, config, parser):
@@ -409,6 +429,12 @@ def _parse_args():
         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)
@@ -454,12 +480,28 @@ def _parse_args():
         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")
@@ -507,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.13.0 → git_commit_guard-0.14.1}/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,7 +16,8 @@ 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,
@@ -173,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()
@@ -285,7 +287,7 @@ class TestCheckRequiredTrailers:
         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][1]
+        assert "missing required trailer: Closes" in r.errors[0][2]
 
     def test_multiple_all_present_passes(self):
         r = Result()
@@ -304,7 +306,7 @@ class TestCheckRequiredTrailers:
             r,
         )
         assert not r.ok
-        assert any("Reviewed-by" in msg for _, msg in r.errors)
+        assert any("Reviewed-by" in msg for _, _, msg in r.errors)
 
     def test_case_sensitive(self):
         r = Result()
@@ -447,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()
@@ -455,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:
@@ -604,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>"
 
 
@@ -1268,3 +1321,71 @@ class TestRequireTrailerIntegration:
             ),
         ):
             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