yard-lint 0.2.1 → 1.1.0

data/lib/yard/lint/validators/tags/type_syntax.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TypeSyntax validator
+        #
+        # Validates YARD type syntax using YARD's TypesExplainer::Parser. This
+        # validator ensures that type annotations can be properly parsed by YARD
+        # and follow YARD's type specification format. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Invalid type syntax that YARD cannot parse
+        #   # @param data [{String, Integer}] invalid hash syntax
+        #   # @return [String]] extra closing bracket
+        #   def process(data)
+        #   end
+        #
+        # @example Good - Valid parseable YARD type syntax
+        #   # @param data [Hash{String => Integer}] valid hash syntax
+        #   # @return [String] correct bracket usage
+        #   def process(data)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/TypeSyntax:
+        #       Enabled: false
+        #
+        module TypeSyntax
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/duplicated_parameter_name.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # DuplicatedParameterName validator module
+        # DuplicatedParameterName validator
+        #
+        # Detects duplicate `@param` tags for the same parameter name. If a parameter
+        # is documented multiple times, it's unclear which documentation is correct
+        # and can confuse both readers and YARD's parser. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Duplicate @param tags
+        #   # @param name [String] the name
+        #   # @param name [Symbol] oops, documented again
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Each parameter documented once
+        #   # @param name [String] the name
+        #   # @param age [Integer] the age
+        #   def process(name, age)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/DuplicatedParameterName:
+        #       Enabled: false
+        #
         module DuplicatedParameterName
         end
       end

data/lib/yard/lint/validators/warnings/invalid_directive_format/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/invalid_directive_format.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidDirectiveFormat validator module
+        # InvalidDirectiveFormat validator
+        #
+        # Detects malformed YARD directive syntax. Directives have specific format
+        # requirements (like `@!attribute [r] name` for read-only attributes), and
+        # this validator ensures those requirements are met. This validator is
+        # enabled by default.
+        #
+        # @example Bad - Malformed directive syntax
+        #   # @!attribute name missing brackets
+        #   # @!method [r] foo wrong format for method
+        #   class User
+        #   end
+        #
+        # @example Good - Correctly formatted directives
+        #   # @!attribute [r] name
+        #   # @!method foo(bar)
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidDirectiveFormat:
+        #       Enabled: false
+        #
         module InvalidDirectiveFormat
         end
       end

data/lib/yard/lint/validators/warnings/invalid_tag_format/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/invalid_tag_format.rb

@@ -5,7 +5,31 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidTagFormat validator module
+        # InvalidTagFormat validator
+        #
+        # Detects malformed YARD tag syntax. This validator checks that tags follow
+        # the correct format expected by YARD, such as proper spacing, brackets for
+        # types, and required components. This validator is enabled by default.
+        #
+        # @example Bad - Malformed tag syntax
+        #   # @param name[String] missing space before type
+        #   # @return [String the result missing closing bracket
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Correctly formatted tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidTagFormat:
+        #       Enabled: false
+        #
         module InvalidTagFormat
         end
       end

data/lib/yard/lint/validators/warnings/unknown_directive/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/unknown_directive.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownDirective validator module
+        # UnknownDirective validator
+        #
+        # Detects usage of unrecognized YARD directives in documentation. Directives
+        # are special YARD commands (like `@!attribute`, `@!method`) that control
+        # documentation generation. This validator flags unknown directives that
+        # could indicate errors. This validator is enabled by default.
+        #
+        # @example Bad - Unknown or misspelled directive
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # @example Good - Standard YARD directives
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownDirective:
+        #       Enabled: false
+        #
         module UnknownDirective
         end
       end

data/lib/yard/lint/validators/warnings/unknown_parameter_name/parser.rb

@@ -8,10 +8,13 @@ module Yard
           # Parser for UnknownParameterName warnings
           class Parser < ::Yard::Lint::Parsers::TwoLineBase
             # Set of regexps for detecting warnings reported by YARD stats
+            # YARD output format:
+            #   [warn]: @param tag has unknown parameter name: ...
+            #       in file `filename.rb' near line 8
             self.regexps = {
               general: /^\[warn\]: @param tag has unknown parameter name/,
               message: /\[warn\]: (.*)$/,
-              location: /in file `(.*?)'\?\s*near/,
+              location: /in file `(.*?)'\s*near/,
               line: /near line (\d+)/
             }.freeze
           end

data/lib/yard/lint/validators/warnings/unknown_parameter_name/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/unknown_parameter_name.rb

@@ -5,7 +5,29 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownParameterName validator module
+        # UnknownParameterName validator
+        #
+        # Detects `@param` tags that document parameters which don't exist in the
+        # method signature. This often occurs after refactoring when parameter names
+        # change but documentation isn't updated. This validator is enabled by default.
+        #
+        # @example Bad - @param documents non-existent parameter
+        #   # @param old_name [String] this parameter doesn't exist anymore
+        #   def process(new_name)
+        #   end
+        #
+        # @example Good - @param matches actual parameters
+        #   # @param new_name [String] the name to process
+        #   def process(new_name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownParameterName:
+        #       Enabled: false
+        #
         module UnknownParameterName
         end
       end

data/lib/yard/lint/validators/warnings/unknown_tag/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD stats command with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

data/lib/yard/lint/validators/warnings/unknown_tag.rb

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownTag validator module
+        # UnknownTag validator
+        #
+        # Detects usage of unrecognized YARD tags in documentation. This validator
+        # checks against YARD's standard tag set and flags any tags that YARD
+        # doesn't recognize, which could indicate typos or unsupported tags.
+        # This validator is enabled by default.
+        #
+        # @example Bad - Misspelled or non-existent tags
+        #   # @param name [String] typo in param tag
+        #   # @returns [String] should be @return not @returns
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Standard YARD tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownTag:
+        #       Enabled: false
+        #
         module UnknownTag
         end
       end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '0.2.1'
+    VERSION = '1.1.0'
   end
 end

data/lib/yard/lint.rb

@@ -3,6 +3,7 @@
 require 'yaml'
 require 'shellwords'
 require 'open3'
+require 'tempfile'
 require 'tmpdir'
 require 'digest'
 require 'net/http'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +74,7 @@ files:
 - lib/yard/lint.rb
 - lib/yard/lint/command_cache.rb
 - lib/yard/lint/config.rb
+- lib/yard/lint/config_generator.rb
 - lib/yard/lint/config_loader.rb
 - lib/yard/lint/errors.rb
 - lib/yard/lint/formatters/progress.rb
@@ -72,6 +87,12 @@ files:
 - lib/yard/lint/runner.rb
 - lib/yard/lint/validators/base.rb
 - lib/yard/lint/validators/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/parser.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/result.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/validator.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/config.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/parser.rb
@@ -89,6 +110,11 @@ files:
 - lib/yard/lint/validators/documentation/undocumented_objects/parser.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/result.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/validator.rb
+- lib/yard/lint/validators/documentation/undocumented_options.rb
+- lib/yard/lint/validators/documentation/undocumented_options/config.rb
+- lib/yard/lint/validators/documentation/undocumented_options/parser.rb
+- lib/yard/lint/validators/documentation/undocumented_options/result.rb
+- lib/yard/lint/validators/documentation/undocumented_options/validator.rb
 - lib/yard/lint/validators/semantic/abstract_methods.rb
 - lib/yard/lint/validators/semantic/abstract_methods/config.rb
 - lib/yard/lint/validators/semantic/abstract_methods/messages_builder.rb
@@ -101,12 +127,30 @@ files:
 - lib/yard/lint/validators/tags/api_tags/parser.rb
 - lib/yard/lint/validators/tags/api_tags/result.rb
 - lib/yard/lint/validators/tags/api_tags/validator.rb
+- lib/yard/lint/validators/tags/collection_type.rb
+- lib/yard/lint/validators/tags/collection_type/config.rb
+- lib/yard/lint/validators/tags/collection_type/messages_builder.rb
+- lib/yard/lint/validators/tags/collection_type/parser.rb
+- lib/yard/lint/validators/tags/collection_type/result.rb
+- lib/yard/lint/validators/tags/collection_type/validator.rb
+- lib/yard/lint/validators/tags/example_syntax.rb
+- lib/yard/lint/validators/tags/example_syntax/config.rb
+- lib/yard/lint/validators/tags/example_syntax/messages_builder.rb
+- lib/yard/lint/validators/tags/example_syntax/parser.rb
+- lib/yard/lint/validators/tags/example_syntax/result.rb
+- lib/yard/lint/validators/tags/example_syntax/validator.rb
 - lib/yard/lint/validators/tags/invalid_types.rb
 - lib/yard/lint/validators/tags/invalid_types/config.rb
 - lib/yard/lint/validators/tags/invalid_types/messages_builder.rb
 - lib/yard/lint/validators/tags/invalid_types/parser.rb
 - lib/yard/lint/validators/tags/invalid_types/result.rb
 - lib/yard/lint/validators/tags/invalid_types/validator.rb
+- lib/yard/lint/validators/tags/meaningless_tag.rb
+- lib/yard/lint/validators/tags/meaningless_tag/config.rb
+- lib/yard/lint/validators/tags/meaningless_tag/messages_builder.rb
+- lib/yard/lint/validators/tags/meaningless_tag/parser.rb
+- lib/yard/lint/validators/tags/meaningless_tag/result.rb
+- lib/yard/lint/validators/tags/meaningless_tag/validator.rb
 - lib/yard/lint/validators/tags/option_tags.rb
 - lib/yard/lint/validators/tags/option_tags/config.rb
 - lib/yard/lint/validators/tags/option_tags/messages_builder.rb
@@ -119,6 +163,24 @@ files:
 - lib/yard/lint/validators/tags/order/parser.rb
 - lib/yard/lint/validators/tags/order/result.rb
 - lib/yard/lint/validators/tags/order/validator.rb
+- lib/yard/lint/validators/tags/redundant_param_description.rb
+- lib/yard/lint/validators/tags/redundant_param_description/config.rb
+- lib/yard/lint/validators/tags/redundant_param_description/messages_builder.rb
+- lib/yard/lint/validators/tags/redundant_param_description/parser.rb
+- lib/yard/lint/validators/tags/redundant_param_description/result.rb
+- lib/yard/lint/validators/tags/redundant_param_description/validator.rb
+- lib/yard/lint/validators/tags/tag_type_position.rb
+- lib/yard/lint/validators/tags/tag_type_position/config.rb
+- lib/yard/lint/validators/tags/tag_type_position/messages_builder.rb
+- lib/yard/lint/validators/tags/tag_type_position/parser.rb
+- lib/yard/lint/validators/tags/tag_type_position/result.rb
+- lib/yard/lint/validators/tags/tag_type_position/validator.rb
+- lib/yard/lint/validators/tags/type_syntax.rb
+- lib/yard/lint/validators/tags/type_syntax/config.rb
+- lib/yard/lint/validators/tags/type_syntax/messages_builder.rb
+- lib/yard/lint/validators/tags/type_syntax/parser.rb
+- lib/yard/lint/validators/tags/type_syntax/result.rb
+- lib/yard/lint/validators/tags/type_syntax/validator.rb
 - lib/yard/lint/validators/warnings/duplicated_parameter_name.rb
 - lib/yard/lint/validators/warnings/duplicated_parameter_name/config.rb
 - lib/yard/lint/validators/warnings/duplicated_parameter_name/parser.rb
@@ -150,6 +212,7 @@ files:
 - lib/yard/lint/validators/warnings/unknown_tag/result.rb
 - lib/yard/lint/validators/warnings/unknown_tag/validator.rb
 - lib/yard/lint/version.rb
+- misc/logo.png
 - renovate.json
 homepage: https://github.com/mensfeld/yard-lint
 licenses: