commenter 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31fa0d4ee056c833d9f2b329d994e5d6151e3430426e6d4f02dfca4c670d0c18
-  data.tar.gz: b459baef384850cfa84cfb22c48212771ee57fa0e11cbd803c1db33dfb44aae2
+  metadata.gz: 1609bb9eed80e408daebc9c67cda2c657e8484186acce89b823e6b411a5f9ea5
+  data.tar.gz: 46316674e2c639b9256390385d2cb3c59ed8946b604b44fbb0be28728475cd38
 SHA512:
-  metadata.gz: 989ff9a26a63210438385658edaee8a0d94a35c9d80916dfefe89575ce739f9efc75bdcc372d737a955de236fdefdeaaca0be65146363dea5833ac280cc97cdb
-  data.tar.gz: 5cdcb2b0ca204b6e419d009f45eeb6dfd4867c7eb51196a04ad2499c7c64e5cb5288b85522f031a7a823e9242c3e8edec771d7c2d1bb8f5f9b079df7e86cc54b
+  metadata.gz: 887aa19ab8ca3559fd20caf3e19a9941b631c677faeda86553597671883fc8dbae8c1e1f6d83bd0014e036774743addc16bc538b7404f6939be6636e1d623704
+  data.tar.gz: 3b850d0872f2f572b599d0bf7a70a977e1e5e7e797f5fb3447905c09cc7578cff18d99de6b32ae3b539758b7319b07590fdfd9d5249f74024ffdcd842d48d09d

data/.rubocop.yml

@@ -8,3 +8,11 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Metrics/ModuleLength:
+  Exclude:
+    - "spec/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```sh
+bin/setup                        # install dependencies
+bundle exec rake                 # default task: specs + RuboCop (this is what CI runs)
+bundle exec rspec                # all specs
+bundle exec rspec spec/commenter/comment_spec.rb          # single spec file
+bundle exec rspec spec/commenter/comment_spec.rb:42       # single example
+bundle exec rubocop              # lint (part of default rake task — must be clean)
+bundle exec rubocop -a           # autocorrect
+bundle exec exe/commenter        # run the CLI locally
+bin/console                      # interactive prompt
+```
+
+CI (metanorma/ci `generic-rake.yml`) runs `bundle exec rake` on Ruby 3.2/3.4/4.0 across macOS/Ubuntu/Windows. RuboCop offenses fail CI — run `bundle exec rake`, not just rspec, before pushing. `Gemfile.lock` is gitignored; dependencies resolve fresh in CI.
+
+Specs generate XLSX fixtures at runtime via `spec/support/xlsx_builder.rb` (plain rubyzip, no spreadsheet-writing dependency) plus row data in `spec/support/osd_fixtures.rb` — there are no binary fixture files in the repo. Redline DOCX fixtures are built at runtime via `spec/support/redline_docx_builder.rb` (same approach).
+
+## Release
+
+NEVER bump `lib/commenter/version.rb` by hand and never push tags. Releases go through the GHA workflow, which does the version bump, `v*` tag, and gem push itself:
+
+```sh
+gh workflow run release.yml --ref main -f next_version=X.Y.Z
+```
+
+The version number is the maintainer's decision — ask, never infer it from semver reasoning. PRs are rebase-merged.
+
+## What this gem does
+
+Converts ISO comment sheets to structured YAML and back, and syncs comments to GitHub issues:
+
+- **Import**: DOCX (ISO 2012-03 balloting template) or XLSX (ISO Online Standards Development exports) → YAML + schema file. Format auto-detected from extension. Redline DOCX with tracked changes is dispatched to `Parser::TrackChangeDocxParser` via `--format redline`.
+- **Fill**: YAML → filled DOCX comment sheet (`data/iso_comment_template_2012-03.docx`), optional status-based cell shading.
+- **GitHub round-trip**: `github-create` makes issues from YAML via Liquid templates; `github-retrieve` pulls `> **OBSERVATION:**` blockquotes from closed issues back into the YAML's observations field.
+
+Plain text only — formulas/images/complex formatting are unsupported (docx gem limitation).
+
+## Architecture
+
+Core flow: `Parser` → `CommentSheet` (metadata + `Comment` objects) → YAML / DOCX / GitHub issues.
+
+- `Commenter::Comment` / `Commenter::CommentSheet` — data model. `Comment` carries the common fields plus optional OSD-specific fields (`user_name`, `resolution_status`, `motivation`, etc.) and a `github` sub-hash tracking issue state. Comment types: short codes (`ge`/`te`/`ed`) are expanded to full names (`general`/`technical`/`editorial`) when a `Comment` is loaded; YAML output stores the expanded form. The sheet's `version` field (`"2012-03"` vs `"osd"`) selects the output schema.
+- `Commenter::Parser` — dispatches by format: `.docx` parsed inline with the `docx` gem; `.xlsx` delegated to `Parser::OsdXlsxParser` (uses `roo`); `redline` delegated to `Parser::TrackChangeDocxParser`.
+- `Parser::OsdXlsxParser` — auto-detects two OSD export variants by header row ("resolved" 17-col starting `Comment ID`; "unresolved" 15-col starting `User name`), extracts metadata (date/reference/stage/titles) from header rows 1–2, maps columns by header name into `Comment` attributes, and synthesizes `observations` from `resolution_status` + `motivation`.
+- `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 (`lib/commenter/github_integration.rb`) — two classes with parallel structure: `GitHubIssueCreator` (`github-create`) and `GitHubIssueRetriever` (`github-retrieve`). Each loads its own config YAML and Octokit client, and rewrites the comments YAML in place after the run. Duplicate detection searches issue titles for a unique ID rendered from a configurable Liquid `unique_id` template (stage-aware by default: `[DIS] GB-001`), so the same comment ID at different ballot stages creates separate issues.
+- `Commenter::Cli` (`lib/commenter/cli.rb`) — Thor CLI with subcommands `import`, `fill`, `github-create`, `github-retrieve`.
+
+### Schemas
+
+`schema/iso_comment_2012-03.yaml` and `schema/iso_comment_osd.yaml` are JSON-Schema-style files for IDE validation. `import` copies the matching schema (based on sheet version) into the schema dir and stamps the YAML header with a `yaml-language-server` reference. When the data model changes, update the corresponding schema file.
+
+### Templates
+
+`data/github_issue_title_template.liquid` and `data/github_issue_body_template.liquid` render issue titles/bodies; both are user-overridable via config. See README.adoc for the full variable list.
+
+## Conventions
+
+- Ruby style: double-quoted strings (enforced by RuboCop).
+- `data/` files (DOCX template, Liquid templates, sample config) are shipped with the gem and loaded relative to `__dir__` — do not treat them as disposable.
+- Testing GitHub integration: use `--dry-run` with `GITHUB_TOKEN=dummy_token` — exercises template rendering without API calls.
+- `sig/commenter.rbs` is a minimal stub; RBS coverage is not currently maintained.

data/README.adoc

@@ -7,14 +7,20 @@ image:https://img.shields.io/github/commits-since/metanorma/commenter/latest.svg
 
 == Purpose
 
-Commenter is a Ruby gem for working with ISO comment sheets in DOCX format.
+Commenter is a Ruby gem for working with ISO comment sheets in DOCX and XLSX
+format.
 
 It provides utilities for parsing, manipulating, and serializing ISO comment
-data, converting between DOCX and structured YAML with schema validation.
+data, converting between DOCX/XLSX and structured YAML with schema validation.
 
-The format is taken from:
+The supported input formats are:
 
 * "ISO/IEC/CEN/CENELEC electronic balloting commenting template/version 2012-03"
+  (DOCX)
+* ISO Online Standards Development (OSD) XLSX exports (resolved and unresolved
+  comment sheets)
+* Redlined Word documents containing tracked changes (e.g. ISO/CS editor
+  redlines), imported with `--format redline`
 
 This gem only supports plain text comment extraction and filling. Only use this
 to handle plain text comments and resolutions.
@@ -49,19 +55,49 @@ $ gem install commenter
 
 == Usage
 
-=== Importing comments from DOCX
+=== Importing comments
 
-Convert an ISO comment sheet DOCX file to structured YAML:
+Convert an ISO comment sheet (DOCX or XLSX) to structured YAML.
+The format is auto-detected from the file extension; redline DOCX must be
+selected explicitly with `--format redline` because the extension cannot
+distinguish a redline from a comment sheet.
 
 [source,shell]
 ----
+# From DOCX (ISO 2012-03 template or OSD DOCX export)
 $ commenter import "ISO 80000-2 review comments.docx" -o comments.yaml
+
+# From XLSX (ISO OSD resolved comment export)
+$ commenter import "91855-Comments-resolved.xlsx" -o comments.yaml
+
+# From XLSX (ISO OSD comments-only export)
+$ commenter import "ISO 5843-6-Comments.xlsx" -o comments.yaml
+
+# From a redlined DOCX with tracked changes (ISO/CS editor redline)
+$ commenter import "ISO_DIS 2533 Enquiry Trackchange Word.docx" --format redline \
+    --body CS --document "ISO 2533:2026" --stage DIS \
+    --observations "Accepted. ISO/CS tracked change accepted." \
+    -o comments-cs.yaml
 ----
 
+Each tracked change (`w:ins`, `w:del`, `w:moveFrom`, `w:moveTo`) becomes a
+comment entry whose `proposed_change` renders the change itself
+(`Insert: "..."` / `Delete: "..."` / `Move ...: "..."`) and whose
+`locality.clause` is resolved from the nearest preceding heading (including
+sub-clauses such as `4.2.1` and `Annex A`), with `locality.element` resolved
+from the nearest `Table`/`Figure`/`Formula`/`NOTE` reference in the same
+clause. Self-closing paragraph-mark markers are skipped because they carry
+no content.
+
+Reviewer comment threads (`w:comment`) are emitted after the track changes
+with `-CNNN` ids: the remark verbatim in `comments`, its instruction
+reworded as the `proposed_change` (a leading "Please " is dropped), and
+empty `observations` for the document owner to draft.
+
 This will create two files:
 
 `comments.yaml`:: The structured comment data
-`schema/iso_comment_2012-03.yaml`:: The YAML schema for validation
+`schema/iso_comment_2012-03.yaml` or `schema/iso_comment_osd.yaml`:: The YAML schema for validation (selected automatically based on input format)
 
 ==== Import options
 
@@ -75,6 +111,15 @@ Options:
 `-o, --output FILE`:: Output YAML file (default: comments.yaml)
 `-e, --exclude-observations`:: Skip the observations column
 `--schema-dir DIR`:: Directory for schema file (default: schema)
+`--format FORMAT`:: Force input format (`docx`, `xlsx` or `redline`; auto-detected by default)
+`--sheet NAME`:: XLSX: sheet name to parse (default: first sheet)
+`--resolved-only`:: XLSX: use resolved comments sheet only
+`--unresolved-only`:: XLSX: use unresolved comments sheet only
+`--body CODE`:: Redline: member body code for comment IDs (default: `CS`)
+`--observations TEXT`:: Redline: observations stamped on all track changes
+`--accept-all`:: Redline: stamp `Accepted. Tracked change accepted.` on all track changes (an explicit `--observations` wins)
+`--document ID`:: Redline: document identifier (e.g. `ISO 2533:2026`)
+`--stage STAGE`:: Redline: approval stage (e.g. `DIS`)
 
 ==== Metadata (extraction limitation)
 
@@ -118,7 +163,7 @@ comments:
       line_number:
       clause: "_whole document"
       element:
-    type: ge
+    type: general
     comments: |
       The document should include more examples
       to clarify the implementation requirements.
@@ -134,7 +179,7 @@ comments:
       line_number: "45"
       clause: "5.2.1"
       element: "Table 3"
-    type: te
+    type: technical
     comments: |
       The values in Table 3 appear to be
       inconsistent with the formula in 5.1.
@@ -455,7 +500,7 @@ comments:
     locality:
       clause: "5.2.1"
       element: "Table 3"
-    type: te
+    type: technical
     comments: "The values in Table 3 appear inconsistent..."
     proposed_change: "Correct the values in column 2..."
     observations: ""
@@ -530,12 +575,17 @@ The comment types are defined as follows:
 `te`:: Technical comment
 `ed`:: Editorial comment
 
+NOTE: In generated YAML, types are stored in expanded form (`general`,
+`technical`, `editorial`). Short codes are accepted as input anywhere and are
+expanded when the comment is loaded.
+
 === Workflow integration
 
 [source,mermaid]
 ----
 flowchart LR
-    A[ISO Comment Sheet DOCX] --> B[commenter import]
+    A1[ISO Comment Sheet DOCX] --> B[commenter import]
+    A2[ISO OSD XLSX export] --> B
     B --> C[YAML + Schema]
     C --> D[commenter github-create]
     D --> E[YAML + GitHub Info]
@@ -566,6 +616,8 @@ recognized and applied to the observations column:
 
 == Data model
 
+=== ISO 2012-03 template (DOCX)
+
 The comment structure follows this schema:
 
 [source,yaml]
@@ -593,14 +645,61 @@ comments:           # Array of comment objects
       updated_at: string      # ISO 8601 timestamp (optional)
 ----
 
+=== ISO OSD format (XLSX)
+
+The OSD format includes additional metadata and resolution fields extracted from
+the ISO Online Standards Development platform:
+
+[source,yaml]
+----
+version: "osd"           # OSD format identifier
+date: string             # Date from XLSX header (auto-extracted)
+document: string         # Document reference, e.g. "ISO/DIS 5843-6(en)"
+project: string          # Project name (auto-extracted)
+stage: string            # Stage: WD, CD, DIS, FDIS, PRF, PUB (auto-extracted)
+title_en: string         # Document title in English (auto-extracted)
+title_fr: string         # Document title in French (auto-extracted)
+comments:
+  - id: string           # Comment ID (numeric from OSD)
+    body: string         # User name / member body
+    locality:
+      clause: string     # Clause number
+      element: string    # Clause title
+    type: "ge" | "te" | "ed"
+    comments: string     # Comment text
+    proposed_change: string
+    observations: string # Built from resolution_status + motivation
+    user_name: string         # OSD user name
+    comment_type: string      # Subtype: Editorial, General, Technical
+    resolution_status: string # Accepted, Partially accepted, Rejected, etc.
+    resolution_date: string   # Date resolved
+    feedbacks: string         # Discussion replies
+    motivation: string        # Resolution justification
+    created_date: string      # Date comment was created
+    stage_code: string        # ISO stage code (e.g. "40.20")
+----
+
+The OSD XLSX format comes in two variants, both auto-detected:
+
+*Resolved*: 17 columns starting with `Comment ID`, includes resolution data
+(`Resolution status`, `Motivation`, `Resolution Date`, `Stage code`)
+
+*Unresolved/comments-only*: 15 columns starting with `User name`, includes
+`Comment type`, `Comment/Motivation`, `Replies`, `Comment number`
+
 
 == Schema validation
 
-Each exported YAML file includes a schema reference for IDE support:
+Each exported YAML file includes a schema reference for IDE support.
+The schema is selected automatically based on the input format:
 
 [source,yaml]
 ----
+# For ISO 2012-03 DOCX imports:
 # yaml-language-server: $schema=schema/iso_comment_2012-03.yaml
+
+# For ISO OSD XLSX imports:
+# yaml-language-server: $schema=schema/iso_comment_osd.yaml
 ----
 
 This enables:
@@ -695,7 +794,8 @@ The gem is organized into several key components:
 
 `Commenter::Comment`:: Represents individual comments with locality, type, and content
 `Commenter::CommentSheet`:: Container for multiple comments with metadata
-`Commenter::Parser`:: Handles DOCX parsing and YAML generation
+`Commenter::Parser`:: Handles DOCX and XLSX parsing with auto-detection
+`Commenter::Parser::OsdXlsxParser`:: Parses ISO OSD XLSX exports (resolved and unresolved variants)
 `Commenter::Filler`:: Fills DOCX templates with comment data
 `Commenter::GitHubIssueCreator`:: Creates GitHub issues from comments
 
@@ -703,7 +803,7 @@ The gem is organized into several key components:
 
 `Commenter::Cli`:: Thor-based command-line interface with subcommands:
 
-** `import` - Convert DOCX to YAML
+** `import` - Convert DOCX or XLSX to YAML
 ** `fill` - Fill DOCX template from YAML
 ** `github-create` - Create GitHub issues from comments
 ** `github-retrieve` - Retrieve observations from GitHub issues
@@ -714,7 +814,8 @@ The gem is organized into several key components:
 * `data/github_issue_title_template.liquid` - GitHub issue title template
 * `data/github_issue_body_template.liquid` - GitHub issue body template
 * `data/github_config_sample.yaml` - Sample GitHub configuration
-* `schema/iso_comment_2012-03.yaml` - YAML schema for validation
+* `schema/iso_comment_2012-03.yaml` - YAML schema for ISO 2012-03 validation
+* `schema/iso_comment_osd.yaml` - YAML schema for ISO OSD format validation
 
 === Debugging
 

data/commenter.gemspec

@@ -12,8 +12,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Ribose"]
   spec.email = ["open.source@ribose.com"]
 
-  spec.summary = "Library to work with ISO comment sheets in DOCX format."
-  spec.description = "Convert between ISO comment sheet DOCX and structured YAML with schema validation."
+  spec.summary = "Library to work with ISO comment sheets in DOCX and XLSX formats."
+  spec.description = "Convert between ISO comment sheets (DOCX and XLSX) and structured YAML with schema validation."
   spec.homepage = "https://github.com/metanorma/commenter"
   spec.license = "BSD-2-Clause"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
@@ -35,5 +35,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dotenv", "~> 2.8"
   spec.add_dependency "liquid", "~> 5.0"
   spec.add_dependency "octokit", "~> 6.0"
+  spec.add_dependency "roo", ">= 2.10"
   spec.add_dependency "thor", "~> 1.0"
 end

data/lib/commenter/cli.rb

@@ -3,43 +3,49 @@
 require "thor"
 require "yaml"
 require "fileutils"
-require "commenter/parser"
-require "commenter/filler"
-require "commenter/github_integration"
+require "commenter"
 
 module Commenter
   class Cli < Thor
-    desc "import INPUT.docx", "Convert DOCX comment sheet to YAML"
+    desc "import INPUT", "Convert comment sheet (DOCX or XLSX) or redline DOCX to YAML"
     option :output, type: :string, aliases: :o, default: "comments.yaml", desc: "Output YAML file"
     option :exclude_observations, type: :boolean, aliases: :e, desc: "Exclude observations column"
     option :schema_dir, type: :string, default: "schema", desc: "Directory for schema file"
-    def import(input_docx)
+    option :format, type: :string, desc: "Force input format (docx, xlsx or redline)"
+    option :sheet, type: :string, desc: "XLSX sheet name to parse (default: first sheet)"
+    option :resolved_only, type: :boolean, desc: "XLSX: use resolved comments sheet only"
+    option :unresolved_only, type: :boolean, desc: "XLSX: use unresolved comments sheet only"
+    option :body, type: :string, desc: "Redline: member body code for comment IDs (default: CS)"
+    option :observations, type: :string, desc: "Redline: observations stamped on all track changes"
+    option :accept_all, type: :boolean, desc: "Redline: stamp 'Accepted. Tracked change accepted.' on all track changes"
+    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 DOCX file
+      # Parse the input file
       parser = Parser.new
-      comment_sheet = parser.parse(input_docx, options)
+      comment_sheet = parser.parse(input_file, options)
 
       # Write the YAML data file with schema reference
-      yaml_content = generate_yaml_with_header(comment_sheet.to_yaml_h, schema_dir)
-      File.write(output_yaml, yaml_content)
+      File.write(output_yaml, comment_sheet.to_yaml_document(schema_dir))
 
       # Copy schema file to output directory
-      schema_source = File.join(__dir__, "../../schema/iso_comment_2012-03.yaml")
-      schema_target = File.join(schema_dir, "iso_comment_2012-03.yaml")
+      schema_name = comment_sheet.schema_name
+      schema_source = File.join(__dir__, "../../schema/#{schema_name}")
+      schema_target = File.join(schema_dir, schema_name)
 
       # Only copy if source and target are different
-      unless File.expand_path(schema_source) == File.expand_path(schema_target)
-        FileUtils.cp(schema_source,
-                     schema_target)
-      end
+      FileUtils.cp(schema_source, schema_target) unless File.expand_path(schema_source) == File.expand_path(schema_target)
 
-      puts "Converted #{input_docx} to #{output_yaml}"
-      puts "Schema file created at #{schema_target}"
+      puts "Converted #{input_file} to #{output_yaml}"
+      puts "  Version: #{comment_sheet.version}"
+      puts "  Comments: #{comment_sheet.comments.length}"
+      puts "  Schema: #{schema_target}"
     end
 
     desc "fill INPUT.yaml", "Fill DOCX template from YAML comments"
@@ -206,13 +212,5 @@ module Commenter
     def self.exit_on_failure?
       true
     end
-
-    private
-
-    def generate_yaml_with_header(data, schema_dir)
-      schema_path = File.join(schema_dir, "iso_comment_2012-03.yaml")
-      header = "# yaml-language-server: $schema=#{schema_path}\n\n"
-      header + data.to_yaml
-    end
   end
 end

data/lib/commenter/comment.rb

@@ -2,7 +2,9 @@
 
 module Commenter
   class Comment
-    attr_accessor :id, :body, :locality, :type, :comments, :proposed_change, :observations, :github
+    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
@@ -11,20 +13,25 @@ module Commenter
       @id = attrs[:id]
       @body = attrs[:body]
       @locality = symbolize_keys(attrs[:locality] || {})
-      @type = expand_comment_type(attrs[:type])
+      @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]
     end
 
     def expand_comment_type(type)
-      case type&.downcase
-      when "ge" then "general"
-      when "te" then "technical"
-      when "ed" then "editorial"
-      else type
-      end
+      CommentType.full_name(type)
     end
 
     def line_number
@@ -117,6 +124,14 @@ module Commenter
         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

data/lib/commenter/comment_sheet.rb

@@ -4,7 +4,7 @@ require_relative "comment"
 
 module Commenter
   class CommentSheet
-    attr_accessor :version, :date, :document, :project, :stage, :comments
+    attr_accessor :version, :date, :document, :project, :stage, :comments, :title_en, :title_fr
 
     def initialize(attributes = {})
       # Normalize input to symbols
@@ -15,6 +15,8 @@ module Commenter
       @document = attrs[:document]
       @project = attrs[:project]
       @stage = attrs[:stage]
+      @title_en = attrs[:title_en]
+      @title_fr = attrs[:title_fr]
       @comments = (attrs[:comments] || []).map { |c| c.is_a?(Comment) ? c : Comment.from_hash(c) }
     end
 
@@ -29,12 +31,26 @@ module Commenter
         document: @document,
         project: @project,
         stage: @stage,
+        title_en: @title_en,
+        title_fr: @title_fr,
         comments: @comments.map(&:to_h)
       }
     end
 
     def to_yaml_h
-      stringify_keys(to_h.merge(comments: @comments.map(&:to_yaml_h)))
+      hash = to_h.merge(comments: @comments.map(&:to_yaml_h))
+      # Remove nil-valued keys for cleaner YAML output
+      hash.delete(:title_en) if hash[:title_en].nil?
+      hash.delete(:title_fr) if hash[:title_fr].nil?
+      stringify_keys(hash)
+    end
+
+    def schema_name
+      version == "osd" ? "iso_comment_osd.yaml" : "iso_comment_2012-03.yaml"
+    end
+
+    def to_yaml_document(schema_dir = "schema")
+      "# yaml-language-server: $schema=#{File.join(schema_dir.to_s, schema_name)}\n\n#{to_yaml_h.to_yaml}"
     end
 
     def self.from_hash(hash)

data/lib/commenter/comment_type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Single home for the comment type vocabulary: short codes (ge/te/ed) and
+  # their expanded names (general/technical/editorial). Unrecognized values
+  # pass through unchanged; display_name capitalizes recognized types.
+  module CommentType
+    FULL_NAMES = {
+      "ge" => "general",
+      "te" => "technical",
+      "ed" => "editorial"
+    }.freeze
+
+    CODES = FULL_NAMES.invert.freeze
+
+    DISPLAY_NAMES = FULL_NAMES.each_with_object({}) do |(code, full), display|
+      display[code] = full.capitalize
+      display[full] = full.capitalize
+    end.freeze
+
+    module_function
+
+    def code(type)
+      CODES.fetch(type.to_s.strip.downcase) { type&.to_s&.strip }
+    end
+
+    def full_name(type)
+      FULL_NAMES.fetch(type.to_s.strip.downcase) { type&.to_s&.strip }
+    end
+
+    def display_name(type)
+      DISPLAY_NAMES.fetch(type.to_s.strip.downcase) { type || "Unknown" }
+    end
+  end
+end