@mcptoolshop/registry-stats 2.3.0 → 3.1.0

package/dist/index.js

@@ -34,7 +34,7 @@ async function fetchWithRetry(url, registry, init) {
   let lastError;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     await acquireSlot(registry);
-    const res = await fetch(url, init);
+    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
     if (res.status === 404) return null;
     if (res.ok) return res.json();
     const retryAfter = res.headers.get("retry-after");
@@ -56,7 +56,7 @@ async function fetchWithRetry(url, registry, init) {
 async function fetchDirect(url, registry, init) {
   let lastError;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    const res = await fetch(url, init);
+    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
     if (res.status === 404) return null;
     if (res.ok) return res.json();
     const retryAfter = res.headers.get("retry-after");
@@ -278,7 +278,8 @@ var docker = {
     if (options?.dockerToken) {
       headers["Authorization"] = `Bearer ${options.dockerToken}`;
     }
-    const json2 = await fetchWithRetry(`${API4}/${pkg}`, "docker", { headers });
+    const safePkg = pkg.split("/").map((s) => encodeURIComponent(s)).join("/");
+    const json2 = await fetchWithRetry(`${API4}/${safePkg}`, "docker", { headers });
     if (!json2 || !json2.name || !json2.namespace) return null;
     return {
       registry: "docker",
@@ -565,6 +566,299 @@ Endpoints:`);
   return server;
 }
 
+// src/inference.ts
+function mean(arr) {
+  if (arr.length === 0) return 0;
+  return arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+function stddev(arr) {
+  if (arr.length < 2) return 0;
+  const m = mean(arr);
+  const variance = arr.reduce((s, v) => s + (v - m) ** 2, 0) / arr.length;
+  return Math.sqrt(variance);
+}
+function linearRegression(ys) {
+  const n = ys.length;
+  if (n < 2) return { slope: 0, intercept: ys[0] ?? 0, r2: 0 };
+  let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0;
+  for (let i = 0; i < n; i++) {
+    sumX += i;
+    sumY += ys[i];
+    sumXY += i * ys[i];
+    sumX2 += i * i;
+  }
+  const denom = n * sumX2 - sumX * sumX;
+  if (denom === 0) return { slope: 0, intercept: sumY / n, r2: 0 };
+  const slope = (n * sumXY - sumX * sumY) / denom;
+  const intercept = (sumY - slope * sumX) / n;
+  const meanY = sumY / n;
+  let ssTot = 0, ssRes = 0;
+  for (let i = 0; i < n; i++) {
+    ssTot += (ys[i] - meanY) ** 2;
+    ssRes += (ys[i] - (intercept + slope * i)) ** 2;
+  }
+  const r2 = ssTot > 0 ? 1 - ssRes / ssTot : 0;
+  return { slope, intercept, r2 };
+}
+var DAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function forecast(series, days = 7) {
+  if (series.length < 7) return [];
+  const window = series.slice(-Math.min(14, series.length));
+  const n = window.length;
+  const weights = window.map((_, i) => Math.exp(0.1 * (i - n + 1)));
+  const totalW = weights.reduce((a, b) => a + b, 0);
+  let wSumX = 0, wSumY = 0, wSumXY = 0, wSumX2 = 0;
+  for (let i = 0; i < n; i++) {
+    const w = weights[i];
+    wSumX += w * i;
+    wSumY += w * window[i];
+    wSumXY += w * i * window[i];
+    wSumX2 += w * i * i;
+  }
+  const denom = totalW * wSumX2 - wSumX * wSumX;
+  let slope, intercept;
+  if (Math.abs(denom) < 1e-10) {
+    slope = 0;
+    intercept = wSumY / totalW;
+  } else {
+    slope = (totalW * wSumXY - wSumX * wSumY) / denom;
+    intercept = (wSumY - slope * wSumX) / totalW;
+  }
+  let ssRes = 0;
+  for (let i = 0; i < n; i++) {
+    ssRes += weights[i] * (window[i] - (intercept + slope * i)) ** 2;
+  }
+  const rse = Math.sqrt(ssRes / Math.max(1, totalW - 2));
+  const z80 = 1.28;
+  const results = [];
+  for (let d = 1; d <= days; d++) {
+    const x = n - 1 + d;
+    const predicted = Math.max(0, Math.round(intercept + slope * x));
+    const margin = Math.round(z80 * rse * Math.sqrt(1 + 1 / n + (x - n / 2) ** 2 / (n * n / 12)));
+    results.push({
+      day: d,
+      predicted,
+      lower: Math.max(0, predicted - margin),
+      upper: predicted + margin
+    });
+  }
+  return results;
+}
+function detectAnomalies(series, threshold = 2) {
+  if (series.length < 7) return [];
+  const anomalies = [];
+  const windowSize = Math.min(14, Math.floor(series.length * 0.7));
+  for (let i = windowSize; i < series.length; i++) {
+    const window = series.slice(i - windowSize, i);
+    const m = mean(window);
+    const s = stddev(window);
+    if (s < 1) continue;
+    const zscore = (series[i] - m) / s;
+    if (Math.abs(zscore) >= threshold) {
+      anomalies.push({
+        day: i,
+        value: series[i],
+        expected: Math.round(m),
+        zscore: Math.round(zscore * 10) / 10,
+        type: zscore > 0 ? "spike" : "drop"
+      });
+    }
+  }
+  return anomalies;
+}
+function segmentTrends(series, minSegmentLength = 5) {
+  if (series.length < minSegmentLength) return [];
+  const segments = [];
+  let segStart = 0;
+  while (segStart < series.length - minSegmentLength + 1) {
+    let bestEnd = segStart + minSegmentLength - 1;
+    const initialSlope = linearRegression(series.slice(segStart, segStart + minSegmentLength)).slope;
+    const initialDir = initialSlope > 0.5 ? "up" : initialSlope < -0.5 ? "down" : "flat";
+    for (let end = segStart + minSegmentLength; end < series.length; end++) {
+      const seg2 = series.slice(segStart, end + 1);
+      const { slope: slope2 } = linearRegression(seg2);
+      const dir = slope2 > 0.5 ? "up" : slope2 < -0.5 ? "down" : "flat";
+      if (dir !== initialDir) break;
+      bestEnd = end;
+    }
+    const seg = series.slice(segStart, bestEnd + 1);
+    const { slope } = linearRegression(seg);
+    const direction = slope > 0.5 ? "up" : slope < -0.5 ? "down" : "flat";
+    segments.push({
+      start: segStart,
+      end: bestEnd,
+      direction,
+      slope: Math.round(slope * 10) / 10,
+      magnitude: Math.round(seg[seg.length - 1] - seg[0])
+    });
+    segStart = bestEnd + 1;
+  }
+  return segments;
+}
+function detectSeasonality(series, startDaysAgo) {
+  if (series.length < 14) return null;
+  const buckets = [[], [], [], [], [], [], []];
+  const today = /* @__PURE__ */ new Date();
+  for (let i = 0; i < series.length; i++) {
+    const date = new Date(today);
+    date.setDate(date.getDate() - (startDaysAgo - i));
+    const dow = date.getDay();
+    buckets[dow].push(series[i]);
+  }
+  const dayAvgs = buckets.map((b) => Math.round(mean(b)));
+  const overallMean = mean(dayAvgs);
+  const maxAvg = Math.max(...dayAvgs);
+  const minAvg = Math.min(...dayAvgs);
+  if (overallMean < 1 || (maxAvg - minAvg) / overallMean < 0.15) return null;
+  const peakIdx = dayAvgs.indexOf(maxAvg);
+  return {
+    dayOfWeek: dayAvgs,
+    peakDay: DAY_NAMES[peakIdx]
+  };
+}
+function computeMomentum(series) {
+  if (series.length < 14) return 0;
+  const last7 = series.slice(-7);
+  const prev7 = series.slice(-14, -7);
+  const last7Sum = last7.reduce((a, b) => a + b, 0);
+  const prev7Sum = prev7.reduce((a, b) => a + b, 0);
+  const dampK = 10;
+  const dirScore = prev7Sum > dampK ? Math.max(-40, Math.min(40, (last7Sum - prev7Sum) / Math.sqrt(prev7Sum + dampK) * 4)) : last7Sum > 0 ? 20 : 0;
+  const { slope: recentSlope } = linearRegression(last7);
+  const { slope: prevSlope } = linearRegression(prev7);
+  const accelScore = Math.max(-20, Math.min(20, (recentSlope - prevSlope) * 2));
+  const cv = last7Sum > 0 ? stddev(last7) / mean(last7) : 1;
+  const consistencyScore = Math.max(0, 20 - cv * 20);
+  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)));
+}
+function generateRecommendations(packages, opts = {}) {
+  const recs = [];
+  const declining = packages.filter((p) => p.momentum < -30);
+  if (declining.length > 0) {
+    const names = declining.slice(0, 3).map((p) => p.name).join(", ");
+    recs.push({
+      type: "attention",
+      priority: declining.some((p) => p.momentum < -60) ? "high" : "medium",
+      title: `${declining.length} package${declining.length > 1 ? "s" : ""} losing momentum`,
+      detail: `${names}${declining.length > 3 ? ` and ${declining.length - 3} more` : ""} show sustained decline. Consider: release updates, fix open issues, or update documentation.`,
+      metric: `Worst momentum: ${Math.min(...declining.map((p) => p.momentum))}`
+    });
+  }
+  if (opts.gini !== void 0 && opts.gini > 0.7) {
+    recs.push({
+      type: "risk",
+      priority: opts.gini > 0.85 ? "high" : "medium",
+      title: "High portfolio concentration",
+      detail: `Gini coefficient ${opts.gini.toFixed(2)} indicates downloads are heavily concentrated in a few packages. Diversify promotion efforts across the portfolio.`,
+      metric: `Gini: ${opts.gini.toFixed(2)}`
+    });
+  }
+  if (opts.npmPct !== void 0 && opts.npmPct > 75) {
+    recs.push({
+      type: "risk",
+      priority: "medium",
+      title: "Heavy npm dependency",
+      detail: `${opts.npmPct}% of downloads come from npm. Consider cross-publishing to PyPI and NuGet to reduce single-registry risk.`,
+      metric: `npm share: ${opts.npmPct}%`
+    });
+  }
+  const growing = packages.filter((p) => p.momentum > 40 && p.anomalies.some((a) => a.type === "spike"));
+  if (growing.length > 0) {
+    const names = growing.slice(0, 3).map((p) => p.name).join(", ");
+    recs.push({
+      type: "opportunity",
+      priority: "medium",
+      title: `${growing.length} package${growing.length > 1 ? "s" : ""} gaining traction`,
+      detail: `${names} show organic growth with download spikes. Capitalize with blog posts, social media, or conference talks.`,
+      metric: `Best momentum: ${Math.max(...growing.map((p) => p.momentum))}`
+    });
+  }
+  const forecastGrowing = packages.filter((p) => {
+    if (p.forecast7.length < 7) return false;
+    const lastActual = p.forecast7[0]?.predicted ?? 0;
+    const lastForecast = p.forecast7[6]?.predicted ?? 0;
+    return lastForecast > lastActual * 1.2;
+  });
+  if (forecastGrowing.length > 0) {
+    recs.push({
+      type: "growth",
+      priority: "low",
+      title: `${forecastGrowing.length} package${forecastGrowing.length > 1 ? "s" : ""} predicted to grow`,
+      detail: `Statistical models predict >20% growth in the next 7 days for ${forecastGrowing.slice(0, 3).map((p) => p.name).join(", ")}.`
+    });
+  }
+  const spiked = packages.filter((p) => p.anomalies.filter((a) => a.type === "spike").length >= 2);
+  if (spiked.length > 0) {
+    recs.push({
+      type: "attention",
+      priority: "low",
+      title: `${spiked.length} package${spiked.length > 1 ? "s" : ""} with repeated spikes`,
+      detail: `Multiple download spikes detected for ${spiked.slice(0, 3).map((p) => p.name).join(", ")}. Could indicate bot activity, viral posts, or dependency adoption.`
+    });
+  }
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  recs.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+  return recs;
+}
+function inferPortfolio(leaderboard, opts = {}) {
+  const packages = [];
+  for (const row of leaderboard) {
+    const series = row.range30;
+    if (!series || series.length < 7) {
+      packages.push({
+        name: row.name,
+        registry: row.registry,
+        forecast7: [],
+        anomalies: [],
+        trendSegments: [],
+        seasonality: null,
+        momentum: 0
+      });
+      continue;
+    }
+    packages.push({
+      name: row.name,
+      registry: row.registry,
+      forecast7: forecast(series, 7),
+      anomalies: detectAnomalies(series),
+      trendSegments: segmentTrends(series),
+      seasonality: detectSeasonality(series, 30),
+      momentum: computeMomentum(series)
+    });
+  }
+  const forecastTotal7 = new Array(7).fill(0);
+  for (const pkg of packages) {
+    for (const pt of pkg.forecast7) {
+      forecastTotal7[pt.day - 1] += pt.predicted;
+    }
+  }
+  const totalWeek = leaderboard.reduce((s, r) => s + (r.week ?? 0), 0);
+  let weightedMomentum = 0;
+  for (const pkg of packages) {
+    const row = leaderboard.find((r) => r.name === pkg.name);
+    const weight = totalWeek > 0 ? (row?.week ?? 0) / totalWeek : 1 / packages.length;
+    weightedMomentum += pkg.momentum * weight;
+  }
+  const decliningPct = packages.filter((p) => p.momentum < -20).length / Math.max(1, packages.length);
+  const totalAnomalies = packages.reduce((s, p) => s + p.anomalies.length, 0);
+  const anomalyDensity = totalAnomalies / Math.max(1, packages.length);
+  const giniRisk = (opts.gini ?? 0) * 30;
+  const declineRisk = decliningPct * 40;
+  const anomalyRisk = Math.min(30, anomalyDensity * 10);
+  const riskScore = Math.round(Math.max(0, Math.min(100, giniRisk + declineRisk + anomalyRisk)));
+  const diversityTrend = "stable";
+  const recommendations = generateRecommendations(packages, opts);
+  return {
+    packages,
+    recommendations,
+    forecastTotal7,
+    riskScore,
+    diversityTrend,
+    portfolioMomentum: Math.round(weightedMomentum)
+  };
+}
+
 // src/index.ts
 function createCache() {
   const store = /* @__PURE__ */ new Map();
@@ -761,11 +1055,18 @@ stats.mine = async function mine(maintainer, options) {
 export {
   RegistryError,
   calc,
+  computeMomentum,
   createCache,
   createHandler,
   defaultConfig,
+  detectAnomalies,
+  detectSeasonality,
+  forecast,
+  generateRecommendations,
+  inferPortfolio,
   loadConfig,
   registerProvider,
+  segmentTrends,
   serve,
   starterConfig,
   stats

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/registry-stats",
-  "version": "2.3.0",
+  "version": "3.1.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",