commenter 0.3.1 → 0.5.0

data/lib/commenter/comment.rb

@@ -1,172 +1,157 @@
 # frozen_string_literal: true
 
+require "lutaml/model"
+
 module Commenter
-  class Comment
-    attr_accessor :id, :body, :locality, :type, :comments, :proposed_change, :observations, :github,
-                  :user_name, :comment_type, :resolution_status, :resolution_date, :feedbacks,
-                  :motivation, :created_date, :stage_code
-
-    def initialize(attributes = {})
-      # Normalize input to symbols
-      attrs = symbolize_keys(attributes)
-
-      @id = attrs[:id]
-      @body = attrs[:body]
-      @locality = symbolize_keys(attrs[:locality] || {})
-      @type = CommentType.full_name(attrs[:type])
-      @comments = attrs[:comments]
-      @proposed_change = attrs[:proposed_change]
-      @observations = attrs[:observations]
-      @github = symbolize_keys(attrs[:github] || {})
-
-      # OSD-specific fields
-      @user_name = attrs[:user_name]
-      @comment_type = attrs[:comment_type]
-      @resolution_status = attrs[:resolution_status]
-      @resolution_date = attrs[:resolution_date]
-      @feedbacks = attrs[:feedbacks]
-      @motivation = attrs[:motivation]
-      @created_date = attrs[:created_date]
-      @stage_code = attrs[:stage_code]
+  # A single comment on a reviewed document. (De)serialization is declared
+  # with lutaml-model; the only custom mapping logic is the type expansion
+  # (short codes to full names) and empty-observation omission, both at the
+  # YAML boundary.
+  class Comment < Lutaml::Model::Serializable
+    attribute :id, :string
+    attribute :body, :string
+    attribute :locality, CommentLocality
+    attribute :type, :string
+    attribute :comments, :string
+    attribute :proposed_change, :string
+    attribute :observations, :string
+
+    # OSD-specific fields
+    attribute :user_name, :string
+    attribute :comment_type, :string
+    attribute :resolution_status, :string
+    attribute :resolution_date, :string
+    attribute :feedbacks, :string
+    attribute :motivation, :string
+    attribute :created_date, :string
+    attribute :stage_code, :string
+
+    attribute :github, GithubInfo
+
+    yaml do
+      map "id", to: :id
+      map "body", to: :body
+      map "locality", to: :locality
+      map "type", with: { to: :type_to_yaml, from: :type_from_yaml }
+      map "comments", to: :comments
+      map "proposed_change", to: :proposed_change
+      map "observations", with: { to: :observations_to_yaml, from: :observations_from_yaml }
+      map "user_name", to: :user_name
+      map "comment_type", to: :comment_type
+      map "resolution_status", to: :resolution_status
+      map "resolution_date", to: :resolution_date
+      map "feedbacks", to: :feedbacks
+      map "motivation", to: :motivation
+      map "created_date", to: :created_date
+      map "stage_code", to: :stage_code
+      map "github", to: :github
+    end
+
+    def type_from_yaml(model, value)
+      model.type = CommentType.full_name(value)
+    end
+
+    def type_to_yaml(model, doc)
+      doc["type"] = model.type if model.type && !model.type.empty?
+    end
+
+    def observations_from_yaml(model, value)
+      model.observations = value.to_s.empty? ? nil : value
+    end
+
+    def observations_to_yaml(model, doc)
+      doc["observations"] = model.observations if model.observations && !model.observations.empty?
     end
 
     def expand_comment_type(type)
       CommentType.full_name(type)
     end
 
+    def to_h
+      Comment.to_hash(self)
+    end
+
+    alias to_yaml_h to_h
+
     def line_number
-      @locality[:line_number]
+      locality&.line_number
     end
 
     def line_number=(value)
-      @locality[:line_number] = value
+      self.locality = CommentLocality.new if locality.nil?
+      locality.line_number = value
     end
 
     def clause
-      @locality[:clause]
+      locality&.clause
     end
 
     def clause=(value)
-      @locality[:clause] = value
+      self.locality = CommentLocality.new if locality.nil?
+      locality.clause = value
     end
 
     def element
-      @locality[:element]
+      locality&.element
     end
 
     def element=(value)
-      @locality[:element] = value
+      self.locality = CommentLocality.new if locality.nil?
+      locality.element = value
     end
 
-    def brief_summary(max_length = 80)
-      parts = []
-
-      # Add locality information first
-      parts << "Clause #{clause}" if clause && !clause.strip.empty?
-      parts << element if element && !element.strip.empty?
-      parts << "Line #{line_number}" if line_number && !line_number.strip.empty?
+    def brief_summary(max_length = 60)
+      description = comments.to_s.split(/[.!?\n]/).map(&:strip).reject(&:empty?).first.to_s
+      locality_text = format_locality
 
-      locality_text = parts.join(", ")
-
-      # Add description from comment text
-      if @comments && !@comments.strip.empty?
-        # Extract first sentence or truncate
-        clean_text = @comments.strip.gsub(/\s+/, " ")
-        first_sentence = clean_text.split(/[.!?]/).first&.strip
-        description = if first_sentence && first_sentence.length < max_length
-                        first_sentence
-                      else
-                        clean_text[0...50]
-                      end
-
-        if locality_text.empty?
-          description
-        else
-          # Combine locality + description, respecting max_length
-          combined = "#{locality_text}: #{description}"
-          combined.length <= max_length ? combined : "#{locality_text}: #{description[0...(max_length - locality_text.length - 2)]}"
-        end
-      else
+      if description.empty?
         locality_text.empty? ? "No description" : locality_text
+      elsif locality_text.empty?
+        combined = description
+        combined.length <= max_length ? combined : "#{combined[0...(max_length - 3)]}..."
+      else
+        combined = "#{locality_text}: #{description}"
+        combined.length <= max_length ? combined : "#{locality_text}: #{description[0...(max_length - locality_text.length - 2)]}"
       end
     end
 
     def github_issue_number
-      @github[:issue_number]
+      github&.issue_number
     end
 
     def github_issue_url
-      @github[:issue_url]
+      github&.issue_url
     end
 
     def github_status
-      @github[:status]
+      github&.status
     end
 
     def github_created_at
-      @github[:created_at]
+      github&.created_at
     end
 
     def github_updated_at
-      @github[:updated_at]
+      github&.updated_at
     end
 
     def has_github_issue?
-      !@github[:issue_number].nil?
+      !github&.issue_number.nil?
     end
 
-    def to_h
-      {
-        id: @id,
-        body: @body,
-        locality: @locality,
-        type: @type,
-        comments: @comments,
-        proposed_change: @proposed_change,
-        observations: @observations,
-        user_name: @user_name,
-        comment_type: @comment_type,
-        resolution_status: @resolution_status,
-        resolution_date: @resolution_date,
-        feedbacks: @feedbacks,
-        motivation: @motivation,
-        created_date: @created_date,
-        stage_code: @stage_code,
-        github: @github.empty? ? nil : @github
-      }.compact
-    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)
+    def record_github_issue(issue_number:, issue_url:, status:, created_at: nil)
+      self.github = GithubInfo.new(issue_number: issue_number, issue_url: issue_url,
+                                   status: status, created_at: created_at)
     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
+    def format_locality
+      parts = []
+      parts << "Clause #{clause}" if clause && !clause.strip.empty?
+      parts << element if element && !element.strip.empty?
+      parts << "Line #{line_number}" if line_number && !line_number.strip.empty?
+      parts.join(", ")
     end
   end
 end

data/lib/commenter/comment_locality.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Commenter
+  # Location of a comment within the reviewed document.
+  class CommentLocality < Lutaml::Model::Serializable
+    attribute :line_number, :string
+    attribute :clause, :string
+    attribute :element, :string
+
+    yaml do
+      map "line_number", to: :line_number
+      map "clause", to: :clause
+      map "element", to: :element
+    end
+  end
+end

data/lib/commenter/comment_sheet.rb

@@ -1,48 +1,33 @@
 # frozen_string_literal: true
 
-require_relative "comment"
+require "lutaml/model"
 
 module Commenter
-  class CommentSheet
-    attr_accessor :version, :date, :document, :project, :stage, :comments, :title_en, :title_fr
-
-    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]
-      @stage = attrs[:stage]
-      @title_en = attrs[:title_en]
-      @title_fr = attrs[:title_fr]
-      @comments = (attrs[:comments] || []).map { |c| c.is_a?(Comment) ? c : Comment.from_hash(c) }
+  # One ballot submission: metadata plus its comments. Serialization is
+  # declared with lutaml-model.
+  class CommentSheet < Lutaml::Model::Serializable
+    attribute :version, :string, default: -> { "2012-03" }
+    attribute :date, :string
+    attribute :document, :string
+    attribute :project, :string
+    attribute :stage, :string
+    attribute :title_en, :string
+    attribute :title_fr, :string
+    attribute :comments, Comment, collection: true
+
+    yaml do
+      map "version", to: :version
+      map "date", to: :date
+      map "document", to: :document
+      map "project", to: :project
+      map "stage", to: :stage
+      map "title_en", to: :title_en
+      map "title_fr", to: :title_fr
+      map "comments", to: :comments
     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,
-        stage: @stage,
-        title_en: @title_en,
-        title_fr: @title_fr,
-        comments: @comments.map(&:to_h)
-      }
-    end
-
-    def to_yaml_h
-      hash = to_h.merge(comments: @comments.map(&:to_yaml_h))
-      # Remove nil-valued keys for cleaner YAML output
-      hash.delete(:title_en) if hash[:title_en].nil?
-      hash.delete(:title_fr) if hash[:title_fr].nil?
-      stringify_keys(hash)
+      self.comments = (comments || []) + [comment.is_a?(Comment) ? comment : Comment.from_hash(comment)]
     end
 
     def schema_name
@@ -50,40 +35,15 @@ module Commenter
     end
 
     def to_yaml_document(schema_dir = "schema")
-      "# yaml-language-server: $schema=#{File.join(schema_dir.to_s, schema_name)}\n\n#{to_yaml_h.to_yaml}"
+      "# yaml-language-server: $schema=#{File.join(schema_dir.to_s, schema_name)}\n\n#{to_yaml}"
     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
+    def to_yaml_h
+      CommentSheet.to_hash(self)
     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
+    def to_h
+      CommentSheet.to_hash(self)
     end
   end
 end

data/lib/commenter/comment_type.rb

@@ -25,7 +25,11 @@ module Commenter
     end
 
     def full_name(type)
-      FULL_NAMES.fetch(type.to_s.strip.downcase) { type&.to_s&.strip }
+      return nil if type.nil?
+
+      value = type.to_s.strip
+      downcased = value.downcase
+      FULL_NAMES[downcased] || (FULL_NAMES.values.include?(downcased) ? downcased : value)
     end
 
     def display_name(type)

data/lib/commenter/disposition_status.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Canonical disposition vocabulary, shared by cell shading (Filler) and
+  # ballot statistics (BallotReport). Matches free-text observations and
+  # OSD's structured resolution_status values. One home for the question
+  # "what counts as an accepted disposition".
+  module DispositionStatus
+    PATTERNS = [
+      [:accept_with_modifications, /awm|accept(ed)?[ ,]*with +(modifications|changes)/].freeze,
+      [:rejected, /reject(ed)?|not accepted/].freeze,
+      [:accepted, /accept(ed)?/].freeze,
+      [:noted, /noted/].freeze,
+      [:todo, /todo/].freeze
+    ].freeze
+
+    module_function
+
+    # Returns the canonical status symbol for the given text, or nil when
+    # nothing matches. Order matters: "accept with modifications" and
+    # "not accepted" must be classified before the bare "accept" pattern.
+    def match(text)
+      value = text.to_s.downcase.strip
+      return nil if value.empty?
+
+      PATTERNS.each do |status, pattern|
+        return status if value.match?(pattern)
+      end
+
+      nil
+    end
+
+    def statuses
+      PATTERNS.map(&:first)
+    end
+  end
+end

data/lib/commenter/filler.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
 require "docx"
+require "zip"
 
 module Commenter
   class Filler
+    # Labels of the sheet metadata fields in the template's page header
+    # (word/header*.xml). Values supplied to #fill are appended after each
+    # label; the docx gem cannot write header parts (see docx PR #73), so
+    # this is done by rewriting the entry directly.
+    HEADER_METADATA = { date: "Date", document: "Document", project: "Project" }.freeze
+
     def fill(template_path, output_path, comments, options = {})
       doc = Docx::Document.open(template_path)
       table = doc.tables.first
@@ -11,48 +18,88 @@ module Commenter
       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 StandardError => e
-          puts "Warning: Could not add row for comment #{comment_data[:id]}: #{e.message}"
-          next
-        end
+      # The template row (first row in the table) is copied for each comment;
+      # all original template rows are removed afterwards via their XML
+      # nodes (the shipped 2012-03 template carries extra blank rows beyond
+      # the first, and the docx gem's Row exposes no #remove).
+      template_rows = table.rows.to_a
+      comments.each { |comment| fill_row(template_rows.first, comment, options) }
+      template_rows.each { |row| row.node.remove }
+
+      doc.save(output_path)
+      write_header_metadata(output_path, options)
+      output_path
+    end
+
+    private
+
+    def fill_row(template_row, comment, options)
+      comment = Comment.from_hash(comment) unless comment.is_a?(Comment)
+
+      new_row = template_row.copy
+      new_row.insert_before(template_row)
+
+      set_cell_text(new_row.cells[0], comment.id.to_s)
+      set_cell_text(new_row.cells[1], comment.line_number.to_s)
+      set_cell_text(new_row.cells[2], comment.clause.to_s)
+      set_cell_text(new_row.cells[3], comment.element.to_s)
+      set_cell_text(new_row.cells[4], comment.type.to_s)
+      set_cell_text(new_row.cells[5], comment.comments.to_s)
+      set_cell_text(new_row.cells[6], comment.proposed_change.to_s)
+
+      observations = comment.observations.to_s
+      return if observations.empty?
+
+      set_cell_text(new_row.cells[7], observations)
+      apply_shading(new_row.cells[7], observations) if options[:shading]
+    rescue StandardError => e
+      puts "Warning: Could not add row for comment #{comment.id}: #{e.message}"
+    end
+
+    def write_header_metadata(output_path, options)
+      metadata = HEADER_METADATA.map do |key, label|
+        value = options[key].to_s.strip
+        value.empty? ? nil : [label, value]
+      end.compact
+      return if metadata.empty?
 
-        # 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]
+      rewrite_headers(output_path, metadata)
+    end
+
+    def rewrite_headers(output_path, metadata)
+      # In-memory buffer + File.binwrite rather than rewriting the archive
+      # in place: rubyzip commits in-place edits with File.rename, which
+      # fails with EACCES on Windows.
+      buffer = Zip::OutputStream.write_buffer do |out|
+        Zip::File.open(output_path) do |zip|
+          zip.entries.each do |entry|
+            # Block form: the entry stream is closed eagerly, otherwise its
+            # handle keeps the file locked on Windows and the binwrite below
+            # fails with EACCES.
+            content = entry.get_input_stream(&:read)
+            out.put_next_entry(entry.name)
+            out.write(patch_header(entry.name, content, metadata))
+          end
         end
       end
+      File.binwrite(output_path, buffer.string)
+    end
 
-      # Remove the original template row after all comments are added
-      template_row.remove if template_row.respond_to?(:remove)
+    def patch_header(entry_name, content, metadata)
+      return content unless entry_name.match?(%r{\Aword/header\d*\.xml\z})
 
-      doc.save(output_path)
+      xml = content.dup.force_encoding(Encoding::UTF_8)
+      metadata.each do |label, value|
+        xml.sub!(%r{(<w:t[^>]*>)\s*#{label}:\s*(</w:t>)}) do
+          "#{Regexp.last_match(1)}#{label}: #{escape(value)}#{Regexp.last_match(2)}"
+        end
+      end
+      xml
     end
 
-    private
+    def escape(text)
+      text.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+    end
 
     def set_cell_text(cell, text)
       return if text.nil? || text.empty?
@@ -86,14 +133,16 @@ module Commenter
       puts "Warning: Could not set text '#{text}' in cell: #{e.message}"
     end
 
-    def symbolize_keys(hash)
-      return hash unless hash.is_a?(Hash)
+    SHADING_COLORS = {
+      accept_with_modifications: "C4D79B", # Olive Green
+      accepted: "92D050", # Green
+      noted: "8DB4E2", # Blue
+      rejected: "FF99CC", # Pink
+      todo: "D9D9D9" # Light Gray (for diagonal stripes, we use solid for now)
+    }.freeze
 
-      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
+    def determine_shading_color(observation)
+      SHADING_COLORS[DispositionStatus.match(observation)]
     end
 
     def apply_shading(cell, observation)
@@ -111,23 +160,6 @@ module Commenter
       puts "Warning: Could not apply shading to cell: #{e.message}"
     end
 
-    def determine_shading_color(observation)
-      text = observation.downcase.strip
-
-      case text
-      when /awm|accept with modifications/
-        "C4D79B"  # Olive Green
-      when /accept(ed)?/
-        "92D050"  # Green
-      when /noted/
-        "8DB4E2"  # Blue
-      when /reject(ed)?/
-        "FF99CC"  # Pink
-      when /todo/
-        "D9D9D9"  # Light Gray (for diagonal stripes, we'll use solid for now)
-      end
-    end
-
     def apply_cell_shading(cell, color)
       # Access the cell's XML node
       cell_node = cell.node

data/lib/commenter/github_info.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Commenter
+  # GitHub issue tracking state attached to a comment by github-create /
+  # github-retrieve.
+  class GithubInfo < Lutaml::Model::Serializable
+    attribute :issue_number, :integer
+    attribute :issue_url, :string
+    attribute :status, :string
+    attribute :created_at, :string
+    attribute :updated_at, :string
+
+    yaml do
+      map "issue_number", to: :issue_number
+      map "issue_url", to: :issue_url
+      map "status", to: :status
+      map "created_at", to: :created_at
+      map "updated_at", to: :updated_at
+    end
+  end
+end