theme-check 0.8.2 → 0.10.1

data/docs/api/json_check.md

@@ -0,0 +1,19 @@
+# JSON check API
+
+For checking the content of `.json` files.
+
+```ruby
+module ThemeCheck
+  class MyCheckName < JsonCheck
+    category :json,
+    # A check can belong to multiple categories. Valid ones:
+    categories :translation, :performance
+    severity :suggestion # :error or :style
+
+    def on_file(file)
+      file # an instance of `ThemeCheck::JsonFile`
+      file.content # the parsed JSON, as a Ruby object, usually a Hash
+    end
+  end
+end
+```

data/docs/api/liquid_check.md

@@ -0,0 +1,99 @@
+# Liquid check API
+
+For checking the Liquid code in `.liquid` files.
+
+All code inside `{% ... %}` or `{{ ... }}` is Liquid code.
+
+Liquid files are parsed using the Liquid parser, by consequence you will get Liquid nodes (tags, blocks) in your callback methods. Check the Liquid source for details on those nodes: [Liquid source][liquidsource].
+
+
+```ruby
+module ThemeCheck
+  class MyCheckName < LiquidCheck
+    category :liquid,
+    # A check can belong to multiple categories. Valid ones:
+    categories :translation, :performance
+    severity :suggestion # :error or :style
+
+    def on_document(node)
+      # Called with the root node of all templates
+      node.value    # is the original Liquid object for this node. See Liquid source code for details.
+      node.template # is the template being analyzed, See lib/theme_check/template.rb.
+      node.parent   # is the parent node.
+      node.children # are the children nodes.
+      # See lib/theme_check/node.rb for more helper methods
+      theme # Gives you access to all the templates in the theme. See lib/theme_check/theme.rb.
+    end
+
+    def on_node(node)
+      # Called for every node
+    end
+
+    def on_tag(node)
+      # Called for each tag (if, include, for, assign, etc.)
+    end
+
+    def after_tag(node)
+      # Called after the tag children have been visited
+      
+      # If you find an issue, add an offense:
+      add_offense("Describe the problem...", node: node)
+      # Or, if the offense is related to the whole template:
+      add_offense("Describe the problem...", template: node.template)
+    end
+
+    def on_assign(node)
+      # Called only for {% assign ... %} tags
+    end
+
+    def on_string(node)
+      # Called for every `String` (including inside if conditions).
+      if node.parent.block?
+        # If parent is a block, `node.value` is a String written directly to the output when
+        # the template is rendered.
+      end
+    end
+
+    def on_variable(node)
+      # Called for each {{ ... }}
+    end
+
+    def on_error(exception)
+      # Called each time a Liquid exception is raised while parsing the template
+    end
+
+    def on_end
+      # A special callback after we're done visiting all the files of the theme
+    end
+
+    # Each type of node has a corresponding `on_node_class_name` & `after_node_class_name`
+    # A few common examples:
+    # on_capture(node)
+    # on_case(node)
+    # on_comment(node)
+    # on_if(node)
+    # on_condition(node)
+    # on_else_condition(node)
+    # on_for(node)
+    # on_form(node)
+    # on_include(node)
+    # on_integer(node)
+    # on_layout(node)
+    # on_method_literal(node)
+    # on_paginate(node)
+    # on_range(node)
+    # on_render(node)
+    # on_schema(node)
+    # on_section(node)
+    # on_style(node)
+    # on_unless(node)
+    # on_variable_lookup(node)
+  end
+end
+```
+
+## Resources
+
+- [Liquid source][liquidsource]
+
+[liquidsource]: https://github.com/Shopify/liquid/tree/master/lib/liquid

data/docs/checks/{CHECK_DOCS_TEMPLATE.md → TEMPLATE.md.erb}

@@ -1,4 +1,4 @@
-# Check Title (`CheckClassName`)
+# Check Title (`<%= class_name %>`)
 
 A brief paragraph explaining why the check exists.
 
@@ -21,7 +21,7 @@ This check is aimed at eliminating ...
 The default configuration for this check is the following:
 
 ```yaml
-CheckClassName:
+<%= class_name %>:
   enabled: true
   some_option: 10
 ```
@@ -36,12 +36,12 @@ If you don't want to ..., then it's safe to disable this rule.
 
 ## Version
 
-This check has been introduced in Theme Check X.X.X.
+This check has been introduced in Theme Check THEME_CHECK_VERSION.
 
 ## Resources
 
 - [Rule Source][codesource]
 - [Documentation Source][docsource]
 
-[codesource]: /lib/theme_check/checks/check_class_name.rb
-[docsource]: /docs/checks/check_class_name.md
+[codesource]: /<%= code_source %>
+[docsource]: /<%= doc_source %>

data/docs/checks/asset_url_filters.md

@@ -0,0 +1,56 @@
+# Ensure `asset_url` filters are used when serving assets (`AssetUrlFilters`)
+
+See the [`RemoteAsset` check documentation][remote_asset] for a detailed explanation on why remote assets are discouraged.
+
+## Check Details
+
+This check is aimed at eliminating unnecessary HTTP connections.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- Using multiple CDNs -->
+{{ "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" | stylesheet_tag }}
+
+<!-- Missing img_url filter -->
+{{ url | img_tag }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{{ 'bootstrap.min.css' | asset_url | stylesheet_tag }}
+
+<!-- Images -->
+{{ url | img_url | img_tag }}
+```
+
+Use the [`assets_url`](asset_url) or [`img_url`](img_url) filter to load the files in your theme's `assets/` folder from the Shopify CDN.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+AssetUrlFilters:
+  enabled: true
+```
+
+## When Not To Use It
+
+When the remote content is highly dynamic.
+
+## Version
+
+This check has been introduced in Theme Check 0.9.1.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/remote_asset_filters.rb
+[docsource]: /docs/checks/remote_asset_filters.md
+[remote_asset]: /docs/checks/remote_asset.md
+[asset_url]: https://shopify.dev/docs/themes/liquid/reference/filters/url-filters#assert_url
+[img_url]: https://shopify.dev/docs/themes/liquid/reference/filters/url-filters#img_url

data/docs/checks/content_for_header_modification.md

@@ -0,0 +1,42 @@
+# Do not depend on the content of `content_for_header` (`ContentForHeaderModification`)
+
+Do not rely on the content of `content_for_header` as it might change in the future, which could cause your Liquid code behavior to change.
+
+## Check Details
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% assign parts = content_for_header | split: ',' %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+The only acceptable usage of `content_for_header` is:
+
+```liquid
+{{ content_for_header }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ContentForHeaderModification:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.9.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+- [`theme.liquid` template considerations][considerations]
+
+[codesource]: /lib/theme_check/checks/check_class_name.rb
+[docsource]: /docs/checks/check_class_name.md
+[considerations]: https://shopify.dev/docs/themes/theme-templates/theme-liquid#template-considerations

data/docs/checks/img_lazy_loading.md

@@ -0,0 +1,61 @@
+# Lazy loading image tags (`ImgLazyLoading`)
+
+Lazy loading is a strategy to identify resources as non-blocking (non-critical) and load these only when needed. It's a way to shorten the length of the critical rendering path, which translates into reduced page load times.
+
+Lazy loading can occur on different moments in the application, but it typically happens on some user interactions such as scrolling and navigation.
+
+Very often, webpages contain many images that contribute to data-usage and how fast a page can load. Most of those images are off-screen (non-critical), requiring user interaction (an example being scroll) in order to view them.
+
+_Quoted from [MDN - Lazy loading][mdn]_
+
+## Check Details
+
+This check is aimed at defering loading non-critical images.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<img src="a.jpg">
+
+<!-- Replaces lazysize.js -->
+<img src="a.jpg" class="lazyload">
+
+<!-- `auto` is deprecated -->
+<img src="a.jpg" loading="auto">
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<img src="a.jpg" loading="lazy">
+
+<!-- `eager` is also accepted, but prefer `lazy` -->
+<img src="a.jpg" loading="eager">
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ImgLazyLoading:
+  enabled: true
+```
+
+## When Not To Use It
+
+If you don't want to defer loading of images, then it's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.10.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+- [MDN - Lazy loading][mdn]
+
+[codesource]: /lib/theme_check/checks/img_lazy_loading.rb
+[docsource]: /docs/checks/img_lazy_loading.md
+[mdn]: https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading

data/docs/checks/parser_blocking_script_tag.md

@@ -0,0 +1,53 @@
+# Discourage use of parser-blocking `script_tag` filter (`ParserBlockingScriptTag`)
+
+The `script_tag` filter emits a parser-blocking script tag.
+
+See the [ParserBlockingJavaScript check documentation][parser_blocking_javascript] for why this is generally discouraged.
+
+## Check Details
+
+This check is aimed at eliminating parser-blocking JavaScript on themes.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- The script_tag filter outputs a parser-blocking script -->
+{{ 'app-code.js' | asset_url | script_tag }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<!-- Good. Using the asset_url filter + defer -->
+<script src="{{ 'theme.js' | asset_url }}" defer></script>
+
+<!-- Also good. Using the asset_url filter + async -->
+<script src="{{ 'theme.js' | asset_url }}" async></script>
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ParserBlockingScriptTag:
+  enabled: true
+```
+
+## When Not To Use It
+
+This should only be turned off with the `theme-check-disable` comment when there's no better way to accomplish what you're doing than with a parser-blocking script.
+
+It is discouraged to turn this rule off.
+
+## Version
+
+This check has been introduced in Theme Check 0.9.0.
+
+## Resources
+
+- [ParserBlockingJavaScript check][parser_blocking_javascript]
+- [Documentation Source][docsource]
+
+[parser_blocking_javascript]: /docs/checks/parser_blocking_javascript.md
+[docsource]: /docs/checks/parser_blocking_script_tag.md

data/exe/theme-check-language-server

@@ -6,7 +6,6 @@ require 'theme_check'
 if ENV["THEME_CHECK_DEBUG"] == "true"
   $DEBUG = true
 end
-# Force encoding to UTF-8 to fix VSCode
-Encoding.default_external = Encoding::UTF_8
+
 status_code = ThemeCheck::LanguageServer.start
 exit! status_code

data/lib/theme_check.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require "liquid"
 
+require_relative "theme_check/version"
 require_relative "theme_check/bug"
 require_relative "theme_check/exceptions"
 require_relative "theme_check/analyzer"
@@ -35,6 +36,12 @@ require_relative "theme_check/template"
 require_relative "theme_check/theme"
 require_relative "theme_check/visitor"
 require_relative "theme_check/corrector"
-require_relative "theme_check/version"
+require_relative "theme_check/html_node"
+require_relative "theme_check/html_visitor"
+require_relative "theme_check/html_check"
 
 Dir[__dir__ + "/theme_check/checks/*.rb"].each { |file| require file }
+
+# UTF-8 is the default internal and external encoding, like in Rails & Shopify.
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8

data/lib/theme_check/analyzer.rb

@@ -7,6 +7,7 @@ module ThemeCheck
 
       @liquid_checks = Checks.new
       @json_checks = Checks.new
+      @html_checks = Checks.new
 
       checks.each do |check|
         check.theme = @theme
@@ -16,33 +17,58 @@ module ThemeCheck
           @liquid_checks << check
         when JsonCheck
           @json_checks << check
+        when HtmlCheck
+          @html_checks << check
         end
       end
-
-      @visitor = Visitor.new(@liquid_checks)
     end
 
     def offenses
-      @liquid_checks.flat_map(&:offenses) + @json_checks.flat_map(&:offenses)
+      @liquid_checks.flat_map(&:offenses) +
+        @json_checks.flat_map(&:offenses) +
+        @html_checks.flat_map(&:offenses)
     end
 
-    def offenses_clear!
-      @liquid_checks.each do |check|
-        check.offenses.clear
-      end
+    def analyze_theme
+      reset
 
-      @json_checks.each do |check|
-        check.offenses.clear
+      liquid_visitor = Visitor.new(@liquid_checks, @disabled_checks)
+      html_visitor = HtmlVisitor.new(@html_checks)
+      @theme.liquid.each do |template|
+        liquid_visitor.visit_template(template)
+        html_visitor.visit_template(template)
       end
-    end
 
-    def analyze_theme
-      offenses_clear!
-      @theme.liquid.each { |template| @visitor.visit_template(template) }
       @theme.json.each { |json_file| @json_checks.call(:on_file, json_file) }
-      @liquid_checks.call(:on_end)
-      @json_checks.call(:on_end)
-      offenses
+
+      finish
+    end
+
+    def analyze_files(files)
+      reset
+
+      # Call all checks that run on the whole theme
+      liquid_visitor = Visitor.new(@liquid_checks.whole_theme, @disabled_checks)
+      html_visitor = HtmlVisitor.new(@html_checks.whole_theme)
+      @theme.liquid.each do |template|
+        liquid_visitor.visit_template(template)
+        html_visitor.visit_template(template)
+      end
+      @theme.json.each { |json_file| @json_checks.whole_theme.call(:on_file, json_file) }
+
+      # Call checks that run on a single files, only on specified file
+      liquid_visitor = Visitor.new(@liquid_checks.single_file, @disabled_checks)
+      html_visitor = HtmlVisitor.new(@html_checks.single_file)
+      files.each do |file|
+        if file.liquid?
+          liquid_visitor.visit_template(file)
+          html_visitor.visit_template(file)
+        elsif file.json?
+          @json_checks.single_file.call(:on_file, file)
+        end
+      end
+
+      finish
     end
 
     def uncorrectable_offenses
@@ -59,5 +85,35 @@ module ThemeCheck
         @theme.liquid.each(&:write)
       end
     end
+
+    private
+
+    def reset
+      @disabled_checks = DisabledChecks.new
+
+      @liquid_checks.each do |check|
+        check.offenses.clear
+      end
+
+      @html_checks.each do |check|
+        check.offenses.clear
+      end
+
+      @json_checks.each do |check|
+        check.offenses.clear
+      end
+    end
+
+    def finish
+      @liquid_checks.call(:on_end)
+      @html_checks.call(:on_end)
+      @json_checks.call(:on_end)
+
+      @disabled_checks.remove_disabled_offenses(@liquid_checks)
+      @disabled_checks.remove_disabled_offenses(@json_checks)
+      @disabled_checks.remove_disabled_offenses(@html_checks)
+
+      offenses
+    end
   end
 end