kettle-drift 1.0.0

data/lib/kettle/drift/cli.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "set"
+
+module Kettle
+  module Drift
+    class CLI
+      def run(argv = ARGV)
+        options = parse(argv)
+        return options if options.is_a?(Integer)
+
+        project_root = File.expand_path(options.fetch(:project_root))
+        outcome = Kettle::Drift.run(
+          project_root: project_root,
+          template_dir: options[:template_dir],
+          min_chars: options.fetch(:min_chars),
+          json_path: options[:json_path],
+          lock_path: options[:lock_path],
+          mode: options.fetch(:mode),
+        )
+
+        if outcome.clean?
+          puts "[kettle-drift] ✅  No duplicate drift detected (min_chars=#{options[:min_chars]}, files=#{outcome.files.size}, baseline=#{outcome.baseline_set.size})"
+        else
+          puts "[kettle-drift] ⚠️  #{outcome.warning_count} drift warning(s) across #{outcome.results.size} unique chunk(s) (files=#{outcome.files.size}, baseline=#{outcome.baseline_set.size})"
+          puts "[kettle-drift] 📄  Report: #{Kettle::Drift.display_path(outcome.json_path)}" if outcome.json_path
+        end
+
+        outcome.exit_code
+      end
+
+      private
+
+      def parse(argv)
+        options = {
+          min_chars: Kettle::Drift::DuplicateLineValidator::DEFAULT_MIN_CHARS,
+          lock_path: Kettle::Drift::DEFAULT_LOCKFILE,
+          mode: :update,
+          project_root: Dir.pwd,
+        }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: kettle-drift [PROJECT_ROOT] [options]"
+          opts.on("--min-chars=N", Integer, "Minimum non-whitespace characters per line") { |value| options[:min_chars] = value }
+          opts.on("--json=PATH", "Write JSON report to PATH") { |value| options[:json_path] = value }
+          opts.on("--lockfile=PATH", "Use PATH for the lockfile") { |value| options[:lock_path] = value }
+          opts.on("--template-dir=PATH", "Use template-managed files and template baseline from PATH") { |value| options[:template_dir] = value }
+          opts.on("--update", "Update the lockfile when drift is new, reduced, or otherwise changed (default)") { options[:mode] = :update }
+          opts.on("--check", "Fail if current drift differs from the lockfile") { options[:mode] = :check }
+          opts.on("--force-update", "Update the lockfile even when drift gets worse") { options[:mode] = :force_update }
+        end
+
+        remaining = parser.parse(argv.dup)
+        options[:project_root] = remaining.first if remaining.first
+        options[:template_dir] = expand_optional_path(options[:template_dir], File.expand_path(options[:project_root]))
+        options[:lock_path] = File.expand_path(options.fetch(:lock_path), File.expand_path(options[:project_root]))
+        options[:json_path] = options[:json_path] && File.expand_path(options[:json_path], File.expand_path(options[:project_root]))
+        options
+      rescue OptionParser::ParseError => e
+        warn("[kettle-drift] #{e.message}")
+        2
+      end
+
+      def expand_optional_path(path, project_root)
+        return if path.to_s.strip.empty?
+
+        File.expand_path(path, project_root)
+      end
+    end
+  end
+end

data/lib/kettle/drift/diff.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Drift
+    class Diff
+      attr_reader :state, :new_entries, :fixed_entries, :unchanged_entries
+
+      def initialize(state:, new_entries: [], fixed_entries: [], unchanged_entries: [])
+        @state = state
+        @new_entries = new_entries
+        @fixed_entries = fixed_entries
+        @unchanged_entries = unchanged_entries
+      end
+
+      def statistics
+        {
+          left: unchanged_entries.size + new_entries.size,
+          fixed: fixed_entries.size,
+          new: new_entries.size,
+          unchanged: unchanged_entries.size,
+        }
+      end
+
+      def files
+        new_entries.group_by { |entry| entry[:file] }
+      end
+    end
+  end
+end

data/lib/kettle/drift/duplicate_line_validator.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "set"
+
+module Kettle
+  module Drift
+    # Scans managed files for repeated adjacent-line chunks that usually signal
+    # duplication drift or template corruption.
+    module DuplicateLineValidator
+      module_function
+
+      DEFAULT_MIN_CHARS = 6
+      BINARY_EXTENSIONS = Set.new(%w[
+        .7z
+        .bz2
+        .class
+        .dll
+        .exe
+        .gem
+        .gif
+        .gz
+        .ico
+        .jar
+        .jpeg
+        .jpg
+        .pdf
+        .png
+        .so
+        .tar
+        .tgz
+        .ttf
+        .woff
+        .woff2
+        .xz
+        .zip
+      ]).freeze
+      APPRAISALS_DEP_LINE_RE = /\A(?:eval_gemfile|gem)\s+["']/
+      CHANGELOG_METRIC_RE = /\A-\s+(?:(?:(?:line|branch)\s+)?coverage:|\d+\.\d+%\s+documented)/i
+      EXCLUDED_FILENAMES = Set.new(["CODE_OF_CONDUCT.md", ".gitlab-ci.yml"]).freeze
+      KETTLE_JEM_CONFIG_RE = /\A(?:strategy|recipe|preference|add_missing|freeze_token|file_type|max_recursion_depth):\s/
+      RAKEFILE_ENV_ASSIGNMENT_RE = /\AENV\[["']/
+      RESCUE_LOAD_ERROR_RE = /\Arescue\s+LoadError/
+      NOCOV_MARKER_RE = /\A# :nocov:\z/
+      CHANGELOG_SUBHEADINGS = Set.new([
+        "### Added",
+        "### Changed",
+        "### Deprecated",
+        "### Removed",
+        "### Fixed",
+        "### Security",
+      ]).freeze
+
+      def scan(files:, min_chars: DEFAULT_MIN_CHARS)
+        duplicates = {}
+
+        files.each do |path|
+          next unless File.file?(path)
+          next if EXCLUDED_FILENAMES.include?(File.basename(path.to_s))
+
+          content = read_text_content(path)
+          next unless content
+
+          fence_lines = (File.extname(path.to_s) == ".md") ? compute_fence_lines(content) : Set.new
+          indexed = content.each_line.map.with_index(1) { |raw, n| [n, raw.strip] }
+
+          chunk_map = Hash.new { |h, k| h[k] = [] }
+          indexed.each_cons(2) do |(lineno1, line1), (lineno2, line2)|
+            next if line1.gsub(/\s/, "").length <= min_chars
+            next if line2.gsub(/\s/, "").length <= min_chars
+            next if CHANGELOG_SUBHEADINGS.include?(line1)
+            next if fence_lines.include?(lineno1) && fence_lines.include?(lineno2)
+            next if ignored_duplicate_chunk?(path, line1, line2)
+
+            chunk_map["#{line1}\n#{line2}"] << lineno1
+          end
+
+          chunk_map.each do |chunk_content, start_lines|
+            next if start_lines.size < 2
+
+            duplicates[chunk_content] ||= []
+            duplicates[chunk_content] << {
+              file: path,
+              lines: start_lines,
+            }
+          end
+        end
+
+        duplicates
+      end
+
+      def ignored_duplicate_chunk?(path, line1, line2)
+        basename = File.basename(path.to_s)
+
+        if basename == "Appraisals"
+          return true if APPRAISALS_DEP_LINE_RE.match?(line1) && APPRAISALS_DEP_LINE_RE.match?(line2)
+          return true if line1.start_with?("#") && APPRAISALS_DEP_LINE_RE.match?(line2)
+        end
+
+        return true if basename == "CHANGELOG.md" && CHANGELOG_METRIC_RE.match?(line1) && CHANGELOG_METRIC_RE.match?(line2)
+        return true if basename == "Rakefile" && RAKEFILE_ENV_ASSIGNMENT_RE.match?(line1) && RAKEFILE_ENV_ASSIGNMENT_RE.match?(line2)
+        return true if RESCUE_LOAD_ERROR_RE.match?(line1) && NOCOV_MARKER_RE.match?(line2)
+        return true if File.extname(path.to_s) == ".md" && line1.start_with?("|") && line2.start_with?("|")
+        return true if basename == ".kettle-jem.yml" && KETTLE_JEM_CONFIG_RE.match?(line1) && KETTLE_JEM_CONFIG_RE.match?(line2)
+
+        false
+      end
+
+      def compute_fence_lines(content)
+        in_fence = false
+        fence_marker = nil
+        fence_lines = Set.new
+
+        content.each_line.with_index(1) do |raw, lineno|
+          stripped = raw.strip
+          if in_fence
+            fence_lines.add(lineno)
+            if stripped.match?(/\A#{Regexp.escape(fence_marker)}\s*\z/)
+              in_fence = false
+              fence_marker = nil
+            end
+          elsif (match = stripped.match(/\A(`{3,}|~{3,})/))
+            fence_marker = match[1]
+            in_fence = true
+            fence_lines.add(lineno)
+          end
+        end
+
+        fence_lines
+      end
+
+      def scan_template_results(template_results:, min_chars: DEFAULT_MIN_CHARS)
+        written_files = template_results.select { |_path, rec| %i[create replace].include?(rec[:action]) }.keys
+        scan(files: written_files, min_chars: min_chars)
+      end
+
+      def baseline(template_dir: nil, min_chars: DEFAULT_MIN_CHARS)
+        return Set.new unless template_dir && File.directory?(template_dir)
+
+        template_files = Dir.glob(
+          File.join(template_dir, "**", "*"),
+          File::FNM_DOTMATCH,
+        ).select { |f| File.file?(f) }
+
+        Set.new(scan(files: template_files, min_chars: min_chars).keys)
+      end
+
+      def subtract_baseline(results, baseline_set:)
+        results.reject { |line_content, _| baseline_set.include?(line_content) }
+      end
+
+      def template_managed_files(project_root:, template_dir: nil)
+        template_dir ||= File.join(project_root, "template")
+        return [] unless File.directory?(template_dir)
+
+        managed = []
+        Dir.glob(File.join(template_dir, "**", "*"), File::FNM_DOTMATCH).each do |src|
+          next unless File.file?(src)
+
+          rel = src.sub(%r{^#{Regexp.escape(template_dir)}/?}, "")
+          rel = rel.sub(/\.example\z/, "")
+          next if rel.include?(".no-osc")
+
+          dest = File.join(project_root, rel)
+          managed << dest if File.file?(dest)
+        end
+
+        managed.uniq
+      end
+
+      def warning_count(results)
+        results.values.flatten.size
+      end
+
+      def to_json(results)
+        JSON.pretty_generate(results.transform_values do |entries|
+          entries.map { |entry| {file: Kettle::Drift.display_path(entry[:file]), lines: entry[:lines]} }
+        end)
+      end
+
+      def write_json(results, json_path)
+        FileUtils.mkdir_p(File.dirname(json_path))
+        File.write(json_path, to_json(results))
+        json_path
+      end
+
+      def report_summary(results, project_root: nil)
+        return "No duplicate lines detected.\n" if results.empty?
+
+        lines = ["### Duplicate Line Report\n", "| Chunk (line1 ↵ line2) | File | Start Lines |", "|---|---|---|"]
+
+        results.each do |content, entries|
+          display = content.gsub("\n", " ↵ ")
+          display = "#{display[0, 77]}..." if display.length > 80
+          display = display.gsub("|", "\\|")
+
+          entries.each do |entry|
+            file = Kettle::Drift.display_path(entry[:file])
+            if project_root
+              display_root = Kettle::Drift.display_path(project_root)
+              file = file.sub(%r{^#{Regexp.escape(display_root)}/?}, "")
+            end
+            lines << "| `#{display}` | #{file} | #{entry[:lines].join(", ")} |"
+          end
+        end
+
+        lines << ""
+        lines.join("\n")
+      end
+
+      def read_text_content(path)
+        raw = File.binread(path)
+        return if binary_content?(path, raw)
+
+        content = raw.dup.force_encoding(Encoding::UTF_8)
+        return content if content.valid_encoding?
+
+        content.scrub
+      rescue StandardError
+        nil
+      end
+
+      def binary_content?(path, raw)
+        return true if BINARY_EXTENSIONS.include?(File.extname(path.to_s).downcase)
+
+        sample = raw.byteslice(0, 4096) || "".b
+        return true if sample.include?("\x00")
+        return false if sample.empty?
+
+        control_bytes = sample.each_byte.count do |byte|
+          (0..8).cover?(byte) || byte == 11 || byte == 12 || (14..31).cover?(byte)
+        end
+        control_bytes.fdiv(sample.bytesize) > 0.1
+      end
+    end
+  end
+end

data/lib/kettle/drift/lock_file.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Kettle
+  module Drift
+    class LockFile
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+      end
+
+      def read_results
+        return unless File.exist?(path)
+
+        Kettle::Drift::Serializer.deserialize(File.read(path, encoding: Encoding::UTF_8))
+      end
+
+      def write_results(results, project_root: nil)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, Kettle::Drift::Serializer.serialize(results, project_root: project_root), encoding: Encoding::UTF_8)
+      end
+
+      def delete
+        return unless File.exist?(path)
+
+        File.delete(path)
+      end
+    end
+  end
+end

data/lib/kettle/drift/outcome.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Drift
+    class Outcome
+      attr_reader :project_root,
+        :files,
+        :template_dir,
+        :baseline_set,
+        :results,
+        :warning_count,
+        :json_path,
+        :lock_path,
+        :mode,
+        :diff,
+        :exit_code
+
+      def initialize(
+        project_root:,
+        files:,
+        template_dir:,
+        baseline_set:,
+        results:,
+        warning_count:,
+        json_path:,
+        lock_path:,
+        mode:,
+        diff:,
+        exit_code:
+      )
+        @project_root = project_root
+        @files = files
+        @template_dir = template_dir
+        @baseline_set = baseline_set
+        @results = results
+        @warning_count = warning_count
+        @json_path = json_path
+        @lock_path = lock_path
+        @mode = mode
+        @diff = diff
+        @exit_code = exit_code
+      end
+
+      def clean?
+        results.empty?
+      end
+    end
+  end
+end

data/lib/kettle/drift/plugin.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Drift
+    module Plugin
+      module_function
+
+      SNIPPET_MARKER = "### DUPLICATE DRIFT TASKS"
+
+      RAKEFILE_SNIPPET = <<~RUBY
+        ### DUPLICATE DRIFT TASKS
+        begin
+          require "kettle/drift"
+          Kettle::Drift.install_tasks
+        rescue LoadError
+          desc("(stub) kettle:drift:check is unavailable")
+          task("kettle:drift:check") do
+            warn("NOTE: kettle-drift isn't installed, or is disabled for \#{RUBY_VERSION} in the current environment")
+          end
+          desc("(stub) kettle:drift:update is unavailable")
+          task("kettle:drift:update") do
+            warn("NOTE: kettle-drift isn't installed, or is disabled for \#{RUBY_VERSION} in the current environment")
+          end
+          desc("(stub) kettle:drift:force_update is unavailable")
+          task("kettle:drift:force_update") do
+            warn("NOTE: kettle-drift isn't installed, or is disabled for \#{RUBY_VERSION} in the current environment")
+          end
+          desc("(stub) kettle:drift is unavailable")
+          task("kettle:drift" => "kettle:drift:update")
+        end
+      RUBY
+
+      def register!(registrar)
+        registrar.after_phase(:remaining_files) do |context:, **|
+          inject_rakefile_tasks(context)
+        end
+      end
+
+      def inject_rakefile_tasks(context)
+        rakefile_path = File.join(context.project_root, "Rakefile")
+        return unless File.exist?(rakefile_path)
+
+        existing = File.read(rakefile_path)
+        updated = upsert_rakefile_snippet(existing)
+        return if updated == existing
+
+        File.write(rakefile_path, updated)
+        context.helpers.record_template_result(rakefile_path, :replace)
+        context.out.report_detail("[kettle-drift] Injected Rakefile tasks")
+      end
+
+      def upsert_rakefile_snippet(content)
+        if content.include?(SNIPPET_MARKER)
+          return replace_existing_snippet(content)
+        end
+
+        insert_snippet(content)
+      end
+
+      def replace_existing_snippet(content)
+        marker_index = content.index(SNIPPET_MARKER)
+        next_section_index = content.index(/\n### [A-Z][^\n]*\n/, marker_index + SNIPPET_MARKER.length)
+        prefix = content[0...marker_index].rstrip
+        suffix = next_section_index ? content[next_section_index..].lstrip : ""
+        "#{[prefix, RAKEFILE_SNIPPET.rstrip, suffix].reject(&:empty?).join("\n\n").rstrip}\n"
+      end
+
+      def insert_snippet(content)
+        lines = content.lines
+        require_index = lines.rindex { |line| line.match?(/^\s*require\s+["']kettle\/dev["']/) }
+        if require_index
+          lines.insert(require_index + 1, "\n", RAKEFILE_SNIPPET, "\n")
+          lines.join
+        else
+          [content.rstrip, "", RAKEFILE_SNIPPET.rstrip, ""].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/kettle/drift/process/calculate_diff.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Drift
+    class Process
+      module CalculateDiff
+        class << self
+          def call(new_results, old_results)
+            new_entries = flatten_results(new_results)
+            return Kettle::Drift::Diff.new(state: :complete, fixed_entries: [], new_entries: [], unchanged_entries: []) if new_entries.empty? && old_results.nil?
+            return Kettle::Drift::Diff.new(state: :new, new_entries: new_entries, unchanged_entries: []) if old_results.nil?
+
+            old_entries = flatten_results(old_results)
+            new_map = index_entries(new_entries)
+            old_map = index_entries(old_entries)
+
+            added = (new_map.keys - old_map.keys).map { |key| new_map.fetch(key) }
+            fixed = (old_map.keys - new_map.keys).map { |key| old_map.fetch(key) }
+            unchanged = (new_map.keys & old_map.keys).map { |key| new_map.fetch(key) }
+
+            state = if new_entries.empty?
+              :complete
+            elsif added.empty? && fixed.empty?
+              :no_changes
+            elsif added.empty?
+              :better
+            elsif fixed.empty?
+              :worse
+            else
+              :updated
+            end
+
+            Kettle::Drift::Diff.new(
+              state: state,
+              new_entries: added,
+              fixed_entries: fixed,
+              unchanged_entries: unchanged,
+            )
+          end
+
+          private
+
+          def flatten_results(results)
+            results.keys.sort.flat_map do |chunk|
+              Array(results.fetch(chunk)).map do |entry|
+                {
+                  chunk: chunk,
+                  file: entry.fetch(:file),
+                  lines: entry.fetch(:lines),
+                }
+              end
+            end
+          end
+
+          def index_entries(entries)
+            entries.each_with_object({}) do |entry, indexed|
+              indexed[entry_key(entry)] = entry
+            end
+          end
+
+          def entry_key(entry)
+            [entry.fetch(:chunk), entry.fetch(:file), Array(entry.fetch(:lines))]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kettle/drift/process/printer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Drift
+    class Process
+      class Printer
+        def initialize(diff:, lock_path:, mode: :update)
+          @diff = diff
+          @lock_path = lock_path
+          @mode = mode
+        end
+
+        def print_results
+          send(:"print_#{diff.state}")
+        end
+
+        private
+
+        attr_reader :diff, :lock_path, :mode
+
+        def print_complete
+          puts "Kettle Drift is complete!"
+          puts "Removing `#{Kettle::Drift.display_path(lock_path)}` lock file..." if diff.statistics[:fixed].positive?
+        end
+
+        def print_updated
+          if mode == :force_update
+            puts "Kettle Drift found both fixed drift and new untracked drift, and is force-updating the lockfile."
+          else
+            puts "Kettle Drift found both fixed drift and new untracked drift."
+          end
+        end
+
+        def print_no_changes
+          puts "Kettle Drift got no changes."
+        end
+
+        def print_new
+          puts "Kettle Drift got results for the first time. #{diff.statistics[:left]} drift item(s) found."
+          puts "Don't forget to commit `#{Kettle::Drift.display_path(lock_path)}`."
+        end
+
+        def print_better
+          puts "Kettle Drift got #{diff.statistics[:fixed]} drift item(s) fixed, #{diff.statistics[:left]} left. Keep going!"
+        end
+
+        def print_worse
+          if mode == :force_update
+            puts "Kettle Drift found new untracked drift and is force-updating the lockfile:"
+          else
+            puts "Uh oh, Kettle Drift got worse:"
+          end
+          diff.files.each do |file, entries|
+            puts "-> #{Kettle::Drift.display_path(file)} (#{entries.size} new drift item(s))"
+            entries.each do |entry|
+              puts "    (lines #{entry[:lines].join(", ")}) #{entry[:chunk].inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kettle/drift/process.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "process/calculate_diff"
+require_relative "process/printer"
+
+module Kettle
+  module Drift
+    class Process
+      Result = Struct.new(:diff, :exit_code, keyword_init: true)
+
+      attr_reader :project_root, :lock_file, :old_results, :new_results, :mode, :printer_class
+
+      def initialize(project_root:, results:, lock_path:, mode: :update, printer_class: Kettle::Drift::Process::Printer)
+        @project_root = File.expand_path(project_root)
+        @lock_file = Kettle::Drift::LockFile.new(lock_path)
+        @old_results = lock_file.read_results
+        @new_results = Kettle::Drift::Serializer.normalize(results, project_root: @project_root)
+        @mode = mode
+        @printer_class = printer_class
+      end
+
+      def call
+        run.exit_code
+      end
+
+      def run
+        diff = Kettle::Drift::Process::CalculateDiff.call(new_results, old_results)
+        printer_class&.new(diff: diff, lock_path: lock_file.path, mode: mode)&.print_results
+
+        exit_code = error_code(diff)
+        sync_lock_file(diff) if exit_code.zero?
+        Result.new(diff: diff, exit_code: exit_code)
+      end
+
+      private
+
+      def fail_with_outdated_lock?(diff)
+        return false unless mode == :check
+        return false if diff.state == :complete && old_results.nil?
+
+        diff.state != :no_changes
+      end
+
+      def new_untracked_drift?(diff)
+        return false if old_results.nil?
+
+        diff.new_entries.any?
+      end
+
+      def sync_lock_file(diff)
+        return lock_file.delete if diff.state == :complete
+
+        lock_file.write_results(new_results)
+      end
+
+      def error_code(diff)
+        return 1 if fail_with_outdated_lock?(diff)
+        return 1 if new_untracked_drift?(diff) && mode != :force_update
+
+        0
+      end
+    end
+  end
+end