diffstory 0.2.0__tar.gz → 0.2.1__tar.gz

diffstory-0.2.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: diffstory
+Version: 0.2.1
+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.2.1/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.2.1}/pyproject.toml

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

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

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

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

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import os
 import sys
 from pathlib import Path
 from typing import Optional

{diffstory-0.2.0 → diffstory-0.2.1}/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.2.1}/src/diffstory/html_generator.py

@@ -9,7 +9,7 @@ from typing import Any, Optional
 
 import json
 
-from diffstory.diff_parser import DiffFile, DiffLine, Hunk, compute_word_diffs, IMAGE_EXTENSIONS
+from diffstory.diff_parser import DiffFile, DiffLine, Hunk, compute_word_diffs
 from diffstory.syntax import get_highlighted_line, get_syntax_styles
 from diffstory.git_utils import get_blame_for_revision, get_commit_info, get_repo_name
 
@@ -278,10 +278,33 @@ def _render_file_section(file: DiffFile, file_index: int, lexer_cache: dict) ->
     sbs_html = ""
     inline_html = ""
 
-    for hunk in file.hunks:
-        unified_html += _render_unified_hunk(hunk, file.display_path, lexer_cache)
-        sbs_html += _render_sidebyside_hunk(hunk, file.display_path, lexer_cache)
-        inline_html += _render_inline_hunk(hunk, file.display_path, lexer_cache)
+    if file.is_binary_file:
+        # Binary file — show placeholder instead of diff hunks
+        binary_content = escape("Binary file")
+        if file.is_image:
+            binary_content = (
+                '<div class="binary-preview">'
+                '<div class="binary-icon">&#128247;</div>'
+                '<div class="binary-label">Image file &mdash; ' + escape(file_label) + '</div>'
+                '<div class="binary-note">Preview requires the file to be checked out locally</div>'
+                '</div>'
+            )
+        else:
+            binary_content = (
+                '<div class="binary-preview">'
+                '<div class="binary-icon">&#128196;</div>'
+                '<div class="binary-label">Binary file &mdash; ' + escape(file_label) + '</div>'
+                '<div class="binary-note">Diff content not available for binary files</div>'
+                '</div>'
+            )
+        unified_html = '<div class="binary-container">' + binary_content + '</div>'
+        sbs_html = '<div class="binary-container">' + binary_content + '</div>'
+        inline_html = '<div class="binary-container">' + binary_content + '</div>'
+    else:
+        for hunk in file.hunks:
+            unified_html += _render_unified_hunk(hunk, file.display_path, lexer_cache)
+            sbs_html += _render_sidebyside_hunk(hunk, file.display_path, lexer_cache)
+            inline_html += _render_inline_hunk(hunk, file.display_path, lexer_cache)
 
     additions = sum(1 for h in file.hunks for l in h.lines if l.line_type == "addition")
     deletions = sum(1 for h in file.hunks for l in h.lines if l.line_type == "deletion")
@@ -1713,6 +1736,39 @@ body {
     background: #ffd70033;
 }
 
+/* Binary file preview */
+.binary-container {
+    padding: 20px;
+    text-align: center;
+}
+
+.binary-preview {
+    padding: 24px;
+    border: 2px dashed var(--border);
+    border-radius: 8px;
+    background: var(--bg-secondary);
+    max-width: 400px;
+    margin: 0 auto;
+}
+
+.binary-icon {
+    font-size: 40px;
+    margin-bottom: 8px;
+}
+
+.binary-label {
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--text);
+    font-family: 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', monospace;
+}
+
+.binary-note {
+    font-size: 12px;
+    color: var(--text-secondary);
+    margin-top: 4px;
+}
+
 /* Diff line hover cursor for blame */
 .diff-line {
     cursor: pointer;