commenter 0.3.0 → 0.4.0

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

@@ -8,11 +8,10 @@ require "dotenv/load"
 module Commenter
   class GitHubIssueCreator
     def initialize(config_path, title_template_path = nil, body_template_path = nil)
-      @config = load_config(config_path)
-      @github_client = create_github_client
-      @repo = @config.dig("github", "repository")
-
-      raise "GitHub repository not specified in config" unless @repo
+      @session = GitHubSession.new(config_path)
+      @config = @session.config
+      @github_client = @session.client
+      @repo = @session.repo
 
       @title_template = load_liquid_template(title_template_path || default_title_template_path)
       @body_template = load_liquid_template(body_template_path || default_body_template_path)
@@ -20,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]
@@ -43,19 +41,6 @@ module Commenter
 
     private
 
-    def load_config(config_path)
-      YAML.load_file(config_path)
-    rescue Errno::ENOENT
-      raise "Configuration file not found: #{config_path}"
-    end
-
-    def create_github_client
-      token = @config.dig("github", "token") || ENV["GITHUB_TOKEN"]
-      raise "GitHub token not found. Set GITHUB_TOKEN environment variable or specify in config file." unless token
-
-      Octokit::Client.new(access_token: token)
-    end
-
     def default_title_template_path
       File.join(__dir__, "../../data/github_issue_title_template.liquid")
     end
@@ -103,7 +88,7 @@ module Commenter
         "comment_id" => comment.id || "",
         "body" => comment.body || "",
         "type" => comment.type || "",
-        "type_full_name" => expand_comment_type(comment.type),
+        "type_full_name" => CommentType.display_name(comment.type),
         "comments" => comment.comments || "",
         "proposed_change" => comment.proposed_change || "",
         "observations" => comment.observations || "",
@@ -134,15 +119,6 @@ module Commenter
       @unique_id_template.render(base_variables).strip
     end
 
-    def expand_comment_type(type)
-      case type&.downcase
-      when "ge", "general" then "General"
-      when "te", "technical" then "Technical"
-      when "ed", "editorial" then "Editorial"
-      else type || "Unknown"
-      end
-    end
-
     def format_locality(comment)
       parts = []
       parts << "Clause #{comment.clause}" if comment.clause && !comment.clause.strip.empty?
@@ -305,37 +281,26 @@ 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
       output_file = options[:output] || yaml_file
-      yaml_content = generate_yaml_with_header(comment_sheet.to_yaml_h)
-      File.write(output_file, yaml_content)
-    end
-
-    def generate_yaml_with_header(data)
-      header = "# yaml-language-server: $schema=schema/iso_comment_2012-03.yaml\n\n"
-      header + data.to_yaml
+      File.write(output_file, comment_sheet.to_yaml_document)
     end
   end
 
   class GitHubIssueRetriever
     def initialize(config_path)
-      @config = load_config(config_path)
-      @github_client = create_github_client
-      @repo = @config.dig("github", "repository")
-
-      raise "GitHub repository not specified in config" unless @repo
+      @session = GitHubSession.new(config_path)
+      @config = @session.config
+      @github_client = @session.client
+      @repo = @session.repo
     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|
@@ -357,19 +322,6 @@ module Commenter
 
     private
 
-    def load_config(config_path)
-      YAML.load_file(config_path)
-    rescue Errno::ENOENT
-      raise "Configuration file not found: #{config_path}"
-    end
-
-    def create_github_client
-      token = @config.dig("github", "token") || ENV["GITHUB_TOKEN"]
-      raise "GitHub token not found. Set GITHUB_TOKEN environment variable or specify in config file." unless token
-
-      Octokit::Client.new(access_token: token)
-    end
-
     def retrieve_observation(comment, options)
       issue_number = comment.github_issue_number
 
@@ -392,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,
@@ -486,13 +438,7 @@ module Commenter
 
     def update_yaml_with_observations(yaml_file, comment_sheet, options)
       output_file = options[:output] || yaml_file
-      yaml_content = generate_yaml_with_header(comment_sheet.to_yaml_h)
-      File.write(output_file, yaml_content)
-    end
-
-    def generate_yaml_with_header(data)
-      header = "# yaml-language-server: $schema=schema/iso_comment_2012-03.yaml\n\n"
-      header + data.to_yaml
+      File.write(output_file, comment_sheet.to_yaml_document)
     end
   end
 end

data/lib/commenter/github_session.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "octokit"
+require "yaml"
+
+module Commenter
+  # Shared connection setup for the GitHub integration commands: loads the
+  # configuration file, builds the Octokit client, and resolves the target
+  # repository. One constructor, one test surface.
+  class GitHubSession
+    attr_reader :config, :client, :repo
+
+    def initialize(config_path)
+      @config = load_config(config_path)
+      @client = Octokit::Client.new(access_token: required_token)
+      @repo = @config.dig("github", "repository")
+      raise "GitHub repository not specified in config" unless @repo
+    end
+
+    private
+
+    def load_config(config_path)
+      YAML.load_file(config_path)
+    rescue Errno::ENOENT
+      raise "Configuration file not found: #{config_path}"
+    end
+
+    def required_token
+      token = @config.dig("github", "token") || ENV["GITHUB_TOKEN"]
+      raise "GitHub token not found. Set GITHUB_TOKEN environment variable or specify in config file." unless token
+
+      token
+    end
+  end
+end

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: normalize_comment_type(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])
@@ -227,15 +225,6 @@ module Commenter
         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