commenter 0.2.3 → 0.3.0

data/spec/commenter/osd_xlsx_parser_spec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../support/osd_fixtures"
+
+RSpec.describe Commenter::Parser::OsdXlsxParser do
+  include OsdFixtures
+
+  describe "resolved variant" do
+    it "extracts sheet metadata from the header rows" do
+      with_resolved_xlsx do |path|
+        sheet = described_class.new.parse(path)
+
+        expect(sheet.version).to eq("osd")
+        expect(sheet.date).to eq("2026-04-21")
+        expect(sheet.document).to eq("ISO/DIS 5843-6(en)")
+        expect(sheet.stage).to eq("DIS")
+        expect(sheet.project).to eq("ISO/DIS 5843-6")
+        expect(sheet.title_en).to eq("Aerodromes and heliports")
+        expect(sheet.title_fr).to eq("Aerodromes and heliports (FR)")
+      end
+    end
+
+    it "maps columns to comment attributes" do
+      with_resolved_xlsx do |path|
+        comment = described_class.new.parse(path).comments.first
+
+        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.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")
+        expect(comment.resolution_status).to eq("Accepted")
+        expect(comment.resolution_date).to eq("2026-04-10")
+        expect(comment.feedbacks).to eq("Feedback from the working group")
+        expect(comment.motivation).to eq("Reviewed and approved by the working group.")
+        expect(comment.created_date).to eq("2026-04-01")
+        expect(comment.stage_code).to eq("40.20")
+      end
+    end
+
+    it "builds observations from resolution status and motivation" do
+      with_resolved_xlsx do |path|
+        comments = described_class.new.parse(path).comments
+
+        expect(comments.first.observations).to eq("Accepted. Reviewed and approved by the working group.")
+        expect(comments.last.observations).to eq("Rejected")
+      end
+    end
+
+    it "normalizes numeric comment ids to strings" do
+      with_resolved_xlsx do |path|
+        comments = described_class.new.parse(path).comments
+
+        expect(comments.map(&:id)).to eq(%w[1 2])
+      end
+    end
+
+    it "skips empty rows and keeps comments without clause data" do
+      with_resolved_xlsx do |path|
+        comments = described_class.new.parse(path).comments
+
+        expect(comments.length).to eq(2)
+        expect(comments.last.locality).to eq({})
+        expect(comments.last.proposed_change).to be_nil
+      end
+    end
+
+    it "falls back to proposal-on-text when proposed change is blank" do
+      rows = resolved_rows
+      rows[4][8] = nil # Proposed change
+      with_resolved_xlsx(rows) do |path|
+        sheet = described_class.new.parse(path)
+
+        expect(sheet.comments.first.proposed_change).to eq("Proposal on the text")
+      end
+    end
+
+    it "excludes observations when exclude_observations is set" do
+      with_resolved_xlsx do |path|
+        sheet = described_class.new.parse(path, exclude_observations: true)
+
+        expect(sheet.comments.first.observations).to be_nil
+      end
+    end
+
+    it "maps columns by real position when the header row has gaps" do
+      with_resolved_xlsx(resolved_rows(gap: true)) do |path|
+        comment = described_class.new.parse(path).comments.first
+
+        expect(comment.id).to eq("1")
+        expect(comment.type).to eq("editorial")
+        expect(comment.comments).to eq("The values in Table 3 are inconsistent.")
+        expect(comment.resolution_status).to eq("Accepted")
+        expect(comment.stage_code).to eq("40.20")
+      end
+    end
+  end
+end
+
+RSpec.describe Commenter::Parser::OsdXlsxParser do
+  include OsdFixtures
+
+  describe "unresolved variant" do
+    it "parses the first sheet by default" do
+      with_unresolved_workbook do |path|
+        sheet = described_class.new.parse(path)
+
+        expect(sheet.comments.map(&:id)).to eq(%w[7 8])
+        expect(sheet.comments.first.body).to eq("John Doe")
+        expect(sheet.comments.first.type).to eq("editorial")
+        expect(sheet.comments.first.feedbacks).to eq("Reply from secretariat")
+        expect(sheet.comments.first.motivation).to eq("Justification text")
+        expect(sheet.comments.first.created_date).to eq("2026-04-05")
+        expect(sheet.comments.last.observations).to be_nil
+      end
+    end
+
+    it "uses the unresolved sheet when unresolved_only is set" do
+      with_unresolved_workbook do |path|
+        sheet = described_class.new.parse(path, unresolved_only: true)
+
+        expect(sheet.comments.map(&:id)).to eq(["9"])
+        expect(sheet.comments.first.type).to eq("general")
+      end
+    end
+
+    it "uses the resolved sheet when resolved_only is set" do
+      with_unresolved_workbook do |path|
+        sheet = described_class.new.parse(path, resolved_only: true)
+
+        expect(sheet.comments.map(&:id)).to eq(["10"])
+        expect(sheet.comments.first.observations).to eq("Partially accepted. Compromise reached.")
+      end
+    end
+
+    it "parses the sheet given by name" do
+      with_unresolved_workbook do |path|
+        sheet = described_class.new.parse(path, sheet: "Resolved comments (1)")
+
+        expect(sheet.comments.map(&:id)).to eq(["10"])
+      end
+    end
+
+    it "raises when the requested sheet does not exist" do
+      with_unresolved_workbook do |path|
+        expect { described_class.new.parse(path, sheet: "Nope") }
+          .to raise_error(/Sheet 'Nope' not found/)
+      end
+    end
+  end
+end
+
+RSpec.describe Commenter::Parser::OsdXlsxParser do
+  include OsdFixtures
+
+  describe "round-trip stability" do
+    it "produces identical YAML when reloaded from its own output" do
+      with_resolved_xlsx do |path|
+        sheet = described_class.new.parse(path)
+        reparsed = Commenter::CommentSheet.from_hash(sheet.to_yaml_h)
+
+        expect(reparsed.to_yaml_h).to eq(sheet.to_yaml_h)
+      end
+    end
+
+    it "omits nil titles from YAML output" do
+      rows = resolved_rows
+      rows[1] = ["2026-04-21", "ISO/CD 12345(en)"]
+      with_resolved_xlsx(rows) do |path|
+        sheet = described_class.new.parse(path)
+
+        expect(sheet.stage).to eq("CD")
+        expect(sheet.to_yaml_h).not_to have_key("title_en")
+        expect(sheet.to_yaml_h).not_to have_key("title_fr")
+      end
+    end
+  end
+end

data/spec/support/osd_fixtures.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "xlsx_builder"
+
+# Fixture data and helpers mirroring ISO OSD XLSX exports for specs.
+module OsdFixtures
+  RESOLVED_HEADERS = [
+    "Comment ID", "User name", "Clause nb", "Clause Title", "Type", "Subtype",
+    "Comment", "Proposal on Text", "Proposed change", "Feedbacks", "Topic",
+    "Tags", "Created Date", "Resolution status", "Motivation", "Resolution Date", "Stage code"
+  ].freeze
+
+  UNRESOLVED_HEADERS = [
+    "User name", "Clause nb", "Clause Title", "Type", "Comment type",
+    "Comment/Motivation", "Comment on text", "Proposal on Text", "Proposed change",
+    "Replies", "Resolution status", "Justification", "Resolution Date", "Date", "Comment number"
+  ].freeze
+
+  METADATA_ROWS = [
+    ["Date", "Reference", nil, nil, "Title EN", nil, nil, "Title FR"],
+    ["2026-04-21", "ISO/DIS 5843-6(en)", nil, nil, "Aerodromes and heliports",
+     nil, nil, "Aerodromes and heliports (FR)"]
+  ].freeze
+
+  RESOLVED_DATA_ROWS = [
+    [1, "John Doe", "5.2.1", "Requirements", "Comment", "Editorial",
+     "The values in Table 3 are inconsistent.", "Proposal on the text",
+     "Correct the values in column 2.", "Feedback from the working group",
+     "Topic A", "tag1", "2026-04-01", "Accepted",
+     "Reviewed and approved by the working group.", "2026-04-10", "40.20"],
+    [],
+    [2, "Jane Roe", nil, nil, "Comment", "Technical", "General remark on the introduction.",
+     nil, nil, nil, nil, nil, "2026-04-02", "Rejected", nil, nil, "40.20"]
+  ].freeze
+
+  def resolved_rows(gap: false)
+    headers = RESOLVED_HEADERS.dup
+    data_rows = RESOLVED_DATA_ROWS.map(&:dup)
+    if gap
+      headers.insert(5, nil)
+      data_rows = data_rows.map { |row| row.empty? ? row : row.insert(5, nil) }
+    end
+
+    METADATA_ROWS + [[]] + [headers] + data_rows
+  end
+
+  def unresolved_workbook_sheets
+    [
+      ["Comments (3)",
+       header_block(UNRESOLVED_HEADERS) + [
+         ["John Doe", "5.2.1", "Requirements", "Comment", "Editorial",
+          "The scope is too narrow.", "On text remark", "Proposal on the text",
+          "Widen the scope to include heliports.", "Reply from secretariat",
+          nil, "Justification text", nil, "2026-04-05", 7],
+         ["Jane Roe", "3.1", "Terms", "Comment", "Technical", "Define the term consistently.",
+          nil, nil, "Add a definition.", nil, nil, nil, nil, "2026-04-06", 8]
+       ]],
+      ["Unresolved comments (1)",
+       header_block(UNRESOLVED_HEADERS) + [
+         ["Jack Black", "4.2", "Design", "Comment", "General", "Improve the design section.",
+          nil, nil, nil, nil, nil, nil, nil, "2026-04-07", 9]
+       ]],
+      ["Resolved comments (1)",
+       header_block(RESOLVED_HEADERS) + [
+         [10, "Jill Hill", "6.1", "Testing", "Comment", "Technical", "Add test requirements.",
+          nil, nil, nil, nil, nil, "2026-04-08", "Partially accepted",
+          "Compromise reached.", "2026-04-12", "40.92"]
+       ]]
+    ]
+  end
+
+  def with_resolved_xlsx(rows = nil)
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "comments.xlsx")
+      XlsxBuilder.write(path, [["Comments (2)", rows || resolved_rows]])
+      yield path
+    end
+  end
+
+  def with_unresolved_workbook
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "workbook.xlsx")
+      XlsxBuilder.write(path, unresolved_workbook_sheets)
+      yield path
+    end
+  end
+
+  private
+
+  def header_block(headers)
+    METADATA_ROWS + [[]] + [headers]
+  end
+end

data/spec/support/xlsx_builder.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "zip"
+
+# Builds minimal single-workbook XLSX files for specs, without needing a
+# spreadsheet-writing dependency. Strings are stored via sharedStrings; numbers
+# are written as plain numeric cells. Empty/nil cells are omitted (sparse
+# rows), matching how real exports represent empty cells.
+module XlsxBuilder
+  SHEET_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+  RELS_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+  OFFICE_REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+  private_constant :SHEET_NS, :RELS_NS, :OFFICE_REL_NS
+
+  # sheets: array of [name, rows] pairs, where rows is an array of arrays.
+  # Cell values: String or Numeric. nil and "" cells are skipped.
+  def self.write(path, sheets)
+    shared = []
+    worksheets = sheets.map { |name, rows| [name, worksheet_xml(rows, shared)] }
+
+    zip = Zip::File.new(path, create: true)
+    write_entry(zip, "[Content_Types].xml", content_types_xml(worksheets.size))
+    write_entry(zip, "_rels/.rels", root_rels_xml)
+    write_entry(zip, "xl/workbook.xml", workbook_xml(worksheets.map(&:first)))
+    write_entry(zip, "xl/_rels/workbook.xml.rels", workbook_rels_xml(worksheets.size))
+    write_entry(zip, "xl/sharedStrings.xml", shared_strings_xml(shared))
+    write_entry(zip, "xl/styles.xml", styles_xml)
+    worksheets.each_with_index do |(_name, xml), index|
+      write_entry(zip, "xl/worksheets/sheet#{index + 1}.xml", xml)
+    end
+    zip.close
+    path
+  end
+
+  def self.write_entry(zip, name, content)
+    zip.get_output_stream(name) { |stream| stream.write(content) }
+  end
+
+  def self.worksheet_xml(rows, shared)
+    row_elements = rows.each_with_index.map do |values, row_number|
+      cells = values.each_with_index.map do |value, column_index|
+        cell_xml(value, row_number + 1, column_index, shared)
+      end
+      "<row r=\"#{row_number + 1}\">#{cells.compact.join}</row>"
+    end
+
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <worksheet xmlns="#{SHEET_NS}"><sheetData>#{row_elements.join}</sheetData></worksheet>
+    XML
+  end
+
+  def self.cell_xml(value, row_number, column_index, shared)
+    return if value.nil? || (value.is_a?(String) && value.empty?)
+
+    ref = "#{column_name(column_index)}#{row_number}"
+    return "<c r=\"#{ref}\"><v>#{value}</v></c>" if value.is_a?(Numeric)
+
+    text = value.to_s
+    index = shared.index(text)
+    if index.nil?
+      shared << text
+      index = shared.length - 1
+    end
+    "<c r=\"#{ref}\" t=\"s\"><v>#{index}</v></c>"
+  end
+
+  def self.column_name(index)
+    name = +""
+    remainder = index
+    loop do
+      name.prepend((remainder % 26 + 65).chr)
+      remainder = remainder / 26 - 1
+      break if remainder.negative?
+    end
+    name
+  end
+
+  def self.shared_strings_xml(shared)
+    entries = shared.map { |text| "<si><t>#{escape(text)}</t></si>" }
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <sst xmlns="#{SHEET_NS}" count="#{shared.length}" uniqueCount="#{shared.length}">#{entries.join}</sst>
+    XML
+  end
+
+  def self.content_types_xml(sheet_count)
+    overrides = [
+      "<Override PartName=\"/xl/workbook.xml\" " \
+        "ContentType=\"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml\"/>",
+      "<Override PartName=\"/xl/sharedStrings.xml\" " \
+        "ContentType=\"application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml\"/>",
+      "<Override PartName=\"/xl/styles.xml\" " \
+        "ContentType=\"application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml\"/>"
+    ]
+    (1..sheet_count).each do |index|
+      overrides << "<Override PartName=\"/xl/worksheets/sheet#{index}.xml\" " \
+        "ContentType=\"application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml\"/>"
+    end
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/>#{overrides.join}</Types>
+    XML
+  end
+
+  def self.root_rels_xml
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <Relationships xmlns="#{RELS_NS}"><Relationship Id="rId1" Type="#{OFFICE_REL_NS}/officeDocument" Target="xl/workbook.xml"/></Relationships>
+    XML
+  end
+
+  def self.workbook_xml(sheet_names)
+    sheets = sheet_names.each_with_index.map do |name, index|
+      "<sheet name=\"#{escape(name)}\" sheetId=\"#{index + 1}\" r:id=\"rId#{index + 1}\"/>"
+    end
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <workbook xmlns="#{SHEET_NS}" xmlns:r="#{OFFICE_REL_NS}"><sheets>#{sheets.join}</sheets></workbook>
+    XML
+  end
+
+  def self.workbook_rels_xml(sheet_count)
+    relationships = (1..sheet_count).map do |index|
+      "<Relationship Id=\"rId#{index}\" Type=\"#{OFFICE_REL_NS}/worksheet\" Target=\"worksheets/sheet#{index}.xml\"/>"
+    end
+    relationships << "<Relationship Id=\"rId#{sheet_count + 1}\" Type=\"#{OFFICE_REL_NS}/sharedStrings\" " \
+      "Target=\"sharedStrings.xml\"/>"
+    relationships << "<Relationship Id=\"rId#{sheet_count + 2}\" Type=\"#{OFFICE_REL_NS}/styles\" " \
+      "Target=\"styles.xml\"/>"
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <Relationships xmlns="#{RELS_NS}">#{relationships.join}</Relationships>
+    XML
+  end
+
+  def self.styles_xml
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <styleSheet xmlns="#{SHEET_NS}"><fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts><fills count="1"><fill><patternFill patternType="none"/></fill></fills><borders count="1"><border/></borders><cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs><cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs></styleSheet>
+    XML
+  end
+
+  def self.escape(text)
+    text.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: commenter
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: roo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.10'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -94,8 +108,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Convert between ISO comment sheet DOCX and structured YAML with schema
-  validation.
+description: Convert between ISO comment sheets (DOCX and XLSX) and structured YAML
+  with schema validation.
 email:
 - open.source@ribose.com
 executables:
@@ -109,6 +123,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - README.adoc
@@ -127,14 +142,20 @@ files:
 - lib/commenter/filler.rb
 - lib/commenter/github_integration.rb
 - lib/commenter/parser.rb
+- lib/commenter/parser/osd_xlsx_parser.rb
 - lib/commenter/version.rb
 - schema/iso_comment_2012-03.yaml
+- schema/iso_comment_osd.yaml
 - sig/commenter.rbs
+- spec/commenter/cli_spec.rb
 - spec/commenter/comment_sheet_spec.rb
 - spec/commenter/comment_spec.rb
 - spec/commenter/github_integration_spec.rb
+- spec/commenter/osd_xlsx_parser_spec.rb
 - spec/commenter_spec.rb
 - spec/spec_helper.rb
+- spec/support/osd_fixtures.rb
+- spec/support/xlsx_builder.rb
 homepage: https://github.com/metanorma/commenter
 licenses:
 - BSD-2-Clause
@@ -160,5 +181,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Library to work with ISO comment sheets in DOCX format.
+summary: Library to work with ISO comment sheets in DOCX and XLSX formats.
 test_files: []