dependabot-common 0.335.0 → 0.337.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca29ec928a5e569aa377708755f29f998ca87ddb68ed2722a5171386427e3f87
-  data.tar.gz: 206f507ef450d40f3a002187a7890dc5b5abc88c7d8df5e53a87a27a14aa9f71
+  metadata.gz: 5b0ffe5707059285fd1f9a5ec262e5bb5ee208edbc66bf448bab3bafb1777e2f
+  data.tar.gz: 8822c407c862de5043ac786b628a8640e977a2a806f5abc5b16cd2aebbcba0d1
 SHA512:
-  metadata.gz: 3a3baf81472a1b7528fb6f95f9c5ed76f79186fd4aa442e073b2f0bc60e676186f592ab16a18f1f6bb747e652e522d0f1af2a7ac077a3dbce0d89001c001fc93
-  data.tar.gz: 26a4aaa04570ec094267b7e2739a394fe4d279807ad03453ac6cec8c766d18cb3b13e73665923cf8e58ca64ab6fad7b8b8a20656a0feaa93b80bcdaed6119503
+  metadata.gz: 101633a5e8ee69f8b9da421b78ef56d080fa128574038f9ead3e66611e9411e12ae9e12ca71e0511a7be2ece9a586a061733aec9188b723acae48bef0c3dc226
+  data.tar.gz: be0d92563c07aa54897bef06002c76e4c8ee262a48e6dde7298afb7aace9b0a14854600e99486d47d39eb3eb0d06b110c57f408cc9e662ae0b68f92a588289c6

data/lib/dependabot/dependency_graphers/README.md

@@ -2,7 +2,7 @@
 
 Dependency graphers are used to convert a set of parsed dependencies into a data structure we can use to output the dependency graph of a project in a generic data structure based on GitHub's [Dependency submission API](https://docs.github.com/en/rest/dependency-graph/dependency-submission).
 
-We will expect each language Dependabot supports to implement a `Dependabot::DependencyGraphers` class in future, but for now any modules that do not implement a specific class fail over to a 'best effort' generic implementation that works in most cases.
+We will expect each language Dependabot supports to implement a `Dependabot::DependencyGraphers` class in future, but for now any modules that do not implement a specific class fail over to a 'best effort' generic implementation.
 
 ## Public API
 
@@ -39,9 +39,9 @@ An example of a `.resolved_dependencies` hash for a Bundler project:
 }
 ```
 
-## Writing a file fetcher for a new language
+## Writing a dependency grapher for a new language
 
-All new file fetchers should inherit from `Dependabot::DependencyGraphers::Base` and
+All new dependency graphers should inherit from `Dependabot::DependencyGraphers::Base` and
 implement the following methods:
 
 | Method                           | Description                                                                                   |
@@ -52,3 +52,10 @@ implement the following methods:
 
 > [!WARNING]
 > While PURLs are preferred in all languages for `.fetch_subdependencies`, for languages where multiple versions of a single dependency are permitted they _must_ be provided to be precise.
+
+## Overriding file parser behaviour
+
+In most cases, an ecosystem's file parser should provide us the dependency data we need to build the graph, but in some cases we may need to tweak this behaviour or experiment with alternative parsing strategies.
+
+The `Dependabot::DependencyGraphers::Base` class provides the `prepare!` method as the hook that is called to generate the dependency list - if required this method can be redefined for a specific ecosystem to make
+additional or alternative calls.

data/lib/dependabot/dependency_graphers/base.rb

@@ -5,6 +5,21 @@ require "sorbet-runtime"
 
 module Dependabot
   module DependencyGraphers
+    # This is a small value class that specifies the information we expect to be returned for each
+    # dependency strictly.
+    class ResolvedDependency < T::ImmutableStruct
+      # A valid purl for the dependency, e.g. pkg:/npm/tunnel@0.0.6
+      const :package_url, String
+      # Is this a direct dependency?
+      const :direct, T::Boolean
+      # Is this a runtime dependency?
+      const :runtime, T::Boolean
+      # A list of packages this dependency itself depends on if direct is false. Note that:
+      # - a valid purl for the parent dependency is preferable
+      # - the package name is acceptable **unless the ecosystem allows multiple versions of a package to be used**
+      const :dependencies, T::Array[String]
+    end
+
     class Base
       extend T::Sig
       extend T::Helpers
@@ -13,23 +28,16 @@ module Dependabot
 
       abstract!
 
-      # TODO(brrygrdn): Inject the Dependency parser instead of pre-parsed `dependencies`
-      #
-      # Semantically it makes sense for the grapher to wrap the parser as a higher order function, but we already know
-      # that some package managers will require extra native commands before, after or during the parse - in extreme
-      # cases it may make sense to use an alternative parser that is more optimal.
-      #
-      # By injecting the parser, this allows the ecosystem to encapsulate the package manager specifics without the
-      # executor needing to manage parser modes / feature flags.
+      sig { returns(T::Boolean) }
+      attr_reader :prepared
+
       sig do
-        params(
-          dependency_files: T::Array[Dependabot::DependencyFile],
-          dependencies: T::Array[Dependabot::Dependency]
-        ).void
+        params(file_parser: Dependabot::FileParsers::Base).void
       end
-      def initialize(dependency_files:, dependencies:)
-        @dependency_files = dependency_files
-        @dependencies = dependencies
+      def initialize(file_parser:)
+        @file_parser = file_parser
+        @dependencies = T.let([], T::Array[Dependabot::Dependency])
+        @prepared = T.let(false, T::Boolean)
       end
 
       # Each grapher must implement a heuristic to determine which dependency file should be used as the owner
@@ -40,21 +48,38 @@ module Dependabot
       sig { abstract.returns(Dependabot::DependencyFile) }
       def relevant_dependency_file; end
 
-      sig { returns(T::Hash[Symbol, T.untyped]) }
+      # A grapher may override this method if it needs to perform extra steps around the normal file parser for
+      # the ecosystem.
+      sig { void }
+      def prepare!
+        @dependencies = @file_parser.parse
+        @prepared = true
+      end
+
+      sig { returns(T::Hash[String, ResolvedDependency]) }
       def resolved_dependencies
+        prepare! unless prepared
+
         @dependencies.each_with_object({}) do |dep, resolved|
-          resolved[dep.name] = {
+          resolved[dep.name] = ResolvedDependency.new(
             package_url: build_purl(dep),
-            relationship: relationship_for(dep),
-            scope: scope_for(dep),
-            dependencies: fetch_subdependencies(dep),
-            metadata: {}
-          }
+            direct: dep.top_level?,
+            runtime: dep.production?,
+            dependencies: fetch_subdependencies(dep)
+          )
         end
       end
 
       private
 
+      sig { returns(Dependabot::FileParsers::Base) }
+      attr_reader :file_parser
+
+      sig { returns(T::Array[Dependabot::DependencyFile]) }
+      def dependency_files
+        file_parser.dependency_files
+      end
+
       # Each grapher is expected to implement a method to look up the parents of a given dependency.
       #
       # The strategy that should be used is highly dependent on the ecosystem, in some cases the parser
@@ -95,24 +120,6 @@ module Dependabot
           version: purl_version_for(dependency)
         )
       end
-
-      sig { params(dep: Dependabot::Dependency).returns(String) }
-      def relationship_for(dep)
-        if dep.top_level?
-          "direct"
-        else
-          "indirect"
-        end
-      end
-
-      sig { params(dependency: Dependabot::Dependency).returns(String) }
-      def scope_for(dependency)
-        if dependency.production?
-          "runtime"
-        else
-          "development"
-        end
-      end
     end
   end
 end

data/lib/dependabot/dependency_graphers/generic.rb

@@ -25,7 +25,7 @@ module Dependabot
 
       sig { returns(T::Array[Dependabot::DependencyFile]) }
       def filtered_dependency_files
-        @dependency_files.reject { |f| f.support_file? || f.vendored_file? }
+        dependency_files.reject { |f| f.support_file? || f.vendored_file? }
       end
 
       # Our generic strategy is to check if the parser has attached a `depends_on` key to the Dependency's

data/lib/dependabot.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Dependabot
-  VERSION = "0.335.0"
+  VERSION = "0.337.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dependabot-common
 version: !ruby/object:Gem::Version
-  version: 0.335.0
+  version: 0.337.0
 platform: ruby
 authors:
 - Dependabot
@@ -630,7 +630,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dependabot/dependabot-core/issues
-  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.335.0
+  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.337.0
 rdoc_options: []
 require_paths:
 - lib