yard-fence 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c452cadbc7138751c282b00e156b13a181a6dde7de5ea94b9a11f2e4b2cd8b
-  data.tar.gz: 82255194452e4fd285fc1c48b72daf6c6a4d3d3a0a628d237e7ec4e2c3a50bc1
+  metadata.gz: 5baded4374cd088861f834e9979c206e08dac16af4c52fdbf3d28ea1e7ce8c58
+  data.tar.gz: bf14fe77229b435e7361883d6dd6128bcff08f58ed8a7742fb88eb9223148a2d
 SHA512:
-  metadata.gz: 81831151e5e12a8cab9fde1c590ba09c3b10a45e49fadb47565827f30aaca3eec7494d2005ff7a6d97a16a20d6cc74e93b8ad1fceb7b766d7e31a62bbf2f692f
-  data.tar.gz: 8b46e712c8705da88215adc176afe5e3d908ace26d0ecc2e8303150091042420bbf60907a29e477d58caa061531df84fdc9c237609f10b0dd529c4be6622d179
+  metadata.gz: 0c10875a2282e3e6613bdc39bcf37b5aa3507489a5f94406ded819765e3a9feb3ab1581c8a9a3e9c4b11e22564bafb0c7f137db6f7f038248e4d59827080cbdf
+  data.tar.gz: fae576e37e8f9c840bb5e6c772cfdfa7e8eb5e3a065ae9c3deda8d23860595a6827f52f529ae7d12944be2321d4fe0a74753e752505b8b2574a4df49704f1803

data/CHANGELOG.md

@@ -30,6 +30,40 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.3.0] - 2025-11-07
+
+- TAG: [v0.3.0][0.3.0t]
+- COVERAGE: 96.43% -- 81/84 lines in 4 files
+- BRANCH COVERAGE: 93.75% -- 15/16 branches in 4 files
+- 29.17% documented
+
+### Added
+
+- yard/fence/hoist.rb: Hoisting the customized GFM kramdown parser
+
+## [0.2.0] - 2025-11-07
+
+- TAG: [v0.2.0][0.2.0t]
+- COVERAGE: 96.43% -- 81/84 lines in 4 files
+- BRANCH COVERAGE: 93.75% -- 15/16 branches in 4 files
+- 29.17% documented
+
+### Added
+
+- Up to 96% lines / 93% branches test coverage
+
+### Fixed
+
+- handling of optional dependencies
+    - kramdown
+    - kramdown-parser-gfm
+
 ## [0.1.0] - 2025-11-06
 
 - Initial release
+
+[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.2.0...v0.3.0
+[0.3.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.3.0
+[0.2.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.1.0...v0.2.0
+[0.2.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.2.0

data/README.md

@@ -48,7 +48,7 @@
 
 ## 🌻 Synopsis
 
-A brace converter for the markdown fences in your YARD docs.
+A brace converter for the markdown fences in your YARD docs to prevent the `InvalidLink` warning.
 
 Just the important bits:
 - Preprocesses top-level README and other `.md`/`.txt` files into `tmp/` replacing ASCII braces inside fenced code blocks, inline code spans, and simple placeholders like `{issuer}` or `{{TOKEN}}` with visually identical fullwidth braces.
@@ -56,6 +56,22 @@ Just the important bits:
 - Prioritizes Kramdown's GFM parser so tables and fenced code blocks render correctly.
 - After YARD finishes generating HTML, restores fullwidth braces back to normal ASCII braces so code examples are copy‑pastable.
 
+Create a `.yardopts` file like this:
+
+```text
+--plugin fence
+-e yard/fence/hoist.rb
+--readme tmp/README.md
+--markup markdown
+--output docs
+'lib/**/*.rb'
+-
+'tmp/*.md'
+'tmp/*.txt'
+```
+
+See the configuration and usage sections for more details.
+
 ## 💡 Info you can shake a stick at
 
 | Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                                                          |
@@ -175,7 +191,7 @@ Recommended .yardopts (noise‑free):
 
 ```text
 --plugin fence
--e 'Yard::Fence.use_kramdown_gfm!'
+-e yard/fence/hoist.rb
 --readme tmp/README.md
 --markup markdown
 --output docs
@@ -195,7 +211,7 @@ CLI example that would be similar to what is accomplished by the `.yardopts` fro
 ```bash
 yard doc \
   --plugin fence \
-  -e 'Yard::Fence.use_kramdown_gfm!' \
+  -e yard/fence/hoist.rb \
   --readme tmp/README.md \
   lib/**/*.rb - tmp/*.md tmp/*.txt
 ```
@@ -557,7 +573,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-4.278-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.084-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/hoist.rb

@@ -0,0 +1,9 @@
+if defined?(Yard::Fence) && Yard::Fence.respond_to?(:use_kramdown_gfm!)
+  if Yard::Fence.use_kramdown_gfm!
+    puts "[yard/fence/hoist] Kramdown GFM provider registered"
+  else
+    warn "[yard/fence/hoist] Kramdown GFM provider registration failed"
+  end
+else
+  warn("[yard/fence/hoist] Yard::Fence.use_kramdown_gfm! not available; skipping")
+end

data/lib/yard/fence/version.rb

@@ -3,7 +3,7 @@
 module Yard
   module Fence
     module Version
-      VERSION = "0.1.0"
+      VERSION = "0.3.0"
     end
     VERSION = Version::VERSION
   end

data/lib/yard/fence.rb

@@ -43,7 +43,19 @@ require "version_gem"
 
 # includes gem files
 require_relative "fence/version"
-require_relative "fence/kramdown_gfm_document"
+begin
+  require_relative "fence/kramdown_gfm_document"
+# :nocov:
+# Not covering, because kramdown support is tested, so this rescue is not hit in test runs.
+rescue LoadError => error
+  # check the error message, and re-raise if not what is expected
+  if error.message.include?("kramdown")
+    warn("Yard::Fence: Kramdown GFM provider not loaded: #{error.class}: #{error.message}") if ENV.fetch("YARD_DEBUG", "false").casecmp?("true")
+  else
+    raise error
+  end
+end
+# :nocov:
 
 module Yard
   module Fence
@@ -57,7 +69,10 @@ module Yard
     SINGLE_BRACE_PLACEHOLDER_REGEX = /{([A-Za-z0-9_:\-]+)}/
 
     class Error < StandardError; end
+    # :nocov:
+    # This is a runtime sanity check to ensure our fullwidth braces differ from ASCII braces.
     raise Error, "ASCII braces are not the same as Unicode Fullwidth braces" if ASCII_BRACES == FULLWIDTH_BRACES
+    # :nocov:
 
     module_function
 
@@ -139,6 +154,12 @@ module Yard
     # require warnings when YARD is in the middle of loading itself. Call this
     # from a file loaded via .yardopts (e.g. `-e 'require "yard/fence/kramdown_gfm"; Yard::Fence.use_kramdown_gfm!'`).
     def use_kramdown_gfm!
+      # :nocov:
+      # Not covering, because kramdown support is tested, so this rescue is not hit in test runs.
+      unless defined?(Yard::Fence::KramdownGfmDocument)
+        raise Error, "Yard::Fence: Kramdown GFM provider not loaded. Add kramdown and kramdown-parser-gfm to your Gemfile."
+      end
+      # :nocov:
       providers = ::YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown]
       providers.unshift(KRAMDOWN_PROVIDER)
       providers.uniq! { |p| [p[:lib].to_s, p[:const].to_s] }
@@ -162,8 +183,10 @@ Yard::Fence::Version.class_eval do
   extend VersionGem::Basic
 end
 
-# After YARD completes, restore ASCII braces in generated HTML docs.
-# This guarantees the published docs (docs/*.html) show and copy normal { }.
-at_exit do
-  Yard::Fence.postprocess_html_docs
+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 { }.
+  at_exit do
+    Yard::Fence.postprocess_html_docs
+  end
 end

data/sig/kramdown.rbs

@@ -1,6 +1,6 @@
+# (RBS) Kramdown minimal signatures used by yard-fence
 module Kramdown
   class Document
     def initialize: (String source, ?::Hash[Symbol, untyped] options) -> void
   end
 end
-

data/sig/yard/fence.rbs

@@ -1,10 +1,10 @@
 module Yard
   module Fence
-    # Constants
+    # Constants (refined literal types where possible)
     VERSION: String
-    ASCII_BRACES: String
-    FULLWIDTH_BRACES: String
-    KRAMDOWN_PROVIDER: Hash[Symbol, untyped]
+    ASCII_BRACES: "{}"
+    FULLWIDTH_BRACES: "｛｝"
+    KRAMDOWN_PROVIDER: { lib: Symbol, const: String }
     GLOB_PATTERN: String
     TRIPLE_TICK_FENCE: ::Regexp
     INLINE_TICK_FENCE: ::Regexp
@@ -15,16 +15,33 @@ module Yard
     class Error < ::StandardError
     end
 
-    # Module functions
+    # Module functions (available both as singleton and instance via module_function)
     def self.fullwidth_braces: (String str) -> String
+    def fullwidth_braces: (String str) -> String
+
     def self.sanitize_inline_code: (String line) -> String
+    def sanitize_inline_code: (String line) -> String
+
     def self.sanitize_fenced_blocks: (String text) -> String
+    def sanitize_fenced_blocks: (String text) -> String
+
+    # Accept any object; if String returns String, otherwise returns original (untyped)
     def self.sanitize_text: (String text) -> String
                           | (untyped text) -> untyped
+    def sanitize_text: (String text) -> String
+                     | (untyped text) -> untyped
+
     def self.prepare_tmp_files: () -> void
+    def prepare_tmp_files: () -> void
+
     def self.restore_ascii_braces_in_html_file: (String html_filepath) -> void
+    def restore_ascii_braces_in_html_file: (String html_filepath) -> void
+
     def self.postprocess_html_docs: () -> void
+    def postprocess_html_docs: () -> void
+
     def self.use_kramdown_gfm!: () -> bool
+    def use_kramdown_gfm!: () -> bool
 
     module Version
       VERSION: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-fence
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -306,6 +306,7 @@ files:
 - SECURITY.md
 - lib/yard-fence.rb
 - lib/yard/fence.rb
+- lib/yard/fence/hoist.rb
 - lib/yard/fence/kramdown_gfm_document.rb
 - lib/yard/fence/version.rb
 - sig/kramdown.rbs
@@ -315,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.1.0
-  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.3.0
+  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.3.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-fence/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.1.0
+  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.3.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