@cdxgen/cdxgen 13.5.0 → 13.7.0

package/lib/evinser/evinser.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { builtinModules } from "node:module";
 import path, { basename, join, resolve } from "node:path";
 import process from "node:process";
 
@@ -16,6 +17,7 @@ import {
   safeRmSync,
   safeWriteSync,
 } from "../core/fs.js";
+import { thoughtLog } from "../core/logger.js";
 import { isProjectToolingAllowed } from "../core/projectTooling.js";
 import { hasCppSources } from "../ecosystems/cppEvidence.js";
 import {
@@ -41,6 +43,7 @@ import {
   kosiWorkspaceComponent,
   mergeKosiEvidence,
 } from "../ecosystems/kosi.js";
+import { keepResolvedNpmVersions } from "../ecosystems/npmVersionResolution.js";
 import {
   analyzeRusiProject,
   collectRusiEvidence,
@@ -54,6 +57,7 @@ import {
   isScalasemLanguage,
 } from "../ecosystems/scalasem.js";
 import {
+  atomBomFileArgs,
   atomBuildToolArgs,
   atomCompileCommandsArgs,
   buildAtomCommandEnv,
@@ -69,6 +73,10 @@ import {
   findCryptoAlgos,
 } from "../inventory/cbomutils.js";
 import { cmakeBuildDirCandidates } from "../inventory/cmakeBuildDirs.js";
+import {
+  formatReadLossNotice,
+  loadBomForAnalysis,
+} from "../inventory/cyclonedx20.js";
 import { collectMvnDependencies } from "../inventory/deps.js";
 import { mergeServices } from "../inventory/depsUtils.js";
 import {
@@ -84,6 +92,7 @@ import {
   dosaiOmittedSections,
   dosaiReportFileOmittedSections,
   dosaiSectionsCdxgenReads,
+  dosaiSlicesFileIsFresh,
   isDosaiDotnetLanguage,
   normalizeDosaiServiceMap,
   persistDosaiSemanticsReport,
@@ -91,6 +100,11 @@ import {
   readDosaiMethodsReport,
 } from "../inventory/dosai.js";
 import { parseOccurrenceEvidenceLocation } from "../inventory/evidenceUtils.js";
+import {
+  dropSubsumedOccurrenceKeys,
+  occurrenceLocationKey,
+} from "../inventory/occurrenceKey.js";
+import { splitPurlLoose } from "../inventory/purl.js";
 import { executeOsQuery } from "../managers/binary.js";
 import { MAX_JSON_TEXT_BYTES, readJsonFile } from "../parsers/largeJson.js";
 import { postProcess } from "../stages/postgen/postgen.js";
@@ -98,7 +112,8 @@ import { createOrLoad } from "./db.js";
 import { findPurlLocations } from "./scalasem.js";
 import { createSemanticsSlices } from "./swiftsem.js";
 
-const typePurlsCache = {};
+// keyed by type names, which can be "constructor", "toString", ...: no prototype
+const typePurlsCache = Object.create(null);
 
 function appendUniqueProperty(properties, name, value) {
   if (value === undefined || value === null || value === "") {
@@ -261,6 +276,7 @@ export function buildEvinseOptions(options, args, input) {
     force: false,
     withReachables: options.deep,
     usagesSlicesFile: options.usagesSlicesFile,
+    callsitesSlicesFile: options.callsitesSlicesFile,
     dataFlowSlicesFile: options.dataFlowSlicesFile,
     reachablesSlicesFile: options.reachablesSlicesFile,
     semanticsSlicesFile: options.semanticsSlicesFile,
@@ -293,6 +309,45 @@ export function buildEvinseOptions(options, args, input) {
   };
 }
 
+/**
+ * Read the evinse input BOM as cdxgen's 1.x-shaped internal model. A
+ * CycloneDX 2.0 document is converted with loadBomForAnalysis; a 1.x document
+ * (or an internal model) is returned as is. When `options.inputBomJson` holds
+ * a model converted earlier, a copy of it is returned instead of reading
+ * `options.input` again, so prepareDB, analyzeProject and createEvinseFile
+ * each get their own object, as they did when each parsed the file.
+ *
+ * @param {Object} options Evinse options with `input` and optional
+ *   `inputBomJson`
+ * @returns {{bomJson: Object, losses: Array<{pointer: string, reason: string}>}}
+ *   The internal model and the losses of the 2.0 read (none when
+ *   `inputBomJson` was given)
+ */
+export function loadEvinseInputBom(options) {
+  if (options?.inputBomJson && typeof options.inputBomJson === "object") {
+    return { bomJson: structuredClone(options.inputBomJson), losses: [] };
+  }
+  const parsedBom = JSON.parse(fs.readFileSync(options.input, "utf8"));
+  const { internalBom, losses } = loadBomForAnalysis(parsedBom);
+  return { bomJson: internalBom, losses };
+}
+
+/**
+ * Print the one-line notice for the losses of reading a 2.0 evinse input,
+ * with the details in thoughtLog.
+ *
+ * @param {Array<{pointer: string, reason: string}>} losses Reader losses
+ */
+export function reportEvinseInputLosses(losses) {
+  if (!losses?.length) {
+    return;
+  }
+  console.log(formatReadLossNotice(losses));
+  for (const loss of losses) {
+    thoughtLog(`evinse 2.0 loss at ${loss.pointer}: ${loss.reason}`);
+  }
+}
+
 /**
  * Function to create the db for the libraries referred in the sbom.
  *
@@ -312,7 +367,7 @@ export async function prepareDB(options) {
     }
     return;
   }
-  const bomJson = JSON.parse(fs.readFileSync(bomJsonFile, "utf8"));
+  const { bomJson } = loadEvinseInputBom(options);
   if (bomJson.specVersion < 1.5) {
     console.log(
       "Evinse requires the input SBOM in CycloneDX 1.5 format or above. You can generate one by invoking cdxgen without any --spec-version argument.",
@@ -734,6 +789,7 @@ export async function createSlice(
     args.push("--slice-depth");
     args.push(readEnvironmentVariable("ATOM_SLICE_DEPTH"));
   }
+  args.push(...atomBomFileArgs(sliceType, options));
   args.push(...atomCompileCommandsArgs(filePath, language, options));
   args.push(...buildToolArgs);
   args.push(resolve(filePath));
@@ -839,15 +895,18 @@ export function purlToLanguage(purl, filePath) {
  * Walks the supplied components reading `internal:ImportedModules` (or
  * `internal:Namespaces` for php/ruby, plus the `internal:ImportedSymbols` the
  * C/C++ collector records) and `evidence.occurrences` properties to construct
- * lookup maps used during slice analysis.
+ * lookup maps used during slice analysis. An occurrence that carries `offset`
+ * or `symbol` seeds those too, so a re-run over a previous evinse output keys
+ * and annotates the same use sites the fresh slice adds.
  *
  * @param {Object[]} components CycloneDX components from the input SBOM
  * @param {string} language Application language used to select the import property name
- * @returns {{ purlLocationMap: Object<string, Set>, purlImportsMap: Object<string, string[]> }} Seeded purl location and import maps
+ * @returns {{ purlLocationMap: Object<string, Set>, purlImportsMap: Object<string, string[]>, purlSymbolMap: Object<string, Object<string, string>> }} Seeded purl location, import and symbol maps
  */
 export function initFromSbom(components, language) {
   const purlLocationMap = {};
   const purlImportsMap = {};
+  const purlSymbolMap = {};
   for (const comp of components) {
     if (!comp?.evidence) {
       continue;
@@ -880,17 +939,30 @@ export function initFromSbom(components, language) {
     if (comp.evidence.occurrences) {
       // Keep the `location#line` shape so a re-run over a cdxgen BOM does not
       // degrade seeded occurrences to file-only entries and duplicate the
-      // richer locations the fresh slice merge adds to the same set.
+      // richer locations the fresh slice merge adds to the same set. The key
+      // function also writes the location with `/`, so a Windows BOM's
+      // backslash spelling and a slice's forward-slash spelling of one place
+      // are one occurrence.
       purlLocationMap[comp.purl] = new Set(
-        comp.evidence.occurrences.map((v) =>
-          v.line ? `${v.location}#${v.line}` : v.location,
-        ),
+        comp.evidence.occurrences
+          .map((v) => occurrenceLocationKey(v.location, v.line, v.offset))
+          .filter(Boolean),
       );
+      // The first symbol a key carries wins, so a line two records without a
+      // column share keeps one symbol across a re-run over this output.
+      const symbols = (purlSymbolMap[comp.purl] ??= {});
+      for (const v of comp.evidence.occurrences) {
+        const key = occurrenceLocationKey(v.location, v.line, v.offset);
+        if (v.symbol && key && symbols[key] === undefined) {
+          symbols[key] = v.symbol;
+        }
+      }
     }
   }
   return {
     purlLocationMap,
     purlImportsMap,
+    purlSymbolMap,
   };
 }
 
@@ -1244,7 +1316,7 @@ export async function analyzeProject(dbObjMap, options) {
   let retMap = {};
   let userDefinedTypesMap = {};
   const bomFile = options.input;
-  const bomJson = JSON.parse(fs.readFileSync(bomFile, "utf8"));
+  const { bomJson } = loadEvinseInputBom(options);
   const components = bomJson.components || [];
   let cryptoComponents = [];
   let aiComponents = [];
@@ -1252,7 +1324,22 @@ export async function analyzeProject(dbObjMap, options) {
   let openapiSpecFile;
   // Load any existing purl-location information from the sbom.
   // For eg: cdxgen populates this information for javascript projects
-  let { purlLocationMap, purlImportsMap } = initFromSbom(components, language);
+  let { purlLocationMap, purlImportsMap, purlSymbolMap } = initFromSbom(
+    components,
+    language,
+  );
+  // purls whose input occurrences all belong to another installed version
+  let clearedOccurrencePurls = new Set();
+  // The places the input BOM's own import evidence gives each npm version,
+  // before any slice adds to them: they say which version a file uses.
+  const seededJsLocationMap = JS_LANGUAGES.includes(language)
+    ? Object.fromEntries(
+        Object.entries(purlLocationMap).map(([purl, keys]) => [
+          purl,
+          new Set(keys),
+        ]),
+      )
+    : {};
 
   if (isGolemGoLanguage(language)) {
     const golemReport = analyzeGolemProject(dirPath, options);
@@ -1271,6 +1358,7 @@ export async function analyzeProject(dbObjMap, options) {
         cryptoGeneratePurls: golemEvidence.cryptoGeneratePurls,
         servicesMap,
         userDefinedTypesMap,
+        purlSymbolMap,
       };
     }
     return {
@@ -1278,6 +1366,7 @@ export async function analyzeProject(dbObjMap, options) {
       servicesMap,
       dataFlowFrames,
       userDefinedTypesMap,
+      purlSymbolMap,
     };
   }
 
@@ -1297,6 +1386,7 @@ export async function analyzeProject(dbObjMap, options) {
         cryptoGeneratePurls: rusiEvidence.cryptoGeneratePurls,
         servicesMap,
         userDefinedTypesMap,
+        purlSymbolMap,
       };
     }
     return {
@@ -1304,6 +1394,7 @@ export async function analyzeProject(dbObjMap, options) {
       servicesMap,
       dataFlowFrames,
       userDefinedTypesMap,
+      purlSymbolMap,
     };
   }
 
@@ -1375,6 +1466,7 @@ export async function analyzeProject(dbObjMap, options) {
         servicesMap,
         userDefinedTypesMap,
         workspaceComponent,
+        purlSymbolMap,
       };
     }
     return {
@@ -1382,6 +1474,7 @@ export async function analyzeProject(dbObjMap, options) {
       servicesMap,
       dataFlowFrames,
       userDefinedTypesMap,
+      purlSymbolMap,
     };
   }
 
@@ -1443,6 +1536,17 @@ export async function analyzeProject(dbObjMap, options) {
             `The dosai deps slices file "${options.depsSlicesFile}" omits sections (${omittedSections.join(", ")}); running dosai for the full usages report.`,
           );
         }
+      } else if (
+        !dosaiSlicesFileIsFresh(options.depsSlicesFile, dirPath, options)
+      ) {
+        // A slice older than the sources it describes holds the occurrences
+        // of the sources as they were when it was written, so reusing it
+        // keeps occurrences of call sites that no longer exist (issue 4675).
+        if (DEBUG_MODE) {
+          console.log(
+            `The dosai deps slices file "${options.depsSlicesFile}" is older than the sources it describes; running dosai for a fresh usages report.`,
+          );
+        }
       } else {
         if (DEBUG_MODE) {
           console.log(
@@ -1540,6 +1644,7 @@ export async function analyzeProject(dbObjMap, options) {
       cryptoComponents,
       aiComponents,
       cryptoGeneratePurls,
+      purlSymbolMap,
     };
   }
   // Do reachables first so that usages slicing can reuse the atom file
@@ -1573,6 +1678,7 @@ export async function analyzeProject(dbObjMap, options) {
     cryptoGeneratePurls = retMap.cryptoGeneratePurls;
   }
   // Reuse existing usages slices
+  let usagesAtomFile;
   if (options.usagesSlicesFile && usableSlicesFile(options.usagesSlicesFile)) {
     usageSlice = filterAtomSliceData(
       readSlicesFile(options.usagesSlicesFile, "usages"),
@@ -1582,6 +1688,7 @@ export async function analyzeProject(dbObjMap, options) {
   } else {
     // Generate our own slices
     retMap = await createSlice(language, dirPath, "usages", options);
+    usagesAtomFile = retMap?.atomFile || "";
     if (retMap?.slicesFile && safeExistsSync(retMap.slicesFile)) {
       usageSlice = filterAtomSliceData(
         readSlicesFile(retMap.slicesFile, "usages"),
@@ -1661,6 +1768,48 @@ export async function analyzeProject(dbObjMap, options) {
     servicesMap = retMap.servicesMap;
     userDefinedTypesMap = retMap.userDefinedTypesMap;
   }
+  // Parse the callsites slice (JS/TS): one record per external use site, each
+  // record's own (file, line) is an occurrence of the module's package. The
+  // usages slice above still provides services and endpoints.
+  if (JS_LANGUAGES.includes(language)) {
+    let callsitesSlice;
+    if (
+      options.callsitesSlicesFile &&
+      usableSlicesFile(options.callsitesSlicesFile)
+    ) {
+      callsitesSlice = readSlicesFile(options.callsitesSlicesFile, "callsites");
+    } else if (
+      usagesAtomFile !== undefined &&
+      !safeExistsSync(usagesAtomFile)
+    ) {
+      // The usages run above built no atom (stopped at the timeout, or atom
+      // failed); a callsites run would rebuild the same atom and fail the same way.
+      console.log(
+        "Skipping the callsites slice since atom could not build the atom for the usages slice.",
+      );
+    } else {
+      retMap = await createSlice(language, dirPath, "callsites", options);
+      if (retMap?.slicesFile && safeExistsSync(retMap.slicesFile)) {
+        callsitesSlice = readSlicesFile(retMap.slicesFile, "callsites");
+      }
+    }
+    if (callsitesSlice?.callsites?.length) {
+      attributeJsCallsites(
+        callsitesSlice,
+        purlImportsMap,
+        purlLocationMap,
+        purlSymbolMap,
+      );
+    }
+    // A slice record names a package, not a version: keep each occurrence on
+    // the installed version its file uses.
+    clearedOccurrencePurls = keepResolvedNpmVersions(
+      purlLocationMap,
+      purlSymbolMap,
+      seededJsLocationMap,
+      bomJson,
+    );
+  }
   // A component whose calls the slices do not show (code inside the project,
   // such as a vendored library) is still used where its header is included
   for (const [purl, includeLocations] of cIncludeLocations) {
@@ -1734,6 +1883,8 @@ export async function analyzeProject(dbObjMap, options) {
     reachablesSlicesFile,
     semanticsSlicesFile,
     purlLocationMap,
+    purlSymbolMap,
+    clearedOccurrencePurls,
     servicesMap,
     dataFlowFrames,
     tempDir: retMap?.tempDir,
@@ -1840,11 +1991,7 @@ export function attributeCIncludes(
       continue;
     }
     const known = locations.get(purl) || new Set();
-    known.add(
-      slice.lineNumber
-        ? `${slice.fileName}#${slice.lineNumber}`
-        : slice.fileName,
-    );
+    known.add(occurrenceLocationKey(slice.fileName, slice.lineNumber));
     locations.set(purl, known);
   }
   return { symbols, locations };
@@ -1968,8 +2115,15 @@ export async function parseSliceUsages(
 ) {
   const fileName = slice.fileName;
   const typesToLookup = new Set();
-  const lKeyOverrides = {};
-  const usages = slice.usages || [];
+  // keyed by type names, which can be "constructor", "toString", ...: no prototype
+  const lKeyOverrides = Object.create(null);
+  // A user defined type has no usages; its fields' types are evidence at the fields' lines.
+  const usages =
+    slice.usages ||
+    (slice.fields || [])
+      .filter((f) => f?.typeFullName)
+      .map((f) => ({ targetObj: f }));
+  const isJs = JS_LANGUAGES.includes(language);
   // What should be the line number to use. slice.lineNumber would be quite coarse and could lead to reports such as
   // #1670. Line numbers under targetObj and definedBy is a safe bet for dynamic languages, but occassionally leads to
   // confusion when inter-procedural tracking works better than expected.
@@ -1992,13 +2146,27 @@ export async function parseSliceUsages(
       sliceLineNumber ||
       ausage?.targetObj?.lineNumber ||
       ausage?.definedBy?.lineNumber;
+    // JavaScript entries name the imported module they resolve to; attribute those by package
+    // and keep the symbol-based matching below for entries without one.
+    if (isJs) {
+      attributeJsModules(ausage, fileName, purlImportsMap, purlLocationMap);
+    }
+    const viaSymbols = (o) => !(isJs && o?.module);
     // First capture the types in the targetObj and definedBy
     for (const atype of [
-      [ausage?.targetObj?.isExternal, ausage?.targetObj?.typeFullName],
-      [ausage?.targetObj?.isExternal, ausage?.targetObj?.resolvedMethod],
-      [ausage?.definedBy?.name?.includes("::"), ausage?.definedBy?.name],
-      [ausage?.definedBy?.isExternal, ausage?.definedBy?.typeFullName],
-      [ausage?.definedBy?.isExternal, ausage?.definedBy?.resolvedMethod],
+      ...(viaSymbols(ausage?.targetObj)
+        ? [
+            [ausage?.targetObj?.isExternal, ausage?.targetObj?.typeFullName],
+            [ausage?.targetObj?.isExternal, ausage?.targetObj?.resolvedMethod],
+          ]
+        : []),
+      ...(viaSymbols(ausage?.definedBy)
+        ? [
+            [ausage?.definedBy?.name?.includes("::"), ausage?.definedBy?.name],
+            [ausage?.definedBy?.isExternal, ausage?.definedBy?.typeFullName],
+            [ausage?.definedBy?.isExternal, ausage?.definedBy?.resolvedMethod],
+          ]
+        : []),
       ...(ausage?.fields || []).map((f) => [f?.isExternal, f?.typeFullName]),
     ]) {
       if (
@@ -2039,7 +2207,8 @@ export async function parseSliceUsages(
     for (const acall of []
       .concat(ausage?.invokedCalls || [])
       .concat(ausage?.argToCalls || [])
-      .concat(ausage?.procedures || [])) {
+      .concat(ausage?.procedures || [])
+      .filter(viaSymbols)) {
       if (
         acall.resolvedMethod?.startsWith("@") ||
         acall?.callName?.includes("::")
@@ -2139,9 +2308,7 @@ export async function parseSliceUsages(
               if (!purlLocationMap[apurl]) {
                 purlLocationMap[apurl] = new Set();
               }
-              if (lKeyOverrides[atype]) {
-                purlLocationMap[apurl].add(...lKeyOverrides[atype]);
-              }
+              addAllLocations(purlLocationMap[apurl], lKeyOverrides[atype]);
             }
           }
         } else {
@@ -2149,9 +2316,7 @@ export async function parseSliceUsages(
             if (!purlLocationMap[apurl]) {
               purlLocationMap[apurl] = new Set();
             }
-            if (lKeyOverrides[atype]) {
-              purlLocationMap[apurl].add(...lKeyOverrides[atype]);
-            }
+            addAllLocations(purlLocationMap[apurl], lKeyOverrides[atype]);
           }
         }
       }
@@ -2173,9 +2338,7 @@ export async function parseSliceUsages(
           if (!purlLocationMap[ns.purl]) {
             purlLocationMap[ns.purl] = new Set();
           }
-          if (lKeyOverrides[atype]) {
-            purlLocationMap[ns.purl].add(...lKeyOverrides[atype]);
-          }
+          addAllLocations(purlLocationMap[ns.purl], lKeyOverrides[atype]);
         }
         typePurlsCache[atype] = nsHits;
       } else {
@@ -2231,7 +2394,7 @@ export function parseSemanticSlices(_language, components, semanticsSlice) {
             continue;
           }
           for (const aline of lines) {
-            locations.add(`${aswiftFile}#${aline}`);
+            locations.add(occurrenceLocationKey(aswiftFile, aline));
           }
         }
       }
@@ -2241,7 +2404,7 @@ export function parseSemanticSlices(_language, components, semanticsSlice) {
         fileIndexes,
       )) {
         for (const aline of ahit.lineNumbers) {
-          locations.add(`${ahit.file}#${aline}`);
+          locations.add(occurrenceLocationKey(ahit.file, aline));
         }
       }
     }
@@ -2583,6 +2746,17 @@ export function detectServicesFromOpenAPI(
  * @param {Array} slice Usages array for each objectSlice
  * @param {Object} servicesMap Existing service map
  */
+/**
+ * The text routes and endpoints are read from: JavaScript slices keep a call's source text in
+ * `code` and the resolved callee name in `resolvedMethod`; other languages have only the latter.
+ *
+ * @param {Object|undefined} entry slice entry
+ * @returns {string|undefined} text
+ */
+function sourceTextOf(entry) {
+  return entry?.code || entry?.resolvedMethod;
+}
+
 export function detectServicesFromUsages(language, slice, servicesMap = {}) {
   const usages = slice.usages;
   if (!usages) {
@@ -2595,30 +2769,30 @@ export function detectServicesFromUsages(language, slice, servicesMap = {}) {
     let authenticated;
     if (language === "ruby" && definedBy?.name?.includes("/")) {
       endpoints = extractEndpoints(language, definedBy.name);
-    } else if (targetObj?.resolvedMethod) {
+    } else if (sourceTextOf(targetObj)) {
       if (language !== "php") {
-        endpoints = extractEndpoints(language, targetObj?.resolvedMethod);
+        endpoints = extractEndpoints(language, sourceTextOf(targetObj));
       }
-      if (targetObj?.resolvedMethod.toLowerCase().includes("auth")) {
+      if (sourceTextOf(targetObj).toLowerCase().includes("auth")) {
         authenticated = true;
       }
-    } else if (definedBy?.resolvedMethod) {
+    } else if (sourceTextOf(definedBy)) {
       if (language !== "php") {
-        endpoints = extractEndpoints(language, definedBy?.resolvedMethod);
+        endpoints = extractEndpoints(language, sourceTextOf(definedBy));
       }
-      if (definedBy?.resolvedMethod.toLowerCase().includes("auth")) {
+      if (sourceTextOf(definedBy).toLowerCase().includes("auth")) {
         authenticated = true;
       }
     }
     if (usage.invokedCalls) {
       for (const acall of usage.invokedCalls) {
-        if (acall.resolvedMethod) {
+        if (sourceTextOf(acall)) {
           if (language !== "php") {
             const tmpEndpoints = extractEndpoints(
               language,
-              acall.resolvedMethod,
+              sourceTextOf(acall),
             );
-            if (acall.resolvedMethod.toLowerCase().includes("auth")) {
+            if (sourceTextOf(acall).toLowerCase().includes("auth")) {
               authenticated = true;
             }
             if (tmpEndpoints?.length) {
@@ -2824,12 +2998,81 @@ export function extractEndpoints(language, code) {
   return endpoints;
 }
 
+/**
+ * Key naming the package a purl refers to, independent of its version,
+ * qualifiers and subpath. Namespace and name are the decoded purl segments,
+ * so an encoded scope (`%40angular/common`) keys like a plain one.
+ *
+ * @param {string} purl Purl string
+ * @returns {string|undefined} `type/namespace/name`, or undefined for a non-purl
+ */
+export function versionlessPurlKey(purl) {
+  const parts = splitPurlLoose(purl);
+  if (!parts) {
+    return undefined;
+  }
+  return `${parts.type}/${parts.namespace || ""}/${parts.name}`;
+}
+
+/**
+ * Index the data-flow frames recorded under versionless flow purls by
+ * {@link versionlessPurlKey}. A flow purl without a version attaches to every
+ * BOM component of the same package name, whatever its version (maintainer
+ * decision, 2026-10-27); chen leaves the version off exactly when it cannot
+ * pick one between apps that pin the package differently.
+ *
+ * @param {Object} dataFlowFrames Frames keyed by flow purl
+ * @returns {Object} Frames keyed by versionless purl key
+ */
+export function indexVersionlessPurls(dataFlowFrames) {
+  const index = {};
+  for (const [purl, frames] of Object.entries(dataFlowFrames || {})) {
+    if (splitPurlLoose(purl)?.version === null) {
+      const key = versionlessPurlKey(purl);
+      if (!key) {
+        continue;
+      }
+      index[key] ??= [];
+      index[key].push(...frames);
+    }
+  }
+  return index;
+}
+
+/**
+ * Index the crypto generate pools recorded under versionless flow purls by
+ * {@link versionlessPurlKey}, the crypto counterpart of
+ * {@link indexVersionlessPurls}.
+ *
+ * @param {Object} cryptoGeneratePurls Algorithm bom-refs keyed by flow purl
+ * @returns {Object} Algorithm bom-ref sets keyed by versionless purl key
+ */
+export function indexVersionlessCrypto(cryptoGeneratePurls) {
+  const index = {};
+  for (const [purl, algos] of Object.entries(cryptoGeneratePurls || {})) {
+    if (splitPurlLoose(purl)?.version === null) {
+      const key = versionlessPurlKey(purl);
+      if (!key) {
+        continue;
+      }
+      index[key] ??= new Set();
+      for (const ref of algos || []) {
+        index[key].add(ref);
+      }
+    }
+  }
+  return index;
+}
+
 /**
  * Method to create the SBOM with evidence file called evinse file.
  *
  * @param {Object} sliceArtefacts Various artefacts from the slice operation
- * @param {Object} options Command line options
- * @returns
+ * @param {Object} options Command line options. With `returnInternalModel`,
+ *   a CycloneDX 2.0 run returns the 1.x-shaped internal model instead of the
+ *   rendered document; the file written is the rendered document either way.
+ * @returns {Promise<Object>} The BOM written to the output file, or its
+ *   internal model when `returnInternalModel` is set
  */
 export async function createEvinseFile(sliceArtefacts, options) {
   const {
@@ -2839,6 +3082,8 @@ export async function createEvinseFile(sliceArtefacts, options) {
     dataFlowSlicesFile,
     reachablesSlicesFile,
     purlLocationMap,
+    purlSymbolMap = {},
+    clearedOccurrencePurls,
     servicesMap,
     dataFlowFrames,
     componentPropertiesMap = {},
@@ -2848,9 +3093,13 @@ export async function createEvinseFile(sliceArtefacts, options) {
     cryptoGeneratePurls,
     workspaceComponent,
   } = sliceArtefacts;
-  const bomFile = options.input;
   const evinseOutFile = options.output;
-  const bomJson = JSON.parse(fs.readFileSync(bomFile, "utf8"));
+  // A 2.0 input is read into the 1.x internal model; everything below works
+  // on the 1.x shape and the final postProcess renders 2.0 again. A caller
+  // that converted the input already (bin/evinse.js) passes the model as
+  // `inputBomJson` and has printed the losses.
+  const { bomJson, losses: bomLosses } = loadEvinseInputBom(options);
+  reportEvinseInputLosses(bomLosses);
   const components = bomJson.components || [];
   // Clear existing annotations
   bomJson.annotations = [];
@@ -2875,27 +3124,62 @@ export async function createEvinseFile(sliceArtefacts, options) {
   let servicesPresent = false;
   const propertyEvidencePresent =
     metadataProperties.length || Object.keys(componentPropertiesMap).length;
+  // Versionless flow purls attach to every same-name component (see
+  // indexVersionlessPurls), so look both ways: exact purl first, then the
+  // versionless index.
+  const versionlessFrames = indexVersionlessPurls(dataFlowFrames);
+  const versionlessCrypto = indexVersionlessCrypto(cryptoGeneratePurls);
+  const depCryptoPurls =
+    Object.keys(versionlessCrypto).length && cryptoGeneratePurls
+      ? { ...cryptoGeneratePurls }
+      : cryptoGeneratePurls;
   for (const comp of [bomJson.metadata?.component, ...components]) {
     if (!comp?.purl) {
       continue;
     }
     delete comp.signature;
     appendComponentProperties(comp, componentPropertiesMap[comp.purl]);
-    const locationOccurrences = Array.from(
-      purlLocationMap[comp.purl] || [],
-    ).sort();
+    // A key with an offset names a use site; the line-only key of the same
+    // line names no place of its own then, so it is dropped rather than
+    // counted beside the use sites (see dropSubsumedOccurrenceKeys).
+    const locationOccurrences = dropSubsumedOccurrenceKeys(
+      Array.from(purlLocationMap[comp.purl] || [])
+        .filter(Boolean)
+        .sort(),
+    );
     if (locationOccurrences.length) {
       if (!comp.evidence) {
         comp.evidence = {};
       }
       // This step would replace any existing occurrences
       // This is fine as long as the input sbom was also generated by cdxgen
-      comp.evidence.occurrences = locationOccurrences
-        .filter((l) => !!l)
-        .map((l) => parseOccurrenceEvidenceLocation(l));
+      // A callsites occurrence carries its column as `offset` and its member
+      // as `symbol`; an occurrence from any other source has neither.
+      const symbols = purlSymbolMap[comp.purl] || {};
+      comp.evidence.occurrences = locationOccurrences.map((l) =>
+        parseOccurrenceEvidenceLocation(
+          l,
+          symbols[l] ? { symbol: symbols[l] } : {},
+        ),
+      );
       occEvidencePresent = true;
+    } else if (
+      clearedOccurrencePurls?.has(comp.purl) &&
+      comp.evidence?.occurrences
+    ) {
+      // The input BOM credited this version with places another installed
+      // version of the package takes.
+      delete comp.evidence.occurrences;
+      if (!Object.keys(comp.evidence).length) {
+        delete comp.evidence;
+      }
+    }
+    const compKey = versionlessPurlKey(comp.purl);
+    let dfFrames = dataFlowFrames[comp.purl];
+    const extraFrames = compKey ? versionlessFrames[compKey] : undefined;
+    if (extraFrames?.length) {
+      dfFrames = [...(dfFrames || []), ...extraFrames];
     }
-    const dfFrames = dataFlowFrames[comp.purl];
     if (dfFrames?.length) {
       if (!comp.evidence) {
         comp.evidence = {};
@@ -2909,10 +3193,20 @@ export async function createEvinseFile(sliceArtefacts, options) {
       }
     }
     // Add crypto tags if this purl offers any generation algorithm
-    if (
-      cryptoGeneratePurls?.[comp.purl] &&
-      Array.from(cryptoGeneratePurls[comp.purl]).length
-    ) {
+    let compCryptoPurls = cryptoGeneratePurls?.[comp.purl];
+    const extraCrypto = compKey ? versionlessCrypto[compKey] : undefined;
+    if (extraCrypto?.size) {
+      compCryptoPurls = new Set([...(compCryptoPurls || []), ...extraCrypto]);
+      // The provides section below looks pool entries up by bom-ref, so the
+      // merged set has to be reachable that way too.
+      if (depCryptoPurls) {
+        depCryptoPurls[comp.purl] = compCryptoPurls;
+        if (comp["bom-ref"]) {
+          depCryptoPurls[comp["bom-ref"]] = compCryptoPurls;
+        }
+      }
+    }
+    if (compCryptoPurls && Array.from(compCryptoPurls).length) {
       comp.tags = ["crypto", "crypto-generate"];
     }
   } // for
@@ -2944,14 +3238,14 @@ export async function createEvinseFile(sliceArtefacts, options) {
   }
   // Fix the dependencies section with provides information
   if (
-    cryptoGeneratePurls &&
-    Object.keys(cryptoGeneratePurls).length &&
+    depCryptoPurls &&
+    Object.keys(depCryptoPurls).length &&
     bomJson.dependencies
   ) {
     const newDependencies = [];
     for (const depObj of bomJson.dependencies) {
-      if (depObj.ref && cryptoGeneratePurls[depObj.ref]) {
-        const providedAlgos = Array.from(cryptoGeneratePurls[depObj.ref]);
+      if (depObj.ref && depCryptoPurls[depObj.ref]) {
+        const providedAlgos = Array.from(depCryptoPurls[depObj.ref]);
         if (providedAlgos.length) {
           depObj.provides = providedAlgos;
         }
@@ -2993,9 +3287,10 @@ export async function createEvinseFile(sliceArtefacts, options) {
   // Redo post-processing with evinse data. `executeOsQuery` has to be injected
   // because postgen no longer imports it directly (stages is below managers);
   // without it the crypto formulation path receives `undefined` and throws.
+  const { inputBomJson: _inputBomJson, ...postProcessOptions } = options;
   const bomNSData = await postProcess(
     { bomJson },
-    { ...options, executeOsQuery },
+    { ...postProcessOptions, executeOsQuery },
   );
   safeWriteSync(
     evinseOutFile,
@@ -3036,6 +3331,9 @@ export async function createEvinseFile(sliceArtefacts, options) {
   if (tempDirOwned && tempDir?.startsWith(getTmpDir())) {
     safeRmSync(tempDir, { recursive: true, force: true });
   }
+  if (options.returnInternalModel && bomNSData?.internalBomJson) {
+    return bomNSData.internalBomJson;
+  }
   return bomNSData?.bomJson;
 }
 
@@ -3196,15 +3494,15 @@ export function collectReachableFrames(_language, reachablesSlice) {
       if (tagStr.includes("crypto")) {
         isCryptoFlow = true;
       }
+      // Join with a space: findCryptoAlgos treats every non-alphanumeric as a
+      // word separator, and a space is the one separator cleanStr keeps.
       if (isCryptoFlow && fnode.code) {
-        codeSnippets = `${codeSnippets}\\n${fnode.code}`;
+        codeSnippets = `${codeSnippets} ${fnode.code}`;
       }
-      if (
-        tagStr.includes("crypto-generate") ||
-        fnode.code.includes("encrypt") ||
-        fnode.code.includes("decrypt") ||
-        fnode.code.includes("sign")
-      ) {
+      // Pool membership is tag-driven: a node contributes its pkg: tags only
+      // when the tagger marked it crypto-generate. Code substring tests read
+      // assign/design/signup into encrypt/decrypt/sign and are gone.
+      if (tagStr.includes("crypto-generate")) {
         cpurls = tagStr.split(", ").filter((t) => t.startsWith("pkg:"));
         for (const cpurl of cpurls) {
           if (!cryptoGeneratePurls[cpurl]) {
@@ -3407,9 +3705,176 @@ export function getClassTypeFromSignature(language, typeFullName) {
   return simplifyType(typeFullName);
 }
 
+const JS_LANGUAGES = ["javascript", "js", "ts", "typescript"];
+
+/**
+ * Add every location of a set to a purl's locations (Set.add takes a single value).
+ *
+ * @param {Set<string>} target purl location set
+ * @param {Set<string>|undefined} locations locations to add
+ */
+function addAllLocations(target, locations) {
+  for (const l of locations || []) {
+    target.add(l);
+  }
+}
+
+/**
+ * npm package name of a JavaScript module specifier: `@scope/pkg/sub` -> `@scope/pkg`,
+ * `lodash/fp` -> `lodash`. Node.js builtins (`node:fs`, `fs`) are not packages.
+ *
+ * @param {string} module module specifier
+ * @returns {string|undefined} package name
+ */
+export function jsPackageOfModule(module) {
+  if (!module || module.startsWith("node:") || module.startsWith(".")) {
+    return undefined;
+  }
+  const parts = module.split("/");
+  const pkg = module.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+  if (isNodeBuiltin(pkg)) {
+    return undefined;
+  }
+  return pkg;
+}
+
+function isNodeBuiltin(name) {
+  return NODE_BUILTINS.has(name);
+}
+
+const NODE_BUILTINS = new Set(builtinModules);
+
+const jsPurlsByPackageCache = new WeakMap();
+
+function jsPurlsByPackage(purlImportsMap) {
+  let byPackage = jsPurlsByPackageCache.get(purlImportsMap);
+  if (!byPackage) {
+    byPackage = {};
+    for (const apurl of Object.keys(purlImportsMap || {})) {
+      try {
+        const purlObj = Purl.parse(apurl);
+        if (purlObj.type !== "npm") {
+          continue;
+        }
+        const name = purlObj.namespace
+          ? `${purlObj.namespace}/${purlObj.name}`
+          : purlObj.name;
+        (byPackage[name] = byPackage[name] || []).push(apurl);
+      } catch (_e) {
+        // not a valid purl
+      }
+    }
+    jsPurlsByPackageCache.set(purlImportsMap, byPackage);
+  }
+  return byPackage;
+}
+
+/**
+ * Attribute a JavaScript usage's module-qualified entries to the packages providing them.
+ *
+ * Each call entry with a `module` is a use of that module's package at the call's line. When
+ * the slice's object is an import binding (defined by a require/import naming the module),
+ * every call the object takes part in is a use of that package too.
+ *
+ * @param {Object} ausage usage entry of an object slice
+ * @param {string} fileName file of the slice
+ * @param {Object} purlImportsMap purl -> imported modules and symbols
+ * @param {Object} purlLocationMap purl -> Set of `file#line`
+ */
+export function attributeJsModules(
+  ausage,
+  fileName,
+  purlImportsMap,
+  purlLocationMap,
+) {
+  const byPackage = jsPurlsByPackage(purlImportsMap);
+  const record = (module, line) => {
+    const pkg = jsPackageOfModule(module);
+    if (!pkg || !line) {
+      return;
+    }
+    for (const apurl of byPackage[pkg] || []) {
+      if (!purlLocationMap[apurl]) {
+        purlLocationMap[apurl] = new Set();
+      }
+      purlLocationMap[apurl].add(occurrenceLocationKey(fileName, line));
+    }
+  };
+  const calls = []
+    .concat(ausage?.invokedCalls || [])
+    .concat(ausage?.argToCalls || []);
+  for (const c of [ausage?.targetObj, ausage?.definedBy, ...calls]) {
+    if (c?.module) {
+      record(c.module, c.lineNumber);
+    }
+  }
+  // Only an import binding stands for its module: a value merely returned by a package's call
+  // (`const s = purl.toString()`) is not a use of that package wherever it goes.
+  const definedBy = ausage?.definedBy;
+  const isImportBinding =
+    definedBy?.name === "require" ||
+    definedBy?.name === "import" ||
+    /^(require|import)\(/.test(definedBy?.code || "");
+  const bindingModule = isImportBinding ? definedBy?.module : undefined;
+  if (bindingModule) {
+    for (const c of calls) {
+      record(bindingModule, c?.lineNumber);
+    }
+  }
+}
+
+/**
+ * Attribute a callsites slice's records to the packages providing their modules.
+ *
+ * Each record of `{"callsites": [...]}` (atom `callsites` command) is one external use site
+ * carrying its own file, line and column; the record is an occurrence of every purl whose
+ * package matches the record's module. A record with a column (0 or more; atom writes -1 for
+ * none) is keyed `file:line:col`, so two use sites on one line are two occurrences, and its
+ * occurrence carries the column as `offset` and `module` joined with `path` by `.` as
+ * `symbol`. A record without a column keys the line (`file#line`) and its occurrence carries
+ * the `symbol` alone; a record without a `path` leaves the symbol at the bare `module`.
+ *
+ * @param {Object} callsitesSlice callsites slice with a `callsites` array
+ * @param {Object} purlImportsMap purl -> imported modules and symbols
+ * @param {Object} purlLocationMap purl -> Set of occurrence keys
+ * @param {Object} [purlSymbolMap] purl -> occurrence key -> symbol, filled in place
+ */
+export function attributeJsCallsites(
+  callsitesSlice,
+  purlImportsMap,
+  purlLocationMap,
+  purlSymbolMap = {},
+) {
+  const byPackage = jsPurlsByPackage(purlImportsMap);
+  for (const record of callsitesSlice?.callsites || []) {
+    const pkg = jsPackageOfModule(record?.module);
+    if (!pkg || !(record.line > 0)) {
+      continue;
+    }
+    const key = occurrenceLocationKey(record.file, record.line, record.col);
+    const symbol = record.path
+      ? `${record.module}.${record.path}`
+      : record.module;
+    for (const apurl of byPackage[pkg] || []) {
+      if (!purlLocationMap[apurl]) {
+        purlLocationMap[apurl] = new Set();
+      }
+      purlLocationMap[apurl].add(key);
+      // The first symbol a key carries wins, so a re-run over a previous
+      // output, which seeds the symbol the first run wrote, stays stable.
+      if (symbol) {
+        const symbols = (purlSymbolMap[apurl] ??= {});
+        if (symbols[key] === undefined) {
+          symbols[key] = symbol;
+        }
+      }
+    }
+  }
+}
+
 function addToOverrides(lKeyOverrides, atype, fileName, ausageLineNumber) {
   if (!lKeyOverrides[atype]) {
     lKeyOverrides[atype] = new Set();
   }
-  lKeyOverrides[atype].add(`${fileName}#${ausageLineNumber}`);
+  lKeyOverrides[atype].add(occurrenceLocationKey(fileName, ausageLineNumber));
 }