kamal-lint 0.1.0

data/lib/kamal/lint/checks/image_registry_mismatch.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class ImageRegistryMismatch < Check
+        id "image-registry-mismatch"
+        severity :error
+        since "2.0.0"
+        title "`image:` registry prefix doesn't match `builder.registry.server`"
+
+        # Docker Hub accepts unprefixed images (`myorg/myapp` resolves to
+        # `docker.io/myorg/myapp`), so we don't flag a missing prefix when the
+        # configured registry is Docker Hub under any of its canonical names.
+        DOCKER_HUB_HOSTS = %w[docker.io index.docker.io registry.hub.docker.com].freeze
+
+        def call
+          image = parsed["image"]
+          registry = parsed["registry"] || parsed.dig("builder", "registry") || {}
+          server = registry["server"] if registry.is_a?(Hash)
+          return [] unless image.is_a?(String) && server.is_a?(String) && !server.empty?
+
+          normalized_server = server.sub(%r{/+\z}, "")
+          return [] if DOCKER_HUB_HOSTS.include?(normalized_server)
+
+          prefix = "#{normalized_server}/"
+          return [] if image.start_with?(prefix)
+
+          [ finding(
+            message: "image `#{image}` does not include the configured registry `#{server}`; Kamal will push to the wrong registry",
+            line: context.line_for([ "image" ])
+          ) ]
+        end
+      end
+
+      Lint.registry.register(ImageRegistryMismatch)
+    end
+  end
+end

data/lib/kamal/lint/checks/kamal_secrets_not_gitignored.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class KamalSecretsNotGitignored < Check
+        id "kamal-secrets-not-gitignored"
+        severity :warning
+        since "2.0.0"
+        autofixable true
+        title ".kamal/secrets is not in .gitignore"
+
+        # We only flag when:
+        #   - a .kamal/secrets file exists (so there's something to leak), AND
+        #   - it is NOT covered by .gitignore (or .gitignore is missing).
+        def call
+          return [] unless File.exist?(context.secrets_path)
+          return [] if gitignored?
+
+          [ finding(
+            message: ".kamal/secrets exists but isn't ignored by .gitignore; you risk committing real secrets",
+            line: 1,
+            autofix: method(:apply_fix)
+          ) ]
+        end
+
+        def gitignored?
+          return false unless File.exist?(context.gitignore_path)
+
+          File.foreach(context.gitignore_path).any? do |line|
+            stripped = line.strip
+            next false if stripped.empty? || stripped.start_with?("#")
+
+            stripped == ".kamal/secrets" ||
+              stripped == "/.kamal/secrets" ||
+              stripped == ".kamal/*" ||
+              stripped == ".kamal/" ||
+              stripped == ".kamal"
+          end
+        end
+
+        def apply_fix(ctx)
+          path = ctx.gitignore_path
+          existing = File.exist?(path) ? File.read(path) : ""
+          existing = existing + "\n" unless existing.empty? || existing.end_with?("\n")
+          File.write(path, "#{existing}.kamal/secrets\n")
+          true
+        rescue => _e
+          false
+        end
+      end
+
+      Lint.registry.register(KamalSecretsNotGitignored)
+    end
+  end
+end

data/lib/kamal/lint/checks/missing_proxy_healthcheck.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class MissingProxyHealthcheck < Check
+        id "missing-proxy-healthcheck"
+        severity :warning
+        since "2.0.0"
+        title "`proxy:` block has no healthcheck — zero-downtime deploys may fail"
+
+        def call
+          proxy = parsed["proxy"]
+          return [] unless proxy.is_a?(Hash)
+          return [] if proxy.key?("healthcheck")
+
+          [ finding(
+            message: "proxy block has no `healthcheck:` configured; Kamal-proxy can't verify a new release before cutover",
+            line: context.line_for([ "proxy" ])
+          ) ]
+        end
+      end
+
+      Lint.registry.register(MissingProxyHealthcheck)
+    end
+  end
+end

data/lib/kamal/lint/checks/missing_service_name.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class MissingServiceName < Check
+        id "missing-service-name"
+        severity :error
+        since "2.0.0"
+        autofixable true
+        title "`service:` is required and missing"
+
+        def call
+          service = parsed["service"]
+          return [] if service.is_a?(String) && !service.strip.empty?
+
+          [ finding(
+            message: "`service:` is required; without it Kamal can't name the deployed container",
+            line: 1,
+            autofix: method(:apply_fix)
+          ) ]
+        end
+
+        def apply_fix(ctx)
+          file = ctx.file_for_finding
+          text = File.read(file)
+          parsed = YAML.safe_load(text, aliases: true) || {}
+          return false if parsed["service"].is_a?(String) && !parsed["service"].empty?
+
+          name = File.basename(ctx.working_dir).gsub(/[^A-Za-z0-9_-]/, "-")
+          return false if name.empty?
+
+          # Parse-and-dump so the fix composes safely with other autofixes
+          # that may also rewrite the file. The trade-off is that comments
+          # in the original YAML are lost — documented in the README.
+          File.write(file, YAML.dump({ "service" => name }.merge(parsed)))
+          true
+        rescue
+          false
+        end
+      end
+
+      Lint.registry.register(MissingServiceName)
+    end
+  end
+end

data/lib/kamal/lint/checks/registry_without_explicit_server.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class RegistryWithoutExplicitServer < Check
+        id "registry-without-explicit-server"
+        severity :warning
+        since "2.0.0"
+        title "`registry.server` not set; image will default to Docker Hub"
+
+        def call
+          registry = parsed["registry"] || parsed.dig("builder", "registry")
+          return [] unless registry.is_a?(Hash)
+
+          server = registry["server"]
+          return [] if server.is_a?(String) && !server.empty?
+
+          image = parsed["image"]
+          # If image already has an explicit registry prefix (host with a "."),
+          # this is intentional and we don't warn.
+          if image.is_a?(String) && image.include?("/")
+            first_segment = image.split("/", 2).first
+            return [] if first_segment.include?(".") || first_segment.include?(":")
+          end
+
+          [ finding(
+            message: "registry has no `server:` set; Kamal will push/pull from Docker Hub by default",
+            line: context.line_for([ "registry" ]) || context.line_for([ "registry", "username" ])
+          ) ]
+        end
+      end
+
+      Lint.registry.register(RegistryWithoutExplicitServer)
+    end
+  end
+end

data/lib/kamal/lint/checks/role_hosts_empty.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../servers_helper"
+
+module Kamal
+  module Lint
+    module Checks
+      class RoleHostsEmpty < Check
+        id "role-hosts-empty"
+        severity :error
+        since "2.0.0"
+        title "A role under `servers:` has no hosts"
+
+        def call
+          servers = parsed["servers"]
+          return [] unless servers.is_a?(Hash)
+
+          findings = []
+          servers.each do |role, entry|
+            hosts = ServersHelper.extract_hosts(entry)
+            next unless hosts.empty?
+
+            findings << finding(
+              message: "role `#{role}` under `servers` has no hosts; deploys to this role will silently no-op",
+              line: context.line_for([ "servers", role.to_s ])
+            )
+          end
+          findings
+        end
+      end
+
+      Lint.registry.register(RoleHostsEmpty)
+    end
+  end
+end

data/lib/kamal/lint/checks/secret_in_env_clear.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class SecretInEnvClear < Check
+        id "secret-in-env-clear"
+        severity :warning
+        since "2.0.0"
+        title "Value in `env.clear` looks like a secret"
+
+        SECRET_KEY_PATTERN = /(\A|_)(KEY|SECRET|TOKEN|PASSWORD|PWD|CREDENTIALS?)(_|\z)/i
+
+        def call
+          findings = []
+          scan_env(parsed["env"], [ "env" ], findings)
+          (parsed["accessories"] || {}).each do |name, accessory|
+            scan_env(accessory["env"], [ "accessories", name, "env" ], findings) if accessory.is_a?(Hash)
+          end
+          findings
+        end
+
+        private
+
+        def scan_env(env, prefix, findings)
+          return unless env.is_a?(Hash)
+
+          clear = env["clear"]
+          return unless clear.is_a?(Hash)
+
+          clear.each do |key, _value|
+            next unless key.is_a?(String) && key.match?(SECRET_KEY_PATTERN)
+
+            findings << finding(
+              message: "env.clear contains `#{key}` which looks like a secret; move it to env.secret + .kamal/secrets",
+              line: context.line_for(prefix + [ "clear", key ])
+            )
+          end
+        end
+      end
+
+      Lint.registry.register(SecretInEnvClear)
+    end
+  end
+end

data/lib/kamal/lint/checks/secret_not_declared.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class SecretNotDeclared < Check
+        id "secret-not-declared"
+        severity :error
+        since "2.0.0"
+        title "env.secret references a key not declared in .kamal/secrets"
+
+        def call
+          findings = []
+          declared = context.secrets
+
+          referenced_secret_keys.each do |path, name|
+            next if declared.include?(name)
+
+            findings << finding(
+              message: "env.secret references `#{name}` but it isn't declared in .kamal/secrets",
+              line: context.line_for(path)
+            )
+          end
+
+          findings
+        end
+
+        private
+
+        def referenced_secret_keys
+          refs = []
+          collect_secrets(parsed["env"], [ "env" ], refs)
+          (parsed["accessories"] || {}).each do |name, accessory|
+            next unless accessory.is_a?(Hash)
+
+            collect_secrets(accessory["env"], [ "accessories", name, "env" ], refs)
+          end
+          refs
+        end
+
+        def collect_secrets(env_block, prefix, refs)
+          return unless env_block.is_a?(Hash)
+
+          list = env_block["secret"]
+          return unless list.is_a?(Array)
+
+          list.each_with_index do |name, idx|
+            next unless name.is_a?(String)
+
+            refs << [ prefix + [ "secret", idx.to_s ], name ]
+          end
+        end
+      end
+
+      Lint.registry.register(SecretNotDeclared)
+    end
+  end
+end

data/lib/kamal/lint/checks/ssl_without_host.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class SslWithoutHost < Check
+        id "ssl-without-host"
+        severity :error
+        since "2.0.0"
+        title "SSL enabled without a host configured"
+
+        def call
+          proxy = parsed["proxy"]
+          return [] unless proxy.is_a?(Hash)
+
+          ssl_enabled = proxy["ssl"] == true
+          return [] unless ssl_enabled
+
+          host = proxy["host"]
+          hosts = proxy["hosts"]
+
+          host_set = (host.is_a?(String) && !host.empty?) ||
+                     (hosts.is_a?(Array) && hosts.any? { |h| h.is_a?(String) && !h.empty? })
+
+          return [] if host_set
+
+          [ finding(
+            message: "proxy.ssl: true requires `host:` (or `hosts:`) to be set for automatic Let's Encrypt provisioning",
+            line: context.line_for([ "proxy", "ssl" ]) || context.line_for([ "proxy" ])
+          ) ]
+        end
+      end
+
+      Lint.registry.register(SslWithoutHost)
+    end
+  end
+end

data/lib/kamal/lint/checks/traefik_legacy_keys.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class TraefikLegacyKeys < Check
+        id "traefik-legacy-keys"
+        severity :warning
+        since "2.0.0"
+        autofixable true
+        title "Kamal 1.x `traefik:` keys present (use `proxy:` in Kamal 2+)"
+
+        def call
+          return [] unless parsed.key?("traefik")
+
+          [ finding(
+            message: "`traefik:` block is Kamal 1.x legacy and is ignored in Kamal 2+; use `proxy:` instead",
+            line: context.line_for([ "traefik" ]),
+            autofix: method(:apply_fix)
+          ) ]
+        end
+
+        def apply_fix(ctx)
+          file = ctx.file_for_finding
+          text = File.read(file)
+          parsed = YAML.safe_load(text, aliases: true) || {}
+          return false unless parsed.is_a?(Hash) && parsed.key?("traefik")
+
+          traefik = parsed.delete("traefik") || {}
+          proxy = parsed["proxy"] || {}
+
+          # Conservative translation:
+          # - traefik.host           → proxy.host
+          # - traefik.ssl_redirect   → proxy.ssl: true (Kamal 2 handles SSL via proxy.ssl)
+          # - traefik.args.entryPoints.address: ":<port>" → proxy.app_port: <port>
+          if (host = traefik["host"]) && !proxy["host"]
+            proxy["host"] = host
+          end
+          if traefik["ssl_redirect"] == true || traefik.dig("args", "entrypoints.websecure.address")
+            proxy["ssl"] = true unless proxy.key?("ssl")
+          end
+          if (addr = traefik.dig("args", "entrypoints.web.address")) && addr.is_a?(String)
+            port = addr.scan(/\d+/).first
+            proxy["app_port"] = port.to_i if port && !proxy.key?("app_port")
+          end
+
+          parsed["proxy"] = proxy unless proxy.empty?
+          File.write(file, YAML.dump(parsed))
+          true
+        rescue => _e
+          false
+        end
+      end
+
+      Lint.registry.register(TraefikLegacyKeys)
+    end
+  end
+end

data/lib/kamal/lint/cli.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Kamal
+  module Lint
+    class CLI < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      class_option :config_file, aliases: "-c", type: :string,
+        default: "config/deploy.yml",
+        desc: "Path to the Kamal deploy.yml"
+      class_option :destination, aliases: "-d", type: :string,
+        desc: "Destination override (e.g. production → config/deploy.production.yml)"
+      class_option :format, aliases: "-f", type: :string, default: "human",
+        enum: %w[human json github],
+        desc: "Output format"
+      class_option :fail_on, type: :string, default: "warning",
+        enum: %w[error warning info],
+        desc: "Minimum severity that causes a non-zero exit code"
+      class_option :fix, type: :boolean, default: false,
+        desc: "Apply safe autofixes in-place"
+      class_option :"kamal-version", type: :string,
+        desc: "Override detected Kamal version"
+      class_option :"include-kamal-errors", type: :boolean, default: false,
+        desc: "Also surface errors from Kamal's own loader (off by default; use `kamal config` for that)"
+      class_option :no_color, type: :boolean, default: false,
+        desc: "Disable colored output"
+
+      desc "lint", "Lint the Kamal deploy.yml (default command)"
+      def lint
+        runner = Runner.new(
+          config_file: options[:config_file],
+          destination: options[:destination],
+          kamal_version: options[:"kamal-version"],
+          fix: options[:fix],
+          include_kamal_errors: options[:"include-kamal-errors"]
+        )
+        result = runner.call
+        formatter = build_formatter(options[:format], options[:no_color])
+        formatter.render(result)
+        formatter.render_fix_summary(result) if options[:fix]
+        exit(result.exit_code(fail_on: options[:fail_on].to_sym))
+      rescue ConfigNotFoundError => e
+        warn "kamal-lint: #{e.message}"
+        exit(2)
+      end
+
+      default_task :lint
+
+      desc "list-checks", "List all registered checks"
+      def list_checks
+        registry = Lint.registry
+        format = options[:format]
+
+        if format == "json"
+          require "json"
+          payload = registry.all.map do |check|
+            {
+              id: check.id,
+              severity: check.severity.to_s,
+              title: check.title,
+              since: check.since,
+              until_version: check.until_version,
+              autofixable: check.autofixable
+            }
+          end
+          puts JSON.pretty_generate(payload)
+        else
+          puts "#{"ID".ljust(38)} #{"SEVERITY".ljust(9)} #{"SINCE".ljust(8)} TITLE"
+          puts "-" * 110
+          registry.all.each do |check|
+            line = [
+              check.id.to_s.ljust(38),
+              check.severity.to_s.ljust(9),
+              (check.since || "—").to_s.ljust(8),
+              check.title.to_s
+            ].join(" ")
+            line += " (autofixable)" if check.autofixable
+            puts line
+          end
+          puts
+          puts "Total: #{registry.all.size} checks"
+        end
+      end
+
+      desc "version", "Show version"
+      def version
+        puts "kamal-lint #{Kamal::Lint::VERSION}"
+      end
+
+      map "--version" => :version
+      map "-v" => :version
+
+      no_commands do
+        def build_formatter(name, no_color)
+          klass = FORMATTERS.fetch(name) { raise ArgumentError, "unknown formatter: #{name}" }
+          if klass == Formatters::Human
+            klass.new(color: !no_color && $stdout.tty?)
+          else
+            klass.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kamal/lint/finding.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    Finding = Struct.new(
+      :check_id,
+      :severity,
+      :message,
+      :file,
+      :line,
+      :column,
+      :autofix,
+      keyword_init: true
+    ) do
+      def autofixable?
+        !autofix.nil?
+      end
+
+      def to_h
+        {
+          check: check_id,
+          severity: severity.to_s,
+          message: message,
+          file: file,
+          line: line,
+          column: column,
+          autofixable: autofixable?
+        }
+      end
+    end
+  end
+end

data/lib/kamal/lint/formatters/github.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Formatters
+      # GitHub Actions workflow command output.
+      # See: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+      class Github
+        LEVEL = {
+          error: "error",
+          warning: "warning",
+          info: "notice"
+        }.freeze
+
+        def initialize(io: $stdout)
+          @io = io
+        end
+
+        def render(result)
+          result.findings.each do |finding|
+            level = LEVEL[finding.severity] || "notice"
+            attrs = {
+              file: finding.file,
+              line: finding.line,
+              col: finding.column,
+              title: "kamal-lint: #{finding.check_id}"
+            }.compact
+
+            attr_str = attrs.map { |k, v| "#{k}=#{escape_property(v.to_s)}" }.join(",")
+            message = escape_message(finding.message)
+            @io.puts "::#{level} #{attr_str}::#{message}"
+          end
+        end
+
+        def render_fix_summary(result)
+          return if result.fixed.empty?
+
+          result.fixed.each do |finding|
+            @io.puts "::notice file=#{finding.file},title=kamal-lint autofix::Fixed #{finding.check_id}"
+          end
+        end
+
+        private
+
+        def escape_message(value)
+          value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+        end
+
+        def escape_property(value)
+          value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A").gsub(":", "%3A").gsub(",", "%2C")
+        end
+      end
+    end
+  end
+end