Add function and task for computing and uploading package trends

app/lib/service/download_counts/computations.dart

@@ -6,15 +6,45 @@ import 'dart:math';
 
 import 'package:_pub_shared/data/download_counts_data.dart';
 import 'package:gcloud/storage.dart';
+import 'package:pub_dev/package/backend.dart';
 import 'package:pub_dev/service/download_counts/backend.dart';
 import 'package:pub_dev/service/download_counts/download_counts.dart';
 import 'package:pub_dev/service/download_counts/models.dart';
+import 'package:pub_dev/service/download_counts/package_trends.dart';
 import 'package:pub_dev/shared/configuration.dart';
 import 'package:pub_dev/shared/storage.dart';
 import 'package:pub_dev/shared/utils.dart';
 
 import '../../shared/redis_cache.dart' show cache;
 
+Future<void> computeTrendScoreTask() async {
+  final trendScores = await computeTrend();
+  await uploadTrendScores(trendScores);
+}
+
+Future<Map<String, double>> computeTrend() async {
+  final res = <String, double>{};
+
+  await for (final pkg in packageBackend.allPackages()) {
+    final name = pkg.name!;
+    final downloads =
+        (await downloadCountsBackend.lookupDownloadCountData(name))
+                ?.totalCounts ??
+            [0];
+    res[name] = computeTrendScore(downloads);
+  }
+  return res;
+}
+
+final trendScoreFileName = 'trend-scores.json';
+
+Future<void> uploadTrendScores(Map<String, double> trends) async {
+  final reportsBucket =
+      storageService.bucket(activeConfiguration.reportsBucketName!);
+  await uploadBytesWithRetry(
+      reportsBucket, trendScoreFileName, jsonUtf8Encoder.convert(trends));
+}
+
 Future<void> compute30DaysTotalTask() async {
   final allDownloadCounts = await downloadCountsBackend.listAllDownloadCounts();
   final totals = await compute30DayTotals(allDownloadCounts);

app/lib/service/download_counts/package_trends.dart

@@ -2,7 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'dart:math';
+
 const analysisWindowDays = 30;
+const minThirtyDaysDownloadThreshold = 30000;
 
 /// Calculates the relative daily growth rate of a package's downloads.
 ///
@@ -89,3 +92,21 @@ double calculateLinearRegressionSlope(List<num> yValues) {
   }
   return (n * sumXY - sumX * sumY) / denominator;
 }
+
+/// Computes a trend score for a package, factoring in both its recent
+/// relative growth rate and its overall download volume.
+///
+/// This score is designed to balance how quickly a package is growing
+/// ([computeRelativeGrowthRate]) against its existing popularity. Popularity is
+/// assessed by comparing the sum of its downloads over the available history
+/// (up to [analysisWindowDays]) against a [minThirtyDaysDownloadThreshold].
+double computeTrendScore(List<int> totalDownloads) {
+  final n = min(analysisWindowDays, totalDownloads.length);
+  final thirtydaySum = totalDownloads.isEmpty
+      ? 0
+      : totalDownloads.sublist(0, n).reduce((prev, element) => prev + element);
+  final dampening = min(thirtydaySum / minThirtyDaysDownloadThreshold, 1.0);
+  final relativGrowth = computeRelativeGrowthRate(totalDownloads);
+
+  return relativGrowth * dampening * dampening;
+}

app/lib/tool/neat_task/pub_dev_tasks.dart

@@ -211,6 +211,12 @@ List<NeatPeriodicTaskScheduler> createPeriodicTaskSchedulers({
       task: compute30DaysTotalTask,
     ),
 
+    _daily(
+      name: 'compute-trend-scores',
+      isRuntimeVersioned: false,
+      task: computeTrendScoreTask,
+    ),
+
     _daily(
       name: 'count-topics',
       isRuntimeVersioned: false,

app/test/service/download_counts/computations_test.dart

@@ -2,19 +2,23 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 import 'dart:convert';
+import 'dart:io';
 
 import 'package:basics/basics.dart';
 import 'package:gcloud/storage.dart';
+import 'package:path/path.dart' as path;
 import 'package:pub_dev/fake/backend/fake_download_counts.dart';
 import 'package:pub_dev/service/download_counts/backend.dart';
 import 'package:pub_dev/service/download_counts/computations.dart';
+import 'package:pub_dev/service/download_counts/package_trends.dart';
+import 'package:pub_dev/service/download_counts/sync_download_counts.dart';
 import 'package:pub_dev/shared/configuration.dart';
 import 'package:test/test.dart';
 
 import '../../shared/test_services.dart';
 
 void main() {
-  group('', () {
+  group('30 days download counts', () {
     testWithProfile('compute download counts 30-days totals', fn: () async {
       final pkg = 'foo';
       final versionsCounts = {
@@ -119,7 +123,9 @@ void main() {
       expect(downloadCountsBackend.lookup30DaysTotalCounts('baz'), 150);
       expect(downloadCountsBackend.lookup30DaysTotalCounts('bax'), isNull);
     });
+  });
 
+  group('weekly download counts', () {
     testWithProfile('compute weekly', fn: () async {
       final pkg = 'foo';
       final date = DateTime.parse('1986-02-16');
@@ -276,4 +282,59 @@ void main() {
       }
     });
   });
+  group('trends', () {
+    testWithProfile('compute trend', fn: () async {
+      String date(int i) => i < 10 ? '2024-01-0$i' : '2024-01-$i';
+
+      for (int i = 1; i < 16; i++) {
+        final d = DateTime.parse(date(i));
+        final downloadCountsJsonFileName =
+            'daily_download_counts/${date(i)}T00:00:00Z/data-000000000000.jsonl';
+        await uploadFakeDownloadCountsToBucket(
+            downloadCountsJsonFileName,
+            path.join(
+                Directory.current.path,
+                'test',
+                'service',
+                'download_counts',
+                'fake_download_counts_data_for_trend1.jsonl'));
+        await processDownloadCounts(d);
+      }
+      for (int i = 16; i < 31; i++) {
+        final d = DateTime.parse(date(i));
+        final downloadCountsJsonFileName =
+            'daily_download_counts/${date(i)}T00:00:00Z/data-000000000000.jsonl';
+        await uploadFakeDownloadCountsToBucket(
+            downloadCountsJsonFileName,
+            path.join(
+                Directory.current.path,
+                'test',
+                'service',
+                'download_counts',
+                'fake_download_counts_data_for_trend2.jsonl'));
+        await processDownloadCounts(d);
+      }
+      final neonTrend = computeTrendScore(
+          [...List.filled(15, 2000), ...List.filled(15, 1000)]);
+      final oxygenTrend = computeTrendScore(
+          [...List.filled(15, 5000), ...List.filled(15, 3000)]);
+
+      expect(await computeTrend(),
+          {'flutter_titanium': 0.0, 'neon': neonTrend, 'oxygen': oxygenTrend});
+    });
+
+    testWithProfile('succesful trends upload', fn: () async {
+      final trends = {'foo': 1.0, 'bar': 3.0, 'baz': 2.0};
+      await uploadTrendScores(trends);
+
+      final data = await storageService
+          .bucket(activeConfiguration.reportsBucketName!)
+          .read(trendScoreFileName)
+          .transform(utf8.decoder)
+          .transform(json.decoder)
+          .single;
+
+      expect(data, trends);
+    });
+  });
 }

app/test/service/download_counts/fake_download_counts_data_for_trend1.jsonl

@@ -0,0 +1,2 @@
+{"package":"oxygen","total":"3000","per_version":[{"version":"1.0.0","count":"1000"},{"version":"1.2.0","count":"1000"},{"version":"2.0.0-dev","count":"1000"}]}
+{"package":"neon","total":"1000","per_version":[{"version":"1.0.0","count":"1000"}]}

app/test/service/download_counts/fake_download_counts_data_for_trend2.jsonl

@@ -0,0 +1,2 @@
+{"package":"oxygen","total":"5000","per_version":[{"version":"1.0.0","count":"3000"},{"version":"1.2.0","count":"1000"},{"version":"2.0.0-dev","count":"1000"}]}
+{"package":"neon","total":"2000","per_version":[{"version":"1.0.0","count":"2000"}]}

app/test/service/download_counts/package_trends_test.dart

@@ -2,6 +2,8 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'dart:math';
+
 import 'package:pub_dev/service/download_counts/package_trends.dart';
 import 'package:test/test.dart';
 
@@ -99,4 +101,87 @@ void main() {
       expect(computeRelativeGrowthRate(downloads), expectedRate);
     });
   });
+  group('computeTrendScore', () {
+    test('Short history, very low sum, positive growth -> heavily dampened',
+        () {
+      final downloads = [100, 50];
+      // For relativeGrowth:
+      //   Padded data: [100, 50, 0...0] (28 zeros)
+      //   avg = 150/30 = 5
+      //   growthRate = 63750 / 67425
+      final expectedDampening = min(1.0, 150 / 30000);
+      final expectedRelativeGrowth = 63750 / 67425 / 5;
+      final expectedScore =
+          expectedRelativeGrowth * expectedDampening * expectedDampening;
+      expect(computeTrendScore(downloads), expectedScore);
+    });
+  });
+
+  test('Full history, sum meets threshold, positive growth -> no dampening',
+      () {
+    final downloads =
+        List<int>.generate(analysisWindowDays, (i) => 1645 - (i * 10));
+    // For relativeGrowth:
+    //   data: [1645, 1635, ..., 1355]
+    //   avg = 1500,
+    //   growthrate = 10
+    final expectedDampening = min(1.0, 45000 / 30000);
+    final expectedRelativeGrowth = 10 / 1500;
+    final expectedScore =
+        expectedRelativeGrowth * expectedDampening * expectedDampening;
+    expect(computeTrendScore(downloads), expectedScore);
+  });
+
+  test('Negative growth, sum meets threshold -> no dampening', () {
+    final downloads =
+        List<int>.generate(analysisWindowDays, (i) => 1355 + (i * 10));
+    // For relativeGrowth:
+    //   data: [1645, 1635, ..., 1355]
+    //   avg = 1500,
+    //   growthrate = -10
+    final expectedDampening = min(1.0, 45000 / 30000);
+    final expectedRelativeGrowth = -10.0 / 1500;
+    final expectedScore =
+        expectedRelativeGrowth * expectedDampening * expectedDampening;
+    expect(computeTrendScore(downloads), expectedScore);
+  });
+  test('Full history, sum below threshold, positive growth -> dampened', () {
+    final downloads =
+        List<int>.generate(analysisWindowDays, (i) => 645 - (i * 10));
+    // For relativeGrowth:
+    //   data: [645,..., 345, 355]
+    //   avg = 500
+    //   growthrate = 10
+    final expectedDampening = min(1.0, 15000 / 30000);
+    final expectedRelativeGrowth = 10.0 / 500.0;
+    final expectedScore =
+        expectedRelativeGrowth * expectedDampening * expectedDampening;
+
+    expect(computeTrendScore(downloads), expectedScore);
+  });
+
+  test('Empty totalDownloads list -> score 0', () {
+    final downloads = <int>[];
+    expect(computeTrendScore(downloads), 0);
+  });
+
+  test('Full history, all zero downloads -> score 0', () {
+    final downloads = List<int>.filled(analysisWindowDays, 0);
+    expect(computeTrendScore(downloads), 0);
+  });
+
+  test('ThirtyDaySum just below threshold correctly, flat growth', () {
+    final downloads = List<int>.filled(analysisWindowDays, 999);
+    expect(computeTrendScore(downloads), 0);
+  });
+
+  test('Short history, high sum meets threshold -> no dampening', () {
+    final downloads = List<int>.filled(15, 2000);
+    final expectedDampening = min(1.0, 30000 / 30000);
+    final expectedRelativeGrowth = 6750000 / 67425 / 1000;
+    final expectedScore =
+        expectedRelativeGrowth * expectedDampening * expectedDampening;
+
+    expect(computeTrendScore(downloads), expectedScore);
+  });
 }