conventional.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/git/conventional.py
 
"""
Purpose
-------
Conventional Commits parser and validator (Phase 4D — G-D1, G-D2, G-D5).
 
Responsibilities
----------------
- Parse commit messages into structured ``ConventionalCommit`` objects.
- Validate commit messages against the Conventional Commits specification
  with Option C extensions (blueprint §6).
- Format validation errors for human-readable display.
- Analyse git diffs for ``_dbg`` diagnostics impact (ChatGPT contribution).
 
Diagnostics
-----------
Domain: GIT
Levels:
    L2 — validation lifecycle
    L3 — parsing details
    L4 — diagnostics impact analysis
 
Contracts
---------
- ``validate_commit_message`` never raises; always returns a list.
- ``parse_commit_message`` returns None for unparseable messages.
- ``analyse_diagnostics_impact`` is best-effort; returns empty list on error.
"""
 
from __future__ import annotations
 
import re
from dataclasses import dataclass, field
 
 
# =====================================================================
# Constants (blueprint §6.1)
# =====================================================================
 
COMMIT_TYPES: tuple[str, ...] = (
    "feat", "fix", "docs", "style", "refactor", "perf", "test", "chore", "sec",
)
 
MAX_SUBJECT_LENGTH: int = 72
 
# Regex for the first line of a Conventional Commit:
#   type[(scope)][!]: subject
_HEADER_RE = re.compile(
    r"^(?P<type>\w+)"          # type word
    r"(?:\‍((?P<scope>[^)]+)\‍))?"  # optional (scope)
    r"(?P<bang>!)?"            # optional breaking indicator
    r"\s*:\s*"                 # colon separator
    r"(?P<subject>.+)$"       # subject text
)
 
# Footer line detector: "Token: value" or "BREAKING CHANGE: ...".
# Compiled at module scope so parse_commit_message() doesn't recompile per call.
_FOOTER_RE = re.compile(r"^[\w-]+\s*:\s*|^BREAKING CHANGE\s*:\s*")
 
 
# =====================================================================
# Data structures
# =====================================================================
 
 
@dataclass
class ConventionalCommit:
    """Parsed representation of a Conventional Commit message."""
 
    type: str
    scope: str | None
    subject: str
    body: str
    footer: str
    breaking: bool
 
 
# =====================================================================
# Parsing
# =====================================================================
 
 
def parse_commit_message(message: str) -> ConventionalCommit | None:
    """Parse a commit message into a :class:`ConventionalCommit`.
 
    Returns ``None`` if the first line does not match the Conventional
    Commits ``type[(scope)][!]: subject`` pattern.
    """
    if not message or not message.strip():
        return None
 
    lines = message.strip().splitlines()
    header = lines[0].strip()
 
    m = _HEADER_RE.match(header)
    if m is None:
        return None
 
    # Split body and footer from remaining lines.
    body_lines: list[str] = []
    footer_lines: list[str] = []
    rest = lines[1:]
 
    # Skip leading blank line(s) between header and body.
    while rest and not rest[0].strip():
        rest = rest[1:]
 
    # Footer detection: lines matching "Token: value" or "BREAKING CHANGE: ..."
    # at the end of the message. Uses module-level _FOOTER_RE (compiled once).
    # Walk backwards to find footer start.
    footer_start = len(rest)
    for i in range(len(rest) - 1, -1, -1):
        if _FOOTER_RE.match(rest[i]):
            footer_start = i
        elif rest[i].strip() == "":
            # Blank line before footer block — footer starts after it.
            if footer_start < len(rest):
                footer_start = i + 1
            break
        else:
            break
 
    body_lines = rest[:footer_start]
    footer_lines = rest[footer_start:]
 
    # Trim trailing blank lines from body.
    while body_lines and not body_lines[-1].strip():
        body_lines.pop()
 
    breaking = bool(m.group("bang"))
    # Also check for BREAKING CHANGE footer.
    footer_text = "\n".join(footer_lines)
    if "BREAKING CHANGE" in footer_text or "BREAKING-CHANGE" in footer_text:
        breaking = True
 
    return ConventionalCommit(
        type=m.group("type"),
        scope=m.group("scope"),
        subject=m.group("subject").strip(),
        body="\n".join(body_lines),
        footer=footer_text,
        breaking=breaking,
    )
 
 
# =====================================================================
# Validation (blueprint §6.1)
# =====================================================================
 
 
def validate_commit_message(message: str) -> list[str]:
    """Validate a commit message against Conventional Commits rules.
 
    Returns a list of human-readable error strings.  An empty list
    means the message is valid.
 
    Rules checked:
    1. Must match Conventional Commits pattern.
    2. Type must be one of :data:`COMMIT_TYPES`.
    3. Subject must start with a lowercase letter.
    4. Subject must not end with a period.
    5. First line (header) must be ≤ :data:`MAX_SUBJECT_LENGTH` characters.
    6. Subject must not be empty.
    """
    errors: list[str] = []
 
    if not message or not message.strip():
        errors.append("Commit message is empty.")
        return errors
 
    parsed = parse_commit_message(message)
    if parsed is None:
        errors.append(
            "Message does not match Conventional Commits format: "
            "type[(scope)]: subject"
        )
        return errors
 
    # 2. Type check.
    if parsed.type not in COMMIT_TYPES:
        types_str = ", ".join(COMMIT_TYPES)
        errors.append(
            f'Type "{parsed.type}" is not valid. '
            f"Use one of: {types_str}"
        )
 
    # 6. Empty subject.
    if not parsed.subject:
        errors.append("Subject must not be empty.")
        return errors  # No point checking other subject rules.
 
    # 3. Lowercase first character.
    if parsed.subject[0].isupper():
        errors.append("Subject must start with a lowercase letter.")
 
    # 4. No trailing period.
    if parsed.subject.endswith("."):
        errors.append("Subject must not end with a period.")
 
    # 5. Header length (type + optional scope + colon + subject).
    header = message.strip().splitlines()[0].strip()
    if len(header) > MAX_SUBJECT_LENGTH:
        errors.append(
            f"Subject line exceeds {MAX_SUBJECT_LENGTH} characters "
            f"(was {len(header)})."
        )
 
    return errors
 
 
def format_validation_errors(errors: list[str]) -> str:
    """Format validation errors for display.
 
    Returns a multi-line string with bullet points and an example.
    """
    lines = ["Commit message validation failed:"]
    for err in errors:
        lines.append(f"  - {err}")
    lines.append("")
    lines.append("Example: fix(auth): prevent token leak in session logs")
    return "\n".join(lines)
 
 
# =====================================================================
# Diagnostics impact analysis (blueprint §6.3 — ChatGPT contribution)
# =====================================================================
 
# Regex to extract _dbg("DOMAIN", ..., LEVEL) calls from diff lines.
_DBG_CALL_RE = re.compile(
    r'_dbg\‍(\s*["\'](?P<domain>[A-Z_]+)["\']'
    r'(?:\s*,\s*[^,]+)?'  # skip func argument
    r'(?:\s*,\s*[^,]+)?'  # skip message argument
    r'(?:\s*,\s*(?P<level>\d+))?'  # optional level
)
 
 
def analyse_diagnostics_impact(diff_text: str) -> list[str]:
    """Analyse a unified diff for ``_dbg``-related changes.
 
    Scans added (``+``) and removed (``-``) lines for ``_dbg()`` calls.
    Returns a list of human-readable impact lines, e.g.::
 
        + Added: GIT domain (L2)
        - Removed: AUTH domain (L3)
 
    Returns an empty list if no ``_dbg`` changes are detected or if the
    diff cannot be parsed. This function is best-effort and never raises.
    """
    try:
        return _analyse_diagnostics_impact_inner(diff_text)
    except Exception:
        return []
 
 
def _analyse_diagnostics_impact_inner(diff_text: str) -> list[str]:
    """Inner implementation of diagnostics impact analysis."""
    added: dict[str, set[str]] = {}   # domain -> set of levels
    removed: dict[str, set[str]] = {}
 
    for line in diff_text.splitlines():
        if line.startswith("+++") or line.startswith("---"):
            continue
 
        if line.startswith("+") and "_dbg(" in line:
            m = _DBG_CALL_RE.search(line)
            if m:
                domain = m.group("domain")
                level = m.group("level") or "?"
                added.setdefault(domain, set()).add(f"L{level}")
 
        elif line.startswith("-") and "_dbg(" in line:
            m = _DBG_CALL_RE.search(line)
            if m:
                domain = m.group("domain")
                level = m.group("level") or "?"
                removed.setdefault(domain, set()).add(f"L{level}")
 
    # Build impact lines.
    impact: list[str] = []
 
    # Domains only in added.
    for domain in sorted(added.keys() - removed.keys()):
        levels = ", ".join(sorted(added[domain]))
        impact.append(f"+ Added: {domain} domain ({levels})")
 
    # Domains only in removed.
    for domain in sorted(removed.keys() - added.keys()):
        levels = ", ".join(sorted(removed[domain]))
        impact.append(f"- Removed: {domain} domain ({levels})")
 
    # Domains in both — modifications.
    for domain in sorted(added.keys() & removed.keys()):
        old_levels = ", ".join(sorted(removed[domain]))
        new_levels = ", ".join(sorted(added[domain]))
        impact.append(f"~ Modified: {domain} ({old_levels} -> {new_levels})")
 
    return impact