commenter 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 117378c9e464895bd51cb22c7b17e8793c256923b5985a88e0f1f6baa3d317b9
-  data.tar.gz: 97ccf63eb89b9f2e91c1620801ed9c297af6ccf62c78bcd60400916389491f85
+  metadata.gz: 31fa0d4ee056c833d9f2b329d994e5d6151e3430426e6d4f02dfca4c670d0c18
+  data.tar.gz: b459baef384850cfa84cfb22c48212771ee57fa0e11cbd803c1db33dfb44aae2
 SHA512:
-  metadata.gz: 9ee87e7b5aa0e5d4129d3466fd4d322820fbcd5436a63d498ce39f9fa1a58dea3cd0c3967a74117c3e30573a0f3c778d5b80fd39351f4bbb851fc2fb43f76519
-  data.tar.gz: 7beffdc600b9305eb1ced613ed81e62d4feecd15e44a118727ab50c89a8089f7477e3b30e5a8db9f70c106a5b10484bbcfacdf4a66c009b7b7d2e68ebef01e0d
+  metadata.gz: 989ff9a26a63210438385658edaee8a0d94a35c9d80916dfefe89575ce739f9efc75bdcc372d737a955de236fdefdeaaca0be65146363dea5833ac280cc97cdb
+  data.tar.gz: 5cdcb2b0ca204b6e419d009f45eeb6dfd4867c7eb51196a04ad2499c7c64e5cb5288b85522f031a7a823e9242c3e8edec771d7c2d1bb8f5f9b079df7e86cc54b

data/.github/workflows/release.yml

@@ -22,4 +22,3 @@ jobs:
     secrets:
       rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
-

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   TargetRubyVersion: 3.0
 

data/.rubocop_todo.yml

@@ -0,0 +1,79 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# 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
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'commenter.gemspec'
+
+# Offense count: 1
+Lint/NonLocalExitFromIterator:
+  Exclude:
+    - 'lib/commenter/filler.rb'
+
+# Offense count: 15
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 78
+
+# Offense count: 10
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 171
+
+# Offense count: 5
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 231
+
+# Offense count: 8
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 22
+
+# Offense count: 22
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 53
+
+# Offense count: 8
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 22
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/commenter/comment.rb'
+
+# Offense count: 7
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/commenter/cli.rb'
+    - 'lib/commenter/comment.rb'
+    - 'lib/commenter/comment_sheet.rb'
+    - 'lib/commenter/filler.rb'
+    - 'lib/commenter/github_integration.rb'
+    - 'lib/commenter/parser.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 138

data/README.adoc

@@ -161,13 +161,348 @@ Syntax:
 $ commenter fill comments.yaml -o filled_comments.docx
 ----
 
-==== Fill Options
+==== 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)
+`-s, --shading`:: Apply status-based cell shading
+
+=== GitHub Integration
+
+==== Overview
+
+The commenter gem provides comprehensive GitHub integration for collaborative comment review and tracking. The workflow consists of two main commands:
+
+* `github-create` - Creates GitHub issues from comments and tracks them in YAML
+* `github-retrieve` - Retrieves final observations from closed GitHub issues
+
+==== Creating GitHub issues from comments
+
+===== Basic usage
+
+[source,shell]
+----
+$ commenter github-create --config github_config.yaml comments.yaml
+----
+
+This command creates GitHub issues for each comment and automatically updates the YAML file with GitHub issue information (issue numbers, URLs, status, timestamps).
+
+==== Configuration file
+
+Create a GitHub configuration file to specify repository, authentication, and
+issue settings:
+
+[source,yaml]
+----
+github:
+  repository: "owner/repo-name"
+  token: "ghp_xxxxxxxxxxxx"
+  milestone:
+    name: "ISO 80000-2 DIS Review"
+  default_labels: ["comment-review", "iso-standard"]
+  stage_labels:
+    WD: ["working-draft"]
+    DIS: ["draft-international-standard"]
+----
+
+A sample configuration file is provided at `data/github_config_sample.yaml`.
+
+==== Issue templates
+
+===== General
+
+The gem uses Liquid templates to format GitHub issue titles and bodies. Default
+templates are provided, but you can customize them.
+
+===== Title template variables
+
+The title template (`data/github_issue_title_template.liquid`) supports these variables:
+
+* `stage` - Approval stage (WD/CD/DIS/FDIS/PRF/PUB)
+* `document` - Document identifier
+* `comment_id` - Comment identifier
+* `brief_summary` - Generated summary combining locality and description
+* `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
+
+The body template (`data/github_issue_body_template.liquid`) supports all title
+variables plus:
+
+* `comments` - Full comment text
+* `proposed_change` - Proposed change text
+* `observations` - Secretariat observations
+* `has_observations` - Boolean for conditional rendering
+* `has_proposed_change` - Boolean for conditional rendering
+* `project` - Project name
+* `date` - Comment sheet date
+* `version` - Template version
+* `type_full_name` - Full comment type name (General/Technical/Editorial)
+* `locality_summary` - Formatted locality string
+
+===== Custom templates
+
+[example]
+====
+Create custom templates and reference them in your configuration:
+
+[source,yaml]
+----
+github:
+  templates:
+    title: "custom_title.liquid"
+    body: "custom_body.liquid"
+    unique_id: "[{{ stage | upcase }}] {{ comment_id }}"  # Optional: customize unique ID
+----
+====
+
+==== Command options
+
+* `-c, --config FILE` - GitHub configuration YAML file (required)
+* `--stage STAGE` - Override approval stage
+* `--milestone NAME` - Override milestone name
+* `--assignee HANDLE` - Override assignee GitHub handle
+* `--title-template FILE` - Custom title template
+* `--body-template FILE` - Custom body template
+* `--dry-run` - Preview issues without creating them
+
+==== Examples
+
+[example]
+====
+Create issues with custom stage:
+
+[source,shell]
+----
+$ commenter github-create --config github_config.yaml --stage DIS comments.yaml
+----
+
+Preview issues before creation:
+
+[source,shell]
+----
+$ commenter github-create --config github_config.yaml --dry-run comments.yaml
+----
+====
+
+==== Security considerations
+
+For security reasons, it is recommended to use the `GITHUB_TOKEN` environment
+variable instead of storing the token in the configuration file.
+
+[source,shell]
+----
+$ export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+$ commenter github comments.yaml --config github_config.yaml
+----
+
+==== Duplicate detection
+
+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
+
+===== Basic usage
+
+After GitHub issues have been created and reviewed, use the `github-retrieve` command to extract final observations from closed issues:
+
+[source,shell]
+----
+$ commenter github-retrieve --config github_config.yaml comments.yaml
+----
+
+This command:
+
+* Reads GitHub issue information from the YAML file (no searching required)
+* Fetches observations from closed GitHub issues only
+* Updates the same YAML file with extracted observations
+* Preserves all existing comment data
+
+===== Magic comment syntax
+
+To provide official observations in GitHub issues, use markdown blockquotes with special markers:
+
+[source,markdown]
+----
+> **OBSERVATION:**
+> Accepted. The proposed change will be included in clause 5.2.1 of the next revision.
+> Technical details have been reviewed and approved by the working group.
+----
+
+Alternative shorter syntax:
+
+[source,markdown]
+----
+> **COMMENTER OBSERVATION:**
+> Noted. This will be considered for future revisions.
+----
+
+===== Retrieval options
+
+* `-c, --config FILE` - GitHub configuration YAML file (required)
+* `-o, --output FILE` - Output YAML file (default: update original)
+* `--include-open` - Include observations from open issues (not recommended)
+* `--dry-run` - Preview observations without updating YAML
+
+===== Examples
+
+[example]
+====
+Preview observations before updating:
+
+[source,shell]
+----
+$ commenter github-retrieve --config github_config.yaml --dry-run comments.yaml
+----
+
+Save to new file instead of updating original:
+
+[source,shell]
+----
+$ commenter github-retrieve --config github_config.yaml -o final_comments.yaml comments.yaml
+----
+
+Include observations from open issues:
+
+[source,shell]
+----
+$ commenter github-retrieve --config github_config.yaml --include-open comments.yaml
+----
+====
+
+===== Enhanced YAML structure
+
+After using `github-create`, your YAML file will include GitHub integration information:
+
+[source,yaml]
+----
+comments:
+  - id: US-001
+    body: US
+    locality:
+      clause: "5.2.1"
+      element: "Table 3"
+    type: te
+    comments: "The values in Table 3 appear inconsistent..."
+    proposed_change: "Correct the values in column 2..."
+    observations: ""
+    github:
+      issue_number: 123
+      issue_url: "https://github.com/owner/repo/issues/123"
+      status: "open"
+      created_at: "2024-01-15T10:30:00Z"
+----
+
+After using `github-retrieve` (when the issue is closed):
+
+[source,yaml]
+----
+comments:
+  - id: US-001
+    # ... other fields unchanged ...
+    observations: "Accepted. The proposed change will be included in clause 5.2.1."
+    github:
+      issue_number: 123
+      issue_url: "https://github.com/owner/repo/issues/123"
+      status: "closed"
+      created_at: "2024-01-15T10:30:00Z"
+      updated_at: "2024-01-20T14:45:00Z"
+----
+
+===== Configuration for retrieval
+
+The GitHub configuration file supports retrieval-specific settings:
+
+[source,yaml]
+----
+github:
+  repository: "owner/repo-name"
+  retrieval:
+    # Magic comment markers to look for
+    observation_markers:
+      - "**OBSERVATION:**"
+      - "**COMMENTER OBSERVATION:**"
+
+    # Fallback to last comment if no magic comment found
+    fallback_to_last_comment: true
+
+    # Only retrieve from closed issues (recommended)
+    closed_issues_only: true
+----
+
 
 === Comment ID format
 
@@ -187,7 +522,7 @@ Where:
 * `CC` = CalConnect
 ====
 
-=== Comment Types
+=== Comment types
 
 The comment types are defined as follows:
 
@@ -202,22 +537,20 @@ The comment types are defined as follows:
 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]
+    C --> D[commenter github-create]
+    D --> E[YAML + GitHub Info]
+    E --> F[GitHub Issues + Review Process]
+    F --> G[commenter github-retrieve]
+    G --> H[YAML + Observations]
+    H --> I[commenter fill]
+    I --> J[Final DOCX]
+    J --> K[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.
+=== Shading rules
 
-When the `--shading` option is used, the following status patterns would be
-recognized:
+When the `--shading` option is used, the following status patterns are
+recognized and applied to the observations column:
 
 |===
 | Status Pattern | Intended Color | Hex Code | Example
@@ -252,6 +585,12 @@ comments:           # Array of comment objects
     comments: string          # Comment text
     proposed_change: string   # Proposed solution
     observations: string | null  # Secretariat observations (optional)
+    github:         # GitHub integration information (optional)
+      issue_number: integer   # GitHub issue number
+      issue_url: string       # GitHub issue URL
+      status: "open" | "closed"  # GitHub issue status
+      created_at: string      # ISO 8601 timestamp
+      updated_at: string      # ISO 8601 timestamp (optional)
 ----
 
 
@@ -271,14 +610,164 @@ This enables:
 * Inline documentation
 
 
+== Development
+
+=== Getting started
+
+After checking out the repo, run `bin/setup` to install dependencies:
+
+[source,shell]
+----
+$ git clone https://github.com/metanorma/commenter.git
+$ cd commenter
+$ bin/setup
+----
+
+Then, run `rake spec` to run the tests:
+
+[source,shell]
+----
+$ bundle exec rake spec
+----
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment:
+
+[source,shell]
+----
+$ bin/console
+----
+
+=== Running tests
+
+The gem includes comprehensive test coverage for all major components:
+
+[source,shell]
+----
+# Run all tests
+$ bundle exec rspec
+
+# Run specific test files
+$ bundle exec rspec spec/commenter/comment_spec.rb
+$ bundle exec rspec spec/commenter/comment_sheet_spec.rb
+$ bundle exec rspec spec/commenter/github_integration_spec.rb
+
+# Run tests with coverage
+$ bundle exec rspec --format documentation
+----
+
+=== Testing GitHub integration
+
+To test the GitHub integration features:
+
+1. Create a test repository on GitHub
+2. Generate a personal access token with appropriate permissions
+3. Create a test configuration file:
+
+[source,yaml]
+----
+github:
+  repository: "your-username/test-repo"
+  default_labels: ["test-comment"]
+  default_assignee: "your-username"
+----
+
+4. Test with dry-run mode first:
+
+[source,shell]
+----
+$ GITHUB_TOKEN=your_token bundle exec exe/commenter github test_comments.yaml --config test_config.yaml --dry-run
+----
+
+NOTE: For testing template rendering and dry-run functionality without a real GitHub token, you can use a dummy token:
+
+[source,shell]
+----
+$ GITHUB_TOKEN=dummy_token bundle exec exe/commenter github test_comments.yaml --config test_config.yaml --dry-run
+----
+
+This allows you to test the issue preview functionality, template rendering, and configuration parsing without making actual GitHub API calls.
+
+=== Code structure
+
+The gem is organized into several key components:
+
+==== Core classes
+
+`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::Filler`:: Fills DOCX templates with comment data
+`Commenter::GitHubIssueCreator`:: Creates GitHub issues from comments
+
+==== CLI interface
+
+`Commenter::Cli`:: Thor-based command-line interface with subcommands:
+
+** `import` - Convert DOCX to YAML
+** `fill` - Fill DOCX template from YAML
+** `github-create` - Create GitHub issues from comments
+** `github-retrieve` - Retrieve observations from GitHub issues
+
+==== Templates and configuration
+
+* `data/iso_comment_template_2012-03.docx` - Base DOCX template
+* `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
+
+=== Debugging
+
+Enable debug output for troubleshooting:
+
+[source,shell]
+----
+# Enable verbose output
+$ bundle exec exe/commenter import input.docx --verbose
+
+# Debug GitHub API calls
+$ OCTOKIT_DEBUG=true bundle exec exe/commenter github comments.yaml --config config.yaml --dry-run
+----
+
+=== Troubleshooting
+
+==== Common issues
+
+**DOCX parsing errors**::
+** Ensure the DOCX file follows the ISO comment template format
+** Check for corrupted or password-protected files
+** Verify table structure matches expected format
+
+**GitHub API errors**::
+** Verify your GitHub token has appropriate permissions
+** Check rate limiting if making many requests
+** Ensure repository exists and is accessible
+
+**Template rendering errors**::
+** Validate Liquid template syntax
+** Check that all referenced variables are available
+** Test templates with sample data first
+
+**Schema validation errors**::
+** Ensure YAML follows the required structure
+** Check for missing required fields
+** Validate comment ID format
+
+==== Getting help
+
+* Check the issue tracker on GitHub
+* Review existing test cases for usage examples
+* Run commands with `--help` for detailed options
+* Use `--dry-run` mode to preview operations safely
+
+
 == Copyright
 
 This gem is developed, maintained and funded by
-https://www.ribose.com[Ribose Inc.]
+https://www.ribose.com[Ribose]
 
 
 == 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/commenter.gemspec

@@ -30,6 +30,10 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "base64", "~> 0.1"
   spec.add_dependency "docx", "~> 0.8"
+  spec.add_dependency "dotenv", "~> 2.8"
+  spec.add_dependency "liquid", "~> 5.0"
+  spec.add_dependency "octokit", "~> 6.0"
   spec.add_dependency "thor", "~> 1.0"
 end