dash 4.0.8 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a417156134dd79a4724f87192f70baa55fdbc4478a115e021845e3742bacee88
-  data.tar.gz: ebdbb8d7f192b692c31c8cdaa9834584c01dec3653b744b1a481672fee179d28
+  metadata.gz: 32799cf5de0b149a2b36f88e0af2d671c82a5d05a3c54180f034d8574eb58bf8
+  data.tar.gz: 1e33d017d9ec6e3e3545ea0c1125d9d4b38a2e12557197b2c827e00e608b4aa0
 SHA512:
-  metadata.gz: 3b263730b7ccf4eeeb857304477945fd9d2476bdf52cdb30a964b12b09143b36b5f585ae672d776eac29a6e009606add151aa6e9dd98385f9146980bbc40a9db
-  data.tar.gz: a3ebb3e0141a0f692bd70205aa3d438f9a3cbd1022d1b92c229bf1daf19294c4826a7420c0fefbb077f5a6d6cb46016ee6ab3926bb08f11383bb7a6eb0aaa23e
+  metadata.gz: bac661834cb626277175f2e0a9abbfb273975a0e70dd45779352798f547c5097ff836cfaed017316a207d59aa4d62b1b337112692db9fa7870aec2056bcd14e4
+  data.tar.gz: a8879e8f7b3250903eb854f23436b63892cdced0a303969039ebc809f29cce5231f3dda51faa2c5d3755b55edb8b543a007f96964272dc7afe1a1cf6c132ec6b

data/lib/dash/build/progress_parser.rb

@@ -0,0 +1,136 @@
+# Reads `docker buildx build --progress=plain` as it streams past and turns it into a
+# per-step report. It is an SSHKit interaction handler, so it sees the same bytes SSHKit
+# is already printing — no second process, no `docker buildx history`, no extra command.
+#
+# The stream is line-oriented but arrives in chunks (the SSH backend splits on packet
+# boundaries, not newlines), so data is buffered and only whole lines are parsed. Every
+# line belongs to a vertex — `#12` — and the first line for a vertex names it; the rest
+# are events on it (DONE, CACHED, ERROR) or its own stdout, which is ignored.
+#
+# Nothing here may raise into a build. A parse error stops the parsing and is reported
+# once by the caller; the deploy keeps whatever was collected up to that point.
+class Dash::Build::ProgressParser
+  VERTEX = /\A#(?<number>\d+)(?: (?<rest>.*))?\z/
+
+  # `[linux/amd64 build 2/3] RUN …` — the platform prefix only appears on multi-platform
+  # builds, and the stage name only when the Dockerfile named it with AS.
+  STEP = %r{\A\[(?:(?<platform>[a-z0-9]+/[a-z0-9][\w./-]*) )?(?:(?<stage>[A-Za-z0-9][\w.-]*) )?(?<ordinal>\d+)/(?<steps_in_stage>\d+)\] (?<instruction>.+)\z}
+  INTERNAL = /\A\[(?:\S+ )?internal\] (?<what>.+)\z/
+  DONE = /\ADONE (?<seconds>\d+(?:\.\d+)?)s\z/
+  ERROR = /\AERROR: (?<message>.+)\z/
+  TRANSFERRING_CONTEXT = /\Atransferring context: (?<size>[\d.]+)(?<unit>[a-zA-Z]+)(?: (?<seconds>\d+(?:\.\d+)?)s)? done\z/
+  PUSHING = /\Apushing .*?(?<seconds>\d+(?:\.\d+)?)s done\z/
+
+  BYTE_UNITS = { "b" => 1, "kb" => 1_000, "mb" => 1_000_000, "gb" => 1_000_000_000, "tb" => 1_000_000_000_000 }.freeze
+
+  attr_reader :error
+
+  def initialize
+    @steps = {}
+    @order = []
+    @buffer = +""
+    @push_seconds = 0.0
+    @mutex = Mutex.new
+  end
+
+  # SSHKit's interaction-handler contract.
+  def on_data(_command, _stream_name, data, _channel)
+    @mutex.synchronize do
+      next if @error
+
+      @buffer << data.to_s
+      while (newline = @buffer.index("\n"))
+        parse_line @buffer.slice!(0..newline).chomp
+      end
+    rescue StandardError => e
+      @error = e
+    end
+  end
+
+  # The last line of a build has no trailing newline when the command dies mid-write.
+  def finish
+    @mutex.synchronize do
+      next if @error
+
+      parse_line @buffer.chomp unless @buffer.empty?
+      @buffer = +""
+    rescue StandardError => e
+      @error = e
+    end
+  end
+
+  def result
+    @mutex.synchronize do
+      Dash::Build::Report.new(steps: @order.map { |number| @steps[number] }, push_seconds: @push_seconds)
+    end
+  end
+
+  private
+    def parse_line(line)
+      match = VERTEX.match(line) or return
+      rest = match[:rest].to_s.strip
+
+      # `#3 ...` is buildx saying the vertex is deferred, not a step of its own.
+      return if rest.empty? || rest == "..."
+
+      number = match[:number].to_i
+      step = @steps[number]
+
+      unless step
+        step = @steps[number] = build_step(number, rest)
+        @order << number
+      end
+
+      update step, rest
+    end
+
+    def build_step(number, rest)
+      Dash::Build::Step.new(number, kind: :other, name: rest).tap do |step|
+        if (match = STEP.match(rest))
+          step.platform = match[:platform]
+          step.stage = match[:stage]
+          step.ordinal = match[:ordinal].to_i
+          step.steps_in_stage = match[:steps_in_stage].to_i
+          step.instruction = match[:instruction].squeeze(" ").strip
+          step.kind = step.instruction.start_with?("FROM ") ? :from : :instruction
+        elsif (match = INTERNAL.match(rest))
+          step.kind = internal_kind(match[:what])
+        elsif rest.start_with?("exporting cache")
+          step.kind = :cache_export
+        elsif rest.match?(/\A(exporting|pushing|writing image)/)
+          step.kind = :export
+        end
+      end
+    end
+
+    def internal_kind(what)
+      case what
+      when /\Aload build context/ then :context
+      when /\Aload metadata for/ then :metadata
+      else :other
+      end
+    end
+
+    # Later lines for a vertex are its result, its output, or its progress. buildx
+    # re-reports DONE per platform on a multi-platform build, so the last one wins.
+    def update(step, rest)
+      if (match = DONE.match(rest))
+        step.seconds = match[:seconds].to_f
+      elsif rest == "CACHED"
+        step.cached = true
+        step.seconds = 0.0
+      elsif (match = ERROR.match(rest))
+        step.error = match[:message]
+      elsif (match = TRANSFERRING_CONTEXT.match(rest)) && step.kind == :context
+        step.bytes = bytes(match[:size], match[:unit])
+        step.seconds ||= match[:seconds]&.to_f
+      elsif (match = PUSHING.match(rest)) && step.kind == :export
+        @push_seconds += match[:seconds].to_f
+      end
+    end
+
+    # buildx reports decimal units — 25.18MB is 25,180,000 bytes, not 25.18 MiB.
+    def bytes(size, unit)
+      (size.to_f * BYTE_UNITS.fetch(unit.downcase, 1)).round
+    end
+end

data/lib/dash/build/report.rb

@@ -0,0 +1,104 @@
+# What the build actually spent its time on, derived from the buildx progress stream.
+#
+# "Steps" here means the operator's own Dockerfile steps — the vertices buildx numbered
+# `[stage k/m]`. BuildKit's own bookkeeping (booting, auth tokens, metadata lookups) is
+# kept in `steps` because it is still time the build took, but it is never counted as a
+# step the operator wrote.
+class Dash::Build::Report
+  attr_reader :steps, :push_seconds
+
+  # Rebuilds a report from what #to_h exported. Only the steps and the push are restored:
+  # every other number in the export is derived from them, so recomputing keeps a
+  # hand-edited file from claiming a total its own steps do not add up to.
+  def self.from_h(hash)
+    hash = hash.transform_keys(&:to_sym)
+
+    new steps: Array(hash[:steps]).map { |step| Dash::Build::Step.from_h(step) }, push_seconds: hash[:push_seconds].to_f
+  end
+
+  def initialize(steps: [], push_seconds: 0.0)
+    @steps = steps
+    @push_seconds = push_seconds
+  end
+
+  def any?
+    steps.any?
+  end
+
+  def dockerfile_steps
+    steps.select(&:dockerfile_step?)
+  end
+
+  def instruction_steps
+    steps.select { |step| step.kind == :instruction }
+  end
+
+  def cached_steps
+    dockerfile_steps.select(&:cached)
+  end
+
+  def uncached_steps
+    dockerfile_steps.reject(&:cached)
+  end
+
+  # The rows worth printing: the operator's own instructions, longest first. A FROM or a
+  # metadata lookup is not something they can speed up by editing the Dockerfile.
+  def slowest(count)
+    instruction_steps.reject(&:cached).sort_by { |step| -step.seconds.to_f }.first(count)
+  end
+
+  def context_step
+    steps.find { |step| step.kind == :context }
+  end
+
+  def context_bytes
+    context_step&.bytes
+  end
+
+  def context_seconds
+    context_step&.seconds
+  end
+
+  def export_seconds
+    seconds_for(:export)
+  end
+
+  def cache_export_seconds
+    seconds_for(:cache_export)
+  end
+
+  def total_step_seconds
+    steps.sum { |step| step.seconds.to_f }
+  end
+
+  def errors
+    steps.select(&:error)
+  end
+
+  # The errors worth putting in front of an operator. BuildKit reports a cache-import
+  # miss as an ERROR on its own vertex — the first build against a fresh cache always
+  # has one — and a row saying "error" for something that did not fail the build teaches
+  # people to ignore the column.
+  def failed_steps
+    errors.select { |step| step.dockerfile_step? || step.kind == :export }
+  end
+
+  def to_h
+    {
+      context_bytes: context_bytes,
+      context_seconds: context_seconds,
+      cached_steps: cached_steps.size,
+      total_steps: dockerfile_steps.size,
+      export_seconds: export_seconds,
+      cache_export_seconds: cache_export_seconds,
+      push_seconds: push_seconds,
+      total_step_seconds: total_step_seconds,
+      steps: steps.map(&:to_h)
+    }
+  end
+
+  private
+    def seconds_for(kind)
+      steps.sum { |step| step.kind == kind ? step.seconds.to_f : 0.0 }
+    end
+end

data/lib/dash/build/step.rb

@@ -0,0 +1,49 @@
+# One buildx vertex. A vertex is a unit of work BuildKit reports on: a Dockerfile
+# instruction, the context transfer, a metadata lookup, the export to the registry.
+#
+# Only the ones with an ordinal (`[build 5/9]`) are the operator's own steps — the rest
+# are BuildKit's own bookkeeping, and counting them would make "cached steps 9 of 22"
+# say something nobody asked.
+class Dash::Build::Step
+  attr_reader :number
+  attr_accessor :kind, :name, :platform, :stage, :ordinal, :steps_in_stage, :instruction, :seconds, :cached, :error, :bytes
+
+  def self.from_h(step)
+    step = step.transform_keys(&:to_sym)
+
+    new(step[:number], kind: step[:kind]&.to_sym || :other, name: step[:label]).tap do |rebuilt|
+      rebuilt.platform, rebuilt.stage = step[:platform], step[:stage]
+      rebuilt.ordinal, rebuilt.steps_in_stage = step[:ordinal], step[:steps_in_stage]
+      rebuilt.instruction, rebuilt.seconds = step[:instruction], step[:seconds]
+      rebuilt.cached, rebuilt.bytes, rebuilt.error = !!step[:cached], step[:bytes], step[:error]
+    end
+  end
+
+  def initialize(number, kind: :other, name: nil)
+    @number = number
+    @kind = kind
+    @name = name
+    @cached = false
+  end
+
+  # What buildx itself printed for this vertex, minus the platform prefix it adds on a
+  # multi-platform build — the operator matches these against their Dockerfile, and the
+  # platform is already its own column in the data.
+  def label
+    ordinal ? "[#{[ stage, "#{ordinal}/#{steps_in_stage}" ].compact.join(" ")}] #{instruction}" : name.to_s
+  end
+
+  def dockerfile_step?
+    !ordinal.nil?
+  end
+
+  # `label` is here for whatever reads the JSON — it is the string buildx printed and the
+  # one a human matches against their Dockerfile — and the parts it is built from are here
+  # so #from_h can rebuild it rather than trusting a field a hand-edited file may disagree
+  # with.
+  def to_h
+    { number: number, kind: kind, label: label, platform: platform, stage: stage, ordinal: ordinal,
+      steps_in_stage: steps_in_stage, instruction: instruction, seconds: seconds, cached: cached,
+      bytes: bytes, error: error }
+  end
+end

data/lib/dash/cli/app/boot.rb

@@ -38,22 +38,36 @@ class Dash::Cli::App::Boot
   end
 
   private
+    # Both answers come back from one round trip, which means the running version is read
+    # before any rename happens. When the clashing container IS the running one, the
+    # version to stop later is the name it was renamed to - the name that was read now
+    # belongs to the container this boot is about to start.
     def old_version_renamed_if_clashing
-      if capture_with_info(*app.container_id_for_version(version), raise_on_non_zero_exit: false).present?
+      clashing_container_id, old_version = capture_boot_state
+
+      if clashing_container_id.present?
         renamed_version = "#{version}_replaced_#{SecureRandom.hex(8)}"
         info "Renaming container #{version} to #{renamed_version} as already deployed on #{host}"
-        audit("Renaming container #{version} to #{renamed_version}")
-        execute *app.rename_container(version: version, new_version: renamed_version)
+        execute *auditor.record_then("Renaming container #{version} to #{renamed_version}",
+          app.rename_container(version: version, new_version: renamed_version))
+
+        old_version = renamed_version if old_version == version
       end
 
-      capture_with_info(*app.current_running_version, raise_on_non_zero_exit: false).strip.presence
+      old_version
+    end
+
+    def capture_boot_state
+      output = capture_with_info(*app.boot_state(version), raise_on_non_zero_exit: false).to_s
+      clashing, _, running = output.partition(/^#{Regexp.escape(Dash::Commands::App::BOOT_STATE_SEPARATOR)}$/)
+
+      [ clashing.strip.presence, running.strip.presence ]
     end
 
     def start_new_version
-      audit "Booted app version #{version}"
       hostname = "#{host.to_s[0...51].chomp(".")}-#{SecureRandom.hex(6)}"
 
-      execute *app.ensure_env_directory
+      execute *auditor.record_then("Booted app version #{version}", app.ensure_env_directory)
       upload! role.secrets_io(host), role.secrets_path, mode: "0600"
 
       execute *app.run(hostname: hostname)
@@ -161,10 +175,6 @@ class Dash::Cli::App::Boot
       @auditor = DASH.auditor(role: role)
     end
 
-    def audit(message)
-      execute *auditor.record(message), verbosity: :debug
-    end
-
     def gatekeeper?
       barrier && barrier_role?
     end

data/lib/dash/cli/app.rb

@@ -40,8 +40,8 @@ class Dash::Cli::App < Dash::Cli::Base
 
         # Tag once the app booted on all hosts
         on(DASH.app_hosts) do |host|
-          execute *DASH.auditor.record("Tagging #{DASH.config.absolute_image} as the latest image"), verbosity: :debug
-          execute *DASH.app.tag_latest_image
+          execute *DASH.auditor.record_then("Tagging #{DASH.config.absolute_image} as the latest image",
+            DASH.app.tag_latest_image)
         end
       end
     end

data/lib/dash/cli/base.rb

@@ -1,4 +1,5 @@
 require "thor"
+require "time"
 require "dash/sshkit_with_ext"
 
 module Dash::Cli
@@ -145,13 +146,111 @@ module Dash::Cli
       def print_runtime
         started_at = Time.now
         @print_runtime_depth = @print_runtime_depth.to_i + 1
+        record_startup_timing if @print_runtime_depth == 1
         yield
         Time.now - started_at
+      rescue StandardError => e
+        # Kept so the saved report says how the run ended. `setup` nests, and the inner
+        # deploy sets it first — the outermost writer reads the same error either way.
+        @report_error = e
+        raise
       ensure
         @print_runtime_depth -= 1
         runtime = Time.now - started_at
         puts "  Finished all in #{sprintf("%.1f seconds", runtime)}"
-        puts DASH.timings.lines if @print_runtime_depth.zero? && DASH.timings.any?
+        finish_report(started_at, runtime) if @print_runtime_depth.zero? && DASH.timings.any?
+      end
+
+      # Trends, then the table, then the saved JSON. Each half is guarded on its own so a
+      # report that cannot be written still prints, and a table that cannot be compared is
+      # still a table — none of this is allowed to be why a deploy ends badly.
+      def finish_report(started_at, runtime)
+        run = nil
+
+        guarded_report do
+          run = report_run(started_at, runtime)
+          DASH.report.advice += report_trends(run)
+        end
+
+        puts DASH.report.lines
+
+        guarded_report { write_report(run) } if run
+      end
+
+      # What this invocation was, for the saved report and for the trend rules that
+      # compare it with the invocations before it.
+      def report_run(started_at, runtime)
+        {
+          command: [ command, subcommand ].compact.join(" "),
+          service: DASH.config.service, destination: DASH.config.destination, version: DASH.config.version,
+          started_at: started_at.getutc.iso8601, runtime: runtime.round(1),
+          status: @report_error ? "failed" : "succeeded",
+          error: @report_error && { class: @report_error.class.name, message: @report_error.message }
+        }.compact
+      end
+
+      def report_trends(run)
+        return [] unless DASH.config.report.advice?
+
+        history = Dash::Report::History.new(reports_directory, destination: DASH.config.destination)
+
+        Dash::Report::Trends.new(run.merge(phases: DASH.timings.to_h),
+          history: history.recent(DASH.config.report.history), ignore: DASH.config.report.ignore).findings
+      end
+
+      def write_report(run)
+        @report_path = Dash::Report::Writer.new(DASH.report,
+          run: run, keep: DASH.config.report.history, directory: reports_directory).write
+
+        puts "  Report written to #{@report_path}" if @report_path
+      end
+
+      def reports_directory
+        Dash::ProjectDirectory.join("reports")
+      end
+
+      # Summary numbers for the post-deploy hook, so a hook can page on a build that
+      # doubled or a warning that appeared without re-deriving any of it. Phases that did
+      # not run contribute nothing rather than a zero that reads as "instant".
+      def report_hook_details
+        guarded_report({}) do
+          {
+            build_runtime: phase_runtime(Dash::Report::Trends::BUILD_PHASE),
+            boot_runtime: phase_runtime(Dash::Report::Trends::BOOT_PHASE),
+            advice_count: DASH.report.advice.size.to_s,
+            advice_warnings: DASH.report.advice.count(&:warn?).to_s,
+            report_path: @report_path
+          }.compact
+        end
+      end
+
+      def phase_runtime(name)
+        DASH.timings.seconds_for(name)&.round(1)&.to_s
+      end
+
+      # Everything that happened before the first phase could be timed: requiring the gem,
+      # Zeitwerk, Thor parsing the command line, and building the config. It is the one row
+      # an operator cannot influence from deploy.yml, which is exactly why it has to be
+      # visible — a five-second startup is dash's problem, not theirs.
+      def record_startup_timing
+        DASH.timings.record "Startup (load, config)", Process.clock_gettime(Process::CLOCK_MONOTONIC) - Dash::PROCESS_STARTED_AT
+      end
+
+      # Advice about the Dockerfile, run once the build report is in so measured rules can
+      # name real seconds. Nothing here is allowed to end a deploy: a report is a courtesy
+      # printed next to the work, and the work already succeeded or failed on its own.
+      def analyze_report
+        guarded_report { DASH.report.analyze!(DASH.config) }
+      end
+
+      # `fallback` is what the caller gets when the report could not be produced, for the
+      # callers that need a value rather than a side effect.
+      def guarded_report(fallback = nil)
+        yield
+      rescue StandardError => e
+        say "Deploy report unavailable: #{e.class}: #{e.message}", :yellow
+        say e.backtrace.join("\n"), :yellow if ENV["VERBOSE"]
+        fallback
       end
 
       def timed(name, depth: 0, &block)
@@ -204,6 +303,10 @@ module Dash::Cli
       # in one `on(hosts)` sweep would leave the locks we did win in place, and
       # every retry would then collide with itself and wait out the timeout.
       def acquire_server_lock
+        timed("Acquire server lock") { acquire_server_lock_now }
+      end
+
+      def acquire_server_lock_now
         ensure_run_directory
 
         timeout = DASH.lock_wait_timeout
@@ -343,6 +446,10 @@ module Dash::Cli
       end
 
       def acquire_lock
+        timed("Acquire deploy lock") { acquire_lock_now }
+      end
+
+      def acquire_lock_now
         ensure_run_directory
 
         if DASH.lock_wait
@@ -470,10 +577,18 @@ module Dash::Cli
         instance_variable_get("@_invocations")[cli_class].pop
       end
 
+      # Every lock acquire wants the run directory to exist, but the sweep is idempotent
+      # and a process only needs it once per host - the deploy lock and the server lock
+      # were paying for it twice.
       def ensure_run_directory
-        on(DASH.hosts) do
+        pending = DASH.hosts.map(&:to_s) - DASH.run_directory_ensured_on
+        return if pending.empty?
+
+        on(pending) do
           execute(*DASH.server.ensure_run_directory)
         end
+
+        DASH.run_directory_ensured_on.concat(pending)
       end
 
       def with_env(env)

data/lib/dash/cli/build.rb

@@ -37,6 +37,9 @@ class Dash::Cli::Build < Dash::Cli::Base
       say "Building with uncommitted changes:\n #{uncommitted_changes}", :yellow
     end
 
+    parser = build_progress_parser
+    handler = handler_for(parser)
+
     forward_local_registry_port_for_remote_builder do
       with_env(DASH.config.builder.secrets) do
         run_locally do
@@ -60,11 +63,13 @@ class Dash::Cli::Build < Dash::Cli::Base
           push = DASH.builder.push(cli.options[:output], no_cache: cli.options[:no_cache])
 
           DASH.with_verbosity(:debug) do
-            Dir.chdir(DASH.config.builder.build_directory) { execute *push, env: DASH.builder.push_env }
+            Dir.chdir(DASH.config.builder.build_directory) { execute *push, env: DASH.builder.push_env, **handler }
           end
         end
       end
     end
+  ensure
+    record_build_report parser
   end
 
   desc "pull", "Pull app image from registry onto servers"
@@ -147,17 +152,66 @@ class Dash::Cli::Build < Dash::Cli::Base
       say
     end
 
+    parser = build_progress_parser
+    handler = handler_for(parser)
+
     with_env(DASH.config.builder.secrets) do
       run_locally do
         build = DASH.builder.push(cli.options[:output], tag_as_dirty: true, no_cache: cli.options[:no_cache])
         DASH.with_verbosity(:debug) do
-          execute(*build)
+          execute(*build, **handler)
         end
       end
     end
+  ensure
+    # `dev` builds the working directory even when `push` would clone, so the advice reads
+    # the Dockerfile here rather than in a clone that may not exist.
+    record_build_report parser, build_directory: "."
   end
 
   private
+    # Buildpacks print a total and nothing else, so there is nothing for the parser to
+    # read and no reason to attach it.
+    def build_progress_parser
+      Dash::Build::ProgressParser.new unless DASH.builder.pack?
+    end
+
+    def handler_for(parser)
+      parser ? { interaction_handler: parser } : {}
+    end
+
+    # Runs whether the build succeeded or failed: a partial report naming the step that
+    # broke is exactly what an operator wants from a failed build. Measurement must never
+    # be the reason a build fails, so nothing in here is allowed to raise.
+    def record_build_report(parser, build_directory: DASH.config.builder.build_directory)
+      return unless parser
+
+      guarded_report do
+        parser.finish
+        DASH.report.build = parser.result
+
+        say "Deploy report unavailable: #{parser.error.class}: #{parser.error.message}", :yellow if parser.error
+
+        # Inside a deploy the phase table prints these at the end and the deploy runs its
+        # own analysis once the image is delivered. Standalone, this is the only chance.
+        unless DASH.report.build_entry
+          print_build_report
+          DASH.report.analyze!(DASH.config, build_directory: build_directory)
+          puts DASH.report.advice_lines
+        end
+      end
+    end
+
+    # A standalone `dash build push` has no phase table to sit under, but a CI pipeline
+    # that splits build from deploy should still see where the build time went.
+    def print_build_report
+      rows = DASH.report.build_lines
+      return if rows.empty?
+
+      puts "  Build"
+      puts rows
+    end
+
     def connect_to_remote_host(remote_host)
       remote_uri = URI.parse(remote_host)
       if remote_uri.scheme == "ssh"
@@ -186,11 +240,13 @@ class Dash::Cli::Build < Dash::Cli::Base
       end
     end
 
+    # Audit, clean and pull share one round trip. validate_image keeps its own: folding it
+    # in would put the pull under validate_image's trailing `|| (echo ... && exit 1)`, and
+    # a failed pull would then report a missing service label.
     def pull_on_hosts(hosts)
       on(hosts) do
-        execute *DASH.auditor.record("Pulled image with version #{DASH.config.version}"), verbosity: :debug
-        execute *DASH.builder.clean, raise_on_non_zero_exit: false
-        execute *DASH.builder.pull
+        execute *DASH.auditor.record_then("Pulled image with version #{DASH.config.version}",
+          DASH.builder.clean_then_pull)
         execute *DASH.builder.validate_image
       end
     end

data/lib/dash/cli/doctor/config_checks.rb

@@ -2,7 +2,7 @@
 # that are visible in deploy.yml alone, so they still run when every host is unreachable.
 class Dash::Cli::Doctor::ConfigChecks
   def run
-    readiness_results
+    readiness_results + dockerfile_results
   end
 
   private
@@ -25,4 +25,39 @@ class Dash::Cli::Doctor::ConfigChecks
           "add a `healthcheck:` block, or opt out with `healthcheck: false`"
       end
     end
+
+    # The static half of the deploy report's advice: the same rules, without a build to
+    # measure against. `advice: false` is not consulted — it silences the block printed
+    # next to a deploy, and this check is one the operator asked for by name.
+    def dockerfile_results
+      dockerfile = DASH.config.builder.dockerfile
+      path = File.expand_path(dockerfile)
+
+      unless File.exist?(path)
+        return [ result(:dockerfile, dockerfile, :fail, "not found — `dash build push` fails with Missing #{dockerfile}") ]
+      end
+
+      findings = analyzer(dockerfile, path).findings
+      return [ result(:dockerfile, dockerfile, :ok, "no findings") ] if findings.empty?
+
+      findings.map { |finding| finding_result(finding) }
+    rescue StandardError => e
+      [ result(:dockerfile, dockerfile, :warn, "could not be analysed (#{e.class}: #{e.message})") ]
+    end
+
+    def analyzer(dockerfile, path)
+      Dash::Dockerfile::Analyzer.new \
+        document: Dash::Dockerfile::Parser.parse(File.read(path)),
+        path: dockerfile,
+        context_dir: File.expand_path(DASH.config.builder.context),
+        builder: DASH.config.builder,
+        ignore: DASH.config.report.ignore,
+        hadolint: DASH.config.report.hadolint?
+    end
+
+    # An informational finding is not a reason to hold up a deploy, so it reports as ok
+    # with its message intact — visible, but never the difference between ready and not.
+    def finding_result(finding)
+      result :dockerfile, finding.location, (finding.warn? ? :warn : :ok), "#{finding.message} [#{finding.rule}]"
+    end
 end