commenter 0.2.2 → 0.3.0

data/lib/commenter/parser.rb

@@ -1,12 +1,44 @@
 # frozen_string_literal: true
 
 require "docx"
+require "pathname"
 require_relative "comment_sheet"
 require_relative "comment"
+require_relative "parser/osd_xlsx_parser"
 
 module Commenter
   class Parser
-    def parse(docx_path, options = {})
+    def parse(input_path, options = {})
+      format = detect_format(input_path, options)
+
+      case format
+      when :docx
+        parse_docx(input_path, options)
+      when :xlsx
+        parse_xlsx(input_path, options)
+      else
+        raise "Unsupported file format: #{input_path}. Supported formats: .docx, .xlsx"
+      end
+    end
+
+    private
+
+    def detect_format(path, options = {})
+      return options[:format].to_sym if options[:format]
+
+      ext = File.extname(path).downcase
+      case ext
+      when ".docx" then :docx
+      when ".xlsx", ".xls" then :xlsx
+      else :unknown
+      end
+    end
+
+    def parse_xlsx(xlsx_path, options)
+      OsdXlsxParser.new.parse(xlsx_path, options)
+    end
+
+    def parse_docx(docx_path, options)
       doc = Docx::Document.open(docx_path)
 
       # Extract metadata from the first table
@@ -17,41 +49,13 @@ module Commenter
       raise "No comments table found in document" unless comments_table
       raise "Comments table appears to be empty" if comments_table.row_count < 2
 
-      comments = []
-
       # Process all rows - don't skip any rows, respect all content
-      (0..comments_table.row_count - 1).each do |i|
-        row = comments_table.rows[i]
-        cells = row.cells.map { |c| c.text.strip }
-
-        # Skip only completely empty rows
+      comments = (0..comments_table.row_count - 1).map do |row_index|
+        cells = comments_table.rows[row_index].cells.map { |cell| cell.text.strip }
         next if cells.all?(&:empty?)
 
-        # Extract body from ID (e.g., "DE-001" -> "DE")
-        id = cells[0] || ""
-        body = id.include?("-") ? id.split("-").first : id
-
-        # Create comment with symbol keys, respecting all input data
-        comment_attrs = {
-          id: id,
-          body: body,
-          locality: {
-            line_number: cells[1] && cells[1].empty? ? nil : cells[1],
-            clause: cells[2] && cells[2].empty? ? nil : cells[2],
-            element: cells[3] && cells[3].empty? ? nil : cells[3]
-          },
-          type: cells[4] || "",
-          comments: cells[5] || "",
-          proposed_change: cells[6] || ""
-        }
-
-        # Handle observations column
-        unless options[:exclude_observations]
-          comment_attrs[:observations] = cells[7] && cells[7].empty? ? nil : cells[7]
-        end
-
-        comments << Comment.new(comment_attrs)
-      end
+        osd_docx_row?(cells) ? build_osd_docx_comment(cells, options) : build_classic_docx_comment(cells, options)
+      end.compact
 
       # Create comment sheet
       CommentSheet.new(
@@ -63,7 +67,64 @@ module Commenter
       )
     end
 
-    private
+    # The DOCX from ISO OSD has 9 columns:
+    # 0: User name, 1: (empty/line), 2: Clause nb, 3: Clause Title,
+    # 4: Type, 5: Comment, 6: (empty/proposal), 7: Observations, 8: Comment number
+    # Detected by checking if last column looks like a numeric ID.
+    def osd_docx_row?(cells)
+      cells.length >= 9 && cells[8].to_s.match?(/^\d+$/)
+    end
+
+    def build_osd_docx_comment(cells, options)
+      attrs = {
+        id: cells[8],
+        body: cells[0].to_s.strip,
+        locality: {
+          clause: presence(cells[2]),
+          element: presence(cells[3])
+        },
+        type: normalize_type(cells[4]),
+        comments: cells[5] || "",
+        proposed_change: presence(cells[6]),
+        user_name: cells[0].to_s.strip
+      }
+      attrs[:observations] = presence(cells[7]) unless options[:exclude_observations]
+      Comment.new(attrs)
+    end
+
+    # Classic ISO comment template format (8 columns):
+    # 0: ID, 1: line_number, 2: clause, 3: element, 4: type, 5: comments,
+    # 6: proposed_change, 7: observations
+    def build_classic_docx_comment(cells, options)
+      id = cells[0] || ""
+      attrs = {
+        id: id,
+        body: id.include?("-") ? id.split("-").first : id,
+        locality: {
+          line_number: presence(cells[1]),
+          clause: presence(cells[2]),
+          element: presence(cells[3])
+        },
+        type: cells[4] || "",
+        comments: cells[5] || "",
+        proposed_change: cells[6] || ""
+      }
+      attrs[:observations] = presence(cells[7]) unless options[:exclude_observations]
+      Comment.new(attrs)
+    end
+
+    def presence(value)
+      value && !value.empty? ? value : nil
+    end
+
+    def normalize_type(type_str)
+      case type_str.to_s.strip.downcase
+      when "editorial" then "ed"
+      when "technical" then "te"
+      when "general" then "ge"
+      else type_str.to_s.strip
+      end
+    end
 
     def extract_metadata(doc)
       metadata = { date: nil, document: nil, project: nil }
@@ -96,9 +157,6 @@ module Commenter
       project_match = all_text.match(/Project:\s*([^\n\r]+)/)
       metadata[:project] = project_match[1]&.strip if project_match
 
-      # If no metadata found, try to extract from filename or other sources
-      # This is a fallback - in practice, users might need to provide metadata manually
-
       metadata
     end
   end

data/lib/commenter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Commenter
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/schema/iso_comment_2012-03.yaml

@@ -68,8 +68,8 @@ properties:
           required: ["clause"]
         type:
           type: string
-          enum: ["ge", "te", "ed"]
-          description: "Type of comment: ge=general, te=technical, ed=editorial"
+          enum: ["ge", "te", "ed", "general", "technical", "editorial"]
+          description: "Type of comment: ge=general, te=technical, ed=editorial. Codes are expanded to full names in output"
         comments:
           type: string
           description: "The actual comment text"

data/schema/iso_comment_osd.yaml

@@ -0,0 +1,112 @@
+# ISO Comment Schema for ISO Online Standards Development (OSD) format
+# Supports both resolved and unresolved XLSX exports from ISO OSD
+$schema: http://json-schema.org/draft-07/schema#
+title: ISO Comment OSD
+description: Schema for ISO comments exported from ISO Online Standards Development (OSD) platform
+type: object
+properties:
+  version:
+    type: string
+    const: "osd"
+    description: Version identifier for OSD format
+  date:
+    type: ["string", "null"]
+    description: Date from the XLSX header
+    format: date
+  document:
+    type: ["string", "null"]
+    description: Document reference (e.g. ISO/DIS 5843-6(en))
+  project:
+    type: ["string", "null"]
+    description: Project name
+  title_en:
+    type: ["string", "null"]
+    description: Document title in English
+  title_fr:
+    type: ["string", "null"]
+    description: Document title in French
+  stage:
+    type: ["string", "null"]
+    description: Approval stage (WD/CD/DIS/FDIS/PRF/PUB)
+    enum: [null, "WD", "CD", "DIS", "FDIS", "PRF", "PUB"]
+  comments:
+    type: array
+    description: Array of comment entries from the ISO OSD export
+    items:
+      type: object
+      properties:
+        id:
+          type: ["string", "number"]
+          description: "Comment ID (numeric from OSD)"
+        body:
+          type: ["string", "null"]
+          description: "Member body or user name"
+        locality:
+          type: object
+          description: "Location information for the comment"
+          properties:
+            line_number:
+              type: ["string", "null"]
+            clause:
+              type: ["string", "null"]
+            element:
+              type: ["string", "null"]
+              description: "Clause Title from OSD"
+        type:
+          type: ["string", "null"]
+          description: "Type of comment; codes (ge/te/ed) are expanded to general/technical/editorial in output"
+          enum: [null, "ge", "te", "ed", "general", "technical", "editorial"]
+        comments:
+          type: ["string", "null"]
+          description: "The comment text"
+        proposed_change:
+          type: ["string", "null"]
+          description: "Proposed change text"
+        observations:
+          type: ["string", "null"]
+          description: "Resolution status or observations"
+        user_name:
+          type: ["string", "null"]
+          description: "User name from OSD"
+        comment_type:
+          type: ["string", "null"]
+          description: "Comment type/subtype from OSD (e.g. Editorial, General, Technical)"
+        resolution_status:
+          type: ["string", "null"]
+          description: "Resolution status (Accepted, Partially accepted, Rejected, etc.)"
+        resolution_date:
+          type: ["string", "null"]
+          description: "Date when the comment was resolved"
+        feedbacks:
+          type: ["string", "null"]
+          description: "Feedback/replies from the discussion"
+        motivation:
+          type: ["string", "null"]
+          description: "Motivation/justification for resolution"
+        created_date:
+          type: ["string", "null"]
+          description: "Date when the comment was created"
+        stage_code:
+          type: ["string", "null"]
+          description: "ISO stage code (e.g. 40.20)"
+        github:
+          type: ["object", "null"]
+          description: "GitHub integration information"
+          properties:
+            issue_number:
+              type: integer
+            issue_url:
+              type: string
+              format: uri
+            status:
+              type: string
+              enum: ["open", "closed"]
+            created_at:
+              type: string
+              format: date-time
+            updated_at:
+              type: string
+              format: date-time
+          required: ["issue_number", "issue_url", "status"]
+      required: ["id", "locality", "comments"]
+required: ["version", "comments"]

data/spec/commenter/cli_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "commenter/cli"
+require_relative "../support/osd_fixtures"
+require_relative "../support/xlsx_builder"
+
+RSpec.describe Commenter::Cli do
+  include OsdFixtures
+
+  describe "#import" do
+    it "writes OSD YAML and copies the OSD schema for XLSX input" do
+      Dir.mktmpdir do |dir|
+        xlsx = File.join(dir, "comments.xlsx")
+        rows = header_block(OsdFixtures::RESOLVED_HEADERS) + [
+          [1, "John Doe", "5.2.1", "Requirements", "Comment", "Editorial",
+           "The values in Table 3 are inconsistent.", nil, "Correct the values.", nil, nil, nil,
+           "2026-04-01", "Accepted", nil, "2026-04-10", "40.20"]
+        ]
+        XlsxBuilder.write(xlsx, [["Comments (1)", rows]])
+        output = File.join(dir, "out", "comments.yaml")
+        schema_dir = File.join(dir, "out", "schema")
+
+        described_class.start(["import", xlsx, "--output", output, "--schema-dir", schema_dir])
+
+        data = YAML.safe_load_file(output)
+        expect(data["version"]).to eq("osd")
+        expect(data["comments"].length).to eq(1)
+        expect(data["comments"].first["id"]).to eq("1")
+        expect(File.read(output)).to start_with("# yaml-language-server: $schema=")
+        expect(File).to exist(File.join(schema_dir, "iso_comment_osd.yaml"))
+      end
+    end
+  end
+end

data/spec/commenter/comment_spec.rb

@@ -22,7 +22,7 @@ RSpec.describe Commenter::Comment do
       expect(comment.clause).to eq("5.1")
       expect(comment.element).to eq("Table 1")
       expect(comment.line_number).to eq("42")
-      expect(comment.type).to eq("te")
+      expect(comment.type).to eq("technical")
       expect(comment.comments).to eq("Test comment")
       expect(comment.proposed_change).to eq("Test change")
       expect(comment.observations).to eq("Test observations")
@@ -173,7 +173,7 @@ RSpec.describe Commenter::Comment do
       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("te")
+      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")

data/spec/commenter/github_integration_spec.rb

@@ -120,7 +120,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
         expect(result[:title]).to eq("US-001: Clause 5.1, Table 1: Test comment text")
         expect(result[:body]).to include("Comment: Test comment text")
         expect(result[:body]).to include("Type: Technical")
-        expect(result[:labels]).to include("comment-review", "draft-international-standard", "te")
+        expect(result[:labels]).to include("comment-review", "draft-international-standard", "technical")
         expect(result[:assignees]).to eq(["test-assignee"])
       end
     end
@@ -144,7 +144,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
       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("te")
+      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")
@@ -164,7 +164,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
 
       expect(labels).to include("comment-review") # default
       expect(labels).to include("draft-international-standard") # stage-specific
-      expect(labels).to include("te") # comment type
+      expect(labels).to include("technical") # comment type (expanded)
       expect(labels.uniq).to eq(labels) # no duplicates
     end
   end

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