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

git_graphable-0.4.0/.github/actions/git-graphable/action.yml

@@ -0,0 +1,76 @@
+name: 'Git Graphable'
+description: 'Generate interactive Git hygiene graphs and reports.'
+author: 'TheTrueSCU'
+branding:
+  icon: 'activity'
+  color: 'blue'
+
+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
+        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 }}

{git_graphable-0.3.0 → git_graphable-0.4.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: ./.github/actions/git-graphable
+        with:
+          production_branch: 'main'
+          output_dir: 'git-graph-reports'

git_graphable-0.4.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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.4.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.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: git-graphable
-Version: 0.3.0
+Version: 0.4.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,7 +16,7 @@ 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:
@@ -26,7 +26,7 @@ git graphable .
 
 ## 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,16 +53,41 @@ 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/.github/actions/git-graphable@v0.4.0
+        with:
+          production_branch: 'main'
+          output_dir: '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
@@ -71,12 +96,12 @@ Git Graphable provides several ways to highlight commits and relationships. Mult
 
 | 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 +122,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.4.0}/README.md

@@ -1,6 +1,6 @@
 # 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:
@@ -10,7 +10,7 @@ git graphable .
 
 ## 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,16 +37,41 @@ 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/.github/actions/git-graphable@v0.4.0
+        with:
+          production_branch: 'main'
+          output_dir: '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
@@ -55,12 +80,12 @@ Git Graphable provides several ways to highlight commits and relationships. Mult
 
 | 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 +106,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.4.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.4.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.3.0 → git_graphable-0.4.0}/examples/EXAMPLES.md

@@ -1,13 +1,13 @@
 # Git Graphable Examples
 
-This page demonstrates the visual output and hygiene analysis of `git-graphable` using generated example repositories.
+This page demonstrates the visual output and hygiene analysis of `git-graphable analyze` using generated example repositories.
 
 ## 1. Pristine Repository (Score: 100%)
 Demonstrates a clean, PR-based workflow with multi-author highlighting and critical branch marking.
 
 **Command:**
 ```bash
-git-graphable repo-pristine --highlight-critical --critical-branch main --highlight-authors
+git-graphable analyze repo-pristine --highlight-critical --critical-branch main --highlight-authors
 ```
 
 **Output:**
@@ -40,7 +40,7 @@ Demonstrates common hygiene issues: WIP commits, direct pushes to protected bran
 
 **Command:**
 ```bash
-git-graphable repo-messy --highlight-wip --highlight-direct-pushes --highlight-stale
+git-graphable analyze repo-messy --highlight-wip --highlight-direct-pushes --highlight-stale
 ```
 
 **Output:**
@@ -73,7 +73,7 @@ Highlights branches with many commits but only one contributor. This indicates a
 
 **Command:**
 ```bash
-git-graphable repo-risk-silo --highlight-silos --silo-threshold 20
+git-graphable analyze repo-risk-silo --highlight-silos --silo-threshold 20
 ```
 
 **Output:**
@@ -140,7 +140,7 @@ Highlights redundant back-merges.
 
 **Command:**
 ```bash
-git-graphable repo-complex-hygiene --highlight-back-merges
+git-graphable analyze repo-complex-hygiene --highlight-back-merges
 ```
 
 **Output:**
@@ -172,7 +172,7 @@ Highlights desyncs between Git and external trackers (Jira, GitHub Issues).
 
 **Command:**
 ```bash
-git-graphable repo-issue-desync --highlight-issue-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED"
+git-graphable analyze repo-issue-desync --highlight-issue-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED"
 ```
 
 **Output:**
@@ -190,7 +190,7 @@ Highlights issues marked as "Released" in the tracker but not yet reachable from
 
 **Command:**
 ```bash
-git-graphable repo-release-desync --highlight-release-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED"
+git-graphable analyze repo-release-desync --highlight-release-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED"
 ```
 
 **Output:**
@@ -210,7 +210,7 @@ Highlights when the Git commit author doesn't match the assigned issue owner in
 
 **Command:**
 ```bash
-git-graphable repo-collab-gap --highlight-collaboration-gaps --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo OPEN,Bob"
+git-graphable analyze repo-collab-gap --highlight-collaboration-gaps --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo OPEN,Bob"
 ```
 
 **Output:**
@@ -228,7 +228,7 @@ Demonstrates features like orphan/dangling commits and divergence.
 
 **Command:**
 ```bash
-git-graphable repo-features --highlight-orphans --highlight-diverging-from main
+git-graphable analyze repo-features --highlight-orphans --highlight-diverging-from main
 ```
 
 **Output:**
@@ -247,14 +247,32 @@ style ebeaa6afb7b85a2d84d8aa5279ca3ad50f54a987 stroke:orange,stroke-width:2px,st
 ---
 
 ## 9. CI Mode (Gating)
-Demonstrates how to use `git-graphable` as a CI gate.
+Demonstrates how to use `git-graphable analyze` as a CI gate.
 
 **Command (Fails):**
 ```bash
-git-graphable repo-messy --check --min-score 80 --bare --highlight-wip --highlight-direct-pushes
+git-graphable analyze repo-messy --check --min-score 80 --highlight-wip --highlight-direct-pushes
 ```
 
 **Output:**
 ```text
 Error: Hygiene score 76% is below required 80%
 ```
+
+---
+
+## 10. Interactive HTML Viewer
+The HTML engine produces a self-contained, interactive visualization with a live-toggle legend.
+
+**Command:**
+```bash
+git-graphable analyze repo-messy --engine html -o graph.html
+```
+
+**Key Features:**
+- **Live Legend**: Toggle hygiene overlays (WIP, Direct Push, Divergence) on/off.
+- **Color Modes**: Switch between Authors, PR Status, Distance, and Staleness views.
+- **Searchable**: Find specific commits by hash or message.
+- **Hierarchical Layout**: Powered by Dagre for a clean top-down flow.
+- **Details Sidebar**: View full commit metadata upon selection.
+