Module: RuboCop::Cop::ApiAnnotationHelper Private

Defined in:
rubocops/shared/api_annotation_helper.rb

Overview

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Shared helpers for reading @api public/internal/private annotations from source files at RuboCop runtime. Results are cached at the class level so each file is parsed at most once per RuboCop invocation.

Constant Summary collapse

OFFICIAL_TAPS =

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.

Taps that enforce stricter public API rules.

%w[
  homebrew-core
  homebrew-cask
].freeze
API_SOURCE_FILES =

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.

Source files whose @api annotations define the public API surface.

%w[
  formula.rb
  cask/cask.rb
  cask/dsl.rb
  utils/path.rb
].freeze
FORMULA_COOKBOOK_METHODS =

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.

Methods documented in docs/Formula-Cookbook.md mapped to their defining source files (relative to Library/Homebrew/). Validated by Homebrew/PublicApiCookbook against rubydoc links in docs/Formula-Cookbook.md.

T.let({
  "cd"                    => "extend/pathname.rb",
  "change_make_var!"      => "utils/string_inreplace_extension.rb",
  "compatibility_version" => "formula.rb",
  "conflicts_with"        => "formula.rb",
  "depends_on"            => "formula.rb",
  "deprecated_option"     => "formula.rb",
  "desc"                  => "formula.rb",
  "change_dylib_id"       => "formula.rb",
  "env_script_all_files"  => "extend/pathname.rb",
  "fails_with"            => "formula.rb",
  "post_install_steps"    => "formula.rb",
  "head"                  => "formula.rb",
  "homepage"              => "formula.rb",
  "install_symlink"       => "extend/pathname.rb",
  "keg_only"              => "formula.rb",
  "libexec"               => "formula.rb",
  "license"               => "formula.rb",
  "option"                => "formula.rb",
  "patch"                 => "formula.rb",
  "resource"              => "formula.rb",
  "revision"              => "formula.rb",
  "sha256"                => "formula.rb",
  "stable"                => "formula.rb",
  "test"                  => "formula.rb",
  "testpath"              => "formula.rb",
  "url"                   => "formula.rb",
  "uses_from_macos"       => "formula.rb",
  "version"               => "formula.rb",
  "version_scheme"        => "formula.rb",
  "write_env_script"      => "extend/pathname.rb",
  "write_exec_script"     => "extend/pathname.rb",
  "write_jar_script"      => "extend/pathname.rb",
}.freeze, T::Hash[String, String])
CASK_COOKBOOK_METHODS =

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.

Methods documented in docs/Cask-Cookbook.md mapped to their defining source files (relative to Library/Homebrew/). Validated by Homebrew/PublicApiCookbook against @api public annotations in cask source files.

T.let({
  "after_comma"          => "cask/dsl/version.rb",
  "app"                  => "cask/dsl.rb",
  "appdir"               => "cask/dsl.rb",
  "arch"                 => "cask/dsl.rb",
  "artifact"             => "cask/dsl.rb",
  "auto_updates"         => "cask/dsl.rb",
  "before_comma"         => "cask/dsl/version.rb",
  "binary"               => "cask/dsl.rb",
  "caveats"              => "cask/dsl.rb",
  "chomp"                => "cask/dsl/version.rb",
  "conflicts_with"       => "cask/dsl.rb",
  "container"            => "cask/dsl.rb",
  "csv"                  => "cask/dsl/version.rb",
  "depends_on"           => "cask/dsl.rb",
  "deprecate!"           => "cask/dsl.rb",
  "desc"                 => "cask/dsl.rb",
  "disable!"             => "cask/dsl.rb",
  "dots_to_hyphens"      => "cask/dsl/version.rb",
  "font"                 => "cask/dsl.rb",
  "homepage"             => "cask/dsl.rb",
  "hyphens_to_dots"      => "cask/dsl/version.rb",
  "installer"            => "cask/dsl.rb",
  "language"             => "cask/dsl.rb",
  "livecheck"            => "cask/dsl.rb",
  "major"                => "cask/dsl/version.rb",
  "major_minor"          => "cask/dsl/version.rb",
  "major_minor_patch"    => "cask/dsl/version.rb",
  "manpage"              => "cask/dsl.rb",
  "minor"                => "cask/dsl/version.rb",
  "minor_patch"          => "cask/dsl/version.rb",
  "name"                 => "cask/dsl.rb",
  "no_autobump!"         => "cask/dsl.rb",
  "no_dividers"          => "cask/dsl/version.rb",
  "no_dots"              => "cask/dsl/version.rb",
  "no_hyphens"           => "cask/dsl/version.rb",
  "no_underscores"       => "cask/dsl/version.rb",
  "patch"                => "cask/dsl/version.rb",
  "pkg"                  => "cask/dsl.rb",
  "postflight"           => "cask/dsl.rb",
  "preflight"            => "cask/dsl.rb",
  "rename"               => "cask/dsl.rb",
  "service"              => "cask/dsl.rb",
  "sha256"               => "cask/dsl.rb",
  "stage_only"           => "cask/dsl.rb",
  "staged_path"          => "cask/dsl.rb",
  "suite"                => "cask/dsl.rb",
  "to_s"                 => "cask/cask.rb",
  "token"                => "cask/cask.rb",
  "uninstall"            => "cask/dsl.rb",
  "uninstall_postflight" => "cask/dsl.rb",
  "uninstall_preflight"  => "cask/dsl.rb",
  "url"                  => "cask/dsl.rb",
  "version"              => "cask/dsl.rb",
  "zap"                  => "cask/dsl.rb",
}.freeze, T::Hash[String, String])
SERVICE_COOKBOOK_METHODS =

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.

Methods listed in the "Service block methods" table of docs/Formula-Cookbook.md. All live in service.rb. Validated by Homebrew/PublicApiCookbook against that table and against the @api public annotations in service.rb (a 1:1 correspondence).

T.let(%w[
  cron
  environment_variables
  error_log_path
  input_path
  interval
  keep_alive
  launch_only_once
  log_path
  macos_legacy_timers
  name
  nice
  process_type
  require_root
  restart_delay
  root_dir
  run
  run_at_load
  run_type
  sockets
  stop_timeout
  throttle_interval
  working_dir
].to_set.freeze, T::Set[String])

Class Method Summary collapse

Class Method Details

.homebrew_dir ⇒ String

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.

Returns the Homebrew library root path (parent of rubocops/).

Returns:



189
190
191
 
# File 'rubocops/shared/api_annotation_helper.rb', line 189

def self.homebrew_dir
  File.expand_path("../..", __dir__)
end

.methods_with_api_level(source_path, level) ⇒ Set<String>

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.

Returns the set of method names annotated with a given @api level (e.g. "internal", "private", "public") in the given Ruby source file.

Parameters:

Returns:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'rubocops/shared/api_annotation_helper.rb', line 156

def self.methods_with_api_level(source_path, level)
  @api_method_cache = T.let(@api_method_cache, T.nilable(T::Hash[String, T::Set[String]]))
  @api_method_cache ||= {}
  cache_key = "#{source_path}:#{level}"
  return @api_method_cache.fetch(cache_key) if @api_method_cache.key?(cache_key)

  methods = T.let(Set.new, T::Set[String])
  return methods unless File.exist?(source_path)

  lines = File.readlines(source_path)
  lines.each_with_index do |line, idx|
    next if line.strip != "# @api #{level}"

    # Scan forward up to 5 lines for a def, attr_reader, or delegate
    (1..5).each do |offset|
      target_line = lines[idx + offset]&.strip
      break if target_line.blank?

      m = target_line.match(/\A(?:def\s+(?:self\.)?|attr_reader\s+:|attr_accessor\s+:)(\w+[!?]?)/) ||
          target_line.match(/\Adelegate\s+(\w+[!?]?):/)
      if m
        methods.add(m[1].to_s)
        break
      end
    end
  end

  @api_method_cache[cache_key] = methods.freeze
  methods
end