@mcptoolshop/registry-stats 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -116,6 +116,183 @@ declare function createHandler(opts?: StatsOptions): Handler;
 /** Starts an HTTP server. Returns the server instance. */
 declare function serve(opts?: ServerOptions): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
 
+/**
+ * AI Inference Module — statistical forecasting, anomaly detection, and recommendations.
+ *
+ * Zero dependencies. Pure math on time-series data arrays.
+ * Designed to run at build-time in the fetch-stats pipeline.
+ */
+interface ForecastPoint {
+    day: number;
+    predicted: number;
+    lower: number;
+    upper: number;
+}
+interface Anomaly {
+    day: number;
+    value: number;
+    expected: number;
+    zscore: number;
+    type: 'spike' | 'drop';
+}
+interface TrendSegment {
+    start: number;
+    end: number;
+    direction: 'up' | 'down' | 'flat';
+    slope: number;
+    magnitude: number;
+}
+interface Recommendation {
+    type: 'growth' | 'risk' | 'opportunity' | 'attention';
+    priority: 'high' | 'medium' | 'low';
+    title: string;
+    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;
+    forecast7: ForecastPoint[];
+    anomalies: Anomaly[];
+    trendSegments: TrendSegment[];
+    seasonality: {
+        dayOfWeek: number[];
+        peakDay: string;
+    } | null;
+    momentum: number;
+}
+interface PortfolioInference {
+    packages: PackageInference[];
+    recommendations: Recommendation[];
+    forecastTotal7: number[];
+    riskScore: number;
+    diversityTrend: 'improving' | 'stable' | 'declining';
+    portfolioMomentum: number;
+    healthScores: PackageHealthScore[];
+    actionableAdvice: ActionableAdvice[];
+}
+/**
+ * Forecast next N days using weighted linear regression on recent data.
+ * Uses the last 14 days with exponential weighting (recent days matter more).
+ * Returns predictions with 80% confidence intervals.
+ */
+declare function forecast(series: number[], days?: number): ForecastPoint[];
+/**
+ * Detect anomalies using adaptive z-score with rolling baseline.
+ * More sophisticated than simple global z-score — uses a 14-day rolling
+ * window so seasonal patterns don't trigger false positives.
+ */
+declare function detectAnomalies(series: number[], threshold?: number): Anomaly[];
+/**
+ * Segment a time series into directional trend segments.
+ * Uses a simple piecewise linear approach with minimum segment length.
+ */
+declare function segmentTrends(series: number[], minSegmentLength?: number): TrendSegment[];
+/**
+ * Detect day-of-week seasonality patterns.
+ * Requires at least 14 days of data to identify weekly cycles.
+ */
+declare function detectSeasonality(series: number[], startDaysAgo: number): {
+    dayOfWeek: number[];
+    peakDay: string;
+} | null;
+/**
+ * Compute a composite momentum score (-100 to +100).
+ * 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.
+ */
+declare function generateRecommendations(packages: PackageInference[], opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): Recommendation[];
+/**
+ * Run full inference pipeline on a leaderboard dataset.
+ * This is the main entry point called from fetch-stats.mjs.
+ */
+declare function inferPortfolio(leaderboard: Array<{
+    name: string;
+    registry: string;
+    week: number;
+    range30?: number[] | null;
+    trendPct?: number | null;
+}>, opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): PortfolioInference;
+
 declare function createCache(): StatsCache;
 
 declare function registerProvider(provider: RegistryProvider): void;
@@ -130,4 +307,4 @@ declare namespace stats {
     }) => Promise<PackageStats[]>;
 }
 
-export { type ChartData, type ComparisonResult, type Config, type DailyDownloads, type PackageConfig, type PackageStats, type RateLimitConfig, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, calc, createCache, createHandler, defaultConfig, loadConfig, registerProvider, 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

@@ -116,6 +116,183 @@ declare function createHandler(opts?: StatsOptions): Handler;
 /** Starts an HTTP server. Returns the server instance. */
 declare function serve(opts?: ServerOptions): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
 
+/**
+ * AI Inference Module — statistical forecasting, anomaly detection, and recommendations.
+ *
+ * Zero dependencies. Pure math on time-series data arrays.
+ * Designed to run at build-time in the fetch-stats pipeline.
+ */
+interface ForecastPoint {
+    day: number;
+    predicted: number;
+    lower: number;
+    upper: number;
+}
+interface Anomaly {
+    day: number;
+    value: number;
+    expected: number;
+    zscore: number;
+    type: 'spike' | 'drop';
+}
+interface TrendSegment {
+    start: number;
+    end: number;
+    direction: 'up' | 'down' | 'flat';
+    slope: number;
+    magnitude: number;
+}
+interface Recommendation {
+    type: 'growth' | 'risk' | 'opportunity' | 'attention';
+    priority: 'high' | 'medium' | 'low';
+    title: string;
+    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;
+    forecast7: ForecastPoint[];
+    anomalies: Anomaly[];
+    trendSegments: TrendSegment[];
+    seasonality: {
+        dayOfWeek: number[];
+        peakDay: string;
+    } | null;
+    momentum: number;
+}
+interface PortfolioInference {
+    packages: PackageInference[];
+    recommendations: Recommendation[];
+    forecastTotal7: number[];
+    riskScore: number;
+    diversityTrend: 'improving' | 'stable' | 'declining';
+    portfolioMomentum: number;
+    healthScores: PackageHealthScore[];
+    actionableAdvice: ActionableAdvice[];
+}
+/**
+ * Forecast next N days using weighted linear regression on recent data.
+ * Uses the last 14 days with exponential weighting (recent days matter more).
+ * Returns predictions with 80% confidence intervals.
+ */
+declare function forecast(series: number[], days?: number): ForecastPoint[];
+/**
+ * Detect anomalies using adaptive z-score with rolling baseline.
+ * More sophisticated than simple global z-score — uses a 14-day rolling
+ * window so seasonal patterns don't trigger false positives.
+ */
+declare function detectAnomalies(series: number[], threshold?: number): Anomaly[];
+/**
+ * Segment a time series into directional trend segments.
+ * Uses a simple piecewise linear approach with minimum segment length.
+ */
+declare function segmentTrends(series: number[], minSegmentLength?: number): TrendSegment[];
+/**
+ * Detect day-of-week seasonality patterns.
+ * Requires at least 14 days of data to identify weekly cycles.
+ */
+declare function detectSeasonality(series: number[], startDaysAgo: number): {
+    dayOfWeek: number[];
+    peakDay: string;
+} | null;
+/**
+ * Compute a composite momentum score (-100 to +100).
+ * 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.
+ */
+declare function generateRecommendations(packages: PackageInference[], opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): Recommendation[];
+/**
+ * Run full inference pipeline on a leaderboard dataset.
+ * This is the main entry point called from fetch-stats.mjs.
+ */
+declare function inferPortfolio(leaderboard: Array<{
+    name: string;
+    registry: string;
+    week: number;
+    range30?: number[] | null;
+    trendPct?: number | null;
+}>, opts?: {
+    gini?: number;
+    npmPct?: number;
+    totalWeekly?: number;
+}): PortfolioInference;
+
 declare function createCache(): StatsCache;
 
 declare function registerProvider(provider: RegistryProvider): void;
@@ -130,4 +307,4 @@ declare namespace stats {
     }) => Promise<PackageStats[]>;
 }
 
-export { type ChartData, type ComparisonResult, type Config, type DailyDownloads, type PackageConfig, type PackageStats, type RateLimitConfig, RegistryError, type RegistryName, type RegistryProvider, type ServerOptions, type StatsCache, type StatsOptions, calc, createCache, createHandler, defaultConfig, loadConfig, registerProvider, 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 };