feat: schema contracts + dashboard freshness — v1.6.0

JSON Schema (draft-07) for all evidence outputs with zero-dep validator
in CI. Dashboard now shows pipeline freshness banner, stale data warnings,
per-repo status dots, and trend arrows from health-trends.json.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dusan-maintains

.github/workflows/validate.yml

@@ -60,3 +60,18 @@ jobs:
       - name: Verify CLI runs
         working-directory: cli
         run: node bin/scan.js --version
+
+  validate-evidence:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Validate evidence schemas
+        run: node scripts/validate-evidence.js

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented here.
 
+## [1.6.0] — 2026-03-20
+
+### Added
+- **JSON Schema contracts**: Draft-07 schemas for all evidence output files — `ecosystem-status`, `health-scores`, `manifest`, `action-queue`. Machine-readable structure definitions in `schemas/` directory.
+- **Evidence validator**: Zero-dep Node.js script (`scripts/validate-evidence.js`) validates evidence JSON against schemas in CI. Handles PowerShell BOM, validates types/required/enum/ranges, first 5 items per array.
+- **CI validation step**: New `validate-evidence` job in `validate.yml` catches schema violations before merge.
+- **Dashboard freshness banner**: Pipeline status badge (success/partial/failed), relative time since last refresh ("2h ago"), step counts ("8/8 steps"). Stale data warning (orange banner) when data >12h old with link to GitHub Actions.
+- **Per-repo freshness dots**: Green/yellow/red dots on health cards showing per-repository pipeline status from `manifest.json`.
+- **Trend arrows on health cards**: ↑ improving, → stable, ↓ declining with 7-day delta from `health-trends.json`.
+- Dashboard now fetches `manifest.json` + `health-trends.json` alongside existing data (5 parallel fetches).
+
 ## [1.5.0] — 2026-03-20
 
 ### Added

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oss-health-scan",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Scan npm dependencies for abandoned packages, outdated versions (libyear), and known CVEs (OSV.dev). Health scores 0-100, SARIF for GitHub Code Scanning, zero dependencies.",
   "main": "./lib/api.js",
   "exports": {

docs/ARCHITECTURE.md

@@ -80,6 +80,17 @@ Package exports:
 - `critical-count` — number of packages below score 30
 - `avg-health` — average health score across tracked packages
 
+## Schema Contracts
+
+JSON Schema (draft-07) files in `schemas/` validate evidence output structure:
+
+- `schemas/ecosystem-status.schema.json` — aggregated ecosystem snapshot
+- `schemas/health-scores.schema.json` — per-package health scoring with breakdown
+- `schemas/manifest.schema.json` — pipeline run health (steps, per-repo status)
+- `schemas/action-queue.schema.json` — prioritized SLA action items
+
+Validated in CI by `scripts/validate-evidence.js` (zero dependencies, handles PowerShell BOM).
+
 ## Design Principles
 
 - One source of truth for tracked repositories.

docs/ROADMAP.md

@@ -25,27 +25,20 @@
 - ✅ CLI unit tests and smoke test in CI
 - ✅ Structural validation (config, markers, scripts, docs)
 
-## Next High-Impact Engineering Moves
-
-### 1. Schema Contracts
-
-Current gap: outputs are validated structurally by scripts and markers, but not by formal JSON schemas.
-
-Best next steps:
-
-- add JSON Schema for each output family (ecosystem-status, health-scores, manifest)
-- validate generated evidence in CI before commit
-- keep backward compatibility explicit with schema versioning
+### Schema Contracts
+- ✅ JSON Schema (draft-07) for all evidence output families: ecosystem-status, health-scores, manifest, action-queue
+- ✅ Zero-dep Node.js validator (`scripts/validate-evidence.js`) — runs in CI, strips BOM, validates types/required/enum/ranges
+- ✅ CI step `validate-evidence` in validate.yml workflow
+- ✅ PowerShell single-item quirk documented in action-queue schema (object | array)
+
+### Dashboard Freshness
+- ✅ Freshness banner: pipeline status badge (success/partial/failed), relative time, step counts
+- ✅ Stale data warning: orange banner when data >12h old with link to Actions
+- ✅ Per-repo freshness dots on health cards (green = fresh, yellow = partial, red = failed)
+- ✅ Trend arrows on health cards from health-trends.json (↑ improving, → stable, ↓ declining with 7d delta)
+- ✅ manifest.json + health-trends.json fetched alongside existing data
 
-### 2. Dashboard Freshness
-
-Current gap: dashboard consumes evidence JSON but doesn't surface staleness or partial-failure state.
-
-Best next steps:
-
-- consume manifest.json to show per-repo freshness status
-- add visual indicators for stale data (>12h since last refresh)
-- expose failing steps and link to manifest details
+## Next High-Impact Engineering Moves
 
 ## What Not To Prioritize
 

index.html

@@ -273,6 +273,60 @@
     font-size: 0.75rem;
   }
 
+  /* ── Freshness Banner ──────────────────────────────────── */
+  .freshness-banner {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 14px 20px;
+    margin-bottom: 24px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 8px;
+    font-size: 0.8rem;
+  }
+  .freshness-left { display: flex; align-items: center; gap: 10px; }
+  .pipe-badge {
+    padding: 3px 10px; border-radius: 20px;
+    font-size: 0.68rem; font-weight: 600;
+    text-transform: uppercase; letter-spacing: 0.04em;
+  }
+  .pipe-badge.success { background: var(--green-dim); color: var(--green); }
+  .pipe-badge.partial { background: var(--yellow-dim); color: var(--yellow); }
+  .pipe-badge.failed { background: var(--red-dim); color: var(--red); }
+  .freshness-right { color: var(--muted); font-size: 0.72rem; }
+
+  .stale-banner {
+    background: rgba(234,179,8,0.08);
+    border: 1px solid rgba(234,179,8,0.25);
+    border-radius: 12px;
+    padding: 12px 20px;
+    margin-bottom: 16px;
+    color: var(--yellow);
+    font-size: 0.8rem;
+    font-weight: 500;
+  }
+
+  /* ── Trend & Freshness on Cards ──────────────────────── */
+  .trend-tag {
+    font-size: 0.68rem; font-weight: 600;
+    display: inline-flex; align-items: center; gap: 3px;
+    padding: 2px 8px; border-radius: 10px;
+    margin-top: 6px;
+  }
+  .trend-tag.up { background: var(--green-dim); color: var(--green); }
+  .trend-tag.down { background: var(--red-dim); color: var(--red); }
+  .trend-tag.stable { background: rgba(100,116,139,0.12); color: var(--muted); }
+  .repo-status-dot {
+    width: 7px; height: 7px; border-radius: 50%;
+    display: inline-block; margin-right: 4px; flex-shrink: 0;
+  }
+  .repo-status-dot.fresh { background: var(--green); }
+  .repo-status-dot.partial { background: var(--yellow); }
+  .repo-status-dot.failed { background: var(--red); }
+
   .loading { color: var(--muted); font-size: 0.85rem; padding: 24px; text-align: center; }
   .error { color: var(--red); font-size: 0.85rem; padding: 24px; }
 
@@ -319,6 +373,9 @@ <h1>OSS Maintenance Log</h1>
     <div class="stat"><div class="label">Open PRs</div><div class="value purple" id="s-prs">—</div></div>
   </div>
 
+  <!-- Freshness Banner -->
+  <div id="freshness-wrap"></div>
+
   <!-- Health Score Cards -->
   <section>
     <h2>Package Health Scores</h2>
@@ -367,6 +424,16 @@ <h2>Action Queue</h2>
   return String(n);
 }
 
+function relTime(dateStr) {
+  const ms = Date.now() - new Date(dateStr).getTime();
+  const m = Math.floor(ms / 60000);
+  if (m < 1) return 'just now';
+  if (m < 60) return m + 'm ago';
+  const h = Math.floor(m / 60);
+  if (h < 24) return h + 'h ago';
+  return Math.floor(h / 24) + 'd ago';
+}
+
 function scoreColor(score) {
   if (score < 30) return COLORS.red;
   if (score < 60) return COLORS.yellow;
@@ -400,15 +467,30 @@ <h2>Action Queue</h2>
   </div>`;
 }
 
-function healthCard(s, i) {
+function trendTag(trend) {
+  if (!trend) return '';
+  const t = trend.trend || 'stable';
+  const d7 = trend.delta_7d;
+  const arrow = t === 'improving' ? '↑' : t === 'declining' ? '↓' : '→';
+  const cls = t === 'improving' ? 'up' : t === 'declining' ? 'down' : 'stable';
+  const delta = d7 != null ? ` ${d7 > 0 ? '+' : ''}${d7.toFixed(1)}` : '';
+  return `<span class="trend-tag ${cls}">${arrow}${delta}</span>`;
+}
+
+function healthCard(s, i, trendMap, repoStatusMap) {
   const color = scoreColor(s.health_score);
   const b = s.breakdown;
+  const key = s.owner + '/' + s.repo;
+  const trend = trendMap && trendMap[key];
+  const repoStatus = repoStatusMap && repoStatusMap[key];
+  const dot = repoStatus ? `<span class="repo-status-dot ${repoStatus}" title="${repoStatus}"></span>` : '';
   return `<div class="health-card animate-in" style="animation-delay:${i * 0.08}s">
     <div class="card-header">
       <div>
-        <div class="pkg-owner">${s.owner}</div>
+        <div class="pkg-owner">${dot}${s.owner}</div>
         <div class="pkg-name"><a href="${s.repo_url}" target="_blank">${s.repo}</a></div>
         ${riskBadge(s.risk_level)}
+        ${trendTag(trend)}
       </div>
       ${scoreCircle(s.health_score, color)}
     </div>
@@ -428,10 +510,12 @@ <h2>Action Queue</h2>
 
 async function load() {
   try {
-    const [eco, health, queue] = await Promise.all([
+    const [eco, health, queue, manifest, trends] = await Promise.all([
       fetch(RAW + 'ecosystem-status.json').then(r => r.json()),
       fetch(RAW + 'health-scores.json').then(r => r.json()).catch(() => null),
-      fetch(RAW + 'action-queue.json').then(r => r.json()).catch(() => null)
+      fetch(RAW + 'action-queue.json').then(r => r.json()).catch(() => null),
+      fetch(RAW + 'manifest.json').then(r => r.json()).catch(() => null),
+      fetch(RAW + 'health-trends.json').then(r => r.json()).catch(() => null)
     ]);
 
     const sm = eco.summary || {};
@@ -451,11 +535,46 @@ <h2>Action Queue</h2>
         'Last updated: ' + new Date(eco.generated_at_utc).toUTCString();
     }
 
+    // Freshness banner
+    const fw = document.getElementById('freshness-wrap');
+    if (manifest) {
+      const ts = manifest.run_completed_at_utc || manifest.run_started_at_utc;
+      const ms = manifest.summary || {};
+      const status = manifest.run_status || 'unknown';
+      const stepsInfo = ms.total_steps ? `${ms.successful_steps}/${ms.total_steps} steps` : '';
+      const failInfo = ms.failed_steps > 0 ? `, ${ms.failed_steps} failed` : '';
+      const ageMs = ts ? Date.now() - new Date(ts).getTime() : 0;
+      const stale = ageMs > 12 * 3600 * 1000;
+
+      let html = '';
+      if (stale) {
+        html += `<div class="stale-banner">Data is ${relTime(ts)} old — pipeline may not be running. <a href="https://github.com/dusan-maintains/oss-maintenance-log/actions/workflows/evidence-daily.yml">Check Actions</a></div>`;
+      }
+      html += `<div class="freshness-banner">
+        <div class="freshness-left">
+          <span class="pipe-badge ${status}">${status}</span>
+          <span style="color:var(--text)">Pipeline refreshed ${ts ? relTime(ts) : '—'}</span>
+        </div>
+        <div class="freshness-right">${stepsInfo}${failInfo}</div>
+      </div>`;
+      fw.innerHTML = html;
+    }
+
+    // Build trend + repo-status maps
+    const trendMap = {};
+    if (trends && trends.trends) {
+      for (const t of trends.trends) trendMap[t.repo] = t;
+    }
+    const repoStatusMap = {};
+    if (manifest && manifest.repositories) {
+      for (const r of manifest.repositories) repoStatusMap[r.repository] = r.status;
+    }
+
     // Health cards
     if (health && health.scores) {
       const sorted = [...health.scores].sort((a,b) => a.health_score - b.health_score);
       document.getElementById('health-cards').innerHTML =
-        sorted.map((s, i) => healthCard(s, i)).join('');
+        sorted.map((s, i) => healthCard(s, i, trendMap, repoStatusMap)).join('');
     } else {
       // Fallback: show ecosystem data without health scores
       document.getElementById('health-cards').innerHTML =

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oss-health-scan",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": true,
   "description": "Scan npm dependencies for abandoned/unhealthy packages. Get health scores (0-100).",
   "bin": {

schemas/action-queue.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Action Queue",
+  "description": "Cross-repo prioritized action list built from SLA outputs.",
+  "type": "object",
+  "required": ["generated_at_utc", "open_actions", "urgent_actions", "items"],
+  "properties": {
+    "generated_at_utc": { "type": "string" },
+    "open_actions": { "type": "number", "minimum": 0 },
+    "urgent_actions": { "type": "number", "minimum": 0 },
+    "items": {
+      "description": "Single object when 1 item (PowerShell quirk), array when multiple",
+      "type": ["array", "object"],
+      "items": {
+        "type": "object",
+        "required": ["repository", "pr_number"],
+        "properties": {
+          "repository": { "type": "string" },
+          "pr_number": { "type": "number" },
+          "pr_title": { "type": "string" },
+          "pr_url": { "type": "string" },
+          "hours_since_last_external": { "type": "number" },
+          "overdue_sla": { "type": "boolean" },
+          "priority": { "type": "string" }
+        }
+      }
+    }
+  }
+}

schemas/ecosystem-status.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Ecosystem Status",
+  "description": "Aggregated snapshot across all tracked repositories. Generated by update-all-evidence.ps1.",
+  "type": "object",
+  "required": ["generated_at_utc", "summary", "projects"],
+  "properties": {
+    "generated_at_utc": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "required": ["tracked_projects", "tracked_prs_total", "tracked_prs_open", "total_stars", "total_forks", "total_npm_downloads_last_week"],
+      "properties": {
+        "tracked_projects": { "type": "number", "minimum": 0 },
+        "tracked_prs_total": { "type": "number", "minimum": 0 },
+        "tracked_prs_open": { "type": "number", "minimum": 0 },
+        "total_stars": { "type": "number", "minimum": 0 },
+        "total_forks": { "type": "number", "minimum": 0 },
+        "total_npm_downloads_last_week": { "type": "number", "minimum": 0 }
+      }
+    },
+    "projects": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["owner", "repo"],
+        "properties": {
+          "owner": { "type": "string" },
+          "repo": { "type": "string" },
+          "repo_url": { "type": "string" },
+          "stars": { "type": "number" },
+          "forks": { "type": "number" },
+          "open_issues": { "type": "number" },
+          "pushed_at": { "type": "string" },
+          "package": { "type": ["string", "null"] },
+          "npm_downloads_last_week": { "type": "number" },
+          "status_label": { "type": "string" },
+          "tracked_pr_numbers": { "type": "array", "items": { "type": "number" } },
+          "tracked_prs_open": { "type": "number" },
+          "tracked_pr_details": { "type": "array" }
+        }
+      }
+    }
+  }
+}