Gitlab RuboCop docs

# bad
Organizations::Organization::DEFAULT_ORGANIZATION_ID
::Organizations::Organization::DEFAULT_ORGANIZATION_ID
DEFAULT_ORGANIZATION_ID = 1

# good
Organizations::Organization.find(id)
project.organization
namespace.organization

# bad
class SomeService
  def execute
    do_something_with(Current.organization)
  end
end

# good
class SomeController < ApplicationController
  def create
    response = SomeService.new(organization: Current.organization).execute
  end
end

class SomeService
  def initialize(organization:)
    @organization = organization
  end

  def execute
    do_something_with(@organization)
  end
end

# bad
Organizations::Organization.default_organization
::Organizations::Organization.default_organization
Organization.default_organization

# good
Organizations::Organization.find(id)
project.organization
namespace.organization

# bad
WorkItems::Type.default_by_type(:issue)
::WorkItems::Type.base_types
WorkItems::TypesFramework::SystemDefined::Type.all

# good
WorkItems::TypesFramework::Provider.new(namespace).find_by_base_type(:issue)
WorkItems::TypesFramework::Provider.unfiltered_base_types
WorkItems::TypesFramework::Provider.new(namespace).all

# bad

Feature.get(:x).enable
Feature.get(:x).enable_percentage_of_time(100)
Feature.get(:x).remove

# good

stub_feature_flags(x: true)
Feature.enable(:x)
Feature.enable_percentage_of_time(:x, 100)
Feature.remove(:x)

# bad
if Gitlab::CurrentSettings.gitlab_dedicated_instance?
  do_dedicated_specific_thing
end

# bad
return unless Gitlab::Dedicated.dedicated_instance?

# good
if Gitlab::Dedicated.feature_available?(:my_dedicated_feature)
  do_dedicated_specific_thing
end

# bad
if Gitlab.com?
  Ci::Runner::FORM_EDITABLE + Ci::Runner::MINUTES_COST_FACTOR_FIELDS
else
  Ci::Runner::FORM_EDITABLE
end

# good
if Gitlab::Saas.feature_available?(:purchases_additional_minutes)
  Ci::Runner::FORM_EDITABLE + Ci::Runner::MINUTES_COST_FACTOR_FIELDS
else
  Ci::Runner::FORM_EDITABLE
end

# bad
organization_root_path(org)
organization_projects_url(namespace, organization_path: org.path)
organization_project_issues_path(project, organization_path: org.path)

# good - standard helpers auto-redirect based on Current.organization
root_path
projects_url(namespace)
project_issues_path(project)

# good - organization resource routes (not org-scoped clones)
organization_path(org)
organizations_path
new_organization_path

# bad
project_issue_url(project, issue)
project_issue_path(project, issue)
project_work_item_url(project, work_item)
project_work_item_path(project, work_item)

# good
Gitlab::UrlBuilder.build(issue)
Gitlab::UrlBuilder.build(issue, only_path: true)

# bad
Rails.cache.delete_matched("users/*/feature_enabled/*")

# bad
Rails.cache.delete_matched(
  "some/key/*"
)

# good - delete specific cache keys
Rails.cache.delete("some/key")

# good - redesign caching strategy to avoid wildcard deletions
# Use a versioned cache key approach:
def cache_key
  "some/key/id/v#{cache_version}"
end

def cache_version
  # Increment version when cache needs invalidation
  user.cache_version
end

# bad
class MyAwfulApi < Grape::API::Instance
  params do
    optional 'file.path', type: String
    optional 'file.name', type: String
    optional 'file.type', type: String
    optional 'file.size', type: Integer
    optional 'file.md5', type: String
    optional 'file.sha1', type: String
    optional 'file.sha256', type: String
  end
  put '/files' do
    uploaded_file = UploadedFile.from_params(params, :file, FileUploader.workhorse_local_upload_path)
  end
end

# good
class MyMuchBetterApi < Grape::API::Instance
  params do
    requires :file, type: ::API::Validations::Types::WorkhorseFile
  end
  put '/files' do
    uploaded_file = declared_params[:file]
  end
end

# bad
class SomeService
  def execute
    do_something_with(user.organization)
  end
end

# bad
class SomeService
  def execute
    do_something_with(current_user.organization)
  end
end

# good
class SomeController < ApplicationController
  def create
    response = SomeService.new(organization: Current.organization).execute
  end
end

class SomeService
  def initialize(organization:)
    @organization = organization
  end

  def execute
    do_something_with(@organization)
  end
end

# good (these are not User objects)
project.organization
group.organization
namespace.organization

# bad
delegate :is_foo?, to: :bar, allow_nil: true

# good
def is_foo?
  return false unless bar
  bar.is_foo?
end

def is_foo?
  !!bar&.is_foo?
end

# bad
AuditEventService.new(...)

# good
Gitlab::Audit::Auditor.audit { ... }

# bad
$stdout.puts("Checking LDAP ...")
$stderr.puts("Error: #{message}")
STDOUT.print("done")
STDERR.print("done")

# good
Gitlab::AppLogger.info("Checking LDAP ...")
say("Checking LDAP ...") # via Gitlab::TaskHelpers or SystemCheck::Helpers

# bad
id = Current.organization&.id
id = ::Current.organization&.id

# good
# If Current.organization is expected to be present (which it is),
# this will raise Current::OrganizationNotAssignedError if it's unexpectedly nil,
# making the underlying issue visible.
id = Current.organization.id

# bad (in lib/gitlab/gon_helper.rb with ee/config/feature_flags/beta/ee_only_flag.yml)
push_frontend_feature_flag(:ee_only_flag, current_user)

# good (in ee/lib/ee/gitlab/gon_helper.rb)
push_frontend_feature_flag(:ee_only_flag, current_user)

# good (in lib/gitlab/gon_helper.rb with config/feature_flags/beta/some_flag.yml)
push_frontend_feature_flag(:some_flag, current_user)

# bad
class MyEvent < Gitlab::EventStore::Event
  def schema
    { 'type' => 'object' }
  end
end

# bad
class MyEvent < ::Gitlab::EventStore::Event
end

# good
class MyEvent < Gitlab::EventStore::CloudEvent
  event_category :my_domain
  event_type :my_event

  def data_schema
    { 'type' => 'object' }
  end
end

# good
class MyEvent < ::Gitlab::EventStore::CloudEvent
end

# bad - data/events/ci/pipeline_created_event.yml is missing
module Ci
  class PipelineCreatedEvent < Gitlab::EventStore::Event; end
end

# good - data/events/ci/pipeline_created_event.yml exists:
# event: Ci::PipelineCreatedEvent
# description: Published when a CI pipeline is created.
# feature_category: continuous_integration

# bad
class MySubscriber
  include Gitlab::EventStore::Subscriber

  def perform(*args)
  end
end

# bad
class MySubscriber
  include Gitlab::EventStore::Subscriber
end

# good
class MySubscriber
  include Gitlab::EventStore::Subscriber

  def handle_event(event)
  end
end

# bad
Feature.enabled?('some_flag')
Feature.enabled?(flag_name)
Feature.disabled?(flag)
Gitlab::AiGateway.push_feature_flag(flag)

# good
Feature.enabled?(:some_flag)
Feature.disabled?(:other_flag)
Gitlab::AiGateway.push_feature_flag(:another_flag)

# bad - no arguments beyond payload -> corrected to SafeParser.parse

Gitlab::Json.parse(user_input)
Gitlab::Json.parse(request.body.read)
::Gitlab::Json.parse(params[:data])

# good (autocorrected)

Gitlab::Json::SafeParser.parse(user_input)
Gitlab::Json::SafeParser.parse(request.body.read)
::Gitlab::Json::SafeParser.parse(params[:data])

# bad - extra arguments present -> corrected to Gitlab::Json.safe_parse
# (SafeParser.parse only accepts parse-limit keys and would raise
# UnknownConfigurationError for JSON options like `symbolize_names:`.)

Gitlab::Json.parse(data, symbolize_names: true)
Gitlab::Json.parse(data, legacy_mode: true)

# good (autocorrected)

Gitlab::Json.safe_parse(data, symbolize_names: true)
Gitlab::Json.safe_parse(data, legacy_mode: true)

# also good - already using `Gitlab::Json.safe_parse`

Gitlab::Json.safe_parse(data)
Gitlab::Json.safe_parse(data, parse_limits: { max_depth: 10 })

# bad

hash.keys.first
hash.values.first

# good

hash.each_key.first
hash.each_value.first

# bad
class MyClass
end

module Gitlab
  class MyClass
  end
end

class Gitlab::MyClass
end

# good
module MyDomain
  class MyClass
  end
end

module Gitlab
  module MyDomain
    class MyClass
    end
  end
end

class Gitlab::MyDomain::MyClass
end

# bad
# :nocov:
def method
end
# :nocov:

# good
def method
end

# bad
class ExampleWorker
  def perform
    record = Klass.find(id)
  end
end

# good
class ExampleWorker
  def perform
    record = Klass.find_by_id(id)
    return unless record
  end
end

# bad
class BasePresenter
  include DiffHelper

  def diffs_slice
    @diffs_slice ||= resource.first_diffs_slice(offset, diff_options)
  end
end

# good
class BasePresenter
  attr_reader :diff_options

  def initialize(diff_options)
    @diff_options = diff_options
  end

  def diffs_slice
    @diffs_slice ||= resource.first_diffs_slice(offset, diff_options)
  end
end

# bad, `conducts_electricity` returns a Rule object, not a boolean!
rule { conducts_electricity && batteries }.enable :light_bulb

# good
rule { conducts_electricity & batteries }.enable :light_bulb

# bad, `conducts_electricity` returns a Rule object, so the ternary is always going to be true
rule { conducts_electricity ? can?(:magnetize) : batteries }.enable :motor

# good
rule { conducts_electricity & can?(:magnetize) }.enable :motor
rule { ~conducts_electricity & batteries }.enable :motor

# bad
Organizations::Organization.first
Organizations::Organization.first!

# good
Organizations::Organization.find(id)
project.organization
namespace.organization

# bad (outside /ee directory)
if Gitlab::Saas.feature_available?(:some_feature)
  # do something
end

# bad (outside /ee directory with safe navigation)
if Gitlab::Saas&.feature_available?(:some_feature)
  # do something
end

# good (inside /ee directory)
if Gitlab::Saas.feature_available?(:some_feature)
  # do something
end

# bad
add_authentication_token_field :foo

# good
add_authentication_token_field :foo, format_with_prefix: method_name_here

# bad
add_authentication_token_field :foo

# good
add_authentication_token_field :foo, routable_token: { payload: { c: ->(record) { record.cell_id } } }

# bad
class Example
  def class_name
    self.name.underscore.tr('/', '_')
  end
end

# good
class Example
  def class_name
    Gitlab::Utils.param_key(self)
  end
end

# bad
Users::Internal.alert_bot
Internal.support_bot

# good
Users::Internal.in_organization(organization).alert_bot
Users::Internal.in_organization(organization).support_bot