liquid_lint 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc0be0f5e41c033324636c9048e17b98c742f85856ca55880aebf2b7fff1268a
+  data.tar.gz: 0b3daf13f2a25aa8acad78f8c44faeaf401045f60f71edd6f8f1da9b6e5dcc55
+SHA512:
+  metadata.gz: 21f74da0cfeed7899fe99fc8021152f46cd792293db7b2ffcad398531f681380a7517297191d3b6e801953715d5acb55fc3ec5c55fd3a6bb8588afbc14483bc9
+  data.tar.gz: 7029b2c2dd0cce358776e3b87c537a662ef729b492396d90aa97a415e65fe6ff203cbccacd640f2beeaee3b62ba9ec251f2a76c1d508c8b1031879a6d72263c0

data/LICENSE.md

@@ -0,0 +1 @@
+

data/bin/liquid-lint

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'liquid_lint/cli'
+
+logger = LiquidLint::Logger.new($stdout)
+exit LiquidLint::CLI.new(logger).run(ARGV)

data/config/default.yml

@@ -0,0 +1,99 @@
+# Default application configuration that all configurations inherit from.
+#
+# This is an opinionated list of which hooks are valuable to run and what their
+# out of the box settings should be.
+
+# Whether to ignore frontmatter at the beginning of Liquid documents for
+# frameworks such as Jekyll/Middleman
+skip_frontmatter: false
+
+linters:
+  CommentControlStatement:
+    enabled: true
+
+  ConsecutiveControlStatements:
+    enabled: true
+    max_consecutive: 2
+
+  ControlStatementSpacing:
+    enabled: true
+
+  EmbeddedEngines:
+    enabled: false
+    forbidden_engines: []
+
+  EmptyControlStatement:
+    enabled: true
+
+  EmptyLines:
+    enabled: true
+
+  FileLength:
+    enabled: false
+    max: 300
+
+  LineLength:
+    enabled: true
+    max: 80
+
+  RedundantDiv:
+    enabled: true
+
+  RuboCop:
+    enabled: true
+    # These cops are incredibly noisy since the Ruby we extract from Liquid
+    # templates isn't well-formatted, so we ignore them.
+    # WARNING: If you define this list in your own .liquid-lint.yml file, you'll
+    # be overriding the list defined here.
+    ignored_cops:
+      - Layout/ArgumentAlignment
+      - Layout/ArrayAlignment
+      - Layout/BlockAlignment
+      - Layout/ClosingParenthesisIndentation
+      - Layout/EmptyLineAfterGuardClause
+      - Layout/EndAlignment
+      - Layout/FirstArgumentIndentation
+      - Layout/FirstArrayElementIndentation
+      - Layout/FirstHashElementIndentation
+      - Layout/FirstParameterIndentation
+      - Layout/HashAlignment
+      - Layout/IndentationConsistency
+      - Layout/IndentationWidth
+      - Layout/InitialIndentation
+      - Layout/LineEndStringConcatenationIndentation
+      - Layout/LineLength
+      - Layout/MultilineArrayBraceLayout
+      - Layout/MultilineAssignmentLayout
+      - Layout/MultilineHashBraceLayout
+      - Layout/MultilineMethodCallBraceLayout
+      - Layout/MultilineMethodCallIndentation
+      - Layout/MultilineMethodDefinitionBraceLayout
+      - Layout/MultilineOperationIndentation
+      - Layout/ParameterAlignment
+      - Layout/TrailingEmptyLines
+      - Layout/TrailingWhitespace
+      - Lint/Void
+      - Metrics/BlockLength
+      - Metrics/BlockNesting
+      - Naming/FileName
+      - Style/FrozenStringLiteralComment
+      - Style/IdenticalConditionalBranches
+      - Style/IfUnlessModifier
+      - Style/Next
+      - Style/WhileUntilDo
+      - Style/WhileUntilModifier
+
+  Tab:
+    enabled: true
+
+  TagCase:
+    enabled: true
+
+  TrailingBlankLines:
+    enabled: true
+
+  TrailingWhitespace:
+    enabled: true
+
+  Zwsp:
+    enabled: false

data/lib/liquid_lint/atom.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Represents an atomic, childless, literal value within an S-expression.
+  #
+  # This creates a light wrapper around literal values of S-expressions so we
+  # can make an {Atom} quack like a {Sexp} without being an {Sexp}.
+  class Atom
+    # Stores the line number of the code in the original document that this Atom
+    # came from.
+    attr_accessor :line
+
+    # Creates an atom from the specified value.
+    #
+    # @param value [Object]
+    def initialize(value)
+      @value = value
+    end
+
+    # Returns whether this atom is equivalent to another object.
+    #
+    # This defines a helper which unwraps the inner value of the atom to compare
+    # against a literal value, saving us having to do it ourselves everywhere
+    # else.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      @value == (other.is_a?(Atom) ? other.instance_variable_get(:@value) : other)
+    end
+
+    # Returns whether this atom matches the given Sexp pattern.
+    #
+    # This exists solely to make an {Atom} quack like a {Sexp}, so we don't have
+    # to manually check the type when doing comparisons elsewhere.
+    #
+    # @param [Array, Object]
+    # @return [Boolean]
+    def match?(pattern)
+      # Delegate matching logic if we're comparing against a matcher
+      if pattern.is_a?(LiquidLint::Matcher::Base)
+        return pattern.match?(@value)
+      end
+
+      @value == pattern
+    end
+
+    # Displays the string representation the value this {Atom} wraps.
+    #
+    # @return [String]
+    def to_s
+      @value.to_s
+    end
+
+    # Displays a string representation of this {Atom} suitable for debugging.
+    #
+    # @return [String]
+    def inspect
+      "<#Atom #{@value.inspect}>"
+    end
+
+    # Redirect methods to the value this {Atom} wraps.
+    #
+    # Again, this is for convenience so we don't need to manually unwrap the
+    # value ourselves. It's pretty magical, but results in much DRYer code.
+    #
+    # @param method_sym [Symbol] method that was called
+    # @param args [Array]
+    # @yield block that was passed to the method
+    def method_missing(method_sym, *args, &block)
+      if @value.respond_to?(method_sym)
+        @value.send(method_sym, *args, &block)
+      else
+        super
+      end
+    end
+
+    # @param method_name [String,Symbol] method name
+    # @param args [Array]
+    def respond_to_missing?(method_name, *args)
+      @value.__send__(:respond_to_missing?, method_name, *args) || super
+    end
+
+    # Return whether this {Atom} or the value it wraps responds to the given
+    # message.
+    #
+    # @param method_sym [Symbol]
+    # @param include_private [Boolean]
+    # @return [Boolean]
+    def respond_to?(method_sym, include_private = false)
+      if super
+        true
+      else
+        @value.respond_to?(method_sym, include_private)
+      end
+    end
+  end
+end

data/lib/liquid_lint/capture_map.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Holds the list of captures, providing a convenient interface for accessing
+  # the values and unwrapping them on your behalf.
+  class CaptureMap < Hash
+    # Returns the captured value with the specified name.
+    #
+    # @param capture_name [Symbol]
+    # @return [Object]
+    def [](capture_name)
+      if key?(capture_name)
+        super.value
+      else
+        raise ArgumentError, "Capture #{capture_name.inspect} does not exist!"
+      end
+    end
+  end
+end

data/lib/liquid_lint/cli.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'liquid_lint'
+require 'liquid_lint/options'
+
+module LiquidLint
+  # Command line application interface.
+  class CLI # rubocop:disable Metrics/ClassLength
+    # Exit codes
+    # @see https://man.openbsd.org/sysexits.3
+    EX_OK = 0
+    EX_USAGE = 64
+    EX_DATAERR = 65
+    EX_NOINPUT = 67
+    EX_SOFTWARE = 70
+    EX_CONFIG = 78
+
+    # Create a CLI that outputs to the specified logger.
+    #
+    # @param logger [LiquidLint::Logger]
+    def initialize(logger)
+      @log = logger
+    end
+
+    # Parses the given command-line arguments and executes appropriate logic
+    # based on those arguments.
+    #
+    # @param args [Array<String>] command line arguments
+    # @return [Integer] exit status code
+    def run(args)
+      options = LiquidLint::Options.new.parse(args)
+      act_on_options(options)
+    rescue StandardError => e
+      handle_exception(e)
+    end
+
+    private
+
+    attr_reader :log
+
+    # Given the provided options, execute the appropriate command.
+    #
+    # @return [Integer] exit status code
+    def act_on_options(options)
+      log.color_enabled = options.fetch(:color, log.tty?)
+
+      if options[:help]
+        print_help(options)
+        EX_OK
+      elsif options[:version] || options[:verbose_version]
+        print_version(options)
+        EX_OK
+      elsif options[:show_linters]
+        print_available_linters
+        EX_OK
+      elsif options[:show_reporters]
+        print_available_reporters
+        EX_OK
+      else
+        scan_for_lints(options)
+      end
+    end
+
+    # Outputs a message and returns an appropriate error code for the specified
+    # exception.
+    def handle_exception(exception)
+      case exception
+      when LiquidLint::Exceptions::ConfigurationError
+        log.error exception.message
+        EX_CONFIG
+      when LiquidLint::Exceptions::InvalidCLIOption
+        log.error exception.message
+        log.log "Run `#{APP_NAME}` --help for usage documentation"
+        EX_USAGE
+      when LiquidLint::Exceptions::InvalidFilePath
+        log.error exception.message
+        EX_NOINPUT
+      when LiquidLint::Exceptions::NoLintersError
+        log.error exception.message
+        EX_NOINPUT
+      else
+        print_unexpected_exception(exception)
+        EX_SOFTWARE
+      end
+    end
+
+    # Scans the files specified by the given options for lints.
+    #
+    # @return [Integer] exit status code
+    def scan_for_lints(options)
+      report = Runner.new.run(options)
+      print_report(report, options)
+      report.failed? ? EX_DATAERR : EX_OK
+    end
+
+    # Outputs a report of the linter run using the specified reporter.
+    def print_report(report, options)
+      reporter = options.fetch(:reporter,
+                               LiquidLint::Reporter::DefaultReporter).new(log)
+      reporter.display_report(report)
+    end
+
+    # Outputs a list of all currently available linters.
+    def print_available_linters
+      log.info 'Available linters:'
+
+      linter_names = LiquidLint::LinterRegistry.linters.map do |linter|
+        linter.name.split('::').last
+      end
+
+      linter_names.sort.each do |linter_name|
+        log.log " - #{linter_name}"
+      end
+    end
+
+    # Outputs a list of currently available reporters.
+    def print_available_reporters
+      log.info 'Available reporters:'
+
+      reporter_names = LiquidLint::Reporter.descendants.map do |reporter|
+        reporter.name.split('::').last.sub(/Reporter$/, '').downcase
+      end
+
+      reporter_names.sort.each do |reporter_name|
+        log.log " - #{reporter_name}"
+      end
+    end
+
+    # Outputs help documentation.
+    def print_help(options)
+      log.log options[:help]
+    end
+
+    # Outputs the application name and version.
+    def print_version(options)
+      log.log "#{LiquidLint::APP_NAME} #{LiquidLint::VERSION}"
+
+      if options[:verbose_version]
+        log.log "liquid #{Gem.loaded_specs['liquid'].version}"
+        log.log "rubocop #{Gem.loaded_specs['rubocop'].version}"
+        log.log RUBY_DESCRIPTION
+      end
+    end
+
+    # Outputs the backtrace of an exception with instructions on how to report
+    # the issue.
+    def print_unexpected_exception(exception) # rubocop:disable Metrics/AbcSize
+      log.bold_error exception.message
+      log.error exception.backtrace.join("\n")
+      log.warning 'Report this bug at ', false
+      log.info LiquidLint::BUG_REPORT_URL
+      log.newline
+      log.success 'To help fix this issue, please include:'
+      log.log '- The above stack trace'
+      log.log '- Liquid-Lint version: ', false
+      log.info LiquidLint::VERSION
+      log.log '- RuboCop version: ', false
+      log.info Gem.loaded_specs['rubocop'].version
+      log.log '- Ruby version: ', false
+      log.info RUBY_VERSION
+    end
+  end
+end

data/lib/liquid_lint/configuration.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Stores runtime configuration for the application.
+  #
+  # The purpose of this class is to validate and ensure all configurations
+  # satisfy some basic pre-conditions so other parts of the application don't
+  # have to check the configuration for errors. It should have no knowledge of
+  # how these configuration values are ultimately used.
+  class Configuration
+    # Internal hash storing the configuration.
+    attr_reader :hash
+
+    # Creates a configuration from the given options hash.
+    #
+    # @param options [Hash]
+    def initialize(options)
+      @hash = options
+      validate
+    end
+
+    # Access the configuration as if it were a hash.
+    #
+    # @param key [String]
+    # @return [Array,Hash,Number,String]
+    def [](key)
+      @hash[key]
+    end
+
+    # Compares this configuration with another.
+    #
+    # @param other [LiquidLint::Configuration]
+    # @return [true,false] whether the given configuration is equivalent
+    def ==(other)
+      super || @hash == other.hash
+    end
+
+    # Returns a non-modifiable configuration for the specified linter.
+    #
+    # @param linter [LiquidLint::Linter,Class]
+    def for_linter(linter)
+      linter_name =
+        case linter
+        when Class
+          linter.name.split('::').last
+        when LiquidLint::Linter
+          linter.name
+        end
+
+      @hash['linters'].fetch(linter_name, {}).dup.freeze
+    end
+
+    # Merges the given configuration with this one, returning a new
+    # {Configuration}. The provided configuration will either add to or replace
+    # any options defined in this configuration.
+    #
+    # @param config [LiquidLint::Configuration]
+    def merge(config)
+      self.class.new(smart_merge(@hash, config.hash))
+    end
+
+    private
+
+    # Merge two hashes such that nested hashes are merged rather than replaced.
+    #
+    # @param parent [Hash]
+    # @param child [Hash]
+    # @return [Hash]
+    def smart_merge(parent, child)
+      parent.merge(child) do |_key, old, new|
+        case old
+        when Hash
+          smart_merge(old, new)
+        else
+          new
+        end
+      end
+    end
+
+    # Validates the configuration for any invalid options, normalizing it where
+    # possible.
+    def validate
+      ensure_exclude_option_array_exists
+      ensure_linter_section_exists
+      ensure_linter_include_exclude_arrays_exist
+    end
+
+    # Ensures the `exclude` global option is an array.
+    def ensure_exclude_option_array_exists
+      @hash['exclude'] = Array(@hash['exclude'])
+    end
+
+    # Ensures the `linters` configuration section exists.
+    def ensure_linter_section_exists
+      @hash['linters'] ||= {}
+    end
+
+    # Ensure `include` and `exclude` options for linters are arrays
+    # (since users can specify a single string glob pattern for convenience)
+    def ensure_linter_include_exclude_arrays_exist
+      @hash['linters'].each_key do |linter_name|
+        %w[include exclude].each do |option|
+          linter_config = @hash['linters'][linter_name]
+          linter_config[option] = Array(linter_config[option])
+        end
+      end
+    end
+  end
+end

data/lib/liquid_lint/configuration_loader.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'yaml'
+
+module LiquidLint
+  # Manages configuration file loading.
+  class ConfigurationLoader
+    DEFAULT_CONFIG_PATH = File.join(LiquidLint::HOME, 'config', 'default.yml').freeze
+    CONFIG_FILE_NAME = '.liquid-lint.yml'
+
+    class << self
+      # Load configuration file given the current working directory the
+      # application is running within.
+      def load_applicable_config
+        directory = File.expand_path(Dir.pwd)
+        config_file = possible_config_files(directory).find(&:file?)
+
+        if config_file
+          load_file(config_file.to_path)
+        else
+          default_configuration
+        end
+      end
+
+      # Loads the built-in default configuration.
+      def default_configuration
+        @default_configuration ||= load_from_file(DEFAULT_CONFIG_PATH)
+      end
+
+      # Loads a configuration, ensuring it extends the default configuration.
+      #
+      # @param file [String]
+      # @return [LiquidLint::Configuration]
+      def load_file(file)
+        config = load_from_file(file)
+
+        default_configuration.merge(config)
+      rescue Psych::SyntaxError, Errno::ENOENT => e
+        raise LiquidLint::Exceptions::ConfigurationError,
+              "Unable to load configuration from '#{file}': #{e}",
+              e.backtrace
+      end
+
+      # Creates a configuration from the specified hash, ensuring it extends the
+      # default configuration.
+      #
+      # @param hash [Hash]
+      # @return [LiquidLint::Configuration]
+      def load_hash(hash)
+        config = LiquidLint::Configuration.new(hash)
+
+        default_configuration.merge(config)
+      end
+
+      private
+
+      # Parses and loads a configuration from the given file.
+      #
+      # @param file [String]
+      # @return [LiquidLint::Configuration]
+      def load_from_file(file)
+        hash =
+          if yaml = YAML.load_file(file)
+            yaml.to_hash
+          else
+            {}
+          end
+
+        LiquidLint::Configuration.new(hash)
+      end
+
+      # Returns a list of possible configuration files given the context of the
+      # specified directory.
+      #
+      # @param directory [String]
+      # @return [Array<Pathname>]
+      def possible_config_files(directory)
+        files = Pathname.new(directory)
+                        .enum_for(:ascend)
+                        .map { |path| path + CONFIG_FILE_NAME }
+        files << Pathname.new(CONFIG_FILE_NAME)
+      end
+    end
+  end
+end

data/lib/liquid_lint/constants.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Global application constants.
+module LiquidLint
+  HOME = File.expand_path(File.join(File.dirname(__FILE__), '..', '..')).freeze
+  APP_NAME = 'liquid-lint'
+
+  REPO_URL = 'https://github.com/zeusintuivo/liquid-lint'
+  BUG_REPORT_URL = "#{REPO_URL}/issues"
+end

data/lib/liquid_lint/document.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LiquidLint
+  # Represents a parsed Liquid document and its associated metadata.
+  class Document
+    # @return [LiquidLint::Configuration] Configuration used to parse template
+    attr_reader :config
+
+    # @return [String] Liquid template file path
+    attr_reader :file
+
+    # @return [LiquidLint::Sexp] Sexpression representing the parsed document
+    attr_reader :sexp
+
+    # @return [String] original source code
+    attr_reader :source
+
+    # @return [Array<String>] original source code as an array of lines
+    attr_reader :source_lines
+
+    # Parses the specified Liquid code into a {Document}.
+    #
+    # @param source [String] Liquid code to parse
+    # @param options [Hash]
+    # @option options :file [String] file name of document that was parsed
+    # @raise [Liquid::Parser::Error] if there was a problem parsing the document
+    def initialize(source, options)
+      @config = options[:config]
+      @file = options.fetch(:file, nil)
+
+      process_source(source)
+    end
+
+    private
+
+    # @param source [String] Liquid code to parse
+    # @raise [LiquidLint::Exceptions::ParseError] if there was a problem parsing the document
+    def process_source(source)
+      @source = process_encoding(source)
+      @source = strip_frontmatter(source)
+      @source_lines = @source.split("\n")
+
+      engine = LiquidLint::Engine.new(file: @file)
+      @sexp = engine.parse(@source)
+    end
+
+    # Ensure the string's encoding is valid.
+    #
+    # @param source [String]
+    # @return [String] source encoded in a valid encoding
+    def process_encoding(source)
+      ::Temple::Filters::Encoding.new.call(source)
+    end
+
+    # Removes YAML frontmatter
+    def strip_frontmatter(source)
+      if config['skip_frontmatter'] &&
+        source =~ /
+          # From the start of the string
+          \A
+          # First-capture match --- followed by optional whitespace up
+          # to a newline then 0 or more chars followed by an optional newline.
+          # This matches the --- and the contents of the frontmatter
+          (---\s*\n.*?\n?)
+          # From the start of the line
+          ^
+          # Second capture match --- or ... followed by optional whitespace
+          # and newline. This matches the closing --- for the frontmatter.
+          (---|\.\.\.)\s*$\n?/mx
+        source = ::Regexp.last_match.post_match
+      end
+
+      source
+    end
+  end
+end