git2xml 0.1.0__py3-none-any.whl

git2xml/__init__.py

@@ -0,0 +1,43 @@
+"""git2xml - structured XML briefs of git commits and pull requests for LLMs.
+
+Public API:
+    generate_commit_brief / generate_pr_brief             - async (native interface)
+    generate_commit_brief_sync / generate_pr_brief_sync   - sync convenience wrappers
+    Git2xmlConfig                                         - typed, validated config
+    Git2xmlError (+ subclasses)                           - error hierarchy to catch
+
+Everything else (GitScanner, the rendering helpers, ChangedFile/ScanResult) is an
+internal implementation detail and may change without notice.
+"""
+
+__version__ = "0.1.0"
+
+from .api import (
+    generate_commit_brief,
+    generate_commit_brief_sync,
+    generate_pr_brief,
+    generate_pr_brief_sync,
+)
+from .models import (
+    Git2xmlConfig,
+    Git2xmlError,
+    GitCommandError,
+    GitNotInstalledError,
+    NotAGitRepositoryError,
+)
+
+__all__ = [
+    # async API
+    "generate_commit_brief",
+    "generate_pr_brief",
+    # sync API
+    "generate_commit_brief_sync",
+    "generate_pr_brief_sync",
+    # config + errors
+    "Git2xmlConfig",
+    "Git2xmlError",
+    "GitNotInstalledError",
+    "NotAGitRepositoryError",
+    "GitCommandError",
+    "__version__",
+]

git2xml/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m git2xml`` alongside the installed ``git2xml`` entry point."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

git2xml/api.py

@@ -0,0 +1,95 @@
+"""Public programmatic interface for git2xml.
+
+These functions are the stable, supported way to use git2xml from other Python
+code. Each takes a fully-typed, validated ``Git2xmlConfig`` and returns the
+generated brief as an XML string - no disk I/O. The async functions are the
+native interface (the engine is asyncio-based); the ``*_sync`` variants are
+convenience adapters for plain synchronous scripts.
+
+Anything not exported here - ``GitScanner``, the rendering helpers, the
+``ChangedFile`` / ``ScanResult`` dataclasses - is an internal implementation
+detail and may change without notice. The supported surface is exactly: these
+four functions, ``Git2xmlConfig``, and the ``Git2xmlError`` hierarchy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from typing import Any, Callable, Coroutine
+
+from .core import build_brief
+from .models import Git2xmlConfig
+
+__all__ = [
+    "generate_commit_brief",
+    "generate_pr_brief",
+    "generate_commit_brief_sync",
+    "generate_pr_brief_sync",
+]
+
+
+# --- Async API (native interface) -------------------------------------------
+
+
+async def generate_commit_brief(config: Git2xmlConfig) -> str:
+    """Generate a commit-mode brief and return it as an XML string.
+
+    Covers working-tree changes against HEAD (or staged changes when
+    ``config.staged`` is set). The mode is fixed by the function name:
+    ``config.command`` is coerced to ``"commit"``, so a config built for another
+    mode is adapted rather than rejected.
+    """
+    return await build_brief(replace(config, command="commit"))
+
+
+async def generate_pr_brief(config: Git2xmlConfig) -> str:
+    """Generate a pr-mode brief and return it as an XML string.
+
+    Covers the current branch's changes against ``config.base`` (a
+    ``base...HEAD`` diff) plus a structured commit log. ``config.command`` is
+    coerced to ``"pr"``.
+    """
+    return await build_brief(replace(config, command="pr"))
+
+
+# --- Sync wrappers (convenience adapters) -----------------------------------
+
+
+def generate_commit_brief_sync(config: Git2xmlConfig) -> str:
+    """Synchronous wrapper around :func:`generate_commit_brief`.
+
+    For plain (non-async) scripts. Raises ``RuntimeError`` if called from within
+    a running event loop - use the async function there instead.
+    """
+    return _run_sync(generate_commit_brief, config)
+
+
+def generate_pr_brief_sync(config: Git2xmlConfig) -> str:
+    """Synchronous wrapper around :func:`generate_pr_brief`. See its sync note."""
+    return _run_sync(generate_pr_brief, config)
+
+
+# --- internal ---------------------------------------------------------------
+
+
+def _run_sync(
+    async_fn: Callable[[Git2xmlConfig], Coroutine[Any, Any, str]],
+    config: Git2xmlConfig,
+) -> str:
+    """Drive an async API function to completion from sync code.
+
+    ``asyncio.run`` raises an opaque error if a loop is already running (Jupyter,
+    an async web handler, an agent runtime). We detect that case and fail with a
+    clear, actionable message instead - and we only build the coroutine on the
+    safe path, so there's no orphaned "coroutine was never awaited" warning.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop -> safe to start one.
+        return asyncio.run(async_fn(config))
+    raise RuntimeError(
+        "git2xml's synchronous API cannot run inside an existing event loop. "
+        "Call the async variant instead, e.g. `await generate_commit_brief(config)`."
+    )

git2xml/cli.py

@@ -0,0 +1,158 @@
+"""Command-line entry point: argv -> Git2xmlConfig -> save_brief.
+
+Thin adapter around the engine. Parses arguments, maps them onto a validated
+``Git2xmlConfig``, configures logging, and translates the typed error
+hierarchy into process exit codes - it contains no brief-building logic of its
+own. The ``git2xml`` console script and ``python -m git2xml`` both land in
+``main`` here.
+"""
+
+import argparse
+import asyncio
+import dataclasses
+import logging
+import sys
+
+from . import __version__
+from .constants import DIFF_SEMAPHORE_LIMIT, GIT_TIMEOUT, MAX_DIFF_SIZE, MAX_TEXT_FILE_SIZE
+from .core import save_brief
+from .models import Git2xmlCliConfig, Git2xmlError
+
+
+def _int(value: str) -> int:
+    """Parse an integer from argv. Bounds are enforced by Git2xmlConfig."""
+    try:
+        return int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"invalid integer value: '{value}'") from None
+
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> int:
+    """Console-script entry point: parse argv, run the brief, map errors to exit codes.
+
+    Parses command-line arguments, builds a validated ``Git2xmlCliConfig`` from
+    them, configures root logging (DEBUG under ``-v``, otherwise INFO), and runs
+    ``save_brief`` to generate and write the brief. Contains no brief-building
+    logic itself - that lives in the engine.
+
+    Side effects: configures logging on the root logger and terminates the
+    process by returning a status integer. Exit codes: 0 on success; 2 on an
+    argparse usage error (argparse's own exit); 1 on a known ``Git2xmlError``, a
+    user interrupt (Ctrl-C), or any unexpected exception (logged with a traceback
+    only under ``-v``).
+
+    Both the ``git2xml`` console script and ``python -m git2xml`` dispatch here.
+    """
+
+    parser = argparse.ArgumentParser(
+        prog="git2xml", description="Generate contextual XML briefs for Git Commits and PRs."
+    )
+    parser.add_argument("command", choices=["commit", "pr"], help="Type of brief to generate.")
+    parser.add_argument(
+        "--repo", default=".", help="Git repository root location (default: current directory)."
+    )
+    parser.add_argument(
+        "--output", help="Output file name. Defaults to commit_brief.xml or pr_brief.xml."
+    )
+    parser.add_argument("--base", default="main", help="Base branch for PR diffs (default: main).")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show detailed file-by-file and commit-by-commit processing.",
+    )
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        help="Only include staged files in commit mode (ignores unstaged/untracked).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--strict-xml",
+        action="store_true",
+        help="Enforce strict XML 1.0 compliance (escapes control chars and CDATA terminators).",
+    )
+    parser.add_argument(
+        "--no-untracked",
+        action="store_true",
+        help="Exclude untracked files from commit-mode output. No-op with --staged or in PR mode.",
+    )
+    parser.add_argument(
+        "--max-size",
+        type=_int,
+        default=MAX_TEXT_FILE_SIZE,
+        metavar="N",
+        help=f"Maximum file size in bytes before content is omitted (default: {MAX_TEXT_FILE_SIZE}).",
+    )
+    parser.add_argument(
+        "--max-diff-size",
+        type=_int,
+        default=MAX_DIFF_SIZE,
+        metavar="N",
+        help=f"Maximum diff size in bytes. Larger diffs are omitted with a reason (default: {MAX_DIFF_SIZE}; 0 = unlimited).",
+    )
+    parser.add_argument(
+        "--no-content",
+        action="store_true",
+        help="Omit <content> for all files; still emit <file> elements and <diff>. Produces a diff-only brief.",
+    )
+    parser.add_argument(
+        "--git-timeout",
+        type=_int,
+        default=GIT_TIMEOUT,
+        metavar="N",
+        help=f"Git command timeout (default: {GIT_TIMEOUT}).",
+    )
+    parser.add_argument(
+        "--diff-semaphore-limit",
+        type=_int,
+        default=DIFF_SEMAPHORE_LIMIT,
+        metavar="N",
+        help=f"Maximum number of concurrent diff fetch actions (default: {DIFF_SEMAPHORE_LIMIT}).",
+    )
+    parser.add_argument(
+        "--hide-repo-path",
+        action="store_true",
+        help='Emit only the repo directory name in the root <... repo=""> attribute instead of the absolute local path. Use when sharing briefs externally.',
+    )
+
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO, format="%(levelname)s: %(message)s"
+    )
+
+    # Filter out unexpected arguments or with None value
+    valid_fields = {f.name for f in dataclasses.fields(Git2xmlCliConfig)}
+    config_args = {k: v for k, v in vars(args).items() if k in valid_fields and v is not None}
+
+    # Catch missing required arguments safely
+    try:
+        config = Git2xmlCliConfig(**config_args)
+    except (TypeError, ValueError) as e:
+        logger.error("Invalid configuration: %s", e)
+        return 1
+
+    try:
+        asyncio.run(save_brief(config))
+    except Git2xmlError as e:
+        logger.error(e)
+        return 1
+    except KeyboardInterrupt:
+        logger.error("Operation cancelled by user.")
+        return 1
+    except Exception as exc:
+        if args.verbose:
+            logger.exception("Unexpected error: %s", exc)
+        else:
+            logger.error("Unexpected error: %s. Run with -v for details.", exc)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

git2xml/constants.py

@@ -0,0 +1,31 @@
+"""Default tuning values for size limits, timeouts, and diff concurrency.
+
+The defaults behind the matching ``Git2xmlConfig`` fields and CLI flags
+(``--max-size``, ``--git-timeout``, ``--diff-semaphore-limit``); every value
+here is overridable per run, so this is just the baseline, not a hard limit.
+"""
+
+# Max size of a file whose content is included in the XML. Larger files omit
+# their content and carry an explanatory reason instead.
+MAX_TEXT_FILE_SIZE = 5 * 1024 * 1024
+
+# Max size (bytes, UTF-8) of a single file's diff included in the XML. Larger diffs are
+# omitted with a reason.
+MAX_DIFF_SIZE = 1 * 1024 * 1024
+
+# Git command timeout, in seconds.
+GIT_TIMEOUT = 30
+
+# Max number of git diffs fetched concurrently.
+DIFF_SEMAPHORE_LIMIT = 20
+
+
+# Per-batch budget (UTF-16 code units) for ls-tree path args. Derived solely
+# from the Windows CreateProcessW cap (32,767 UTF-16 units), the binding
+# constraint across platforms — POSIX ARG_MAX is far higher, so this single
+# budget is safe everywhere. If a future change makes this per-platform (e.g.
+# a larger Unix budget to cut ls-tree spawns), update _chunk_paths' counting
+# unit to match: it counts UTF-16 units to align with this cap.
+_WINDOWS_CMDLINE_CAP = 32_767
+_CMDLINE_RESERVE = 2_048
+LS_TREE_PATH_BUDGET = _WINDOWS_CMDLINE_CAP - _CMDLINE_RESERVE  # ~30,700