yard-fence 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5baded4374cd088861f834e9979c206e08dac16af4c52fdbf3d28ea1e7ce8c58
-  data.tar.gz: bf14fe77229b435e7361883d6dd6128bcff08f58ed8a7742fb88eb9223148a2d
+  metadata.gz: '0909353a8e193134a57cf571979c154be5c08adb0ce6c53855282996ea8d96de'
+  data.tar.gz: 69400f31490fb97d56aa19a79519c7f15c160b689b48ca6d0228df640410655b
 SHA512:
-  metadata.gz: 0c10875a2282e3e6613bdc39bcf37b5aa3507489a5f94406ded819765e3a9feb3ab1581c8a9a3e9c4b11e22564bafb0c7f137db6f7f038248e4d59827080cbdf
-  data.tar.gz: fae576e37e8f9c840bb5e6c772cfdfa7e8eb5e3a065ae9c3deda8d23860595a6827f52f529ae7d12944be2321d4fe0a74753e752505b8b2574a4df49704f1803
+  metadata.gz: e7e3af604e115d051dac3bb1763df43aeacdd693c947504ace79f8864f12e343ea54e065be3b3b13e55b4b29bc8d193fcb939c44fbcad3a6f0307df5c55dd06e
+  data.tar.gz: 28c385b149403931cf456ad76223a33b12df2272fa47bcde51cfff31344e43b699227a7a10902f27e910beced70db24fd674b0831e2652ef7dc487669139ca78

data/CHANGELOG.md

@@ -30,6 +30,38 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [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]
+- COVERAGE: 96.43% -- 81/84 lines in 4 files
+- BRANCH COVERAGE: 93.75% -- 15/16 branches in 4 files
+- 29.17% documented
+
+### Added
+
+- Docs: Document importance of `require: false` in `Gemfile` for this gem
+
+### Changed
+
+- Docs: Improved markdown syntax in README.md for Kramdown => HTML
+
+### Fixed
+
+- Use namespaced directory in `tmp/` (`tmp/yard-fence`)
+  - avoids polluting, and pollution from, other garbage in `tmp/`
+
 ## [0.3.0] - 2025-11-07
 
 - TAG: [v0.3.0][0.3.0t]
@@ -62,7 +94,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.3.0...HEAD
+[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.5.0...HEAD
+[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
 [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

data/README.md

@@ -51,7 +51,8 @@
 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.
+
+- Preprocesses top-level README and other `.md`/`.txt` files into `tmp/yard-fence/` replacing ASCII braces inside fenced code blocks, inline code spans, and simple placeholders like `{issuer}` or `{{TOKEN}}` with visually identical fullwidth braces.
 - This prevents YARD from emitting `InvalidLink` warnings.
 - 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.
@@ -61,13 +62,13 @@ Create a `.yardopts` file like this:
 ```text
 --plugin fence
 -e yard/fence/hoist.rb
---readme tmp/README.md
+--readme tmp/yard-fence/README.md
 --markup markdown
 --output docs
 'lib/**/*.rb'
 -
-'tmp/*.md'
-'tmp/*.txt'
+'tmp/yard-fence/*.md'
+'tmp/yard-fence/*.txt'
 ```
 
 See the configuration and usage sections for more details.
@@ -97,7 +98,7 @@ Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRu
 
 ### Federated DVCS
 
-<details>
+<details markdown="1">
   <summary>Find this repo on federated forges (Coming soon!)</summary>
 
 | Federated [DVCS][💎d-in-dvcs] Repository           | Status                                                                | Issues                    | PRs                      | Wiki                      | CI                       | Discussions                  |
@@ -115,7 +116,7 @@ Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRu
 
 Available as part of the Tidelift Subscription.
 
-<details>
+<details markdown="1">
   <summary>Need enterprise-level guarantees?</summary>
 
 The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
@@ -139,7 +140,18 @@ Alternatively:
 Install the gem and add to the application's Gemfile by executing:
 
 ```console
-bundle add yard-fence
+bundle add yard-fence --require false
+```
+
+NOTE: if you add it directly to your Gemfile,
+be sure to include `require: false` so bundler doesn't load it when bootstrapping.
+This is important because this gem has a global `at_exit` callback that only makes sense to run after yard runs.
+As such this gem should only be loaded by YARD itself via the `--plugin fence` option.
+
+Example:
+
+```ruby
+gem "yard-fence", "~> 0.3", require: false
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
@@ -150,7 +162,7 @@ gem install yard-fence
 
 ### 🔒 Secure Installation
 
-<details>
+<details markdown="1">
   <summary>For Medium or High Security Installations</summary>
 
 This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
@@ -185,24 +197,25 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
-Yard::Fence writes sanitized copies of top‑level Markdown/TXT into tmp/ at load time. To avoid YARD parsing the unsanitized originals, point YARD at the tmp/ copies.
+NOTE: `Yard::Fence` writes sanitized copies of top‑level Markdown/TXT into `tmp/yard-fence/` at load time. To avoid YARD parsing the unsanitized originals, point YARD at the `tmp/yard-fence/` copies.
 
 Recommended .yardopts (noise‑free):
 
 ```text
 --plugin fence
 -e yard/fence/hoist.rb
---readme tmp/README.md
+--readme tmp/yard-fence/README.md
 --markup markdown
 --output docs
 'lib/**/*.rb'
 -
-'tmp/*.md'
-'tmp/*.txt'
+'tmp/yard-fence/*.md'
+'tmp/yard-fence/*.txt'
 ```
 
-Why tmp/?
-- The plugin converts ASCII `{ }` to fullwidth `｛ ｝` only in `tmp/` so YARD won’t treat brace content as reference tags and emit InvalidLink warnings. After docs are generated, the HTML is restored back to normal ASCII braces for easy copy/paste.
+Why tmp/yard-fence/?
+
+- The plugin converts ASCII `{ }` to fullwidth `｛ ｝` only in `tmp/yard-fence/` so YARD won’t treat brace content as reference tags and emit `InvalidLink` warnings. After docs are generated, the HTML is restored back to normal ASCII braces for easy copy/paste.
 
 ## 🔧 Basic Usage
 
@@ -212,8 +225,8 @@ CLI example that would be similar to what is accomplished by the `.yardopts` fro
 yard doc \
   --plugin fence \
   -e yard/fence/hoist.rb \
-  --readme tmp/README.md \
-  lib/**/*.rb - tmp/*.md tmp/*.txt
+  --readme tmp/yard-fence/README.md \
+  lib/**/*.rb - tmp/yard-fence/*.md tmp/yard-fence/*.txt
 ```
 
 ## 🦷 FLOSS Funding
@@ -344,10 +357,10 @@ the [Pessimistic Version Constraint][📌pvc] with two digits of precision.
 For example:
 
 ```ruby
-spec.add_dependency("yard-fence", "~> 1.0")
+spec.add_dependency("yard-fence", "~> 0.4")
 ```
 
-<details>
+<details markdown="1">
 <summary>📌 Is "Platform Support" part of the public API? More details inside.</summary>
 
 SemVer should, IMO, but doesn't explicitly, say that dropping support for specific Platforms
@@ -573,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.098-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/version.rb

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

data/lib/yard/fence.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Prepare sanitized copies of Markdown/TXT files in tmp/ for YARD consumption.
+# Prepare sanitized copies of Markdown/TXT files in tmp/yard-fence/ for YARD consumption.
 #
 # Why this exists
 # - YARD treats any `{…}` sequence in extra files (like README.md) as a potential link
@@ -14,8 +14,8 @@
 #   no backslash escapes sprinkled throughout examples).
 # - We need YARD to stop interpreting code-fenced braces as links.
 #
-# Strategy (tmp/ preprocessor)
-# - At doc build time, copy top-level *.md/*.txt into tmp/ and transform only the risky
+# Strategy (tmp/yard-fence/ preprocessor)
+# - At doc build time, copy top-level *.md/*.txt into tmp/yard-fence/ and transform only the risky
 #   brace pairs in contexts YARD misinterprets:
 #   * inside triple‑backtick fenced code blocks
 #   * inside single‑backtick inline code spans
@@ -28,7 +28,7 @@
 #
 # Key lines to see:
 # - Transform to fullwidth:   str.tr('{}', '｛｝')
-#   This replaces ASCII { and } with their fullwidth Unicode counterparts in sanitized tmp files.
+#   This replaces ASCII { and } with their fullwidth Unicode counterparts in sanitized tmp/yard-fence files.
 # - Restore to ASCII (HTML):  out = src.tr('｛｝', '{}')
 #   This runs after docs are generated and rewrites the HTML contents back to normal { and }.
 #
@@ -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,7 +91,11 @@ module Yard
 
     # Escape braces inside inline `code` spans only.
     def sanitize_inline_code(line)
-      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.
@@ -92,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
@@ -114,10 +143,10 @@ module Yard
       sanitize_fenced_blocks(text)
     end
 
-    # Copy top-level *.md/*.txt into tmp/ with the above sanitization applied.
+    # Copy top-level *.md/*.txt into tmp/yard-fence/ with the above sanitization applied.
     def prepare_tmp_files
       root = Dir.pwd
-      outdir = File.join(root, "tmp")
+      outdir = File.join(root, "tmp", "yard-fence")
       FileUtils.mkdir_p(outdir)
 
       candidates = Dir.glob(File.join(root, GLOB_PATTERN))
@@ -161,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
@@ -168,14 +201,16 @@ module Yard
       warn("Yard::Fence.use_kramdown_gfm!: failed to load YARD helper: #{e.class}: #{e.message}")
       false
     end
-  end
 
-  # Execute at load-time so files exist before YARD scans tmp/*.md
-  begin
-    Yard::Fence.prepare_tmp_files
-  rescue => e
-    warn("Yard::Fence: failed to prepare tmp files: #{e.class}: #{e.message}")
+    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
+  Yard::Fence.at_load_hook
 end
 
 # Extend the Version with VersionGem::Basic to provide semantic version helpers.
@@ -183,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 { }.
@@ -190,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.3.0
+  version: 0.5.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.3.0
-  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.3.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.5.0
+  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.5.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-fence/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.3.0
+  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.5.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