esys-gitlog 0.1.0__py3-none-any.whl

esys_gitlog/interpret.py

@@ -0,0 +1,308 @@
+"""Pure interpretation: subject + body -> claims."""
+
+from __future__ import annotations
+
+import re
+
+from esys_gitlog.config import AnalysisConfig, ProfileRules
+from esys_gitlog.identifiers import matches_family
+from esys_gitlog.model import Claim, CommitResult
+
+_TRAILER_LINE = re.compile(r"^(?P<key>[A-Za-z0-9][A-Za-z0-9 -]*):\s?(?P<value>.*)$")
+_PREFIX_REF = re.compile(r"^(?P<token>[A-Za-z][A-Za-z0-9._-]*-\d+)\b")
+_BREAKING_KEYS = frozenset({"breaking change", "breaking"})
+
+
+def title_pattern(types: tuple[str, ...]) -> re.Pattern[str]:
+    """Conventional title pattern for the configured type list."""
+    type_alt = "|".join(re.escape(item) for item in types)
+    return re.compile(
+        rf"^(WIP: )?("
+        rf"(?P<type>{type_alt})"
+        rf"(?:\((?P<scope>[a-z0-9._/-]+)\))?"
+        rf"(?P<breaking>!)?"
+        rf"): (?P<description>[A-Za-z0-9].+)$"
+    )
+
+
+def _title_pattern(types: tuple[str, ...]) -> re.Pattern[str]:
+    return title_pattern(types)
+
+
+def _split_refs_tokens(value: str) -> list[str]:
+    """Split a Refs value on commas and spaces, keeping Bug N together."""
+    text = value.strip()
+    if not text:
+        return []
+    pattern = re.compile(
+        r"Bug\s+#?\d+|issue\s+#\d+|[^,\s]+",
+        re.IGNORECASE,
+    )
+    tokens: list[str] = []
+    for match in pattern.finditer(text.replace(",", " ")):
+        token = match.group(0).strip(" ,")
+        if token:
+            tokens.append(token)
+    return tokens
+
+
+def _parse_trailers(body_lines: list[str]) -> list[tuple[str, str, int, int, bool]]:
+    """Return (key, value, line, column, empty) for footer trailers.
+
+    Line numbers are 1-based in the full message (subject is line 1).
+    """
+    if not body_lines:
+        return []
+
+    blank_index: int | None = None
+    for index, line in enumerate(body_lines):
+        if line.strip() == "":
+            blank_index = index
+
+    if blank_index is None:
+        candidate = list(body_lines)
+        start_line = 2
+    else:
+        candidate = list(body_lines[blank_index + 1 :])
+        start_line = blank_index + 3
+
+    if not candidate:
+        return []
+
+    while candidate and not _TRAILER_LINE.match(candidate[0]):
+        candidate = candidate[1:]
+        start_line += 1
+    if not candidate:
+        return []
+
+    trailers: list[tuple[str, str, int, int, bool]] = []
+    line_no = start_line
+    index = 0
+    while index < len(candidate):
+        line = candidate[index]
+        match = _TRAILER_LINE.match(line)
+        if match is None:
+            break
+        key = match.group("key")
+        value = match.group("value") or ""
+        colon_at = line.index(":")
+        value_column = colon_at + 2
+        index += 1
+        while index < len(candidate) and (
+            candidate[index].startswith(" ") or candidate[index].startswith("\t")
+        ):
+            continuation = candidate[index].lstrip(" \t")
+            value = f"{value}\n{continuation}"
+            index += 1
+            line_no += 1
+        empty = value.strip() == ""
+        trailers.append((key, value, line_no, value_column, empty))
+        line_no += 1
+    return trailers
+
+
+def _reference_key_names(rules: ProfileRules) -> set[str]:
+    return {key.casefold() for key in rules.reference_keys} | {"refs"}
+
+
+def interpret_commit(subject: str, body: str, config: AnalysisConfig) -> CommitResult:
+    """Interpret one commit message under the resolved profile."""
+    result = CommitResult()
+    rules = config.profile
+    subject_line = subject.splitlines()[0] if subject else ""
+    body_lines = body.splitlines() if body else []
+
+    if rules.conventional and "title" in rules.conventional_locations:
+        _interpret_title(subject_line, rules, result)
+
+    if rules.references and "prefix" in rules.reference_locations:
+        _interpret_prefix_refs(subject_line, rules, result)
+
+    trailer_type_ok = False
+    for key, value, line, column, empty in _parse_trailers(body_lines):
+        key_folded = key.casefold()
+        if empty:
+            result.claims.append(
+                Claim(
+                    field="trailer",
+                    value="",
+                    source="trailer",
+                    line=line,
+                    column=column,
+                    key=key,
+                )
+            )
+            continue
+
+        if key_folded in ("type",) and rules.conventional:
+            result.claims.append(
+                Claim(
+                    field="type",
+                    value=value.strip(),
+                    source="trailer",
+                    line=line,
+                    column=column,
+                    key=key,
+                )
+            )
+            if value.strip() in rules.types:
+                trailer_type_ok = True
+            continue
+
+        if key_folded in ("scope",) and rules.conventional:
+            result.claims.append(
+                Claim(
+                    field="scope",
+                    value=value.strip(),
+                    source="trailer",
+                    line=line,
+                    column=column,
+                    key=key,
+                )
+            )
+            continue
+
+        if key_folded in _BREAKING_KEYS:
+            result.claims.append(
+                Claim(
+                    field="breaking",
+                    value=value,
+                    source="trailer",
+                    line=line,
+                    column=column,
+                    key=key,
+                )
+            )
+            continue
+
+        if (
+            key_folded in _reference_key_names(rules)
+            and rules.references
+            and "refs" in rules.reference_locations
+        ):
+            _interpret_refs(key, value, line, column, rules, result)
+            continue
+
+        if key_folded == "signed-off-by" and rules.signed_off_by:
+            result.signed_off_by.append(value)
+            result.claims.append(
+                Claim(
+                    field="signed-off-by",
+                    value=value,
+                    source="trailer",
+                    line=line,
+                    column=column,
+                    key=key,
+                )
+            )
+            continue
+
+        result.generic_trailers.append((key, value))
+        result.claims.append(
+            Claim(
+                field="trailer",
+                value=value,
+                source="trailer",
+                line=line,
+                column=column,
+                key=key,
+            )
+        )
+
+    if (
+        rules.conventional
+        and "trailer" in rules.conventional_locations
+        and trailer_type_ok
+        and "title" not in rules.conventional_locations
+    ):
+        result.conventional_matched = True
+    elif (
+        rules.conventional
+        and "trailer" in rules.conventional_locations
+        and "title" in rules.conventional_locations
+        and trailer_type_ok
+    ):
+        result.conventional_matched = True
+
+    return result
+
+
+def _interpret_title(subject_line: str, rules: ProfileRules, result: CommitResult) -> None:
+    match = _title_pattern(rules.types).fullmatch(subject_line)
+    if match is None:
+        return
+    result.conventional_matched = True
+    result.claims.append(
+        Claim(
+            field="type",
+            value=match.group("type"),
+            source="subject",
+            line=1,
+            column=match.start("type") + 1,
+        )
+    )
+    scope_value = match.group("scope")
+    if scope_value is not None:
+        result.claims.append(
+            Claim(
+                field="scope",
+                value=scope_value,
+                source="subject",
+                line=1,
+                column=match.start("scope") + 1,
+            )
+        )
+    if match.group("breaking"):
+        result.claims.append(
+            Claim(
+                field="breaking",
+                value="!",
+                source="subject",
+                line=1,
+                column=match.start("breaking") + 1,
+            )
+        )
+
+
+def _interpret_prefix_refs(subject_line: str, rules: ProfileRules, result: CommitResult) -> None:
+    match = _PREFIX_REF.match(subject_line)
+    if match is None:
+        return
+    token = match.group("token")
+    result.claims.append(
+        Claim(
+            field="refs",
+            value=token,
+            source="subject",
+            line=1,
+            column=1,
+            key="prefix",
+        )
+    )
+    if matches_family(token, rules.identifier_family):
+        result.references_matched = True
+
+
+def _interpret_refs(
+    key: str,
+    value: str,
+    line: int,
+    column: int,
+    rules: ProfileRules,
+    result: CommitResult,
+) -> None:
+    for token in _split_refs_tokens(value):
+        relative = value.find(token)
+        token_column = column + max(relative, 0)
+        result.claims.append(
+            Claim(
+                field="refs",
+                value=token,
+                source="trailer",
+                line=line,
+                column=token_column,
+                key=key,
+            )
+        )
+        if matches_family(token, rules.identifier_family):
+            result.references_matched = True

esys_gitlog/links.py

@@ -0,0 +1,87 @@
+"""Resolve ticket and forge commit URLs for the report (CLI config only)."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from esys_gitlog.config import ProfileRules
+
+_GITHUB_SSH = re.compile(r"^git@github\.com:(?P<path>.+?)(?:\.git)?$")
+_GITHUB_HTTPS = re.compile(r"^https?://(?:www\.)?github\.com/(?P<path>.+?)(?:\.git)?/?$")
+_GITLAB_SSH = re.compile(r"^git@gitlab\.com:(?P<path>.+?)(?:\.git)?$")
+_GITLAB_HTTPS = re.compile(r"^https?://(?:www\.)?gitlab\.com/(?P<path>.+?)(?:\.git)?/?$")
+_AZURE_HTTPS = re.compile(
+    r"^https://(?:[\w.-]+@)?dev\.azure\.com/(?P<org>[^/]+)/(?P<project>[^/]+)/_git/"
+    r"(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+
+def apply_template(template: str, **values: str) -> str:
+    result = template
+    for key, value in values.items():
+        result = result.replace("{" + key + "}", value)
+    return result
+
+
+def resolve_ref_url(ref_id: str, family: str, rules: ProfileRules) -> str | None:
+    template = rules.ref_links.get(family) or rules.ref_links.get("*")
+    if not template:
+        return None
+    return apply_template(template, id=ref_id)
+
+
+def detect_commit_link_from_remote(remote_url: str) -> str | None:
+    text = remote_url.strip()
+    for pattern, fmt in (
+        (_GITHUB_SSH, "https://github.com/{path}/commit/{{commit}}"),
+        (_GITHUB_HTTPS, "https://github.com/{path}/commit/{{commit}}"),
+        (_GITLAB_SSH, "https://gitlab.com/{path}/-/commit/{{commit}}"),
+        (_GITLAB_HTTPS, "https://gitlab.com/{path}/-/commit/{{commit}}"),
+    ):
+        match = pattern.match(text)
+        if match:
+            path = match.group("path").removesuffix(".git")
+            return fmt.format(path=path)
+    match = _AZURE_HTTPS.match(text)
+    if match:
+        org = match.group("org")
+        project = match.group("project")
+        repo = match.group("repo").removesuffix(".git")
+        return f"https://dev.azure.com/{org}/{project}/_git/{repo}/commit/{{commit}}"
+    return None
+
+
+def read_origin_url(cwd: Path, *, git_executable: str = "git") -> str | None:
+    try:
+        completed = subprocess.run(
+            [git_executable, "remote", "get-url", "origin"],
+            cwd=cwd,
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+    except OSError:
+        return None
+    if completed.returncode != 0:
+        return None
+    url = completed.stdout.strip()
+    return url or None
+
+
+def resolve_commit_url(
+    commit_id: str,
+    rules: ProfileRules,
+    *,
+    cwd: Path | None = None,
+    git_executable: str = "git",
+) -> str | None:
+    """Apply ``commitLink`` from resolved preferences (detection runs in ``resolve_config``)."""
+    _ = cwd, git_executable  # kept for call-site compatibility
+    template = rules.commit_link
+    if not template:
+        return None
+    return apply_template(template, commit=commit_id)

esys_gitlog/model.py

@@ -0,0 +1,138 @@
+"""Typed result model for one commit.
+
+Claims stay beside the displayed value. Display does not erase evidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Severity = Literal["warning", "error"]
+ClaimSource = Literal["subject", "trailer"]
+
+
+@dataclass(frozen=True, slots=True)
+class Claim:
+    """One recognized value with provenance."""
+
+    field: str
+    value: str
+    source: ClaimSource
+    line: int
+    column: int
+    key: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """One QA finding."""
+
+    code: str
+    severity: Severity
+    field: str
+    claims: tuple[Claim, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DisplayRef:
+    """One displayed reference id with optional autolink."""
+
+    id: str
+    family: str | None = None
+    url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DisplaySelection:
+    """Displayed values for the report."""
+
+    reason: Literal["subject-precedence", "trailer-precedence"]
+    type: str | None = None
+    scope: str | None = None
+    title: str | None = None
+    breaking: bool = False
+    refs: tuple[DisplayRef, ...] = ()
+
+
+@dataclass(slots=True)
+class CommitResult:
+    """Interpretation, QA, and display for one commit message."""
+
+    claims: list[Claim] = field(default_factory=list)
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    display: DisplaySelection | None = None
+    conventional_matched: bool = False
+    references_matched: bool = False
+    signed_off_by: list[str] = field(default_factory=list)
+    generic_trailers: list[tuple[str, str]] = field(default_factory=list)
+    # Opaque transport / presentation (set by the application layer).
+    message: str | None = None
+    author_name: str | None = None
+    author_email: str | None = None
+    authored_date: str | None = None
+    commit_url: str | None = None
+
+    def claims_for(self, field_name: str) -> list[Claim]:
+        return [claim for claim in self.claims if claim.field == field_name]
+
+    def to_report_commit(self, commit_id: str = "") -> dict[str, Any]:
+        """Map to the per-commit report object."""
+        diagnostics: list[dict[str, Any]] = []
+        for item in self.diagnostics:
+            entry: dict[str, Any] = {
+                "code": item.code,
+                "severity": item.severity,
+                "field": item.field,
+                "claims": [],
+            }
+            for claim in item.claims:
+                claim_entry: dict[str, Any] = {
+                    "source": claim.source,
+                    "value": claim.value,
+                    "line": claim.line,
+                    "column": claim.column,
+                }
+                if claim.key is not None:
+                    claim_entry["key"] = claim.key
+                entry["claims"].append(claim_entry)
+            diagnostics.append(entry)
+
+        display_selection: dict[str, Any] = {}
+        if self.display is not None:
+            display_selection["reason"] = self.display.reason
+            if self.display.type is not None:
+                display_selection["type"] = self.display.type
+            if self.display.scope is not None:
+                display_selection["scope"] = self.display.scope
+            if self.display.title is not None:
+                display_selection["title"] = self.display.title
+            if self.display.breaking:
+                display_selection["breaking"] = True
+            if self.display.refs:
+                display_selection["refs"] = [
+                    {
+                        **{"id": ref.id},
+                        **({"family": ref.family} if ref.family else {}),
+                        **({"url": ref.url} if ref.url else {}),
+                    }
+                    for ref in self.display.refs
+                ]
+
+        result: dict[str, Any] = {
+            "diagnostics": diagnostics,
+            "displaySelection": display_selection,
+        }
+        if commit_id:
+            result["commit"] = commit_id
+        if self.commit_url:
+            result["commitUrl"] = self.commit_url
+        if self.message is not None:
+            result["message"] = self.message
+        if self.author_name is not None:
+            result["authorName"] = self.author_name
+        if self.author_email is not None:
+            result["authorEmail"] = self.author_email
+        if self.authored_date is not None:
+            result["authoredDate"] = self.authored_date
+        return result

esys_gitlog/pager.py

@@ -0,0 +1,106 @@
+"""Screenful human-output pager (Enter/Space = next page, not next line).
+
+Works on Windows (``msvcrt``) and Unix (``termios`` / ``tty``).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from typing import TextIO
+
+from rich.pager import Pager
+
+
+def _read_key(stdin: TextIO | None = None) -> str:
+    """Read one keypress without requiring a following Enter.
+
+    Returns a single character. Enter is ``\\r`` (Windows) or ``\\n`` (Unix).
+    ``q`` / ``Q`` means quit. Empty string means “ignore / treat as next page”.
+    """
+    stream = stdin if stdin is not None else sys.stdin
+
+    if not hasattr(stream, "isatty") or not stream.isatty():
+        # Piped / non-interactive: one line to continue, or EOF to stop.
+        line = stream.readline()
+        if not line:
+            return "q"
+        if line.lower().startswith("q"):
+            return "q"
+        return "\n"
+
+    if sys.platform == "win32":  # pragma: no cover
+        import msvcrt
+
+        char = msvcrt.getwch()
+        # Arrow / function keys are a two-char prefix + code.
+        if char in ("\x00", "\xe0"):
+            msvcrt.getwch()
+            return ""
+        return char
+
+    # POSIX TTY raw read — not exercised under non-interactive pytest.
+    return _read_key_posix(stream)  # pragma: no cover
+
+
+def _read_key_posix(stream: TextIO) -> str:  # pragma: no cover
+    import select
+    import termios
+    import tty
+
+    fd = stream.fileno()
+    old = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        char = stream.read(1)
+        # Drain a short ESC sequence (arrows) so it does not leak into the next page.
+        if char == "\x1b":
+            while True:
+                ready, _, _ = select.select([fd], [], [], 0.05)
+                if not ready:
+                    break
+                stream.read(1)
+            return ""
+        return char
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+
+class ScreenPager(Pager):
+    """Page by terminal height on Windows and Linux.
+
+    Enter or Space advances one screen; ``q`` quits.
+    """
+
+    def show(self, content: str) -> None:
+        lines = content.splitlines()
+        if not lines:
+            return
+
+        # Leave one row for the ``:`` prompt.
+        page_size = max(1, shutil.get_terminal_size((80, 24)).lines - 1)
+        stdout = sys.stdout
+        index = 0
+        total = len(lines)
+
+        while index < total:
+            chunk = lines[index : index + page_size]
+            stdout.write("\n".join(chunk))
+            stdout.write("\n")
+            index += len(chunk)
+            if index >= total:
+                break
+            stdout.write(":")
+            stdout.flush()
+            try:
+                key = _read_key()
+            except (EOFError, KeyboardInterrupt, OSError):
+                stdout.write("\n")
+                break
+            # Clear the ``:`` prompt before the next page.
+            stdout.write("\r \r")
+            stdout.flush()
+            if key in ("q", "Q"):
+                stdout.write("\n")
+                break
+            # Enter (\\r / \\n), Space, and other keys → next screenful.

esys_gitlog/pipeline.py

@@ -0,0 +1,44 @@
+"""Compose interpretation, QA, and display for one commit."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from esys_gitlog.config import AnalysisConfig, DisplayMode, QaMode, resolve_config
+from esys_gitlog.display import select_display
+from esys_gitlog.interpret import interpret_commit
+from esys_gitlog.model import CommitResult
+from esys_gitlog.qa import evaluate_qa
+
+
+def analyze_commit(
+    subject: str,
+    body: str = "",
+    *,
+    profile: str | None = None,
+    qa: QaMode | None = None,
+    display: DisplayMode | None = None,
+    config_path: Path | None = None,
+    preferences_path: Path | None = None,
+    cwd: Path | None = None,
+    config: AnalysisConfig | None = None,
+    apply_detection: bool = False,
+) -> CommitResult:
+    """Run the pure semantic stages. No Git and no terminal."""
+    resolved = (
+        config
+        if config is not None
+        else resolve_config(
+            profile=profile,
+            qa=qa,
+            display=display,
+            config_path=config_path,
+            preferences_path=preferences_path,
+            cwd=cwd,
+            apply_detection=apply_detection,
+        )
+    )
+    result = interpret_commit(subject, body, resolved)
+    evaluate_qa(result, resolved)
+    select_display(result, resolved, subject=subject)
+    return result