git-graphable 0.2.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.2.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.2.0 → git_graphable-0.4.0}/Justfile

@@ -58,7 +58,7 @@ publish: build
 
 [group('qa')]
 check: lint typing coverage
-    uv run git-graphable . --check --min-score 80 --bare --highlight-wip --highlight-direct-pushes
+    uv run git-graphable . --check --min-score 75 --bare --highlight-wip --highlight-direct-pushes
 
 [group('qa')]
 @coverage *args:
@@ -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')]
@@ -112,3 +120,6 @@ generate-examples:
     uv run git-graphable examples/repos/repo-features --engine mermaid -o examples/assets/features.mmd --highlight-orphans --highlight-diverging-from main --bare
     uv run git-graphable examples/repos/repo-risk-silo --engine mermaid -o examples/assets/silo.mmd --highlight-silos --silo-threshold 20 --bare
     uv run git-graphable examples/repos/repo-complex-hygiene --engine mermaid -o examples/assets/complex.mmd --highlight-back-merges --bare
+    uv run git-graphable examples/repos/repo-issue-desync --engine mermaid -o examples/assets/issue_desync.mmd --highlight-issue-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED" --bare
+    uv run git-graphable examples/repos/repo-release-desync --engine mermaid -o examples/assets/release_desync.mmd --highlight-release-inconsistencies --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo CLOSED" --bare
+    uv run git-graphable examples/repos/repo-collab-gap --engine mermaid -o examples/assets/collab_gap.mmd --highlight-collaboration-gaps --issue-pattern "PROJ-[0-9]+" --issue-engine script --issue-script "echo OPEN,Bob" --bare

{git_graphable-0.2.0 → git_graphable-0.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: git-graphable
-Version: 0.2.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,12 +26,16 @@ 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.
 - **Hygiene Analysis**: Automatically detect WIP commits, direct pushes to protected branches, squashed PRs, back-merges, and contributor silos.
+- **Issue Tracker Integration**: Connect to Jira, GitHub Issues, or custom scripts to highlight status desyncs.
+- **Release & Assignment Validation**: Verify that "Released" tickets are actually tagged in Git and that commit authors match ticket assignees.
 - **Health Scoring**: Get a numeric "Hygiene Score" (0-100%) with a color-coded grade and detailed breakdown of workflow anti-patterns.
+- **Visual Customization**: Fully customize colors, widths, and line styles for nodes and edges. See [STYLING.md](STYLING.md).
+- **Configurable Penalties**: Fully customize the scoring logic by adjusting penalties and caps for each metric.
 - **CI Gating**: Use the `--check` flag to return a non-zero exit code if the hygiene score falls below a threshold (configurable via `--min-score`).
 - **Flexible Input**: Works with local repository paths or remote Git URLs.
 - **Dual CLI**: Modern Rich/Typer interface with a robust argparse fallback for bare environments.
@@ -49,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
@@ -67,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 |
@@ -81,48 +110,56 @@ Git Graphable provides several ways to highlight commits and relationships. Mult
 | `--highlight-squashed` | **Stroke/Edge** | Grey Solid outline and dashed Grey logical merge edge | None |
 | `--highlight-back-merges` | **Stroke** | Orange Dashed outline | None |
 | `--highlight-silos` | **Stroke** | Blue Solid outline | None |
+| `--highlight-issue-inconsistencies` | **Label** | Adds `[ISSUE-DESYNC]` label | None |
+| `--highlight-release-inconsistencies`| **Label** | Adds `[NOT-RELEASED]` label | None |
+| `--highlight-collaboration-gaps` | **Label** | Adds `[COLLAB-GAP]` label | None |
+| `--highlight-longevity-mismatch` | **Label** | Adds `[LONGEVITY]` label | None |
 
-### Highlighting Priorities
-- **Fill**: `--highlight-authors`, `--highlight-pr-status`, `--highlight-distance-from`, `--highlight-stale`, and `--highlight-wip` are mutually exclusive.
-- **Edge**: Path highlighting (Thick Orange) takes priority over Long-Running highlighting (Thick Purple), which takes priority over Logical Squashed Merges (Dashed Grey).
-- **Stroke**: Critical outlines (Thick Red Solid) take priority over Direct Pushes (Thick Red Dashed), which take priority over PR Conflicts (Thick Red Solid), which take priority over Back-Merges (Orange Dashed), which take priority over Squash Commits (Grey Solid), which take priority over Contributor Silos (Blue Solid), which take priority over all other outlines (Divergence, Orphan, Long-Running).
+For a full reference of the default visual styles and how to customize them, see [STYLING.md](STYLING.md).
 
 ## Advanced Examples
 
 ### 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
 ```
 
-### Large Repositories
-For repositories with long histories, use the `--limit` flag to keep the graph readable and avoid engine rendering limits:
+### Issue Tracker Integration
+Flag mismatches between your code and your tickets:
 ```bash
-uv run git-graphable . --limit 100 --highlight-authors
+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 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 can be configured via a TOML file (`.git-graphable.toml` or `pyproject.toml`). CLI flags always take precedence over configuration file settings.
 
-### Configuration Locations
-The tool searches for configuration in the following order:
-1. File specified via `--config <path>`
-2. `.git-graphable.toml` in the repository root
-3. `pyproject.toml` in the repository root (under `[tool.git-graphable]`)
-
 ### Example `.git-graphable.toml`
 ```toml
 [git-graphable]
@@ -142,15 +179,34 @@ highlight_back_merges = true
 highlight_silos = true
 silo_commit_threshold = 20
 silo_author_count = 1
-min_hygiene_score = 80
-```
 
-### Example `pyproject.toml`
-```toml
-[tool.git-graphable]
-development_branch = "main"
-simplify = true
-highlight_authors = true
+# Issue Tracker
+highlight_issue_inconsistencies = true
+highlight_release_inconsistencies = true
+highlight_collaboration_gaps = true
+highlight_longevity_mismatch = true
+issue_pattern = "JIRA-[0-9]+"
+issue_engine = "jira"
+jira_url = "https://your-org.atlassian.net"
+jira_closed_statuses = ["Done", "Closed", "Resolved"]
+released_statuses = ["Released"]
+author_mapping = { "Git Name" = "Jira Name" }
+longevity_threshold_days = 14
+
+# Custom Scoring
+[git-graphable.hygiene_weights]
+direct_push_penalty = 25
+direct_push_cap = 75
+wip_commit_penalty = 5
+
+# Custom Theme
+[git-graphable.theme.critical]
+stroke = "teal"
+width = 2
+
+[git-graphable.theme.direct_push]
+stroke = "magenta"
+dash = "dotted"
 ```
 
 ## Development

{git_graphable-0.2.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,12 +10,16 @@ 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.
 - **Hygiene Analysis**: Automatically detect WIP commits, direct pushes to protected branches, squashed PRs, back-merges, and contributor silos.
+- **Issue Tracker Integration**: Connect to Jira, GitHub Issues, or custom scripts to highlight status desyncs.
+- **Release & Assignment Validation**: Verify that "Released" tickets are actually tagged in Git and that commit authors match ticket assignees.
 - **Health Scoring**: Get a numeric "Hygiene Score" (0-100%) with a color-coded grade and detailed breakdown of workflow anti-patterns.
+- **Visual Customization**: Fully customize colors, widths, and line styles for nodes and edges. See [STYLING.md](STYLING.md).
+- **Configurable Penalties**: Fully customize the scoring logic by adjusting penalties and caps for each metric.
 - **CI Gating**: Use the `--check` flag to return a non-zero exit code if the hygiene score falls below a threshold (configurable via `--min-score`).
 - **Flexible Input**: Works with local repository paths or remote Git URLs.
 - **Dual CLI**: Modern Rich/Typer interface with a robust argparse fallback for bare environments.
@@ -33,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
@@ -51,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 |
@@ -65,48 +94,56 @@ Git Graphable provides several ways to highlight commits and relationships. Mult
 | `--highlight-squashed` | **Stroke/Edge** | Grey Solid outline and dashed Grey logical merge edge | None |
 | `--highlight-back-merges` | **Stroke** | Orange Dashed outline | None |
 | `--highlight-silos` | **Stroke** | Blue Solid outline | None |
+| `--highlight-issue-inconsistencies` | **Label** | Adds `[ISSUE-DESYNC]` label | None |
+| `--highlight-release-inconsistencies`| **Label** | Adds `[NOT-RELEASED]` label | None |
+| `--highlight-collaboration-gaps` | **Label** | Adds `[COLLAB-GAP]` label | None |
+| `--highlight-longevity-mismatch` | **Label** | Adds `[LONGEVITY]` label | None |
 
-### Highlighting Priorities
-- **Fill**: `--highlight-authors`, `--highlight-pr-status`, `--highlight-distance-from`, `--highlight-stale`, and `--highlight-wip` are mutually exclusive.
-- **Edge**: Path highlighting (Thick Orange) takes priority over Long-Running highlighting (Thick Purple), which takes priority over Logical Squashed Merges (Dashed Grey).
-- **Stroke**: Critical outlines (Thick Red Solid) take priority over Direct Pushes (Thick Red Dashed), which take priority over PR Conflicts (Thick Red Solid), which take priority over Back-Merges (Orange Dashed), which take priority over Squash Commits (Grey Solid), which take priority over Contributor Silos (Blue Solid), which take priority over all other outlines (Divergence, Orphan, Long-Running).
+For a full reference of the default visual styles and how to customize them, see [STYLING.md](STYLING.md).
 
 ## Advanced Examples
 
 ### 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
 ```
 
-### Large Repositories
-For repositories with long histories, use the `--limit` flag to keep the graph readable and avoid engine rendering limits:
+### Issue Tracker Integration
+Flag mismatches between your code and your tickets:
 ```bash
-uv run git-graphable . --limit 100 --highlight-authors
+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 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 can be configured via a TOML file (`.git-graphable.toml` or `pyproject.toml`). CLI flags always take precedence over configuration file settings.
 
-### Configuration Locations
-The tool searches for configuration in the following order:
-1. File specified via `--config <path>`
-2. `.git-graphable.toml` in the repository root
-3. `pyproject.toml` in the repository root (under `[tool.git-graphable]`)
-
 ### Example `.git-graphable.toml`
 ```toml
 [git-graphable]
@@ -126,15 +163,34 @@ highlight_back_merges = true
 highlight_silos = true
 silo_commit_threshold = 20
 silo_author_count = 1
-min_hygiene_score = 80
-```
 
-### Example `pyproject.toml`
-```toml
-[tool.git-graphable]
-development_branch = "main"
-simplify = true
-highlight_authors = true
+# Issue Tracker
+highlight_issue_inconsistencies = true
+highlight_release_inconsistencies = true
+highlight_collaboration_gaps = true
+highlight_longevity_mismatch = true
+issue_pattern = "JIRA-[0-9]+"
+issue_engine = "jira"
+jira_url = "https://your-org.atlassian.net"
+jira_closed_statuses = ["Done", "Closed", "Resolved"]
+released_statuses = ["Released"]
+author_mapping = { "Git Name" = "Jira Name" }
+longevity_threshold_days = 14
+
+# Custom Scoring
+[git-graphable.hygiene_weights]
+direct_push_penalty = 25
+direct_push_cap = 75
+wip_commit_penalty = 5
+
+# Custom Theme
+[git-graphable.theme.critical]
+stroke = "teal"
+width = 2
+
+[git-graphable.theme.direct_push]
+stroke = "magenta"
+dash = "dotted"
 ```
 
 ## Development