feat: add an admin statistics dashboard

[netomi]

Closes #351. Adds a statistics page to the admin dashboard at /admin-dashboard/statistics, with a CSV export.

Two of that issue's three asks had already been met since it was filed in 2021: /admin/report gained a JSON variant, and the webui now ships @mui/x-charts, so the d3js suggestion is moot. That left the auth change, the missing current month, and the page itself.

1. New session-authenticated endpoints, rather than changing /admin/report

The issue suggested switching /admin/report to Spring authentication. I added /admin/statistics and /admin/statistics/csv alongside it instead, because /admin/report takes its token as a request parameter and is consequently listed in SecurityConfig's permitAll block — which is exactly why a logged-in browser session can't use it, and why changing it would break anyone scripting the CSV export today.

The new endpoints authenticate with checkAdminUser(), the way every other endpoint under /admin/ does, and need no SecurityConfig change: /admin/** already requires ROLE_ADMIN, so leaving them out of the permitAll list is all it takes.

The CSV sits on its own path rather than behind content negotiation, because the download is a plain link and a browser navigation can't set an Accept header. It sets Content-Disposition, so the file saves as openvsx-statistics-2026-09.csv instead of being named after the route.

2. The month in progress is now computed on request

#235 specified "when current month data is requested, calculations are done on the fly", and that was never built. getAdminStatistics rejected the current month as lying in the future and 404'd anything unarchived, so a dashboard would have shown nothing until a month had elapsed — and nothing at all on a fresh deployment, since the archival job only runs on the first of the following month.

The computation moves out of AdminStatisticsJobRequestHandler into AdminStatisticsService, so the archival job and the on-the-fly path cannot compute the same month differently. The validation relaxes from month >= now to month > now.

The on-the-fly result is deliberately not saved: it is a partial month, and the job will archive the complete figure in its own time. A past month with no row stays a 404 — every figure except downloads is a snapshot of the registry as it was, so it cannot be reconstructed after the fact, and reporting today's numbers under a past month's heading would be worse than reporting nothing.

This does change /admin/report's behaviour for the current month, from 400 to 200. Permissive rather than breaking, but it is a public endpoint, so flagging it rather than burying it.

3. The page

Reads the endpoint a month at a time:

• headline figures — extensions, this month's downloads, all-time downloads, publishers, namespace owners, average reviews per extension;
• the two numeric breakdowns (extensions by rating, publishers by extensions published) as bar charts, following the existing usage-stats chart's @mui/x-charts usage rather than introducing anything new;
• the four "top ten" lists as ranked tables, linking to the extensions and namespaces they name.

Months step one at a time, forward navigation stops at the month in progress, and a month with nothing archived is explained rather than surfaced as a failure — for any registry that wasn't running yet, that is the normal state, not an error.

Note the existing Usage Stats page is per-customer rate-limit usage and unrelated to this, despite the similar name.

Testing

Server 1148 tests, webui 285 across 55 files, tsc and eslint clean. New coverage: AdminStatisticsServiceTest for the computation, five AdminAPITest cases for the new endpoints (archived month, computed current month, CSV attachment, and non-admin rejection on both), and nine webui cases for the page.

Two test changes are deliberate behaviour changes rather than fixes, and are the places to look first in review:

• testCurrentMonthAdminReportCsv / ...Json asserted the current month returns 400 Combination of year and month lies in the future. They now assert it is computed — the Deployment Statistics #235 behaviour above.
• The archival job's computation tests moved to AdminStatisticsServiceTest with the logic they cover, leaving the job's own test as a thin delegation check.

AdminAPITest also needed AdminStatisticsService registered as a mock bean, since it constructs AdminService directly and the constructor gained an argument.

Not included

There is no "which months have data" endpoint, so stepping back through unarchived months shows the empty-state message one month at a time. That is fine on open-vsx.org, which has years of history, and slightly clunky on a young registry. A month index would fix it and is a small addition — happy to add it here or separately if you would rather the picker only offered months that exist.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new dashboard currently treats any fetch failure as “not archived” (masking real errors), and the added server API tests use local time instead of UTC which can make them flaky around month boundaries.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds an admin-facing “Statistics” dashboard and supporting server endpoints to display monthly registry-wide stats (including current-month on-the-fly computation) and provide a CSV export, aligning with the remaining asks from #351 / #235 without breaking the existing token-based /admin/report integrations.

Changes:

• Server: add session-authenticated /admin/statistics (JSON) and /admin/statistics/csv (CSV attachment) endpoints and allow current-month stats to be computed on demand.
• Server: refactor monthly computation into AdminStatisticsService so the archival job and on-demand path share identical logic.
• Web UI: add /admin-dashboard/statistics page with month navigation, charts/tables, and CSV download; add unit tests.

File summaries

File	Description
webui/test/unit/pages/admin-dashboard/statistics.spec.tsx	Adds unit tests for the new admin statistics page.
webui/src/pages/admin-dashboard/statistics/use-admin-statistics.ts	Introduces a React Query hook for fetching monthly admin statistics.
webui/src/pages/admin-dashboard/statistics/statistics.tsx	Implements the admin statistics dashboard UI (cards, charts, tables, CSV link).
webui/src/pages/admin-dashboard/admin-dashboard.tsx	Registers the new Statistics nav entry and route.
webui/src/pages/admin-dashboard/admin-dashboard-routes.ts	Adds the STATISTICS route constant.
webui/src/extension-registry-types.ts	Adds the AdminStatistics type mirroring the server JSON payload.
webui/src/extension-registry-service.ts	Adds getAdminStatistics + CSV URL helper to the admin service client.
server/src/test/java/org/eclipse/openvsx/admin/AdminStatisticsServiceTest.java	Adds focused unit tests for the refactored statistics computation.
server/src/test/java/org/eclipse/openvsx/admin/AdminStatisticsJobRequestHandlerTest.java	Updates the job handler test to verify delegation to the service.
server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java	Extends API tests for current-month behavior and new /admin/statistics* endpoints.
server/src/main/java/org/eclipse/openvsx/admin/AdminStatisticsService.java	Adds computeAdminStatistics and shared computation logic (TOP_LIMIT, downloads delta).
server/src/main/java/org/eclipse/openvsx/admin/AdminStatisticsJobRequestHandler.java	Refactors handler to compute via service and persist archived rows.
server/src/main/java/org/eclipse/openvsx/admin/AdminService.java	Serves current-month stats on demand; relaxes future-month validation.
server/src/main/java/org/eclipse/openvsx/admin/AdminAPI.java	Adds session-authenticated JSON + CSV endpoints for the dashboard.

Review details

Suppressed comments (7)

webui/src/pages/admin-dashboard/statistics/statistics.tsx:192

• StatisticsAdmin currently shows the “No statistics were archived…” empty-state for any query error (including network/5xx/403), and it can also show the empty-state while still rendering previously cached data. It should only treat HTTP 404 as the normal “not archived” case, and handle other errors separately (e.g. show an error alert / bubble up to global error handling).

            {isFetching && !data ? <CircularProgress /> : null}
            {error && !isFetching ? <NoStatistics month={heading} /> : null}
            {data ? <StatisticsContent statistics={data} /> : null}

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1842

• Same UTC-vs-local-time issue here: LocalDateTime.now() can disagree with the service’s TimeUtil.getCurrentUTC() month logic and make this test flaky at month boundaries.

    void testCurrentMonthAdminReportJson() throws Exception {
        var token = mockAdminToken();
        var now = LocalDateTime.now();
        var year = now.getYear();

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1864

• Same UTC-vs-local-time issue: past is derived from LocalDateTime.now() but the API uses UTC for deciding whether a month is current/future. Use TimeUtil.getCurrentUTC() to avoid boundary flakiness.

    void testPastMonthWithoutArchivedReportIsNotFound() throws Exception {
        var token = mockAdminToken();
        var past = LocalDateTime.now().minusMonths(2);
        when(repositories.findAdminStatisticsByYearAndMonth(past.getYear(), past.getMonthValue())).thenReturn(null);

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1884

• Same UTC-vs-local-time issue: this archived-month test derives past from the system zone, but the server-side month logic is UTC-based; use TimeUtil.getCurrentUTC() to avoid flakiness around month boundaries.

    void testStatisticsForAnArchivedMonth() throws Exception {
        mockAdminUser();
        var past = LocalDateTime.now().minusMonths(1);
        var year = past.getYear();

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1902

• Same UTC-vs-local-time issue: use TimeUtil.getCurrentUTC() instead of LocalDateTime.now() so the test’s “current month” matches the service’s UTC-based logic.

    @Test
    void testStatisticsComputesTheCurrentMonth() throws Exception {
        mockAdminUser();
        var now = LocalDateTime.now();
        var year = now.getYear();

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1934

• Same UTC-vs-local-time issue for the CSV attachment test: deriving past from LocalDateTime.now() can mismatch the server’s UTC month logic around boundaries; use TimeUtil.getCurrentUTC() here too.

    void testStatisticsCsvIsAnAttachment() throws Exception {
        mockAdminUser();
        var past = LocalDateTime.now().minusMonths(1);
        var year = past.getYear();
        var month = past.getMonthValue();

server/src/test/java/org/eclipse/openvsx/admin/AdminAPITest.java:1955

• Same UTC-vs-local-time issue for the “not admin” CSV test: use UTC-derived month/year so the request month classification matches production behavior.

    void testStatisticsCsvNotAdmin() throws Exception {
        mockNormalUser();
        var past = LocalDateTime.now().minusMonths(1);
        mockMvc.perform(
                get("/admin/statistics/csv?year={year}&month={month}", past.getYear(), past.getMonthValue())

• Files reviewed: 14/14 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.