esys-gitlog 0.1.0__py3-none-any.whl

esys_gitlog/__init__.py

@@ -0,0 +1,3 @@
+"""esys_gitlog — installable package."""
+
+__version__ = "0.1.0"

esys_gitlog/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m esys_gitlog`` and PyInstaller entry."""
+
+from esys_gitlog.cli import main
+
+if __name__ == "__main__":
+    main()

esys_gitlog/app.py

@@ -0,0 +1,215 @@
+"""Application service. Callable without Typer."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from rich.console import Console
+
+from esys_gitlog.config import AnalysisConfig, DisplayMode, QaMode, resolve_config
+from esys_gitlog.git_adapter import GitError, iter_commits, list_commits
+from esys_gitlog.links import resolve_commit_url
+from esys_gitlog.model import CommitResult
+from esys_gitlog.pipeline import analyze_commit
+from esys_gitlog.render import render_history
+from esys_gitlog.report import (
+    build_report,
+    report_exit_code,
+    stream_commit_event,
+    stream_end_event,
+    stream_exit_code,
+    stream_start_event,
+    write_report,
+    write_stream_event,
+)
+
+
+def analyze_history(
+    cwd: str | Path = ".",
+    *,
+    profile: str | None = None,
+    qa: QaMode | None = None,
+    display: DisplayMode | None = None,
+    config_path: Path | None = None,
+    preferences_path: Path | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> tuple[list[tuple[str, CommitResult, str]], AnalysisConfig]:
+    """Load Git history and run the semantic pipeline.
+
+    Returns ``(rows, config)`` where each row is
+    ``(commit_id, result, subject)`` in ``git log`` order.
+    """
+    root = Path(cwd)
+    resolved = resolve_config(
+        profile=profile,
+        qa=qa,
+        display=display,
+        config_path=config_path,
+        preferences_path=preferences_path,
+        cwd=root,
+    )
+    analyzed: list[tuple[str, CommitResult, str]] = []
+    for raw in list_commits(root, git_log_args=git_log_args):
+        result = analyze_commit(raw.subject, raw.body, config=resolved)
+        result.message = raw.message or "\n\n".join(
+            part for part in (raw.subject, raw.body) if part
+        )
+        result.author_name = raw.author_name or None
+        result.author_email = raw.author_email or None
+        result.authored_date = raw.authored_date or None
+        result.commit_url = resolve_commit_url(
+            raw.id,
+            resolved.profile,
+            cwd=root,
+        )
+        analyzed.append((raw.id, result, raw.subject))
+    return analyzed, resolved
+
+
+def run_json(
+    stdout: TextIO[str],
+    *,
+    cwd: str | Path = ".",
+    profile: str | None = None,
+    qa: QaMode | None = None,
+    display: DisplayMode | None = None,
+    config_path: Path | None = None,
+    preferences_path: Path | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> int:
+    """Write the QA report to ``stdout`` only. Return the process exit code."""
+    analyzed, _config = analyze_history(
+        cwd,
+        profile=profile,
+        qa=qa,
+        display=display,
+        config_path=config_path,
+        preferences_path=preferences_path,
+        git_log_args=git_log_args,
+    )
+    pairs = [(commit_id, result) for commit_id, result, _subject in analyzed]
+    document = build_report(pairs)
+    write_report(stdout, document)
+    return report_exit_code(document, walk_finished=True)
+
+
+def run_json_stream(
+    stdout: TextIO[str],
+    *,
+    cwd: str | Path = ".",
+    profile: str | None = None,
+    qa: QaMode | None = None,
+    display: DisplayMode | None = None,
+    config_path: Path | None = None,
+    preferences_path: Path | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> int:
+    """Write NDJSON stream events to ``stdout`` as each commit is analyzed."""
+    root = Path(cwd)
+    resolved = resolve_config(
+        profile=profile,
+        qa=qa,
+        display=display,
+        config_path=config_path,
+        preferences_path=preferences_path,
+        cwd=root,
+    )
+    write_stream_event(stdout, stream_start_event())
+    commits = 0
+    warnings = 0
+    errors = 0
+    walk_finished = True
+    try:
+        for raw in iter_commits(root, git_log_args=git_log_args):
+            result = analyze_commit(raw.subject, raw.body, config=resolved)
+            result.message = raw.message or "\n\n".join(
+                part for part in (raw.subject, raw.body) if part
+            )
+            result.author_name = raw.author_name or None
+            result.author_email = raw.author_email or None
+            result.authored_date = raw.authored_date or None
+            result.commit_url = resolve_commit_url(
+                raw.id,
+                resolved.profile,
+                cwd=root,
+            )
+            for diagnostic in result.diagnostics:
+                if diagnostic.severity == "warning":
+                    warnings += 1
+                elif diagnostic.severity == "error":
+                    errors += 1
+            commits += 1
+            write_stream_event(stdout, stream_commit_event(raw.id, result))
+    except BrokenPipeError:
+        walk_finished = False
+        return stream_exit_code(errors=errors, walk_finished=False)
+    write_stream_event(
+        stdout,
+        stream_end_event(
+            commits=commits,
+            warnings=warnings,
+            errors=errors,
+            walk_finished=walk_finished,
+        ),
+    )
+    return stream_exit_code(errors=errors, walk_finished=walk_finished)
+
+
+def run_human(
+    *,
+    cwd: str | Path = ".",
+    profile: str | None = None,
+    qa: QaMode | None = None,
+    display: DisplayMode | None = None,
+    config_path: Path | None = None,
+    preferences_path: Path | None = None,
+    console: Console | None = None,
+    show_author: bool | None = None,
+    show_date: bool | None = None,
+    show_body: bool | None = None,
+    show_id: bool | None = None,
+    show_conventional: bool | None = None,
+    use_pager: bool | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> int:
+    """Render history for a person. Return the process exit code.
+
+    Explicit ``show_*`` CLI values override preference defaults; ``None`` keeps
+    the resolved preference. ``use_pager`` defaults to on when stdout is a TTY.
+    """
+    analyzed, config = analyze_history(
+        cwd,
+        profile=profile,
+        qa=qa,
+        display=display,
+        config_path=config_path,
+        preferences_path=preferences_path,
+        git_log_args=git_log_args,
+    )
+    render_history(
+        analyzed,
+        console=console,
+        ref_id_width=config.ref_id_width,
+        type_width=config.type_width,
+        show_author=(config.show_author if show_author is None else show_author),
+        show_date=config.show_date if show_date is None else show_date,
+        show_body=config.show_body if show_body is None else show_body,
+        show_id=config.show_id if show_id is None else show_id,
+        show_conventional=(
+            config.show_conventional if show_conventional is None else show_conventional
+        ),
+        use_pager=use_pager,
+    )
+    pairs = [(commit_id, result) for commit_id, result, _subject in analyzed]
+    return report_exit_code(build_report(pairs), walk_finished=True)
+
+
+__all__ = [
+    "GitError",
+    "analyze_history",
+    "run_human",
+    "run_json",
+    "run_json_stream",
+]

esys_gitlog/cli.py

@@ -0,0 +1,323 @@
+"""Thin Typer command boundary for ``git-elog`` / ``git elog``."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import typer
+from typer.core import TyperGroup
+
+from esys_gitlog import app as application
+from esys_gitlog.config import DisplayMode, QaMode
+from esys_gitlog.detection import detect_links, dump_detection_debug
+from esys_gitlog.git_adapter import GitError, filter_git_log_args
+from esys_gitlog.preferences import (
+    fill_link_gaps,
+    load_layered_preferences,
+    merge_missing_links_into_user_file,
+    preferences_to_object,
+)
+from esys_gitlog.tool_paths import user_preferences_path
+
+# Subcommands must not be treated as git log revisions.
+_SUBCOMMANDS = frozenset({"preferences"})
+
+# elog options that consume the next argv token as a value.
+_OPTIONS_WITH_VALUE = frozenset(
+    {
+        "--profile",
+        "--qa",
+        "--display",
+        "--config",
+        "--preferences",
+    }
+)
+
+
+class _ElogGroup(TyperGroup):
+    """Group that only resolves known subcommands; other tokens stay as extra args."""
+
+    def resolve_command(
+        self, ctx: object, args: list[str]
+    ) -> tuple[str | None, object | None, list[str]]:
+        if args and args[0] in self.commands:
+            return super().resolve_command(ctx, args)  # type: ignore[arg-type]
+        return None, None, args
+
+    def invoke(self, ctx: object) -> object:
+        # Typer asserts cmd is not None when leftovers look like a subcommand.
+        # Unknown leftovers are git log args — fold them into ctx.args and run
+        # the group callback. Known names (``preferences``) keep normal dispatch.
+        protected = list(getattr(ctx, "_protected_args", None) or [])
+        extra = list(getattr(ctx, "args", None) or [])
+        combined = [*protected, *extra]
+        if combined and combined[0] not in self.commands:
+            ctx._protected_args = []  # type: ignore[attr-defined]
+            ctx.args = combined  # type: ignore[attr-defined]
+            ctx.invoked_subcommand = None  # type: ignore[attr-defined]
+        return super().invoke(ctx)  # type: ignore[arg-type]
+
+
+app = typer.Typer(
+    cls=_ElogGroup,
+    add_completion=False,
+    context_settings={
+        "help_option_names": ["-h", "--help"],
+        "allow_extra_args": True,
+        # Unknown tokens (``-n``, ``--since``, …) become ctx.args for git log.
+        # Known elog flags still bind first; use ``--`` when a token is both.
+        "ignore_unknown_options": True,
+    },
+)
+preferences_app = typer.Typer(
+    add_completion=False,
+    help="Manage layered tool preferences (SADR-0009 / CADR-0012).",
+)
+app.add_typer(preferences_app, name="preferences")
+
+
+def prepare_argv(argv: list[str]) -> list[str]:
+    """Insert ``--`` before git-log positionals so Typer does not treat them as commands.
+
+    Bare revisions/pathspecs (``HEAD~5``, ``main``) are accepted without an
+    explicit separator. Pure integers after short options (e.g. ``-n 1``) are
+    left in place so they stay with the preceding flag. Unknown git log options
+    (``--since``, ``-n``, …) rely on ``ignore_unknown_options``.
+    """
+    if "--" in argv:
+        return argv
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token in _OPTIONS_WITH_VALUE:
+            index += 2
+            continue
+        if token.startswith("--") and "=" in token:
+            index += 1
+            continue
+        if token.startswith("-"):
+            index += 1
+            continue
+        # Likely a value for a preceding short option such as ``-n 1``.
+        if token.isdigit():
+            index += 1
+            continue
+        # Positional: subcommand or git log revision/path.
+        if token in _SUBCOMMANDS:
+            return argv
+        return [*argv[:index], "--", *argv[index:]]
+    return argv
+
+
+@app.callback(invoke_without_command=True)
+def cli(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Write the QA report as one JSON document to standard output.",
+    ),
+    json_stream: bool = typer.Option(
+        False,
+        "--json-stream",
+        help="Write NDJSON stream events (start/commit/end) to standard output.",
+    ),
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        help="Profile name: default, trailer, or profiles/<name>.json under tool roots.",
+    ),
+    qa: str | None = typer.Option(
+        None,
+        "--qa",
+        help="QA mode: strict or permissive (overrides preference defaults).",
+    ),
+    display: str | None = typer.Option(
+        None,
+        "--display",
+        help="Display precedence: subject-precedence or trailer-precedence.",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        help="Path to a custom profile JSON object for this run.",
+        exists=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    preferences: Path | None = typer.Option(
+        None,
+        "--preferences",
+        help="Path to a preference JSON overlay (highest preference layer).",
+        exists=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    show_author: bool | None = typer.Option(
+        None,
+        "--author/--no-a",
+        "-a",
+        help=(
+            "Show author on an indented line under each commit (human output). "
+            "Overrides defaults.showAuthor when set. Short flags combine (e.g. -abd)."
+        ),
+    ),
+    show_date: bool | None = typer.Option(
+        None,
+        "--date/--no-d",
+        "-d",
+        help=(
+            "Show authored date on an indented line under each commit (human output). "
+            "Overrides defaults.showDate when set. Short flags combine (e.g. -abd)."
+        ),
+    ),
+    show_body: bool | None = typer.Option(
+        None,
+        "--body/--no-b",
+        "-b",
+        help=(
+            "Show commit body on indented lines under each commit (human output). "
+            "Overrides defaults.showBody when set. Short flags combine (e.g. -abd)."
+        ),
+    ),
+    show_id: bool | None = typer.Option(
+        None,
+        "--id/--no-i",
+        "-i",
+        help=(
+            "Show ticket / Jira reference ids on the summary line (human output). "
+            "Overrides defaults.showId when set (default on). Not the commit SHA."
+        ),
+    ),
+    show_conventional: bool | None = typer.Option(
+        None,
+        "--conventional/--no-c",
+        "-c",
+        help=(
+            "Show Type(Scope)[!] on the summary line (human output). "
+            "Overrides defaults.showConventional when set (default on)."
+        ),
+    ),
+    use_pager: bool | None = typer.Option(
+        None,
+        "--pager/--no-p",
+        "-p",
+        help=(
+            "Page human output one screen at a time (default: on when stdout is "
+            "a TTY). Enter/Space = next page, q = quit."
+        ),
+    ),
+) -> None:
+    """Read Git history with the shared esys-gitlog contract.
+
+    Extra arguments after ``--`` (and unknown options / bare revisions) are
+    forwarded to ``git log``. Pretty/diff format options such as ``--oneline``
+    are ignored with a warning; elog owns framing.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    if qa is not None and qa not in ("strict", "permissive"):
+        typer.echo(f"unknown qa mode: {qa}", err=True)
+        raise typer.Exit(code=2)
+    if display is not None and display not in (
+        "subject-precedence",
+        "trailer-precedence",
+    ):
+        typer.echo(f"unknown display mode: {display}", err=True)
+        raise typer.Exit(code=2)
+
+    cwd = Path.cwd()
+    qa_mode: QaMode | None = qa  # type: ignore[assignment]
+    display_mode: DisplayMode | None = display  # type: ignore[assignment]
+    if json_output and json_stream:
+        typer.echo("use only one of --json or --json-stream", err=True)
+        raise typer.Exit(code=2)
+
+    git_log_args, git_log_warnings = filter_git_log_args(list(ctx.args))
+    for message in git_log_warnings:
+        typer.echo(message, err=True)
+
+    try:
+        if json_stream:
+            code = application.run_json_stream(
+                sys.stdout,
+                cwd=cwd,
+                profile=profile,
+                qa=qa_mode,
+                display=display_mode,
+                config_path=config,
+                preferences_path=preferences,
+                git_log_args=git_log_args,
+            )
+        elif json_output:
+            code = application.run_json(
+                sys.stdout,
+                cwd=cwd,
+                profile=profile,
+                qa=qa_mode,
+                display=display_mode,
+                config_path=config,
+                preferences_path=preferences,
+                git_log_args=git_log_args,
+            )
+        else:
+            code = application.run_human(
+                cwd=cwd,
+                profile=profile,
+                qa=qa_mode,
+                display=display_mode,
+                config_path=config,
+                preferences_path=preferences,
+                show_author=show_author,
+                show_date=show_date,
+                show_body=show_body,
+                show_id=show_id,
+                show_conventional=show_conventional,
+                use_pager=use_pager,
+                git_log_args=git_log_args,
+            )
+    except GitError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from exc
+    except ValueError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from exc
+    raise typer.Exit(code=code)
+
+
+@preferences_app.command("detect")
+def preferences_detect(
+    write: bool = typer.Option(
+        True,
+        "--write/--no-write",
+        help="Merge discovered link bases into the user config.json (missing keys only).",
+    ),
+    show_debug: bool = typer.Option(
+        False,
+        "--debug",
+        help="Print which vendor CLIs are on PATH.",
+    ),
+) -> None:
+    """Probe local Jira/GitHub/GitLab CLIs and git remote; optionally persist."""
+    cwd = Path.cwd()
+    prefs = load_layered_preferences(cwd)
+    discovered = detect_links(cwd, detection=prefs.detection)
+    if show_debug:
+        typer.echo(dump_detection_debug())
+    merged = fill_link_gaps(prefs, discovered)
+    typer.echo(json.dumps(preferences_to_object(merged), indent=2))
+    if write:
+        path = user_preferences_path()
+        merge_missing_links_into_user_file(discovered=discovered, user_path=path)
+        typer.echo(f"wrote missing keys to {path}", err=True)
+
+
+def main() -> None:
+    """Console script entry point."""
+    app(args=prepare_argv(sys.argv[1:]), prog_name="git-elog")
+
+
+if __name__ == "__main__":
+    main()