haml_lint 0.53.0 → 0.76.0

data/lib/haml_lint/linter/unnecessary_string_output.rb

@@ -11,32 +11,99 @@ module HamlLint
   class Linter::UnnecessaryStringOutput < Linter
     include LinterRegistry
 
+    supports_autocorrect(true)
+    autocorrect_safe(false)
+
     MESSAGE = '`= "..."` should be rewritten as `...`'
 
     def visit_tag(node)
-      if tag_has_inline_script?(node) && inline_content_is_string?(node)
-        record_lint(node, MESSAGE)
-      end
+      return unless tag_has_inline_script?(node) && inline_content_is_string?(node)
+
+      plain = safe_plain_text(node.script)
+      corrected = plain ? correct_tag(node, plain) : false
+      record_lint(node, MESSAGE, corrected: corrected)
     end
 
     def visit_script(node)
-      # Some script nodes created by the HAML parser aren't actually script
+      # Some script nodes created by the Haml parser aren't actually script
       # nodes declared via the `=` marker. Check for it.
-      return if node.source_code !~ /\A\s*=/
+      return unless /\A\s*=/.match?(node.source_code)
+      return unless plain = safe_plain_text(node.script)
 
-      if outputs_string_literal?(node)
-        record_lint(node, MESSAGE)
-      end
+      record_lint(node, MESSAGE, corrected: correct_script(node, plain))
     end
 
     private
 
-    def outputs_string_literal?(script_node)
-      return unless tree = parse_ruby(script_node.script)
-      %i[str dstr].include?(tree.type) &&
-        !starts_with_reserved_character?(tree.children.first)
+    # Rewrites `%tag= "..."` as `%tag ...`, dropping the `=` marker and the
+    # surrounding quotes.
+    #
+    # @return [Boolean] whether a correction was applied
+    def correct_tag(node, plain)
+      marker = node.inline_marker_source.rstrip
+      # Only unwrap plain escaped output (`= "..."`); leave `!=`, `~`, and the
+      # whitespace-removal markers (`<`/`>`) untouched, as they change rendering.
+      return false unless /\A=\s*["']/.match?(marker)
+
+      index = node.line - 1
+      line = autocorrected_lines[index]
+      return false unless line.rstrip.end_with?(marker)
+
+      prefix = line.rstrip[0...(line.rstrip.length - marker.length)]
+      correct_line(index, "#{prefix} #{plain}")
+    end
+
+    # Rewrites a standalone `= "..."` script as plain text, preserving the
+    # node's indentation.
+    #
+    # @return [Boolean] whether a correction was applied
+    def correct_script(node, plain)
+      index = node.line - 1
+      line = autocorrected_lines[index]
+      indentation = line[/\A\s*/]
+      correct_line(index, "#{indentation}#{plain}")
+    end
+
+    # Returns the Haml plain-text equivalent of a Ruby string literal script, or
+    # +nil+ when the script is not a string literal that can be safely unwrapped
+    # (i.e. unwrapping would change the rendered output).
+    #
+    # @return [String, nil]
+    def safe_plain_text(script)
+      return if script.include?("\n")
+      return unless tree = parse_ruby(script)
+      return unless %i[str dstr].include?(tree.type)
+      return unless safely_unwrappable?(tree)
+
+      plain_text_from(tree)
     rescue ::Parser::SyntaxError
       # Gracefully ignore syntax errors, as that's managed by a different linter
+      nil
+    end
+
+    # Whether unwrapping the string literal into Haml plain text would preserve
+    # the rendered output.
+    #
+    # @return [Boolean]
+    def safely_unwrappable?(tree)
+      !starts_with_reserved_character?(tree.children.first) &&
+        !contains_escape_sequence?(tree) &&
+        !contains_significant_whitespace?(tree)
+    end
+
+    # Reconstructs the Haml plain-text form of a string literal. Literal segments
+    # keep their text (with any `#{` escaped so Haml won't interpolate it), while
+    # interpolation segments are emitted verbatim in their `#{...}` form.
+    #
+    # @return [String]
+    def plain_text_from(tree)
+      string_segments(tree).map do |segment|
+        if segment.type == :str
+          segment.children.first.gsub('#{') { '\#{' }
+        else
+          segment.location.expression.source
+        end
+      end.join
     end
 
     # Returns whether a string starts with a character that would otherwise be
@@ -45,5 +112,34 @@ module HamlLint
       string = stringish.respond_to?(:children) ? stringish.children.first : stringish
       string =~ %r{\A\s*[/#-=%~]} if string.is_a?(String)
     end
+
+    # The ordered segments of a string literal, including any interpolation.
+    # A plain `str` node has no interpolation, so it is its own only segment.
+    def string_segments(tree)
+      tree.type == :dstr ? tree.children : [tree]
+    end
+
+    # Returns whether any literal portion of the string contains a backslash
+    # escape (e.g. `\n`, `\t`, `\u202F`). Such escapes are interpreted inside
+    # a Ruby string but would be emitted verbatim as Haml plain text, so the
+    # `= "..."` form is not equivalent to the unwrapped plain text.
+    def contains_escape_sequence?(tree)
+      string_segments(tree).any? do |segment|
+        segment.type == :str && segment.location.expression.source.include?('\\')
+      end
+    end
+
+    # Returns whether the string begins or ends with whitespace. Haml strips
+    # trailing whitespace from plain text (and leading whitespace denotes
+    # indentation), so unwrapping such a string would change the output.
+    def contains_significant_whitespace?(tree)
+      segments = string_segments(tree)
+      bounded_by_whitespace?(segments.first, /\A\s/) ||
+        bounded_by_whitespace?(segments.last, /\s\z/)
+    end
+
+    def bounded_by_whitespace?(segment, pattern)
+      segment.type == :str && segment.children.first.to_s.match?(pattern)
+    end
   end
 end

data/lib/haml_lint/linter.rb

@@ -37,7 +37,7 @@ module HamlLint
           :error
         )
     rescue StandardError => e
-      msg = "Couldn't process the file".dup
+      msg = +"Couldn't process the file"
       if @autocorrect
         # Those lints related to auto-correction were not saved, so don't display them
         @lints = []
@@ -56,13 +56,14 @@ module HamlLint
     end
 
     # Runs the linter against the given Haml document, raises if the file cannot be processed due to
-    # Syntax or HAML-Lint internal errors. (For testing purposes)
+    # Syntax or Haml-Lint internal errors. (For testing purposes)
     #
     # @param document [HamlLint::Document]
     def run_or_raise(document, autocorrect: nil)
       @document = document
       @lints = []
       @autocorrect = autocorrect
+      reset_autocorrect_state
       visit(document.tree)
       @lints
     end
@@ -85,6 +86,30 @@ module HamlLint
       self.class.supports_autocorrect?
     end
 
+    # Returns whether this linter's autocorrect is safe. Defaults to true (safe)
+    # unless the linter declares otherwise via `autocorrect_safe(false)`.
+    #
+    # @return [Boolean]
+    def self.autocorrect_safe?
+      @autocorrect_safe != false
+    end
+
+    # The autocorrect ordering priority for this linter. During autocorrect,
+    # linters with a lower priority run first and higher priority run later,
+    # against the same (already mutated) document. Linters with the same priority
+    # keep their default (alphabetical) order.
+    #
+    # Called with an argument (e.g. `autocorrect_priority(1)`) in a linter's
+    # top-level scope, it sets the priority; called with no argument it reads it.
+    # The default, when never set, is 0.
+    #
+    # @param value [Integer, nil] the new priority, or nil to read the current one
+    # @return [Integer]
+    def self.autocorrect_priority(value = nil)
+      @autocorrect_priority = value unless value.nil?
+      @autocorrect_priority || 0
+    end
+
     private
 
     attr_reader :config, :document
@@ -97,15 +122,104 @@ module HamlLint
       @supports_autocorrect = value
     end
 
+    # Linters can call autocorrect_safe(false) in their top-level scope to declare that their
+    # autocorrect is unsafe, meaning it only runs under `--auto-correct-all` (`:all`).
+    # The default, when not called, is safe.
+    #
+    # @params value [Boolean] The new value for autocorrect_safe
+    private_class_method def self.autocorrect_safe(value)
+      @autocorrect_safe = value
+    end
+
+    # Resets the per-run autocorrect bookkeeping. Linter instances are reused
+    # across files, so subclasses that accumulate extra autocorrect state during
+    # a traversal (e.g. a list of lines to merge or delete) must override this,
+    # calling `super`, to clear that state between files. Otherwise corrections
+    # from one file leak into the next.
+    def reset_autocorrect_state
+      @autocorrected_lines = nil
+      @autocorrect_changed = false
+    end
+
+    # Whether the linter is currently allowed to apply autocorrections, given the active
+    # autocorrect mode and this linter's declared safety:
+    #
+    #   * safe linters correct under both `:safe` and `:all`;
+    #   * unsafe linters correct only under `:all`;
+    #   * with no mode (`nil`) nothing is corrected (detection only).
+    #
+    # @return [Boolean]
+    def autocorrect?
+      case @autocorrect
+      when :all
+        true
+      when :safe
+        self.class.autocorrect_safe?
+      else
+        false
+      end
+    end
+
+    # Applies a corrected, full-document source to the document through the single
+    # mutation path (`Document#change_source`), but only when the safety gate permits.
+    # No-ops otherwise; `change_source` itself also no-ops when the source is unchanged.
+    #
+    # @param new_source [String] the corrected Haml source
+    def apply_autocorrect(new_source)
+      return unless autocorrect?
+      document.change_source(new_source)
+    end
+
+    # Lazily-initialized working copy of the document's source lines, used to
+    # accumulate line-level corrections during a single tree traversal. Editing
+    # this copy (rather than calling `apply_autocorrect` per node) avoids
+    # reparsing the document mid-walk, which would invalidate the tree being
+    # visited.
+    #
+    # @return [Array<String>]
+    def autocorrected_lines
+      @autocorrected_lines ||= document.source_lines.dup
+    end
+
+    # Replaces a single source line (0-indexed) in the working copy, but only
+    # when autocorrect is permitted and the new text actually differs.
+    #
+    # @param index [Integer] the 0-indexed line to replace
+    # @param new_text [String] the corrected line
+    # @return [Boolean] true if a change was recorded, false otherwise
+    def correct_line(index, new_text)
+      return false unless autocorrect?
+      return false if autocorrected_lines[index] == new_text
+
+      autocorrected_lines[index] = new_text
+      @autocorrect_changed = true
+    end
+
+    # Flushes any corrections accumulated via `correct_line` through the single
+    # mutation path, once, after the whole tree has been visited. Defined on the
+    # base so per-node linters need no boilerplate; no-ops for linters that never
+    # accumulated a change (including those that apply within `visit_root`).
+    #
+    # NOTE: a linter that overrides `after_visit_root` must call `super`, or
+    # accumulated corrections will not be applied.
+    def after_visit_root(_node)
+      return unless @autocorrect_changed
+
+      apply_autocorrect(autocorrected_lines.join("\n"))
+    end
+
     # Record a lint for reporting back to the user.
     #
     # @param node_or_line [#line] line number or node to extract the line number from
     # @param message [String] error/warning to display to the user
-    def record_lint(node_or_line, message, corrected: false)
+    # @param corrected [Boolean] whether the lint was fixed by auto-correct
+    # @param correctable [Boolean] whether the lint can be fixed by auto-correct;
+    #   defaults to whether this linter supports auto-correct at all
+    def record_lint(node_or_line, message, corrected: false, correctable: supports_autocorrect?)
       line = node_or_line.is_a?(Integer) ? node_or_line : node_or_line.line
       @lints << HamlLint::Lint.new(self, @document.file, line, message,
                                    config.fetch('severity', :warning).to_sym,
-                                   corrected: corrected)
+                                   corrected: corrected, correctable: correctable)
     end
 
     # Parse Ruby code into an abstract syntax tree.
@@ -231,7 +345,7 @@ module HamlLint
       # excess whitespace
       @document.source_lines[(tag_node.line - 1)...(following_node_line(tag_node) - 1)]
                .map do |line|
-        line.strip.gsub(/\|\z/, '').rstrip
+        line.strip.delete_suffix('|').rstrip
       end.join(' ')
     end
   end

data/lib/haml_lint/node_transformer.rb

@@ -4,7 +4,7 @@ module HamlLint
   # Responsible for transforming {Haml::Parser::ParseNode} objects into
   # corresponding {HamlLint::Tree::Node} objects.
   #
-  # The parse tree generated by HAML has a number of strange cases where certain
+  # The parse tree generated by Haml has a number of strange cases where certain
   # types of nodes are created that don't necessarily correspond to what one
   # would expect. This class is intended to isolate and handle these cases so
   # that linters don't have to deal with them.
@@ -16,7 +16,7 @@ module HamlLint
       @document = document
     end
 
-    # Converts the given HAML parse node into its corresponding HAML-Lint parse
+    # Converts the given Haml parse node into its corresponding Haml-Lint parse
     # node.
     #
     # @param haml_node [Haml::Parser::ParseNode]

data/lib/haml_lint/options.rb

@@ -10,7 +10,7 @@ module HamlLint
     # @param args [Array<String>] arguments passed via the command line
     # @return [Hash] parsed options
     def parse(args)
-      @options = {}
+      @options = default_options
 
       OptionParser.new do |parser|
         parser.banner = "Usage: #{APP_NAME} [options] [file1, file2, ...]"
@@ -32,7 +32,11 @@ module HamlLint
 
     private
 
-    def add_linter_options(parser) # rubocop:disable Metrics/MethodLength
+    def default_options
+      { parallel: true }
+    end
+
+    def add_linter_options(parser) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       parser.on('--auto-gen-config', 'Generate a configuration file acting as a TODO list') do
         @options[:auto_gen_config] = true
       end
@@ -56,6 +60,10 @@ module HamlLint
         @options[:parallel] = true
       end
 
+      parser.on('--no-parallel', 'Disable parallel linter runs') do
+        @options[:parallel] = false
+      end
+
       parser.on('-a', '--auto-correct', 'Auto-correct offenses (only when it’s safe)') do
         @options[:autocorrect] = :safe
       end
@@ -70,7 +78,13 @@ module HamlLint
         @options[:autocorrect] ||= :safe
       end
 
-      parser.on('--stderr', 'Write all output to stderr') do
+      parser.on('-s', '--stdin FILE', 'Pipe source from STDIN, using FILE in ' \
+          'offense when combined with --auto-correct and --stdin.') do |file_path|
+        @options[:stdin] = file_path
+      end
+
+      parser.on('--stderr', 'Write all output to stderr except for the autocorrected source. ' \
+          'This is especially useful when combined with --auto-correct and --stdin') do
         @options[:stderr] = true
       end
     end

data/lib/haml_lint/rake_task.rb

@@ -2,7 +2,8 @@
 
 require 'rake'
 require 'rake/tasklib'
-require 'haml_lint/constants'
+
+require_relative 'constants'
 
 module HamlLint
   # Rake task interface for haml-lint command line interface.
@@ -93,7 +94,7 @@ module HamlLint
 
       task(name, [:files]) do |_task, task_args|
         # Lazy-load so task doesn't affect Rakefile load time
-        require 'haml_lint/cli'
+        require_relative 'cli'
 
         run_cli(task_args)
       end

data/lib/haml_lint/reporter/default_reporter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'haml_lint/reporter/utils'
+require_relative 'utils'
 
 module HamlLint
   # Outputs lints in a simple format with the filename, line number, and lint

data/lib/haml_lint/reporter/disabled_config_reporter.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
-require 'haml_lint/reporter/progress_reporter'
+require_relative 'progress_reporter'
 
 module HamlLint
   # Outputs a YAML configuration file based on existing violations.
   class Reporter::DisabledConfigReporter < Reporter::ProgressReporter
-    HEADING =
+    DEFAULT_EXCLUDE_LIMIT = 15
+
+    HEADING_TEMPLATE =
       ['# This configuration was generated by',
-       '# `haml-lint --auto-gen-config`',
-       "# on #{Time.now} using Haml-Lint version #{HamlLint::VERSION}.",
+       '# `%<command>s`',
+       '# on %<timestamp>s using Haml-Lint version %<version>s.',
        '# The point is for the user to remove these configuration records',
        '# one by one as the lints are removed from the code base.',
        '# Note that changes in the inspected code, or installation of new',
@@ -25,11 +27,12 @@ module HamlLint
     # Create the reporter that will display the report and write the config.
     #
     # @param _log [HamlLint::Logger]
-    def initialize(log, limit: 15)
+    def initialize(log, limit: DEFAULT_EXCLUDE_LIMIT, options: {})
       super(log)
       @linters_with_lints = Hash.new { |hash, key| hash[key] = [] }
       @linters_lint_count = Hash.new(0)
       @exclude_limit = limit
+      @options = options
     end
 
     # A hash of linters with the files that have that type of lint.
@@ -81,17 +84,35 @@ module HamlLint
 
     private
 
+    # Reconstructs the CLI command used to generate this config.
+    #
+    # @return [String] the command string
+    def command
+      cmd = "#{HamlLint::APP_NAME} --auto-gen-config"
+      if @options[:auto_gen_exclude_limit]
+        cmd += " --auto-gen-exclude-limit #{@options[:auto_gen_exclude_limit]}"
+      end
+      cmd
+    end
+
+    # The heading comment for the generated config file.
+    #
+    # @return [String]
+    def heading
+      format(HEADING_TEMPLATE, command: command, timestamp: Time.now, version: HamlLint::VERSION)
+    end
+
     # The contents of the generated configuration file based on captured lint.
     #
     # @return [String] a Yaml-formatted configuration file's contents
     def config_file_contents
       output = []
-      output << HEADING
+      output << heading
       output << 'linters:' if linters_with_lints.any?
-      linters_with_lints.each do |linter, files|
+      linters_with_lints.sort.each do |linter, files|
         output << generate_config_for_linter(linter, files)
       end
-      output.join("\n\n")
+      output.join("\n\n") + "\n"
     end
 
     # Constructs the configuration for excluding a linter in some files.

data/lib/haml_lint/reporter/github_reporter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: false
+
+module HamlLint
+  # Outputs GitHub workflow commands for GitHub check annotations when run within GitHub actions.
+  class Reporter::GithubReporter < Reporter
+    # Characters to escape within a command message.
+    ESCAPE_MAP = { '%' => '%25', "\n" => '%0A', "\r" => '%0D' }.freeze
+    # Property values also escape the `:` and `,` that delimit the command.
+    PROPERTY_ESCAPE_MAP = ESCAPE_MAP.merge(':' => '%3A', ',' => '%2C').freeze
+
+    include Reporter::Utils
+
+    def added_lint(lint, report)
+      severity = lint.severity >= report.fail_level ? 'error' : 'warning'
+      print_workflow_command(lint, severity)
+    end
+
+    def display_report(report)
+      print_summary(report)
+    end
+
+    private
+
+    def print_workflow_command(lint, severity)
+      log.log "::#{severity} file=#{github_escape_property(lint.filename)}," \
+              "line=#{lint.line},title=#{github_escape_property(annotation_title(lint))}" \
+              "::#{github_escape(annotation_message(lint))}"
+    end
+
+    # Annotation title, naming the linter that produced the lint when known.
+    def annotation_title(lint)
+      lint.linter ? "haml-lint #{lint.linter.name}" : 'haml-lint'
+    end
+
+    # Message body, prefixed with the location and linter so it stays useful in the plain log.
+    def annotation_message(lint)
+      location = "#{lint.filename}:#{lint.line}"
+      location += " #{lint.linter.name}:" if lint.linter
+      "#{location} #{lint.message}"
+    end
+
+    def github_escape(string)
+      string.to_s.gsub(Regexp.union(ESCAPE_MAP.keys), ESCAPE_MAP)
+    end
+
+    def github_escape_property(string)
+      string.to_s.gsub(Regexp.union(PROPERTY_ESCAPE_MAP.keys), PROPERTY_ESCAPE_MAP)
+    end
+  end
+end

data/lib/haml_lint/reporter/hash_reporter.rb

@@ -47,6 +47,8 @@ module HamlLint
       {
         severity: offense.severity,
         message: offense.message,
+        corrected: offense.corrected,
+        correctable: offense.correctable,
         location: {
           line: offense.line,
         },

data/lib/haml_lint/reporter/json_reporter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'haml_lint/reporter/hash_reporter'
+require_relative 'hash_reporter'
 
 module HamlLint
   # Outputs report as a JSON document.

data/lib/haml_lint/reporter/progress_reporter.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require 'rainbow'
-require 'haml_lint/reporter/utils'
+
+require_relative 'utils'
 
 module HamlLint
   # Outputs files as they are output as a simple symbol, then outputs

data/lib/haml_lint/reporter/utils.rb

@@ -58,6 +58,8 @@ module HamlLint
       def print_message(lint)
         if lint.corrected
           log.success('[Corrected] ', false)
+        elsif lint.correctable
+          log.info('[Correctable] ', false)
         end
 
         if lint.linter
@@ -96,7 +98,7 @@ module HamlLint
       # Prints a summary of the number of lints found in a report.
       #
       # @param report [HamlLint::Report] the report to print
-      # @param is_append [Boolean] if this is appending to a line. Will preffix with ", ".
+      # @param is_append [Boolean] if this is appending to a line. Will prefix with ", ".
       # @return [void]
       def print_summary_lints(report, is_append:)
         log.log ', ', false if is_append
@@ -114,7 +116,7 @@ module HamlLint
       # Prints a summary of the number of lints corrected in a report.
       #
       # @param report [HamlLint::Report] the report to print
-      # @param is_append [Boolean] if this is appending to a line. Will preffix with ", ".
+      # @param is_append [Boolean] if this is appending to a line. Will prefix with ", ".
       # @return [void]
       def print_summary_corrected_lints(report, is_append:)
         lint_count = report.lints.count(&:corrected)

data/lib/haml_lint/reporter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'haml_lint/reporter/hooks'
+require_relative 'reporter/hooks'
 
 module HamlLint
   # Abstract lint reporter. Subclass and override {#display_report} to

data/lib/haml_lint/ruby_extraction/base_chunk.rb

@@ -2,13 +2,13 @@
 
 module HamlLint::RubyExtraction
   # This is the base class for all of the Chunks of HamlLint::RubyExtraction.
-  # A Chunk represents a part of the HAML file that HamlLint::Linter::RuboCop
+  # A Chunk represents a part of the Haml file that HamlLint::Linter::RuboCop
   # is processing and will insert some Ruby code in a file passed to RuboCop.
   #
-  # There are chunks for most HAML concepts, even if they don't represent Ruby
+  # There are chunks for most Haml concepts, even if they don't represent Ruby
   # code. For example, there is a chunk that represents a `%div` tag, which
   # uses a `begin` in the generated Ruby to add indentation for the children
-  # of the %div in the Ruby file just like there is in the HAML file.
+  # of the %div in the Ruby file just like there is in the Haml file.
   class BaseChunk
     COMMA_CHANGES_LINES = true
 
@@ -63,7 +63,7 @@ module HamlLint::RubyExtraction
       transfer_correction_logic(coordinator, to_ruby_lines, haml_lines)
     end
 
-    # To be overriden by subclasses.
+    # To be overridden by subclasses.
     #
     # Logic to transfer the corrections that turned from_ruby_lines into to_ruby_lines.
     #