esys-gitlog 0.1.0__tar.gz

esys_gitlog-0.1.0/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 esys-gitlog-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

esys_gitlog-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: esys-gitlog
+Version: 0.1.0
+Summary: Python implementation of git elog
+Author: Project maintainers
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Provides-Extra: standalone
+Requires-Dist: pyinstaller>=6.0; extra == "standalone"
+Dynamic: license-file
+
+# esys-gitlog
+
+Python implementation of `git elog`. The distribution name is `esys-gitlog`. The import package is `esys_gitlog`. The installed command is `git-elog`, so Git can run `git elog`.
+
+The shared contract lives in `esys-gitlog-spec`. This repository carries that contract in Python. It does not define a second one.
+
+## Smoke
+
+```bash
+pip install .
+git elog --help
+git elog --json
+```
+
+`--json` writes one QA report document to stdout. The first skeleton returns an empty `commits` array.
+
+## Release / publish
+
+Tag-driven CI publishes to GitLab Package Registry, TestPyPI, then PyPI (Deckicorn-style ADR-0009 flow). See [docs/release-pipeline.md](docs/release-pipeline.md).
+
+```bash
+python scripts/publish_release.py --dry-run --bump patch
+python scripts/build_package.py
+python scripts/smoke_install_package.py --dist dist --expected-version 0.1.0
+```
+
+## Preferences and profiles
+
+Layered tool preferences (user → `.tools/esys/esys-gitlog/` → `.tools_local/…`)
+and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.
+
+```bash
+git-elog --preferences path.json   # preference overlay
+git-elog --profile acme            # built-in or profiles/acme.json
+git-elog --config path/profile.json  # one-off profile file
+git-elog preferences detect        # probe jira/gh/glab/git remote; write missing user keys
+```
+
+## Standalone binary (optional)
+
+The primary install remains the wheel + `git-elog` console script. For a
+frozen one-file binary (for example Cursor `esysGitlog.executablePath` without
+a Python env on PATH):
+
+```bash
+python scripts/build_standalone.py
+```
+
+Output: `dist/git-elog.exe` (Windows) or `dist/git-elog` (Linux/macOS). Build on
+the OS you need — this does not cross-compile.
+
+- [Architecture](docs/architecture/overview.md)
+- [ADRs](docs/adr/INDEX.md)
+- [ASRs](docs/asr/INDEX.md)
+- [Implementation plan](plans/implementation.md)

esys_gitlog-0.1.0/README.md

@@ -0,0 +1,55 @@
+# esys-gitlog
+
+Python implementation of `git elog`. The distribution name is `esys-gitlog`. The import package is `esys_gitlog`. The installed command is `git-elog`, so Git can run `git elog`.
+
+The shared contract lives in `esys-gitlog-spec`. This repository carries that contract in Python. It does not define a second one.
+
+## Smoke
+
+```bash
+pip install .
+git elog --help
+git elog --json
+```
+
+`--json` writes one QA report document to stdout. The first skeleton returns an empty `commits` array.
+
+## Release / publish
+
+Tag-driven CI publishes to GitLab Package Registry, TestPyPI, then PyPI (Deckicorn-style ADR-0009 flow). See [docs/release-pipeline.md](docs/release-pipeline.md).
+
+```bash
+python scripts/publish_release.py --dry-run --bump patch
+python scripts/build_package.py
+python scripts/smoke_install_package.py --dist dist --expected-version 0.1.0
+```
+
+## Preferences and profiles
+
+Layered tool preferences (user → `.tools/esys/esys-gitlog/` → `.tools_local/…`)
+and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.
+
+```bash
+git-elog --preferences path.json   # preference overlay
+git-elog --profile acme            # built-in or profiles/acme.json
+git-elog --config path/profile.json  # one-off profile file
+git-elog preferences detect        # probe jira/gh/glab/git remote; write missing user keys
+```
+
+## Standalone binary (optional)
+
+The primary install remains the wheel + `git-elog` console script. For a
+frozen one-file binary (for example Cursor `esysGitlog.executablePath` without
+a Python env on PATH):
+
+```bash
+python scripts/build_standalone.py
+```
+
+Output: `dist/git-elog.exe` (Windows) or `dist/git-elog` (Linux/macOS). Build on
+the OS you need — this does not cross-compile.
+
+- [Architecture](docs/architecture/overview.md)
+- [ADRs](docs/adr/INDEX.md)
+- [ASRs](docs/asr/INDEX.md)
+- [Implementation plan](plans/implementation.md)

esys_gitlog-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esys-gitlog"
+version = "0.1.0"
+description = "Python implementation of git elog"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Project maintainers" }]
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.8",
+  "build>=1.0",
+  "twine>=5.0",
+  "pre-commit>=3.0",
+]
+standalone = [
+  "pyinstaller>=6.0",
+]
+
+[project.scripts]
+git-elog = "esys_gitlog.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]
+addopts = [
+  "--cov=esys_gitlog",
+  "--cov-report=term-missing",
+  "--cov-fail-under=95.01",
+]
+
+[tool.coverage.run]
+source = ["esys_gitlog"]
+branch = false
+omit = ["*/esys_gitlog/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

esys_gitlog-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esys_gitlog-0.1.0/src/esys_gitlog/__init__.py

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

esys_gitlog-0.1.0/src/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-0.1.0/src/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",
+]