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.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import re
from dataclasses import dataclass, field
from oct.core.diagnostics import _dbg
 
 
# =====================================================================
# 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(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    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*")
 
# Option C plan-prefix extension (Plan 151 T6 - routed oct fix ii).
# Commit subjects in Option C repos carry a leading bracketed plan/area
# prefix ahead of the Conventional Commits header, e.g.
#   "[151.T6][oct] feat: bound the root walk-up"
# The prefix is project metadata (plan id / tranche / area), not part of
# the Conventional Commits subject; the header is parsed and length-checked
# on the text that FOLLOWS this optional prefix. One or more adjacent
# ``[...]`` groups are accepted (each non-empty, single-line), plus any
# trailing whitespace. Anchored at start, so a bracket that merely appears
# inside a subject (e.g. "feat: add [beta] flag") is never treated as a
# prefix.
_PLAN_PREFIX_RE = re.compile(r"^(?:\‍[[^\‍]\n]+\‍]\s*)+")
 
# AI-Model trailer detector (Plan 151 T6 - inventory item 4 / R03 F-08).
# The Option C commit-forensics convention requires every commit body to
# carry an ``AI-Model: <name> <version>`` trailer line identifying the LLM
# that did the reasoning. Presence validation only - the value must name at
# least a model and a version (>= 2 whitespace-separated tokens).
_AI_MODEL_TRAILER_RE = re.compile(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    r"(?m)^[ \t]*AI-Model:[ \t]*(?P<value>\S.*)$"
)
 
 
def _strip_plan_prefix(header: str) -> str:
    """Return *header* without an optional leading Option C plan/area prefix.
 
    ``"[151.T6][oct] feat: x"`` -> ``"feat: x"``; a header with no leading
    ``[...]`` prefix is returned unchanged. Used by both the parser and the
    header-length validator so the Conventional Commits rules apply to the
    conventional portion, not the project metadata.
    """
    m = _PLAN_PREFIX_RE.match(header)
    return header[m.end():] if m else header
 
 
# =====================================================================
# 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.
    """
    func = "parse_commit_message"
    _dbg("GIT", func, f"parsing a {len(message)}-char commit message", 4)
    if not message or not message.strip():
        return None
 
    lines = message.strip().splitlines()
    header = lines[0].strip()
 
    # Strip an optional Option C plan/area bracket prefix before matching
    # the Conventional Commits header (Plan 151 T6, routed fix ii).
    m = _HEADER_RE.match(_strip_plan_prefix(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.
    """
    func = "validate_commit_message"
    _dbg("GIT", func, "validating the commit message", 3)
    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). The
    # optional Option C plan/area bracket prefix is metadata and does not
    # count against the Conventional Commits header budget (Plan 151 T6).
    header = _strip_plan_prefix(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 validate_ai_model_trailer(message: str) -> list[str]:
    """Validate presence of the Option C ``AI-Model:`` commit trailer.
 
    Returns a list of human-readable error strings; an empty list means an
    ``AI-Model: <name> <version>`` trailer is present and well-formed. This
    is the Option C commit-forensics convention (Plan 151 T6, inventory
    item 4): every commit body must name the LLM that did the reasoning.
 
    Presence validation only - the trailer value must contain at least a
    model name and a version (two or more whitespace-separated tokens).
    Never raises; always returns a list.
    """
    errors: list[str] = []
 
    if not message or not message.strip():
        errors.append("Commit message is empty (no AI-Model trailer).")
        return errors
 
    m = _AI_MODEL_TRAILER_RE.search(message)
    if m is None:
        errors.append(
            # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
            "Missing required 'AI-Model: <name> <version>' trailer "
            "(Option C commit-forensics convention)."
        )
        return errors
 
    value = m.group("value").strip()
    if len(value.split()) < 2:
        errors.append(
            # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
            "'AI-Model:' trailer must name both a model and a version "
            "(e.g. 'AI-Model: Claude Opus 4.8')."
        )
 
    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(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    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.
    """
    func = "analyse_diagnostics_impact"
    _dbg("GIT", func, "analysing the diff for diagnostics impact", 4)
    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