yard-markdown 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3bf19f52aa053b77b3bdfa88b447e7db00c746135a47b77e81e2a08ceb4367a
-  data.tar.gz: 8a141a935807d808abec2fa5f2e6d690cfb0c9ec70e89fc0709e7a39f60fb697
+  metadata.gz: 41e14595e84affb837da2c36afb9a40f0e7ea866472fa32e5aefabc7c32c2ec8
+  data.tar.gz: 605f1ad9c9496ebaf48afc7245ab25db98b5e22aed88c7c718bb3968f78b3b5e
 SHA512:
-  metadata.gz: d53e7cd3f76693122642ec6196bf8e49f11b2b5457ebb0942be702e33efe25348141580188bb00dfc9846b5766ee412e14c9c059e119358ab79c1a0f828e30c1
-  data.tar.gz: 02d47f00d6408f1d645ac0d46936e2734c89f1c853632d88b4217d0bb2985993ddcd6d99dbe38de18ee40a858b1441a35b44c3ce7e6ea2161b4a6705e2dcb540
+  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

@@ -33,7 +33,7 @@ It seems important to note, that yard claims to have support for RDoc. That supp
 
 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-mardown gem](https://github.com/skatkov/rdoc-markdown/).
+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
 This gem emits index of all markdown files in a index.csv file.
@@ -43,6 +43,42 @@ There are decent tools that offer search through structured plain-text files. Bu
 In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
 ## Testing
-Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
+Unit tests verify renderer behavior, index links, and anchor consistency for both YARD-style and RDoc-style sources.
 
-Easiest way to test is to run `rake generate_example` and check output in `example` directory.
+Run:
+
+```bash
+bundle exec rake test
+```
+
+Regenerate local sample docs:
+
+```bash
+bundle exec rake examples:generate
+```
+
+Validate generated markdown in sample docs:
+
+```bash
+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
+bundle exec rake markdown:validate_real_world
+```
+
+This task validates generated markdown against CommonMark + GFM rendering, and reports unresolved local links found in upstream source comments while still validating local anchor/link structure.
+
+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

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "open3"
+require "shellwords"
+
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+require_relative "test/support/markdown_validator"
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
@@ -11,6 +17,102 @@ end
 
 task default: %i[test stree:write]
 
+TYPES_OUTPUT_PATH = "sig/yard/markdown.rbs"
+
+def shell_escape(path)
+  Shellwords.escape(path)
+end
+
+COMMAND_WARNING_REGEX = /\bwarning:/i
+COMMAND_ERROR_REGEX = /\b(?:error|exception|fatal|loaderror)\b/i
+
+def analyze_command_output(text)
+  lines = text.each_line.map(&:strip).reject(&:empty?)
+  {
+    warnings: lines.grep(COMMAND_WARNING_REGEX),
+    errors: lines.grep(COMMAND_ERROR_REGEX)
+  }
+end
+
+def command_log_path(label)
+  safe_label = label.gsub(%r{[^a-zA-Z0-9_-]+}, "_")
+  File.join("tmp", "command-logs", "#{safe_label}.log")
+end
+
+def run_command_with_analysis(command, label:)
+  puts command
+
+  stdout, stderr, status = Open3.capture3(command)
+  combined_output = [stdout, stderr].reject(&:empty?).join("\n")
+  log_path = command_log_path(label)
+
+  FileUtils.mkdir_p(File.dirname(log_path))
+  File.write(log_path, combined_output)
+
+  puts combined_output unless combined_output.empty?
+
+  stdout_analysis = analyze_command_output(stdout)
+  stderr_analysis = analyze_command_output(stderr)
+  combined_analysis = {
+    warnings: stdout_analysis[:warnings] + stderr_analysis[:warnings],
+    errors: stdout_analysis[:errors] + stderr_analysis[:errors]
+  }
+
+  puts "Output analysis for #{label}: warnings=#{combined_analysis[:warnings].size}, errors=#{combined_analysis[:errors].size}"
+
+  return if status.success? && combined_analysis[:errors].empty?
+
+  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?
+  raise details.join("\n")
+end
+
+def generate_markdown_docs(source, output_dir)
+  FileUtils.rm_rf(output_dir)
+  FileUtils.mkdir_p(output_dir)
+
+  command = "yardoc --no-stats --quiet --format markdown --load ./lib/yard-markdown.rb --output-dir #{shell_escape(output_dir)} #{shell_escape(source)}"
+  run_command_with_analysis(command, label: "yardoc_#{output_dir}")
+end
+
+def checkout_repo(url, destination, ref: nil)
+  FileUtils.rm_rf(destination)
+  FileUtils.mkdir_p(File.dirname(destination))
+
+  command = "git clone --depth 1"
+  command += " --branch #{shell_escape(ref)}" if ref
+  command += " #{shell_escape(url)} #{shell_escape(destination)}"
+  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"
@@ -21,11 +123,74 @@ namespace :examples do
 
   desc "Generate example documentation for code annotated with yard"
   task :yard do
-    sh "yardoc --output-dir example/yard example_yard.rb"
+    generate_markdown_docs("example_yard.rb", "example/yard")
   end
 
   desc "Generate example documentation for code annotated with rdoc"
   task :rdoc do
-    sh "yardoc --output-dir example/rdoc example_rdoc.rb"
+    generate_markdown_docs("example_rdoc.rb", "example/rdoc")
+  end
+end
+
+namespace :real_world do
+  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")
+  end
+
+  desc "Checkout sidekiq repository"
+  task :checkout_sidekiq do
+    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")
+  end
+
+  desc "Generate markdown docs for sidekiq"
+  task sidekiq: :checkout_sidekiq do
+    generate_markdown_docs("#{SIDEKIQ_REPO}/lib", "tmp/real-world/sidekiq")
+  end
+
+  desc "Generate markdown docs for rspec-core and sidekiq"
+  task :generate do
+    Rake::Task["real_world:rspec"].invoke
+    Rake::Task["real_world:sidekiq"].invoke
+  end
+end
+
+namespace :markdown do
+  desc "Validate checked-in example markdown output"
+  task validate_examples: "examples:generate" do
+    ["example/yard", "example/rdoc"].each do |dir|
+      file_count = MarkdownValidator.new(dir).validate!
+      puts "Validated #{file_count} markdown files in #{dir}"
+    end
+  end
+
+  desc "Generate and validate markdown output for rspec-core and sidekiq"
+  task validate_real_world: "real_world:generate" do
+    ["tmp/real-world/rspec-core", "tmp/real-world/sidekiq"].each do |dir|
+      validator = MarkdownValidator.new(dir, strict_links: false)
+      file_count = validator.validate!
+      puts "Validated #{file_count} markdown files in #{dir} (unresolved local links: #{validator.unresolved_links})"
+    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#