Class: RuboCop::Cop::Homebrew::PublicApiCookbook Private
- Defined in:
- rubocops/public_api_cookbook.rb
Overview
This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.
Ensures that methods and DSL calls documented in the Formula Cookbook
or Cask Cookbook are annotated with @api public in their source
definitions.
Both cookbook method lists live in ApiAnnotationHelper and are validated by this cop.
Constant Summary collapse
- MSG =
This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
"Method `%<method>s` is referenced in the %<cookbook>s but is not annotated with `@api public`."- MISSING_FORMULA_LIST_MSG =
This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
"Formula Cookbook references methods missing from " \ "`FORMULA_COOKBOOK_METHODS`: %<methods>s."
- MISSING_CASK_LIST_MSG =
This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
"Method `%<method>s` is annotated with `@api public` in `%<file>s` but is " \ "missing from `CASK_COOKBOOK_METHODS`."
- MISSING_SERVICE_LIST_MSG =
This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
"Method `%<method>s` is annotated with `@api public` in `service.rb` but is " \ "missing from the Formula Cookbook's \"Service block methods\" table."
- MISMATCHED_SERVICE_LIST_MSG =
This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
"`SERVICE_COOKBOOK_METHODS` is out of sync with the Formula Cookbook's " \ "\"Service block methods\" table: %<diff>s."
Instance Method Summary collapse
- #on_new_investigation ⇒ void private
Instance Method Details
#on_new_investigation ⇒ void
This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
This method returns an undefined value.
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 |
# File 'rubocops/public_api_cookbook.rb', line 27 def on_new_investigation super file_path = processed_source.file_path return if file_path.nil? relative_path = file_path.sub(%r{.*/Library/Homebrew/}, "") if relative_path == "rubocops/shared/api_annotation_helper.rb" missing_formula = (HOMEBREW_LIBRARY_PATH.parent.parent/"docs/Formula-Cookbook.md").read .scan( %r{/rubydoc/\w+(?:/\w+)*\.html#(\w+[!?]?)-(?:class|instance)_method}, ) .flatten - ApiAnnotationHelper::FORMULA_COOKBOOK_METHODS.keys missing_formula.sort! if missing_formula.any? add_offense( processed_source.ast&.each_descendant(:casgn)&.find do |node| node.const_name == "FORMULA_COOKBOOK_METHODS" end || processed_source.ast || processed_source.buffer.source_range, message: format( MISSING_FORMULA_LIST_MSG, methods: missing_formula.map { |method| "`#{method}`" }.join(", "), ), ) end check_service_cookbook_list return end # Line numbers of definitions directly preceded by an `@api public` annotation, # matching only the immediately following definition; not one 20 lines away. api_public_targets = T.let(Set.new, T::Set[Integer]) lines = processed_source.lines processed_source.comments.each do |comment| text = comment.text.strip next if text != "# @api public" && text != "@api public" # Scan forward from the annotation to find the definition it applies to. # Skip blank lines, comments, and sig blocks (including multi-line). line_idx = comment.loc.line # 1-based; lines array is 0-based in_sig = T.let(false, T::Boolean) (1..lines.length).each do |offset| target_line = lines[line_idx - 1 + offset]&.strip break if target_line.nil? next if target_line.empty? || target_line.start_with?("#") if target_line.match?(/(?:\A|\.|\})sig[\s({]/) in_sig = !target_line.include?("}") next end if in_sig in_sig = !target_line.include?("}") next end api_public_targets.add(line_idx + offset) break end end check_cookbook_methods(ApiAnnotationHelper::FORMULA_COOKBOOK_METHODS, "Formula Cookbook", relative_path, api_public_targets) check_cookbook_methods(ApiAnnotationHelper::CASK_COOKBOOK_METHODS, "Cask Cookbook", relative_path, api_public_targets) check_service_methods(relative_path, api_public_targets) return unless %w[cask/dsl.rb cask/cask.rb cask/dsl/version.rb].include?(relative_path) cookbook_methods = ApiAnnotationHelper::CASK_COOKBOOK_METHODS.keys.to_set processed_source.comments.each do |comment| next unless ["# @api public", "@api public"].include?(comment.text.strip) (1..5).each do |offset| target_line = lines[comment.loc.line - 1 + offset]&.strip break if target_line.blank? match = target_line.match(/\A(?:def\s+(?:self\.)?|attr_reader\s+:|attr_accessor\s+:)(\w+[!?]?)/) || target_line.match(/\Adelegate\s+(\w+[!?]?):/) next if match.nil? method_name = match[1].to_s break if cookbook_methods.include?(method_name) add_offense(comment, message: format(MISSING_CASK_LIST_MSG, method: method_name, file: relative_path)) break end end end |