coplan-engine 0.1.0

data/app/services/coplan/plans/apply_operations.rb

@@ -0,0 +1,128 @@
+module CoPlan
+  module Plans
+    class ApplyOperations
+      def self.call(content:, operations:)
+        new(content:, operations:).call
+      end
+
+      def initialize(content:, operations:)
+        @content = content.dup
+        @operations = operations
+        @applied = []
+      end
+
+      def call
+        @operations.each_with_index do |op, index|
+          op = op.transform_keys(&:to_s)
+          applied_data = case op["op"]
+          when "replace_exact"
+            apply_replace_exact(op, index)
+          when "insert_under_heading"
+            apply_insert_under_heading(op, index)
+          when "delete_paragraph_containing"
+            apply_delete_paragraph_containing(op, index)
+          else
+            raise OperationError, "Operation #{index}: unknown op '#{op["op"]}'"
+          end
+          @applied << applied_data
+        end
+
+        { content: @content, applied: @applied }
+      end
+
+      private
+
+      def apply_replace_exact(op, index)
+        old_text = op["old_text"]
+        new_text = op["new_text"]
+
+        raise OperationError, "Operation #{index}: replace_exact requires 'old_text'" if old_text.blank?
+        raise OperationError, "Operation #{index}: replace_exact requires 'new_text'" if new_text.nil?
+
+        ranges = if op.key?("_pre_resolved_ranges")
+          op["_pre_resolved_ranges"]
+        else
+          Plans::PositionResolver.call(content: @content, operation: op).ranges
+        end
+
+        applied_data = op.except("_pre_resolved_ranges")
+
+        if ranges.length > 1
+          replacements = []
+          cumulative_delta = 0
+
+          ranges.sort_by { |r| r[0] }.each do |range|
+            adjusted_start = range[0] + cumulative_delta
+            adjusted_end = range[1] + cumulative_delta
+
+            @content = @content[0...adjusted_start] + new_text + @content[adjusted_end..]
+
+            delta = new_text.length - old_text.length
+            replacements << {
+              "resolved_range" => range,
+              "new_range" => [range[0], range[0] + new_text.length],
+              "delta" => delta
+            }
+            cumulative_delta += delta
+          end
+
+          applied_data["replacements"] = replacements
+          applied_data["total_delta"] = cumulative_delta
+        else
+          range = ranges[0]
+          @content = @content[0...range[0]] + new_text + @content[range[1]..]
+
+          delta = new_text.length - old_text.length
+          applied_data["resolved_range"] = range
+          applied_data["new_range"] = [range[0], range[0] + new_text.length]
+          applied_data["delta"] = delta
+        end
+
+        applied_data
+      end
+
+      def apply_insert_under_heading(op, index)
+        heading = op["heading"]
+
+        raise OperationError, "Operation #{index}: insert_under_heading requires 'heading'" if heading.blank?
+        raise OperationError, "Operation #{index}: insert_under_heading requires 'content'" if op["content"].nil?
+
+        insert_point = if op.key?("_pre_resolved_ranges")
+          op["_pre_resolved_ranges"][0]
+        else
+          Plans::PositionResolver.call(content: @content, operation: op).ranges[0]
+        end
+        content_to_insert = "\n" + op["content"]
+
+        @content = @content[0...insert_point[0]] + content_to_insert + @content[insert_point[1]..]
+
+        applied_data = op.except("_pre_resolved_ranges")
+        applied_data["resolved_range"] = insert_point
+        applied_data["new_range"] = [insert_point[0], insert_point[0] + content_to_insert.length]
+        applied_data["delta"] = content_to_insert.length
+        applied_data
+      end
+
+      def apply_delete_paragraph_containing(op, index)
+        needle = op["needle"]
+
+        raise OperationError, "Operation #{index}: delete_paragraph_containing requires 'needle'" if needle.blank?
+
+        range = if op.key?("_pre_resolved_ranges")
+          op["_pre_resolved_ranges"][0]
+        else
+          Plans::PositionResolver.call(content: @content, operation: op).ranges[0]
+        end
+
+        deleted_length = range[1] - range[0]
+        @content = @content[0...range[0]] + @content[range[1]..]
+
+        applied_data = op.except("_pre_resolved_ranges")
+        applied_data["resolved_range"] = range
+        applied_data["new_range"] = [range[0], range[0]]
+        applied_data["delta"] = -deleted_length
+        applied_data
+      end
+    end
+  end
+end

data/app/services/coplan/plans/commit_session.rb

@@ -0,0 +1,186 @@
+module CoPlan
+  module Plans
+    # Commits an EditSession's accumulated operations as a single PlanVersion.
+    #
+    # If the session's base_revision is behind current_revision, each
+    # operation's resolved ranges are transformed through intervening versions
+    # via TransformRange (OT). All versions must have positional metadata —
+    # TransformRange raises Conflict if any operation lacks it.
+    class CommitSession
+      class StaleSessionError < StandardError; end
+      class SessionConflictError < StandardError; end
+      class SessionNotOpenError < StandardError; end
+
+      def self.call(session:, change_summary: nil)
+        new(session:, change_summary:).call
+      end
+
+      def initialize(session:, change_summary: nil)
+        @session = session
+        @change_summary = change_summary || session.change_summary
+      end
+
+      def call
+        raise SessionNotOpenError, "Session is not open" unless @session.open?
+
+        plan = @session.plan
+
+        ActiveRecord::Base.transaction do
+          @session.lock!
+          raise SessionNotOpenError, "Session is not open" unless @session.open?
+
+          # No operations: just mark committed, no version created
+          unless @session.has_operations?
+            @session.update!(status: "committed", committed_at: Time.current)
+            return { session: @session, version: nil }
+          end
+
+          plan.lock!
+
+          base_revision = @session.base_revision
+          current_revision = plan.current_revision
+          current_content = plan.current_content || ""
+
+          # Determine the content to use as the result
+          if base_revision == current_revision
+            # No intervening edits — use draft_content directly
+            new_content = @session.draft_content || current_content
+            final_ops = @session.operations_json
+          else
+            # Stale! Need to rebase through intervening versions
+            stale_gap = current_revision - base_revision
+            if stale_gap > 20
+              raise StaleSessionError, "Session is too stale (#{stale_gap} revisions behind, max 20)"
+            end
+
+            # Get intervening versions
+            intervening_versions = plan.plan_versions
+              .where("revision > ? AND revision <= ?", base_revision, current_revision)
+              .order(revision: :asc)
+              .to_a
+
+            # Transform each operation's resolved positions through intervening edits,
+            # then re-apply using the transformed positions (not re-resolving from scratch)
+            verification_content = current_content.dup
+            rebased_ops = []
+            @session.operations_json.each do |op_data|
+              op_data = op_data.transform_keys(&:to_s)
+              semantic_keys = %w[op old_text new_text heading content needle occurrence replace_all count]
+              semantic_op = op_data.slice(*semantic_keys)
+
+              if op_data["resolved_range"]
+                begin
+                  transformed_range = Plans::TransformRange.transform_through_versions(
+                    op_data["resolved_range"], intervening_versions
+                  )
+                rescue Plans::TransformRange::Conflict => e
+                  raise SessionConflictError, "Conflict during rebase: #{e.message}"
+                end
+
+                verify_text_at_range!(verification_content, transformed_range, op_data)
+                semantic_op["_pre_resolved_ranges"] = [transformed_range]
+              elsif op_data.key?("replacements")
+                transformed_ranges = op_data["replacements"].map do |rep|
+                  begin
+                    Plans::TransformRange.transform_through_versions(
+                      rep["resolved_range"], intervening_versions
+                    )
+                  rescue Plans::TransformRange::Conflict => e
+                    raise SessionConflictError, "Conflict during rebase: #{e.message}"
+                  end
+                end
+
+                transformed_ranges.each { |tr| verify_text_at_range!(verification_content, tr, op_data) }
+                semantic_op["_pre_resolved_ranges"] = transformed_ranges
+              end
+
+              rebased_ops << semantic_op
+
+              # Advance verification content so subsequent ops verify against
+              # the incrementally updated snapshot (not the original current_content).
+              step = Plans::ApplyOperations.call(content: verification_content, operations: [semantic_op])
+              verification_content = step[:content]
+            end
+
+            result = Plans::ApplyOperations.call(content: current_content, operations: rebased_ops)
+            new_content = result[:content]
+            final_ops = result[:applied]
+          end
+
+          # Create the version
+          new_revision = plan.current_revision + 1
+          diff = Diffy::Diff.new(current_content, new_content).to_s
+
+          version = PlanVersion.create!(
+            plan: plan,
+            revision: new_revision,
+            content_markdown: new_content,
+            actor_type: @session.actor_type,
+            actor_id: @session.actor_id,
+            change_summary: @change_summary,
+            diff_unified: diff.presence,
+            operations_json: final_ops,
+            base_revision: @session.base_revision
+          )
+
+          plan.update!(
+            current_plan_version: version,
+            current_revision: new_revision
+          )
+
+          plan.comment_threads.mark_out_of_date_for_new_version!(version)
+
+          @session.update!(
+            status: "committed",
+            committed_at: Time.current,
+            plan_version_id: version.id,
+            change_summary: @change_summary
+          )
+
+          # Broadcast update
+          Broadcaster.replace_to(
+            plan,
+            target: "plan-header",
+            partial: "coplan/plans/header",
+            locals: { plan: plan }
+          )
+
+          { session: @session, version: version }
+        end
+      end
+
+      private
+
+      def verify_text_at_range!(content, range, op_data)
+        case op_data["op"]
+        when "replace_exact"
+          return unless op_data["old_text"]
+          actual_text = content[range[0]...range[1]]
+          return if actual_text == op_data["old_text"]
+
+          context_start = [range[0] - 200, 0].max
+          context_end = [range[1] + 200, content.length].min
+          raise SessionConflictError,
+            "Content changed at conflict region. Expected '#{op_data["old_text"]}' " \
+            "but found '#{actual_text}'. Context: ...#{content[context_start...context_end]}..."
+        when "insert_under_heading"
+          return unless op_data["heading"]
+          line_start = range[0] > 0 ? (content.rindex("\n", range[0] - 1) || -1) + 1 : 0
+          line_text = content[line_start...range[0]]
+          return if line_text&.match?(/\A#{Regexp.escape(op_data["heading"])}\s*\z/)
+
+          raise SessionConflictError,
+            "Heading changed at insert position. Expected '#{op_data["heading"]}' " \
+            "but found '#{line_text}'"
+        when "delete_paragraph_containing"
+          return unless op_data["needle"]
+          actual_text = content[range[0]...range[1]]
+          return if actual_text&.include?(op_data["needle"])
+
+          raise SessionConflictError,
+            "Paragraph at target position no longer contains '#{op_data["needle"]}'"
+        end
+      end
+    end
+  end
+end

data/app/services/coplan/plans/create.rb

@@ -0,0 +1,30 @@
+module CoPlan
+  module Plans
+    class Create
+      def self.call(title:, content:, user:)
+        new(title:, content:, user:).call
+      end
+
+      def initialize(title:, content:, user:)
+        @title = title
+        @content = content
+        @user = user
+      end
+
+      def call
+        ActiveRecord::Base.transaction do
+          plan = Plan.create!(title: @title, created_by_user: @user)
+          version = PlanVersion.create!(
+            plan: plan,
+            revision: 1,
+            content_markdown: @content,
+            actor_type: "human",
+            actor_id: @user.id
+          )
+          plan.update!(current_plan_version: version, current_revision: 1)
+          plan
+        end
+      end
+    end
+  end
+end

data/app/services/coplan/plans/operation_error.rb

@@ -0,0 +1,5 @@
+module CoPlan
+  module Plans
+    class OperationError < StandardError; end
+  end
+end

data/app/services/coplan/plans/position_resolver.rb

@@ -0,0 +1,191 @@
+module CoPlan
+  module Plans
+    class PositionResolver
+      Resolution = Data.define(:op, :ranges)
+
+      def self.call(content:, operation:)
+        new(content:, operation:).call
+      end
+
+      def initialize(content:, operation:)
+        @content = content
+        @op = operation.transform_keys(&:to_s)
+      end
+
+      def call
+        case @op["op"]
+        when "replace_exact"
+          resolve_replace_exact
+        when "insert_under_heading"
+          resolve_insert_under_heading
+        when "delete_paragraph_containing"
+          resolve_delete_paragraph_containing
+        else
+          raise OperationError, "Unknown operation: #{@op["op"]}"
+        end
+      end
+
+      private
+
+      def resolve_replace_exact
+        old_text = @op["old_text"]
+        raise OperationError, "replace_exact requires 'old_text'" if old_text.blank?
+        raise OperationError, "replace_exact requires 'new_text'" if @op["new_text"].nil?
+
+        replace_all = @op["replace_all"] == true
+        occurrence = (@op["occurrence"] || 1).to_i
+        raise OperationError, "replace_exact: occurrence must be >= 1, got #{occurrence}" if occurrence < 1
+
+        ranges = find_all_occurrences(old_text)
+
+        if ranges.empty?
+          raise OperationError, "replace_exact found 0 occurrences of the specified text"
+        end
+
+        if replace_all
+          Resolution.new(op: "replace_exact", ranges: ranges)
+        else
+          count = @op["count"]&.to_i
+          if count && count > 1
+            Resolution.new(op: "replace_exact", ranges: ranges)
+          else
+            if !@op.key?("occurrence") && !@op.key?("replace_all") && ranges.length > 1 && (!count || count == 1)
+              raise OperationError, "replace_exact found #{ranges.length} occurrences, expected at most 1"
+            end
+
+            if occurrence > ranges.length
+              raise OperationError, "replace_exact: occurrence #{occurrence} requested but only #{ranges.length} found"
+            end
+
+            Resolution.new(op: "replace_exact", ranges: [ranges[occurrence - 1]])
+          end
+        end
+      end
+
+      def resolve_insert_under_heading
+        heading = @op["heading"]
+        raise OperationError, "insert_under_heading requires 'heading'" if heading.blank?
+        raise OperationError, "insert_under_heading requires 'content'" if @op["content"].nil?
+
+        pattern = /^#{Regexp.escape(heading)}[^\S\n]*$/
+        matches = []
+        @content.scan(pattern) do
+          match_end = Regexp.last_match.end(0)
+          matches << [match_end, match_end]
+        end
+
+        if matches.empty?
+          raise OperationError, "insert_under_heading found no heading matching '#{heading}'"
+        end
+
+        if matches.length > 1
+          raise OperationError, "insert_under_heading found #{matches.length} headings matching '#{heading}'"
+        end
+
+        Resolution.new(op: "insert_under_heading", ranges: matches)
+      end
+
+      def resolve_delete_paragraph_containing
+        needle = @op["needle"]
+        raise OperationError, "delete_paragraph_containing requires 'needle'" if needle.blank?
+
+        paragraphs = locate_paragraphs
+        matching = paragraphs.select { |para| para[:text].include?(needle) }
+
+        if matching.empty?
+          raise OperationError, "delete_paragraph_containing found no paragraph containing '#{needle}'"
+        end
+
+        if matching.length > 1
+          raise OperationError, "delete_paragraph_containing found #{matching.length} paragraphs containing '#{needle}'"
+        end
+
+        para = matching.first
+        ranges = [deletion_range_for(para, paragraphs)]
+
+        Resolution.new(op: "delete_paragraph_containing", ranges: ranges)
+      end
+
+      def find_all_occurrences(text)
+        ranges = []
+        start_pos = 0
+        while (idx = @content.index(text, start_pos))
+          ranges << [idx, idx + text.length]
+          start_pos = idx + text.length
+        end
+        ranges
+      end
+
+      # Locate each paragraph's text and its position in the content.
+      # Paragraphs are separated by 2+ newlines. We track where each
+      # paragraph's text starts/ends and the separator that follows it.
+      def locate_paragraphs
+        return [] if @content.empty?
+
+        paragraphs = []
+        scanner_pos = 0
+
+        # Skip leading blank lines
+        if (m = @content.match(/\A(\n+)/, scanner_pos))
+          scanner_pos = m.end(0)
+        end
+
+        while scanner_pos < @content.length
+          # Find the end of paragraph text (next \n\n or end of string)
+          next_sep = @content.index(/\n{2,}/, scanner_pos)
+
+          if next_sep
+            text_end = next_sep
+            # Find end of separator
+            sep_match = @content.match(/\n{2,}/, next_sep)
+            sep_end = sep_match.end(0)
+          else
+            text_end = @content.length
+            sep_end = @content.length
+          end
+
+          text = @content[scanner_pos...text_end]
+          paragraphs << { text: text, text_start: scanner_pos, text_end: text_end, sep_end: sep_end }
+
+          scanner_pos = sep_end
+        end
+
+        paragraphs
+      end
+
+      # Determine the character range to delete so that removing
+      # content[range[0]...range[1]] produces clean output with
+      # correct paragraph spacing.
+      def deletion_range_for(para, all_paragraphs)
+        idx = all_paragraphs.index(para)
+        is_first = idx == 0
+        is_last = idx == all_paragraphs.length - 1
+
+        if all_paragraphs.length == 1
+          # Only paragraph — delete everything
+          [0, @content.length]
+        elsif is_first
+          # First paragraph: delete from text_start through the separator after it,
+          # so the next paragraph becomes the start.
+          [para[:text_start], para[:sep_end]]
+        elsif is_last
+          # Last paragraph: delete from the separator before it (end of previous
+          # paragraph's text) to the end of this paragraph's text.
+          prev = all_paragraphs[idx - 1]
+          [prev[:text_end], para[:text_end]]
+        else
+          # Middle paragraph: delete from end of previous paragraph's text
+          # through the separator after this paragraph, but keep one separator
+          # between the previous and next paragraphs.
+          # Simplest: delete from previous text_end to this paragraph's sep_end,
+          # then the next paragraph starts right there. But we need to preserve
+          # one separator. Instead: delete this paragraph's text_start through
+          # sep_end. That removes the paragraph and its trailing separator, and
+          # the separator before it (from previous text_end to this text_start)
+          # becomes the separator between prev and next.
+          [para[:text_start], para[:sep_end]]
+        end
+      end
+    end
+  end
+end

data/app/services/coplan/plans/review_prompt_formatter.rb

@@ -0,0 +1,25 @@
+module CoPlan
+  module Plans
+    class ReviewPromptFormatter
+      RESPONSE_FORMAT_INSTRUCTIONS = <<~INSTRUCTIONS.freeze
+        You MUST respond with a JSON array of feedback items. Each item is an object with two keys:
+        - "anchor_text": An exact substring copied verbatim from the plan document that this feedback applies to. Keep it short (a phrase or single sentence). Must match the plan text exactly. Use null for general feedback not tied to specific text.
+        - "comment": Your feedback in Markdown. Be concise and actionable.
+
+        Example response:
+        ```json
+        [
+          {"anchor_text": "API tokens scoped to a user", "comment": "Consider adding token expiration by default. Long-lived tokens without expiry are a common security risk."},
+          {"anchor_text": null, "comment": "Overall the plan looks solid. One general concern: there's no mention of audit logging for administrative actions."}
+        ]
+        ```
+
+        Return ONLY the JSON array. No other text before or after it.
+      INSTRUCTIONS
+
+      def self.call(reviewer_prompt:)
+        "#{reviewer_prompt}\n\n#{RESPONSE_FORMAT_INSTRUCTIONS}"
+      end
+    end
+  end
+end

data/app/services/coplan/plans/review_response_parser.rb

@@ -0,0 +1,65 @@
+module CoPlan
+  module Plans
+    class ReviewResponseParser
+      def self.call(response_text, plan_content:)
+        new(response_text, plan_content:).call
+      end
+
+      def initialize(response_text, plan_content:)
+        @response_text = response_text
+        @plan_content = plan_content
+      end
+
+      def call
+        items = parse_json
+        items.filter_map { |item| normalize_item(item) }
+      end
+
+      private
+
+      def parse_json
+        json_text = extract_json_from_response
+        parsed = JSON.parse(json_text)
+
+        unless parsed.is_a?(Array)
+          return fallback_single_comment
+        end
+
+        parsed
+      rescue JSON::ParserError
+        fallback_single_comment
+      end
+
+      def extract_json_from_response
+        # Strip markdown code fences if present
+        text = @response_text.strip
+        if text.start_with?("```")
+          text = text.sub(/\A```(?:json)?\s*\n?/, "").sub(/\n?```\s*\z/, "")
+        end
+        text
+      end
+
+      def normalize_item(item)
+        return nil unless item.is_a?(Hash)
+
+        anchor = item["anchor_text"].presence
+        comment = item["comment"].to_s.strip
+
+        return nil if comment.blank?
+
+        # Verify anchor_text actually exists in the plan content
+        if anchor && !@plan_content.include?(anchor)
+          # Anchor doesn't match — demote to unanchored with the quote in the comment
+          comment = "> #{anchor}\n\n#{comment}"
+          anchor = nil
+        end
+
+        { anchor_text: anchor, comment: comment }
+      end
+
+      def fallback_single_comment
+        [{ "anchor_text" => nil, "comment" => @response_text }]
+      end
+    end
+  end
+end