al_folio_upgrade 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311c5c378bf84cb75344dad471da0f2638381cf02bbc3fa0df7efb2334d4d2dc
-  data.tar.gz: 3a105b308d61ea92afee0d7c2cc3c5dfe98a0a1038bb2bf1aa58f3c45eb30ce0
+  metadata.gz: a948a64341e82725be8159f090200f98fac9a935d96048740fc5ce971a84466a
+  data.tar.gz: 566e9c3db9d558b0161c7ec821b1e32388e4b0fe5d12a1896392af17a7827b5a
 SHA512:
-  metadata.gz: ece6ab6b41a0afcf7d92a85e73407708451df2e3914031a39518d11c13e45df25625b5bc47fbc93a609920efb7ff9dd543adc29994b2a932770d844c60a80a96
-  data.tar.gz: b90842fe6f7b7a6ef987a725cf06c7df0885991407b832cf0fbbcd9a8df4ebd5ee3a8b62df69257b2ce110609fb333fae264cda54fb1c078de010866c49c6979
+  metadata.gz: 69308f22a57519e24253b7e85f64275c9d27fa8eb43a30210e12a92d2ace66d615f1f7c3db0781a9f30367285cfe3ac0f635905c4dab4b98b10f37830c0ae0a7
+  data.tar.gz: 37879887dcbaa46cff34f17a8968f7335b800b47f4541712616422e97b7fb13f45e30317b94912493be1fb45966fd15016c37892c539482d2aa9dede9812e5c9

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.3 - 2026-05-25
+
+- Added local override audit/diff/acknowledgement commands so customized sites can detect when local copies shadow changed plugin-owned files.
+
 ## 1.0.2 - 2026-05-24
 
 - Expanded upgrade audit coverage for legacy local plugins and runtime assets that are now owned by v1 feature gems.

data/README.md

@@ -7,6 +7,9 @@
 - `al-folio upgrade audit`
 - `al-folio upgrade apply --safe`
 - `al-folio upgrade report`
+- `al-folio upgrade overrides audit`
+- `al-folio upgrade overrides diff LOCAL_PATH`
+- `al-folio upgrade overrides accept [--all|LOCAL_PATH ...]`
 
 ## What it checks
 
@@ -16,8 +19,20 @@
 - Distill remote-loader policy
 - Local override drift when `theme: al_folio_core` is enabled
 - Plugin-owned local asset drift (for example copied search, icon, Distill, citation, and external-post runtime files)
+- Local files that shadow installed plugin-owned layouts, includes, Sass, templates, and assets
 - Migration manifest availability from `al_folio_core`
 
+## Local override workflow
+
+Customized sites can keep local copies of plugin-owned files, but those copies do not produce Git merge conflicts when the owning gem changes. Use the overrides workflow after dependency updates:
+
+1. Run `bundle exec al-folio upgrade overrides audit`.
+2. For every stale or unacknowledged override, run `bundle exec al-folio upgrade overrides diff LOCAL_PATH`.
+3. Reconcile the local file with the plugin-owned upstream file.
+4. Run `bundle exec al-folio upgrade overrides accept LOCAL_PATH` or `bundle exec al-folio upgrade overrides accept --all`.
+
+Acknowledgements are stored in `.al-folio-overrides.yml`. Commit that file in customized sites so future gem updates can flag upstream changes explicitly.
+
 ## Ecosystem context
 
 - Starter execution/docs live in `al-folio`.

data/lib/al_folio_upgrade/cli.rb

@@ -4,6 +4,8 @@ require "optparse"
 require "pathname"
 require "yaml"
 require "date"
+require "digest"
+require "English"
 
 begin
   require "al_folio_core"
@@ -14,8 +16,19 @@ end
 module AlFolioUpgrade
   class CLI
     REPORT_PATH = "al-folio-upgrade-report.md"
+    OVERRIDE_ACK_PATH = ".al-folio-overrides.yml"
 
     Finding = Struct.new(:id, :severity, :message, :file, :line, :snippet, keyword_init: true)
+    OverrideResult = Struct.new(
+      :local_path,
+      :plugin_path,
+      :owner,
+      :version,
+      :local_sha,
+      :upstream_sha,
+      :status,
+      keyword_init: true
+    )
 
     FILE_GLOBS = [
       "_config.yml",
@@ -129,6 +142,8 @@ module AlFolioUpgrade
         write_report(findings)
         print_summary(findings)
         0
+      when "overrides"
+        run_overrides(argv)
       else
         @stderr.puts("Unsupported subcommand: #{subcommand.inspect}")
         usage(1)
@@ -138,10 +153,53 @@ module AlFolioUpgrade
     private
 
     def usage(code)
-      @stdout.puts("Usage: al-folio upgrade [audit|apply --safe|report] [--no-fail]")
+      @stdout.puts("Usage: al-folio upgrade [audit|apply --safe|report|overrides] [--no-fail]")
+      @stdout.puts("       al-folio upgrade overrides audit [--fail-on-stale]")
+      @stdout.puts("       al-folio upgrade overrides diff LOCAL_PATH")
+      @stdout.puts("       al-folio upgrade overrides accept [--all|LOCAL_PATH ...]")
       code
     end
 
+    def run_overrides(argv)
+      command = argv.shift
+      case command
+      when "audit"
+        options = { fail_on_stale: false }
+        OptionParser.new do |opts|
+          opts.on("--fail-on-stale", "Exit non-zero when stale/unacknowledged overrides are found") do
+            options[:fail_on_stale] = true
+          end
+        end.parse!(argv)
+
+        results = local_override_results
+        print_override_audit(results)
+        return 1 if options[:fail_on_stale] && override_attention_required?(results)
+
+        0
+      when "diff"
+        local_path = argv.shift
+        if local_path.nil? || local_path.empty?
+          @stderr.puts("Usage: al-folio upgrade overrides diff LOCAL_PATH")
+          return 1
+        end
+
+        diff_override(local_path)
+      when "accept"
+        options = { all: false }
+        OptionParser.new do |opts|
+          opts.on("--all", "Acknowledge all detected local overrides") do
+            options[:all] = true
+          end
+        end.parse!(argv)
+
+        paths = options[:all] ? :all : argv
+        acknowledge_overrides(paths)
+      else
+        @stderr.puts("Unsupported overrides subcommand: #{command.inspect}")
+        usage(1)
+      end
+    end
+
     def blocking?(findings)
       findings.any? { |finding| finding.severity == :blocking }
     end
@@ -153,7 +211,7 @@ module AlFolioUpgrade
       check_legacy_assets(findings)
       check_legacy_patterns(findings)
       check_distill_runtime(findings)
-      check_core_override_drift(findings)
+      check_local_override_drift(findings)
       check_plugin_owned_local_assets(findings)
       findings
     end
@@ -356,6 +414,239 @@ module AlFolioUpgrade
       paths.select(&:file?).uniq
     end
 
+    def check_local_override_drift(findings)
+      local_override_results.each do |override|
+        case override.status
+        when :identical
+          findings << Finding.new(
+            id: "local_override_identical",
+            severity: :warning,
+            message: "Local override is identical to `#{override.owner}` #{override.version}; remove it unless it is intentional.",
+            file: override.local_path,
+            line: 1,
+            snippet: "Matches #{override.owner}:#{override.plugin_path}."
+          )
+        when :unacknowledged
+          findings << Finding.new(
+            id: "local_override_unacknowledged",
+            severity: :warning,
+            message: "Local override shadows `#{override.owner}` #{override.version}; review and acknowledge it with `al-folio upgrade overrides accept #{override.local_path}`.",
+            file: override.local_path,
+            line: 1,
+            snippet: "Diff with `al-folio upgrade overrides diff #{override.local_path}`."
+          )
+        when :stale
+          findings << Finding.new(
+            id: "local_override_upstream_changed",
+            severity: :warning,
+            message: "`#{override.owner}` changed the upstream file since this local override was acknowledged.",
+            file: override.local_path,
+            line: 1,
+            snippet: "Reconcile with `al-folio upgrade overrides diff #{override.local_path}`."
+          )
+        when :local_changed
+          findings << Finding.new(
+            id: "local_override_changed_since_ack",
+            severity: :warning,
+            message: "Local override changed since it was last acknowledged.",
+            file: override.local_path,
+            line: 1,
+            snippet: "Review and re-acknowledge with `al-folio upgrade overrides accept #{override.local_path}`."
+          )
+        end
+      end
+    end
+
+    def local_override_results
+      acknowledgements = override_acknowledgements
+      override_candidates.map do |candidate|
+        local_sha = sha256(@root.join(candidate[:local_path]))
+        upstream_sha = sha256(candidate[:plugin_absolute_path])
+        ack = acknowledgements[candidate[:local_path]]
+
+        status = if local_sha == upstream_sha
+                   :identical
+                 elsif ack.nil?
+                   :unacknowledged
+                 elsif ack["upstream_sha256"] != upstream_sha
+                   :stale
+                 elsif ack["local_sha256"] != local_sha
+                   :local_changed
+                 else
+                   :acknowledged
+                 end
+
+        OverrideResult.new(
+          local_path: candidate[:local_path],
+          plugin_path: candidate[:plugin_path],
+          owner: candidate[:owner],
+          version: candidate[:version],
+          local_sha: local_sha,
+          upstream_sha: upstream_sha,
+          status: status
+        )
+      end.sort_by(&:local_path)
+    end
+
+    def print_override_audit(results)
+      if results.empty?
+        @stdout.puts("No local overrides shadowing installed al-folio plugin files were detected.")
+        return
+      end
+
+      @stdout.puts("Detected #{results.length} local override(s):")
+      results.each do |override|
+        @stdout.puts(
+          "- #{override.local_path}: #{override.status} " \
+          "(#{override.owner} #{override.version}, upstream #{override.plugin_path})"
+        )
+      end
+      @stdout.puts("Acknowledgement file: #{OVERRIDE_ACK_PATH}")
+    end
+
+    def diff_override(local_path)
+      override = local_override_results.find { |result| result.local_path == normalize_relative_path(local_path) }
+      unless override
+        @stderr.puts("No plugin-owned override found for #{local_path}.")
+        return 1
+      end
+
+      candidate = override_candidates.find { |entry| entry[:local_path] == override.local_path }
+      system("diff", "-u", candidate[:plugin_absolute_path].to_s, @root.join(override.local_path).to_s)
+      $CHILD_STATUS&.exitstatus || 0
+    end
+
+    def acknowledge_overrides(paths)
+      results = local_override_results
+      selected = if paths == :all
+                   results
+                 else
+                   wanted = Array(paths).map { |path| normalize_relative_path(path) }
+                   results.select { |result| wanted.include?(result.local_path) }
+                 end
+
+      if selected.empty?
+        @stderr.puts("No matching local overrides to acknowledge.")
+        return 1
+      end
+
+      data = override_ack_file
+      data["version"] = 1
+      data["overrides"] ||= {}
+
+      selected.each do |override|
+        data["overrides"][override.local_path] = {
+          "owner" => override.owner,
+          "gem_version" => override.version,
+          "upstream_path" => override.plugin_path,
+          "upstream_sha256" => override.upstream_sha,
+          "local_sha256" => override.local_sha,
+          "acknowledged_at" => Date.today.iso8601,
+        }
+      end
+
+      sorted = data["overrides"].sort.to_h
+      data["overrides"] = sorted
+      File.write(@root.join(OVERRIDE_ACK_PATH), YAML.dump(data))
+      @stdout.puts("Acknowledged #{selected.length} local override(s) in #{OVERRIDE_ACK_PATH}.")
+      0
+    end
+
+    def override_attention_required?(results)
+      results.any? { |result| %i[unacknowledged stale local_changed identical].include?(result.status) }
+    end
+
+    def override_candidates
+      plugin_file_entries.each_with_object([]) do |entry, candidates|
+        local = @root.join(entry[:local_path])
+        next unless local.file?
+
+        candidates << entry
+      end
+    end
+
+    def plugin_file_entries
+      entries = []
+      al_folio_plugin_specs.each do |spec|
+        root = Pathname.new(spec.full_gem_path)
+        next unless root.directory?
+
+        plugin_globs.each do |glob|
+          Dir.glob(root.join(glob)).sort.each do |path|
+            next unless File.file?(path)
+
+            plugin_path = Pathname.new(path).relative_path_from(root).to_s
+            local_path = local_override_path(plugin_path)
+            next unless local_path
+
+            entries << {
+              local_path: local_path,
+              plugin_path: plugin_path,
+              plugin_absolute_path: Pathname.new(path),
+              owner: spec.name,
+              version: spec.version.to_s,
+            }
+          end
+        end
+      end
+
+      entries.uniq { |entry| [entry[:owner], entry[:local_path], entry[:plugin_path]] }
+    end
+
+    def plugin_globs
+      [
+        "_includes/**/*",
+        "_layouts/**/*",
+        "_sass/**/*",
+        "assets/**/*",
+        "templates/**/*",
+        "lib/assets/**/*",
+        "lib/templates/**/*",
+      ]
+    end
+
+    def local_override_path(plugin_path)
+      case plugin_path
+      when %r{\Atemplates/(.+)}
+        "_includes/#{Regexp.last_match(1)}"
+      when %r{\Alib/templates/(.+)}
+        "_includes/#{Regexp.last_match(1)}"
+      when %r{\Alib/assets/(.+)}
+        "assets/#{Regexp.last_match(1)}"
+      when %r{\A(?:_includes|_layouts|_sass|assets)/}
+        plugin_path
+      end
+    end
+
+    def al_folio_plugin_specs
+      Gem::Specification.each.select do |spec|
+        spec.name.start_with?("al_") && File.directory?(spec.full_gem_path)
+      end
+    end
+
+    def override_ack_file
+      path = @root.join(OVERRIDE_ACK_PATH)
+      return {} unless path.file?
+
+      parsed = parse_yaml(path.read) || {}
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue StandardError
+      {}
+    end
+
+    def override_acknowledgements
+      overrides = override_ack_file["overrides"]
+      overrides.is_a?(Hash) ? overrides.transform_keys(&:to_s) : {}
+    end
+
+    def sha256(path)
+      Digest::SHA256.file(path).hexdigest
+    end
+
+    def normalize_relative_path(path)
+      Pathname.new(path.to_s).cleanpath.to_s.sub(%r{\A\./}, "")
+    end
+
     def check_core_override_drift(findings)
       return unless using_core_theme?
 

data/lib/al_folio_upgrade/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AlFolioUpgrade
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: al_folio_upgrade
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - al-folio maintainers
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -119,6 +120,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/al-org-dev/al-folio-upgrade
   source_code_uri: https://github.com/al-org-dev/al-folio-upgrade
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -133,7 +135,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Upgrade tooling for al-folio v1.x
 test_files: []