diffstory 0.2.0__tar.gz → 0.3.0__tar.gz

diffstory-0.3.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: diffstory
+Version: 0.3.0
+Summary: Transform Git diffs into rich, interactive, self-contained HTML reports
+License: MIT
+Project-URL: Homepage, https://github.com/lakshayjindal/diffstory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pygments>=2.10
+
+# DiffStory
+
+**Transform Git diffs into rich, interactive, self-contained HTML reports.**
+
+DiffStory turns any `git diff` into a beautiful, portable HTML report that answers not just *what* changed, but *who* changed it, *when*, and *why* — all offline, in a single file you can share, archive, or email.
+
+```bash
+pip install diffstory
+cd my-repo
+diffstory --staged -o review.html
+# Open review.html in any browser — zero setup required
+```
+
+---
+
+## Features
+
+### Three Diff Views
+
+| View | Description |
+|---|---|
+| **Unified** | Classic git-style diff with line numbers and syntax highlighting |
+| **Side-by-Side** | Original (left) and modified (right) columns, visually aligned |
+| **Inline Edit** | Word-level diff — shows exact token changes inline, green additions and red strikethrough removals. No more mental diffing. |
+
+Switch between views instantly with the toolbar or keyboard shortcuts — no regeneration needed.
+
+### Blame & Provenance
+
+Every changed line carries its history. **Hover** any line to see a tooltip with author name, commit hash, subject, date, and relative time (e.g. "2h ago"). **Click** any line to open the commit drawer — a side panel with full metadata: commit body, author, committer, parents, files changed, insertions, and deletions.
+
+### Search & Filtering
+
+- **Global search** — find files by name, author, commit subject, or code content with live results
+- **Filter chips** — narrow the view by file extension (`.py`, `.js`, `.html`, etc.) or change type (added, deleted, modified, renamed)
+- **File sidebar** — searchable file list with add/delete indicators and collapse/expand
+
+### Statistics Dashboard
+
+A floating panel showing:
+- Files changed, additions, deletions
+- Added / deleted / modified / renamed file counts
+- Author count and commit count (from blame)
+- Contributor breakdown with commit counts
+- Top 10 most-changed files
+
+### Keyboard Navigation
+
+| Key | Action |
+|---|---|
+| `J` / `K` | Next / previous file |
+| `F` or `/` | Focus global search |
+| `U` / `S` / `I` | Unified / Side-by-side / Inline view |
+| `D` | Toggle light/dark theme |
+| `Esc` | Close drawer → close search → close stats |
+
+### Deep Linking
+
+Link directly to specific files and lines: `#file-0` scrolls to the first file, `#L-0-42` scrolls to line 42 in the first file. Shareable, stable anchors.
+
+### Binary File Support
+
+Binary files are detected and displayed with meaningful placeholders — image files get a preview icon, other binaries show metadata — preventing crashes and keeping the report clean.
+
+### Customization
+
+- **Light/Dark themes** — toggle instantly, persists across sessions
+- **Config file** — `~/.diffstory.toml` or `.diffstory.toml` in your project sets defaults for verbose mode, debug output, and more
+- **`--verbose` / `--debug` flags** — see what's happening under the hood
+
+### Export Formats
+
+Alongside the HTML report, export structured data:
+
+```bash
+diffstory --staged --json --md --csv
+```
+
+---
+
+## Installation
+
+```bash
+pip install diffstory
+```
+
+**Requires:** Python 3.10+ and Git.
+
+To install from source:
+
+```bash
+git clone https://github.com/lakshayjindal/diffstory.git
+cd diffstory
+pip install -e .
+```
+
+---
+
+## Usage
+
+```bash
+# Working tree diff
+diffstory
+
+# Staged changes (what will be committed)
+diffstory --staged
+
+# Compare commits
+diffstory HEAD~3 HEAD
+
+# Compare branches
+diffstory main feature-branch
+
+# Compare revisions with path restriction
+diffstory HEAD~3 HEAD src/
+
+# Generate from a diff file directly (no git repo needed)
+diffstory --diff /path/to/patch.diff
+
+# Custom output file
+diffstory -o my-review.html
+
+# Multiple export formats at once
+diffstory --staged --json --md --csv -o release-v2.0
+
+# Verbose mode
+diffstory --staged --verbose
+
+# Show version
+diffstory --version
+```
+
+### Config File Example
+
+Create `~/.diffstory.toml` or `.diffstory.toml` in your project:
+
+```toml
+[cli]
+verbose = true
+debug = false
+```
+
+---
+
+## HTML Report
+
+Every generated HTML report is **fully self-contained**:
+
+- All CSS inlined — no external stylesheets
+- All JavaScript inlined — no external scripts
+- All data (blame, commits, search index) embedded as JSON
+- Works offline in any modern browser
+- Safe to email, archive, or include in audit evidence
+- Zero external dependencies at runtime
+
+Open it, share it, attach it to a PR, or file it for compliance. It just works.
+
+---
+
+## Project Structure
+
+```
+diffstory/
+├── pyproject.toml              # Build config & CLI entry point
+├── README.md
+├── requirements.md             # Full product requirements & spec
+├── deploy.sh                   # Build & publish script
+├── .github/workflows/publish.yml  # CI/CD for PyPI publishing
+├── src/diffstory/
+│   ├── __init__.py             # Package version
+│   ├── __main__.py             # python -m diffstory support
+│   ├── cli.py                  # CLI argument parsing & orchestration
+│   ├── git_utils.py            # Git subprocess wrappers (diff, blame, log)
+│   ├── diff_parser.py          # Unified diff parser → structured data
+│   ├── syntax.py               # Pygments syntax highlighting
+│   └── html_generator.py       # Self-contained HTML report generation
+└── tests/
+    └── __init__.py
+```
+
+---
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Test with a quick repo
+cd /tmp && mkdir test-diffstory && cd test-diffstory
+git init && echo "hello" > test.py && git add -A && git commit -m "init"
+echo "world" >> test.py
+diffstory --staged
+
+# Build the package
+python -m build
+
+# Deploy (version bump, build, publish)
+./deploy.sh           # patch bump
+./deploy.sh minor     # minor bump
+```
+
+---
+
+## Design Philosophy
+
+DiffStory was built to answer five questions about every changed line:
+
+> **What changed? Who changed it? When? Why? How did it evolve?**
+
+It consolidates `git diff`, `git blame`, `git log`, and GitHub-style review UX into a single, portable artifact — no server, no accounts, no data leaving your machine.
+
+### Security
+
+- Never uploads code or transmits data
+- No telemetry, no analytics, no accounts
+- No external API calls by default
+- Never modifies your repository
+- Generated reports are safe for air-gapped environments, client deliverables, and compliance audits
+
+---
+
+## License
+
+MIT

diffstory-0.3.0/README.md

@@ -0,0 +1,225 @@
+# DiffStory
+
+**Transform Git diffs into rich, interactive, self-contained HTML reports.**
+
+DiffStory turns any `git diff` into a beautiful, portable HTML report that answers not just *what* changed, but *who* changed it, *when*, and *why* — all offline, in a single file you can share, archive, or email.
+
+```bash
+pip install diffstory
+cd my-repo
+diffstory --staged -o review.html
+# Open review.html in any browser — zero setup required
+```
+
+---
+
+## Features
+
+### Three Diff Views
+
+| View | Description |
+|---|---|
+| **Unified** | Classic git-style diff with line numbers and syntax highlighting |
+| **Side-by-Side** | Original (left) and modified (right) columns, visually aligned |
+| **Inline Edit** | Word-level diff — shows exact token changes inline, green additions and red strikethrough removals. No more mental diffing. |
+
+Switch between views instantly with the toolbar or keyboard shortcuts — no regeneration needed.
+
+### Blame & Provenance
+
+Every changed line carries its history. **Hover** any line to see a tooltip with author name, commit hash, subject, date, and relative time (e.g. "2h ago"). **Click** any line to open the commit drawer — a side panel with full metadata: commit body, author, committer, parents, files changed, insertions, and deletions.
+
+### Search & Filtering
+
+- **Global search** — find files by name, author, commit subject, or code content with live results
+- **Filter chips** — narrow the view by file extension (`.py`, `.js`, `.html`, etc.) or change type (added, deleted, modified, renamed)
+- **File sidebar** — searchable file list with add/delete indicators and collapse/expand
+
+### Statistics Dashboard
+
+A floating panel showing:
+- Files changed, additions, deletions
+- Added / deleted / modified / renamed file counts
+- Author count and commit count (from blame)
+- Contributor breakdown with commit counts
+- Top 10 most-changed files
+
+### Keyboard Navigation
+
+| Key | Action |
+|---|---|
+| `J` / `K` | Next / previous file |
+| `F` or `/` | Focus global search |
+| `U` / `S` / `I` | Unified / Side-by-side / Inline view |
+| `D` | Toggle light/dark theme |
+| `Esc` | Close drawer → close search → close stats |
+
+### Deep Linking
+
+Link directly to specific files and lines: `#file-0` scrolls to the first file, `#L-0-42` scrolls to line 42 in the first file. Shareable, stable anchors.
+
+### Binary File Support
+
+Binary files are detected and displayed with meaningful placeholders — image files get a preview icon, other binaries show metadata — preventing crashes and keeping the report clean.
+
+### Customization
+
+- **Light/Dark themes** — toggle instantly, persists across sessions
+- **Config file** — `~/.diffstory.toml` or `.diffstory.toml` in your project sets defaults for verbose mode, debug output, and more
+- **`--verbose` / `--debug` flags** — see what's happening under the hood
+
+### Export Formats
+
+Alongside the HTML report, export structured data:
+
+```bash
+diffstory --staged --json --md --csv
+```
+
+---
+
+## Installation
+
+```bash
+pip install diffstory
+```
+
+**Requires:** Python 3.10+ and Git.
+
+To install from source:
+
+```bash
+git clone https://github.com/lakshayjindal/diffstory.git
+cd diffstory
+pip install -e .
+```
+
+---
+
+## Usage
+
+```bash
+# Working tree diff
+diffstory
+
+# Staged changes (what will be committed)
+diffstory --staged
+
+# Compare commits
+diffstory HEAD~3 HEAD
+
+# Compare branches
+diffstory main feature-branch
+
+# Compare revisions with path restriction
+diffstory HEAD~3 HEAD src/
+
+# Generate from a diff file directly (no git repo needed)
+diffstory --diff /path/to/patch.diff
+
+# Custom output file
+diffstory -o my-review.html
+
+# Multiple export formats at once
+diffstory --staged --json --md --csv -o release-v2.0
+
+# Verbose mode
+diffstory --staged --verbose
+
+# Show version
+diffstory --version
+```
+
+### Config File Example
+
+Create `~/.diffstory.toml` or `.diffstory.toml` in your project:
+
+```toml
+[cli]
+verbose = true
+debug = false
+```
+
+---
+
+## HTML Report
+
+Every generated HTML report is **fully self-contained**:
+
+- All CSS inlined — no external stylesheets
+- All JavaScript inlined — no external scripts
+- All data (blame, commits, search index) embedded as JSON
+- Works offline in any modern browser
+- Safe to email, archive, or include in audit evidence
+- Zero external dependencies at runtime
+
+Open it, share it, attach it to a PR, or file it for compliance. It just works.
+
+---
+
+## Project Structure
+
+```
+diffstory/
+├── pyproject.toml              # Build config & CLI entry point
+├── README.md
+├── requirements.md             # Full product requirements & spec
+├── deploy.sh                   # Build & publish script
+├── .github/workflows/publish.yml  # CI/CD for PyPI publishing
+├── src/diffstory/
+│   ├── __init__.py             # Package version
+│   ├── __main__.py             # python -m diffstory support
+│   ├── cli.py                  # CLI argument parsing & orchestration
+│   ├── git_utils.py            # Git subprocess wrappers (diff, blame, log)
+│   ├── diff_parser.py          # Unified diff parser → structured data
+│   ├── syntax.py               # Pygments syntax highlighting
+│   └── html_generator.py       # Self-contained HTML report generation
+└── tests/
+    └── __init__.py
+```
+
+---
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Test with a quick repo
+cd /tmp && mkdir test-diffstory && cd test-diffstory
+git init && echo "hello" > test.py && git add -A && git commit -m "init"
+echo "world" >> test.py
+diffstory --staged
+
+# Build the package
+python -m build
+
+# Deploy (version bump, build, publish)
+./deploy.sh           # patch bump
+./deploy.sh minor     # minor bump
+```
+
+---
+
+## Design Philosophy
+
+DiffStory was built to answer five questions about every changed line:
+
+> **What changed? Who changed it? When? Why? How did it evolve?**
+
+It consolidates `git diff`, `git blame`, `git log`, and GitHub-style review UX into a single, portable artifact — no server, no accounts, no data leaving your machine.
+
+### Security
+
+- Never uploads code or transmits data
+- No telemetry, no analytics, no accounts
+- No external API calls by default
+- Never modifies your repository
+- Generated reports are safe for air-gapped environments, client deliverables, and compliance audits
+
+---
+
+## License
+
+MIT

{diffstory-0.2.0 → diffstory-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "diffstory"
-version = "0.2.0"
+version = "0.3.0"
 description = "Transform Git diffs into rich, interactive, self-contained HTML reports"
 readme = "README.md"
 license = {text = "MIT"}

{diffstory-0.2.0 → diffstory-0.3.0}/src/diffstory/__init__.py

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

{diffstory-0.2.0 → diffstory-0.3.0}/src/diffstory/cli.py

@@ -3,8 +3,8 @@
 from __future__ import annotations
 
 import argparse
-import os
 import sys
+import webbrowser
 from pathlib import Path
 from typing import Optional
 
@@ -15,6 +15,7 @@ from diffstory.git_utils import (
     check_git_repo,
     get_diff,
     get_diff_with_renames,
+    get_git_root,
 )
 from diffstory.html_generator import generate_report
 
@@ -142,6 +143,13 @@ def build_parser() -> argparse.ArgumentParser:
         help="Generate report from a diff file directly (no git repository needed)",
     )
 
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        default=False,
+        help="Do not open the report in a browser after generation",
+    )
+
     parser.add_argument(
         "--verbose", "-v",
         action="store_true",
@@ -280,6 +288,16 @@ def _export_csv(files, output_path: Path) -> None:
     print(f"  CSV: {output_path}")
 
 
+def _open_in_browser(path: str) -> None:
+    """Open the generated report in the default browser."""
+    try:
+        file_url = "file://" + path
+        webbrowser.open(file_url)
+        print(f"  Opened in browser: {file_url}")
+    except Exception as e:
+        print(f"  Could not open browser: {e}", file=sys.stderr)
+
+
 def _read_diff_from_file(path: str) -> str:
     """Read diff content from a file."""
     try:
@@ -292,6 +310,31 @@ def _read_diff_from_file(path: str) -> str:
         sys.exit(1)
 
 
+def _resolve_output_path(given_path: str) -> str:
+    """Resolve the output file path.
+
+    If the given path is the default and we're inside a git repo,
+    place it in a 'stories/' directory outside the git working tree
+    so that git does not track it.
+    """
+    given = Path(given_path)
+    # Only redirect the default path — if the user explicitly passed -o, use as-is
+    if given.name != "diffstory-report.html":
+        return str(given.resolve())
+
+    try:
+        git_root = get_git_root()
+        if git_root:
+            git_root = Path(git_root).resolve()
+            stories_dir = git_root.parent / "stories"
+            stories_dir.mkdir(parents=True, exist_ok=True)
+            return str(stories_dir / given.name)
+    except Exception:
+        pass
+
+    return str(given.resolve())
+
+
 def main() -> None:
     """Main entry point for the diffstory CLI."""
     parser = build_parser()
@@ -305,6 +348,9 @@ def main() -> None:
     if debug:
         verbose = True  # debug implies verbose
 
+    # Resolve output path — for the default, put it outside the git repo
+    output_path = _resolve_output_path(args.output)
+
     # Handle --diff flag (read diff from file, no git needed)
     if args.diff:
         if verbose:
@@ -318,9 +364,9 @@ def main() -> None:
             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)
+            generate_exports(files, output_path, args.json, args.md, args.csv)
         try:
-            report_path = generate_report(files, output_path=args.output, repo_name="diff", verbose=verbose)
+            report_path = generate_report(files, output_path=output_path, repo_name="diff", verbose=verbose)
         except Exception as e:
             if debug:
                 import traceback
@@ -329,6 +375,10 @@ def main() -> None:
             sys.exit(1)
         print(f"\\n  HTML: {report_path}")
         print("  Report generated successfully!")
+
+        # Open in browser unless --no-open
+        if not args.no_open:
+            _open_in_browser(report_path)
         return
 
     # Validate Git repository
@@ -379,13 +429,13 @@ def main() -> None:
     # 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)
+        generate_exports(files, output_path, args.json, args.md, args.csv)
 
     # Always generate HTML report
     try:
         report_path = generate_report(
             files,
-            output_path=args.output,
+            output_path=output_path,
             staged=args.staged,
             commit_a=commit_a,
             commit_b=commit_b,
@@ -400,3 +450,7 @@ def main() -> None:
 
     print(f"\\n  HTML: {report_path}")
     print("  Report generated successfully!")
+
+    # Open in browser unless --no-open
+    if not args.no_open:
+        _open_in_browser(report_path)

{diffstory-0.2.0 → diffstory-0.3.0}/src/diffstory/diff_parser.py

@@ -134,6 +134,7 @@ def parse_diff(diff_text: str) -> list[DiffFile]:
 
         # Binary files
         if line.startswith("Binary files ") or line == "Binary files differ":
+            current_file.is_binary_file = True
             continue
 
         # New file mode

{diffstory-0.2.0 → diffstory-0.3.0}/src/diffstory/git_utils.py

@@ -45,6 +45,14 @@ def check_git_repo(cwd: Optional[Path] = None) -> bool:
         return False
 
 
+def get_git_root(cwd: Optional[Path] = None) -> Optional[str]:
+    """Get the absolute path to the root of the Git repository."""
+    try:
+        return _run_git(["rev-parse", "--show-toplevel"], cwd=cwd).strip()
+    except GitError:
+        return None
+
+
 def get_diff(
     staged: bool = False,
     commit_a: Optional[str] = None,