changelog.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/git/changelog.py
 
"""
Purpose
-------
Generate a Keep a Changelog formatted changelog from Conventional Commits
history (Phase 4E — G-E1).
 
Responsibilities
----------------
- Parse git log output into structured changelog entries.
- Map Conventional Commits types to Keep a Changelog sections.
- Render changelog in Markdown and JSON formats.
 
Diagnostics
-----------
Domain: GIT
Levels:
    L2 — changelog generation lifecycle
    L3 — entry collection details
    L4 — per-commit parsing trace
 
Contracts
---------
- ``collect_changelog_entries`` returns an empty list on fresh repos.
- ``format_changelog`` always returns valid Markdown.
- Non-conventional commits are silently skipped (never raises).
"""
 
from __future__ import annotations
 
from dataclasses import dataclass
from datetime import date
from pathlib import Path
 
from oct.core.diagnostics import _dbg
from oct.git.conventional import parse_commit_message
 
 
# =====================================================================
# Constants
# =====================================================================
 
#: Map Conventional Commits types to Keep a Changelog sections.
#: Types not listed here (style, test, chore) are omitted.
_TYPE_TO_SECTION: dict[str, str] = {
    "feat": "Added",
    "fix": "Fixed",
    "docs": "Documentation",
    "refactor": "Changed",
    "perf": "Changed",
    "sec": "Security",
}
 
#: Section display order (Keep a Changelog convention).
_SECTION_ORDER: list[str] = [
    "Added",
    "Changed",
    "Fixed",
    "Security",
    "Documentation",
]
 
 
# =====================================================================
# Data structures
# =====================================================================
 
 
@dataclass
class ChangelogEntry:
    """One parsed commit mapped to a changelog section."""
 
    section: str
    scope: str | None
    subject: str
    breaking: bool
    sha: str
 
 
# =====================================================================
# Entry collection
# =====================================================================
 
 
def collect_changelog_entries(
    repo_root: Path,
    since_ref: str | None = None,
) -> list[ChangelogEntry]:
    """Read git log, parse each conventional commit, return entries.
 
    Non-conventional commits are silently skipped. If *since_ref* is
    ``None``, the latest tag is used; if no tags exist, the entire
    history is scanned.
    """
    func = "collect_changelog_entries"
    _dbg("GIT", func, f"repo_root={repo_root} since_ref={since_ref!r}", 2)
 
    from oct.core.git import list_tags, get_commit_log
 
    # Determine starting point.
    effective_ref = since_ref
    if effective_ref is None:
        tags = list_tags(repo_root)
        if tags:
            effective_ref = tags[0]
            _dbg("GIT", func, f"using latest tag: {effective_ref}", 3)
 
    # Fetch log lines: "SHA<SEP>subject+body"
    # Use a separator unlikely to appear in commit messages.
    sep = "|||"
    raw_lines = get_commit_log(
        repo_root,
        since_ref=effective_ref,
        format_str=f"%h{sep}%B%x00",
    )
 
    # get_commit_log returns lines; with %B%x00 the output may span
    # multiple lines per commit. Rejoin and split on the null byte.
    raw_text = "\n".join(raw_lines)
    raw_commits = [c.strip() for c in raw_text.split("\x00") if c.strip()]
 
    entries: list[ChangelogEntry] = []
    for raw in raw_commits:
        # Split on separator to extract short SHA and message.
        if sep not in raw:
            continue
        sha_part, message = raw.split(sep, 1)
        sha = sha_part.strip()
        message = message.strip()
 
        parsed = parse_commit_message(message)
        if parsed is None:
            _dbg("GIT", func, f"skipping non-conventional: {sha}", 4)
            continue
 
        section = _TYPE_TO_SECTION.get(parsed.type)
        if section is None:
            _dbg("GIT", func, f"skipping unmapped type: {parsed.type}", 4)
            continue
 
        entries.append(ChangelogEntry(
            section=section,
            scope=parsed.scope,
            subject=parsed.subject,
            breaking=parsed.breaking,
            sha=sha,
        ))
 
    _dbg("GIT", func, f"collected {len(entries)} entries", 2)
    return entries
 
 
# =====================================================================
# Formatting
# =====================================================================
 
 
def format_changelog(
    entries: list[ChangelogEntry],
    version: str | None = None,
) -> str:
    """Render entries in Keep a Changelog format.
 
    Groups entries by section in the canonical order. If *version* is
    provided, the header uses ``## [version] - YYYY-MM-DD``; otherwise
    ``## [Unreleased]``.
    """
    lines: list[str] = []
 
    # Header.
    if version:
        lines.append(f"## [{version}] - {date.today().isoformat()}")
    else:
        lines.append("## [Unreleased]")
    lines.append("")
 
    # Group entries by section.
    grouped: dict[str, list[ChangelogEntry]] = {}
    for entry in entries:
        grouped.setdefault(entry.section, []).append(entry)
 
    if not grouped:
        lines.append("No notable changes.")
        lines.append("")
        return "\n".join(lines)
 
    for section in _SECTION_ORDER:
        section_entries = grouped.get(section)
        if not section_entries:
            continue
        lines.append(f"### {section}")
        lines.append("")
        for entry in section_entries:
            prefix = "**BREAKING:** " if entry.breaking else ""
            scope = f"**{entry.scope}:** " if entry.scope else ""
            lines.append(f"- {prefix}{scope}{entry.subject} ({entry.sha})")
        lines.append("")
 
    return "\n".join(lines)
 
 
def changelog_to_json(
    entries: list[ChangelogEntry],
    version: str | None = None,
) -> dict:
    """Return structured dict for ``--json`` output."""
    grouped: dict[str, list[dict]] = {}
    for entry in entries:
        grouped.setdefault(entry.section, []).append({
            "scope": entry.scope,
            "subject": entry.subject,
            "breaking": entry.breaking,
            "sha": entry.sha,
        })
 
    return {
        "version": version or "Unreleased",
        "date": date.today().isoformat(),
        "sections": {
            section: grouped.get(section, [])
            for section in _SECTION_ORDER
            if grouped.get(section)
        },
        "total_entries": len(entries),
    }