prosereflect 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5c6ec18ecdd44c7efaba52819b0763d35c829c7af571ef7b423da2863d29caf
-  data.tar.gz: ed3ed8a65bb95e4dbc89a0e96efe4f2dd4a2c57b0cc7210f6296c03a6b8c5d66
+  metadata.gz: d9f70970efc856c322c1d356262ae1492856c2432d2ed6343b7f00a4b96a97a9
+  data.tar.gz: 4670d12e397d85fa399ea4bd721d0eaa4d35aa24b7425c0bb7e6b61eb057a173
 SHA512:
-  metadata.gz: f736e62b0ef5909c60daebb95b79f29c23be47b76c56edf327adeb4bdf76df1071493def7a5530209cd5a431332f1dfec3a3428453c50c5e3e336873126be238
-  data.tar.gz: 56d78409069b3a61caf41ab36a44494f71b1f2be53e9ef15bd2290fad0eebab31cc3c7a22945b09b05f0dd0f011f65b77f0cc8045fa36230e723750b6796f118
+  metadata.gz: 42bb32f0114a3cb597a65498681177c93345f3ddcff24412a2ba03dd8492b1ec0da306797ada94fac95c984e0f80a63631de555fae2a836b647c8805ab73e0b6
+  data.tar.gz: d6b5dcf22e6d6b0c923c5b35a1dbccecea6e7103af0001428ca567ad8f2333d2f63fe7652149f087b2ea0383beff80afc69e02b09f086f93b5fd51ee7be1dca1

data/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+  repository_dispatch:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: docs
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --verbose --trace --baseurl "${{ steps.pages.outputs.base_path }}"
+        working-directory: docs
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/links.yml

@@ -0,0 +1,97 @@
+name: links
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  link_checker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+        working-directory: docs
+
+    - name: Build site
+      env:
+        JEKYLL_ENV: production
+      run: bundle exec jekyll build --trace
+      working-directory: docs
+
+    - name: Restore lychee cache
+      uses: actions/cache@v4
+      with:
+        path: .lycheecache
+        key: cache-lychee-${{ github.sha }}
+        restore-keys: cache-lychee-
+
+    - name: Check if site was built
+      run: |
+        if [ ! -d "_site" ]; then
+          echo "Error: _site directory not created"
+          exit 1
+        fi
+        echo "Site built successfully"
+        ls -la _site/
+      working-directory: docs
+
+    - name: Link Checker (Built Site)
+      uses: lycheeverse/lychee-action@v2
+      with:
+        args: >-
+          --verbose
+          --no-progress
+          --config lychee.toml
+          --root-dir "$(pwd)/_site"
+          --scheme https,http
+          '_site/**/*.html'
+        fail: true
+        output: link-check-results.md
+        format: markdown
+        workingDirectory: docs
+
+    - name: Upload link check results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: link-check-results
+        path: |
+          docs/link-check-results.md
+        retention-days: 30
+
+    - name: Comment PR with results
+      if: failure() && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          let comment = '## Link Check Failed\n\n';
+
+          if (fs.existsSync('docs/link-check-results.md')) {
+            const results = fs.readFileSync('docs/link-check-results.md', 'utf8');
+            comment += '### Built Site Results\n\n' + results + '\n\n';
+          }
+
+          comment += '\n---\n\n*Please fix the broken links and push a new commit.*';
+
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: comment
+          });

data/.gitignore

@@ -10,3 +10,7 @@
 # rspec failure tracking
 .rspec_status
 Gemfile.lock
+docs/_site/
+docs/.jekyll-cache/
+docs/.bundle/
+docs/vendor/

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-13 10:04:56 UTC using RuboCop version 1.86.1.
+# on 2026-04-14 23:12:52 UTC using RuboCop version 1.86.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
@@ -11,17 +11,29 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'prosereflect.gemspec'
 
-# Offense count: 5
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
+Layout/ElseAlignment:
   Exclude:
-    - 'spec/prosereflect/schema/conftest.rb'
+    - 'lib/prosereflect/schema/schema_main.rb'
 
-# Offense count: 80
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/prosereflect/schema/schema_main.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/prosereflect/schema/schema_main.rb'
+
+# Offense count: 264
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -29,20 +41,14 @@ Layout/LineLength:
   Enabled: false
 
 # Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'spec/prosereflect/schema/conftest.rb'
-
-# Offense count: 4
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
     - 'lib/prosereflect/input/html.rb'
     - 'lib/prosereflect/schema/attribute.rb'
+    - 'lib/prosereflect/schema/content_match.rb'
     - 'lib/prosereflect/schema/mark.rb'
-    - 'lib/prosereflect/schema/schema_class.rb'
+    - 'spec/fixtures/test_builder/helpers.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -52,84 +58,60 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/prosereflect/schema/node.rb'
 
-# Offense count: 34
+# Offense count: 57
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
-  Exclude:
-    - 'lib/prosereflect/input/html.rb'
-    - 'lib/prosereflect/node.rb'
-    - 'lib/prosereflect/output/html.rb'
-    - 'lib/prosereflect/parser.rb'
-    - 'lib/prosereflect/schema/fragment.rb'
-    - 'lib/prosereflect/schema/mark_type.rb'
-    - 'lib/prosereflect/schema/node.rb'
-    - 'lib/prosereflect/schema/node_type.rb'
-    - 'lib/prosereflect/schema/schema_class.rb'
-    - 'spec/support/matchers.rb'
+  Enabled: false
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 27
 
 # Offense count: 1
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 30
+# Offense count: 57
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
-  Exclude:
-    - 'lib/prosereflect/code_block.rb'
-    - 'lib/prosereflect/input/html.rb'
-    - 'lib/prosereflect/node.rb'
-    - 'lib/prosereflect/output/html.rb'
-    - 'lib/prosereflect/parser.rb'
-    - 'lib/prosereflect/schema/attribute.rb'
-    - 'lib/prosereflect/schema/fragment.rb'
-    - 'lib/prosereflect/schema/mark_type.rb'
-    - 'lib/prosereflect/schema/node.rb'
-    - 'lib/prosereflect/schema/node_type.rb'
-    - 'lib/prosereflect/schema/schema_class.rb'
-    - 'spec/support/matchers.rb'
+  Enabled: false
 
-# Offense count: 45
+# Offense count: 82
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 84
+  Max: 93
 
-# Offense count: 2
+# Offense count: 9
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 8
 
-# Offense count: 30
+# Offense count: 52
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
-  Exclude:
-    - 'lib/prosereflect/code_block.rb'
-    - 'lib/prosereflect/input/html.rb'
-    - 'lib/prosereflect/node.rb'
-    - 'lib/prosereflect/output/html.rb'
-    - 'lib/prosereflect/parser.rb'
-    - 'lib/prosereflect/schema/fragment.rb'
-    - 'lib/prosereflect/schema/mark_type.rb'
-    - 'lib/prosereflect/schema/node.rb'
-    - 'lib/prosereflect/schema/node_type.rb'
-    - 'lib/prosereflect/schema/schema_class.rb'
-    - 'spec/support/matchers.rb'
+  Enabled: false
 
-# Offense count: 4
+# Offense count: 7
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
   Exclude:
+    - 'lib/prosereflect/schema/content_match.rb'
     - 'lib/prosereflect/schema/fragment.rb'
+    - 'lib/prosereflect/schema/mark.rb'
     - 'lib/prosereflect/schema/node.rb'
 
-# Offense count: 6
+# Offense count: 8
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
 # WaywardPredicates: infinite?, nonzero?
 Naming/PredicateMethod:
   Exclude:
     - 'lib/prosereflect/schema/attribute.rb'
+    - 'lib/prosereflect/schema/content_match.rb'
     - 'lib/prosereflect/schema/node.rb'
 
 # Offense count: 12
@@ -160,12 +142,12 @@ RSpec/ContextWording:
     - 'spec/prosereflect/schema/conftest.rb'
     - 'spec/support/shared_examples.rb'
 
-# Offense count: 142
+# Offense count: 254
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 134
 
-# Offense count: 73
+# Offense count: 158
 RSpec/MultipleExpectations:
   Max: 8
 
@@ -174,24 +156,28 @@ RSpec/MultipleExpectations:
 RSpec/NestedGroups:
   Max: 4
 
+# Offense count: 1
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/prosereflect/schema/schema_spec.rb'
+
 # Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/IdenticalConditionalBranches:
   Exclude:
     - 'lib/prosereflect/schema/mark.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInArguments:
+# Offense count: 1
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: allow_single_line, disallow
+Style/NumberedParameters:
   Exclude:
-    - 'spec/prosereflect/schema/conftest.rb'
+    - 'lib/prosereflect/schema/content_match.rb'
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInHashLiteral:
+# Offense count: 1
+# Configuration parameters: AllowedClasses.
+Style/OneClassPerFile:
   Exclude:
-    - 'spec/prosereflect/schema/conftest.rb'
+    - 'lib/prosereflect/schema.rb'

data/README.adoc

@@ -14,6 +14,8 @@ accessing the hierarchical document tree structure represented in ProseMirror's
 JSON/YAML format. This allows for convenient traversal and extraction of content
 from rich text documents.
 
+https://metanorma.org/prosereflect/[Full documentation] is available on the docs site.
+
 
 == Installation
 

data/docs/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "jekyll-asciidoc"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
+end

data/docs/INDEX.adoc

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Home
+nav_order: 1
+---
+
+= Prosereflect Documentation
+
+`prosereflect` is a Ruby gem for working with the document structure used by the https://prosemirror.net/[ProseMirror rich text editor].
+
+It provides a set of models and utilities for parsing, manipulating, and accessing the hierarchical document tree structure represented in ProseMirror's JSON/YAML format.
+
+== Quick Start
+
+Install the gem:
+
+[source,sh]
+----
+gem install prosereflect
+----
+
+Parse a document:
+
+[source,ruby]
+----
+require 'prosereflect'
+
+doc = Prosereflect::Parser.parse_document({
+  "type" => "doc",
+  "content" => [
+    { "type" => "paragraph", "content" => [{ "type" => "text", "text" => "Hello world" }] }
+  ]
+})
+----
+
+== Documentation Sections
+
+* x:features:node-types[Node Types] -- All available node types and their attributes
+* x:features:marks[Marks] -- Text formatting marks (bold, italic, links, etc.)
+* x:understanding:document-model[Document Model] -- Node hierarchy and content model
+* x:understanding:fragment[Fragment] -- Flat content collections
+* x:understanding:resolved-position[Resolved Positions] -- Position resolution in the document tree
+* x:advanced:transform[Transforms] -- Document transformations and step-based editing
+* x:advanced:schema[Schema] -- Schema definition and validation
+* x:guides:round-trip-html[HTML Round-Trip] -- Convert between HTML and ProseMirror documents

data/docs/_advanced/index.adoc

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Advanced
+nav_order: 5
+has_children: true
+---
+= Advanced
+
+This section covers advanced topics for power users.
+
+* x:transform[Transforms] -- Step-based document transformations
+* x:steps[Step Types] -- Individual step types and their behavior
+* x:step-map[Step Maps and Mappings] -- Position tracking through transforms
+* x:schema[Schema] -- Schema definition and content validation
+* x:test-builder[Test Builder] -- DSL for building test documents

data/docs/_advanced/schema.adoc

@@ -0,0 +1,112 @@
+---
+layout: default
+title: Schema
+parent: Advanced
+nav_order: 4
+---
+= Schema
+
+`Prosereflect::Schema` defines the structure of valid documents: which node types exist, what content they can contain, and which marks are allowed.
+
+== Creating a Schema
+
+[source,ruby]
+----
+schema = Prosereflect::Schema.new(
+  nodes_spec: {
+    "doc" => { content: "block+" },
+    "paragraph" => { content: "inline*", group: "block" },
+    "heading" => { content: "inline*", group: "block", attrs: { "level" => { "default" => 1 } } },
+    "text" => { group: "inline" }
+  },
+  marks_spec: {
+    "bold" => {},
+    "italic" => {},
+    "link" => { attrs: { "href" => {} } }
+  }
+)
+----
+
+== Requirements
+
+Every schema must define:
+
+* A `"doc"` node type (the top-level container)
+* A `"text"` node type (inline text)
+* At least one block node type in the doc's content expression
+
+== Content Expressions
+
+Content expressions define what children a node can have. Supported syntax:
+
+* `"block+"` -- one or more block nodes
+* `"inline*"` -- zero or more inline nodes
+* `"paragraph heading"` -- a paragraph followed by a heading
+* `"(paragraph | heading)"` -- either paragraph or heading
+* `"block{2,4}"` -- between 2 and 4 block nodes
+* `"block?"` -- optional block node
+
+== NodeType
+
+Access and use node types from a schema:
+
+[source,ruby]
+----
+para_type = schema.node_type("paragraph")
+para_type.name             # => "paragraph"
+para_type.is_block?        # => true
+para_type.is_inline?       # => false
+para_type.is_textblock?    # => true
+para_type.is_leaf?         # => false
+para_type.is_atom?         # => false
+----
+
+Creating validated nodes:
+
+[source,ruby]
+----
+# Create with validation
+node = para_type.create_checked(nil, [text_node])
+
+# Create with defaults
+node = para_type.create_and_fill
+
+# Check content validity
+para_type.valid_content?(fragment)
+----
+
+== MarkType
+
+Access and use mark types:
+
+[source,ruby]
+----
+bold_type = schema.mark_type("bold")
+mark = bold_type.create      # Schema::Mark instance
+mark.attrs                  # => {}
+
+link_type = schema.mark_type("link")
+link = link_type.create("href" => "https://example.com")
+link.attrs  # => {"href" => "https://example.com"}
+----
+
+== ContentMatch
+
+`ContentMatch` is the engine that validates content expressions. It uses an NFA/DFA approach to parse and match content expressions:
+
+* `match_type(node_type)` -- try to match a node type, returns next match state or nil
+* `match_fragment(fragment)` -- match a full fragment
+* `valid_end` -- whether this state is a valid end state
+* `fill_before(after:, to_end:)` -- compute filler content
+* `find_wrapping(target_type)` -- find wrapping nodes for content
+* `inline_content?` -- whether this match accepts inline content
+* `default_type` -- the default node type for this match
+
+== Validation Errors
+
+The schema raises `Prosereflect::SchemaErrors::ValidationError` for:
+
+* Missing required node types (doc, text)
+* Name collisions between nodes and marks
+* Invalid content in created nodes
+* Missing required attributes

data/docs/_advanced/step-map.adoc

@@ -0,0 +1,66 @@
+---
+layout: default
+title: Step Maps and Mappings
+parent: Advanced
+nav_order: 3
+---
+= Step Maps and Mappings
+
+When steps are applied to a document, positions in the original document may no longer correspond to the same locations. Step maps and mappings track these changes.
+
+== StepMap
+
+`Prosereflect::Transform::StepMap` maps positions through a single step. It stores an array of ranges `[old_start, old_end, new_start, new_end]`.
+
+[source,ruby]
+----
+# Create a step map
+map = Prosereflect::Transform::StepMap.new([[0, 5, 0, 8]])
+
+# Map a position
+map.map(3)  # => new position after the step
+
+# Check if a position was deleted
+map.deleted?(3)  # => true/false
+
+# Map with deletion info
+result = map.map_result(3)
+result.pos       # => new position
+result.deleted   # => whether the position was deleted
+result.transformed  # => whether the position changed
+----
+
+=== Factory Methods
+
+* `StepMap.empty` -- identity map (no changes)
+* `StepMap.delete(from, to)` -- map for a deletion
+* `StepMap.replace(from, to, target_from, target_to)` -- map for a replacement
+
+== Mapping
+
+`Prosereflect::Transform::Mapping` composes multiple step maps to track positions through a full transform chain.
+
+[source,ruby]
+----
+mapping = Prosereflect::Transform::Mapping.new
+mapping.add_map(step_map_1)
+mapping.add_map(step_map_2)
+
+# Map a position through all steps
+mapping.map(5)  # => final position
+
+# Map with deletion tracking
+result = mapping.map_result(5)
+result[:pos]       # => final position
+result[:deleted]   # => whether deleted by any step
+
+# Map backwards
+mapping.map_reverse(8)  # => original position
+----
+
+=== Checking Deletions
+
+[source,ruby]
+----
+mapping.map_deletes(5)  # => whether position 5 was deleted by any step
+----