dash 4.0.7 → 4.1.0

data/lib/dash/dockerfile/context.rb

@@ -0,0 +1,147 @@
+# Everything a rule is allowed to look at: the parsed Dockerfile, the build context on
+# disk, the builder's configuration, and — when the advice is printed next to a build
+# that actually ran — what that build measured.
+#
+# The shared predicates live here rather than in each rule so that "what counts as a
+# dependency install" has one answer, and so the measured half of a rule can find the
+# buildx vertex that corresponds to a Dockerfile line.
+class Dash::Dockerfile::Context
+  # The package managers whose install step is worth protecting from cache busting, and
+  # the cache directory each conventionally wants mounted.
+  DEPENDENCY_INSTALLS = [
+    [ /\bbundle\s+(?:_[\d._]+_\s+)?install\b/, "/usr/local/bundle/cache" ],
+    [ /\bnpm\s+(?:ci|install)\b/, "/root/.npm" ],
+    [ /\byarn\s+install\b/, "/usr/local/share/.cache/yarn" ],
+    [ /\bpnpm\s+install\b/, "/root/.local/share/pnpm/store" ],
+    [ /\bbun\s+install\b/, "/root/.bun/install/cache" ],
+    [ /\bpip3?\s+install\b/, "/root/.cache/pip" ],
+    [ /\bpoetry\s+install\b/, "/root/.cache/pypoetry" ],
+    [ /\bgo\s+mod\s+download\b/, "/go/pkg/mod" ],
+    [ /\bcargo\s+(?:build|fetch)\b/, "/usr/local/cargo/registry" ],
+    [ /\bcomposer\s+install\b/, "/root/.composer/cache" ],
+    [ /\bmix\s+deps\.get\b/, "/root/.hex" ],
+    [ /\bdotnet\s+restore\b/, "/root/.nuget/packages" ]
+  ].freeze
+
+  # apt takes its options before or after the verb (`apt-get -y install`,
+  # `apt-get -t bookworm-backports install`), so the verb is found past any of them. A
+  # shell separator is never an option or its value, so `apt-get -y && install` is not
+  # an apt install.
+  APT_OPTIONS = /(?:-[^\s;&|]+(?:\s+[^-\s;&|][^\s;&|]*)?\s+)*/
+  APT_INSTALL = [ /\bapt-get\s+#{APT_OPTIONS.source}install\b/, "/var/cache/apt" ].freeze
+
+  # A copy that ships the whole tree, so every commit invalidates it and everything
+  # layered on top of it.
+  BROAD_SOURCES = [ ".", "./", "*", "/" ].freeze
+
+  # buildx expands ARG and ENV references in the vertex name it prints, so a step's text
+  # and the Dockerfile line it came from stop agreeing at the first ${…}. Match on the
+  # longest shared prefix instead, and require enough of it that two unrelated RUNs
+  # cannot be confused for each other.
+  MINIMUM_STEP_MATCH = 12
+
+  attr_reader :document, :context_dir, :dockerignore, :build, :builder, :path
+
+  def initialize(document:, context_dir: nil, dockerignore: nil, build: nil, builder: nil, path: "Dockerfile")
+    @document = document
+    @context_dir = context_dir
+    @dockerignore = dockerignore
+    @build = build
+    @builder = builder
+    @path = path
+  end
+
+  def location_for(instruction)
+    "#{path}:#{instruction.line}"
+  end
+
+  def dependency_install?(instruction)
+    !install_match(instruction).nil?
+  end
+
+  # The command that made it a dependency install ("bundle install"), for advice that
+  # names what the operator wrote rather than the whole RUN.
+  def install_command(instruction)
+    install_match(instruction)&.first
+  end
+
+  def install_cache_target(instruction)
+    install_match(instruction)&.last
+  end
+
+  def apt_install?(instruction)
+    instruction.name == "RUN" && instruction.shell_command.match?(APT_INSTALL.first)
+  end
+
+  def broad_copy?(instruction)
+    return false unless %w[ COPY ADD ].include?(instruction.name)
+    return false if instruction.flag?("from")
+
+    sources(instruction).any? { |source| BROAD_SOURCES.include?(source) }
+  end
+
+  # A dependency install directly after a broad copy is invalidated by every commit,
+  # which is a finding of its own — rules that would otherwise report the same slow step
+  # twice defer to it.
+  def busted_by_broad_copy?(instruction)
+    stage = instruction.stage or return false
+
+    stage.instructions.any? { |other| other.line < instruction.line && broad_copy?(other) }
+  end
+
+  # buildx labels a step with its stage name except in a single-stage build, where it
+  # prints none. A multi-platform build reports the same step once per platform; the
+  # slowest one is the number worth quoting.
+  def build_step_for(instruction)
+    return unless build
+
+    text = normalize(instruction.to_s)
+    candidates = build.instruction_steps.select { |step| same_stage?(step, instruction) }
+
+    best = candidates.max_by do |step|
+      matched = normalize(step.instruction)
+      [ matched == text ? 1 : 0, shared_prefix(text, matched), step.seconds.to_f ]
+    end
+    return unless best
+
+    matched = normalize(best.instruction)
+    best if matched == text || shared_prefix(text, matched) >= MINIMUM_STEP_MATCH
+  end
+
+  def context_entries(name)
+    return [] unless context_dir
+
+    Dir.glob(name, base: context_dir, flags: ::File::FNM_DOTMATCH)
+  end
+
+  private
+    def install_match(instruction)
+      return unless instruction.name == "RUN"
+
+      command = instruction.shell_command
+      DEPENDENCY_INSTALLS.each do |pattern, target|
+        matched = command[pattern]
+        return [ matched, target ] if matched
+      end
+      nil
+    end
+
+    def same_stage?(step, instruction)
+      step.stage.nil? ? document.stages.one? : step.stage == instruction.stage&.name
+    end
+
+    def sources(instruction)
+      words = instruction.json? ? instruction.argv : instruction.args.split(/\s+/)
+      words.size > 1 ? words[0..-2] : words
+    end
+
+    def normalize(text)
+      text.to_s.squeeze(" ").strip
+    end
+
+    def shared_prefix(one, other)
+      length = 0
+      length += 1 while length < one.length && length < other.length && one[length] == other[length]
+      length
+    end
+end

data/lib/dash/dockerfile/dockerignore.rb

@@ -0,0 +1,29 @@
+# Just enough .dockerignore to answer "does this file ship in the build context?".
+#
+# Not a reimplementation of BuildKit's matcher: negations are skipped rather than
+# applied, so a path this says is covered might still ship. That direction is the safe
+# one — it costs a piece of advice, never a false accusation.
+class Dash::Dockerfile::Dockerignore
+  FILENAME = ".dockerignore"
+
+  attr_reader :patterns
+
+  def self.in(directory)
+    path = ::File.join(directory.to_s, FILENAME)
+    new(::File.read(path).lines) if ::File.file?(path)
+  end
+
+  def initialize(lines)
+    @patterns = lines
+      .map(&:strip)
+      .reject { |line| line.empty? || line.start_with?("#", "!") }
+      .map { |line| line.delete_prefix("**/").delete_prefix("./").delete_prefix("/").delete_suffix("/") }
+      .reject(&:empty?)
+  end
+
+  def covers?(path)
+    patterns.any? do |pattern|
+      ::File.fnmatch?(pattern, path, ::File::FNM_DOTMATCH) || path.start_with?("#{pattern}/")
+    end
+  end
+end

data/lib/dash/dockerfile/document.rb

@@ -0,0 +1,28 @@
+# A parsed Dockerfile: its instructions in file order, grouped into stages.
+#
+# Named Document rather than File so that `File.fnmatch` inside Dash::Dockerfile still
+# means the one in Ruby's core library.
+class Dash::Dockerfile::Document
+  attr_reader :instructions, :stages, :directives
+
+  def initialize(instructions:, stages:, directives: {})
+    @instructions = instructions
+    @stages = stages
+    @directives = directives
+  end
+
+  def shipped_stages
+    stages.select(&:shipped?)
+  end
+
+  def final_stage
+    stages.last
+  end
+
+  def each_instruction(name)
+    return to_enum(:each_instruction, name) unless block_given?
+
+    name = name.to_s.upcase
+    instructions.each { |instruction| yield instruction if instruction.name == name }
+  end
+end

data/lib/dash/dockerfile/finding.rb

@@ -0,0 +1,20 @@
+# One piece of advice about the Dockerfile or the build context.
+#
+# `rule` is a stable public string an operator can put in `report: ignore:`, so renaming
+# one is a breaking change to their deploy.yml. `location` is whatever they should open:
+# a Dockerfile line, `.dockerignore`, `build context`, or a deploy.yml key.
+Dash::Dockerfile::Finding = Struct.new(:rule, :severity, :location, :message, :suggestion, keyword_init: true) do
+  def warn?
+    severity == :warn
+  end
+
+  def self.from_h(hash)
+    hash = hash.transform_keys(&:to_sym)
+
+    new(**hash.slice(:rule, :location, :message, :suggestion), severity: hash[:severity].to_sym)
+  end
+
+  def to_h
+    { rule: rule, severity: severity.to_s, location: location, message: message, suggestion: suggestion }
+  end
+end

data/lib/dash/dockerfile/hadolint.rb

@@ -0,0 +1,75 @@
+require "json"
+require "open3"
+require "active_support/core_ext/string/filters"
+
+# Optional supplement to the built-in rules: whatever `hadolint` has to say about the same
+# file, when the operator already has it installed.
+#
+# Run as a plain local process rather than through SSHKit, so the command sequence a deploy
+# prints — and the cost-guard test that pins it — is unchanged. `--no-fail` keeps its exit
+# status out of the deploy, and anything that goes wrong becomes one informational finding
+# rather than an exception.
+class Dash::Dockerfile::Hadolint
+  EXECUTABLE = "hadolint".freeze
+  # hadolint's own levels. `error` is the only one worth a warning next to a deploy; the
+  # rest are style notes that should not compete with a measured finding.
+  SEVERITIES = { "error" => :warn }.freeze
+
+  class << self
+    # No shell: PATH is walked directly, so a directory with a space or a semicolon in it
+    # cannot turn a lookup into a command.
+    def available?
+      ENV["PATH"].to_s.split(::File::PATH_SEPARATOR).any? do |directory|
+        path = ::File.join(directory, EXECUTABLE)
+        ::File.executable?(path) && !::File.directory?(path)
+      end
+    end
+  end
+
+  def initialize(path:, file: path)
+    @path = path
+    @file = file
+  end
+
+  def findings
+    return [] unless self.class.available?
+
+    output, status = Open3.capture2(EXECUTABLE, "--format", "json", "--no-fail", @file)
+    return unavailable("exited #{status.exitstatus}") unless status.success?
+    return [] if output.strip.empty?
+
+    issues = JSON.parse(output)
+    return unparsable("expected a JSON array, got #{issues.class.name.downcase}") unless issues.is_a?(Array)
+
+    issues.map { |issue| finding_for(issue) }
+  # Only JSON.parse raises this, so it is the one error that means "it ran fine, dash
+  # could not read what it printed". Anything else that raises in here is dash's own.
+  rescue JSON::ParserError => e
+    unparsable(e.message.truncate(80))
+  rescue StandardError => e
+    unavailable(e.message)
+  end
+
+  private
+    def finding_for(issue)
+      Dash::Dockerfile::Finding.new \
+        rule: issue["code"],
+        severity: SEVERITIES.fetch(issue["level"], :info),
+        location: "#{@path}:#{issue["line"]}",
+        message: "#{issue["code"]}: #{issue["message"]}",
+        suggestion: nil
+    end
+
+    def unparsable(reason)
+      note "hadolint output could not be parsed (#{reason})"
+    end
+
+    def unavailable(reason)
+      note "hadolint could not run (#{reason})"
+    end
+
+    def note(message)
+      [ Dash::Dockerfile::Finding.new(rule: "hadolint", severity: :info, location: EXECUTABLE,
+        message: message, suggestion: "silence this with report: hadolint: false") ]
+    end
+end

data/lib/dash/dockerfile/instruction.rb

@@ -0,0 +1,58 @@
+require "json"
+
+# One logical Dockerfile instruction: the keyword, its flags, and everything else on the
+# line — continuations joined, heredoc bodies appended, comments dropped.
+#
+# `line` is the first physical line the instruction started on, because that is the line
+# an operator opens their editor at when advice names it.
+class Dash::Dockerfile::Instruction
+  attr_reader :name, :args, :flags, :line
+  attr_accessor :stage
+
+  def initialize(name:, args:, flags: {}, line: 1)
+    @name = name
+    @args = args
+    @flags = flags
+    @line = line
+  end
+
+  # The first value of a flag. Repeated flags (several `--mount`s on one RUN) keep every
+  # value in `flags`; callers that only care whether one is present ask for the first.
+  def flag(key)
+    Array(flags[key]).first
+  end
+
+  def flag?(key)
+    flags.key?(key)
+  end
+
+  def json?
+    args.start_with?("[") && !argv.nil?
+  end
+
+  # The exec form's arguments, or nil when this is the shell form (or malformed JSON,
+  # which BuildKit would reject but which must not take the analyzer down with it).
+  def argv
+    return @argv if defined?(@argv)
+
+    @argv = begin
+      parsed = JSON.parse(args) if args.start_with?("[")
+      parsed if parsed.is_a?(Array) && parsed.all?(String)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # What the instruction runs, as one string, whichever form it was written in — the
+  # rules match against shell text and should not have to care.
+  def shell_command
+    json? ? argv.join(" ") : args
+  end
+
+  # Collapsed to a single line so it can be compared with what buildx printed for the
+  # matching vertex, and so advice can name it without wrapping the terminal.
+  def to_s
+    [ name, *flags.flat_map { |key, values| values.map { |value| "--#{key}=#{value}" } }, args ]
+      .reject(&:blank?).join(" ").gsub(/\s+/, " ")
+  end
+end

data/lib/dash/dockerfile/parser.rb

@@ -0,0 +1,199 @@
+# Turns Dockerfile text into instructions and stages.
+#
+# Line-oriented, because that is how BuildKit reads it: a physical line is joined to the
+# next while it ends in the escape character, comment lines in between are dropped, and a
+# heredoc redirection pulls the following lines in verbatim until its delimiter.
+#
+# It is deliberately forgiving. Advice is a courtesy printed next to a deploy, so a file
+# this parser cannot make sense of must produce fewer findings, never an exception — the
+# authority on whether a Dockerfile builds is BuildKit, not this.
+class Dash::Dockerfile::Parser
+  DIRECTIVE = /\A#\s*(?<name>syntax|escape)\s*=\s*(?<value>\S+)\s*\z/i
+  COMMENT = /\A\s*#/
+  BLANK = /\A\s*\z/
+  INSTRUCTION = /\A\s*(?<name>[A-Za-z]+)(?:\s+(?<rest>.*))?\z/m
+  FLAG = /\A--(?<key>[a-zA-Z][\w-]*)=(?<value>(?:"[^"]*"|'[^']*'|\S)*)\s*/
+  # `<<EOF`, `<<-EOF`, `<<"EOF"`, `<<'EOF'` — the quoted forms only change how BuildKit
+  # expands the body, not where it ends.
+  HEREDOC = /<<-?\s*(?<quote>["']?)(?<delimiter>[A-Za-z_]\w*)\k<quote>/
+  STAGE_NAME = /\A(?<base>\S+)(?:\s+AS\s+(?<name>\S+))?\z/i
+
+  def self.parse(text)
+    new(text).parse
+  end
+
+  def initialize(text)
+    @lines = text.to_s.lines.map(&:chomp)
+  end
+
+  def parse
+    directives = parse_directives
+    escape = directives["escape"] == "`" ? "`" : "\\"
+
+    instructions = parse_instructions(escape)
+    stages = build_stages(instructions)
+
+    Dash::Dockerfile::Document.new(instructions: instructions, stages: stages, directives: directives)
+  end
+
+  private
+    attr_reader :lines
+
+    # Only the comment block at the very top can carry directives; after the first
+    # instruction a `# syntax=` line is an ordinary comment.
+    def parse_directives
+      directives = {}
+
+      lines.each do |line|
+        break unless line.match?(COMMENT) || line.match?(BLANK)
+        next unless (match = line.match(DIRECTIVE))
+
+        directives[match[:name].downcase] = match[:value]
+      end
+
+      directives
+    end
+
+    def parse_instructions(escape)
+      instructions = []
+      index = 0
+
+      while index < lines.size
+        line = lines[index]
+
+        if line.match?(BLANK) || line.match?(COMMENT)
+          index += 1
+          next
+        end
+
+        started_at = index
+        text, index = join_continuations(index, escape)
+        text, index = append_heredocs(text, index)
+
+        instruction = build_instruction(text, started_at + 1)
+        instructions << instruction if instruction
+      end
+
+      instructions
+    end
+
+    # Joins physical lines while each ends in the escape character. Comment lines between
+    # them are BuildKit's own convention for annotating a long RUN, and are not part of
+    # the command.
+    def join_continuations(index, escape)
+      parts = []
+
+      while index < lines.size
+        line = lines[index]
+        index += 1
+
+        next if line.match?(COMMENT) && parts.any?
+
+        continues = line.rstrip.end_with?(escape)
+        parts << (continues ? line.rstrip.delete_suffix(escape) : line)
+        break unless continues
+      end
+
+      [ parts.map(&:strip).reject(&:empty?).join(" "), index ]
+    end
+
+    # Every heredoc opened on the instruction line consumes lines until its delimiter, in
+    # the order they were opened. The bodies are appended to the arguments so rules can
+    # match what the instruction actually runs.
+    #
+    # A delimiter that never arrives means this was not a heredoc after all (`'<<EOF'` as
+    # a quoted shell word, or a typo): nothing is consumed, so the rest of the file is
+    # still parsed rather than folded into this one instruction.
+    def append_heredocs(text, index)
+      delimiters = text.scan(HEREDOC).map(&:last)
+      return [ text, index ] if delimiters.empty?
+
+      body = []
+      at = index
+
+      delimiters.each do |delimiter|
+        terminator = (at...lines.size).find { |line| lines[line].strip == delimiter }
+        return [ text, index ] unless terminator
+
+        body.concat heredoc_commands(lines[at...terminator])
+        at = terminator + 1
+      end
+
+      # Line breaks are kept: in a RUN heredoc each line is its own shell command, and the
+      # apt rules need to know where one ends.
+      [ [ text, *body ].join("\n"), at ]
+    end
+
+    # Inside the body the shell's own continuation applies: a line ending in `\` is the
+    # same command as the next one.
+    def heredoc_commands(body)
+      body.map(&:strip).each_with_object([]) do |line, commands|
+        if commands.last&.end_with?("\\")
+          commands[-1] = "#{commands.last.delete_suffix("\\").rstrip} #{line}"
+        else
+          commands << line
+        end
+      end
+    end
+
+    def build_instruction(text, line)
+      match = text.match(INSTRUCTION)
+      return unless match
+
+      flags, args = extract_flags(match[:rest].to_s.strip)
+
+      Dash::Dockerfile::Instruction.new(name: match[:name].upcase, args: args, flags: flags, line: line)
+    end
+
+    def extract_flags(rest)
+      flags = {}
+
+      while (match = rest.match(FLAG))
+        (flags[match[:key]] ||= []) << match[:value].delete_prefix('"').delete_suffix('"')
+        rest = match.post_match.lstrip
+      end
+
+      [ flags, rest ]
+    end
+
+    def build_stages(instructions)
+      stages = []
+
+      instructions.each do |instruction|
+        if instruction.name == "FROM"
+          stages << new_stage(instruction, stages.size)
+        elsif (stage = stages.last)
+          stage.instructions << instruction
+        end
+
+        instruction.stage = stages.last unless stages.empty? && instruction.name != "FROM"
+      end
+
+      mark_shipped stages
+      stages
+    end
+
+    def new_stage(instruction, index)
+      match = instruction.args.match(STAGE_NAME)
+
+      Dash::Dockerfile::Stage.new \
+        name: match && match[:name] || "stage-#{index}",
+        named: !(match && match[:name]).nil?,
+        index: index,
+        base: (match ? match[:base] : instruction.args),
+        from: instruction
+    end
+
+    # Walk back from the final stage through the bases it inherits. A stage reached only
+    # by `COPY --from=` is not on that chain, which is the point. Only an explicit `AS`
+    # name can be inherited from; the generated `stage-N` labels are dash's, not BuildKit's.
+    def mark_shipped(stages)
+      by_name = stages.select(&:named?).to_h { |stage| [ stage.name, stage ] }
+      stage = stages.last
+
+      while stage && !stage.shipped?
+        stage.shipped = true
+        stage = by_name[stage.base]
+      end
+    end
+end

data/lib/dash/dockerfile/rules/apt_hygiene.rb

@@ -0,0 +1,35 @@
+# apt's recommended packages and its package lists both ship in the layer unless the same
+# RUN gets rid of them. Only worth saying about a stage that ends up in the image.
+class Dash::Dockerfile::Rules::AptHygiene < Dash::Dockerfile::Rules::Base
+  NO_RECOMMENDS = /--no-install-recommends/
+  LIST_CLEANUP = %r{rm\s+-rf\s+/var/lib/apt/lists}
+  APT_OPERATION = /\bapt-get\s+#{Dash::Dockerfile::Context::APT_OPTIONS.source}(?:update|install|upgrade)\b/
+  # One shell command at a time: a later, compliant install must not vouch for an
+  # earlier one, and a cleanup only counts after the last thing that refilled the lists.
+  # A heredoc body keeps its line breaks, so each of its lines is a command too.
+  SEGMENT = /&&|\|\||;|\n/
+  SUGGESTION = "add --no-install-recommends to every install and rm -rf /var/lib/apt/lists/* at the end of the same RUN"
+
+  def findings
+    document.shipped_stages.flat_map { |stage| stage.instructions }.filter_map do |instruction|
+      next unless context.apt_install?(instruction)
+
+      problems = problems_in(instruction.shell_command.split(SEGMENT))
+      next if problems.empty?
+
+      note at(instruction), "apt-get install #{problems.join(" and ")}", SUGGESTION
+    end
+  end
+
+  private
+    def problems_in(segments)
+      installs = segments.select { |segment| segment.match?(Dash::Dockerfile::Context::APT_INSTALL.first) }
+      last_apt = segments.rindex { |segment| segment.match?(APT_OPERATION) } or return []
+      cleaned = segments.drop(last_apt + 1).any? { |segment| segment.match?(LIST_CLEANUP) }
+
+      problems = []
+      problems << "installs recommended packages" if installs.any? { |segment| !segment.match?(NO_RECOMMENDS) }
+      problems << "leaves /var/lib/apt/lists in the layer" unless cleaned
+      problems
+    end
+end

data/lib/dash/dockerfile/rules/base.rb

@@ -0,0 +1,44 @@
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/string/inflections"
+
+# A rule looks at the analysis context and returns findings. Nothing else: no IO, no
+# state, no ordering assumptions about the other rules.
+#
+# The id is derived from the class name and is a public string — operators put it in
+# `report: ignore:`, so renaming a rule class renames a config value.
+class Dash::Dockerfile::Rules::Base
+  attr_reader :context
+  delegate :document, :build, :builder, :context_dir, :dockerignore, to: :context
+
+  class << self
+    def id
+      @id ||= name.demodulize.underscore.dasherize
+    end
+  end
+
+  def initialize(context)
+    @context = context
+  end
+
+  def findings
+    []
+  end
+
+  private
+    def warning(location, message, suggestion = nil)
+      finding :warn, location, message, suggestion
+    end
+
+    def note(location, message, suggestion = nil)
+      finding :info, location, message, suggestion
+    end
+
+    def finding(severity, location, message, suggestion)
+      Dash::Dockerfile::Finding.new \
+        rule: self.class.id, severity: severity, location: location, message: message, suggestion: suggestion
+    end
+
+    def at(instruction)
+      context.location_for(instruction)
+    end
+end

data/lib/dash/dockerfile/rules/cache_busting_arg.rb

@@ -0,0 +1,40 @@
+# An ARG that changes on every commit — a git SHA, a build timestamp — invalidates every
+# layer from its first use onwards. Referenced after the dependency install it costs
+# nothing; referenced before it, it costs the whole install.
+class Dash::Dockerfile::Rules::CacheBustingArg < Dash::Dockerfile::Rules::Base
+  CACHE_BUSTING = /\A(?:.*_)?(?:GIT_SHA|COMMIT|SHA|BUILD_DATE|BUILD_TIME|BUILDTIME|VERSION)\z/i
+  # RUBY_VERSION, NODE_VERSION and friends name a toolchain and change once a quarter.
+  TOOLCHAIN = /_VERSION\z/i
+  SUGGESTION = "reference it after the dependency install, so a new commit does not invalidate it"
+
+  def findings
+    document.each_instruction("ARG").filter_map { |arg| finding_for(arg) }
+  end
+
+  private
+    def finding_for(arg)
+      name = arg.args.split("=").first.to_s
+      return unless name.match?(CACHE_BUSTING) && !name.match?(TOOLCHAIN)
+
+      stage = arg.stage || document.stages.first or return
+      barrier = last_install_line(stage) or return
+      reference = reference_before(name, arg.line, barrier)
+      return unless reference
+
+      note at(arg), "ARG #{name} changes on every commit and is referenced on line #{reference.line}, before the dependency install on line #{barrier}", SUGGESTION
+    end
+
+    def last_install_line(stage)
+      stage.instructions.select { |instruction| context.dependency_install?(instruction) }.last&.line
+    end
+
+    # A FROM that uses the ARG is pinning its base with it, which is a different thing
+    # and not something "reference it later" could ever fix.
+    def reference_before(name, from_line, barrier)
+      pattern = /\$(?:\{#{Regexp.escape(name)}\}|#{Regexp.escape(name)}(?!\w))/
+
+      document.instructions.find do |instruction|
+        instruction.name != "FROM" && instruction.line > from_line && instruction.line < barrier && instruction.to_s.match?(pattern)
+      end
+    end
+end