commenter 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1609bb9eed80e408daebc9c67cda2c657e8484186acce89b823e6b411a5f9ea5
-  data.tar.gz: 46316674e2c639b9256390385d2cb3c59ed8946b604b44fbb0be28728475cd38
+  metadata.gz: 90d4268c6a071ae365af24ef05a5c19dcdfd6fe03545c05a84767f91f70dc411
+  data.tar.gz: b44468b6f9cc18e0726c1df1c1433247e8fc19f6ff9fafc4c3f0eff341a21785
 SHA512:
-  metadata.gz: 887aa19ab8ca3559fd20caf3e19a9941b631c677faeda86553597671883fc8dbae8c1e1f6d83bd0014e036774743addc16bc538b7404f6939be6636e1d623704
-  data.tar.gz: 3b850d0872f2f572b599d0bf7a70a977e1e5e7e797f5fb3447905c09cc7578cff18d99de6b32ae3b539758b7319b07590fdfd9d5249f74024ffdcd842d48d09d
+  metadata.gz: 00d4838eadd5c0751199832ff6401a753b2bc4c27cd94d02f6c0d2bab6392a629c216c6cc350766c0d35920f871b4e2bd74102967460e370ebc15fc005a17e9c
+  data.tar.gz: '09420029845d4e6b776eeb40b726326486a409dd8f0ec33be792dcc193e30f5d5774e99777cd64e85c31a5137a69d2648eac4ab06bde2a5ea93a7d2569d0e90a'

data/CONTEXT.md

@@ -0,0 +1,27 @@
+# CONTEXT.md — Domain Glossary
+
+The domain language of the commenter gem. Used to name modules and commands;
+keep this current when concepts sharpen.
+
+- **Comment Sheet** — one ballot submission as a whole: metadata (document,
+  stage, date, project, titles) plus its comments. `CommentSheet`.
+- **Comment** — a single remark on a document: identity (id, member body),
+  locality (clause, element, line), type, the remark text, the proposed
+  change, and the disposition (`observations`).
+- **Member Body** — the national body or committee that submitted the comment
+  (`DE`, `US`, `CS` for the ISO/CS secretariat, `**` for ISO itself). A
+  secretariat receives one sheet per member body per ballot.
+- **Ballot** — the set of all comment sheets for one ballot round. Merging
+  member sheets into one is collation; `Ballot`.
+- **Disposition** — the resolution of a comment: accepted, accept with
+  modifications, noted, rejected, or still open. `DispositionStatus` is the
+  single matcher for both free-text observations and OSD's structured
+  `resolution_status`.
+- **Stage** — the ballot stage of the document (WD, CD, DIS, FDIS, PRF, PUB).
+  The same comment ID at different stages is a different comment.
+- **Redline** — a DOCX with tracked changes (`w:ins`/`w:del`/moves), typically
+  from ISO/CS editors; also carries reviewer remark threads.
+- **OSD** — ISO Online Standards Development; its XLSX comment exports come
+  in resolved and unresolved variants.
+- **Unique ID** — stage-aware identity of a comment's GitHub issue
+  (`[DIS] GB-001` by default), used for duplicate detection.

data/README.adoc

@@ -124,12 +124,16 @@ Options:
 ==== Metadata (extraction limitation)
 
 WARNING: Due to a limitation in the underlying `docx` gem, metadata fields
-(Date, Document, Project) from the DOCX header cannot be automatically
-extracted. This is because the required functionality is not yet merged (see
-https://github.com/ruby-docx/docx/pull/73[docx gem PR #73]).
+(Date, Document, Project) cannot yet be automatically extracted from the DOCX
+header during import (see https://github.com/ruby-docx/docx/pull/73[docx gem
+PR #73]). Redline imports take them from the `--document` / `--stage` options;
+for template imports, populate the YAML fields manually.
 
-The generated YAML will have empty metadata fields that you can manually
-populate:
+The reverse direction works: `commenter fill` writes the sheet's
+`date`, `document`, and `project` values into the Date/Document/Project labels
+of the template's page header, so the filled comment sheet is complete.
+
+For template imports, populate the YAML metadata manually:
 
 [source,yaml]
 ----
@@ -142,9 +146,6 @@ project: ""        # Manually add: e.g., "Project name"
 comments:
 ----
 
-Alternatively, you can provide metadata during import using CLI options (planned
-for future release).
-
 
 ==== Example YAML output
 
@@ -189,11 +190,56 @@ comments:
     observations:
 ----
 
+=== Merging comment sheets (ballot collation)
+
+A secretariat receives one comment file per member body per ballot — mixed
+DOCX templates, OSD XLSX exports, and late redlines that arrive by email.
+`commenter merge` collates them into a single ballot sheet:
+
+[source,shell]
+----
+commenter merge de.yaml us.yaml jp.yaml cs-redline.yaml -o ballot.yaml
+----
+
+Metadata (document, stage, date) is taken from the first sheet that provides
+each field. Comments keep their input order. Identical duplicates of the same
+comment ID are deduplicated silently; the same ID with differing content
+raises an error listing the conflicting IDs — collation stops loudly rather
+than silently dropping a member's comment.
+
+=== Ballot statistics (disposition reports)
+
+Every ballot report needs disposition counts — by member body and overall.
+The data is already in the YAML, so `commenter stats` produces the table:
+
+[source,shell]
+----
+commenter stats ballot.yaml
+----
+
+[source,markdown]
+....
+| Body | Total | Accepted | AWM | Noted | Rejected | TODO | Open | Undecided |
+|------|-------|----------|-----|-------|----------|------|------|-----------|
+| DE   | 12    | 5        | 3   | 2     | 1        | 0    | 0    | 1         |
+| US   | 9     | 4        | 1   | 2     | 1        | 0    | 1    | 0         |
+| **Total** | **21** | **9** | **4** | **4** | **2** | **0** | **1** | **1** |
+
+Comment types: technical 13 · general 5 · editorial 3
+....
+
+A comment's disposition is read from its `observations` text, falling back to
+the OSD `resolution_status` field, then to the GitHub issue state (a still-open
+issue counts as *open*; no disposition at all counts as *undecided*). Use
+`--format yaml` for machine-readable output, and `-o report.md` to write to a
+file — the Markdown pastes directly into a GitHub issue or WG minutes.
+
 === Filling DOCX templates from YAML
 
 This gem contains a command-line utility to fill a DOCX template with comments
 from a YAML file. It generates a filled comment sheet that can be used for
-review and resolution tracking.
+review and resolution tracking. The sheet's `date`, `document`, and `project`
+metadata are written into the template's page header.
 
 The base template is the ISO comment sheet template located at
 `data/iso_comment_template_2012-03.docx`. You can also provide a custom
@@ -605,10 +651,10 @@ recognized and applied to the observations column:
 |===
 | Status Pattern | Intended Color | Hex Code | Example
 
+| `awm\|accept(ed)? with (modifications\|changes)` | Olive Green | #C4D79B | "Accepted with modifications"
 | `accept(ed)?` | Green | #92D050 | "Accepted"
-| `awm\|accept with modifications` | Olive Green | #C4D79B | "Accept with modifications"
 | `noted` | Blue | #8DB4E2 | "Noted"
-| `reject(ed)?` | Pink | #FF99CC | "Rejected"
+| `reject(ed)?\|not accepted` | Pink | #FF99CC | "Rejected"
 | `todo` | Diagonal stripes | #D9D9D9 | "TODO: Review"
 
 |===

data/commenter.gemspec

@@ -34,6 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "docx", "~> 0.8"
   spec.add_dependency "dotenv", "~> 2.8"
   spec.add_dependency "liquid", "~> 5.0"
+  spec.add_dependency "lutaml-model", "~> 0.8"
   spec.add_dependency "octokit", "~> 6.0"
   spec.add_dependency "roo", ">= 2.10"
   spec.add_dependency "thor", "~> 1.0"

data/lib/commenter/ballot.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Merges member-body comment sheets into a single ballot sheet — the
+  # collation step secretariats otherwise do by hand (ISO's own Comment
+  # Collation Tool fails on non-conforming files).
+  #
+  # Policy: sheet metadata is first-non-nil across the given sheets (the
+  # output version comes from the first sheet); comments keep their input
+  # order. Identical duplicate IDs are deduplicated silently; the same ID
+  # with differing content raises.
+  class Ballot
+    def initialize(sheets)
+      @sheets = sheets
+    end
+
+    def merge
+      CommentSheet.new(
+        version: first_sheet&.version || "2012-03",
+        date: first_value(:date),
+        document: first_value(:document),
+        project: first_value(:project),
+        stage: first_value(:stage),
+        title_en: first_value(:title_en),
+        title_fr: first_value(:title_fr),
+        comments: deduplicate(@sheets.flat_map(&:comments))
+      )
+    end
+
+    private
+
+    def first_sheet
+      @sheets.first
+    end
+
+    def first_value(attribute)
+      @sheets.lazy.map { |sheet| sheet.public_send(attribute) }.find { |value| !value.nil? }
+    end
+
+    def deduplicate(comments)
+      seen = {}
+      conflicts = []
+      kept = comments.reject do |comment|
+        key = comment.id.to_s
+        next false if key.empty?
+
+        existing = seen[key]
+        if existing.nil?
+          seen[key] = comment
+          false
+        elsif identical?(existing, comment)
+          true
+        else
+          conflicts << key
+          false
+        end
+      end
+      return kept if conflicts.empty?
+
+      raise Commenter::Error, "Duplicate comment IDs with differing content: #{conflicts.uniq.sort.join(", ")}"
+    end
+
+    def identical?(one, another)
+      one.comments == another.comments && one.proposed_change == another.proposed_change
+    end
+  end
+end

data/lib/commenter/ballot_report.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Disposition statistics over a comment sheet: the counts ballot reports
+  # need — comments per member body by disposition, and per comment type.
+  module BallotReport
+    module_function
+
+    # status bucket for one comment: matched observation text, else matched
+    # OSD resolution_status, else open when a GitHub issue is still open,
+    # else undecided.
+    def status_for(comment)
+      DispositionStatus.match(comment.observations) ||
+        DispositionStatus.match(comment.resolution_status) ||
+        (comment.github&.status == "open" ? :open : nil) ||
+        (comment.observations.to_s.strip.empty? && comment.resolution_status.to_s.strip.empty? ? :undecided : nil)
+    end
+
+    def counts(comment_sheet)
+      bodies = Hash.new { |hash, body| hash[body] = bucket_hash }
+      types = Hash.new(0)
+      comment_sheet.comments.each do |comment|
+        body = comment.body.to_s.strip.empty? ? "(unknown)" : comment.body
+        bodies[body][:total] += 1
+        status = status_for(comment)
+        bodies[body][status] += 1 if status
+        types[comment.type.to_s.strip.empty? ? "(untyped)" : comment.type] += 1
+      end
+      { total: bodies.values.sum { |bucket| bucket[:total] }, bodies: bodies, types: types }
+    end
+
+    def to_markdown(comment_sheet)
+      data = counts(comment_sheet)
+      sorted_bodies = data[:bodies].sort_by { |body, _| body }
+
+      lines = []
+      lines << "| Body | Total | Accepted | AWM | Noted | Rejected | TODO | Open | Undecided |"
+      lines << "|------|-------|----------|-----|-------|----------|------|------|-----------|"
+      sorted_bodies.each do |body, bucket|
+        lines << "| #{body} | #{bucket[:total]} | #{bucket[:accepted]} | #{bucket[:accept_with_modifications]} | " \
+                 "#{bucket[:noted]} | #{bucket[:rejected]} | #{bucket[:todo]} | #{bucket[:open]} | #{bucket[:undecided]} |"
+      end
+      totals = data[:bodies].values.reduce(bucket_hash) { |sum, bucket| merge_bucket(sum, bucket) }
+      lines << "| **Total** | **#{totals[:total]}** | **#{totals[:accepted]}** | " \
+               "**#{totals[:accept_with_modifications]}** | **#{totals[:noted]}** | " \
+               "**#{totals[:rejected]}** | **#{totals[:todo]}** | **#{totals[:open]}** | **#{totals[:undecided]}** |"
+      lines << ""
+      lines << "Comment types: #{data[:types].sort_by { |type, _| type }.map { |type, count| "#{type} #{count}" }.join(" · ")}"
+      lines.join("\n")
+    end
+
+    def bucket_hash
+      { total: 0, accepted: 0, accept_with_modifications: 0, noted: 0, rejected: 0, todo: 0, open: 0, undecided: 0 }
+    end
+
+    def merge_bucket(sum, bucket)
+      sum.merge(bucket) { |_key, accumulated, addition| accumulated + addition }
+    end
+  end
+end

data/lib/commenter/cli.rb

@@ -21,33 +21,50 @@ module Commenter
     option :document, type: :string, desc: "Redline: document identifier (e.g. ISO 2533:2026)"
     option :stage, type: :string, desc: "Redline: approval stage (e.g. DIS)"
     def import(input_file)
-      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 input file
-      parser = Parser.new
-      comment_sheet = parser.parse(input_file, options)
-
-      # Write the YAML data file with schema reference
-      File.write(output_yaml, comment_sheet.to_yaml_document(schema_dir))
-
-      # Copy schema file to output directory
-      schema_name = comment_sheet.schema_name
-      schema_source = File.join(__dir__, "../../schema/#{schema_name}")
-      schema_target = File.join(schema_dir, schema_name)
+      comment_sheet = Parser.new.parse(input_file, options)
 
-      # Only copy if source and target are different
-      FileUtils.cp(schema_source, schema_target) unless File.expand_path(schema_source) == File.expand_path(schema_target)
+      schema_target = write_sheet(comment_sheet, options[:output], options[:schema_dir])
 
-      puts "Converted #{input_file} to #{output_yaml}"
+      puts "Converted #{input_file} to #{options[:output]}"
       puts "  Version: #{comment_sheet.version}"
       puts "  Comments: #{comment_sheet.comments.length}"
       puts "  Schema: #{schema_target}"
     end
 
+    desc "merge INPUT.yaml...", "Merge multiple comment sheets into one ballot sheet"
+    option :output, type: :string, aliases: :o, default: "merged.yaml", desc: "Output YAML file"
+    option :schema_dir, type: :string, default: "schema", desc: "Directory for schema file"
+    def merge(*input_files)
+      raise "At least one input file is required" if input_files.empty?
+
+      sheets = input_files.map { |path| CommentSheet.from_yaml(File.read(path)) }
+      comment_sheet = Ballot.new(sheets).merge
+      write_sheet(comment_sheet, options[:output], options[:schema_dir])
+
+      puts "Merged #{input_files.length} files (#{comment_sheet.comments.length} comments) to #{options[:output]}"
+    end
+
+    desc "stats INPUT.yaml", "Disposition statistics for ballot reports"
+    option :output, type: :string, aliases: :o, desc: "Output file (default: stdout)"
+    option :format, type: :string, default: "markdown", enum: %w[markdown yaml], desc: "Report format"
+    def stats(input_yaml)
+      comment_sheet = CommentSheet.from_yaml(File.read(input_yaml))
+
+      report = if options[:format] == "yaml"
+                 BallotReport.counts(comment_sheet).to_yaml
+               else
+                 BallotReport.to_markdown(comment_sheet)
+               end
+
+      if options[:output]
+        File.write(options[:output], report)
+        puts "Wrote statistics to #{options[:output]}"
+      else
+        puts report
+      end
+    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"
@@ -55,23 +72,20 @@ module Commenter
     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
-
+      comment_sheet = CommentSheet.from_yaml(File.read(input_yaml))
+      comments = comment_sheet.comments
       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)
+      # Fill the template, including the sheet metadata in the page header
+      fill_options = options.merge(
+        date: comment_sheet.date,
+        document: comment_sheet.document,
+        project: comment_sheet.project
+      ).compact
+      Filler.new.fill(template_path, output_docx, comments, fill_options)
       puts "Filled template to #{output_docx}"
     end
 
@@ -212,5 +226,18 @@ module Commenter
     def self.exit_on_failure?
       true
     end
+
+    private
+
+    def write_sheet(comment_sheet, output_yaml, schema_dir)
+      FileUtils.mkdir_p(schema_dir) unless Dir.exist?(schema_dir)
+      File.write(output_yaml, comment_sheet.to_yaml_document(schema_dir))
+
+      schema_name = comment_sheet.schema_name
+      schema_source = File.join(__dir__, "../../schema/#{schema_name}")
+      schema_target = File.join(schema_dir, schema_name)
+      FileUtils.cp(schema_source, schema_target) unless File.expand_path(schema_source) == File.expand_path(schema_target)
+      schema_target
+    end
   end
 end

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