Skip to main content

Submodule Health Dashboard HTML Generator

Script: scripts/submodule-dashboard-html.py Created: 2026-02-02 Status: Production Ready

Overview​

A self-contained HTML dashboard generator that visualizes the health of all CODITECT submodules. Reuses the data collection functions from submodule-health-check.py to provide an interactive, browser-based view of submodule status.

Features​

Dashboard Components​

  1. Header

    • Title: "CODITECT Submodule Health Dashboard"
    • Generation timestamp

  2. Summary Cards

    • Total Repositories
    • Clean (green)
    • Dirty (yellow)
    • Stale (red - behind remote)
    • Unpushed (orange - local commits)
    • Average Health Score

  3. Category Filter Tabs

    • All (default)
    • Cloud, Core, Dev, Docs, GTM, Integrations, Investors, Labs, Ops, Products, Enterprise

  4. Submodule Table

    • Sortable columns (click header to sort)
    • Columns: Name, Category, Branch, Status, Uncommitted, Unpushed, Behind, Ahead, Last Commit, Health Score, Symlinks
    • Health Score with color-coded progress bar (green/yellow/red)
    • Symlink status with checkmarks

  5. Search/Filter

    • Real-time text search by submodule name
    • Combines with category filter

Technical Features​

  • Self-contained: All CSS and JavaScript inline (no external dependencies)
  • Dark theme: Matches terminal aesthetic
  • Responsive: Works on desktop, tablet, mobile
  • Performance: Vanilla JS (no frameworks), fast rendering
  • Color coding:
    • Green: score >= 80
    • Yellow: score 50-79
    • Red: score < 50

Usage​

Basic Usage​

# Generate to file
python3 scripts/submodule-dashboard-html.py --output dashboard.html

# Generate and open in browser
python3 scripts/submodule-dashboard-html.py --output dashboard.html --open

# Pipe to stdout
python3 scripts/submodule-dashboard-html.py > dashboard.html

From Different Locations​

# From rollout-master root (scans all 74 submodules)
cd ~/PROJECTS/coditect-rollout-master
python3 submodules/core/coditect-core/scripts/submodule-dashboard-html.py --output dashboard.html

# From coditect-core (scans core submodules only)
cd ~/PROJECTS/coditect-rollout-master/submodules/core/coditect-core
python3 scripts/submodule-dashboard-html.py --output dashboard.html

# With verbose logging
python3 scripts/submodule-dashboard-html.py --output dashboard.html --verbose

Options​

OptionShortDescription
--output-oOutput file path (default: stdout)
--openOpen dashboard in browser after generation
--verbose-vVerbose logging
--help-hShow help message

Health Score Calculation​

The dashboard reuses the health score calculation from submodule-health-check.py:

CriteriaDeduction
Uncommitted changes5 points each (max 20)
Unpushed commits5 points each (max 20)
Behind remote10 points
Detached HEAD15 points
Not on main branch5 points
Missing .coditect symlink20 points
Broken .coditect symlink20 points
Framework not accessible10 points

Score range: 0-100 (100 = perfect health)

Dashboard Features​

Interactive Sorting​

Click any column header to sort:

  • First click: ascending
  • Second click: descending
  • Numeric columns (uncommitted, unpushed, etc.) sort numerically
  • Text columns sort alphabetically

Category Filtering​

  • Click category tab to filter by category
  • "All" shows all submodules
  • Combines with text search

Text Search​

  • Type in search box to filter by submodule name
  • Real-time filtering (no Enter key needed)
  • Case-insensitive
  • Combines with category filter

Health Score Visualization​

  • Animated progress bar on page load
  • Color gradient: green (good) → yellow (warning) → red (critical)
  • Numeric score displayed next to bar

Output Structure​

The generated HTML file is self-contained:

<!DOCTYPE html>
<html>
  <head>
    <style>
      /* Inline CSS (~300 lines) */
      /* Dark theme, responsive, color-coded */
    </style>
  </head>
  <body>
    <div class="container">
      <header>...</header>
      <div class="summary-cards">...</div>
      <div class="controls">...</div>
      <div class="table-container">...</div>
    </div>
    <script>
      /* Vanilla JavaScript (~150 lines) */
      /* Sorting, filtering, search, animations */
    </script>
  </body>
</html>

File size: ~16-20 KB (depending on number of submodules)

Dependencies​

  • Python: 3.10+ (stdlib only)
  • Required script: submodule-health-check.py (same directory)
  • Runtime: No external dependencies (self-contained HTML)

Architecture​

Data Flow​

submodule-health-check.py
  ├── find_rollout_master_root()    → Find root directory
  ├── check_submodule_health()       → Check each submodule
  └── HealthStatus dataclass         → Health data structure
        ↓
submodule-dashboard-html.py
  ├── Import health check functions
  ├── Collect submodule paths
  ├── Run health checks
  ├── generate_html_dashboard()      → Generate HTML
  └── Output to file or stdout

HTML Structure​

Dashboard
├── Header (title + timestamp)
├── Summary Cards (6 cards)
│   ├── Total Repositories
│   ├── Clean
│   ├── Dirty
│   ├── Stale
│   ├── Unpushed
│   └── Average Health Score
├── Controls (sticky)
│   ├── Search Box
│   └── Category Tabs
└── Table (sortable, filterable)
    ├── Name
    ├── Category
    ├── Branch
    ├── Status (badge)
    ├── Uncommitted
    ├── Unpushed
    ├── Behind
    ├── Ahead
    ├── Last Commit
    ├── Health Score (bar)
    └── Symlinks (✓/✗)

Testing​

The dashboard includes comprehensive test coverage:

# Run test suite
python3 analyze-new-artifacts/test-dashboard-script.py

Test coverage:

  • HTML structure validation
  • Data rendering
  • Summary calculations
  • Component presence (search, tabs, table, bars)
  • JavaScript functionality

Integration​

With CI/CD​

# Generate dashboard in CI pipeline
python3 scripts/submodule-dashboard-html.py --output artifacts/dashboard.html

# Publish as artifact
# (Upload dashboard.html to build artifacts)

With Cron Job​

# Daily dashboard generation
0 9 * * * cd ~/PROJECTS/coditect-rollout-master && \
  python3 submodules/core/coditect-core/scripts/submodule-dashboard-html.py \
  --output ~/public_html/submodule-dashboard.html

With Git Hooks​

# Post-commit hook to regenerate dashboard
#!/bin/bash
python3 scripts/submodule-dashboard-html.py --output dashboard.html
git add dashboard.html

Error Handling​

The script includes robust error handling:

  1. Import errors: Clear message if health check script not found
  2. Path errors: Validates submodules directory exists
  3. Git errors: Gracefully handles submodules with git issues
  4. File errors: Reports I/O errors when writing output

Performance​

  • Scan time: ~1-2 seconds per 10 submodules
  • Generation time: <1 second for HTML
  • Render time: <100ms in browser (vanilla JS)
  • File size: ~250 bytes per submodule + 16KB base

Accessibility​

  • Semantic HTML structure
  • Keyboard navigation support
  • High contrast color scheme
  • Responsive breakpoints for mobile

Browser Compatibility​

  • Chrome/Edge: Full support
  • Firefox: Full support
  • Safari: Full support
  • Mobile browsers: Full support

No legacy browser support needed (uses modern CSS/JS)

Future Enhancements​

Potential additions:

  1. Export to CSV/JSON
  2. Historical trend graphs
  3. Drill-down detail views
  4. Automated recommendations
  5. Integration with GitHub API for PR/issue counts
  6. Webhook notifications for health score changes
  • submodule-health-check.py - Data collection (required)
  • sync-all-submodules.sh - Bulk submodule operations
  • checkpoint-with-submodules.py - Checkpoint creation

Support​

Issues: Report to CODITECT core team Documentation: This file + script docstring Testing: analyze-new-artifacts/test-dashboard-script.py

Author: Claude (Sonnet 4.5) Date: 2026-02-02 Version: 1.0.0