commenter 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac1118f53d0edcb5d61c345203bdfdc20a5711c4971e68ae5bb9225744bae8b3
-  data.tar.gz: 309347f180dee0adbe3a51c5d75fbf5aea0f95884667048c5a12a14faae479a2
+  metadata.gz: 31fa0d4ee056c833d9f2b329d994e5d6151e3430426e6d4f02dfca4c670d0c18
+  data.tar.gz: b459baef384850cfa84cfb22c48212771ee57fa0e11cbd803c1db33dfb44aae2
 SHA512:
-  metadata.gz: 7b90c6ec2ee250680be18144d1e32a285d26994d760806a0b2d555c964163bae84330fea41d7531b6aeb0a95d790e7ad01436592fb60640af22bcf094a5f91cb
-  data.tar.gz: 93a090640a00260ca88db27683f8e8b38f71978e8040ab10f019013cc34472316729c66e19324b5fe1ce56b4f286abd8ff019c919e854cc2fc19d6212569185f
+  metadata.gz: 989ff9a26a63210438385658edaee8a0d94a35c9d80916dfefe89575ce739f9efc75bdcc372d737a955de236fdefdeaaca0be65146363dea5833ac280cc97cdb
+  data.tar.gz: 5cdcb2b0ca204b6e419d009f45eeb6dfd4867c7eb51196a04ad2499c7c64e5cb5288b85522f031a7a823e9242c3e8edec771d7c2d1bb8f5f9b079df7e86cc54b

data/.rubocop_todo.yml

@@ -1,80 +1,21 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-06-04 10:43:42 UTC using RuboCop version 1.75.8.
+# on 2026-03-16 10:59:51 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 1
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'commenter.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith, Severity.
-# SupportedStylesAlignWith: start_of_line, begin
-Layout/BeginEndAlignment:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: empty_lines, no_empty_lines
-Layout/EmptyLinesAroundBlockBody:
-  Exclude:
-    - 'spec/commenter_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/RescueEnsureAlignment:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
 # Offense count: 1
 Lint/NonLocalExitFromIterator:
   Exclude:
     - 'lib/commenter/filler.rb'
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-Lint/SafeNavigationWithEmpty:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
-Lint/UnusedBlockArgument:
-  Exclude:
-    - 'lib/commenter/filler.rb'
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
-# NotImplementedExceptions: NotImplementedError
-Lint/UnusedMethodArgument:
-  Exclude:
-    - 'lib/commenter/github_integration.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect.
-Lint/UselessAssignment:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
 # Offense count: 15
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
@@ -89,9 +30,9 @@ Metrics/BlockLength:
 # Offense count: 5
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 202
+  Max: 231
 
-# Offense count: 9
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
   Max: 22
@@ -101,7 +42,7 @@ Metrics/CyclomaticComplexity:
 Metrics/MethodLength:
   Max: 53
 
-# Offense count: 9
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
   Max: 22
@@ -112,7 +53,7 @@ Metrics/PerceivedComplexity:
 # ForbiddenPrefixes: is_, has_, have_, does_
 # AllowedMethods: is_a?
 # MethodDefinitionMacros: define_method, define_singleton_method
-Naming/PredicateName:
+Naming/PredicatePrefix:
   Exclude:
     - 'spec/**/*'
     - 'lib/commenter/comment.rb'
@@ -130,45 +71,9 @@ Style/Documentation:
     - 'lib/commenter/github_integration.rb'
     - 'lib/commenter/parser.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, EnforcedStyle, AllowComments.
-# SupportedStyles: empty, nil, both
-Style/EmptyElse:
-  Exclude:
-    - 'lib/commenter/filler.rb'
-
 # Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
-Style/IfUnlessModifier:
-  Exclude:
-    - 'lib/commenter/cli.rb'
-    - 'lib/commenter/github_integration.rb'
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/RescueModifier:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: implicit, explicit
-Style/RescueStandardError:
-  Exclude:
-    - 'lib/commenter/parser.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
-  Max: 132
+  Max: 138

data/README.adoc

@@ -227,6 +227,7 @@ The title template (`data/github_issue_title_template.liquid`) supports these va
 * `body` - Member body abbreviation
 * `type` - Comment type code
 * `clause`, `element`, `line_number` - Location information
+* `unique_id` - Rendered unique identifier (see <<_duplicate_detection>>)
 
 ===== Body template variables
 
@@ -256,6 +257,7 @@ github:
   templates:
     title: "custom_title.liquid"
     body: "custom_body.liquid"
+    unique_id: "[{{ stage | upcase }}] {{ comment_id }}"  # Optional: customize unique ID
 ----
 ====
 
@@ -301,9 +303,75 @@ $ commenter github comments.yaml --config github_config.yaml
 
 ==== Duplicate detection
 
-The gem automatically checks for existing issues to avoid duplicates by
-searching for the comment ID in issue titles. If an issue already exists, it
-will be skipped.
+The gem automatically checks for existing issues to avoid duplicates. The duplicate
+detection uses a **configurable unique identifier** that is:
+
+. Rendered from a Liquid template
+. Embedded in the issue title for human identification
+. Used as the search pattern to find existing issues
+
+This ensures that the search pattern always matches what appears in the title,
+preventing synchronization issues.
+
+===== Unique ID template
+
+The unique identifier is defined by the `unique_id` template in your configuration:
+
+[source,yaml]
+----
+github:
+  templates:
+    # Default: "[STAGE] COMMENT_ID"
+    unique_id: "[{{ stage | upcase }}] {{ comment_id }}"
+----
+
+The default renders to: `[DIS] GB-001`
+
+===== Why stage-aware unique IDs?
+
+ISO standards go through multiple ballot stages (WD, CD, DIS, FDIS). The same
+comment ID (e.g., `GB-001`) appears at each stage, but represents **different
+comments**:
+
+| Stage | Comment ID | Unique ID | Same Issue? |
+|-------|------------|-----------|-------------|
+| CD | GB-001 | `[CD] GB-001` | No |
+| DIS | GB-001 | `[DIS] GB-001` | No |
+
+Without stage-aware unique IDs, CD `GB-001` and DIS `GB-001` would be treated as
+duplicates, causing the DIS comment to be skipped.
+
+===== Custom unique ID patterns
+
+You can customize the unique ID pattern to match your title template format:
+
+[source,yaml]
+----
+github:
+  templates:
+    # Different order
+    unique_id: "{{ comment_id }} [{{ stage | upcase }}]"
+
+    # With document prefix
+    unique_id: "{{ document }} - {{ comment_id }}"
+
+    # With body prefix (for multi-body projects)
+    unique_id: "{{ body }}/{{ comment_id }}"
+
+    # Single stage project (no stage needed)
+    unique_id: "{{ comment_id }}"
+----
+
+===== Using unique_id in templates
+
+The `unique_id` is available as a variable in title and body templates:
+
+[source,liquid]
+----
+{{ unique_id }}: {{ brief_summary }} {% if document %}({{ document }}){% endif %}
+----
+
+This renders to: `[DIS] GB-001: Clause 5.1 summary (ISO/DIS 2533)`
 
 ==== Retrieving observations from GitHub issues
 

data/data/github_config_sample.yaml

@@ -61,9 +61,17 @@ github:
 
   # Custom template paths (optional)
   templates:
+    # Title template for GitHub issues
+    # The {{ unique_id }} variable is required for duplicate detection
     title: "custom_title_template.liquid"
     body: "custom_body_template.liquid"
 
+    # Unique identifier template for duplicate detection
+    # This is rendered and used to search for existing issues
+    # Default: "[{{ stage | upcase }}] {{ comment_id }}"
+    # The unique_id is also available as {{ unique_id }} in title/body templates
+    unique_id: "[{{ stage | upcase }}] {{ comment_id }}"
+
   # Retrieval configuration for github-retrieve command
   retrieval:
     # Magic comment markers to look for in GitHub issue comments

data/data/github_issue_body_template.liquid

@@ -1,4 +1,4 @@
-# {% if stage %}[{{ stage | upcase }}] {% endif %}{% if document %}{{ document }} - {% endif %}Comment {{ comment_id }}
+# {% if stage %}[{{ stage | upcase }}] {% endif %}{{ comment_id }} {% if document %}({{ document }}){% endif %}
 
 **Stage:** {{ stage | default: "Not specified" }}
 **Document:** {{ document | default: "Not specified" }}

data/data/github_issue_title_template.liquid

@@ -1 +1 @@
-{% if stage %}[{{ stage | upcase }}] {% endif %}{% if document %}{{ document }} - {% endif %}{{ comment_id }}: {{ brief_summary }}
+{{ unique_id }}: {{ brief_summary }} {% if document %}({{ document }}){% endif %}

data/lib/commenter/cli.rb

@@ -33,7 +33,10 @@ module Commenter
       schema_target = File.join(schema_dir, "iso_comment_2012-03.yaml")
 
       # 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)
+      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}"

data/lib/commenter/comment.rb

@@ -11,13 +11,22 @@ module Commenter
       @id = attrs[:id]
       @body = attrs[:body]
       @locality = symbolize_keys(attrs[:locality] || {})
-      @type = attrs[:type]
+      @type = expand_comment_type(attrs[:type])
       @comments = attrs[:comments]
       @proposed_change = attrs[:proposed_change]
       @observations = attrs[:observations]
       @github = symbolize_keys(attrs[:github] || {})
     end
 
+    def expand_comment_type(type)
+      case type&.downcase
+      when "ge" then "general"
+      when "te" then "technical"
+      when "ed" then "editorial"
+      else type
+      end
+    end
+
     def line_number
       @locality[:line_number]
     end

data/lib/commenter/github_integration.rb

@@ -16,6 +16,7 @@ module Commenter
 
       @title_template = load_liquid_template(title_template_path || default_title_template_path)
       @body_template = load_liquid_template(body_template_path || default_body_template_path)
+      @unique_id_template = load_unique_id_template
     end
 
     def create_issues_from_yaml(yaml_file, options = {})
@@ -70,7 +71,26 @@ module Commenter
       raise "Template file not found: #{template_path}"
     end
 
+    def load_unique_id_template
+      unique_id_config = @config.dig("github", "templates", "unique_id")
+
+      if unique_id_config
+        # Check if it's a file path or inline template
+        if File.exist?(unique_id_config)
+          load_liquid_template(unique_id_config)
+        else
+          Liquid::Template.parse(unique_id_config)
+        end
+      else
+        # Default unique_id pattern: "[STAGE] COMMENT_ID"
+        Liquid::Template.parse("[{{ stage | upcase }}] {{ comment_id }}")
+      end
+    end
+
     def template_variables(comment, comment_sheet)
+      # Render unique_id first so it can be used in other templates
+      unique_id = render_unique_id(comment, comment_sheet)
+
       {
         # Comment sheet variables
         "stage" => comment_sheet.stage || "",
@@ -95,17 +115,30 @@ module Commenter
         "line_number" => comment.line_number || "",
 
         # Computed variables
+        "unique_id" => unique_id,
         "has_observations" => !comment.observations.nil? && !comment.observations.strip.empty?,
         "has_proposed_change" => !comment.proposed_change.nil? && !comment.proposed_change.strip.empty?,
         "locality_summary" => format_locality(comment)
       }
     end
 
+    def render_unique_id(comment, comment_sheet)
+      base_variables = {
+        "stage" => comment_sheet.stage || "",
+        "document" => comment_sheet.document || "",
+        "project" => comment_sheet.project || "",
+        "comment_id" => comment.id || "",
+        "body" => comment.body || "",
+        "type" => comment.type || ""
+      }
+      @unique_id_template.render(base_variables).strip
+    end
+
     def expand_comment_type(type)
       case type&.downcase
-      when "ge" then "General"
-      when "te" then "Technical"
-      when "ed" then "Editorial"
+      when "ge", "general" then "General"
+      when "te", "technical" then "Technical"
+      when "ed", "editorial" then "Editorial"
       else type || "Unknown"
       end
     end
@@ -119,9 +152,11 @@ module Commenter
     end
 
     def create_issue(comment, comment_sheet, options = {})
-      # Check if issue already exists
-      existing_issue = find_existing_issue(comment)
+      puts "[GitHubIssueCreator] Creating issue for comment ID: #{comment.id}"
+      # Check if issue already exists (stage-aware)
+      existing_issue = find_existing_issue(comment, comment_sheet)
       if existing_issue
+        puts "[GitHubIssueCreator] Issue already exists for comment ID: #{comment.id} at stage #{comment_sheet.stage}, skipping creation."
         return {
           comment_id: comment.id,
           status: :skipped,
@@ -139,8 +174,10 @@ module Commenter
         milestone: determine_milestone(comment, comment_sheet, options)
       }.compact
 
+      puts "[GitHubIssueCreator] Creating issue with title: #{title}"
       begin
         issue = @github_client.create_issue(@repo, title, body, issue_options)
+        puts "[GitHubIssueCreator] Issue created successfully: #{issue.html_url}"
         {
           comment_id: comment.id,
           status: :created,
@@ -148,6 +185,7 @@ module Commenter
           issue_url: issue.html_url
         }
       rescue Octokit::Error => e
+        puts "[GitHubIssueCreator] Error creating issue for comment ID: #{comment.id} - #{e.message}"
         {
           comment_id: comment.id,
           status: :error,
@@ -157,6 +195,8 @@ module Commenter
     end
 
     def preview_issue(comment, comment_sheet)
+      puts "[GitHubIssueCreator] Previewing issue for comment ID: #{comment.id}"
+
       title = @title_template.render(template_variables(comment, comment_sheet))
       body = @body_template.render(template_variables(comment, comment_sheet))
 
@@ -170,9 +210,13 @@ module Commenter
       }
     end
 
-    def find_existing_issue(comment)
-      # Search for existing issues with the comment ID in the title
-      query = "repo:#{@repo} in:title #{comment.id}"
+    def find_existing_issue(comment, comment_sheet)
+      unique_id = render_unique_id(comment, comment_sheet)
+      puts "[GitHubIssueCreator] Searching for existing issue with unique_id: #{unique_id}"
+
+      # Search for existing issues with the unique_id in the title
+      # The unique_id is configurable and defaults to "[STAGE] COMMENT_ID"
+      query = "repo:#{@repo} in:title \"#{unique_id}\""
       results = @github_client.search_issues(query)
       results.items.first
     rescue Octokit::Error
@@ -212,26 +256,25 @@ module Commenter
       assignees.compact.uniq
     end
 
-    def determine_milestone(_comment, comment_sheet, options)
-      # Check for override in options
-      return resolve_milestone_by_name_or_number(options[:milestone]) if options[:milestone]
-
-      # Check for stage-specific milestone
-      if comment_sheet.stage
-        stage_milestone = @config.dig("github", "stage_milestones", comment_sheet.stage)
-        if stage_milestone
-          milestone_number = resolve_milestone_by_name_or_number(stage_milestone)
-          return milestone_number if milestone_number
-        end
-      end
+    def determine_milestone(_comment, _comment_sheet, _options)
+      # # Check for stage-specific milestone
+      # if comment_sheet.stage
+      #   stage_milestone = @config.dig("github", "stage_milestones", comment_sheet.stage)
+      #   if stage_milestone
+      #     milestone_number = resolve_milestone_by_name_or_number(stage_milestone)
+      #     return milestone_number if milestone_number
+      #   end
+      # end
 
       # Use configured milestone
       milestone_config = @config.dig("github", "milestone")
       return nil unless milestone_config
 
       if milestone_config["number"]
+        puts "[GitHubIssueCreator] Using milestone number: #{milestone_config["number"]}"
         milestone_config["number"]
       elsif milestone_config["name"]
+        puts "[GitHubIssueCreator] Using milestone name: #{milestone_config["name"]}"
         resolve_milestone_by_name_or_number(milestone_config["name"])
       end
     end
@@ -246,6 +289,8 @@ module Commenter
 
     def find_milestone_by_name(name)
       milestones = @github_client.milestones(@repo, state: "all")
+
+      puts "[GitHubIssueCreator] Found #{milestones.size} milestones in repository #{@repo}" if milestones.any?
       milestone = milestones.find { |m| m.title == name }
       milestone&.number
     rescue Octokit::Error
@@ -411,7 +456,8 @@ module Commenter
       end
 
       # Fallback to last comment if configured and no magic comment found
-      return comments.last.body.strip if @config.dig("github", "retrieval", "fallback_to_last_comment") && !comments.empty?
+      return comments.last.body.strip if @config.dig("github", "retrieval",
+                                                     "fallback_to_last_comment") && !comments.empty?
 
       nil
     rescue Octokit::Error

data/lib/commenter/version.rb

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

data/spec/commenter/comment_spec.rb

@@ -22,7 +22,7 @@ RSpec.describe Commenter::Comment do
       expect(comment.clause).to eq("5.1")
       expect(comment.element).to eq("Table 1")
       expect(comment.line_number).to eq("42")
-      expect(comment.type).to eq("te")
+      expect(comment.type).to eq("technical")
       expect(comment.comments).to eq("Test comment")
       expect(comment.proposed_change).to eq("Test change")
       expect(comment.observations).to eq("Test observations")
@@ -173,7 +173,7 @@ RSpec.describe Commenter::Comment do
       expect(hash[:id]).to eq("US-001")
       expect(hash[:body]).to eq("US")
       expect(hash[:locality][:clause]).to eq("5.1")
-      expect(hash[:type]).to eq("te")
+      expect(hash[:type]).to eq("technical")
       expect(hash[:comments]).to eq("Test")
       expect(hash[:proposed_change]).to eq("Change")
       expect(hash[:observations]).to eq("Obs")

data/spec/commenter/github_integration_spec.rb

@@ -120,7 +120,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
         expect(result[:title]).to eq("US-001: Clause 5.1, Table 1: Test comment text")
         expect(result[:body]).to include("Comment: Test comment text")
         expect(result[:body]).to include("Type: Technical")
-        expect(result[:labels]).to include("comment-review", "draft-international-standard", "te")
+        expect(result[:labels]).to include("comment-review", "draft-international-standard", "technical")
         expect(result[:assignees]).to eq(["test-assignee"])
       end
     end
@@ -144,7 +144,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
       expect(variables["stage"]).to eq("DIS")
       expect(variables["document"]).to eq("Test Document")
       expect(variables["comment_id"]).to eq("US-001")
-      expect(variables["type"]).to eq("te")
+      expect(variables["type"]).to eq("technical")
       expect(variables["type_full_name"]).to eq("Technical")
       expect(variables["clause"]).to eq("5.1")
       expect(variables["element"]).to eq("Table 1")
@@ -164,7 +164,7 @@ RSpec.describe Commenter::GitHubIssueCreator do
 
       expect(labels).to include("comment-review") # default
       expect(labels).to include("draft-international-standard") # stage-specific
-      expect(labels).to include("te") # comment type
+      expect(labels).to include("technical") # comment type (expanded)
       expect(labels.uniq).to eq(labels) # no duplicates
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: commenter
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-04 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64