upkeep-rails 0.1.0

data/lib/upkeep/dependencies.rb

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Upkeep
+  module Dependencies
+    class Base
+      attr_reader :source, :key, :metadata
+
+      def initialize(source:, key:, metadata: {})
+        @source = source
+        @key = key
+        @metadata = metadata
+      end
+
+      def cache_key
+        [source, key]
+      end
+
+      def matches_change?(_change)
+        false
+      end
+
+      def identity?
+        false
+      end
+
+      def identity_key
+        nil
+      end
+
+      def visibility
+        :public
+      end
+
+      def precision
+        :unknown
+      end
+
+      def narrow_frame_safe?
+        false
+      end
+
+      def to_h
+        {
+          source: source,
+          key: key,
+          visibility: visibility,
+          precision: precision,
+          metadata: metadata
+        }
+      end
+    end
+
+    class ActiveRecordAttribute < Base
+      def initialize(table:, id:, attribute:, model: nil)
+        super(
+          source: :active_record_attribute,
+          key: { table: table, id: id, attribute: attribute },
+          metadata: { model: model }.compact
+        )
+      end
+
+      def matches_change?(change)
+        key.fetch(:table) == change.fetch(:table) &&
+          (!change[:id] || key.fetch(:id) == change[:id]) &&
+          change.fetch(:changed_attributes, []).include?(key.fetch(:attribute))
+      end
+
+      def precision
+        :record_attribute
+      end
+
+      def narrow_frame_safe?
+        true
+      end
+    end
+
+    class ActiveRecordCollection < Base
+      UNKNOWN = Object.new
+
+      def initialize(
+        primary_table:,
+        table_columns:,
+        coverage:,
+        sql:,
+        predicates: [],
+        source: :active_record_collection,
+        precision: :collection_predicate
+      )
+        table_columns = normalize_table_columns(table_columns)
+        coverage = coverage.to_sym
+        unless coverage == :columns
+          raise ArgumentError,
+            "unsupported Active Record predicate coverage: #{coverage}; collection dependencies require proven column coverage"
+        end
+
+        @precision = precision.to_sym
+        super(
+          source: source.to_sym,
+          key: {
+            table: primary_table,
+            predicate_digest: Digest::SHA256.hexdigest(sql)[0, 16]
+          },
+          metadata: {
+            primary_table: primary_table,
+            table_columns: table_columns,
+            coverage: coverage.to_s,
+            sql: sql,
+            predicates: normalize_predicates(predicates)
+          }
+        )
+      end
+
+      def matches_change?(change)
+        return false unless table_columns.key?(change.fetch(:table))
+
+        predicate_match = predicate_match(change)
+        return predicate_match unless predicate_match == UNKNOWN
+
+        return true if create_change?(change)
+        return true if delete_change?(change)
+
+        table_columns.fetch(change.fetch(:table)).intersect?(change.fetch(:changed_attributes, []))
+      end
+
+      def precision
+        @precision
+      end
+
+      def collection_lookup_tables
+        table_columns.keys.sort
+      end
+
+      def collection_lookup_columns
+        table_columns.flat_map do |table, columns|
+          columns.map { |column| [table, column] }
+        end.sort
+      end
+
+      private
+
+      def predicate_match(change)
+        predicates = predicates_for_table(change.fetch(:table))
+        return UNKNOWN if predicates.empty?
+
+        old_match = values_match_predicates(change.fetch(:old_values, {}), predicates)
+        new_match = values_match_predicates(change.fetch(:new_values, {}), predicates)
+        return true if old_match == true || new_match == true
+
+        if old_match == false || new_match == false
+          return false if predicate_columns(predicates).intersect?(change.fetch(:changed_attributes, [])) ||
+            create_change?(change) ||
+            delete_change?(change)
+        end
+
+        UNKNOWN
+      end
+
+      def create_change?(change)
+        change.fetch(:type).to_s.include?("create")
+      end
+
+      def delete_change?(change)
+        type = change.fetch(:type).to_s
+        type.include?("delete") || type.include?("destroy")
+      end
+
+      def values_match_predicates(values, predicates)
+        values = stringify_keys(values)
+        return UNKNOWN unless predicates.all? { |predicate| values.key?(predicate.fetch(:column)) }
+
+        predicates.all? do |predicate|
+          value = values.fetch(predicate.fetch(:column))
+          predicate.fetch(:values).include?(value)
+        end
+      end
+
+      def predicates_for_table(table)
+        predicates.select { |predicate| predicate.fetch(:table) == table.to_s }
+      end
+
+      def predicate_columns(predicates)
+        predicates.map { |predicate| predicate.fetch(:column) }.uniq
+      end
+
+      def coverage
+        metadata.fetch(:coverage).to_sym.tap do |value|
+          raise ArgumentError, "unsupported Active Record collection coverage: #{value}" unless value == :columns
+        end
+      end
+
+      def table_columns
+        metadata.fetch(:table_columns)
+      end
+
+      def predicates
+        metadata.fetch(:predicates)
+      end
+
+      def normalize_table_columns(value)
+        Dependencies.symbolize_keys(value).to_h do |table, columns|
+          [table.to_s, Array(columns).map(&:to_s).uniq.sort]
+        end
+      end
+
+      def normalize_predicates(value)
+        Array(value).filter_map do |predicate|
+          predicate = Dependencies.symbolize_keys(predicate)
+          values = Array(predicate[:values]).compact
+          next if predicate[:table].nil? || predicate[:column].nil? || values.empty?
+
+          {
+            table: predicate.fetch(:table).to_s,
+            column: predicate.fetch(:column).to_s,
+            operator: predicate.fetch(:operator, "eq").to_s,
+            values: values.uniq
+          }
+        end
+      end
+
+      def stringify_keys(values)
+        values.to_h.transform_keys(&:to_s)
+      end
+    end
+
+    class ActiveRecordQuery < ActiveRecordCollection
+      def initialize(primary_table:, table_columns:, coverage:, sql:, predicates: [])
+        super(
+          primary_table: primary_table,
+          table_columns: table_columns,
+          coverage: coverage,
+          sql: sql,
+          predicates: predicates,
+          source: :active_record_query,
+          precision: :query_predicate
+        )
+      end
+    end
+
+    class Identity < Base
+      def initialize(source:, key:, value:, metadata: {})
+        super(
+          source: source,
+          key: { key: key, value: value },
+          metadata: metadata
+        )
+      end
+
+      def identity?
+        true
+      end
+
+      def identity_key
+        { source: source, key: key.fetch(:key), value: key.fetch(:value) }
+      end
+
+      def visibility
+        :identity_bound
+      end
+
+      def precision
+        :identity
+      end
+    end
+
+    class WardenUser < Identity
+      def initialize(scope:, user:)
+        super(
+          source: :warden_user,
+          key: scope.to_s,
+          value: Dependencies.model_identity(user),
+          metadata: Dependencies.model_metadata(user).merge(scope: scope.to_s)
+        )
+      end
+    end
+
+    class CurrentAttribute < Identity
+      def initialize(owner:, name:, value:)
+        super(
+          source: :current_attribute,
+          key: "#{owner}.#{name}",
+          value: Dependencies.canonical_identity(value),
+          metadata: { owner: owner.to_s, name: name.to_s }
+        )
+      end
+    end
+
+    class SessionValue < Identity
+      def initialize(key:, value:)
+        super(
+          source: :session,
+          key: key.to_s,
+          value: Dependencies.private_fingerprint(value),
+          metadata: { key: key.to_s, value_class: value.class.name }
+        )
+      end
+    end
+
+    class CookieValue < Identity
+      def initialize(key:, value:)
+        super(
+          source: :cookie,
+          key: key.to_s,
+          value: Dependencies.private_fingerprint(value),
+          metadata: { key: key.to_s, value_class: value.class.name }
+        )
+      end
+    end
+
+    class RequestValue < Identity
+      def initialize(key:, value:)
+        super(
+          source: :request,
+          key: key.to_s,
+          value: Dependencies.private_fingerprint(value),
+          metadata: { key: key.to_s, value_class: value.class.name }
+        )
+      end
+    end
+
+    class Unknown < Base
+      def initialize(source:, metadata: {})
+        super(
+          source: source,
+          key: Digest::SHA256.hexdigest(metadata.inspect)[0, 16],
+          metadata: metadata
+        )
+      end
+
+      def visibility
+        :private
+      end
+    end
+
+    class Restored < Base
+      def initialize(source:, key:, metadata:, visibility:, precision:)
+        super(source: source, key: key, metadata: metadata)
+        @visibility = visibility.to_sym
+        @precision = precision.to_sym
+      end
+
+      def identity?
+        visibility == :identity_bound
+      end
+
+      def identity_key
+        return unless identity?
+
+        { source: source, key: key.fetch(:key), value: key.fetch(:value) }
+      end
+
+      attr_reader :visibility, :precision
+    end
+
+    module_function
+
+    def from_h(snapshot)
+      snapshot = symbolize_keys(snapshot)
+      source = snapshot.fetch(:source)
+      key = symbolize_keys(snapshot.fetch(:key))
+      metadata = symbolize_keys(snapshot.fetch(:metadata))
+
+      case source.to_sym
+      when :active_record_attribute
+        ActiveRecordAttribute.new(
+          table: key.fetch(:table),
+          id: key.fetch(:id),
+          attribute: key.fetch(:attribute),
+          model: metadata[:model]
+        )
+      when :active_record_collection, :active_record_query
+        dependency_class = source.to_sym == :active_record_query ? ActiveRecordQuery : ActiveRecordCollection
+        dependency_class.new(
+          primary_table: metadata.fetch(:primary_table),
+          table_columns: metadata.fetch(:table_columns),
+          coverage: metadata.fetch(:coverage),
+          sql: metadata.fetch(:sql),
+          predicates: metadata.fetch(:predicates)
+        )
+      else
+        if snapshot.fetch(:visibility).to_sym == :identity_bound
+          Identity.new(
+            source: source,
+            key: key.fetch(:key),
+            value: key.fetch(:value),
+            metadata: metadata
+          )
+        else
+          Restored.new(
+            source: source,
+            key: key,
+            metadata: metadata,
+            visibility: snapshot.fetch(:visibility),
+            precision: snapshot.fetch(:precision)
+          )
+        end
+      end
+    end
+
+    def model_identity(value)
+      return nil unless value
+
+      if value.respond_to?(:id) && value.class.respond_to?(:name)
+        { model: value.class.name, id: value.id }
+      end
+    end
+
+    def model_metadata(value)
+      return {} unless value
+
+      {
+        model: value.class.name,
+        table: value.class.respond_to?(:table_name) ? value.class.table_name : nil,
+        id: value.respond_to?(:id) ? value.id : nil
+      }.compact
+    end
+
+    def canonical_identity(value)
+      case value
+      when nil, true, false, Numeric, String, Symbol
+        value
+      else
+        model_identity(value) || private_fingerprint(value)
+      end
+    end
+
+    def private_fingerprint(value)
+      Digest::SHA256.hexdigest(JSON.generate(private_fingerprint_payload(value)))[0, 16]
+    end
+
+    def private_fingerprint_payload(value)
+      case value
+      when nil, true, false, Numeric, String
+        [value.class.name, value]
+      when Symbol
+        ["Symbol", value.to_s]
+      when Array
+        ["Array", value.map { |item| private_fingerprint_payload(item) }]
+      when Hash
+        entries = value.keys.sort_by { |key| JSON.generate(private_fingerprint_payload(key)) }.map do |key|
+          [private_fingerprint_payload(key), private_fingerprint_payload(value.fetch(key))]
+        end
+        ["Hash", entries]
+      else
+        identity = model_identity(value)
+        identity ? ["Model", identity] : ["Object", value.class.name, value.inspect]
+      end
+    end
+
+    def symbolize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), result|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          result[normalized_key] = symbolize_keys(nested_value)
+        end
+      when Array
+        value.map { |nested_value| symbolize_keys(nested_value) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/upkeep/herb/developer_report.rb

@@ -0,0 +1,116 @@
+# 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.",
+        "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),
+          render_sites: manifest.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|
+            {
+              source: "template",
+              path: manifest.path,
+              reason: blocker,
+              message: template_action_message(blocker)
+            }
+          end
+        end
+      end
+
+      def template_blockers(manifest)
+        blockers = []
+        blockers << "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 << "helper_lowered_html" if manifest.helper_lowered_elements.any?
+        blockers
+      end
+
+      def template_action_message(blocker)
+        case blocker
+        when "parse_failure"
+          FALLBACK_ACTIONS.fetch("parse_failure")
+        when "partial_without_single_root"
+          FALLBACK_ACTIONS.fetch("multi_root_partial")
+        when "page_without_render_site"
+          FALLBACK_ACTIONS.fetch("no_herb_render_site")
+        when "helper_lowered_html"
+          "Replace helper-lowered HTML with explicit template structure when it should be independently updateable."
+        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
+    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