solargraph-yard-lint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61f4706a15a10a7daf1a6799bcf2b34a6399d52287055c3764eb6d4d23bbf88d
+  data.tar.gz: 8ab135ecc1779da62b5bb122c300d8e2c01e967483b563da88b280c6be103a62
+SHA512:
+  metadata.gz: 49a4f3cef512e8dbe65691d122154a46ca068b7226a8b0f27ade5e667cbbe9ca9a18d859acc3f01ed94d177950bb4af1eb81094686b1d78ba4539a53c4548970
+  data.tar.gz: 431848919af29a62c0931ba4bba1a3d5ec1672dc3e16107731a9f73e3874a8fa197e6d8ac1528879258ada826e5deb6163d7cb72ce12e70a526190a54d8e6db8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,27 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  Exclude:
+    - 'spec/fixtures/**/*'
+    - 'vendor/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/MethodDefParentheses:
+  EnforcedStyle: require_no_parentheses
+
+Metrics/MethodLength:
+  Max: 20
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 10

data/.solargraph.yml

@@ -0,0 +1,21 @@
+---
+include:
+  - "**/*.rb"
+exclude:
+  - "**/spec/**/*"
+  - test/**/*
+  - vendor/**/*
+  - ".bundle/**/*"
+require: []
+domains: []
+plugins:
+  - solargraph-yard-lint
+reporters:
+  - typecheck:strict
+  - rubocop
+  - require_not_found
+  - yard_lint
+formatter:
+  rubocop:
+    cops: all
+max_files: 20000

data/.yard-lint.yml

@@ -0,0 +1,313 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# 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/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: warning
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  # MinCoverage: 80.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: warning
+  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: warning
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/MissingReturn:
+  Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  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: warning
+
+Documentation/EmptyCommentLine:
+  Description: 'Detects empty comment lines at the start or end of documentation blocks.'
+  Enabled: true
+  Severity: convention
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: 'Detects blank lines between YARD documentation and method definition.'
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
+# Tags validators
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  # Disabled: we use YARD shorthand like `Hash{:a, :b => String; :c => Integer}`
+  # to document fixed-shape hashes; this validator rejects the semicolon form.
+  # See https://github.com/mensfeld/yard-lint/issues/171
+  Enabled: false
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: convention
+  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: convention
+  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: warning
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: warning
+
+Tags/ExampleSyntax:
+  Description: 'Validates Ruby syntax in @example tags.'
+  Enabled: true
+  Severity: warning
+
+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: convention
+  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: warning
+  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: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: 'Enforces blank line separators between different YARD tag groups.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  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: convention
+  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: warning

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- Registers a `yard_lint` diagnostic reporter that surfaces yard-lint
+  offenses as LSP diagnostics.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lekë Mula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,47 @@
+# solargraph-yard-lint
+
+A [Solargraph](https://github.com/castwide/solargraph) plugin that surfaces
+[yard-lint](https://github.com/mensfeld/yard-lint) offenses as LSP diagnostics
+in your editor.
+
+## Installation
+
+Add to your project's `Gemfile`:
+
+```ruby
+group :development do
+  gem 'solargraph'
+  gem 'solargraph-yard-lint'
+end
+```
+
+Then `bundle install`.
+
+## Usage
+
+Add to your project's `.solargraph.yml`:
+
+```yaml
+plugins:
+  - solargraph-yard-lint
+reporters:
+  - rubocop
+  - require_not_found
+  - yard_lint
+```
+
+Restart your Solargraph language server. YARD documentation offenses will
+appear as diagnostics in your editor.
+
+Configure yard-lint itself via `.yard-lint.yml` in your project root — see
+[yard-lint's documentation](https://github.com/mensfeld/yard-lint) for details.
+
+## Notes
+
+yard-lint reads files from disk and does not accept stdin, so this reporter
+only lints sources whose buffer contents match the on-disk file. Unsaved
+edits will not produce yard-lint diagnostics until the file is saved.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/solargraph/yard_lint/diagnostic.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Solargraph language server.
+module Solargraph
+  # yard-lint diagnostics plugin for Solargraph.
+  module YardLint
+    # Solargraph diagnostic reporter backed by yard-lint.
+    class Diagnostic < Solargraph::Diagnostics::Base
+      include Helpers
+
+      # Conversion of yard-lint severity names to LSP constants
+      SEVERITIES = {
+        'convention' => Solargraph::Diagnostics::Severities::INFORMATION,
+        'warning' => Solargraph::Diagnostics::Severities::WARNING,
+        'error' => Solargraph::Diagnostics::Severities::ERROR
+      }.freeze
+
+      # @param source [Solargraph::Source]
+      # @param _api_map [Solargraph::ApiMap]
+      # @return [Array<Hash{:range => Hash; :severity => Integer; :source, :code, :message => String}>]
+      def diagnose source, _api_map
+        @source = source
+        return [] unless lintable?(source)
+
+        require_yard_lint(yard_lint_version)
+        result = Solargraph::CHDIR_MUTEX.synchronize do
+          ::Yard::Lint.run(path: source.filename, progress: false)
+        end
+        return [] if result.clean?
+
+        result.offenses.map { |off| offense_to_diagnostic(off) }
+      rescue InvalidVersionError
+        raise
+      rescue StandardError => e
+        raise Solargraph::DiagnosticsError, "Error running yard-lint: #{e.message}"
+      end
+
+      private
+
+      # yard-lint reads from disk and cannot accept unsaved buffer contents,
+      # so only lint when the source is backed by an on-disk file.
+      #
+      # @param source [Solargraph::Source]
+      # @return [Boolean]
+      def lintable? source
+        filename = source.filename
+        return false if filename.nil? || filename.empty?
+
+        File.file?(filename)
+      end
+
+      # @return [String]
+      def yard_lint_version
+        args.find { |a| a =~ /version=/ }.to_s.split('=').last
+      end
+
+      # Convert a yard-lint offense to an LSP diagnostic
+      #
+      # rubocop:disable Layout/LineLength
+      # @param off [Hash{:name, :message, :location, :severity, :type => String; :line, :location_line => Integer}] Offense received from yard-lint
+      # @return [Hash{:range => Hash; :severity => Integer; :source, :code, :message => String}] LSP diagnostic
+      # rubocop:enable Layout/LineLength
+      def offense_to_diagnostic off
+        {
+          range: offense_range(off).to_hash,
+          severity: SEVERITIES[off[:severity]] || Solargraph::Diagnostics::Severities::WARNING,
+          source: 'yard-lint',
+          code: off[:name],
+          message: off[:message]
+        }
+      end
+
+      # yard-lint reports offenses at line granularity only (no column),
+      # so the range spans the entire reported line.
+      #
+      # @param off [Hash{:line, :location_line => Integer}]
+      # @return [Solargraph::Range]
+      def offense_range off
+        line = (off[:location_line] || off[:line] || 1).to_i - 1
+        line = 0 if line.negative?
+        line_text = @source.code.lines[line] || ''
+        end_col = line_text.chomp.length
+        Solargraph::Range.new(
+          Solargraph::Position.new(line, 0),
+          Solargraph::Position.new(line, end_col)
+        )
+      end
+    end
+  end
+end

data/lib/solargraph/yard_lint/helpers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Solargraph language server.
+module Solargraph
+  # yard-lint diagnostics plugin for Solargraph.
+  module YardLint
+    # Raised when a requested yard-lint version is not installed.
+    class InvalidVersionError < RuntimeError; end
+
+    # Utility methods for the yard-lint diagnostics reporter.
+    module Helpers
+      module_function
+
+      # Requires a specific version of yard-lint, or the latest installed
+      # version if _version_ is `nil`.
+      #
+      # @param version [String, nil]
+      # @return [void]
+      # @raise [InvalidVersionError] if _version_ is not installed
+      def require_yard_lint version = nil
+        begin
+          gem_path = Gem::Specification.find_by_name('yard-lint', version).full_gem_path
+          gem_lib_path = File.join(gem_path, 'lib')
+          $LOAD_PATH.unshift(gem_lib_path) unless $LOAD_PATH.include?(gem_lib_path)
+        rescue Gem::MissingSpecVersionError => e
+          specs = e.specs
+          raise InvalidVersionError,
+                "could not find '#{e.name}' (#{e.requirement}) - " \
+                "did find: [#{specs.map { |s| s.version.version }.join(', ')}]"
+        end
+        require 'yard-lint'
+      end
+    end
+  end
+end

data/lib/solargraph/yard_lint/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Solargraph language server.
+module Solargraph
+  # yard-lint diagnostics plugin for Solargraph.
+  module YardLint
+    # Gem version.
+    VERSION = '0.1.0'
+  end
+end

data/lib/solargraph-yard-lint.rb

@@ -0,0 +1,11 @@
+# rubocop:disable Naming/FileName
+# frozen_string_literal: true
+
+require 'solargraph'
+
+require_relative 'solargraph/yard_lint/version'
+require_relative 'solargraph/yard_lint/helpers'
+require_relative 'solargraph/yard_lint/diagnostic'
+
+Solargraph::Diagnostics.register('yard_lint', Solargraph::YardLint::Diagnostic)
+# rubocop:enable Naming/FileName

data/solargraph-yard-lint.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/solargraph/yard_lint/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'solargraph-yard-lint'
+  spec.version = Solargraph::YardLint::VERSION
+  spec.authors = ['Lekë Mula']
+  spec.email = ['leke.mula@gmail.com']
+
+  spec.summary = 'Solargraph plugin that surfaces yard-lint offenses as LSP diagnostics'
+  spec.description = 'Adds a yard_lint diagnostic reporter to Solargraph, powered by the ' \
+                     'yard-lint gem. Surfaces YARD documentation issues in your editor.'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['source_code_uri'] = 'https://github.com/lekemula/solargraph-yard-lint'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ doc/ .git .github Gemfile])
+    end
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'solargraph', '>= 0.52.0'
+  spec.add_dependency 'yard-lint', '~> 1.5'
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: solargraph-yard-lint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lekë Mula
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: solargraph
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.52.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.52.0
+- !ruby/object:Gem::Dependency
+  name: yard-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: Adds a yard_lint diagnostic reporter to Solargraph, powered by the yard-lint
+  gem. Surfaces YARD documentation issues in your editor.
+email:
+- leke.mula@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".solargraph.yml"
+- ".yard-lint.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/solargraph-yard-lint.rb
+- lib/solargraph/yard_lint/diagnostic.rb
+- lib/solargraph/yard_lint/helpers.rb
+- lib/solargraph/yard_lint/version.rb
+- solargraph-yard-lint.gemspec
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/lekemula/solargraph-yard-lint
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: Solargraph plugin that surfaces yard-lint offenses as LSP diagnostics
+test_files: []