yard-yaml 0.1.0 → 0.1.2

data/certs/pboling.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+L9nRqA==
+-----END CERTIFICATE-----

data/lib/yard/yaml/converter.rb

@@ -12,10 +12,17 @@ module Yard
     #
     # Note: We intentionally keep the contract minimal and stable. Tests stub the backend.
     class Converter
+      BACKEND_STATE = {backend: nil}
+      BACKEND_MUTEX = Mutex.new
+
       class << self
         # Assignable backend for dependency injection in tests.
-        # Expected to respond to `convert(yaml, options)` and return a Hash with :html, :title, :description, and :meta keys
-        attr_writer :backend
+        # Preferred backends respond to `to_markdown(yaml, options:)`. Legacy
+        # test backends may respond to `convert(yaml, options)` and return a
+        # Hash with :html, :title, :description, and :meta keys.
+        def backend=(backend)
+          BACKEND_MUTEX.synchronize { BACKEND_STATE[:backend] = backend }
+        end
 
         # Convert a YAML string into an HTML result.
         #
@@ -34,49 +41,119 @@ module Yard
         # @param config [Yard::Yaml::Config]
         # @return [Hash]
         def from_file(path, options = {}, config: Yard::Yaml.config)
-          content = read_file(path)
+          content = read_file(path, config: config)
           return empty_result if content.nil?
           run_convert(content, options.merge(source_path: path.to_s), config)
         end
 
         # Backend accessor with auto-discovery.
         def backend
-          return @backend if defined?(@backend) && @backend
+          configured_backend = BACKEND_MUTEX.synchronize { BACKEND_STATE[:backend] }
+          return configured_backend if configured_backend
+
           begin
             require "yaml/converter"
           rescue LoadError
             # ignore; backend may be set by tests
           end
-          @backend = if defined?(::Yaml) && ::Yaml.const_defined?(:Converter)
-            ::Yaml::Converter
+
+          BACKEND_MUTEX.synchronize do
+            BACKEND_STATE[:backend] ||= ::Yaml::Converter if defined?(::Yaml) && ::Yaml.const_defined?(:Converter)
           end
         end
 
         private
 
-        def read_file(path)
-          File.read(path.to_s)
+        def read_file(path, config: Yard::Yaml.config)
+          raw = File.binread(path.to_s)
+          if binary_content?(raw)
+            handle_error(Yard::Yaml::Error.new("binary file not supported"), strict: config.strict, context: path.to_s)
+            return
+          end
+
+          content = raw.dup.force_encoding(Encoding::UTF_8)
+          return content if content.valid_encoding?
+
+          if config.strict
+            handle_error(Yard::Yaml::Error.new("invalid UTF-8 bytes in file"), strict: true, context: path.to_s)
+            return
+          end
+
+          handle_error(
+            Yard::Yaml::Error.new("invalid UTF-8 bytes in file; replaced invalid sequences"),
+            strict: false,
+            context: path.to_s,
+          )
+          content.scrub
         rescue Errno::ENOENT => e
-          handle_error(e, strict: Yard::Yaml.config.strict, context: "missing file: #{path}")
+          handle_error(e, strict: config.strict, context: "missing file: #{path}")
           nil
         end
 
+        def binary_content?(raw)
+          sample = raw.byteslice(0, 4096) || "".b
+          return true if sample.include?("\x00")
+          return false if sample.empty?
+
+          control_bytes = sample.bytes.count do |byte|
+            (0..8).cover?(byte) || byte == 11 || byte == 12 || (14..31).cover?(byte)
+          end
+          control_bytes.fdiv(sample.bytesize) > 0.1
+        end
+
         def run_convert(yaml, options, config)
           opts = build_options(options, config)
           b = backend
-          unless b && b.respond_to?(:convert)
+          unless converter_backend?(b)
             handle_error(Yard::Yaml::Error.new("yaml-converter backend not available"), strict: config.strict, context: "backend")
             return empty_result
           end
 
           begin
-            normalize_result(b.convert(yaml, opts))
+            normalize_result(convert_with_backend(b, yaml, opts))
           rescue StandardError => e
             handle_error(e, strict: config.strict, context: opts[:source_path] || "string")
             empty_result
           end
         end
 
+        def converter_backend?(backend)
+          backend&.respond_to?(:to_markdown) || backend&.respond_to?(:convert)
+        end
+
+        def convert_with_backend(backend, yaml, options)
+          return convert_markdown_backend(backend, yaml, options) if backend.respond_to?(:to_markdown)
+
+          backend.convert(yaml, options)
+        end
+
+        def convert_markdown_backend(backend, yaml, options)
+          markdown = backend.to_markdown(yaml, options: options)
+          metadata = metadata_from_yaml(yaml)
+          {
+            html: markdown_to_html(markdown),
+            title: metadata["title"],
+            description: metadata["abstract"],
+            meta: metadata,
+          }
+        end
+
+        def markdown_to_html(markdown)
+          require "kramdown"
+          require "kramdown-parser-gfm"
+
+          Kramdown::Document.new(markdown.to_s, input: "GFM").to_html
+        end
+
+        def metadata_from_yaml(yaml)
+          require "yaml"
+
+          parsed = YAML.safe_load(yaml.to_s, permitted_classes: [], permitted_symbols: [], aliases: false)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue Psych::Exception
+          {}
+        end
+
         def build_options(options, config)
           safe = {
             allow_erb: !!config.allow_erb,

data/lib/yard/yaml/emitter.rb

@@ -25,13 +25,14 @@ module Yard
         # @return [Array<String>] list of written file paths
         def emit!(pages:, output_dir:, config: Yard::Yaml.config)
           pages = Array(pages)
+          pages_with_slugs = assign_slugs(pages)
           written = []
           base = File.join(output_dir.to_s, config.out_dir.to_s)
           FileUtils.mkdir_p(base)
 
           # Write per-page files
-          pages.each do |page|
-            slug = page_slug(page)
+          pages_with_slugs.each do |page|
+            slug = page.fetch(:__yard_yaml_slug)
             path = File.join(base, "#{slug}.html")
             html = render_page_html(page)
             atomic_write(path, html, strict: config.strict)
@@ -41,7 +42,7 @@ module Yard
           # Index (optional)
           if config.index
             index_path = File.join(base, "index.html")
-            html = render_index_html(pages)
+            html = render_index_html(pages_with_slugs)
             atomic_write(index_path, html, strict: config.strict)
             written << index_path
           end
@@ -58,20 +59,36 @@ module Yard
 
         private
 
+        def assign_slugs(pages)
+          seen = Hash.new(0)
+          pages.map do |page|
+            slug = page_slug(page)
+            count = seen[slug]
+            seen[slug] += 1
+            page.merge(__yard_yaml_slug: count.zero? ? slug : "#{slug}-#{count + 1}")
+          end
+        end
+
         def page_slug(page)
           meta = page[:meta] || {}
           slug = meta["slug"] || meta[:slug]
           return sanitize_slug(slug) if slug && !slug.to_s.empty?
 
-          title = page[:title].to_s
-          return sanitize_slug(title) unless title.empty?
-
           if page[:path]
-            base = File.basename(page[:path].to_s, File.extname(page[:path].to_s))
-            return sanitize_slug(base)
+            path_slug = path_slug(page[:path])
+            return path_slug unless path_slug.empty?
           end
 
-          "page"
+          title = sanitize_slug(page[:title])
+          title.empty? ? "page" : title
+        end
+
+        def path_slug(path)
+          relative = path.to_s.delete_prefix("#{Dir.pwd}/")
+          dirname = File.dirname(relative)
+          basename = File.basename(relative, File.extname(relative))
+          parts = (dirname == ".") ? [basename] : dirname.split(File::SEPARATOR) + [basename]
+          sanitize_slug(parts.join("-"))
         end
 
         def sanitize_slug(s)
@@ -108,8 +125,8 @@ module Yard
 
         def render_index_html(pages)
           rows = pages.map do |p|
-            title = p[:title] || page_slug(p)
-            slug = page_slug(p)
+            slug = p[:__yard_yaml_slug] || page_slug(p)
+            title = p[:title] || slug
             desc = p[:description]
             %(<li><a href="#{escape_html(slug)}.html">#{escape_html(title)}</a>#{" — #{escape_html(desc)}" if desc}</li>)
           end.join("\n")

data/lib/yard/yaml/plugin.rb

@@ -4,7 +4,8 @@ module Yard
   module Yaml
     # Plugin activation for yard-yaml (Phase 3: config + discovery; still no YARD registrations).
     module Plugin
-      @activated = false
+      STATE = {activated: false, at_exit_installed: false}
+      STATE_MUTEX = Mutex.new
 
       class << self
         # Whether the plugin has been activated for the current process.
@@ -12,7 +13,7 @@ module Yard
         #
         # @return [Boolean]
         def activated?
-          @activated
+          STATE[:activated]
         end
 
         # Activate the plugin.
@@ -44,16 +45,82 @@ module Yard
             # Non-strict errors are already warned by converter/discovery
           end
 
-          @activated = true
+          STATE_MUTEX.synchronize { STATE[:activated] = true }
           nil
         end
 
+        # Install an at-exit emitter for YARD's plugin loader. YARD loads
+        # plugins before it has generated the HTML tree, so converted YAML
+        # pages must be written after YARD finishes.
+        #
+        # @param argv [Array<String>, nil] the YARD argv used to discover output
+        # @return [void]
+        def install_at_exit(argv = nil)
+          should_install = STATE_MUTEX.synchronize do
+            if STATE[:at_exit_installed]
+              false
+            else
+              STATE[:at_exit_installed] = true
+            end
+          end
+          return unless should_install
+
+          at_exit do
+            emit!(output_dir: yard_output_dir(argv || ARGV))
+          end
+          nil
+        end
+
+        # Emit converted pages collected during activation.
+        #
+        # @param output_dir [String] YARD HTML output directory
+        # @return [Array<String>]
+        def emit!(output_dir:)
+          pages = Yard::Yaml.pages
+          return [] if pages.nil? || pages.empty?
+
+          Yard::Yaml::Emitter.emit!(pages: pages, output_dir: output_dir, config: Yard::Yaml.config)
+        end
+
+        # Resolve YARD's HTML output directory from argv or .yardopts.
+        #
+        # @param argv [Array<String>]
+        # @return [String]
+        def yard_output_dir(argv)
+          output_dir_from_tokens(Array(argv).map(&:to_s)) ||
+            output_dir_from_tokens(yardopts_tokens) ||
+            "doc"
+        end
+
         # Test-helper: reset internal activation flag.
         # Not part of public API; used from test teardown to avoid state leakage.
         def __reset_state__
-          @activated = false
+          STATE_MUTEX.synchronize do
+            STATE[:activated] = false
+            STATE[:at_exit_installed] = false
+          end
+          nil
+        end
+
+        private
+
+        def output_dir_from_tokens(tokens)
+          tokens.each_with_index do |token, index|
+            return tokens[index + 1] if token == "--output" || token == "-o"
+            match = token.match(/\A--output=(.+)\z/)
+            return match[1] if match
+          end
           nil
         end
+
+        def yardopts_tokens
+          return [] unless File.file?(".yardopts")
+
+          require "shellwords"
+          Shellwords.split(File.read(".yardopts"))
+        rescue StandardError
+          []
+        end
       end
     end
   end

data/lib/yard/yaml/tag_renderer.rb

@@ -19,7 +19,7 @@ module Yard
       # @param config [Yard::Yaml::Config]
       # @return [String] HTML fragment (may be empty string)
       def render_for(object, base_dir: Dir.pwd, config: Yard::Yaml.config)
-        return "" unless object && object.respond_to?(:tags)
+        return "" unless object&.respond_to?(:tags)
 
         parts = []
 

data/lib/yard/yaml/tags.rb

@@ -24,14 +24,10 @@ module Yard
             end
           else
             # Create a minimal shim that records define_tag calls
+            calls = []
             lib = Module.new
-            class << lib
-              attr_accessor :calls
-              def define_tag(*args)
-                self.calls ||= []
-                self.calls << args
-              end
-            end
+            lib.define_singleton_method(:calls) { calls }
+            lib.define_singleton_method(:define_tag) { |*args| calls << args }
             begin
               ::YARD::Tags.const_set(:Library, lib)
             rescue StandardError

data/lib/yard/yaml/version.rb

@@ -3,8 +3,8 @@
 module Yard
   module Yaml
     module Version
-      VERSION = "0.1.0"
+      VERSION = "0.1.2"
     end
-    VERSION = Version::VERSION # Support the traditional VERSION constant.
+    VERSION = Version::VERSION # Traditional Constant Location
   end
 end

data/lib/yard/yaml.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
+require "version_gem"
 require_relative "yaml/version"
+
+Yard::Yaml::Version.class_eval do
+  extend VersionGem::Basic
+end
 require_relative "yaml/config"
 require_relative "yaml/cli"
 require_relative "yaml/plugin"
@@ -17,8 +22,11 @@ module Yard
     # Generic error for yard-yaml
     class Error < StandardError; end
 
-    @config = nil
-    @pages = nil
+    STATE = {
+      config: nil,
+      pages: nil,
+    }
+    STATE_MUTEX = Mutex.new
 
     class << self
       # Access the global configuration for yard-yaml.
@@ -28,19 +36,21 @@ module Yard
       #
       # @return [Yard::Yaml::Config]
       def config
-        @config ||= Config.new
+        STATE[:config] || STATE_MUTEX.synchronize { STATE[:config] ||= Config.new }
       end
 
       # Access collected pages (Phase 3). Nil until plugin activation performs discovery.
       # Each page is a Hash with keys: :path, :html, :title, :description, :meta
       # @return [Array<Hash>, nil]
-      attr_reader :pages
+      def pages
+        STATE[:pages]
+      end
 
       # Internal: set collected pages (used by Plugin during activation)
       def __set_pages__(list)
-        @pages = Array(list)
-        mirror_pages_to_registry(@pages)
-        @pages
+        pages = STATE_MUTEX.synchronize { STATE[:pages] = Array(list) }
+        mirror_pages_to_registry(pages)
+        pages
       end
 
       # Configure the plugin programmatically.
@@ -80,8 +90,10 @@ module Yard
 
       # Test-helper: reset memoized config to defaults (not public API)
       def __reset_state__
-        @config = nil
-        @pages = nil
+        STATE_MUTEX.synchronize do
+          STATE[:config] = nil
+          STATE[:pages] = nil
+        end
         if defined?(::Yard::Yaml::Plugin) && ::Yard::Yaml::Plugin.respond_to?(:__reset_state__)
           ::Yard::Yaml::Plugin.__reset_state__
         end

data/lib/yard-yaml.rb

@@ -4,3 +4,6 @@
 # YARD tries requiring several patterns; providing `yard-yaml` ensures
 # it can be loaded regardless of whether YARD attempts `yard-yaml` or `yard/yaml`.
 require_relative "yard/yaml"
+
+Yard::Yaml::Plugin.activate(ARGV)
+Yard::Yaml::Plugin.install_at_exit(ARGV)

data/sig/yard/yaml/version.rbs

@@ -0,0 +1,8 @@
+module Yard
+  module Yaml
+    module Version
+      VERSION: String
+    end
+    VERSION: String
+  end
+end