Class: MilkTea::Linter

Inherits:
Object
  • Object
show all
Includes:
LinterDocTags, LinterFlowRules, LinterImportsPlatform, LinterReleaseRules, LinterReservedNames, LinterRules, LinterSourceHelpers, LinterTrailingComma, LinterVisitors
Defined in:
lib/milk_tea/tooling/linter.rb,
lib/milk_tea/tooling/linter/rules.rb,
lib/milk_tea/tooling/linter/doc_tags.rb,
lib/milk_tea/tooling/linter/visitors.rb,
lib/milk_tea/tooling/linter/fix_engine.rb,
lib/milk_tea/tooling/linter/flow_rules.rb,
lib/milk_tea/tooling/linter/release_rules.rb,
lib/milk_tea/tooling/linter/reserved_names.rb,
lib/milk_tea/tooling/linter/source_helpers.rb,
lib/milk_tea/tooling/linter/trailing_comma.rb,
lib/milk_tea/tooling/linter/imports_platform.rb

Defined Under Namespace

Modules: FixEngine, LinterDocTags, LinterFlowRules, LinterImportsPlatform, LinterReleaseRules, LinterReservedNames, LinterRules, LinterSourceHelpers, LinterTrailingComma, LinterVisitors Classes: Binding, DeadAssignmentAnalysis, FixEdit, Profile, ReservedPrimitiveNameFix, ReservedPrimitiveNameSite, StatementFlowAnalysis, Warning

Constant Summary collapse

UNSET = 
Object.new.freeze
DEFAULT_CONFIG_FILE_NAME = 
".mt-lint.yml".freeze
KNOWN_RULE_CODES = 
%w[
  borrow-and-mutate
  constant-condition
  dead-assignment
  directional-ffi-arg
  doc-tag
  duplicate-if-condition
  event-capacity
  line-too-long
  loop-single-iteration
  missing-return
  noop-compound-assignment
  owning-release-double
  owning-release-leak
  platform-api-drift
  prefer-conditional-expression
  prefer-inline-if
  prefer-inline-methods
  prefer-is-variant
  prefer-let
  prefer-let-else
  prefer-or-pattern
  prefer-own-ptr
  prefer-struct-with
  prefer-try
  prefer-var-else
  redundant-bool-compare
  redundant-cast
  redundant-else
  redundant-ignored-match-binding
  redundant-null-check
  redundant-return
  redundant-type-annotation
  redundant-unsafe
  reserved-primitive-name
  self-assignment
  self-comparison
  shadow
  trailing-list-comma
  unreachable-code
  unused-import
  unused-local
  unused-param
  useless-expression
].freeze
RESERVED_VALUE_TYPE_NAMES = 
Types::RESERVED_VALUE_TYPE_NAMES.to_set.freeze
RESERVED_IMPORT_ALIAS_NAMES = 
Types::RESERVED_IMPORT_ALIAS_NAMES.to_set.freeze
RESERVED_TYPE_BINDING_NAMES = 
Types::RESERVED_TYPE_BINDING_NAMES.to_set.freeze
AUTO_FIXABLE_RULE_CODES = 
%w[
  prefer-let
  redundant-ignored-match-binding
  prefer-let-else
  prefer-var-else
  prefer-inline-methods
  redundant-bool-compare
  redundant-cast
  redundant-else
  redundant-return
  redundant-type-annotation
  redundant-unsafe
  reserved-primitive-name
  trailing-list-comma
].freeze
LINT_TIERS =

NOTE: unused-import is intentionally NOT auto-fixable. Removing an import has non-local effects the linter cannot see under per-file validation: it may drop extension methods / canonical hooks (hash[T], equal[T]), a bare-name type provided via the prelude bootstrap (e.g. std.option), or break downstream consumers of a library module. It remains a reported hint so authors can remove genuinely-unused imports deliberately.

%i[fast full].freeze
STATIC_QUICK_FIX_TITLES = 
{
  "line-too-long" => "Wrap long line",
  "prefer-let" => "Replace 'var' with 'let'",
  "redundant-ignored-match-binding" => "Remove redundant as _",
  "redundant-bool-compare" => "Simplify boolean comparison",
  "redundant-cast" => "Remove redundant cast",
  "redundant-else" => "Remove redundant else",
  "redundant-return" => "Remove redundant return",
  "redundant-type-annotation" => "Remove redundant type annotation",
  "redundant-unsafe" => "Remove redundant unsafe",
  "prefer-let-else" => "Rewrite as let-else",
  "prefer-var-else" => "Rewrite as var-else",
  "prefer-inline-methods" => "Inline methods into struct",
  "trailing-list-comma" => "Remove trailing list comma",
}.freeze
EVENT_STACK_SNAPSHOT_WARNING_THRESHOLD = 
128
FIX_ALL_TITLE = 
"Apply all auto-fixes".freeze

Constants included from LinterVisitors

LinterVisitors::BINARY_CAST_SAFE_OPS, LinterVisitors::BINARY_OP_CHARS, LinterVisitors::BORROW_CALL_NAMES, LinterVisitors::COMPARISON_CAST_OPS, LinterVisitors::INTEGER_TYPE_RANGES

Constants included from LinterRules

LinterRules::PURE_EXPRESSION_TYPES, LinterRules::SIDE_EFFECTING_EXPRESSION_TYPES

Constants included from LinterImportsPlatform

LinterImportsPlatform::HOOK_BUILTIN_NAMES

Class Method Summary collapse

Instance Method Summary collapse

Methods included from LinterVisitors

#alloc_wrapper_name, #balanced_inline_line?, #boolean_literal_value, #check_binary_operand_cast, #check_comparison_literal_operand, #check_prefer_conditional_expression_if, #check_prefer_conditional_expression_match, #check_prefer_inline_if, #check_prefer_is_variant, #check_prefer_or_pattern, #check_prefer_struct_with, #check_prefer_try, #check_redundant_binary_operand_cast, #check_redundant_cast, #check_redundant_cast_parens, #check_redundant_literal_operand_cast, #check_redundant_type_annotation, #check_redundant_unsafe, #classify_is_variant_arms, #collect_borrowed_names, #collect_borrows_from_expr, #collect_borrows_from_stmt, #collect_writes_from_stmt, #collect_writes_from_stmt_list, #collect_written_names, #copy_field_argument?, #declare_local, #declare_param, #declared_callable_names, #declared_directional_functions, #editable_receiver_expression?, #emit_conciseness_hint, #emit_redundant_cast, #emit_scope_warnings, #expr_source_name, #expression_literal_type_name, #extending_block_generic?, #find_borrow_location, #find_borrow_location_in_expr, #find_borrow_location_in_stmt, #find_primitive_type, #flag_redundant_literal_cast, #flag_redundant_widening_cast, #generic_function_context?, #heap_alloc_call?, #implicit_cast_allowed?, #inline_if_too_wide?, #inline_simple_statement?, #inner_has_top_level_operators?, #mark_alias_source_mutated, #mark_assignment_target_reads, #mark_call_argument_mutated, #mark_call_receiver_mutated, #mark_mutated, #mark_used, #match_paren, #member_named?, #mutating_argument_identifier?, #node_fingerprint, #own_to_pointer_cast_redundant?, #propagation_return?, #record_ptr_candidate, #report_conditional_expression, #resolve_expr_type, #same_resolved_type?, #seed_module_bindings, #short_circuit_arm_pattern?, #single_statement_body, #source_line_from, #stmt_sub_stmts, #terminator?, #track_binding_unsafe_use, #type_ref_name, #type_ref_source, #visit_assignment_target, #visit_expression, #visit_function, #visit_source_file, #visit_statement, #visit_statement_list, #visit_type_argument, #visit_type_ref, #visually_inline_if?, #wildcard_pattern?, #with_scope

Methods included from LinterTrailingComma

#call_symbol_name, #each_call_argument_list_candidate, #each_call_in_expression, #each_call_in_statement_list, #emit_trailing_list_comma_warnings, #trailing_call_argument_comma_site

Methods included from LinterSourceHelpers

#condition_span, #condition_symbol_name, #declaration_column, #each_event_declaration, #each_nested_struct_event_declaration, #each_statement_expression, #emit_event_capacity_warnings, #emit_line_too_long_warnings, #expression_column, #expression_length, #expression_line, #external_or_foreign_function_header_line?, #param_column, #param_line, #profile_phase, #source_code_line, #source_condition_span, #source_line_text, #source_statement_span, #statement_column, #statement_length, #walk_expression_tree, #walk_statement_lists

Methods included from LinterRules

#always_returns?, #assertion_false?, #binding_type_for_declaration, #check_directional_ffi_call, #check_duplicate_if_conditions, #check_missing_return, #check_noop_compound_assignment, #check_redundant_bool_compare, #check_redundant_else, #check_self_assignment, #check_self_comparison, #check_useless_expression, #contains_side_effecting_expression?, #directional_ffi_binding?, #emit_prefer_else_warnings, #emit_prefer_inline_methods_warnings, #emit_prefer_let_else_warnings, #emit_prefer_var_else_warnings, #emit_redundant_return_warnings, #expression_signature, #infinite_while_without_break?, #integer_literal_zero?, #legacy_directional_argument_expression?, #loop_body_can_break?, #lvalue_expression?, #noop_compound_identity_value, #null_equality_identifier, #nullable_binding_declaration?, #nullable_initializer_without_binding_type?, #numeric_literal_one?, #parameter_name, #parameter_passing_mode, #pointer_like_cast_expression, #pointer_like_type_ref?, #prefer_else_candidate, #prefer_var_else_binding_mutated?, #redundant_bool_compare_length, #resolve_directional_ffi_call, #static_assert_false?, #terminating_callee?, #terminating_expression?, #void_return_type?

Methods included from LinterReservedNames

#declare_reserved_import_alias_module_binding, #declare_reserved_module_binding, #declare_reserved_primitive_module_binding, #declare_reserved_value_type_module_binding, #next_available_reserved_primitive_name, #record_reserved_primitive_identifier_use, #register_reserved_primitive_name_fix, #resolve_reserved_primitive_name_conflicts!, #suggested_reserved_primitive_name, #visible_binding_names, #visible_bindings, #warn_large_event_capacity, #warn_redundant_ignored_match_binding, #warn_reserved_primitive_name, #warn_reserved_primitive_type_params

Methods included from LinterReleaseRules

#_any_stmt?, #_any_stmt_or_expr?, #_check_double_release_in_seq, #_collect_heap_release_names, #_collect_own_released_names, #_collect_own_released_names_in_stmt, #_collect_own_typed_locals, #_collect_owning_locals, #_collect_released_names, #_collect_released_names_in_expr, #_collect_released_names_in_stmt, #_expr_contains_transfer?, #_expr_has_release?, #all_own_released_names, #all_released_names, #argument_transfers?, #build_owning_type_set, #check_own_release_leaks, #check_owning_release_double, #check_owning_release_leaks, #classify_cfg_nodes, #emit_owning_release_cfg_warnings, #emit_owning_release_double_warnings, #emit_owning_release_leak_warnings, #emit_owning_release_warnings, #every_path_to_exit_has_consumer?, #extract_expr, #extract_initializer_type, #extract_line, #find_decl_node_id, #find_reachable_release, #heap_release_call_on_name?, #heap_release_target_name, #is_heap_alloc_call?, #own_cast_in_unsafe?, #own_struct_field_transfer?, #own_transfer_identifier?, #own_transferred?, #own_typed_local_bindings, #ownership_transferred?, #owning_base_name, #owning_local_bindings, #owning_type_by_name?, #owning_type_from_receiver, #reassigns_owning_binding?, #release_call_in_stmt?, #release_call_on_binding?, #release_helper_binding_names, #resolve_local_own_pointer_type, #resolve_local_owning_type, #return_for_name?, #returned_name?, #struct_field_transfer?, #struct_transfer_in_stmt?, #type_base_name

Methods included from LinterImportsPlatform

#check_platform_api_drift, #check_unused_imports, #collect_hook_provider_import_uses, #collect_indirect_import_uses_from_declaration, #collect_indirect_import_uses_from_expr, #collect_indirect_import_uses_from_stmt, #collect_method_only_import_uses, #collect_method_provider_import_uses, #collect_names_from_declaration, #collect_names_from_expr, #collect_names_from_statement, #collect_names_from_type, #collect_qualified_name_root, #collect_used_names, #declaration_anchor, #exported_api_surface, #exported_api_surface_sites, #exported_declaration?, #exported_type_names, #identifier_binding_type, #import_module_defines_method?, #import_module_provides_hook_method?, #lint_method_dispatch_receiver_type, #load_sibling_source_file, #method_map_defines_method?, #platform_api_drift_anchor, #platform_api_drift_message, #platform_variant_sibling_paths, #receiver_import_alias, #render_attribute_application_surface, #render_attribute_applications_surface, #render_callable_surface, #render_enum_surface, #render_event_surface, #render_fields_surface, #render_implements_surface, #render_interface_method_surface, #render_interface_surface, #render_method_surface, #render_opaque_surface, #render_param_surface, #render_struct_surface, #render_type_argument_surface, #render_type_param_constraints_surface, #render_type_params_surface, #render_type_surface, #render_union_surface, #render_value_surface, #render_variant_arm_surface, #render_variant_surface, #resolved_expr_type, #summarize_platform_surface_entries, #type_module_name

Methods included from LinterFlowRules

#cfg_binding_resolution, #cfg_identifier_binding_key, #dead_assignment_analysis, #emit_borrow_warnings, #emit_constant_condition_warnings, #emit_dead_assignment_warnings, #emit_loop_single_iteration_warnings, #emit_redundant_null_check_warnings, #emit_unreachable_warnings, #ignored_binding_name?, #null_check_identifier, #statement_flow_analysis, #walk_stmts_for_loop_check

Methods included from LinterDocTags

#collect_doc_comment_block_for_line, #doc_tag_column, #each_doc_comment_definition, #emit_doc_tag_warnings, #parse_doc_tag_block, #validate_doc_tags_for_declaration

Constructor Details

#initialize(path: nil, sema_facts: nil, source: nil, unresolved_import_paths: nil, imported_modules: nil, source_ast: nil, profile: nil, lint_tier: :full, max_line_length: nil) ⇒ Linter

Returns a new instance of Linter.



738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
 
# File 'lib/milk_tea/tooling/linter.rb', line 738

def initialize(path: nil, sema_facts: nil, source: nil, unresolved_import_paths: nil, imported_modules: nil, source_ast: nil, profile: nil, lint_tier: :full, max_line_length: nil)
  @path = path
  @sema_facts = sema_facts
  @unresolved_import_paths = (unresolved_import_paths || Set.new).to_set
  @imported_modules = (imported_modules || {}).dup
  @source = source.to_s
  @source_lines = source ? source.lines.map { |line| line.delete_suffix("\n") } : []
  @tokens = begin
    Lexer.lex(@source, path: @path)
  rescue StandardError
    []
  end
  @token_index_by_location = @tokens.each_with_index.each_with_object({}) do |(token, index), locations|
    locations[[token.line, token.column]] ||= index
  end
  @tokens_by_line = @tokens.each_with_object(Hash.new { |hash, line| hash[line] = [] }) do |token, by_line|
    next if %i[newline indent dedent eof].include?(token.type)

    by_line[token.line] << token
  end
  @source_ast = source_ast
  @profile = profile
  @warnings = []
  @scopes = []
  @module_bindings = {}
  @declared_callable_names = Set.new
  @declared_directional_functions = {}
  @generic_function_depth = 0
  @current_function_stack = []
  @unsafe_depth = 0
  @binding_ptr_unsafe_uses = Hash.new { |h, k| h[k] = { safe: 0, unsafe: 0 } }
  @ptr_candidates = Set.new
  @reserved_primitive_name_fixes = []
  @lint_tier = self.class.normalize_lint_tier(lint_tier)
  @max_line_length = max_line_length&.to_i&.positive? ? max_line_length.to_i : Formatter::DEFAULT_MAX_LINE_LENGTH
  @cfg_binding_resolution = nil
  @cfg_binding_resolution_computed = false
  @statement_flow_analysis_cache = {}
  @dead_assignment_analysis_cache = {}
end

Class Method Details

.apply_reserved_primitive_name_fixes(source, fixes) ⇒ Object 



528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
 
# File 'lib/milk_tea/tooling/linter.rb', line 528

def self.apply_reserved_primitive_name_fixes(source, fixes)
  return source if fixes.empty?

  line_offsets = line_start_offsets(source)
  edits = fixes.flat_map do |fix|
    fix.sites.uniq { |site| [site.line, site.column] }.filter_map do |site|
      next unless site.line && site.column
      next unless site.line >= 1 && site.line <= line_offsets.length

      {
        start_offset: line_offsets[site.line - 1] + site.column - 1,
        length: site.length,
        replacement: fix.replacement_name,
      }
    end
  end
  return source if edits.empty?

  updated_source = source.dup
  edits.sort_by { |edit| [edit[:start_offset], edit[:length]] }.reverse_each do |edit|
    updated_source[edit[:start_offset], edit[:length]] = edit[:replacement]
  end
  updated_source
end

.apply_suppressions(warnings, suppressions) ⇒ Object 



719
720
721
722
723
724
725
726
727
728
729
730
 
# File 'lib/milk_tea/tooling/linter.rb', line 719

def self.apply_suppressions(warnings, suppressions)
  return warnings if suppressions.empty?

  warnings.reject do |w|
    next false unless w.line
    # Suppression on same line (trailing) or preceding line (leading comment)
    [w.line, w.line - 1].any? do |check_line|
      entry = suppressions[check_line]
      entry == :all || (entry.is_a?(Set) && entry.include?(w.code))
    end
  end
end

.best_effort_lint_context(source, path: nil, profile: nil, label: "best_effort_lint_context") ⇒ Object 



587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
 
# File 'lib/milk_tea/tooling/linter.rb', line 587

def self.best_effort_lint_context(source, path: nil, profile: nil, label: "best_effort_lint_context")
  ast = profile_phase(profile, "#{label}.parse") { Parser.parse(source, path:) }
  imported_modules = {}
  unresolved_import_paths = Set.new

  resolved_path = resolve_lint_path(path)
  if resolved_path && File.file?(resolved_path)
    effective_platform = ModuleLoader.effective_platform_for_path(resolved_path)
    loader = ModuleLoader.new(
      module_roots: MilkTea::ModuleRoots.roots_for_path(resolved_path),
      package_graph: load_lint_package_graph(resolved_path),
      source_overrides: { resolved_path => source },
      platform: effective_platform,
    )
    ast = profile_phase(profile, "#{label}.load_root") { loader.load_file(resolved_path) }
    resolution = profile_phase(profile, "#{label}.imports") do
      loader.imported_modules_for_ast_collecting_errors(ast, importer_path: resolved_path)
    end
    imported_modules = resolution.modules
    unresolved_import_paths.merge(resolution.errors.filter_map { |entry| entry.import&.path&.to_s })
  end

  sema_snapshot = profile_phase(profile, "#{label}.sema") do
    SemanticAnalyzer.tooling_snapshot(ast, imported_modules: imported_modules, path: resolved_path || path)
  end

  {
    ast: ast,
    facts: sema_snapshot.facts,
    sema_snapshot: sema_snapshot,
    errors: sema_snapshot.diagnostics,
    imported_modules: imported_modules,
    unresolved_import_paths: unresolved_import_paths,
  }
rescue StandardError
  unresolved = ast ? ast.imports.map { |i| i.path.to_s }.to_set : Set.new
  { ast: nil, facts: nil, sema_snapshot: nil, errors: nil, imported_modules: {}, unresolved_import_paths: unresolved }
end

.best_effort_sema_facts(source, path: nil) ⇒ Object 



626
627
628
 
# File 'lib/milk_tea/tooling/linter.rb', line 626

def self.best_effort_sema_facts(source, path: nil)
  best_effort_lint_context(source, path:).fetch(:facts)
end

.bool_literal_value(text) ⇒ Object 



682
683
684
685
686
687
688
 
# File 'lib/milk_tea/tooling/linter.rb', line 682

def self.bool_literal_value(text)
  case text
  when "true" then true
  when "false" then false
  else nil
  end
end

.build_prefer_let_else_fix(lines, if_idx, symbol_name: nil) ⇒ Object 



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
 
# File 'lib/milk_tea/tooling/linter.rb', line 563

def self.build_prefer_let_else_fix(lines, if_idx, symbol_name: nil)
  return nil if if_idx.nil? || if_idx <= 0 || if_idx >= lines.length

  declaration = lines[if_idx - 1].delete_suffix("\n")
  guard = lines[if_idx].delete_suffix("\n")
  name = symbol_name ||
    guard[/\A\s*if\s+([A-Za-z_][A-Za-z0-9_]*)\s*==\s*null\s*:/, 1] ||
    guard[/\A\s*if\s+null\s*==\s*([A-Za-z_][A-Za-z0-9_]*)\s*:/, 1]
  return nil unless name

  declaration_comment = declaration[/\s+#.*\z/] || ""
  declaration_base = declaration.sub(/\s+#.*\z/, "").rstrip
  declaration_match = declaration_base.match(/\A(\s*)(let|var)\s+#{Regexp.escape(name)}\s*=\s*.+\z/)
  return nil unless declaration_match
  return nil if declaration_base.end_with?(" else:")
  return nil unless guard.match?(/\A\s*if\s+(?:#{Regexp.escape(name)}\s*==\s*null|null\s*==\s*#{Regexp.escape(name)})\s*:\s*(?:#.*)?\z/)

  new_text = +"#{declaration_base} else:"
  new_text << declaration_comment unless declaration_comment.empty?
  new_text << "\n"

  { start_line_idx: if_idx - 1, end_line_idx: if_idx, new_text: }
end

.collect_reserved_primitive_name_fixes(source, path: nil, sema_facts: UNSET, unresolved_import_paths: UNSET) ⇒ Object 



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/milk_tea/tooling/linter.rb', line 281

def self.collect_reserved_primitive_name_fixes(source, path: nil, sema_facts: UNSET, unresolved_import_paths: UNSET)
  sema_facts_provided = !sema_facts.equal?(UNSET)
  unresolved_import_paths_provided = !unresolved_import_paths.equal?(UNSET)
  context = nil
  if !sema_facts_provided || !unresolved_import_paths_provided
    context = best_effort_lint_context(source, path:)
    sema_facts = context[:facts] unless sema_facts_provided
    unresolved_import_paths = context[:unresolved_import_paths] unless unresolved_import_paths_provided
  end

  ast = sema_facts&.ast || context&.fetch(:ast, nil) || Parser.parse(source, path:)
  imported_modules = context&.fetch(:imported_modules, nil)
  imported_modules ||= imported_modules_from_facts(ast, sema_facts)
  linter = new(path:, sema_facts:, source:, unresolved_import_paths:, imported_modules:, source_ast: ast)
  linter.lint(ast)
  linter.reserved_primitive_name_fixes
end

.default_config_source ⇒ Object 



267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/milk_tea/tooling/linter.rb', line 267

def self.default_config_source
  lines = [
    "# Default Milk Tea lint configuration.",
    "# Remove entries from `select` to disable rules globally.",
    "max_line_length: #{Formatter::DEFAULT_MAX_LINE_LENGTH}",
    "select:",
  ]
  KNOWN_RULE_CODES.each do |code|
    lines << "  - #{code}"
  end
  lines << "ignore: []"
  "#{lines.join("\n")}\n"
end

.effective_max_line_length(path = nil) ⇒ Object 



263
264
265
 
# File 'lib/milk_tea/tooling/linter.rb', line 263

def self.effective_max_line_length(path = nil)
  load_config(path)&.fetch(:max_line_length, nil) || Formatter::DEFAULT_MAX_LINE_LENGTH
end

.error_signature_counts(errors) ⇒ Object 



516
517
518
519
520
 
# File 'lib/milk_tea/tooling/linter.rb', line 516

def self.error_signature_counts(errors)
  Array(errors).each_with_object(Hash.new(0)) do |error, counts|
    counts[[error.line, error.column, error.message]] += 1
  end
end

.filter_by_rules(warnings, select:, ignore:) ⇒ Object 



732
733
734
735
736
 
# File 'lib/milk_tea/tooling/linter.rb', line 732

def self.filter_by_rules(warnings, select:, ignore:)
  warnings = warnings.select { |w| select.include?(w.code) } if select
  warnings = warnings.reject { |w| ignore.include?(w.code) } if ignore
  warnings
end

.fix_source(source, path: nil, sema_facts: nil, select: nil, ignore: nil, max_passes: 5, profile: nil) ⇒ Object

Apply auto-fixable rules to source text. Handles: prefer-let, redundant-ignored-match-binding, prefer-let-else, prefer-var-else, redundant-bool-compare, redundant-else, redundant-return, reserved-primitive-name, trailing-list-comma. Returns the fixed source (may be identical to nothing-was-fixable input).



364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/milk_tea/tooling/linter.rb', line 364

def self.fix_source(source, path: nil, sema_facts: nil, select: nil, ignore: nil, max_passes: 5, profile: nil)
  pass_limit = [max_passes.to_i, 1].max
  current_source = source
  current_sema_facts = sema_facts

  pass_limit.times do
    updated_source = fix_source_single_pass_isolating_rules(
      current_source,
      path:,
      sema_facts: current_sema_facts,
      select:,
      ignore:,
      profile:,
    )
    return current_source if updated_source == current_source

    current_source = updated_source
    # Facts passed by callers are only valid for the first source snapshot.
    current_sema_facts = nil
  end

  current_source
end

.fix_source_single_pass(source, path: nil, sema_facts: nil, select: nil, ignore: nil) ⇒ Object 



437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
 
# File 'lib/milk_tea/tooling/linter.rb', line 437

def self.fix_source_single_pass(source, path: nil, sema_facts: nil, select: nil, ignore: nil)
  cfg = load_config(path)
  effective_select = select || cfg&.fetch(:select, nil)
  effective_ignore = ignore || cfg&.fetch(:ignore, nil)
  rule_enabled = lambda do |code|
    next false if effective_select && !effective_select.include?(code)
    next false if effective_ignore && effective_ignore.include?(code)

    true
  end

  working_context = sema_facts ? nil : best_effort_lint_context(source, path:)
  working_sema_facts = sema_facts || working_context[:facts]
  unresolved_import_paths = sema_facts ? Set.new : working_context[:unresolved_import_paths]
  # With unresolved imports the analysis facts are incomplete (receiver
  # editability, casts, ownership), so hint rules can misfire and fixes
  # would land on false positives. Leave such sources to the author.
  return source if unresolved_import_paths.any?

  warnings = lint_source(
    source,
    path:,
    sema_facts: working_sema_facts,
    unresolved_import_paths:,
    select:,
    ignore:,
  )
  lines = source.lines

  warnings.group_by(&:code).each do |code, code_warnings|
    next unless rule_enabled.call(code)

    code_warnings.sort_by { |w| [-(w.line || 0), -(w.column || 0)] }.each do |warning|
      edits = FixEngine.edits_for_rule(code, lines, warning)
      FixEngine.apply_fix_edits(lines, edits)
    end
  end

  fixed_source = lines.join

  if rule_enabled.call("reserved-primitive-name")
    reserved_warnings = lint_source(fixed_source, path:, select: Set["reserved-primitive-name"]).select do |w|
      w.code == "reserved-primitive-name" && w.line && w.column && w.symbol_name
    end
    unless reserved_warnings.empty?
      warning_sites = reserved_warnings.each_with_object(Set.new) do |warning, sites|
        sites << [warning.line, warning.column, warning.symbol_name]
      end
      reserved_fixes = collect_reserved_primitive_name_fixes(fixed_source, path:).select do |fix|
        declaration_site = fix.sites.first
        warning_sites.include?([declaration_site.line, declaration_site.column, fix.original_name])
      end

      fixed_source = apply_reserved_primitive_name_fixes(fixed_source, reserved_fixes)
    end
  end
  # Validation compares a best-effort re-analysis of the fixed source against
  # a baseline. When the caller supplied rich (full-package) facts there is
  # no working_context, but the fixed-source check is still best-effort — so
  # the baseline must also come from a best-effort analysis of the ORIGINAL
  # source, otherwise pre-existing best-effort-only errors (e.g. unresolved
  # cross-module imports in std files) would be counted as "new" and reject
  # every otherwise-valid fix.
  baseline_context = working_context || best_effort_lint_context(source, path:)
  validated_fixed_source(source, fixed_source, path:, baseline_errors: baseline_context[:errors])
end

.fix_source_single_pass_isolating_rules(source, path: nil, sema_facts: nil, select: nil, ignore: nil, profile: nil) ⇒ Object 



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/milk_tea/tooling/linter.rb', line 388

def self.fix_source_single_pass_isolating_rules(source, path: nil, sema_facts: nil, select: nil, ignore: nil, profile: nil)
  cfg = load_config(path)
  effective_select = select || cfg&.fetch(:select, nil)
  effective_ignore = ignore || cfg&.fetch(:ignore, nil)
  enabled_rules = AUTO_FIXABLE_RULE_CODES.select do |rule_code|
    next false if effective_select && !effective_select.include?(rule_code)
    next false if effective_ignore && effective_ignore.include?(rule_code)

    true
  end
  return source if enabled_rules.empty?

  current_source = source
  current_sema_facts = sema_facts

  # When no semantic facts are supplied, omit the argument entirely so
  # lint_source rebuilds a best-effort context. Passing an explicit `nil`
  # would suppress sema-dependent rules (e.g. widening redundant-cast).
  preflight_args = {
    path:,
    select: Set.new(enabled_rules),
    ignore: effective_ignore,
    profile:,
  }
  preflight_args[:sema_facts] = current_sema_facts if current_sema_facts
  preflight_warnings = lint_source(current_source, **preflight_args)
  return current_source if preflight_warnings.empty?

  preflight_codes = preflight_warnings.map(&:code).to_set
  active_rules = enabled_rules.select { |rule_code| preflight_codes.include?(rule_code) }
  return current_source if active_rules.empty?

  active_rules.each do |rule_code|
    updated_source = fix_source_single_pass(
      current_source,
      path:,
      sema_facts: current_sema_facts,
      select: Set[rule_code],
      ignore: effective_ignore,
    )
    next if updated_source == current_source

    current_source = updated_source
    current_sema_facts = nil
  end

  current_source
end

.imported_modules_from_facts(ast, sema_facts) ⇒ Object 



347
348
349
350
351
352
353
354
355
 
# File 'lib/milk_tea/tooling/linter.rb', line 347

def self.imported_modules_from_facts(ast, sema_facts)
  return {} unless ast && sema_facts

  ast.imports.each_with_object({}) do |import, imported_modules|
    alias_name = import.alias_name || import.path.parts.last
    module_binding = sema_facts.imports[alias_name]
    imported_modules[import.path.to_s] = module_binding if module_binding
  end
end

.introduces_new_errors?(modified_counts, baseline_counts) ⇒ Boolean

Returns:

  • (Boolean) 


522
523
524
525
526
 
# File 'lib/milk_tea/tooling/linter.rb', line 522

def self.introduces_new_errors?(modified_counts, baseline_counts)
  modified_counts.any? do |signature, count|
    count > baseline_counts.fetch(signature, 0)
  end
end

.line_start_offsets(source) ⇒ Object 



553
554
555
556
557
558
559
560
561
 
# File 'lib/milk_tea/tooling/linter.rb', line 553

def self.line_start_offsets(source)
  offsets = []
  start_offset = 0
  source.lines.each do |line|
    offsets << start_offset
    start_offset += line.length
  end
  offsets
end

.lint_source(source, path: nil, select: nil, ignore: nil, sema_facts: UNSET, unresolved_import_paths: UNSET, profile: nil, lint_tier: :full) ⇒ Object 



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/milk_tea/tooling/linter.rb', line 209

def self.lint_source(source, path: nil, select: nil, ignore: nil, sema_facts: UNSET, unresolved_import_paths: UNSET, profile: nil, lint_tier: :full)
  sema_facts_provided = !sema_facts.equal?(UNSET)
  unresolved_import_paths_provided = !unresolved_import_paths.equal?(UNSET)
  if sema_facts_provided && !unresolved_import_paths_provided
    # Callers that already computed semantic facts should not pay for a
    # second context bootstrap only to derive unresolved imports.
    unresolved_import_paths = Set.new
    unresolved_import_paths_provided = true
  end
  cfg = load_config(path)
  context = nil
  if !sema_facts_provided || !unresolved_import_paths_provided
    context = best_effort_lint_context(source, path:, profile:, label: "context_bootstrap")
    sema_facts = context[:facts] unless sema_facts_provided
    unresolved_import_paths = context[:unresolved_import_paths] unless unresolved_import_paths_provided
  end

  ast = profile_phase(profile, "resolve_ast") do
    sema_facts&.ast || context&.fetch(:ast, nil) || Parser.parse(source, path:)
  end
  imported_modules = context&.fetch(:imported_modules, nil)
  imported_modules ||= imported_modules_from_facts(ast, sema_facts)
  suppressions = {}
  if source.match?(/#\s*lint:\s*ignore(?:\(|\b)/)
    trivia = profile_phase(profile, "lex_trivia") { Lexer.lex_with_trivia(source, path:).trivia }
    suppressions = profile_phase(profile, "parse_suppressions") { parse_suppressions(trivia) }
  end
  warnings = new(
    path:,
    sema_facts:,
    source:,
    unresolved_import_paths:,
    imported_modules:,
    source_ast: ast,
    profile:,
    lint_tier: normalize_lint_tier(lint_tier),
    max_line_length: cfg&.fetch(:max_line_length, nil),
  ).lint(ast)
  warnings = profile_phase(profile, "apply_suppressions") { apply_suppressions(warnings, suppressions) }

  # Layer in config-file defaults before per-call overrides
  if cfg
    select ||= cfg[:select]
    ignore ||= cfg[:ignore]
  end

  warnings = profile_phase(profile, "filter_rules") { filter_by_rules(warnings, select:, ignore:) }
  warnings
end

.load_config(path) ⇒ Object

Load the nearest .mt-lint.yml walking up from the source file's directory. Returns Hash { select: Set|nil, ignore: Set|nil } or nil if no config found.



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/milk_tea/tooling/linter.rb', line 301

def self.load_config(path)
  resolved_path = resolve_lint_path(path)
  return nil unless resolved_path

  dir = File.directory?(resolved_path) ? resolved_path : File.dirname(resolved_path)
  # Walk up until we either find a config or leave the project
  100.times do
    candidate = File.join(dir, DEFAULT_CONFIG_FILE_NAME)
    if File.exist?(candidate)
      return parse_config_file(candidate)
    end
    parent = File.dirname(dir)
    break if parent == dir  # filesystem root

    dir = parent
  end
  nil
rescue StandardError
  nil
end

.load_lint_package_graph(path) ⇒ Object 



697
698
699
700
701
 
# File 'lib/milk_tea/tooling/linter.rb', line 697

def self.load_lint_package_graph(path)
  PackageGraph.load(path)
rescue PackageManifestError, PackageLockError
  nil
end

.negate_expression_text(text) ⇒ Object 



690
691
692
693
694
695
 
# File 'lib/milk_tea/tooling/linter.rb', line 690

def self.negate_expression_text(text)
  stripped = text.strip
  return "not #{stripped}" if stripped.match?(/\A[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*\z/)

  "not (#{stripped})"
end

.normalize_lint_tier(tier) ⇒ Object 



204
205
206
207
 
# File 'lib/milk_tea/tooling/linter.rb', line 204

def self.normalize_lint_tier(tier)
  normalized = tier.to_s.strip.downcase.to_sym
  LINT_TIERS.include?(normalized) ? normalized : :full
end

.parse_config_file(path) ⇒ Object 



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/milk_tea/tooling/linter.rb', line 322

def self.parse_config_file(path)
  require "yaml"
  raw = YAML.safe_load_file(path, symbolize_names: true) || {}
  result = {}
  if (s = raw[:select])
    result[:select] = Array(s).map(&:to_s).to_set
  end
  if (i = raw[:ignore])
    result[:ignore] = Array(i).map(&:to_s).to_set
  end
  if raw.key?(:max_line_length)
    max_line_length = raw[:max_line_length].to_i
    result[:max_line_length] = max_line_length if max_line_length.positive?
  end
  result
rescue StandardError
  {}
end

.parse_suppressions(trivia) ⇒ Object

Parse # lint: ignore / # lint: ignore(rule1, rule2) comments. Returns Hash { line_number => Set | :all }



705
706
707
708
709
710
711
712
713
714
715
716
717
 
# File 'lib/milk_tea/tooling/linter.rb', line 705

def self.parse_suppressions(trivia)
  result = {}
  trivia.select { |t| t.kind == :comment }.each do |t|
    text = t.text.strip
    if (m = text.match(/\A#\s*lint:\s*ignore\(([^)]+)\)\z/))
      codes = m[1].split(",").map(&:strip).to_set
      result[t.line] = codes
    elsif text.match(/\A#\s*lint:\s*ignore\z/)
      result[t.line] = :all
    end
  end
  result
end

.profile_phase(profile, name) ⇒ Object 



341
342
343
344
345
 
# File 'lib/milk_tea/tooling/linter.rb', line 341

def self.profile_phase(profile, name)
  return yield unless profile

  profile.measure(name) { yield }
end

.quick_fix_title(code) ⇒ Object 



259
260
261
 
# File 'lib/milk_tea/tooling/linter.rb', line 259

def self.quick_fix_title(code)
  STATIC_QUICK_FIX_TITLES[code]
end

.redundant_bool_compare_replacement(expression_text) ⇒ Object 



660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
 
# File 'lib/milk_tea/tooling/linter.rb', line 660

def self.redundant_bool_compare_replacement(expression_text)
  match = expression_text.match(/\A\s*(.+?)\s*(==|!=)\s*(.+?)\s*\z/m)
  return nil unless match

  left_text = match[1].strip
  operator = match[2]
  right_text = match[3].strip
  left_bool = bool_literal_value(left_text)
  right_bool = bool_literal_value(right_text)
  return nil if left_bool.nil? == right_bool.nil?

  literal_value = left_bool.nil? ? right_bool : left_bool
  compared_text = left_bool.nil? ? left_text : right_text
  negate = if operator == "=="
             literal_value == false
           else
             literal_value == true
           end

  negate ? negate_expression_text(compared_text) : compared_text
end

.redundant_ignored_match_binding_span(line, column:) ⇒ Object 



642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
 
# File 'lib/milk_tea/tooling/linter.rb', line 642

def self.redundant_ignored_match_binding_span(line, column:)
  anchor_idx = column - 1
  return nil unless anchor_idx >= 0 && anchor_idx < line.length

  scan_start = [anchor_idx - 5, 0].max
  match = line[scan_start..]&.match(/\s+as\s+_/)
  return nil unless match

  start_char = scan_start + match.begin(0)
  end_char = scan_start + match.end(0)
  return nil unless anchor_idx >= start_char && anchor_idx < end_char

  {
    start_char:,
    end_char:,
  }
end

.resolve_lint_path(path) ⇒ Object 



630
631
632
633
634
635
636
637
638
639
640
 
# File 'lib/milk_tea/tooling/linter.rb', line 630

def self.resolve_lint_path(path)
  return nil unless path.is_a?(String) && !path.empty?

  if path.start_with?("file://")
    CGI.unescape(URI.parse(path).path)
  else
    File.expand_path(path)
  end
rescue StandardError
  nil
end

.validated_fixed_source(original_source, fixed_source, path:, baseline_errors:) ⇒ Object 



504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/milk_tea/tooling/linter.rb', line 504

def self.validated_fixed_source(original_source, fixed_source, path:, baseline_errors:)
  return fixed_source if fixed_source == original_source

  fixed_context = best_effort_lint_context(fixed_source, path:)
  return fixed_source if fixed_context[:ast] && !introduces_new_errors?(
    error_signature_counts(fixed_context[:errors]),
    error_signature_counts(baseline_errors),
  )

  original_source
end

Instance Method Details

#full_tier? ⇒ Boolean

Returns:

  • (Boolean) 


790
791
792
 
# File 'lib/milk_tea/tooling/linter.rb', line 790

def full_tier?
  @lint_tier == :full
end

#lint(ast) ⇒ Object 



779
780
781
782
783
784
785
786
787
788
 
# File 'lib/milk_tea/tooling/linter.rb', line 779

def lint(ast)
  @source_ast ||= ast
  visit_source_file(ast)
  profile_phase("rule.doc_tag") { emit_doc_tag_warnings(ast) } if full_tier?
  profile_phase("rule.event_capacity") { emit_event_capacity_warnings(ast) }
  profile_phase("rule.trailing_list_comma") { emit_trailing_list_comma_warnings(ast) }
  profile_phase("rule.prefer_inline_methods") { emit_prefer_inline_methods_warnings(ast) }
  profile_phase("rule.line_too_long") { emit_line_too_long_warnings }
  @warnings
end

#reserved_primitive_name_fixes ⇒ Object 



794
795
796
 
# File 'lib/milk_tea/tooling/linter.rb', line 794

def reserved_primitive_name_fixes
  @reserved_primitive_name_fixes
end