Conventional Commits skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Conventional Commits"
  short_description: "Commit types your release tooling can trust"
  default_prompt: "$conventional-commits Add commitlint with conventional commits and a husky hook to this repo"

#!/usr/bin/env python3
"""Check commit messages against Conventional Commits 1.0.0 and report the semver bump.

Usage:
  python3 check_commit_msg.py .git/COMMIT_EDITMSG        # one message file (commit-msg hook)
  python3 check_commit_msg.py --range origin/main..HEAD  # every non-merge commit in a range
  echo "feat(api): add search" | python3 check_commit_msg.py -

Options:
  --types a,b,c     allowed types (default: the @commitlint/config-conventional set)
  --scopes a,b      allowed scopes (default: any)
  --require-scope   fail when a header has no scope
  --max-header N    maximum header length (default 100, as in config-conventional)

Exit status: 0 when every message passes, 1 when any fails, 2 on usage or git errors.
Standard library only (Python 3.10+).
"""
from __future__ import annotations

import argparse
import re
import subprocess
import sys

DEFAULT_TYPES = "build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test"
HEADER = re.compile(r"^(?P<type>[A-Za-z]+)(?:\((?P<scope>[^()\r\n]*)\))?(?P<bang>!)?: (?P<desc>.*)$")
FOOTER = re.compile(r"^(?P<token>BREAKING[ -]CHANGE|[A-Za-z][\w-]*)(?:: | #)(?P<value>.*)$")
IGNORED = re.compile(r"^(Merge |Revert \"|fixup! |squash! |amend! )")
BUMP_ORDER = {"none": 0, "patch": 1, "minor": 2, "major": 3}


def clean(raw: str, strip_comments: bool) -> str:
    lines = raw.replace("\r\n", "\n").split("\n")
    if strip_comments:
        # git's default cleanup drops everything after the scissors line and '#' comments
        out = []
        for line in lines:
            if line.startswith("# ------------------------ >8"):
                break
            if not line.startswith("#"):
                out.append(line)
        lines = out
    return "\n".join(lines).strip("\n")


def check(msg: str, types: set[str], scopes: set[str] | None, require_scope: bool,
          max_header: int) -> tuple[list[str], list[str], str]:
    errors: list[str] = []
    warnings: list[str] = []
    lines = msg.split("\n")
    header = lines[0] if lines else ""
    if not header.strip():
        return ["empty commit message"], warnings, "none"
    if IGNORED.match(header):
        return errors, ["skipped (merge, git revert or fixup message)"], "none"

    m = HEADER.match(header)
    if not m:
        errors.append(f"header does not match 'type(scope)!: description': {header!r}")
        return errors, warnings, "none"

    ctype, scope, bang, desc = m["type"], m["scope"], m["bang"], m["desc"]
    if ctype != ctype.lower():
        errors.append(f"type '{ctype}' must be lower case")
    if ctype.lower() not in types:
        errors.append(f"type '{ctype}' not in allowed types: {', '.join(sorted(types))}")
    if scope is not None and not scope.strip():
        errors.append("scope is empty; drop the parentheses or name a scope")
    if require_scope and scope is None:
        errors.append("scope is required")
    if scopes is not None and scope is not None:
        for part in re.split(r"[,/]", scope):
            if part.strip() and part.strip() not in scopes:
                errors.append(f"scope '{part.strip()}' not in allowed scopes: {', '.join(sorted(scopes))}")
    if not desc.strip():
        errors.append("description is empty")
    elif desc != desc.strip():
        errors.append("description has leading or trailing whitespace")
    if desc.rstrip().endswith("."):
        errors.append("description must not end with a period")
    if desc[:1].isupper() and not desc[:2].isupper():
        warnings.append("description starts with a capital letter (config-conventional rejects sentence case)")
    if len(header) > max_header:
        errors.append(f"header is {len(header)} chars (max {max_header})")

    if len(lines) > 1 and lines[1].strip():
        errors.append("line 2 must be blank (separate header from body)")

    breaking = bool(bang)
    for line in lines[1:]:
        if re.match(r"^breaking[ -]change", line, re.IGNORECASE):
            if not re.match(r"^BREAKING[ -]CHANGE: \S", line):
                errors.append(f"breaking-change footer must read 'BREAKING CHANGE: <text>': {line!r}")
            else:
                breaking = True
    # footers must sit in the last paragraph; warn when a footer-looking line is followed by prose
    paragraphs = "\n".join(lines[1:]).strip("\n").split("\n\n") if len(lines) > 1 else []
    for para in paragraphs[:-1]:
        if all(FOOTER.match(l) for l in para.split("\n") if l.strip()) and re.search(r"BREAKING", para):
            warnings.append("BREAKING CHANGE footer is not in the final paragraph; some tools will miss it")

    if breaking:
        bump = "major"
    elif ctype.lower() == "feat":
        bump = "minor"
    elif ctype.lower() in {"fix", "perf"}:
        bump = "patch"
    else:
        bump = "none"
    return errors, warnings, bump


def messages_from_range(rng: str) -> list[tuple[str, str]]:
    try:
        out = subprocess.run(
            ["git", "log", "--no-merges", "--format=%H%x00%B%x1e", rng],
            check=True, capture_output=True, text=True,
        ).stdout
    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
        detail = getattr(exc, "stderr", "") or str(exc)
        print(f"error: git log failed for range {rng!r}: {detail.strip()}", file=sys.stderr)
        sys.exit(2)
    result = []
    for record in out.split("\x1e"):
        record = record.strip("\n")
        if not record:
            continue
        sha, _, body = record.partition("\x00")
        result.append((sha[:10], body.strip("\n")))
    return list(reversed(result))  # oldest first


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("file", nargs="?", help="message file, or '-' for stdin")
    ap.add_argument("--range", help="git revision range, e.g. origin/main..HEAD")
    ap.add_argument("--types", default=DEFAULT_TYPES)
    ap.add_argument("--scopes")
    ap.add_argument("--require-scope", action="store_true")
    ap.add_argument("--max-header", type=int, default=100)
    args = ap.parse_args()

    if bool(args.file) == bool(args.range):
        ap.print_usage(sys.stderr)
        print("error: give exactly one of FILE, '-' or --range", file=sys.stderr)
        return 2

    types = {t.strip().lower() for t in args.types.split(",") if t.strip()}
    scopes = {s.strip() for s in args.scopes.split(",")} if args.scopes else None

    if args.range:
        items = messages_from_range(args.range)
        if not items:
            print(f"no non-merge commits in {args.range}")
            return 0
    elif args.file == "-":
        items = [("stdin", clean(sys.stdin.read(), strip_comments=False))]
    else:
        try:
            with open(args.file, encoding="utf-8") as fh:
                items = [(args.file, clean(fh.read(), strip_comments=True))]
        except OSError as exc:
            print(f"error: {exc}", file=sys.stderr)
            return 2

    failed = 0
    overall = "none"
    for label, msg in items:
        errors, warnings, bump = check(msg, types, scopes, args.require_scope, args.max_header)
        header = msg.split("\n", 1)[0]
        status = "FAIL" if errors else "ok  "
        print(f"{status} {label}  [{bump}]  {header}")
        for e in errors:
            print(f"     error: {e}")
        for w in warnings:
            print(f"     warn:  {w}")
        if errors:
            failed += 1
        elif BUMP_ORDER[bump] > BUMP_ORDER[overall]:
            overall = bump

    print(f"\n{len(items) - failed}/{len(items)} messages valid; implied release bump: {overall}")
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main())