chore(docs): add adoption metrics generation and service

- Introduced `AdoptionService` to fetch and cache public adoption metrics from npm, jsDelivr, and GitHub.
- Added `adoption.ts` task to generate adoption metrics and save them to `static/adoption.json`.
- Implemented utility functions for parsing adoption data from various sources.
- Updated `package.json` scripts to include a new `generate:adoption` command.
- Enhanced documentation to reflect the new adoption metrics functionality.

Signed-off-by: Cory Rylan <crylan@nvidia.com>

Author: coryrylan

projects/internals/metadata/README.md

@@ -26,6 +26,7 @@ Node.js scripts that parse the monorepo and generate static JSON metadata files:
 - **`lighthouse.ts`** - Collects performance metrics (bundled via Git LFS)
 - **`wireit.ts`** - Generates build dependency graph visualization data
 - **`releases.ts`** - Parses git history to extract package release information
+- **`adoption.ts`** - Refreshes public npm, jsDelivr, and GitHub adoption metrics
 
 ### 2. Services (`src/services/`)
 
@@ -37,6 +38,7 @@ Runtime services that provide cached access to generated metadata with fallback
 - **`TestsService`** - Exposes test coverage and results
 - **`ReleasesService`** - Returns release history
 - **`WireitService`** - Exposes build graph data
+- **`AdoptionService`** - Returns the public adoption metrics snapshot
 
 Services use a **dual-loading pattern**: first attempting to load from local `static/*.json` files, then falling back to fetching from public CDN if unavailable.
 
@@ -83,3 +85,6 @@ The metadata scripts generate common metadata about projects in the repo. This i
 - `pnpm run generate:examples`: runs the examples metadata script gathering all the source examples from the packages.
 - `pnpm run generate:wireit`: runs the wireit script that gathers all metadata details about the CI build and wireit dependencies.
 
+## Manual/scheduled tasks
+
+- `pnpm run generate:adoption`: refreshes the public adoption metrics snapshot from npm, jsDelivr, and GitHub public APIs. This task is not part of normal CI because it uses live public network data.

projects/internals/metadata/package.json

@@ -4,12 +4,13 @@
   "private": true,
   "version": "0.0.0",
   "scripts": {
-    "dev": "node --experimental-strip-types ./src/metadata.ts",
+    "dev": "node ./src/metadata.ts",
     "ci": "wireit",
     "build": "wireit",
     "generate:api": "wireit",
     "generate:tests": "wireit",
     "generate:examples": "wireit",
+    "generate:adoption": "wireit",
     "generate:lighthouse": "wireit",
     "generate:wireit": "wireit",
     "generate:releases": "wireit",
@@ -28,6 +29,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./services/adoption.service.js": {
+      "types": "./dist/services/adoption.service.d.ts",
+      "default": "./dist/src/services/adoption.service.js"
+    },
     "./services/api.service.js": {
       "types": "./dist/services/api.service.d.ts",
       "default": "./dist/src/services/api.service.js"
@@ -65,6 +70,7 @@
       "files": [
         "src/**",
         "!src/**/*.test.ts",
+        "static/adoption.json",
         "static/lighthouse.json",
         "static/releases.json",
         "static/tests.json",
@@ -85,7 +91,7 @@
       ]
     },
     "generate:api": {
-      "command": "node --experimental-strip-types ./src/tasks/api.ts",
+      "command": "node ./src/tasks/api.ts",
       "files": [
         "./src/tasks/api.ts",
         "./src/tasks/api.utils.ts",
@@ -143,7 +149,7 @@
       ]
     },
     "generate:projects": {
-      "command": "node --experimental-strip-types ./src/tasks/projects.ts",
+      "command": "node ./src/tasks/projects.ts",
       "files": [
         "./src/tasks/projects.ts",
         "./src/tasks/projects.utils.ts",
@@ -177,7 +183,7 @@
       ]
     },
     "generate:tests": {
-      "command": "node --experimental-strip-types ./src/tasks/tests.ts",
+      "command": "node ./src/tasks/tests.ts",
       "files": [
         "./src/tasks/tests.ts",
         "./src/tasks/tests.utils.ts",
@@ -272,7 +278,7 @@
       ]
     },
     "generate:examples": {
-      "command": "node --experimental-strip-types ./src/tasks/examples.ts",
+      "command": "node ./src/tasks/examples.ts",
       "clean": false,
       "files": [
         "./src/tasks/examples.ts",
@@ -321,8 +327,20 @@
         }
       ]
     },
+    "generate:adoption": {
+      "command": "node ./src/tasks/adoption.ts",
+      "clean": false,
+      "files": [
+        "src/tasks/adoption.ts",
+        "src/tasks/adoption.utils.ts",
+        "../../*/package.json"
+      ],
+      "output": [
+        "static/adoption.json"
+      ]
+    },
     "generate:lighthouse": {
-      "command": "node --experimental-strip-types ./src/tasks/lighthouse.ts",
+      "command": "node ./src/tasks/lighthouse.ts",
       "clean": false,
       "files": [
         "src/tasks/lighthouse.ts",
@@ -336,7 +354,7 @@
       ]
     },
     "generate:wireit": {
-      "command": "node --experimental-strip-types ./src/tasks/wireit.ts",
+      "command": "node ./src/tasks/wireit.ts",
       "clean": false,
       "files": [
         "src/tasks/wireit.ts",
@@ -348,7 +366,7 @@
       "dependencies": []
     },
     "generate:releases": {
-      "command": "node --experimental-strip-types ./src/tasks/releases.ts",
+      "command": "node ./src/tasks/releases.ts",
       "clean": false,
       "files": [
         "src/tasks/releases.ts",

projects/internals/metadata/src/index.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export { ExamplesService } from './services/examples.service.js';
+export * from './services/adoption.service.js';
 export * from './services/api.service.js';
 export * from './services/tests.service.js';
 export * from './services/wireit.service.js';

projects/internals/metadata/src/services/adoption.service.test.ts

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from 'vitest';
+import { AdoptionService } from './adoption.service.js';
+
+describe('AdoptionService', () => {
+  it('should return the adoption data', async () => {
+    const adoption = await AdoptionService.getData();
+
+    expect(adoption.created).toBeDefined();
+    expect(adoption.packages.length).toBeGreaterThan(0);
+    expect(adoption.totals.packages).toBe(adoption.packages.length);
+    expect(adoption.github.repository).toBe('NVIDIA/elements');
+    expect(await AdoptionService.getData()).toBe(adoption);
+  });
+});

projects/internals/metadata/src/services/adoption.service.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AdoptionSummary } from '../types.js';
+
+export class AdoptionService {
+  static #adoption: AdoptionSummary = {
+    created: '',
+    period: '',
+    sources: {
+      npmDownloads: '',
+      npmRegistry: '',
+      jsdelivr: '',
+      github: ''
+    },
+    totals: {
+      packages: 0,
+      publishedPackages: 0,
+      unavailablePackages: 0,
+      npmDownloads: 0,
+      cdnRequests: 0
+    },
+    packages: [],
+    github: {
+      repository: '',
+      stars: 0,
+      forks: 0,
+      subscribers: 0,
+      contributors: 0,
+      releases: 0,
+      stargazers: [],
+      errors: []
+    }
+  };
+
+  static async getData(): Promise<AdoptionSummary> {
+    if (AdoptionService.#adoption.created === '') {
+      AdoptionService.#adoption = (await import('../../static/adoption.json', { with: { type: 'json' } }))
+        .default as AdoptionSummary;
+    }
+
+    return AdoptionService.#adoption;
+  }
+}

projects/internals/metadata/src/services/releases.service.test.ts

@@ -10,6 +10,7 @@ describe('ReleasesService', () => {
     expect(releases).toBeDefined();
     expect(releases.created).toBeDefined();
     expect(releases.data).toBeDefined();
-    expect(releases.data.length).toBeGreaterThan(0);
+    expect(releases.data.length).toBeGreaterThan(1);
+    expect(releases.data.some(release => release.name === '@nvidia-elements/core-v2.0.2')).toBe(true);
   });
 });

projects/internals/metadata/src/tasks/adoption.ts

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { writeFileSync } from 'node:fs';
+import { getAdoptionData } from './adoption.utils.ts';
+
+const adoption = await getAdoptionData();
+
+writeFileSync('./static/adoption.json', JSON.stringify(adoption, null, 2));
+
+console.log('✅ Adoption metrics generated successfully.');