commenter 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 116bd5694762b20a730aa2d67d9950e3acedecf5e0e5d2f95a6d183d376c0e97
-  data.tar.gz: d1c34482394b44f5195a91268eb3b46f4db58c986afc214a841d74b908f98edb
+  metadata.gz: 94c3f6c75b5bf2bc60da48e3b38f3bfcbc17eb259d29834bc9b4a496da1a70fb
+  data.tar.gz: 5533dfb8fab486205a4f6a164ee5604561354d116e36018fc487913d036cf56a
 SHA512:
-  metadata.gz: 1d755c6bfefe119528e4ddb9e65033263f5c03550d972ae29bd62aaaea8df3fa571439305f80429eefb017856d387e5dde23c18a744ecdfb03d2f77d6a6e486e
-  data.tar.gz: 6d297683a681dc1918be0db3a5dd63aded21fca0fce0a63799b36e1342d60f927b9690ca9757c8935c74c530edc3205acb7b510e4930360a7f4a99d595a865fc
+  metadata.gz: 66614ec628ece4764cb10b33fc6213de4dad08fc72dba5a89a2c0cebda64848795f7a7372b0ed8b44b081ec4a8daa4b80f5605867986672a32ac7c26f2778545
+  data.tar.gz: 866aa00a35e504930f882ca391d335d7bb7602e77da086148712797e9772da0683ae5055350aaf2515a4ea8b620793c3780e2c0dae8fe63486e55410a8c19e07

data/CLAUDE.md

@@ -50,7 +50,7 @@ Core flow: `Parser` → `CommentSheet` (metadata + `Comment` objects) → YAML /
 - `Parser::TrackChangeDocxParser` — redline DOCX import: streams `word/document.xml` with Nokogiri XML::Reader (redlines can exceed 100 MB), captures `w:ins`/`w:del`/`w:moveFrom`/`w:moveTo` as comment entries (`proposed_change` renders the change itself, e.g. `Insert: "text"`; clause resolved from the nearest preceding heading including sub-clauses; element resolved from Table/Figure/Formula/NOTE references in the same clause; self-closing paragraph-mark markers skipped), plus reviewer `w:comment` threads as `-CNNN` remark entries (remark verbatim in `comments`, instruction reworded in `proposed_change`, empty `observations` for the owner). Stamps `observations` from the `observations`/`accept_all` options.
 - `Commenter::Filler` — writes comments into the DOCX template table; maps observation status text (`accept(ed)?`, `noted`, `reject(ed)?`, …) to shading colors.
 - GitHub integration — `GitHubIssueCreator` (`github-create`, `lib/commenter/github_integration.rb`), `GitHubIssueRetriever` (`github-retrieve`, `lib/commenter/github_issue_retriever.rb`), and `GitHubSync` (`github-sync`, subclass of the creator). Each loads its own config YAML and Octokit client, and rewrites the comments YAML in place after the run. Duplicate detection verifies issue numbers already recorded in the YAML, then searches issue bodies for a deterministic `urn:commenter:` marker appended to every created issue, then falls back to a title search over a configurable Liquid `unique_id` template (stage-aware by default: `[DIS] GB-001`). The same comment ID at different ballot stages creates separate issues. github-retrieve fills observations from open and closed issues alike.
-- `Commenter::Cli` (`lib/commenter/cli.rb`) — Thor CLI with subcommands `import`, `merge`, `stats`, `diff`, `fill`, `export`, `github-create`, `github-sync`, `github-retrieve`.
+- `Commenter::Cli` (`lib/commenter/cli.rb`) — Thor CLI with subcommands `import`, `merge`, `stats`, `diff`, `validate`, `fill`, `export`, `github-create`, `github-sync`, `github-retrieve`.
 
 ### Schemas
 

data/README.adoc

@@ -234,6 +234,18 @@ 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.
 
+=== Validating a comment sheet
+
+The shipped schemas power IDE validation; `commenter validate` checks the
+same structure from the command line — unknown versions, missing ids or
+comment text, duplicate ids, and unrecognized comment types — and exits
+non-zero when errors are found, so it fits CI and pre-flight checks:
+
+[source,shell]
+----
+commenter validate ballot.yaml
+----
+
 === Comparing ballots between stages
 
 The same comment ID (`DE-001`) recurs at every ballot stage; comparing two

data/lib/commenter/cli.rb

@@ -86,6 +86,24 @@ module Commenter
       end
     end
 
+    desc "validate INPUT.yaml", "Check a comment sheet for structural problems"
+    def validate(input_yaml)
+      comment_sheet = CommentSheet.from_yaml(File.read(input_yaml))
+      problems = SheetValidator.call(comment_sheet)
+
+      if problems.empty?
+        puts "OK: #{comment_sheet.comments.length} comments, no problems found"
+        return
+      end
+
+      problems.each do |problem|
+        where = problem[:comment] ? "#{problem[:comment]}: " : ""
+        puts "#{problem[:severity].to_s.upcase}: #{where}#{problem[:message]}"
+      end
+      errors = problems.count { |problem| problem[:severity] == :error }
+      raise Commenter::Error, "#{errors} error(s) found in #{input_yaml}"
+    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"

data/lib/commenter/sheet_validator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Structural validation of a comment sheet — the checks the CLI schemas
+  # express, living next to the model so the vocabulary stays in one place.
+  # Returns a list of problems; entries are hashes with :severity (:error or
+  # :warning), :comment (id when the problem belongs to one comment), and
+  # :message. An empty list means the sheet is valid.
+  module SheetValidator
+    VERSIONS = %w[2012-03 osd].freeze
+    STAGES = %w[WD CD DIS FDIS PRF PUB].freeze
+
+    module_function
+
+    def call(sheet)
+      problems = []
+      unless VERSIONS.include?(sheet.version)
+        problems << { severity: :error,
+                      message: "unknown version #{sheet.version.inspect} (expected #{VERSIONS.join(" or ")})" }
+      end
+      if sheet.stage && !STAGES.include?(sheet.stage)
+        problems << { severity: :warning,
+                      message: "unusual stage #{sheet.stage.inspect} (expected one of #{STAGES.join(", ")})" }
+      end
+
+      sheet.comments.each_with_index do |comment, index|
+        problems.concat(comment_problems(comment, index))
+      end
+
+      duplicates = sheet.comments.group_by { |comment| comment.id.to_s }
+                        .reject { |id, _| id.empty? }
+                        .select { |_, comments| comments.length > 1 }
+                        .keys
+      duplicates.sort.each do |id|
+        problems << { severity: :error, comment: id, message: "duplicate comment id #{id}" }
+      end
+
+      problems
+    end
+
+    def comment_problems(comment, index)
+      problems = []
+      label = comment.id.to_s.empty? ? "comment ##{index + 1}" : comment.id
+
+      problems << { severity: :error, comment: label, message: "missing id" } if comment.id.to_s.strip.empty?
+      problems << { severity: :error, comment: label, message: "missing comment text" } if comment.comments.to_s.strip.empty?
+      unless comment.type.to_s.strip.empty? || CommentType.known?(comment.type)
+        problems << { severity: :warning, comment: label,
+                      message: "unrecognized comment type #{comment.type.inspect} (no label will be minted for it)" }
+      end
+
+      problems
+    end
+  end
+end

data/lib/commenter/version.rb

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

data/lib/commenter.rb

@@ -14,6 +14,7 @@ module Commenter
   autoload :Ballot, "commenter/ballot"
   autoload :BallotReport, "commenter/ballot_report"
   autoload :BallotDiff, "commenter/ballot_diff"
+  autoload :SheetValidator, "commenter/sheet_validator"
   autoload :Comment, "commenter/comment"
   autoload :CommentSheet, "commenter/comment_sheet"
   autoload :GitHubSession, "commenter/github_session"

data/spec/commenter/sheet_validator_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Commenter::SheetValidator do
+  def sheet(comments, version: "2012-03", stage: nil)
+    Commenter::CommentSheet.new(version: version, stage: stage, comments: comments)
+  end
+
+  def comment(id, text: "Text", type: "technical")
+    Commenter::Comment.new(id: id, body: id.to_s.split("-").first, comments: text, type: type)
+  end
+
+  it "accepts a clean sheet" do
+    expect(described_class.call(sheet([comment("DE-001")]))).to eq([])
+  end
+
+  it "reports unknown versions and unusual stages" do
+    problems = described_class.call(sheet([comment("DE-001")], version: "2018-01", stage: "CUSTOM"))
+
+    expect(problems).to include(severity: :error, message: a_string_including("unknown version"))
+    expect(problems).to include(severity: :warning, message: a_string_including("unusual stage"))
+  end
+
+  it "reports missing ids, missing text, and duplicate ids as errors" do
+    problems = described_class.call(sheet([
+                                            comment("", text: "No id"),
+                                            comment("DE-001"),
+                                            comment("DE-001"),
+                                            comment("DE-002", text: "")
+                                          ]))
+
+    errors = problems.select { |problem| problem[:severity] == :error }
+    expect(errors.map { |problem| problem[:message] }).to include("missing id", "missing comment text",
+                                                                  "duplicate comment id DE-001")
+  end
+
+  it "warns about unrecognized comment types without failing" do
+    problems = described_class.call(sheet([comment("DE-001", type: "ge/te")]))
+
+    expect(problems).to contain_exactly(severity: :warning, comment: "DE-001",
+                                        message: a_string_including("unrecognized comment type"))
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: commenter
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Ribose
@@ -169,6 +169,7 @@ files:
 - lib/commenter/parser.rb
 - lib/commenter/parser/osd_xlsx_parser.rb
 - lib/commenter/parser/track_change_docx_parser.rb
+- lib/commenter/sheet_validator.rb
 - lib/commenter/version.rb
 - schema/iso_comment_2012-03.yaml
 - schema/iso_comment_osd.yaml
@@ -185,6 +186,7 @@ files:
 - spec/commenter/github_integration_spec.rb
 - spec/commenter/github_sync_spec.rb
 - spec/commenter/osd_xlsx_parser_spec.rb
+- spec/commenter/sheet_validator_spec.rb
 - spec/commenter/track_change_docx_parser_spec.rb
 - spec/commenter_spec.rb
 - spec/spec_helper.rb