yard-markdown 0.7.1 → 0.7.2

data/.yard-lint.yml

@@ -1,317 +0,0 @@
-# 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/.yardopts

@@ -1 +0,0 @@
---load ./lib/yard-markdown.rb

data/AGENTS.md

@@ -1,54 +0,0 @@
-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/Rakefile

@@ -1,195 +0,0 @@
-# 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"
-  t.test_files = FileList["test/**/test_*.rb"]
-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"
-  task :generate do
-    Rake::Task["examples:yard"].invoke
-    Rake::Task["examples:rdoc"].invoke
-  end
-
-  desc "Generate example documentation for code annotated with yard"
-  task :yard do
-    generate_markdown_docs("example_yard.rb", "example/yard")
-  end
-
-  desc "Generate example documentation for code annotated with rdoc"
-  task :rdoc do
-    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

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

data/example/rdoc/Bird.md

@@ -1,25 +0,0 @@
-# Class Bird <a id="class-Bird"></a>
-
-**Inherits:** `Object`
-
-The base class for all birds.
-
-## Public Instance Methods
-### `fly(direction, velocity)` <a id="method-i-fly"></a> <a id="fly-instance_method"></a>
-Fly somewhere.
-
-Flying is the most critical feature of birds.
-
-:args: direction, velocity
-
-:call-seq:
-    Bird.fly(symbol, number) -> bool
-    Bird.fly(string, number) -> bool
-
-# Example
-
-    fly(:south, 70)
-
-### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
-Produce some noise. -- FIXME: maybe extract this to a base class `Animal`? ++
-- **@yield** ["tweet"]

data/example/rdoc/Duck.md

@@ -1,59 +0,0 @@
-# Class Duck <a id="class-Duck"></a>
-
-**Inherits:** `Object`
-**Extended by:** `Animal`
-**Includes:** `Waterfowl`
-
-A duck is a Waterfowl Bird.
-
-Features:
-
-    bird::
-
-      * speak
-      * fly
-
-    waterfowl::
-
-      * swim
-
-## Constants
-### `@@rubber_ducks` <a id="classvariable--40-40rubber_ducks"></a> <a id="@@rubber_ducks-classvariable"></a>
-Global list of all rubber ducks.
-
-Use when in trouble.
-
-### `MAX_VELOCITY` <a id="constant-MAX_VELOCITY"></a> <a id="MAX_VELOCITY-constant"></a>
-Maximum velocity for a flying duck.
-
-## Attributes
-### `domestic` [RW] <a id="attribute-i-domestic"></a> <a id="domestic-instance_method"></a>
-True for domestic ducks.
-
-### `rubber` [R] <a id="attribute-i-rubber"></a> <a id="rubber-instance_method"></a>
-True for rubber ducks.
-
-## Public Class Methods
-### `rubber_ducks()` <a id="method-c-rubber_ducks"></a> <a id="rubber_ducks-class_method"></a>
-- **@return** [Array<Duck>] list of all rubber ducks
-
-## Public Instance Methods
-### `initialize(domestic, rubber)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
-Creates a new duck.
-- **@param** `domestic` [Boolean]
-- **@param** `rubber` [Boolean]
-- **@return** [Duck] a new instance of Duck
-
-### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
-Duck overrides generic implementation.
-- **@yield** [speech]
-
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swimming helper.
-
-### `useful?()` <a id="method-i-useful-3F"></a> <a id="useful?-instance_method"></a>
-Checks if this duck is a useful one.
-
-:call-seq:
-    Bird.useful? -> bool
-- **@return** [Boolean]

data/example/rdoc/Waterfowl.md

@@ -1,7 +0,0 @@
-# Module Waterfowl <a id="module-Waterfowl"></a>
-
-A mixin for waterfowl creatures.
-
-## Public Instance Methods
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swimming helper.

data/example/rdoc/index.csv

@@ -1,16 +0,0 @@
-name,type,path
-Waterfowl,Module,Waterfowl.md
-Waterfowl.swim,Method,Waterfowl.md#method-i-swim
-Bird,Class,Bird.md
-Bird.fly,Method,Bird.md#method-i-fly
-Bird.speak,Method,Bird.md#method-i-speak
-Duck,Class,Duck.md
-Duck.MAX_VELOCITY,Constant,Duck.md#constant-MAX_VELOCITY
-Duck.@@rubber_ducks,Constant,Duck.md#classvariable--40-40rubber_ducks
-Duck.initialize,Method,Duck.md#method-i-initialize
-Duck.speak,Method,Duck.md#method-i-speak
-Duck.swim,Method,Duck.md#method-i-swim
-Duck.useful?,Method,Duck.md#method-i-useful-3F
-Duck.rubber_ducks,Method,Duck.md#method-c-rubber_ducks
-Duck.domestic,Attribute,Duck.md#attribute-i-domestic
-Duck.rubber,Attribute,Duck.md#attribute-i-rubber

data/example/yard/Aquatic.md

@@ -1,8 +0,0 @@
-# Module Aquatic <a id="module-Aquatic"></a>
-
-A mixin for aquatic creatures.
-
-## Public Instance Methods
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swim in the water.
-- **@return** [void]