commenter 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 117378c9e464895bd51cb22c7b17e8793c256923b5985a88e0f1f6baa3d317b9
+  data.tar.gz: 97ccf63eb89b9f2e91c1620801ed9c297af6ccf62c78bcd60400916389491f85
+SHA512:
+  metadata.gz: 9ee87e7b5aa0e5d4129d3466fd4d322820fbcd5436a63d498ce39f9fa1a58dea3cd0c3967a74117c3e30573a0f3c778d5b80fd39351f4bbb851fc2fb43f76519
+  data.tar.gz: 7beffdc600b9305eb1ced613ed81e62d4feecd15e44a118727ab50c89a8089f7477e3b30e5a8db9f70c106a5b10484bbcfacdf4a66c009b7b7d2e68ebef01e0d

data/.github/workflows/rake.yml

@@ -0,0 +1,15 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: rake
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        required: true
+        default: 'skip'
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
+

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in commenter.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/README.adoc

@@ -0,0 +1,284 @@
+= Commenter: ISO Comment Sheet Processor
+
+image:https://img.shields.io/gem/v/commenter.svg["Gem Version", link="https://rubygems.org/gems/commenter"]
+image:https://github.com/metanorma/commenter/actions/workflows/rake.yml/badge.svg["Build Status", link="https://github.com/metanorma/commenter/actions/workflows/rake.yml"]
+image:https://img.shields.io/github/issues-pr-raw/metanorma/commenter.svg["Pull Requests", link="https://github.com/metanorma/commenter/pulls"]
+image:https://img.shields.io/github/commits-since/metanorma/commenter/latest.svg["Commits since latest",link="https://github.com/metanorma/commenter/releases"]
+
+== Purpose
+
+Commenter is a Ruby gem for working with ISO comment sheets in DOCX format.
+
+It provides utilities for parsing, manipulating, and serializing ISO comment
+data, converting between DOCX and structured YAML with schema validation.
+
+The format is taken from:
+
+* "ISO/IEC/CEN/CENELEC electronic balloting commenting template/version 2012-03"
+
+This gem only supports plain text comment extraction and filling. Only use this
+to handle plain text comments and resolutions.
+
+NOTE: Mathematical formulas, images, and complex formatting are not supported
+due to limitations in the underlying docx gem. Comments containing such elements
+will have their text content extracted, but formatting and embedded objects will
+be lost.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'commenter'
+----
+
+And then execute:
+
+[source,shell]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+$ gem install commenter
+----
+
+== Usage
+
+=== Importing comments from DOCX
+
+Convert an ISO comment sheet DOCX file to structured YAML:
+
+[source,shell]
+----
+$ commenter import "ISO 80000-2 review comments.docx" -o comments.yaml
+----
+
+This will create two files:
+
+`comments.yaml`:: The structured comment data
+`schema/iso_comment_2012-03.yaml`:: The YAML schema for validation
+
+==== Import options
+
+[source,shell]
+----
+$ commenter import input.docx -o comments.yaml --exclude-observations --schema-dir schemas/
+----
+
+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)
+
+==== 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]).
+
+The generated YAML will have empty metadata fields that you can manually
+populate:
+
+[source,yaml]
+----
+# yaml-language-server: $schema=schema/iso_comment_2012-03.yaml
+
+version: "2012-03"
+date: ""           # Manually add: e.g., "2023-04-25"
+document: ""       # Manually add: e.g., "ISO 80000-2:2019"
+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
+
+[source,yaml]
+----
+# yaml-language-server: $schema=schema/iso_comment_2012-03.yaml
+
+version: "2012-03"
+date: "2023-04-25"
+document: "ISO 80000-2:2019"
+project: "Mathematics review"
+comments:
+  - id: DE-001
+    body: DE
+    locality:
+      line_number:
+      clause: "_whole document"
+      element:
+    type: ge
+    comments: |
+      The document should include more examples
+      to clarify the implementation requirements.
+    proposed_change: |
+      Add section 4.5 with practical examples
+      showing typical use cases.
+    observations: |
+      Accepted. Examples will be added in the
+      next revision.
+  - id: US-002
+    body: US
+    locality:
+      line_number: "45"
+      clause: "5.2.1"
+      element: "Table 3"
+    type: te
+    comments: |
+      The values in Table 3 appear to be
+      inconsistent with the formula in 5.1.
+    proposed_change: |
+      Correct the values in column 2 of Table 3
+      to match the calculation method.
+    observations:
+----
+
+=== 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.
+
+The base template is the ISO comment sheet template located at
+`data/iso_comment_template_2012-03.docx`. You can also provide a custom
+template file using the `--template` option.
+
+Syntax:
+
+[source,shell]
+----
+$ commenter fill comments.yaml -o filled_comments.docx
+----
+
+==== Fill Options
+
+Options:
+
+`-o, --output FILE`:: Output DOCX file (default: filled_comments.docx)
+`-t, --template FILE`:: Custom template file
+`-s, --shading`:: Apply status-based cell shading (FIXME: not yet supported)
+
+=== Comment ID format
+
+Typical comment IDs follow the pattern: `{MB/NC}-{number}` or `{MB/NC}-{org_id}-{seq_id}`
+
+[example]
+====
+* `US-001` - First comment from ANSI (US)
+* `DE-01-002` - Second comment from organization 01 within DIN (DE)
+* `**-001` - First comment from ISO secretariat
+
+Where:
+
+* `US` = ANSI (American National Standards Institute)
+* `DE` = DIN (Deutsches Institut für Normung)
+* `**` = ISO Secretariat
+* `CC` = CalConnect
+====
+
+=== Comment Types
+
+The comment types are defined as follows:
+
+`ge`:: General comment
+`te`:: Technical comment
+`ed`:: Editorial comment
+
+=== Workflow integration
+
+[source,mermaid]
+----
+flowchart LR
+    A[ISO Comment Sheet DOCX] --> B[commenter import]
+    B --> C[YAML + Schema]
+    C --> D[Version Control, e.g. post to GitHub issues]
+    D --> E[Review Process]
+    E --> F[commenter fill, e.g. pull from resolved GitHub issues]
+    F --> G[Updated DOCX]
+    G --> H[ISO Secretariat]
+----
+
+=== Shading Rules
+
+WARNING: Cell shading is not currently implemented.
+
+The `--shading` option is accepted but will only print status information to the
+console.
+
+When the `--shading` option is used, the following status patterns would be
+recognized:
+
+|===
+| Status Pattern | Intended Color | Hex Code | Example
+
+| `accept(ed)?` | Green | #92D050 | "Accepted"
+| `awm\|accept with modifications` | Olive Green | #C4D79B | "Accept with modifications"
+| `noted` | Blue | #8DB4E2 | "Noted"
+| `reject(ed)?` | Pink | #FF99CC | "Rejected"
+| `todo` | Diagonal stripes | #D9D9D9 | "TODO: Review"
+
+|===
+
+
+== Data model
+
+The comment structure follows this schema:
+
+[source,yaml]
+----
+version: "2012-03"  # Template version
+date: string | null # Comment sheet date (manually populated)
+document: string | null # Document being reviewed (manually populated)
+project: string | null  # Project name (manually populated)
+comments:           # Array of comment objects
+  - id: string      # Comment identifier
+    body: string    # Member body abbreviation
+    locality:       # Location information
+      line_number: string | null
+      clause: string
+      element: string | null
+    type: "ge" | "te" | "ed"  # Comment type
+    comments: string          # Comment text
+    proposed_change: string   # Proposed solution
+    observations: string | null  # Secretariat observations (optional)
+----
+
+
+== Schema validation
+
+Each exported YAML file includes a schema reference for IDE support:
+
+[source,yaml]
+----
+# yaml-language-server: $schema=schema/iso_comment_2012-03.yaml
+----
+
+This enables:
+
+* Auto-completion in VS Code and other editors
+* Real-time validation
+* Inline documentation
+
+
+== Copyright
+
+This gem is developed, maintained and funded by
+https://www.ribose.com[Ribose Inc.]
+
+
+== License
+
+The gem is available as open source under the terms of the
+https://opensource.org/licenses/BSD-2-Clause[2-Clause BSD License].
+

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/commenter.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/commenter/version"
+
+all_files_in_git = Dir.chdir(File.expand_path(__dir__)) do
+  `git ls-files -z`.split("\x0")
+end
+
+Gem::Specification.new do |spec|
+  spec.name = "commenter"
+  spec.version = Commenter::VERSION
+  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.homepage = "https://github.com/metanorma/commenter"
+  spec.license = "BSD-2-Clause"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = all_files_in_git
+               .reject { |f| f.match(%r{\A(?:test|features|bin|\.)/}) }
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "docx", "~> 0.8"
+  spec.add_dependency "thor", "~> 1.0"
+end