coradoc 1.1.6 → 2.0.1

data/coradoc-adoc/spec/coradoc/developer_experience_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# rubocop:disable RSpec/DescribeClass - This is a feature spec for the API facade
+RSpec.describe 'Developer Experience API' do
+  # Load coradoc core and asciidoc
+
+  describe 'Coradoc.parse' do
+    it 'parses AsciiDoc text to CoreModel' do
+      text = "= Document Title\n\n== Section\n\nContent here."
+
+      result = Coradoc.parse(text, format: :asciidoc)
+
+      expect(result).to be_a(Coradoc::CoreModel::StructuralElement)
+      expect(result.element_type).to eq('document')
+    end
+
+    it 'raises error for unregistered format' do
+      expect do
+        Coradoc.parse('text', format: :unknown)
+      end.to raise_error(Coradoc::UnsupportedFormatError, /not registered/)
+    end
+
+    it 'lists available formats in error message' do
+      expect do
+        Coradoc.parse('text', format: :unknown)
+      end.to raise_error(/Available formats:.*asciidoc/)
+    end
+  end
+
+  describe 'Coradoc.convert' do
+    it 'converts AsciiDoc to AsciiDoc (round-trip)' do
+      input = "= Title\n\n== Section\n\nParagraph."
+
+      result = Coradoc.convert(input, from: :asciidoc, to: :asciidoc)
+
+      expect(result).to include('Title')
+      expect(result).to include('Section')
+      expect(result).to include('Paragraph')
+    end
+
+    it 'preserves document structure in conversion' do
+      input = <<~ADOC
+        = Complex Document
+
+        == Introduction
+
+        Some intro text.
+
+        * Item 1
+        * Item 2
+
+        == Details
+
+        More details here.
+      ADOC
+
+      result = Coradoc.convert(input, from: :asciidoc, to: :asciidoc)
+
+      expect(result).to include('Introduction')
+      expect(result).to include('Item 1')
+      expect(result).to include('Details')
+    end
+
+    it 'raises error for unknown source format' do
+      expect do
+        Coradoc.convert('text', from: :unknown, to: :asciidoc)
+      end.to raise_error(Coradoc::UnsupportedFormatError)
+    end
+
+    it 'raises error for unknown target format' do
+      expect do
+        Coradoc.convert('text', from: :asciidoc, to: :unknown)
+      end.to raise_error(Coradoc::UnsupportedFormatError)
+    end
+  end
+
+  describe 'Coradoc.serialize' do
+    it 'serializes CoreModel to AsciiDoc' do
+      core = Coradoc::CoreModel::StructuralElement.new(
+        element_type: 'document',
+        title: 'My Document',
+        children: []
+      )
+
+      result = Coradoc.serialize(core, to: :asciidoc)
+
+      expect(result).to include('My Document')
+    end
+  end
+
+  describe 'Coradoc.to_core' do
+    it 'returns CoreModel as-is' do
+      core = Coradoc::CoreModel::Block.new(content: 'test')
+
+      result = Coradoc.to_core(core)
+
+      expect(result).to eq(core)
+    end
+
+    it 'transforms AsciiDoc model to CoreModel' do
+      adoc = Coradoc::AsciiDoc::Model::Paragraph.new(
+        content: [Coradoc::AsciiDoc::Model::TextElement.new(content: 'Hello')]
+      )
+
+      result = Coradoc.to_core(adoc)
+
+      expect(result).to be_a(Coradoc::CoreModel::Block)
+      expect(result.element_type).to eq('paragraph')
+    end
+  end
+
+  describe 'format registration' do
+    it 'lists registered formats' do
+      expect(Coradoc.registered_formats).to include(:asciidoc)
+    end
+
+    it 'returns format module' do
+      expect(Coradoc.get_format(:asciidoc)).to eq(Coradoc::AsciiDoc)
+    end
+  end
+end
+# rubocop:enable RSpec/DescribeClass

data/coradoc-adoc/spec/coradoc/util/asciidoc_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Coradoc::Util::AsciiDoc do
+  describe '.escape_characters' do
+    it 'returns empty string for nil input' do
+      expect(described_class.escape_characters(nil)).to eq('')
+    end
+
+    it 'returns empty string for empty input' do
+      expect(described_class.escape_characters('')).to eq('')
+    end
+
+    it 'returns content unchanged when no escape_chars specified' do
+      expect(described_class.escape_characters('hello world')).to eq('hello world')
+    end
+
+    it 'escapes asterisks' do
+      result = described_class.escape_characters('2 * 3 = 6', escape_chars: ['*'])
+      expect(result).to eq('2 \\* 3 = 6')
+    end
+
+    it 'escapes underscores' do
+      result = described_class.escape_characters('hello_world', escape_chars: ['_'])
+      expect(result).to eq('hello\\_world')
+    end
+
+    it 'escapes multiple occurrences' do
+      result = described_class.escape_characters('*a* and *b*', escape_chars: ['*'])
+      expect(result).to eq('\\*a\\* and \\*b\\*')
+    end
+
+    it 'escapes multiple different characters' do
+      result = described_class.escape_characters('*bold* and _italic_', escape_chars: %w[* _])
+      expect(result).to eq('\\*bold\\* and \\_italic\\_')
+    end
+
+    it 'does not double-escape already escaped characters' do
+      result = described_class.escape_characters('already \\* escaped', escape_chars: ['*'])
+      expect(result).to eq('already \\* escaped')
+    end
+  end
+
+  describe '.unescape_characters' do
+    it 'returns empty string for nil input' do
+      expect(described_class.unescape_characters(nil)).to eq('')
+    end
+
+    it 'returns content unchanged when no escape_chars specified' do
+      expect(described_class.unescape_characters('hello world')).to eq('hello world')
+    end
+
+    it 'unescapes asterisks' do
+      result = described_class.unescape_characters('2 \\* 3 = 6', escape_chars: ['*'])
+      expect(result).to eq('2 * 3 = 6')
+    end
+
+    it 'is inverse of escape_characters' do
+      original = '2 * 3 = 6'
+      escaped = described_class.escape_characters(original, escape_chars: ['*'])
+      unescaped = described_class.unescape_characters(escaped, escape_chars: ['*'])
+      expect(unescaped).to eq(original)
+    end
+  end
+end

data/coradoc-adoc/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Add local lib directory to load path FIRST
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'bundler/setup'
+
+# Load coradoc core first (which includes Logger)
+require 'coradoc'
+
+# Now load our asciidoc module
+require 'coradoc/asciidoc'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.filter_run_when_matching :focus
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+end

data/coradoc-adoc/spec/transform/from_core_model_spec.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Coradoc::AsciiDoc::Transform::FromCoreModel do
+  let(:transformer) { described_class.new }
+
+  describe '#transform' do
+    context 'when transforming a document' do
+      it 'transforms a CoreModel document to AsciiDoc' do
+        doc = Coradoc::CoreModel::StructuralElement.new(
+          element_type: 'document',
+          title: 'Test Document',
+          children: []
+        )
+
+        result = transformer.transform(doc)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Document)
+        expect(result.header.title.content).to eq('Test Document')
+      end
+    end
+
+    context 'when transforming a section' do
+      it 'transforms a CoreModel section to AsciiDoc' do
+        section = Coradoc::CoreModel::StructuralElement.new(
+          element_type: 'section',
+          id: 'intro',
+          level: 2,
+          title: 'Introduction',
+          children: []
+        )
+
+        result = transformer.transform(section)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Section)
+        expect(result.id).to eq('intro')
+        expect(result.level).to eq(2)
+        expect(result.title.content).to eq('Introduction')
+      end
+    end
+
+    context 'when transforming a block' do
+      it 'transforms a CoreModel block to AsciiDoc' do
+        block = Coradoc::CoreModel::Block.new(
+          id: 'example-1',
+          delimiter_type: '====',
+          content: "Line 1\nLine 2"
+        )
+
+        result = transformer.transform(block)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Block::Core)
+        expect(result.id).to eq('example-1')
+        expect(result.delimiter).to eq('====')
+      end
+    end
+
+    context 'when transforming a list' do
+      it 'transforms a CoreModel list to AsciiDoc' do
+        items = [
+          Coradoc::CoreModel::ListItem.new(marker: '*', content: 'Item 1'),
+          Coradoc::CoreModel::ListItem.new(marker: '*', content: 'Item 2')
+        ]
+        list = Coradoc::CoreModel::ListBlock.new(
+          marker_type: 'asterisk',
+          items: items
+        )
+
+        result = transformer.transform(list)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::List::Unordered)
+        expect(result.items.count).to eq(2)
+      end
+    end
+
+    context 'when transforming a table' do
+      it 'transforms a CoreModel table to AsciiDoc' do
+        rows = [
+          Coradoc::CoreModel::TableRow.new(
+            cells: [
+              Coradoc::CoreModel::TableCell.new(content: 'Cell 1'),
+              Coradoc::CoreModel::TableCell.new(content: 'Cell 2')
+            ]
+          )
+        ]
+        table = Coradoc::CoreModel::Table.new(rows: rows)
+
+        result = transformer.transform(table)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Table)
+        expect(result.rows.count).to eq(1)
+      end
+    end
+
+    context 'when transforming an image' do
+      it 'transforms a CoreModel image to AsciiDoc' do
+        image = Coradoc::CoreModel::Image.new(
+          src: 'diagram.png',
+          alt: 'System Diagram'
+        )
+
+        result = transformer.transform(image)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Image::BlockImage)
+        expect(result.path).to eq('diagram.png')
+        expect(result.alt).to eq('System Diagram')
+      end
+    end
+
+    context 'when transforming an annotation' do
+      it 'transforms a CoreModel annotation to AsciiDoc admonition' do
+        annotation = Coradoc::CoreModel::AnnotationBlock.new(
+          annotation_type: 'note',
+          content: 'This is important'
+        )
+
+        result = transformer.transform(annotation)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Admonition)
+        expect(result.type).to eq('NOTE')
+      end
+
+      it 'distinguishes AnnotationBlock from Block (AnnotationBlock < Block)' do
+        annotation = Coradoc::CoreModel::AnnotationBlock.new(
+          annotation_type: 'warning',
+          content: 'Danger'
+        )
+
+        result = transformer.transform(annotation)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Admonition)
+        expect(result.type).to eq('WARNING')
+      end
+    end
+
+    context 'when transforming inline elements' do
+      it 'transforms bold to Inline::Bold' do
+        inline = Coradoc::CoreModel::InlineElement.new(format_type: 'bold', content: 'bold text')
+
+        result = transformer.transform(inline)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Inline::Bold)
+      end
+
+      it 'transforms italic to Inline::Italic' do
+        inline = Coradoc::CoreModel::InlineElement.new(format_type: 'italic', content: 'italic text')
+
+        result = transformer.transform(inline)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Inline::Italic)
+      end
+
+      it 'transforms monospace to Inline::Monospace' do
+        inline = Coradoc::CoreModel::InlineElement.new(format_type: 'monospace', content: 'code')
+
+        result = transformer.transform(inline)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Inline::Monospace)
+      end
+
+      it 'transforms link to Inline::CrossReference for xref' do
+        inline = Coradoc::CoreModel::InlineElement.new(
+          format_type: 'xref', content: 'Section', target: 'section_1'
+        )
+
+        result = transformer.transform(inline)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Inline::CrossReference)
+      end
+    end
+
+    context 'when transforming a footnote' do
+      it 'transforms a CoreModel footnote to AsciiDoc' do
+        footnote = Coradoc::CoreModel::Footnote.new(id: '1', content: 'A footnote')
+
+        result = transformer.transform(footnote)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::Inline::Footnote)
+      end
+    end
+
+    context 'when transforming a definition list' do
+      it 'transforms a CoreModel definition list to AsciiDoc' do
+        dl = Coradoc::CoreModel::DefinitionList.new(
+          items: [
+            Coradoc::CoreModel::DefinitionItem.new(term: 'Term 1', definitions: ['Definition 1'])
+          ]
+        )
+
+        result = transformer.transform(dl)
+
+        expect(result).to be_a(Coradoc::AsciiDoc::Model::List::Definition)
+        expect(result.items.count).to eq(1)
+      end
+    end
+
+    context 'when transforming an array' do
+      it 'transforms each element in the collection' do
+        elements = [
+          Coradoc::CoreModel::StructuralElement.new(
+            element_type: 'section',
+            level: 1,
+            title: 'Section 1'
+          ),
+          Coradoc::CoreModel::StructuralElement.new(
+            element_type: 'section',
+            level: 1,
+            title: 'Section 2'
+          )
+        ]
+
+        result = transformer.transform(elements)
+
+        expect(result).to be_an(Array)
+        expect(result.length).to eq(2)
+        expect(result.first).to be_a(Coradoc::AsciiDoc::Model::Section)
+      end
+    end
+  end
+end

data/coradoc-adoc/spec/transform/to_core_model_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Coradoc::AsciiDoc::Transform::ToCoreModel do
+  let(:transformer) { described_class.new }
+
+  describe '#transform' do
+    context 'when transforming a document' do
+      it 'transforms an AsciiDoc document to CoreModel' do
+        header = Coradoc::AsciiDoc::Model::Header.new(
+          title: Coradoc::AsciiDoc::Model::Title.new(content: 'Test Document')
+        )
+        doc = Coradoc::AsciiDoc::Model::Document.new(
+          header: header,
+          sections: []
+        )
+
+        result = transformer.transform(doc)
+
+        expect(result).to be_a(Coradoc::CoreModel::StructuralElement)
+        expect(result.element_type).to eq('document')
+        expect(result.title).to eq('Test Document')
+      end
+    end
+
+    context 'when transforming a section' do
+      it 'transforms an AsciiDoc section to CoreModel' do
+        section = Coradoc::AsciiDoc::Model::Section.new(
+          id: 'intro',
+          level: 1,
+          title: Coradoc::AsciiDoc::Model::Title.new(content: 'Introduction'),
+          contents: []
+        )
+
+        result = transformer.transform(section)
+
+        expect(result).to be_a(Coradoc::CoreModel::StructuralElement)
+        expect(result.element_type).to eq('section')
+        expect(result.level).to eq(1)
+        expect(result.title).to eq('Introduction')
+        expect(result.id).to eq('intro')
+      end
+    end
+
+    context 'when transforming a block' do
+      it 'transforms an AsciiDoc block to CoreModel' do
+        block = Coradoc::AsciiDoc::Model::Block::Core.new(
+          id: 'example-1',
+          delimiter: '====',
+          lines: ['Line 1', 'Line 2']
+        )
+
+        result = transformer.transform(block)
+
+        expect(result).to be_a(Coradoc::CoreModel::Block)
+        expect(result.delimiter_type).to eq('====')
+        expect(result.content).to eq("Line 1\nLine 2")
+      end
+    end
+
+    context 'when transforming an array' do
+      it 'transforms each element in the collection' do
+        sections = [
+          Coradoc::AsciiDoc::Model::Section.new(
+            level: 1,
+            title: Coradoc::AsciiDoc::Model::Title.new(content: 'Section 1')
+          ),
+          Coradoc::AsciiDoc::Model::Section.new(
+            level: 1,
+            title: Coradoc::AsciiDoc::Model::Title.new(content: 'Section 2')
+          )
+        ]
+
+        result = transformer.transform(sections)
+
+        expect(result).to be_an(Array)
+        expect(result.length).to eq(2)
+        expect(result.first).to be_a(Coradoc::CoreModel::StructuralElement)
+      end
+    end
+  end
+end

data/coradoc-docx/README.adoc

@@ -0,0 +1,164 @@
+= coradoc-docx
+image:https://img.shields.io/gem/v/coradoc-docx.svg[RubyGems Version]
+
+DOCX (OOXML) format support for the
+https://github.com/lutaml/coradoc[Coradoc] document transformation library.
+
+== Purpose
+
+coradoc-docx reads Microsoft Word `.docx` files via
+https://github.com/lutaml/uniword[Uniword] and transforms the OOXML model
+tree into Coradoc's canonical CoreModel. Once in CoreModel, the document can
+be serialized to AsciiDoc, Markdown, or any other supported output format.
+
+== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'coradoc-docx'
+----
+
+Or install directly:
+
+[source,bash]
+----
+gem install coradoc-docx
+----
+
+The gem depends on `coradoc` and `uniword`, which will be installed
+automatically.
+
+== Usage
+
+=== Convert DOCX to AsciiDoc
+
+[source,ruby]
+----
+require 'coradoc'
+require 'coradoc/docx'
+
+adoc = Coradoc.convert("input.docx", from: :docx, to: :asciidoc)
+----
+
+=== Convert DOCX to Markdown
+
+[source,ruby]
+----
+md = Coradoc.convert("input.docx", from: :docx, to: :markdown)
+----
+
+=== Parse DOCX to CoreModel
+
+[source,ruby]
+----
+core = Coradoc.parse("input.docx", format: :docx)
+
+core.title         # => "Document Title"
+core.children      # => Array of sections, paragraphs, tables, etc.
+
+# Serialize to any format
+adoc = Coradoc.serialize(core, to: :asciidoc)
+html = Coradoc.serialize(core, to: :html)
+----
+
+=== CLI
+
+[source,bash]
+----
+# Convert DOCX to AsciiDoc
+coradoc convert document.docx -o output.adoc
+
+# Convert DOCX to Markdown
+coradoc convert document.docx -o output.md
+----
+
+== How It Works
+
+The DOCX pipeline uses Uniword to parse the OOXML zip archive into a typed
+model tree, then transforms it to CoreModel:
+
+....
+DOCX file
+  → Uniword::DocumentFactory.from_file
+  → OOXML model tree (Uniword::Wordprocessingml::*)
+  → Coradoc::Docx::Transform::ToCoreModel (rule-based dispatch)
+  → CoreModel tree (canonical hub)
+  → FromCoreModel (AsciiDoc or Markdown)
+  → Format model tree → Serializer → .adoc or .md file
+....
+
+The transform uses a **rule registry** with priority-based dispatch. Each
+OOXML element type has a dedicated rule class that produces a typed CoreModel
+node. Style-based semantic detection (headings, lists, quotes) is handled by
+`StyleResolver` and `NumberingResolver`.
+
+=== Supported OOXML Elements
+
+| OOXML Element | Style/Condition | CoreModel Target |
+|---------------|-----------------|------------------|
+| `w:p` (Heading style) | pStyle=HeadingN | StructuralElement (section) |
+| `w:p` (numPr) | numbering reference | ListBlock + ListItem |
+| `w:p` (Quote style) | style detection | Block (quote) |
+| `w:p` (Code style) | style detection | Block (source/listing) |
+| `w:p` (default) | - | Block (paragraph) |
+| `w:r` (bold) | rPr/bold | InlineElement (bold) |
+| `w:r` (italic) | rPr/italic | InlineElement (italic) |
+| `w:r` (underline) | rPr/underline | InlineElement (underline) |
+| `w:r` (strike) | rPr/strike | InlineElement (strikethrough) |
+| `w:r` (sub/sup) | rPr/vertAlign | InlineElement (subscript/superscript) |
+| `w:hyperlink` | r:id or w:anchor | InlineElement (link) |
+| `w:tbl` | - | Table |
+| `w:drawing` / `w:pict` | inline or anchor | Image |
+| `m:oMathPara` / `m:oMath` | - | Block or InlineElement (stem) |
+| `w:footnoteReference` | - | FootnoteReference |
+
+== Limitations
+
+* **Parse only** -- DOCX to CoreModel is supported; CoreModel to DOCX is not
+  yet implemented.
+* **Print layout** -- Page size, margins, headers/footers as page regions are
+  discarded (CoreModel is semantic, not print layout).
+* **Complex fields** -- Field characters (TOC, PAGE) are partially handled.
+* **Tracked changes** -- Deleted text is currently skipped.
+* **VML shapes** -- Only inline drawings are extracted.
+
+== Architecture
+
+=== Rule Classes
+
+Each OOXML element type is handled by a dedicated rule class in
+`Coradoc::Docx::Transform::Rules`:
+
+- `HeadingRule` -- Detects heading paragraphs via style or outline level
+- `ListItemRule` -- Detects numbered/bulleted paragraphs via numbering resolver
+- `ParagraphRule` -- Default paragraph transform
+- `RunRule` -- Inline formatting (bold, italic, monospace, links, etc.)
+- `TableRule` -- Table structure with rowspan/colspan
+- `HyperlinkRule` -- External links and bookmarks
+- `ImageRule` -- Inline and anchored drawings
+- `FootnoteRule` -- Footnote references
+- `MathRule` -- OMML math via Plurimath/LaTeX
+
+=== Resolvers
+
+- `StyleResolver` -- Walks the OOXML style definitions to detect semantic
+  roles (heading levels, code style, quote style) including `basedOn` chains
+- `NumberingResolver` -- Resolves numbering definitions to detect ordered vs.
+  unordered lists and their marker types
+
+== Development
+
+Run tests:
+
+[source,bash]
+----
+bundle exec rake spec:coradoc_docx
+----
+
+== License
+
+Copyright:: 2024-2026 Ribose Inc.
+
+Licensed under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache License, Version 2.0].