activeadmin_annotations 0.1.0

data/app/views/active_admin/annotations/_panel.html.erb

@@ -0,0 +1,98 @@
+<% annotations_payload = annotations.map do |annotation|
+     {
+       id: annotation.id,
+       field_name: annotation.field_name,
+       selected_text: annotation.selected_text,
+       start_offset: annotation.start_offset,
+       end_offset: annotation.end_offset,
+       comment: annotation.comment,
+       category: annotation.category
+     }
+   end %>
+<% category_options = categories.to_h %>
+<% panel_id = "aa-annotation-#{review.id}" %>
+
+<%= stylesheet_link_tag "activeadmin_annotations", "data-turbo-track": "reload" %>
+
+<div class="aa-annotations-panel">
+  <% if content_stale && stale_message.present? %>
+    <div class="aa-annotations-stale-banner" role="status">
+      <p><%= stale_message %></p>
+      <% if advance_review_url.present? %>
+        <%= button_to "Review latest version",
+          advance_review_url,
+          method: :post,
+          class: "action-item-button" %>
+      <% end %>
+    </div>
+  <% end %>
+
+  <div
+    class="aa-annotations-layout"
+    data-controller="activeadmin-annotations--annotator"
+    data-activeadmin-annotations--annotator-review-id-value="<%= review.id %>"
+    data-activeadmin-annotations--annotator-field-value="<%= field %>"
+    data-activeadmin-annotations--annotator-category-label-value="<%= category_label %>"
+    data-activeadmin-annotations--annotator-categories-value="<%= ERB::Util.html_escape(category_options.to_json) %>"
+    data-activeadmin-annotations--annotator-create-url-value="<%= admin_annotation_spans_path(format: :json) %>"
+    data-activeadmin-annotations--annotator-update-url-template-value="<%= admin_annotation_span_path(":id", format: :json) %>"
+    data-activeadmin-annotations--annotator-annotations-value="<%= ERB::Util.html_escape(annotations_payload.to_json) %>">
+    <div class="aa-annotations-main">
+      <div class="aa-annotations-output">
+        <div
+          class="aa-annotations-annotatable prose"
+          data-activeadmin-annotations--annotator-target="annotatable">
+          <%= content %>
+        </div>
+      </div>
+
+      <% if context_panels.any? %>
+        <div class="aa-annotations-context">
+          <% context_panels.each do |panel| %>
+            <details class="aa-annotations-context-panel">
+              <summary><%= panel.fetch(:title) %></summary>
+              <pre><%= panel.fetch(:content) %></pre>
+            </details>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+
+    <aside class="aa-annotations-sidebar" data-activeadmin-annotations--annotator-target="sidebar">
+      <h4>Annotations</h4>
+      <p class="aa-annotations-hint">Select text in the block, then add a comment.</p>
+      <% if content_revision_enabled && content_revision_label.present? %>
+        <p class="aa-annotations-version"><%= content_revision_label %></p>
+      <% end %>
+
+      <div class="aa-annotations-composer aa-annotations-composer-hidden" data-activeadmin-annotations--annotator-target="composer">
+        <h4 data-activeadmin-annotations--annotator-target="composerHeading">New annotation</h4>
+        <p class="aa-annotations-selected-preview" data-activeadmin-annotations--annotator-target="selectedPreview"></p>
+        <label for="<%= panel_id %>-comment">Comment</label>
+        <textarea
+          id="<%= panel_id %>-comment"
+          rows="4"
+          data-activeadmin-annotations--annotator-target="commentInput"
+          data-action="keydown.meta+enter->activeadmin-annotations--annotator#submitComposer keydown.ctrl+enter->activeadmin-annotations--annotator#submitComposer"></textarea>
+        <% if category_options.any? %>
+          <label for="<%= panel_id %>-category"><%= category_label %></label>
+          <select id="<%= panel_id %>-category" data-activeadmin-annotations--annotator-target="categoryInput">
+            <option value="">None</option>
+            <% category_options.each do |value, label| %>
+              <option value="<%= value %>"><%= label %></option>
+            <% end %>
+          </select>
+        <% else %>
+          <input type="hidden" value="" data-activeadmin-annotations--annotator-target="categoryInput">
+        <% end %>
+        <div class="aa-annotations-composer-actions">
+          <button type="button" class="action-item-button aa-annotations-save-button" data-action="activeadmin-annotations--annotator#submitComposer">Save annotation</button>
+          <button type="button" class="action-item-button" data-action="activeadmin-annotations--annotator#cancelComposer">Cancel</button>
+        </div>
+        <p class="aa-annotations-error aa-annotations-hidden" data-activeadmin-annotations--annotator-target="errorMessage"></p>
+      </div>
+
+      <div class="aa-annotations-list" data-activeadmin-annotations--annotator-target="annotationList"></div>
+    </aside>
+  </div>
+</div>

data/app/views/active_admin/annotations/_read_only_content.html.erb

@@ -0,0 +1,3 @@
+<div class="aa-annotations-panel aa-annotations-panel--read-only">
+  <%= content %>
+</div>

data/config/polyrun_coverage.yml

@@ -0,0 +1,8 @@
+track_under:
+  - lib
+  - app
+minimum_line_percent: 50
+report_formats:
+  - html
+  - cobertura
+  - console

data/db/migrate/20260617120000_create_activeadmin_annotations_tables.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[8.1]
+  def change
+    create_table :annotation_reviews, id: :uuid do |t|
+      t.references :subject, polymorphic: true, null: false, type: :uuid, index: true
+      t.uuid :reviewer_id, null: false
+      t.string :review_status, null: false, default: "pending"
+      t.text :notes
+      t.jsonb :context_json, null: false, default: {}
+      t.string :context_digest
+      t.integer :content_revision_version, null: false, default: 0
+      t.jsonb :metadata_json, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :annotation_reviews, %i[subject_type subject_id reviewer_id], unique: true, name: "index_annotation_reviews_on_subject_and_reviewer"
+    add_index :annotation_reviews, :review_status
+    add_index :annotation_reviews, :context_digest
+    add_index :annotation_reviews, :reviewer_id
+
+    create_table :annotation_spans, id: :uuid do |t|
+      t.references :annotation_review, null: false, type: :uuid, foreign_key: {to_table: :annotation_reviews}, index: true
+      t.string :field_name, null: false
+      t.text :selected_text, null: false
+      t.integer :start_offset, null: false
+      t.integer :end_offset, null: false
+      t.text :comment, null: false
+      t.string :category
+      t.integer :content_revision_version, null: false, default: 0
+      t.jsonb :context_paths_json, null: false, default: []
+      t.jsonb :metadata_json, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :annotation_spans, :category
+    add_index :annotation_spans, :field_name
+  end
+end

data/db/migrate/20260706150000_add_metadata_json_gin_index_to_annotation_reviews.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddMetadataJsonGinIndexToAnnotationReviews < ActiveRecord::Migration[8.1]
+  def change
+    return unless connection.adapter_name.match?(/postgres/i)
+
+    add_index :annotation_reviews, :metadata_json, using: :gin, if_not_exists: true
+  end
+end

data/db/migrate/20260710120000_add_panel_query_index_to_annotation_spans.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddPanelQueryIndexToAnnotationSpans < ActiveRecord::Migration[8.1]
+  def change
+    add_index :annotation_spans,
+      %i[annotation_review_id field_name content_revision_version],
+      name: "index_annotation_spans_on_review_field_and_revision",
+      if_not_exists: true
+  end
+end

data/lib/activeadmin/annotations/annotatable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  module Annotatable
+    extend ::ActiveSupport::Concern
+
+    included do
+      has_many :annotation_reviews,
+        as: :subject,
+        class_name: "ActiveAdmin::Annotations::Review",
+        dependent: :destroy,
+        inverse_of: :subject
+    end
+  end
+end

data/lib/activeadmin/annotations/categories.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  module Categories
+    def self.all
+      ActiveAdmin::Annotations.categories
+    end
+
+    def self.allowed?(value)
+      value.blank? || all.key?(value)
+    end
+  end
+end

data/lib/activeadmin/annotations/content_revision.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  module ContentRevision
+    class << self
+      def enabled_for?(subject)
+        case ActiveAdmin::Annotations.content_revision_strategy
+        when false, :none
+          false
+        when true, :active_version
+          active_version_subject?(subject) || custom_version_resolver?
+        else
+          custom_version_resolver? || active_version_subject?(subject)
+        end
+      end
+
+      def current_version_for(subject)
+        if custom_current_version
+          return custom_current_version.call(subject).to_i
+        end
+
+        return subject.current_version.to_i if active_version_subject?(subject)
+
+        0
+      end
+
+      def content_subject_for(subject, version)
+        if custom_content_subject
+          return custom_content_subject.call(subject, version.to_i)
+        end
+
+        if active_version_subject?(subject)
+          return active_version_content_subject(subject, version.to_i)
+        end
+
+        subject
+      end
+
+      def stale_review_message(review:, pinned_version:, latest_version:)
+        message = ActiveAdmin::Annotations.stale_content_review_message
+        return if message.blank?
+
+        if message.respond_to?(:call)
+          return message.call(review, pinned_version:, latest_version:)
+        end
+
+        format(message.to_s, pinned_version:, latest_version:)
+      end
+
+      def stale_context_message(review:)
+        message = ActiveAdmin::Annotations.stale_context_message
+        return if message.blank?
+
+        return message.call(review) if message.respond_to?(:call)
+
+        message.to_s
+      end
+
+      def version_label(version)
+        label = ActiveAdmin::Annotations.content_revision_label
+        return if label == false
+
+        if label.respond_to?(:call)
+          return label.call(version.to_i)
+        end
+
+        format((label || "Content version %{version}").to_s, version: version.to_i)
+      end
+
+      private
+
+      def custom_version_resolver?
+        custom_current_version.present? || custom_content_subject.present?
+      end
+
+      def custom_current_version
+        ActiveAdmin::Annotations.current_content_revision_version
+      end
+
+      def custom_content_subject
+        ActiveAdmin::Annotations.content_subject_for_revision
+      end
+
+      def active_version_subject?(subject)
+        subject.class.respond_to?(:has_revisions?) &&
+          subject.class.has_revisions? &&
+          subject.respond_to?(:current_version)
+      end
+
+      def active_version_content_subject(subject, requested_version)
+        head_version = subject.current_version.to_i
+        return subject if requested_version == head_version
+
+        snapshot_version = requested_version + 1
+        return subject.at_version(snapshot_version) if subject.respond_to?(:at_version) && subject.at_version(snapshot_version)
+
+        subject
+      end
+    end
+  end
+end

data/lib/activeadmin/annotations/context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ActiveAdmin::Annotations
+  module Context
+    def self.digest_for(context)
+      Digest::SHA256.hexdigest(context.to_json)
+    end
+  end
+end

data/lib/activeadmin/annotations/copy_text.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveAdmin::Annotations
+  class CopyText
+    def self.for(annotation)
+      new(annotation).to_s
+    end
+
+    def initialize(annotation)
+      @annotation = annotation
+      @review = annotation.annotation_review
+    end
+
+    def to_s
+      sections = []
+      instructions = copy_instructions
+      sections << instructions if instructions.present?
+      sections << review_section
+      sections << context_section
+      sections << annotation_section
+      sections.join("\n\n")
+    end
+
+    private
+
+    attr_reader :annotation, :review
+
+    def copy_instructions
+      instructions = ActiveAdmin::Annotations.copy_instructions
+      return if instructions.blank?
+      return instructions.call(annotation, review) if instructions.respond_to?(:call)
+
+      instructions.to_s
+    end
+
+    def review_section
+      lines = [
+        "Review",
+        "Subject: #{review.subject_type} ##{review.subject_id}",
+        "Status: #{review.review_status}",
+        "Reviewer ID: #{review.reviewer_id}",
+        "Review ID: #{review.id}"
+      ]
+      if content_revision_enabled?
+        lines.insert(2, "Content revision version: #{review.content_revision_version}")
+      end
+      lines << "Notes: #{review.notes}" if review.notes.present?
+      lines << "Context digest: #{review.context_digest}" if review.context_digest.present?
+      lines.join("\n")
+    end
+
+    def context_section
+      "Context:\n#{JSON.pretty_generate(review.context_json.to_h)}"
+    end
+
+    def annotation_section
+      category_label = ActiveAdmin::Annotations.category_label
+      category_value = category_label_for(annotation.category)
+      context_paths = Array(annotation.context_paths_json)
+
+      lines = [
+        "Annotation",
+        "Annotation ID: #{annotation.id}",
+        "Field: #{annotation.field_name}",
+        "Selected text:\n#{annotation.selected_text}",
+        "Comment:\n#{annotation.comment}",
+        "#{category_label}: #{category_value}",
+        "Span: #{annotation.start_offset}-#{annotation.end_offset}"
+      ]
+      lines << if context_paths.any?
+        "Context paths: #{context_paths.join(", ")}"
+      else
+        "Context paths: (none)"
+      end
+      lines << "Created: #{annotation.created_at&.iso8601}" if annotation.created_at
+      lines << "Updated: #{annotation.updated_at&.iso8601}" if annotation.updated_at
+      if content_revision_enabled?
+        lines.insert(2, "Content revision version: #{annotation.content_revision_version}")
+      end
+      lines.join("\n")
+    end
+
+    def content_revision_enabled?
+      subject = review.subject
+      return false if subject.blank?
+
+      ContentRevision.enabled_for?(subject)
+    end
+
+    def category_label_for(value)
+      return "(none)" if value.blank?
+
+      ActiveAdmin::Annotations.categories[value] || value
+    end
+  end
+end

data/lib/activeadmin/annotations/engine.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Annotations
+    class Engine < ::Rails::Engine
+      engine_name "activeadmin_annotations"
+
+      isolate_namespace ActiveAdmin::Annotations
+
+      config.generators do |generator|
+        generator.test_framework :rspec
+      end
+
+      initializer "activeadmin_annotations.active_admin", after: :load_config_initializers do
+        next unless defined?(ActiveAdmin) && ActiveAdmin.respond_to?(:application)
+
+        ActiveAdmin.application.load_paths << ActiveAdmin::Annotations::Engine.root.join("admin").to_s
+      end
+
+      initializer "activeadmin_annotations.importmap", after: :load_config_initializers do
+        next unless Rails.application.respond_to?(:importmap)
+
+        pin_controller = proc do |importmap|
+          importmap.pin "controllers/activeadmin_annotations/annotator_controller",
+            to: "activeadmin_annotations/annotator_controller.js"
+          importmap.pin "controllers/activeadmin_annotations/clipboard_controller",
+            to: "activeadmin_annotations/clipboard_controller.js"
+        end
+
+        Rails.application.importmap.draw(&pin_controller)
+        ActiveAdmin.importmap.draw(&pin_controller) if defined?(ActiveAdmin)
+      end
+
+      initializer "activeadmin_annotations.assets" do |app|
+        assets_path = root.join("app/assets")
+        app.config.importmap.cache_sweepers << assets_path.join("controllers") if app.config.respond_to?(:importmap)
+
+        assets = app.config.assets if app.config.respond_to?(:assets)
+        assets.precompile << "activeadmin_annotations.css" if assets&.respond_to?(:precompile)
+      end
+
+      initializer "activeadmin_annotations.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include ActiveAdmin::Annotations::PanelHelper
+        end
+      end
+    end
+  end
+end

data/lib/activeadmin/annotations/exporter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActiveAdmin::Annotations
+  class Exporter
+    BATCH_SIZE = 100
+
+    def initialize(reviews:)
+      @reviews = reviews
+    end
+
+    def to_jsonl
+      lines = []
+      each_jsonl_row { |row| lines << JSON.generate(row) }
+      return "" if lines.empty?
+
+      "#{lines.join("\n")}\n"
+    end
+
+    def each_jsonl_row
+      return enum_for(:each_jsonl_row) unless block_given?
+
+      if reviews.is_a?(ActiveRecord::Relation)
+        export_relation_in_batches { |row| yield row }
+      else
+        Array(reviews).each do |review|
+          rows_for(review).each { |row| yield row }
+        end
+      end
+    end
+
+    private
+
+    attr_reader :reviews
+
+    def export_relation_in_batches
+      reviews.find_in_batches(batch_size: BATCH_SIZE) do |batch|
+        ActiveRecord::Associations::Preloader.new(records: batch, associations: :annotations).call
+        batch.each do |review|
+          rows_for(review).each { |row| yield row }
+        end
+      end
+    end
+
+    def rows_for(review)
+      context = review.context_json.to_h
+      revision_enabled = ContentRevision.enabled_for?(review.subject)
+      annotations_for(review).map do |annotation|
+        {
+          review_id: review.id,
+          annotation_id: annotation.id,
+          subject: {
+            type: review.subject_type,
+            id: review.subject_id
+          },
+          field: annotation.field_name,
+          context: context,
+          annotation: annotation_payload(annotation, revision_enabled: revision_enabled),
+          review: review_payload(review, revision_enabled: revision_enabled)
+        }
+      end
+    end
+
+    def annotation_payload(annotation, revision_enabled:)
+      payload = {
+        selected_text: annotation.selected_text,
+        comment: annotation.comment,
+        category: annotation.category,
+        start_offset: annotation.start_offset,
+        end_offset: annotation.end_offset,
+        context_paths: Array(annotation.context_paths_json)
+      }
+      payload[:content_revision_version] = annotation.content_revision_version if revision_enabled
+      payload
+    end
+
+    def annotations_for(review)
+      association = review.association(:annotations)
+      if association.loaded?
+        association.target.sort_by(&:created_at)
+      else
+        review.annotations.order(:created_at).to_a
+      end
+    end
+
+    def review_payload(review, revision_enabled:)
+      payload = {
+        reviewer_id: review.reviewer_id,
+        review_status: review.review_status,
+        notes: review.notes,
+        context_digest: review.context_digest,
+        reviewed_at: review.updated_at&.iso8601
+      }
+      payload[:content_revision_version] = review.content_revision_version if revision_enabled
+      payload
+    end
+  end
+end

data/lib/activeadmin/annotations/review_access.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  module ReviewAccess
+    class Error < StandardError; end
+
+    class NotFound < Error; end
+
+    class Forbidden < Error; end
+
+    def self.review_for_span_create!(review_id:, reviewer:)
+      raise NotFound, "Review not found" if review_id.blank?
+
+      review = Review.find_by(id: review_id)
+      raise NotFound, "Review not found" unless review
+      raise Forbidden, "Review not found" unless reviewer.present? && review.reviewer_id == reviewer.id
+
+      review
+    end
+
+    def self.authorize_annotation!(annotation:, reviewer:)
+      raise Forbidden, "Annotation not found" unless annotation
+      raise Forbidden, "Annotation not found" unless reviewer.present? &&
+        annotation.annotation_review.reviewer_id == reviewer.id
+
+      annotation
+    end
+  end
+end