chore(bitrot): add checking of instrumentations not supporting the 'latest' release of a package (#3167)

The bitrot script compares the 'Supported Versions' range from the README to
the 'latest' version published to npm. The value from the README is used
because that was easiest -- gleaning the package and version range from
the instrumentation code is not straightforward.

Author: trentm

packages/instrumentation-fastify/README.md

@@ -23,7 +23,7 @@ npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrument
 
 ### Supported Versions
 
-- [`fastify`](https://www.npmjs.com/package/fastify) versions `>=3.0.0 <5`
+- [`fastify`](https://www.npmjs.com/package/fastify) versions `>=3.0.0 <6`
 
 ## Usage
 

packages/instrumentation-lru-memoizer/README.md

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-lru-memoizer
 
 ## Supported Versions
 
-- [`lru-memorizer`](https://www.npmjs.com/package/lru-memoizer) versions `>=1.3.0 <3`
+- [`lru-memoizer`](https://www.npmjs.com/package/lru-memoizer) versions `>=1.3.0 <3`
 
 ## Usage
 

packages/instrumentation-openai/README.md

@@ -15,7 +15,7 @@ npm install --save @opentelemetry/instrumentation-openai
 
 ## Supported Versions
 
-- openai `>=4.19.0 <7`
+- [`openai`](https://www.npmjs.com/package/openai) versions `>=4.19.0 <7`
 
 ## Usage
 

packages/instrumentation-pino/README.md

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-pino
 
 ## Supported Versions
 
-- [`pino`](https://www.npmjs.com/package/pino) versions `>=5.14.0 <10`
+- [`pino`](https://www.npmjs.com/package/pino) versions `>=5.14.0 <11`
   - The "log sending" feature is only supported in pino v7 and later.
 
 ## Usage

packages/instrumentation-typeorm/README.md

@@ -15,9 +15,9 @@ Compatible with OpenTelemetry JS API `^1.3.0` and SDK `2.0+`.
 npm install --save @opentelemetry/instrumentation-typeorm
 ```
 
-### Supported versions
+## Supported versions
 
-- `>=0.3.0 <1`
+- [`typeorm`](https://www.npmjs.com/package/typeorm) versions `>=0.3.0 <1`
 
 ## Usage
 

scripts/bitrot.mjs

@@ -32,6 +32,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { globSync } from 'glob';
+import { satisfies } from 'semver';
 
 const TOP = path.resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
 const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR?.length > 0;
@@ -50,6 +51,17 @@ function problem(...args) {
   }
 }
 
+function warn(...args) {
+  if (USE_COLOR) {
+    process.stdout.write('\x1b[33m');
+  }
+  args.unshift('bitrot warn:');
+  console.warn(...args);
+  if (USE_COLOR) {
+    process.stdout.write('\x1b[39m');
+  }
+}
+
 function gitCloneSync(repo, dir) {
   execSync(`git clone ${repo} "${dir}"`)
 }
@@ -108,8 +120,122 @@ function bitrotRenovateCoreExperimental() {
   }
 }
 
+function getNpmInfo(name) {
+  const CACHE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+  const cache = ensureCacheLoaded('npmInfo');
+  const cacheEntry = cache[name];
+  if (cacheEntry) {
+    if (cacheEntry.timestamp + CACHE_TIMEOUT_MS > Date.now()) {
+      return cacheEntry.value;
+    } else {
+      delete cache[name];
+    }
+  }
+
+  // Limited security guard on exec'ing given `name`.
+  const PKG_NAME_RE = /^(@[\w_.-]+\/)?([\w_.-]+)$/;
+  if (!PKG_NAME_RE.test(name)) {
+    throw new Error(
+      `${JSON.stringify(name)} does not look like a valid npm package name`,
+    );
+  }
+
+  const stdout = execSync(`npm info -j "${name}"`);
+  const npmInfo = JSON.parse(stdout);
+
+  cache[name] = {
+    timestamp: Date.now(),
+    value: npmInfo,
+  };
+  saveCache();
+  return npmInfo;
+}
+
+/**
+ * BITROT: Check if instrumentations are missing support for major releases of
+ * the target package.
+ *
+ * Limitations:
+ * - This doesn't currently handle both `pg` and `pg-pool` from instr-pg.
+ * - This doesn't currently support instr-aws-sdk, because of the wildcard in
+ *   the packages supported: `@aws-sdk/client-*`.
+ */
+function bitrotInstrumentations() {
+  const instrReadmes = globSync(path.join(TOP, 'packages/instrumentation-*/README.md'));
+
+  // Match examples:
+  //  - [`undici`](https://www.npmjs.com/package/undici) version `>=5.12.0`
+  //  - [`pino`](https://www.npmjs.com/package/pino) versions `>=5.14.0 <10`
+  //  - [`tedious`](https://www.npmjs.com/package/tedious) `>=1.11.0 <20`
+  //  - [socket.io](https://www.npmjs.com/package/socket.io) versions `>=2.0.0 <5`
+  const supVerRe = /^###? Supported Versions\n\n*^- \[`?([\w\.@\/-]+)`?\].* `(.*?)`$/mi
+
+  // Skip some instrumentations for which the supported version range is N/A.
+  const SKIP_INSTRS = [
+    'user-interaction',
+    'long-task',
+    'document-load',
+    'runtime-node',
+    'dns',
+    'net',
+    'fs',
+    'redis-4',
+    'aws-sdk',
+    'aws-lambda',
+  ]
+
+  for (const readmePath of instrReadmes) {
+    const instrName = path.basename(path.dirname(readmePath)).slice('instrumentation-'.length)
+    if (SKIP_INSTRS.includes(instrName)) {
+      continue;
+    }
+    const content = fs.readFileSync(readmePath, 'utf8');
+    const match = supVerRe.exec(content)
+    if (match) delete match.input;
+    if (!match) {
+      warn(`could not determine supported versions from "packages/instrumentation-${instrName}/README.md`);
+      continue;
+    }
+    const pkgName = match[1];
+    const supVerRange = match[2];
+
+    const npmInfo = getNpmInfo(pkgName);
+    const latestVer = npmInfo['dist-tags'].latest;
+    if (!satisfies(latestVer, supVerRange)) {
+      problem(`packages/instrumentation-${instrName}/README.md: the "latest" version of \`${pkgName}\` (${latestVer}) is not supported: the supported range is \`${supVerRange}\``);
+    }
+  }
+}
+
 function bitrot() {
   bitrotRenovateCoreExperimental();
+  bitrotInstrumentations();
+}
+
+// ---- caching
+
+const gCachePath = path.join(BUILD_DIR, 'bitrot.cache.json');
+let gCache = null;
+
+function ensureCacheLoaded(ns) {
+  if (gCache === null) {
+    try {
+      gCache = JSON.parse(fs.readFileSync(gCachePath));
+    } catch (loadErr) {
+      gCache = {};
+    }
+  }
+  if (!(ns in gCache)) {
+    gCache[ns] = {};
+  }
+  return gCache[ns];
+}
+
+function saveCache() {
+  if (gCache !== null) {
+    fs.mkdirSync(path.dirname(gCachePath), { recursive: true });
+    fs.writeFileSync(gCachePath, JSON.stringify(gCache, null, 2));
+  }
 }
 
 // ---- mainline