esys-gitlog 0.1.0__py3-none-any.whl

esys_gitlog/config.py

@@ -0,0 +1,202 @@
+"""Resolved analysis configuration for one run."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, Literal
+
+from esys_gitlog.detection import detect_links
+from esys_gitlog.preferences import (
+    Preferences,
+    empty_preferences,
+    fill_link_gaps,
+    load_layered_preferences,
+    merge_missing_links_into_user_file,
+    resolved_ref_id_width,
+    resolved_show_author,
+    resolved_show_body,
+    resolved_show_conventional,
+    resolved_show_date,
+    resolved_show_id,
+    resolved_type_width,
+)
+from esys_gitlog.tool_paths import profile_search_roots_high_to_low
+
+QaMode = Literal["strict", "permissive"]
+DisplayMode = Literal["subject-precedence", "trailer-precedence"]
+
+DEFAULT_TYPES: tuple[str, ...] = (
+    "adr",
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "refactor",
+    "revert",
+    "style",
+    "test",
+)
+
+
+@dataclass(frozen=True)
+class ProfileRules:
+    """Active profile rules for interpretation and QA."""
+
+    name: str
+    conventional: bool = True
+    conventional_locations: tuple[str, ...] = ("title",)
+    references: bool = True
+    reference_locations: tuple[str, ...] = ("refs",)
+    identifier_family: str = "jira-id"
+    signed_off_by: bool = True
+    types: tuple[str, ...] = DEFAULT_TYPES
+    reference_keys: tuple[str, ...] = ("Refs",)
+    # Populated from preference ``links`` at resolve time (not from profile JSON).
+    ref_links: dict[str, str] = field(default_factory=dict)
+    commit_link: str | None = None
+
+
+@dataclass(frozen=True)
+class AnalysisConfig:
+    """Fully resolved settings for one analysis."""
+
+    profile: ProfileRules
+    qa: QaMode = "strict"
+    display: DisplayMode = "subject-precedence"
+    preferences: Preferences = field(default_factory=empty_preferences)
+    # Human history: fixed-width refs / minimum Type(Scope) columns.
+    ref_id_width: int = 10
+    type_width: int = 10
+    show_author: bool = False
+    show_date: bool = False
+    show_body: bool = False
+    show_id: bool = True
+    show_conventional: bool = True
+
+
+def _default_profile() -> ProfileRules:
+    return ProfileRules(name="default")
+
+
+def _trailer_profile() -> ProfileRules:
+    return ProfileRules(
+        name="trailer",
+        conventional_locations=("trailer",),
+    )
+
+
+KNOWN_PROFILES: dict[str, ProfileRules] = {
+    "default": _default_profile(),
+    "trailer": _trailer_profile(),
+}
+
+
+def _profile_from_object(data: dict[str, Any], *, name: str = "custom") -> ProfileRules:
+    conventional_locations = data.get("conventionalLocations", ["title"])
+    reference_locations = data.get("referenceLocations", ["refs"])
+    types = data.get("types", list(DEFAULT_TYPES))
+    reference_keys = data.get("referenceKeys", ["Refs"])
+    # Legacy profile link keys are ignored (CADR-0012); prefer preference files.
+    return ProfileRules(
+        name=name,
+        conventional=bool(data.get("conventional", True)),
+        conventional_locations=tuple(conventional_locations),
+        references=bool(data.get("references", True)),
+        reference_locations=tuple(reference_locations),
+        identifier_family=str(data.get("identifierFamily", "jira-id")),
+        signed_off_by=bool(data.get("signedOffBy", True)),
+        types=tuple(types),
+        reference_keys=tuple(reference_keys),
+    )
+
+
+def load_profile_file(path: Path) -> ProfileRules:
+    """Load a custom profile object from a JSON file."""
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("profile config must be a JSON object")
+    return _profile_from_object(payload, name=str(payload.get("name", "custom")))
+
+
+def resolve_named_profile(
+    name: str,
+    *,
+    cwd: Path,
+    config_path: Path | None = None,
+) -> ProfileRules:
+    """Resolve built-in, ``--config`` file, or layered ``profiles/<name>.json``."""
+    if config_path is not None:
+        return load_profile_file(config_path)
+    if name in KNOWN_PROFILES:
+        return KNOWN_PROFILES[name]
+    for root in profile_search_roots_high_to_low(cwd):
+        path = root / "profiles" / f"{name}.json"
+        if path.is_file():
+            return load_profile_file(path)
+    raise ValueError(f"unknown profile: {name}")
+
+
+def resolve_config(
+    *,
+    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,
+    apply_detection: bool = True,
+    persist_detection: bool | None = None,
+) -> AnalysisConfig:
+    """Resolve preferences, named profile, and optional link detection."""
+    root = (cwd or Path.cwd()).resolve()
+    prefs = load_layered_preferences(root, preferences_path=preferences_path)
+
+    if apply_detection:
+        discovered = detect_links(root, detection=prefs.detection)
+        prefs = fill_link_gaps(prefs, discovered)
+        should_persist = (
+            persist_detection if persist_detection is not None else prefs.detection.resolved()[2]
+        )
+        if should_persist and (discovered.ref_links or discovered.commit_link is not None):
+            merge_missing_links_into_user_file(discovered=discovered)
+
+    profile_name = profile or prefs.defaults.profile or "default"
+    qa_mode: QaMode = qa or prefs.defaults.qa or "strict"
+    rules = resolve_named_profile(
+        profile_name,
+        cwd=root,
+        config_path=config_path,
+    )
+    rules = replace(
+        rules,
+        ref_links=dict(prefs.links.ref_links),
+        commit_link=prefs.links.commit_link,
+    )
+
+    if display is not None:
+        display_mode = display
+    elif prefs.defaults.display is not None:
+        display_mode = prefs.defaults.display
+    elif "trailer" in rules.conventional_locations and "title" not in rules.conventional_locations:
+        display_mode = "trailer-precedence"
+    else:
+        display_mode = "subject-precedence"
+
+    return AnalysisConfig(
+        profile=rules,
+        qa=qa_mode,
+        display=display_mode,
+        preferences=prefs,
+        ref_id_width=resolved_ref_id_width(prefs.defaults),
+        type_width=resolved_type_width(prefs.defaults),
+        show_author=resolved_show_author(prefs.defaults),
+        show_date=resolved_show_date(prefs.defaults),
+        show_body=resolved_show_body(prefs.defaults),
+        show_id=resolved_show_id(prefs.defaults),
+        show_conventional=resolved_show_conventional(prefs.defaults),
+    )

esys_gitlog/detection.py

@@ -0,0 +1,145 @@
+"""Optional local CLI / git-remote link-base detection (SADR-0010)."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from esys_gitlog.links import detect_commit_link_from_remote, read_origin_url
+from esys_gitlog.preferences import DetectionSettings, LinkPreferences
+
+_JIRA_SERVER = re.compile(r"""(?mx)^\s*(?:server|endpoint|url)\s*[:=]\s*["']?(https?://[^\s"']+)""")
+
+
+def _run_text(argv: list[str]) -> str | None:
+    executable = shutil.which(argv[0])
+    if not executable:
+        return None
+    try:
+        completed = subprocess.run(
+            [executable, *argv[1:]],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if completed.returncode != 0:
+        return None
+    text = (completed.stdout or "").strip()
+    return text or None
+
+
+def _browse_template(base: str) -> str:
+    return base.rstrip("/") + "/browse/{id}"
+
+
+def detect_jira_ref_link() -> str | None:
+    """Return a ``jira-id`` browse template from local jira CLI config if possible."""
+    host = _run_text(["jira", "me", "--plain"])  # may fail; try config files next
+    # Prefer config files — avoid network. `jira me` can hit the API.
+    for candidate in _jira_config_candidates():
+        if not candidate.is_file():
+            continue
+        text = candidate.read_text(encoding="utf-8", errors="replace")
+        match = _JIRA_SERVER.search(text)
+        if match:
+            return _browse_template(match.group(1))
+    # Some jira CLIs expose server without network:
+    for argv in (
+        ["jira", "config", "get", "server"],
+        ["acli", "jira", "config", "get", "site"],
+    ):
+        value = _run_text(list(argv))
+        if value and value.startswith("http"):
+            return _browse_template(value)
+    _ = host  # unused; kept for future plain local probes
+    return None
+
+
+def _jira_config_candidates() -> list[Path]:
+    home = Path.home()
+    return [
+        home / ".config" / ".jira" / ".config.yml",
+        home / ".jira" / ".config.yml",
+        home / ".config" / "jira" / "config.yml",
+    ]
+
+
+def detect_github_commit_link(*, cwd: Path | None = None) -> str | None:
+    """Prefer ``gh`` host config; fall back to origin remote when appropriate."""
+    host = _run_text(["gh", "config", "get", "host"])
+    if host and "github" in host:
+        # Repo-specific commit URL still needs remote path; leave to git remote.
+        return None
+    # ``gh repo view --json url`` needs network; skip.
+    _ = cwd
+    return None
+
+
+def detect_gitlab_commit_link() -> str | None:
+    host = _run_text(["glab", "config", "get", "host"])
+    if host and host.startswith("http"):
+        # Project path still needs git remote; host alone is not a commit template.
+        return None
+    return None
+
+
+def detect_links(
+    cwd: Path,
+    *,
+    detection: DetectionSettings | None = None,
+    git_executable: str = "git",
+) -> LinkPreferences:
+    """Discover link templates for unset preference gaps (best-effort, local)."""
+    settings = detection or DetectionSettings()
+    cli_on, git_on, _persist = settings.resolved()
+    ref_links: dict[str, str] = {}
+    commit_link: str | None = None
+
+    if cli_on:
+        jira = detect_jira_ref_link()
+        if jira:
+            ref_links["jira-id"] = jira
+        # gh/glab currently contribute via git remote for commit URLs.
+        detect_github_commit_link(cwd=cwd)
+        detect_gitlab_commit_link()
+
+    if git_on:
+        remote = read_origin_url(cwd, git_executable=git_executable)
+        if remote:
+            commit_link = detect_commit_link_from_remote(remote)
+
+    return LinkPreferences(ref_links=ref_links, commit_link=commit_link)
+
+
+def read_gh_host_file() -> str | None:
+    """Test helper: parse ``gh`` hosts.yml for a github.com entry."""
+    path = Path.home() / ".config" / "gh" / "hosts.yml"
+    if not path.is_file():
+        return None
+    try:
+        # Avoid requiring PyYAML; look for github.com key.
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if "github.com:" in text or "github.com" in text:
+        return "https://github.com"
+    return None
+
+
+def dump_detection_debug() -> str:
+    """Return a short JSON summary of what would be detected (for CLI)."""
+    return json.dumps(
+        {
+            "jiraConfigCandidates": [str(p) for p in _jira_config_candidates()],
+            "ghOnPath": bool(shutil.which("gh")),
+            "glabOnPath": bool(shutil.which("glab")),
+            "jiraOnPath": bool(shutil.which("jira")),
+        },
+        indent=2,
+    )

esys_gitlog/display.py

@@ -0,0 +1,82 @@
+"""Display selection. Does not erase claims or diagnostics."""
+
+from __future__ import annotations
+
+import re
+
+from esys_gitlog.config import AnalysisConfig
+from esys_gitlog.identifiers import matches_family, ref_identity_key
+from esys_gitlog.interpret import title_pattern
+from esys_gitlog.links import resolve_ref_url
+from esys_gitlog.model import CommitResult, DisplayRef, DisplaySelection
+
+_SUFFIX_REF = re.compile(r"(?:\s+|\[)(?P<token>[A-Za-z][A-Za-z0-9._-]*-\d+)\]?\s*$")
+_PREFIX_REF = re.compile(r"^(?:\[)?(?P<token>[A-Za-z][A-Za-z0-9._-]*-\d+)(?:\])?(?::|\s+)\s*")
+
+
+def _pick_single(
+    result: CommitResult,
+    field_name: str,
+    reason: str,
+) -> str | None:
+    claims = result.claims_for(field_name)
+    subject = [claim for claim in claims if claim.source == "subject"]
+    trailer = [claim for claim in claims if claim.source == "trailer"]
+    if reason == "trailer-precedence":
+        if trailer:
+            return trailer[0].value
+        if subject:
+            return subject[0].value
+        return None
+    if subject:
+        return subject[0].value
+    if trailer:
+        return trailer[0].value
+    return None
+
+
+def _cleaned_title(subject: str, config: AnalysisConfig) -> str:
+    line = subject.splitlines()[0] if subject else ""
+    rules = config.profile
+    if rules.conventional and "title" in rules.conventional_locations:
+        match = title_pattern(rules.types).fullmatch(line)
+        if match is not None:
+            return match.group("description")
+    if rules.references:
+        stripped = _PREFIX_REF.sub("", line, count=1)
+        stripped = _SUFFIX_REF.sub("", stripped)
+        return stripped.strip() or line
+    return line
+
+
+def _display_refs(result: CommitResult, config: AnalysisConfig) -> tuple[DisplayRef, ...]:
+    seen: set[str] = set()
+    refs: list[DisplayRef] = []
+    family = config.profile.identifier_family
+    for claim in result.claims_for("refs"):
+        key = ref_identity_key(claim.value)
+        if key in seen:
+            continue
+        seen.add(key)
+        claim_family = family if matches_family(claim.value, family) else family
+        url = resolve_ref_url(claim.value, family, config.profile)
+        refs.append(DisplayRef(id=claim.value, family=claim_family, url=url))
+    return tuple(refs)
+
+
+def select_display(
+    result: CommitResult,
+    config: AnalysisConfig,
+    *,
+    subject: str = "",
+) -> None:
+    """Choose displayed values without inventing claims."""
+    reason = config.display
+    result.display = DisplaySelection(
+        reason=reason,
+        type=_pick_single(result, "type", reason),
+        scope=_pick_single(result, "scope", reason),
+        title=_cleaned_title(subject, config) or None,
+        breaking=len(result.claims_for("breaking")) > 0,
+        refs=_display_refs(result, config),
+    )