git-graphable 0.1.0__py3-none-any.whl

git_graphable/__init__.py

@@ -0,0 +1,19 @@
+from .core import (
+    CommitMetadata,
+    GitCommit,
+    GitLogConfig,
+    generate_summary,
+    process_repo,
+)
+from .parser import get_git_log
+from .styler import export_graph
+
+__all__ = [
+    "CommitMetadata",
+    "GitCommit",
+    "GitLogConfig",
+    "generate_summary",
+    "get_git_log",
+    "export_graph",
+    "process_repo",
+]

git_graphable/cli.py

@@ -0,0 +1,398 @@
+import argparse
+import os
+import sys
+import tempfile
+import webbrowser
+from typing import Dict, List, Optional
+
+from graphable.enums import Engine
+
+# Try to import rich
+try:
+    import typer
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.table import Table
+
+    HAS_CLI_EXTRAS = True
+except ImportError:
+    HAS_CLI_EXTRAS = False
+
+from .core import GitCommit, GitLogConfig, generate_summary, process_repo
+from .styler import export_graph
+
+
+def get_extension(engine: Engine, as_image: bool) -> str:
+    """Get file extension for the given engine and export type."""
+    if as_image:
+        return ".svg"  # Default to SVG for images
+
+    extensions = {
+        Engine.MERMAID: ".mmd",
+        Engine.GRAPHVIZ: ".dot",
+        Engine.D2: ".d2",
+        Engine.PLANTUML: ".puml",
+    }
+    return extensions.get(engine, ".txt")
+
+
+def handle_output(
+    graph,
+    engine: Engine,
+    output: Optional[str],
+    config: GitLogConfig,
+    as_image: bool = False,
+):
+    """Handles exporting and optionally opening the graph."""
+    if output:
+        # If output path is provided, we use the specified as_image flag or infer from extension
+        image_exts = [".png", ".svg", ".jpg", ".jpeg", ".pdf"]
+        is_image = as_image or any(output.lower().endswith(ext) for ext in image_exts)
+        export_graph(graph, output, config, engine, as_image=is_image)
+        print(f"Exported to {output}")
+    else:
+        # Create temp file and open as image
+        ext = get_extension(engine, as_image=True)
+        with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tf:
+            temp_path = tf.name
+
+        export_graph(graph, temp_path, config, engine, as_image=True)
+        print(f"Opening temporary image: {temp_path}")
+        webbrowser.open(f"file://{os.path.abspath(temp_path)}")
+
+
+def display_summary(summary: Dict[str, List[GitCommit]], bare: bool = False):
+    """Displays a summary of flagged commits."""
+    if bare:
+        print("\n--- Git Hygiene Summary ---")
+        for category, commits in summary.items():
+            if commits:
+                print(f"{category}: {len(commits)} commits")
+                for c in commits[:5]:  # Show first 5
+                    branches = (
+                        f" ({', '.join(c.reference.branches)})"
+                        if c.reference.branches
+                        else ""
+                    )
+                    print(
+                        f"  - {c.reference.hash[:7]}{branches}: {c.reference.message}"
+                    )
+                if len(commits) > 5:
+                    print(f"  ... and {len(commits) - 5} more")
+    else:
+        console = Console()
+        table = Table(title="Git Hygiene Summary", box=None)
+        table.add_column("Category", style="cyan", no_wrap=True)
+        table.add_column("Count", style="magenta")
+        table.add_column("Examples (SHA - Message)", style="green")
+
+        for category, commits in summary.items():
+            if commits:
+                examples = []
+                for c in commits[:3]:
+                    examples.append(
+                        f"{c.reference.hash[:7]} - {c.reference.message[:50]}"
+                    )
+                example_str = "\n".join(examples)
+                if len(commits) > 3:
+                    example_str += f"\n... and {len(commits) - 3} more"
+                table.add_row(category, str(len(commits)), example_str)
+
+        if table.row_count > 0:
+            console.print(Panel(table, border_style="blue"))
+        else:
+            console.print("[bold green]History looks clean! No issues flagged.[/]")
+
+
+def validate_highlights(
+    highlight_authors: bool,
+    highlight_distance_from: Optional[str],
+    highlight_stale: Optional[int],
+) -> Optional[str]:
+    """Check for conflicting fill-based highlight options."""
+    active = []
+    if highlight_authors:
+        active.append("--highlight-authors")
+    if highlight_distance_from:
+        active.append("--highlight-distance-from")
+    if highlight_stale is not None:
+        active.append("--highlight-stale")
+
+    if len(active) > 1:
+        return f"Error: Cannot use multiple fill-based highlights at once: {', '.join(active)}"
+    return None
+
+
+# --- Bare Argument Parser CLI ---
+def run_bare_cli(argv: List[str]):
+    parser = argparse.ArgumentParser(
+        description="Git graph to Mermaid/Graphviz/D2/PlantUML converter"
+    )
+    parser.add_argument("path", help="Path to local directory or git URL")
+    parser.add_argument(
+        "--date-format", default="%Y%m%d%H%M%S", help="Date format for commit labels"
+    )
+    parser.add_argument(
+        "--engine",
+        type=str,
+        default="mermaid",
+        choices=[e.value for e in Engine],
+        help="Visualization engine",
+    )
+    parser.add_argument(
+        "-o", "--output", help="Output file path (default: create and open temp image)"
+    )
+    parser.add_argument(
+        "--image",
+        action="store_true",
+        help="Export as image even when output path is provided",
+    )
+    parser.add_argument(
+        "--simplify",
+        action="store_true",
+        help="Pass --simplify-by-decoration to git log",
+    )
+    parser.add_argument(
+        "--limit", type=int, help="Limit the number of commits to process"
+    )
+    parser.add_argument(
+        "--highlight-critical",
+        action="append",
+        default=[],
+        help="Branch names to highlight as critical",
+    )
+    parser.add_argument(
+        "--highlight-authors",
+        action="store_true",
+        help="Assign colors to different authors",
+    )
+    parser.add_argument(
+        "--highlight-distance-from", help="Base branch/hash for distance highlighting"
+    )
+    parser.add_argument(
+        "--highlight-path", help="Highlight path between two SHAs (format: START..END)"
+    )
+    parser.add_argument(
+        "--highlight-diverging-from",
+        help="Base branch/hash for divergence/behind analysis",
+    )
+    parser.add_argument(
+        "--highlight-orphans",
+        action="store_true",
+        help="Highlight dangling/orphan commits",
+    )
+    parser.add_argument(
+        "--highlight-stale",
+        type=int,
+        help="Threshold in days to highlight stale branch tips",
+    )
+    parser.add_argument(
+        "--highlight-long-running",
+        type=int,
+        help="Threshold in days to highlight long-running branches",
+    )
+    parser.add_argument(
+        "--long-running-base",
+        default="main",
+        help="Base branch for long-running analysis",
+    )
+    parser.add_argument(
+        "--bare", action="store_true", help="Force bare mode (already active)"
+    )
+
+    args = parser.parse_args(argv)
+
+    error = validate_highlights(
+        args.highlight_authors, args.highlight_distance_from, args.highlight_stale
+    )
+    if error:
+        print(error, file=sys.stderr)
+        sys.exit(1)
+
+    engine = Engine(args.engine)
+
+    highlight_path = None
+    if args.highlight_path and ".." in args.highlight_path:
+        parts = args.highlight_path.split("..")
+        highlight_path = (parts[0], parts[1])
+
+    config = GitLogConfig(
+        simplify=args.simplify,
+        limit=args.limit,
+        date_format=args.date_format,
+        highlight_critical=args.highlight_critical,
+        highlight_authors=args.highlight_authors,
+        highlight_distance_from=args.highlight_distance_from,
+        highlight_path=highlight_path,
+        highlight_diverging_from=args.highlight_diverging_from,
+        highlight_orphans=args.highlight_orphans,
+        highlight_stale=args.highlight_stale,
+        highlight_long_running=args.highlight_long_running,
+        long_running_base=args.long_running_base,
+    )
+
+    try:
+        graph = process_repo(args.path, config)
+
+        # Safety check
+        if engine == Engine.MERMAID and len(graph) > 500:
+            print(
+                f"Warning: Graph contains {len(graph)} nodes. Mermaid might exceed size limits.",
+                file=sys.stderr,
+            )
+
+        handle_output(graph, engine, args.output, config, as_image=args.image)
+        display_summary(generate_summary(graph), bare=True)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+# --- Typer CLI ---
+if HAS_CLI_EXTRAS:
+    app = typer.Typer(
+        help="Git graph to Mermaid/Graphviz/D2/PlantUML converter",
+        no_args_is_help=True,
+    )
+
+    @app.command()
+    def convert(
+        path: str = typer.Argument(..., help="Path to local directory or git URL"),
+        date_format: str = typer.Option(
+            "%Y%m%d%H%M%S", help="Date format for commit labels"
+        ),
+        engine: Engine = typer.Option(Engine.MERMAID, help="Visualization engine"),
+        output: Optional[str] = typer.Option(
+            None, "--output", "-o", help="Output file path"
+        ),
+        image: bool = typer.Option(
+            False, "--image", help="Export as image even when output path is provided"
+        ),
+        simplify: bool = typer.Option(
+            False, "--simplify", help="Pass --simplify-by-decoration to git log"
+        ),
+        limit: Optional[int] = typer.Option(
+            None, "--limit", help="Limit the number of commits to process"
+        ),
+        highlight_critical: List[str] = typer.Option(
+            [], "--highlight-critical", help="Branch names to highlight as critical"
+        ),
+        highlight_authors: bool = typer.Option(
+            False, "--highlight-authors", help="Assign colors to different authors"
+        ),
+        highlight_distance_from: Optional[str] = typer.Option(
+            None,
+            "--highlight-distance-from",
+            help="Base branch/hash for distance highlighting",
+        ),
+        highlight_path: Optional[str] = typer.Option(
+            None,
+            "--highlight-path",
+            help="Highlight path between two SHAs (START..END)",
+        ),
+        highlight_diverging_from: Optional[str] = typer.Option(
+            None,
+            "--highlight-diverging-from",
+            help="Base branch/hash for divergence/behind analysis",
+        ),
+        highlight_orphans: bool = typer.Option(
+            False, "--highlight-orphans", help="Highlight dangling/orphan commits"
+        ),
+        highlight_stale: Optional[int] = typer.Option(
+            None,
+            "--highlight-stale",
+            help="Threshold in days to highlight stale branch tips",
+        ),
+        highlight_long_running: Optional[int] = typer.Option(
+            None,
+            "--highlight-long-running",
+            help="Threshold in days to highlight long-running branches",
+        ),
+        long_running_base: str = typer.Option(
+            "main", "--long-running-base", help="Base branch for long-running analysis"
+        ),
+        bare: bool = typer.Option(
+            False, "--bare", help="Force bare mode (no rich output)"
+        ),
+    ):
+        """Git graph to Mermaid/Graphviz/D2/PlantUML converter."""
+        error = validate_highlights(
+            highlight_authors, highlight_distance_from, highlight_stale
+        )
+        if error:
+            typer.secho(error, fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1)
+
+        path_tuple = None
+        if highlight_path and ".." in highlight_path:
+            parts = highlight_path.split("..")
+            path_tuple = (parts[0], parts[1])
+
+        config = GitLogConfig(
+            simplify=simplify,
+            limit=limit,
+            date_format=date_format,
+            highlight_critical=highlight_critical,
+            highlight_authors=highlight_authors,
+            highlight_distance_from=highlight_distance_from,
+            highlight_path=path_tuple,
+            highlight_diverging_from=highlight_diverging_from,
+            highlight_orphans=highlight_orphans,
+            highlight_stale=highlight_stale,
+            highlight_long_running=highlight_long_running,
+            long_running_base=long_running_base,
+        )
+
+        if bare:
+            try:
+                graph = process_repo(path, config)
+                if engine == Engine.MERMAID and len(graph) > 500:
+                    print(
+                        f"Warning: Graph contains {len(graph)} nodes. Mermaid might exceed size limits.",
+                        file=sys.stderr,
+                    )
+                handle_output(graph, engine, output, config, as_image=image)
+                display_summary(generate_summary(graph), bare=True)
+            except Exception as e:
+                print(f"Error: {e}", file=sys.stderr)
+                sys.exit(1)
+            return
+
+        console = Console()
+        with console.status(
+            f"[bold green]Processing repository using {engine.value} engine..."
+        ):
+            try:
+                graph = process_repo(path, config)
+
+                if engine == Engine.MERMAID and len(graph) > 500:
+                    console.print(
+                        f"[bold yellow]Warning:[/] Graph contains {len(graph)} nodes. Mermaid might exceed size limits."
+                    )
+
+                handle_output(graph, engine, output, config, as_image=image)
+                display_summary(generate_summary(graph), bare=False)
+            except Exception as e:
+                console.print(f"[bold red]Error:[/] {e}")
+                sys.exit(1)
+else:
+    app = None
+
+
+def main():
+    # If forced bare OR if typer/rich are missing, use bare CLI
+    if "--bare" in sys.argv or not HAS_CLI_EXTRAS:
+        # Just pass everything except --bare to let argparse handle it
+        bare_argv = [a for a in sys.argv[1:] if a != "--bare"]
+        run_bare_cli(bare_argv)
+    else:
+        # Default to Typer
+        if app is not None:
+            app()
+        else:
+            # Fallback if Typer is somehow missing but logic got here
+            run_bare_cli(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    main()

git_graphable/core.py

@@ -0,0 +1,127 @@
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from graphable import Graph, Graphable
+
+
+@dataclass
+class CommitMetadata:
+    hash: str
+    parents: List[str]
+    branches: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    timestamp: int = 0
+    author: str = ""
+    message: str = ""
+
+
+@dataclass
+class GitLogConfig:
+    """Configuration for retrieving git log."""
+
+    simplify: bool = False
+    limit: Optional[int] = None
+    date_format: str = "%Y%m%d%H%M%S"
+    highlight_critical: List[str] = field(default_factory=list)
+    highlight_authors: bool = False
+    highlight_distance_from: Optional[str] = None  # For distance highlighting
+    highlight_path: Optional[Tuple[str, str]] = None  # (start_input, end_input)
+    highlight_diverging_from: Optional[str] = None  # For divergence analysis
+    highlight_orphans: bool = False
+    highlight_stale: Optional[int] = None  # Days
+    highlight_long_running: Optional[int] = None  # Days
+    long_running_base: str = "main"
+
+
+class GitCommit(Graphable[CommitMetadata]):
+    """A Git commit represented as a graphable object."""
+
+    def __init__(self, metadata: CommitMetadata, config: GitLogConfig):
+        super().__init__(metadata)
+        from .models import Tag
+
+        # Add metadata as tags for filtering/formatting
+        self.add_tag(f"{Tag.AUTHOR.value}{metadata.author}")
+        for branch in metadata.branches:
+            self.add_tag(f"{Tag.BRANCH.value}{branch}")
+            if branch in config.highlight_critical:
+                self.add_tag(Tag.CRITICAL.value)
+
+        for tag in metadata.tags:
+            self.add_tag(f"{Tag.TAG.value}{tag}")
+
+        self.add_tag(Tag.GIT_COMMIT.value)
+
+
+def generate_summary(graph: Graph[GitCommit]) -> Dict[str, List[GitCommit]]:
+    """Generate a summary of flagged commits."""
+    from .models import Tag
+
+    summary = {
+        "Critical": [],
+        "Behind Base": [],
+        "Orphan": [],
+        "Stale": [],
+        "Long-Running": [],
+    }
+
+    for commit in graph:
+        if commit.is_tagged(Tag.CRITICAL.value):
+            summary["Critical"].append(commit)
+        if commit.is_tagged(Tag.BEHIND.value):
+            summary["Behind Base"].append(commit)
+        if commit.is_tagged(Tag.ORPHAN.value):
+            summary["Orphan"].append(commit)
+        if commit.is_tagged(Tag.STALE_COLOR.value):
+            summary["Stale"].append(commit)
+        if commit.is_tagged(Tag.LONG_RUNNING.value):
+            # Only count branch tips for long-running summary to avoid redundancy
+            if commit.reference.branches:
+                summary["Long-Running"].append(commit)
+
+    return summary
+
+
+def process_repo(input_path: str, config: GitLogConfig) -> Graph[GitCommit]:
+    """Clones (if URL) and processes the repo, returning a Graph of GitCommits."""
+    from .highlighter import apply_highlights
+    from .parser import get_git_log
+
+    repo_path = input_path
+    temp_dir = None
+
+    if input_path.startswith(("http://", "https://", "git@", "ssh://")):
+        temp_dir = tempfile.mkdtemp()
+        try:
+            import subprocess
+
+            subprocess.run(
+                ["git", "clone", input_path, temp_dir], check=True, capture_output=True
+            )
+            repo_path = temp_dir
+        except Exception as e:
+            if temp_dir:
+                shutil.rmtree(temp_dir)
+            raise RuntimeError(f"Failed to clone repository: {e}")
+
+    try:
+        if not os.path.exists(os.path.join(repo_path, ".git")):
+            raise RuntimeError(f"{repo_path} is not a git repository.")
+
+        commits_dict = get_git_log(repo_path, config=config)
+
+        for sha, commit in commits_dict.items():
+            for p_sha in commit.reference.parents:
+                if p_sha in commits_dict:
+                    commit.requires(commits_dict[p_sha])
+
+        graph = Graph(list(commits_dict.values()))
+        apply_highlights(graph, config)
+        return graph
+
+    finally:
+        if temp_dir and os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir)

git_graphable/highlighter.py

@@ -0,0 +1,203 @@
+import time
+from typing import Optional
+
+from graphable import Graph
+
+from .core import GitCommit, GitLogConfig
+from .models import Tag
+
+
+def apply_highlights(graph: Graph[GitCommit], config: GitLogConfig):
+    """Apply highlighting tags based on configuration."""
+
+    # 1. Author highlighting
+    if config.highlight_authors:
+        authors = sorted(list(set(c.reference.author for c in graph)))
+        palette = [
+            "#FFD700",
+            "#C0C0C0",
+            "#CD7F32",
+            "#ADD8E6",
+            "#90EE90",
+            "#F08080",
+            "#E6E6FA",
+            "#FFE4E1",
+        ]
+        author_to_color = {
+            author: palette[i % len(palette)] for i, author in enumerate(authors)
+        }
+
+        for commit in graph:
+            color = author_to_color.get(commit.reference.author)
+            if color:
+                commit.add_tag(f"{Tag.COLOR.value}{color}")
+
+    # 2. Distance highlighting
+    if config.highlight_distance_from:
+
+        def find_base_node(query: str) -> Optional[GitCommit]:
+            for commit in graph:
+                if (
+                    query in commit.reference.branches
+                    or commit.reference.hash.startswith(query)
+                ):
+                    return commit
+            return None
+
+        base_commit = find_base_node(config.highlight_distance_from)
+
+        if base_commit:
+            distances = {base_commit: 0}
+            queue = [(base_commit, 0)]
+            visited = {base_commit}
+
+            while queue:
+                current, dist = queue.pop(0)
+                for parent, _ in graph.internal_depends_on(current):
+                    if parent not in visited:
+                        visited.add(parent)
+                        distances[parent] = dist + 1
+                        queue.append((parent, dist + 1))
+                for child, _ in graph.internal_dependents(current):
+                    if child not in visited:
+                        visited.add(child)
+                        distances[child] = dist + 1
+                        queue.append((child, dist + 1))
+
+            if distances:
+                max_dist = max(distances.values())
+                for commit, dist in distances.items():
+                    intensity = int(230 * (dist / max_dist)) if max_dist > 0 else 0
+                    color = f"#{intensity:02x}{intensity:02x}ff"
+                    commit.add_tag(f"{Tag.DISTANCE_COLOR.value}{color}")
+                    if not config.highlight_authors and not config.highlight_stale:
+                        commit.add_tag(f"{Tag.COLOR.value}{color}")
+
+    # 3. Path highlighting
+    if config.highlight_path:
+        start_input, end_input = config.highlight_path
+
+        def find_node(query: str) -> Optional[GitCommit]:
+            for commit in graph:
+                if (
+                    query in commit.reference.branches
+                    or commit.reference.hash.startswith(query)
+                ):
+                    return commit
+            return None
+
+        start_node = find_node(start_input)
+        end_node = find_node(end_input)
+
+        if start_node and end_node:
+            path_graph = graph.subgraph_between(start_node, end_node)
+            path_nodes = set(path_graph)
+            for commit in path_nodes:
+                # Tag edges that connect nodes within this path
+                for parent, _ in graph.internal_depends_on(commit):
+                    if parent in path_nodes:
+                        commit.set_edge_attribute(parent, Tag.EDGE_PATH.value, True)
+
+    # 4. Divergence highlighting
+    if config.highlight_diverging_from:
+
+        def find_divergence_node(query: str) -> Optional[GitCommit]:
+            for commit in graph:
+                if (
+                    query in commit.reference.branches
+                    or commit.reference.hash.startswith(query)
+                ):
+                    return commit
+            return None
+
+        base_node = find_divergence_node(config.highlight_diverging_from)
+
+        if base_node:
+            base_reach = set(graph.ancestors(base_node))
+            base_reach.add(base_node)
+            other_reach = set()
+            for commit in graph:
+                if (
+                    commit.reference.branches
+                    and config.highlight_diverging_from not in commit.reference.branches
+                ):
+                    other_reach.update(graph.ancestors(commit))
+                    other_reach.add(commit)
+
+            behind_commits = base_reach - other_reach
+            for commit in behind_commits:
+                commit.add_tag(Tag.BEHIND.value)
+
+    # 5. Orphan highlighting
+    if config.highlight_orphans:
+        branch_reachable = set()
+        for commit in graph:
+            if commit.reference.branches:
+                branch_reachable.update(graph.ancestors(commit))
+                branch_reachable.add(commit)
+
+        for commit in graph:
+            if commit not in branch_reachable:
+                commit.add_tag(Tag.ORPHAN.value)
+
+    # 6. Stale branch detection
+    if config.highlight_stale:
+        now = time.time()
+        stale_threshold_sec = config.highlight_stale * 86400
+
+        for commit in graph:
+            if commit.reference.branches:
+                age_sec = now - commit.reference.timestamp
+                if age_sec > 0:
+                    ratio = min(age_sec / stale_threshold_sec, 1.0)
+                    gb_value = int(255 - (ratio * 85))  # 255 -> 170
+                    color = f"#ff{gb_value:02x}{gb_value:02x}"
+                    commit.add_tag(f"{Tag.STALE_COLOR.value}{color}")
+                    if not config.highlight_authors:
+                        commit.add_tag(f"{Tag.COLOR.value}{color}")
+
+    # 7. Long-running branch detection
+    if config.highlight_long_running is not None:
+        now = time.time()
+        # Use a small negative threshold for 0 to handle near-instant commits in tests
+        threshold_sec = config.highlight_long_running * 86400
+        if config.highlight_long_running == 0:
+            threshold_sec = -1
+
+        def find_base_tip(query: str) -> Optional[GitCommit]:
+            for commit in graph:
+                if (
+                    query in commit.reference.branches
+                    or commit.reference.hash.startswith(query)
+                ):
+                    return commit
+            return None
+
+        base_tip = find_base_tip(config.long_running_base)
+        if base_tip:
+            base_reach = set(graph.ancestors(base_tip))
+            base_reach.add(base_tip)
+
+            for tip in graph:
+                if (
+                    tip.reference.branches
+                    and config.long_running_base not in tip.reference.branches
+                ):
+                    branch_reach = set(graph.ancestors(tip))
+                    branch_reach.add(tip)
+
+                    unique_commits = branch_reach - base_reach
+                    if unique_commits:
+                        oldest_unique = min(
+                            unique_commits, key=lambda c: c.reference.timestamp
+                        )
+                        age_sec = now - oldest_unique.reference.timestamp
+
+                        if age_sec > threshold_sec:
+                            for commit in unique_commits:
+                                commit.add_tag(Tag.LONG_RUNNING.value)
+                                for parent, _ in graph.internal_depends_on(commit):
+                                    if parent in unique_commits or parent in base_reach:
+                                        commit.set_edge_attribute(
+                                            parent, Tag.EDGE_LONG_RUNNING.value, True
+                                        )

git_graphable/models.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class Tag(str, Enum):
+    GIT_COMMIT = "git_commit"
+    CRITICAL = "critical"
+    BEHIND = "behind"
+    ORPHAN = "orphan"
+    LONG_RUNNING = "long_running"
+    PATH_HIGHLIGHT = "path_highlight"
+
+    # Prefix tags
+    AUTHOR = "author:"
+    BRANCH = "branch:"
+    TAG = "tag:"
+    COLOR = "color:"
+    DISTANCE_COLOR = "distance_color:"
+    STALE_COLOR = "stale_color:"
+    AUTHOR_HIGHLIGHT = "author_highlight:"
+
+    # Edge attributes
+    EDGE_PATH = "highlight"
+    EDGE_LONG_RUNNING = "long_running_edge"

git_graphable/parser.py

@@ -0,0 +1,79 @@
+import subprocess
+import sys
+from typing import Dict, List, Optional
+
+from .core import CommitMetadata, GitCommit, GitLogConfig
+
+
+def run_git_command(args: List[str], cwd: Optional[str] = None) -> str:
+    """Run a git command and return its output."""
+    try:
+        return subprocess.check_output(
+            ["git"] + args, cwd=cwd, text=True, stderr=subprocess.PIPE
+        ).strip()
+    except subprocess.CalledProcessError as e:
+        print(f"Error running git command: {e.stderr}", file=sys.stderr)
+        raise
+
+
+def parse_ref_names(ref_names: str) -> tuple[List[str], List[str]]:
+    """Parse git log ref names (%D) into branches and tags."""
+    branches = []
+    tags = []
+    if not ref_names:
+        return branches, tags
+
+    parts = [p.strip() for p in ref_names.split(",")]
+    for part in parts:
+        if part.startswith("tag: "):
+            tags.append(part[len("tag: ") :])
+        elif "->" in part:
+            branches.append(part.split("->")[-1].strip())
+        elif part == "HEAD":
+            continue
+        else:
+            branches.append(part)
+    return branches, tags
+
+
+def get_git_log(repo_path: str, config: GitLogConfig) -> Dict[str, GitCommit]:
+    """Retrieve git log and parse into GitCommit objects."""
+    # Format: hash|parents|refs|timestamp|author|message
+    format_str = "%H|%P|%D|%at|%an|%s"
+    args = ["log", "--all", f"--format={format_str}"]
+    if config.simplify:
+        args.append("--simplify-by-decoration")
+    if config.limit:
+        args.append(f"-n {config.limit}")
+
+    output = run_git_command(args, cwd=repo_path)
+
+    commits: Dict[str, GitCommit] = {}
+    for line in output.split("\n"):
+        if not line:
+            continue
+        parts = line.split("|")
+        if len(parts) < 6:
+            continue
+
+        sha = parts[0]
+        parents = parts[1].split() if parts[1] else []
+        refs = parts[2]
+        timestamp = parts[3]
+        author = parts[4]
+        message = parts[5]
+
+        branches, tags = parse_ref_names(refs)
+
+        metadata = CommitMetadata(
+            hash=sha,
+            parents=parents,
+            branches=branches,
+            tags=tags,
+            timestamp=int(timestamp) if timestamp.isdigit() else 0,
+            author=author,
+            message=message,
+        )
+        commits[sha] = GitCommit(metadata, config)
+
+    return commits

git_graphable/styler.py

@@ -0,0 +1,246 @@
+from datetime import datetime
+from typing import Any, Optional
+
+from graphable import Graph, Graphable
+from graphable.enums import Engine
+from graphable.views import (
+    D2StylingConfig,
+    GraphvizStylingConfig,
+    MermaidStylingConfig,
+    PlantUmlStylingConfig,
+    export_topology_d2,
+    export_topology_d2_image,
+    export_topology_graphviz_dot,
+    export_topology_graphviz_image,
+    export_topology_mermaid_image,
+    export_topology_mermaid_mmd,
+    export_topology_plantuml,
+    export_topology_plantuml_image,
+)
+
+from .core import GitCommit, GitLogConfig
+from .models import Tag
+
+
+def get_node_text(
+    node: GitCommit, date_format: str = "%Y%m%d%H%M%S", engine: Engine = Engine.MERMAID
+) -> str:
+    """Generate node text for a commit, specialized for the visualization engine."""
+    meta = node.reference
+
+    def sanitize(s: str) -> str:
+        if engine == Engine.MERMAID:
+            for char in "[](){}|":
+                s = s.replace(char, " ")
+            return " ".join(s.split())
+        elif engine == Engine.D2:
+            return s.replace('"', '\\"')
+        return s
+
+    branches = [
+        sanitize(t[len(Tag.BRANCH.value) :])
+        for t in node.tags
+        if t.startswith(Tag.BRANCH.value)
+    ]
+    tags = [
+        sanitize(t[len(Tag.TAG.value) :])
+        for t in node.tags
+        if t.startswith(Tag.TAG.value)
+    ]
+    author_raw = next(
+        (
+            t[len(Tag.AUTHOR.value) :]
+            for t in node.tags
+            if t.startswith(Tag.AUTHOR.value)
+        ),
+        meta.author,
+    )
+    author = sanitize(author_raw)
+
+    display_label = f"{meta.hash[:7]}"
+
+    sep = " - "
+    newline = " - "
+    if engine in [Engine.D2, Engine.GRAPHVIZ, Engine.PLANTUML]:
+        newline = "\\n"
+
+    if branches:
+        display_label += f"{sep}{', '.join(branches)}"
+    if tags:
+        display_label += f"{sep}tags: {', '.join(tags)}"
+
+    dt_str = (
+        datetime.fromtimestamp(meta.timestamp).strftime(date_format)
+        if meta.timestamp
+        else ""
+    )
+    label = f"{display_label}{newline}{author}{newline}{dt_str}"
+
+    if engine == Engine.D2:
+        return f'"{label}"'
+
+    return label
+
+
+def get_generic_style(node: Graphable[Any], engine: Engine) -> dict[str, str]:
+    styles = {}
+    for tag in node.tags:
+        if tag.startswith(Tag.COLOR.value):
+            color = tag.split(":", 1)[1]
+            if engine == Engine.D2:
+                styles.update(
+                    {
+                        "fill": color,
+                        "font-color": "black"
+                        if color.startswith("#F") or color.startswith("#E")
+                        else "white",
+                    }
+                )
+            elif engine == Engine.GRAPHVIZ:
+                styles.update({"fillcolor": color, "style": "filled"})
+
+    if node.is_tagged(Tag.CRITICAL.value):
+        if engine == Engine.D2:
+            styles["stroke"] = "red"
+            styles["stroke-width"] = "6"
+            styles["double-border"] = "true"
+        elif engine == Engine.GRAPHVIZ:
+            styles["color"] = "red"
+            styles["penwidth"] = "5"
+            styles["style"] = styles.get("style", "") + ",bold"
+
+    if node.is_tagged(Tag.BEHIND.value):
+        if engine == Engine.D2:
+            styles["stroke"] = "orange"
+            styles["stroke-dash"] = "5"
+        elif engine == Engine.GRAPHVIZ:
+            styles["color"] = "orange"
+            styles["style"] = styles.get("style", "") + ",dashed"
+
+    if node.is_tagged(Tag.ORPHAN.value):
+        if engine == Engine.D2:
+            styles["stroke"] = "grey"
+            styles["stroke-dash"] = "3"
+            styles["opacity"] = "0.6"
+        elif engine == Engine.GRAPHVIZ:
+            styles["color"] = "grey"
+            styles["style"] = styles.get("style", "") + ",dashed"
+
+    if node.is_tagged(Tag.LONG_RUNNING.value):
+        if engine == Engine.D2:
+            styles["stroke"] = "purple"
+            styles["stroke-width"] = "4"
+        elif engine == Engine.GRAPHVIZ:
+            styles["color"] = "purple"
+            styles["penwidth"] = "3"
+
+    return styles
+
+
+def get_generic_link_style(
+    node: Graphable[Any], subnode: Graphable[Any], engine: Engine
+) -> dict[str, str]:
+    styles = {}
+    if node.edge_attributes(subnode).get(Tag.EDGE_PATH.value):
+        if engine == Engine.D2:
+            styles.update({"stroke": "#FFA500", "stroke-width": "6"})
+        elif engine == Engine.GRAPHVIZ:
+            styles.update({"color": "#FFA500", "penwidth": "4"})
+    elif node.edge_attributes(subnode).get(Tag.EDGE_LONG_RUNNING.value):
+        if engine == Engine.D2:
+            styles.update({"stroke": "purple", "stroke-width": "4"})
+        elif engine == Engine.GRAPHVIZ:
+            styles.update({"color": "purple", "penwidth": "3"})
+    return styles
+
+
+def export_graph(
+    graph: Graph[GitCommit],
+    output_path: str,
+    config: GitLogConfig,
+    engine: Engine = Engine.MERMAID,
+    as_image: bool = False,
+) -> None:
+    """Export the graph to a file using the specified engine."""
+
+    def label_fnc(n):
+        return get_node_text(n, config.date_format, engine)
+
+    def node_ref_fnc(n):
+        return n.reference.hash
+
+    if engine == Engine.MERMAID:
+
+        def mermaid_style(node: Graphable[Any]) -> Optional[str]:
+            style_parts = []
+            for tag in node.tags:
+                if tag.startswith(Tag.COLOR.value):
+                    color = tag.split(":", 1)[1]
+                    style_parts.append(f"fill:{color}")
+                    style_parts.append(
+                        "color:black"
+                        if color.startswith("#F") or color.startswith("#E")
+                        else "color:white"
+                    )
+            if node.is_tagged(Tag.CRITICAL.value):
+                style_parts.append("stroke:red,stroke-width:4px")
+            if node.is_tagged(Tag.BEHIND.value):
+                style_parts.append(
+                    "stroke:orange,stroke-width:2px,stroke-dasharray: 5 5"
+                )
+            if node.is_tagged(Tag.ORPHAN.value):
+                style_parts.append(
+                    "stroke:grey,stroke-width:1px,stroke-dasharray: 3 3,opacity:0.5"
+                )
+            if node.is_tagged(Tag.LONG_RUNNING.value) and not node.is_tagged(
+                Tag.CRITICAL.value
+            ):
+                style_parts.append("stroke:purple,stroke-width:3px")
+            return ",".join(style_parts) if style_parts else None
+
+        def mermaid_link_style(
+            node: Graphable[Any], subnode: Graphable[Any]
+        ) -> Optional[str]:
+            attrs = node.edge_attributes(subnode)
+            if attrs.get(Tag.EDGE_PATH.value):
+                return "stroke:#FFA500,stroke-width:4px"
+            if attrs.get(Tag.EDGE_LONG_RUNNING.value):
+                return "stroke:purple,stroke-width:3px"
+            return None
+
+        styling_config = MermaidStylingConfig(
+            node_ref_fnc=node_ref_fnc,
+            node_text_fnc=label_fnc,
+            node_style_fnc=mermaid_style,
+            link_style_fnc=mermaid_link_style,
+        )
+        fnc = export_topology_mermaid_image if as_image else export_topology_mermaid_mmd
+        graph.export(fnc, output_path, config=styling_config)
+    elif engine == Engine.GRAPHVIZ:
+        styling_config = GraphvizStylingConfig(
+            node_ref_fnc=node_ref_fnc,
+            node_label_fnc=label_fnc,
+            node_attr_fnc=lambda n: get_generic_style(n, Engine.GRAPHVIZ),
+            edge_attr_fnc=lambda n, sn: get_generic_link_style(n, sn, Engine.GRAPHVIZ),
+        )
+        fnc = (
+            export_topology_graphviz_image if as_image else export_topology_graphviz_dot
+        )
+        graph.export(fnc, output_path, config=styling_config)
+    elif engine == Engine.D2:
+        styling_config = D2StylingConfig(
+            node_ref_fnc=node_ref_fnc,
+            node_label_fnc=label_fnc,
+            node_style_fnc=lambda n: get_generic_style(n, Engine.D2),
+            edge_style_fnc=lambda n, sn: get_generic_link_style(n, sn, Engine.D2),
+        )
+        fnc = export_topology_d2_image if as_image else export_topology_d2
+        graph.export(fnc, output_path, config=styling_config)
+    elif engine == Engine.PLANTUML:
+        styling_config = PlantUmlStylingConfig(
+            node_ref_fnc=node_ref_fnc, node_label_fnc=label_fnc
+        )
+        fnc = export_topology_plantuml_image if as_image else export_topology_plantuml
+        graph.export(fnc, output_path, config=styling_config)
+    else:
+        graph.write(output_path)

git_graphable-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: git-graphable
+Version: 0.1.0
+Summary: A powerful tool to convert Git commit history into beautiful flowcharts.
+Project-URL: Homepage, https://github.com/TheTrueSCU/git-graphable
+Project-URL: Issues, https://github.com/TheTrueSCU/git-graphable/issues
+Project-URL: Repository, https://github.com/TheTrueSCU/git-graphable
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Keywords: analysis,d2,git,graph,hygiene,mermaid,topology,visualization
+Requires-Python: >=3.13
+Requires-Dist: graphable>=0.6.0
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.12.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# Git Graphable
+
+A powerful Python tool to convert Git commit history into beautiful, interactive flowcharts using the `graphable` library. Supporting Mermaid, D2, Graphviz, and PlantUML.
+
+## Git Plugin Support
+When installed in your PATH, you can use this as a native Git plugin:
+```bash
+git graphable .
+```
+
+## Features
+
+- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or PlantUML (.puml).
+- **Automatic Visualization**: Generates and opens an image (SVG/PNG) automatically if no output is specified.
+- **Advanced Highlighting**: Visualize author patterns, topological distance, and specific merge paths.
+- **Hygiene Analysis**: Identify commits that are "behind" a base branch with divergence analysis.
+- **Flexible Input**: Works with local repository paths or remote Git URLs.
+- **Dual CLI**: Modern Rich/Typer interface with a robust argparse fallback for bare environments.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv sync --all-extras
+```
+
+## Usage
+
+For a complete reference of all command-line options, see the [USAGE.md](USAGE.md) file.
+
+```bash
+# Basic usage (opens a Mermaid image)
+uv run git-graphable .
+
+# Specify an engine and output file
+uv run git-graphable https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+
+# Simplify the graph (only show branches/tags)
+uv run git-graphable . --simplify
+```
+
+## Highlighting Options
+
+Git Graphable provides several ways to highlight commits and relationships. Multiple options can be combined to layer information.
+
+| Option | Target | Effect | Conflicts With |
+| :--- | :--- | :--- | :--- |
+| `--highlight-authors` | **Fill** | Unique color per author | Distance, Stale |
+| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, Stale |
+| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, Distance |
+| `--highlight-path` | **Edge** | Thick Orange edge connecting nodes | None |
+| `--highlight-critical` | **Stroke** | Thick Red Solid outline | None |
+| `--highlight-diverging-from` | **Stroke** | Orange Dashed outline | None |
+| `--highlight-orphans` | **Stroke** | Grey Dashed outline | None |
+| `--highlight-long-running` | **Stroke/Edge** | Purple outline and thick Purple edge | None |
+
+### Highlighting Priorities
+- **Fill**: `--highlight-authors`, `--highlight-distance-from`, and `--highlight-stale` are mutually exclusive.
+- **Edge**: Path highlighting (Thick Orange) takes priority over Long-Running highlighting (Thick Purple).
+- **Stroke**: Critical outlines (Thick Red) take priority over all other outlines (Divergence, Orphan, Long-Running).
+
+## Advanced Examples
+
+### Divergence Analysis (Hygiene)
+Highlight commits that exist in `main` but are missing from your feature branches:
+```bash
+uv run git-graphable . --highlight-diverging-from main
+```
+
+### Path Highlighting
+See the exact sequence of commits between a feature branch and a specific tag:
+```bash
+uv run git-graphable . --highlight-path develop..v1.0.0
+```
+
+### Large Repositories
+For repositories with long histories, use the `--limit` flag to keep the graph readable and avoid engine rendering limits:
+```bash
+uv run git-graphable . --limit 100 --highlight-authors
+```
+
+## Development
+
+Run tests and linting:
+```bash
+just check
+```
+
+### CI/CD
+This project uses GitHub Actions for continuous integration and automated publishing:
+- **CI**: Runs `just check` on all pushes and PRs to `main`.
+- **Publish**: Automatically builds and publishes to PyPI when a version tag (`v*`) is pushed.

git_graphable-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+git_graphable/__init__.py,sha256=6LX5QNSP5_QZnebjIPFZK9uR_flXuB9eP_JzDPFnwXw,337
+git_graphable/cli.py,sha256=H7vRPQhIgRVMvHJzq33PzCuWxVoDXQtjd59U0XupqSs,13929
+git_graphable/core.py,sha256=KPA5mYQoNq5yH_FkvuxAdJpK_4a464GSuyo3NhHCBqc,4150
+git_graphable/highlighter.py,sha256=0XP8204XShcXhflapUOK9yGoUKbJvV-ZCv0QWSz0Tdo,7761
+git_graphable/models.py,sha256=fUPdXylbMY2IbLokudocL60d-Ct9iXnGSJYyG7flD2o,531
+git_graphable/parser.py,sha256=rbS0n0ZGCKboEV8YB1FgDN2BbADmB_pWN0puOhPMaVU,2367
+git_graphable/styler.py,sha256=crt2ow1YIyaoknOTHvp6AeVSBT5NxL3BsmfnNSRDsso,8582
+git_graphable-0.1.0.dist-info/METADATA,sha256=o8TE2uWzC7Ku7-TSWoFIjr0lX6NrE3U4nvjghdSJjb0,4210
+git_graphable-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+git_graphable-0.1.0.dist-info/entry_points.txt,sha256=zQ1J0MYhxnambuj__xHwpr_KBYH-GYxumYkuntJw6WU,57
+git_graphable-0.1.0.dist-info/RECORD,,

git_graphable-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_graphable-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-graphable = git_graphable.cli:main