patchnote 0.1.1__py3-none-any.whl

patchnote/gitlog.py

@@ -0,0 +1,201 @@
+"""Read git history by calling the ``git`` binary (no GitPython)."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import subprocess
+from collections.abc import Sequence
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from patchnote.model import Commit, GitError, UsageError
+
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+
+# hash, short, author name, email, author date, parents, subject, body
+PRETTY = (
+    f"%H{FIELD_SEP}%h{FIELD_SEP}%an{FIELD_SEP}%ae{FIELD_SEP}"
+    f"%aI{FIELD_SEP}%P{FIELD_SEP}%s{FIELD_SEP}%b{RECORD_SEP}"
+)
+
+
+class GitRunner:
+    """Thin wrapper around ``git`` subprocess calls, injectable in tests."""
+
+    def __init__(self, repo: Path, env: dict[str, str] | None = None) -> None:
+        self.repo = repo
+        extra = env or {}
+        self.env = {**os.environ, "LC_ALL": "C", "GIT_TERMINAL_PROMPT": "0", **extra}
+
+    def run(self, args: Sequence[str], *, check: bool = True, timeout: int = 60) -> str:
+        try:
+            result = subprocess.run(
+                ["git", *args],
+                cwd=self.repo,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+                check=False,
+                env=self.env,
+            )
+        except FileNotFoundError as exc:
+            raise GitError("git executable not found on PATH") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise GitError(f"git {' '.join(args)} timed out after {timeout}s") from exc
+        if check and result.returncode != 0:
+            err = (result.stderr or result.stdout or "").strip()
+            raise GitError(f"git {' '.join(args)} failed: {err or result.returncode}")
+        return result.stdout
+
+    def run_ok(self, args: Sequence[str]) -> bool:
+        try:
+            result = subprocess.run(
+                ["git", *args],
+                cwd=self.repo,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=30,
+                check=False,
+                env=self.env,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+        return result.returncode == 0
+
+
+def discover_repo(path: Path) -> Path:
+    runner = GitRunner(path)
+    try:
+        root = runner.run(["rev-parse", "--show-toplevel"]).strip()
+    except GitError as exc:
+        raise GitError(f"{path} is not a git repository") from exc
+    return Path(root)
+
+
+def _parse_datetime(value: str) -> datetime:
+    text = value.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return datetime.now(timezone.utc)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def parse_log_output(raw: str) -> list[Commit]:
+    commits: list[Commit] = []
+    if not raw.strip():
+        return commits
+    records = raw.split(RECORD_SEP)
+    for record in records:
+        record = record.strip("\n")
+        if not record.strip():
+            continue
+        parts = record.split(FIELD_SEP)
+        if len(parts) < 8:
+            # Body may have been empty and split short; pad.
+            parts = parts + [""] * (8 - len(parts))
+        full, short, name, email, when, parents, subject = parts[:7]
+        body = FIELD_SEP.join(parts[7:]) if len(parts) > 8 else parts[7]
+        body = body.strip("\n")
+        parent_list = [p for p in parents.split() if p]
+        commits.append(
+            Commit(
+                hash=full.strip(),
+                short_hash=short.strip(),
+                author_name=name.strip(),
+                author_email=email.strip(),
+                author_date=_parse_datetime(when),
+                parents=parent_list,
+                subject=subject.strip("\n"),
+                body=body,
+            )
+        )
+    return commits
+
+
+def list_commits(runner: GitRunner, from_ref: str | None, to_ref: str) -> list[Commit]:
+    """Return commits in ``from_ref..to_ref`` (exclusive of from, inclusive of to).
+
+    When ``from_ref`` is None, the full history reachable from ``to_ref`` is used.
+    """
+    for ref in (from_ref, to_ref):
+        if ref and ref.startswith("-"):
+            raise UsageError("Git references must not start with a dash")
+    rev_range = f"{from_ref}..{to_ref}" if from_ref else to_ref
+    raw = runner.run(["log", f"--pretty=format:{PRETTY}", "--date=iso-strict", rev_range, "--"])
+    return parse_log_output(raw)
+
+
+def list_tags(runner: GitRunner, pattern: str = "v*") -> list[str]:
+    raw = runner.run(["tag", "--list", pattern, "--sort=-v:refname"], check=True)
+    tags = [line.strip() for line in raw.splitlines() if line.strip()]
+    if tags:
+        return tags
+    # Fall back to every tag, then filter with fnmatch (in case git glob differs).
+    raw_all = runner.run(["tag", "--list", "--sort=-v:refname"])
+    all_tags = [line.strip() for line in raw_all.splitlines() if line.strip()]
+    return [tag for tag in all_tags if fnmatch.fnmatch(tag, pattern)]
+
+
+def latest_tag(runner: GitRunner, pattern: str = "v*") -> str | None:
+    tags = list_tags(runner, pattern)
+    return tags[0] if tags else None
+
+
+def previous_tag(runner: GitRunner, current: str, pattern: str = "v*") -> str | None:
+    tags = list_tags(runner, pattern)
+    if current in tags:
+        idx = tags.index(current)
+        if idx + 1 < len(tags):
+            return tags[idx + 1]
+        return None
+    return tags[0] if tags else None
+
+
+def resolve_ref(runner: GitRunner, ref: str) -> str:
+    return runner.run(["rev-parse", ref]).strip()
+
+
+def ref_exists(runner: GitRunner, ref: str) -> bool:
+    if ref.startswith("-"):
+        return False
+    return runner.run_ok(
+        ["rev-parse", "--verify", "--quiet", "--end-of-options", f"{ref}^{{commit}}"]
+    )
+
+
+def tag_date(runner: GitRunner, tag: str) -> date | None:
+    raw = runner.run(["log", "-1", "--format=%aI", tag], check=False).strip()
+    if not raw:
+        return None
+    return _parse_datetime(raw).date()
+
+
+def remote_url(runner: GitRunner, name: str = "origin") -> str | None:
+    raw = runner.run(["remote", "get-url", name], check=False).strip()
+    return raw or None
+
+
+def current_branch(runner: GitRunner) -> str | None:
+    raw = runner.run(["rev-parse", "--abbrev-ref", "HEAD"], check=False).strip()
+    if not raw or raw == "HEAD":
+        return None
+    return raw
+
+
+def create_tag(runner: GitRunner, tag: str, message: str) -> None:
+    runner.run(["tag", "-a", tag, "-m", message])
+
+
+def push_tag(runner: GitRunner, tag: str, remote: str = "origin") -> None:
+    runner.run(["push", remote, tag])

patchnote/model.py

@@ -0,0 +1,228 @@
+"""Domain models and error types for Patchnote."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PatchnoteError(Exception):
+    """Base error. ``exit_code`` is used by the CLI."""
+
+    exit_code = 3
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class UsageError(PatchnoteError):
+    """Bad arguments or configuration the user can fix."""
+
+    exit_code = 2
+
+
+class ConfigError(UsageError):
+    """Invalid configuration file."""
+
+    exit_code = 2
+
+
+class CheckViolationError(PatchnoteError):
+    """``patchnote check`` found convention violations."""
+
+    exit_code = 1
+
+    def __init__(self, message: str, violations: list[str]) -> None:
+        super().__init__(message)
+        self.violations = violations
+
+
+class GitError(PatchnoteError):
+    """The git binary failed or the repository is unusable."""
+
+    exit_code = 3
+
+
+class RuntimeNetworkError(PatchnoteError):
+    """A required network call failed (release publish, etc.)."""
+
+    exit_code = 3
+
+
+class Confidence(str, Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class EntrySource(str, Enum):
+    CONVENTIONAL = "conventional"
+    LABEL = "label"
+    HEURISTIC = "heuristic"
+    OTHER = "other"
+    BOT = "bot"
+    REVERT = "revert"
+
+
+class Style(str, Enum):
+    KEEPACHANGELOG = "keepachangelog"
+    CONVENTIONAL = "conventional"
+
+
+class OutputFormat(str, Enum):
+    MARKDOWN = "markdown"
+    JSON = "json"
+    GITHUB_RELEASE = "github-release"
+
+
+class AiMode(str, Enum):
+    NONE = "none"
+    POLISH = "polish"
+    SUMMARY = "summary"
+    BOTH = "both"
+
+
+class Commit(BaseModel):
+    """A single git commit as returned by the git binary."""
+
+    hash: str
+    short_hash: str
+    author_name: str
+    author_email: str
+    author_date: datetime
+    parents: list[str] = Field(default_factory=list)
+    subject: str
+    body: str = ""
+
+    @property
+    def is_merge(self) -> bool:
+        return len(self.parents) > 1
+
+    @property
+    def message(self) -> str:
+        if self.body.strip():
+            return f"{self.subject}\n\n{self.body}"
+        return self.subject
+
+
+class Footer(BaseModel):
+    key: str
+    value: str
+
+
+class ParsedCommit(BaseModel):
+    """Conventional-commit parse result. ``type`` is None when unmatched."""
+
+    type: str | None = None
+    scope: str | None = None
+    breaking: bool = False
+    description: str
+    body: str = ""
+    footers: list[Footer] = Field(default_factory=list)
+    raw: Commit
+    reverted_hash: str | None = None
+    pr_numbers: list[int] = Field(default_factory=list)
+
+    @property
+    def is_conventional(self) -> bool:
+        return self.type is not None
+
+
+class PullRequest(BaseModel):
+    number: int
+    title: str
+    body: str | None = None
+    labels: list[str] = Field(default_factory=list)
+    author: str | None = None
+    url: str = ""
+    merged_at: datetime | None = None
+    merge_commit_sha: str | None = None
+    linked_issues: list[int] = Field(default_factory=list)
+
+
+class Contributor(BaseModel):
+    login: str | None = None
+    name: str
+    email: str | None = None
+    first_time: bool = False
+    pr_count: int = 0
+
+
+class ChangelogEntry(BaseModel):
+    """A single rendered changelog bullet."""
+
+    id: str
+    summary: str
+    original_summary: str
+    pr_body: str | None = Field(default=None, exclude=True)
+    section: str
+    scope: str | None = None
+    pr_number: int | None = None
+    pr_url: str | None = None
+    authors: list[str] = Field(default_factory=list)
+    hashes: list[str] = Field(default_factory=list)
+    short_hashes: list[str] = Field(default_factory=list)
+    breaking: bool = False
+    breaking_description: str | None = None
+    confidence: Confidence = Confidence.HIGH
+    source: EntrySource = EntrySource.CONVENTIONAL
+    labels: list[str] = Field(default_factory=list)
+    first_time_contributors: list[str] = Field(default_factory=list)
+    linked_issues: list[int] = Field(default_factory=list)
+
+    def to_ai_payload(self, *, include_bodies: bool = False) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "id": self.id,
+            "summary": self.summary,
+            "section": self.section,
+            "scope": self.scope,
+            "pr_number": self.pr_number,
+            "breaking": self.breaking,
+            "hashes": list(self.short_hashes),
+        }
+        if include_bodies:
+            payload["original_summary"] = self.original_summary
+            if self.pr_body:
+                payload["pr_body"] = self.pr_body
+        return payload
+
+
+class Changelog(BaseModel):
+    version: str | None = None
+    from_ref: str
+    to_ref: str
+    date: date
+    sections: dict[str, list[ChangelogEntry]] = Field(default_factory=dict)
+    breaking: list[ChangelogEntry] = Field(default_factory=list)
+    contributors: list[Contributor] = Field(default_factory=list)
+    compare_url: str | None = None
+    previous_tag: str | None = None
+    repository_url: str | None = None
+    overview: str | None = None
+    style: Style = Style.KEEPACHANGELOG
+    tag_name: str | None = None
+
+    @property
+    def all_entries(self) -> list[ChangelogEntry]:
+        items: list[ChangelogEntry] = list(self.breaking)
+        seen = {e.id for e in items}
+        for entries in self.sections.values():
+            for entry in entries:
+                if entry.id not in seen:
+                    items.append(entry)
+                    seen.add(entry.id)
+        return items
+
+    @property
+    def entry_count(self) -> int:
+        return len(self.all_entries)
+
+    def to_ai_payload(self, *, include_bodies: bool = False) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "entries": [e.to_ai_payload(include_bodies=include_bodies) for e in self.all_entries],
+        }

patchnote/render/__init__.py

@@ -0,0 +1,17 @@
+"""Render changelogs to markdown, JSON, or GitHub-release body."""
+
+from __future__ import annotations
+
+from patchnote.config import Config
+from patchnote.model import Changelog, OutputFormat
+from patchnote.render.github_release import render_github_release
+from patchnote.render.json import render_json
+from patchnote.render.markdown import render_markdown
+
+
+def render(changelog: Changelog, config: Config, fmt: OutputFormat) -> str:
+    if fmt is OutputFormat.JSON:
+        return render_json(changelog)
+    if fmt is OutputFormat.GITHUB_RELEASE:
+        return render_github_release(changelog, config)
+    return render_markdown(changelog, config, include_header=False)

patchnote/render/changelog_file.py

@@ -0,0 +1,138 @@
+"""Insert or replace a version section in an existing Keep a Changelog file."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from patchnote.config import Config
+from patchnote.model import Changelog
+from patchnote.render.markdown import render_section_body
+
+VERSION_HEADER_RE = re.compile(
+    r"^## \[([^\]\n]+)\](?:\s*-\s*\d{4}-\d{2}-\d{2})?\s*$",
+    re.MULTILINE,
+)
+UNRELEASED_RE = re.compile(r"^## \[Unreleased\]\s*$", re.MULTILINE | re.IGNORECASE)
+LINK_REF_RE = re.compile(r"^\[([^\]]+)\]:\s+\S+\s*$", re.MULTILINE)
+
+
+def _section_bounds(text: str, start: int) -> tuple[int, int]:
+    """Return [start, end) of a `## …` section starting at ``start``."""
+    next_header = re.search(r"^## ", text[start + 3 :], re.MULTILINE)
+    end = start + 3 + next_header.start() if next_header else len(text)
+    return start, end
+
+
+def _find_section(text: str, version: str) -> tuple[int, int] | None:
+    for match in VERSION_HEADER_RE.finditer(text):
+        if match.group(1).lower() == version.lower():
+            return _section_bounds(text, match.start())
+    if version.lower() == "unreleased":
+        unreleased = UNRELEASED_RE.search(text)
+        if unreleased:
+            return _section_bounds(text, unreleased.start())
+    return None
+
+
+def _split_link_footer(text: str) -> tuple[str, str]:
+    """Peel a trailing Keep-a-Changelog link-reference block off ``text``."""
+    lines = text.splitlines(keepends=True)
+    idx = len(lines)
+    saw_link = False
+    while idx > 0:
+        stripped = lines[idx - 1].strip()
+        if not stripped:
+            idx -= 1
+            continue
+        if LINK_REF_RE.match(stripped):
+            saw_link = True
+            idx -= 1
+            continue
+        break
+    if not saw_link:
+        return text, ""
+    body = "".join(lines[:idx])
+    footer = "".join(lines[idx:])
+    return body, footer
+
+
+def _upsert_link(footer: str, label: str, url: str) -> str:
+    pattern = re.compile(rf"^\[{re.escape(label)}\]:\s+\S+\s*$", re.MULTILINE)
+    line = f"[{label}]: {url}\n"
+    if pattern.search(footer):
+        return pattern.sub(line.rstrip(), footer, count=1)
+    if footer and not footer.endswith("\n"):
+        footer += "\n"
+    return footer + line
+
+
+def prepend_release(
+    existing: str,
+    changelog: Changelog,
+    config: Config,
+) -> str:
+    """Insert ``changelog`` after the file header / Unreleased section.
+
+    Running twice for the same version replaces the existing section instead of
+    duplicating it. Everything else in the file is preserved byte-for-byte
+    outside the replaced span and the compare-link footer.
+    """
+    section = render_section_body(changelog, config).rstrip() + "\n"
+    # Drop the compare link from the section; we maintain those at file bottom.
+    section_lines = [
+        line for line in section.splitlines(keepends=True) if not LINK_REF_RE.match(line.strip())
+    ]
+    section = "".join(section_lines)
+    if not section.endswith("\n"):
+        section += "\n"
+
+    if not existing.strip():
+        header = config.header.rstrip() + "\n\n" if config.header else ""
+        body = header + section
+        footer = ""
+        if changelog.compare_url:
+            footer = _upsert_link(footer, changelog.version or "Unreleased", changelog.compare_url)
+        return body.rstrip() + "\n\n" + footer if footer else body
+
+    newline = "\r\n" if "\r\n" in existing else "\n"
+    section = section.replace("\n", newline).rstrip("\r\n") + newline * 2
+    body, link_footer = _split_link_footer(existing)
+    version = changelog.version or "Unreleased"
+    found = _find_section(body, version)
+    if found is not None:
+        start, end = found
+        if end == len(body) and link_footer.startswith(("\n", "\r")):
+            section = section.rstrip("\r\n") + newline
+        body = body[:start] + section + body[end:]
+    else:
+        unreleased = _find_section(body, "Unreleased")
+        first_version = VERSION_HEADER_RE.search(body)
+        if unreleased is not None:
+            at = unreleased[1]
+        elif first_version is not None:
+            at = first_version.start()
+        else:
+            at = len(body)
+        prefix, suffix = body[:at], body[at:]
+        separator = "" if not prefix or prefix.endswith(newline * 2) else newline * 2
+        body = prefix + separator + section + suffix
+    if changelog.compare_url:
+        label = changelog.version or "Unreleased"
+        pattern = re.compile(rf"^\[{re.escape(label)}\]:[^\r\n]*(?:\r?\n|$)", re.MULTILINE)
+        line = f"[{label}]: {changelog.compare_url}{newline}"
+        if pattern.search(link_footer):
+            link_footer = pattern.sub(lambda _match: line, link_footer, count=1)
+        else:
+            if link_footer and not link_footer.endswith(("\n", "\r")):
+                link_footer += newline
+            link_footer += line
+    return body + link_footer
+
+
+def write_prepend(path: Path, changelog: Changelog, config: Config) -> str:
+    existing = path.read_bytes().decode("utf-8") if path.exists() else ""
+    updated = prepend_release(existing, changelog, config)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(updated.encode("utf-8"))
+    return updated

patchnote/render/github_release.py

@@ -0,0 +1,36 @@
+"""GitHub Release body: markdown without the H2 version heading or compare link."""
+
+from __future__ import annotations
+
+from patchnote.config import Config
+from patchnote.model import Changelog
+from patchnote.render.markdown import format_entry, iter_ordered_sections
+
+
+def render_github_release(changelog: Changelog, config: Config) -> str:
+    lines: list[str] = []
+    if changelog.overview:
+        lines.append(changelog.overview.rstrip())
+        lines.append("")
+    if changelog.breaking:
+        lines.append(f"### {config.breaking_section}")
+        lines.append("")
+        for entry in changelog.breaking:
+            lines.append(f"- {format_entry(entry, config)}")
+            if entry.breaking_description:
+                lines.append(f"  - **BREAKING CHANGE:** {entry.breaking_description}")
+        lines.append("")
+    for name, entries in iter_ordered_sections(changelog, config):
+        lines.append(f"### {name}")
+        lines.append("")
+        for entry in entries:
+            lines.append(f"- {format_entry(entry, config)}")
+        lines.append("")
+    if changelog.contributors and config.include_contributors:
+        lines.append("### Contributors")
+        lines.append("")
+        for person in changelog.contributors:
+            suffix = " (first-time contributor)" if person.first_time else ""
+            lines.append(f"- {person.name}{suffix}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

patchnote/render/json.py

@@ -0,0 +1,12 @@
+"""JSON changelog rendering."""
+
+from __future__ import annotations
+
+import json
+
+from patchnote.model import Changelog
+
+
+def render_json(changelog: Changelog) -> str:
+    payload = changelog.model_dump(mode="json")
+    return json.dumps(payload, indent=2, sort_keys=False) + "\n"