lgit-cli 3.7.0__py3-none-any.whl

lgit/templates.py

@@ -0,0 +1,385 @@
+"""Prompt template loading and rendering helpers."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment
+
+from .errors import ConfigError
+
+USER_SEPARATOR_MARKER = "======USER======="
+PROMPT_CATEGORIES = (
+    "analysis",
+    "summary",
+    "changelog",
+    "map",
+    "reduce",
+    "fast",
+    "compose-intent",
+    "compose-bind",
+)
+
+_ENV = Environment(autoescape=False, keep_trailing_newline=True)
+
+
+@dataclass(frozen=True, slots=True)
+class PromptParts:
+    """Rendered prompt split into static system text and rendered user text."""
+
+    system: str
+    user: str
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisParams:
+    """Parameters for rendering the analysis prompt."""
+
+    variant: str = "default"
+    stat: str = ""
+    diff: str = ""
+    scope_candidates: str = ""
+    recent_commits: str | None = None
+    common_scopes: str | None = None
+    types_description: str | None = None
+    project_context: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MapFile:
+    """One file diff passed to the map prompt."""
+
+    path: str
+    diff: str
+
+
+@dataclass(frozen=True, slots=True)
+class ComposeIntentPromptParams:
+    """Parameters for rendering the compose-intent prompt."""
+
+    variant: str = "default"
+    max_commits: int = 1
+    stat: str = ""
+    snapshot_summary: str = ""
+    planning_targets: str = ""
+    planning_notes: str = ""
+    split_bias: str = ""
+    types_description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ComposeBindPromptParams:
+    """Parameters for rendering the compose-bind prompt."""
+
+    variant: str = "default"
+    groups: str = ""
+    ambiguous_files: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class FastPromptParams:
+    """Parameters for rendering the fast-mode prompt."""
+
+    variant: str = "default"
+    stat: str = ""
+    diff: str = ""
+    scope_candidates: str = ""
+    user_context: str | None = None
+    types_description: str | None = None
+
+
+def get_user_prompts_dir() -> Path | None:
+    """Return the user prompt override directory, if a home directory is known."""
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE")
+    if not home:
+        return None
+    return Path(home).joinpath(".llm-git", "prompts")
+
+
+def ensure_prompts_dir() -> Path | None:
+    """Create the user prompt directory and unpack package prompt files."""
+    user_prompts_dir = get_user_prompts_dir()
+    if user_prompts_dir is None:
+        return None
+    try:
+        user_prompts_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ConfigError(f"Failed to create prompts directory {user_prompts_dir}: {exc}") from exc
+
+    for relative_path, content in _iter_package_prompt_files():
+        destination = user_prompts_dir.joinpath(relative_path)
+        try:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            if not destination.exists():
+                destination.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            raise ConfigError(f"Failed to write prompt file {destination}: {exc}") from exc
+    return user_prompts_dir
+
+
+def split_prompt_template(template_content: str) -> tuple[str | None, str]:
+    """Split a prompt into optional system text and templated user text."""
+    separator = _find_user_separator(template_content)
+    if separator is None:
+        return None, template_content
+    system_end, user_start = separator
+    return template_content[:system_end], template_content[user_start:]
+
+
+def render_prompt_parts(
+    template_name: str,
+    template_content: str,
+    context: Mapping[str, Any],
+) -> PromptParts:
+    """Render one prompt while enforcing a static system section."""
+    system_template, user_template = split_prompt_template(template_content)
+    system = ""
+    if system_template is not None:
+        _ensure_static_system_prompt(system_template, template_name)
+        system = system_template.strip()
+    try:
+        rendered_user = _ENV.from_string(user_template).render(**context)
+    except Exception as exc:  # jinja2 has several template-specific subclasses.
+        raise ConfigError(f"Failed to render {template_name} prompt template: {exc}") from exc
+    return PromptParts(system=system, user=rendered_user.strip())
+
+
+def render_analysis_prompt(params: AnalysisParams | None = None, **kwargs: Any) -> PromptParts:
+    """Render the analysis prompt variant."""
+    p = params if params is not None else AnalysisParams(**kwargs)
+    template_content = load_template_file("analysis", p.variant)
+    context = {
+        "stat": p.stat,
+        "diff": p.diff,
+        "scope_candidates": p.scope_candidates,
+        "recent_commits": p.recent_commits,
+        "common_scopes": p.common_scopes,
+        "types_description": p.types_description,
+        "project_context": p.project_context,
+    }
+    return render_prompt_parts(f"analysis/{p.variant}.md", template_content, context)
+
+
+def render_summary_prompt(
+    variant: str,
+    commit_type: str,
+    scope: str,
+    chars: str,
+    details: str,
+    stat: str,
+    user_context: str | None = None,
+) -> PromptParts:
+    """Render the summary prompt variant."""
+    template_content = load_template_file("summary", variant)
+    context = {
+        "commit_type": commit_type,
+        "scope": scope,
+        "chars": chars,
+        "details": details,
+        "stat": stat,
+        "user_context": user_context,
+    }
+    return render_prompt_parts(f"summary/{variant}.md", template_content, context)
+
+
+def render_changelog_prompt(
+    variant: str,
+    changelog_path: str,
+    is_package_changelog: bool,
+    stat: str,
+    diff: str,
+    existing_entries: str | None = None,
+) -> PromptParts:
+    """Render the changelog prompt variant."""
+    template_content = load_template_file("changelog", variant)
+    context = {
+        "changelog_path": changelog_path,
+        "is_package_changelog": is_package_changelog,
+        "stat": stat,
+        "diff": diff,
+        "existing_entries": existing_entries,
+    }
+    return render_prompt_parts(f"changelog/{variant}.md", template_content, context)
+
+
+def render_map_prompt(
+    variant: str,
+    files: Iterable[MapFile | Mapping[str, str]],
+    context_header: str = "",
+) -> PromptParts:
+    """Render the map prompt for batched file-observation extraction."""
+    template_content = load_template_file("map", variant)
+    context = {
+        "files": [_mapping_for_file(file) for file in files],
+        "context_header": context_header,
+    }
+    return render_prompt_parts(f"map/{variant}.md", template_content, context)
+
+
+def render_reduce_prompt(
+    variant: str,
+    observations: str,
+    stat: str,
+    scope_candidates: str,
+    types_description: str | None = None,
+) -> PromptParts:
+    """Render the reduce prompt for synthesizing map observations."""
+    template_content = load_template_file("reduce", variant)
+    context = {
+        "observations": observations,
+        "stat": stat,
+        "scope_candidates": scope_candidates,
+        "types_description": types_description,
+    }
+    return render_prompt_parts(f"reduce/{variant}.md", template_content, context)
+
+
+def render_fast_prompt(params: FastPromptParams | None = None, **kwargs: Any) -> PromptParts:
+    """Render the fast-mode single-call prompt variant."""
+    p = params if params is not None else FastPromptParams(**kwargs)
+    template_content = load_template_file("fast", p.variant)
+    context = {
+        "stat": p.stat,
+        "diff": p.diff,
+        "scope_candidates": p.scope_candidates,
+        "user_context": p.user_context,
+        "types_description": p.types_description,
+    }
+    return render_prompt_parts(f"fast/{p.variant}.md", template_content, context)
+
+
+def render_compose_intent_prompt(
+    params: ComposeIntentPromptParams | None = None,
+    **kwargs: Any,
+) -> PromptParts:
+    """Render the compose-intent planning prompt variant."""
+    p = params if params is not None else ComposeIntentPromptParams(**kwargs)
+    template_content = load_template_file("compose-intent", p.variant)
+    context = {
+        "max_commits": p.max_commits,
+        "stat": p.stat,
+        "snapshot_summary": p.snapshot_summary,
+        "planning_targets": p.planning_targets,
+        "planning_notes": p.planning_notes,
+        "split_bias": p.split_bias,
+        "types_description": p.types_description,
+    }
+    return render_prompt_parts(f"compose-intent/{p.variant}.md", template_content, context)
+
+
+def render_compose_bind_prompt(
+    params: ComposeBindPromptParams | None = None,
+    **kwargs: Any,
+) -> PromptParts:
+    """Render the compose-bind hunk-assignment prompt variant."""
+    p = params if params is not None else ComposeBindPromptParams(**kwargs)
+    template_content = load_template_file("compose-bind", p.variant)
+    context = {"groups": p.groups, "ambiguous_files": p.ambiguous_files}
+    return render_prompt_parts(f"compose-bind/{p.variant}.md", template_content, context)
+
+
+def load_template_file(category: str, variant: str) -> str:
+    """Load a user override prompt first, then the packaged prompt resource."""
+    if category not in PROMPT_CATEGORIES:
+        raise ConfigError(f"Unknown prompt category {category!r}")
+    _validate_variant(variant)
+    if prompts_dir := get_user_prompts_dir():
+        user_template = prompts_dir.joinpath(category, f"{variant}.md")
+        if user_template.exists():
+            try:
+                return user_template.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise ConfigError(f"Failed to read template file {user_template}: {exc}") from exc
+
+    resource = resources.files("lgit.resources").joinpath("prompts", category, f"{variant}.md")
+    if resource.is_file():
+        try:
+            return resource.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ConfigError(f"Failed to read package template {category}/{variant}.md: {exc}") from exc
+    raise ConfigError(
+        f"Template variant {variant!r} in category {category!r} not found as user override or package resource"
+    )
+
+
+def _find_user_separator(content: str) -> tuple[int, int] | None:
+    marker_pos = content.find(USER_SEPARATOR_MARKER)
+    if marker_pos == -1:
+        return None
+    if marker_pos >= 2 and content[marker_pos - 2 : marker_pos] == "\r\n":
+        system_end = marker_pos - 2
+    elif marker_pos >= 1 and content[marker_pos - 1 : marker_pos] == "\n":
+        system_end = marker_pos - 1
+    else:
+        system_end = marker_pos
+    after_marker = marker_pos + len(USER_SEPARATOR_MARKER)
+    if content[after_marker : after_marker + 2] == "\r\n":
+        user_start = after_marker + 2
+    elif content[after_marker : after_marker + 1] == "\n":
+        user_start = after_marker + 1
+    else:
+        user_start = after_marker
+    return system_end, user_start
+
+
+def _ensure_static_system_prompt(system_template: str, template_name: str) -> None:
+    if "{{" in system_template or "{%" in system_template or "{#" in system_template:
+        raise ConfigError(
+            f"Template {template_name!r} contains dynamic tags in system section. "
+            f"Move interpolated content below {USER_SEPARATOR_MARKER}."
+        )
+
+
+def _validate_variant(variant: str) -> None:
+    if not variant or "/" in variant or "\\" in variant or variant in {".", ".."}:
+        raise ConfigError(f"Invalid prompt variant {variant!r}")
+
+
+def _mapping_for_file(file: MapFile | Mapping[str, str]) -> Mapping[str, str]:
+    if isinstance(file, MapFile):
+        return {"path": file.path, "diff": file.diff}
+    return file
+
+
+def _iter_package_prompt_files() -> Iterable[tuple[Path, str]]:
+    prompts_root = resources.files("lgit.resources").joinpath("prompts")
+    yield from _walk_prompt_resources(prompts_root, Path())
+
+
+def _walk_prompt_resources(root: Any, prefix: Path) -> Iterable[tuple[Path, str]]:
+    for child in sorted(root.iterdir(), key=lambda item: item.name):
+        child_prefix = prefix / child.name
+        if child.is_dir():
+            yield from _walk_prompt_resources(child, child_prefix)
+        elif child.name.endswith(".md"):
+            yield child_prefix, child.read_text(encoding="utf-8")
+
+
+__all__ = [
+    "USER_SEPARATOR_MARKER",
+    "PROMPT_CATEGORIES",
+    "PromptParts",
+    "AnalysisParams",
+    "MapFile",
+    "ComposeIntentPromptParams",
+    "ComposeBindPromptParams",
+    "FastPromptParams",
+    "get_user_prompts_dir",
+    "ensure_prompts_dir",
+    "split_prompt_template",
+    "render_prompt_parts",
+    "load_template_file",
+    "render_analysis_prompt",
+    "render_summary_prompt",
+    "render_changelog_prompt",
+    "render_map_prompt",
+    "render_reduce_prompt",
+    "render_fast_prompt",
+    "render_compose_intent_prompt",
+    "render_compose_bind_prompt",
+]

lgit/testing/__init__.py

@@ -0,0 +1,62 @@
+"""Fixture-based testing harness for lgit."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .compare import CompareResult, compare_analysis
+from .fixture import (
+    FIXTURES_DIR,
+    Fixture,
+    FixtureContext,
+    FixtureEntry,
+    FixtureInput,
+    FixtureMeta,
+    Golden,
+    Manifest,
+    add_fixture,
+    discover_fixtures,
+    load_fixtures,
+)
+from .report import generate_html_report
+from .runner import RunResult, TestRunner, TestSummary, run_test_mode
+
+
+def fixtures_dir() -> Path:
+    """Return the default fixtures directory path."""
+
+    return Path(FIXTURES_DIR)
+
+
+def list_fixtures(path: str | Path | None = None) -> list[str]:
+    """List available fixtures from the manifest when present, else discover directories."""
+
+    root = fixtures_dir() if path is None else Path(path)
+    manifest = Manifest.load(root)
+    if manifest.fixtures:
+        return sorted(manifest.fixtures)
+    return discover_fixtures(root)
+
+
+__all__ = [
+    "CompareResult",
+    "FIXTURES_DIR",
+    "Fixture",
+    "FixtureContext",
+    "FixtureEntry",
+    "FixtureInput",
+    "FixtureMeta",
+    "Golden",
+    "Manifest",
+    "RunResult",
+    "TestRunner",
+    "TestSummary",
+    "add_fixture",
+    "compare_analysis",
+    "discover_fixtures",
+    "fixtures_dir",
+    "generate_html_report",
+    "list_fixtures",
+    "load_fixtures",
+    "run_test_mode",
+]

lgit/testing/compare.py

@@ -0,0 +1,57 @@
+"""Comparison logic for fixture golden analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lgit.models import ConventionalAnalysis
+
+
+@dataclass(frozen=True, slots=True)
+class CompareResult:
+    """Result of comparing actual analysis to a golden analysis."""
+
+    type_match: bool
+    scope_match: bool
+    scope_diff: str | None
+    golden_detail_count: int
+    actual_detail_count: int
+    passed: bool
+    summary: str
+
+
+def compare_analysis(golden: ConventionalAnalysis, actual: ConventionalAnalysis) -> CompareResult:
+    """Compare two analyses using Rust harness-compatible pass rules."""
+
+    type_match = golden.commit_type == actual.commit_type
+    scope_match = golden.scope == actual.scope
+    scope_diff = None if scope_match else f"{_scope_text(golden)} -> {_scope_text(actual)}"
+    golden_detail_count = len(golden.details)
+    actual_detail_count = len(actual.details)
+
+    passed = type_match
+    if passed and scope_match:
+        summary = (
+            f"PASS {actual.commit_type} | {_scope_text(actual, none='(no scope)')} | {actual_detail_count} details"
+        )
+    elif passed:
+        summary = f"WARN {actual.commit_type} | scope: {scope_diff} | {actual_detail_count} details"
+    else:
+        summary = f"FAIL type: {golden.commit_type} -> {actual.commit_type} | {actual_detail_count} details"
+
+    return CompareResult(
+        type_match=type_match,
+        scope_match=scope_match,
+        scope_diff=scope_diff,
+        golden_detail_count=golden_detail_count,
+        actual_detail_count=actual_detail_count,
+        passed=passed,
+        summary=summary,
+    )
+
+
+def _scope_text(analysis: ConventionalAnalysis, *, none: str = "null") -> str:
+    return none if analysis.scope is None else str(analysis.scope)
+
+
+__all__ = ["CompareResult", "compare_analysis"]