@mcptoolshop/registry-stats 3.1.0 → 3.2.0

package/README.md

@@ -50,10 +50,12 @@ A self-updating stats dashboard lives at [`/dashboard/`](https://mcp-tool-shop-o
 - **Tabbed interface** — Home, Analytics, Leaderboard, and Help tabs
 - **Pulse AI co-pilot** — Ollama-powered conversational assistant with streaming voice synthesis (speaks as the LLM streams, 4 voices via [mcp-voice-soundboard](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard)), web search (Wikipedia + optional SearXNG), auto-speak, fullscreen mode, GitHub org data connector, model selector, and conversation memory
 - **Executive snapshot** — health score (0–100), diversity index, weekly change, total downloads across all registries
-- **Six interactive charts** — 30-day trend (aggregate / per-registry / top-5 toggles), registry share (polar area), portfolio risk (histogram + Gini & P90), top-10 momentum, velocity tracker with sparklines, and 30-day heatmap with spike detection (>2σ)
+- **Seven interactive charts** — 30-day trend (aggregate / per-registry / top-5 toggles + click-to-drill-down + scroll zoom/pan), registry share (polar area), portfolio risk (histogram + Gini & P90), top-10 momentum, velocity tracker with sparklines, 30-day heatmap with spike detection (>2σ), and portfolio trend (stacked area, yearly)
 - **Smart growth engine** — handles small-denominator distortion with baseline threshold, percentage cap, and damped velocity formula
-- **AI Inference Panel** — portfolio momentum (-100 to +100), risk score, 7-day forecast with confidence intervals, and automated recommendations (growth, risk, opportunity, attention)
-- **Actionable insights** — auto-generated recommendations and attention alerts for declining packages
+- **AI Inference Panel** — portfolio momentum (-100 to +100), risk score, 7-day forecast with confidence intervals, automated recommendations, actionable advice with severity/urgency levels, and package health scoreboard (A–F grades)
+- **Actionable advice** — severity-tagged advice cards (critical/warning/info/success) with urgency levels, specific action steps, and affected package lists
+- **Package health scores** — 0–100 composite score (activity + consistency + growth + stability) with letter grades per package
+- **Yearly progress tracking** — persistent history layer accumulates monthly per-package and weekly portfolio aggregates; portfolio trend chart with per-registry stacking
 - **Pulse panel** — split view of Established Movers (≥ 50 downloads/wk) and Emerging & New packages, with inline 7-day sparklines, absolute + percentage deltas, baseline context, and a one-line executive summary
 - **Live refresh** — on-demand client-side fetch from npm and PyPI APIs with progress indicator; results cached in sessionStorage (5 min TTL) so tab switches are instant
 - **Export reports** — dropdown next to the Refresh button offering three formats: **Exec PDF** (via jsPDF), **LLM JSONL** (typed records for AI ingestion), and **Dev Markdown** (GFM tables)
@@ -75,7 +77,9 @@ Zero-dependency, pure-math inference that runs at build time — no ML runtime,
 import {
   forecast, detectAnomalies, segmentTrends,
   detectSeasonality, computeMomentum,
-  generateRecommendations, inferPortfolio,
+  generateRecommendations, computeHealthScore,
+  generateActionableAdvice, computeYearlyProgress,
+  inferPortfolio,
 } from '@mcptoolshop/registry-stats';
 
 // 7-day forecast with 80% confidence intervals
@@ -89,9 +93,17 @@ const anomalies = detectAnomalies(dailySeries);
 // Composite momentum score (-100 to +100)
 const momentum = computeMomentum(dailySeries);
 
-// Full portfolio analysis
+// Package health score (0-100 with A-F grade)
+const health = computeHealthScore('my-pkg', 'npm', dailySeries, momentum);
+// → { score: 72, grade: 'B', components: { activity: 20, consistency: 18, growth: 16, stability: 18 } }
+
+// Yearly progress from monthly history
+const progress = computeYearlyProgress('my-pkg', 'npm', monthlyHistory);
+// → { currentYearTotal, yoyGrowthPct, projectedYearEnd, milestones, ... }
+
+// Full portfolio analysis (now includes health scores + actionable advice)
 const result = inferPortfolio(leaderboard, { gini: 0.6, npmPct: 85 });
-// → { packages, forecastTotal7, riskScore, portfolioMomentum, recommendations }
+// → { packages, forecastTotal7, riskScore, portfolioMomentum, recommendations, healthScores, actionableAdvice }
 ```
 
 | Capability | Method | What it does |
@@ -101,6 +113,9 @@ const result = inferPortfolio(leaderboard, { gini: 0.6, npmPct: 85 });
 | **Trend segmentation** | Piecewise linear | Identifies up/down/flat segments in time series |
 | **Seasonality** | Day-of-week decomposition | Detects weekly patterns, reports peak day |
 | **Momentum** | Composite score | Direction + acceleration + consistency + volume |
+| **Health score** | Multi-factor composite | Activity + consistency + growth + stability (0–100, A–F grade) |
+| **Yearly progress** | Monthly accumulation | YoY growth, projected year-end, milestone tracking |
+| **Actionable advice** | Severity rule engine | Critical/warning/info/success with urgency and specific actions |
 | **Recommendations** | Rule engine | Growth, risk, opportunity, and attention categories |
 
 ## Desktop App

package/dist/index.cjs

@@ -22,13 +22,16 @@ var index_exports = {};
 __export(index_exports, {
   RegistryError: () => RegistryError,
   calc: () => calc,
+  computeHealthScore: () => computeHealthScore,
   computeMomentum: () => computeMomentum,
+  computeYearlyProgress: () => computeYearlyProgress,
   createCache: () => createCache,
   createHandler: () => createHandler,
   defaultConfig: () => defaultConfig,
   detectAnomalies: () => detectAnomalies,
   detectSeasonality: () => detectSeasonality,
   forecast: () => forecast,
+  generateActionableAdvice: () => generateActionableAdvice,
   generateRecommendations: () => generateRecommendations,
   inferPortfolio: () => inferPortfolio,
   loadConfig: () => loadConfig,
@@ -774,6 +777,181 @@ function computeMomentum(series) {
   const volumeScore = last7Sum > 0 ? Math.min(20, Math.log10(last7Sum + 1) * 5) : 0;
   return Math.round(Math.max(-100, Math.min(100, dirScore + accelScore + consistencyScore + volumeScore)));
 }
+var MILESTONE_THRESHOLDS = [100, 500, 1e3, 5e3, 1e4, 5e4, 1e5, 5e5, 1e6];
+function computeYearlyProgress(name, registry, monthlyHistory) {
+  const now = /* @__PURE__ */ new Date();
+  const currentYear = now.getFullYear();
+  const currentMonth = now.getMonth();
+  const prevYear = currentYear - 1;
+  const currentMonths = [];
+  const prevMonths = [];
+  for (const [monthKey, agg] of Object.entries(monthlyHistory)) {
+    const [yearStr, monthStr] = monthKey.split("-");
+    const year = parseInt(yearStr, 10);
+    const dl = agg.month || agg.week * 4;
+    if (year === currentYear) {
+      currentMonths.push({ month: monthKey, downloads: dl });
+    } else if (year === prevYear) {
+      prevMonths.push({ month: monthKey, downloads: dl });
+    }
+  }
+  currentMonths.sort((a, b) => a.month.localeCompare(b.month));
+  prevMonths.sort((a, b) => a.month.localeCompare(b.month));
+  const currentYearTotal = currentMonths.reduce((s, m) => s + m.downloads, 0);
+  const previousYearTotal = prevMonths.length > 0 ? prevMonths.reduce((s, m) => s + m.downloads, 0) : null;
+  const yoyGrowthPct = previousYearTotal !== null && previousYearTotal > 0 ? (currentYearTotal - previousYearTotal) / previousYearTotal * 100 : null;
+  const monthsElapsed = currentMonth + 1;
+  const monthlyRate = monthsElapsed > 0 ? currentYearTotal / monthsElapsed : 0;
+  const projectedYearEnd = Math.round(monthlyRate * 12);
+  const bestMonth = currentMonths.length > 0 ? currentMonths.reduce((best, m) => m.downloads > best.downloads ? m : best) : null;
+  const milestones = MILESTONE_THRESHOLDS.filter((t) => t <= projectedYearEnd * 2).map((threshold) => {
+    const crossed = currentYearTotal >= threshold;
+    const crossedAt = crossed ? currentMonths.find((_, idx) => {
+      const running = currentMonths.slice(0, idx + 1).reduce((s, m) => s + m.downloads, 0);
+      return running >= threshold;
+    })?.month : void 0;
+    return { threshold, crossed, ...crossedAt ? { crossedAt } : {} };
+  });
+  return {
+    name,
+    registry,
+    currentYearTotal,
+    previousYearTotal,
+    yoyGrowthPct: yoyGrowthPct !== null ? Math.round(yoyGrowthPct * 10) / 10 : null,
+    projectedYearEnd,
+    monthlyTotals: currentMonths,
+    bestMonth,
+    milestones
+  };
+}
+function computeHealthScore(name, registry, series, momentum) {
+  const empty = {
+    name,
+    registry,
+    score: 0,
+    grade: "F",
+    components: { activity: 0, consistency: 0, growth: 0, stability: 0 }
+  };
+  if (!series || series.length < 7) return empty;
+  const last7Sum = series.slice(-7).reduce((a, b) => a + b, 0);
+  const activity = Math.min(25, Math.round(Math.log10(last7Sum + 1) * 7));
+  const last14 = series.slice(-14);
+  const m = mean(last14);
+  const cv = m > 0 ? stddev(last14) / m : 1;
+  const consistency = Math.min(25, Math.round(Math.max(0, 25 - cv * 25)));
+  const growth = Math.round(Math.max(0, Math.min(25, (momentum + 100) / 8)));
+  const anomalies = detectAnomalies(series, 2.5);
+  const anomalyPenalty = Math.min(25, anomalies.length * 8);
+  const stability = Math.max(0, 25 - anomalyPenalty);
+  const score = activity + consistency + growth + stability;
+  const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+  return {
+    name,
+    registry,
+    score,
+    grade,
+    components: { activity, consistency, growth, stability }
+  };
+}
+function generateActionableAdvice(packages, healthScores, opts = {}) {
+  const advice = [];
+  const failing = healthScores.filter((h) => h.grade === "F");
+  if (failing.length > 0) {
+    advice.push({
+      type: "attention",
+      severity: "critical",
+      urgency: "immediate",
+      title: `${failing.length} package${failing.length > 1 ? "s" : ""} in critical health`,
+      detail: `${failing.map((h) => h.name).slice(0, 5).join(", ")} scored below 20/100.`,
+      action: "Review these packages for broken installs, outdated dependencies, or missing documentation. Consider archiving if no longer maintained.",
+      packages: failing.map((h) => h.name)
+    });
+  }
+  const steepDecline = packages.filter((p) => p.momentum < -50);
+  if (steepDecline.length > 0) {
+    advice.push({
+      type: "attention",
+      severity: "warning",
+      urgency: "this-week",
+      title: `${steepDecline.length} package${steepDecline.length > 1 ? "s" : ""} in rapid decline`,
+      detail: `${steepDecline.map((p) => p.name).slice(0, 3).join(", ")} lost significant download momentum.`,
+      action: "Check for competing packages, broken releases, or ecosystem changes. Push a patch release or announcement.",
+      packages: steepDecline.map((p) => p.name)
+    });
+  }
+  if (opts.gini !== void 0 && opts.gini > 0.7) {
+    advice.push({
+      type: "risk",
+      severity: opts.gini > 0.85 ? "warning" : "info",
+      urgency: "this-month",
+      title: "Portfolio concentration risk",
+      detail: `Gini coefficient ${opts.gini.toFixed(2)} \u2014 downloads are concentrated in a few packages.`,
+      action: "Promote underperforming packages in README badges, blog posts, and release notes of popular packages.",
+      metric: `Gini: ${opts.gini.toFixed(2)}`
+    });
+  }
+  if (opts.npmPct !== void 0 && opts.npmPct > 75) {
+    advice.push({
+      type: "risk",
+      severity: "info",
+      urgency: "this-month",
+      title: `${opts.npmPct}% of traffic from npm`,
+      detail: "Single-registry dependency increases blast radius if npm has outages or policy changes.",
+      action: "Cross-publish key packages to PyPI (via wrapper) or NuGet. Add install instructions for all registries in READMEs.",
+      metric: `npm share: ${opts.npmPct}%`
+    });
+  }
+  const surging = packages.filter((p) => p.momentum > 50);
+  if (surging.length > 0) {
+    advice.push({
+      type: "opportunity",
+      severity: "success",
+      urgency: "this-week",
+      title: `${surging.length} package${surging.length > 1 ? "s" : ""} surging`,
+      detail: `${surging.map((p) => p.name).slice(0, 3).join(", ")} have strong positive momentum.`,
+      action: 'Capitalize now: write a blog post, tweet, or submit to newsletters. Post a "Thank you" issue or discussion.',
+      packages: surging.map((p) => p.name)
+    });
+  }
+  const highVolume = packages.filter((p) => {
+    const pkg = packages.find((pp) => pp.name === p.name);
+    return pkg && pkg.forecast7.length > 0 && pkg.forecast7[6]?.predicted > 100;
+  });
+  for (const pkg of highVolume.slice(0, 3)) {
+    const weekSum = pkg.forecast7.reduce((s, f) => s + f.predicted, 0);
+    for (const threshold of [1e3, 5e3, 1e4]) {
+      if (weekSum >= threshold * 0.9 && weekSum <= threshold * 1.1) {
+        advice.push({
+          type: "milestone",
+          severity: "success",
+          urgency: "informational",
+          title: `${pkg.name} approaching ${threshold.toLocaleString()} weekly downloads`,
+          detail: `Forecasted at ~${weekSum.toLocaleString()} downloads next week.`,
+          action: "Prepare a milestone announcement and update the README with a downloads badge.",
+          packages: [pkg.name]
+        });
+      }
+    }
+  }
+  const dGrade = healthScores.filter((h) => h.grade === "D");
+  const easyWins = dGrade.filter((h) => {
+    return h.components.activity >= 10 && h.components.growth < 10;
+  });
+  if (easyWins.length > 0) {
+    advice.push({
+      type: "opportunity",
+      severity: "info",
+      urgency: "this-month",
+      title: `${easyWins.length} package${easyWins.length > 1 ? "s" : ""} with untapped potential`,
+      detail: `${easyWins.map((h) => h.name).slice(0, 3).join(", ")} have active users but stalled growth.`,
+      action: "Add new features, improve docs, or create tutorials. Small efforts can shift these from D to C+ quickly.",
+      packages: easyWins.map((h) => h.name)
+    });
+  }
+  const severityOrder = { critical: 0, warning: 1, success: 2, info: 3 };
+  advice.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  return advice;
+}
 function generateRecommendations(packages, opts = {}) {
   const recs = [];
   const declining = packages.filter((p) => p.momentum < -30);
@@ -891,13 +1069,20 @@ function inferPortfolio(leaderboard, opts = {}) {
   const riskScore = Math.round(Math.max(0, Math.min(100, giniRisk + declineRisk + anomalyRisk)));
   const diversityTrend = "stable";
   const recommendations = generateRecommendations(packages, opts);
+  const healthScores = leaderboard.map((row) => {
+    const pkg = packages.find((p) => p.name === row.name);
+    return computeHealthScore(row.name, row.registry, row.range30 ?? null, pkg?.momentum ?? 0);
+  });
+  const actionableAdvice = generateActionableAdvice(packages, healthScores, opts);
   return {
     packages,
     recommendations,
     forecastTotal7,
     riskScore,
     diversityTrend,
-    portfolioMomentum: Math.round(weightedMomentum)
+    portfolioMomentum: Math.round(weightedMomentum),
+    healthScores,
+    actionableAdvice
   };
 }
 
@@ -1098,13 +1283,16 @@ stats.mine = async function mine(maintainer, options) {
 0 && (module.exports = {
   RegistryError,
   calc,
+  computeHealthScore,
   computeMomentum,
+  computeYearlyProgress,
   createCache,
   createHandler,
   defaultConfig,
   detectAnomalies,
   detectSeasonality,
   forecast,
+  generateActionableAdvice,
   generateRecommendations,
   inferPortfolio,
   loadConfig,

package/dist/index.d.cts

@@ -149,6 +149,55 @@ interface Recommendation {
     detail: string;
     metric?: string;
 }
+interface MonthlyAggregate {
+    week: number;
+    month: number;
+    total: number;
+    lastUpdated: string;
+}
+interface YearlyProgress {
+    name: string;
+    registry: string;
+    currentYearTotal: number;
+    previousYearTotal: number | null;
+    yoyGrowthPct: number | null;
+    projectedYearEnd: number;
+    monthlyTotals: Array<{
+        month: string;
+        downloads: number;
+    }>;
+    bestMonth: {
+        month: string;
+        downloads: number;
+    } | null;
+    milestones: Array<{
+        threshold: number;
+        crossed: boolean;
+        crossedAt?: string;
+    }>;
+}
+interface PackageHealthScore {
+    name: string;
+    registry: string;
+    score: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    components: {
+        activity: number;
+        consistency: number;
+        growth: number;
+        stability: number;
+    };
+}
+interface ActionableAdvice {
+    type: 'growth' | 'risk' | 'opportunity' | 'attention' | 'milestone';
+    severity: 'critical' | 'warning' | 'info' | 'success';
+    urgency: 'immediate' | 'this-week' | 'this-month' | 'informational';
+    title: string;
+    detail: string;
+    action: string;
+    metric?: string;
+    packages?: string[];
+}
 interface PackageInference {
     name: string;
     registry: string;
@@ -168,6 +217,8 @@ interface PortfolioInference {
     riskScore: number;
     diversityTrend: 'improving' | 'stable' | 'declining';
     portfolioMomentum: number;
+    healthScores: PackageHealthScore[];
+    actionableAdvice: ActionableAdvice[];
 }
 /**
  * Forecast next N days using weighted linear regression on recent data.
@@ -199,6 +250,25 @@ declare function detectSeasonality(series: number[], startDaysAgo: number): {
  * Combines: short-term trend, acceleration, volume, and consistency.
  */
 declare function computeMomentum(series: number[]): number;
+/**
+ * Compute yearly progress for a package given its monthly history.
+ * `monthlyHistory` maps month keys ("2026-01") to MonthlyAggregate.
+ */
+declare function computeYearlyProgress(name: string, registry: string, monthlyHistory: Record<string, MonthlyAggregate>): YearlyProgress;
+/**
+ * Compute a health score (0-100) for a package based on its 30-day series.
+ * Grade scale: A (80-100), B (60-79), C (40-59), D (20-39), F (0-19).
+ */
+declare function computeHealthScore(name: string, registry: string, series: number[] | null, momentum: number): PackageHealthScore;
+/**
+ * Generate specific, actionable advice with severity and urgency levels.
+ * More detailed than `generateRecommendations` — includes concrete steps.
+ */
+declare function generateActionableAdvice(packages: PackageInference[], healthScores: PackageHealthScore[], opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): ActionableAdvice[];
 /**
  * Generate automated recommendations based on portfolio analysis.
  */
@@ -237,4 +307,4 @@ declare namespace stats {
     }) => Promise<PackageStats[]>;
 }
 
-export { type Anomaly, type ChartData, type ComparisonResult, type Config, type DailyDownloads, type ForecastPoint, type PackageConfig, type PackageInference, type PackageStats, type PortfolioInference, type RateLimitConfig, type Recommendation, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, type TrendSegment, calc, computeMomentum, createCache, createHandler, defaultConfig, detectAnomalies, detectSeasonality, forecast, generateRecommendations, inferPortfolio, loadConfig, registerProvider, segmentTrends, serve, starterConfig, stats };
+export { type ActionableAdvice, type Anomaly, type ChartData, type ComparisonResult, type Config, type DailyDownloads, type ForecastPoint, type MonthlyAggregate, type PackageConfig, type PackageHealthScore, type PackageInference, type PackageStats, type PortfolioInference, type RateLimitConfig, type Recommendation, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, type TrendSegment, type YearlyProgress, calc, computeHealthScore, computeMomentum, computeYearlyProgress, createCache, createHandler, defaultConfig, detectAnomalies, detectSeasonality, forecast, generateActionableAdvice, generateRecommendations, inferPortfolio, loadConfig, registerProvider, segmentTrends, serve, starterConfig, stats };

package/dist/index.d.ts

@@ -149,6 +149,55 @@ interface Recommendation {
     detail: string;
     metric?: string;
 }
+interface MonthlyAggregate {
+    week: number;
+    month: number;
+    total: number;
+    lastUpdated: string;
+}
+interface YearlyProgress {
+    name: string;
+    registry: string;
+    currentYearTotal: number;
+    previousYearTotal: number | null;
+    yoyGrowthPct: number | null;
+    projectedYearEnd: number;
+    monthlyTotals: Array<{
+        month: string;
+        downloads: number;
+    }>;
+    bestMonth: {
+        month: string;
+        downloads: number;
+    } | null;
+    milestones: Array<{
+        threshold: number;
+        crossed: boolean;
+        crossedAt?: string;
+    }>;
+}
+interface PackageHealthScore {
+    name: string;
+    registry: string;
+    score: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    components: {
+        activity: number;
+        consistency: number;
+        growth: number;
+        stability: number;
+    };
+}
+interface ActionableAdvice {
+    type: 'growth' | 'risk' | 'opportunity' | 'attention' | 'milestone';
+    severity: 'critical' | 'warning' | 'info' | 'success';
+    urgency: 'immediate' | 'this-week' | 'this-month' | 'informational';
+    title: string;
+    detail: string;
+    action: string;
+    metric?: string;
+    packages?: string[];
+}
 interface PackageInference {
     name: string;
     registry: string;
@@ -168,6 +217,8 @@ interface PortfolioInference {
     riskScore: number;
     diversityTrend: 'improving' | 'stable' | 'declining';
     portfolioMomentum: number;
+    healthScores: PackageHealthScore[];
+    actionableAdvice: ActionableAdvice[];
 }
 /**
  * Forecast next N days using weighted linear regression on recent data.
@@ -199,6 +250,25 @@ declare function detectSeasonality(series: number[], startDaysAgo: number): {
  * Combines: short-term trend, acceleration, volume, and consistency.
  */
 declare function computeMomentum(series: number[]): number;
+/**
+ * Compute yearly progress for a package given its monthly history.
+ * `monthlyHistory` maps month keys ("2026-01") to MonthlyAggregate.
+ */
+declare function computeYearlyProgress(name: string, registry: string, monthlyHistory: Record<string, MonthlyAggregate>): YearlyProgress;
+/**
+ * Compute a health score (0-100) for a package based on its 30-day series.
+ * Grade scale: A (80-100), B (60-79), C (40-59), D (20-39), F (0-19).
+ */
+declare function computeHealthScore(name: string, registry: string, series: number[] | null, momentum: number): PackageHealthScore;
+/**
+ * Generate specific, actionable advice with severity and urgency levels.
+ * More detailed than `generateRecommendations` — includes concrete steps.
+ */
+declare function generateActionableAdvice(packages: PackageInference[], healthScores: PackageHealthScore[], opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): ActionableAdvice[];
 /**
  * Generate automated recommendations based on portfolio analysis.
  */
@@ -237,4 +307,4 @@ declare namespace stats {
     }) => Promise<PackageStats[]>;
 }
 
-export { type Anomaly, type ChartData, type ComparisonResult, type Config, type DailyDownloads, type ForecastPoint, type PackageConfig, type PackageInference, type PackageStats, type PortfolioInference, type RateLimitConfig, type Recommendation, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, type TrendSegment, calc, computeMomentum, createCache, createHandler, defaultConfig, detectAnomalies, detectSeasonality, forecast, generateRecommendations, inferPortfolio, loadConfig, registerProvider, segmentTrends, serve, starterConfig, stats };
+export { type ActionableAdvice, type Anomaly, type ChartData, type ComparisonResult, type Config, type DailyDownloads, type ForecastPoint, type MonthlyAggregate, type PackageConfig, type PackageHealthScore, type PackageInference, type PackageStats, type PortfolioInference, type RateLimitConfig, type Recommendation, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, type TrendSegment, type YearlyProgress, calc, computeHealthScore, computeMomentum, computeYearlyProgress, createCache, createHandler, defaultConfig, detectAnomalies, detectSeasonality, forecast, generateActionableAdvice, generateRecommendations, inferPortfolio, loadConfig, registerProvider, segmentTrends, serve, starterConfig, stats };

package/dist/index.js

@@ -732,6 +732,181 @@ function computeMomentum(series) {
   const volumeScore = last7Sum > 0 ? Math.min(20, Math.log10(last7Sum + 1) * 5) : 0;
   return Math.round(Math.max(-100, Math.min(100, dirScore + accelScore + consistencyScore + volumeScore)));
 }
+var MILESTONE_THRESHOLDS = [100, 500, 1e3, 5e3, 1e4, 5e4, 1e5, 5e5, 1e6];
+function computeYearlyProgress(name, registry, monthlyHistory) {
+  const now = /* @__PURE__ */ new Date();
+  const currentYear = now.getFullYear();
+  const currentMonth = now.getMonth();
+  const prevYear = currentYear - 1;
+  const currentMonths = [];
+  const prevMonths = [];
+  for (const [monthKey, agg] of Object.entries(monthlyHistory)) {
+    const [yearStr, monthStr] = monthKey.split("-");
+    const year = parseInt(yearStr, 10);
+    const dl = agg.month || agg.week * 4;
+    if (year === currentYear) {
+      currentMonths.push({ month: monthKey, downloads: dl });
+    } else if (year === prevYear) {
+      prevMonths.push({ month: monthKey, downloads: dl });
+    }
+  }
+  currentMonths.sort((a, b) => a.month.localeCompare(b.month));
+  prevMonths.sort((a, b) => a.month.localeCompare(b.month));
+  const currentYearTotal = currentMonths.reduce((s, m) => s + m.downloads, 0);
+  const previousYearTotal = prevMonths.length > 0 ? prevMonths.reduce((s, m) => s + m.downloads, 0) : null;
+  const yoyGrowthPct = previousYearTotal !== null && previousYearTotal > 0 ? (currentYearTotal - previousYearTotal) / previousYearTotal * 100 : null;
+  const monthsElapsed = currentMonth + 1;
+  const monthlyRate = monthsElapsed > 0 ? currentYearTotal / monthsElapsed : 0;
+  const projectedYearEnd = Math.round(monthlyRate * 12);
+  const bestMonth = currentMonths.length > 0 ? currentMonths.reduce((best, m) => m.downloads > best.downloads ? m : best) : null;
+  const milestones = MILESTONE_THRESHOLDS.filter((t) => t <= projectedYearEnd * 2).map((threshold) => {
+    const crossed = currentYearTotal >= threshold;
+    const crossedAt = crossed ? currentMonths.find((_, idx) => {
+      const running = currentMonths.slice(0, idx + 1).reduce((s, m) => s + m.downloads, 0);
+      return running >= threshold;
+    })?.month : void 0;
+    return { threshold, crossed, ...crossedAt ? { crossedAt } : {} };
+  });
+  return {
+    name,
+    registry,
+    currentYearTotal,
+    previousYearTotal,
+    yoyGrowthPct: yoyGrowthPct !== null ? Math.round(yoyGrowthPct * 10) / 10 : null,
+    projectedYearEnd,
+    monthlyTotals: currentMonths,
+    bestMonth,
+    milestones
+  };
+}
+function computeHealthScore(name, registry, series, momentum) {
+  const empty = {
+    name,
+    registry,
+    score: 0,
+    grade: "F",
+    components: { activity: 0, consistency: 0, growth: 0, stability: 0 }
+  };
+  if (!series || series.length < 7) return empty;
+  const last7Sum = series.slice(-7).reduce((a, b) => a + b, 0);
+  const activity = Math.min(25, Math.round(Math.log10(last7Sum + 1) * 7));
+  const last14 = series.slice(-14);
+  const m = mean(last14);
+  const cv = m > 0 ? stddev(last14) / m : 1;
+  const consistency = Math.min(25, Math.round(Math.max(0, 25 - cv * 25)));
+  const growth = Math.round(Math.max(0, Math.min(25, (momentum + 100) / 8)));
+  const anomalies = detectAnomalies(series, 2.5);
+  const anomalyPenalty = Math.min(25, anomalies.length * 8);
+  const stability = Math.max(0, 25 - anomalyPenalty);
+  const score = activity + consistency + growth + stability;
+  const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+  return {
+    name,
+    registry,
+    score,
+    grade,
+    components: { activity, consistency, growth, stability }
+  };
+}
+function generateActionableAdvice(packages, healthScores, opts = {}) {
+  const advice = [];
+  const failing = healthScores.filter((h) => h.grade === "F");
+  if (failing.length > 0) {
+    advice.push({
+      type: "attention",
+      severity: "critical",
+      urgency: "immediate",
+      title: `${failing.length} package${failing.length > 1 ? "s" : ""} in critical health`,
+      detail: `${failing.map((h) => h.name).slice(0, 5).join(", ")} scored below 20/100.`,
+      action: "Review these packages for broken installs, outdated dependencies, or missing documentation. Consider archiving if no longer maintained.",
+      packages: failing.map((h) => h.name)
+    });
+  }
+  const steepDecline = packages.filter((p) => p.momentum < -50);
+  if (steepDecline.length > 0) {
+    advice.push({
+      type: "attention",
+      severity: "warning",
+      urgency: "this-week",
+      title: `${steepDecline.length} package${steepDecline.length > 1 ? "s" : ""} in rapid decline`,
+      detail: `${steepDecline.map((p) => p.name).slice(0, 3).join(", ")} lost significant download momentum.`,
+      action: "Check for competing packages, broken releases, or ecosystem changes. Push a patch release or announcement.",
+      packages: steepDecline.map((p) => p.name)
+    });
+  }
+  if (opts.gini !== void 0 && opts.gini > 0.7) {
+    advice.push({
+      type: "risk",
+      severity: opts.gini > 0.85 ? "warning" : "info",
+      urgency: "this-month",
+      title: "Portfolio concentration risk",
+      detail: `Gini coefficient ${opts.gini.toFixed(2)} \u2014 downloads are concentrated in a few packages.`,
+      action: "Promote underperforming packages in README badges, blog posts, and release notes of popular packages.",
+      metric: `Gini: ${opts.gini.toFixed(2)}`
+    });
+  }
+  if (opts.npmPct !== void 0 && opts.npmPct > 75) {
+    advice.push({
+      type: "risk",
+      severity: "info",
+      urgency: "this-month",
+      title: `${opts.npmPct}% of traffic from npm`,
+      detail: "Single-registry dependency increases blast radius if npm has outages or policy changes.",
+      action: "Cross-publish key packages to PyPI (via wrapper) or NuGet. Add install instructions for all registries in READMEs.",
+      metric: `npm share: ${opts.npmPct}%`
+    });
+  }
+  const surging = packages.filter((p) => p.momentum > 50);
+  if (surging.length > 0) {
+    advice.push({
+      type: "opportunity",
+      severity: "success",
+      urgency: "this-week",
+      title: `${surging.length} package${surging.length > 1 ? "s" : ""} surging`,
+      detail: `${surging.map((p) => p.name).slice(0, 3).join(", ")} have strong positive momentum.`,
+      action: 'Capitalize now: write a blog post, tweet, or submit to newsletters. Post a "Thank you" issue or discussion.',
+      packages: surging.map((p) => p.name)
+    });
+  }
+  const highVolume = packages.filter((p) => {
+    const pkg = packages.find((pp) => pp.name === p.name);
+    return pkg && pkg.forecast7.length > 0 && pkg.forecast7[6]?.predicted > 100;
+  });
+  for (const pkg of highVolume.slice(0, 3)) {
+    const weekSum = pkg.forecast7.reduce((s, f) => s + f.predicted, 0);
+    for (const threshold of [1e3, 5e3, 1e4]) {
+      if (weekSum >= threshold * 0.9 && weekSum <= threshold * 1.1) {
+        advice.push({
+          type: "milestone",
+          severity: "success",
+          urgency: "informational",
+          title: `${pkg.name} approaching ${threshold.toLocaleString()} weekly downloads`,
+          detail: `Forecasted at ~${weekSum.toLocaleString()} downloads next week.`,
+          action: "Prepare a milestone announcement and update the README with a downloads badge.",
+          packages: [pkg.name]
+        });
+      }
+    }
+  }
+  const dGrade = healthScores.filter((h) => h.grade === "D");
+  const easyWins = dGrade.filter((h) => {
+    return h.components.activity >= 10 && h.components.growth < 10;
+  });
+  if (easyWins.length > 0) {
+    advice.push({
+      type: "opportunity",
+      severity: "info",
+      urgency: "this-month",
+      title: `${easyWins.length} package${easyWins.length > 1 ? "s" : ""} with untapped potential`,
+      detail: `${easyWins.map((h) => h.name).slice(0, 3).join(", ")} have active users but stalled growth.`,
+      action: "Add new features, improve docs, or create tutorials. Small efforts can shift these from D to C+ quickly.",
+      packages: easyWins.map((h) => h.name)
+    });
+  }
+  const severityOrder = { critical: 0, warning: 1, success: 2, info: 3 };
+  advice.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  return advice;
+}
 function generateRecommendations(packages, opts = {}) {
   const recs = [];
   const declining = packages.filter((p) => p.momentum < -30);
@@ -849,13 +1024,20 @@ function inferPortfolio(leaderboard, opts = {}) {
   const riskScore = Math.round(Math.max(0, Math.min(100, giniRisk + declineRisk + anomalyRisk)));
   const diversityTrend = "stable";
   const recommendations = generateRecommendations(packages, opts);
+  const healthScores = leaderboard.map((row) => {
+    const pkg = packages.find((p) => p.name === row.name);
+    return computeHealthScore(row.name, row.registry, row.range30 ?? null, pkg?.momentum ?? 0);
+  });
+  const actionableAdvice = generateActionableAdvice(packages, healthScores, opts);
   return {
     packages,
     recommendations,
     forecastTotal7,
     riskScore,
     diversityTrend,
-    portfolioMomentum: Math.round(weightedMomentum)
+    portfolioMomentum: Math.round(weightedMomentum),
+    healthScores,
+    actionableAdvice
   };
 }
 
@@ -1055,13 +1237,16 @@ stats.mine = async function mine(maintainer, options) {
 export {
   RegistryError,
   calc,
+  computeHealthScore,
   computeMomentum,
+  computeYearlyProgress,
   createCache,
   createHandler,
   defaultConfig,
   detectAnomalies,
   detectSeasonality,
   forecast,
+  generateActionableAdvice,
   generateRecommendations,
   inferPortfolio,
   loadConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/registry-stats",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Multi-registry download stats — engine, AI-powered dashboard, and desktop app for npm, PyPI, NuGet, VS Code Marketplace, and Docker Hub",
   "type": "module",
   "main": "./dist/index.cjs",