lumin 0.1.0

data/lib/lumin/cache.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "cache_manifest"
+require_relative "registry"
+require_relative "source_snapshot"
+require_relative "version"
+
+module Lumin
+  class Cache
+    PathEntry = CacheManifest::PathEntry
+
+    MANIFEST = "manifest".freeze
+    LOCK_FILE = "manifest.lock".freeze
+    MANIFEST_VERSION = CacheManifest::VERSION
+    LEGACY_DIRECTORY_PATTERN = /\A[0-9a-f]{2}\z/
+    MANIFEST_TEMPORARY_PATTERN = /\A#{Regexp.escape(MANIFEST)}\.\d+\.tmp\z/
+
+    attr_reader :directory
+
+    def self.default_directory
+      base = ENV["XDG_CACHE_HOME"]
+      base = File.join(Dir.home, ".cache") if base.nil? || base.empty?
+      File.join(base, "lumin")
+    end
+
+    def initialize(config:, registry: Registry, directory: self.class.default_directory)
+      @config = config
+      @registry = registry
+      @directory = File.expand_path(directory)
+      @environment_digest = build_environment_digest
+      @manifest = nil
+      @pending_paths = {}
+      @pending_offenses = {}
+    end
+
+    def fetch(path, source = nil)
+      expanded_path = File.expand_path(path)
+      entry = @pending_paths.fetch(expanded_path) { manifest.paths[expanded_path] }
+      if valid_entry?(entry, path)
+        cached = cached_offenses(entry.key)
+        return rebase(cached, path) if cached
+      end
+      return unless source
+
+      cached = cached_offenses(key(source))
+      rebase(cached, path) if cached
+    end
+
+    def put(path:, offenses:, source: nil, content_digest: nil, fingerprint: nil)
+      current_fingerprint = SourceSnapshot.fingerprint(path)
+      return false if fingerprint && fingerprint != current_fingerprint
+
+      cache_key = key_for_digest(content_digest || digest_source(source))
+      @pending_offenses[cache_key] = offenses
+      @pending_paths[File.expand_path(path)] = PathEntry.new(
+        fingerprint: current_fingerprint,
+        environment_digest: @environment_digest,
+        key: cache_key
+      )
+      offenses
+    end
+
+    def flush
+      return false if @pending_paths.empty?
+
+      with_lock do
+        merged = merge_pending(CacheManifest.load(manifest_path))
+        compacted = compact(merged)
+        atomic_write(manifest_path) { |file| file.write(CacheManifest.serialize(compacted)) }
+        remove_legacy_entries
+        @manifest = compacted
+        @pending_paths.clear
+        @pending_offenses.clear
+      end
+      true
+    end
+
+    def clear
+      with_lock do
+        FileUtils.rm_f(manifest_path)
+        remove_legacy_entries
+        @manifest = CacheManifest.empty
+        @pending_paths.clear
+        @pending_offenses.clear
+      end
+      true
+    end
+
+    def key(source)
+      key_for_digest(Digest::SHA256.hexdigest(source))
+    end
+
+    private
+
+    def key_for_digest(content_digest)
+      Digest::SHA256.hexdigest(content_digest + @environment_digest)
+    end
+
+    def digest_source(source)
+      raise ArgumentError, "source or content_digest is required" unless source
+
+      Digest::SHA256.hexdigest(source)
+    end
+
+    def build_environment_digest
+      enabled = @config.enabled_rules(@registry).map(&:first).sort.join("\0")
+      Digest::SHA256.hexdigest([@config.digest, VERSION, enabled].join("\0"))
+    end
+
+    def manifest
+      @manifest ||= CacheManifest.load(manifest_path)
+    end
+
+    def merge_pending(latest)
+      paths = latest.paths.dup
+      @pending_paths.each do |path, entry|
+        paths[path] = entry if current_fingerprint?(path, entry.fingerprint)
+      end
+      CacheManifest::Contents.new(paths: paths, offenses: latest.offenses.merge(@pending_offenses))
+    end
+
+    def compact(data)
+      paths = data.paths.select do |path, entry|
+        data.offenses.key?(entry.key) && current_fingerprint?(path, entry.fingerprint)
+      end
+      referenced_keys = paths.each_value.to_h { |entry| [entry.key, true] }
+      offenses = data.offenses.select { |cache_key, _entries| referenced_keys.key?(cache_key) }
+      CacheManifest::Contents.new(paths: paths, offenses: offenses)
+    end
+
+    def valid_entry?(entry, path)
+      entry.is_a?(PathEntry) &&
+        entry.environment_digest == @environment_digest &&
+        current_fingerprint?(path, entry.fingerprint)
+    end
+
+    def current_fingerprint?(path, fingerprint)
+      SourceSnapshot.fingerprint(path) == fingerprint
+    rescue ArgumentError, SystemCallError
+      false
+    end
+
+    def cached_offenses(cache_key)
+      @pending_offenses.fetch(cache_key) { manifest.offenses[cache_key] }
+    end
+
+    def rebase(offenses, path)
+      offenses.map { |offense| offense.with_path(path) }
+    end
+
+    def with_lock
+      FileUtils.mkdir_p(directory)
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      ensure
+        lock.flock(File::LOCK_UN)
+      end
+    end
+
+    def atomic_write(target)
+      temporary = "#{target}.#{Process.pid}.tmp"
+      File.open(temporary, "wb", 0o600) { |file| yield file }
+      File.rename(temporary, target)
+    ensure
+      FileUtils.rm_f(temporary) if defined?(temporary) && temporary
+    end
+
+    def remove_legacy_entries
+      Dir.children(directory).each do |child|
+        path = File.join(directory, child)
+        status = File.lstat(path)
+        if child.match?(LEGACY_DIRECTORY_PATTERN) && status.directory?
+          remove_legacy_content_files(path, child)
+        elsif child.match?(MANIFEST_TEMPORARY_PATTERN) && status.file?
+          FileUtils.rm_f(path)
+        end
+      end
+    rescue SystemCallError
+      nil
+    end
+
+    def remove_legacy_content_files(directory_path, prefix)
+      pattern = /\A#{prefix}[0-9a-f]{62}(?:\.\d+\.tmp)?\z/
+      Dir.children(directory_path).each do |entry|
+        path = File.join(directory_path, entry)
+        FileUtils.rm_f(path) if entry.match?(pattern) && File.lstat(path).file?
+      end
+      Dir.rmdir(directory_path) if Dir.empty?(directory_path)
+    end
+
+    def manifest_path
+      File.join(directory, MANIFEST)
+    end
+
+    def lock_path
+      File.join(directory, LOCK_FILE)
+    end
+  end
+end

data/lib/lumin/cache_manifest.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "offense"
+
+module Lumin
+  class CacheManifest
+    PathEntry = Data.define(:fingerprint, :environment_digest, :key)
+    Contents = Data.define(:paths, :offenses)
+
+    VERSION = 2
+    DIGEST_PATTERN = /\A[0-9a-f]{64}\z/
+    LOCATION_KEYS = %w[start_offset end_offset start_line start_column end_line end_column].freeze
+
+    class << self
+      def load(path)
+        return empty unless File.file?(path)
+
+        payload = File.open(path, "rb") do |file|
+          JSON.parse(file.read, create_additions: false, max_nesting: 20)
+        end
+        return empty unless payload.is_a?(Hash) && payload["version"] == VERSION
+
+        decode(payload)
+      rescue StandardError
+        empty
+      end
+
+      def serialize(data)
+        JSON.generate(
+          "version" => VERSION,
+          "paths" => data.paths.map { |path, entry| encode_path_entry(path, entry) },
+          "offenses" => data.offenses.transform_values do |entries|
+            entries.map { |entry| encode_offense(entry) }
+          end
+        )
+      end
+
+      def empty
+        Contents.new(paths: {}, offenses: {})
+      end
+
+      private
+
+      def encode_path_entry(path, entry)
+        {
+          "path" => encode_string(path),
+          "fingerprint" => entry.fingerprint,
+          "environment_digest" => entry.environment_digest,
+          "key" => entry.key
+        }
+      end
+
+      def encode_offense(offense)
+        {
+          "location" => offense.location.to_h.transform_keys(&:to_s),
+          "rule_name" => encode_string(offense.rule_name),
+          "message" => encode_string(offense.message),
+          "correctable" => offense.correctable?,
+          "safe" => offense.safe,
+          "source_line" => offense.source_line && encode_string(offense.source_line)
+        }
+      end
+
+      def decode(payload)
+        raw_paths = payload["paths"].is_a?(Array) ? payload["paths"] : []
+        raw_offenses = payload["offenses"].is_a?(Hash) ? payload["offenses"] : {}
+        Contents.new(paths: decode_paths(raw_paths), offenses: decode_offenses(raw_offenses))
+      end
+
+      def decode_paths(raw_paths)
+        raw_paths.each_with_object({}) do |value, paths|
+          next unless value.is_a?(Hash)
+
+          path = decode_string(value["path"])
+          next unless path && !path.b.include?("\0".b)
+
+          entry = decode_path_entry(value)
+          paths[path] = entry if entry
+        end
+      end
+
+      def decode_path_entry(value)
+        return unless value.is_a?(Hash)
+
+        fingerprint = value["fingerprint"]
+        environment_digest = value["environment_digest"]
+        cache_key = value["key"]
+        return unless valid_fingerprint?(fingerprint)
+        return unless valid_digest?(environment_digest) && valid_digest?(cache_key)
+
+        PathEntry.new(fingerprint: fingerprint.freeze, environment_digest: environment_digest, key: cache_key)
+      end
+
+      def decode_offenses(raw_offenses)
+        raw_offenses.each_with_object({}) do |(cache_key, values), offenses|
+          next unless valid_digest?(cache_key) && values.is_a?(Array)
+
+          entries = values.map { |value| decode_offense(value) }
+          offenses[cache_key] = entries if entries.none?(&:nil?)
+        end
+      end
+
+      def decode_offense(value)
+        return unless value.is_a?(Hash)
+
+        location = decode_location(value["location"])
+        rule_name = decode_string(value["rule_name"])
+        message = decode_string(value["message"])
+        correctable = value["correctable"]
+        safe = value["safe"]
+        source_line = value["source_line"] && decode_string(value["source_line"])
+        return unless location && rule_name && message
+        return unless boolean?(correctable) && boolean?(safe)
+        return if value["source_line"] && !source_line
+
+        Offense.new(
+          path: "",
+          location: location,
+          rule_name: rule_name,
+          message: message,
+          correctable: correctable,
+          safe: safe,
+          source_line: source_line
+        )
+      end
+
+      def decode_location(value)
+        return unless value.is_a?(Hash)
+
+        attributes = LOCATION_KEYS.to_h { |key| [key.to_sym, value[key]] }
+        return unless attributes.values.all? { |part| part.is_a?(Integer) }
+        return unless valid_location?(attributes)
+
+        Astel::Location.new(**attributes)
+      end
+
+      def valid_location?(location)
+        return false if location[:start_offset].negative? || location[:start_offset] > location[:end_offset]
+        return false if location[:start_line] < 1 || location[:end_line] < location[:start_line]
+        return false if location[:start_column].negative? || location[:end_column].negative?
+
+        location[:end_line] != location[:start_line] || location[:end_column] >= location[:start_column]
+      end
+
+      def valid_fingerprint?(value)
+        return false unless value.is_a?(Array) && value.length == 6
+        return false unless value.all? { |part| part.is_a?(Integer) }
+
+        size, _mtime, mtime_nsec, _ctime, ctime_nsec, inode = value
+        size >= 0 && inode >= 0 && [mtime_nsec, ctime_nsec].all? { |part| part.between?(0, 999_999_999) }
+      end
+
+      def valid_digest?(value)
+        valid_json_string?(value) && value.match?(DIGEST_PATTERN)
+      end
+
+      def boolean?(value)
+        value == true || value == false
+      end
+
+      def encode_string(value)
+        {
+          "bytes" => [value.b].pack("m0"),
+          "encoding" => value.encoding.name
+        }
+      end
+
+      def decode_string(value)
+        return unless value.is_a?(Hash)
+
+        bytes = value["bytes"]
+        encoding_name = value["encoding"]
+        return unless valid_json_string?(bytes) && valid_json_string?(encoding_name)
+
+        encoding = Encoding.find(encoding_name)
+        return unless encoding.is_a?(Encoding)
+
+        bytes.unpack1("m0").force_encoding(encoding)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def valid_json_string?(value)
+        value.is_a?(String) && value.encoding == Encoding::UTF_8 && value.valid_encoding?
+      end
+    end
+  end
+end

data/lib/lumin/cli.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Lumin
+  class CLI
+    FORMATTER_FEATURES = {
+      "text" => "formatters/text",
+      "json" => "formatters/json",
+      "github" => "formatters/github"
+    }.freeze
+    autoload :FORMATTERS, File.expand_path("cli_formatters", __dir__)
+
+    def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr)
+      new(stdout: stdout, stderr: stderr).run(argv)
+    end
+
+    def initialize(stdout:, stderr:)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv)
+      options = default_options
+      arguments = argv.dup
+      parser = option_parser(options)
+      parser.parse!(arguments)
+      if options[:help]
+        @stdout.puts(options[:help])
+        return 0
+      end
+      return print_version if options[:version]
+      raise OptionParser::InvalidOption, "--dry-run requires --fix" if options[:dry_run] && !options[:fix]
+
+      load_runtime
+      execute(options, arguments)
+    rescue OptionParser::ParseError, ArgumentError => error
+      @stderr.puts("lumin: #{error.message}")
+      2
+    rescue StandardError => error
+      @stderr.puts("lumin: internal error: #{error.class}: #{error.message}")
+      2
+    end
+
+    private
+
+    def execute(options, arguments)
+      config = Config.load(options[:config])
+      runner = Runner.new(
+        config: config,
+        parallel: options[:parallel],
+        cache: options[:cache],
+        cache_dir: options[:cache_dir]
+      )
+      if options[:clear_cache]
+        runner.clear_cache
+        return 0
+      end
+
+      result = runner.run(arguments, fix: options[:fix], unsafe: options[:unsafe], dry_run: options[:dry_run])
+      result.diffs.each { |diff| @stdout.puts(diff) }
+      unless options[:dry_run]
+        formatted = formatter(options[:format]).new.format(result.offenses)
+        @stdout.puts(formatted) unless formatted.empty?
+      end
+      result.warnings.each { |warning| @stderr.puts("warning: #{warning}") }
+      result.errors.each { |error| @stderr.puts(error) }
+      return 2 unless result.errors.empty?
+
+      result.offenses.empty? ? 0 : 1
+    rescue Config::ConfigError => error
+      @stderr.puts("lumin: #{error.message}")
+      2
+    end
+
+    def default_options
+      {
+        config: ".lumin.yml",
+        format: "text",
+        parallel: nil,
+        cache: true,
+        cache_dir: nil,
+        clear_cache: false,
+        fix: false,
+        unsafe: false,
+        dry_run: false,
+        help: nil,
+        version: false
+      }
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: lumin [options] [paths...]"
+        parser.on("-c", "--config PATH", "configuration file") { |value| options[:config] = value }
+        parser.on("-f", "--format NAME", FORMATTER_FEATURES.keys, "output format") do |value|
+          options[:format] = value
+        end
+        parser.on("--parallel[=N]", Integer, "number of worker processes") do |value|
+          options[:parallel] = value || processor_count
+        end
+        parser.on("--no-parallel", "disable parallel execution") { options[:parallel] = false }
+        parser.on("--[no-]cache", "enable or disable result cache") { |value| options[:cache] = value }
+        parser.on("--cache-dir PATH", "cache directory") { |value| options[:cache_dir] = value }
+        parser.on("--clear-cache", "remove cached results") { options[:clear_cache] = true }
+        parser.on("--fix", "apply safe corrections") { options[:fix] = true }
+        parser.on("--fix-unsafe", "apply safe and unsafe corrections") do
+          options[:fix] = true
+          options[:unsafe] = true
+        end
+        parser.on("--dry-run", "show corrections as a unified diff") { options[:dry_run] = true }
+        parser.on("-v", "--version", "print the version") { options[:version] = true }
+        parser.on("-h", "--help", "show this help") do
+          options[:help] = parser.to_s
+        end
+      end
+    end
+
+    def print_version
+      require_relative "version"
+      @stdout.puts(VERSION)
+      0
+    end
+
+    def processor_count
+      require "etc"
+      Etc.nprocessors
+    end
+
+    def load_runtime
+      require_relative "../lumin"
+    end
+
+    def formatter(name)
+      require_relative FORMATTER_FEATURES.fetch(name)
+      Formatters.const_get(name.capitalize, false)
+    end
+  end
+end

data/lib/lumin/cli_formatters.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "formatters/text"
+require_relative "formatters/json"
+require_relative "formatters/github"
+
+module Lumin
+  class CLI
+    FORMATTERS = {
+      "text" => Formatters::Text,
+      "json" => Formatters::Json,
+      "github" => Formatters::Github
+    }.freeze
+  end
+end

data/lib/lumin/config/loader.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Lumin
+  class Config
+    class Loader
+      def initialize
+        @loading = []
+      end
+
+      def load_file(path)
+        expanded = File.expand_path(path)
+        if @loading.include?(expanded)
+          raise ConfigError, "configuration inheritance cycle: #{expanded}"
+        end
+
+        @loading << expanded
+        raw = YAML.safe_load_file(expanded, permitted_classes: [], permitted_symbols: [], aliases: false) || {}
+        raise ConfigError, "configuration root must be a mapping" unless raw.is_a?(Hash)
+
+        raw = Config.stringify_keys(raw)
+        inherited = Array(raw.delete("inherit_from")).reduce({}) do |merged, reference|
+          Config.deep_merge(merged, load_file(resolve(reference, File.dirname(expanded))))
+        end
+        Config.deep_merge(inherited, raw)
+      rescue Psych::Exception => error
+        raise ConfigError, "cannot load #{expanded}: #{error.message}"
+      ensure
+        @loading.delete(expanded) if expanded
+      end
+
+      private
+
+      def resolve(reference, directory)
+        raise ConfigError, "inherit_from entries must be strings" unless reference.is_a?(String)
+
+        candidate = File.expand_path(reference, directory)
+        return candidate if File.file?(candidate)
+
+        specification = Gem::Specification.find_by_name(reference)
+        gem_config = [File.join(specification.full_gem_path, ".lumin.yml"),
+                      File.join(specification.full_gem_path, "config", "lumin.yml")].find { |path| File.file?(path) }
+        return gem_config if gem_config
+
+        raise ConfigError, "#{reference} does not provide a Lumin configuration"
+      rescue Gem::MissingSpecError
+        raise ConfigError, "cannot resolve inherited configuration: #{reference}"
+      end
+    end
+  end
+end