commenter 0.3.0 → 0.3.1

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

data/spec/support/redline_docx_builder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "zip"
+
+# Builds minimal redline DOCX files for specs, without binary fixtures. The
+# document body is assembled from a paragraph DSL:
+#
+#   { heading: "1", level: 1, text: "Scope" }
+#   { text: "Body text " }
+#   { change: :ins, id: "1", author: "CHEN Yvonne", date: "2025-12-05T20:10:00Z",
+#     text: "inserted" }
+#   { marker: true }  # self-closing paragraph-mark insertion inside rPr
+#   { anchor: "74", text: "Anchored text" }  # w:commentRangeStart/End around text
+#
+# Multiple entries in one paragraph can be given via :parts.
+#
+# comments: [{ id: "74", author: "CHEN Yvonne", date: "...", text: "remark" }]
+# are written to word/comments.xml.
+module RedlineDocxBuilder
+  W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+  private_constant :W_NS
+
+  HEADING_LEVEL_STYLE = { 1 => "Heading1", 2 => "Heading2", 3 => "Heading3" }.freeze
+  CHANGE_TAG = { ins: "w:ins", del: "w:del", moveFrom: "w:moveFrom", moveTo: "w:moveTo" }.freeze
+  private_constant :HEADING_LEVEL_STYLE, :CHANGE_TAG
+
+  def self.write(path, paragraphs, comments: [])
+    zip = Zip::File.new(path, create: true)
+    zip.get_output_stream("word/document.xml") { |stream| stream.write(document_xml(paragraphs)) }
+    zip.get_output_stream("word/comments.xml") { |stream| stream.write(comments_xml(comments)) }
+    zip.close
+    path
+  end
+
+  def self.document_xml(paragraphs)
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <w:document xmlns:w="#{W_NS}"><w:body>#{paragraphs.map { |p| paragraph_xml(p) }.join}</w:body></w:document>
+    XML
+  end
+
+  def self.comments_xml(comments)
+    entries = comments.map do |c|
+      attrs = %(w:id="#{c[:id]}" w:author="#{c[:author]}" w:date="#{c[:date]}" w:initials="X")
+      %(<w:comment #{attrs}><w:p><w:r><w:t>#{c[:text]}</w:t></w:r></w:p></w:comment>)
+    end
+
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <w:comments xmlns:w="#{W_NS}">#{entries.join}</w:comments>
+    XML
+  end
+
+  def self.paragraph_xml(paragraph)
+    if paragraph[:marker]
+      return %(<w:p><w:pPr><w:rPr><w:ins w:id="#{paragraph[:id]}" w:author="#{paragraph[:author]}"/></w:rPr></w:pPr></w:p>)
+    end
+
+    inner = if paragraph[:parts]
+              paragraph[:parts].map { |part| part_xml(part) }.join
+            elsif paragraph[:heading]
+              %(<w:r><w:t>#{paragraph[:text]}</w:t></w:r>)
+            elsif paragraph[:change]
+              change_xml(paragraph)
+            else
+              %(<w:r><w:t>#{paragraph[:text]}</w:t></w:r>)
+            end
+
+    ppr = paragraph[:heading] ? %(<w:pPr><w:pStyle w:val="#{HEADING_LEVEL_STYLE.fetch(paragraph[:level], 1)}"/></w:pPr>) : ""
+    anchor = paragraph[:anchor] ? %(<w:commentRangeStart w:id="#{paragraph[:anchor]}"/>) : ""
+    anchor_end = paragraph[:anchor] ? %(<w:commentRangeEnd w:id="#{paragraph[:anchor]}"/>) : ""
+    "<w:p>#{ppr}#{anchor}#{inner}#{anchor_end}</w:p>"
+  end
+
+  def self.part_xml(part)
+    part[:change] ? change_xml(part) : %(<w:r><w:t>#{part[:text]}</w:t></w:r>)
+  end
+
+  def self.change_xml(change)
+    tag = CHANGE_TAG.fetch(change[:change])
+    attrs = %(w:id="#{change[:id]}" w:author="#{change[:author]}" w:date="#{change[:date]}")
+
+    return %(<#{tag} #{attrs}>#{change[:nested].map { |child| change_xml(child) }.join}</#{tag}>) if change[:nested]
+
+    text_tag = change[:change] == :del ? "w:delText" : "w:t"
+    %(<#{tag} #{attrs}><w:r><#{text_tag}>#{change[:text]}</#{text_tag}></w:r></#{tag}>)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: commenter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -139,10 +139,13 @@ files:
 - lib/commenter/cli.rb
 - lib/commenter/comment.rb
 - lib/commenter/comment_sheet.rb
+- lib/commenter/comment_type.rb
 - lib/commenter/filler.rb
 - lib/commenter/github_integration.rb
+- lib/commenter/github_session.rb
 - lib/commenter/parser.rb
 - lib/commenter/parser/osd_xlsx_parser.rb
+- lib/commenter/parser/track_change_docx_parser.rb
 - lib/commenter/version.rb
 - schema/iso_comment_2012-03.yaml
 - schema/iso_comment_osd.yaml
@@ -150,11 +153,14 @@ files:
 - spec/commenter/cli_spec.rb
 - spec/commenter/comment_sheet_spec.rb
 - spec/commenter/comment_spec.rb
+- spec/commenter/comment_type_spec.rb
 - spec/commenter/github_integration_spec.rb
 - spec/commenter/osd_xlsx_parser_spec.rb
+- spec/commenter/track_change_docx_parser_spec.rb
 - spec/commenter_spec.rb
 - spec/spec_helper.rb
 - spec/support/osd_fixtures.rb
+- spec/support/redline_docx_builder.rb
 - spec/support/xlsx_builder.rb
 homepage: https://github.com/metanorma/commenter
 licenses: