activeadmin_annotations 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6894d360b6a6c23d6037fc43d359f3314938190d684cc74b7d31d57443b70e4
-  data.tar.gz: b99349efb918936290803c2ea2f9ccebd105952e7b891c5c4369c0a615b54a72
+  metadata.gz: 552186e90302ae8e259a730bed26b0c7f8de35070f98d60accfcd81f17c95ba8
+  data.tar.gz: '048dfedf289691780333a9ab149475f106d2ddc3832cf90d3f6fd153d7192038'
 SHA512:
-  metadata.gz: 8ca59dc12c98c45d3f467db454bac3c9f32fcdc0e11a32f45f599b31f26c77e76be9c7c9d1dd7b385a6ab2d0d5f42fa76d439ef420f3c19ef4af44d1edcec6f8
-  data.tar.gz: 5da69787410fe7c3ad81ee7c952a0a2e58f1f9e43ddcc6ecdeaa3766623bed2417314dd573824527ac82a6c647c16d835bb12a164842f857fe3f4acffefe48d8
+  metadata.gz: c8fb4cfa2c652a145ce5ec4e263b9c1d37e2d4f9899cee3c72eab271e18245dbb9780f2f29c595a3fc8be26b6900731d1f6b0d9468860ef3d2a12ae2620559a2
+  data.tar.gz: 58c44f9168cbd4e19dd346891a917e408aab9758b98889cbeaa12e1cf40bdaa7053fac0a69b1fcc9f71f02175a7f00fd9513814c6c43ffa65626a3fff1d0f9d3

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## 0.1.2 (2026-09-04)
+
+- Create the review record when the first annotation is saved.
+- Keep the annotator read-only when browsing a content version other than the one under review.
+- Show This version is read-only. when a save targets a different content version.
+- Show Annotation access denied when a reviewer opens or changes another reviewer's annotation.
+- Limit the review form to status and notes.
+- Omit reviewer identity from copied annotation text.
+- Install annotation tables on SQLite with json columns and on PostgreSQL with jsonb.
+- Escape ordinary panel strings and sanitize html-safe host HTML.
+- Show saved and pending marks when the browser has no custom highlight support.
+
 ## 0.1.1 (2026-07-14)
 
 - Return forbidden responses with access-denied messages for cross-reviewer review and annotation mutations instead of not-found wording.

data/CODE_OF_CONDUCT.md

@@ -1,31 +1,26 @@
 # Code of Conduct
 
-## Our pledge
+## Pledge
 
-We pledge to make participation in our community a harassment-free experience for everyone. We operate on principles of mutual respect, privacy, and authentic engagement. We value substantive contributions and clarity on intentions.
+Participation is a harassment-free experience. Treat each other with respect. Keep private context private.
 
-## Our standards
+## Expected behavior
 
-Examples of behavior that contributes to a positive environment include:
+- Engage with genuine curiosity. Admit uncertainty.
+- Own every line you submit, including generated code.
+- Correct errors politely.
+- Use language that welcomes people and respects identity and privacy.
 
-- Authenticity: engaging with genuine curiosity and admitting uncertainty rather than feigning knowledge.
-- Responsible innovation: taking full responsibility for any content or code contributed, whether manually written or generated by automation tools.
-- Gentle correction: responding politely to errors. We view mistakes as opportunities for learning, provided they are addressed with humility.
-- Inclusive language: using language that welcomes diverse perspectives and respects the privacy and identity of all participants.
+## Unacceptable behavior
 
-Examples of unacceptable behavior include:
+- Harassment, trolling, or insulting comments, public or private.
+- Using jargon or volume, including automated spam, to silence others.
+- Sharing others' data or personal context without permission.
 
-- Harassment: public or private harassment, trolling, or insulting comments.
-- Weaponized complexity: using jargon or overwhelming volume (including automated spam) to silence others.
-- Publishing private information: sharing others' data or personal context without explicit permission.
+## Automation
 
-## Artificial intelligence and automation
-
-In accordance with our commitment to collective awareness:
-
-- Contributors are responsible for the accuracy and security of any AI-generated artifacts they submit.
-- "The AI wrote it" is not a valid excuse for introducing bugs, security vulnerabilities, or bias.
+You remain responsible for bugs, security holes, and bias in generated artifacts you submit.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@kiskolabs.com. All complaints will be reviewed and investigated promptly and fairly.
+Report abusive or harassing behavior to contact@kiskolabs.com. Reports are reviewed and investigated.

data/CONTRIBUTING.md

@@ -1,29 +1,23 @@
 # Contributing Guidelines
 
-Thank you for your interest in contributing to activeadmin_annotations. We value learning over perfection but require rigor and responsibility.
+## Automation authorship
 
-## The golden rule of automation
+You may use AI and automation tools. You remain the author of every line you submit: review, debug, and understand the change.
 
-We welcome the use of AI and automation tools to reduce toil, but you must strictly adhere to the following:
+Keep pull requests small enough to review. Annotate non-obvious logic.
 
-1. You are the author. You act as the responsible agent for any code you submit. You must review, debug, and understand every line.
-2. Manage cognitive load. Do not submit massive, unreviewed automated dumps. Respect the reviewers' time by annotating complex logic.
-3. Security. Never feed project secrets or private context into public AI models.
+Never send project secrets or private context to public models.
 
 ## How to contribute
 
 ### Reporting issues
 
-- Verify accuracy before posting. Avoid generalizations.
-- Use issue templates to provide clear goals, constraints, and reproduction steps.
+Verify the facts before filing. Use issue templates for goals, constraints, and reproduction steps.
 
-### Pull request process
+### Pull requests
 
-- Scope: keep PRs focused on a single goal.
-- Context: explain why the change is necessary.
-- Testing: run `make test` locally before opening a PR.
+Keep one pull request to one goal. Explain why the change is needed. Run smoke tests and regression checks locally before opening the request.
 
-### Review process
+### Review
 
-- We encourage productive friction. Expect questions about your approach.
-- If a reviewer suggests a change, view it as mutual aid, not criticism.
+Reviewers will ask about approach and trade-offs. Treat suggested changes as part of the work.

data/GOVERNANCE.md

@@ -1,29 +1,25 @@
 # Project Governance
 
-## Overview
-
-This project balances individual autonomy with collective coordination. We aim for a workflow that supports rapid iteration while maintaining strict guardrails for safety and architectural integrity.
-
 ## Roles
 
 ### Contributors
 
-Anyone who submits code, documentation, or participates in discussions. Contributors are expected to exercise direct action—taking ownership of problems they identify—while adhering to our quality standards.
+Anyone who submits code, documentation, or participates in discussions. Contributors take ownership of problems they identify and follow the project's quality standards.
 
-### Maintainers (Human Oversight)
+### Maintainers
 
-Maintainers are responsible for:
+Maintainers:
 
-1. Strategic judgment: defining scope and architectural direction.
-2. Review: verifying that contributions (human or automated) meet security and logic standards.
-3. Consensus building: facilitating decisions when the community is divided.
+1. Set scope and architectural direction.
+2. Review contributions (human or automated) against security and logic standards.
+3. Decide when the community is divided.
 
-## Decision making process
+## Decision making
 
 ### Lazy consensus
 
-For most routine changes, we operate on lazy consensus. If a proposal is made and no objections are raised within two weeks, it is considered approved.
+For routine changes, a proposal that draws no objection within two weeks is approved.
 
-### Strategic alignment
+### Maintainer approval
 
-Major architectural changes, high-risk automation integrations, or changes that affect business logic require explicit approval from the maintainers. We prioritize substance over performance—a change must solve a real problem, not just appear polished.
+Major architectural changes, high-risk automation integrations, or changes that affect business logic need explicit maintainer approval. A change must solve a real problem.

data/README.md

@@ -8,10 +8,10 @@ The gem stays domain-agnostic: the host app chooses what review context means, w
 
 ## Requirements
 
-- Ruby 3.2+
+- Ruby 3.4+
 - Rails 7.1+
 - ActiveAdmin 3.0+
-- PostgreSQL recommended for production (SQLite works for development; some metadata filters use Postgres JSON operators)
+- SQLite (`json` columns) or PostgreSQL (`jsonb`, plus GIN on review metadata). CI appraisals start at Rails 7.2.
 
 ## Host app setup
 
@@ -89,7 +89,9 @@ text_node helpers.activeadmin_annotations_panel(
 )
 ```
 
-The gem stores annotations against the live subject text. If the reviewed text changes, stale detection uses `context_digest` only. No version UI is shown.
+Ordinary strings are escaped. html-safe host HTML is sanitized so paragraphs stay and scripts and event handlers are stripped.
+
+The gem stores annotations against the live subject text. The review row is created on the first annotation save, not when the panel is shown. If the reviewed text changes, stale detection uses `context_digest` only. No version UI is shown.
 
 ## Content revisions (optional)
 
@@ -127,7 +129,7 @@ class Article < ApplicationRecord
 end
 ```
 
-Then either render the panel through `ActiveAdmin::Annotations::ReviewPanel` (handles pinning, stale state, and version filtering):
+Then either render the panel through `ActiveAdmin::Annotations::ReviewPanel` (handles pinning, stale state, and version filtering). Browsing a content version other than the one under review is read-only. Add notes on the version being reviewed:
 
 ```ruby
 text_node ActiveAdmin::Annotations::ReviewPanel.render(
@@ -231,11 +233,13 @@ Add a host stylesheet that loads after the gem asset (for example in your Active
   border-color: var(--primary, #2563eb);
 }
 
-::highlight(aa-annotations-saved) {
+::highlight(aa-annotations-saved),
+.aa-annotations-mark--saved {
   background-color: color-mix(in srgb, var(--primary, #2563eb) 30%, #fef08a);
 }
 
-::highlight(aa-annotations-pending) {
+::highlight(aa-annotations-pending),
+.aa-annotations-mark--pending {
   background-color: color-mix(in srgb, var(--primary, #2563eb) 40%, #fef08a);
   text-decoration-color: var(--primary, #2563eb);
 }
@@ -298,7 +302,7 @@ bundle exec rubocop
 bundle exec polyrun parallel-rspec --workers 5 --merge-failures
 ```
 
-Matrixed Rails versions use [Appraisal](https://github.com/thoughtbot/appraisal): `gemfiles/rails72.gemfile`, `rails8ruby34.gemfile`, and `rails8truffleruby.gemfile`. Run `bundle exec appraisal rspec` to execute RSpec in each gemfile context.
+Matrixed Rails versions use [Appraisal](https://github.com/thoughtbot/appraisal): `gemfiles/rails72.gemfile` and `rails8ruby34.gemfile`. Run `bundle exec appraisal rspec` to execute RSpec in each gemfile context.
 
 Shared agent guidance is managed with [pray](https://github.com/kiskolabs/pray) via `Prayfile`.
 
@@ -308,6 +312,19 @@ Shared agent guidance is managed with [pray](https://github.com/kiskolabs/pray)
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and pull requests are welcome at https://github.com/amkisko/activeadmin_annotations.rb/issues
 
+## Links
+
+- [GitHub](https://github.com/amkisko/activeadmin_annotations.rb)
+- [GitLab](https://gitlab.com/amkisko/activeadmin_annotations.rb)
+- [RubyGems](https://rubygems.org/gems/activeadmin_annotations)
+- [Versions Atom](https://rubygems.org/gems/activeadmin_annotations/versions.atom) (feed id `11581035749940`)
+- [libraries.io](https://libraries.io/rubygems/activeadmin_annotations)
+- [Deps.dev](https://deps.dev/rubygems/activeadmin_annotations)
+- [SonarCloud](https://sonarcloud.io/project/overview?id=amkisko_activeadmin_annotations.rb)
+- [Snyk](https://snyk.io/test/github/amkisko/activeadmin_annotations.rb)
+- [Codecov](https://app.codecov.io/github/amkisko/activeadmin_annotations.rb)
+- [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/amkisko/activeadmin_annotations.rb)
+
 ## License
 
 MIT — see [LICENSE.md](LICENSE.md).

data/SECURITY.md

@@ -1,27 +1,25 @@
 # SECURITY
 
-## Reporting a vulnerability
-
-Do NOT open a public GitHub issue for security vulnerabilities.
+## Reporting a Vulnerability
 
 Email security details to: security@kiskolabs.com
 
-Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+Send the report only to that address. Include description, steps to reproduce, potential impact, and a suggested fix when you have one.
 
-### Response timeline
+### Response Timeline
 
-- We will acknowledge receipt of your report
-- We will provide an initial assessment
-- We will keep you informed of our progress and resolution timeline
+- We will acknowledge receipt of your report.
+- We will provide an initial assessment.
+- We will keep you informed of our progress and resolution timeline.
 
-### Disclosure policy
+### Disclosure Policy
 
-- We will work with you to understand and resolve the issue
-- We will credit you for the discovery (unless you prefer to remain anonymous)
-- We will publish a security advisory after the vulnerability is patched
-- We will coordinate public disclosure with you
+- We will work with you to understand and resolve the issue.
+- We will credit you for the discovery unless you prefer to remain anonymous.
+- We will publish a security advisory after the vulnerability is patched.
+- We will coordinate public disclosure with you.
 
-## Automation security
+## Automation Security
 
-- Context isolation: it is strictly forbidden to include production credentials, API keys, or personally identifiable information in prompts sent to third-party LLMs or automation services.
-- Supply chain: all automated dependencies must be verified.
+- Keep production credentials, API keys, and personal data out of prompts sent to third-party models or automation services.
+- Verify automated dependencies.

data/activeadmin_annotations.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Collect text highlights and comments inside a bounded ActiveAdmin block, with optional review context, content revision pinning, and JSONL export."
   spec.license = "MIT"
   spec.platform = Gem::Platform::RUBY
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.4"
 
   repository_url = "https://github.com/amkisko/activeadmin_annotations.rb"
 
@@ -64,5 +64,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard-performance", "~> 1.8"
   spec.add_development_dependency "standard-rails", "~> 1.5"
   spec.add_development_dependency "standard-rspec", "~> 0.3"
-  spec.add_development_dependency "rbs", "~> 3"
+  spec.add_development_dependency "rbs", "~> 4"
 end

data/admin/annotation_reviews.rb

@@ -8,13 +8,16 @@ ActiveAdmin.register ActiveAdmin::Annotations::Review, as: "annotation_reviews"
 
   controller do
     def scoped_collection
-      super.includes(:annotations)
+      annotation_counts = ActiveAdmin::Annotations::Annotation
+        .where("annotation_spans.annotation_review_id = annotation_reviews.id")
+        .select("COUNT(*)")
+      super.select("annotation_reviews.*", "(#{annotation_counts.to_sql}) AS annotations_count")
     end
   end
 
   actions :index, :show, :create, :update
 
-  permit_params :review_status, :notes, :metadata_json
+  permit_params :review_status, :notes
 
   filter :subject_type, as: :select
   filter :subject_id
@@ -36,7 +39,7 @@ ActiveAdmin.register ActiveAdmin::Annotations::Review, as: "annotation_reviews"
     column :subject_id
     column :reviewer
     column :review_status
-    column("Annotations") { |review| review.annotations.size }
+    column("Annotations") { |review| review.annotations_count }
     column :context_digest
     column :created_at
     actions
@@ -91,9 +94,14 @@ ActiveAdmin.register ActiveAdmin::Annotations::Review, as: "annotation_reviews"
 
   collection_action :export_jsonl, method: :get do
     exporter = ActiveAdmin::Annotations::Exporter.new(reviews: collection)
-    send_data exporter.to_jsonl,
-      filename: "annotation-reviews-#{Time.current.strftime("%Y%m%d%H%M%S")}.jsonl",
-      type: "application/jsonl"
+    filename = "annotation-reviews-#{Time.current.strftime("%Y%m%d%H%M%S")}.jsonl"
+    headers["Content-Type"] = "application/jsonl"
+    headers["Content-Disposition"] = %(attachment; filename="#{filename}")
+    self.response_body = Enumerator.new do |yielder|
+      exporter.each_jsonl_row do |row|
+        yielder << "#{JSON.generate(row)}\n"
+      end
+    end
   end
 
   action_item :export_jsonl, only: :index do

data/admin/annotations.rb

@@ -59,13 +59,22 @@ ActiveAdmin.register ActiveAdmin::Annotations::Annotation, as: "annotation_spans
   end
 
   controller do
-    before_action :authorize_annotation_access!, only: %i[update destroy copy_text]
+    before_action :authorize_annotation_access!, only: %i[show update destroy copy_text]
+
+    def scoped_collection
+      return super unless action_name == "index"
+
+      reviewer = current_annotation_reviewer
+      return super.none if reviewer.blank?
+
+      super.joins(:annotation_review).where(annotation_reviews: {reviewer_id: reviewer.id})
+    end
 
     def create
       review = authorize_review_for_create!
       return if performed?
 
-      assign_content_revision_version_from_review(review)
+      stamp_span_from_review!(review)
       super do |success, failure|
         success.html { redirect_to request.referer || resource_path, notice: "Annotation saved." }
         success.json { render json: annotation_json(resource), status: :created }
@@ -95,12 +104,18 @@ ActiveAdmin.register ActiveAdmin::Annotations::Annotation, as: "annotation_spans
     private
 
     def authorize_review_for_create!
-      ActiveAdmin::Annotations::ReviewAccess.review_for_span_create!(
-        review_id: params.dig(:annotation, :annotation_review_id),
+      ActiveAdmin::Annotations::SpanCreate.review_for!(
+        params: params,
         reviewer: current_annotation_reviewer
       )
-    rescue ActiveAdmin::Annotations::ReviewAccess::Forbidden, ActiveAdmin::Annotations::ReviewAccess::NotFound
-      respond_to_denied_review_access
+    rescue ActiveAdmin::Annotations::SpanCreate::ReadOnly => error
+      respond_to_span_error(error, status: :unprocessable_entity)
+      nil
+    rescue ActiveAdmin::Annotations::ReviewAccess::NotFound => error
+      respond_to_span_error(error, status: :not_found)
+      nil
+    rescue ActiveAdmin::Annotations::ReviewAccess::Forbidden => error
+      respond_to_span_error(error, status: :forbidden)
       nil
     end
 
@@ -109,8 +124,10 @@ ActiveAdmin.register ActiveAdmin::Annotations::Annotation, as: "annotation_spans
         annotation: resource,
         reviewer: current_annotation_reviewer
       )
-    rescue ActiveAdmin::Annotations::ReviewAccess::Forbidden
-      respond_to_denied_review_access
+    rescue ActiveAdmin::Annotations::ReviewAccess::NotFound => error
+      respond_to_span_error(error, status: :not_found)
+    rescue ActiveAdmin::Annotations::ReviewAccess::Forbidden => error
+      respond_to_span_error(error, status: :forbidden)
     end
 
     def current_annotation_reviewer
@@ -119,21 +136,24 @@ ActiveAdmin.register ActiveAdmin::Annotations::Annotation, as: "annotation_spans
       nil
     end
 
-    def respond_to_denied_review_access
+    def respond_to_span_error(error, status:)
       if request.format.json?
-        render json: {errors: ["Review not found"]}, status: :forbidden
+        render json: {errors: [error.message]}, status: status
       else
-        redirect_to request.referer || admin_root_path, alert: "Review not found."
+        redirect_to request.referer || admin_root_path, alert: error.message
       end
     end
 
-    def assign_content_revision_version_from_review(review)
-      params[:annotation][:content_revision_version] = review.content_revision_version
+    def stamp_span_from_review!(review)
+      annotation_params = params[:annotation] ||= ActionController::Parameters.new
+      annotation_params[:annotation_review_id] = review.id
+      annotation_params[:content_revision_version] = review.content_revision_version
     end
 
     def annotation_json(annotation)
       {
         id: annotation.id,
+        annotation_review_id: annotation.annotation_review_id,
         field_name: annotation.field_name,
         selected_text: annotation.selected_text,
         start_offset: annotation.start_offset,

data/app/assets/controllers/activeadmin_annotations/annotation_client.js

@@ -0,0 +1,44 @@
+export class AnnotationClient {
+  constructor({ csrfToken }) {
+    this.csrfToken = csrfToken;
+  }
+
+  async create(url, payload) {
+    return this.requestJson(url, { method: "POST", body: payload });
+  }
+
+  async update(url, payload) {
+    return this.requestJson(url, { method: "PATCH", body: payload });
+  }
+
+  async destroy(url) {
+    await this.requestJson(url, { method: "DELETE" });
+  }
+
+  async requestJson(url, { method, body }) {
+    const response = await fetch(url, {
+      method,
+      credentials: "same-origin",
+      headers: {
+        Accept: "application/json",
+        "X-CSRF-Token": this.csrfToken,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      const error = new Error("request failed");
+      error.response = response;
+      throw error;
+    }
+
+    if (method === "DELETE") return null;
+    return response.json();
+  }
+}
+
+export function csrfToken() {
+  const meta = document.querySelector("meta[name='csrf-token']");
+  return meta ? meta.getAttribute("content") : "";
+}

data/app/assets/controllers/activeadmin_annotations/annotation_list.js

@@ -0,0 +1,29 @@
+import { categoryLabelFor, escapeHtml } from "activeadmin_annotations/annotator_logic";
+
+export function emptyAnnotationListItem() {
+  const item = document.createElement("p");
+  item.className = "aa-annotations-empty";
+  item.textContent = "No annotations yet.";
+  return item;
+}
+
+export function annotationListItem(annotation, { readonly, categoryLabel, categories }) {
+  const item = document.createElement("article");
+  item.className = "aa-annotations-annotation-item";
+  const resolvedCategory = categoryLabelFor(annotation.category, categories);
+  const actions = readonly
+    ? ""
+    : `
+      <div class="aa-annotations-annotation-actions">
+        <button type="button" class="action-item-button" data-annotation-id="${escapeHtml(String(annotation.id))}" data-action="activeadmin-annotations--annotator#editAnnotation">Edit</button>
+        <button type="button" class="action-item-button aa-annotations-delete-button" data-annotation-id="${escapeHtml(String(annotation.id))}" data-action="activeadmin-annotations--annotator#deleteAnnotation">Delete</button>
+      </div>
+    `;
+  item.innerHTML = `
+      <blockquote>${escapeHtml(annotation.selected_text)}</blockquote>
+      <p>${escapeHtml(annotation.comment)}</p>
+      ${annotation.category ? `<p><strong>${escapeHtml(categoryLabel)}:</strong> ${escapeHtml(resolvedCategory)}</p>` : ""}
+      ${actions}
+    `;
+  return item;
+}