dependabot-apm 0.400.0 → 0.402.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 332d6b2c76b5d6ae722f9793731e25984be0835ca971d986f9316b594982c7b2
-  data.tar.gz: b2dea7a2bb867c041702a05754820c048aaa2f6a336cad5cc4edc777dcecc6d0
+  metadata.gz: 6ba8a0fe03d88d3c9a98aba6d2f8fd7c4d235bded82fd3e158a4dac7936def80
+  data.tar.gz: 19c19651c79805c932dc12b4e84b9b579bf8db15f6c131a0e0cd82947cefc1b2
 SHA512:
-  metadata.gz: e4cedd6bf6ff0eba62c8689dbf5793bba8684e4dafde2ad12873adcff61ac60f06a4c9319af598a942547a84bd2c199193434d29a550c14a518d3534c3667abb
-  data.tar.gz: 60922c751e3a27e4e1a7302f799603efd4ac732f67aa02c194e81563e1621972c9b93a0befe45566801ba16ccf1d2555babec7f0277bbde9f816fdbddba0b605
+  metadata.gz: 71dc26756e87e1412601d85d0ae7f72f8849289194abc3ce0e29211000ccd991439ffe846ac60d8a4d1432343ca6e8072732ed1ea919bd83fc60c81e67f6edd9
+  data.tar.gz: d15140aaef4a1e2e74eb510d8ab4f25774d36abaf8fffa428af782a46edf782784c1c3742771c0f648d15159d98b5b519c458f6fb4ed54c5ecdc46c64f35f7d7

data/lib/dependabot/apm/file_fetcher.rb

@@ -1,4 +1,4 @@
-# typed: strict
+# typed: strong
 # frozen_string_literal: true
 
 require "sorbet-runtime"
@@ -78,7 +78,7 @@ module Dependabot
         return @lockfile if defined?(@lockfile)
 
         @lockfile = T.let(
-          fetch_file_if_present(LOCKFILE_FILENAME)&.tap { |f| f.support_file = true },
+          fetch_file_if_present(LOCKFILE_FILENAME),
           T.nilable(Dependabot::DependencyFile)
         )
       end

data/lib/dependabot/apm/file_parser.rb

@@ -8,6 +8,7 @@ require "dependabot/dependency"
 require "dependabot/errors"
 require "dependabot/file_parsers"
 require "dependabot/file_parsers/base"
+require "dependabot/apm/lockfile"
 require "dependabot/apm/package_manager"
 require "dependabot/apm/package_specifier"
 require "dependabot/apm/version"
@@ -50,6 +51,23 @@ module Dependabot
         T::Array[Integer]
       )
 
+      PIN_TAG = "tag"
+      PIN_SHA = "sha"
+      PIN_BRANCH = "branch"
+      PIN_PRECEDENCE = T.let([PIN_TAG, PIN_SHA, PIN_BRANCH].freeze, T::Array[String])
+
+      # A manifest scalar entry and the dependency groups its block confers.
+      class Declaration < T::Struct
+        const :raw_entry, String
+        const :span, String
+        const :groups, T::Array[String]
+      end
+
+      class PinnedEntry < T::Struct
+        const :pin_type, String
+        const :dependency, Dependabot::Dependency
+      end
+
       sig { override.returns(T::Array[Dependabot::Dependency]) }
       def parse
         # Non-GitHub git hosts (e.g. GitLab) are case-sensitive, so use a
@@ -57,9 +75,9 @@ module Dependabot
         # case distinct. PackageSpecifier canonicalises GitHub owner/repo casing
         # itself, so case-insensitive GitHub paths still deduplicate correctly.
         dependency_set = DependencySet.new(case_sensitive: true)
-        # Reading the host first also validates the manifest and raises
+        # Reading the manifest first validates it and raises
         # DependencyFileNotParseable before we walk it for source positions.
-        host = default_host
+        parsed_manifest
 
         # When the manifest configures a default registry, APM routes plain
         # string-shorthand entries through that registry rather than Git. We
@@ -69,28 +87,27 @@ module Dependabot
         # never registry-routed and are still updated.
         skip_shorthand = default_registry_configured?
 
-        DEPENDENCY_BLOCKS.each do |block_key, groups|
-          apm_entries_in(block_key).each do |entry, declaration_span|
+        pinned_entries = DEPENDENCY_BLOCKS.flat_map do |block_key, groups|
+          apm_entries_in(block_key).filter_map do |entry, declaration_span|
             # v1 supports the string shorthand form (e.g. "owner/repo#v1.0.0").
             # Object entries (git:/registry:/id:/path:) and `mcp` entries are
             # not yet supported and are skipped by only reading scalar entries.
-            spec = PackageSpecifier.parse(entry, default_host: host)
+            # Shorthands resolve against github.com: APM reads no manifest-level
+            # default host (only the GITHUB_HOST env var, which Dependabot does
+            # not set for the CLI), so `apm lock` resolves them there too.
+            spec = PackageSpecifier.parse(entry)
             next unless spec # local paths and unparseable specs are skipped
             next if skip_shorthand && PackageSpecifier.shorthand?(entry)
 
-            # Only entries pinned to a semver tag are updatable. Branch-, SHA-
-            # and unpinned entries are resolved by APM's own lockfile, so we
-            # leave them out of the dependency set entirely rather than have the
-            # update checker reach out to the git remote for something we will
-            # never bump. The tag may be plain (`v1.2.0`) or package-scoped
-            # (`review--v1.2.0`), so resolve it through the shared APM extractor.
-            ref = spec.ref
-            next unless ref && Version.semver_from_ref(ref, dependency_name: spec.name)
-
-            dependency_set << build_dependency(spec, entry, declaration_span, groups)
+            pinned_entry(spec, entry, declaration_span, groups)
           end
         end
 
+        preferred_pins = preferred_pin_types(pinned_entries)
+        pinned_entries.each do |entry|
+          dependency_set << entry.dependency if preferred_pins[entry.dependency.name] == entry.pin_type
+        end
+
         dependency_set.dependencies
       end
 
@@ -107,21 +124,97 @@ module Dependabot
 
       private
 
+      # Classifies a pinned manifest entry and builds its dependency, or returns
+      # nil for entries Dependabot doesn't update:
+      #
+      #   * tag pins (`v1.2.0`, or package-scoped `review--v1.2.0`) are versioned
+      #     by the SemVer core of the tag;
+      #   * full 40-character SHA pins are versioned by the SHA, matching the
+      #     pins `apm update` moves between annotated release tags;
+      #   * any other ref is a branch (or similar moving ref) and is versioned by
+      #     the commit the lockfile resolved it to, so it is only updatable when
+      #     the lockfile records a commit for that ref.
+      #
+      # Unpinned entries and abbreviated SHAs are skipped, as APM leaves those
+      # unchanged too.
       sig do
         params(
           spec: Dependabot::Apm::PackageSpecifier,
           raw_entry: String,
           declaration_span: String,
           groups: T::Array[String]
-        ).returns(Dependabot::Dependency)
+        ).returns(T.nilable(PinnedEntry))
       end
-      def build_dependency(spec, raw_entry, declaration_span, groups)
+      def pinned_entry(spec, raw_entry, declaration_span, groups)
         ref = spec.ref
-        # The dependency version is the SemVer core of the pinned tag, even when
-        # the tag is package-scoped (`review--v1.2.0` -> `1.2.0`); the manifest
-        # requirement below keeps the original ref so the updater rewrites it.
-        core = Version.semver_from_ref(ref, dependency_name: spec.name) if ref
-        version = Version.new(core).to_s if core
+        return if ref.nil? || ref.empty?
+
+        declaration = Declaration.new(raw_entry: raw_entry, span: declaration_span, groups: groups)
+        tag_version = Version.semver_from_ref(ref, dependency_name: spec.name)
+        if tag_version
+          return PinnedEntry.new(
+            pin_type: PIN_TAG,
+            dependency: build_dependency(spec, declaration, version: Version.new(tag_version).to_s)
+          )
+        end
+        if ref.match?(PackageSpecifier::FULL_SHA_REGEX)
+          return PinnedEntry.new(
+            pin_type: PIN_SHA,
+            dependency: build_dependency(spec, declaration, version: ref.downcase)
+          )
+        end
+        return if ref.match?(PackageSpecifier::ABBREVIATED_SHA_REGEX)
+
+        branch_pinned_entry(spec, declaration, ref)
+      end
+
+      sig do
+        params(spec: Dependabot::Apm::PackageSpecifier, declaration: Declaration, branch: String)
+          .returns(T.nilable(PinnedEntry))
+      end
+      def branch_pinned_entry(spec, declaration, branch)
+        lockfile_key = spec.lockfile_key
+        commit = parsed_lockfile&.resolved_commit(lockfile_key, ref: branch)
+        return unless commit
+
+        PinnedEntry.new(
+          pin_type: PIN_BRANCH,
+          dependency: build_dependency(spec, declaration, version: commit, branch: branch, lockfile_key: lockfile_key)
+        )
+      end
+
+      # DependencySet merges every declaration of a package into one dependency,
+      # but a dependency can only carry one kind of version (a tag version or a
+      # commit). When a package is declared with several kinds of pin, only the
+      # declarations of the most specific kind (tag, then SHA, then branch) are
+      # updated; the others are left as they are.
+      sig { params(entries: T::Array[PinnedEntry]).returns(T::Hash[String, String]) }
+      def preferred_pin_types(entries)
+        entries.group_by { |entry| entry.dependency.name }.transform_values do |pins|
+          T.must(pins.map(&:pin_type).min_by { |pin_type| T.must(PIN_PRECEDENCE.index(pin_type)) })
+        end
+      end
+
+      sig do
+        params(
+          spec: Dependabot::Apm::PackageSpecifier,
+          declaration: Declaration,
+          version: String,
+          branch: T.nilable(String),
+          lockfile_key: T.nilable(String)
+        ).returns(Dependabot::Dependency)
+      end
+      def build_dependency(spec, declaration, version:, branch: nil, lockfile_key: nil)
+        # `declaration_span` locates the exact manifest scalar (see
+        # `encode_span`) so the file updater rewrites only that occurrence,
+        # never an identical string elsewhere in the file. Branch pins also
+        # record their lockfile identity so the lockfile updater can move the
+        # matching lock entry to the branch's new head commit.
+        metadata = T.let(
+          { declaration_string: declaration.raw_entry, declaration_span: declaration.span },
+          T::Hash[Symbol, String]
+        )
+        metadata[:lockfile_key] = lockfile_key if lockfile_key
 
         Dependency.new(
           name: spec.name,
@@ -130,20 +223,14 @@ module Dependabot
           requirements: [{
             requirement: nil,
             file: manifest_file.name,
-            groups: groups,
+            groups: declaration.groups,
             source: {
               type: "git",
               url: spec.git_url,
-              ref: ref,
-              branch: nil
+              ref: spec.ref,
+              branch: branch
             },
-            # `declaration_span` locates the exact manifest scalar (see
-            # `encode_span`) so the file updater rewrites only that occurrence,
-            # never an identical string elsewhere in the file.
-            metadata: {
-              declaration_string: raw_entry,
-              declaration_span: declaration_span
-            }
+            metadata: metadata
           }]
         )
       end
@@ -232,12 +319,6 @@ module Dependabot
         )
       end
 
-      sig { returns(String) }
-      def default_host
-        host = parsed_manifest["default_host"]
-        host.is_a?(String) && !host.empty? ? host : PackageSpecifier::DEFAULT_HOST
-      end
-
       # APM routes string-shorthand dependencies through a configured default
       # registry instead of Git. Only the project-level `registries.default`
       # selector (a string naming a configured entry) is visible here; a user's
@@ -286,6 +367,14 @@ module Dependabot
         )
       end
 
+      sig { returns(T.nilable(Dependabot::Apm::Lockfile)) }
+      def parsed_lockfile
+        return @parsed_lockfile if defined?(@parsed_lockfile)
+
+        file = lockfile
+        @parsed_lockfile = T.let(file && Lockfile.new(file), T.nilable(Dependabot::Apm::Lockfile))
+      end
+
       sig { override.void }
       def check_required_files
         return if get_original_file(MANIFEST_FILENAME)

data/lib/dependabot/apm/file_updater/lockfile_updater.rb

@@ -0,0 +1,175 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "fileutils"
+require "sorbet-runtime"
+
+require "dependabot/errors"
+require "dependabot/shared_helpers"
+require "dependabot/apm/file_updater"
+require "dependabot/apm/lockfile"
+require "dependabot/apm/native_helpers"
+
+module Dependabot
+  module Apm
+    class FileUpdater < Dependabot::FileUpdaters::Base
+      # Regenerates `apm.lock.yaml` with `apm lock`, which resolves the updated
+      # manifest without deploying any package files. APM only re-resolves the
+      # entries whose manifest ref changed, keeping every other entry on its
+      # locked commit, so tag and SHA updates are picked up from the manifest.
+      # A branch pin's ref doesn't change, so its lock entry is first moved to
+      # the branch's new head commit for APM to verify and re-hash.
+      class LockfileUpdater
+        extend T::Sig
+
+        APM_MODULES_DIRECTORY = "apm_modules"
+
+        AUTHENTICATION_FAILED_REGEX = /Authentication failed for '(?<url>[^']+)'/
+        REPOSITORY_NOT_FOUND_REGEX = /repository '(?<url>[^']+)' not found/i
+        # APM replaces git's error with its own when a clone is rejected or the
+        # repository is missing, e.g. "Failed to clone repository x/y.
+        # Authentication failed for clone on github.com."
+        APM_AUTHENTICATION_FAILED_REGEX = /
+          Failed\sto\sclone\srepository\s(?<repo>[^\s:]+?)\.\s
+          Authentication\sfailed\sfor\s[^\n]*?\son\s(?<host>\S+?)\.(?=\s|\z)
+        /x
+        FAILURE_PREFIX = /Failed\sto\sdownload\sdependency\s|Failed\sto\sresolve\stransitive\sdep\s/
+        # One failed package: its name (with an optional transitive `(via …)`
+        # chain) and the diagnostic up to the next failure in APM's output.
+        PACKAGE_FAILURE_REGEX = /
+          (?:#{FAILURE_PREFIX})(?<name>\S+?)(?:\s\(via\s[^)]*\))?:\s
+          (?<detail>.*?)(?=\n\s*\+-\s|#{FAILURE_PREFIX}|\z)
+        /mx
+        # Diagnostics that show a ref is missing. APM's own "Could not resolve
+        # commit/reference" wrapper is deliberately not matched: it wraps any
+        # failure, including network errors, so only the detail it carries
+        # (APM's or git's) says whether the ref exists.
+        MISSING_REFERENCE_REGEX = /
+          Remote\sbranch\s\S+\snot\sfound|
+          Reference\s'[^']+'\snot\sfound|
+          Needed\sa\ssingle\srevision|
+          unable\sto\sread\stree|
+          did\snot\smatch\sany\sfile\(s\)\sknown\sto\sgit|
+          reference\sis\snot\sa\stree
+        /x
+
+        sig do
+          params(
+            dependencies: T::Array[Dependabot::Dependency],
+            lockfile: Dependabot::DependencyFile,
+            manifest_content: String,
+            credentials: T::Array[Dependabot::Credential],
+            repo_contents_path: T.nilable(String)
+          ).void
+        end
+        def initialize(dependencies:, lockfile:, manifest_content:, credentials:, repo_contents_path:)
+          @dependencies = dependencies
+          @lockfile = lockfile
+          @manifest_content = manifest_content
+          @credentials = credentials
+          @repo_contents_path = repo_contents_path
+        end
+
+        sig { returns(String) }
+        def updated_lockfile_content
+          SharedHelpers.in_a_temporary_repo_directory(lockfile.directory, repo_contents_path) do
+            # `apm lock` downloads packages into apm_modules/ and resolves
+            # transitive dependencies from what is already there. The git reset
+            # between updates doesn't remove that ignored directory, so clear it
+            # to keep one update's packages from leaking into the next.
+            FileUtils.rm_rf(APM_MODULES_DIRECTORY)
+            File.write(FileUpdater::MANIFEST_FILENAME, manifest_content)
+            File.write(FileUpdater::LOCKFILE_FILENAME, prepared_lockfile_content)
+
+            SharedHelpers.with_git_configured(credentials: credentials) do
+              NativeHelpers.run_apm_command("lock")
+            end
+
+            File.read(FileUpdater::LOCKFILE_FILENAME)
+          ensure
+            FileUtils.rm_rf(APM_MODULES_DIRECTORY)
+          end
+        rescue SharedHelpers::HelperSubprocessFailed => e
+          handle_apm_lock_error(e)
+        end
+
+        private
+
+        sig { returns(T::Array[Dependabot::Dependency]) }
+        attr_reader :dependencies
+
+        sig { returns(Dependabot::DependencyFile) }
+        attr_reader :lockfile
+
+        sig { returns(String) }
+        attr_reader :manifest_content
+
+        sig { returns(T::Array[Dependabot::Credential]) }
+        attr_reader :credentials
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :repo_contents_path
+
+        sig { returns(String) }
+        def prepared_lockfile_content
+          branch_updates = updated_branch_pins
+          return T.must(lockfile.content) if branch_updates.empty?
+
+          parsed_lockfile = Lockfile.new(lockfile)
+          branch_updates.each { |key, commit| parsed_lockfile.pin_commit(key, commit) }
+          parsed_lockfile.to_yaml
+        end
+
+        # The new commit of each updated branch pin, keyed by its lockfile entry.
+        sig { returns(T::Hash[String, String]) }
+        def updated_branch_pins
+          dependencies.each_with_object({}) do |dependency, pins|
+            new_commit = dependency.version
+            next if new_commit.nil? || new_commit == dependency.previous_version
+
+            dependency.requirements.each do |requirement|
+              key = requirement.metadata_string("lockfile_key")
+              pins[key] = new_commit if key && requirement.source_string("branch")
+            end
+          end
+        end
+
+        sig { params(error: SharedHelpers::HelperSubprocessFailed).returns(T.noreturn) }
+        def handle_apm_lock_error(error)
+          message = error.message
+
+          unreachable_url = unreachable_repository_url(message)
+          raise Dependabot::GitDependenciesNotReachable, unreachable_url if unreachable_url
+
+          missing_reference = package_with_missing_reference(message)
+          raise Dependabot::GitDependencyReferenceNotFound, missing_reference if missing_reference
+
+          raise Dependabot::DependencyFileNotResolvable, message
+        end
+
+        sig { params(message: String).returns(T.nilable(String)) }
+        def unreachable_repository_url(message)
+          git_url = message.match(AUTHENTICATION_FAILED_REGEX)&.[](:url) ||
+                    message.match(REPOSITORY_NOT_FOUND_REGEX)&.[](:url)
+          return git_url if git_url
+
+          apm_failure = message.match(APM_AUTHENTICATION_FAILED_REGEX)
+          "https://#{apm_failure[:host]}/#{apm_failure[:repo]}" if apm_failure
+        end
+
+        # Checks each failed package's own diagnostic, so a missing ref is
+        # attributed to the package it belongs to rather than an earlier failure.
+        sig { params(message: String).returns(T.nilable(String)) }
+        def package_with_missing_reference(message)
+          position = 0
+          while (failure = PACKAGE_FAILURE_REGEX.match(message, position))
+            return failure[:name] if failure[:detail].to_s.match?(MISSING_REFERENCE_REGEX)
+
+            position = failure.end(0)
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/dependabot/apm/file_updater.rb

@@ -13,6 +13,13 @@ module Dependabot
       extend T::Sig
 
       MANIFEST_FILENAME = "apm.yml"
+      LOCKFILE_FILENAME = "apm.lock.yaml"
+
+      # What may follow a SHA pin on its line for `apm update`'s `# <tag>`
+      # comment to be written: nothing but whitespace or an existing comment.
+      LINE_REMAINDER_REGEX = /\A[ \t]*(?:#[^\r\n]*)?(?=\r?\n|\z)/
+
+      require_relative "file_updater/lockfile_updater"
 
       # A single ref-bump edit, located by an absolute [start_offset, end_offset)
       # character range in the original manifest content.
@@ -24,7 +31,7 @@ module Dependabot
 
       sig { returns(T::Array[Regexp]) }
       def self.updated_files_regex
-        [/^apm\.yml$/]
+        [/^apm\.yml$/, /^apm\.lock\.yaml$/]
       end
 
       sig { override.returns(T::Array[Dependabot::DependencyFile]) }
@@ -35,6 +42,9 @@ module Dependabot
           updated_file(file: file, content: updated_manifest_content(file))
         end
 
+        updated_lockfile = updated_lockfile(updated_files)
+        updated_files << updated_lockfile if updated_lockfile
+
         raise "No files changed!" if updated_files.none?
 
         updated_files
@@ -59,6 +69,31 @@ module Dependabot
         dependencies.any? { |dep| requirement_changed?(file, dep) }
       end
 
+      # Regenerates the lockfile against the updated manifest. A branch pin
+      # update changes only the lockfile, as the manifest still names the branch.
+      # The lockfile is only ever updated, never created.
+      sig do
+        params(updated_manifests: T::Array[Dependabot::DependencyFile])
+          .returns(T.nilable(Dependabot::DependencyFile))
+      end
+      def updated_lockfile(updated_manifests)
+        lockfile = get_original_file(LOCKFILE_FILENAME)
+        manifest = get_original_file(MANIFEST_FILENAME)
+        return unless lockfile && manifest
+
+        manifest_content = updated_manifests.find { |f| f.name == manifest.name }&.content || manifest.content
+        content = LockfileUpdater.new(
+          dependencies: dependencies,
+          lockfile: lockfile,
+          manifest_content: T.must(manifest_content),
+          credentials: credentials,
+          repo_contents_path: repo_contents_path
+        ).updated_lockfile_content
+        return if content == lockfile.content
+
+        updated_file(file: lockfile, content: content)
+      end
+
       sig { params(file: Dependabot::DependencyFile).returns(String) }
       def updated_manifest_content(file)
         original_content = T.must(file.content)
@@ -125,11 +160,32 @@ module Dependabot
         return unless original.include?(declaration)
 
         new_declaration = declaration.sub(ref_at_end, "##{new_ref}\\1")
-        Substitution.new(
+        substitution = Substitution.new(
           start_offset: start_offset,
           end_offset: end_offset,
           text: original.sub(declaration, new_declaration)
         )
+        with_release_tag_comment(content, substitution, new_req.metadata_string("release_tag"))
+      end
+
+      # Like `apm update`, annotates a bumped SHA pin with the release it now
+      # points at, replacing any comment already on the line. The comment is
+      # only written when nothing but whitespace or a comment follows the entry
+      # on its line, so entries in a flow sequence are left uncommented.
+      sig do
+        params(content: String, substitution: Substitution, release_tag: T.nilable(String)).returns(Substitution)
+      end
+      def with_release_tag_comment(content, substitution, release_tag)
+        return substitution unless release_tag
+
+        line_remainder = content[substitution.end_offset..]&.match(LINE_REMAINDER_REGEX)
+        return substitution unless line_remainder
+
+        Substitution.new(
+          start_offset: substitution.start_offset,
+          end_offset: substitution.end_offset + line_remainder[0].to_s.length,
+          text: "#{substitution.text} # #{release_tag}"
+        )
       end
 
       # Applies the substitutions from the end of the file backwards. Rewriting in

data/lib/dependabot/apm/git_commit_checker.rb

@@ -49,8 +49,63 @@ module Dependabot
         to_local_tag(max_version_tag)
       end
 
+      # The release a commit-SHA pin should move to, following `apm update`:
+      # the highest non-prerelease version tag in any of APM's tag forms
+      # (plain or package-scoped), considering only annotated tags. Lightweight
+      # tags and branches are never used, since they are not deliberate
+      # releases. Ignore conditions and cooldown apply as for tag pins.
+      #
+      # APM moves a SHA pin to that release even when the pinned commit is
+      # newer. When the pinned commit is itself a tagged release, Dependabot
+      # additionally requires a strictly higher version so it never proposes a
+      # downgrade.
+      sig do
+        params(cooldown_options: T.nilable(Dependabot::Package::ReleaseCooldownOptions))
+          .returns(T.nilable(Dependabot::GitTagDetails))
+      end
+      def latest_annotated_release_tag(cooldown_options = nil)
+        candidates = allowed_versions(local_tags, filter_by_prefix: false).select { |tag| annotated_release?(tag) }
+        pinned_version = current_version
+        candidates = candidates.select { |tag| version_from_tag(tag) > pinned_version } if pinned_version
+
+        filtered = apply_cooldown(candidates, cooldown_options)
+        return if filtered.nil?
+
+        max_local_tag(filtered)
+      end
+
+      # A SHA pin carries no version of its own, so the inherited lookup (which
+      # reads `dependency.version`) yields nil and cooldown would fall back to
+      # `default_days` for every candidate. When the pinned commit is a tagged
+      # release, use that version so SemVer-specific cooldown days apply.
+      sig { override.returns(T.nilable(Gem::Version)) }
+      def current_version
+        super || pinned_commit_version
+      end
+
       private
 
+      # An annotated tag is advertised as a tag object whose peeled (`^{}`)
+      # commit differs from it; a lightweight tag points at the commit directly.
+      sig { params(tag: Dependabot::GitRef).returns(T::Boolean) }
+      def annotated_release?(tag)
+        return false if tag.ref_sha.nil? || tag.ref_sha == tag.commit_sha
+
+        !version_from_tag(tag).prerelease?
+      end
+
+      # The highest version tagged on the pinned commit, if any.
+      sig { returns(T.nilable(Gem::Version)) }
+      def pinned_commit_version
+        pinned_sha = ref&.downcase
+        return unless pinned_sha
+
+        local_tags
+          .select { |tag| tag.commit_sha == pinned_sha && version_tag?(tag.name) }
+          .map { |tag| version_from_tag(tag) }
+          .max
+      end
+
       # Recognise a tag as a version only when it is a valid APM SemVer ref
       # (optionally package-scoped), so non-SemVer tags (e.g. `v1.2.3.4`) are
       # dropped before they can raise an ArgumentError, while build-metadata

data/lib/dependabot/apm/lockfile.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "yaml"
+
+require "dependabot/dependency_file"
+require "dependabot/errors"
+require "dependabot/apm/package_specifier"
+
+module Dependabot
+  module Apm
+    # A parsed `apm.lock.yaml`, with its `dependencies` entries addressable by
+    # APM's package identity (see PackageSpecifier#lockfile_key).
+    class Lockfile
+      extend T::Sig
+
+      sig { params(file: Dependabot::DependencyFile).void }
+      def initialize(file)
+        @document = T.let(parse(file), T::Hash[Object, Object])
+      end
+
+      # The commit the lockfile pins for `key`, provided it was resolved from
+      # `ref`. A lock entry resolved from a different ref is stale (APM
+      # re-resolves it on the next run), so it is not reported as the
+      # dependency's current commit.
+      sig { params(key: String, ref: String).returns(T.nilable(String)) }
+      def resolved_commit(key, ref:)
+        entry = entry_for(key)
+        return unless entry && entry["resolved_ref"] == ref
+
+        commit = entry["resolved_commit"]
+        commit.is_a?(String) && !commit.empty? ? commit : nil
+      end
+
+      # Moves the entry for `key` to `commit`. Its `content_hash` describes the
+      # previous commit's contents, and APM fails a hash mismatch as a potential
+      # supply-chain attack, so it is dropped for APM to recompute. The rest of
+      # the entry (e.g. `deployed_files`) is kept.
+      sig { params(key: String, commit: String).void }
+      def pin_commit(key, commit)
+        entry = entry_for(key)
+        return unless entry
+
+        entry["resolved_commit"] = commit
+        entry.delete("content_hash")
+      end
+
+      sig { returns(String) }
+      def to_yaml
+        @document.to_yaml
+      end
+
+      private
+
+      sig { params(key: String).returns(T.nilable(T::Hash[Object, Object])) }
+      def entry_for(key)
+        entries = @document["dependencies"]
+        return unless entries.is_a?(Array)
+
+        entries.each do |entry|
+          return entry if entry.is_a?(Hash) && entry_key(entry) == key
+        end
+        nil
+      end
+
+      sig { params(entry: T::Hash[Object, Object]).returns(T.nilable(String)) }
+      def entry_key(entry)
+        repo_url = entry["repo_url"]
+        return unless repo_url.is_a?(String)
+
+        host = entry["host"]
+        virtual_path = entry["virtual_path"]
+        PackageSpecifier.lockfile_key(
+          host: host.is_a?(String) && !host.empty? ? host : PackageSpecifier::DEFAULT_HOST,
+          repo_url: repo_url,
+          virtual_path: virtual_path.is_a?(String) && !virtual_path.empty? ? virtual_path : nil
+        )
+      end
+
+      sig { params(file: Dependabot::DependencyFile).returns(T::Hash[Object, Object]) }
+      def parse(file)
+        parsed = YAML.safe_load(T.must(file.content))
+        parsed = {} if parsed.nil?
+        raise Dependabot::DependencyFileNotParseable, file.path unless parsed.is_a?(Hash)
+
+        parsed
+      rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::BadAlias
+        raise Dependabot::DependencyFileNotParseable, file.path
+      end
+    end
+  end
+end

data/lib/dependabot/apm/native_helpers.rb

@@ -0,0 +1,54 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "pathname"
+require "sorbet-runtime"
+
+require "dependabot/shared_helpers"
+
+module Dependabot
+  module Apm
+    module NativeHelpers
+      extend T::Sig
+
+      # APM renders its output through a terminal-width-aware console, which
+      # wraps long error messages mid-sentence. A wide, colourless console keeps
+      # each message on one line so errors can be matched reliably.
+      COMMAND_ENV = T.let(
+        {
+          "COLUMNS" => "1000",
+          "NO_COLOR" => "1",
+          "GIT_TERMINAL_PROMPT" => "0"
+        }.freeze,
+        T::Hash[String, String]
+      )
+
+      sig { returns(String) }
+      def self.apm_path
+        clean_path(File.join(native_helpers_root, "apm/bin/apm"))
+      end
+
+      # Runs an APM CLI command (e.g. `lock`) in the current directory, raising
+      # SharedHelpers::HelperSubprocessFailed with APM's output on failure.
+      sig { params(command: String).returns(String) }
+      def self.run_apm_command(command)
+        SharedHelpers.run_shell_command(
+          "#{apm_path} #{command}",
+          env: COMMAND_ENV,
+          fingerprint: "apm #{command}"
+        )
+      end
+
+      sig { returns(String) }
+      def self.native_helpers_root
+        default_path = File.join(__dir__, "../../../helpers/install-dir")
+        ENV.fetch("DEPENDABOT_NATIVE_HELPERS_PATH", default_path)
+      end
+
+      sig { params(path: String).returns(String) }
+      def self.clean_path(path)
+        Pathname.new(path).cleanpath.to_path
+      end
+    end
+  end
+end

data/lib/dependabot/apm/package_specifier.rb

@@ -37,7 +37,9 @@ module Dependabot
     # path is treated as the repository so nested subgroups resolve to the
     # correct remote; virtual packages there are out of scope for v1, as is
     # self-hosted GHES on an arbitrary hostname that cannot be recognised from
-    # the host alone.
+    # the host alone. As in APM, explicit clone URLs never carry a virtual path,
+    # so a URL with segments beyond `owner/repo` on a GitHub-family host
+    # resolves to `nil`.
     #
     # Azure DevOps hosts (`dev.azure.com`, `ssh.dev.azure.com` and legacy
     # `*.visualstudio.com`) expose repositories at `org/project/_git/repo`, a
@@ -52,6 +54,12 @@ module Dependabot
 
       DEFAULT_HOST = "github.com"
 
+      # APM only moves refs that are full commit SHAs (matched
+      # case-insensitively). Abbreviated SHAs are left alone, since they cannot
+      # be told apart from a branch name reliably.
+      FULL_SHA_REGEX = /\A[0-9a-f]{40}\z/i
+      ABBREVIATED_SHA_REGEX = /\A[0-9a-f]{7,39}\z/i
+
       # Azure DevOps Services hosts. Their repositories live at
       # `org/project/_git/repo`, a structure this generic owner/repo builder
       # cannot express, so ADO entries are out of scope for v1 (see README) and
@@ -98,6 +106,7 @@ module Dependabot
         spec, _, ref = entry.partition("#")
         host, path = split_host_and_path(spec, default_host)
         return nil unless path
+        return nil if explicit_git_form?(spec) && embedded_sub_path?(host, path)
 
         build(host: host, path: path, ref: ref, default_host: default_host)
       end
@@ -233,6 +242,24 @@ module Dependabot
         T.must(match[:port]).to_i == 443 ? T.must(match[:hostname]) : host
       end
 
+      sig { params(spec: String).returns(T::Boolean) }
+      def self.explicit_git_form?(spec)
+        spec.match?(SCP_STYLE) || spec.match?(URL_STYLE)
+      end
+
+      # APM never infers a virtual package from an explicit clone URL: virtual
+      # packages must use the shorthand or the object form's `path:` key. A
+      # GitHub-family URL with segments beyond `owner/repo`, or any URL with a
+      # path after a `.git` segment, is rejected by `apm` (or names a repository
+      # that cannot exist), so such entries are skipped rather than updated.
+      sig { params(host: String, path: String).returns(T::Boolean) }
+      def self.embedded_sub_path?(host, path)
+        segments = path.split("/").reject(&:empty?)
+        return true if segments[0...-1]&.any? { |segment| segment.end_with?(".git") }
+
+        github_family?(host.downcase) && segments.length > 2
+      end
+
       sig { params(entry: String).returns(T::Boolean) }
       def self.local_path?(entry)
         entry.start_with?("./", "../", "/", "~/", ".\\", "..\\", "~\\") ||
@@ -342,6 +369,35 @@ module Dependabot
         virtual_path = sub_path
         virtual_path ? "#{repo_name}/#{virtual_path}" : repo_name
       end
+
+      # The key APM uses to identify this package in `apm.lock.yaml`. Unlike
+      # `name`, it ignores the manifest's `default_host` and any port: APM keys
+      # entries by `repo_url`, prefixed by the host for anything other than
+      # github.com, plus the virtual path for virtual packages. The virtual path
+      # is joined with `//`, which never appears in a repository path, so a
+      # virtual package only matches a lock entry with the same repository: a
+      # GitLab `acme/prompts/skills/review` repository doesn't match the
+      # `acme/prompts` repository's `skills/review` package.
+      sig { returns(String) }
+      def lockfile_key
+        self.class.lockfile_key(
+          host: self.class.hostname_without_port(host),
+          repo_url: "#{owner}/#{repo}",
+          virtual_path: sub_path
+        )
+      end
+
+      # Builds a lockfile key from a lock entry's coordinates (or a manifest
+      # entry's, via #lockfile_key). GitHub-family identifiers are
+      # case-insensitive, so they are lowercased; other hosts keep their casing,
+      # as APM does.
+      sig { params(host: String, repo_url: String, virtual_path: T.nilable(String)).returns(String) }
+      def self.lockfile_key(host:, repo_url:, virtual_path: nil)
+        hostname = host.downcase
+        repo_url = repo_url.downcase if github_family?(hostname)
+        key = hostname == DEFAULT_HOST ? repo_url : "#{hostname}/#{repo_url}"
+        virtual_path ? "#{key}//#{virtual_path}" : key
+      end
     end
   end
 end

data/lib/dependabot/apm/update_checker.rb

@@ -9,6 +9,7 @@ require "dependabot/git_tag_details"
 require "dependabot/update_checkers"
 require "dependabot/update_checkers/base"
 require "dependabot/apm/git_commit_checker"
+require "dependabot/apm/package_specifier"
 require "dependabot/apm/requirement"
 require "dependabot/apm/version"
 
@@ -34,8 +35,12 @@ module Dependabot
 
       sig { override.returns(T.nilable(T.any(String, Gem::Version))) }
       def latest_resolvable_version_with_no_unlock
-        # Updating an APM dependency always rewrites its manifest requirement,
-        # so there is no newer version reachable "without unlocking".
+        # A branch pin moves to the branch's new head commit through the
+        # lockfile alone, without touching the manifest requirement.
+        return latest_version if branch_pinned?
+
+        # Every other APM update rewrites its manifest requirement, so there is
+        # no newer version reachable "without unlocking".
         dependency.version
       end
 
@@ -59,6 +64,7 @@ module Dependabot
       sig { override.returns(T::Array[Dependabot::DependencyRequirement]) }
       def updated_requirements
         return dependency.requirements unless git_commit_checker.git_dependency?
+        return updated_sha_pin_requirements if sha_pinned?
 
         dependency.requirements.map do |req|
           source = req.source_hash
@@ -98,6 +104,25 @@ module Dependabot
         raise NotImplementedError
       end
 
+      # The inherited check compares only the merged `dependency.version` (the
+      # first declaration's SHA) with the latest release commit. When that first
+      # declaration is already at the release but a later one is pinned to an
+      # older SHA, both resolve to the same commit and the outdated declaration
+      # would never be moved, so judge SHA pins by their individual declarations.
+      sig { returns(T::Boolean) }
+      def sha1_version_up_to_date?
+        return super unless sha_pinned?
+
+        updated_sha_pin_requirements == dependency.requirements
+      end
+
+      sig { returns(T::Boolean) }
+      def preferred_version_resolvable_with_unlock?
+        return super unless sha_pinned?
+
+        !sha1_version_up_to_date?
+      end
+
       # `latest_version` deliberately reports the MAX tag reachable by ANY family
       # so the base `can_update?` gate still fires when only a higher family can
       # move. But `DependencySet` defines a merged dependency's version as its
@@ -111,8 +136,12 @@ module Dependabot
       # version separate.
       sig { returns(Dependabot::Dependency) }
       def updated_dependency_with_own_req_unlock
+        # A branch pin is versioned by commit, so the base behaviour of
+        # reporting the latest commit as the new version applies to it.
+        return super unless tag_pinned? || sha_pinned?
+
         new_requirements = updated_requirements
-        new_version = pinned_versions(new_requirements).min
+        new_version = sha_pinned? ? merged_sha_version(new_requirements) : pinned_versions(new_requirements).min
 
         Dependabot::Dependency.new(
           name: dependency.name,
@@ -126,13 +155,21 @@ module Dependabot
         )
       end
 
+      # DependencySet keeps the first declaration's version when merging SHA
+      # pins, so that's the version the updated manifest parses to.
+      sig { params(requirements: T::Array[Dependabot::DependencyRequirement]).returns(T.nilable(String)) }
+      def merged_sha_version(requirements)
+        requirements.first&.source_string("ref")&.downcase
+      end
+
       sig { returns(T.nilable(T.any(String, Gem::Version))) }
       def fetch_latest_version
         return dependency.version unless git_commit_checker.git_dependency?
+        return latest_branch_commit if branch_pinned?
+        return latest_sha_pin_commit if sha_pinned?
 
-        # Only entries pinned to a semver tag are bumped in the manifest.
-        # Branch- and SHA-pinned entries are resolved via the lockfile, which
-        # APM regenerates itself, so Dependabot leaves them untouched.
+        # Unpinned entries are never parsed, so any other dependency is
+        # expected to be pinned to a version tag.
         return dependency.version unless git_commit_checker.pinned_ref_looks_like_version?
 
         # A merged dependency can hold several ref families (e.g. `review--v*`
@@ -146,6 +183,74 @@ module Dependabot
         end.max || dependency.version
       end
 
+      sig { returns(T::Boolean) }
+      def branch_pinned?
+        dependency.requirements.any? { |req| req.source_string("branch") }
+      end
+
+      sig { returns(T::Boolean) }
+      def sha_pinned?
+        refs = dependency.requirements.map { |req| req.source_string("ref") }
+        refs.any? && refs.all? { |ref| ref&.match?(PackageSpecifier::FULL_SHA_REGEX) }
+      end
+
+      sig { returns(T::Boolean) }
+      def tag_pinned?
+        !branch_pinned? && !sha_pinned?
+      end
+
+      # A branch pin is versioned by the commit the lockfile resolved, and moves
+      # to the branch's current head commit.
+      sig { returns(T.nilable(String)) }
+      def latest_branch_commit
+        git_commit_checker.head_commit_for_current_branch
+      end
+
+      # The commit of the release each SHA-pinned declaration moves to. All of a
+      # dependency's declarations share one repository, so they resolve to the
+      # same release unless a declaration is already pinned beyond it.
+      sig { returns(T.nilable(String)) }
+      def latest_sha_pin_commit
+        dependency.requirements.filter_map { |req| sha_pin_release(req)&.commit_sha }.first || dependency.version
+      end
+
+      # Moves each SHA pin to its release commit, recording the release tag so
+      # the manifest can be annotated with it as `apm update` does.
+      sig { returns(T::Array[Dependabot::DependencyRequirement]) }
+      def updated_sha_pin_requirements
+        dependency.requirements.map do |req|
+          release = sha_pin_release(req)
+          source = req.source_hash
+          next req unless release && source
+
+          Dependabot::DependencyRequirement.create(
+            req.merge(
+              source: source.merge(ref: release.commit_sha),
+              metadata: (req.metadata || {}).merge(release_tag: release.tag)
+            )
+          )
+        end
+      end
+
+      sig { params(req: Dependabot::DependencyRequirement).returns(T.nilable(Dependabot::GitTagDetails)) }
+      def sha_pin_release(req)
+        source = req.source_hash
+        pinned_sha = req.source_string("ref")&.downcase
+        return unless source && pinned_sha&.match?(PackageSpecifier::FULL_SHA_REGEX)
+
+        releases = sha_pin_releases
+        return releases[pinned_sha] if releases.key?(pinned_sha)
+
+        release = git_commit_checker_for(source).latest_annotated_release_tag(update_cooldown)
+        release = nil if release&.commit_sha.nil? || release&.commit_sha == pinned_sha
+        releases[pinned_sha] = release
+      end
+
+      sig { returns(T::Hash[String, T.nilable(Dependabot::GitTagDetails)]) }
+      def sha_pin_releases
+        @sha_pin_releases ||= T.let({}, T.nilable(T::Hash[String, T.nilable(Dependabot::GitTagDetails)]))
+      end
+
       # The tag a single requirement should move to: the latest tag resolved
       # within that requirement's own ref family (via a checker scoped to its
       # ref). Returns nil when there is no strictly-higher tag, so a requirement
@@ -235,7 +340,7 @@ module Dependabot
         params(
           source: Dependabot::DependencyRequirement::ObjectHash,
           ref_version: T.nilable(String)
-        ).returns(Dependabot::GitCommitChecker)
+        ).returns(Dependabot::Apm::GitCommitChecker)
       end
       def git_commit_checker_for(source, ref_version = nil)
         scoped_dependency =

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dependabot-apm
 version: !ruby/object:Gem::Version
-  version: 0.400.0
+  version: 0.402.0
 platform: ruby
 authors:
 - Dependabot
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.400.0
+        version: 0.402.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.400.0
+        version: 0.402.0
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -245,8 +245,11 @@ files:
 - lib/dependabot/apm/file_fetcher.rb
 - lib/dependabot/apm/file_parser.rb
 - lib/dependabot/apm/file_updater.rb
+- lib/dependabot/apm/file_updater/lockfile_updater.rb
 - lib/dependabot/apm/git_commit_checker.rb
+- lib/dependabot/apm/lockfile.rb
 - lib/dependabot/apm/metadata_finder.rb
+- lib/dependabot/apm/native_helpers.rb
 - lib/dependabot/apm/package_manager.rb
 - lib/dependabot/apm/package_specifier.rb
 - lib/dependabot/apm/requirement.rb
@@ -257,7 +260,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.400.0
+  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.402.0
 rdoc_options: []
 require_paths:
 - lib