commenter 0.3.1 → 0.4.0

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

data/lib/commenter/github_integration.rb

@@ -19,8 +19,7 @@ module Commenter
     end
 
     def create_issues_from_yaml(yaml_file, options = {})
-      data = YAML.load_file(yaml_file)
-      comment_sheet = CommentSheet.from_hash(data)
+      comment_sheet = CommentSheet.from_yaml(File.read(yaml_file))
 
       # Override stage if provided
       comment_sheet.stage = options[:stage] if options[:stage]
@@ -282,11 +281,8 @@ module Commenter
         comment = comment_sheet.comments.find { |c| c.id == result[:comment_id] }
         next unless comment
 
-        # Add GitHub information to the comment
-        comment.github[:issue_number] = result[:issue_number]
-        comment.github[:issue_url] = result[:issue_url]
-        comment.github[:status] = "open"
-        comment.github[:created_at] = Time.now.utc.iso8601
+        comment.record_github_issue(issue_number: result[:issue_number], issue_url: result[:issue_url],
+                                    status: "open", created_at: Time.now.utc.iso8601)
       end
 
       # Write updated YAML
@@ -304,8 +300,7 @@ module Commenter
     end
 
     def retrieve_observations_from_yaml(yaml_file, options = {})
-      data = YAML.load_file(yaml_file)
-      comment_sheet = CommentSheet.from_hash(data)
+      comment_sheet = CommentSheet.from_yaml(File.read(yaml_file))
 
       results = []
       comment_sheet.comments.each do |comment|
@@ -349,8 +344,8 @@ module Commenter
         if observation
           # Update comment with observation and current status
           comment.observations = observation
-          comment.github[:status] = issue.state
-          comment.github[:updated_at] = Time.now.utc.iso8601
+          comment.github.status = issue.state
+          comment.github.updated_at = Time.now.utc.iso8601
 
           {
             comment_id: comment.id,

data/lib/commenter/parser/osd_xlsx_parser.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "roo"
-require_relative "../comment_sheet"
-require_relative "../comment"
 
 module Commenter
   class Parser
@@ -201,7 +199,7 @@ module Commenter
             clause: clause.empty? ? nil : clause,
             element: clause_title.empty? ? nil : clause_title
           }.compact,
-          type: CommentType.code(cell_value_str(row, col_map[:comment_type]).to_s),
+          type: CommentType.full_name(cell_value_str(row, col_map[:comment_type])),
           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])

data/lib/commenter/parser/track_change_docx_parser.rb

@@ -2,8 +2,6 @@
 
 require "zip"
 require "nokogiri"
-require_relative "../comment"
-require_relative "../comment_sheet"
 
 module Commenter
   class Parser
@@ -54,7 +52,7 @@ module Commenter
           raise Commenter::Error, "word/document.xml not found in #{path}" unless entry
 
           remarks = read_remarks(zip)
-          changes = stream_changes(entry.get_input_stream, anchors)
+          changes = entry.get_input_stream { |stream| stream_changes(stream, anchors) }
         end
 
         CommentSheet.new(
@@ -80,7 +78,7 @@ module Commenter
         entry = zip.glob("word/comments.xml").first
         return {} unless entry
 
-        document = Nokogiri::XML(entry.get_input_stream)
+        document = entry.get_input_stream { |stream| Nokogiri::XML(stream) }
         document.xpath("//w:comment", "w" => W_NS).each_with_object({}) do |node, remarks|
           remarks[node["w:id"]] = {
             author: node["w:author"],
@@ -102,7 +100,7 @@ module Commenter
             id: format("%<body>s-%03<index>d", body: body, index: index + 1),
             body: body,
             locality: { clause: change[:clause], line_number: nil, element: change[:element] },
-            type: options[:type] || "te",
+            type: CommentType.full_name(options[:type] || "te"),
             comments: "Track change (#{KIND_COMMENT.fetch(kind, kind)})",
             proposed_change: "#{KIND_LABEL.fetch(kind, kind)}: \"#{change[:text].strip}\"",
             observations: observations_for(options)

data/lib/commenter/parser.rb

@@ -2,13 +2,12 @@
 
 require "docx"
 require "pathname"
-require_relative "comment_sheet"
-require_relative "comment"
-require_relative "parser/osd_xlsx_parser"
-require_relative "parser/track_change_docx_parser"
 
 module Commenter
   class Parser
+    autoload :OsdXlsxParser, "commenter/parser/osd_xlsx_parser"
+    autoload :TrackChangeDocxParser, "commenter/parser/track_change_docx_parser"
+
     def parse(input_path, options = {})
       format = detect_format(input_path, options)
 
@@ -90,7 +89,7 @@ module Commenter
           clause: presence(cells[2]),
           element: presence(cells[3])
         },
-        type: CommentType.code(cells[4]),
+        type: CommentType.full_name(cells[4]),
         comments: cells[5] || "",
         proposed_change: presence(cells[6]),
         user_name: cells[0].to_s.strip

data/lib/commenter/version.rb

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

data/lib/commenter.rb

@@ -1,11 +1,6 @@
 # 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"
-require_relative "commenter/github_integration"
 
 # Commenter converts ISO comment sheets (DOCX/XLSX) to structured YAML and
 # syncs comments to GitHub issues.
@@ -13,5 +8,16 @@ module Commenter
   class Error < StandardError; end
 
   autoload :CommentType, "commenter/comment_type"
+  autoload :CommentLocality, "commenter/comment_locality"
+  autoload :GithubInfo, "commenter/github_info"
+  autoload :DispositionStatus, "commenter/disposition_status"
+  autoload :Ballot, "commenter/ballot"
+  autoload :BallotReport, "commenter/ballot_report"
+  autoload :Comment, "commenter/comment"
+  autoload :CommentSheet, "commenter/comment_sheet"
   autoload :GitHubSession, "commenter/github_session"
+  autoload :Parser, "commenter/parser"
+  autoload :Filler, "commenter/filler"
+  autoload :GitHubIssueCreator, "commenter/github_integration"
+  autoload :GitHubIssueRetriever, "commenter/github_integration"
 end

data/spec/commenter/ballot_report_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Commenter::BallotReport do
+  def comment(body:, observations: nil, resolution_status: nil, github: {}, type: "technical")
+    Commenter::Comment.new(
+      id: "#{body}-1", body: body, type: type,
+      comments: "A comment", observations: observations,
+      resolution_status: resolution_status, github: github
+    )
+  end
+
+  let(:sheet) do
+    Commenter::CommentSheet.new(comments: [
+                                  comment(body: "DE", observations: "Accepted."),
+                                  comment(body: "DE", observations: "Accept with modifications"),
+                                  comment(body: "US", observations: "Noted"),
+                                  comment(body: "US", observations: "Rejected"),
+                                  comment(body: "US"),
+                                  comment(body: "CS", resolution_status: "Not accepted"),
+                                  comment(body: "CS", github: { status: "open" })
+                                ])
+  end
+
+  describe ".status_for" do
+    it "prefers observation text, then resolution status, then GitHub state" do
+      comments = sheet.comments
+      expect(described_class.status_for(comments[0])).to eq(:accepted)
+      expect(described_class.status_for(comments[4])).to eq(:undecided)
+      expect(described_class.status_for(comments[5])).to eq(:rejected)
+      expect(described_class.status_for(comments[6])).to eq(:open)
+    end
+  end
+
+  describe ".counts" do
+    it "counts per member body, disposition, and type" do
+      counts = described_class.counts(sheet)
+
+      expect(counts[:total]).to eq(7)
+      expect(counts[:bodies]["DE"][:total]).to eq(2)
+      expect(counts[:bodies]["DE"][:accepted]).to eq(1)
+      expect(counts[:bodies]["DE"][:accept_with_modifications]).to eq(1)
+      expect(counts[:bodies]["US"][:noted]).to eq(1)
+      expect(counts[:bodies]["US"][:rejected]).to eq(1)
+      expect(counts[:bodies]["US"][:undecided]).to eq(1)
+      expect(counts[:bodies]["CS"][:open]).to eq(1)
+      expect(counts[:types]["technical"]).to eq(7)
+    end
+  end
+
+  describe ".to_markdown" do
+    it "renders a ballot report table with totals" do
+      markdown = described_class.to_markdown(sheet)
+
+      expect(markdown).to start_with("| Body | Total | Accepted | AWM | Noted | Rejected | TODO | Open | Undecided |")
+      expect(markdown).to include("| DE | 2 | 1 | 1 | 0 | 0 | 0 | 0 | 0 |")
+      expect(markdown).to include("| **Total** | **7** | **1** | **1** | **1** | **2** | **0** | **1** | **1** |")
+      expect(markdown).to include("Comment types: technical 7")
+    end
+  end
+end