progress-dashboard · diff
git:20260919.20d77cb to git:20261106.16929e6
87 added, 52 removed. Audit A to A.
---
name: progress-dashboard
description: >
Generate an interactive HTML dashboard that visualizes improvement progress
- from software-evaluation and vulnerability-scan reports over time.
- Reads JSON summary files from docs/evaluation/ and docs/security-audit/,
- then produces a single self-contained HTML file with charts and trend analysis.
+ from software-evaluation, vulnerability-scan and dependency-audit reports over time.
+ Reads JSON summary files from docs/evaluation/, docs/security-audit/ and docs/dependency-audit/,
+ then produces a single self-contained HTML file with Quality, SAST and Dependency Audit tabs.
Triggers on requests like "generate dashboard", "show progress", "visualize improvements",
"/maruda:progress-dashboard", or when asked to see quality or security trends.
---
# Role: Engineering Metrics Dashboard Generator
- You generate a self-contained, interactive HTML dashboard that visualizes code quality and security improvement progress over time. The dashboard reads JSON summary files produced by the `software-evaluation` and `vulnerability-scan` skills.
+ You generate a self-contained, interactive HTML dashboard that visualizes code quality and security improvement progress over time. The dashboard reads JSON summary files produced by the `software-evaluation`, `vulnerability-scan` and `dependency-audit` skills, and shows each on its own tab: **Quality**, **SAST** and **Dependency Audit**.
---
## Phase 1: Data Collection
### 1.1 Locate JSON Summary Files
Scan for JSON files in:
- `docs/evaluation/*.json` — software evaluation summaries
- `docs/security-audit/*.json` — vulnerability scan summaries
+ - `docs/dependency-audit/*.json` — dependency audit summaries
- If no JSON files exist, inform the user that they need to run `software-evaluation` and/or `vulnerability-scan` first with JSON output enabled.
+ If no JSON files exist, inform the user that they need to run `software-evaluation`, `vulnerability-scan` and/or `dependency-audit` first with JSON output enabled.
- ### 1.2 Parse & Validate
+ ### 1.2 Parse, Validate & Route by `type`
- For each JSON file, verify:
+ Route every file by its `type` field, not by its directory:
+
+ | `type` | Data constant | Tab |
+ |--------|---------------|-----|
+ | `software-evaluation` | `EVALUATION_DATA` | Quality |
+ | `vulnerability-scan` | `SECURITY_DATA` | SAST (and the Dependency Audit back-fill, 2.3) |
+ | `dependency-audit` | `DEPENDENCY_DATA` | Dependency Audit |
+
+ For each file, verify:
- `schemaVersion` is `"1.0"`
- - `type` is either `"software-evaluation"` or `"vulnerability-scan"`
+ - `type` is one of the three above
- `date` is a valid ISO date string
- - Required fields are present (scores for evaluation, findings for vulnerability)
+ - Required fields are present (scores for evaluation, findings for vulnerability scan, `status` for dependency audit)
+ A file whose `type` is unknown (or missing) is **skipped, not fatal**: leave it out of the data
+ constants, list its file name in `SKIPPED_FILES`, and tell the user which files were skipped.
+ One unreadable summary must never stop the whole dashboard.
+
Sort all entries by `date` ascending. Group by `target` if multiple targets exist.
---
## Phase 2: Dashboard Generation
### 2.1 Technology
Generate a **single self-contained HTML file** with:
- **Chart.js** via CDN (`https://cdn.jsdelivr.net/npm/chart.js`) for charts
- Inline CSS for styling (dark theme, responsive)
- - Inline JavaScript for data processing and chart rendering
+ - Inline JavaScript for data processing, tab switching and chart rendering
- No build step required — open directly in any browser
- ### 2.2 Dashboard Sections
-
- The HTML must include these sections:
+ ### 2.2 Layout
- #### Header
+ #### Header (shared)
- Project name (derived from target names)
- - Date range of available data
+ - Date range of available data, across all three sources
- Last updated timestamp
- #### 1. Quality Score Trend (Line Chart)
- - X-axis: dates
- - Y-axis: score (0–10)
- - Lines: one per pillar (Architecture, Reliability, Observability, Security, DX) + Overall
- - Tooltip: show exact score and date
- - Color-coded by pillar
+ #### Tabs
+ Three tabs — **Quality**, **SAST**, **Dependency Audit** — following the WAI-ARIA tabs pattern:
+ `role="tablist"` / `tab` / `tabpanel`, `aria-selected`, `aria-controls`, a roving `tabindex`,
+ Left/Right/Home/End to move between tabs, and a visible focus outline. Quality is selected
+ first.
- #### 2. Latest Score Radar Chart
- - Compare the most recent evaluation against the previous one
- - 5 axes for the 5 pillars
- - Two overlaid datasets: "Current" (solid) vs "Previous" (dashed)
- - If only one evaluation exists, show only "Current"
+ Draw a tab's charts the first time it is shown, not on page load: Chart.js measures a hidden
+ canvas as zero-width.
- #### 3. Security Findings Trend (Stacked Bar Chart)
- - X-axis: dates
- - Y-axis: finding count
- - Stacks: Critical (red), High (orange), Medium (yellow), Low (blue)
- - Separate bars or annotation for false positives
+ #### Quality tab (`software-evaluation`)
+ - **Summary cards** — Overall Quality (delta from previous), P0 Blockers (red if > 0), Security Score
+ - **Quality Score Trend** (line) — one line per pillar (Architecture, Reliability, Observability,
+ Security, DX) + Overall, y 0–10, color-coded by pillar
+ - **Latest vs Previous** (radar) — 5 pillar axes, "Current" solid vs "Previous" dashed; only
+ "Current" when a single evaluation exists
+ - **Roadmap Progress** — evaluation roadmap P0 / P1 over time
- #### 4. Improvement Velocity (Combined Metrics)
- - Roadmap items by priority (P0–P3) over time — show if P0/P1 counts are decreasing
- - Remediation priority items (P0, P1) from vulnerability scans
- - Use a grouped bar chart or summary cards
+ #### SAST tab (`vulnerability-scan`)
+ - **Summary cards** — Total Vulnerabilities (delta), Remediation P0 (red if > 0), False Positives
+ - **Security Findings Trend** (stacked bar) — Critical (red), High (orange), Medium (yellow), Low (blue)
+ - **Remediation Progress** — scan remediation P0 / P1 over time
+ - **Latest Findings** — `topFindings` of the latest scan
- #### 5. Dependency Risk Panel
- - Latest dependency vulnerability counts (Critical/High/Medium/Low)
- - Trend if multiple scans exist
+ #### Dependency Audit tab (`dependency-audit`, back-filled from `vulnerability-scan`)
+ - **Summary cards** — Dependency Vulnerabilities (latest total, delta), Latest Audit Status
+ (status, `notRunReason`, coverage, source), Upgrades P0 / P1, Scanner (version, pinned, DB date)
+ - **Dependency Vulnerabilities Trend** (stacked bar) — Critical / High / Medium / Low / Unknown,
+ one bar per date from the series in 2.3, the source in the tooltip
+ - **Dependency Remediation** — upgrade P0 / P1 from dependency-audit summaries
- #### 6. Summary Cards (Top Row)
- - **Overall Quality Score** — latest value with delta from previous
- - **Total Vulnerabilities** — latest count with delta
- - **P0 Blockers** — current count (red if > 0)
- - **Security Posture** — latest security pillar score
+ ### 2.3 The dependency series
- ### 2.3 Styling Requirements
+ The Dependency Audit trend is one series across the split, built per date:
+ 1. A `dependency-audit` summary on that date wins.
+ - `complete` → its `vulnerabilities` counts.
+ - `partial` → its counts, labelled "(partial)" — they cover scanned targets only.
+ - `not-run` (or any other status, or no `vulnerabilities`) → no counts, labelled "(not run)"
+ or "(unavailable)".
+ 2. Otherwise, the `dependencies` field of that date's `vulnerability-scan` summary, so the history
+ from before the split stays on the chart. Those summaries have no `unknown` severity: leave
+ it empty, not 0. A scan without `dependencies` (its audit was partial or did not run) has no
+ counts, labelled "(unavailable)".
+
+ A date without counts is a **labelled gap** — the bar is empty and the axis label says why. Never
+ draw it as 0, never leave it unlabelled, and never fall back to an older audit's counts for the
+ latest card (say "Last counted: <date>" instead): any of those reads as a clean audit.
+
+ ### 2.4 Styling Requirements
+
- Dark theme (background: `#0f172a`, cards: `#1e293b`, text: `#e2e8f0`)
- - Responsive: works on desktop and tablet
+ - Responsive: works on desktop and tablet; the tab bar scrolls horizontally when narrow
- Cards with subtle border radius and shadow
- Color palette:
- Architecture: `#3b82f6` (blue)
- Reliability: `#10b981` (green)
- Observability: `#f59e0b` (amber)
- Security: `#ef4444` (red)
- DX: `#8b5cf6` (purple)
- Overall: `#06b6d4` (cyan)
+ - Severity: Critical `#dc2626`, High `#f97316`, Medium `#eab308`, Low `#3b82f6`, Unknown `#64748b`
- ### 2.4 Data Embedding
+ ### 2.5 Data Embedding
- Embed the JSON data directly into the HTML as a JavaScript constant:
+ Embed the JSON data directly into the HTML as JavaScript constants:
```javascript
- const EVALUATION_DATA = [ /* parsed evaluation JSONs */ ];
- const SECURITY_DATA = [ /* parsed security-audit JSONs */ ];
+ const EVALUATION_DATA = [ /* software-evaluation JSONs */ ];
+ const SECURITY_DATA = [ /* vulnerability-scan JSONs */ ];
+ const DEPENDENCY_DATA = [ /* dependency-audit JSONs */ ];
+ const SKIPPED_FILES = [ /* file names skipped for an unknown type */ ];
```
+ Summaries are data, not markup. Embed them as JSON with `<` written as `<`, so a string
+ containing `</script>` cannot end the script block, and put every string from them into the
+ page with `textContent` — never `innerHTML`.
+
This makes the HTML fully self-contained and portable.
---
## Phase 3: Output
### 3.1 File Output
Save the generated dashboard as:
```
docs/dashboard.html
```
### 3.2 Quality Gate
Before finalizing, verify:
- - [ ] All available JSON summary files were included
- - [ ] Charts render correctly with the embedded data
+ - [ ] All available JSON summary files were included, routed by `type`; skipped files are listed
+ - [ ] Each tab renders its charts when opened, with the embedded data
+ - [ ] The Dependency Audit trend runs across the split without a break, and every date without counts is a labelled gap, not 0
+ - [ ] Tabs work with the keyboard (arrows, Home, End) and show focus
- [ ] The HTML is self-contained (no local file dependencies)
+ - [ ] No summary string is inserted as HTML
- [ ] Responsive layout works at 1200px and 768px widths
- [ ] Color contrast meets WCAG AA standards
- [ ] Delta calculations (current vs previous) are correct
---
## Phase 4: User Guidance
After generating the dashboard, tell the user:
1. Open `docs/dashboard.html` in a browser to view
- 2. Re-run this skill after new evaluations or scans to update
+ 2. Re-run this skill after new evaluations, scans or dependency audits to update
3. The dashboard can be committed to the repo for team visibility
> See `examples/progress-dashboard/` for sample JSON inputs and a working dashboard example.