yard-fence 0.1.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/yard/fence/kramdown_gfm_document.rb

@@ -0,0 +1,25 @@
+# YARD GFM support shim: ensure Kramdown GFM provider is first in the provider list
+# so markdown code fences and GitHub-style markdown render as expected. This does not
+# alter content; it influences the order in which YARD tries markdown engines.
+# See test_gfm.rb for a quick sanity check of provider order and <pre><code> rendering.
+
+# Gratefully and liberally taken from the MIT-licensed https://github.com/bensheldon/good_job/pull/113/files
+require "kramdown"
+require "kramdown-parser-gfm"
+
+# Custom markup provider class that always renders Kramdown using GFM (Github Flavored Markdown).
+# GFM is needed to render markdown tables and fenced code blocks in the README.
+module Yard
+  module Fence
+    class KramdownGfmDocument < Kramdown::Document
+      def initialize(source, options = {})
+        options[:input] = "GFM" unless options.key?(:input)
+        super(source, options)
+      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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Yard
+  module Fence
+    module Version
+      VERSION = "0.1.0"
+    end
+    VERSION = Version::VERSION
+  end
+end

data/lib/yard/fence.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# Prepare sanitized copies of Markdown/TXT files in tmp/ for YARD consumption.
+#
+# Why this exists
+# - YARD treats any `{…}` sequence in extra files (like README.md) as a potential link
+#   to a code object (its "reference tag" syntax). This scanning happens outside of
+#   the Markdown renderer and does not reliably respect fenced code blocks.
+# - As a result, normal hash literals in code examples, e.g. {get: :query} or
+#   {"Authorization" => "Basic ..."}, trigger lots of `[InvalidLink] Cannot resolve link` warnings.
+#
+# Our constraints
+# - We want to keep the source Markdown clean and readable on GitHub (no HTML entities,
+#   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
+#   brace pairs in contexts YARD misinterprets:
+#   * inside triple‑backtick fenced code blocks
+#   * inside single‑backtick inline code spans
+#   * simple brace placeholders in prose like ｛issuer｝ or ｛｛TEMPLATE｝｝
+# - The transformation uses Unicode "fullwidth" braces: ｛ and ｝.
+#   These look like normal ASCII braces when rendered, but importantly they do not match
+#   YARD's `{…}` reference tag regex, so they are ignored by the link resolver.
+# - After YARD finishes generating HTML into docs/, we post‑process the HTML and convert
+#   fullwidth braces back to ASCII braces so copying code from the docs works as expected.
+#
+# Key lines to see:
+# - Transform to fullwidth:   str.tr('{}', '｛｝')
+#   This replaces ASCII { and } with their fullwidth Unicode counterparts in sanitized tmp files.
+# - Restore to ASCII (HTML):  out = src.tr('｛｝', '{}')
+#   This runs after docs are generated and rewrites the HTML contents back to normal { and }.
+#
+# This keeps README.md pristine while eliminating YARD InvalidLink noise and ensuring
+# the published docs remain copy‑pastable.
+
+# includes modules from stdlib
+require "fileutils"
+
+# third party gems
+require "version_gem"
+
+# includes gem files
+require_relative "fence/version"
+require_relative "fence/kramdown_gfm_document"
+
+module Yard
+  module Fence
+    ASCII_BRACES = "{}"
+    FULLWIDTH_BRACES = "｛｝"
+    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_:\-]+)}/
+
+    class Error < StandardError; end
+    raise Error, "ASCII braces are not the same as Unicode Fullwidth braces" if ASCII_BRACES == FULLWIDTH_BRACES
+
+    module_function
+
+    # Replace ASCII { } with Unicode fullwidth ｛ ｝.
+    # Visual effect in browsers is the same, but YARD's link matcher won't recognize them.
+    def fullwidth_braces(str)
+      str.tr(ASCII_BRACES, FULLWIDTH_BRACES)
+    end
+
+    # Escape braces inside inline `code` spans only.
+    def sanitize_inline_code(line)
+      line.gsub(INLINE_TICK_FENCE) { |_| "`#{fullwidth_braces($1)}`" }
+    end
+
+    # Walk the text, toggling a simple in_fence state on ``` lines.
+    # While inside a fence, convert braces to fullwidth; outside, also sanitize inline code
+    # and disarm simple prose placeholders like ｛issuer｝ or ｛｛something｝｝.
+    def sanitize_fenced_blocks(text)
+      in_fence = false
+
+      text.each_line.map do |line|
+        if line.match?(TRIPLE_TICK_FENCE)
+          in_fence = !in_fence
+          line
+        elsif in_fence
+          fullwidth_braces(line)
+        else
+          ln = sanitize_inline_code(line)
+          # IMPORTANT: handle double-brace placeholders first so we don't partially
+          # convert the inner {TOKEN} and leave outer ASCII braces from `{｛TOKEN｝}`.
+          ln = ln.gsub(DOUBLE_BRACE_PLACEHOLDER_REGEX) { |m| fullwidth_braces(m) }
+          ln.gsub(SINGLE_BRACE_PLACEHOLDER_REGEX) { |m| fullwidth_braces(m) }
+        end
+      end.join
+    end
+
+    def sanitize_text(text)
+      return text unless text.is_a?(String)
+      sanitize_fenced_blocks(text)
+    end
+
+    # Copy top-level *.md/*.txt into tmp/ with the above sanitization applied.
+    def prepare_tmp_files
+      root = Dir.pwd
+      outdir = File.join(root, "tmp")
+      FileUtils.mkdir_p(outdir)
+
+      candidates = Dir.glob(File.join(root, GLOB_PATTERN))
+      candidates.each do |src|
+        next unless File.file?(src)
+        content = File.read(src)
+        sanitized = sanitize_text(content)
+        dst = File.join(outdir, File.basename(src))
+        File.write(dst, sanitized)
+      end
+    end
+
+    def restore_ascii_braces_in_html_file(html_filepath)
+      return unless File.file?(html_filepath)
+      content = File.read(html_filepath)
+      restored = content.tr(FULLWIDTH_BRACES, ASCII_BRACES)
+      File.write(html_filepath, restored)
+    end
+
+    def postprocess_html_docs
+      docs = File.join(Dir.pwd, "docs")
+      return unless Dir.exist?(docs)
+      Dir.glob(File.join(docs, "**", "*.html")).each do |html|
+        restore_ascii_braces_in_html_file(html)
+      end
+    rescue => e
+      warn("Yard::Fence.postprocess_html_docs failed: #{e.class}: #{e.message}")
+    end
+
+    # Register Kramdown GFM as the highest priority Markdown provider in YARD.
+    # Returns true if registration succeeded, false otherwise.
+    #
+    # This method is intentionally not executed at file load to avoid circular
+    # 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!
+      providers = ::YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown]
+      providers.unshift(KRAMDOWN_PROVIDER)
+      providers.uniq! { |p| [p[:lib].to_s, p[:const].to_s] }
+      true
+    rescue NameError => e
+      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}")
+  end
+end
+
+# Extend the Version with VersionGem::Basic to provide semantic version helpers.
+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
+end

data/lib/yard-fence.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# YARD plugin loader for `--plugin fence`.
+# YARD tries requiring several patterns; providing `yard-fence` ensures
+# it can be loaded regardless of whether YARD attempts `yard-fence` or `yard/fence`.
+require_relative "yard/fence"

data/sig/kramdown.rbs

@@ -0,0 +1,6 @@
+module Kramdown
+  class Document
+    def initialize: (String source, ?::Hash[Symbol, untyped] options) -> void
+  end
+end
+

data/sig/yard/fence.rbs

@@ -0,0 +1,37 @@
+module Yard
+  module Fence
+    # Constants
+    VERSION: String
+    ASCII_BRACES: String
+    FULLWIDTH_BRACES: String
+    KRAMDOWN_PROVIDER: Hash[Symbol, untyped]
+    GLOB_PATTERN: String
+    TRIPLE_TICK_FENCE: ::Regexp
+    INLINE_TICK_FENCE: ::Regexp
+    DOUBLE_BRACE_PLACEHOLDER_REGEX: ::Regexp
+    SINGLE_BRACE_PLACEHOLDER_REGEX: ::Regexp
+
+    # Error class
+    class Error < ::StandardError
+    end
+
+    # Module functions
+    def self.fullwidth_braces: (String str) -> String
+    def self.sanitize_inline_code: (String line) -> String
+    def self.sanitize_fenced_blocks: (String text) -> String
+    def self.sanitize_text: (String text) -> String
+                          | (untyped text) -> untyped
+    def self.prepare_tmp_files: () -> void
+    def self.restore_ascii_braces_in_html_file: (String html_filepath) -> void
+    def self.postprocess_html_docs: () -> void
+    def self.use_kramdown_gfm!: () -> bool
+
+    module Version
+      VERSION: String
+    end
+
+    class KramdownGfmDocument < ::Kramdown::Document
+      def initialize: (String source, ?Hash[Symbol, untyped] options) -> void
+    end
+  end
+end