kamal-lint 0.1.0

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Formatters
+      class Human
+        COLORS = {
+          reset: "\e[0m",
+          bold: "\e[1m",
+          dim: "\e[2m",
+          red: "\e[31m",
+          yellow: "\e[33m",
+          green: "\e[32m",
+          blue: "\e[34m",
+          magenta: "\e[35m",
+          cyan: "\e[36m",
+          gray: "\e[90m"
+        }.freeze
+
+        SEVERITY_GLYPH = {
+          error: "✖",
+          warning: "⚠",
+          info: "•"
+        }.freeze
+
+        SEVERITY_COLOR = {
+          error: :red,
+          warning: :yellow,
+          info: :blue
+        }.freeze
+
+        def initialize(io: $stdout, color: nil)
+          @io = io
+          @color = color.nil? ? io.tty? : color
+        end
+
+        def render(result)
+          render_header(result)
+
+          if result.findings.empty?
+            @io.puts c(:green, "  ✓ No issues found.")
+            return
+          end
+
+          result.findings
+            .sort_by { |f| [ SEVERITIES.index(f.severity), f.line || 0 ] }
+            .each { |finding| render_finding(finding) }
+
+          render_summary(result)
+        end
+
+        def render_fix_summary(result)
+          return if result.fixed.empty?
+
+          @io.puts
+          @io.puts c(:bold, "Applied autofixes:")
+          result.fixed.each do |finding|
+            @io.puts "  #{c(:green, "✓")} [#{finding.check_id}] #{finding.message}"
+          end
+        end
+
+        private
+
+        def render_header(result)
+          version = Kamal::Lint::VERSION
+          kamal = result.context.kamal_version || "?"
+          @io.puts "#{c(:bold, "kamal-lint")} #{c(:dim, version)} · kamal #{c(:cyan, kamal)} detected"
+          if (dest = result.context.destination)
+            @io.puts "  destination: #{c(:cyan, dest)}"
+          end
+          @io.puts "  config:      #{c(:cyan, result.context.file_for_finding)}"
+          @io.puts
+        end
+
+        def render_finding(finding)
+          loc = "#{finding.file}:#{finding.line || "?"}"
+          glyph = SEVERITY_GLYPH[finding.severity] || "?"
+          color = SEVERITY_COLOR[finding.severity] || :gray
+          sev = finding.severity.to_s.ljust(7)
+          fix_hint = finding.autofixable? ? c(:dim, " (autofixable)") : ""
+
+          @io.puts "#{c(color, glyph)} #{c(:bold, sev)} #{c(:gray, loc)}#{fix_hint}"
+          @io.puts "    #{finding.message}"
+          @io.puts "    #{c(:dim, "[#{finding.check_id}]")}"
+          @io.puts
+        end
+
+        def render_summary(result)
+          errors = result.errors.size
+          warnings = result.warnings.size
+          infos = result.infos.size
+          autofixable = result.findings.count(&:autofixable?)
+
+          parts = []
+          parts << "#{c(:red, errors.to_s)} error#{plural(errors)}" if errors > 0
+          parts << "#{c(:yellow, warnings.to_s)} warning#{plural(warnings)}" if warnings > 0
+          parts << "#{c(:blue, infos.to_s)} info" if infos > 0
+          parts << "#{c(:dim, "#{autofixable} autofixable")}" if autofixable > 0
+
+          @io.puts c(:bold, "Summary: ") + parts.join(", ")
+        end
+
+        def plural(n)
+          n == 1 ? "" : "s"
+        end
+
+        def c(color, text)
+          return text unless @color
+
+          code = COLORS[color]
+          return text unless code
+
+          "#{code}#{text}#{COLORS[:reset]}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kamal
+  module Lint
+    module Formatters
+      class Json
+        def initialize(io: $stdout)
+          @io = io
+        end
+
+        def render(result)
+          payload = {
+            kamal_lint_version: Kamal::Lint::VERSION,
+            kamal_version: result.context.kamal_version,
+            file: result.context.file_for_finding,
+            destination: result.context.destination,
+            findings: result.findings.map(&:to_h),
+            summary: {
+              errors: result.errors.size,
+              warnings: result.warnings.size,
+              infos: result.infos.size,
+              autofixable: result.findings.count(&:autofixable?)
+            }
+          }
+          @io.puts JSON.pretty_generate(payload)
+        end
+
+        def render_fix_summary(result)
+          return if result.fixed.empty?
+
+          @io.puts JSON.pretty_generate(fixed: result.fixed.map(&:to_h))
+        end
+      end
+    end
+  end
+end

data/lib/kamal/lint/kamal_version.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Kamal
+  module Lint
+    # Detect the installed Kamal version from (in priority order):
+    #   1. explicit override
+    #   2. Bundler.locked_gems
+    #   3. Gem.loaded_specs / Gem::Specification
+    #   4. shell out to `kamal version`
+    module KamalVersion
+      module_function
+
+      def detect(override: nil)
+        return normalize(override) if override
+
+        from_bundler || from_loaded_specs || from_shell
+      end
+
+      def from_bundler
+        return nil unless defined?(Bundler)
+
+        locked = Bundler.locked_gems&.specs&.find { |s| s.name == "kamal" }
+        locked&.version&.to_s
+      rescue Bundler::GemfileNotFound
+        nil
+      rescue => _e
+        nil
+      end
+
+      def from_loaded_specs
+        spec = Gem.loaded_specs["kamal"] if defined?(Gem) && Gem.respond_to?(:loaded_specs)
+        return spec.version.to_s if spec
+
+        if defined?(Gem::Specification)
+          found = Gem::Specification.find_all_by_name("kamal").max_by(&:version)
+          return found&.version&.to_s
+        end
+
+        nil
+      rescue => _e
+        nil
+      end
+
+      def from_shell
+        out, _err, status = Open3.capture3("kamal", "version")
+        return nil unless status.success?
+
+        out.strip.split.last
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def normalize(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        value.to_s.strip
+      end
+    end
+  end
+end

data/lib/kamal/lint/loader.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "psych"
+require "pathname"
+require "yaml"
+
+module Kamal
+  module Lint
+    # Holds all the data a check needs to inspect a single Kamal config:
+    # the parsed YAML, the source lines, helper to look up source lines for a
+    # given path (for finding line numbers), the destination override, the
+    # secrets file contents, and a flag indicating whether Kamal's own loader
+    # rejected the config (in which case some checks are skipped to avoid
+    # cascading false positives).
+    Context = Struct.new(
+      :config_file,
+      :destination,
+      :working_dir,
+      :parsed,
+      :base_parsed,
+      :override_parsed,
+      :source_lines,
+      :line_index,
+      :secrets,
+      :secrets_path,
+      :gitignore_path,
+      :kamal_version,
+      :kamal_loaded,
+      :kamal_load_error,
+      keyword_init: true
+    ) do
+      def file_for_finding
+        return config_file unless destination
+
+        override_path = override_file
+        File.exist?(override_path) ? override_path : config_file
+      end
+
+      def override_file
+        File.join(File.dirname(config_file), "deploy.#{destination}.yml")
+      end
+
+      def line_for(path)
+        line_index[Array(path).join(".")]
+      end
+    end
+
+    module Loader
+      module_function
+
+      def load(config_file:, destination: nil, kamal_version: nil)
+        raise ConfigNotFoundError, "Config file not found: #{config_file}" unless File.exist?(config_file)
+
+        working_dir = Pathname.new(config_file).realpath.dirname.dirname.to_s
+        # If config_file is at config/deploy.yml inside a project, working_dir = project root.
+        # If the user pointed somewhere else, fall back to its parent dir's parent.
+
+        base_text = File.read(config_file)
+        base_parsed = safe_parse_yaml(base_text)
+        source_lines = base_text.lines
+
+        override_parsed = nil
+        if destination
+          override_path = File.join(File.dirname(config_file), "deploy.#{destination}.yml")
+          if File.exist?(override_path)
+            override_parsed = safe_parse_yaml(File.read(override_path))
+            source_lines = File.read(override_path).lines
+          end
+        end
+
+        merged = override_parsed ? deep_merge(base_parsed, override_parsed) : base_parsed
+
+        line_index = build_line_index(base_text)
+        secrets_path = File.join(working_dir, ".kamal", "secrets")
+        gitignore_path = File.join(working_dir, ".gitignore")
+        secrets_keys = SecretsFile.read_keys(secrets_path)
+
+        loaded = true
+        load_error = nil
+        begin
+          # Run Kamal's own loader for parse-level validation. We don't use the
+          # returned object — we keep working off the parsed Hash so we can
+          # report line numbers — but we surface Kamal's own errors as findings.
+          require "kamal"
+          Dir.chdir(working_dir) do
+            Kamal::Configuration.create_from(
+              config_file: Pathname.new(config_file),
+              destination: destination,
+              version: "kamal-lint"
+            )
+          end
+        rescue => e
+          loaded = false
+          load_error = e
+        end
+
+        Context.new(
+          config_file: config_file,
+          destination: destination,
+          working_dir: working_dir,
+          parsed: merged || {},
+          base_parsed: base_parsed || {},
+          override_parsed: override_parsed,
+          source_lines: source_lines,
+          line_index: line_index,
+          secrets: secrets_keys,
+          secrets_path: secrets_path,
+          gitignore_path: gitignore_path,
+          kamal_version: kamal_version || KamalVersion.detect,
+          kamal_loaded: loaded,
+          kamal_load_error: load_error
+        )
+      end
+
+      def safe_parse_yaml(text)
+        result = YAML.safe_load(text, aliases: true, permitted_classes: [ Symbol ])
+        result.is_a?(Hash) ? result : {}
+      rescue Psych::SyntaxError
+        {}
+      end
+
+      def deep_merge(base, override)
+        return override unless base.is_a?(Hash) && override.is_a?(Hash)
+
+        result = base.dup
+        override.each do |k, v|
+          result[k] = if result[k].is_a?(Hash) && v.is_a?(Hash)
+            deep_merge(result[k], v)
+          else
+            v
+          end
+        end
+        result
+      end
+
+      # Build a mapping from dot-path ("env.secret") to source line numbers.
+      # Walks the Psych AST.
+      def build_line_index(text)
+        index = {}
+        stream = Psych.parse_stream(text)
+        stream.children.each do |doc|
+          walk_node(doc.root, [], index)
+        end
+        index
+      rescue Psych::SyntaxError
+        index
+      end
+
+      def walk_node(node, path, index)
+        case node
+        when Psych::Nodes::Mapping
+          node.children.each_slice(2) do |key_node, value_node|
+            next unless key_node && value_node
+
+            key = key_node.value
+            new_path = path + [ key ]
+            index[new_path.join(".")] ||= key_node.start_line + 1
+            walk_node(value_node, new_path, index)
+          end
+        when Psych::Nodes::Sequence
+          node.children.each_with_index do |child, idx|
+            new_path = path + [ idx.to_s ]
+            # Index the position itself so checks can find sequence elements
+            # by ordinal (e.g. "env.secret.0").
+            index[new_path.join(".")] ||= child.start_line + 1
+            walk_node(child, new_path, index)
+          end
+        when Psych::Nodes::Scalar
+          # Scalars at non-root locations need no further indexing; their
+          # parent already wrote the line for them.
+        end
+      end
+    end
+  end
+end

data/lib/kamal/lint/registry.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    class Registry
+      def self.default
+        @default ||= new
+      end
+
+      def initialize
+        @checks = []
+      end
+
+      def register(check_class)
+        @checks << check_class unless @checks.include?(check_class)
+        check_class
+      end
+
+      def all
+        @checks.dup
+      end
+
+      def applicable_to(kamal_version)
+        @checks.select { |c| c.applies_to?(kamal_version) }
+      end
+
+      def find(id)
+        @checks.find { |c| c.id == id }
+      end
+    end
+  end
+end

data/lib/kamal/lint/runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    Result = Struct.new(:findings, :context, :fixed, keyword_init: true) do
+      def errors
+        findings.select { |f| f.severity == :error }
+      end
+
+      def warnings
+        findings.select { |f| f.severity == :warning }
+      end
+
+      def infos
+        findings.select { |f| f.severity == :info }
+      end
+
+      def empty?
+        findings.empty?
+      end
+
+      def exit_code(fail_on: :error)
+        threshold = SEVERITIES.index(fail_on.to_sym)
+        worst = findings.map { |f| SEVERITIES.index(f.severity) }.compact.min
+        return 0 if worst.nil?
+
+        worst <= threshold ? 1 : 0
+      end
+    end
+
+    class Runner
+      def initialize(config_file:, destination: nil, kamal_version: nil,
+        registry: Lint.registry, fix: false, include_kamal_errors: false)
+        @config_file = config_file
+        @destination = destination
+        @kamal_version_override = kamal_version
+        @registry = registry
+        @fix = fix
+        @include_kamal_errors = include_kamal_errors
+      end
+
+      def call
+        context = load_context
+        findings = collect_findings(context)
+
+        fixed = @fix ? apply_autofixes(findings, context) : []
+
+        if @fix && !fixed.empty?
+          context = load_context
+          findings = collect_findings(context)
+        end
+
+        Result.new(findings: findings, context: context, fixed: fixed)
+      end
+
+      private
+
+      def load_context
+        Loader.load(
+          config_file: @config_file,
+          destination: @destination,
+          kamal_version: @kamal_version_override
+        )
+      end
+
+      def collect_findings(context)
+        findings = []
+
+        if @include_kamal_errors && context.kamal_load_error
+          findings << kamal_parse_error_finding(context)
+        end
+
+        @registry.applicable_to(context.kamal_version).each do |check_class|
+          findings.concat(Array(check_class.new(context).call))
+        end
+
+        findings
+      end
+
+      def kamal_parse_error_finding(context)
+        Finding.new(
+          check_id: "kamal-parse-error",
+          severity: :error,
+          message: "kamal could not load this config: #{context.kamal_load_error.message}",
+          file: context.file_for_finding,
+          line: 1,
+          column: 1,
+          autofix: nil
+        )
+      end
+
+      def apply_autofixes(findings, context)
+        applied = []
+        findings.select(&:autofixable?).each do |finding|
+          ok = finding.autofix.call(context)
+          applied << finding if ok
+        end
+        applied
+      end
+    end
+  end
+end

data/lib/kamal/lint/secrets_file.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    # Reads .kamal/secrets (shell-style KEY=value, with optional `export` prefix
+    # and `#` comments). Returns the set of declared keys. We don't expand or
+    # substitute — we only care whether a name is declared.
+    module SecretsFile
+      module_function
+
+      def read_keys(path)
+        return [] unless path && File.exist?(path)
+
+        keys = []
+        File.foreach(path) do |raw|
+          line = raw.strip
+          next if line.empty?
+          next if line.start_with?("#")
+
+          line = line.sub(/\Aexport\s+/, "")
+          name, _eq, _value = line.partition("=")
+          name = name.strip
+          keys << name unless name.empty?
+        end
+        keys.uniq
+      end
+    end
+  end
+end

data/lib/kamal/lint/servers_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    # Helpers for walking `servers:` in its various shapes:
+    #
+    #   servers: [host1, host2]                            → implicit "web" role
+    #   servers: { web: [...], workers: [...] }            → role => hosts
+    #   servers: { web: { hosts: [...], cmd: ..., ... } }  → role => expanded
+    module ServersHelper
+      module_function
+
+      def role_names(servers)
+        case servers
+        when Array
+          [ "web" ]
+        when Hash
+          servers.keys.map(&:to_s)
+        else
+          []
+        end
+      end
+
+      def hosts_for_role(servers, role)
+        case servers
+        when Array
+          role == "web" ? servers.dup : []
+        when Hash
+          entry = servers[role] || servers[role.to_sym]
+          extract_hosts(entry)
+        else
+          []
+        end
+      end
+
+      def all_hosts(servers)
+        case servers
+        when Array
+          servers.dup
+        when Hash
+          servers.values.flat_map { |v| extract_hosts(v) }
+        else
+          []
+        end
+      end
+
+      def extract_hosts(entry)
+        case entry
+        when Array
+          entry
+        when Hash
+          hosts = entry["hosts"] || entry[:hosts] || []
+          hosts.is_a?(Array) ? hosts : [ hosts ].compact
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/kamal/lint/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    VERSION = "0.1.0"
+  end
+end

data/lib/kamal/lint.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "lint/version"
+
+module Kamal
+  module Lint
+    SEVERITIES = %i[error warning info].freeze
+
+    class Error < StandardError; end
+
+    class ConfigNotFoundError < Error; end
+
+    def self.registry
+      Registry.default
+    end
+
+    def self.formatters
+      FORMATTERS
+    end
+  end
+end
+
+require_relative "lint/finding"
+require_relative "lint/check"
+require_relative "lint/registry"
+require_relative "lint/secrets_file"
+require_relative "lint/servers_helper"
+require_relative "lint/loader"
+require_relative "lint/kamal_version"
+require_relative "lint/runner"
+
+require_relative "lint/formatters/human"
+require_relative "lint/formatters/json"
+require_relative "lint/formatters/github"
+
+module Kamal
+  module Lint
+    FORMATTERS = {
+      "human" => Formatters::Human,
+      "json" => Formatters::Json,
+      "github" => Formatters::Github
+    }.freeze
+  end
+end
+
+require_relative "lint/checks/secret_not_declared"
+require_relative "lint/checks/accessory_role_undefined"
+require_relative "lint/checks/role_hosts_empty"
+require_relative "lint/checks/image_registry_mismatch"
+require_relative "lint/checks/builder_registry_secret_undeclared"
+require_relative "lint/checks/ssl_without_host"
+require_relative "lint/checks/empty_web_role"
+require_relative "lint/checks/traefik_legacy_keys"
+require_relative "lint/checks/boot_limit_exceeds_hosts"
+require_relative "lint/checks/accessory_placement_missing"
+require_relative "lint/checks/missing_service_name"
+require_relative "lint/checks/kamal_secrets_not_gitignored"
+require_relative "lint/checks/secret_in_env_clear"
+require_relative "lint/checks/missing_proxy_healthcheck"
+require_relative "lint/checks/accessory_image_latest"
+require_relative "lint/checks/registry_without_explicit_server"
+
+require_relative "lint/cli"