yard-fence 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaa318b924e8efbaddbb3666df3f71157678a5fbab11972f51550ecd48f4ddb2
-  data.tar.gz: af4bb34d3b799695511f5b880aa1fffa7d9765dcb71a8c5c780bfbd53f5d9f35
+  metadata.gz: dedaaa231c20409b1d4aedb72ac7b12c0716076eedea5375ed2a232999b2ea7b
+  data.tar.gz: f6b65e208d3fc7c9a0b19939949309e6020ad1808cb5378372ac0a6ef2511715
 SHA512:
-  metadata.gz: c59ecea9ee908fe804879b2197ab6047769d70a2256e69522afff4069ad73e95b48f370f0ab9a1827dc4f955e2e1f3ded8c7017da27869c0cb2b262e986f910c
-  data.tar.gz: 4ed6d00979a897c5ced52a0c72ae108c2eb05a29be9e73b9e0dd5bbc1546e80c6f54a1d780460b4a41268e0dcac27cff10142e70fb7826755f8ba511a6715508
+  metadata.gz: a5f0e3c15d75462209e1a717b762b137256aab58dfc44527008cf159458ed50fa47450ddb8355f0f2b006db3cff4f18ba9258ffc6f5542177c5921a2a2d42292
+  data.tar.gz: 81f406fdc8c3e399fa730ec7ab3790fa62981a96a02852abaaa8c0edca52cc8070cef89933407e142bc1e741a3f1e46cd933c369ade528cbf2f593c188d02b52

data/CHANGELOG.md

@@ -30,6 +30,29 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.6.0] - 2025-11-07
+
+- TAG: [v0.6.0][0.6.0t]
+- COVERAGE: 100.00% -- 119/119 lines in 4 files
+- BRANCH COVERAGE: 100.00% -- 34/34 branches in 4 files
+- 37.93% documented
+
+### Added
+
+- Catch unrendered code blocks and attempt to convert to HTML
+
+## [0.5.0] - 2025-11-07
+
+- TAG: [v0.5.0][0.5.0t]
+- COVERAGE: 100.00% -- 98/98 lines in 4 files
+- BRANCH COVERAGE: 100.00% -- 22/22 branches in 4 files
+- 34.62% documented
+
+### Added
+
+- Support multi-line braces
+- 100% lines / 100% branches test coverage
+
 ## [0.4.0] - 2025-11-07
 
 - TAG: [v0.4.0][0.4.0t]
@@ -82,7 +105,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.5.0...v0.6.0
+[0.6.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.6.0
+[0.5.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.4.0...v0.5.0
+[0.5.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.5.0
 [0.4.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.3.0...v0.4.0
 [0.4.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.4.0
 [0.3.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.2.0...v0.3.0

data/README.md

@@ -586,7 +586,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.084-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.119-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/yard/fence/kramdown_gfm_document.rb

@@ -12,14 +12,57 @@ require "kramdown-parser-gfm"
 module Yard
   module Fence
     class KramdownGfmDocument < Kramdown::Document
+      # Detects an unrendered fenced code block that slipped through HTML generation.
+      # Note on <details markdown="1">:
+      # - The classic kramdown parser honors the markdown="1" attribute on block HTML like <details>,
+      #   and will parse contained markdown as block-level content.
+      # - The GFM parser generally handles many cases well, and markdown="1" may appear to work in
+      #   most sections; however, we've observed edge cases where fenced code blocks inside a
+      #   <details markdown="1"> are left as literal backticks (rendered as <p>``` …</p>).
+      #   This fallback detects that situation and re-renders with the classic parser.
+      UNRENDERED_FENCE_PARAGRAPH = /<p>```/
+      DETAILS_MARKDOWN_1 = /<details[^>]*markdown=["']1["'][^>]*>/i
+
       def initialize(source, options = {})
         options[:input] = "GFM" unless options.key?(:input)
+        @__yard_fence_source = source # Keep original for potential fallback.
         super(source, options)
       end
+
+      # Override to_html to provide a smart fallback: if the GFM parse leaves literal
+      # fenced code markers (```), re-run the render with the classic 'kramdown' input which
+      # correctly evaluates markdown inside <details markdown="1"> blocks.
+      # Opt-out via ENV["YARD_FENCE_DISABLE_FALLBACK"] == "1".
+      def to_html
+        html = super
+        return html if ENV["YARD_FENCE_DISABLE_FALLBACK"] == "1"
+        return html unless @__yard_fence_source.include?("```")
+
+        if needs_fallback?(html)
+          fallback_options = @options.merge(input: "kramdown")
+          fb_html = Kramdown::Document.new(@__yard_fence_source, fallback_options).to_html
+          return fb_html if fallback_improved?(fb_html)
+        end
+        html
+      end
+
+      private
+
+      def needs_fallback?(html)
+        # Obvious failure: raw fenced code rendered as a paragraph
+        return true if html.match?(UNRENDERED_FENCE_PARAGRAPH)
+        # Edge case: details wrapper present in source but output lacks any code block
+        if @__yard_fence_source.match?(DETAILS_MARKDOWN_1)
+          has_code_block = html.include?("<pre") && html.include?("<code")
+          return !has_code_block
+        end
+        false
+      end
+
+      def fallback_improved?(fb_html)
+        fb_html.match?(UNRENDERED_FENCE_PARAGRAPH) == false &&
+          fb_html.include?("<pre") && fb_html.include?("<code")
+      end
     end
   end
 end
-
-# Note:
-# We intentionally do NOT auto-register here to avoid circular require warnings when
-# YARD is loading. Prefer calling Yard::Fence.use_kramdown_gfm! from your .yardopts.

data/lib/yard/fence/version.rb

@@ -3,7 +3,7 @@
 module Yard
   module Fence
     module Version
-      VERSION = "0.4.0"
+      VERSION = "0.6.0"
     end
     VERSION = Version::VERSION
   end

data/lib/yard/fence.rb

@@ -61,12 +61,19 @@ module Yard
   module Fence
     ASCII_BRACES = "{}"
     FULLWIDTH_BRACES = "｛｝"
+    # IMPORTANT: YARD expects :const to be a String.
+    # YARD concatenates with a String prefix (e.g., "::" + const),
+    # so a Symbol here will break provider resolution. Some static analyzers
+    # suggest making this a Symbol to match types, but that is incorrect for YARD.
+    # Do NOT change this to a Symbol.
     KRAMDOWN_PROVIDER = {lib: :kramdown, const: "KramdownGfmDocument"}
     GLOB_PATTERN = "*.{md,MD,txt,TXT}"
     TRIPLE_TICK_FENCE = /^\s*```/
     INLINE_TICK_FENCE = /`([^`]+)`/
     DOUBLE_BRACE_PLACEHOLDER_REGEX = /{{([^{}]+)}}/
     SINGLE_BRACE_PLACEHOLDER_REGEX = /{([A-Za-z0-9_:\-]+)}/
+    # Lines that are part of a classic indented code block (CommonMark: 4 spaces)
+    INDENTED_CODE_LINE = /^ {4,}\S/
 
     class Error < StandardError; end
     # :nocov:
@@ -84,8 +91,11 @@ module Yard
 
     # Escape braces inside inline `code` spans only.
     def sanitize_inline_code(line)
-      # Use $1 because the block parameter (_) is the matched substring, not a MatchData object.
-      line.gsub(INLINE_TICK_FENCE) { |_| "`#{fullwidth_braces($1)}`" }
+      # Use Regexp.last_match to safely access capture; to_s guards against nil
+      line.gsub(INLINE_TICK_FENCE) do |_|
+        inner = Regexp.last_match(1).to_s
+        "`#{fullwidth_braces(inner)}`"
+      end
     end
 
     # Walk the text, toggling a simple in_fence state on ``` lines.
@@ -93,13 +103,31 @@ module Yard
     # and disarm simple prose placeholders like ｛issuer｝ or ｛｛something｝｝.
     def sanitize_fenced_blocks(text)
       in_fence = false
+      in_indented_block = false
 
       text.each_line.map do |line|
         if line.match?(TRIPLE_TICK_FENCE)
+          # Toggle fenced block state; leaving indented block if switching into explicit fence
           in_fence = !in_fence
+          in_indented_block = false if in_fence
           line
         elsif in_fence
           fullwidth_braces(line)
+        elsif in_indented_block
+          # Continue indented block until a blank line or non-indented line breaks it
+          if line.strip.empty? || !line.match?(INDENTED_CODE_LINE)
+            in_indented_block = false
+            # Process this line as normal prose outside block
+            ln = sanitize_inline_code(line)
+            ln = ln.gsub(DOUBLE_BRACE_PLACEHOLDER_REGEX) { |m| fullwidth_braces(m) }
+            ln.gsub(SINGLE_BRACE_PLACEHOLDER_REGEX) { |m| fullwidth_braces(m) }
+          else
+            fullwidth_braces(line)
+          end
+        elsif line.match?(INDENTED_CODE_LINE)
+          # Enter indented code block on first qualifying line
+          in_indented_block = true
+          fullwidth_braces(line)
         else
           ln = sanitize_inline_code(line)
           # IMPORTANT: handle double-brace placeholders first so we don't partially
@@ -162,6 +190,10 @@ module Yard
       end
       # :nocov:
       providers = ::YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown]
+      # NOTE: Intentionally using String for :const in KRAMDOWN_PROVIDER.
+      # YARD performs string concatenation with this value (e.g., "::" + const).
+      # Changing it to a Symbol to satisfy static type hints breaks runtime behavior.
+      # Suppress type fuzz complaints: expected Hash{Symbol->Symbol}, actual includes String by design.
       providers.unshift(KRAMDOWN_PROVIDER)
       providers.uniq! { |p| [p[:lib].to_s, p[:const].to_s] }
       true
@@ -169,14 +201,16 @@ module Yard
       warn("Yard::Fence.use_kramdown_gfm!: failed to load YARD helper: #{e.class}: #{e.message}")
       false
     end
+
+    def at_load_hook
+      Yard::Fence.prepare_tmp_files
+    rescue => e
+      warn("Yard::Fence: failed to prepare tmp/yard-fence files: #{e.class}: #{e.message}")
+    end
   end
 
   # Execute at load-time so files exist before YARD scans tmp/yard-fence/*.md
-  begin
-    Yard::Fence.prepare_tmp_files
-  rescue => e
-    warn("Yard::Fence: failed to prepare tmp/yard-fence files: #{e.class}: #{e.message}")
-  end
+  Yard::Fence.at_load_hook
 end
 
 # Extend the Version with VersionGem::Basic to provide semantic version helpers.
@@ -184,6 +218,8 @@ Yard::Fence::Version.class_eval do
   extend VersionGem::Basic
 end
 
+# :nocov:
+# Not checking coverage of the at_exit hook, because it would require a forked process.
 unless ENV["YARD_FENCE_SKIP_AT_EXIT"] == "1"
   # After YARD completes, restore ASCII braces in generated HTML docs.
   # This guarantees the published docs (docs/*.html) show and copy normal { }.
@@ -191,3 +227,4 @@ unless ENV["YARD_FENCE_SKIP_AT_EXIT"] == "1"
     Yard::Fence.postprocess_html_docs
   end
 end
+# :nocov:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-fence
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -316,10 +316,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://yard-fence.galtzo.com/
-  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.4.0
-  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.4.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.6.0
+  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.6.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-fence/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.4.0
+  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.6.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/yard-fence/wiki
   news_uri: https://www.railsbling.com/tags/yard-fence