yard-markdown 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92bac83ffe7c1f83b26164adef991efe13678b96096ba61af2626f83e9505991
-  data.tar.gz: 7c871bffa551b5acc83e0b954163d933b7289db6542b1485c385ab97fb53e4eb
+  metadata.gz: 20eaf2ccb5ab45418bcb82e961f472231fb5d705090e8650dd854a8cc0e1d92f
+  data.tar.gz: ec1a4f6d7f3afa2f7af44c44a72af9ba6a22148ffeb643dda1ffbb747a0cf1ee
 SHA512:
-  metadata.gz: 7d7fb3ae97903f7c61aa0a057cdefd878a562264d15d5e7a3da17a5a2bdd5ea35c63cc47244022ab10fe20356c7adf367eee27e1de5b67281376174645c29b54
-  data.tar.gz: 126033d377d8e652a19b33731d57ccfad197731cf819521766dbee5b37d1ee293baf41fc58c7927073ae3cddea9c5a4227b57539023de96ff66740e3d53e88d7
+  metadata.gz: ea0c103943a5b5361ecab753fa0d014835016a6a154bb77552e7c8d3c1f253eea2a8c62c2aafe2d7f72afd31dfe5cac763c864a7768cd0126bc229ba8f19ace4
+  data.tar.gz: 0f2ade24652236aef7cfb310cafe04f1f0dcc43a5bccba854ec9712d0a7edb752d91a6f85b723a8c5e19e66aff798ff2cbf669b4e5401f33f2f18c66875e8dd3

data/.standard.yml

@@ -0,0 +1,3 @@
+ignore:
+  - "example_*.rb"
+  - "test/example/example.rb"

data/.yard-lint.yml

@@ -0,0 +1,317 @@
+# YARD-Lint Configuration (Strict Mode)
+# See https://github.com/mensfeld/yard-lint for documentation
+#
+# This is a strict configuration suitable for new projects with high documentation standards.
+# All validators are set to 'error' severity (no warnings or conventions).
+# Minimum coverage is set to 100%.
+
+# Global settings for all validators
+AllValidators:
+  # YARD command-line options (applied to all validators by default)
+  YardOptions:
+    - --private
+    - --protected
+
+  # Global file exclusion patterns
+  Exclude:
+    - '\.git'
+    - "vendor/**/*"
+    - "node_modules/**/*"
+    - "spec/**/*"
+    - "test/**/*"
+    - "tmp/**/*"
+    - "example_rdoc.rb"
+    - "example_yard.rb"
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: error
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  MinCoverage: 100.0
+
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: "Checks for classes, modules, and methods without documentation."
+  Enabled: true
+  Severity: error
+  ExcludedMethods:
+    - "initialize/0" # Exclude parameter-less initialize
+    - "/^_/" # Exclude private methods (by convention)
+
+Documentation/UndocumentedMethodArguments:
+  Description: "Checks for method parameters without @param tags."
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedBooleanMethods:
+  Description: "Checks that question mark methods document their boolean return."
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedOptions:
+  Description: "Detects methods with options hash parameters but no @option tags."
+  Enabled: true
+  Severity: error
+
+Documentation/MissingReturn:
+  Description: "Requires @return tags on all methods (opt-in for strict documentation)."
+  Enabled: true # Enabled in strict mode
+  Severity: error
+  ExcludedMethods:
+    - "initialize" # Exclude all initialize methods
+    # - '/^_/'        # Uncomment to exclude private methods (by convention)
+
+Documentation/MarkdownSyntax:
+  Description: "Detects common markdown syntax errors in documentation."
+  Enabled: true
+  Severity: error
+
+Documentation/EmptyCommentLine:
+  Description: "Detects empty comment lines at the start or end of documentation blocks."
+  Enabled: true
+  Severity: error
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: "Detects blank lines between YARD documentation and method definition."
+  Enabled: true
+  Severity: error
+  OrphanedSeverity: error
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
+# Tags validators
+Tags/Order:
+  Description: "Enforces consistent ordering of YARD tags."
+  Enabled: true
+  Severity: error
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+Tags/InvalidTypes:
+  Description: "Validates type definitions in @param, @return, @option tags."
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: "Validates YARD type syntax using YARD parser."
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: "Detects @param/@option tags on classes, modules, or constants."
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: "Validates Hash collection syntax consistency."
+  Enabled: true
+  Severity: error
+  EnforcedStyle: long # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: "Validates type annotation position in tags."
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: "Enforces @api tags on public objects."
+  Enabled: false # Opt-in validator
+  Severity: error
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: "Requires @option tags for methods with options parameters."
+  Enabled: true
+  Severity: error
+
+Tags/ExampleSyntax:
+  Description: "Validates Ruby syntax in @example tags."
+  Enabled: true
+  Severity: error
+
+Tags/ExampleStyle:
+  Description: "Validates code style in @example tags using RuboCop/StandardRB."
+  Enabled: false # Opt-in validator (requires RuboCop or StandardRB)
+  Severity: convention
+  # Linter: auto  # Uncomment to explicitly configure: 'auto', 'rubocop', 'standard', 'none'
+  # SkipPatterns:  # Uncomment to skip examples matching patterns
+  #   - '/skip-lint/i'
+  #   - '/bad code/i'
+
+Tags/RedundantParamDescription:
+  Description: "Detects meaningless parameter descriptions that add no value."
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  Articles:
+    - The
+    - the
+    - A
+    - a
+    - An
+    - an
+  MaxRedundantWords: 6
+  GenericTerms:
+    - object
+    - instance
+    - value
+    - data
+    - item
+    - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
+  Enabled: true
+  Severity: error
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: "@note"
+    Todo: "@todo"
+    TODO: "@todo"
+    FIXME: "@todo"
+    See: "@see"
+    See also: "@see"
+    Warning: "@deprecated"
+    Deprecated: "@deprecated"
+    Author: "@author"
+    Version: "@version"
+    Since: "@since"
+    Returns: "@return"
+    Raises: "@raise"
+    Example: "@example"
+
+Tags/NonAsciiType:
+  Description: "Detects non-ASCII characters in type annotations."
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: "Enforces blank line separators between different YARD tag groups."
+  Enabled: false # Opt-in validator
+  Severity: error
+  TagGroups:
+    param: [param, option]
+    return: [return]
+    error: [raise, throws]
+    example: [example]
+    meta: [see, note, todo, deprecated, since, version, api]
+    yield: [yield, yieldparam, yieldreturn]
+  RequireAfterDescription: false
+
+Tags/ForbiddenTags:
+  Description: "Detects forbidden tag and type combinations."
+  Enabled: false # Opt-in validator
+  Severity: error
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: "Detects unknown YARD tags."
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: "Detects unknown YARD directives."
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: "Detects malformed tag syntax."
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: "Detects malformed directive syntax."
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: "Detects duplicate @param tags."
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: "Detects @param tags for non-existent parameters."
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: "Ensures @abstract methods do not have real implementations."
+  Enabled: true
+  Severity: error

data/AGENTS.md

@@ -0,0 +1,54 @@
+You are working in a Ruby project that uses mutation testing.
+
+## Goal
+
+Achieve 100% mutation coverage. Verify with:
+
+```
+bundle exec mutant run
+```
+
+When iterating, prefer `--fail-fast` so you address one surviving
+mutant at a time:
+
+```
+bundle exec mutant run --fail-fast
+```
+
+## When you find an alive mutation
+
+Decide which bucket it falls into:
+
+- **A) The code does too much** for what the tests ask for. The
+  surviving mutation reveals behavior that no test requires. The
+  fix is to simplify the implementation.
+- **B) A test is missing.** The behavior is intentional but no test
+  observes it. The fix is to add a test.
+
+Decide between A) and B) before changing anything. If unsure, ask
+the user.
+
+## Constraints
+
+- Line coverage must stay at 100%. Verify with:
+
+  ```
+  SIMPLECOV=1 bundle exec rake test
+  ```
+
+- You may not skip mutants by configuring mutant to ignore them.
+  No `expressions:` filters, no `coverage_criteria:` tweaks.
+- You may not use `send` or `__send__` to invoke private methods
+  in tests just to satisfy mutant.
+- You may not stub or mock the system under test.
+
+## Done
+
+You are done when all of these commands are green and don't return any offenses:
+
+```
+SIMPLECOV=1 bundle exec rake test
+bundle exec mutant run
+bundle exec rake markdown:validate_real_world
+yard-lint
+```

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.7.1
+
+### Fixed
+- Preserve fenced code blocks in YARD docstrings so generated Markdown examples render correctly.
+
+## 0.7.0
+## Added
+- Adding yard-lint and all method documentation
+- Generating rbs signature based on yard tags
+- Adding mutant testing into a project
+
+## Changed
+- Refactoring and simplification of teamplate, mostly driven by mutantion testing
+- Improve documentation for entire project

data/README.md

@@ -12,15 +12,6 @@ It's a pitty that rdoc and yard can't output a proper markdown file. I would lik
 - Mimick yard html layout where it makes sense to maintain familiarity
 
 ## Usage
-Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
-
-```yaml
-!!!yaml
-load_plugins: true
-autoload_plugins:
-  - markdown
-```
-
 Install a plugin
 ```
 gem install yard-markdown
@@ -28,20 +19,32 @@ gem install yard-markdown
 
 Run `yardoc --format=markdown` to generate markdown documentation.
 
-## Note on RDoc support
+## FAQ
+
+### Note on RDoc support
 It seems important to note, that yard claims to have support for RDoc. That support is certainly present, but output for rdoc is dramatically different. A lot of useful information seems lost in the process.
 
 If you know how to improve that, please get in touch or submit a patch.
 
 So in meantime, there is work going on a competing gem for RDoc and it's called [rdoc-markdown gem](https://github.com/skatkov/rdoc-markdown/).
 
-## Note on index.csv file
+### Note on index.csv file
 This gem emits index of all markdown files in a index.csv file.
 
 There are decent tools that offer search through structured plain-text files. But my expectation is that nobody will use CSV as an actual search index, but rather import it into something that performs this function better.
 
 In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
+### Yard doesn't load plugin properly? 
+so you need to load plugin through `~/.yard/config`:
+
+```yaml
+!!!yaml
+load_plugins: true
+autoload_plugins:
+  - markdown
+```
+
 ## Testing
 Unit tests verify renderer behavior, index links, and anchor consistency for both YARD-style and RDoc-style sources.
 
@@ -63,6 +66,12 @@ Validate generated markdown in sample docs:
 bundle exec rake markdown:validate_examples
 ```
 
+Regenerate the checked-in RBS types derived from YARD docs:
+
+```bash
+bundle exec rake types:generate
+```
+
 There is also a real-world validation harness for repositories with substantial YARD documentation (`rspec-core`, `sidekiq`):
 
 ```bash
@@ -73,4 +82,6 @@ This task validates generated markdown against CommonMark + GFM rendering, and r
 
 GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
 
+CI also regenerates `sig/yard/markdown.rbs` with `sord` and fails if the checked-in RBS file is out of date.
+
 For reproducible checks, the task clones pinned tags (`rspec-core` `v3.13.2`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` before generating output.

data/Rakefile

@@ -17,6 +17,8 @@ end
 
 task default: %i[test stree:write]
 
+TYPES_OUTPUT_PATH = "sig/yard/markdown.rbs"
+
 def shell_escape(path)
   Shellwords.escape(path)
 end
@@ -62,7 +64,7 @@ def run_command_with_analysis(command, label:)
 
   details = ["#{label} failed output checks (log: #{log_path})"]
   details << "exit status: #{status.exitstatus}" unless status.success?
-  details << "errors: #{combined_analysis[:errors].first(5).join(' | ')}" unless combined_analysis[:errors].empty?
+  details << "errors: #{combined_analysis[:errors].first(5).join(" | ")}" unless combined_analysis[:errors].empty?
   raise details.join("\n")
 end
 
@@ -84,6 +86,32 @@ def checkout_repo(url, destination, ref: nil)
   run_command_with_analysis(command, label: "git_clone_#{destination}")
 end
 
+def generate_types(output_path = TYPES_OUTPUT_PATH)
+  FileUtils.mkdir_p(File.dirname(output_path))
+
+  command = [
+    "sord gen",
+    "--rbs",
+    "--no-sord-comments",
+    "--replace-unresolved-with-untyped",
+    "--replace-errors-with-untyped",
+    shell_escape(output_path)
+  ].join(" ")
+
+  run_command_with_analysis(command, label: "sord_generate")
+end
+
+def ensure_clean_generated_file(path)
+  command = "git status --short -- #{shell_escape(path)}"
+  stdout, stderr, status = Open3.capture3(command)
+  combined_output = [stdout, stderr].reject(&:empty?).join("\n")
+
+  raise "Unable to verify generated types for #{path}" unless status.success?
+  return if combined_output.strip.empty?
+
+  puts combined_output
+  raise "#{path} is out of date. Run `bundle exec rake types:generate` and commit the updated file."
+end
 
 namespace :examples do
   desc "Generate basic example documentation using yard-markdown plugin"
@@ -104,28 +132,28 @@ namespace :examples do
 end
 
 namespace :real_world do
-  REPOS_DIR = "tmp/real-world/repos"
-  RSPEC_REPO = "#{REPOS_DIR}/rspec-core"
-  SIDEKIQ_REPO = "#{REPOS_DIR}/sidekiq"
+  repos_dir = "tmp/real-world/repos"
+  rspec_repo = "#{repos_dir}/rspec-core"
+  sidekiq_repo = "#{repos_dir}/sidekiq"
 
   desc "Checkout rspec-core repository"
   task :checkout_rspec do
-    checkout_repo("https://github.com/rspec/rspec-core.git", RSPEC_REPO, ref: "v3.13.2")
+    checkout_repo("https://github.com/rspec/rspec-core.git", rspec_repo, ref: "v3.13.2")
   end
 
   desc "Checkout sidekiq repository"
   task :checkout_sidekiq do
-    checkout_repo("https://github.com/sidekiq/sidekiq.git", SIDEKIQ_REPO, ref: "v7.3.10")
+    checkout_repo("https://github.com/sidekiq/sidekiq.git", sidekiq_repo, ref: "v7.3.10")
   end
 
   desc "Generate markdown docs for rspec-core"
   task rspec: :checkout_rspec do
-    generate_markdown_docs("#{RSPEC_REPO}/lib", "tmp/real-world/rspec-core")
+    generate_markdown_docs("#{rspec_repo}/lib", "tmp/real-world/rspec-core")
   end
 
   desc "Generate markdown docs for sidekiq"
   task sidekiq: :checkout_sidekiq do
-    generate_markdown_docs("#{SIDEKIQ_REPO}/lib", "tmp/real-world/sidekiq")
+    generate_markdown_docs("#{sidekiq_repo}/lib", "tmp/real-world/sidekiq")
   end
 
   desc "Generate markdown docs for rspec-core and sidekiq"
@@ -153,3 +181,15 @@ namespace :markdown do
     end
   end
 end
+
+namespace :types do
+  desc "Generate checked-in RBS types from YARD documentation"
+  task :generate do
+    generate_types
+  end
+
+  desc "Verify checked-in RBS types are up to date"
+  task check: :generate do
+    ensure_clean_generated_file(TYPES_OUTPUT_PATH)
+  end
+end

data/config/mutant.yml

@@ -0,0 +1,15 @@
+usage: opensource
+
+integration:
+  name: minitest
+
+includes:
+  - lib
+  - test
+
+requires:
+  - ./test/support/mutant_setup.rb
+
+matcher:
+  subjects:
+    - YARD::Markdown*

data/example_rdoc.rb

@@ -133,7 +133,6 @@ end
 DEFAULT_DUCK_VELOCITY = 70
 DEFAULT_SPEED = 10 # Maximum speed for a swimming duck.
 
-
 # Default rubber duck.
 #
 # *Note:*

data/example_yard.rb

@@ -142,4 +142,4 @@ $default_wild_salmon = Salmon.new(false, true)
 # Farmed sustainable salmon.
 #
 # @note This is just a local variable for demonstration purposes.
-farmed_sustainable_salmon = Salmon.new(true, false)
+Salmon.new(true, false)

data/lib/yard/markdown/anchor_component_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Namespace for YARD extensions used by this gem.
+module YARD
+  # Shared helpers for rendering YARD objects as Markdown.
+  module Markdown
+    # Builds anchor-safe identifier fragments from arbitrary values.
+    module AnchorComponentHelper
+      # Encodes a value so it can be embedded safely in an HTML anchor id.
+      #
+      # @param value [Object] Raw anchor fragment to encode.
+      # @return [String] Anchor-safe identifier fragment.
+      def anchor_component(value)
+        value.to_s.each_char.map do |char|
+          char.match?(/[A-Za-z0-9_-]/) ? char : format("-%X", char.ord)
+        end.join
+      end
+    end
+  end
+end

data/lib/yard/markdown/aref_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Computes anchor ids that match the generated Markdown headings.
+    module ArefHelper
+      include AnchorComponentHelper
+
+      # Returns the primary anchor id for a documented object.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [String] Anchor id for the object's heading.
+      def aref(object)
+        type = object.type
+
+        return "class-#{object.path.gsub("::", "-")}" if type == :class
+        return "module-#{object.path.gsub("::", "-")}" if type == :module
+        return "constant-#{object.name}" if type == :constant
+        return "classvariable-#{anchor_component(object.name)}" if type == :classvariable
+
+        scope = (object.scope == :class) ? "c" : "i"
+
+        if !object.attr_info.nil?
+          "attribute-#{scope}-#{object.name}"
+        else
+          "method-#{scope}-#{anchor_component(object.name)}"
+        end
+      end
+    end
+  end
+end