upkeep-rails 0.2.5-aarch64-linux-gnu

data/lib/upkeep/herb/developer_report.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "template_manifest"
+
+module Upkeep
+  module HerbSupport
+    class DeveloperReport
+      FALLBACK_ACTIONS = {
+        "helper_hidden_collection" => "Move collection rendering out of helper-only HTML and into an explicit render site.",
+        "manifest_runtime_mismatch" => "Inspect manifest provenance mismatches before trusting narrow updates.",
+        "multi_root_partial" => "Wrap the partial in one stable root element so it can carry a fragment marker.",
+        "no_herb_render_site" => "Extract updateable repeated markup into a partial render so Herb can plan a render site.",
+        "page_dependency_without_narrower_frame" => "Add a fragment or render-site boundary around the data-dependent region.",
+        "parse_failure" => "Fix the Herb parse error before using source-derived update addresses.",
+        "parse_recovered" => "Herb recovered with non-strict parsing, but Upkeep kept narrow source-derived addresses disabled. Fix the strict warnings to enable narrow updates.",
+        "preloaded_plain_data" => "Keep record identity available to the view or attach summaries to their source records."
+      }.freeze
+
+      def initialize(manifests:, proof_report: nil)
+        @manifests = manifests
+        @proof_report = proof_report
+      end
+
+      def to_h
+        actions = template_actions + fallback_actions
+
+        {
+          summary: TemplateManifest.summary(manifests).merge(
+            page_fallback_reasons: page_fallback_reasons,
+            actionable_items: actions.size,
+            gate_passed: actions.all? { |action| action.fetch(:message) }
+          ),
+          templates: manifests.map { |manifest| template_report(manifest) },
+          actions: actions
+        }
+      end
+
+      private
+
+      attr_reader :manifests, :proof_report
+
+      def template_report(manifest)
+        {
+          path: manifest.path,
+          kind: manifest.partial? ? "partial" : "page",
+          parse_ok: manifest.parse.fetch(:ok),
+          parse_recovered: manifest.recovered?,
+          strict_parse_errors: strict_parse_errors(manifest),
+          parse_warnings: parse_warnings(manifest),
+          render_sites: manifest.render_nodes.size,
+          recovered_render_sites: manifest.recovery_render_nodes.size,
+          fragment_root_tags: manifest.frontend_tag_plan.count { |tag| tag.fetch(:kind) == "fragment_root" },
+          helper_lowered_elements: manifest.helper_lowered_elements.size,
+          blockers: template_blockers(manifest)
+        }
+      end
+
+      def template_actions
+        manifests.flat_map do |manifest|
+          template_blockers(manifest).map do |blocker|
+            action = {
+              source: "template",
+              path: manifest.path,
+              reason: blocker,
+              message: template_action_message(blocker)
+            }
+            action[:recovered_render_sites] = manifest.recovery_render_nodes.size if blocker == "parse_recovered"
+            action
+          end
+        end
+      end
+
+      def template_blockers(manifest)
+        blockers = []
+        blockers << (manifest.recovered? ? "parse_recovered" : "parse_failure") unless manifest.parse.fetch(:ok)
+        blockers << "partial_without_single_root" if manifest.partial? && manifest.parse.fetch(:ok) && !manifest.root_shape.fetch(:single_root, false)
+        blockers << "page_without_render_site" if !manifest.partial? && manifest.parse.fetch(:ok) && manifest.render_nodes.empty?
+        blockers
+      end
+
+      def template_action_message(blocker)
+        case blocker
+        when "parse_failure"
+          FALLBACK_ACTIONS.fetch("parse_failure")
+        when "parse_recovered"
+          FALLBACK_ACTIONS.fetch("parse_recovered")
+        when "partial_without_single_root"
+          FALLBACK_ACTIONS.fetch("multi_root_partial")
+        when "page_without_render_site"
+          FALLBACK_ACTIONS.fetch("no_herb_render_site")
+        end
+      end
+
+      def fallback_actions
+        proof_cases.flat_map do |test_case|
+          test_case.fetch(:selected_targets).filter_map do |target|
+            next unless target.fetch(:kind) == "page"
+
+            fallback_reason = target[:fallback_reason]
+            next unless fallback_reason
+
+            {
+              source: "proof",
+              case: test_case.fetch(:name),
+              target: target.fetch(:id),
+              reason: fallback_reason,
+              message: FALLBACK_ACTIONS.fetch(fallback_reason, "Add a narrower template boundary or keep the page fallback.")
+            }
+          end
+        end
+      end
+
+      def proof_cases
+        Array(proof_report&.fetch(:cases, []))
+      end
+
+      def page_fallback_reasons
+        proof_report&.fetch(:summary, {})&.fetch(:page_fallback_reasons, {}) || {}
+      end
+
+      def strict_parse_errors(manifest)
+        Array(manifest.parse[:errors])
+      end
+
+      def parse_warnings(manifest)
+        warnings = Array(manifest.parse[:warnings])
+        return warnings unless manifest.recovered?
+
+        warnings + strict_parse_errors(manifest).map do |error|
+          error.merge(severity: "warning", recovery: "non_strict")
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/herb/manifest_cache.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "manifest_diff"
+
+module Upkeep
+  module HerbSupport
+    class ManifestCache
+      Entry = Data.define(:path, :source_digest, :source, :manifest, :last_update)
+
+      attr_reader :entries
+
+      def initialize
+        @entries = {}
+      end
+
+      def fetch(path:, source:, parse_options: ManifestDiff::PARSE_OPTIONS)
+        source_digest = digest(source)
+        entry = entries[path]
+
+        return entry.manifest if entry&.source_digest == source_digest
+
+        update = update_for(path: path, old_source: entry&.source, new_source: source, parse_options: parse_options)
+        manifest = update[:new_manifest] || TemplateManifest.build(path: path, source: source, parse_options: parse_options)
+        entries[path] = Entry.new(path, source_digest, source.dup, manifest, update_payload(update))
+
+        manifest
+      end
+
+      def last_update_for(path)
+        entries.fetch(path).last_update
+      end
+
+      def summary
+        updates = entries.values.map(&:last_update)
+
+        {
+          entries: entries.size,
+          actions: updates.map { |update| update.fetch(:action) }.tally,
+          topology_changes: updates.count { |update| update.fetch(:topology_changed, false) }
+        }
+      end
+
+      def clear
+        entries.clear
+      end
+
+      private
+
+      def update_for(path:, old_source:, new_source:, parse_options:)
+        return initial_update(path: path, source: new_source, parse_options: parse_options) unless old_source
+
+        ManifestDiff.plan(path: path, old_source: old_source, new_source: new_source, parse_options: parse_options).to_h
+      end
+
+      def initial_update(path:, source:, parse_options:)
+        manifest = TemplateManifest.build(path: path, source: source, parse_options: parse_options)
+
+        {
+          path: path,
+          action: "initial_build",
+          reason: "new_template",
+          topology_changed: true,
+          diff_identical: false,
+          operation_types: [],
+          operations: [],
+          new_manifest: manifest,
+          new_manifest_fingerprint: manifest.fingerprint,
+          stable_topology: false,
+          gate_passed: manifest.parse.fetch(:ok)
+        }
+      end
+
+      def update_payload(update)
+        update.reject { |key, _value| %i[old_manifest new_manifest old_topology_signature new_topology_signature].include?(key) }
+      end
+
+      def digest(source)
+        Digest::SHA256.hexdigest(source)
+      end
+    end
+  end
+end

data/lib/upkeep/herb/manifest_diff.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "template_manifest"
+
+module Upkeep
+  module HerbSupport
+    class ManifestDiff
+      PARSE_OPTIONS = TemplateManifest::DEFAULT_PARSE_OPTIONS.merge(
+        action_view_helpers: false,
+        transform_conditionals: false
+      ).freeze
+
+      CONTENT_ONLY_OPERATION_TYPES = %i[
+        attribute_added
+        attribute_removed
+        attribute_value_changed
+        text_changed
+      ].freeze
+
+      Plan = Data.define(
+        :path,
+        :action,
+        :reason,
+        :topology_changed,
+        :diff_identical,
+        :operation_types,
+        :operations,
+        :old_manifest,
+        :new_manifest,
+        :old_topology_signature,
+        :new_topology_signature,
+        :error
+      ) do
+        def gate_passed?
+          error.nil?
+        end
+
+        def to_h
+          {
+            path: path,
+            action: action,
+            reason: reason,
+            topology_changed: topology_changed,
+            diff_identical: diff_identical,
+            operation_types: operation_types,
+            operations: operations,
+            old_manifest_fingerprint: old_manifest&.fingerprint,
+            new_manifest_fingerprint: new_manifest&.fingerprint,
+            stable_topology: old_topology_signature == new_topology_signature,
+            gate_passed: gate_passed?,
+            error: error
+          }.compact
+        end
+      end
+
+      def self.plan(path:, old_source:, new_source:, parse_options: PARSE_OPTIONS)
+        new(path: path, old_source: old_source, new_source: new_source, parse_options: parse_options).plan
+      end
+
+      def initialize(path:, old_source:, new_source:, parse_options: PARSE_OPTIONS)
+        @path = path
+        @old_source = old_source
+        @new_source = new_source
+        @parse_options = parse_options
+      end
+
+      def plan
+        old_manifest = build_manifest(old_source)
+        new_manifest = build_manifest(new_source)
+        diff_result = ::Herb.diff(old_source, new_source)
+        old_signature = topology_signature(old_manifest)
+        new_signature = topology_signature(new_manifest)
+        action, reason, topology_changed = classify(
+          diff_result: diff_result,
+          old_manifest: old_manifest,
+          new_manifest: new_manifest,
+          old_signature: old_signature,
+          new_signature: new_signature
+        )
+
+        Plan.new(
+          path: path,
+          action: action,
+          reason: reason,
+          topology_changed: topology_changed,
+          diff_identical: diff_result.identical?,
+          operation_types: diff_result.map { |operation| operation.type.to_s },
+          operations: diff_result.map { |operation| operation_payload(operation) },
+          old_manifest: old_manifest,
+          new_manifest: new_manifest,
+          old_topology_signature: old_signature,
+          new_topology_signature: new_signature,
+          error: nil
+        )
+      rescue StandardError => error
+        Plan.new(
+          path: path,
+          action: "full_rebuild",
+          reason: "herb_diff_failed",
+          topology_changed: true,
+          diff_identical: false,
+          operation_types: [],
+          operations: [],
+          old_manifest: nil,
+          new_manifest: nil,
+          old_topology_signature: nil,
+          new_topology_signature: nil,
+          error: { class: error.class.name, message: error.message }
+        )
+      end
+
+      private
+
+      attr_reader :path, :old_source, :new_source, :parse_options
+
+      def build_manifest(source)
+        TemplateManifest.build(path: path, source: source, parse_options: parse_options)
+      end
+
+      def classify(diff_result:, old_manifest:, new_manifest:, old_signature:, new_signature:)
+        return ["full_rebuild", "manifest_parse_failure", true] unless old_manifest.parse.fetch(:ok) && new_manifest.parse.fetch(:ok)
+        return ["noop", "identical_source", false] if diff_result.identical?
+
+        operation_types = diff_result.map(&:type)
+        stable_topology = old_signature == new_signature
+
+        if content_only?(operation_types) && stable_topology
+          ["refresh_manifest", "content_only_stable_topology", false]
+        elsif stable_topology
+          ["rebuild_manifest", "dynamic_template_operation", true]
+        else
+          ["rebuild_manifest", "manifest_topology_changed", true]
+        end
+      end
+
+      def content_only?(operation_types)
+        (operation_types - CONTENT_ONLY_OPERATION_TYPES).empty?
+      end
+
+      def topology_signature(manifest)
+        return { parse_ok: false } unless manifest.parse.fetch(:ok)
+
+        {
+          root_shape: manifest.root_shape.slice(:significant_children, :root_elements, :root_types, :single_root, :multi_root),
+          fragment_roots: fragment_root_signature(manifest),
+          render_sites: render_site_signature(manifest)
+        }
+      end
+
+      def fragment_root_signature(manifest)
+        manifest.frontend_tag_plan
+          .select { |tag| tag.fetch(:kind) == "fragment_root" }
+          .map { |tag| { tag_name: tag.fetch(:tag_name), attributes: tag.fetch(:attributes).map { |attribute| attribute.fetch(:name) } } }
+      end
+
+      def render_site_signature(manifest)
+        manifest.render_nodes.map do |render_node|
+          {
+            kind: render_node.fetch(:kind),
+            partial: render_node.fetch(:partial),
+            template_path: render_node.fetch(:template_path),
+            collection: render_node.fetch(:collection),
+            object: render_node.fetch(:object),
+            as: render_node.fetch(:as),
+            locals: render_node.fetch(:locals),
+            block_arguments: render_node.fetch(:block_arguments)
+          }
+        end
+      end
+
+      def operation_payload(operation)
+        {
+          type: operation.type.to_s,
+          path: operation.path,
+          old_node: operation.old_node&.class&.name,
+          new_node: operation.new_node&.class&.name,
+          old_index: operation.old_index,
+          new_index: operation.new_index
+        }.compact
+      end
+    end
+  end
+end

data/lib/upkeep/herb/source_instrumenter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "template_manifest"
+
+module Upkeep
+  module HerbSupport
+    class SourceInstrumenter
+      def initialize(manifest:)
+        @manifest = manifest
+      end
+
+      def instrument(source)
+        return source unless manifest.parse.fetch(:ok) || manifest.recovered?
+
+        apply_replacements(source, replacements_for(source))
+      end
+
+      private
+
+      attr_reader :manifest
+
+      def replacements_for(source)
+        render_site_replacements + marker_replacements(source)
+      end
+
+      def render_site_replacements
+        return [] unless manifest.parse.fetch(:ok)
+
+        manifest.render_nodes.select { |render_node| render_node.fetch(:render_site_container) }.map do |render_node|
+          [
+            render_node.fetch(:start_offset),
+            render_node.fetch(:end_offset),
+            %(<%= upkeep_frame("#{render_node.fetch(:site_id)}", manifest_path: "#{manifest.path}", manifest_fingerprint: "#{manifest.fingerprint}") { #{render_node.fetch(:expression)} } %>)
+          ]
+        end
+      end
+
+      def marker_replacements(source)
+        frontend_tag_plan_for_instrumentation
+          .filter_map { |tag| root_marker_replacement(source, tag) }
+      end
+
+      def frontend_tag_plan_for_instrumentation
+        return manifest.frontend_tag_plan.select { |entry| %w[fragment_root page_root render_site].include?(entry.fetch(:kind)) } if manifest.parse.fetch(:ok)
+
+        manifest.recovery_frontend_tag_plan.select { |entry| %w[fragment_root page_root].include?(entry.fetch(:kind)) }
+      end
+
+      def root_marker_replacement(source, tag)
+        return helper_marker_replacement(source, tag) if helper_lowered_tag?(tag)
+
+        offset = offset_for_location(source, tag.fetch(:location).fetch(:start))
+        open_tag_end = source.index(">", offset)
+        return unless open_tag_end
+
+        open_tag = source[offset...open_tag_end]
+        return if tag.fetch(:attributes).any? { |attribute| open_tag.include?(%(#{attribute.fetch(:name)}=)) }
+
+        insert_at = fragment_root_insert_offset(source, offset, tag.fetch(:tag_name))
+        [insert_at, insert_at, " #{attributes_source(tag.fetch(:attributes))}"]
+      end
+
+      def helper_marker_replacement(source, tag)
+        return unless tag_helper_source?(tag)
+
+        offset = offset_for_location(source, tag.fetch(:location).fetch(:start))
+        erb_end = source.index("%>", offset)
+        return unless erb_end
+
+        opening = source[offset...erb_end]
+        return if tag.fetch(:attributes).any? { |attribute| opening.include?(attribute.fetch(:name)) }
+
+        block_match = /\s+do(?:\s*\|[^|]*\|)?\s*\z/.match(opening)
+        return unless block_match
+
+        before_block = opening[0...block_match.begin(0)].rstrip
+        insert_at = offset + block_match.begin(0)
+        [
+          insert_at,
+          insert_at,
+          "#{helper_attribute_separator(before_block)}#{helper_attributes_source(tag.fetch(:attributes))}"
+        ]
+      end
+
+      def helper_lowered_tag?(tag)
+        tag.fetch(:element_source) != "HTML"
+      end
+
+      def tag_helper_source?(tag)
+        [
+          "ActionView::Helpers::TagHelper#tag",
+          "ActionView::Helpers::TagHelper#content_tag"
+        ].include?(tag.fetch(:element_source))
+      end
+
+      def helper_attribute_separator(before_block)
+        return ", " if before_block.match?(/\bcontent_tag\b/)
+
+        tag_call = before_block.match(/<%=?\s*tag\.[a-zA-Z_][a-zA-Z0-9_:-]*/)
+        return " " if tag_call && before_block[tag_call.end(0)..].to_s.strip.empty?
+
+        ", "
+      end
+
+      def helper_attributes_source(attributes)
+        attributes.map do |attribute|
+          %(#{attribute.fetch(:name).inspect} => #{ruby_attribute_value(attribute.fetch(:value))})
+        end.join(", ")
+      end
+
+      def ruby_attribute_value(value)
+        if (match = /\A<%=\s*(.*?)\s*%>\z/.match(value.to_s))
+          match[1]
+        else
+          value.inspect
+        end
+      end
+
+      def fragment_root_insert_offset(source, offset, tag_name)
+        match = /\A<\s*#{Regexp.escape(tag_name)}\b/i.match(source[offset..])
+        raise "could not locate fragment root tag for #{manifest.path}" unless match
+
+        offset + match.end(0)
+      end
+
+      def attributes_source(attributes)
+        attributes.map { |attribute| %(#{attribute.fetch(:name)}="#{attribute.fetch(:value)}") }.join(" ")
+      end
+
+      def apply_replacements(source, replacements)
+        replacements.sort_by { |start_offset, end_offset, _replacement| [-start_offset, -end_offset] }.each_with_object(source.dup) do |(start_offset, end_offset, replacement), result|
+          result[start_offset...end_offset] = replacement
+        end
+      end
+
+      def offset_for_location(source, position)
+        line_offsets(source).fetch(position.fetch(:line) - 1) + position.fetch(:column)
+      end
+
+      def line_offsets(source)
+        offsets = [0]
+        source.each_line(chomp: false).with_index do |line, index|
+          offsets[index + 1] = offsets[index] + line.bytesize
+        end
+        offsets
+      end
+    end
+  end
+end