@cdxgen/cdxgen 13.2.0 → 13.4.0

package/lib/ecosystems/rubyutils.js

@@ -1,26 +1,34 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import process from "node:process";
 
 import { build, Purl } from "@cdxgen/cdx-purl";
 
 // utils.js does not import rubyutils.js, so importing from it here is safe and
 // does not introduce a cyclic dependency.
-import {
-  cdxgenAgent,
-  DEBUG_MODE,
-  readEnvironmentVariable,
-} from "../core/activity.js";
+import { DEBUG_MODE, readEnvironmentVariable } from "../core/activity.js";
 import { shouldFetchLicense } from "../core/env.js";
 import { getAllFiles, safeExistsSync, safeSpawnSync } from "../core/fs.js";
+import { thoughtLog } from "../core/logger.js";
 import { dirNameStr, isWin } from "../core/paths.js";
+import { mergeDependencies } from "../inventory/depsUtils.js";
 import {
+  gatedGet,
   prefetchEnabled,
   prefetchedResponse,
   prefetchJson,
   recordPolicyDegradationFromError,
 } from "../inventory/fetchBatch.js";
+import { genericPurl } from "../inventory/purl.js";
 
 // FIXME. This has to get removed, once we improve the module detection one-liner.
 // If you're a Rubyist, please help us improve this code.
@@ -168,7 +176,7 @@ const GEM_METADATA_REFERENCE_TYPES = {
   documentation_uri: "documentation",
   funding_uri: "other",
   homepage_uri: "website",
-  mailing_list_uri: "other",
+  mailing_list_uri: "mailing-list",
   source_code_uri: "vcs",
   wiki_uri: "documentation",
 };
@@ -219,6 +227,430 @@ function parseGemRequirement(value) {
   return parts.length ? parts.join(", ") : undefined;
 }
 
+// Closing delimiters of the bracketing Ruby percent literals, such as `%q{}`.
+// Any other punctuation closes itself, as in `%q|...|`.
+const RUBY_CLOSING_DELIMITERS = { "(": ")", "[": "]", "{": "}", "<": ">" };
+
+// Longest heredoc or multi-line array a gemspec assignment is followed across
+const GEMSPEC_MAX_CONTINUATION_LINES = 200;
+
+/**
+ * Tells whether the source that follows a literal ends the statement, so the
+ * literal is the whole value: nothing, a `.freeze`, a comment, or an `if` /
+ * `unless` modifier. Anything else, such as `+ suffix`, makes the value an
+ * expression that cannot be read statically.
+ *
+ * @param {string} rest Source after the literal
+ * @returns {boolean} true when the literal is the complete value
+ */
+function endsRubyStatement(rest) {
+  let tail = rest.trim();
+  while (tail.startsWith(".freeze")) {
+    tail = tail.slice(".freeze".length).trim();
+  }
+  return (
+    !tail.length ||
+    tail.startsWith("#") ||
+    tail.startsWith(";") ||
+    tail.startsWith("if ") ||
+    tail.startsWith("unless ")
+  );
+}
+
+/**
+ * Read the Ruby string literal at the start of `text`: a double or single
+ * quoted string, or a `%q`/`%Q`/`%` percent literal. Escaped delimiters and
+ * backslashes are unescaped; every other escape sequence is kept as written.
+ * An interpolation such as `#{spec.name}` is kept verbatim, including any
+ * quotes inside it.
+ *
+ * @param {string} text Source starting with the literal
+ * @returns {{value: string, interpolated: boolean, complete: boolean, rest: string} | undefined}
+ *   The literal's value, whether it holds an interpolation, whether it was
+ *   closed within `text`, and the source after it. Undefined when `text` does
+ *   not start with a string literal.
+ */
+export function readRubyStringLiteral(text) {
+  if (!text?.length) {
+    return undefined;
+  }
+  let opener;
+  let interpolates;
+  let start;
+  if (text[0] === '"' || text[0] === "'") {
+    opener = text[0];
+    interpolates = opener === '"';
+    start = 1;
+  } else if (text[0] === "%") {
+    const kind = text[1] === "q" || text[1] === "Q" ? text[1] : "";
+    opener = text[1 + kind.length];
+    // `%w` and `%i` arrays, or a `%` that is the modulo operator
+    if (!opener || /[\w\s]/.test(opener)) {
+      return undefined;
+    }
+    interpolates = kind !== "q";
+    start = 2 + kind.length;
+  } else {
+    return undefined;
+  }
+  const closer = RUBY_CLOSING_DELIMITERS[opener] || opener;
+  let depth = 0;
+  let value = "";
+  let interpolated = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\" && i + 1 < text.length) {
+      const next = text[i + 1];
+      value += [opener, closer, "\\"].includes(next) ? next : `${ch}${next}`;
+      i++;
+      continue;
+    }
+    if (interpolates && ch === "#" && text[i + 1] === "{") {
+      const end = text.indexOf("}", i + 2);
+      if (end < 0) {
+        value += text.slice(i);
+        break;
+      }
+      value += text.slice(i, end + 1);
+      interpolated = true;
+      i = end;
+      continue;
+    }
+    if (ch === closer && depth === 0) {
+      return {
+        value,
+        interpolated,
+        complete: true,
+        rest: text.slice(i + 1),
+      };
+    }
+    if (closer !== opener) {
+      if (ch === opener) {
+        depth++;
+      } else if (ch === closer) {
+        depth--;
+      }
+    }
+    value += ch;
+  }
+  return { value, interpolated, complete: false, rest: "" };
+}
+
+/**
+ * Read a Ruby list of strings as written for `authors`, `email`, or `licenses`:
+ * an array of string literals, a `%w[]` word array, or a single string. Array
+ * elements that are not string literals, such as constants, are skipped.
+ *
+ * @param {string} text Source of the value
+ * @returns {{values: string[], complete: boolean} | undefined} The strings,
+ *   and whether the array was closed within `text`. Undefined when the value
+ *   is an expression that cannot be read statically.
+ */
+export function readRubyStringList(text) {
+  const source = text?.trim();
+  if (!source?.length) {
+    return undefined;
+  }
+  if (/^%[wW][^\w\s]/.test(source)) {
+    const closer = RUBY_CLOSING_DELIMITERS[source[2]] || source[2];
+    const end = source.indexOf(closer, 3);
+    const words = source.slice(3, end < 0 ? undefined : end);
+    return {
+      values: words.split(" ").filter((word) => word.length),
+      complete: end >= 0,
+    };
+  }
+  if (source.startsWith("[")) {
+    const values = [];
+    let rest = source.slice(1).trim();
+    while (rest.length) {
+      if (rest.startsWith("]")) {
+        return { values, complete: true };
+      }
+      const literal = readRubyStringLiteral(rest);
+      if (literal) {
+        if (!literal.complete) {
+          return { values, complete: false };
+        }
+        if (!literal.interpolated && literal.value.trim().length) {
+          values.push(literal.value.trim());
+        }
+        rest = literal.rest.trim();
+        while (rest.startsWith(".freeze")) {
+          rest = rest.slice(".freeze".length).trim();
+        }
+      } else {
+        // Skip an element that is not a string literal
+        const comma = rest.indexOf(",");
+        const close = rest.indexOf("]");
+        if (close >= 0 && (comma < 0 || close < comma)) {
+          return { values, complete: true };
+        }
+        if (comma < 0) {
+          return { values, complete: false };
+        }
+        rest = rest.slice(comma);
+      }
+      if (rest.startsWith(",")) {
+        rest = rest.slice(1).trim();
+      }
+    }
+    return { values, complete: false };
+  }
+  const literal = readRubyStringLiteral(source);
+  if (
+    !literal?.complete ||
+    literal.interpolated ||
+    !endsRubyStatement(literal.rest)
+  ) {
+    return undefined;
+  }
+  return {
+    values: literal.value
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => value.length),
+    complete: true,
+  };
+}
+
+/**
+ * Find the value assigned to a gemspec attribute on a line, such as the
+ * `"1.0".freeze` of `s.version = "1.0".freeze`.
+ *
+ * @param {string} line Whitespace-normalized gemspec line
+ * @param {string} attribute Attribute name, such as `version`
+ * @returns {string | undefined} Source of the assigned value
+ */
+function readGemspecAssignment(line, attribute) {
+  const target = `.${attribute}`;
+  let idx = line.indexOf(target);
+  while (idx >= 0) {
+    const after = line.slice(idx + target.length).trimStart();
+    // `.version =` but neither `.versions`, `.version ==`, nor `.version =>`
+    if (
+      after.startsWith("=") &&
+      !["=", "~", ">"].includes(after[1]) &&
+      !/\w/.test(line[idx + target.length] || "")
+    ) {
+      return after.slice(1).trim();
+    }
+    idx = line.indexOf(target, idx + target.length);
+  }
+  return undefined;
+}
+
+/**
+ * Read the heredoc terminator of a value such as `<<~DESC` or `<<-'EOS'.strip`.
+ *
+ * @param {string} value Source of an assigned value
+ * @returns {string | undefined} The terminator, or undefined for any other value
+ */
+function readHeredocTerminator(value) {
+  if (!value.startsWith("<<")) {
+    return undefined;
+  }
+  let rest = value.slice(2);
+  if (rest[0] === "~" || rest[0] === "-") {
+    rest = rest.slice(1);
+  }
+  const quote = rest[0] === '"' || rest[0] === "'" ? rest[0] : "";
+  rest = rest.slice(quote.length);
+  let terminator = "";
+  while (
+    terminator.length < rest.length &&
+    /\w/.test(rest[terminator.length])
+  ) {
+    terminator += rest[terminator.length];
+  }
+  return /^[A-Za-z_]\w*$/.test(terminator) ? terminator : undefined;
+}
+
+/**
+ * Change in the nesting depth of hash braces on a line. Braces inside string
+ * literals, including the ones of a `#{...}` interpolation, are not counted.
+ *
+ * @param {string} line Gemspec line
+ * @returns {number} Opened minus closed braces
+ */
+function hashBraceDelta(line) {
+  let delta = 0;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "#" && line[i + 1] !== "{") {
+      // A comment
+      break;
+    }
+    if (ch === '"' || ch === "'") {
+      const literal = readRubyStringLiteral(line.slice(i));
+      if (!literal?.complete) {
+        break;
+      }
+      i = line.length - literal.rest.length - 1;
+      continue;
+    }
+    if (ch === "{") {
+      delta++;
+    } else if (ch === "}") {
+      delta--;
+    }
+  }
+  return delta;
+}
+
+/**
+ * Expand the interpolations of a gemspec string that refer to the gem's own
+ * fields, such as `#{spec.name}` and `#{spec.version}`. Gems routinely build
+ * their changelog and documentation URIs this way.
+ *
+ * @param {string} value String value with interpolations
+ * @param {string | undefined} specVar Block variable of `Gem::Specification.new`
+ * @param {Object<string, string | undefined>} fields Known gem fields by name
+ * @returns {string} The value with every resolvable interpolation expanded
+ */
+function expandGemspecInterpolation(value, specVar, fields) {
+  return value.replace(/#\{([^{}]*)\}/g, (token, expression) => {
+    const [receiver, field, ...extra] = expression.trim().split(".");
+    if (
+      extra.length ||
+      !(specVar ? receiver === specVar : /^\w+$/.test(receiver)) ||
+      !Object.hasOwn(fields, field) ||
+      !fields[field]
+    ) {
+      return token;
+    }
+    return fields[field];
+  });
+}
+
+/**
+ * Tells whether a string is usable as a RubyGems version.
+ *
+ * @param {string | undefined} version Candidate version
+ * @returns {boolean} true for values such as `0.8.1` or `2.0.0.rc1`
+ */
+function looksLikeGemVersion(version) {
+  return !!version && /^\d[\w.+-]*$/.test(version);
+}
+
+/**
+ * Collect the local file a gemspec `require` line loads, when the file looks
+ * like the one defining the gem version, such as `lib/<gem>/version.rb`.
+ *
+ * Supported forms are `require "<gem>/version"`, `require_relative
+ * "lib/<gem>/version"`, and `require File.expand_path("../lib/<gem>/version",
+ * __FILE__)` or its `__dir__` variant.
+ *
+ * @param {string} line Whitespace-normalized gemspec line
+ * @param {string} gemspecFile Path of the gemspec
+ * @returns {string[]} Candidate file paths, most likely first
+ */
+function gemspecVersionRequireCandidates(line, gemspecFile) {
+  const keyword = ["require_relative", "require"].find(
+    (akeyword) =>
+      line.startsWith(`${akeyword} `) || line.startsWith(`${akeyword}(`),
+  );
+  if (!keyword) {
+    return [];
+  }
+  let argument = line.slice(keyword.length).trim();
+  if (argument.startsWith("(")) {
+    argument = argument.slice(1).trim();
+  }
+  const baseDir = dirname(gemspecFile);
+  let requirePath;
+  let candidates;
+  const direct = readRubyStringLiteral(argument);
+  if (direct?.complete && !direct.interpolated) {
+    requirePath = direct.value;
+    candidates =
+      keyword === "require_relative"
+        ? [join(baseDir, requirePath)]
+        : [join(baseDir, "lib", requirePath), join(baseDir, requirePath)];
+  } else if (argument.startsWith("File.expand_path(")) {
+    const expanded = readRubyStringLiteral(
+      argument.slice("File.expand_path(".length).trim(),
+    );
+    if (!expanded?.complete || expanded.interpolated) {
+      return [];
+    }
+    requirePath = expanded.value;
+    const anchor = expanded.rest.replace(/^\s*,\s*/, "");
+    // `File.expand_path(path, __FILE__)` resolves against the gemspec itself,
+    // so its leading `..` steps out of the file name, not the directory
+    if (anchor.startsWith("__FILE__")) {
+      candidates = [join(gemspecFile, requirePath)];
+    } else if (
+      anchor.startsWith("__dir__") ||
+      anchor.startsWith("File.dirname(__FILE__)")
+    ) {
+      candidates = [join(baseDir, requirePath)];
+    } else {
+      return [];
+    }
+  } else {
+    return [];
+  }
+  if (!/version$/i.test(basename(requirePath).replace(/\.rb$/, ""))) {
+    return [];
+  }
+  return candidates.map((candidate) =>
+    candidate.endsWith(".rb") ? candidate : `${candidate}.rb`,
+  );
+}
+
+/**
+ * Resolve a version constant such as `OpenTelemetry::Instrumentation::VERSION`
+ * from the version file the gemspec requires. Only files inside the gemspec
+ * directory are read, and only a plain string assignment to the constant is
+ * accepted.
+ *
+ * @param {string} gemspecFile Path of the gemspec
+ * @param {string[]} candidates Version files the gemspec requires
+ * @param {string} constantName Last segment of the constant, such as `VERSION`
+ * @returns {string | undefined} Resolved version
+ */
+function resolveGemVersionConstant(gemspecFile, candidates, constantName) {
+  const root = resolve(dirname(gemspecFile));
+  for (const candidate of candidates) {
+    const relativePath = relative(root, resolve(candidate));
+    if (
+      !relativePath.length ||
+      relativePath.split(sep)[0] === ".." ||
+      isAbsolute(relativePath) ||
+      !safeExistsSync(candidate)
+    ) {
+      continue;
+    }
+    let content;
+    try {
+      content = readFileSync(candidate, { encoding: "utf-8" });
+    } catch (_err) {
+      continue;
+    }
+    for (const aline of content.split("\n")) {
+      const trimmed = aline.trim();
+      if (!trimmed.startsWith(constantName)) {
+        continue;
+      }
+      const after = trimmed.slice(constantName.length).trimStart();
+      if (!after.startsWith("=") || after[1] === "=") {
+        continue;
+      }
+      const literal = readRubyStringLiteral(after.slice(1).trim());
+      if (
+        literal?.complete &&
+        !literal.interpolated &&
+        endsRubyStatement(literal.rest) &&
+        looksLikeGemVersion(literal.value)
+      ) {
+        return literal.value;
+      }
+    }
+  }
+  return undefined;
+}
+
 // Digest algorithms Bundler may record in the CHECKSUMS section, mapped to the
 // CycloneDX hash algorithm names.
 const GEM_CHECKSUM_ALGOS = {
@@ -478,6 +910,9 @@ export async function enrichGemsFromLocalCache(pkgList, options = {}) {
         installedPkgs = await parseGemspecData(
           readFileSync(gemspecFile, { encoding: "utf-8" }),
           gemspecFile,
+          // The gemspec is read only for the fields it holds; the registry
+          // round the caller is about to make answers the rest.
+          { noFetch: true },
         );
       } catch (_err) {
         // pass
@@ -487,6 +922,11 @@ export async function enrichGemsFromLocalCache(pkgList, options = {}) {
         if (!p.description?.length && installed.description?.length) {
           p.description = installed.description;
         }
+        // The installed gemspec is the only offline source of the gem's
+        // authors, which the registry lookups cannot supply in dry-run mode
+        if (!p.authors?.length && installed.authors?.length) {
+          p.authors = installed.authors;
+        }
         if (!p.license && installed.licenses?.length) {
           // parseGemspecData returns the CycloneDX license shape, but the
           // license of an unfinished component is a plain list of names
@@ -543,16 +983,21 @@ function applyGemMetadata(p, body) {
       p.properties.push({ name, value: `${value}` });
     }
   };
-  p.description = body.description || body.summary || "";
-  if (body.licenses) {
+  // The registry fills only what the lockfile, the gemspec and the caches on
+  // this machine left open, so a local answer survives the round.
+  if (!p.description?.length && (body.description || body.summary)) {
+    p.description = body.description || body.summary;
+  }
+  if (body.licenses && !p.license) {
     p.license = body.licenses;
   }
   if (body.metadata) {
-    if (body.metadata.source_code_uri) {
+    if (body.metadata.source_code_uri && !p.repository) {
       p.repository = { url: body.metadata.source_code_uri };
       if (
         body.homepage_uri &&
-        body.homepage_uri !== body.metadata.source_code_uri
+        body.homepage_uri !== body.metadata.source_code_uri &&
+        !p.homepage
       ) {
         p.homepage = { url: body.homepage_uri };
       }
@@ -593,11 +1038,20 @@ function applyGemMetadata(p, body) {
   if (!p.externalReferences.length) {
     p.externalReferences = undefined;
   }
-  if (body.sha) {
+  if (body.sha && !p._integrity && !p.hashes?.length) {
     p._integrity = `sha256-${body.sha}`;
   }
-  if (body.authors) {
-    p.author = body.authors;
+  // RubyGems reports the authors as a comma separated string. It is split into
+  // the `authors` array CycloneDX expects, so a gemspec sighting that already
+  // resolved the authors with their email addresses keeps the richer value.
+  if (typeof body.authors === "string" && !p.authors?.length) {
+    const names = body.authors
+      .split(",")
+      .map((name) => name.trim())
+      .filter((name) => name.length);
+    if (names.length) {
+      p.authors = names.map((name) => ({ name }));
+    }
   }
   // `ruby_version` is the `required_ruby_version` requirement. Note that the
   // sibling `rubygems_version` field is the version of RubyGems that packaged
@@ -669,14 +1123,18 @@ function gemDirectUrl(p, v2Url, v1Url) {
  * @param {Array} pkgList List of packages with metadata
  */
 export async function getRubyGemsMetadata(pkgList) {
+  // The endpoints are joined by plain concatenation, so an override without
+  // the trailing slash must not turn into a malformed URL
+  const withTrailingSlash = (url) =>
+    url?.length ? (url.endsWith("/") ? url : `${url}/`) : undefined;
   const RUBYGEMS_V2_URL =
-    readEnvironmentVariable("RUBYGEMS_V2_URL") ||
+    withTrailingSlash(readEnvironmentVariable("RUBYGEMS_V2_URL")) ||
     "https://rubygems.org/api/v2/rubygems/";
   const RUBYGEMS_V1_URL =
-    readEnvironmentVariable("RUBYGEMS_V1_URL") ||
+    withTrailingSlash(readEnvironmentVariable("RUBYGEMS_V1_URL")) ||
     "https://rubygems.org/api/v1/gems/";
   const RUBYGEMS_V1_VERSIONS_URL =
-    readEnvironmentVariable("RUBYGEMS_V1_VERSIONS_URL") ||
+    withTrailingSlash(readEnvironmentVariable("RUBYGEMS_V1_VERSIONS_URL")) ||
     "https://rubygems.org/api/v1/versions/";
   const rdepList = [];
   const apiOptions = {
@@ -720,7 +1178,17 @@ export async function getRubyGemsMetadata(pkgList) {
     for (const [name, pkgs] of Object.entries(pkgsByName)) {
       const versionedPkgs = pkgs.filter((p) => p.version);
       if (versionedPkgs.length > 1) {
+        // The listing answers every versioned variant of this gem in one
+        // request. A direct URL is asked for only an entry the listing does
+        // not answer, so it is not prefetched here: the serial path below
+        // requests one when the listing misses.
         addBatchUrl(`${RUBYGEMS_V1_VERSIONS_URL}${name}.json`);
+        for (const p of pkgs) {
+          if (!p.version) {
+            addBatchUrl(gemDirectUrl(p, RUBYGEMS_V2_URL, RUBYGEMS_V1_URL));
+          }
+        }
+        continue;
       }
       for (const p of pkgs) {
         addBatchUrl(gemDirectUrl(p, RUBYGEMS_V2_URL, RUBYGEMS_V1_URL));
@@ -748,7 +1216,7 @@ export async function getRubyGemsMetadata(pkgList) {
           }
           const res =
             prefetchedResponse(prefetched, versionsUrl) ||
-            (await cdxgenAgent.get(versionsUrl, apiOptions));
+            (await gatedGet(versionsUrl, apiOptions));
           versions = res.body;
         }
         if (Array.isArray(versions) && versions.length) {
@@ -827,7 +1295,7 @@ async function enrichGemFromVersionEndpoint(
     }
     const res =
       prefetchedResponse(prefetched, fullUrl) ||
-      (await cdxgenAgent.get(fullUrl, apiOptions));
+      (await gatedGet(fullUrl, apiOptions));
     let body = res.body;
     if (body?.length) {
       body = body[0];
@@ -1025,13 +1493,101 @@ export function collectGemModuleNames(
     : Array.from(simpleModuleNames).sort();
 }
 
+// One `"key" => value` pair of a gemspec metadata hash, or one
+// `metadata["key"] = value` assignment. The value is a string literal or a
+// reference to another spec field, as in `spec.metadata["homepage_uri"] =
+// spec.homepage`.
+const GEM_METADATA_PAIR =
+  /["']([a-z_]+)["']\s*(?:=>|\]\s*=)\s*(?:["']([^"']*)["']|(\w+)\.(homepage|name|version)\b)/g;
+
+/**
+ * Last segment of a version constant such as `Foo::Bar::VERSION`.
+ *
+ * @param {string} expression Source assigned to `spec.version`
+ * @returns {string | undefined} The constant name, such as `VERSION`
+ */
+function gemVersionConstantName(expression) {
+  let constantPath = expression.split(" ")[0];
+  let suffix;
+  while (
+    (suffix = [".freeze", ".to_s", ".dup"].find((s) =>
+      constantPath.endsWith(s),
+    ))
+  ) {
+    constantPath = constantPath.slice(0, -suffix.length);
+  }
+  if (constantPath.startsWith("::")) {
+    constantPath = constantPath.slice(2);
+  }
+  const segments = constantPath.split("::");
+  if (!segments.every((segment) => /^[A-Z]\w*$/.test(segment))) {
+    return undefined;
+  }
+  return segments[segments.length - 1];
+}
+
+/**
+ * List the executables a gem computes from its bindir, such as the `bundle
+ * gem` template's `spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }`.
+ * RubyGems installs every file of the bindir, `bin` unless the gemspec says
+ * otherwise, so the plain files there are the executables. A bindir outside
+ * the gemspec's directory is not followed.
+ *
+ * @param {string} gemspecFile Path of the gemspec
+ * @param {string} [bindir] The gemspec's `bindir`
+ * @returns {string[]} Executable names, sorted
+ */
+function listGemBindirFiles(gemspecFile, bindir = "bin") {
+  if (!gemspecFile) {
+    return [];
+  }
+  const gemDir = resolve(dirname(gemspecFile));
+  const binPath = resolve(gemDir, bindir);
+  const relativeBinPath = relative(gemDir, binPath);
+  if (
+    !relativeBinPath.length ||
+    relativeBinPath.startsWith("..") ||
+    isAbsolute(relativeBinPath) ||
+    !safeExistsSync(binPath)
+  ) {
+    return [];
+  }
+  try {
+    return readdirSync(binPath, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+      .map((entry) => entry.name)
+      .sort();
+  } catch (_err) {
+    return [];
+  }
+}
+
 /**
- * Method to parse Gemspec file contents
+ * Method to parse Gemspec file contents.
+ *
+ * A source gemspec is Ruby code. The values that can be read without running
+ * it are string literals, lists of them, heredocs, and a version constant
+ * defined in the version file the gemspec requires. Anything else is left
+ * unresolved instead of being guessed.
+ *
+ * Bundler evaluates the gemspec of a project that uses the Gemfile `gemspec`
+ * directive, and locks the gem under `PATH remote: .`. Such a locked version
+ * can be supplied through `options.lockedVersions` and is used when the
+ * gemspec computes its version in a way that cannot be read statically.
  *
  * @param {string} gemspecData Gemspec data
  * @param {string} gemspecFile File name for evidence.
+ * @param {Object} [options] Parse options
+ * @param {Object<string, string>} [options.lockedVersions] Locked versions of
+ *   the gems the project directory serves, by gem name
+ * @param {boolean} [options.projectGemspec] The gemspec describes the project
+ *   being scanned. No registry holds the project, so its gem is never looked
+ *   up and keeps what the gemspec says.
+ * @param {boolean} [options.noFetch] Read the gemspec for the fields it holds
+ *   without asking the registry about the gem. The local cache enricher uses
+ *   this, since the caller is responsible for the registry round.
  */
-export async function parseGemspecData(gemspecData, gemspecFile) {
+export async function parseGemspecData(gemspecData, gemspecFile, options = {}) {
   let pkgList = [];
   const pkg = { properties: [] };
   if (gemspecFile) {
@@ -1042,15 +1598,93 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
   }
   let versionHackMatch = false;
   let gemPlatform;
-  const gemMetadata = {};
-  let metadataBlock = false;
-  gemspecData.split("\n").forEach((l) => {
-    versionHackMatch = false;
-    l = l.replaceAll("\r", "");
-    l = l.replace(/\s+/g, " ").replaceAll("%q{", "").trim().replace(/}$/, "");
-    if (l.startsWith("#")) {
+  let specVar;
+  let literalVersion;
+  let versionExpression;
+  let bindir;
+  let computedExecutables = false;
+  const texts = {};
+  const lists = {};
+  const versionFiles = [];
+  // Keyed by metadata keys taken from the gemspec, so it has no prototype
+  const gemMetadata = Object.create(null);
+  let metadataDepth = 0;
+  // A heredoc, string, or array whose value continues on the following lines
+  let pending;
+  const assignText = (field, value) => {
+    const text = value.trim();
+    if (text.length) {
+      texts[field] = text;
+    }
+  };
+  gemspecData.split("\n").forEach((rawLine) => {
+    const line = rawLine.replaceAll("\r", "").replace(/\s+/g, " ").trim();
+    // A string or array that seems to run into the next spec attribute was
+    // misread, so keep what it had and parse the line as usual
+    if (
+      pending &&
+      pending.kind !== "heredoc" &&
+      specVar &&
+      line.startsWith(`${specVar}.`)
+    ) {
+      if (pending.kind === "list") {
+        const partialList = readRubyStringList(pending.text);
+        if (partialList?.values.length) {
+          lists[pending.field] = partialList.values;
+        }
+      } else {
+        assignText(pending.field, readRubyStringLiteral(pending.text).value);
+      }
+      pending = undefined;
+    }
+    if (pending) {
+      pending.lineCount++;
+      if (pending.kind === "heredoc") {
+        if (line === pending.terminator) {
+          assignText(pending.field, pending.text);
+          pending = undefined;
+        } else {
+          pending.text = `${pending.text} ${line}`;
+        }
+      } else {
+        pending.text = `${pending.text} ${line}`;
+        if (pending.kind === "list") {
+          const list = readRubyStringList(pending.text);
+          if (list?.complete) {
+            lists[pending.field] = list.values;
+            pending = undefined;
+          }
+        } else {
+          const literal = readRubyStringLiteral(pending.text);
+          if (literal?.complete) {
+            assignText(pending.field, literal.value);
+            pending = undefined;
+          }
+        }
+      }
+      if (pending && pending.lineCount > GEMSPEC_MAX_CONTINUATION_LINES) {
+        pending = undefined;
+      }
       return;
     }
+    if (line.startsWith("#")) {
+      return;
+    }
+    const l = line.replaceAll("%q{", "").replace(/}$/, "");
+    if (!specVar && line.includes("Gem::Specification.new")) {
+      const opening = line.indexOf("|");
+      const closing = line.indexOf("|", opening + 1);
+      const candidate =
+        opening >= 0 && closing > opening
+          ? line.slice(opening + 1, closing).trim()
+          : "";
+      if (/^\w+$/.test(candidate)) {
+        specVar = candidate;
+      }
+    }
+    if (gemspecFile) {
+      versionFiles.push(...gemspecVersionRequireCandidates(line, gemspecFile));
+    }
     // Native gems declare a platform. Installed gemspecs use either a plain
     // string (`s.platform = "java".freeze`) or the marshalled array form
     // (`s.platform = Gem::Platform.new(["x86_64", "linux", nil])`).
@@ -1075,116 +1709,100 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
         }
       }
     }
-    for (const aprop of ["name", "version", "description", "homepage"]) {
-      if (l.includes(`.${aprop} = `)) {
-        let value = l
-          .split(`.${aprop} = `)[1]
-          .replace(".freeze", "")
-          .replaceAll("''', ", "")
-          .replace(/"/g, "");
-        if (["name", "version"].includes(aprop)) {
-          value = value.replace(/["']/g, "");
-        }
-        // Do not set name=name or version=version
-        if (value !== aprop) {
-          pkg[aprop] = value;
-          break;
-        }
+    const versionValue = readGemspecAssignment(line, "version");
+    if (versionValue !== undefined) {
+      const literal = readRubyStringLiteral(versionValue);
+      if (
+        literal?.complete &&
+        !literal.interpolated &&
+        endsRubyStatement(literal.rest) &&
+        looksLikeGemVersion(literal.value.trim())
+      ) {
+        literalVersion = literal.value.trim();
+        versionExpression = undefined;
+      } else {
+        literalVersion = undefined;
+        versionExpression = versionValue;
       }
     }
-    // Handle common problems
-    if (pkg.name === "name") {
-      console.log(
-        "Unable to identify the package name by parsing the file",
-        gemspecFile,
-      );
-      return;
-    }
-    if (
-      pkg?.version === "version" ||
-      pkg?.version?.includes("$") ||
-      pkg?.version?.includes("gem_version") ||
-      pkg?.version?.includes("File.") ||
-      pkg?.version?.includes("::")
-    ) {
-      const origVersion = pkg.version;
-      pkg.version = undefined;
-      // Can we find the version from the directory name?
-      if (gemspecFile) {
-        const parentDir = basename(dirname(gemspecFile));
-        const prefix = `${pkg.name}-`;
-        if (parentDir.startsWith(prefix)) {
-          const versionFromDir = parentDir.slice(prefix.length).split("-")[0];
-          if (/\d/.test(versionFromDir)) {
-            pkg.version = versionFromDir;
-            versionHackMatch = true;
-          }
+    for (const field of ["name", "description", "summary", "homepage"]) {
+      const value = readGemspecAssignment(line, field);
+      if (value === undefined) {
+        continue;
+      }
+      const terminator = readHeredocTerminator(value);
+      if (terminator && field !== "name") {
+        pending = {
+          kind: "heredoc",
+          field,
+          terminator,
+          text: "",
+          lineCount: 0,
+        };
+        return;
+      }
+      const literal = readRubyStringLiteral(value);
+      if (!literal) {
+        continue;
+      }
+      if (!literal.complete) {
+        if (field !== "name") {
+          pending = { kind: "literal", field, text: value, lineCount: 0 };
+          return;
         }
+        continue;
       }
-      if (!versionHackMatch && !pkg.version) {
-        if (origVersion?.toLowerCase().includes("version")) {
-          if (DEBUG_MODE) {
-            console.log(
-              `Unable to identify the version for '${pkg.name}' from the string '${origVersion}'. Spec file: ${gemspecFile}`,
-            );
-          }
-        } else {
-          console.log(
-            `Unable to identify the version for '${pkg.name}'. Spec file: ${gemspecFile}`,
-          );
+      if (!endsRubyStatement(literal.rest)) {
+        continue;
+      }
+      if (field === "name") {
+        if (!literal.interpolated && literal.value.trim().length) {
+          pkg.name = literal.value.trim();
         }
+      } else {
+        assignText(field, literal.value);
       }
     }
-    for (const aprop of ["authors", "licenses"]) {
-      if (l.includes(`.${aprop} = `)) {
-        try {
-          const pline = l
-            .split(`.${aprop} = `)
-            .pop()
-            .replaceAll(".freeze", "")
-            .replaceAll("%w", "")
-            .replaceAll("'", '"')
-            .replaceAll(']"', "");
-          const apropList = JSON.parse(pline);
-          if (apropList) {
-            if (Array.isArray(apropList)) {
-              pkg[aprop] = apropList;
-            } else if (
-              typeof apropList === "string" ||
-              apropList instanceof String
-            ) {
-              pkg[aprop] = apropList.split(",");
-            }
-          }
-        } catch (_err) {
-          const alist = l
-            .replace(/[[\]'"]/g, "")
-            .replaceAll("%w", "")
-            .split(", ");
-          if (alist?.length) {
-            pkg[aprop] = alist;
-          }
+    // The singular spellings are aliases of the plural attributes, and a
+    // gemspec may spread an array over several lines
+    for (const [attribute, field] of [
+      ["authors", "authors"],
+      ["author", "authors"],
+      ["email", "email"],
+      ["licenses", "licenses"],
+      ["license", "licenses"],
+      ["executables", "executables"],
+      ["executable", "executables"],
+    ]) {
+      const value = readGemspecAssignment(line, attribute);
+      if (value === undefined) {
+        continue;
+      }
+      const list = readRubyStringList(value);
+      if (!list) {
+        // Computed executables, such as the `bundle gem` template's
+        // `spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }`, are read
+        // from the bindir once the whole gemspec is known
+        if (field === "executables") {
+          computedExecutables = true;
         }
+        continue;
       }
+      if (!list.complete) {
+        pending = { kind: "list", field, text: value, lineCount: 0 };
+        return;
+      }
+      lists[field] = list.values;
     }
-    if (l.includes(".executables = ")) {
-      try {
-        const exeList = JSON.parse(
-          l
-            .split(".executables = ")
-            .pop()
-            .replaceAll(".freeze", "")
-            .replaceAll("'", '"')
-            .replaceAll(']"', ""),
-        );
-        if (exeList && Array.isArray(exeList)) {
-          pkg.properties.push({
-            name: "cdx:gem:executables",
-            value: exeList.join(", "),
-          });
-        }
-      } catch (_err) {
-        // pass
+    const bindirValue = readGemspecAssignment(line, "bindir");
+    if (bindirValue !== undefined) {
+      const literal = readRubyStringLiteral(bindirValue);
+      if (
+        literal?.complete &&
+        !literal.interpolated &&
+        literal.value.trim().length
+      ) {
+        bindir = literal.value.trim();
       }
     }
     // A gem with extensions compiles native code at install time, which is a
@@ -1215,22 +1833,87 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
     // The free form metadata hash carries the well known project URIs and the
     // `rubygems_mfa_required` supply chain signal. It may be written inline as
     // `s.metadata = { "a" => "b", "c" => "d" }`, spread over several lines, or
-    // assigned a key at a time with `s.metadata["a"] = "b"`.
-    if (l.includes(".metadata")) {
-      metadataBlock = true;
-    }
-    if (metadataBlock) {
-      for (const [, key, value] of l.matchAll(
-        /["']([a-z_]+)["']\s*(?:=>|\]\s*=)\s*["']([^"']*)["']/g,
+    // assigned a key at a time with `s.metadata["a"] = "b"`. A multi-line hash
+    // is followed until its braces balance, so a `#{...}` interpolation or an
+    // unrelated hash further down cannot end or extend it.
+    if (metadataDepth > 0 || line.includes(".metadata")) {
+      for (const [, key, value, refVar, refField] of line.matchAll(
+        GEM_METADATA_PAIR,
       )) {
-        gemMetadata[key] = value;
+        gemMetadata[key] =
+          value !== undefined ? { value } : { refVar, refField };
       }
-      if (l.includes("}") || (!l.includes(".metadata") && !l.includes("=>"))) {
-        metadataBlock = false;
+      if (metadataDepth > 0) {
+        metadataDepth = Math.max(0, metadataDepth + hashBraceDelta(line));
+      } else if (readGemspecAssignment(line, "metadata") !== undefined) {
+        metadataDepth = Math.max(0, hashBraceDelta(line));
       }
     }
   });
-  for (const [key, value] of Object.entries(gemMetadata)) {
+  if (literalVersion) {
+    pkg.version = literalVersion;
+  } else if (versionExpression !== undefined) {
+    // Installed gems live in a `<name>-<version>` directory
+    if (gemspecFile) {
+      const parentDir = basename(dirname(gemspecFile));
+      const prefix = `${pkg.name}-`;
+      if (parentDir.startsWith(prefix)) {
+        const versionFromDir = parentDir.slice(prefix.length).split("-")[0];
+        if (looksLikeGemVersion(versionFromDir)) {
+          pkg.version = versionFromDir;
+          versionHackMatch = true;
+        }
+      }
+    }
+    // Most gems built from source assign a constant defined in the
+    // `lib/<gem>/version.rb` file the gemspec requires
+    const constantName = gemVersionConstantName(versionExpression);
+    if (!pkg.version) {
+      pkg.version =
+        constantName && versionFiles.length
+          ? resolveGemVersionConstant(gemspecFile, versionFiles, constantName)
+          : undefined;
+    }
+  }
+  // Fall back to the release Bundler evaluated the gemspec to
+  const lockedVersion =
+    options.lockedVersions && Object.hasOwn(options.lockedVersions, pkg.name)
+      ? options.lockedVersions[pkg.name]
+      : undefined;
+  if (!pkg.version && looksLikeGemVersion(lockedVersion)) {
+    pkg.version = lockedVersion;
+  }
+  if (!pkg.version && versionExpression !== undefined && DEBUG_MODE) {
+    console.log(
+      `Unable to identify the version for '${pkg.name}' from '${versionExpression}'. Spec file: ${gemspecFile}`,
+    );
+  }
+  const specFields = { name: pkg.name, version: pkg.version };
+  const expand = (value) =>
+    expandGemspecInterpolation(value, specVar, specFields);
+  // Gems that only set `summary` still deserve a description in the BOM
+  const description = texts.description || texts.summary;
+  if (description) {
+    pkg.description = expand(description);
+  }
+  // A URL whose interpolation cannot be resolved would be a wrong link
+  const homepage = texts.homepage ? expand(texts.homepage) : undefined;
+  specFields.homepage = homepage?.includes("#{") ? undefined : homepage;
+  for (const [key, entry] of Object.entries(gemMetadata)) {
+    const value =
+      entry.value !== undefined
+        ? expand(entry.value)
+        : !specVar || entry.refVar === specVar
+          ? specFields[entry.refField]
+          : undefined;
+    if (!value?.length || value.includes("#{")) {
+      if (DEBUG_MODE && entry.value !== undefined) {
+        console.log(
+          `Ignoring the metadata '${key}' of '${pkg.name}' with the unresolved value '${entry.value}'. Spec file: ${gemspecFile}`,
+        );
+      }
+      continue;
+    }
     if (key === "rubygems_mfa_required") {
       pkg.properties.push({
         name: "cdx:gem:mfaRequired",
@@ -1238,21 +1921,25 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
       });
       continue;
     }
-    const refType = GEM_METADATA_REFERENCE_TYPES[key];
+    const refType = Object.hasOwn(GEM_METADATA_REFERENCE_TYPES, key)
+      ? GEM_METADATA_REFERENCE_TYPES[key]
+      : undefined;
     if (refType) {
       pkg.externalReferences = pkg.externalReferences || [];
       pkg.externalReferences.push({ type: refType, url: value, comment: key });
     }
   }
-  // `s.homepage = "..."` is the project website. Keep it as an external
-  // reference; the transient `homepage` key is a plain string that never
-  // reaches the BOM because component conversion expects the `{ url }` shape.
-  if (pkg.homepage) {
+  // `s.homepage = "..."` is the project website
+  if (specFields.homepage) {
     pkg.externalReferences = pkg.externalReferences || [];
-    if (!pkg.externalReferences.some((ref) => ref.url === pkg.homepage)) {
-      pkg.externalReferences.push({ type: "website", url: pkg.homepage });
+    if (
+      !pkg.externalReferences.some((ref) => ref.url === specFields.homepage)
+    ) {
+      pkg.externalReferences.push({
+        type: "website",
+        url: specFields.homepage,
+      });
     }
-    delete pkg.homepage;
   }
   if (pkg.name) {
     const purlString = toGemPurl(pkg.name, pkg.version, gemPlatform);
@@ -1276,22 +1963,48 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
       },
     };
   }
-  if (pkg.authors) {
-    pkg.authors = pkg.authors.map((a) => {
-      return { name: a };
+  if (lists.authors?.length) {
+    // `spec.email` holds the contact addresses of the gem, not of an author.
+    // An address can only be attributed when there is one per author, in the
+    // same order, or when the gem has a single author.
+    const emails = (lists.email || []).filter(
+      (email) => email.includes("@") && !email.includes(" "),
+    );
+    pkg.authors = lists.authors.map((name, i) => {
+      let email;
+      if (emails.length === lists.authors.length) {
+        email = emails[i];
+      } else if (lists.authors.length === 1) {
+        email = emails[0];
+      }
+      return email ? { name, email } : { name };
     });
   }
-  if (pkg.licenses) {
-    pkg.licenses = pkg.licenses.map((l) => {
+  if (lists.licenses?.length) {
+    pkg.licenses = lists.licenses.map((l) => {
       return { license: { name: l } };
     });
   }
+  // The executables a gem ships make it an application (discussions 4407 and
+  // 4408). A literal list names them; computed ones are the files the gem
+  // installs from its bindir, which a project has next to its gemspec.
+  const executables = lists.executables?.length
+    ? lists.executables
+    : computedExecutables
+      ? listGemBindirFiles(gemspecFile, bindir)
+      : [];
+  if (executables.length) {
+    pkg.properties.push({
+      name: "cdx:gem:executables",
+      value: executables.join(", "),
+    });
+  }
   if (pkg.name) {
     pkgList = [pkg];
   } else {
     console.log("Unable to parse", gemspecData, gemspecFile);
   }
-  if (shouldFetchLicense()) {
+  if (shouldFetchLicense() && !options.projectGemspec && !options.noFetch) {
     return await getRubyGemsMetadata(pkgList);
   }
   return pkgList;
@@ -1300,11 +2013,29 @@ export async function parseGemspecData(gemspecData, gemspecFile) {
 /**
  * Method to parse Gemfile.lock
  *
+ * Besides the components and the dependency tree, the result lists as
+ * `projectGemRefs` the bom-refs of the gems served from the lockfile's own
+ * directory (`PATH` with `remote: .`), which is how Bundler records the gem a
+ * project builds when its Gemfile uses the `gemspec` directive.
+ *
+ * Gems the lockfile serves from a git remote or from a path outside the
+ * project are never sent to rubygems.org: no public registry holds the release
+ * they pinned. Before the registry round, the caches on this machine are read
+ * first, so a gem whose installed gemspec or compact index entry is present
+ * keeps those answers.
+ *
  * @param {object} gemLockData Gemfile.lock data
  * @param {string} lockFile Lock file
+ * @param {object} [options] Options
+ * @param {string} [options.gemHome] GEM_HOME to read installed gemspecs from
+ * @param {string} [options.compactIndexCacheDir] Bundler compact index cache
  */
-export async function parseGemfileLockData(gemLockData, lockFile) {
-  let pkgList = [];
+export async function parseGemfileLockData(
+  gemLockData,
+  lockFile,
+  options = {},
+) {
+  const pkgList = [];
   const pkgnames = {};
   const dependenciesList = [];
   const dependenciesMap = {};
@@ -1373,14 +2104,24 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
   let lastBranch;
   let lastTag;
   let lastParentPlatform;
+  // The section (`PATH`, `GIT`, `GEM`) and the remote the specs come from
+  let lastSection;
+  let lastSectionRemote;
+  // Source of each gem, recorded from its own top-level line in a specs
+  // section. A nested line such as `opentelemetry-api (~> 1.7)` under a `PATH`
+  // remote is only a dependency constraint: the gem itself is resolved — and
+  // described by its own `remote:` — in another section (discussion 4404).
+  const gemSourceInfo = {};
   // Dependencies block would begin with DEPENDENCIES
   let dependenciesBlock = false;
   const rootList = [];
+  const projectGemRefs = [];
   // In the second pass, we use the space in the prefix to figure out the dependency tree
   gemLockData.split("\n").forEach((l) => {
     l = l.replaceAll("\r", "");
     if (l.trim().startsWith("remote:")) {
       lastRemote = l.trim().split(" ")[1];
+      lastSectionRemote = lastRemote;
       if (lastRemote.length < 3) {
         lastRemote = undefined;
       }
@@ -1406,6 +2147,8 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
       lastBranch = undefined;
       lastTag = undefined;
       lastParentPlatform = undefined;
+      lastSection = l.trim() || undefined;
+      lastSectionRemote = undefined;
     }
     if (l.trim() === "specs:") {
       specsFound = true;
@@ -1489,6 +2232,27 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
         const bomRef = decodeURIComponent(purlString);
         if (level === 1) {
           lastParent = bomRef;
+          if (
+            lastSection === "PATH" &&
+            lastSectionRemote === "." &&
+            !projectGemRefs.includes(bomRef)
+          ) {
+            projectGemRefs.push(bomRef);
+          }
+          // Bundler locks every gem against exactly one source, so the gem's
+          // own top-level line is where its remote belongs. A later duplicate
+          // sighting of the same name would be the same release. The section
+          // is kept as well: a gem under GIT or PATH is served from a source
+          // no public registry holds.
+          if (!gemSourceInfo[name]) {
+            gemSourceInfo[name] = {
+              remote: lastRemote,
+              revision: lastRevision,
+              branch: lastBranch,
+              tag: lastTag,
+              section: lastSection,
+            };
+          }
         }
         const properties = [
           {
@@ -1496,30 +2260,6 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
             value: lockFile,
           },
         ];
-        if (lastRemote) {
-          properties.push({
-            name: "cdx:gem:remote",
-            value: lastRemote,
-          });
-        }
-        if (lastRevision) {
-          properties.push({
-            name: "cdx:gem:remoteRevision",
-            value: lastRevision,
-          });
-        }
-        if (lastBranch) {
-          properties.push({
-            name: "cdx:gem:remoteBranch",
-            value: lastBranch,
-          });
-        }
-        if (lastTag) {
-          properties.push({
-            name: "cdx:gem:remoteTag",
-            value: lastTag,
-          });
-        }
         const apkg = {
           name,
           version,
@@ -1628,6 +2368,37 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
       }
     }
   });
+  // Attach each gem's own source to it, wherever in the lockfile it was first
+  // sighted. The source properties follow the SrcFile entry to keep the order
+  // the inline construction used to produce.
+  for (const apkg of pkgList) {
+    const info = gemSourceInfo[apkg.name];
+    if (!info || !apkg.properties?.length) {
+      continue;
+    }
+    const sourceProps = [];
+    for (const [propName, value] of [
+      ["cdx:gem:remote", info.remote],
+      ["cdx:gem:remoteRevision", info.revision],
+      ["cdx:gem:remoteBranch", info.branch],
+      ["cdx:gem:remoteTag", info.tag],
+    ]) {
+      if (value && !apkg.properties.some((prop) => prop.name === propName)) {
+        sourceProps.push({ name: propName, value });
+      }
+    }
+    if (!sourceProps.length) {
+      continue;
+    }
+    const srcFileIndex = apkg.properties.findIndex(
+      (prop) => prop.name === "internal:SrcFile",
+    );
+    apkg.properties.splice(
+      srcFileIndex < 0 ? 0 : srcFileIndex + 1,
+      0,
+      ...sourceProps,
+    );
+  }
   for (const k of Object.keys(dependenciesMap)) {
     dependenciesList.push({
       ref: k,
@@ -1635,8 +2406,547 @@ export async function parseGemfileLockData(gemLockData, lockFile) {
     });
   }
   if (shouldFetchLicense()) {
-    pkgList = await getRubyGemsMetadata(pkgList);
-    return { pkgList, dependenciesList, rootList };
+    // The caches on this machine answer first: the installed gemspec holds
+    // the licence the registry would be asked for, and the compact index the
+    // checksum, so the registry round below only fills what is still missing.
+    await enrichGemsFromLocalCache(pkgList, options);
+    // The gem the lockfile serves from the project's own directory is the
+    // project itself, and a gem under GIT or PATH is served from a source no
+    // public registry holds; only the rest are looked up.
+    const lookupList = pkgList.filter(
+      (p) =>
+        !projectGemRefs.includes(p["bom-ref"]) &&
+        gemSourceInfo[p.name]?.section !== "GIT" &&
+        gemSourceInfo[p.name]?.section !== "PATH",
+    );
+    await getRubyGemsMetadata(lookupList);
   }
-  return { pkgList, dependenciesList, rootList };
+  return { pkgList, dependenciesList, rootList, projectGemRefs };
+}
+
+// Fields that describe a gem, carried over to the parent component
+const GEM_DESCRIPTIVE_FIELDS = [
+  "description",
+  "authors",
+  "licenses",
+  "externalReferences",
+];
+
+/**
+ * Describe the gem a project builds in its parent component.
+ *
+ * A gem project sees its own gem more than once: in its gemspec, in the `PATH`
+ * entry the Gemfile `gemspec` directive adds to its lockfile, and possibly as
+ * an installed copy. Each of them describes the project itself, so all are
+ * folded into the parent (discussion 4388). The parent takes the gem's
+ * identity, its descriptive metadata, and its `cdx:gem:*` properties; the
+ * dependency edges of the sightings move to the parent; and the sightings
+ * leave the component list, so the gem is never a dependency of itself.
+ *
+ * An explicit `--project-version` names the version of the parent. Otherwise
+ * the version of the gemspec, which may have come from the lockfile, is used.
+ *
+ * @param {object} parentComponent Parent component, updated in place
+ * @param {object} projectGem Component parsed from the root gemspec
+ * @param {object[]} pkgList Components
+ * @param {object[]} dependencies Dependency edges
+ * @param {string[]} rootList bom-refs of the direct dependencies
+ * @param {string[]} projectGemRefs bom-refs of the gems the lockfiles serve from the project directory
+ * @param {object} options CLI options
+ * @returns {{pkgList: object[], dependencies: object[], rootList: string[]}}
+ *   The components, edges, and direct dependencies with the gem folded in
+ */
+export function describeProjectGem(
+  parentComponent,
+  projectGem,
+  pkgList,
+  dependencies,
+  rootList,
+  projectGemRefs,
+  options = {},
+) {
+  const version = options.projectVersion
+    ? `${options.projectVersion}`
+    : projectGem.version || "latest";
+  const parentPurl = build({
+    type: "gem",
+    namespace: parentComponent.group || null,
+    name: projectGem.name,
+    version,
+  });
+  parentComponent.name = projectGem.name;
+  parentComponent.version = version;
+  parentComponent.purl = parentPurl;
+  parentComponent["bom-ref"] = decodeURIComponent(parentPurl);
+  // A gem that ships executables is an application; every other gem is a
+  // library. The gemspec decides, so the same gem keeps the same type whether
+  // it is the project being scanned or a dependency of another one
+  // (discussion 4407). After trimComponents the root gemspec sighting carries
+  // the properties of every sighting it absorbed, so checking it covers the
+  // gem's lockfile and installed copies as well.
+  const parentComponentType = projectGem.properties?.some(
+    (prop) => prop.name === "cdx:gem:executables" && prop.value?.trim().length,
+  )
+    ? "application"
+    : "library";
+  parentComponent.type = parentComponentType;
+  const parentRef = parentComponent["bom-ref"];
+  const selfRefs = new Set([parentRef, projectGem["bom-ref"]]);
+  for (const ref of projectGemRefs || []) {
+    if (
+      pkgList.some((p) => p["bom-ref"] === ref && p.name === projectGem.name)
+    ) {
+      selfRefs.add(ref);
+    }
+  }
+  // After trimComponents, the retained sighting holds the metadata of all the
+  // duplicates it absorbed, so every retained sighting is consulted
+  const sightings = [
+    projectGem,
+    ...pkgList.filter((p) => p !== projectGem && selfRefs.has(p["bom-ref"])),
+  ];
+  const hasValue = (value) =>
+    Array.isArray(value) ? value.length > 0 : !!value;
+  for (const field of GEM_DESCRIPTIVE_FIELDS) {
+    if (hasValue(parentComponent[field])) {
+      continue;
+    }
+    const source = sightings.find((s) => hasValue(s[field]));
+    if (source) {
+      parentComponent[field] = source[field];
+    }
+  }
+  for (const sighting of sightings) {
+    for (const prop of sighting.properties || []) {
+      // The manifests the parent's metadata came from belong on the parent
+      // too, so they survive as `cdx:bom:componentSrcFiles` (discussion 4410).
+      // Unlike the single-valued `cdx:gem:*` properties, a SrcFile is unique
+      // by name and value: a gem is routinely described by both its gemspec
+      // and its lockfile.
+      const isSourceFile = prop.name === "internal:SrcFile";
+      if (
+        (prop.name.startsWith("cdx:gem:") || isSourceFile) &&
+        !parentComponent.properties?.some(
+          (p) =>
+            p.name === prop.name && (!isSourceFile || p.value === prop.value),
+        )
+      ) {
+        parentComponent.properties = parentComponent.properties || [];
+        parentComponent.properties.push(prop);
+      }
+    }
+    // Checksums identify an artifact, so only the parent's own release counts
+    if (sighting["bom-ref"] === parentRef && sighting.hashes?.length) {
+      parentComponent.hashes = parentComponent.hashes || [];
+      for (const ahash of sighting.hashes) {
+        if (
+          !parentComponent.hashes.some(
+            (h) => h.alg === ahash.alg && h.content === ahash.content,
+          )
+        ) {
+          parentComponent.hashes.push(ahash);
+        }
+      }
+    }
+  }
+  const rekey = (ref) => (selfRefs.has(ref) ? parentRef : ref);
+  return {
+    pkgList: pkgList.filter((p) => !selfRefs.has(p["bom-ref"])),
+    // mergeDependencies unites the entries that now share the parent's ref and
+    // drops the edges pointing back at the parent
+    dependencies: mergeDependencies(
+      [],
+      dependencies.map((d) => ({
+        ...d,
+        ref: rekey(d.ref),
+        dependsOn: (d.dependsOn || []).map(rekey),
+      })),
+      parentComponent,
+    ),
+    rootList: [
+      ...new Set(rootList.map(rekey).filter((ref) => ref !== parentRef)),
+    ],
+  };
+}
+
+// The public RubyGems registry, whose download URL for a gem release is
+// `https://rubygems.org/gems/<name>-<version>[-<platform>].gem`
+const RUBYGEMS_ORG_REMOTE = "https://rubygems.org";
+
+/**
+ * Point each gem resolved from the public RubyGems registry at its `.gem`
+ * tarball with a `distribution` external reference (discussion 4406).
+ *
+ * The registry API supplies `gem_uri` when it is reachable, but an offline
+ * scan — a dry run, an air-gapped host, or one that only consulted Bundler's
+ * local caches — has no way to learn it. For the public registry the URL is
+ * deterministic, so it is derived from the recorded `cdx:gem:remote` and the
+ * release identity instead. Gems from any other remote are left alone: a
+ * private mirror's layout is its own business.
+ *
+ * @param {Array} pkgList Gem components, enriched in place
+ * @returns {Array} The package list
+ */
+export function addRubyGemsDistributionUrls(pkgList) {
+  for (const p of pkgList) {
+    if (!p?.name || !p.version) {
+      continue;
+    }
+    const remote = p.properties?.find(
+      (prop) => prop.name === "cdx:gem:remote",
+    )?.value;
+    // Older lockfiles name the registry over plain http, which it redirects
+    if (
+      !remote ||
+      !["https://rubygems.org", "http://rubygems.org"].includes(
+        remote.replace(/\/$/, ""),
+      )
+    ) {
+      continue;
+    }
+    if (
+      p.externalReferences?.some((ref) => ref.type === "distribution") ||
+      p.properties?.some((prop) => prop.name === "cdx:gem:gemUri")
+    ) {
+      continue;
+    }
+    const platform = gemComponentPlatform(p);
+    const gemFile =
+      platform && platform !== "ruby"
+        ? `${p.name}-${p.version}-${platform}.gem`
+        : `${p.name}-${p.version}.gem`;
+    p.externalReferences = p.externalReferences || [];
+    p.externalReferences.push({
+      type: "distribution",
+      url: `${RUBYGEMS_ORG_REMOTE}/gems/${gemFile}`,
+    });
+  }
+  return pkgList;
+}
+
+// Gem::Requirement operators, longest first so `>=` is not read as `>`
+const GEM_REQUIREMENT_OPERATORS = ["~>", ">=", "<=", "!=", ">", "<", "="];
+
+/**
+ * Split a RubyGems version into the segments Gem::Version compares: a run of
+ * digits is a number and a run of letters is a string, so `3.3.0.preview1`
+ * reads as `[3, 3, 0, "preview", 1]`. RubyGems treats `-` as `.pre.`.
+ *
+ * @param {string} version Version string
+ * @returns {Array<number|string>} Segments
+ */
+function gemVersionSegments(version) {
+  const segments = [];
+  let token = "";
+  let tokenIsDigits = false;
+  const flush = () => {
+    if (token.length) {
+      segments.push(tokenIsDigits ? Number.parseInt(token, 10) : token);
+    }
+    token = "";
+  };
+  for (const ch of version.replaceAll("-", ".pre.")) {
+    const isDigit = ch >= "0" && ch <= "9";
+    const isLetter = (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z");
+    if (!isDigit && !isLetter) {
+      flush();
+      continue;
+    }
+    if (token.length && isDigit !== tokenIsDigits) {
+      flush();
+    }
+    tokenIsDigits = isDigit;
+    token += ch;
+  }
+  flush();
+  return segments;
+}
+
+/**
+ * Compare two RubyGems versions the way Gem::Version does. Missing segments
+ * count as zero, so `2.3` equals `2.3.0`, and a string segment sorts before a
+ * number, so `3.0.0.pre` comes before `3.0.0`.
+ *
+ * @param {string} a Version
+ * @param {string} b Version
+ * @returns {number} Negative, zero, or positive
+ */
+function compareGemVersions(a, b) {
+  const lhs = gemVersionSegments(a);
+  const rhs = gemVersionSegments(b);
+  const limit = Math.max(lhs.length, rhs.length);
+  for (let i = 0; i < limit; i++) {
+    const l = lhs[i] ?? 0;
+    const r = rhs[i] ?? 0;
+    if (l === r) {
+      continue;
+    }
+    if (typeof l !== typeof r) {
+      return typeof l === "string" ? -1 : 1;
+    }
+    return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The exclusive upper bound of the pessimistic operator, as Gem::Version#bump
+ * computes it: `~> 3.1` allows `< 4`, and `~> 3.1.2` allows `< 3.2`.
+ *
+ * @param {string} version Version the operator was given
+ * @returns {string} Upper bound
+ */
+function bumpGemVersion(version) {
+  const segments = gemVersionSegments(version);
+  while (segments.some((segment) => typeof segment === "string")) {
+    segments.pop();
+  }
+  if (segments.length > 1) {
+    segments.pop();
+  }
+  segments[segments.length - 1] += 1;
+  return segments.join(".");
+}
+
+/**
+ * Read one Gem::Requirement constraint, such as `>= 3.3` or a bare `3.3.5`.
+ *
+ * @param {string} text Constraint
+ * @returns {{operator: string, version: string}|undefined} The constraint, or
+ *   undefined when it is not one, such as an interpolated expression
+ */
+function parseGemConstraint(text) {
+  let rest = text.trim();
+  const operator =
+    GEM_REQUIREMENT_OPERATORS.find((op) => rest.startsWith(op)) || "=";
+  if (rest.startsWith(operator)) {
+    rest = rest.slice(operator.length).trim();
+  }
+  if (
+    !/^[0-9][0-9A-Za-z.-]*$/.test(rest) ||
+    rest.includes("..") ||
+    rest.endsWith(".")
+  ) {
+    return undefined;
+  }
+  return { operator, version: rest };
+}
+
+/**
+ * Intersect Gem::Requirement strings into one `vers` range with the RubyGems
+ * versioning scheme, as the CycloneDX `versionRange` requires. `>= 2.3` and
+ * `>= 3.3` intersect to `vers:gem/>=3.3`, and `~> 3.1` becomes
+ * `vers:gem/>=3.1|<4`, since vers has no pessimistic operator.
+ *
+ * @param {string[]} requirements Requirement strings, each possibly holding
+ *   several comma separated constraints
+ * @returns {string|null|undefined} The range, `null` when the requirements
+ *   exclude each other, or undefined when none of them could be read
+ */
+export function rubyRequirementToVers(requirements) {
+  let lower;
+  let upper;
+  let pinned;
+  const excluded = [];
+  let understood = false;
+  const raiseLower = (version, inclusive) => {
+    const cmp = lower ? compareGemVersions(version, lower.version) : 1;
+    if (cmp > 0 || (cmp === 0 && !inclusive)) {
+      lower = { version, inclusive };
+    }
+  };
+  const dropUpper = (version, inclusive) => {
+    const cmp = upper ? compareGemVersions(version, upper.version) : -1;
+    if (cmp < 0 || (cmp === 0 && !inclusive)) {
+      upper = { version, inclusive };
+    }
+  };
+  for (const requirement of requirements) {
+    for (const part of `${requirement}`.split(",")) {
+      const constraint = parseGemConstraint(part);
+      if (!constraint) {
+        continue;
+      }
+      understood = true;
+      const { operator, version } = constraint;
+      if (operator === ">=" || operator === ">") {
+        raiseLower(version, operator === ">=");
+      } else if (operator === "<=" || operator === "<") {
+        dropUpper(version, operator === "<=");
+      } else if (operator === "~>") {
+        raiseLower(version, true);
+        dropUpper(bumpGemVersion(version), false);
+      } else if (operator === "!=") {
+        excluded.push(version);
+      } else if (pinned && compareGemVersions(pinned, version) !== 0) {
+        return null;
+      } else {
+        pinned = version;
+      }
+    }
+  }
+  if (!understood) {
+    return undefined;
+  }
+  // `>= 0` is the requirement of a gem that does not care
+  if (lower?.inclusive && compareGemVersions(lower.version, "0") === 0) {
+    lower = undefined;
+  }
+  const withinBounds = (version) => {
+    const aboveLower = lower
+      ? compareGemVersions(version, lower.version)
+      : Number.POSITIVE_INFINITY;
+    const belowUpper = upper
+      ? compareGemVersions(upper.version, version)
+      : Number.POSITIVE_INFINITY;
+    return (
+      (aboveLower > 0 || (aboveLower === 0 && lower.inclusive)) &&
+      (belowUpper > 0 || (belowUpper === 0 && upper.inclusive))
+    );
+  };
+  const isExcluded = (version) =>
+    excluded.some((aversion) => compareGemVersions(aversion, version) === 0);
+  if (
+    lower &&
+    upper &&
+    compareGemVersions(lower.version, upper.version) === 0
+  ) {
+    if (!lower.inclusive || !upper.inclusive) {
+      return null;
+    }
+    pinned = pinned || lower.version;
+  }
+  if (pinned) {
+    return withinBounds(pinned) && !isExcluded(pinned)
+      ? `vers:gem/${pinned}`
+      : null;
+  }
+  if (lower && upper && compareGemVersions(lower.version, upper.version) > 0) {
+    return null;
+  }
+  const constraints = [];
+  for (const version of excluded) {
+    // An excluded bound turns the bound exclusive, and an exclusion outside
+    // the bounds says nothing
+    if (lower && compareGemVersions(version, lower.version) === 0) {
+      lower.inclusive = false;
+    } else if (upper && compareGemVersions(version, upper.version) === 0) {
+      upper.inclusive = false;
+    } else if (
+      withinBounds(version) &&
+      !constraints.some((c) => compareGemVersions(c.version, version) === 0)
+    ) {
+      constraints.push({ version, text: `!=${version}` });
+    }
+  }
+  if (lower) {
+    constraints.push({
+      version: lower.version,
+      text: `${lower.inclusive ? ">=" : ">"}${lower.version}`,
+    });
+  }
+  if (upper) {
+    constraints.push({
+      version: upper.version,
+      text: `${upper.inclusive ? "<=" : "<"}${upper.version}`,
+    });
+  }
+  if (!constraints.length) {
+    return "vers:gem/*";
+  }
+  constraints.sort((a, b) => compareGemVersions(a.version, b.version));
+  return `vers:gem/${constraints.map((c) => c.text).join("|")}`;
+}
+
+/**
+ * Describe the Ruby runtime the gems require as one external `platform`
+ * component, and make the components that declare a `required_ruby_version`
+ * depend on it (discussion 4409).
+ *
+ * The component stands for the Ruby the bundle as a whole runs on, so its
+ * `versionRange` is the intersection of every requirement that could be read,
+ * in the `vers` syntax CycloneDX mandates for the field. Each component's own
+ * requirement stays in its `cdx:gem:rubyVersionSpecifiers` property. One
+ * runtime component per distinct requirement would describe the same
+ * interpreter many times over: a modest bundle spells `>= 2.x` a dozen ways.
+ *
+ * The type is `platform`, the CycloneDX type for a runtime environment that
+ * interprets software, and the one cdxgen gives the Ruby it finds in the
+ * build environment. The purl names no version, since a range is not one.
+ *
+ * `isExternal` and `versionRange` are CycloneDX 1.7 fields, and without them
+ * the component would claim the product bundles its interpreter, so the caller
+ * decides whether the BOM should carry it at all.
+ *
+ * @param {Array} pkgList Components
+ * @param {object} parentComponent The metadata.component, when the project is
+ *   itself a gem
+ * @param {Array} dependencies Dependency edges
+ * @returns {{pkgList: Array, dependencies: Array}} Components and edges with
+ *   the runtime component added
+ */
+export function addRubyRuntimeComponent(
+  pkgList,
+  parentComponent,
+  dependencies,
+) {
+  const requirements = [];
+  const declaringRefs = new Set();
+  for (const component of [...pkgList, parentComponent]) {
+    const requirement = component?.["bom-ref"]
+      ? component.properties
+          ?.find((prop) => prop.name === "cdx:gem:rubyVersionSpecifiers")
+          ?.value?.trim()
+      : undefined;
+    // A requirement that cannot be read, such as an interpolated expression,
+    // neither narrows the range nor links its gem to the runtime
+    if (requirement && rubyRequirementToVers([requirement]) !== undefined) {
+      requirements.push(requirement);
+      declaringRefs.add(component["bom-ref"]);
+    }
+  }
+  if (!declaringRefs.size) {
+    return { pkgList, dependencies };
+  }
+  const runtimeRef = genericPurl("ruby");
+  const runtimeComponent = {
+    type: "platform",
+    name: "ruby",
+    scope: "required",
+    // The interpreter comes with the deployment environment, not with the
+    // product the BOM describes
+    isExternal: true,
+    purl: runtimeRef,
+    "bom-ref": runtimeRef,
+  };
+  const versionRange = rubyRequirementToVers(requirements);
+  if (versionRange) {
+    runtimeComponent.versionRange = versionRange;
+  } else {
+    thoughtLog(
+      "The Ruby version requirements of the gems exclude each other, so the Ruby runtime component carries no version range.",
+      { requirements },
+    );
+  }
+  const describedRefs = new Set(dependencies.map((d) => d.ref));
+  const outDependencies = dependencies.map((d) =>
+    declaringRefs.has(d.ref)
+      ? {
+          ...d,
+          dependsOn: [...new Set([...(d.dependsOn || []), runtimeRef])].sort(),
+        }
+      : d,
+  );
+  for (const ref of declaringRefs) {
+    if (!describedRefs.has(ref)) {
+      outDependencies.push({ ref, dependsOn: [runtimeRef] });
+    }
+  }
+  if (!describedRefs.has(runtimeRef)) {
+    outDependencies.push({ ref: runtimeRef, dependsOn: [] });
+  }
+  return {
+    pkgList: [...pkgList, runtimeComponent],
+    dependencies: outDependencies,
+  };
 }