diffstory 0.2.0__py3-none-any.whl

diffstory/__init__.py

@@ -0,0 +1,3 @@
+"""DiffStory — Transform Git diffs into rich, interactive HTML reports."""
+
+__version__ = "0.2.0"

diffstory/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running diffstory with `python -m diffstory`."""
+from diffstory.cli import main
+
+if __name__ == "__main__":
+    main()

diffstory/cli.py

@@ -0,0 +1,402 @@
+"""CLI entry point for DiffStory — parse arguments, gather diffs, generate reports."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from diffstory import __version__
+from diffstory.diff_parser import parse_diff
+from diffstory.git_utils import (
+    GitError,
+    check_git_repo,
+    get_diff,
+    get_diff_with_renames,
+)
+from diffstory.html_generator import generate_report
+
+
+# ---------------------------------------------------------------------------
+# Config file (.diffstory.toml) loader
+# ---------------------------------------------------------------------------
+DEFAULT_CONFIG_PATH = Path.home() / ".diffstory.toml"
+LOCAL_CONFIG_PATH = Path.cwd() / ".diffstory.toml"
+
+
+def _load_config() -> dict:
+    """Load .diffstory.toml config from project or home directory.
+
+    Returns a dict with keys that serve as defaults for CLI flags.
+    """
+    config: dict = {}
+
+    for cfg_path in (LOCAL_CONFIG_PATH, DEFAULT_CONFIG_PATH):
+        if cfg_path.exists():
+            try:
+                text = cfg_path.read_text(encoding="utf-8")
+                config.update(_parse_toml_like(text))
+            except Exception:
+                pass  # ignore broken config files
+    return config
+
+
+def _parse_toml_like(text: str) -> dict:
+    """Minimal TOML parser — enough for our trivial config schema."""
+    result: dict = {}
+    current_section: Optional[str] = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("[") and stripped.endswith("]"):
+            current_section = stripped[1:-1].strip().lower()
+            continue
+        if "=" in stripped:
+            key, _, val = stripped.partition("=")
+            key = key.strip().lower()
+            val = val.strip().strip('"').strip("'")
+            # Lower-case boolean-ish strings
+            if val.lower() in ("true", "yes", "on"):
+                val = True
+            elif val.lower() in ("false", "no", "off"):
+                val = False
+            else:
+                try:
+                    val = int(val)
+                except ValueError:
+                    pass
+            full_key = f"{current_section}.{key}" if current_section else key
+            result[full_key] = val
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="diffstory",
+        description="Transform Git diffs into rich, interactive, self-contained HTML reports.",
+        epilog=(
+            "Examples:\\n"
+            "  diffstory                    # working tree diff\\n"
+            "  diffstory --staged           # staged changes\\n"
+            "  diffstory HEAD~3 HEAD        # commit comparison\\n"
+            "  diffstory main feature       # branch comparison\\n"
+            "  diffstory -o report.html     # custom output file\\n"
+            "  diffstory --json             # JSON export\\n"
+            "  diffstory HEAD~3 HEAD src/   # restrict to path"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"diffstory {__version__}",
+    )
+
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        help="Show staged changes (equivalent to git diff --cached)",
+    )
+
+    parser.add_argument(
+        "revisions",
+        nargs="*",
+        metavar="REVISION",
+        help="Optional commit range: REVISION [REVISION] [-- path]",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="diffstory-report.html",
+        metavar="FILE",
+        help="Output file path (default: diffstory-report.html)",
+    )
+
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Export diff data as JSON",
+    )
+
+    parser.add_argument(
+        "--md",
+        action="store_true",
+        help="Export diff summary as Markdown",
+    )
+
+    parser.add_argument(
+        "--csv",
+        action="store_true",
+        help="Export diff stats as CSV",
+    )
+
+    parser.add_argument(
+        "--diff",
+        metavar="FILE",
+        help="Generate report from a diff file directly (no git repository needed)",
+    )
+
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        default=None,
+        help="Show git commands and timing information",
+    )
+
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=None,
+        help="Show detailed debug output including stack traces",
+    )
+
+    return parser
+
+
+def _parse_revisions(args: argparse.Namespace) -> tuple[Optional[str], Optional[str], Optional[list[str]]]:
+    """Extract commit range and optional path restriction from positional args.
+
+    Supports:
+        []                        -> working tree
+        [COMMIT_A, COMMIT_B]      -> commit comparison
+        [COMMIT_A, COMMIT_B, --, path] -> restricted comparison
+        [COMMIT]                  -> comparison with HEAD
+    """
+    revisions = args.revisions
+    paths: Optional[list[str]] = None
+    commit_a: Optional[str] = None
+    commit_b: Optional[str] = None
+
+    if not revisions:
+        return None, None, None
+
+    # Check for path separator
+    if "--" in revisions:
+        sep_idx = revisions.index("--")
+        revisions = revisions[:sep_idx]
+        paths = revisions[sep_idx + 1:]
+
+    if len(revisions) == 1:
+        commit_a = revisions[0]
+    elif len(revisions) >= 2:
+        commit_a = revisions[0]
+        commit_b = revisions[1]
+
+    return commit_a, commit_b, paths
+
+
+def generate_exports(
+    files,
+    output_path: str,
+    json_export: bool = False,
+    md_export: bool = False,
+    csv_export: bool = False,
+) -> None:
+    """Generate non-HTML export formats."""
+    base = Path(output_path)
+    stem = base.stem
+
+    if json_export:
+        _export_json(files, base.with_name(stem + ".json"))
+    if md_export:
+        _export_markdown(files, base.with_name(stem + ".md"))
+    if csv_export:
+        _export_csv(files, base.with_name(stem + ".csv"))
+
+
+def _export_json(files, output_path: Path) -> None:
+    """Export diff data as JSON."""
+    import json
+
+    data = []
+    for f in files:
+        file_data = {
+            "old_path": f.old_path,
+            "new_path": f.new_path,
+            "status": f.status,
+            "hunks": [],
+        }
+        for hunk in f.hunks:
+            hunk_data = {
+                "old_start": hunk.old_start,
+                "old_count": hunk.old_count,
+                "new_start": hunk.new_start,
+                "new_count": hunk.new_count,
+                "lines": [],
+            }
+            for line in hunk.lines:
+                hunk_data["lines"].append({
+                    "type": line.line_type,
+                    "content": line.content,
+                    "old_lineno": line.old_lineno,
+                    "new_lineno": line.new_lineno,
+                })
+            file_data["hunks"].append(hunk_data)
+        data.append(file_data)
+
+    output_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    print(f"  JSON: {output_path}")
+
+
+def _export_markdown(files, output_path: Path) -> None:
+    """Export diff summary as Markdown."""
+    lines = ["# DiffStory Report\n"]
+    for f in files:
+        adds = sum(1 for h in f.hunks for l in h.lines if l.line_type == "addition")
+        dels = sum(1 for h in f.hunks for l in h.lines if l.line_type == "deletion")
+        status_icon = {"added": "+", "deleted": "-", "renamed": "→", "modified": "~"}.get(f.status, "~")
+        lines.append(f"## {status_icon} `{f.display_path}`")
+        lines.append(f"- **Status:** {f.status}")
+        lines.append(f"- **Additions:** {adds}")
+        lines.append(f"- **Deletions:** {dels}\n")
+        for hunk in f.hunks:
+            lines.append(f"### @@ {hunk.old_start},{hunk.old_count} {hunk.new_start},{hunk.new_count} @@")
+            if hunk.header:
+                lines.append(f"_{hunk.header}_\n")
+            for line in hunk.lines:
+                prefix = {"context": " ", "addition": "+", "deletion": "-"}[line.line_type]
+                lines.append(f"    {prefix} {line.content}")
+            lines.append("")
+
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+    print(f"  Markdown: {output_path}")
+
+
+def _export_csv(files, output_path: Path) -> None:
+    """Export diff stats as CSV."""
+    rows = ["file,status,additions,deletions"]
+    for f in files:
+        adds = sum(1 for h in f.hunks for l in h.lines if l.line_type == "addition")
+        dels = sum(1 for h in f.hunks for l in h.lines if l.line_type == "deletion")
+        rows.append(f"{f.display_path},{f.status},{adds},{dels}")
+
+    output_path.write_text("\n".join(rows) + "\n", encoding="utf-8")
+    print(f"  CSV: {output_path}")
+
+
+def _read_diff_from_file(path: str) -> str:
+    """Read diff content from a file."""
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        print(f"Error: Diff file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error reading diff file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    """Main entry point for the diffstory CLI."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    # Load config file for defaults
+    config = _load_config()
+    verbose = args.verbose if args.verbose is not None else config.get("cli.verbose", False)
+    debug = args.debug if args.debug is not None else config.get("cli.debug", False)
+
+    if debug:
+        verbose = True  # debug implies verbose
+
+    # Handle --diff flag (read diff from file, no git needed)
+    if args.diff:
+        if verbose:
+            print(f"  Reading diff file: {args.diff}")
+        diff_text = _read_diff_from_file(args.diff)
+        commit_a = None
+        commit_b = None
+        files = parse_diff(diff_text)
+        if not files:
+            print("No parseable diff files found.")
+            sys.exit(0)
+        has_exports = args.json or args.md or args.csv
+        if has_exports:
+            generate_exports(files, args.output, args.json, args.md, args.csv)
+        try:
+            report_path = generate_report(files, output_path=args.output, repo_name="diff", verbose=verbose)
+        except Exception as e:
+            if debug:
+                import traceback
+                traceback.print_exc()
+            print(f"Error generating report: {e}", file=sys.stderr)
+            sys.exit(1)
+        print(f"\\n  HTML: {report_path}")
+        print("  Report generated successfully!")
+        return
+
+    # Validate Git repository
+    if not check_git_repo():
+        print("Error: Not inside a Git repository.", file=sys.stderr)
+        sys.exit(1)
+
+    # Parse revisions
+    commit_a, commit_b, paths = _parse_revisions(args)
+
+    if verbose:
+        rev_desc = "staged" if args.staged else "working tree"
+        if commit_a and commit_b:
+            rev_desc = f"{commit_a}..{commit_b}"
+        elif commit_a:
+            rev_desc = commit_a
+        print(f"  Diff: {rev_desc}")
+
+    try:
+        # Get diff
+        diff_text = get_diff_with_renames(
+            staged=args.staged,
+            commit_a=commit_a,
+            commit_b=commit_b,
+            paths=paths,
+        )
+    except GitError as e:
+        print(f"Error fetching diff: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if not diff_text.strip():
+        print("No changes detected.")
+        sys.exit(0)
+
+    if verbose:
+        print(f"  Diff size: {len(diff_text)} bytes")
+
+    # Parse diff
+    files = parse_diff(diff_text)
+
+    if not files:
+        print("No parseable diff files found.")
+        sys.exit(0)
+
+    if verbose:
+        print(f"  Files changed: {len(files)}")
+
+    # Generate exports if requested
+    has_exports = args.json or args.md or args.csv
+    if has_exports:
+        generate_exports(files, args.output, args.json, args.md, args.csv)
+
+    # Always generate HTML report
+    try:
+        report_path = generate_report(
+            files,
+            output_path=args.output,
+            staged=args.staged,
+            commit_a=commit_a,
+            commit_b=commit_b,
+            verbose=verbose,
+        )
+    except Exception as e:
+        if debug:
+            import traceback
+            traceback.print_exc()
+        print(f"Error generating report: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\\n  HTML: {report_path}")
+    print("  Report generated successfully!")

diffstory/diff_parser.py

@@ -0,0 +1,298 @@
+"""Parse unified diff output into structured Python data."""
+
+from __future__ import annotations
+
+import difflib
+import re
+from typing import Optional
+
+
+# Image extensions that can be previewed inline
+IMAGE_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".bmp", ".ico"})
+
+
+class DiffFile:
+    """Represents a single file in a diff."""
+
+    def __init__(
+        self,
+        old_path: str,
+        new_path: str,
+        status: str = "modified",
+        old_mode: Optional[str] = None,
+        new_mode: Optional[str] = None,
+        similarity: Optional[int] = None,
+    ):
+        self.old_path = old_path
+        self.new_path = new_path
+        self.display_path = new_path if new_path != "/dev/null" else old_path
+        self.status = status  # added, deleted, modified, renamed
+        self.old_mode = old_mode
+        self.new_mode = new_mode
+        self.similarity = similarity
+        self.hunks: list[Hunk] = []
+        self.is_binary_file = False  # set True when binary, no hunks
+
+    @property
+    def is_binary(self) -> bool:
+        return not self.hunks and self.status != "added"
+
+    @property
+    def is_image(self) -> bool:
+        """Check if the file path looks like a known image type."""
+        ext = "." + self.display_path.rsplit(".", 1)[-1].lower() if "." in self.display_path else ""
+        return ext in IMAGE_EXTENSIONS
+
+
+class Hunk:
+    """Represents a single hunk (@@ ... @@ section) in a diff."""
+
+    def __init__(
+        self,
+        old_start: int,
+        old_count: int,
+        new_start: int,
+        new_count: int,
+        header: str = "",
+    ):
+        self.old_start = old_start
+        self.old_count = old_count
+        self.new_start = new_start
+        self.new_count = new_count
+        self.header = header
+        self.lines: list[DiffLine] = []
+
+
+class DiffLine:
+    """Represents a single line in a diff."""
+
+    TYPE_CONTEXT = "context"
+    TYPE_ADDITION = "addition"
+    TYPE_DELETION = "deletion"
+
+    def __init__(
+        self,
+        line_type: str,
+        content: str,
+        old_lineno: Optional[int] = None,
+        new_lineno: Optional[int] = None,
+    ):
+        self.line_type = line_type
+        self.content = content
+        self.old_lineno = old_lineno
+        self.new_lineno = new_lineno
+        self.word_diff: Optional[WordDiff] = None
+
+
+class WordDiff:
+    """Word-level diff for inline edit mode."""
+
+    def __init__(self, parts: list[dict]):
+        self.parts = parts  # [{"text": "...", "type": "equal|add|delete"}, ...]
+
+
+def parse_diff(diff_text: str) -> list[DiffFile]:
+    """Parse a unified diff string into a list of DiffFile objects."""
+    files: list[DiffFile] = []
+    current_file: Optional[DiffFile] = None
+    current_hunk: Optional[Hunk] = None
+
+    old_lineno = 0
+    new_lineno = 0
+
+    for line in diff_text.splitlines():
+        # Check for file headers
+        if line.startswith("diff --git "):
+            current_file = _parse_diff_header(line)
+            files.append(current_file)
+            current_hunk = None
+            old_lineno = 0
+            new_lineno = 0
+            continue
+
+        if current_file is None:
+            continue
+
+        # Check for rename/copy info
+        if line.startswith("rename from "):
+            current_file.old_path = line[12:]
+            current_file.status = "renamed"
+            continue
+        if line.startswith("rename to "):
+            current_file.new_path = line[10:]
+            current_file.display_path = current_file.new_path
+            current_file.status = "renamed"
+            continue
+
+        # Similarity index
+        if line.startswith("similarity index "):
+            try:
+                current_file.similarity = int(line[17:].rstrip("%"))
+            except ValueError:
+                pass
+            continue
+
+        # Binary files
+        if line.startswith("Binary files ") or line == "Binary files differ":
+            continue
+
+        # New file mode
+        if line.startswith("new file mode "):
+            current_file.status = "added"
+            current_file.new_mode = line[14:]
+            continue
+
+        # Deleted file mode
+        if line.startswith("deleted file mode "):
+            current_file.status = "deleted"
+            current_file.old_mode = line[18:]
+            continue
+
+        # Old mode / new mode
+        if line.startswith("old mode "):
+            current_file.old_mode = line[9:]
+            continue
+        if line.startswith("new mode "):
+            current_file.new_mode = line[9:]
+            continue
+
+        # Index line
+        if line.startswith("index "):
+            continue
+
+        # --- / +++ lines
+        if line.startswith("--- "):
+            continue
+        if line.startswith("+++ "):
+            continue
+
+        # Hunk header
+        if line.startswith("@@"):
+            current_hunk = _parse_hunk_header(line)
+            current_file.hunks.append(current_hunk)
+            old_lineno = current_hunk.old_start
+            new_lineno = current_hunk.new_start
+            continue
+
+        if current_hunk is None:
+            continue
+
+        # Diff content lines
+        if line.startswith("+"):
+            diff_line = DiffLine(DiffLine.TYPE_ADDITION, line[1:], new_lineno=new_lineno)
+            current_hunk.lines.append(diff_line)
+            new_lineno += 1
+        elif line.startswith("-"):
+            diff_line = DiffLine(DiffLine.TYPE_DELETION, line[1:], old_lineno=old_lineno)
+            current_hunk.lines.append(diff_line)
+            old_lineno += 1
+        else:
+            # Context line (starts with space)
+            content = line[1:] if len(line) > 1 else ""
+            diff_line = DiffLine(DiffLine.TYPE_CONTEXT, content, old_lineno, new_lineno)
+            current_hunk.lines.append(diff_line)
+            old_lineno += 1
+            new_lineno += 1
+
+    return files
+
+
+def _parse_diff_header(line: str) -> DiffFile:
+    """Parse 'diff --git a/path b/path' header."""
+    # Extract paths after 'diff --git '
+    rest = line[11:]
+    parts = rest.split(" b/", 1)
+    if len(parts) == 2:
+        old_path = parts[0][2:] if parts[0].startswith("a/") else parts[0]
+        new_path = parts[1]
+    else:
+        old_path = rest
+        new_path = rest
+    return DiffFile(old_path, new_path)
+
+
+HUNK_HEADER_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)")
+
+
+def _parse_hunk_header(line: str) -> Hunk:
+    """Parse @@ -old,count +new,count @@ header."""
+    match = HUNK_HEADER_RE.match(line)
+    if match:
+        old_start = int(match.group(1))
+        old_count = int(match.group(2) or 1)
+        new_start = int(match.group(3))
+        new_count = int(match.group(4) or 1)
+        header = match.group(5).strip()
+        return Hunk(old_start, old_count, new_start, new_count, header)
+    return Hunk(0, 0, 0, 0)
+
+
+def compute_word_diff(old_line: str, new_line: str) -> WordDiff:
+    """Compute word-level diff between two lines for inline edit mode."""
+    # Tokenize words (split on word boundaries, preserving whitespace)
+    old_tokens = _tokenize(old_line)
+    new_tokens = _tokenize(new_line)
+
+    matcher = difflib.SequenceMatcher(None, old_tokens, new_tokens)
+    parts: list[dict] = []
+
+    for op, old_start, old_end, new_start, new_end in matcher.get_opcodes():
+        if op == "equal":
+            for t in old_tokens[old_start:old_end]:
+                parts.append({"text": t, "type": "equal"})
+        elif op == "replace":
+            # Show deleted tokens then added tokens
+            for t in old_tokens[old_start:old_end]:
+                parts.append({"text": t, "type": "delete"})
+            for t in new_tokens[new_start:new_end]:
+                parts.append({"text": t, "type": "add"})
+        elif op == "delete":
+            for t in old_tokens[old_start:old_end]:
+                parts.append({"text": t, "type": "delete"})
+        elif op == "insert":
+            for t in new_tokens[new_start:new_end]:
+                parts.append({"text": t, "type": "add"})
+
+    return WordDiff(parts)
+
+
+def _tokenize(text: str) -> list[str]:
+    """Tokenize text into words, preserving whitespace."""
+    tokens: list[str] = []
+    current = ""
+    for char in text:
+        if char.isspace():
+            if current:
+                tokens.append(current)
+                current = ""
+            tokens.append(char)
+        else:
+            current += char
+    if current:
+        tokens.append(current)
+    return tokens
+
+
+def compute_word_diffs(file: DiffFile) -> None:
+    """Compute word-level diffs for all applicable lines in a file."""
+    for hunk in file.hunks:
+        additions: list[DiffLine] = []
+        deletions: list[DiffLine] = []
+
+        for line in hunk.lines:
+            if line.line_type == DiffLine.TYPE_ADDITION:
+                additions.append(line)
+            elif line.line_type == DiffLine.TYPE_DELETION:
+                deletions.append(line)
+
+        # Pair additions with deletions (simple approach: match by position)
+        add_idx = 0
+        del_idx = 0
+        while add_idx < len(additions) and del_idx < len(deletions):
+            add_line = additions[add_idx]
+            del_line = deletions[del_idx]
+            word_diff = compute_word_diff(del_line.content, add_line.content)
+            add_line.word_diff = word_diff
+            del_line.word_diff = word_diff
+            add_idx += 1
+            del_idx += 1