metanorma-plugin-openapi 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cc137b68b59999c5d99577793b14fd3ece351ab14f95372ac8745c016d5e780
-  data.tar.gz: a6f5628475121accbf69b485ddca657f1e433b6ed191ae958de85c2bbc97c900
+  metadata.gz: e24aac3a9834450d38c598a2fb5fe97f7fb9c72360dd15ccdf9a53e8659cb511
+  data.tar.gz: 3604d75b940bf467aa2c12dd985a5b075528c7a512e36983b97ebe9643adebd4
 SHA512:
-  metadata.gz: 6adfce232953b977dfb8b7cf1f7474a6047d9ed106626e81e9a5f14f50fa27f7d6dbdaf38c677f6054de1509c40ffcfccc335b83d5ece16df744cea5e83e8965
-  data.tar.gz: 0c21e681440b8a261190099b4d103766f7cc5668ddbb8a66ff1607bc5f2c0bac5632e4bb96577806e0fb0493d31a82dfef5a94dbf64189234d8e8e7d7715b812
+  metadata.gz: e76a0c1ed23c61b5b6f1e08776392c049adaa8f579eca12d588c9d5bbe4659b2281fec42fd47f4b4937700d58531cd5d2411629e152ff5024f0c71da0d610f47
+  data.tar.gz: 84fc464660f03dd22ecd87cfbf80cf88de6863caf4c543d651a13985247609df0a21a49bb4e40ec268df5aa11d3e92d96d4e47db3a5adfc7cbe5484320aa6fd5

data/lib/metanorma/plugin/openapi/preprocessor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+
+module Metanorma
+  module Plugin
+    module Openapi
+      # Splices rendered AsciiDoc in place of an
+      #
+      #   [openapi,path=/to/document.yaml]
+      #   --
+      #   --
+      #
+      # envelope before the document parses. A preprocessor, not a block
+      # processor: Parser.parse_blocks (what block processors get to
+      # parse through) cannot create sections, and the rendered sections
+      # must be real sections (numbering, TOC).
+      class Preprocessor < ::Asciidoctor::Extensions::Preprocessor
+        OPENAPI_ATTRS = /\A\[openapi([,\]].*)?\]\s*\z/
+
+        def process(document, reader)
+          ::Asciidoctor::Reader.new(splice(document, reader.readlines),
+                                    reader.cursor)
+        end
+
+        private
+
+        def splice(document, lines)
+          out = []
+          until lines.empty?
+            line = lines.shift
+            if line.match?(OPENAPI_ATTRS)
+              out.concat(consume_and_render(document, line, lines))
+            else
+              out << line
+            end
+          end
+          out
+        end
+
+        def dashed?(line)
+          line&.strip == "--"
+        end
+
+        def consume_and_render(document, attr_line, lines)
+          envelope(lines) or
+            raise ::ArgumentError,
+                  "openapi block needs a -- -- envelope: #{attr_line}"
+          source = attrs_path(attr_line)
+          content = Renderer.new(load_document(document, source)).render
+          content.split("\n")
+        end
+
+        # The closing -- is optional; a missing opening envelope raises
+        # from consume_and_render
+        def envelope(lines)
+          lines.shift while lines.first && lines.first.strip.empty?
+          return nil unless dashed?(lines.shift)
+
+          body = []
+          while (line = lines.shift) && !dashed?(line)
+            body << line
+          end
+          body
+        end
+
+        def attrs_path(attr_line)
+          path = attr_line[/path=("([^"]+)"|(\S+?))\]/, 2] ||
+            attr_line[/path=("([^"]+)"|(\S+?))\]/, 3] ||
+            attr_line[/path=([^\]\s]+)/, 1]
+          raise ::ArgumentError, "openapi block needs a path" unless path
+
+          path
+        end
+
+        def load_document(document, source)
+          base = ::File.dirname(document.attributes["docfile"] || ".")
+          ::Lutaml::Openapi.parse(::File.read(::File.expand_path(source, base)))
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/openapi/renderer.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
 require "lutaml/openapi"
-require "coradoc"
-require "coradoc/markdown"
-require "coradoc/asciidoc"
 
 module Metanorma
   module Plugin
     module Openapi
+      # metanorma-plugin-lutaml pins coradoc ~> 1.1.8, which excludes the
+      # 2.0 hub in every metanorma-cli bundle, so the monorepo (and its
+      # markdown spoke) may be absent at runtime; without it,
+      # CommonMark descriptions pass through with only the link bridge.
+      begin
+        require "coradoc"
+        require "coradoc/markdown"
+        require "coradoc/asciidoc"
+        MONOREPO = true
+      rescue LoadError
+        MONOREPO = false
+      end
+
       # Renders an OpenAPI document as normative AsciiDoc sections.
       # Descriptions are CommonMark (per the OpenAPI spec) and convert
       # to AsciiDoc through the coradoc tree — the metanorma-ogc#153
@@ -23,9 +33,11 @@ module Metanorma
 
         private
 
+        # The preface is a section: spliced content must stay at `==`
+        # level (a level-0 line mid-document degrades to a paragraph)
         def preface
           info = @document.info || {}
-          lines = ["= #{info['title'] || 'OpenAPI document'}", ""]
+          lines = ["== #{info['title'] || 'OpenAPI document'}", ""]
           lines << "API version: #{@document.openapi}" if @document.openapi
           if (desc = info["description"])
             lines << to_asciidoc(desc) << ""
@@ -69,16 +81,23 @@ module Metanorma
             op.is_a?(Hash)
           end
           entries.flat_map do |method, operation|
-            lines = ["=== #{method.to_s.upcase} #{path}", ""]
-            if (desc = operation["description"])
-              lines << to_asciidoc(desc) << ""
+            ["=== #{method.to_s.upcase} #{path}", "",
+             *operation_text(operation)]
+          end
+        end
+
+        # most real corpora carry summary (the one-liner), not
+        # description; the tiles bundled OAS has summary on all 39
+        def operation_text(operation)
+          %w[summary description].filter_map do |key|
+            if (text = operation[key])
+              to_asciidoc(text) << ""
             end
-            lines
           end
         end
 
         def to_asciidoc(markdown)
-          adoc = Coradoc.convert(markdown, from: :markdown, to: :asciidoc)
+          adoc = convert_markdown(markdown)
           # coradoc-markdown does not convert CommonMark links yet (they
           # pass through raw); bridge the dominant inline form to
           # AsciiDoc's https://url[text]. Remove once coradoc grows
@@ -87,6 +106,12 @@ module Metanorma
             "#{Regexp.last_match(2)}[#{Regexp.last_match(1)}]"
           end
         end
+
+        def convert_markdown(markdown)
+          return markdown unless MONOREPO
+
+          Coradoc.convert(markdown, from: :markdown, to: :asciidoc)
+        end
       end
     end
   end

data/lib/metanorma/plugin/openapi/version.rb

@@ -3,7 +3,7 @@
 module Metanorma
   module Plugin
     module Openapi
-      VERSION = "0.1.0"
+      VERSION = "0.1.1"
     end
   end
 end

data/lib/metanorma/plugin/openapi.rb

@@ -7,7 +7,7 @@ module Metanorma
     module Openapi
       autoload :VERSION, "metanorma/plugin/openapi/version"
       autoload :Renderer, "metanorma/plugin/openapi/renderer"
-      autoload :Block, "metanorma/plugin/openapi/block"
+      autoload :Preprocessor, "metanorma/plugin/openapi/preprocessor"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-openapi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ribose Inc.
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: coradoc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement
@@ -80,7 +66,7 @@ files:
 - Rakefile
 - examples/ogcapi-features-1.adoc
 - lib/metanorma/plugin/openapi.rb
-- lib/metanorma/plugin/openapi/block.rb
+- lib/metanorma/plugin/openapi/preprocessor.rb
 - lib/metanorma/plugin/openapi/renderer.rb
 - lib/metanorma/plugin/openapi/version.rb
 homepage: https://github.com/metanorma/metanorma-plugin-openapi

data/lib/metanorma/plugin/openapi/block.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require "asciidoctor"
-
-module Metanorma
-  module Plugin
-    module Openapi
-      # [openapi,path=/path/to/document.yaml]
-      # --
-      # --
-      #
-      # Loads an OpenAPI document and renders it as normative AsciiDoc
-      # sections. The path resolves against the source document.
-      class Block < ::Asciidoctor::Extensions::BlockProcessor
-        use_dsl
-        named :openapi
-        on_context :open
-
-        def process(parent, _reader, attrs)
-          source = attrs["path"] || parent.document.attr("openapi_document")
-          unless source
-            raise ::ArgumentError,
-                  "openapi block needs a path attribute"
-          end
-
-          content = Renderer.new(load_document(parent, source)).render
-          parent.blocks << ::Asciidoctor::Block.new(
-            parent, :open, source: content.split("\n"), attrs: {}
-          )
-          nil
-        end
-
-        private
-
-        def load_document(parent, source)
-          base = ::File.dirname(parent.document.attributes["docfile"] || ".")
-          Lutaml::Openapi.parse(::File.read(::File.expand_path(source, base)))
-        end
-      end
-    end
-  end
-end