upkeep-rails 0.1.6

data/lib/upkeep/herb/template_manifest.rb

@@ -0,0 +1,514 @@
+# frozen_string_literal: true
+
+require "digest"
+require "herb"
+
+module Upkeep
+  module HerbSupport
+    class TemplateManifest
+      DEFAULT_PARSE_OPTIONS = {
+        strict: true,
+        track_whitespace: true,
+        render_nodes: true,
+        action_view_helpers: true,
+        transform_conditionals: true
+      }.freeze
+
+      EMPTY_ROOT_SHAPE = {
+        significant_children: 0,
+        root_elements: 0,
+        single_root: false,
+        multi_root: false
+      }.freeze
+
+      attr_reader :path, :parse, :root_shape, :frontend_tag_plan, :render_nodes, :helper_lowered_elements, :recovery
+
+      def self.build(path:, source:, parse_options: DEFAULT_PARSE_OPTIONS)
+        parse_result = ::Herb.parse(source, **parse_options)
+        parse = parse_status(parse_result, mode: parse_mode(parse_options))
+
+        if parse.fetch(:ok)
+          visitor = Visitor.new(path: path, source: source)
+          parse_result.value&.accept(visitor)
+
+          return new(
+            path: path,
+            parse: parse,
+            root_shape: visitor.root_shape,
+            frontend_tag_plan: visitor.frontend_tag_plan,
+            render_nodes: visitor.render_nodes,
+            helper_lowered_elements: visitor.helper_lowered_elements,
+            recovery: nil
+          )
+        end
+
+        parse, recovery = recovery_for(path: path, source: source, parse: parse, parse_options: parse_options)
+
+        new(
+          path: path,
+          parse: parse,
+          root_shape: EMPTY_ROOT_SHAPE,
+          frontend_tag_plan: [],
+          render_nodes: [],
+          helper_lowered_elements: [],
+          recovery: recovery
+        )
+      rescue StandardError => error
+        new(
+          path: path,
+          parse: {
+            ok: false,
+            mode: parse_mode(parse_options),
+            exception: error.class.name,
+            message: error.message,
+            recovered: false
+          },
+          root_shape: EMPTY_ROOT_SHAPE,
+          frontend_tag_plan: [],
+          render_nodes: [],
+          helper_lowered_elements: [],
+          recovery: nil
+        )
+      end
+
+      def self.summary(manifests)
+        partials = manifests.select(&:partial?)
+
+        {
+          templates_scanned: manifests.size,
+          strict_parse_failures: manifests.count { |manifest| !manifest.parse.fetch(:ok) },
+          recoverable_parse_failures: manifests.count(&:recovered?),
+          recovered_render_nodes: manifests.sum { |manifest| manifest.recovery_render_nodes.size },
+          render_nodes: manifests.sum { |manifest| manifest.render_nodes.size },
+          helper_lowered_elements: manifests.sum { |manifest| manifest.helper_lowered_elements.size },
+          frontend_tag_targets: manifests.sum { |manifest| manifest.frontend_tag_plan.size },
+          page_root_tags: manifests.sum { |manifest| manifest.frontend_tag_plan.count { |tag| tag.fetch(:kind) == "page_root" } },
+          fragment_root_tags: manifests.sum { |manifest| manifest.frontend_tag_plan.count { |tag| tag.fetch(:kind) == "fragment_root" } },
+          render_site_tags: manifests.sum { |manifest| manifest.frontend_tag_plan.count { |tag| tag.fetch(:kind) == "render_site" } },
+          partials: partials.size,
+          single_root_partials: partials.count { |manifest| manifest.root_shape.fetch(:single_root, false) },
+          multi_root_partials: partials.count { |manifest| manifest.root_shape.fetch(:multi_root, false) }
+        }
+      end
+
+      def self.parse_status(parse_result, mode:)
+        errors = parse_result.errors.map { |error| error_payload(error) }
+        warnings = parse_result.warnings.map { |warning| error_payload(warning) }
+
+        {
+          ok: errors.empty?,
+          mode: mode,
+          errors: errors,
+          warnings: warnings,
+          recovered: false
+        }
+      end
+      private_class_method :parse_status
+
+      def self.recovery_for(path:, source:, parse:, parse_options:)
+        return [parse, nil] unless parse_options.fetch(:strict, false)
+
+        recovery_options = parse_options.merge(strict: false)
+        recovery_result = ::Herb.parse(source, **recovery_options)
+        recovery_parse = parse_status(recovery_result, mode: "non_strict")
+        parse = parse.merge(recovered: recovery_parse.fetch(:ok), recovery: recovery_parse)
+
+        return [parse, { parse: recovery_parse }] unless recovery_parse.fetch(:ok)
+
+        visitor = Visitor.new(path: path, source: source)
+        recovery_result.value&.accept(visitor)
+
+        [
+          parse,
+          {
+            parse: recovery_parse,
+            root_shape: visitor.root_shape,
+            frontend_tag_plan: visitor.frontend_tag_plan,
+            render_nodes: visitor.render_nodes,
+            helper_lowered_elements: visitor.helper_lowered_elements
+          }
+        ]
+      end
+      private_class_method :recovery_for
+
+      def self.parse_mode(parse_options)
+        parse_options.fetch(:strict, false) ? "strict" : "non_strict"
+      end
+      private_class_method :parse_mode
+
+      def self.error_payload(error)
+        {
+          class: error.class.name,
+          message: error.respond_to?(:message) ? error.message : error.inspect,
+          location: error.respond_to?(:location) ? location_payload(error.location) : nil
+        }
+      end
+      private_class_method :error_payload
+
+      def self.location_payload(location)
+        return nil unless location
+
+        {
+          start: {
+            line: location.start.line,
+            column: location.start.column
+          },
+          end: {
+            line: location.end.line,
+            column: location.end.column
+          }
+        }
+      end
+      private_class_method :location_payload
+
+      def initialize(path:, parse:, root_shape:, frontend_tag_plan:, render_nodes:, helper_lowered_elements:, recovery:)
+        @path = path
+        @parse = parse
+        @root_shape = root_shape
+        @frontend_tag_plan = frontend_tag_plan
+        @render_nodes = render_nodes
+        @helper_lowered_elements = helper_lowered_elements
+        @recovery = recovery
+      end
+
+      def to_h
+        {
+          path: path,
+          parse: parse,
+          root_shape: root_shape,
+          frontend_tag_plan: frontend_tag_plan,
+          render_nodes: render_nodes,
+          helper_lowered_elements: helper_lowered_elements,
+          recovery: recovery
+        }.compact
+      end
+
+      def fingerprint
+        @fingerprint ||= Digest::SHA256.hexdigest(to_h.inspect)[0, 16]
+      end
+
+      def partial?
+        File.basename(path).start_with?("_")
+      end
+
+      def recovered?
+        parse.fetch(:recovered, false)
+      end
+
+      def recovery_frontend_tag_plan
+        Array(recovery&.fetch(:frontend_tag_plan, []))
+      end
+
+      def recovery_render_nodes
+        Array(recovery&.fetch(:render_nodes, []))
+      end
+
+      class Visitor < ::Herb::Visitor
+        attr_reader :frontend_tag_plan, :render_nodes, :helper_lowered_elements
+
+        def initialize(path:, source:)
+          super()
+          @path = path
+          @frontend_tag_plan = []
+          @render_nodes = []
+          @helper_lowered_elements = []
+          @html_stack = []
+          @root_shape = nil
+          @line_offsets = build_line_offsets(source)
+        end
+
+        def root_shape
+          @root_shape || EMPTY_ROOT_SHAPE
+        end
+
+        def visit_document_node(node)
+          significant_children = node.children.reject { |child| insignificant_document_child?(child) }
+          root_elements = significant_children.select { |child| html_element?(child) }
+
+          @root_shape = {
+            significant_children: significant_children.size,
+            root_elements: root_elements.size,
+            root_types: significant_children.map { |child| child.class.name },
+            single_root: significant_children.size == 1 && root_elements.size == 1,
+            single_root_element: root_elements.size == 1,
+            multi_root: root_elements.size > 1
+          }
+
+          if partial_template?
+            plan_fragment_root_tag(root_elements.first) if root_shape.fetch(:single_root)
+          elsif root_shape.fetch(:single_root_element)
+            # A page template's recorded frame target needs a matching DOM marker so it can be
+            # resolved during full-page rerender. Page templates routinely carry non-element
+            # siblings such as `content_for`/`yield :head` ERB statements that produce no enclosing
+            # DOM, so anchor the page-frame marker to the single root element rather than requiring
+            # the element to be the only significant child.
+            plan_page_root_tag(root_elements.first)
+          end
+
+          super
+        end
+
+        def visit_erb_render_node(node)
+          keywords = node.keywords
+          render_node = render_node_payload(node, keywords)
+
+          @render_nodes << render_node
+          @frontend_tag_plan << render_site_tag(render_node) if render_node.fetch(:render_site_container)
+
+          super
+        end
+
+        def visit_html_element_node(node)
+          if node.respond_to?(:element_source) && node.element_source && node.element_source != "HTML"
+            @helper_lowered_elements << {
+              location: location_payload(node.location),
+              tag_name: token_value(node.tag_name),
+              element_source: node.element_source
+            }
+          end
+
+          @html_stack.push(node)
+          begin
+            super
+          ensure
+            @html_stack.pop
+          end
+        end
+
+        private
+
+        attr_reader :path, :line_offsets, :html_stack
+
+        def build_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
+
+        def offset_for(position)
+          line_offsets.fetch(position.line - 1) + position.column
+        end
+
+        def render_node_payload(node, keywords)
+          {
+            location: location_payload(node.location),
+            site_id: site_id("render", node.location),
+            expression: token_value(node.content)&.strip,
+            start_offset: offset_for(node.location.start),
+            end_offset: offset_for(node.location.end),
+            kind: render_kind(keywords),
+            partial: token_value(keywords&.partial),
+            template_path: token_value(keywords&.template_path),
+            layout: token_value(keywords&.layout),
+            collection: token_value(keywords&.collection),
+            object: token_value(keywords&.object),
+            as: token_value(keywords&.as_name),
+            locals: Array(keywords&.locals).map { |local| token_value(local.name) },
+            block_arguments: Array(node.block_arguments).map { |argument| token_value(argument.name) },
+            render_site_container: render_site_container_for(node, keywords),
+            render_site_source: render_site_source(keywords)
+          }
+        end
+
+        def plan_fragment_root_tag(root_element)
+          @frontend_tag_plan << {
+            kind: "fragment_root",
+            target: "root_element",
+            location: location_payload(root_element.location),
+            tag_name: token_value(root_element.tag_name),
+            element_source: element_source(root_element),
+            attributes: [
+              {
+                name: "data-upkeep-frame",
+                value: "<%= upkeep_frame_id %>"
+              },
+              {
+                name: "data-upkeep-template",
+                value: template_id
+              }
+            ],
+            update_role: "morph or replace this rendered fragment when runtime observations match a committed change"
+          }
+        end
+
+        def plan_page_root_tag(root_element)
+          @frontend_tag_plan << {
+            kind: "page_root",
+            target: "root_element",
+            location: location_payload(root_element.location),
+            tag_name: token_value(root_element.tag_name),
+            element_source: element_source(root_element),
+            attributes: [
+              {
+                name: "data-upkeep-page-frame",
+                value: "<%= upkeep_page_frame_id %>"
+              }
+            ],
+            update_role: "replace this rendered page when no narrower frame can safely cover a change"
+          }
+        end
+
+        def render_site_tag(render_node)
+          container = render_node.fetch(:render_site_container)
+
+          {
+            kind: "render_site",
+            target: "container_element",
+            location: container.fetch(:location),
+            tag_name: container.fetch(:tag_name),
+            element_source: container.fetch(:element_source),
+            site_id: render_node.fetch(:site_id),
+            attributes: [
+              {
+                name: "data-upkeep-render-site",
+                value: render_node.fetch(:site_id)
+              }
+            ],
+            render: {
+              kind: render_node.fetch(:kind),
+              partial: render_node.fetch(:partial),
+              collection: render_node.fetch(:collection),
+              object: render_node.fetch(:object),
+              as: render_node.fetch(:as),
+              source: render_node.fetch(:render_site_source)
+            },
+            update_role: render_site_update_role(render_node)
+          }
+        end
+
+        def render_site_update_role(render_node)
+          case render_node.fetch(:render_site_source)
+          when "collection_keyword"
+            "anchor collection membership while child partial roots carry per-record frame tags"
+          when "object_shorthand"
+            "anchor a render-object shorthand when ActionView runtime confirms it rendered a collection"
+          else
+            "record where ActionView runtime must confirm the rendered frame target"
+          end
+        end
+
+        def render_site_container_for(node, keywords)
+          source = render_site_source(keywords)
+          return unless source
+
+          container = html_stack.last
+          return unless container
+          return unless safe_collection_container?(container, node)
+
+          {
+            location: location_payload(container.location),
+            tag_name: token_value(container.tag_name),
+            element_source: element_source(container),
+            source: source
+          }
+        end
+
+        def render_site_source(keywords)
+          return "collection_keyword" if token_value(keywords&.collection)
+
+          # ActionView accepts `render @records` / `render records` as a
+          # polymorphic render. Herb can identify the stable DOM container, but
+          # Ruby decides at runtime whether the object is a collection, a single
+          # record, or a renderable component. Mark it as a candidate only; the
+          # runtime collection renderer must still confirm a collection before a
+          # render-site frame is recorded.
+          return "object_shorthand" if token_value(keywords&.object)
+
+          nil
+        end
+
+        def safe_collection_container?(container, render_node)
+          children = meaningful_children(container)
+          children.one? && children.first.equal?(render_node)
+        end
+
+        def meaningful_children(node)
+          Array(node.body).reject { |child| insignificant_document_child?(child) }
+        end
+
+        def render_kind(keywords)
+          return "unknown" unless keywords
+
+          %i[
+            partial template_path layout file inline_template body plain html
+            renderable collection object
+          ].find { |name| token_value(keywords.public_send(name)) }&.to_s || "unknown"
+        end
+
+        def insignificant_document_child?(node)
+          return true if html_text?(node) && token_value(node.content).to_s.strip.empty?
+          return true if html_doctype?(node)
+          return true if erb_comment?(node)
+
+          false
+        end
+
+        def html_text?(node)
+          node.class.name == "Herb::AST::HTMLTextNode"
+        end
+
+        def html_element?(node)
+          [
+            "Herb::AST::HTMLElementNode",
+            "Herb::AST::HTMLConditionalElementNode"
+          ].include?(node.class.name)
+        end
+
+        def element_source(node)
+          node.element_source
+        end
+
+        def html_doctype?(node)
+          node.class.name == "Herb::AST::HTMLDoctypeNode"
+        end
+
+        def erb_comment?(node)
+          node.respond_to?(:tag_opening) && token_value(node.tag_opening).to_s.start_with?("<%#")
+        end
+
+        def partial_template?
+          File.basename(path).start_with?("_")
+        end
+
+        def template_id
+          Digest::SHA256.hexdigest(path)[0, 16]
+        end
+
+        def site_id(kind, location)
+          Digest::SHA256.hexdigest([
+            path,
+            kind,
+            location&.start&.line,
+            location&.start&.column,
+            location&.end&.line,
+            location&.end&.column
+          ].join(":"))[0, 16]
+        end
+
+        def token_value(token)
+          return nil unless token
+          return token.value if token.respond_to?(:value)
+
+          token.to_s
+        end
+
+        def location_payload(location)
+          return nil unless location
+
+          {
+            start: {
+              line: location.start.line,
+              column: location.start.column
+            },
+            end: {
+              line: location.end.line,
+              column: location.end.column
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/invalidation/collection_append.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Invalidation
+    class CollectionAppend
+      def self.build(recipe:, change:)
+        new(recipe, change).build
+      end
+
+      def initialize(recipe, change)
+        @recipe = recipe
+        @change = change
+      end
+
+      def build
+        replay = recipe.replay
+        return unless replay.is_a?(Replay::Collection)
+        return if replay.derived_partial?
+        return unless create_change?
+
+        collection = replay.collection
+        return unless collection.is_a?(Replay::ActiveRecordRelationValue)
+        return unless collection.primary_key
+        return unless collection.appendable? || unfilled_limit_window?(collection)
+
+        model = constantize(collection.model)
+        return unless change.fetch(:table) == model.table_name
+
+        record = model.find_by(id: change.fetch(:id))
+        return unless record && relation_appends_record?(model, collection, record)
+
+        Replay::Recipe.new(
+          kind: :render_site_append,
+          frame_id: recipe.frame_id,
+          target_kind: recipe.target_kind,
+          target_id: recipe.target_id,
+          template: recipe.template,
+          metadata: recipe.metadata,
+          runtime: "rails",
+          replay: Replay::CollectionMember.new(
+            controller_class: replay.controller_class,
+            partial: replay.partial,
+            record: Replay.active_record_value(record),
+            options: replay.options
+          )
+        )
+      end
+
+      private
+
+      attr_reader :recipe, :change
+
+      def create_change?
+        change[:id] && change.fetch(:type).to_s.include?("create")
+      end
+
+      def relation_appends_record?(model, collection, record)
+        primary_key = collection.primary_key
+        snapshot_ids = collection.member_ids.map(&:to_s)
+        candidate_ids = (snapshot_ids + [record.public_send(primary_key).to_s]).uniq
+        ordered_ids = model.find_by_sql(collection.sql).filter_map do |candidate|
+          candidate_id = candidate.public_send(primary_key).to_s
+          candidate_id if candidate_ids.include?(candidate_id)
+        end
+
+        ordered_ids.last == record.public_send(primary_key).to_s &&
+          (snapshot_ids - ordered_ids).empty?
+      end
+
+      def unfilled_limit_window?(collection)
+        return false unless collection.limit_value
+
+        limit = Integer(collection.limit_value)
+        limit.positive? && collection.member_ids.size < limit
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def constantize(name)
+        name.to_s.split("::").reduce(Object) { |namespace, constant_name| namespace.const_get(constant_name) }
+      end
+    end
+  end
+end

data/lib/upkeep/invalidation/collection_member_replace.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Invalidation
+    class CollectionMemberReplace
+      def self.build(recipe:, change:)
+        new(recipe, change).build
+      end
+
+      def initialize(recipe, change)
+        @recipe = recipe
+        @change = change
+      end
+
+      def build
+        replay = recipe.replay
+        return unless replay.is_a?(Replay::Collection)
+        return if replay.derived_partial?
+        return unless update_change?
+
+        collection = replay.collection
+        return unless collection.is_a?(Replay::ActiveRecordRelationValue)
+        return unless collection.primary_key
+        return unless collection.member_ids.map(&:to_s).include?(change.fetch(:id).to_s)
+
+        model = constantize(collection.model)
+        return unless change.fetch(:table) == model.table_name
+
+        record = model.find_by(id: change.fetch(:id))
+        return unless record && relation_keeps_member_order?(model, collection)
+
+        Replay::Recipe.new(
+          kind: :render_site_member_replace,
+          frame_id: recipe.frame_id,
+          target_kind: "dom_id",
+          target_id: dom_id(model, change.fetch(:id)),
+          template: recipe.template,
+          metadata: recipe.metadata,
+          runtime: "rails",
+          replay: Replay::CollectionMember.new(
+            controller_class: replay.controller_class,
+            partial: replay.partial,
+            record: Replay.active_record_value(record),
+            options: replay.options
+          )
+        )
+      end
+
+      private
+
+      attr_reader :recipe, :change
+
+      def update_change?
+        type = change.fetch(:type).to_s
+        change[:id] && !type.include?("create") && !type.include?("destroy") && !type.include?("delete")
+      end
+
+      def relation_keeps_member_order?(model, collection)
+        primary_key = collection.primary_key
+        snapshot_ids = collection.member_ids.map(&:to_s)
+        ordered_ids = model.find_by_sql(collection.sql).filter_map do |candidate|
+          candidate_id = candidate.public_send(primary_key).to_s
+          candidate_id if snapshot_ids.include?(candidate_id)
+        end
+
+        ordered_ids == snapshot_ids
+      end
+
+      def dom_id(model, id)
+        "#{model.model_name.param_key}_#{id}"
+      end
+
+      def constantize(name)
+        name.to_s.split("::").reduce(Object) { |namespace, constant_name| namespace.const_get(constant_name) }
+      end
+    end
+  end
+end