bibliothecary 14.4.0 → 15.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f7fd4aeb8298f9fcb9b5edc69b7936eed8f112f3a6dde000edda36d641cfca
-  data.tar.gz: 4d9b619aab4813b3ee77a36b0fbb1588b561a3dd42275feeb216f01d19f8ea05
+  metadata.gz: f0d3fafafd92ac4eac18f89f709733c655b0f05a803f9fcb2c1ef8b26690c584
+  data.tar.gz: b89c725a5bbbcc8139a8ebac579f610a84839e3eaaf356dd04fe4d371294ad03
 SHA512:
-  metadata.gz: a9a904ac75104ea34f45bfea2900475c89fd29a5d15ac065923d4e9d4c715ec6380d92ecea6499025063abe8f0146d2a89d9661f59f98cd216a4dcc6ce44b054
-  data.tar.gz: a4234dc007565e41587fa92ca7f970e5fdffd479debd202658e8a04edcf01943624df11aa1d0785398b87d10f694f3b84fb68fb985251315fbff67799f24fa2f
+  metadata.gz: 9b8caae9ff6a85ee12a1860f048e69c2910e7f48128a6621fc1c2d14ca587a79ca9478a14b5f092005edb02cc6ff00ee2819d6788a6a7f8fa95d5f10f1addf67
+  data.tar.gz: 408d3891213550d27395f65587010ee0c4a49da47fb290e3805971dbe7f41b7fe2add33c3d3c4dbe646e084b6536e4a33c15928e8560d32ffaa8fde45332b14b

data/CHANGELOG.md

@@ -13,6 +13,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [15.0.0]
+
+15.0.0 includes some breaking changes, so please see UPGRADING_TO_15_0_0.md to migrate your code.
+
+### Changed
+
+- Make the MultiParsers (CycloneDX, Spdx, DependenciesCSV) classes instead of modules.
+- Moved the two parser mixins, JSONRuntime and BundlerLikeManifest, into their own Bibliothecary::ParserMixins namespace.
+- Return all dependencies from SPDX and CycloneDX files regardless of platform
+
+### Removed
+
+- Removed MultiManifestFilter, since it's no longer necessary 
+
 ## [14.4.0]
 
 ### Added

data/UPGRADING_TO_15_0_0.md

@@ -0,0 +1,264 @@
+# Upgrading to Bibliothecary 15.0.0
+
+Bibliothecary 15.0.0 includes several breaking changes related to how parsers are structured and how analysis results are returned. This guide will help you upgrade your code.
+
+## Breaking Changes
+
+### 1. Analysis Results Now Use `parser` Instead of `platform`
+
+**What Changed:**
+- Analysis result hashes now use the key `parser:` instead of `platform:`
+- `Bibliothecary::Analyser.create_analysis()` returns `parser:` instead of `platform:`
+- `Bibliothecary::Analyser.create_error_analysis()` returns `parser:` instead of `platform:`
+
+**Before (14.x):**
+```ruby
+analysis = Bibliothecary.analyse('path/to/project')
+# => [{
+#   platform: "npm",
+#   path: "package.json",
+#   dependencies: [...],
+#   kind: "manifest",
+#   success: true
+# }]
+
+analysis.first[:platform]  # => "npm"
+```
+
+**After (15.0):**
+```ruby
+analysis = Bibliothecary.analyse('path/to/project')
+# => [{
+#   parser: "npm",
+#   path: "package.json",
+#   dependencies: [...],
+#   kind: "manifest",
+#   success: true
+# }]
+
+analysis.first[:parser]  # => "npm"
+```
+
+**Migration:**
+- Replace all references to `analysis[:platform]` with `analysis[:parser]`
+- Update any code that expects the `platform` key in analysis results
+- Note: `Dependency` objects still use `platform:` as this refers to the ecosystem, not the parser
+
+### 2. SBOM Files Now Return Single Parser Results
+
+**What Changed:**
+- SBOM files (CycloneDX, SPDX, dependencies.csv) are now parsed as standalone parser results
+- Previously, multi-parsers would distribute dependencies across multiple platform-specific results
+- Now, all dependencies from an SBOM file are returned in a single result with the SBOM parser name
+
+**Before (14.x):**
+```ruby
+# A cyclonedx.json file containing npm and maven dependencies would return:
+[
+  {
+    platform: "npm",
+    path: "cyclonedx.json",
+    dependencies: [<npm deps>],
+    ...
+  },
+  {
+    platform: "maven",
+    path: "cyclonedx.json", 
+    dependencies: [<maven deps>],
+    ...
+  }
+]
+```
+
+**After (15.0):**
+```ruby
+# The same cyclonedx.json file now returns a single result:
+[
+  {
+    parser: "cyclonedx",
+    path: "cyclonedx.json",
+    dependencies: [<all deps with their platform: field set>],
+    kind: "lockfile",
+    success: true
+  }
+]
+
+# Each dependency still knows its platform:
+dependencies.first.platform  # => "npm"
+dependencies.last.platform   # => "maven"
+```
+
+**Migration:**
+- Update code that expects SBOM files to return multiple platform-specific results
+- Instead of filtering results by `platform`, check `result[:parser]` for "cyclonedx", "spdx", or "dependenciescsv"
+- Group dependencies by their `Dependency#platform` field if you need platform-specific grouping
+
+**Affected Parsers:**
+- `cyclonedx` (cyclonedx.json, cyclonedx.xml, *.cdx.json, *.cdx.xml)
+- `spdx` (*.spdx, *.spdx.json)
+- `dependenciescsv` (dependencies.csv)
+
+### 3. SBOM Files Now Return ALL Dependencies Regardless of Platform
+
+**What Changed:**
+- CycloneDX and SPDX parsers now return ALL dependencies from SBOM files
+- Previously, only dependencies with PURL types mapped in `PURL_TYPE_MAPPING` were returned
+- Now, unmapped PURL types (e.g., `alpine`, `apk`, `deb`, `rpm`) are included with the PURL type used as the platform name
+
+**Before (14.x):**
+```ruby
+# An SBOM with npm, maven, and alpine packages would only return npm and maven
+result = Bibliothecary.analyse('cyclonedx.json')
+# => [{
+#   parser: "cyclonedx",
+#   dependencies: [
+#     { name: "express", platform: "npm", ... },      # included
+#     { name: "junit", platform: "maven", ... },      # included
+#     # alpine packages were silently filtered out
+#   ]
+# }]
+```
+
+**After (15.0):**
+```ruby
+# The same SBOM now returns ALL packages
+result = Bibliothecary.analyse('cyclonedx.json')
+# => [{
+#   parser: "cyclonedx",
+#   dependencies: [
+#     { name: "express", platform: "npm", ... },           # included (mapped)
+#     { name: "junit", platform: "maven", ... },           # included (mapped)
+#     { name: "alpine-base", platform: "alpine", ... },    # included (unmapped, uses PURL type)
+#     { name: "curl", platform: "apk", ... }               # included (unmapped, uses PURL type)
+#   ]
+# }]
+```
+
+**Mapped PURL Types (in PURL_TYPE_MAPPING):**
+- `golang` → `go`
+- `maven` → `maven`
+- `npm` → `npm`
+- `cargo` → `cargo`
+- `composer` → `packagist`
+- `conan` → `conan`
+- `conda` → `conda`
+- `cran` → `cran`
+- `gem` → `rubygems`
+- `nuget` → `nuget`
+- `pypi` → `pypi`
+- `vcpkg` → `vcpkg`
+
+**Unmapped PURL Types (now included as-is):**
+- `alpine`, `apk`, `deb`, `rpm`, `bitbucket`, `github`, `docker`, and any other PURL types
+
+**Migration:**
+- If your code filters or groups by platform, be aware that new platform values may appear
+- System package types (`alpine`, `apk`, `deb`, `rpm`) will now be included in results
+- Consider whether your application needs to handle these additional platform types
+- The behavior is now more comprehensive and accurate to what's actually in SBOM files
+
+### 4. API Method Renames
+
+**What Changed:**
+- Methods containing "package_manager" have been renamed to "parser"
+- Old methods now raise errors with upgrade instructions
+
+**Removed Methods:**
+
+| Old Method (14.x) | New Method (15.0) |
+|-------------------|-------------------|
+| `Bibliothecary.package_managers` | `Bibliothecary.parsers` |
+| `Bibliothecary.applicable_package_managers(info)` | `Bibliothecary.applicable_parsers(info)` |
+| `Runner#package_managers` | `Runner#parsers` |
+| `Runner#applicable_package_managers(info)` | `Runner#applicable_parsers(info)` |
+| `FileInfo#package_manager` | `FileInfo#parser` |
+| `RelatedFilesInfo#package_manager` | `RelatedFilesInfo#parser` |
+
+**Before (14.x):**
+```ruby
+Bibliothecary.package_managers
+# => [Bibliothecary::Parsers::NPM, Bibliothecary::Parsers::Rubygems, ...]
+
+info = Bibliothecary::FileInfo.new(...)
+parsers = Bibliothecary.applicable_package_managers(info)
+```
+
+**After (15.0):**
+```ruby
+Bibliothecary.parsers
+# => [Bibliothecary::Parsers::NPM, Bibliothecary::MultiParsers::CycloneDX, ...]
+
+info = Bibliothecary::FileInfo.new(...)
+parsers = Bibliothecary.applicable_parsers(info)
+```
+
+**Migration:**
+- Search and replace `package_managers` with `parsers` in your codebase
+- Search and replace `applicable_package_managers` with `applicable_parsers`
+- Update any references to `FileInfo#package_manager` to use `FileInfo#parser`
+
+### 4. MultiManifestFilter Removed
+
+**What Changed:**
+- The `Bibliothecary::Runner::MultiManifestFilter` class has been removed
+- Multi-parsers are now standalone parser classes and don't require special filtering
+
+**Before (14.x):**
+```ruby
+# MultiManifestFilter was used internally to handle SBOM files
+```
+
+**After (15.0):**
+```ruby
+# Multi-parsers (CycloneDX, SPDX, DependenciesCSV) are regular parser classes
+# They are included automatically in Bibliothecary.parsers
+```
+
+**Migration:**
+- Remove any direct references to `Bibliothecary::Runner::MultiManifestFilter`
+- The new behavior handles SBOM files transparently through the regular parser system
+
+### 5. Parser Mixins Moved
+
+**What Changed:**
+- `Bibliothecary::MultiParsers::JSONRuntime` moved to `Bibliothecary::ParserMixins::JSONRuntime`
+- `Bibliothecary::MultiParsers::BundlerLikeManifest` moved to `Bibliothecary::ParserMixins::BundlerLikeManifest`
+
+**Migration:**
+- Update any explicit references to these modules in your code
+- Most users won't be affected as these are internal implementation details
+
+### 6. MultiParsers Are Now Classes
+
+**What Changed:**
+- Multi-parsers (CycloneDX, SPDX, DependenciesCSV) are now classes instead of modules
+- They are no longer mixed into platform-specific parsers
+- They are standalone parsers included in `Bibliothecary.parsers`
+
+**Before (14.x):**
+```ruby
+# Multi-parsers were modules that extended individual parsers
+Bibliothecary::Parsers::NPM.ancestors
+# => includes Bibliothecary::MultiParsers::CycloneDX
+```
+
+**After (15.0):**
+```ruby
+# Multi-parsers are independent parser classes
+Bibliothecary.parsers
+# => [
+#   Bibliothecary::Parsers::NPM,
+#   Bibliothecary::Parsers::Maven,
+#   ...,
+#   Bibliothecary::MultiParsers::CycloneDX,
+#   Bibliothecary::MultiParsers::Spdx,
+#   Bibliothecary::MultiParsers::DependenciesCSV
+# ]
+
+# They have their own platform_name
+Bibliothecary::MultiParsers::CycloneDX.platform_name  # => "cyclonedx"
+```
+
+**Migration:**
+- Don't rely on multi-parser methods being available on platform-specific parsers
+- Treat SBOM parsers as independent parsers in your code

data/lib/bibliothecary/analyser/analysis.rb

@@ -43,9 +43,9 @@ module Bibliothecary
         parser_result = parse_file(info.relative_path, info.contents, options: options)
         parser_result = ParserResult.new(dependencies: []) if parser_result.nil? # work around any legacy parsers that return nil
 
-        Bibliothecary::Analyser.create_analysis(platform_name, info.relative_path, kind, parser_result)
+        Bibliothecary::Analyser.create_analysis(parser_name, info.relative_path, kind, parser_result)
       rescue Bibliothecary::FileParsingError => e
-        Bibliothecary::Analyser.create_error_analysis(platform_name, info.relative_path, kind, e.message, e.location)
+        Bibliothecary::Analyser.create_error_analysis(parser_name, info.relative_path, kind, e.message, e.location)
       end
       alias analyze_contents_from_info analyse_contents_from_info
 

data/lib/bibliothecary/analyser.rb

@@ -6,9 +6,9 @@ require_relative "analyser/analysis"
 
 module Bibliothecary
   module Analyser
-    def self.create_error_analysis(platform_name, relative_path, kind, message, location = nil)
+    def self.create_error_analysis(parser_name, relative_path, kind, message, location = nil)
       {
-        platform: platform_name,
+        parser: parser_name,
         path: relative_path,
         dependencies: nil,
         kind: kind,
@@ -18,9 +18,9 @@ module Bibliothecary
       }
     end
 
-    def self.create_analysis(platform_name, relative_path, kind, parser_result)
+    def self.create_analysis(parser_name, relative_path, kind, parser_result)
       {
-        platform: platform_name,
+        parser: parser_name,
         path: relative_path,
         project_name: parser_result.project_name,
         dependencies: parser_result.dependencies,
@@ -52,13 +52,17 @@ module Bibliothecary
 
     module ClassMethods
       def platform_name
-        @platform_name ||= name.to_s.split("::").last.downcase.freeze
+        parser_name
+      end
+
+      def parser_name
+        @parser_name ||= name.to_s.split("::").last.downcase.freeze
       end
 
       def map_dependencies(hash, key, type, source = nil)
         hash.fetch(key, []).map do |name, requirement|
           Dependency.new(
-            platform: platform_name,
+            platform: parser_name,
             name: name,
             requirement: requirement,
             type: type,
@@ -67,23 +71,23 @@ module Bibliothecary
         end
       end
 
-      # Add a MultiParser module to a Parser class. This extends the
-      # self.mapping method on the parser to include the multi parser's
-      # files to watch for, and it extends the Parser class with
-      # the multi parser for you.
-      #
-      # @param klass [Class] A Bibliothecary::MultiParsers class
-      def add_multi_parser(klass)
-        raise "No mapping found! You should place the add_multi_parser call below def self.mapping." unless respond_to?(:mapping)
+      # # Add a MultiParser module to a Parser class. This extends the
+      # # self.mapping method on the parser to include the multi parser's
+      # # files to watch for, and it extends the Parser class with
+      # # the multi parser for you.
+      # #
+      # # @param klass [Class] A Bibliothecary::MultiParsers class
+      # def add_multi_parser(klass)
+      #   raise "No mapping found! You should place the add_multi_parser call below def self.mapping." unless respond_to?(:mapping)
 
-        original_mapping = mapping
+      #   original_mapping = mapping
 
-        define_singleton_method(:mapping) do
-          original_mapping.merge(klass.mapping)
-        end
+      #   define_singleton_method(:mapping) do
+      #     original_mapping.merge(klass.mapping)
+      #   end
 
-        send(:extend, klass)
-      end
+      #   send(:extend, klass)
+      # end
     end
   end
 end

data/lib/bibliothecary/dependency.rb

@@ -5,10 +5,7 @@ module Bibliothecary
   #
   # @attr_reader [String] name The name of the package, e.g. "ansi-string-colors"
   # @attr_reader [String] requirement The version requirement of the release, e.g. "1.0.0" or "^1.0.0"
-  # @attr_reader [String] platform The platform of the package, e.g. "maven". This is optional because
-  #   it's implicit in most parser results, and the analyzer returns the platform name itself. One
-  #   exception are multi-parsers like DependenciesCSV, because they may return deps from multiple platforms.
-  #   Bibliothecary could start returning this field for *all* deps in future, and make it required. (default: nil)
+  # @attr_reader [String] platform The platform of the package, e.g. "maven".
   # @attr_reader [String] type The type or scope of dependency, e.g. "runtime" or "test". In some ecosystems a
   #   default may be set and in other ecosystems it may make sense to return nil when not found.
   # @attr_reader [Boolean] direct Is this dependency a direct dependency (vs transitive dependency)? (default: nil)

data/lib/bibliothecary/file_info.rb

@@ -7,7 +7,11 @@ module Bibliothecary
   # and package manager information if needed.
   class FileInfo
     attr_reader :folder_path, :relative_path, :full_path
-    attr_accessor :package_manager
+    attr_accessor :parser
+
+    def package_manager
+      raise "FileInfo#package_manager() has been removed in bibliothecary 15.0.0. Use parser() instead, which now includes MultiParsers."
+    end
 
     def contents
       @contents ||=
@@ -45,11 +49,11 @@ module Bibliothecary
 
       @contents = contents
 
-      @package_manager = nil
+      @parser = nil
     end
 
     def groupable?
-      @package_manager&.groupable?(self)
+      @parser&.groupable?(self)
     end
   end
 end

data/lib/bibliothecary/multi_parsers/cyclonedx.rb

@@ -12,17 +12,17 @@ Warning[:experimental] = true
 
 module Bibliothecary
   module MultiParsers
-    module CycloneDX
+    class CycloneDX
       include Bibliothecary::Analyser
-      include Bibliothecary::Analyser::TryCache
+      extend Bibliothecary::Analyser::TryCache
 
       NoComponents = Class.new(StandardError)
 
       class ManifestEntries
-        attr_reader :manifests
+        attr_reader :entries
 
         def initialize(parse_queue:)
-          @manifests = {}
+          @entries = Set.new
 
           # Instead of recursing, we'll work through a queue of components
           # to process, letting the different parser add components to the
@@ -31,14 +31,13 @@ module Bibliothecary
         end
 
         def add(purl, source = nil)
-          mapping = PurlUtil::PURL_TYPE_MAPPING[purl.type]
-          return unless mapping
+          # Use the mapped purl->bibliothecary platform, or else fall back to original platform itself.
+          mapping = PurlUtil::PURL_TYPE_MAPPING.fetch(purl.type, purl.type)
 
-          @manifests[mapping] ||= Set.new
-          @manifests[mapping] << Dependency.new(
+          @entries << Dependency.new(
             name: PurlUtil.full_name(purl),
             requirement: purl.version,
-            platform: mapping.to_s,
+            platform: mapping ? mapping.to_s : purl.type,
             type: "lockfile",
             source: source
           )
@@ -60,10 +59,6 @@ module Bibliothecary
             add(purl, source)
           end
         end
-
-        def [](key)
-          @manifests[key]&.to_a
-        end
       end
 
       def self.mapping
@@ -91,25 +86,31 @@ module Bibliothecary
         }
       end
 
-      def parse_cyclonedx_json(file_contents, options: {})
+      def self.platform_name
+        raise "CycloneDX is a multi-parser and does not have a platform name."
+      end
+
+      def self.parse_cyclonedx_json(file_contents, options: {})
         manifest = try_cache(options, options[:filename]) do
           JSON.parse(file_contents)
         end
 
         raise NoComponents unless manifest["components"]
 
-        entries = ManifestEntries.new(parse_queue: manifest["components"])
+        manifest_entries = ManifestEntries.new(
+          parse_queue: manifest["components"]
+        )
 
-        entries.parse!(options.fetch(:filename, nil)) do |component, parse_queue|
+        manifest_entries.parse!(options.fetch(:filename, nil)) do |component, parse_queue|
           parse_queue.concat(component["components"]) if component["components"]
 
           component["purl"]
         end
 
-        ParserResult.new(dependencies: entries[platform_name.to_sym] || [])
+        ParserResult.new(dependencies: manifest_entries.entries.to_a)
       end
 
-      def parse_cyclonedx_xml(file_contents, options: {})
+      def self.parse_cyclonedx_xml(file_contents, options: {})
         manifest = try_cache(options, options[:filename]) do
           Ox.parse(file_contents)
         end
@@ -121,9 +122,11 @@ module Bibliothecary
 
         raise NoComponents unless root.locate("components").first
 
-        entries = ManifestEntries.new(parse_queue: root.locate("components/*"))
+        manifest_entries = ManifestEntries.new(
+          parse_queue: root.locate("components/*")
+        )
 
-        entries.parse!(options.fetch(:filename, nil)) do |component, parse_queue|
+        manifest_entries.parse!(options.fetch(:filename, nil)) do |component, parse_queue|
           # #locate returns an empty array if nothing is found, so we can
           # always safely concatenate it to the parse queue.
           parse_queue.concat(component.locate("components/*"))
@@ -131,7 +134,7 @@ module Bibliothecary
           component.locate("purl").first&.text
         end
 
-        ParserResult.new(dependencies: entries[platform_name.to_sym] || [])
+        ParserResult.new(dependencies: manifest_entries.entries.to_a)
       end
     end
   end

data/lib/bibliothecary/multi_parsers/dependencies_csv.rb

@@ -4,9 +4,9 @@ require "csv"
 
 module Bibliothecary
   module MultiParsers
-    module DependenciesCSV
+    class DependenciesCSV
       include Bibliothecary::Analyser
-      include Bibliothecary::Analyser::TryCache
+      extend Bibliothecary::Analyser::TryCache
 
       def self.mapping
         {
@@ -18,6 +18,10 @@ module Bibliothecary
         }
       end
 
+      def self.platform_name
+        raise "DependenciesCSV is a multi-parser and does not have a platform name."
+      end
+
       # Processing a CSV file isn't as exact as using a real manifest file,
       # but you can get pretty close as long as the data you're importing
       # is simple.
@@ -132,7 +136,7 @@ module Bibliothecary
         end
       end
 
-      def parse_dependencies_csv(file_contents, options: {})
+      def self.parse_dependencies_csv(file_contents, options: {})
         csv_file = try_cache(options, options[:filename]) do
           raw_csv_file = CSVFile.new(file_contents)
           raw_csv_file.parse!
@@ -141,7 +145,6 @@ module Bibliothecary
 
         dependencies = csv_file
           .result
-          .find_all { |dependency| dependency[:platform] == platform_name.to_s }
           .map do |dep_kvs|
             Dependency.new(
               **dep_kvs, source: options.fetch(:filename, nil)