commit-shield 0.2.0__py3-none-any.whl

commit_guard/__init__.py

@@ -0,0 +1,5 @@
+"""
+commit-guard: Lightweight, zero-dependency Git commit message and file linter.
+"""
+
+__version__ = "0.2.0"

commit_guard/_toml.py

@@ -0,0 +1,276 @@
+"""
+Minimal TOML reader for commit-guard configuration files.
+
+Python 3.11+ ships ``tomllib``; on older interpreters we fall back to the
+parser in this module. It deliberately supports only the subset of TOML that
+commit-guard configuration actually uses:
+
+* comments
+* table headers, including dotted ones (``[tool.commit-guard]``)
+* string, integer, float and boolean values
+* arrays of strings/numbers, written on one line or across several
+
+Anything outside that subset raises :class:`TomlError` rather than being
+silently misread. This is not a general-purpose TOML implementation and is not
+intended to become one.
+"""
+
+import re
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+__all__ = ["loads", "TomlError"]
+
+
+class TomlError(ValueError):
+    """Raised when configuration text cannot be parsed."""
+
+
+# Typed as Optional[Any] so both branches type-check: tomllib does not
+# exist below Python 3.11, where this falls back to the parser below.
+_tomllib: Optional[Any]
+if sys.version_info >= (3, 11):
+    import tomllib as _tomllib_mod
+
+    _tomllib = _tomllib_mod
+else:
+    _tomllib = None
+
+
+_TABLE_RE = re.compile(r"^\[([^\[\]]+)\]$")
+_KEY_RE = re.compile(r"^([A-Za-z0-9_\-.]+)\s*=\s*(.*)$")
+
+
+def loads(text: str) -> Dict[str, Any]:
+    """Parse TOML text into nested dictionaries."""
+    if _tomllib is not None:
+        try:
+            return _tomllib.loads(text)
+        except Exception as exc:  # tomllib raises TOMLDecodeError
+            raise TomlError(str(exc)) from exc
+    return _fallback_loads(text)
+
+
+def _fallback_loads(text: str) -> Dict[str, Any]:
+    root: Dict[str, Any] = {}
+    table = root
+    lines = text.splitlines()
+    index = 0
+
+    while index < len(lines):
+        raw = lines[index]
+        index += 1
+        line = _strip_comment(raw).strip()
+        if not line:
+            continue
+
+        table_match = _TABLE_RE.match(line)
+        if table_match:
+            table = _resolve_table(root, table_match.group(1).strip())
+            continue
+
+        key_match = _KEY_RE.match(line)
+        if not key_match:
+            raise TomlError("cannot parse line: {0!r}".format(raw.strip()))
+
+        key, value_text = key_match.group(1), key_match.group(2).strip()
+
+        # An array may continue over later lines until brackets balance.
+        if value_text.startswith("[") and not _brackets_balanced(value_text):
+            parts = [value_text]
+            while index < len(lines):
+                parts.append(_strip_comment(lines[index]).strip())
+                index += 1
+                if _brackets_balanced(" ".join(parts)):
+                    break
+            else:
+                raise TomlError("unterminated array for key {0!r}".format(key))
+            value_text = " ".join(parts)
+
+        _assign(table, key, _parse_value(value_text))
+
+    return root
+
+
+def _strip_comment(line: str) -> str:
+    """Remove a trailing comment, ignoring '#' inside quoted strings."""
+    out: List[str] = []
+    quote = ""
+    for char in line:
+        if quote:
+            out.append(char)
+            if char == quote:
+                quote = ""
+            continue
+        if char == '"' or char == "'":
+            quote = char
+            out.append(char)
+            continue
+        if char == "#":
+            break
+        out.append(char)
+    return "".join(out)
+
+
+def _brackets_balanced(text: str) -> bool:
+    depth = 0
+    quote = ""
+    for char in text:
+        if quote:
+            if char == quote:
+                quote = ""
+            continue
+        if char == '"' or char == "'":
+            quote = char
+        elif char == "[":
+            depth += 1
+        elif char == "]":
+            depth -= 1
+    return depth == 0
+
+
+def _resolve_table(root: Dict[str, Any], header: str) -> Dict[str, Any]:
+    node = root
+    for part in _split_dotted(header):
+        existing = node.get(part)
+        if existing is None:
+            existing = {}
+            node[part] = existing
+        elif not isinstance(existing, dict):
+            raise TomlError("cannot redefine {0!r} as a table".format(part))
+        node = existing
+    return node
+
+
+def _assign(table: Dict[str, Any], key: str, value: Any) -> None:
+    parts = _split_dotted(key)
+    node = table
+    for part in parts[:-1]:
+        existing = node.get(part)
+        if existing is None:
+            existing = {}
+            node[part] = existing
+        elif not isinstance(existing, dict):
+            raise TomlError("cannot assign into non-table {0!r}".format(part))
+        node = existing
+    node[parts[-1]] = value
+
+
+def _split_dotted(name: str) -> List[str]:
+    """Split a dotted key or header, honouring quoted segments."""
+    parts: List[str] = []
+    current: List[str] = []
+    quote = ""
+    for char in name:
+        if quote:
+            if char == quote:
+                quote = ""
+            else:
+                current.append(char)
+            continue
+        if char == '"' or char == "'":
+            quote = char
+            continue
+        if char == ".":
+            parts.append("".join(current).strip())
+            current = []
+            continue
+        current.append(char)
+    parts.append("".join(current).strip())
+
+    cleaned = [part for part in parts if part]
+    if not cleaned:
+        raise TomlError("empty key or table name: {0!r}".format(name))
+    return cleaned
+
+
+def _parse_value(text: str) -> Any:
+    if not text:
+        raise TomlError("missing value")
+
+    if text.startswith("["):
+        return _parse_array(text)
+    if text[0] == '"' or text[0] == "'":
+        value, rest = _parse_string(text)
+        if rest.strip():
+            raise TomlError("trailing text after string: {0!r}".format(rest))
+        return value
+    if text == "true" or text == "false":
+        return text == "true"
+
+    try:
+        return int(text.replace("_", ""))
+    except ValueError:
+        pass
+    try:
+        return float(text.replace("_", ""))
+    except ValueError:
+        pass
+    raise TomlError("unsupported value: {0!r}".format(text))
+
+
+def _parse_array(text: str) -> List[Any]:
+    if not text.startswith("[") or not text.endswith("]"):
+        raise TomlError("malformed array: {0!r}".format(text))
+    body = text[1:-1].strip()
+    if not body:
+        return []
+
+    items: List[Any] = []
+    rest = body
+    while rest:
+        rest = rest.lstrip()
+        if not rest:
+            break
+        if rest[0] == '"' or rest[0] == "'":
+            value, rest = _parse_string(rest)
+            items.append(value)
+        else:
+            chunk, _, rest = rest.partition(",")
+            chunk = chunk.strip()
+            if chunk:
+                items.append(_parse_value(chunk))
+            continue
+        rest = rest.lstrip()
+        if rest.startswith(","):
+            rest = rest[1:]
+        elif rest:
+            raise TomlError("expected a comma in array near {0!r}".format(rest))
+    return items
+
+
+def _parse_string(text: str) -> Tuple[str, str]:
+    """Read one string literal, returning it plus the unconsumed remainder."""
+    quote = text[0]
+    literal = quote == "'"
+    out: List[str] = []
+    index = 1
+    while index < len(text):
+        char = text[index]
+        if not literal and char == "\\":
+            index += 1
+            if index >= len(text):
+                raise TomlError("dangling escape in string")
+            out.append(_unescape(text[index]))
+        elif char == quote:
+            return "".join(out), text[index + 1 :]
+        else:
+            out.append(char)
+        index += 1
+    raise TomlError("unterminated string: {0!r}".format(text))
+
+
+_ESCAPES = {
+    "n": "\n",
+    "t": "\t",
+    "r": "\r",
+    '"': '"',
+    "\\": "\\",
+    "'": "'",
+}
+
+
+def _unescape(char: str) -> str:
+    if char not in _ESCAPES:
+        raise TomlError("unsupported escape sequence")
+    return _ESCAPES[char]

commit_guard/checkers.py

@@ -0,0 +1,277 @@
+"""
+Core validation logic for commit messages and staged files.
+Zero external dependencies (uses only standard library).
+"""
+
+import fnmatch
+import os
+import re
+from typing import List, Optional, Sequence, Tuple
+
+from commit_guard.config import DEFAULT_TYPES, Config
+
+# Kept for backward compatibility with code that imported these in v0.1.x.
+# The authoritative values now live in commit_guard.config.
+CONVENTIONAL_TYPES = set(DEFAULT_TYPES)
+
+# Regex pattern for Conventional Commits
+CONVENTIONAL_REGEX = re.compile(
+    r"^(?P<type>[a-zA-Z]+)"  # type
+    r"(?:\((?P<scope>[a-zA-Z0-9_\-./,\s]+)\))?"  # optional scope
+    r"(?P<breaking>!)?"  # optional breaking marker
+    r":[ ]+"  # separator
+    r"(?P<subject>.+)$"  # commit subject
+)
+
+_DEFAULT_CONFIG = Config()
+
+
+def _config_or_default(config: Optional[Config]) -> Config:
+    return config if config is not None else _DEFAULT_CONFIG
+
+
+def is_skippable_message(msg: str, config: Optional[Config] = None) -> bool:
+    """
+    Report whether a commit message is one git generates rather than one the
+    author wrote: merges, reverts, and rebase fixup/squash markers.
+
+    Validating these blocks ordinary git workflows, since their format is not
+    the author's to control.
+    """
+    cfg = _config_or_default(config)
+    if not cfg.skip_merge_commits:
+        return False
+
+    header = _first_meaningful_line(msg)
+    if header is None:
+        return False
+
+    lowered = header.lower()
+    return any(lowered.startswith(prefix) for prefix in cfg.skip_prefixes)
+
+
+def _first_meaningful_line(msg: str) -> Optional[str]:
+    """Return the first non-blank, non-comment line, or None."""
+    for line in msg.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            return stripped
+    return None
+
+
+def check_commit_message(
+    msg: str,
+    max_header_len: Optional[int] = None,
+    config: Optional[Config] = None,
+) -> Tuple[bool, List[str]]:
+    """
+    Validate commit message against Conventional Commits standard.
+    Returns (is_valid, list_of_error_messages).
+
+    ``max_header_len`` overrides the configured limit; it is kept as a named
+    parameter because v0.1.x callers passed it positionally.
+    """
+    cfg = _config_or_default(config)
+    header_limit = max_header_len if max_header_len is not None else cfg.max_header_len
+
+    # Generated merge/revert/fixup messages are not the author's to format.
+    if is_skippable_message(msg, cfg):
+        return True, []
+
+    errors: List[str] = []
+
+    # Strip comments (lines starting with #) and trailing whitespace
+    lines = [
+        line.strip()
+        for line in msg.splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+
+    if not lines:
+        return False, ["Commit message cannot be empty."]
+
+    header = lines[0]
+
+    if header_limit and len(header) > header_limit:
+        errors.append(
+            "Commit header too long ({0} chars > {1} limit).".format(
+                len(header), header_limit
+            )
+        )
+
+    match = CONVENTIONAL_REGEX.match(header)
+    if not match:
+        errors.append(
+            "Header does not follow Conventional Commits format: "
+            "'<type>(<scope>): <description>'.\n"
+            "  Received: '{0}'\n"
+            "  Allowed types: {1}".format(header, ", ".join(sorted(cfg.types)))
+        )
+    else:
+        errors.extend(_check_header_parts(match, cfg))
+
+    errors.extend(_check_body(msg, cfg))
+    return len(errors) == 0, errors
+
+
+def _check_header_parts(match: "re.Match", cfg: Config) -> List[str]:
+    """Validate the type, scope and subject of a parsed header."""
+    errors: List[str] = []
+
+    ctype = match.group("type")
+    if ctype not in cfg.types:
+        # Catch the common near-miss of an uppercase or mixed-case type.
+        if ctype.lower() in cfg.types:
+            errors.append(
+                "Commit type must be lowercase: '{0}' should be '{1}'.".format(
+                    ctype, ctype.lower()
+                )
+            )
+        else:
+            errors.append(
+                "Unknown commit type: '{0}'. Allowed: {1}".format(
+                    ctype, ", ".join(sorted(cfg.types))
+                )
+            )
+
+    scope = match.group("scope")
+    if cfg.require_scope and not scope:
+        errors.append(
+            "A scope is required. Allowed scopes: {0}".format(
+                ", ".join(sorted(cfg.scopes))
+            )
+        )
+    elif scope and cfg.scopes:
+        # A comma-separated scope list is valid Conventional Commits.
+        for part in (p.strip() for p in scope.split(",")):
+            if part and part not in cfg.scopes:
+                errors.append(
+                    "Unknown scope: '{0}'. Allowed: {1}".format(
+                        part, ", ".join(sorted(cfg.scopes))
+                    )
+                )
+
+    subject = match.group("subject").strip()
+    if len(subject) < cfg.subject_min_len:
+        errors.append(
+            "Commit description is too short (minimum {0} characters).".format(
+                cfg.subject_min_len
+            )
+        )
+    if subject.endswith(".") and not cfg.allow_trailing_period:
+        errors.append("Commit description should not end with a period ('.').")
+
+    return errors
+
+
+def _check_body(msg: str, cfg: Config) -> List[str]:
+    """Validate the blank-line separator and body line lengths."""
+    errors: List[str] = []
+
+    raw_lines = [line for line in msg.splitlines() if not line.strip().startswith("#")]
+
+    # Drop leading blank lines so the header is at index 0.
+    while raw_lines and not raw_lines[0].strip():
+        raw_lines.pop(0)
+
+    if len(raw_lines) > 1 and raw_lines[1].strip() != "":
+        errors.append(
+            "There must be an empty blank line between commit header and body."
+        )
+
+    if cfg.max_body_line_len:
+        for number, line in enumerate(raw_lines[2:], start=3):
+            stripped = line.rstrip()
+            if len(stripped) <= cfg.max_body_line_len:
+                continue
+            # Long URLs and footer trailers cannot be wrapped usefully.
+            if _is_unwrappable(stripped):
+                continue
+            errors.append(
+                "Body line {0} too long ({1} chars > {2} limit).".format(
+                    number, len(stripped), cfg.max_body_line_len
+                )
+            )
+
+    return errors
+
+
+_TRAILER_RE = re.compile(r"^[A-Za-z][A-Za-z\-]*:\s")
+
+
+def _is_unwrappable(line: str) -> bool:
+    """Lines that cannot reasonably be wrapped: URLs, trailers, code."""
+    if "://" in line:
+        return True
+    if _TRAILER_RE.match(line):
+        return True
+    return line.startswith(("    ", "\t", "|", ">"))
+
+
+def is_allowlisted(path: str, allowlist: Sequence[str]) -> bool:
+    """
+    Report whether a path is exempt from sensitive-name matching.
+
+    Each entry is a glob. It is matched against the full path and against the
+    basename, so 'docs/keys/*' and '*.example' both behave as expected.
+    """
+    norm = path.replace("\\", "/")
+    base = os.path.basename(norm)
+    for pattern in allowlist:
+        clean = pattern.replace("\\", "/")
+        if fnmatch.fnmatch(norm, clean) or fnmatch.fnmatch(base, clean):
+            return True
+        # A bare directory entry exempts everything beneath it.
+        if clean.endswith("/") and norm.startswith(clean):
+            return True
+    return False
+
+
+def check_file_path(
+    path: str,
+    max_size_mb: Optional[float] = None,
+    config: Optional[Config] = None,
+    size_bytes: Optional[int] = None,
+) -> Tuple[bool, List[str]]:
+    """
+    Validate an individual file path for size and sensitive filename patterns.
+    Returns (is_valid, list_of_warning_messages).
+
+    ``size_bytes`` supplies the staged blob size; when omitted the working-tree
+    file is measured instead.
+    """
+    cfg = _config_or_default(config)
+    size_limit = max_size_mb if max_size_mb is not None else cfg.max_size_mb
+
+    issues: List[str] = []
+    norm_path = path.replace("\\", "/")
+
+    if not is_allowlisted(norm_path, cfg.allowlist):
+        for pattern in cfg.sensitive_patterns:
+            try:
+                compiled = re.compile(pattern, re.IGNORECASE)
+            except re.error as exc:
+                issues.append(
+                    "Invalid sensitive pattern {0!r}: {1}".format(pattern, exc)
+                )
+                continue
+            if compiled.search(norm_path):
+                issues.append(
+                    "Potentially sensitive file detected: '{0}'. "
+                    "Avoid committing secrets.".format(path)
+                )
+                break
+
+    measured = size_bytes
+    if measured is None and os.path.isfile(path):
+        measured = os.path.getsize(path)
+
+    if measured is not None and size_limit:
+        size_mb = measured / (1024 * 1024)
+        if size_mb > size_limit:
+            issues.append(
+                "File '{0}' exceeds max allowed size ({1:.2f} MB > {2} MB limit). "
+                "Consider using Git LFS.".format(path, size_mb, size_limit)
+            )
+
+    return len(issues) == 0, issues