dependabot-apm 0.400.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 332d6b2c76b5d6ae722f9793731e25984be0835ca971d986f9316b594982c7b2
+  data.tar.gz: b2dea7a2bb867c041702a05754820c048aaa2f6a336cad5cc4edc777dcecc6d0
+SHA512:
+  metadata.gz: e4cedd6bf6ff0eba62c8689dbf5793bba8684e4dafde2ad12873adcff61ac60f06a4c9319af598a942547a84bd2c199193434d29a550c14a518d3534c3667abb
+  data.tar.gz: 60922c751e3a27e4e1a7302f799603efd4ac732f67aa02c194e81563e1621972c9b93a0befe45566801ba16ccf1d2555babec7f0277bbde9f816fdbddba0b605

data/lib/dependabot/apm/file_fetcher.rb

@@ -0,0 +1,95 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/errors"
+require "dependabot/file_fetchers"
+require "dependabot/file_fetchers/base"
+require "dependabot/apm/package_manager"
+
+module Dependabot
+  module Apm
+    class FileFetcher < Dependabot::FileFetchers::Base
+      extend T::Sig
+      extend T::Helpers
+
+      MANIFEST_FILENAME = "apm.yml"
+      LOCKFILE_FILENAME = "apm.lock.yaml"
+
+      # Shown when file fetching runs with beta ecosystems disabled. apm is a
+      # beta ecosystem, so it only operates when a repo opts in; surfacing the
+      # remediation here avoids the misleading "apm.yml not found" message when
+      # the manifest actually exists and the real blocker is the disabled flag.
+      BETA_DISABLED_MESSAGE =
+        "apm is a beta ecosystem. Set `enable-beta-ecosystems: true` in your " \
+        "dependabot.yml so Dependabot fetches and updates apm.yml."
+
+      sig { override.params(filenames: T::Array[String]).returns(T::Boolean) }
+      def self.required_files_in?(filenames)
+        filenames.include?(MANIFEST_FILENAME)
+      end
+
+      sig { override.returns(String) }
+      def self.required_files_message
+        "Repo must contain an #{MANIFEST_FILENAME} file."
+      end
+
+      sig { override.returns(T::Array[DependencyFile]) }
+      def fetch_files
+        # apm is a beta ecosystem, so file fetching is hidden behind the
+        # beta-ecosystems feature flag (see NEW_ECOSYSTEMS.md). When the flag is
+        # off, tell the user to enable it rather than claim the manifest is
+        # missing, which would hide the real remediation when apm.yml exists.
+        unless allow_beta_ecosystems?
+          raise Dependabot::DependencyFileNotFound.new(
+            File.join(directory, MANIFEST_FILENAME),
+            BETA_DISABLED_MESSAGE
+          )
+        end
+
+        fetched_files = T.let([manifest_file], T::Array[DependencyFile])
+        fetched_files << T.must(lockfile) if lockfile
+        fetched_files
+      end
+
+      sig { override.returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      def ecosystem_versions
+        return unless lockfile
+
+        version = parsed_lockfile_apm_version
+        return unless version
+
+        { package_managers: { "apm" => version } }
+      end
+
+      private
+
+      sig { returns(Dependabot::DependencyFile) }
+      def manifest_file
+        @manifest_file ||= T.let(
+          fetch_file_from_host(MANIFEST_FILENAME),
+          T.nilable(Dependabot::DependencyFile)
+        )
+      end
+
+      sig { returns(T.nilable(Dependabot::DependencyFile)) }
+      def lockfile
+        return @lockfile if defined?(@lockfile)
+
+        @lockfile = T.let(
+          fetch_file_if_present(LOCKFILE_FILENAME)&.tap { |f| f.support_file = true },
+          T.nilable(Dependabot::DependencyFile)
+        )
+      end
+
+      sig { returns(T.nilable(String)) }
+      def parsed_lockfile_apm_version
+        PackageManager.version_from_lockfile(lockfile&.content)
+      end
+    end
+  end
+end
+
+Dependabot::FileFetchers
+  .register("apm", Dependabot::Apm::FileFetcher)

data/lib/dependabot/apm/file_parser.rb

@@ -0,0 +1,313 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "yaml"
+
+require "dependabot/dependency"
+require "dependabot/errors"
+require "dependabot/file_parsers"
+require "dependabot/file_parsers/base"
+require "dependabot/apm/package_manager"
+require "dependabot/apm/package_specifier"
+require "dependabot/apm/version"
+
+module Dependabot
+  module Apm
+    class FileParser < Dependabot::FileParsers::Base
+      extend T::Sig
+
+      require "dependabot/file_parsers/base/dependency_set"
+
+      MANIFEST_FILENAME = "apm.yml"
+      LOCKFILE_FILENAME = "apm.lock.yaml"
+
+      # The manifest dependency blocks we parse, mapped to the dependency groups
+      # each block confers. Production entries carry an explicit "dependencies"
+      # marker group rather than an empty list: when DependencySet merges a
+      # package declared in both blocks, Dependency#production? flattens every
+      # requirement's groups, so an empty production marker would vanish and
+      # leave only "development", wrongly classifying the whole dependency as
+      # non-production. The explicit marker survives the merge and the registered
+      # production check treats its presence as production, while `devDependencies`
+      # entries (marked only by "development") stay non-production.
+      DEPENDENCY_BLOCKS = T.let(
+        {
+          "dependencies" => ["dependencies"].freeze,
+          "devDependencies" => ["development"].freeze
+        }.freeze,
+        T::Hash[String, T::Array[String]]
+      )
+
+      # Block scalars (folded `>` / literal `|`) are skipped outright: multi-line
+      # folding and chomping mean their decoded value need not be a contiguous
+      # substring of the raw source span, so the updater could not rewrite them
+      # and the job would fail with "Expected content to change!". Flow scalars
+      # are additionally verified with `scalar_round_trips?`, which also excludes
+      # escaped quoted scalars whose decoding differs from their source bytes.
+      BLOCK_SCALAR_STYLES = T.let(
+        [Psych::Nodes::Scalar::LITERAL, Psych::Nodes::Scalar::FOLDED].freeze,
+        T::Array[Integer]
+      )
+
+      sig { override.returns(T::Array[Dependabot::Dependency]) }
+      def parse
+        # Non-GitHub git hosts (e.g. GitLab) are case-sensitive, so use a
+        # case-sensitive dependency set to keep repositories that differ only by
+        # 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
+        # DependencyFileNotParseable before we walk it for source positions.
+        host = default_host
+
+        # When the manifest configures a default registry, APM routes plain
+        # string-shorthand entries through that registry rather than Git. We
+        # cannot resolve registry versions (registry dependencies are out of
+        # scope for v1), so those entries are skipped rather than bumped against
+        # a git remote they may not even belong to. Explicit clone URLs are
+        # 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|
+            # 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)
+            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)
+          end
+        end
+
+        dependency_set.dependencies
+      end
+
+      sig { returns(Ecosystem) }
+      def ecosystem
+        @ecosystem ||= T.let(
+          Ecosystem.new(
+            name: ECOSYSTEM,
+            package_manager: package_manager
+          ),
+          T.nilable(Dependabot::Ecosystem)
+        )
+      end
+
+      private
+
+      sig do
+        params(
+          spec: Dependabot::Apm::PackageSpecifier,
+          raw_entry: String,
+          declaration_span: String,
+          groups: T::Array[String]
+        ).returns(Dependabot::Dependency)
+      end
+      def build_dependency(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
+
+        Dependency.new(
+          name: spec.name,
+          version: version,
+          package_manager: "apm",
+          requirements: [{
+            requirement: nil,
+            file: manifest_file.name,
+            groups: groups,
+            source: {
+              type: "git",
+              url: spec.git_url,
+              ref: ref,
+              branch: 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.
+            metadata: {
+              declaration_string: raw_entry,
+              declaration_span: declaration_span
+            }
+          }]
+        )
+      end
+
+      # Returns each `<block>.apm` entry as a [value, encoded source span] pair.
+      # Only round-tripping flow scalar entries are returned: object-form entries
+      # (git:/registry:/id:/path: maps), block scalars (folded/literal) and
+      # escaped scalars whose decoding differs from their source bytes are all
+      # skipped, since the updater can only rewrite a value it finds verbatim in
+      # the source span.
+      sig { params(block_key: String).returns(T::Array[[String, String]]) }
+      def apm_entries_in(block_key)
+        block = ast_mapping_value(manifest_ast, block_key)
+        return [] unless block.is_a?(Psych::Nodes::Mapping)
+
+        sequence = ast_mapping_value(block, "apm")
+        return [] unless sequence.is_a?(Psych::Nodes::Sequence)
+
+        sequence.children.filter_map do |node|
+          next unless node.is_a?(Psych::Nodes::Scalar)
+          next if BLOCK_SCALAR_STYLES.include?(node.style)
+          next unless scalar_round_trips?(node)
+
+          [node.value, encode_span(node)]
+        end
+      end
+
+      # Encodes a scalar node's exact source span as
+      # "start_line:start_column:end_line:end_column" (all 0-based). The span
+      # brackets the whole token, including any surrounding quotes, which lets
+      # the updater rewrite block and flow sequences alike.
+      sig { params(node: Psych::Nodes::Scalar).returns(String) }
+      def encode_span(node)
+        [node.start_line, node.start_column, node.end_line, node.end_column].join(":")
+      end
+
+      # True when the scalar's decoded value appears verbatim inside its raw
+      # source span. The updater rewrites a ref by locating the declaration
+      # string (the decoded `node.value`) inside that span slice, so a scalar
+      # whose decoding differs from its source bytes -- e.g. a double-quoted
+      # scalar using escapes such as `\/` or `\x23` -- can never be rewritten and
+      # would fail the job with "Expected content to change!". Skipping those
+      # entries here mirrors the updater's own `original.include?(declaration)`
+      # guard, and the offset maths matches `FileUpdater#span_offsets` so an
+      # entry that survives parsing is always rewritable.
+      sig { params(node: Psych::Nodes::Scalar).returns(T::Boolean) }
+      def scalar_round_trips?(node)
+        content = T.must(manifest_file.content)
+        lines = content.each_line.to_a
+        start_offset = lines.first(node.start_line).sum(&:length) + node.start_column
+        end_offset = lines.first(node.end_line).sum(&:length) + node.end_column
+        return false if start_offset >= end_offset || end_offset > content.length
+
+        T.must(content[start_offset...end_offset]).include?(node.value)
+      end
+
+      # Looks up the value node for `key` in a YAML mapping AST node, whose
+      # children alternate [key, value, key, value, ...].
+      sig do
+        params(mapping: T.nilable(Psych::Nodes::Node), key: String)
+          .returns(T.nilable(Psych::Nodes::Node))
+      end
+      def ast_mapping_value(mapping, key)
+        return unless mapping.is_a?(Psych::Nodes::Mapping)
+
+        children = mapping.children
+        index = 0
+        while index < children.length
+          node_key = children[index]
+          return children[index + 1] if node_key.is_a?(Psych::Nodes::Scalar) && node_key.value == key
+
+          index += 2
+        end
+        nil
+      end
+
+      sig { returns(T.nilable(Psych::Nodes::Mapping)) }
+      def manifest_ast
+        return @manifest_ast if defined?(@manifest_ast)
+
+        document = YAML.parse(T.must(manifest_file.content))
+        root = document.is_a?(Psych::Nodes::Document) ? document.root : nil
+        @manifest_ast = T.let(
+          root.is_a?(Psych::Nodes::Mapping) ? root : nil,
+          T.nilable(Psych::Nodes::Mapping)
+        )
+      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
+      # `~/.apm/config.json` default is not part of the repository, so this
+      # guards the case that is reproducible from the manifest alone.
+      sig { returns(T::Boolean) }
+      def default_registry_configured?
+        registries = parsed_manifest["registries"]
+        return false unless registries.is_a?(Hash)
+
+        default = registries["default"]
+        return false unless default.is_a?(String)
+
+        !default.empty?
+      end
+
+      sig { returns(T::Hash[String, Object]) }
+      def parsed_manifest
+        @parsed_manifest ||= T.let(
+          begin
+            parsed = YAML.safe_load(T.must(manifest_file.content), aliases: true)
+            parsed = {} if parsed.nil?
+            raise Dependabot::DependencyFileNotParseable, manifest_file.path unless parsed.is_a?(Hash)
+
+            parsed
+          rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::BadAlias
+            raise Dependabot::DependencyFileNotParseable, manifest_file.path
+          end,
+          T.nilable(T::Hash[String, Object])
+        )
+      end
+
+      sig { returns(Dependabot::DependencyFile) }
+      def manifest_file
+        @manifest_file ||= T.let(
+          T.must(get_original_file(MANIFEST_FILENAME)),
+          T.nilable(Dependabot::DependencyFile)
+        )
+      end
+
+      sig { returns(T.nilable(Dependabot::DependencyFile)) }
+      def lockfile
+        @lockfile ||= T.let(
+          get_original_file(LOCKFILE_FILENAME),
+          T.nilable(Dependabot::DependencyFile)
+        )
+      end
+
+      sig { override.void }
+      def check_required_files
+        return if get_original_file(MANIFEST_FILENAME)
+
+        raise "No #{MANIFEST_FILENAME}!"
+      end
+
+      sig { returns(Ecosystem::VersionManager) }
+      def package_manager
+        @package_manager ||= T.let(
+          PackageManager.new(apm_version),
+          T.nilable(Dependabot::Apm::PackageManager)
+        )
+      end
+
+      sig { returns(String) }
+      def apm_version
+        PackageManager.version_from_lockfile(lockfile&.content) || DEFAULT_PACKAGE_MANAGER_VERSION
+      end
+    end
+  end
+end
+
+Dependabot::FileParsers
+  .register("apm", Dependabot::Apm::FileParser)

data/lib/dependabot/apm/file_updater.rb

@@ -0,0 +1,174 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/errors"
+require "dependabot/file_updaters"
+require "dependabot/file_updaters/base"
+
+module Dependabot
+  module Apm
+    class FileUpdater < Dependabot::FileUpdaters::Base
+      extend T::Sig
+
+      MANIFEST_FILENAME = "apm.yml"
+
+      # A single ref-bump edit, located by an absolute [start_offset, end_offset)
+      # character range in the original manifest content.
+      class Substitution < T::Struct
+        const :start_offset, Integer
+        const :end_offset, Integer
+        const :text, String
+      end
+
+      sig { returns(T::Array[Regexp]) }
+      def self.updated_files_regex
+        [/^apm\.yml$/]
+      end
+
+      sig { override.returns(T::Array[Dependabot::DependencyFile]) }
+      def updated_dependency_files
+        updated_files = manifest_files.filter_map do |file|
+          next unless file_changed?(file)
+
+          updated_file(file: file, content: updated_manifest_content(file))
+        end
+
+        raise "No files changed!" if updated_files.none?
+
+        updated_files
+      end
+
+      private
+
+      sig { override.void }
+      def check_required_files
+        return if get_original_file(MANIFEST_FILENAME)
+
+        raise "No #{MANIFEST_FILENAME}!"
+      end
+
+      sig { returns(T::Array[Dependabot::DependencyFile]) }
+      def manifest_files
+        dependency_files.select { |f| File.basename(f.name) == MANIFEST_FILENAME }
+      end
+
+      sig { params(file: Dependabot::DependencyFile).returns(T::Boolean) }
+      def file_changed?(file)
+        dependencies.any? { |dep| requirement_changed?(file, dep) }
+      end
+
+      sig { params(file: Dependabot::DependencyFile).returns(String) }
+      def updated_manifest_content(file)
+        original_content = T.must(file.content)
+        content = apply_substitutions(original_content, substitutions_for(file, original_content))
+
+        raise "Expected content to change!" if content == original_content
+
+        content
+      end
+
+      # Collects every ref-bump substitution for `file`, each located by an
+      # absolute range in the ORIGINAL content. Resolving all offsets against the
+      # original (rather than mutating between edits) is what lets
+      # `apply_substitutions` reorder them safely.
+      sig { params(file: Dependabot::DependencyFile, content: String).returns(T::Array[Substitution]) }
+      def substitutions_for(file, content)
+        dependencies.flat_map do |dependency|
+          previous_requirements = dependency.previous_requirements || []
+
+          dependency.requirements.filter_map do |new_req|
+            next unless new_req.file == file.name
+
+            substitution_for(content, new_req, previous_requirements)
+          end
+        end
+      end
+
+      # Builds the substitution for a single requirement. The replacement rewrites
+      # only the declaration substring inside the scalar's span slice, so any
+      # surrounding quotes are preserved and an identical string elsewhere in the
+      # file is never touched.
+      sig do
+        params(
+          content: String,
+          new_req: Dependabot::DependencyRequirement,
+          previous_requirements: T::Array[Dependabot::DependencyRequirement]
+        ).returns(T.nilable(Substitution))
+      end
+      def substitution_for(content, new_req, previous_requirements)
+        declaration = new_req.metadata_string("declaration_string")
+        new_ref = new_req.source_string("ref")
+        return unless declaration && new_ref
+
+        old_req = previous_requirements.find do |req|
+          req.metadata_string("declaration_string") == declaration
+        end
+        old_ref = old_req&.source_string("ref")
+        return unless old_ref && old_ref != new_ref
+
+        # A quoted scalar may carry trailing whitespace after the ref (e.g.
+        # `"owner/repo#v1.0.0 "`). PackageSpecifier strips it before parsing the
+        # ref, but the stored declaration keeps it, so anchor the match before any
+        # trailing whitespace and preserve that whitespace in the rewrite. An
+        # end-anchored `##{old_ref}` check would otherwise miss and fail the whole
+        # update with "Expected content to change!".
+        ref_at_end = /##{Regexp.escape(old_ref)}(\s*)\z/
+        return unless declaration.match?(ref_at_end)
+
+        offsets = span_offsets(content, new_req.metadata_string("declaration_span"))
+        return unless offsets
+
+        start_offset, end_offset = offsets
+        original = T.must(content[start_offset...end_offset])
+        return unless original.include?(declaration)
+
+        new_declaration = declaration.sub(ref_at_end, "##{new_ref}\\1")
+        Substitution.new(
+          start_offset: start_offset,
+          end_offset: end_offset,
+          text: original.sub(declaration, new_declaration)
+        )
+      end
+
+      # Applies the substitutions from the end of the file backwards. Rewriting in
+      # descending start offset means a length change in one edit can never shift
+      # the offsets of the edits still to be applied, so duplicate entries sharing
+      # a line (e.g. a flow sequence) are all updated correctly.
+      sig { params(content: String, substitutions: T::Array[Substitution]).returns(String) }
+      def apply_substitutions(content, substitutions)
+        substitutions.sort_by(&:start_offset).reverse.reduce(content) do |result, sub|
+          "#{T.must(result[0...sub.start_offset])}#{sub.text}#{result[sub.end_offset..]}"
+        end
+      end
+
+      # Resolves the encoded span to an absolute [start, end) character range in
+      # `content`, or nil when the span is missing, malformed, or points past the
+      # end of the current content.
+      sig { params(content: String, declaration_span: T.nilable(String)).returns(T.nilable([Integer, Integer])) }
+      def span_offsets(content, declaration_span)
+        return unless declaration_span
+
+        parts = declaration_span.split(":")
+        return unless parts.length == 4
+
+        lines = content.each_line.to_a
+        start_offset = line_offset(lines, T.must(parts[0]).to_i) + T.must(parts[1]).to_i
+        end_offset = line_offset(lines, T.must(parts[2]).to_i) + T.must(parts[3]).to_i
+        return if start_offset >= end_offset || end_offset > content.length
+
+        [start_offset, end_offset]
+      end
+
+      # Character offset of the start of the given 0-based line.
+      sig { params(lines: T::Array[String], line: Integer).returns(Integer) }
+      def line_offset(lines, line)
+        lines.first(line).sum(&:length)
+      end
+    end
+  end
+end
+
+Dependabot::FileUpdaters
+  .register("apm", Dependabot::Apm::FileUpdater)

data/lib/dependabot/apm/git_commit_checker.rb

@@ -0,0 +1,91 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/git_commit_checker"
+require "dependabot/apm/version"
+
+module Dependabot
+  module Apm
+    # A GitCommitChecker specialised for APM's strict SemVer 2.0.0 tags.
+    #
+    # The shared Dependabot::GitCommitChecker recognises and parses version tags
+    # with a RubyGems-oriented VERSION_REGEX that is incompatible with APM's
+    # strict SemVer grammar in two ways:
+    #
+    #   * it rejects valid SemVer build metadata (e.g. `v1.2.0+build.5`), so
+    #     those releases would never be offered as updates; and
+    #   * it accepts non-SemVer tags such as `v1.2.3.4`, which then raise
+    #     ArgumentError when the checker builds a strict Apm::Version.
+    #
+    # Overriding just the version-grammar seams (tag recognition, version
+    # extraction, prefix comparison and latest-tag selection) routes every tag
+    # through Apm::Version, while reusing all of the shared cooldown, ignore,
+    # prerelease and security handling.
+    #
+    # Besides plain `v?<semver>` tags, APM also recognises package-scoped tags
+    # so a monorepo can release each package independently: `{name}_v{version}`,
+    # `{name}--v{version}` and `{name}-v{version}`, where `{name}` is the
+    # package's own name (the repository name, or the final component of a
+    # virtual package path). A repository that only publishes `review--v1.5.0`
+    # would otherwise offer no update, so those forms are parsed too, with the
+    # accepted prefix scoped to this dependency's package name. That grammar
+    # lives in `Apm::Version.semver_from_ref`, shared with the file parser and
+    # update checker so every consumer reads refs identically.
+    class GitCommitChecker < Dependabot::GitCommitChecker
+      extend T::Sig
+
+      # Build metadata is not part of SemVer precedence, so tags such as
+      # `v1.3.0+build.5` and `v1.3.0+build.9` compare equal and the inherited
+      # `max_by { version_from_tag(...) }` would keep whichever the remote
+      # advertised first. Break that tie by the highest full tag string, as APM
+      # does, so latest-tag selection is deterministic regardless of ref order.
+      # Public to match the shared checker, which exposes this selection seam.
+      sig { override.params(tags: T::Array[Dependabot::GitRef]).returns(T.nilable(Dependabot::GitTagDetails)) }
+      def max_local_tag(tags)
+        max_version_tag = tags.max_by { |tag| [version_from_tag(tag), tag.name] }
+
+        to_local_tag(max_version_tag)
+      end
+
+      private
+
+      # 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
+      # tags (e.g. `v1.2.0+build.5`) and package-scoped tags (e.g.
+      # `review--v1.5.0`) are kept.
+      sig { override.params(tag: String).returns(T::Boolean) }
+      def version_tag?(tag)
+        !Dependabot::Apm::Version.semver_from_ref(tag, dependency_name: dependency.name).nil?
+      end
+
+      # Extract the SemVer core of a tag, keeping any build metadata so
+      # Apm::Version can parse it. Tags reach here only after #version_tag?, so
+      # the tag is always a plain `v?<semver>` or a recognised package-scoped
+      # form and the extraction never returns nil.
+      sig { override.params(name: String).returns(String) }
+      def scan_version(name)
+        T.must(Dependabot::Apm::Version.semver_from_ref(name, dependency_name: dependency.name))
+      end
+
+      # An APM tag's prefix is whatever precedes its SemVer core: the optional
+      # `v` on a plain tag, or `{name}_v` / `{name}--v` / `{name}-v` on a
+      # package-scoped one. Strip the SemVer core (which the shared VERSION_REGEX
+      # cannot remove once build metadata is present) and compare what remains,
+      # treating `v` and no prefix as equivalent to match the shared checker's
+      # lenient behaviour, so a pinned plain tag keeps resolving plain tags and a
+      # pinned scoped tag keeps resolving that package's scoped tags.
+      sig { override.params(tag: String, other_tag: String).returns(T::Boolean) }
+      def same_prefix?(tag, other_tag)
+        normalize_v_prefix(version_prefix(tag)) == normalize_v_prefix(version_prefix(other_tag))
+      end
+
+      sig { params(tag: String).returns(String) }
+      def version_prefix(tag)
+        tag.delete_suffix(scan_version(tag))
+      end
+    end
+  end
+end