lvgl/scripts/commit_msg_check.py

#!/usr/bin/env python3

"""
LVGL Commit Message Style Checker

Format: type(scope): description

Valid types: feat, fix, arch, test, perf, example, refactor, revert, docs, style, chore, ci, build
Scope:       required (except chore/docs/ci), letters/digits/_/-/ allowed, e.g. (draw), (obj)
Description: lowercase start, no trailing period

Usage:
    commit_msg_check.py                     # Check commits between base branch and HEAD
    commit_msg_check.py --base <branch>     # Specify base branch
    commit_msg_check.py --check-title "msg" # Check a single PR title / commit message
    commit_msg_check.py --self-test         # Run self-tests

See: https://docs.lvgl.io/master/contributing/pull_requests.html#commit-message-format
"""

import os
import re
import subprocess
import sys
import argparse

VALID_TYPES = [
    "feat",
    "fix",
    "arch",
    "test",
    "perf",
    "example",
    "refactor",
    "revert",
    "docs",
    "style",
    "chore",
    "ci",
    "build",
]

# Common typos/aliases -> correct type
TYPE_TYPOS = {
    "feature": "feat",
    "fea": "feat",
    "refact": "refactor",
    "doc": "docs",
    "tests": "test",
    "bugfix": "fix",
    "hotfix": "fix",
    "perf_opt": "perf",
    "optimize": "perf",
}

VALID_TYPES_RE = "|".join(VALID_TYPES)

# type(scope): description  (chore/docs/ci allow omitting scope)
FULL_PATTERN = re.compile(rf"^({VALID_TYPES_RE})\(([a-zA-Z0-9_/-]+)\): (.+)$")

# Types that allow omitting scope
SCOPE_OPTIONAL_TYPES = {"chore", "docs", "ci"}

# type: description (no scope, for scope-optional types)
NO_SCOPE_PATTERN = re.compile(rf"^({'|'.join(SCOPE_OPTIONAL_TYPES)}): (.+)$")

# type( or type:
TYPE_ONLY_PATTERN = re.compile(r"^([a-zA-Z_]+)")

# "don't squash" PR pattern (rebase merge, title won't become commit msg)
# Covers: don't squash, dont squash, dont's squash, do not squash, do-not-squash
DONT_SQUASH_PATTERN = re.compile(
    r"(?:don'?t'?s?|do[\s-]+not)[\s-]+squash", re.IGNORECASE
)

# Commit message format documentation URL
COMMIT_MSG_DOC_URL = (
    "https://docs.lvgl.io/master/contributing/pull_requests.html"
    "#commit-message-format"
)


def check_commit_msg(msg):
    """Check a single commit message subject line.

    Returns a list of error strings. Empty list means OK.
    """
    errors = []

    # Strip leading/trailing whitespace (common in git log output)
    msg = msg.strip()

    if not msg:
        errors.append("Commit message is empty")
        return errors

    # Allow Revert commits
    if msg.startswith('Revert "'):
        return errors

    # Allow merge commits
    if msg.startswith("Merge "):
        return errors

    # Check for Chinese punctuation (common mistake)
    cn_punctuation = {
        "\uff08": "(",  # （ -> (
        "\uff09": ")",  # ） -> )
        "\uff1a": ":",  # ： -> :
        "\u3002": ".",  # 。 -> .
        "\uff0c": ",",  # ， -> ,
        "\uff1b": ";",  # ； -> ;
    }
    found_cn = [
        f"'{ch}'(U+{ord(ch):04X}) -> '{en}'"
        for ch, en in cn_punctuation.items()
        if ch in msg
    ]
    if found_cn:
        errors.append(
            f"Chinese punctuation detected: {', '.join(found_cn)}. "
            "Please use English punctuation only"
        )
        return errors

    # Extract type word
    m = TYPE_ONLY_PATTERN.match(msg)
    type_word = m.group(1) if m else ""
    type_lower = type_word.lower()

    # Check common typos first
    if type_lower in TYPE_TYPOS:
        correct = TYPE_TYPOS[type_lower]
        errors.append(f"Type '{type_word}' is not standard, did you mean '{correct}'?")
        return errors

    # Check type is valid and followed by '('
    type_with_paren = re.compile(rf"^({VALID_TYPES_RE})\(")
    if not type_with_paren.match(msg):
        # type: desc (missing scope)
        type_with_colon = re.compile(rf"^({VALID_TYPES_RE}):")
        if type_with_colon.match(msg):
            # Allow scope-optional types (chore, docs, ci) without scope
            if type_lower in SCOPE_OPTIONAL_TYPES:
                no_scope_match = NO_SCOPE_PATTERN.match(msg)
                if no_scope_match:
                    desc = no_scope_match.group(2)
                    if desc and desc[0].isupper():
                        errors.append(
                            f"Description should start with lowercase: '{desc[:30]}...'"
                        )
                    if desc.endswith("."):
                        errors.append("Description should not end with a period")
                    return errors
            errors.append(
                "Missing scope. Use 'type(scope): description' "
                "instead of 'type: description'"
            )
        elif msg and msg[0].isupper():
            errors.append(
                "Do not start with a capital letter. "
                "Use conventional commit format: type(scope): description"
            )
        else:
            errors.append(
                f"Invalid type '{type_word}'. "
                f"Allowed types: {', '.join(VALID_TYPES)}"
            )
        return errors

    # Full format check
    full = FULL_PATTERN.match(msg)
    if not full:
        # Diagnose specific issues
        empty_scope = re.compile(rf"^({VALID_TYPES_RE})\(\)")
        no_space = re.compile(rf"^({VALID_TYPES_RE})\([^)]*\):[^ ]")
        no_colon = re.compile(rf"^({VALID_TYPES_RE})\([^)]*\)[^:]")

        if empty_scope.match(msg):
            errors.append("Scope cannot be empty")
        elif no_space.match(msg):
            errors.append("Missing space after colon. Use 'type(scope): description'")
        elif no_colon.match(msg):
            errors.append("Missing colon after scope. Use 'type(scope): description'")
        else:
            # Check if scope contains filename or PR reference
            scope_match = re.match(rf"^({VALID_TYPES_RE})\(([^)]+)\): .+", msg)
            if scope_match:
                scope = scope_match.group(2)
                if re.search(r"\.[a-zA-Z]+$", scope):
                    errors.append(
                        f"Scope '{scope}' looks like a filename. "
                        "Use a module name instead, e.g. 'obj' not 'lv_obj.h'"
                    )
                elif "#" in scope:
                    errors.append(
                        f"Scope '{scope}' should be a module name, "
                        "not a PR reference. Put PR number in description, "
                        "e.g. 'fix(module): description (#1234)'"
                    )
                else:
                    errors.append("Invalid format. Expected: type(scope): description")
            else:
                errors.append("Invalid format. Expected: type(scope): description")
        return errors

    # Validate description
    desc = full.group(3)

    if desc and desc[0].isupper():
        errors.append(f"Description should start with lowercase: '{desc[:30]}...'")

    if desc.endswith("."):
        errors.append("Description should not end with a period")

    return errors


def git_run(*args):
    """Run a git command and return stdout."""
    result = subprocess.run(["git"] + list(args), capture_output=True, text=True)
    return result.stdout.strip(), result.returncode


def find_base_branch():
    """Find the base branch for comparison."""
    candidates = ["origin/master", "origin/main", "upstream/master", "upstream/main"]
    for branch in candidates:
        _, rc = git_run("rev-parse", "--verify", branch)
        if rc == 0:
            return branch
    return None


def check_commits(base_branch=None, last_n=None):
    """Check all commits between base branch and HEAD."""
    if last_n:
        log_output, _ = git_run("log", "--oneline", f"-{last_n}")
        if not log_output:
            print("No commits to check.")
            return 0
        print(f"Checking commit message style (last {last_n} commits)...")
    else:
        if not base_branch:
            base_branch = find_base_branch()
            if not base_branch:
                print(
                    "Warning: Could not determine base branch, "
                    "skipping commit message style check."
                )
                return 0

        merge_base, rc = git_run("merge-base", base_branch, "HEAD")
        if rc != 0 or not merge_base:
            print(
                "Warning: Could not determine merge base, "
                "skipping commit message style check."
            )
            return 0

        head, _ = git_run("rev-parse", "HEAD")
        if head == merge_base:
            print("No new commits to check, skipping commit message style check.")
            return 0

        log_output, _ = git_run("log", "--oneline", f"{merge_base}..HEAD")
        if not log_output:
            print("No new commits to check.")
            return 0

        print(f"Checking commit message style (base: {base_branch})...")

    error_count = 0
    total_count = 0
    for line in log_output.splitlines():
        parts = line.split(" ", 1)
        if len(parts) < 2:
            continue
        hash_str, msg = parts[0], parts[1]
        total_count += 1
        errors = check_commit_msg(msg)
        if errors:
            error_count += 1
            print(f"\n  Commit: {hash_str[:12]} {msg}")
            for e in errors:
                print(f"  ✗ {e}")
        else:
            print(f"  ✓ {hash_str[:12]} {msg}")

    if error_count > 0:
        print(
            f"""
==========================================
 Commit message style check FAILED
 {error_count} commit(s) with bad format
==========================================

Expected format: type(scope): description

  Valid types: {', '.join(VALID_TYPES)}
  Scope:       required (except chore/docs/ci), e.g. (draw), (obj), (style)
  Description: lowercase start, no trailing period

Good examples:
  feat(draw): add new gradient support
  fix(obj): fix crash when object is deleted
  test(cache): add complete cache test cases
  perf(style): optimize style removal performance

See: {COMMIT_MSG_DOC_URL}

Use 'git commit --amend' or 'git rebase -i' to fix your commit messages."""
        )
        return 1

    print("Commit message style check passed")
    return 0


# ============================================================================
# Self-test
# ============================================================================


def self_test():
    """Run self-tests to verify the checker works correctly."""

    pass_cases = [
        # Standard format
        ("feat(draw): add support for dashed line rendering", "standard feat"),
        ("fix(render): resolve null pointer in flush callback", "standard fix"),
        ("test(cache): add unit tests for eviction policy", "standard test"),
        ("perf(style): reduce redundant lookups in style resolve", "standard perf"),
        ("refactor(obj): split tree logic into separate module", "standard refactor"),
        ("docs(readme): update build instructions for linux", "standard docs"),
        ("style(src): apply clang-format to all source files", "standard style"),
        ("chore(deps): bump third-party library to latest tag", "standard chore"),
        ("ci(github): add workflow for automated testing", "standard ci"),
        ("build(cmake): add option to disable example targets", "standard build"),
        ("arch(core): restructure module dependency graph", "standard arch"),
        ("example(widgets): add demo for new button styles", "standard example"),
        # Scope with special chars
        ("fix(mod_a/sub_b): handle edge case in sub module", "scope with slash"),
        ("fix(draw-sw): prevent buffer overflow in blend op", "scope with hyphen"),
        ("feat(widget_v2): expose new public api for widgets", "scope with underscore"),
        ("feat(myGFX): add hardware acceleration support", "scope with uppercase"),
        # Revert / Merge (always allowed)
        ('Revert "fix(render): disable fast path for now"', "revert commit"),
        ("Merge branch 'main' into dev", "merge commit"),
        ("revert(render): undo fast path optimization change", "revert with scope"),
        # Edge: description exactly 10 chars
        ("feat(core): 0123456789", "description exactly 10 chars"),
        # PR number in description
        ("fix(render): handle opacity reset on layer fail (#9521)", "with PR number"),
        # chore/docs/ci without scope (allowed)
        ("chore: bump version to release candidate tag", "chore without scope"),
        ("chore: fix typos in configuration file names", "chore without scope 2"),
        ("docs: fix typos", "docs without scope"),
        ("docs: add hero image", "docs without scope 2"),
        ("ci: add workflow for automated testing", "ci without scope"),
        ("ci: deploy doc builds to release folders", "ci without scope 2"),
        # Leading/trailing whitespace (should be stripped)
        ("  feat(draw): add gradient support  ", "leading/trailing spaces"),
    ]

    # Don't squash cases: should pass check_title() but NOT check_commit_msg()
    dont_squash_cases = [
        ("Dont's squash: minor docs fixes", "dont squash variant 1"),
        (
            "Dont' Squash: improvements and fixes to workflow",
            "dont squash variant 2",
        ),
        ("Dont's squash - gradient updates", "dont squash variant 3"),
        (
            "feat(gdb): add lvgl GDB plugin (don't squash)",
            "dont squash in parens",
        ),
        ("DONT SQUASH: feat(draw): add new gradient support", "dont squash caps"),
        ("dont squash - multiple independent fixes", "dont squash lowercase"),
        ("do not squash: multiple independent fixes", "do not squash"),
        ("do-not-squash: multiple independent fixes", "do-not-squash"),
    ]

    fail_cases = [
        # Common typos
        ("feature(anim): add transition support for opacity", "typo: feature -> feat"),
        ("fea(scroll): add force elastic attribute to scroll", "typo: fea -> feat"),
        (
            "refact(gif): restructure decoder and add testcase",
            "typo: refact -> refactor",
        ),
        ("doc(readme): update build instructions for linux", "typo: doc -> docs"),
        ("tests(cache): add unit tests for eviction policy", "typo: tests -> test"),
        ("bugfix(render): resolve null pointer in callback", "typo: bugfix -> fix"),
        ("hotfix(obj): fix crash when object is deleted", "typo: hotfix -> fix"),
        # Missing scope
        ("fix: handle invalid escape sequence in parser", "missing scope"),
        ("feat: add something really cool to the project", "missing scope"),
        ("test: add unit tests without specifying a scope", "missing scope test"),
        # Capital letter start (no type)
        ("Add new parameter for module initialization", "capital letter start"),
        ("Update documentation with new build instructions", "capital letter start"),
        # Invalid type
        ("update(core): change default config values here", "invalid type"),
        ("add(draw): introduce new gradient for objects", "invalid type"),
        ("wayland: add API to get fullscreen state", "invalid type module name"),
        # Empty scope
        ("feat(): add something without a scope name", "empty scope"),
        # Missing space after colon
        ("feat(draw):implement dashed line rendering now", "no space after colon"),
        ("fix(parser):handle edge case in token scanner", "no space after colon 2"),
        # Scope is a filename (not allowed)
        ("fix(helper_sw.c): prevent buffer overflow in blend", "scope is filename .c"),
        ("feat(lv_obj.h): expose new public api for widgets", "scope is filename .h"),
        ("docs(README.md): update build instructions for dev", "scope is filename .md"),
        # Scope is a PR reference (not allowed)
        (
            "fix(PR#1234): address review comments from reviewer",
            "scope is PR reference",
        ),
        # Space before colon
        ("fix(parser) :handle edge case in token scanner", "space before colon"),
        # Missing colon
        ("feat(draw) implement dashed line rendering now", "no colon after scope"),
        # Description starts with uppercase
        ("feat(draw): Implement dashed line rendering now", "uppercase description"),
        ("fix(scale): Don't return early on main drawing", "uppercase contraction"),
        (
            "chore(cmsis-pack): Prepare for v9.5.0",
            "uppercase description chore with scope",
        ),
        # Description ends with period
        ("feat(draw): implement dashed line rendering now.", "trailing period"),
        (
            "feat(nema_gfx): integrate hardware acceleration.",
            "trailing period 2",
        ),
        # Chinese punctuation
        ("fix\uff08draw\uff09: handle edge case in flush callback", "chinese parens"),
        ("fix(draw)\uff1ahandle edge case in flush callback", "chinese colon"),
        ("fix(draw): handle edge case in flush callback\u3002", "chinese period"),
        (
            "fix(draw)\uff1a handle edge case in flush callback",
            "chinese colon with space",
        ),
        (
            "feat\uff08core\uff09\uff1aadd new public api for widget tree",
            "all chinese punctuation",
        ),
        # Random garbage
        ("this is not a valid commit message at all", "random text"),
        ("just some random words without any structure", "random text 2"),
        ("WIP something something something something", "WIP commit"),
        ("Feat/lv check obj", "branch name as title"),
        ("Initial commit", "initial commit"),
        # Empty message
        ("", "empty message"),
        ("   ", "whitespace only"),
    ]

    passed = 0
    failed = 0
    total = len(pass_cases) + len(fail_cases)

    print("=" * 60)
    print(" Commit Message Checker Self-Test")
    print("=" * 60)

    # Test cases that should PASS
    print("\n--- Should PASS ---")
    for msg, desc in pass_cases:
        errors = check_commit_msg(msg)
        if not errors:
            passed += 1
            print(f"  ✓ PASS  [{desc}]")
        else:
            failed += 1
            print(f"  ✗ FAIL  [{desc}]")
            print(f"          msg: {msg}")
            for e in errors:
                print(f"          err: {e}")

    # Test cases that should FAIL
    print("\n--- Should FAIL ---")
    for msg, desc in fail_cases:
        errors = check_commit_msg(msg)
        if errors:
            passed += 1
            print(f"  ✓ PASS  [{desc}] -> caught: {errors[0]}")
        else:
            failed += 1
            print(f"  ✗ FAIL  [{desc}] -> should have been rejected!")
            print(f"          msg: {msg}")

    # Test don't squash: should bypass check_title() but NOT check_commit_msg()
    total += len(dont_squash_cases)
    print("\n--- Don't Squash (check_title should pass, check_commit_msg should fail) ---")
    for msg, desc in dont_squash_cases:
        title_rc = check_title(msg)
        commit_errors = check_commit_msg(msg)
        # check_title should return 0 (pass) due to don't squash bypass
        # check_commit_msg should return errors (unless msg is independently valid)
        msg_is_valid = not check_commit_msg(msg.replace("don't squash", "").replace("dont squash", ""))
        if title_rc == 0 and (commit_errors or msg_is_valid):
            passed += 1
            if commit_errors:
                print(f"  ✓ PASS  [{desc}] -> title bypassed, commit rejected")
            else:
                print(f"  ✓ PASS  [{desc}] -> title bypassed, commit valid independently")
        else:
            failed += 1
            if title_rc != 0:
                print(f"  ✗ FAIL  [{desc}] -> check_title should have bypassed!")
            else:
                print(f"  ✗ FAIL  [{desc}] -> check_commit_msg should have rejected!")
            print(f"          msg: {msg}")

    print(f"\n{'=' * 60}")

    # Lint self
    total += 1
    print(f"\n{'=' * 60}")
    print(" Lint Check (self)")
    print(f"{'=' * 60}")

    script_path = os.path.abspath(__file__)
    lint_failed = False

    # Syntax check
    try:
        import py_compile

        py_compile.compile(script_path, doraise=True)
        print("  ✓ py_compile: syntax OK")
    except py_compile.PyCompileError as e:
        print(f"  ✗ py_compile: {e}")
        lint_failed = True

    # flake8 if available
    try:
        result = subprocess.run(
            ["flake8", "--max-line-length=120", "--ignore=E501,W503", script_path],
            capture_output=True,
            text=True,
        )
        if result.returncode == 0:
            print("  ✓ flake8: no issues")
        else:
            print("  ✗ flake8:")
            for line in result.stdout.strip().splitlines():
                print(f"    {line}")
            lint_failed = True
    except FileNotFoundError:
        print("  - flake8: not installed, skipped")

    if lint_failed:
        failed += 1
    else:
        passed += 1

    print(f"\n{'=' * 60}")
    print(f" Final Results: {passed}/{total} passed, {failed} failed")
    print(f"{'=' * 60}")

    return 0 if failed == 0 else 1


def check_title(title):
    """Check a single PR title / commit message string."""
    # Allow "don't squash" PRs (rebase merge, title won't become commit msg)
    if DONT_SQUASH_PATTERN.search(title):
        print(f"✓ PR title OK (don't squash): {title}")
        return 0
    errors = check_commit_msg(title)
    if errors:
        print(f"\n  PR Title: {title}")
        for e in errors:
            print(f"  ✗ {e}")
        print(
            f"\nExpected format: type(scope): description\n"
            f"\n"
            f"  Valid types: {', '.join(VALID_TYPES)}\n"
            f"  Scope:       required (except chore/docs/ci), e.g. (draw), (obj)\n"
            f"  Description: lowercase start, no trailing period\n"
            f"\n"
            f"Examples:\n"
            f"  feat(draw): add new gradient support\n"
            f"  fix(obj): fix crash when object is deleted\n"
            f"\n"
            f"See: {COMMIT_MSG_DOC_URL}"
        )
        return 1
    print(f"✓ PR title OK: {title}")
    return 0


def main():
    parser = argparse.ArgumentParser(description="LVGL Commit Message Style Checker")
    parser.add_argument(
        "--self-test", action="store_true", help="Run self-tests to verify the checker"
    )
    parser.add_argument(
        "--base",
        type=str,
        default=None,
        help="Base branch for comparison (auto-detected if omitted)",
    )
    parser.add_argument(
        "--last",
        type=int,
        default=None,
        help="Check the last N commits (useful for local testing)",
    )
    parser.add_argument(
        "--check-title",
        type=str,
        default=None,
        help="Check a single PR title / commit message string",
    )
    args = parser.parse_args()

    if args.self_test:
        return self_test()

    if args.check_title is not None:
        return check_title(args.check_title)

    return check_commits(args.base, args.last)


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