Changelog Generator

#!/usr/bin/env python3
"""Scan commit messages and diff summaries for breaking change indicators.

Analyzes git log output and optional diff stat summaries to detect breaking
changes through multiple heuristic signals: the conventional commit ! suffix,
BREAKING CHANGE footers, removal of public APIs, renamed/deleted files, and
keyword patterns in commit messages and diffs.

Usage:
    git log v1.0.0..HEAD --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' --no-merges | python breaking_change_detector.py
    python breaking_change_detector.py --file git-log.txt
    python breaking_change_detector.py --file git-log.txt --diff-file diff-stat.txt
    python breaking_change_detector.py --file git-log.txt --json
    python breaking_change_detector.py --file git-log.txt --severity high
"""

import argparse
import json
import re
import sys
from collections import OrderedDict

COMMIT_DELIMITER = "---COMMIT_END---"

COMMIT_PATTERN = re.compile(
    r"^(?P<type>feat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)"
    r"(?:\((?P<scope>[^)]+)\))?"
    r"(?P<breaking>!)?"
    r":\s*(?P<description>.+)$"
)

BREAKING_FOOTER_PATTERN = re.compile(
    r"BREAKING CHANGE:\s*(.+)", re.DOTALL
)

# Keyword patterns that suggest breaking changes in commit messages
BREAKING_KEYWORDS = [
    (r"\bremov(?:e|ed|ing|es)\b.*\b(?:api|endpoint|field|column|method|function|class|param|argument|route)\b", "high"),
    (r"\brenam(?:e|ed|ing|es)\b.*\b(?:api|endpoint|field|column|method|function|class|param|argument|route)\b", "high"),
    (r"\bdelet(?:e|ed|ing|es)\b.*\b(?:api|endpoint|field|column|table|method|function|class|route)\b", "high"),
    (r"\bdeprecate[ds]?\b", "medium"),
    (r"\bdrop(?:ped|ping|s)?\b.*\bsupport\b", "high"),
    (r"\bmigrat(?:e|ion|ing)\b", "medium"),
    (r"\bincompatible\b", "high"),
    (r"\bbreaking\b", "high"),
    (r"\bnon[- ]?backward[s]?\b", "high"),
    (r"\bbackward[s]?[- ]incompatible\b", "high"),
    (r"\brequire[ds]?\b.*\bmigration\b", "high"),
    (r"\bchanged?\b.*\b(?:signature|return type|schema|contract|interface)\b", "medium"),
    (r"\breplac(?:e|ed|ing)\b.*\b(?:api|endpoint|method|function)\b", "medium"),
    (r"\bmajor\b.*\b(?:version|upgrade|update)\b", "medium"),
    (r"\bv\d+\b.*\b(?:removed|dropped|deleted)\b", "high"),
]

# Patterns in diff stats suggesting breaking changes
DIFF_BREAKING_PATTERNS = [
    (r"(?:^|\s)(?:delete mode|rename)\s.*(?:api|schema|model|migration|interface|proto)", "high"),
    (r"\b\d+\s+files?\s+changed.*\d+\s+deletions", "low"),
    (r"(?:\.proto|schema\.\w+|openapi\.\w+|swagger\.\w+)\s.*\|.*[-]+", "medium"),
    (r"(?:routes|endpoints|api)\.\w+\s.*\|.*[-]+", "medium"),
    (r"migration.*\|", "low"),
]

SEVERITY_LEVELS = {"high": 3, "medium": 2, "low": 1}


def parse_raw_log(text):
    """Split raw git log text into individual commit blocks."""
    blocks = text.split(COMMIT_DELIMITER)
    commits = []
    for block in blocks:
        block = block.strip()
        if not block:
            continue
        lines = block.split("\n")
        if len(lines) < 2:
            continue
        commit_hash = lines[0].strip()
        subject = lines[1].strip()
        body = "\n".join(lines[2:]).strip() if len(lines) > 2 else ""
        if commit_hash and subject:
            commits.append({
                "hash": commit_hash,
                "short_hash": commit_hash[:7],
                "subject": subject,
                "body": body,
            })
    return commits


def detect_conventional_breaking(commit):
    """Detect breaking changes from conventional commit markers."""
    indicators = []
    subject = commit["subject"]
    body = commit["body"]

    match = COMMIT_PATTERN.match(subject)
    if match and match.group("breaking"):
        indicators.append({
            "source": "conventional_commit_bang",
            "severity": "high",
            "detail": f"Commit type has '!' breaking change marker: {subject}",
            "evidence": subject,
        })

    if body:
        footer_match = BREAKING_FOOTER_PATTERN.search(body)
        if footer_match:
            description = footer_match.group(1).strip()
            # Truncate long descriptions for display
            if len(description) > 200:
                description = description[:200] + "..."
            indicators.append({
                "source": "breaking_change_footer",
                "severity": "high",
                "detail": f"BREAKING CHANGE footer found",
                "evidence": description,
            })

    return indicators


def detect_keyword_breaking(commit):
    """Detect potential breaking changes from keyword patterns."""
    indicators = []
    full_text = f"{commit['subject']} {commit['body']}".lower()

    for pattern, severity in BREAKING_KEYWORDS:
        if re.search(pattern, full_text, re.IGNORECASE):
            # Find the matching line for evidence
            evidence_line = None
            for line in f"{commit['subject']}\n{commit['body']}".split("\n"):
                if re.search(pattern, line, re.IGNORECASE):
                    evidence_line = line.strip()
                    break

            indicators.append({
                "source": "keyword_heuristic",
                "severity": severity,
                "detail": f"Keyword pattern matched: {pattern}",
                "evidence": evidence_line or full_text[:100],
            })
            # Only report the first keyword match per pattern category
            break

    return indicators


def detect_diff_breaking(diff_text):
    """Detect breaking changes from diff stat output."""
    indicators = []
    if not diff_text:
        return indicators

    for line in diff_text.split("\n"):
        line = line.strip()
        if not line:
            continue
        for pattern, severity in DIFF_BREAKING_PATTERNS:
            if re.search(pattern, line, re.IGNORECASE):
                indicators.append({
                    "source": "diff_heuristic",
                    "severity": severity,
                    "detail": f"Diff pattern matched: {pattern}",
                    "evidence": line[:150],
                })
                break

    return indicators


def analyze_commit(commit, diff_text=None):
    """Run all detection methods on a single commit."""
    indicators = []
    indicators.extend(detect_conventional_breaking(commit))
    indicators.extend(detect_keyword_breaking(commit))
    if diff_text:
        indicators.extend(detect_diff_breaking(diff_text))

    if not indicators:
        return None

    # Determine overall severity (highest found)
    max_severity = max(
        (SEVERITY_LEVELS.get(i["severity"], 0) for i in indicators),
        default=0,
    )
    severity_name = {v: k for k, v in SEVERITY_LEVELS.items()}.get(max_severity, "low")

    return {
        "hash": commit["hash"],
        "short_hash": commit["short_hash"],
        "subject": commit["subject"],
        "severity": severity_name,
        "indicator_count": len(indicators),
        "indicators": indicators,
        "confirmed": any(
            i["source"] in ("conventional_commit_bang", "breaking_change_footer")
            for i in indicators
        ),
    }


def filter_by_severity(results, min_severity):
    """Filter results to only include entries at or above the minimum severity."""
    min_level = SEVERITY_LEVELS.get(min_severity, 0)
    return [r for r in results if SEVERITY_LEVELS.get(r["severity"], 0) >= min_level]


def format_human_readable(results, stats):
    """Render detection results as human-readable text."""
    lines = []
    lines.append("=" * 65)
    lines.append("BREAKING CHANGE DETECTION REPORT")
    lines.append("=" * 65)
    lines.append("")
    lines.append(f"Commits scanned:        {stats['total_scanned']}")
    lines.append(f"Breaking changes found:  {stats['breaking_found']}")
    lines.append(f"  Confirmed (explicit):  {stats['confirmed']}")
    lines.append(f"  Suspected (heuristic): {stats['suspected']}")
    lines.append(f"Severity breakdown:")
    lines.append(f"  High:   {stats['severity_high']}")
    lines.append(f"  Medium: {stats['severity_medium']}")
    lines.append(f"  Low:    {stats['severity_low']}")
    lines.append(f"Recommended bump:        {stats['recommended_bump']}")
    lines.append("")

    if not results:
        lines.append("No breaking changes detected.")
        return "\n".join(lines)

    for result in results:
        confirmed_tag = "CONFIRMED" if result["confirmed"] else "SUSPECTED"
        severity_tag = result["severity"].upper()
        lines.append("-" * 65)
        lines.append(f"[{severity_tag}] [{confirmed_tag}] {result['short_hash']}  {result['subject']}")
        lines.append("")

        for indicator in result["indicators"]:
            source_label = indicator["source"].replace("_", " ").title()
            lines.append(f"  Source:   {source_label}")
            lines.append(f"  Severity: {indicator['severity']}")
            if indicator.get("evidence"):
                evidence = indicator["evidence"]
                if len(evidence) > 120:
                    evidence = evidence[:120] + "..."
                lines.append(f"  Evidence: {evidence}")
            lines.append("")

    # Migration guidance reminder
    lines.append("=" * 65)
    lines.append("RECOMMENDED ACTIONS")
    lines.append("=" * 65)
    lines.append("")

    confirmed_results = [r for r in results if r["confirmed"]]
    suspected_results = [r for r in results if not r["confirmed"]]

    if confirmed_results:
        lines.append("Confirmed breaking changes require:")
        lines.append("  1. Major version bump (semver)")
        lines.append("  2. Migration guide in release notes")
        lines.append("  3. Deprecation notice for removed features")
        lines.append("")

    if suspected_results:
        lines.append("Suspected breaking changes should be reviewed:")
        lines.append("  1. Verify if the change affects the public API")
        lines.append("  2. If confirmed, add BREAKING CHANGE footer to commit")
        lines.append("  3. Document migration path for affected users")
        lines.append("")

    return "\n".join(lines)


def read_input(args):
    """Read git log text from file or stdin."""
    if args.file:
        with open(args.file, "r", encoding="utf-8") as f:
            return f.read()
    if not sys.stdin.isatty():
        return sys.stdin.read()
    print("Error: No input provided. Pipe git log output or use --file.", file=sys.stderr)
    print("Example: git log v1.0.0..HEAD --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' "
          "--no-merges | python breaking_change_detector.py", file=sys.stderr)
    sys.exit(1)


def main():
    parser = argparse.ArgumentParser(
        description="Scan commit messages and diffs for breaking change indicators.",
        epilog="Reads git log output formatted with ---COMMIT_END--- delimiters. "
               "Detects breaking changes via conventional commit markers, keyword "
               "heuristics, and optional diff analysis.",
    )
    parser.add_argument(
        "--file", "-f",
        help="Path to file containing git log output (default: read from stdin)",
    )
    parser.add_argument(
        "--diff-file",
        help="Path to file containing diff stat output for additional analysis",
    )
    parser.add_argument(
        "--json", "-j",
        action="store_true",
        dest="json_output",
        help="Output as JSON instead of human-readable text",
    )
    parser.add_argument(
        "--severity", "-s",
        choices=["low", "medium", "high"],
        default="low",
        help="Minimum severity level to report (default: low)",
    )
    parser.add_argument(
        "--confirmed-only", "-c",
        action="store_true",
        help="Only show confirmed breaking changes (conventional commit markers)",
    )
    parser.add_argument(
        "--indent",
        type=int,
        default=2,
        help="JSON indentation level (default: 2)",
    )

    args = parser.parse_args()

    raw_text = read_input(args)
    commits = parse_raw_log(raw_text)

    diff_text = None
    if args.diff_file:
        with open(args.diff_file, "r", encoding="utf-8") as f:
            diff_text = f.read()

    # Analyze each commit
    results = []
    for commit in commits:
        result = analyze_commit(commit, diff_text=diff_text)
        if result:
            results.append(result)

    # Apply filters
    results = filter_by_severity(results, args.severity)
    if args.confirmed_only:
        results = [r for r in results if r["confirmed"]]

    # Compute stats
    confirmed_count = sum(1 for r in results if r["confirmed"])
    stats = {
        "total_scanned": len(commits),
        "breaking_found": len(results),
        "confirmed": confirmed_count,
        "suspected": len(results) - confirmed_count,
        "severity_high": sum(1 for r in results if r["severity"] == "high"),
        "severity_medium": sum(1 for r in results if r["severity"] == "medium"),
        "severity_low": sum(1 for r in results if r["severity"] == "low"),
        "recommended_bump": "major" if results else "see commit types",
    }

    if args.json_output:
        output = {
            "stats": stats,
            "results": results,
        }
        print(json.dumps(output, indent=args.indent, default=str))
    else:
        print(format_human_readable(results, stats))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Format parsed commits into Keep a Changelog markdown.

Accepts JSON from commit_parser.py (via stdin or --file) and renders a
complete changelog entry in Keep a Changelog format. Supports version
headers, comparison links, breaking change sections, and the Unreleased
section pattern.

Usage:
    python commit_parser.py --json | python changelog_formatter.py --version 1.4.0
    python changelog_formatter.py --file parsed.json --version 2.0.0 --repo-url https://github.com/org/repo
    python changelog_formatter.py --file parsed.json --version 2.0.0 --json
    python changelog_formatter.py --file parsed.json --unreleased
"""

import argparse
import json
import sys
from collections import OrderedDict
from datetime import date

SECTION_ORDER = [
    "BREAKING CHANGES",
    "Added",
    "Changed",
    "Deprecated",
    "Removed",
    "Fixed",
    "Performance",
    "Security",
]

TYPE_TO_SECTION = OrderedDict([
    ("feat", "Added"),
    ("fix", "Fixed"),
    ("perf", "Performance"),
    ("security", "Security"),
    ("deprecated", "Deprecated"),
    ("remove", "Removed"),
    ("refactor", "Changed"),
])

CHANGELOG_HEADER = """# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
"""


def read_input(args):
    """Read parsed commit JSON from file or stdin."""
    if args.file:
        with open(args.file, "r", encoding="utf-8") as f:
            return json.load(f)
    if not sys.stdin.isatty():
        return json.load(sys.stdin)
    print("Error: No input provided. Pipe commit_parser.py --json output or use --file.",
          file=sys.stderr)
    sys.exit(1)


def extract_commits(data):
    """Extract the flat list of commits from parser output."""
    if "commits" in data:
        return data["commits"]
    if "groups" in data:
        commits = []
        for group in data["groups"].values():
            if isinstance(group, dict) and "commits" in group:
                commits.extend(group["commits"])
        return commits
    if isinstance(data, list):
        return data
    return []


def build_sections(commits, repo_url=None, link_style="commit"):
    """Group commits into changelog sections."""
    sections = OrderedDict()

    # Collect breaking changes into their own section first
    breaking_commits = [c for c in commits if c.get("breaking")]
    if breaking_commits:
        entries = []
        for c in breaking_commits:
            desc = c.get("breaking_description") or c["description"]
            scope_prefix = f"**{c['scope']}**: " if c.get("scope") else ""
            entries.append(f"- {scope_prefix}{desc}")
        sections["BREAKING CHANGES"] = entries

    # Group remaining commits by section
    for commit in commits:
        section_name = TYPE_TO_SECTION.get(commit.get("type"))
        if not section_name:
            continue

        if section_name not in sections:
            sections[section_name] = []

        scope_prefix = f"**{commit['scope']}**: " if commit.get("scope") else ""
        description = commit["description"]

        # Build link suffix
        link = ""
        if repo_url and commit.get("hash"):
            short = commit.get("short_hash", commit["hash"][:7])
            if link_style == "commit":
                link = f" ([{short}]({repo_url}/commit/{commit['hash']}))"
            elif link_style == "none":
                link = ""

        sections[section_name].append(f"- {scope_prefix}{description}{link}")

    return sections


def render_keep_a_changelog(version, release_date, sections, repo_url=None,
                            previous_version=None, include_header=False):
    """Render sections in Keep a Changelog markdown format."""
    lines = []

    if include_header:
        lines.append(CHANGELOG_HEADER.strip())
        lines.append("")

    # Version heading
    if version.lower() == "unreleased":
        if repo_url and previous_version:
            lines.append(f"## [Unreleased]")
        else:
            lines.append("## [Unreleased]")
    else:
        lines.append(f"## [{version}] - {release_date}")

    lines.append("")

    # Render sections in defined order
    rendered_any = False
    for section_name in SECTION_ORDER:
        if section_name in sections:
            lines.append(f"### {section_name}")
            lines.append("")
            for entry in sections[section_name]:
                lines.append(entry)
            lines.append("")
            rendered_any = True

    # Handle any custom sections not in the standard order
    for section_name, entries in sections.items():
        if section_name not in SECTION_ORDER:
            lines.append(f"### {section_name}")
            lines.append("")
            for entry in entries:
                lines.append(entry)
            lines.append("")
            rendered_any = True

    if not rendered_any:
        lines.append("No notable changes in this release.")
        lines.append("")

    # Comparison link footer
    if repo_url and version.lower() != "unreleased" and previous_version:
        lines.append(
            f"[{version}]: {repo_url}/compare/v{previous_version}...v{version}"
        )
        lines.append("")

    return "\n".join(lines)


def render_github_release(version, sections, repo_url=None, previous_version=None):
    """Render sections in GitHub Release Notes format."""
    github_section_names = {
        "BREAKING CHANGES": "Breaking Changes",
        "Added": "What's New",
        "Changed": "Changes",
        "Deprecated": "Deprecations",
        "Removed": "Removals",
        "Fixed": "Bug Fixes",
        "Performance": "Performance",
        "Security": "Security",
    }

    lines = []
    for section_name in SECTION_ORDER:
        if section_name in sections:
            heading = github_section_names.get(section_name, section_name)
            lines.append(f"## {heading}")
            lines.append("")
            for entry in sections[section_name]:
                lines.append(entry)
            lines.append("")

    if repo_url and previous_version:
        lines.append(
            f"**Full Changelog**: {repo_url}/compare/v{previous_version}...v{version}"
        )
        lines.append("")

    return "\n".join(lines)


def build_json_output(version, release_date, sections, stats=None):
    """Build structured JSON output for automation pipelines."""
    return {
        "version": version,
        "date": release_date,
        "sections": dict(sections),
        "section_count": len(sections),
        "entry_count": sum(len(v) for v in sections.values()),
        "has_breaking_changes": "BREAKING CHANGES" in sections,
        "stats": stats,
    }


def determine_bump(commits):
    """Determine the semver bump level from commits."""
    if any(c.get("breaking") for c in commits):
        return "major"
    if any(c.get("type") == "feat" for c in commits):
        return "minor"
    if any(c.get("type") in ("fix", "perf", "security", "refactor") for c in commits):
        return "patch"
    return "none"


def bump_version(current, bump_level):
    """Apply a semver bump to a version string."""
    clean = current.lstrip("v")
    parts = clean.split(".")
    if len(parts) != 3:
        return current
    try:
        major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2])
    except ValueError:
        return current

    if bump_level == "major":
        return f"{major + 1}.0.0"
    elif bump_level == "minor":
        return f"{major}.{minor + 1}.0"
    elif bump_level == "patch":
        return f"{major}.{minor}.{patch + 1}"
    return current


def main():
    parser = argparse.ArgumentParser(
        description="Format parsed conventional commits into Keep a Changelog markdown.",
        epilog="Reads JSON output from commit_parser.py via stdin or --file.",
    )
    parser.add_argument(
        "--file", "-f",
        help="Path to JSON file from commit_parser.py (default: read from stdin)",
    )
    parser.add_argument(
        "--version", "-v",
        help="Version number for the release header (e.g. 1.4.0)",
    )
    parser.add_argument(
        "--date", "-d",
        default=None,
        help="Release date in YYYY-MM-DD format (default: today)",
    )
    parser.add_argument(
        "--previous-version", "-p",
        help="Previous version for comparison link (e.g. 1.3.2)",
    )
    parser.add_argument(
        "--repo-url", "-r",
        help="Repository URL for commit/comparison links (e.g. https://github.com/org/repo)",
    )
    parser.add_argument(
        "--format",
        choices=["keepachangelog", "github"],
        default="keepachangelog",
        help="Output format (default: keepachangelog)",
    )
    parser.add_argument(
        "--unreleased",
        action="store_true",
        help="Use [Unreleased] as the version header",
    )
    parser.add_argument(
        "--include-header",
        action="store_true",
        help="Include the full Keep a Changelog file header",
    )
    parser.add_argument(
        "--link-style",
        choices=["commit", "none"],
        default="commit",
        help="Style for commit links in entries (default: commit)",
    )
    parser.add_argument(
        "--auto-version",
        help="Auto-determine next version from BASE version (e.g. 1.3.2 -> computed bump)",
    )
    parser.add_argument(
        "--json", "-j",
        action="store_true",
        dest="json_output",
        help="Output as JSON instead of markdown",
    )
    parser.add_argument(
        "--indent",
        type=int,
        default=2,
        help="JSON indentation level (default: 2)",
    )

    args = parser.parse_args()

    data = read_input(args)
    commits = extract_commits(data)

    if not commits:
        print("Warning: No commits found in input.", file=sys.stderr)

    # Determine version
    release_date = args.date or date.today().isoformat()

    if args.unreleased:
        version = "Unreleased"
    elif args.auto_version:
        bump_level = determine_bump(commits)
        version = bump_version(args.auto_version, bump_level)
        if not args.previous_version:
            args.previous_version = args.auto_version.lstrip("v")
    elif args.version:
        version = args.version
    else:
        version = "Unreleased"

    repo_url = args.repo_url.rstrip("/") if args.repo_url else None

    # Build sections
    sections = build_sections(commits, repo_url=repo_url, link_style=args.link_style)

    stats = data.get("stats") if isinstance(data, dict) else None

    if args.json_output:
        output = build_json_output(version, release_date, sections, stats)
        if args.auto_version:
            output["bump_level"] = determine_bump(commits)
            output["previous_version"] = args.auto_version
        print(json.dumps(output, indent=args.indent, default=str))
    elif args.format == "github":
        print(render_github_release(
            version, sections,
            repo_url=repo_url,
            previous_version=args.previous_version,
        ))
    else:
        print(render_keep_a_changelog(
            version, release_date, sections,
            repo_url=repo_url,
            previous_version=args.previous_version,
            include_header=args.include_header,
        ))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Parse git log output (conventional commits) into structured changelog entries.

Reads git log output from stdin or a file and extracts structured data from
Conventional Commit messages. Groups commits by type (feat, fix, docs, etc.)
and detects breaking changes from both the ! suffix and BREAKING CHANGE footer.

Usage:
    git log v1.0.0..HEAD --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' --no-merges | python commit_parser.py
    python commit_parser.py --file git-log-output.txt
    python commit_parser.py --file git-log-output.txt --json
    python commit_parser.py --file git-log-output.txt --scope api
    python commit_parser.py --file git-log-output.txt --types feat,fix
"""

import argparse
import json
import re
import sys
from collections import OrderedDict

COMMIT_DELIMITER = "---COMMIT_END---"

COMMIT_PATTERN = re.compile(
    r"^(?P<type>feat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)"
    r"(?:\((?P<scope>[^)]+)\))?"
    r"(?P<breaking>!)?"
    r":\s*(?P<description>.+)$"
)

BREAKING_CHANGE_PATTERN = re.compile(
    r"BREAKING CHANGE:\s*(.+)", re.DOTALL
)

TYPE_LABELS = OrderedDict([
    ("feat", "Features"),
    ("fix", "Bug Fixes"),
    ("perf", "Performance Improvements"),
    ("security", "Security"),
    ("deprecated", "Deprecations"),
    ("remove", "Removals"),
    ("refactor", "Refactoring"),
    ("docs", "Documentation"),
    ("test", "Tests"),
    ("build", "Build System"),
    ("ci", "Continuous Integration"),
    ("chore", "Chores"),
])

USER_FACING_TYPES = {"feat", "fix", "perf", "security", "deprecated", "remove", "refactor"}


def parse_raw_log(text):
    """Split raw git log text into individual commit blocks."""
    blocks = text.split(COMMIT_DELIMITER)
    commits_raw = []
    for block in blocks:
        block = block.strip()
        if not block:
            continue
        lines = block.split("\n")
        if len(lines) < 2:
            continue
        commit_hash = lines[0].strip()
        subject = lines[1].strip()
        body = "\n".join(lines[2:]).strip() if len(lines) > 2 else ""
        if commit_hash and subject:
            commits_raw.append({
                "hash": commit_hash,
                "subject": subject,
                "body": body,
            })
    return commits_raw


def parse_commit(raw):
    """Parse a single raw commit dict into a structured commit entry.

    Returns None if the subject does not match conventional commit format.
    """
    subject = raw["subject"]
    body = raw["body"]
    commit_hash = raw["hash"]

    match = COMMIT_PATTERN.match(subject)
    if not match:
        return None

    commit_type = match.group("type")
    scope = match.group("scope")
    is_breaking = bool(match.group("breaking"))
    description = match.group("description").strip()

    breaking_description = None
    if body:
        bc_match = BREAKING_CHANGE_PATTERN.search(body)
        if bc_match:
            is_breaking = True
            breaking_description = bc_match.group(1).strip()

    # Extract co-authors from trailers
    co_authors = []
    if body:
        for line in body.split("\n"):
            line = line.strip()
            if line.lower().startswith("co-authored-by:"):
                co_authors.append(line.split(":", 1)[1].strip())

    return {
        "hash": commit_hash,
        "short_hash": commit_hash[:7],
        "type": commit_type,
        "scope": scope,
        "description": description,
        "body": body if body else None,
        "breaking": is_breaking,
        "breaking_description": breaking_description,
        "co_authors": co_authors if co_authors else None,
    }


def group_by_type(commits):
    """Group parsed commits by their type, maintaining defined order."""
    groups = OrderedDict()
    for type_key in TYPE_LABELS:
        matching = [c for c in commits if c["type"] == type_key]
        if matching:
            groups[type_key] = {
                "label": TYPE_LABELS[type_key],
                "count": len(matching),
                "commits": matching,
            }
    return groups


def filter_commits(commits, scope_filter=None, type_filter=None, user_facing_only=False):
    """Apply optional filters to the parsed commit list."""
    result = commits

    if scope_filter:
        scopes = {s.strip().lower() for s in scope_filter.split(",")}
        result = [c for c in result if c["scope"] and c["scope"].lower() in scopes]

    if type_filter:
        types = {t.strip().lower() for t in type_filter.split(",")}
        result = [c for c in result if c["type"] in types]

    if user_facing_only:
        result = [c for c in result if c["type"] in USER_FACING_TYPES]

    return result


def format_human_readable(grouped, stats):
    """Render grouped commits as human-readable text output."""
    lines = []
    lines.append("=" * 60)
    lines.append("PARSED COMMITS")
    lines.append("=" * 60)
    lines.append("")
    lines.append(f"Total parsed:      {stats['parsed']}")
    lines.append(f"Skipped (invalid): {stats['skipped']}")
    lines.append(f"Breaking changes:  {stats['breaking']}")
    lines.append(f"User-facing:       {stats['user_facing']}")
    lines.append("")

    if not grouped:
        lines.append("No commits matched the given filters.")
        return "\n".join(lines)

    for type_key, group in grouped.items():
        lines.append("-" * 60)
        lines.append(f"{group['label']} ({group['count']})")
        lines.append("-" * 60)

        for commit in group["commits"]:
            scope_prefix = f"({commit['scope']}) " if commit["scope"] else ""
            breaking_marker = " [BREAKING]" if commit["breaking"] else ""
            lines.append(f"  {commit['short_hash']}  {scope_prefix}{commit['description']}{breaking_marker}")

            if commit["breaking_description"]:
                # Indent breaking change description
                for bd_line in commit["breaking_description"].split("\n"):
                    lines.append(f"             BREAKING: {bd_line}")

        lines.append("")

    return "\n".join(lines)


def build_output(grouped, stats, all_commits):
    """Build the JSON-serializable output structure."""
    return {
        "stats": stats,
        "groups": grouped,
        "commits": all_commits,
    }


def read_input(args):
    """Read git log text from file or stdin."""
    if args.file:
        with open(args.file, "r", encoding="utf-8") as f:
            return f.read()
    if not sys.stdin.isatty():
        return sys.stdin.read()
    print("Error: No input provided. Pipe git log output or use --file.", file=sys.stderr)
    print("Example: git log v1.0.0..HEAD --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' "
          "--no-merges | python commit_parser.py", file=sys.stderr)
    sys.exit(1)


def main():
    parser = argparse.ArgumentParser(
        description="Parse git log output with conventional commits into structured changelog entries.",
        epilog="Reads git log output formatted with ---COMMIT_END--- delimiters. "
               "Use: git log --pretty=format:'%%H%%n%%s%%n%%b%%n---COMMIT_END---' --no-merges",
    )
    parser.add_argument(
        "--file", "-f",
        help="Path to a file containing git log output (default: read from stdin)",
    )
    parser.add_argument(
        "--json", "-j",
        action="store_true",
        dest="json_output",
        help="Output as JSON instead of human-readable text",
    )
    parser.add_argument(
        "--scope", "-s",
        help="Filter commits by scope (comma-separated, e.g. 'api,ui')",
    )
    parser.add_argument(
        "--types", "-t",
        help="Filter commits by type (comma-separated, e.g. 'feat,fix')",
    )
    parser.add_argument(
        "--user-facing", "-u",
        action="store_true",
        help="Show only user-facing commit types (feat, fix, perf, security, deprecated, remove, refactor)",
    )
    parser.add_argument(
        "--indent",
        type=int,
        default=2,
        help="JSON indentation level (default: 2)",
    )

    args = parser.parse_args()

    raw_text = read_input(args)
    raw_commits = parse_raw_log(raw_text)

    parsed = []
    skipped = 0
    for raw in raw_commits:
        result = parse_commit(raw)
        if result:
            parsed.append(result)
        else:
            skipped += 1

    filtered = filter_commits(
        parsed,
        scope_filter=args.scope,
        type_filter=args.types,
        user_facing_only=args.user_facing,
    )

    grouped = group_by_type(filtered)

    stats = {
        "total_raw": len(raw_commits),
        "parsed": len(parsed),
        "skipped": skipped,
        "filtered": len(filtered),
        "breaking": sum(1 for c in filtered if c["breaking"]),
        "user_facing": sum(1 for c in filtered if c["type"] in USER_FACING_TYPES),
        "types_found": list(grouped.keys()),
        "scopes_found": sorted(set(
            c["scope"] for c in filtered if c["scope"]
        )),
    }

    if args.json_output:
        output = build_output(grouped, stats, filtered)
        print(json.dumps(output, indent=args.indent, default=str))
    else:
        print(format_human_readable(grouped, stats))


if __name__ == "__main__":
    main()