commenter 0.2.3 → 0.3.0

data/lib/commenter/parser/osd_xlsx_parser.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "roo"
+require_relative "../comment_sheet"
+require_relative "../comment"
+
+module Commenter
+  class Parser
+    # Parser for ISO Online Standards Development (OSD) XLSX exports.
+    #
+    # Supports two variants, detected from the header row:
+    #   - "resolved": single "Comments (N)" sheet with resolution data
+    #     (columns: Comment ID, User name, Clause nb, ..., Resolution status,
+    #     Motivation, Resolution Date, Stage code)
+    #   - "unresolved": multi-sheet format with "Comments (N)",
+    #     "Unresolved comments (N)", "Resolved comments (N)" sheets
+    #     (columns: User name, Clause nb, ..., Comment type, Comment/Motivation,
+    #     Comment on text, Proposal on Text, Proposed change, Replies,
+    #     Resolution status, Justification, Resolution Date, Date, Comment number)
+    #
+    # Both variants share the same header structure in the first rows:
+    #   Row 0: [Date, Reference, nil, "", Title EN, nil, nil, Title FR, ...]
+    #   Row 1: ["2026-04-21", "ISO/DIS 5843-6(en)", ...]
+    #   Row 2: empty
+    #   Row 3: column headers
+    #   Row 4+: data
+    class OsdXlsxParser
+      # Header names are mapped per variant onto common attribute keys so both
+      # variants share a single comment builder. Headers are mapped by real
+      # column position, tolerating gaps in the header row.
+      RESOLVED_COLUMN_KEYS = {
+        "Comment ID" => :id,
+        "User name" => :user_name,
+        "Clause nb" => :clause,
+        "Clause Title" => :clause_title,
+        "Subtype" => :comment_type,
+        "Comment" => :comment_text,
+        "Proposal on Text" => :proposal_on_text,
+        "Proposed change" => :proposed_change,
+        "Feedbacks" => :feedbacks,
+        "Created Date" => :created_date,
+        "Resolution status" => :resolution_status,
+        "Motivation" => :motivation,
+        "Resolution Date" => :resolution_date,
+        "Stage code" => :stage_code
+      }.freeze
+
+      UNRESOLVED_COLUMN_KEYS = {
+        "User name" => :user_name,
+        "Clause nb" => :clause,
+        "Clause Title" => :clause_title,
+        "Comment type" => :comment_type,
+        "Comment/Motivation" => :comment_text,
+        "Proposal on Text" => :proposal_on_text,
+        "Proposed change" => :proposed_change,
+        "Replies" => :feedbacks,
+        "Resolution status" => :resolution_status,
+        "Justification" => :motivation,
+        "Resolution Date" => :resolution_date,
+        "Date" => :created_date,
+        "Comment number" => :id
+      }.freeze
+
+      def parse(xlsx_path, options = {})
+        xlsx = Roo::Spreadsheet.open(xlsx_path)
+
+        sheet_name = select_sheet(xlsx, options)
+        sheet = xlsx.sheet(sheet_name)
+        header_row_num = find_header_row(sheet)
+        variant = detect_variant(sheet.row(header_row_num))
+
+        comments = parse_comments(sheet, header_row_num, variant, options)
+        CommentSheet.new(version: "osd", **extract_metadata(xlsx, sheet_name), comments: comments)
+      end
+
+      private
+
+      def select_sheet(xlsx, options)
+        sheets = xlsx.sheets
+
+        if options[:sheet]
+          raise "Sheet '#{options[:sheet]}' not found. Available: #{sheets.join(", ")}" unless sheets.include?(options[:sheet])
+
+          return options[:sheet]
+        end
+
+        if options[:resolved_only]
+          sheets.find { |s| s.start_with?("Resolved") } || sheets.find { |s| s.start_with?("Comments") }
+        elsif options[:unresolved_only]
+          sheets.find { |s| s.start_with?("Unresolved") } || sheets.find { |s| s.start_with?("Comments") }
+        else
+          sheets.first # Default: first sheet (usually "Comments (N)" with all comments)
+        end
+      end
+
+      def find_header_row(sheet)
+        (1..10).each do |row_num|
+          headers = sheet.row(row_num).to_a.compact.map(&:to_s)
+          return row_num if headers.include?("User name") || headers.include?("Comment ID")
+        end
+
+        raise "Could not find header row in XLSX sheet"
+      end
+
+      def detect_variant(header_row)
+        headers = header_row.to_a.compact.map(&:to_s)
+        if headers.include?("Comment ID") || headers.include?("Subtype")
+          :resolved
+        elsif headers.include?("Comment/Motivation") || headers.include?("Comment type")
+          :unresolved
+        else
+          headers.length >= 15 ? :resolved : :unresolved
+        end
+      end
+
+      def extract_metadata(xlsx, sheet_name)
+        values = xlsx.sheet(sheet_name).row(2)
+        metadata = { date: nil, document: nil, project: nil, stage: nil, title_en: nil, title_fr: nil }
+        return metadata if values.nil?
+
+        metadata[:date] = header_value(values[0], "Date")
+
+        reference = header_value(values[1], "Reference")
+        if reference
+          metadata[:document] = reference
+          metadata[:stage] = extract_stage(reference)
+          metadata[:project] = extract_project(reference)
+        end
+
+        metadata[:title_en] = header_value(values[4], "Title EN")
+        metadata[:title_fr] = header_value(values[7], "Title FR")
+        metadata
+      end
+
+      def header_value(raw, label)
+        return nil if raw.nil?
+
+        value = raw.is_a?(Date) ? raw.strftime("%Y-%m-%d") : raw.to_s.strip
+        value.empty? || value == label ? nil : value
+      end
+
+      def extract_stage(reference)
+        case reference
+        when %r{/WD\b}i then "WD"
+        when %r{/CD\b}i then "CD"
+        when %r{/DIS\b}i then "DIS"
+        when %r{/FDIS\b}i then "FDIS"
+        end
+      end
+
+      def extract_project(reference)
+        # Extract ISO number from reference like "ISO/DIS 5843-6(en)"
+        match = reference.match(%r{(ISO[\s/]*\w*\s*\d+[\d-]*)})
+        match ? match[1].strip.gsub(/\s+/, " ") : nil
+      end
+
+      def parse_comments(sheet, header_row_num, variant, options)
+        column_keys = variant == :resolved ? RESOLVED_COLUMN_KEYS : UNRESOLVED_COLUMN_KEYS
+        col_map = build_column_map(sheet.row(header_row_num), column_keys)
+
+        comments = []
+        (header_row_num + 1..sheet.last_row).each do |row_num|
+          row = sheet.row(row_num)
+          next if row.nil? || row.to_a.compact.empty?
+
+          comment = build_comment(row, col_map, options)
+          comments << comment if comment
+        end
+        comments
+      end
+
+      def build_column_map(header_row, column_keys)
+        header_row.to_a.each_with_index.with_object({}) do |(header, index), map|
+          key = column_keys[header.to_s.strip]
+          map[key] = index if key
+        end
+      end
+
+      def build_comment(row, col_map, options)
+        id = cell_value(row, col_map[:id])
+        return nil if id.nil?
+
+        id_str = id.is_a?(Float) ? id.to_i.to_s : id.to_s
+        comment_text = cell_value(row, col_map[:comment_text]) || ""
+        return nil if comment_text.strip.empty? && id_str.empty?
+
+        attrs = base_attributes(row, col_map, id_str, comment_text)
+                .merge(resolution_attributes(row, col_map))
+        attrs[:observations] = resolution_observations(row, col_map) unless options[:exclude_observations]
+        Comment.new(attrs)
+      end
+
+      def base_attributes(row, col_map, id_str, comment_text)
+        user_name = cell_value_str(row, col_map[:user_name]).to_s
+        clause = cell_value_str(row, col_map[:clause]).to_s
+        clause_title = cell_value_str(row, col_map[:clause_title]).to_s
+        {
+          id: id_str,
+          body: user_name,
+          locality: {
+            clause: clause.empty? ? nil : clause,
+            element: clause_title.empty? ? nil : clause_title
+          }.compact,
+          type: normalize_comment_type(cell_value_str(row, col_map[:comment_type]).to_s),
+          comments: comment_text.to_s.strip,
+          proposed_change: cell_value_str(row, col_map[:proposed_change]) ||
+            cell_value_str(row, col_map[:proposal_on_text])
+        }
+      end
+
+      def resolution_attributes(row, col_map)
+        {
+          user_name: cell_value_str(row, col_map[:user_name]).to_s,
+          comment_type: cell_value_str(row, col_map[:comment_type]).to_s,
+          resolution_status: cell_value_str(row, col_map[:resolution_status]),
+          resolution_date: cell_value_str(row, col_map[:resolution_date]),
+          feedbacks: cell_value_str(row, col_map[:feedbacks]),
+          motivation: cell_value_str(row, col_map[:motivation]),
+          created_date: cell_value_str(row, col_map[:created_date]),
+          stage_code: cell_value_str(row, col_map[:stage_code])
+        }
+      end
+
+      def resolution_observations(row, col_map)
+        parts = [cell_value_str(row, col_map[:resolution_status]),
+                 cell_value_str(row, col_map[:motivation])].compact
+        parts.empty? ? nil : parts.join(". ")
+      end
+
+      def normalize_comment_type(type_str)
+        case type_str.strip.downcase
+        when "editorial", "ed" then "ed"
+        when "technical", "te" then "te"
+        when "general", "ge" then "ge"
+        else type_str.strip
+        end
+      end
+
+      def cell_value(row, index)
+        return nil if index.nil? || row.length <= index
+
+        value = row[index]
+        value.is_a?(String) && value.strip.empty? ? nil : value
+      end
+
+      def cell_value_str(row, index)
+        value = cell_value(row, index)
+        value.nil? || value.to_s.strip.empty? ? nil : value.to_s.strip
+      end
+    end
+  end
+end

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.3"
+  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