yard-markdown 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92bac83ffe7c1f83b26164adef991efe13678b96096ba61af2626f83e9505991
-  data.tar.gz: 7c871bffa551b5acc83e0b954163d933b7289db6542b1485c385ab97fb53e4eb
+  metadata.gz: 41e14595e84affb837da2c36afb9a40f0e7ea866472fa32e5aefabc7c32c2ec8
+  data.tar.gz: 605f1ad9c9496ebaf48afc7245ab25db98b5e22aed88c7c718bb3968f78b3b5e
 SHA512:
-  metadata.gz: 7d7fb3ae97903f7c61aa0a057cdefd878a562264d15d5e7a3da17a5a2bdd5ea35c63cc47244022ab10fe20356c7adf367eee27e1de5b67281376174645c29b54
-  data.tar.gz: 126033d377d8e652a19b33731d57ccfad197731cf819521766dbee5b37d1ee293baf41fc58c7927073ae3cddea9c5a4227b57539023de96ff66740e3d53e88d7
+  metadata.gz: '0887584b2fe63298271fad1483237eb303d215068a6da79aee7cb59c463a6c2838a6a72171676e7876f7a7d8c9003c0e23eb0fcb9dbfd88e329f028c5907bdef'
+  data.tar.gz: 9d50e908447b65b564315c996af01a43e35d360f2bafd600d34197ed20fc0cf8fde1b506850eb2fd476ee65d33c44ff10de8658abcd51037011060d4e69ec59f

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 (`Age`).
+
+## Done
+
+You are done when both of these 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 lib/
+```

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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.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

@@ -63,6 +63,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 +79,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
@@ -84,6 +86,33 @@ 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"
@@ -153,3 +182,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,25 @@
+usage: opensource
+
+integration:
+  name: minitest
+
+includes:
+  - lib
+  - test
+
+requires:
+  - ./test/support/mutant_setup.rb
+
+matcher:
+  subjects:
+    - YARD::Markdown::AnchorComponentHelper#
+    - YARD::Markdown::ArefHelper#
+    - YARD::Markdown::CollectionRenderingHelper#
+    - YARD::Markdown::DocumentationHelper#
+    - YARD::Markdown::HeadingHelper#
+    - YARD::Markdown::LinkNormalizationHelper#
+    - YARD::Markdown::MethodPresentationHelper#
+    - YARD::Markdown::ObjectListingHelper#
+    - YARD::Markdown::RelationshipSectionHelper#
+    - YARD::Markdown::SectionAssemblyHelper#
+    - YARD::Markdown::TagFormattingHelper#

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

data/lib/yard/markdown/collection_rendering_helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Renders grouped Markdown sections for constants, attributes, and methods.
+    module CollectionRenderingHelper
+      # Renders the constants section for an object page.
+      #
+      # @param constants [Array<YARD::CodeObjects::Base>] Constant objects collected for the current page.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the constants section.
+      def render_constants(constants, group_order)
+        lines = ['## Constants']
+        grouped_constants = grouped_items(constants.sort_by { |item| item.name }, group_order)
+        uses_groups = grouped_constants.any? { |name, _items| !name.nil? }
+
+        grouped_constants.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || 'General'}"
+            item_heading = '####'
+          else
+            item_heading = '###'
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}`", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+
+      # Renders the attributes section for an object page.
+      #
+      # @param attrs [Array<YARD::CodeObjects::MethodObject>] Attributes to render.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the attributes section.
+      def render_attributes(attrs, group_order)
+        lines = ['## Attributes']
+        grouped_attrs = grouped_items(attrs, group_order)
+        uses_groups = grouped_attrs.any? { |name, _items| !name.nil? }
+
+        grouped_attrs.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || 'General'}"
+            item_heading = '####'
+          else
+            item_heading = '###'
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}` [#{attribute_access(item)}]", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+
+      # Renders a method section for an object page.
+      #
+      # @param section_title [String] Section title to render.
+      # @param methods [Array<YARD::CodeObjects::MethodObject>] Method objects collected for the current section.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the method section.
+      def render_methods(section_title, methods, group_order)
+        lines = ["## #{section_title}"]
+        grouped_methods = grouped_items(methods, group_order)
+        uses_groups = grouped_methods.any? { |name, _items| !name.nil? }
+
+        grouped_methods.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || 'General'}"
+            item_heading = '####'
+          else
+            item_heading = '###'
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{formatted_method_heading(item)}`", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/yard/markdown/documentation_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rdoc'
+
+module YARD
+  module Markdown
+    # Converts YARD docstrings into Markdown-friendly text.
+    module DocumentationHelper
+      # Returns the rendered documentation text for an object.
+      #
+      # @param object [YARD::CodeObjects::Base] Object whose docstring is being rendered.
+      # @return [String] Converted documentation text or a fallback message.
+      def documented_text(object)
+        text = rdoc_to_md(object.docstring)
+        return text unless text.empty?
+        return '' unless object.tags.empty?
+
+        'Not documented.'
+      end
+
+      # Converts an RDoc-formatted docstring to Markdown.
+      #
+      # @param docstring [Object] Raw docstring content.
+      # @return [String] Markdown-rendered docstring content.
+      def rdoc_to_md(docstring)
+        RDoc::Markup::ToMarkdown.new.convert(docstring).rstrip
+      end
+    end
+  end
+end