commenter 0.2.1

data/lib/commenter/cli.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "thor"
+require "yaml"
+require "fileutils"
+require "commenter/parser"
+require "commenter/filler"
+
+module Commenter
+  class CLI < Thor
+    desc "import INPUT.docx", "Convert DOCX comment sheet to YAML"
+    option :output, type: :string, aliases: :o, default: "comments.yaml", desc: "Output YAML file"
+    option :exclude_observations, type: :boolean, aliases: :e, desc: "Exclude observations column"
+    option :schema_dir, type: :string, default: "schema", desc: "Directory for schema file"
+    def import(input_docx)
+      output_yaml = options[:output]
+      schema_dir = options[:schema_dir]
+
+      # Ensure schema directory exists
+      FileUtils.mkdir_p(schema_dir) unless Dir.exist?(schema_dir)
+
+      # Parse the DOCX file
+      parser = Parser.new
+      comment_sheet = parser.parse(input_docx, options)
+
+      # Write the YAML data file with schema reference
+      yaml_content = generate_yaml_with_header(comment_sheet.to_yaml_h, schema_dir)
+      File.write(output_yaml, yaml_content)
+
+      # Copy schema file to output directory
+      schema_source = File.join(__dir__, "../../schema/iso_comment_2012-03.yaml")
+      schema_target = File.join(schema_dir, "iso_comment_2012-03.yaml")
+
+      # Only copy if source and target are different
+      unless File.expand_path(schema_source) == File.expand_path(schema_target)
+        FileUtils.cp(schema_source, schema_target)
+      end
+
+      puts "Converted #{input_docx} to #{output_yaml}"
+      puts "Schema file created at #{schema_target}"
+    end
+
+    desc "fill INPUT.yaml", "Fill DOCX template from YAML comments"
+    option :output, type: :string, aliases: :o, default: "filled_comments.docx", desc: "Output DOCX file"
+    option :template, type: :string, aliases: :t, desc: "Custom template file"
+    option :shading, type: :boolean, aliases: :s, desc: "Apply status-based shading"
+    def fill(input_yaml)
+      output_docx = options[:output]
+
+      # Load YAML data
+      data = YAML.load_file(input_yaml)
+
+      # Extract comments from the structure
+      comments = if data.is_a?(Hash)
+                   data["comments"] || data[:comments] || []
+                 else
+                   data || []
+                 end
+
+      raise "No comments found in YAML file" if comments.empty?
+
+      # Use default template if none specified
+      template_path = options[:template] || File.join(__dir__, "../../data/iso_comment_template_2012-03.docx")
+
+      # Fill the template
+      Filler.new.fill(template_path, output_docx, comments, options)
+      puts "Filled template to #{output_docx}"
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+
+    private
+
+    def generate_yaml_with_header(data, schema_dir)
+      schema_path = File.join(schema_dir, "iso_comment_2012-03.yaml")
+      header = "# yaml-language-server: $schema=#{schema_path}\n\n"
+      header + data.to_yaml
+    end
+  end
+end

data/lib/commenter/comment.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Commenter
+  class Comment
+    attr_accessor :id, :body, :locality, :type, :comments, :proposed_change, :observations
+
+    def initialize(attributes = {})
+      # Normalize input to symbols
+      attrs = symbolize_keys(attributes)
+
+      @id = attrs[:id]
+      @body = attrs[:body]
+      @locality = symbolize_keys(attrs[:locality] || {})
+      @type = attrs[:type]
+      @comments = attrs[:comments]
+      @proposed_change = attrs[:proposed_change]
+      @observations = attrs[:observations]
+    end
+
+    def line_number
+      @locality[:line_number]
+    end
+
+    def line_number=(value)
+      @locality[:line_number] = value
+    end
+
+    def clause
+      @locality[:clause]
+    end
+
+    def clause=(value)
+      @locality[:clause] = value
+    end
+
+    def element
+      @locality[:element]
+    end
+
+    def element=(value)
+      @locality[:element] = value
+    end
+
+    def to_h
+      {
+        id: @id,
+        body: @body,
+        locality: @locality,
+        type: @type,
+        comments: @comments,
+        proposed_change: @proposed_change,
+        observations: @observations
+      }
+    end
+
+    def to_yaml_h
+      hash = to_h
+      # Remove observations if it's nil or empty
+      hash.delete(:observations) if hash[:observations].nil? || hash[:observations] == ""
+      stringify_keys(hash)
+    end
+
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        new_key = key.to_sym
+        new_value = value.is_a?(Hash) ? symbolize_keys(value) : value
+        result[new_key] = new_value
+      end
+    end
+
+    def stringify_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        new_key = key.to_s
+        new_value = value.is_a?(Hash) ? stringify_keys(value) : value
+        result[new_key] = new_value
+      end
+    end
+  end
+end

data/lib/commenter/comment_sheet.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "comment"
+
+module Commenter
+  class CommentSheet
+    attr_accessor :version, :date, :document, :project, :comments
+
+    def initialize(attributes = {})
+      # Normalize input to symbols
+      attrs = symbolize_keys(attributes)
+
+      @version = attrs[:version] || "2012-03"
+      @date = attrs[:date]
+      @document = attrs[:document]
+      @project = attrs[:project]
+      @comments = (attrs[:comments] || []).map { |c| c.is_a?(Comment) ? c : Comment.from_hash(c) }
+    end
+
+    def add_comment(comment)
+      @comments << (comment.is_a?(Comment) ? comment : Comment.from_hash(comment))
+    end
+
+    def to_h
+      {
+        version: @version,
+        date: @date,
+        document: @document,
+        project: @project,
+        comments: @comments.map(&:to_h)
+      }
+    end
+
+    def to_yaml_h
+      stringify_keys(to_h.merge(comments: @comments.map(&:to_yaml_h)))
+    end
+
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        new_key = key.to_sym
+        new_value = value.is_a?(Hash) ? symbolize_keys(value) : value
+        result[new_key] = new_value
+      end
+    end
+
+    def stringify_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        new_key = key.to_s
+        new_value = case value
+                   when Hash
+                     stringify_keys(value)
+                   when Array
+                     value.map { |item| item.is_a?(Hash) ? stringify_keys(item) : item }
+                   else
+                     value
+                   end
+        result[new_key] = new_value
+      end
+    end
+  end
+end

data/lib/commenter/filler.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "docx"
+
+module Commenter
+  class Filler
+    def fill(template_path, output_path, comments, options = {})
+      doc = Docx::Document.open(template_path)
+      table = doc.tables.first
+
+      raise "No table found in template" unless table
+      raise "Template table must have at least one row" if table.row_count < 1
+
+      # Get the template row (first row in the table)
+      template_row = table.rows.first
+
+      # Add new rows for each comment by copying the template row
+      comments.each_with_index do |comment, index|
+        # Convert comment to symbol keys for consistent access
+        comment_data = symbolize_keys(comment)
+
+        # Copy the template row and insert it
+        begin
+          new_row = template_row.copy
+          new_row.insert_before(template_row)
+          row = new_row
+        rescue => e
+          puts "Warning: Could not add row for comment #{comment_data[:id]}: #{e.message}"
+          next
+        end
+
+        # Map comment to table cells using text substitution
+        set_cell_text(row.cells[0], comment_data[:id] || "")
+        set_cell_text(row.cells[1], comment_data.dig(:locality, :line_number) || "")
+        set_cell_text(row.cells[2], comment_data.dig(:locality, :clause) || "")
+        set_cell_text(row.cells[3], comment_data.dig(:locality, :element) || "")
+        set_cell_text(row.cells[4], comment_data[:type] || "")
+        set_cell_text(row.cells[5], comment_data[:comments] || "")
+        set_cell_text(row.cells[6], comment_data[:proposed_change] || "")
+
+        # Handle observations with optional shading
+        observations = comment_data[:observations]
+        if observations && !observations.empty?
+          set_cell_text(row.cells[7], observations)
+          apply_shading(row.cells[7], observations) if options[:shading]
+        end
+      end
+
+      # Remove the original template row after all comments are added
+      template_row.remove if template_row.respond_to?(:remove)
+
+      doc.save(output_path)
+    end
+
+    private
+
+    def set_cell_text(cell, text)
+      return if text.nil? || text.empty?
+
+      # Handle both empty cells and cells with existing text
+      text_set = false
+
+      cell.paragraphs.each do |paragraph|
+        paragraph.each_text_run do |text_run|
+          # Get current text and substitute it with new text
+          current_text = text_run.text
+          if current_text && !current_text.empty?
+            text_run.substitute(current_text, text)
+            text_set = true
+            return # Only substitute in the first text run found
+          end
+        end
+      end
+
+      # If no text runs with content were found, add text to the first paragraph
+      unless text_set
+        if cell.paragraphs.any?
+          paragraph = cell.paragraphs.first
+          # Try to add a text run to the paragraph
+          if paragraph.respond_to?(:add_text)
+            paragraph.add_text(text)
+          elsif paragraph.respond_to?(:text=)
+            paragraph.text = text
+          end
+        end
+      end
+    rescue => e
+      puts "Warning: Could not set text '#{text}' in cell: #{e.message}"
+    end
+
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        new_key = key.to_sym
+        new_value = value.is_a?(Hash) ? symbolize_keys(value) : value
+        result[new_key] = new_value
+      end
+    end
+
+    def apply_shading(cell, observation)
+      # Shading functionality is not fully supported by the docx gem
+      # This is a placeholder for future implementation
+      puts "Shading requested for: #{observation}" if observation
+    end
+  end
+end

data/lib/commenter/parser.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "docx"
+require_relative "comment_sheet"
+require_relative "comment"
+
+module Commenter
+  class Parser
+    def parse(docx_path, options = {})
+      doc = Docx::Document.open(docx_path)
+
+      # Extract metadata from the first table
+      metadata = extract_metadata(doc)
+
+      # The comments are in the second table (or first table if there's only one)
+      comments_table = doc.tables.length > 1 ? doc.tables[1] : doc.tables.first
+      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
+        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]&.empty? ? nil : cells[1],
+            clause: cells[2]&.empty? ? nil : cells[2],
+            element: 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]&.empty? ? nil : cells[7]
+        end
+
+        comments << Comment.new(comment_attrs)
+      end
+
+      # Create comment sheet
+      CommentSheet.new(
+        version: "2012-03",
+        date: metadata[:date],
+        document: metadata[:document],
+        project: metadata[:project],
+        comments: comments
+      )
+    end
+
+    private
+
+    def extract_metadata(doc)
+      metadata = { date: nil, document: nil, project: nil }
+
+      # Try to extract metadata from document properties first
+      begin
+        if doc.respond_to?(:created) && doc.created
+          metadata[:date] = doc.created.strftime("%Y-%m-%d") rescue nil
+        end
+      rescue => e
+        # Ignore errors accessing document properties
+      end
+
+      # Search for metadata in the document text
+      all_text = doc.to_s
+
+      # Look for date patterns
+      date_match = all_text.match(/Date:\s*([0-9]{4}-[0-9]{2}-[0-9]{2})/)
+      metadata[:date] = date_match[1] if date_match
+
+      # Look for document patterns
+      doc_match = all_text.match(/Document:\s*(ISO\s+[0-9\-:]+)/)
+      metadata[:document] = doc_match[1] if doc_match
+
+      # Look for project patterns
+      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
+end

data/lib/commenter/version.rb

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

data/lib/commenter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "commenter/version"
+require_relative "commenter/comment"
+require_relative "commenter/comment_sheet"
+require_relative "commenter/parser"
+require_relative "commenter/filler"
+
+module Commenter
+  class Error < StandardError; end
+end

data/schema/iso_comment_2012-03.yaml

@@ -0,0 +1,69 @@
+# ISO Comment Template 2012-03 Schema
+# Template: "ISO/IEC/CEN/CENELEC electronic balloting commenting template/version 2012-03"
+$schema: http://json-schema.org/draft-07/schema#
+title: ISO Comment 2012-03
+description: Schema for ISO comment sheets following the 2012-03 template format
+type: object
+properties:
+  version:
+    type: string
+    const: "2012-03"
+    description: Version of the ISO commenting template
+  comments:
+    type: array
+    description: Array of comment entries from the ISO comment sheet
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: "^[A-Z*]{2,3}-\\d{2,3}(-\\d{3})?$"
+          description: "Comment ID in format: {MB/NC}-{number} or {MB/NC}-{org_id}-{seq_id}"
+          examples:
+            - "US-001"
+            - "DE-01-002"
+            - "**-001"
+        body:
+          type: string
+          description: "Member body or National committee abbreviation (extracted from ID)"
+          examples:
+            - "US"
+            - "DE"
+            - "**"
+        locality:
+          type: object
+          description: "Location information for the comment"
+          properties:
+            line_number:
+              type: ["string", "null"]
+              description: "Line number reference"
+            clause:
+              type: string
+              description: "Clause/subclause reference"
+              examples:
+                - "_whole document"
+                - "5"
+                - "4.2.1"
+            element:
+              type: ["string", "null"]
+              description: "Paragraph/Figure/Table reference"
+              examples:
+                - "2-5.7, 4th column"
+                - "Table 1"
+                - "Figure 3"
+          required: ["clause"]
+        type:
+          type: string
+          enum: ["ge", "te", "ed"]
+          description: "Type of comment: ge=general, te=technical, ed=editorial"
+        comments:
+          type: string
+          description: "The actual comment text"
+        proposed_change:
+          type: string
+          description: "Proposed change or solution"
+        observations:
+          type: ["string", "null"]
+          description: "Observations of the Secretariat (optional)"
+      required: ["id", "body", "locality", "type", "comments", "proposed_change"]
+required: ["version", "comments"]

data/sig/commenter.rbs

@@ -0,0 +1,4 @@
+module Commenter
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/spec/commenter_spec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RSpec.describe Commenter do
+  it "has a version number" do
+    expect(Commenter::VERSION).not_to be nil
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "commenter"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: commenter
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Ribose
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Convert between ISO comment sheet DOCX and structured YAML with schema
+  validation.
+email:
+- open.source@ribose.com
+executables:
+- commenter
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/rake.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- README.adoc
+- Rakefile
+- commenter.gemspec
+- comments.yaml
+- data/iso_comment_template_2012-03.docx
+- exe/commenter
+- lib/commenter.rb
+- lib/commenter/cli.rb
+- lib/commenter/comment.rb
+- lib/commenter/comment_sheet.rb
+- lib/commenter/filler.rb
+- lib/commenter/parser.rb
+- lib/commenter/version.rb
+- schema/iso_comment_2012-03.yaml
+- sig/commenter.rbs
+- spec/commenter_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/metanorma/commenter
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/metanorma/commenter
+  source_code_uri: https://github.com/metanorma/commenter
+  bug_tracker_uri: https://github.com/metanorma/commenter/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Library to work with ISO comment sheets in DOCX format.
+test_files: []