commenter 0.3.0 → 0.4.0

data/lib/commenter/parser/track_change_docx_parser.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "zip"
+require "nokogiri"
+
+module Commenter
+  class Parser
+    # Extracts tracked changes from a redlined Word document into an ISO
+    # 2012-03 comment sheet.
+    #
+    # Captured track changes (w:ins, w:del, w:moveFrom, w:moveTo):
+    # - proposed_change renders the change itself, e.g. +Insert: "text"+
+    # - locality.clause is resolved from the nearest preceding heading
+    # - locality.element is resolved from caption/inline references
+    #   (Table N, Figure N, Formula (N), NOTE n) within the current clause
+    # - observations can be stamped via the observations or accept_all options
+    #
+    # Reviewer comment threads (word/comments.xml w:comment) are emitted
+    # after the track changes with -CNNN ids: the remark verbatim in
+    # comments, its instruction reworded as the proposed change, and empty
+    # observations for the owner to draft.
+    #
+    # Self-closing markers (paragraph-mark insertions inside rPr) carry no
+    # content and are skipped.
+    #
+    # word/document.xml is streamed with Nokogiri::XML::Reader because redline
+    # documents can exceed 100 MB.
+    class TrackChangeDocxParser
+      W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+      HEADING_STYLE = /\A(?:Heading[1-6]|h[2-5]annex\d*|ANNEX|BaseHeading)\z/i
+      KIND_COMMENT = { "ins" => "insertion", "del" => "deletion", "moveFrom" => "move (from)",
+                       "moveTo" => "move (to)" }.freeze
+      KIND_LABEL = { "ins" => "Insert", "del" => "Delete", "moveFrom" => "Move from",
+                     "moveTo" => "Move to" }.freeze
+
+      DEFAULT_BODY = "CS"
+      WHOLE_DOCUMENT = "_whole document"
+      ACCEPT_ALL = "Accepted. Tracked change accepted."
+
+      attr_reader :skipped_markers
+
+      def parse(path, options = {})
+        body = options[:body] || DEFAULT_BODY
+        changes = []
+        remarks = {}
+        anchors = {}
+        @skipped_markers = 0
+
+        Zip::File.open(path) do |zip|
+          entry = zip.glob("word/document.xml").first
+          raise Commenter::Error, "word/document.xml not found in #{path}" unless entry
+
+          remarks = read_remarks(zip)
+          changes = entry.get_input_stream { |stream| stream_changes(stream, anchors) }
+        end
+
+        CommentSheet.new(
+          version: "2012-03",
+          date: sheet_date(changes),
+          document: options[:document],
+          stage: options[:stage],
+          comments: build_change_comments(changes, body, options) +
+                    build_remark_comments(remarks, anchors, body, options)
+        )
+      end
+
+      # Turns a reviewer's remark phrased as a request ("Please remove this
+      # NOTE...") into the corresponding proposed change ("Remove this
+      # NOTE...").
+      def self.reword_remark(text)
+        text.to_s.strip.sub(/\APlease\s+/i, "").sub(/\A[a-z]/, &:upcase)
+      end
+
+      private
+
+      def read_remarks(zip)
+        entry = zip.glob("word/comments.xml").first
+        return {} unless entry
+
+        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"],
+            date: node["w:date"],
+            text: node.xpath(".//w:t", "w" => W_NS).map(&:text).join
+          }
+        end
+      end
+
+      def sheet_date(changes)
+        dates = changes.filter_map { |change| change[:date].to_s[/\A\d{4}-\d{2}-\d{2}/] }
+        dates.max
+      end
+
+      def build_change_comments(changes, body, options)
+        changes.each_with_index.map do |change, index|
+          kind = change[:kind]
+          Comment.new(
+            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: 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)
+          )
+        end
+      end
+
+      def build_remark_comments(remarks, anchors, body, options)
+        remarks.keys.sort_by(&:to_i).each_with_index.map do |remark_id, index|
+          remark = remarks[remark_id]
+          anchor = anchors[remark_id] || {}
+          clause = anchor[:clause].to_s.empty? ? WHOLE_DOCUMENT : anchor[:clause]
+          Comment.new(
+            id: format("%<body>s-C%03<index>d", body: body, index: index + 1),
+            body: body,
+            locality: { clause: clause, line_number: nil, element: anchor[:element] },
+            type: options[:remark_type] || "ed",
+            comments: remark[:text],
+            proposed_change: self.class.reword_remark(remark[:text]),
+            observations: nil
+          )
+        end
+      end
+
+      def observations_for(options)
+        return nil if options[:exclude_observations]
+
+        options[:observations] || (options[:accept_all] ? ACCEPT_ALL : nil)
+      end
+
+      def stream_changes(io, anchors = {})
+        changes = []
+        change_stack = []
+        paragraph = ParagraphState.new
+
+        Nokogiri::XML::Reader(io).each do |reader|
+          case reader.node_type
+          when Nokogiri::XML::Reader::TYPE_ELEMENT
+            handle_start(reader, change_stack, paragraph, anchors)
+          when Nokogiri::XML::Reader::TYPE_TEXT, Nokogiri::XML::Reader::TYPE_SIGNIFICANT_WHITESPACE
+            handle_text(reader, change_stack, paragraph)
+          when Nokogiri::XML::Reader::TYPE_END_ELEMENT
+            handle_end(reader, change_stack, paragraph, changes)
+          end
+        end
+
+        changes
+      end
+
+      def handle_start(reader, change_stack, paragraph, anchors = {})
+        case reader.local_name
+        when "p"
+          paragraph.begin_paragraph
+        when "pStyle"
+          paragraph.style = reader.attribute("w:val") || reader.attribute("val")
+        when "ins", "del", "moveFrom", "moveTo"
+          start_change(reader, change_stack, paragraph)
+        when "commentRangeStart"
+          anchor_remark(reader, paragraph, anchors)
+        end
+      end
+
+      def anchor_remark(reader, paragraph, anchors)
+        id = reader.attribute("w:id")
+        anchors[id] = {
+          clause: paragraph.pending_clause || paragraph.clause,
+          element: paragraph.pending_element || paragraph.element
+        }
+      end
+
+      def start_change(reader, change_stack, paragraph)
+        if reader.empty_element?
+          @skipped_markers += 1
+          return
+        end
+
+        change_stack.push(
+          kind: reader.local_name,
+          id: reader.attribute("w:id"),
+          author: reader.attribute("w:author"),
+          date: reader.attribute("w:date"),
+          text: +"",
+          clause: paragraph.clause,
+          element: paragraph.element
+        )
+      end
+
+      def handle_text(reader, change_stack, paragraph)
+        if (current = change_stack.last)
+          current[:text] << reader.value
+        else
+          paragraph.append_text(reader.value)
+        end
+      end
+
+      def handle_end(reader, change_stack, paragraph, changes)
+        case reader.local_name
+        when "p"
+          paragraph.commit_paragraph
+        when "ins", "del", "moveFrom", "moveTo"
+          change = change_stack.pop
+          changes << finalize_change(change, paragraph) if change
+        end
+      end
+
+      def finalize_change(change, paragraph)
+        # A change inside a heading or caption paragraph belongs to that
+        # paragraph, which is not committed yet at this point.
+        change[:clause] = paragraph.pending_clause || change[:clause]
+        change[:element] = paragraph.pending_element || change[:element]
+        change[:clause] = WHOLE_DOCUMENT if change[:clause].to_s.empty?
+        change
+      end
+
+      # Tracks the current paragraph's style and text to resolve the locality
+      # context of a change:
+      #
+      # - clause: the clause number of the most recent heading paragraph; an
+      #   unnumbered sub-heading inherits its parent heading's clause
+      # - element: the nearest Table/Figure/Formula/NOTE reference, scoped to
+      #   the current clause (caption paragraphs and inline mentions both
+      #   count)
+      class ParagraphState
+        NUMBERED_CLAUSE = /\A(?:\d+(?:\.\d+)*|Annex\s+[A-Z](?:\.\d+)*|Bibliography|Foreword|Introduction)\z/i
+        ELEMENT_START = /\A\s*(NOTE\s+\d+|NOTE(?=\s*[—:-])|Table\s+(?:[A-Z]\.)?\d+(?:\.\d+)*|Figure\s+(?:[A-Z]\.)?\d+(?:\.\d+)*)\b/i
+        FORMULA = /\b(Formula\s*\(\d+(?:\.\d+)*\))/
+        ELEMENT_ANY = /\b(Table\s+(?:[A-Z]\.)?\d+(?:\.\d+)*|Figure\s+(?:[A-Z]\.)?\d+(?:\.\d+)*|NOTE\s+\d+)\b/i
+
+        attr_writer :style
+        attr_reader :clause, :element
+
+        def initialize
+          @style = nil
+          @text = +""
+          @clause = ""
+          @element = nil
+          @heading_stack = []
+        end
+
+        def begin_paragraph
+          @style = nil
+          @text = +""
+        end
+
+        def append_text(value)
+          @text << value
+        end
+
+        def pending_clause
+          return unless heading_paragraph?
+
+          clause = self.class.clause_for(@text)
+          clause unless clause.empty?
+        end
+
+        def pending_element
+          self.class.element_for(@text)
+        end
+
+        def commit_paragraph
+          if heading_paragraph?
+            commit_heading
+          else
+            @element = self.class.element_for(@text) || @element
+          end
+        end
+
+        def heading_paragraph?
+          @style&.match?(HEADING_STYLE)
+        end
+
+        def self.numbered_clause?(clause)
+          clause.to_s.match?(NUMBERED_CLAUSE)
+        end
+
+        # Extracts the clause identifier from heading text: the leading number
+        # ("4.2.1 Thermodynamic ..." -> "4.2.1"), an annex reference, or a
+        # well-known unnumbered section. Runs may be concatenated without
+        # spaces ("4.2.1Thermodynamic"), so the number is matched with a
+        # lookahead.
+        def self.clause_for(text)
+          s = text.to_s.strip
+          return "" if s.empty?
+
+          return Regexp.last_match(1) if s =~ /\A\s*(Annex\s+[A-Z](?:\.\d+)*)\b/i
+          return Regexp.last_match(1) if s =~ /\A\s*(Bibliography|Foreword|Introduction)\b/i
+          return Regexp.last_match(1) if s =~ /\A\s*((?:\d+\.)*\d+)(?=[A-Z\s])/
+          return Regexp.last_match(1) if s =~ /\A\s*((?:\d+\.)*\d+)\b/
+
+          s
+        end
+
+        # Resolves the element reference of a paragraph: a caption opening the
+        # paragraph ("Table 3 — ...", "NOTE 2 ...", "Formula (9):") wins over an
+        # inline mention ("the values in Table 5 shall ...").
+        def self.element_for(text)
+          s = text.to_s
+          match = s.match(ELEMENT_START) || s.match(FORMULA) || s.match(ELEMENT_ANY)
+          match[1].squeeze(" ").strip if match
+        end
+
+        private
+
+        def commit_heading
+          level = heading_level
+          clause = self.class.clause_for(@text)
+          clause = inherited_clause(level) unless self.class.numbered_clause?(clause)
+          @heading_stack.pop while @heading_stack.last && @heading_stack.last[0] >= level
+          @heading_stack << [level, clause]
+          @clause = clause unless clause.empty?
+          # Element references belong to the clause they appear in.
+          @element = nil
+        end
+
+        def inherited_clause(level)
+          parent = @heading_stack.reverse.find { |(lvl, _)| lvl < level }
+          parent ? parent[1] : ""
+        end
+
+        def heading_level
+          m = @style.match(/\A(?:Heading|h)(\d+)/i)
+          m ? m[1].to_i : 1
+        end
+      end
+    end
+  end
+end

data/lib/commenter/parser.rb

@@ -2,12 +2,12 @@
 
 require "docx"
 require "pathname"
-require_relative "comment_sheet"
-require_relative "comment"
-require_relative "parser/osd_xlsx_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)
 
@@ -16,6 +16,8 @@ module Commenter
         parse_docx(input_path, options)
       when :xlsx
         parse_xlsx(input_path, options)
+      when :redline
+        parse_redline(input_path, options)
       else
         raise "Unsupported file format: #{input_path}. Supported formats: .docx, .xlsx"
       end
@@ -38,6 +40,10 @@ module Commenter
       OsdXlsxParser.new.parse(xlsx_path, options)
     end
 
+    def parse_redline(docx_path, options)
+      TrackChangeDocxParser.new.parse(docx_path, options)
+    end
+
     def parse_docx(docx_path, options)
       doc = Docx::Document.open(docx_path)
 
@@ -83,7 +89,7 @@ module Commenter
           clause: presence(cells[2]),
           element: presence(cells[3])
         },
-        type: normalize_type(cells[4]),
+        type: CommentType.full_name(cells[4]),
         comments: cells[5] || "",
         proposed_change: presence(cells[6]),
         user_name: cells[0].to_s.strip
@@ -117,15 +123,6 @@ module Commenter
       value && !value.empty? ? value : nil
     end
 
-    def normalize_type(type_str)
-      case type_str.to_s.strip.downcase
-      when "editorial" then "ed"
-      when "technical" then "te"
-      when "general" then "ge"
-      else type_str.to_s.strip
-      end
-    end
-
     def extract_metadata(doc)
       metadata = { date: nil, document: nil, project: nil }
 

data/lib/commenter/version.rb

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

data/lib/commenter.rb

@@ -1,12 +1,23 @@
 # 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.
 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

data/spec/commenter/ballot_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Commenter::Ballot do
+  def sheet(body:, ids:, document: nil, stage: nil)
+    Commenter::CommentSheet.new(
+      version: "2012-03",
+      document: document,
+      stage: stage,
+      comments: ids.map do |id|
+        Commenter::Comment.new(id: id, body: body, comments: "Comment #{id} from #{body}")
+      end
+    )
+  end
+
+  it "combines comments from all sheets in input order" do
+    merged = described_class.new([
+                                   sheet(body: "DE", ids: %w[DE-001 DE-002]),
+                                   sheet(body: "US", ids: %w[US-001])
+                                 ]).merge
+
+    expect(merged.comments.map(&:id)).to eq(%w[DE-001 DE-002 US-001])
+    expect(merged.comments.map(&:body)).to eq(%w[DE DE US])
+  end
+
+  it "takes metadata from the first sheet that provides it" do
+    merged = described_class.new([
+                                   sheet(body: "DE", ids: %w[DE-001], stage: nil),
+                                   sheet(body: "US", ids: %w[US-001], document: "ISO 2533:2026", stage: "DIS")
+                                 ]).merge
+
+    expect(merged.version).to eq("2012-03")
+    expect(merged.document).to eq("ISO 2533:2026")
+    expect(merged.stage).to eq("DIS")
+  end
+
+  it "silently deduplicates identical comments sharing an ID" do
+    duplicate = Commenter::Comment.new(id: "DE-001", body: "DE", comments: "Same text", proposed_change: "Same change")
+
+    merged = described_class.new([
+                                   Commenter::CommentSheet.new(comments: [duplicate]),
+                                   Commenter::CommentSheet.new(comments: [
+                                                                 Commenter::Comment.new(id: "DE-001", body: "DE", comments: "Same text",
+                                                                                        proposed_change: "Same change")
+                                                               ])
+                                 ]).merge
+
+    expect(merged.comments.map(&:id)).to eq(["DE-001"])
+  end
+
+  it "raises when the same ID carries differing content" do
+    conflicting = Commenter::Comment.new(id: "DE-001", body: "DE", comments: "Different text entirely")
+
+    expect do
+      described_class.new([
+                            sheet(body: "DE", ids: %w[DE-001]),
+                            Commenter::CommentSheet.new(comments: [conflicting])
+                          ]).merge
+    end.to raise_error(Commenter::Error, /DE-001/)
+  end
+
+  it "returns an empty sheet when no input sheets are given" do
+    merged = described_class.new([]).merge
+
+    expect(merged.comments).to eq([])
+  end
+end

data/spec/commenter/cli_spec.rb

@@ -32,4 +32,45 @@ RSpec.describe Commenter::Cli do
       end
     end
   end
+
+  describe "#merge" do
+    it "writes a combined sheet with schema reference" do
+      Dir.mktmpdir do |dir|
+        one = File.join(dir, "de.yaml")
+        two = File.join(dir, "us.yaml")
+        File.write(one, { "version" => "2012-03", "comments" => [
+          { "id" => "DE-001", "body" => "DE", "comments" => "First" }
+        ] }.to_yaml)
+        File.write(two, { "comments" => [
+          { "id" => "US-001", "body" => "US", "comments" => "Second" }
+        ] }.to_yaml)
+        output = File.join(dir, "out", "merged.yaml")
+        schema_dir = File.join(dir, "out", "schema")
+
+        described_class.start(["merge", one, two, "--output", output, "--schema-dir", schema_dir])
+
+        data = YAML.safe_load_file(output)
+        expect(data["comments"].map { |comment| comment["id"] }).to eq(%w[DE-001 US-001])
+        expect(File).to exist(File.join(schema_dir, "iso_comment_2012-03.yaml"))
+      end
+    end
+  end
+
+  describe "#stats" do
+    it "prints a markdown disposition report" do
+      Dir.mktmpdir do |dir|
+        input = File.join(dir, "comments.yaml")
+        File.write(input, { "comments" => [
+          { "id" => "DE-001", "body" => "DE", "comments" => "A", "observations" => "Accepted." },
+          { "id" => "US-001", "body" => "US", "comments" => "B", "observations" => "Noted" }
+        ] }.to_yaml)
+
+        expect { described_class.start(["stats", input]) }
+          .to output(a_string_including(
+                       "| DE | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 |",
+                       "| US | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 |"
+                     )).to_stdout
+      end
+    end
+  end
 end

data/spec/commenter/comment_sheet_spec.rb

@@ -115,21 +115,21 @@ RSpec.describe Commenter::CommentSheet do
 
       hash = sheet.to_h
 
-      expect(hash[:version]).to eq("2012-03")
-      expect(hash[:date]).to eq("2024-06-04")
-      expect(hash[:document]).to eq("Test Document")
-      expect(hash[:project]).to eq("Test Project")
-      expect(hash[:stage]).to eq("DIS")
-      expect(hash[:comments]).to be_an(Array)
-      expect(hash[:comments].first).to be_a(Hash)
+      expect(hash["version"]).to eq("2012-03")
+      expect(hash["date"]).to eq("2024-06-04")
+      expect(hash["document"]).to eq("Test Document")
+      expect(hash["project"]).to eq("Test Project")
+      expect(hash["stage"]).to eq("DIS")
+      expect(hash["comments"]).to be_an(Array)
+      expect(hash["comments"].first).to be_a(Hash)
     end
 
-    it "includes nil stage when not set" do
+    it "omits unset attributes from the hash" do
       sheet = described_class.new({})
       hash = sheet.to_h
 
-      expect(hash).to have_key(:stage)
-      expect(hash[:stage]).to be_nil
+      expect(hash).not_to have_key("stage")
+      expect(sheet.version).to eq("2012-03")
     end
   end
 
@@ -169,6 +169,31 @@ RSpec.describe Commenter::CommentSheet do
       expect(sheet.comments.length).to eq(1)
     end
   end
+end
+
+RSpec.describe Commenter::CommentSheet do
+  describe "#schema_name" do
+    it "selects the schema for each sheet version" do
+      expect(described_class.new(version: "osd").schema_name).to eq("iso_comment_osd.yaml")
+      expect(described_class.new(version: "2012-03").schema_name).to eq("iso_comment_2012-03.yaml")
+      expect(described_class.new({}).schema_name).to eq("iso_comment_2012-03.yaml")
+    end
+  end
+
+  describe "#to_yaml_document" do
+    it "prepends a header referencing the schema matching the version" do
+      document = described_class.new(version: "osd", comments: []).to_yaml_document
+
+      expect(document.lines.first).to eq("# yaml-language-server: $schema=schema/iso_comment_osd.yaml\n")
+      expect(YAML.safe_load(document)).to include("version" => "osd")
+    end
+
+    it "accepts a schema directory" do
+      document = described_class.new(comments: []).to_yaml_document("schemas")
+
+      expect(document.lines.first).to eq("# yaml-language-server: $schema=schemas/iso_comment_2012-03.yaml\n")
+    end
+  end
 
   describe "stage validation" do
     it "accepts valid stage values" do