yard-lint 0.2.0

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidTagFormat
+          # Runs YARD stats command to check for invalidtagformat
+          class Validator < Base
+            private
+
+            # 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
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # InvalidTagFormat validator module
+        module InvalidTagFormat
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting unknown directives
+        module UnknownDirective
+          # Configuration for UnknownDirective validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :unknown_directive
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownDirective
+          # Parser for UnknownDirective warnings
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting warnings reported by YARD stats
+            self.regexps = {
+              general: /^\[warn\]: Unknown directive.*@!.*near line/,
+              message: /\[warn\]: (.*) in file/,
+              location: /in file `(.*)`/,
+              line: /line (\d*)/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownDirective
+          # Result object for UnknownDirective validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'UnknownDirective'
+
+            # Build human-readable message for UnknownDirective offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'UnknownDirective detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownDirective
+          # Runs YARD stats command to check for unknowndirective
+          class Validator < Base
+            private
+
+            # 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
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # UnknownDirective validator module
+        module UnknownDirective
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting unknown parameter names in @param tags
+        module UnknownParameterName
+          # Configuration for UnknownParameterName validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :unknown_parameter_name
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownParameterName
+          # Result object for UnknownParameterName validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'UnknownParameterName'
+
+            # Build human-readable message for UnknownParameterName offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'UnknownParameterName detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownParameterName
+          # Runs YARD stats command to check for unknownparametername
+          class Validator < Base
+            private
+
+            # 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
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # UnknownParameterName validator module
+        module UnknownParameterName
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting unknown tags in documentation
+        module UnknownTag
+          # Configuration for UnknownTag validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :unknown_tag
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownTag
+          # Parser used to extract warnings details that are related to yard unknown tags
+          # @example
+          #   [warn]: Unknown tag @example1 in file `/builds/path/engine.rb` near line 32
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting warnings reported by YARD stats
+            self.regexps = {
+              general: /^\[warn\]: Unknown tag.*@.*near line/,
+              message: /\[warn\]: (.*) in file/,
+              location: /in file `(.*)`/,
+              line: /line (\d*)/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownTag
+          # Result object for unknown YARD tags validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'UnknownTag'
+
+            # Build human-readable message for unknown tag offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'Unknown tag detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownTag
+          # Runs YARD stats command to check for unknown YARD tags
+          class Validator < Base
+            private
+
+            # 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
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # UnknownTag validator module
+        module UnknownTag
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # @return [String] version of the YARD Lint gem
+    VERSION = '0.2.0'
+  end
+end

data/lib/yard/lint.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'shellwords'
+require 'open3'
+require 'tmpdir'
+require 'digest'
+require 'net/http'
+require 'uri'
+
+module Yard
+  # YARD Lint module providing linting functionality for YARD documentation
+  module Lint
+    class << self
+      # Main entry point for running YARD lint
+      # @param path [String, Array<String>] file or glob pattern to check
+      # @param config [Yard::Lint::Config, nil] configuration object
+      # @param config_file [String, nil] path to config file
+      #   (auto-loads .yard-lint.yml if not specified)
+      # @param progress [Boolean] show progress indicator (default: true for TTY)
+      # @return [Yard::Lint::Result] result object with offenses
+      def run(path:, config: nil, config_file: nil, progress: nil)
+        config ||= load_config(config_file)
+        files = expand_path(path, config)
+        runner = Runner.new(files, config)
+
+        # Enable progress by default if output is a TTY
+        show_progress = progress.nil? ? $stdout.tty? : progress
+        runner.progress_formatter = Formatters::Progress.new if show_progress
+
+        runner.run
+      end
+
+      private
+
+      # Load configuration from file or auto-detect
+      # @param config_file [String, nil] path to config file
+      # @return [Yard::Lint::Config] configuration object
+      def load_config(config_file)
+        if config_file
+          Config.from_file(config_file)
+        else
+          Config.load || Config.new
+        end
+      end
+
+      # Expand path/glob patterns into an array of files
+      # @param path [String, Array<String>] path or array of paths
+      # @param config [Yard::Lint::Config] configuration object
+      # @return [Array<String>] array of absolute file paths
+      def expand_path(path, config)
+        files = Array(path).flat_map do |p|
+          if p.include?('*')
+            Dir.glob(p)
+          elsif File.directory?(p)
+            Dir.glob(File.join(p, '**/*.rb'))
+          else
+            p
+          end
+        end
+
+        files = files.select { |f| File.file?(f) && f.end_with?('.rb') }
+
+        # Convert to absolute paths for YARD
+        files = files.map { |f| File.expand_path(f) }
+
+        # Filter out excluded files
+        files.reject do |file|
+          config.exclude.any? do |pattern|
+            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard-lint.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+# Setup Zeitwerk loader for gem
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore(__FILE__)
+loader.setup
+
+# Manually load the main module since it contains class-level methods
+require_relative 'yard/lint'

data/renovate.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+  "github-actions": {
+    "enabled": true,
+    "pinDigests": true
+  },
+  "includePaths": [
+    "Gemfile",
+    "yard-lint.gemspec"
+  ],
+  "packageRules": [
+    {
+      "matchManagers": [
+        "github-actions"
+      ],
+      "minimumReleaseAge": "7 days"
+    }
+  ]
+}