git-graphable 0.3.0__tar.gz → 0.5.0__tar.gz

{git_graphable-0.3.0 → git_graphable-0.5.0}/.github/workflows/ci.yml

@@ -17,6 +17,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
@@ -31,3 +33,9 @@ jobs:
 
       - name: Run checks
         run: just check
+
+      - name: Git Graph Reports
+        uses: ./
+        with:
+          production_branch: 'main'
+          output_dir: 'git-graph-reports'

git_graphable-0.5.0/.github/workflows/pages.yml

@@ -0,0 +1,46 @@
+name: Deploy Demos to Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Generate Demos
+        run: uv run python examples/publish_demos.py
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'demo-site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{git_graphable-0.3.0 → git_graphable-0.5.0}/.gitignore

@@ -131,8 +131,6 @@ cython_debug/
 .DS_Store
 
 # Examples
+demo-site/
 examples/repos/
 examples/assets/
-
-# Temporary test assets
-test_pr.mmd

git_graphable-0.5.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.5.0] - 2026-03-06
+
+### Added
+- **Interactive Demos**: Implemented `examples/publish_demos.py` to generate and host live HTML demos via GitHub Pages.
+- **Marketplace Preparation**: Moved `action.yml` to the root directory for GitHub Marketplace publishing and updated related documentation and CI workflows.
+
+### Fixed
+- **Squash Merge Detection**: Resolved a `KeyError` and `CycleError` in the logical merge visualization for squashed pull requests when local branch tips were present.
+
+## [0.4.0] - 2026-03-05
+
+### Added
+- **Interactive HTML Viewer**: New `--engine html` output that generates a self-contained interactive graph using Cytoscape.js.
+    - Includes searchable nodes and a details sidebar with live highlight toggling.
+    - Preserves all visual themes and highlighting styles.
+    - Lightweight and portable with zero local dependencies.
+- **Performance Optimizations**:
+    - **Parallel Log Parsing**: Parallelized `GitCommit` instantiation using `ProcessPoolExecutor` for large repositories.
+    - **Parallel Hygiene Scoring**: Concurrent execution of hygiene checks using `ThreadPoolExecutor` for faster report generation.
+- **Modular CLI Architecture**: 
+    - Split into `rich_cli` (Typer/Rich) and `bare_cli` (Argparse) for better environment support.
+    - Intelligent switcher logic in `cli.py` handles optional dependencies and fallbacks.
+- **New `init` Command**: Easily initialize a default `.git-graphable.toml` configuration file.
+- **Reusable GitHub Action**: Added a composite action in `.github/actions/git-graphable/` for automated reporting.
+- **Robust Distance/Divergence Highlights**: Enhanced visualization of branch distance and divergence with clearer legend labels.
+- **Remote URL Support**: Restored and improved ability to pass remote Git URLs (HTTPS/SSH) as the repository path.
+- **Comprehensive UI Testing**: Integrated Playwright for automated browser-based UI testing of the interactive graph.
+
+### Changed
+- **Command Renamed**: Renamed the primary command from `convert` to `analyze` for better semantic alignment.
+- **Decoupled Hygiene Scoring**: Scoring logic is now independent of visual highlighting options, allowing for more granular configuration.
+- **Template System Refactor**: Extracted large HTML/JS blocks into `src/git_graphable/templates.py` for improved maintainability.
+- **Removed PlantUML Support**: Support for PlantUML has been removed in favor of more customizable engines (Mermaid, D2, HTML).
+
+## [0.3.0] - 2026-03-05
+
+### Added
+- **Customizable Visual Styling**: Full override of node and edge styles (colors, widths, dash patterns) via CLI (`--style`) and TOML (`[git-graphable.theme]`).
+- **Configurable Hygiene Scoring**: Customization of hygiene penalties and caps via TOML (`[git-graphable.hygiene_weights]`).
+- **Advanced Issue Tracker Integration**:
+    - **Longevity Mismatch**: Detection of large time gaps between ticket creation and the first commit.
+    - **Collaboration Gaps**: Highlighting when the Git author doesn't match the Issue Tracker assignee.
+    - **Release Validation**: Verification that "Released" tickets are tagged in Git.
+- **New Documentation**: Added `STYLING.md` guide for visual customization.
+- **Engine Consistency**: Unified styling logic across Mermaid, D2, and Graphviz engines.
+
+### Changed
+- **CLI Refactor**: Migrated to a more robust Typer/Rich implementation with enhanced command-line options.
+- **Issue Engine**: Refactored `IssueTracker` to support richer metadata (assignees, timestamps).
+
+### Fixed
+- Fixed inconsistent color application in Mermaid graphs.
+- Improved cleanup of temporary files during image export.
+
+## [0.2.0] - 2026-03-04
+- Initial functional release with basic Git hygiene scoring and GitHub/Jira integration.

{git_graphable-0.3.0 → git_graphable-0.5.0}/Justfile

@@ -77,7 +77,15 @@ lint:
 
 [group('qa')]
 @test *args:
-    uv run -m pytest --git-branch {{ GIT_BRANCH }} --git-commit {{ GIT_COMMIT }} --html-output htmlrep -n auto --should-open-report never {{ args }}
+    uv run -m pytest --git-branch {{ GIT_BRANCH }} --git-commit {{ GIT_COMMIT }} --html-output htmlrep -n auto --should-open-report never -m "not ui" {{ args }}
+
+[group('qa')]
+install-ui:
+    uv run --group ui playwright install chromium
+
+[group('qa')]
+@test-ui *args:
+    uv run --group ui -m pytest --git-branch {{ GIT_BRANCH }} --git-commit {{ GIT_COMMIT }} --html-output htmlrep -n 1 --should-open-report never -m "ui" {{ args }}
 
 [group('qa')]
 [group('view')]

{git_graphable-0.3.0 → git_graphable-0.5.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: git-graphable
-Version: 0.3.0
+Version: 0.5.0
 Summary: A powerful Git history visualizer and hygiene linter with CI gating.
 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,ci,d2,git,git-flow,github,graph,hygiene,lint,mermaid,topology,visualization
+Keywords: analysis,automation,ci,cytoscape,d2,git,git-flow,github,github-actions,graph,html,hygiene,interactive,lint,mermaid,topology,visualization
 Requires-Python: >=3.13
 Requires-Dist: graphable>=0.6.0
 Provides-Extra: cli
@@ -16,17 +16,21 @@ 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.
+A powerful Python tool to convert Git commit history into beautiful, interactive flowcharts using the `graphable` library. Supporting Mermaid, D2, Graphviz, and HTML.
 
 ## Git Plugin Support
 When installed in your PATH, you can use this as a native Git plugin:
 ```bash
-git graphable .
+git graphable analyze .
 ```
 
+## 🚀 Live Interactive Demo
+Check out the tool in action with our **[Live Interactive Demos](https://thetruescu.github.io/git-graphable/)**. Explore different hygiene scenarios and toggle overlays in real-time.
+
+
 ## Features
 
-- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or PlantUML (.puml).
+- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or HTML (.html).
 - **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.
 - **GitHub Integration**: Highlight commits based on pull request status (Merged, Open, Closed, Draft) using the `gh` CLI.
@@ -53,30 +57,79 @@ For a complete reference of all command-line options, see the [USAGE.md](USAGE.m
 
 ```bash
 # Basic usage (opens a Mermaid image)
-uv run git-graphable .
+uv run git-graphable analyze .
 
 # Highlight PR status (requires gh CLI)
-uv run git-graphable . --highlight-pr-status
+uv run git-graphable analyze . --highlight-pr-status
 
 # Specify an engine and output file
-uv run git-graphable https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+uv run git-graphable analyze https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+
+# Initialize a default configuration file
+uv run git-graphable init
 
 # Simplify the graph (only show branches/tags)
-uv run git-graphable . --simplify
+uv run git-graphable analyze . --simplify
+```
+
+## GitHub Action
+
+Git Graphable can be easily integrated into your GitHub workflows to automatically generate hygiene reports on every push or pull request.
+
+```yaml
+jobs:
+  git-hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required to see full history
+
+      - name: Generate Git Graph Reports
+        uses: TheTrueSCU/git-graphable@v0.5.0
+        with:
+          production_branch: 'main'
+          output_dir: 'reports'
 ```
 
+### Inputs
+
+The following inputs are available for the `git-graphable` action:
+
+*   **`path`**
+    *   Description: Path to the git repository
+    *   Required: `false`
+    *   Default: `'.'`
+*   **`production_branch`**
+    *   Description: The main production branch (e.g. main, master)
+    *   Required: `false`
+    *   Default: `'main'`
+*   **`issue_engine`**
+    *   Description: Issue tracker engine (github or jira)
+    *   Required: `false`
+*   **`github_token`**
+    *   Description: GitHub token for issue integration
+    *   Required: `false`
+    *   Default: `${{ github.token }}`
+*   **`output_dir`**
+    *   Description: Directory to save the generated reports
+    *   Required: `false`
+    *   Default: `'git-graph-reports'`
+
+The action generates a **simplified Mermaid summary** (for quick review) and a **full interactive HTML graph** (for deep-dive auditing), uploading them as workflow artifacts.
+
 ## 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 | PR Status, Distance, Stale, WIP |
-| `--highlight-pr-status` | **Fill/Stroke**| Color by PR state (Merged=Purple, Open=Green) | Authors, Distance, Stale, WIP |
-| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, PR Status, Stale, WIP |
-| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, PR Status, Distance, WIP |
-| `--highlight-wip` | **Fill** | Yellow fill for WIP/TODO commits | Authors, PR Status, Distance, Stale |
+| `--highlight-authors` | **Fill** | Unique color per author | PR Status, Distance, Stale |
+| `--highlight-pr-status` | **Fill/Stroke**| Color by PR state (Merged=Purple, Open=Green) | Authors, Distance, Stale |
+| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, PR Status, Stale |
+| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, PR Status, Distance |
 | `--highlight-path` | **Edge** | Thick Orange edge connecting nodes | None |
+| `--highlight-wip` | **Stroke/Fill** | Yellow highlight for WIP/TODO commits | None |
 | `--highlight-critical` | **Stroke** | Thick Red Solid outline | None |
 | `--highlight-diverging-from` | **Stroke** | Orange Dashed outline | None |
 | `--highlight-orphans` | **Stroke** | Grey Dashed outline | None |
@@ -97,32 +150,38 @@ For a full reference of the default visual styles and how to customize them, see
 ### Hygiene Analysis
 Identify problematic patterns like direct pushes to `main`, messy WIP commits, back-merges from `main`, or contributor silos:
 ```bash
-uv run git-graphable . --highlight-direct-pushes --highlight-wip --highlight-squashed --highlight-back-merges --highlight-silos
+uv run git-graphable analyze . --highlight-direct-pushes --highlight-wip --highlight-squashed --highlight-back-merges --highlight-silos
 ```
 
 ### PR Status Highlighting
 View the current state of all PRs in your repository graph:
 ```bash
-uv run git-graphable . --highlight-pr-status
+uv run git-graphable analyze . --highlight-pr-status
 ```
 
 ### 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
+uv run git-graphable analyze . --highlight-diverging-from main
 ```
 
 ### Issue Tracker Integration
 Flag mismatches between your code and your tickets:
 ```bash
-uv run git-graphable . --highlight-issue-inconsistencies --issue-pattern "[A-Z]+-[0-9]+" --issue-engine jira --jira-url "https://your-org.atlassian.net"
+uv run git-graphable analyze . --highlight-issue-inconsistencies --issue-pattern "[A-Z]+-[0-9]+" --issue-engine jira --jira-url "https://your-org.atlassian.net"
 ```
 
 ### Customizable Scoring & Styling
 Adjust hygiene penalties and visual styles to match your team's workflow:
 ```bash
 # Aggressive penalty for direct pushes and custom teal color for critical branches
-uv run git-graphable . --check --penalty direct_push_penalty:50 --style critical:stroke:teal
+uv run git-graphable analyze . --check --penalty direct_push_penalty:50 --style critical:stroke:teal
+```
+
+### Interactive HTML Viewer
+Generate a self-contained HTML file with a searchable graph, details sidebar, and an interactive legend to live-toggle all highlight modes:
+```bash
+uv run git-graphable analyze . --engine html -o graph.html
 ```
 
 ## Configuration

{git_graphable-0.3.0 → git_graphable-0.5.0}/README.md

@@ -1,16 +1,20 @@
 # 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.
+A powerful Python tool to convert Git commit history into beautiful, interactive flowcharts using the `graphable` library. Supporting Mermaid, D2, Graphviz, and HTML.
 
 ## Git Plugin Support
 When installed in your PATH, you can use this as a native Git plugin:
 ```bash
-git graphable .
+git graphable analyze .
 ```
 
+## 🚀 Live Interactive Demo
+Check out the tool in action with our **[Live Interactive Demos](https://thetruescu.github.io/git-graphable/)**. Explore different hygiene scenarios and toggle overlays in real-time.
+
+
 ## Features
 
-- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or PlantUML (.puml).
+- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or HTML (.html).
 - **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.
 - **GitHub Integration**: Highlight commits based on pull request status (Merged, Open, Closed, Draft) using the `gh` CLI.
@@ -37,30 +41,79 @@ For a complete reference of all command-line options, see the [USAGE.md](USAGE.m
 
 ```bash
 # Basic usage (opens a Mermaid image)
-uv run git-graphable .
+uv run git-graphable analyze .
 
 # Highlight PR status (requires gh CLI)
-uv run git-graphable . --highlight-pr-status
+uv run git-graphable analyze . --highlight-pr-status
 
 # Specify an engine and output file
-uv run git-graphable https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+uv run git-graphable analyze https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+
+# Initialize a default configuration file
+uv run git-graphable init
 
 # Simplify the graph (only show branches/tags)
-uv run git-graphable . --simplify
+uv run git-graphable analyze . --simplify
+```
+
+## GitHub Action
+
+Git Graphable can be easily integrated into your GitHub workflows to automatically generate hygiene reports on every push or pull request.
+
+```yaml
+jobs:
+  git-hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required to see full history
+
+      - name: Generate Git Graph Reports
+        uses: TheTrueSCU/git-graphable@v0.5.0
+        with:
+          production_branch: 'main'
+          output_dir: 'reports'
 ```
 
+### Inputs
+
+The following inputs are available for the `git-graphable` action:
+
+*   **`path`**
+    *   Description: Path to the git repository
+    *   Required: `false`
+    *   Default: `'.'`
+*   **`production_branch`**
+    *   Description: The main production branch (e.g. main, master)
+    *   Required: `false`
+    *   Default: `'main'`
+*   **`issue_engine`**
+    *   Description: Issue tracker engine (github or jira)
+    *   Required: `false`
+*   **`github_token`**
+    *   Description: GitHub token for issue integration
+    *   Required: `false`
+    *   Default: `${{ github.token }}`
+*   **`output_dir`**
+    *   Description: Directory to save the generated reports
+    *   Required: `false`
+    *   Default: `'git-graph-reports'`
+
+The action generates a **simplified Mermaid summary** (for quick review) and a **full interactive HTML graph** (for deep-dive auditing), uploading them as workflow artifacts.
+
 ## 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 | PR Status, Distance, Stale, WIP |
-| `--highlight-pr-status` | **Fill/Stroke**| Color by PR state (Merged=Purple, Open=Green) | Authors, Distance, Stale, WIP |
-| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, PR Status, Stale, WIP |
-| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, PR Status, Distance, WIP |
-| `--highlight-wip` | **Fill** | Yellow fill for WIP/TODO commits | Authors, PR Status, Distance, Stale |
+| `--highlight-authors` | **Fill** | Unique color per author | PR Status, Distance, Stale |
+| `--highlight-pr-status` | **Fill/Stroke**| Color by PR state (Merged=Purple, Open=Green) | Authors, Distance, Stale |
+| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, PR Status, Stale |
+| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, PR Status, Distance |
 | `--highlight-path` | **Edge** | Thick Orange edge connecting nodes | None |
+| `--highlight-wip` | **Stroke/Fill** | Yellow highlight for WIP/TODO commits | None |
 | `--highlight-critical` | **Stroke** | Thick Red Solid outline | None |
 | `--highlight-diverging-from` | **Stroke** | Orange Dashed outline | None |
 | `--highlight-orphans` | **Stroke** | Grey Dashed outline | None |
@@ -81,32 +134,38 @@ For a full reference of the default visual styles and how to customize them, see
 ### Hygiene Analysis
 Identify problematic patterns like direct pushes to `main`, messy WIP commits, back-merges from `main`, or contributor silos:
 ```bash
-uv run git-graphable . --highlight-direct-pushes --highlight-wip --highlight-squashed --highlight-back-merges --highlight-silos
+uv run git-graphable analyze . --highlight-direct-pushes --highlight-wip --highlight-squashed --highlight-back-merges --highlight-silos
 ```
 
 ### PR Status Highlighting
 View the current state of all PRs in your repository graph:
 ```bash
-uv run git-graphable . --highlight-pr-status
+uv run git-graphable analyze . --highlight-pr-status
 ```
 
 ### 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
+uv run git-graphable analyze . --highlight-diverging-from main
 ```
 
 ### Issue Tracker Integration
 Flag mismatches between your code and your tickets:
 ```bash
-uv run git-graphable . --highlight-issue-inconsistencies --issue-pattern "[A-Z]+-[0-9]+" --issue-engine jira --jira-url "https://your-org.atlassian.net"
+uv run git-graphable analyze . --highlight-issue-inconsistencies --issue-pattern "[A-Z]+-[0-9]+" --issue-engine jira --jira-url "https://your-org.atlassian.net"
 ```
 
 ### Customizable Scoring & Styling
 Adjust hygiene penalties and visual styles to match your team's workflow:
 ```bash
 # Aggressive penalty for direct pushes and custom teal color for critical branches
-uv run git-graphable . --check --penalty direct_push_penalty:50 --style critical:stroke:teal
+uv run git-graphable analyze . --check --penalty direct_push_penalty:50 --style critical:stroke:teal
+```
+
+### Interactive HTML Viewer
+Generate a self-contained HTML file with a searchable graph, details sidebar, and an interactive legend to live-toggle all highlight modes:
+```bash
+uv run git-graphable analyze . --engine html -o graph.html
 ```
 
 ## Configuration

{git_graphable-0.3.0 → git_graphable-0.5.0}/STYLING.md

@@ -10,13 +10,17 @@ These styles are applied to commit nodes based on their state or identified hygi
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
 | **Critical** | `red` | - | `4` | `solid` | - | Thick Red Solid outline |
 | **WIP** | - | `#ffff00` | - | - | - | Yellow background |
-| **Behind Base** | `orange` | - | `2` | `dashed`| - | Orange Dashed outline (Divergence) |
+| **Divergence** | `orange` | - | `2` | `dashed`| - | Orange Dashed outline |
 | **Orphan** | `grey` | - | - | `dashed`| `0.6` | Faded Grey Dashed outline |
 | **Long Running**| `purple` | - | `3` | `solid` | - | Purple Solid outline |
 | **PR Conflict** | `red` | - | `6` | `solid` | - | Very Thick Red outline |
 | **Direct Push** | `#ff0000` | - | `8` | `dashed`| - | Thickest Red Dashed outline |
 | **Back Merge** | `orange` | - | `4` | `dashed`| - | Thick Orange Dashed outline |
 | **Silo** | `blue` | - | `6` | `solid` | - | Thick Blue Solid outline |
+| **Issue Desync** | `orange` | - | `4` | `solid` | - | Thick Orange outline |
+| **Release Gap** | `red` | - | `2` | `dashed`| - | Red Dashed outline |
+| **Collab Gap** | `purple` | - | `4` | `dotted`| - | Purple Dotted outline |
+| **Longevity** | `brown` | - | `3` | `solid` | - | Brown Solid outline |
 
 ## PR Status Colors
 
@@ -118,3 +122,4 @@ fill = "#00FF00"
 *   **Mermaid**: Supports all properties. Width is mapped to `stroke-width`. Dash is mapped to `stroke-dasharray`.
 *   **D2**: Supports all properties. `double-border` is automatically enabled for Critical nodes.
 *   **Graphviz**: Supports all properties. `penwidth` is used for width. Dash is mapped to `style=dashed/dotted`.
+*   **HTML**: Supports all properties via Cytoscape.js.

{git_graphable-0.3.0 → git_graphable-0.5.0}/USAGE.md

@@ -1,13 +1,24 @@
 # `git-graphable`
 
-Git graph to Mermaid/Graphviz/D2/PlantUML converter.
+Git history hygiene analyzer and visualizer.
 
-**Usage**:
+## Usage
 
 ```console
-$ git-graphable [OPTIONS] PATH
+$ git-graphable [COMMAND] [ARGS]...
 ```
 
+**Commands**:
+
+* `analyze`: Analyze git history and generate a graph (default).
+* `init`: Initialize a default `.git-graphable.toml` configuration file.
+
+---
+
+## `analyze`
+
+Analyze git history and generate a graph. This is the default command; if no command is specified, `analyze` is assumed.
+
 **Arguments**:
 
 * `PATH`: Path to local directory or git URL  [required]
@@ -17,9 +28,13 @@ $ git-graphable [OPTIONS] PATH
 * `--config TEXT`: Path to TOML configuration file
 * `--production-branch TEXT`: Production branch name (e.g. main, master)
 * `--development-branch TEXT`: Development branch name (e.g. develop, main)
-* `--date-format TEXT`: Date format for commit labels  [default: %Y%m%d%H%M%S]
-* `--engine [mermaid|graphviz|d2|plantuml]`: Visualization engine  [default: mermaid]
-* `-o, --output TEXT`: Output file path
+* `--date-format TEXT`: Date format for commit labels
+* `--engine [mermaid|graphviz|d2|html]`: Visualization engine.
+    *   **mermaid**: Static text export (default).
+    *   **graphviz**: Static text export.
+    *   **d2**: Static text export.
+    *   **html**: **Interactive HTML Viewer**. Generates a self-contained file with a searchable graph, details sidebar, and a **dynamic legend** to toggle all highlight modes on/off.
+* `-o, --output TEXT`: Output file path. If no output is provided, a temporary file is created and opened automatically.
 * `--image`: Export as image even when output path is provided
 * `--simplify`: Pass --simplify-by-decoration to git log
 * `--limit INTEGER`: Limit the number of commits to process
@@ -59,6 +74,16 @@ $ git-graphable [OPTIONS] PATH
 * `--check`: Exit with non-zero if hygiene score is below threshold
 * `--min-score INTEGER`: Minimum hygiene score required for --check
 * `--bare`: Force bare mode (no rich output)
-* `--install-completion`: Install completion for the current shell.
-* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+---
+
+## `init`
+
+Initialize a default `.git-graphable.toml` configuration file.
+
+**Options**:
+
+* `-o, --output TEXT`: Path to create the config file  [default: .git-graphable.toml]
+* `-f, --force`: Overwrite existing config file
 * `--help`: Show this message and exit.

git_graphable-0.5.0/action.yml

@@ -0,0 +1,77 @@
+name: 'Git Graphable'
+description: 'Analyze and visualize Git history hygiene with interactive graphs and reports.'
+author: 'TheTrueSCU'
+branding:
+  icon: 'bar-chart'
+  color: 'green'
+
+inputs:
+  path:
+    description: 'Path to the git repository'
+    required: false
+    default: '.'
+  production_branch:
+    description: 'The main production branch (e.g. main, master)'
+    required: false
+    default: 'main'
+  issue_engine:
+    description: 'Issue tracker engine (github or jira)'
+    required: false
+  github_token:
+    description: 'GitHub token for issue integration'
+    required: false
+    default: ${{ github.token }}
+  output_dir:
+    description: 'Directory to save the generated reports'
+    required: false
+    default: 'git-graph-reports'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Install git-graphable
+      shell: bash
+      run: |
+        # Prefer installing local source if we are in the git-graphable repo
+        # github.action_path points to the root in this case
+        ROOT_DIR="${{ github.action_path }}"
+        if [ -f "$ROOT_DIR/pyproject.toml" ] && grep -q "name = \"git-graphable\"" "$ROOT_DIR/pyproject.toml"; then
+          echo "Installing git-graphable from local source: $ROOT_DIR"
+          uv tool install "$ROOT_DIR"
+        else
+          echo "Installing git-graphable from PyPI"
+          uv tool install git-graphable
+        fi
+
+    - name: Create output directory
+      shell: bash
+      run: mkdir -p ${{ inputs.output_dir }}
+
+    - name: Generate Simplified Graph (Mermaid)
+      shell: bash
+      run: |
+        ARGS="--production-branch ${{ inputs.production_branch }} --simplify --engine mermaid -o ${{ inputs.output_dir }}/summary.mmd"
+        if [ -n "${{ inputs.issue_engine }}" ]; then ARGS="$ARGS --issue-engine ${{ inputs.issue_engine }}"; fi
+        uv tool run git-graphable --bare ${{ inputs.path }} $ARGS
+      env:
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+
+    - name: Generate Full Interactive Graph (HTML)
+      shell: bash
+      run: |
+        ARGS="--production-branch ${{ inputs.production_branch }} --engine html -o ${{ inputs.output_dir }}/graph.html"
+        if [ -n "${{ inputs.issue_engine }}" ]; then ARGS="$ARGS --issue-engine ${{ inputs.issue_engine }}"; fi
+        uv tool run git-graphable --bare ${{ inputs.path }} $ARGS
+      env:
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+
+    - name: Upload Reports
+      uses: actions/upload-artifact@v4
+      with:
+        name: git-graph-reports
+        path: ${{ inputs.output_dir }}