liquid_lint 1.0.0

data/lib/liquid_lint/engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Temple engine used to generate a {Sexp} parse tree for use by linters.
+  #
+  # We omit a lot of the filters that are in {Liquid::Engine} because they result
+  # in information potentially being removed from the parse tree (since some
+  # Sexp abstractions are optimized/removed or otherwise transformed). In order
+  # for linters to be useful, they need to operate on the original parse tree.
+  #
+  # The other key task this engine accomplishes is converting the Array-based
+  # S-expressions into {LiquidLint::Sexp} objects, which have a number of helper
+  # methods that makes working with them easier. It also annotates these
+  # {LiquidLint::Sexp} objects with line numbers so it's easy to cross reference
+  # with the original source code.
+  class Engine < Temple::Engine
+    filter :Encoding
+    filter :RemoveBOM
+
+    # Parse into S-expression using Liquid parser
+    use Liquid::Parser
+
+    # Converts Array-based S-expressions into LiquidLint::Sexp objects
+    use LiquidLint::Filters::SexpConverter
+
+    # Annotates Sexps with line numbers
+    use LiquidLint::Filters::InjectLineNumbers
+
+    # Parses the given source code into a Sexp.
+    #
+    # @param source [String] source code to parse
+    # @return [LiquidLint::Sexp] parsed Sexp
+    def parse(source)
+      call(source)
+    rescue ::Liquid::Parser::SyntaxError => e
+      # Convert to our own exception type to isolate from upstream changes
+      error = LiquidLint::Exceptions::ParseError.new(e.error,
+                                                   e.file,
+                                                   e.line,
+                                                   e.lineno,
+                                                   e.column)
+      raise error
+    end
+  end
+end

data/lib/liquid_lint/exceptions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Collection of exceptions that can be raised by the application.
+module LiquidLint::Exceptions
+  # Raised when a {Configuration} could not be loaded from a file.
+  class ConfigurationError < StandardError; end
+
+  # Raised when invalid/incompatible command line options are provided.
+  class InvalidCLIOption < StandardError; end
+
+  # Raised when an invalid file path is specified
+  class InvalidFilePath < StandardError; end
+
+  # Raised when the Liquid parser is unable to parse a template.
+  class ParseError < ::Liquid::Parser::SyntaxError; end
+
+  # Raised when attempting to execute `Runner` with options that would result in
+  # no linters being enabled.
+  class NoLintersError < StandardError; end
+end

data/lib/liquid_lint/file_finder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module LiquidLint
+  # Finds Liquid files that should be linted given a specified list of paths, glob
+  # patterns, and configuration.
+  class FileFinder
+    # List of extensions of files to include under a directory when a directory
+    # is specified instead of a file.
+    VALID_EXTENSIONS = %w[.liquid].freeze
+
+    # Create a file finder using the specified configuration.
+    #
+    # @param config [LiquidLint::Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Return list of files to lint given the specified set of paths and glob
+    # patterns.
+    # @param patterns [Array<String>]
+    # @param excluded_patterns [Array<String>]
+    # @raise [LiquidLint::Exceptions::InvalidFilePath]
+    # @return [Array<String>] list of actual files
+    def find(patterns, excluded_patterns)
+      excluded_patterns = excluded_patterns.map { |pattern| normalize_path(pattern) }
+
+      extract_files_from(patterns).reject do |file|
+        LiquidLint::Utils.any_glob_matches?(excluded_patterns, file)
+      end
+    end
+
+    private
+
+    # Extract the list of matching files given the list of glob patterns, file
+    # paths, and directories.
+    #
+    # @param patterns [Array<String>]
+    # @return [Array<String>]
+    def extract_files_from(patterns) # rubocop:disable Metrics/MethodLength
+      files = []
+
+      patterns.each do |pattern|
+        if File.file?(pattern)
+          files << pattern
+        else
+          begin
+            ::Find.find(pattern) do |file|
+              files << file if liquid_file?(file)
+            end
+          rescue ::Errno::ENOENT
+            # File didn't exist; it might be a file glob pattern
+            matches = ::Dir.glob(pattern)
+            if matches.any?
+              files += matches
+            else
+              # One of the paths specified does not exist; raise a more
+              # descriptive exception so we know which one
+              raise LiquidLint::Exceptions::InvalidFilePath,
+                    "File path '#{pattern}' does not exist"
+            end
+          end
+        end
+      end
+
+      files.uniq.sort.map { |file| normalize_path(file) }
+    end
+
+    # Trim "./" from the front of relative paths.
+    #
+    # @param path [String]
+    # @return [String]
+    def normalize_path(path)
+      path.start_with?(".#{File::SEPARATOR}") ? path[2..-1] : path
+    end
+
+    # Whether the given file should be treated as a Liquid file.
+    #
+    # @param file [String]
+    # @return [Boolean]
+    def liquid_file?(file)
+      return false unless ::FileTest.file?(file)
+
+      VALID_EXTENSIONS.include?(::File.extname(file))
+    end
+  end
+end

data/lib/liquid_lint/filters/attribute_processor.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LiquidLint::Filters
+  # A dumbed-down version of {Liquid::CodeAttributes} which doesn't introduce any
+  # temporary variables or other cruft.
+  class AttributeProcessor < Liquid::Filter
+    define_options :merge_attrs
+
+    # Handle attributes expression `[:html, :attrs, *attrs]`
+    #
+    # @param attrs [Array]
+    # @return [Array]
+    def on_html_attrs(*attrs)
+      [:multi, *attrs.map { |a| compile(a) }]
+    end
+
+    # Handle attribute expression `[:html, :attr, name, value]`
+    #
+    # @param name [String] name of the attribute
+    # @param value [Array] Sexp representing the value
+    def on_html_attr(name, value)
+      if value[0] == :liquid && value[1] == :attrvalue
+        code = value[3]
+        [:code, code]
+      else
+        @attr = name
+        super
+      end
+    end
+  end
+end

data/lib/liquid_lint/filters/control_processor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LiquidLint::Filters
+  # A dumbed-down version of {Liquid::Controls} which doesn't introduce temporary
+  # variables and other cruft (which in the context of extracting Ruby code,
+  # results in a lot of weird cops reported by RuboCop).
+  class ControlProcessor < Liquid::Filter
+    BLOCK_RE = /\A(if|unless)\b|\bdo\s*(\|[^|]*\|)?\s*$/
+
+    # Handle control expression `[:liquid, :control, code, content]`
+    #
+    # @param code [String]
+    # @param content [Array]
+    def on_liquid_control(code, content)
+      [:multi,
+        [:code, code],
+        compile(content)]
+    end
+
+    # Handle output expression `[:liquid, :output, escape, code, content]`
+    #
+    # @param _escape [Boolean]
+    # @param code [String]
+    # @param content [Array]
+    # @return [Array
+    def on_liquid_output(_escape, code, content)
+      if code[BLOCK_RE]
+        [:multi,
+          [:code, code, compile(content)],
+          [:code, 'end']]
+      else
+        [:multi, [:dynamic, code], compile(content)]
+      end
+    end
+
+    # Handle text expression `[:liquid, :text, type, content]`
+    #
+    # @param _type [Symbol]
+    # @param content [Array]
+    # @return [Array]
+    def on_liquid_text(_type, content)
+      # Ensures :newline expressions from static output are still represented in
+      # the final expression
+      compile(content)
+    end
+  end
+end

data/lib/liquid_lint/filters/inject_line_numbers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module LiquidLint::Filters
+  # Traverses a Temple S-expression (that has already been converted to
+  # {LiquidLint::Sexp} instances) and annotates them with line numbers.
+  #
+  # This is a hack that allows us to access line information directly from the
+  # S-expressions, which makes a lot of other tasks easier.
+  class InjectLineNumbers < Temple::Filter
+    # {Sexp} representing a newline.
+    NEWLINE_SEXP = LiquidLint::Sexp.new([:newline])
+
+    # Annotates the given {LiquidLint::Sexp} with line number information.
+    #
+    # @param sexp [LiquidLint::Sexp]
+    # @return [LiquidLint::Sexp]
+    def call(sexp)
+      @line_number = 1
+      traverse(sexp)
+      sexp
+    end
+
+    private
+
+    # Traverses an {Sexp}, annotating it with line numbers.
+    #
+    # @param sexp [LiquidLint::Sexp]
+    def traverse(sexp)
+      sexp.line = @line_number
+
+      case sexp
+      when LiquidLint::Atom
+        @line_number += sexp.strip.count("\n") if sexp.respond_to?(:count)
+      when NEWLINE_SEXP
+        @line_number += 1
+      else
+        sexp.each do |nested_sexp|
+          traverse(nested_sexp)
+        end
+      end
+    end
+  end
+end

data/lib/liquid_lint/filters/sexp_converter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LiquidLint::Filters
+  # Converts a Temple S-expression comprised of {Array}s into {LiquidLint::Sexp}s.
+  #
+  # These {LiquidLint::Sexp}s include additional helpers that makes working with
+  # them more pleasant.
+  class SexpConverter < Temple::Filter
+    # Converts the given {Array} to a {LiquidLint::Sexp}.
+    #
+    # @param array_sexp [Array]
+    # @return [LiquidLint::Sexp]
+    def call(array_sexp)
+      LiquidLint::Sexp.new(array_sexp)
+    end
+  end
+end

data/lib/liquid_lint/filters/splat_processor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LiquidLint::Filters
+  # A dumbed-down version of {Liquid::Splat::Filter} which doesn't introduced
+  # temporary variables or other cruft.
+  class SplatProcessor < Liquid::Filter
+    # Handle liquid splat expressions `[:liquid, :splat, code]`
+    #
+    # @param code [String]
+    # @return [Array]
+    def on_liquid_splat(code)
+      [:code, code]
+    end
+  end
+end

data/lib/liquid_lint/lint.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Contains information about a problem or issue with a Liquid document.
+  class Lint
+    # @return [String] file path to which the lint applies
+    attr_reader :filename
+
+    # @return [String] line number of the file the lint corresponds to
+    attr_reader :line
+
+    # @return [LiquidLint::Linter] linter that reported the lint
+    attr_reader :linter
+
+    # @return [String] error/warning message to display to user
+    attr_reader :message
+
+    # @return [Symbol] whether this lint is a warning or an error
+    attr_reader :severity
+
+    # Creates a new lint.
+    #
+    # @param linter [LiquidLint::Linter]
+    # @param filename [String]
+    # @param line [Fixnum]
+    # @param message [String]
+    # @param severity [Symbol]
+    def initialize(linter, filename, line, message, severity = :warning)
+      @linter   = linter
+      @filename = filename
+      @line     = line || 0
+      @message  = message
+      @severity = severity
+    end
+
+    # Return whether this lint has a severity of error.
+    #
+    # @return [Boolean]
+    def error?
+      @severity == :error
+    end
+  end
+end

data/lib/liquid_lint/linter/comment_control_statement.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Searches for control statements with only comments.
+  class Linter::CommentControlStatement < Linter
+    include LinterRegistry
+
+    on [:liquid, :control] do |sexp|
+      _, _, code = sexp
+      next unless code[/\A\s*#/]
+
+      comment = code[/\A\s*#(.*\z)/, 1]
+
+      next if comment =~ /^\s*rubocop:\w+/
+      next if comment =~ /^\s*Template Dependency:/
+
+      report_lint(sexp,
+                  "Liquid code comments (`/#{comment}`) are preferred over " \
+                  "control statement comments (`-##{comment}`)")
+    end
+  end
+end

data/lib/liquid_lint/linter/consecutive_control_statements.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Searches for more than an allowed number of consecutive control code
+  # statements that could be condensed into a :ruby filter.
+  class Linter::ConsecutiveControlStatements < Linter
+    include LinterRegistry
+
+    on [:multi] do |sexp|
+      Utils.for_consecutive_items(sexp,
+                                  method(:flat_control_statement?),
+                                  config['max_consecutive'] + 1) do |group|
+        report_lint(group.first,
+                    "#{group.count} consecutive control statements can be " \
+                    'merged into a single `ruby:` filter')
+      end
+    end
+
+    private
+
+    def flat_control_statement?(sexp)
+      sexp.match?([:liquid, :control]) &&
+        sexp[3] == [:multi, [:newline]]
+    end
+  end
+end

data/lib/liquid_lint/linter/control_statement_spacing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Checks for missing or superfluous spacing before and after control statements.
+  class Linter::ControlStatementSpacing < Linter
+    include LinterRegistry
+
+    MESSAGE = 'Please add a space before and after the `=`'
+
+    on [:html, :tag, anything, [],
+         [:liquid, :output, anything, capture(:ruby, anything)]] do |sexp|
+      # Fetch original Liquid code that contains an element with a control statement.
+      line = document.source_lines[sexp.line - 1]
+
+      # Remove any Ruby code, because our regexp below must not match inside Ruby.
+      ruby = captures[:ruby]
+      line = line.sub(ruby, 'x')
+
+      next if line =~ /[^ ] ==?<?>? [^ ]/
+
+      report_lint(sexp, MESSAGE)
+    end
+  end
+end

data/lib/liquid_lint/linter/embedded_engines.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Checks for forbidden embedded engines.
+  class Linter::EmbeddedEngines < Linter
+    include LinterRegistry
+
+    MESSAGE = 'Forbidden embedded engine `%s` found'
+
+    on_start do |_sexp|
+      forbidden_engines = config['forbidden_engines']
+      dummy_node = Struct.new(:line)
+      document.source_lines.each_with_index do |line, index|
+        forbidden_engines.each do |forbidden_engine|
+          next unless line =~ /^#{forbidden_engine}.*:\s*$/
+
+          report_lint(dummy_node.new(index + 1), MESSAGE % forbidden_engine)
+        end
+      end
+    end
+  end
+end

data/lib/liquid_lint/linter/empty_control_statement.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Searches for control statements with no code.
+  class Linter::EmptyControlStatement < Linter
+    include LinterRegistry
+
+    on [:liquid, :control] do |sexp|
+      _, _, code = sexp
+      next unless code[/\A\s*\Z/]
+
+      report_lint(sexp, 'Empty control statement can be removed')
+    end
+  end
+end

data/lib/liquid_lint/linter/empty_lines.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # This linter checks for two or more consecutive blank lines
+  # and for the first blank line in file.
+  class Linter::EmptyLines < Linter
+    include LinterRegistry
+
+    on_start do |_sexp|
+      dummy_node = Struct.new(:line)
+
+      was_empty = true
+      document.source.lines.each_with_index do |line, i|
+        if line.blank?
+          if was_empty
+            report_lint(dummy_node.new(i + 1),
+                        'Extra empty line detected')
+          end
+          was_empty = true
+        else
+          was_empty = false
+        end
+      end
+    end
+  end
+end

data/lib/liquid_lint/linter/file_length.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Checks for file longer than a maximum number of lines.
+  class Linter::FileLength < Linter
+    include LinterRegistry
+
+    MSG = 'File is too long. [%d/%d]'
+
+    on_start do |_sexp|
+      max_length = config['max']
+      dummy_node = Struct.new(:line)
+
+      count = document.source_lines.size
+      if count > max_length
+        report_lint(dummy_node.new(1), format(MSG, count, max_length))
+      end
+    end
+  end
+end

data/lib/liquid_lint/linter/line_length.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Checks for lines longer than a maximum number of columns.
+  class Linter::LineLength < Linter
+    include LinterRegistry
+
+    MSG = 'Line is too long. [%d/%d]'
+
+    on_start do |_sexp|
+      max_length = config['max']
+      dummy_node = Struct.new(:line)
+
+      document.source_lines.each_with_index do |line, index|
+        next if line.length <= max_length
+
+        report_lint(dummy_node.new(index + 1), format(MSG, line.length, max_length))
+      end
+    end
+  end
+end

data/lib/liquid_lint/linter/redundant_div.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Checks for unnecessary uses of the `div` tag where a class name or ID
+  # already implies a div.
+  class Linter::RedundantDiv < Linter
+    include LinterRegistry
+
+    MESSAGE = '`div` is redundant when %s attribute shortcut is present'
+
+    on [:html, :tag, 'div',
+         [:html, :attrs,
+           [:html, :attr,
+             capture(:attr_name, anything),
+             [:static]]]] do |sexp|
+      attr = captures[:attr_name]
+      next unless %w[class id].include?(attr)
+
+      report_lint(sexp, MESSAGE % attr)
+    end
+  end
+end

data/lib/liquid_lint/linter/rubocop.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'liquid_lint/ruby_extractor'
+require 'liquid_lint/ruby_extract_engine'
+require 'rubocop'
+
+module LiquidLint
+  # Runs RuboCop on Ruby code extracted from Liquid templates.
+  class Linter::RuboCop < Linter
+    include LinterRegistry
+
+    on_start do |_sexp|
+      processed_sexp = LiquidLint::RubyExtractEngine.new.call(document.source)
+
+      extractor = LiquidLint::RubyExtractor.new
+      extracted_source = extractor.extract(processed_sexp)
+
+      next if extracted_source.source.empty?
+
+      find_lints(extracted_source.source, extracted_source.source_map)
+    end
+
+    private
+
+    # Executes RuboCop against the given Ruby code and records the offenses as
+    # lints.
+    #
+    # @param ruby [String] Ruby code
+    # @param source_map [Hash] map of Ruby code line numbers to original line
+    #   numbers in the template
+    def find_lints(ruby, source_map)
+      rubocop = ::RuboCop::CLI.new
+
+      filename = document.file ? "#{document.file}.rb" : 'ruby_script.rb'
+
+      with_ruby_from_stdin(ruby) do
+        extract_lints_from_offenses(lint_file(rubocop, filename), source_map)
+      end
+    end
+
+    # Defined so we can stub the results in tests
+    #
+    # @param rubocop [RuboCop::CLI]
+    # @param file [String]
+    # @return [Array<RuboCop::Cop::Offense>]
+    def lint_file(rubocop, file)
+      rubocop.run(rubocop_flags << file)
+      OffenseCollector.offenses
+    end
+
+    # Aggregates RuboCop offenses and converts them to {LiquidLint::Lint}s
+    # suitable for reporting.
+    #
+    # @param offenses [Array<RuboCop::Cop::Offense>]
+    # @param source_map [Hash]
+    def extract_lints_from_offenses(offenses, source_map)
+      offenses.select { |offense| !config['ignored_cops'].include?(offense.cop_name) }
+              .each do |offense|
+        @lints << Lint.new(self,
+                           document.file,
+                           source_map[offense.line],
+                           offense.message)
+      end
+    end
+
+    # Returns flags that will be passed to RuboCop CLI.
+    #
+    # @return [Array<String>]
+    def rubocop_flags
+      flags = %w[--format LiquidLint::OffenseCollector]
+      flags += ['--config', ENV['LIQUID_LINT_RUBOCOP_CONF']] if ENV['LIQUID_LINT_RUBOCOP_CONF']
+      flags += ['--stdin']
+      flags
+    end
+
+    # Overrides the global stdin to allow RuboCop to read Ruby code from it.
+    #
+    # @param ruby [String] the Ruby code to write to the overridden stdin
+    # @param _block [Block] the block to perform with the overridden stdin
+    # @return [void]
+    def with_ruby_from_stdin(ruby, &_block)
+      original_stdin = $stdin
+      stdin = StringIO.new
+      stdin.write(ruby)
+      stdin.rewind
+      $stdin = stdin
+      yield
+    ensure
+      $stdin = original_stdin
+    end
+  end
+
+  # Collects offenses detected by RuboCop.
+  class OffenseCollector < ::RuboCop::Formatter::BaseFormatter
+    class << self
+      # List of offenses reported by RuboCop.
+      attr_accessor :offenses
+    end
+
+    # Executed when RuboCop begins linting.
+    #
+    # @param _target_files [Array<String>]
+    def started(_target_files)
+      self.class.offenses = []
+    end
+
+    # Executed when a file has been scanned by RuboCop, adding the reported
+    # offenses to our collection.
+    #
+    # @param _file [String]
+    # @param offenses [Array<RuboCop::Cop::Offense>]
+    def file_finished(_file, offenses)
+      self.class.offenses += offenses
+    end
+  end
+end