esys-gitlog 0.1.0__tar.gz → 0.3.0__tar.gz

esys_gitlog-0.3.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: esys-gitlog
+Version: 0.3.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`. Installed commands: `git-elog` (so Git can run `git elog`) and the shorter alias `elog`. Prefer `elog --help` — `git elog --help` is handled by Git's own help path, not the Typer CLI.
+
+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 .
+elog --help
+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
+elog --preferences path.json   # preference overlay
+elog --profile acme            # built-in or profiles/acme.json
+elog --config path/profile.json  # one-off profile file
+elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
+elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
+elog preferences set-link jira-id 'https://host/browse/{id}'
+elog preferences clear-link jira-id
+elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
+elog preferences set-tool acli /usr/local/bin/acli
+```
+
+Jira browse bases come from local **jira-cli** config and/or **Atlassian acli**
+(`acli jira config get site`), never from per-commit HTTP (SADR-0010). Detection
+only fills unset user keys unless you use `set-link`. Absolute paths live under
+`detection.jiraExecutable` / `detection.acliExecutable` when the tools are not
+on `PATH`.
+
+### Live Jira fixture (SCRUM)
+
+The free site [libesys.atlassian.net](https://libesys.atlassian.net/browse/SCRUM-1)
+uses project key **`SCRUM`** only (do not invent other project keys).
+
+1. Configure acli or jira-cli against that site (optional absolute paths via
+   `elog preferences set-tool`).
+2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):
+
+```bash
+python scripts/seed_jira_live_fixture.py --project SCRUM --count 10
+```
+
+3. Commit `tests/integration/jira_live.pin.json`.
+4. Materialize a durable Git repo for the VS Code extension / manual checks:
+
+```bash
+python scripts/materialize_jira_live_repo.py
+```
+
+   Output: `tests/integration/jira_live_repo/` (gitignored except a placeholder
+   README). Open that folder, store the browse template, refresh the commit browser.
+5. Run the live test locally or enable GitLab variable `ESYS_GITLOG_JIRA_LIVE=1`
+   for job `test:jira-live`:
+
+```bash
+ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov
+```
+
+Default `pytest` excludes `@pytest.mark.jira_live` so coverage stays offline.
+
+## Standalone binary (optional)
+
+The primary install remains the wheel + `git-elog` / `elog` console scripts. 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.3.0/README.md

@@ -0,0 +1,97 @@
+# esys-gitlog
+
+Python implementation of `git elog`. The distribution name is `esys-gitlog`. The import package is `esys_gitlog`. Installed commands: `git-elog` (so Git can run `git elog`) and the shorter alias `elog`. Prefer `elog --help` — `git elog --help` is handled by Git's own help path, not the Typer CLI.
+
+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 .
+elog --help
+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
+elog --preferences path.json   # preference overlay
+elog --profile acme            # built-in or profiles/acme.json
+elog --config path/profile.json  # one-off profile file
+elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
+elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
+elog preferences set-link jira-id 'https://host/browse/{id}'
+elog preferences clear-link jira-id
+elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
+elog preferences set-tool acli /usr/local/bin/acli
+```
+
+Jira browse bases come from local **jira-cli** config and/or **Atlassian acli**
+(`acli jira config get site`), never from per-commit HTTP (SADR-0010). Detection
+only fills unset user keys unless you use `set-link`. Absolute paths live under
+`detection.jiraExecutable` / `detection.acliExecutable` when the tools are not
+on `PATH`.
+
+### Live Jira fixture (SCRUM)
+
+The free site [libesys.atlassian.net](https://libesys.atlassian.net/browse/SCRUM-1)
+uses project key **`SCRUM`** only (do not invent other project keys).
+
+1. Configure acli or jira-cli against that site (optional absolute paths via
+   `elog preferences set-tool`).
+2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):
+
+```bash
+python scripts/seed_jira_live_fixture.py --project SCRUM --count 10
+```
+
+3. Commit `tests/integration/jira_live.pin.json`.
+4. Materialize a durable Git repo for the VS Code extension / manual checks:
+
+```bash
+python scripts/materialize_jira_live_repo.py
+```
+
+   Output: `tests/integration/jira_live_repo/` (gitignored except a placeholder
+   README). Open that folder, store the browse template, refresh the commit browser.
+5. Run the live test locally or enable GitLab variable `ESYS_GITLOG_JIRA_LIVE=1`
+   for job `test:jira-live`:
+
+```bash
+ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov
+```
+
+Default `pytest` excludes `@pytest.mark.jira_live` so coverage stays offline.
+
+## Standalone binary (optional)
+
+The primary install remains the wheel + `git-elog` / `elog` console scripts. 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 → esys_gitlog-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "esys-gitlog"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python implementation of git elog"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,7 @@ standalone = [
 
 [project.scripts]
 git-elog = "esys_gitlog.cli:main"
+elog = "esys_gitlog.cli:main"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
@@ -40,7 +41,12 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = [".", "src"]
+markers = [
+  "jira_live: live Jira fixture (ESYS_GITLOG_JIRA_LIVE=1 + seeded pin)",
+]
 addopts = [
+  "-m",
+  "not jira_live",
   "--cov=esys_gitlog",
   "--cov-report=term-missing",
   "--cov-fail-under=95.01",

{esys_gitlog-0.1.0 → esys_gitlog-0.3.0}/src/esys_gitlog/__init__.py

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

{esys_gitlog-0.1.0 → esys_gitlog-0.3.0}/src/esys_gitlog/cli.py

@@ -1,4 +1,4 @@
-"""Thin Typer command boundary for ``git-elog`` / ``git elog``."""
+"""Thin Typer command boundary for ``git-elog`` / ``elog`` / ``git elog``."""
 
 from __future__ import annotations
 
@@ -11,13 +11,17 @@ 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.detection import detect_report, dump_detection_debug
 from esys_gitlog.git_adapter import GitError, filter_git_log_args
 from esys_gitlog.preferences import (
+    LinkPreferences,
+    clear_user_ref_link,
     fill_link_gaps,
     load_layered_preferences,
     merge_missing_links_into_user_file,
     preferences_to_object,
+    set_user_detection_executables,
+    set_user_ref_link,
 )
 from esys_gitlog.tool_paths import user_preferences_path
 
@@ -299,13 +303,40 @@ def preferences_detect(
         "--debug",
         help="Print which vendor CLIs are on PATH.",
     ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print a machine-readable detection report (candidates, sources, tools).",
+    ),
+    probe_auth: bool = typer.Option(
+        False,
+        "--probe-auth",
+        help="Optionally probe jira-cli/acli auth (setup only; may touch the network).",
+    ),
 ) -> None:
-    """Probe local Jira/GitHub/GitLab CLIs and git remote; optionally persist."""
+    """Probe local Jira (jira-cli/acli), 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())
+    report = detect_report(
+        cwd,
+        detection=prefs.detection,
+        probe_auth=probe_auth,
+    )
+    discovered = LinkPreferences(
+        ref_links=dict(report.get("refLinks") or {}),
+        commit_link=report.get("commitLink"),
+    )
+    if show_debug and not as_json:
+        typer.echo(dump_detection_debug(prefs.detection))
+    if as_json:
+        if write:
+            path = user_preferences_path()
+            merge_missing_links_into_user_file(discovered=discovered, user_path=path)
+            report["wrote"] = str(path)
+        else:
+            report["wrote"] = None
+        typer.echo(json.dumps(report, indent=2))
+        return
     merged = fill_link_gaps(prefs, discovered)
     typer.echo(json.dumps(preferences_to_object(merged), indent=2))
     if write:
@@ -314,9 +345,72 @@ def preferences_detect(
         typer.echo(f"wrote missing keys to {path}", err=True)
 
 
+@preferences_app.command("set-link")
+def preferences_set_link(
+    family: str = typer.Argument(help="Identifier family, e.g. jira-id"),
+    template: str = typer.Argument(
+        help="URL template with {id}, e.g. https://host/browse/{id}",
+    ),
+) -> None:
+    """Create or overwrite a user-layer ref link template (explicit settings edit)."""
+    path = user_preferences_path()
+    set_user_ref_link(family, template, user_path=path)
+    typer.echo(json.dumps({"family": family, "template": template, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("clear-link")
+def preferences_clear_link(
+    family: str = typer.Argument(help="Identifier family, e.g. jira-id"),
+) -> None:
+    """Remove a user-layer ref link template."""
+    path = user_preferences_path()
+    clear_user_ref_link(family, user_path=path)
+    typer.echo(json.dumps({"family": family, "cleared": True, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("set-tool")
+def preferences_set_tool(
+    tool: str = typer.Argument(help="Tool name: jira or acli"),
+    executable: str = typer.Argument(help="Absolute path to the executable"),
+) -> None:
+    """Store an absolute path for jira-cli or acli (when not on PATH)."""
+    name = tool.strip().lower()
+    path = user_preferences_path()
+    if name in ("jira", "jira-cli"):
+        set_user_detection_executables(jira_executable=executable, user_path=path)
+    elif name == "acli":
+        set_user_detection_executables(acli_executable=executable, user_path=path)
+    else:
+        typer.echo("tool must be 'jira' or 'acli'", err=True)
+        raise typer.Exit(code=2)
+    typer.echo(json.dumps({"tool": name, "executable": executable, "path": str(path)}, indent=2))
+
+
+@preferences_app.command("clear-tool")
+def preferences_clear_tool(
+    tool: str = typer.Argument(help="Tool name: jira or acli"),
+) -> None:
+    """Remove a configured jira-cli or acli path (fall back to PATH)."""
+    name = tool.strip().lower()
+    path = user_preferences_path()
+    if name in ("jira", "jira-cli"):
+        set_user_detection_executables(clear_jira=True, user_path=path)
+    elif name == "acli":
+        set_user_detection_executables(clear_acli=True, user_path=path)
+    else:
+        typer.echo("tool must be 'jira' or 'acli'", err=True)
+        raise typer.Exit(code=2)
+    typer.echo(json.dumps({"tool": name, "cleared": True, "path": str(path)}, indent=2))
+
+
 def main() -> None:
     """Console script entry point."""
-    app(args=prepare_argv(sys.argv[1:]), prog_name="git-elog")
+    # Normalize Windows separators so ``Path.name`` works when run under POSIX.
+    invoked = Path(sys.argv[0].replace("\\", "/")).name
+    if invoked.lower().endswith(".exe"):
+        invoked = invoked[:-4]
+    prog_name = invoked or "git-elog"
+    app(args=prepare_argv(sys.argv[1:]), prog_name=prog_name)
 
 
 if __name__ == "__main__":

{esys_gitlog-0.1.0 → esys_gitlog-0.3.0}/src/esys_gitlog/config.py

@@ -49,9 +49,9 @@ class ProfileRules:
 
     name: str
     conventional: bool = True
-    conventional_locations: tuple[str, ...] = ("title",)
+    conventional_locations: tuple[str, ...] = ("title", "trailer")
     references: bool = True
-    reference_locations: tuple[str, ...] = ("refs",)
+    reference_locations: tuple[str, ...] = ("prefix", "suffix", "refs")
     identifier_family: str = "jira-id"
     signed_off_by: bool = True
     types: tuple[str, ...] = DEFAULT_TYPES
@@ -70,7 +70,7 @@ class AnalysisConfig:
     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
+    ref_id_width: int = 14
     type_width: int = 10
     show_author: bool = False
     show_date: bool = False
@@ -87,6 +87,7 @@ def _trailer_profile() -> ProfileRules:
     return ProfileRules(
         name="trailer",
         conventional_locations=("trailer",),
+        reference_locations=("refs",),
     )
 
 
@@ -97,8 +98,14 @@ KNOWN_PROFILES: dict[str, ProfileRules] = {
 
 
 def _profile_from_object(data: dict[str, Any], *, name: str = "custom") -> ProfileRules:
-    conventional_locations = data.get("conventionalLocations", ["title"])
-    reference_locations = data.get("referenceLocations", ["refs"])
+    conventional_locations = data.get(
+        "conventionalLocations",
+        ["title", "trailer"],
+    )
+    reference_locations = data.get(
+        "referenceLocations",
+        ["prefix", "suffix", "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.