Validation script for examples that integrate rollbar locally (#1250)

Author: matux

.github/workflows/ci.yml

@@ -55,3 +55,6 @@ jobs:
 
       - name: Run tests
         run: npm run test-ci
+
+      - name: Validate examples
+        run: npm run validate:examples

package.json

@@ -113,7 +113,9 @@
     "test-ci": "./node_modules/.bin/grunt test && npm run test-server",
     "lint": "./node_modules/.bin/eslint .",
     "pack": "node scripts/pack.js",
+    "validate": "npm run validate:es5 && npm run validate:examples",
     "validate:es5": "es-check es5 './dist/**/*.js' --verbose",
+    "validate:examples": "node scripts/validate-examples.js -p",
     "update:snippets:examples": "node scripts/update-snippets.js examples"
   }
 }

scripts/pack.js

@@ -49,7 +49,7 @@ export async function findUp({ fileName, dir = process.cwd() }) {
 export async function npm(args, { cwd = process.cwd(), id = '' }) {
   const child = spawn('npm', args, {
     cwd,
-    shell: true,
+    shell: false,
     stdio: ['inherit', 'pipe', 'pipe'],
   });
 
@@ -62,7 +62,9 @@ export async function npm(args, { cwd = process.cwd(), id = '' }) {
   const [code, signal] = await once(child, 'close');
 
   if (code !== 0 || signal) {
-    const msg = std.err.trim() || std.out.trim();
+    const stderr = std.err.trim();
+    const stdout = std.out.trim();
+    const msg = `\nSTDERR:\n${stderr}\nSTDOUT:\n${stdout}`;
     throw new Error(
       `npm ` +
         `${args.join(' ')} ` +
@@ -74,3 +76,41 @@ export async function npm(args, { cwd = process.cwd(), id = '' }) {
 
   return std.out;
 }
+
+/**
+ * Transforms each element in a given array in parallel with a specified
+ * concurrency limit, preserving the original order.
+ *
+ * @param {Array} xs - Array of items to transform.
+ * @param {Function} f - Async transform for each item.
+ * @param {number} c - Maximum number of concurrent transforms.
+ * @returns {Promise<Array>} The transformed array.
+ * @example
+ * const results = await parallelMap(files, async (file) => {
+ *   return await processFile(file);
+ * }, 4);
+ */
+export async function parallelMap(xs, f, c) {
+  if (c <= 0) {
+    throw new Error('Concurrency limit must be greater than 0');
+  }
+
+  const ys = new Array(xs.length);
+  const jobs = new Set();
+
+  for (const [i, x] of xs.entries()) {
+    const p = Promise.resolve()
+      .then(() => f(x, i))
+      .then((y) => (ys[i] = y));
+
+    p.finally(() => jobs.delete(p));
+    jobs.add(p);
+
+    if (jobs.size >= c) {
+      await Promise.race(jobs);
+    }
+  }
+
+  await Promise.all(jobs);
+  return ys;
+}

scripts/util.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * Validates all examples in the `examples` directory by installing dependencies
+ * and building each example using the local `rollbar.tgz` package.
+ */
+
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+import { findUp, npm, parallelMap } from './util.js';
+
+const dryRun = ['--dry-run', '-n'].some((f) => process.argv.includes(f));
+const jobsCount = (() => {
+  const i = process.argv.findIndex((a) => a === '--parallel' || a === '-p');
+  const n = i < 0 ? 0 : parseInt(process.argv[i + 1], 10) || os.cpus().length;
+  return Math.max(n, 1);
+})();
+
+async function validateExample(exampleDir, dryRun = false) {
+  const name = `examples/${path.basename(exampleDir)}`;
+
+  if (dryRun) {
+    console.log(`  - ${name} (dry run)`);
+    return;
+  }
+
+  await npm(['install'], { cwd: exampleDir, id: name });
+  await npm(['run', 'build'], { cwd: exampleDir, id: name });
+  console.log(`  ✓ ${name}`);
+}
+
+async function validateExamples() {
+  console.log('Validating examples using the local rollbar package...');
+  if (jobsCount > 1) {
+    console.log(`Running with ${jobsCount} parallel jobs`);
+  }
+  console.log();
+
+  const cwd = path.dirname(fileURLToPath(import.meta.url));
+  const root = await findUp({ fileName: 'package.json', dir: cwd });
+  const examplesDir = path.join(root, 'examples');
+
+  try {
+    await access(path.join(examplesDir, 'rollbar.tgz'));
+  } catch {
+    throw new Error(
+      `No rollbar.tgz found in ${path.relative(root, examplesDir)}. ` +
+        `Please build rollbar first.`,
+    );
+  }
+
+  const entries = await readdir(examplesDir, { withFileTypes: true });
+  const subdirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(examplesDir, entry.name));
+
+  let exampleDirs = [];
+  for (const subdir of subdirs) {
+    let pkg;
+
+    try {
+      pkg = await readFile(path.join(subdir, 'package.json'), 'utf8');
+    } catch {
+      continue;
+    }
+
+    const { dependencies } = JSON.parse(pkg);
+    if (dependencies?.rollbar === 'file:../rollbar.tgz') {
+      exampleDirs.push(subdir);
+    }
+  }
+
+  if (exampleDirs.length === 0) {
+    throw new Error('No examples found using the local rollbar package.');
+  }
+
+  await parallelMap(
+    exampleDirs,
+    async (dir) => validateExample(dir, dryRun),
+    jobsCount,
+  );
+
+  console.log('Validation succeeded');
+}
+
+validateExamples().catch((err) => {
+  console.error('Error validating examples:', err);
+  console.error(
+    '\nUsage: validate-examples [--dry-run|-n] [--parallel|-p <n>]',
+  );
+  console.error('  --parallel | -p <n>: run <n> jobs in parallel');
+  console.error('                   if no <n> is given, defaults to cpu cores');
+  console.error('  --dry-run | -n: do not run commands, just print');
+  console.error('\nExamples:');
+  console.error('  validate-examples --parallel 4');
+  console.error('  validate-examples --dry-run');
+  console.error('  validate-examples -n -p');
+  process.exit(1);
+});