gitglimpse 0.1.6__tar.gz → 0.1.8__tar.gz

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/.gitignore

@@ -213,3 +213,6 @@ __marimo__/
 # Build
 *.pyc
 .venv/
+
+.claude/
+.cursor/

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gitglimpse
-Version: 0.1.6
+Version: 0.1.8
 Summary: Extract structured context from your git history — PR descriptions, standups, weekly reports, and LLM-ready JSON.
-Project-URL: Homepage, https://github.com/dino/gitglimpse
-Project-URL: Repository, https://github.com/dino/gitglimpse
-Project-URL: Bug Tracker, https://github.com/dino/gitglimpse/issues
+Project-URL: Homepage, https://github.com/dino-zecevic/gitglimpse
+Project-URL: Repository, https://github.com/dino-zecevic/gitglimpse
+Project-URL: Bug Tracker, https://github.com/dino-zecevic/gitglimpse/issues
 Author: Dino
 License: MIT
 License-File: LICENSE
@@ -43,7 +43,6 @@ gitglimpse reads your git log, groups commits into logical tasks, filters noise,
 glimpse pr                          # PR summary from current branch
 glimpse standup                     # daily context from recent commits
 glimpse week                        # weekly summary grouped by day
-glimpse report                      # markdown report with file details
 glimpse init                        # generate Claude Code / Cursor slash commands
 glimpse config setup                # interactive configuration
 ```

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/PYPI_README.md

@@ -18,7 +18,6 @@ gitglimpse reads your git log, groups commits into logical tasks, filters noise,
 glimpse pr                          # PR summary from current branch
 glimpse standup                     # daily context from recent commits
 glimpse week                        # weekly summary grouped by day
-glimpse report                      # markdown report with file details
 glimpse init                        # generate Claude Code / Cursor slash commands
 glimpse config setup                # interactive configuration
 ```

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitglimpse"
-version = "0.1.6"
+version = "0.1.8"
 description = "Extract structured context from your git history — PR descriptions, standups, weekly reports, and LLM-ready JSON."
 readme = "PYPI_README.md"
 authors = [{ name = "Dino" }]
@@ -29,9 +29,9 @@ dependencies = [
 llm = ["httpx>=0.27"]
 
 [project.urls]
-Homepage = "https://github.com/dino/gitglimpse"
-Repository = "https://github.com/dino/gitglimpse"
-"Bug Tracker" = "https://github.com/dino/gitglimpse/issues"
+Homepage = "https://github.com/dino-zecevic/gitglimpse"
+Repository = "https://github.com/dino-zecevic/gitglimpse"
+"Bug Tracker" = "https://github.com/dino-zecevic/gitglimpse/issues"
 
 
 [project.scripts]

gitglimpse-0.1.8/src/gitglimpse/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.8"

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/cli.py

@@ -11,11 +11,24 @@ from rich.table import Table
 
 from gitglimpse import __version__
 from gitglimpse.config import Config, is_first_run, load_config
+from gitglimpse.formatters.changelog import (
+    format_changelog_json,
+    format_changelog_markdown,
+    format_changelog_template,
+)
 from gitglimpse.formatters.json import format_standup_json, format_week_json
 from gitglimpse.formatters.markdown import format_report
 from gitglimpse.formatters.pr import format_pr_json, format_pr_template
 from gitglimpse.formatters.template import format_standup, format_week_template
-from gitglimpse.git import GitError, get_branch_commits, get_commit_diff, get_commits, get_current_branch_name
+from gitglimpse.git import (
+    GitError,
+    get_branch_commits,
+    get_commit_diff,
+    get_commits,
+    get_commits_in_range,
+    get_current_branch_name,
+    get_latest_tag,
+)
 from gitglimpse.grouping import filter_noise_commits, group_commits_into_tasks, is_vague_message
 from gitglimpse.providers import get_provider
 
@@ -462,15 +475,18 @@ def standup(
 
     diff_snippets: dict[str, str] | None = None
     if ctx_mode in ("diffs", "both"):
+        # "diffs" shows every commit's diff; "both" only shows vague-message ones.
+        collect_all = ctx_mode == "diffs"
         if multi:
             diff_snippets = {}
-            for rp, _ in repo_pairs:
+            for rp, project_name in repo_pairs:
+                repo_tasks = [t for t in tasks if t.project == project_name]
                 diff_snippets.update(
-                    _collect_diff_snippets(tasks, rp, all_commits=True)
+                    _collect_diff_snippets(repo_tasks, rp, all_commits=collect_all)
                 )
         else:
             rp = repo_pairs[0][0] if repo_pairs[0][1] else (Path(repo) if repo else None)
-            diff_snippets = _collect_diff_snippets(tasks, rp, all_commits=True)
+            diff_snippets = _collect_diff_snippets(tasks, rp, all_commits=collect_all)
 
     if as_json:
         since_date = _parse_date_bound(effective, 1)
@@ -625,7 +641,20 @@ def week(
     start_date = _parse_date_bound(since, 7)
     end_date = _parse_date_bound(until, 0)  # 0 days ago = today
 
-    diff_snippets = _collect_diff_snippets(tasks, None, all_commits=True) if ctx_mode in ("diffs", "both") else None
+    diff_snippets: dict[str, str] | None = None
+    if ctx_mode in ("diffs", "both"):
+        # "diffs" shows every commit's diff; "both" only shows vague-message ones.
+        collect_all = ctx_mode == "diffs"
+        if multi:
+            diff_snippets = {}
+            for rp, project_name in repo_pairs:
+                repo_tasks = [t for t in tasks if t.project == project_name]
+                diff_snippets.update(
+                    _collect_diff_snippets(repo_tasks, rp, all_commits=collect_all)
+                )
+        else:
+            rp = repo_pairs[0][0] if repo_pairs[0][1] else (Path(repo) if repo else None)
+            diff_snippets = _collect_diff_snippets(tasks, rp, all_commits=collect_all)
 
     if as_json:
         json_str = format_week_json(tasks, start_date, end_date, diff_snippets=diff_snippets, context_mode=ctx_mode)
@@ -758,9 +787,10 @@ def pr(
     ticket = extract_ticket_id(current_branch)
 
     # Collect diff snippets if needed.
+    # "diffs" shows every commit's diff; "both" only shows vague-message ones.
     diff_snippets: dict[str, str] | None = None
     if ctx_mode in ("diffs", "both"):
-        diff_snippets = _collect_diff_snippets(tasks, repo_path, all_commits=True)
+        diff_snippets = _collect_diff_snippets(tasks, repo_path, all_commits=ctx_mode == "diffs")
 
     # JSON output.
     if as_json:
@@ -811,6 +841,159 @@ def pr(
             )
 
 
+# ---------------------------------------------------------------------------
+# changelog
+# ---------------------------------------------------------------------------
+
+@app.command()
+def changelog(
+        from_ref: Annotated[
+            Optional[str],
+            typer.Option("--from", help="Start ref (tag/commit). Defaults to the latest tag."),
+        ] = None,
+        to_ref: Annotated[
+            str,
+            typer.Option("--to", help="End ref (tag/commit/branch)."),
+        ] = "HEAD",
+        as_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+        no_llm: Annotated[bool, typer.Option("--no-llm", help="Skip LLM, use template formatter.")] = False,
+        local_llm: Annotated[bool, typer.Option("--local-llm", help="Use local LLM (Ollama).")] = False,
+        local_llm_url: Annotated[
+            Optional[str],
+            typer.Option("--local-llm-url", help="Override local LLM base URL."),
+        ] = None,
+        model: Annotated[
+            Optional[str],
+            typer.Option("--model", help="LLM model to use."),
+        ] = None,
+        repo: Annotated[
+            Optional[str],
+            typer.Option("--repo", help="Path to git repository. Defaults to current directory."),
+        ] = None,
+        context: Annotated[
+            Optional[str],
+            typer.Option("--context", help="LLM context: 'commits', 'diffs', or 'both'."),
+        ] = None,
+        filter_noise: Annotated[
+            Optional[bool],
+            typer.Option("--filter-noise/--no-filter-noise",
+                         help="Filter out noise commits (merges, formatting, lock files)."),
+        ] = None,
+        fmt: Annotated[
+            Optional[str],
+            typer.Option("--format", help="Output format: 'default' (Rich) or 'markdown'."),
+        ] = None,
+        output: Annotated[
+            Optional[str],
+            typer.Option("--output", "-o", help="Save output to file instead of printing."),
+        ] = None,
+        provider: Annotated[
+            Optional[str],
+            typer.Option("--provider", help="LLM provider override: openai, anthropic, gemini, local.", hidden=True),
+        ] = None,
+        skip_setup: Annotated[
+            bool,
+            typer.Option("--skip-setup", help="Skip first-run onboarding.", hidden=True),
+        ] = False,
+) -> None:
+    """Generate a changelog from commits in a tag/ref range.
+
+    \b
+    Examples:
+      glimpse changelog                       # since the latest tag → HEAD
+      glimpse changelog --from v1.2.0 --to v1.3.0
+      glimpse changelog --json
+      glimpse changelog --format markdown -o CHANGELOG_NEXT.md
+    """
+    cfg = _load_or_onboard(skip_setup)
+    _apply_provider_override(cfg, provider, model)
+    ctx_mode = context or cfg.context_mode
+    do_filter = filter_noise if filter_noise is not None else cfg.filter_noise
+
+    repo_path = Path(repo).resolve() if repo else None
+
+    # Resolve the start ref: explicit --from, else the latest tag, else full history.
+    effective_from = from_ref or get_latest_tag(repo_path)
+    rev_range = f"{effective_from}..{to_ref}" if effective_from else to_ref
+
+    try:
+        commits = get_commits_in_range(repo_path=repo_path, rev_range=rev_range)
+    except GitError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(1)
+
+    filtered_count = 0
+    if do_filter:
+        original_count = len(commits)
+        commits = filter_noise_commits(commits)
+        filtered_count = original_count - len(commits)
+
+    if not commits:
+        console.print(f"No changes found in [bold]{rev_range}[/bold].")
+        raise typer.Exit(0)
+
+    # Collect diffs only if an LLM may use them. "diffs" → all; "both" → vague only.
+    diff_snippets: dict[str, str] | None = None
+    if not no_llm and ctx_mode in ("diffs", "both"):
+        from gitglimpse.grouping import changelog_subject
+        collect_all = ctx_mode == "diffs"
+        diff_snippets = {}
+        for commit in commits:
+            if commit.is_merge:
+                continue
+            if collect_all or is_vague_message(changelog_subject(commit.message)):
+                try:
+                    diff_snippets[commit.hash] = get_commit_diff(repo_path, commit.hash)
+                except GitError:
+                    pass
+
+    if as_json:
+        print(format_changelog_json(commits, effective_from, to_ref, filtered_count=filtered_count))
+        return
+
+    use_markdown = fmt and fmt.lower() == "markdown"
+
+    if filtered_count > 0:
+        console.print(f"[dim]Filtered {filtered_count} noise commits (merges, formatting, dependencies)[/dim]",
+                      highlight=False)
+
+    active_provider: object | None = None
+    llm_output: str | None = None
+    if not no_llm:
+        from gitglimpse.providers.local import LocalProvider
+        provider = _resolve_provider(cfg, local_llm, local_llm_url, model, context_mode=ctx_mode)
+        if provider is not None:
+            if isinstance(provider, LocalProvider) and not provider.is_available():
+                if local_llm:
+                    console.print(
+                        "[yellow]⚠ Local LLM not reachable — falling back to template.[/yellow]"
+                    )
+            else:
+                active_provider = provider
+                llm_output = provider.summarize_changelog(commits, effective_from, to_ref, diff_snippets)
+
+    _print_status_line(None, active_provider, ctx_mode)
+
+    if use_markdown or llm_output:
+        md = llm_output if llm_output else format_changelog_markdown(commits, effective_from, to_ref, filtered_count)
+        if output:
+            Path(output).write_text(md, encoding="utf-8")
+            console.print(f"Changelog saved to [bold]{output}[/bold]")
+        else:
+            console.print(md, markup=False, highlight=False)
+    else:
+        rendered = format_changelog_template(commits, effective_from, to_ref, filtered_count)
+        if output:
+            # Strip Rich markup for file output by using the Markdown formatter instead.
+            Path(output).write_text(
+                format_changelog_markdown(commits, effective_from, to_ref, filtered_count),
+                encoding="utf-8",
+            )
+            console.print(f"Changelog saved to [bold]{output}[/bold]")
+        else:
+            console.print(rendered, highlight=False)
+
+
 # ---------------------------------------------------------------------------
 # config show
 # ---------------------------------------------------------------------------
@@ -854,7 +1037,7 @@ def config_setup() -> None:
 # init
 # ---------------------------------------------------------------------------
 
-_COMMAND_TEMPLATES = ("standup.md", "report.md", "week.md", "pr.md")
+_COMMAND_TEMPLATES = ("standup.md", "report.md", "week.md", "pr.md", "changelog.md")
 
 
 def _read_template(name: str) -> str:
@@ -887,7 +1070,11 @@ def _write_command_file(
 def init(
         cursor: Annotated[
             bool,
-            typer.Option("--cursor", help="Also create .cursor/commands/ files."),
+            typer.Option("--cursor", help="Create .cursor/commands/ files."),
+        ] = False,
+        claude: Annotated[
+            bool,
+            typer.Option("--claude", help="Create .claude/commands/ files."),
         ] = False,
         force: Annotated[
             bool,
@@ -898,19 +1085,24 @@ def init(
             typer.Option("--repo", help="Target repository root. Defaults to current directory."),
         ] = None,
 ) -> None:
-    """Initialize Claude Code (and optionally Cursor) slash-command files.
+    """Initialize Claude Code and/or Cursor slash-command files.
 
     \b
     Examples:
-      glimpse init
-      glimpse init --cursor
+      glimpse init                   # Claude Code only (default)
+      glimpse init --cursor          # Cursor only
+      glimpse init --claude --cursor # both
       glimpse init --force
     """
     root = Path(repo) if repo else Path.cwd()
 
-    targets: list[tuple[Path, str]] = [
-        (root / ".claude" / "commands", "Claude Code"),
-    ]
+    # Default to Claude Code if neither flag is specified.
+    if not cursor and not claude:
+        claude = True
+
+    targets: list[tuple[Path, str]] = []
+    if claude:
+        targets.append((root / ".claude" / "commands", "Claude Code"))
     if cursor:
         targets.append((root / ".cursor" / "commands", "Cursor"))
 

gitglimpse-0.1.8/src/gitglimpse/commands/changelog.md

@@ -0,0 +1,36 @@
+Generate a release changelog from your git history.
+
+Run the following shell command and capture its output:
+
+```
+glimpse changelog --json --context both
+```
+
+This compares the latest tag to HEAD by default. To target a specific range, pass refs:
+
+```
+glimpse changelog --json --from v1.2.0 --to v1.3.0
+```
+
+Then format the JSON result into a **changelog** using this structure:
+
+```
+# Changelog — [range]
+
+[If "breaking_changes" is non-empty:]
+## ⚠ Breaking Changes
+- [subject][" (TICKET, hash)" using the entry's ticket/hash if present]
+
+[For each entry in "sections" (already ordered):]
+## [heading]
+- [subject][" (TICKET, hash)" using the entry's ticket/hash if present]
+```
+
+Rules:
+- Preserve the section order from the "sections" array; skip any section with no entries.
+- Rewrite each entry's "subject" as a clear, user-facing change — but do not invent or drop entries.
+- Include the entry "ticket" and short "hash" in parentheses when present.
+- List breaking changes first under the "⚠ Breaking Changes" heading.
+- If the JSON includes a "filtered_commits" count (> 0), note it briefly at the bottom: "X noise commits filtered".
+- If "sections" is empty, write "No changes found in this range."
+- No commentary, suggestions, or next steps — only the changelog.

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/estimation.py

@@ -12,12 +12,39 @@ if TYPE_CHECKING:
 _BREAK_THRESHOLD = timedelta(hours=2)
 _BREAK_CAP_MINUTES = 45
 _PRIOR_WORK_MINUTES = 30
-_COMPLEXITY_THRESHOLD_LINES = 200
-_COMPLEXITY_MULTIPLIER = 1.2
 _SMALL_CHANGE_LINES = 20
 _SMALL_CHANGE_FLOOR_MINUTES = 30
 _MINIMUM_MINUTES = 15
 
+# Size signal for single-commit tasks (no gaps to infer effort from).
+_SIZE_SIGNAL_THRESHOLD_LINES = 50
+_MINUTES_PER_LINE = 0.4
+_MINUTES_PER_EXTRA_FILE = 5
+_SIZE_SIGNAL_CAP_MINUTES = 120
+
+# Complexity multiplier: continuous ramp above the threshold, capped.
+_COMPLEXITY_THRESHOLD_LINES = 200
+_COMPLEXITY_SCALE = 0.2
+_COMPLEXITY_MAX_MULTIPLIER = 1.5
+
+
+def _complexity_multiplier(total_lines: int) -> float:
+    """Return a continuous complexity multiplier in [1.0, _COMPLEXITY_MAX_MULTIPLIER]."""
+    if total_lines <= _COMPLEXITY_THRESHOLD_LINES:
+        return 1.0
+    doublings = math.log2(total_lines / _COMPLEXITY_THRESHOLD_LINES)
+    return min(_COMPLEXITY_MAX_MULTIPLIER, 1.0 + _COMPLEXITY_SCALE * doublings)
+
+
+def _distinct_file_count(task: Task) -> int:
+    """Number of distinct files touched across the task's non-merge commits."""
+    return len({
+        fc.path
+        for c in task.commits
+        if not c.is_merge
+        for fc in c.files
+    })
+
 
 def estimate_task_duration(task: Task) -> int:
     """Estimate how long the task took in minutes.
@@ -28,10 +55,13 @@ def estimate_task_duration(task: Task) -> int:
     3. Gaps between consecutive non-merge commits:
        - gap < 2 h → add actual gap in minutes
        - gap ≥ 2 h → add capped 45 min (developer likely took a break)
-    4. If total line changes < 20 AND any gap was ≥ 2 h: floor at 30 min
+    4. Weak timing (single non-merge commit, no gaps to infer from): add a
+       size-based signal for changes over ~50 lines, plus a little per extra file,
+       so squashed large commits aren't under-counted. Small commits are untouched.
+    5. If total line changes < 20 AND any gap was ≥ 2 h: floor at 30 min
        (captures debugging sessions with little visible output).
-    5. If total line changes > 200: multiply by 1.2× (complex work).
-    6. Clamp to a minimum of 15 minutes.
+    6. Complexity multiplier: a continuous ramp above 200 lines (≤ 1.5×).
+    7. Clamp to a minimum of 15 minutes.
     """
     non_merge = [c for c in task.commits if not c.is_merge]
 
@@ -54,13 +84,18 @@ def estimate_task_duration(task: Task) -> int:
 
     total_lines = task.insertions + task.deletions
 
-    # Rule 4: debugging floor.
+    # Rule 4: weak-timing size signal (single-commit tasks only).
+    if len(ordered) == 1 and total_lines > _SIZE_SIGNAL_THRESHOLD_LINES:
+        size_minutes = (total_lines - _SIZE_SIGNAL_THRESHOLD_LINES) * _MINUTES_PER_LINE
+        size_minutes += max(0, _distinct_file_count(task) - 1) * _MINUTES_PER_EXTRA_FILE
+        total_minutes += min(size_minutes, _SIZE_SIGNAL_CAP_MINUTES)
+
+    # Rule 5: debugging floor.
     if total_lines < _SMALL_CHANGE_LINES and had_long_gap:
         total_minutes = max(total_minutes, _SMALL_CHANGE_FLOOR_MINUTES)
 
-    # Rule 5: complexity multiplier.
-    if total_lines > _COMPLEXITY_THRESHOLD_LINES:
-        total_minutes *= _COMPLEXITY_MULTIPLIER
+    # Rule 6: complexity multiplier (continuous).
+    total_minutes *= _complexity_multiplier(total_lines)
 
     return max(_MINIMUM_MINUTES, round(total_minutes))
 

gitglimpse-0.1.8/src/gitglimpse/formatters/changelog.py

@@ -0,0 +1,177 @@
+"""Changelog formatting (template, Markdown, and JSON)."""
+
+import json as _json
+
+from rich.markup import escape as _escape
+
+from gitglimpse.git import Commit
+from gitglimpse.grouping import (
+    CHANGELOG_SECTIONS,
+    changelog_subject,
+    classify_commit_type,
+    extract_ticket_id,
+    is_breaking_change,
+)
+
+
+def _range_label(from_ref: str | None, to_ref: str) -> str:
+    if from_ref:
+        return f"{from_ref}..{to_ref}"
+    return to_ref
+
+
+def _entry(commit: Commit) -> dict:
+    """Build a single changelog entry from a commit."""
+    return {
+        "subject": changelog_subject(commit.message),
+        "ticket": extract_ticket_id(commit.message),
+        "hash": commit.hash[:7],
+        "breaking": is_breaking_change(commit.message),
+    }
+
+
+def build_sections(commits: list[Commit]) -> list[tuple[str, str, list[dict]]]:
+    """Group commits into ordered (type_key, heading, entries) sections.
+
+    Merge commits are skipped. Duplicate subjects within a section are collapsed.
+    Only sections with at least one entry are returned, in CHANGELOG_SECTIONS order.
+    """
+    buckets: dict[str, list[dict]] = {key: [] for key, _ in CHANGELOG_SECTIONS}
+    seen: dict[str, set[str]] = {key: set() for key, _ in CHANGELOG_SECTIONS}
+
+    for commit in commits:
+        if commit.is_merge:
+            continue
+        key = classify_commit_type(commit.message)
+        entry = _entry(commit)
+        subject_key = entry["subject"].lower()
+        if subject_key in seen[key]:
+            continue
+        seen[key].add(subject_key)
+        buckets[key].append(entry)
+
+    sections: list[tuple[str, str, list[dict]]] = []
+    for key, heading in CHANGELOG_SECTIONS:
+        if buckets[key]:
+            sections.append((key, heading, buckets[key]))
+    return sections
+
+
+def _breaking_entries(sections: list[tuple[str, str, list[dict]]]) -> list[dict]:
+    return [e for _, _, entries in sections for e in entries if e["breaking"]]
+
+
+def _entry_suffix(entry: dict) -> str:
+    parts: list[str] = []
+    if entry["ticket"]:
+        parts.append(entry["ticket"])
+    parts.append(entry["hash"])
+    return f" ({', '.join(parts)})"
+
+
+# ---------------------------------------------------------------------------
+# Template (Rich markup)
+# ---------------------------------------------------------------------------
+
+def format_changelog_template(
+    commits: list[Commit],
+    from_ref: str | None,
+    to_ref: str,
+    filtered_count: int = 0,
+) -> str:
+    """Render a changelog using Rich markup."""
+    sections = build_sections(commits)
+    label = _range_label(from_ref, to_ref)
+    lines: list[str] = [f"[bold yellow]Changelog — {_escape(label)}[/bold yellow]", ""]
+
+    if not sections:
+        lines.append("[dim](no changes found in this range)[/dim]")
+        return "\n".join(lines)
+
+    breaking = _breaking_entries(sections)
+    if breaking:
+        lines.append("[bold red]⚠ Breaking Changes[/bold red]")
+        for e in breaking:
+            lines.append(f"  [red]•[/red] {_escape(e['subject'])}[dim]{_escape(_entry_suffix(e))}[/dim]")
+        lines.append("")
+
+    for _key, heading, entries in sections:
+        lines.append(f"[bold]{heading}[/bold]")
+        for e in entries:
+            lines.append(
+                f"  [yellow]•[/yellow] {_escape(e['subject'])}"
+                f"[dim]{_escape(_entry_suffix(e))}[/dim]"
+            )
+        lines.append("")
+
+    total = sum(len(entries) for _, _, entries in sections)
+    summary = f"[dim]{total} change{'s' if total != 1 else ''}[/dim]"
+    if filtered_count > 0:
+        summary += f" [dim]· {filtered_count} noise commits filtered[/dim]"
+    lines.append(summary)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Markdown
+# ---------------------------------------------------------------------------
+
+def format_changelog_markdown(
+    commits: list[Commit],
+    from_ref: str | None,
+    to_ref: str,
+    filtered_count: int = 0,
+) -> str:
+    """Render a changelog as Markdown."""
+    sections = build_sections(commits)
+    label = _range_label(from_ref, to_ref)
+    lines: list[str] = [f"# Changelog — {label}", ""]
+
+    if not sections:
+        lines.append("No changes found in this range.")
+        return "\n".join(lines)
+
+    breaking = _breaking_entries(sections)
+    if breaking:
+        lines.append("## ⚠ Breaking Changes")
+        lines.append("")
+        for e in breaking:
+            lines.append(f"- {e['subject']}{_entry_suffix(e)}")
+        lines.append("")
+
+    for _key, heading, entries in sections:
+        lines.append(f"## {heading}")
+        lines.append("")
+        for e in entries:
+            lines.append(f"- {e['subject']}{_entry_suffix(e)}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# ---------------------------------------------------------------------------
+# JSON
+# ---------------------------------------------------------------------------
+
+def format_changelog_json(
+    commits: list[Commit],
+    from_ref: str | None,
+    to_ref: str,
+    filtered_count: int = 0,
+) -> str:
+    """Render a changelog as a JSON string."""
+    sections = build_sections(commits)
+    data: dict = {
+        "from": from_ref,
+        "to": to_ref,
+        "range": _range_label(from_ref, to_ref),
+        "total_changes": sum(len(entries) for _, _, entries in sections),
+        "breaking_changes": _breaking_entries(sections),
+        "sections": [
+            {"type": key, "heading": heading, "entries": entries}
+            for key, heading, entries in sections
+        ],
+    }
+    if filtered_count > 0:
+        data["filtered_commits"] = filtered_count
+    return _json.dumps(data, indent=2)

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/git.py

@@ -287,8 +287,11 @@ def get_commits(
     commits = _parse_raw_output(raw)
 
     # Enrich commits that have no branch decoration with source-ref data.
-    branch_map = _get_branch_map(git, cwd)
-    fallback_branch = _get_current_branch(git, cwd)
+    # The source-ref map walks the entire repo history, so only build it when
+    # some commit in this window actually lacks a branch label.
+    needs_branch_map = any(not c.branches for c in commits)
+    branch_map = _get_branch_map(git, cwd) if needs_branch_map else {}
+    fallback_branch = _get_current_branch(git, cwd) if needs_branch_map else ""
     enriched: list[Commit] = []
     for c in commits:
         if not c.branches:
@@ -402,6 +405,81 @@ def get_branch_commits(
     return enriched
 
 
+def get_latest_tag(repo_path: Path | None = None) -> str | None:
+    """Return the most recent tag reachable from HEAD, or None if there are none."""
+    git = _git_bin()
+    cwd = Path(repo_path) if repo_path is not None else Path.cwd()
+    result = subprocess.run(
+        [git, "describe", "--tags", "--abbrev=0"],
+        cwd=cwd, capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        return None
+    tag = result.stdout.strip()
+    return tag or None
+
+
+def get_commits_in_range(
+    repo_path: Path | None = None,
+    rev_range: str = "HEAD",
+) -> list[Commit]:
+    """Return commits in *rev_range* (e.g. ``v1.2.0..HEAD`` or ``HEAD``), newest first.
+
+    Raises GitError if the repo or any ref in the range is invalid.
+    """
+    git = _git_bin()
+    cwd = Path(repo_path) if repo_path is not None else Path.cwd()
+
+    if not cwd.exists():
+        raise GitError(f"Path does not exist: {cwd}")
+
+    verify = subprocess.run(
+        [git, "rev-parse", "--git-dir"],
+        cwd=cwd, capture_output=True, text=True,
+    )
+    if verify.returncode != 0:
+        raise GitError(f"Not a git repository: {cwd}")
+
+    # Empty repo (no commits yet).
+    head_check = subprocess.run(
+        [git, "rev-parse", "HEAD"],
+        cwd=cwd, capture_output=True, text=True,
+    )
+    if head_check.returncode != 0:
+        return []
+
+    cmd = [
+        git, "log",
+        f"--pretty=format:{_LOG_FORMAT}",
+        "--numstat",
+        rev_range,
+    ]
+    raw = _run(cmd, cwd=cwd)
+    commits = _parse_raw_output(raw)
+
+    # Enrich branch info, only walking history if a commit needs it.
+    needs_branch_map = any(not c.branches for c in commits)
+    branch_map = _get_branch_map(git, cwd) if needs_branch_map else {}
+    fallback_branch = _get_current_branch(git, cwd) if needs_branch_map else ""
+    enriched: list[Commit] = []
+    for c in commits:
+        if not c.branches:
+            branch = branch_map.get(c.hash, fallback_branch)
+            c = Commit(
+                hash=c.hash,
+                author_email=c.author_email,
+                message=c.message,
+                timestamp=c.timestamp,
+                branches=[branch],
+                files=c.files,
+                is_merge=c.is_merge,
+            )
+        enriched.append(c)
+
+    enriched.sort(key=lambda c: c.timestamp, reverse=True)
+    return enriched
+
+
 def get_current_author_email(repo_path: Path | None = None) -> str:
     """Return the configured git user.email for the repo.
 

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/grouping.py

@@ -220,6 +220,74 @@ def extract_ticket_id(branch: str) -> str | None:
     return None
 
 
+# ---------------------------------------------------------------------------
+# Conventional-commit classification (used by the changelog command)
+# ---------------------------------------------------------------------------
+
+# Ordered: how sections appear in a generated changelog. Only non-empty
+# sections are rendered.
+CHANGELOG_SECTIONS: list[tuple[str, str]] = [
+    ("feat", "Features"),
+    ("fix", "Bug Fixes"),
+    ("perf", "Performance"),
+    ("refactor", "Refactoring"),
+    ("docs", "Documentation"),
+    ("test", "Tests"),
+    ("build", "Build System"),
+    ("ci", "CI"),
+    ("style", "Styles"),
+    ("revert", "Reverts"),
+    ("chore", "Chores"),
+    ("other", "Other Changes"),
+]
+
+_CONVENTIONAL_TYPES = frozenset(k for k, _ in CHANGELOG_SECTIONS if k != "other")
+
+# type(optional-scope)!: subject
+_CONVENTIONAL_RE = re.compile(
+    r"^(?P<type>[a-z]+)(?:\([^)]+\))?(?P<breaking>!)?:\s*(?P<subject>.+)$",
+    re.IGNORECASE,
+)
+
+
+def classify_commit_type(message: str) -> str:
+    """Return the changelog section key for a commit message.
+
+    Recognises Conventional Commits prefixes (``feat:``, ``fix(scope):``, …).
+    Unknown or prefix-less messages fall back to ``"other"``.
+    """
+    m = _CONVENTIONAL_RE.match(message.strip())
+    if m:
+        ctype = m.group("type").lower()
+        if ctype in _CONVENTIONAL_TYPES:
+            return ctype
+    return "other"
+
+
+def is_breaking_change(message: str) -> bool:
+    """Return True if the commit marks a breaking change (``feat!:`` or footer)."""
+    first_line = message.strip().splitlines()[0] if message.strip() else ""
+    m = _CONVENTIONAL_RE.match(first_line)
+    if m and m.group("breaking"):
+        return True
+    return "BREAKING CHANGE" in message or "BREAKING-CHANGE" in message
+
+
+def changelog_subject(message: str) -> str:
+    """Return the commit's first line with a recognised Conventional Commits prefix stripped.
+
+    Only known types (``feat``, ``fix``, …) are stripped, so an arbitrary
+    ``word:`` prefix (e.g. ``gitglimpse:``) is left intact.
+    """
+    first_line = message.strip().splitlines()[0] if message.strip() else ""
+    m = _CONVENTIONAL_RE.match(first_line)
+    if m and m.group("type").lower() in _CONVENTIONAL_TYPES:
+        subject = m.group("subject").strip()
+        if subject:
+            return subject
+    return first_line
+
+
 def _branch_key(commit: Commit) -> str:
     """Return the primary branch for a commit, or 'main' as fallback."""
     return commit.branches[0] if commit.branches else "main"

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/providers/base.py

@@ -43,6 +43,20 @@ def validate_llm_output(response: str) -> bool:
     return True
 
 
+_MAX_CHANGELOG_LEN = 8000
+
+
+def validate_changelog_output(response: str) -> bool:
+    """Relaxed validation for changelog output (multi-heading Markdown is expected)."""
+    if not response or not response.strip():
+        return False
+    if len(response) > _MAX_CHANGELOG_LEN:
+        return False
+    if _GARBAGE_PHRASES.search(response):
+        return False
+    return True
+
+
 class BaseLLMProvider(ABC):
     """Common interface all LLM providers must implement."""
 
@@ -84,6 +98,16 @@ class BaseLLMProvider(ABC):
     ) -> str | None:
         """Return a formatted PR summary, or None on failure."""
 
+    @abstractmethod
+    def summarize_changelog(
+        self,
+        commits: list,
+        from_ref: str | None,
+        to_ref: str,
+        diff_snippets: dict[str, str] | None = None,
+    ) -> str | None:
+        """Return a formatted changelog (Markdown), or None on failure."""
+
     # ------------------------------------------------------------------
     # Shared helpers
     # ------------------------------------------------------------------
@@ -150,6 +174,63 @@ class BaseLLMProvider(ABC):
         "Keep the total output under 300 words."
     )
 
+    _CHANGELOG_PROMPT = (
+        "Generate a release changelog in Markdown from the structured changes below.\n\n"
+        "Write:\n"
+        "1. A short ## heading per change category that has entries "
+        "(Features, Bug Fixes, etc.), in the order given.\n"
+        "2. One bullet per entry, rewritten as a clear, user-facing change. "
+        "Keep ticket IDs and short hashes in parentheses if present.\n"
+        "3. If there are breaking changes, put them first under a "
+        "'## ⚠ Breaking Changes' heading.\n\n"
+        "Stay faithful to the provided entries — do not invent changes, do not "
+        "drop entries, and do not add commentary, suggestions, or next steps. "
+        "Output only the changelog."
+    )
+
+    @classmethod
+    def get_changelog_system_prompt(cls, context_mode: str = "commits") -> str:
+        """Return system prompt for changelog generation."""
+        return cls._CHANGELOG_PROMPT + cls._context_addendum(context_mode)
+
+    @staticmethod
+    def _format_changelog_context(
+        commits: list,
+        from_ref: str | None,
+        to_ref: str,
+        diff_snippets: dict[str, str] | None = None,
+    ) -> str:
+        """Serialise changelog entries grouped by category for the LLM prompt."""
+        from gitglimpse.formatters.changelog import build_sections
+
+        sections = build_sections(commits)
+        range_label = f"{from_ref}..{to_ref}" if from_ref else to_ref
+        lines = [
+            f"Range: {range_label}",
+            f"Total changes: {sum(len(e) for _, _, e in sections)}",
+            "",
+        ]
+        for _key, heading, entries in sections:
+            lines.append(f"{heading}:")
+            for e in entries:
+                suffix_parts = [p for p in (e["ticket"], e["hash"]) if p]
+                suffix = f" ({', '.join(suffix_parts)})" if suffix_parts else ""
+                breaking = " [BREAKING]" if e["breaking"] else ""
+                lines.append(f"  - {e['subject']}{suffix}{breaking}")
+            lines.append("")
+
+        if diff_snippets:
+            shown = [c for c in commits if not c.is_merge and c.hash in diff_snippets]
+            if shown:
+                lines.append("Selected diffs:")
+                for commit in shown:
+                    lines.append(f"  Diff ({commit.hash[:7]}):")
+                    for dl in diff_snippets[commit.hash].splitlines():
+                        lines.append(f"    {dl}")
+                lines.append("")
+
+        return "\n".join(lines)
+
     @classmethod
     def _context_addendum(cls, context_mode: str) -> str:
         if context_mode == "diffs":

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/providers/claude.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 from datetime import date
 from typing import TYPE_CHECKING
 
-from gitglimpse.providers.base import BaseLLMProvider, _warn, validate_llm_output
+from gitglimpse.providers.base import (
+    BaseLLMProvider,
+    _warn,
+    validate_changelog_output,
+    validate_llm_output,
+)
 
 if TYPE_CHECKING:
     from gitglimpse.grouping import Task
@@ -100,3 +105,8 @@ class ClaudeProvider(BaseLLMProvider):
     def summarize_pr(self, tasks: list[Task], branch: str, base: str, diff_snippets: dict[str, str] | None = None) -> str | None:
         context = self._format_pr_context(tasks, branch, base, diff_snippets)
         return self._validated(self._chat(context, system_prompt=self.get_pr_system_prompt(self.context_mode)))
+
+    def summarize_changelog(self, commits: list, from_ref: str | None, to_ref: str, diff_snippets: dict[str, str] | None = None) -> str | None:
+        context = self._format_changelog_context(commits, from_ref, to_ref, diff_snippets)
+        result = self._chat(context, system_prompt=self.get_changelog_system_prompt(self.context_mode))
+        return result if result is not None and validate_changelog_output(result) else None

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/providers/gemini.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 from datetime import date
 from typing import TYPE_CHECKING
 
-from gitglimpse.providers.base import BaseLLMProvider, _warn, validate_llm_output
+from gitglimpse.providers.base import (
+    BaseLLMProvider,
+    _warn,
+    validate_changelog_output,
+    validate_llm_output,
+)
 
 if TYPE_CHECKING:
     from gitglimpse.grouping import Task
@@ -96,3 +101,8 @@ class GeminiProvider(BaseLLMProvider):
     def summarize_pr(self, tasks: list[Task], branch: str, base: str, diff_snippets: dict[str, str] | None = None) -> str | None:
         context = self._format_pr_context(tasks, branch, base, diff_snippets)
         return self._validated(self._chat(context, system_prompt=self.get_pr_system_prompt(self.context_mode)))
+
+    def summarize_changelog(self, commits: list, from_ref: str | None, to_ref: str, diff_snippets: dict[str, str] | None = None) -> str | None:
+        context = self._format_changelog_context(commits, from_ref, to_ref, diff_snippets)
+        result = self._chat(context, system_prompt=self.get_changelog_system_prompt(self.context_mode))
+        return result if result is not None and validate_changelog_output(result) else None

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/providers/local.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 from datetime import date
 from typing import TYPE_CHECKING
 
-from gitglimpse.providers.base import BaseLLMProvider, _warn, validate_llm_output
+from gitglimpse.providers.base import (
+    BaseLLMProvider,
+    _warn,
+    validate_changelog_output,
+    validate_llm_output,
+)
 
 if TYPE_CHECKING:
     from gitglimpse.grouping import Task
@@ -167,3 +172,15 @@ class LocalProvider(BaseLLMProvider):
         context = self._format_pr_context(tasks, branch, base, diff_snippets)
         prompt = self.get_pr_system_prompt(context_mode=self.context_mode)
         return self._validated(self._chat(context, system_prompt=prompt))
+
+    def summarize_changelog(
+        self,
+        commits: list,
+        from_ref: str | None,
+        to_ref: str,
+        diff_snippets: dict[str, str] | None = None,
+    ) -> str | None:
+        context = self._format_changelog_context(commits, from_ref, to_ref, diff_snippets)
+        prompt = self.get_changelog_system_prompt(context_mode=self.context_mode)
+        result = self._chat(context, system_prompt=prompt)
+        return result if result is not None and validate_changelog_output(result) else None

{gitglimpse-0.1.6 → gitglimpse-0.1.8}/src/gitglimpse/providers/openai.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 from datetime import date
 from typing import TYPE_CHECKING
 
-from gitglimpse.providers.base import BaseLLMProvider, _warn, validate_llm_output
+from gitglimpse.providers.base import (
+    BaseLLMProvider,
+    _warn,
+    validate_changelog_output,
+    validate_llm_output,
+)
 
 if TYPE_CHECKING:
     from gitglimpse.grouping import Task
@@ -98,3 +103,8 @@ class OpenAIProvider(BaseLLMProvider):
     def summarize_pr(self, tasks: list[Task], branch: str, base: str, diff_snippets: dict[str, str] | None = None) -> str | None:
         context = self._format_pr_context(tasks, branch, base, diff_snippets)
         return self._validated(self._chat(context, system_prompt=self.get_pr_system_prompt(self.context_mode)))
+
+    def summarize_changelog(self, commits: list, from_ref: str | None, to_ref: str, diff_snippets: dict[str, str] | None = None) -> str | None:
+        context = self._format_changelog_context(commits, from_ref, to_ref, diff_snippets)
+        result = self._chat(context, system_prompt=self.get_changelog_system_prompt(self.context_mode))
+        return result if result is not None and validate_changelog_output(result) else None

gitglimpse-0.1.6/src/gitglimpse/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.6"