commenter 0.3.0 → 0.4.0

data/spec/commenter/comment_spec.rb

@@ -9,7 +9,7 @@ RSpec.describe Commenter::Comment do
         id: "US-001",
         body: "US",
         locality: { clause: "5.1", element: "Table 1", line_number: "42" },
-        type: "te",
+        type: "technical",
         comments: "Test comment",
         proposed_change: "Test change",
         observations: "Test observations"
@@ -28,6 +28,19 @@ RSpec.describe Commenter::Comment do
       expect(comment.observations).to eq("Test observations")
     end
 
+    it "expands short type codes when loaded from YAML" do
+      yaml = <<~YAML
+        ---
+        id: US-009
+        type: te
+      YAML
+
+      comment = described_class.from_yaml(yaml)
+
+      expect(comment.id).to eq("US-009")
+      expect(comment.type).to eq("technical")
+    end
+
     it "handles string keys in attributes" do
       attributes = {
         "id" => "US-001",
@@ -162,7 +175,7 @@ RSpec.describe Commenter::Comment do
         id: "US-001",
         body: "US",
         locality: { clause: "5.1" },
-        type: "te",
+        type: "technical",
         comments: "Test",
         proposed_change: "Change",
         observations: "Obs"
@@ -170,13 +183,13 @@ RSpec.describe Commenter::Comment do
 
       hash = comment.to_h
 
-      expect(hash[:id]).to eq("US-001")
-      expect(hash[:body]).to eq("US")
-      expect(hash[:locality][:clause]).to eq("5.1")
-      expect(hash[:type]).to eq("technical")
-      expect(hash[:comments]).to eq("Test")
-      expect(hash[:proposed_change]).to eq("Change")
-      expect(hash[:observations]).to eq("Obs")
+      expect(hash["id"]).to eq("US-001")
+      expect(hash["body"]).to eq("US")
+      expect(hash["locality"]["clause"]).to eq("5.1")
+      expect(hash["type"]).to eq("technical")
+      expect(hash["comments"]).to eq("Test")
+      expect(hash["proposed_change"]).to eq("Change")
+      expect(hash["observations"]).to eq("Obs")
     end
   end
 

data/spec/commenter/comment_type_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Commenter::CommentType do
+  describe ".code" do
+    it "maps full names and codes to codes" do
+      expect(described_class.code("Editorial")).to eq("ed")
+      expect(described_class.code("general")).to eq("ge")
+      expect(described_class.code("te")).to eq("te")
+    end
+
+    it "passes unrecognized values through" do
+      expect(described_class.code("custom")).to eq("custom")
+      expect(described_class.code("")).to eq("")
+      expect(described_class.code(nil)).to be_nil
+    end
+  end
+
+  describe ".full_name" do
+    it "expands codes to full names" do
+      expect(described_class.full_name("ge")).to eq("general")
+      expect(described_class.full_name("TE")).to eq("technical")
+      expect(described_class.full_name("editorial")).to eq("editorial")
+    end
+
+    it "passes unrecognized values through" do
+      expect(described_class.full_name("Custom")).to eq("Custom")
+      expect(described_class.full_name(nil)).to be_nil
+    end
+  end
+
+  describe ".display_name" do
+    it "capitalizes recognized types for display" do
+      expect(described_class.display_name("ge")).to eq("General")
+      expect(described_class.display_name("technical")).to eq("Technical")
+      expect(described_class.display_name("ed")).to eq("Editorial")
+    end
+
+    it "defaults unknown or missing types" do
+      expect(described_class.display_name("unknown")).to eq("unknown")
+      expect(described_class.display_name(nil)).to eq("Unknown")
+    end
+  end
+end

data/spec/commenter/disposition_status_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Commenter::DispositionStatus do
+  describe ".match" do
+    it "classifies accepted dispositions" do
+      expect(described_class.match("Accepted")).to eq(:accepted)
+      expect(described_class.match("accepted.")).to eq(:accepted)
+      expect(described_class.match("Partially accepted")).to eq(:accepted)
+    end
+
+    it "classifies accept-with-modifications before the bare accept pattern" do
+      expect(described_class.match("Accept with modifications")).to eq(:accept_with_modifications)
+      expect(described_class.match("Accepted with modifications")).to eq(:accept_with_modifications)
+      expect(described_class.match("Accepted, with changes")).to eq(:accept_with_modifications)
+      expect(described_class.match("AWM")).to eq(:accept_with_modifications)
+    end
+
+    it "classifies rejection including the 'not accepted' phrasing" do
+      expect(described_class.match("Rejected")).to eq(:rejected)
+      expect(described_class.match("Not accepted")).to eq(:rejected)
+    end
+
+    it "classifies noted, todo, and non-matching text" do
+      expect(described_class.match("Noted")).to eq(:noted)
+      expect(described_class.match("TODO: review")).to eq(:todo)
+      expect(described_class.match("Deferred to next revision")).to be_nil
+      expect(described_class.match("")).to be_nil
+      expect(described_class.match(nil)).to be_nil
+    end
+  end
+
+  describe ".statuses" do
+    it "lists the canonical statuses" do
+      expect(described_class.statuses)
+        .to eq(%i[accept_with_modifications rejected accepted noted todo])
+    end
+  end
+end

data/spec/commenter/filler_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "nokogiri"
+require "zip"
+
+RSpec.describe Commenter::Filler do
+  let(:template_path) { File.expand_path("../../data/iso_comment_template_2012-03.docx", __dir__) }
+
+  def comment(attrs)
+    Commenter::Comment.new({ body: "US", type: "technical", comments: "Text" }.merge(attrs))
+  end
+
+  def header_xml(output_path)
+    Zip::File.open(output_path) do |zip|
+      zip.entries.find { |entry| entry.name == "word/header2.xml" }.get_input_stream(&:read)
+    end
+  end
+
+  def body_xml(output_path)
+    Zip::File.open(output_path) do |zip|
+      zip.entries.find { |entry| entry.name == "word/document.xml" }.get_input_stream(&:read)
+    end
+  end
+
+  # Rows of the comment table as arrays of cell text. Read via Nokogiri over
+  # the extracted XML rather than Docx::Document, whose open zip handle keeps
+  # the file locked on Windows and breaks Dir.mktmpdir teardown.
+  def body_rows(output_path)
+    document = Nokogiri::XML(body_xml(output_path))
+    document.xpath("//w:tbl").flat_map { |table| table.xpath("./w:tr") }.map do |row|
+      row.xpath("./w:tc").map { |cell| cell.xpath(".//w:t").map(&:text).join }
+    end
+  end
+
+  it "writes comment rows into the template table" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [
+                                 comment(id: "US-001", locality: { clause: "5.2.1", element: "Table 3", line_number: "45" },
+                                         proposed_change: "Fix them", observations: "Accepted")
+                               ])
+
+      row = body_rows(output).first
+      expect(row[0]).to include("US-001")
+      expect(row[1]).to include("45")
+      expect(row[2]).to include("5.2.1")
+      expect(row[3]).to include("Table 3")
+      expect(row[4]).to include("technical")
+      expect(row[5]).to include("Text")
+      expect(row[6]).to include("Fix them")
+      expect(row[7]).to include("Accepted")
+    end
+  end
+
+  it "keeps multiple comments in input order and accepts plain hashes" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [
+                                 { "id" => "DE-001", "comments" => "First" },
+                                 comment(id: "US-001", comments: "Second")
+                               ])
+
+      rows = body_rows(output)
+      expect(rows.length).to eq(2)
+      expect(rows[0][0]).to include("DE-001")
+      expect(rows[1][0]).to include("US-001")
+    end
+  end
+
+  it "fills the header metadata labels in the page header" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [comment(id: "US-001")],
+                               date: "2026-08-28", document: "ISO 2533:2026", project: "Ballot review")
+
+      header = header_xml(output)
+      expect(header).to include("Date: 2026-08-28")
+      expect(header).to include("Document: ISO 2533:2026")
+      expect(header).to include("Project: Ballot review")
+    end
+  end
+
+  it "leaves header labels untouched when no metadata is given" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [comment(id: "US-001")])
+
+      header = header_xml(output)
+      expect(header).to include(">Date: <")
+      expect(header).to include(">Document:<")
+      expect(header).to include(">Project:<")
+    end
+  end
+
+  it "escapes XML special characters in metadata values" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [comment(id: "US-001")],
+                               document: "A&B <standard>")
+
+      expect(header_xml(output)).to include("Document: A&amp;B &lt;standard&gt;")
+    end
+  end
+
+  it "shades observation cells according to disposition status" do
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "filled.docx")
+      described_class.new.fill(template_path, output, [
+                                 comment(id: "US-001", observations: "Accepted"),
+                                 comment(id: "US-002", observations: "Not accepted")
+                               ], shading: true)
+
+      xml = body_xml(output)
+      expect(xml).to include('w:fill="92D050"')
+      expect(xml).to include('w:fill="FF99CC"')
+    end
+  end
+end

data/spec/commenter/github_integration_spec.rb

@@ -135,49 +135,82 @@ RSpec.describe Commenter::GitHubIssueCreator do
 
   describe "template variable generation" do
     let(:creator) { described_class.new(config_file.path, title_template_file.path, body_template_file.path) }
-    let(:comment_sheet) { Commenter::CommentSheet.from_hash(yaml_data) }
-    let(:comment) { comment_sheet.comments.first }
-
-    it "generates correct template variables" do
-      variables = creator.send(:template_variables, comment, comment_sheet)
-
-      expect(variables["stage"]).to eq("DIS")
-      expect(variables["document"]).to eq("Test Document")
-      expect(variables["comment_id"]).to eq("US-001")
-      expect(variables["type"]).to eq("technical")
-      expect(variables["type_full_name"]).to eq("Technical")
-      expect(variables["clause"]).to eq("5.1")
-      expect(variables["element"]).to eq("Table 1")
-      expect(variables["comments"]).to eq("Test comment text")
-      expect(variables["brief_summary"]).to include("Clause 5.1")
-      expect(variables["has_proposed_change"]).to be true
+    let(:title_template_file) do
+      file = Tempfile.new(["title", ".liquid"])
+      file.write("{{ stage }}|{{ document }}|{{ project }}|{{ version }}|{{ comment_id }}|{{ type }}|" \
+                 "{{ type_full_name }}|{{ clause }}|{{ element }}|{{ line_number }}|" \
+                 "{{ has_observations }}|{{ has_proposed_change }}|{{ locality_summary }}|{{ unique_id }}")
+      file.close
+      file
+    end
+
+    it "exposes sheet, comment, and computed variables to templates" do
+      result = creator.create_issues_from_yaml(yaml_file.path, dry_run: true).first
+      variables = result[:title].split("|")
+
+      expect(variables).to eq(
+        [
+          "DIS", "Test Document", "Test Project", "2012-03", "US-001", "technical",
+          "Technical", "5.1", "Table 1", "", "false", "true", "Clause 5.1, Table 1", "[DIS] US-001"
+        ]
+      )
     end
   end
 
   describe "label determination" do
     let(:creator) { described_class.new(config_file.path, title_template_file.path, body_template_file.path) }
-    let(:comment_sheet) { Commenter::CommentSheet.from_hash(yaml_data) }
-    let(:comment) { comment_sheet.comments.first }
 
-    it "combines default, stage-specific, and comment type labels" do
-      labels = creator.send(:determine_labels, comment, comment_sheet)
+    it "combines default, stage-specific, and comment type labels without duplicates" do
+      result = creator.create_issues_from_yaml(yaml_file.path, dry_run: true).first
+      labels = result[:labels]
 
-      expect(labels).to include("comment-review") # default
-      expect(labels).to include("draft-international-standard") # stage-specific
-      expect(labels).to include("technical") # comment type (expanded)
-      expect(labels.uniq).to eq(labels) # no duplicates
+      expect(labels).to include("comment-review", "draft-international-standard", "technical")
+      expect(labels.uniq).to eq(labels)
     end
   end
+end
 
-  describe "comment type expansion" do
-    let(:creator) { described_class.new(config_file.path, title_template_file.path, body_template_file.path) }
+RSpec.describe Commenter::GitHubIssueRetriever do
+  let(:config_file) do
+    file = Tempfile.new(["config", ".yaml"])
+    file.write({ "github" => { "repository" => "test-org/test-repo", "token" => "test-token" } }.to_yaml)
+    file.close
+    file
+  end
+
+  let(:osd_yaml_file) do
+    file = Tempfile.new(["comments", ".yaml"])
+    file.write({
+      "version" => "osd",
+      "document" => "ISO/DIS 5843-6(en)",
+      "stage" => "DIS",
+      "comments" => [
+        {
+          "id" => "1",
+          "body" => "John Doe",
+          "locality" => { "clause" => "5.2.1" },
+          "type" => "editorial",
+          "comments" => "The values in Table 3 are inconsistent."
+        }
+      ]
+    }.to_yaml)
+    file.close
+    file
+  end
+
+  after do
+    config_file.unlink
+    osd_yaml_file.unlink
+  end
+
+  describe "#retrieve_observations_from_yaml" do
+    it "rewrites the YAML with the schema header matching its version" do
+      retriever = described_class.new(config_file.path)
+
+      retriever.retrieve_observations_from_yaml(osd_yaml_file.path)
 
-    it "expands comment type codes correctly" do
-      expect(creator.send(:expand_comment_type, "ge")).to eq("General")
-      expect(creator.send(:expand_comment_type, "te")).to eq("Technical")
-      expect(creator.send(:expand_comment_type, "ed")).to eq("Editorial")
-      expect(creator.send(:expand_comment_type, "unknown")).to eq("unknown")
-      expect(creator.send(:expand_comment_type, nil)).to eq("Unknown")
+      expect(osd_yaml_file.open.read.lines.first)
+        .to eq("# yaml-language-server: $schema=schema/iso_comment_osd.yaml\n")
     end
   end
 end

data/spec/commenter/osd_xlsx_parser_spec.rb

@@ -27,7 +27,8 @@ RSpec.describe Commenter::Parser::OsdXlsxParser do
 
         expect(comment.id).to eq("1")
         expect(comment.body).to eq("John Doe")
-        expect(comment.locality).to eq({ clause: "5.2.1", element: "Requirements" })
+        expect(comment.locality.clause).to eq("5.2.1")
+        expect(comment.locality.element).to eq("Requirements")
         expect(comment.comments).to eq("The values in Table 3 are inconsistent.")
         expect(comment.proposed_change).to eq("Correct the values in column 2.")
         expect(comment.comment_type).to eq("Editorial")
@@ -62,7 +63,7 @@ RSpec.describe Commenter::Parser::OsdXlsxParser do
         comments = described_class.new.parse(path).comments
 
         expect(comments.length).to eq(2)
-        expect(comments.last.locality).to eq({})
+        expect(comments.last.locality.clause).to be_nil
         expect(comments.last.proposed_change).to be_nil
       end
     end

data/spec/commenter/track_change_docx_parser_spec.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../support/redline_docx_builder"
+
+RSpec.describe Commenter::Parser::TrackChangeDocxParser do
+  def author = "CHEN Yvonne"
+
+  def change(kind, id, text, date: "2025-12-05T20:10:00Z")
+    { change: kind, id: id, author: author, date: date, text: text }
+  end
+
+  def with_redline(paragraphs, comments: [], **options)
+    file = Tempfile.new(%w[redline .docx])
+    RedlineDocxBuilder.write(file.path, paragraphs, comments: comments)
+    yield described_class.new.parse(file.path, options)
+  ensure
+    file.close
+    file.unlink
+  end
+
+  let(:base_paragraphs) do
+    [
+      { change: :ins, id: "1", author: author, date: "2025-12-05T20:10:00Z", text: "ISO boilerplate" },
+      { heading: true, level: 1, text: "4 Basic principles" },
+      { change: :del, id: "2", author: author, date: "2025-12-05T20:11:00Z", text: "old text" },
+      { heading: true, level: 2, text: "4.2.1Thermodynamic temperature tangent" },
+      { marker: true, id: "9", author: author },
+      { parts: [{ text: "Body " }, change(:ins, "3", "inserted")] },
+      { heading: true, level: 1, text: "Annex A" },
+      { change: :moveTo, id: "4", author: author, date: "2025-12-06T10:00:00Z", text: "moved" }
+    ]
+  end
+
+  it "extracts track changes in document order with rendered proposed_change" do
+    with_redline(base_paragraphs) do |sheet|
+      comments = sheet.comments
+
+      expect(comments.map(&:proposed_change)).to eq([
+                                                      'Insert: "ISO boilerplate"',
+                                                      'Delete: "old text"',
+                                                      'Insert: "inserted"',
+                                                      'Move to: "moved"'
+                                                    ])
+      expect(comments.map(&:comments)).to eq([
+                                               "Track change (insertion)",
+                                               "Track change (deletion)",
+                                               "Track change (insertion)",
+                                               "Track change (move (to))"
+                                             ])
+    end
+  end
+
+  it "assigns the clause of the nearest preceding heading, including sub-clauses" do
+    with_redline(base_paragraphs) do |sheet|
+      expect(sheet.comments.map(&:clause)).to eq(["_whole document", "4", "4.2.1", "Annex A"])
+    end
+  end
+
+  it "skips self-closing paragraph-mark markers without corrupting later capture" do
+    with_redline(base_paragraphs) do |sheet|
+      expect(sheet.comments.length).to eq(4)
+    end
+  end
+
+  it "captures nested track changes" do
+    paragraphs = [
+      { change: :ins, id: "1", author: author, date: "2025-12-05T20:10:00Z", text: "",
+        nested: [change(:ins, "2", "inner text")] }
+    ]
+
+    with_redline(paragraphs) do |sheet|
+      # The inner change ends first, so it is emitted before its wrapper.
+      expect(sheet.comments.map(&:proposed_change)).to eq(['Insert: "inner text"', 'Insert: ""'])
+    end
+  end
+
+  it "builds CS-prefixed sequential IDs by default" do
+    with_redline(base_paragraphs) do |sheet|
+      expect(sheet.comments.map(&:id)).to eq(%w[CS-001 CS-002 CS-003 CS-004])
+      expect(sheet.comments.map(&:body).uniq).to eq(["CS"])
+    end
+  end
+
+  it "uses a custom body code and technical type" do
+    with_redline(base_paragraphs, body: "GB", type: "ge") do |sheet|
+      expect(sheet.comments.first.id).to eq("GB-001")
+      expect(sheet.comments.first.type).to eq("general")
+    end
+  end
+
+  it "stamps observations on every entry when given" do
+    with_redline(base_paragraphs, observations: "Accepted. ISO/CS tracked change accepted.") do |sheet|
+      expect(sheet.comments.map(&:observations).uniq)
+        .to eq(["Accepted. ISO/CS tracked change accepted."])
+    end
+  end
+
+  it "leaves observations blank by default and honours exclude_observations" do
+    with_redline(base_paragraphs) do |sheet|
+      expect(sheet.comments.first.observations).to be_nil
+    end
+
+    with_redline(base_paragraphs, observations: "Accepted.", exclude_observations: true) do |sheet|
+      expect(sheet.comments.first.observations).to be_nil
+    end
+  end
+
+  it "builds 2012-03 sheet metadata from the changes and options" do
+    with_redline(base_paragraphs, document: "ISO 2533:2026", stage: "DIS") do |sheet|
+      expect(sheet.version).to eq("2012-03")
+      expect(sheet.schema_name).to eq("iso_comment_2012-03.yaml")
+      expect(sheet.document).to eq("ISO 2533:2026")
+      expect(sheet.stage).to eq("DIS")
+      expect(sheet.date).to eq("2025-12-06")
+    end
+  end
+
+  it "is reachable through Parser dispatch with format redline" do
+    file = Tempfile.new(%w[redline .docx])
+    RedlineDocxBuilder.write(file.path, base_paragraphs)
+
+    sheet = Commenter::Parser.new.parse(file.path, format: "redline")
+    expect(sheet.comments.length).to eq(4)
+  ensure
+    file.close
+    file.unlink
+  end
+
+  describe "element locality" do
+    def table_paragraphs
+      [
+        { heading: true, level: 1, text: "4 Basic principles" },
+        { text: "Table 3 — Atmospheric properties at altitude" },
+        { parts: [{ text: "Body " }, change(:ins, "5", "edited")] },
+        { text: "Formula (9):" },
+        { change: :del, id: "6", author: author, date: "2025-12-05T20:10:00Z", text: "old formula text" },
+        { text: "NOTE 2 — This note provides clarification." },
+        { parts: [{ text: "note body " }, change(:ins, "7", "edited")] }
+      ]
+    end
+
+    it "resolves the element from caption paragraphs and carries it to following changes" do
+      with_redline(table_paragraphs) do |sheet|
+        expect(sheet.comments.map(&:element)).to eq(["Table 3", "Formula (9)", "NOTE 2"])
+      end
+    end
+
+    it "resolves inline element mentions" do
+      paragraphs = [
+        { heading: true, level: 1, text: "5 Data tables" },
+        { parts: [{ text: "The values in Table 5 shall be " }, change(:ins, "8", "interpreted thus")] }
+      ]
+
+      with_redline(paragraphs) do |sheet|
+        expect(sheet.comments.first.element).to eq("Table 5")
+      end
+    end
+
+    it "resolves annex figure captions" do
+      paragraphs = [
+        { heading: true, level: 1, text: "Annex A" },
+        { text: "Figure A.2 — Temperature profile" },
+        { change: :ins, id: "9", author: author, date: "2025-12-05T20:10:00Z", text: "new caption text" }
+      ]
+
+      with_redline(paragraphs) do |sheet|
+        expect(sheet.comments.first.element).to eq("Figure A.2")
+      end
+    end
+
+    it "resets the element when the clause changes" do
+      paragraphs = table_paragraphs + [
+        { heading: true, level: 1, text: "5 Data tables" },
+        { parts: [{ text: "Plain body " }, change(:ins, "10", "edited")] }
+      ]
+
+      with_redline(paragraphs) do |sheet|
+        expect(sheet.comments.last.element).to be_nil
+      end
+    end
+  end
+
+  describe "unnumbered sub-headings" do
+    it "inherit the parent heading clause" do
+      paragraphs = [
+        { heading: true, level: 1, text: "4 Basic principles" },
+        { heading: true, level: 2, text: "4.2 Temperature" },
+        { heading: true, level: 3, text: "Justification" },
+        { parts: [{ text: "Body " }, change(:ins, "11", "edited")] }
+      ]
+
+      with_redline(paragraphs) do |sheet|
+        expect(sheet.comments.first.clause).to eq("4.2")
+      end
+    end
+  end
+
+  describe "reviewer comment threads" do
+    let(:remark_paragraphs) do
+      [
+        { change: :ins, id: "1", author: author, date: "2025-12-05T20:10:00Z", text: "tracked" },
+        { heading: true, level: 1, text: "1 Scope" },
+        { anchor: "74", text: "Values in feet." },
+        { heading: true, level: 1, text: "2 Normative references" },
+        { anchor: "88", text: "Introduction paragraph." }
+      ]
+    end
+
+    let(:remarks) do
+      [
+        { id: "74", author: author, date: "2025-12-05T20:10:00Z",
+          text: "Please provide values in km. Equivalent values in ft can be provided in brackets." },
+        { id: "88", author: author, date: "2025-12-05T20:12:00Z",
+          text: "Remove this paragraph from the Introduction." }
+      ]
+    end
+
+    it "emits remarks after track changes with -CNNN ids and verbatim text" do
+      with_redline(remark_paragraphs, comments: remarks) do |sheet|
+        expect(sheet.comments.length).to eq(3)
+
+        remark = sheet.comments.last
+        expect(sheet.comments[1].id).to eq("CS-C001")
+        expect(remark.id).to eq("CS-C002")
+        expect(remark.comments).to eq("Remove this paragraph from the Introduction.")
+      end
+    end
+
+    it "rewords the remark into proposed_change" do
+      with_redline(remark_paragraphs, comments: remarks) do |sheet|
+        expect(sheet.comments[1].proposed_change)
+          .to eq("Provide values in km. Equivalent values in ft can be provided in brackets.")
+      end
+    end
+
+    it "leaves remark observations empty for the owner to draft" do
+      with_redline(remark_paragraphs, comments: remarks) do |sheet|
+        expect(sheet.comments[1].observations).to be_nil
+      end
+    end
+
+    it "anchors remarks to the clause of their commentRangeStart" do
+      with_redline(remark_paragraphs, comments: remarks) do |sheet|
+        expect(sheet.comments[1].clause).to eq("1")
+        expect(sheet.comments.last.clause).to eq("2")
+      end
+    end
+
+    it "defaults unanchored remarks to _whole document" do
+      unanchored = [{ id: "99", author: author, date: "2025-12-05T20:10:00Z", text: "General remark." }]
+
+      with_redline([{ text: "Body" }], comments: unanchored) do |sheet|
+        expect(sheet.comments.first.clause).to eq("_whole document")
+      end
+    end
+
+    it "stamps accept_all on track changes but not on remarks" do
+      with_redline(remark_paragraphs, accept_all: true, comments: remarks) do |sheet|
+        expect(sheet.comments.first.observations).to eq("Accepted. Tracked change accepted.")
+        expect(sheet.comments[1].observations).to be_nil
+      end
+    end
+
+    it "prefers an explicit observations stamp over accept_all" do
+      with_redline(remark_paragraphs, accept_all: true, observations: "Custom.", comments: remarks) do |sheet|
+        expect(sheet.comments.first.observations).to eq("Custom.")
+      end
+    end
+
+    it "handles documents without comments.xml content" do
+      with_redline([{ text: "No changes, no remarks." }]) do |sheet|
+        expect(sheet.comments).to be_empty
+      end
+    end
+  end
+end