theme-check 0.5.0 → 0.6.0

data/docs/checks/asset_size_css.md

@@ -0,0 +1,52 @@
+# Prevent Large CSS bundles (`AssetSizeCSS`)
+
+This rule exists to prevent large CSS bundles (for speed).
+
+## Check Details
+
+This rule disallows the use of too much CSS in themes, as configured by `threshold_in_bytes`.
+
+:-1: Examples of **incorrect** code for this check:
+```liquid
+<!-- Here, assets/theme.css is **greater** than `threshold_in_bytes` compressed. -->
+{{ 'theme.css' | asset_url | stylesheet_tag }}
+```
+
+:+1: Example of **correct** code for this check:
+```liquid
+<!-- Here, assets/theme.css is **less** than `threshold_in_bytes` compressed. -->
+{{ 'theme.css' | asset_url | stylesheet_tag }}
+```
+
+## Check Options
+
+The default configuration is the following.
+
+```yaml
+AssetSizeCSS:
+  enabled: false
+  threshold_in_bytes: 100_000
+```
+
+### `threshold_in_bytes`
+
+The `threshold_in_bytes` option (default: `100_000`) determines the maximum allowed compressed size in bytes that a single CSS file can take.
+
+This includes theme and remote stylesheets.
+
+## When Not To Use It
+
+This rule is safe to disable.
+
+## Version
+
+This check has been introduced in Theme Check 0.6.0.
+
+## Resources
+
+- [The Performance Inequality Gap](https://infrequently.org/2021/03/the-performance-inequality-gap/)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/asset_size_css.rb
+[docsource]: /docs/checks/asset_size_css.md

data/docs/checks/img_width_and_height.md

@@ -0,0 +1,79 @@
+# Width and height attributes on image tags (`ImgWidthAndHeight`)
+
+This check exists to prevent [cumulative layout shift][cls] (CLS) in themes.
+
+The absence of `width` and `height` attributes on an `img` tag prevents the browser from knowing the aspect ratio of the image before it is downloaded. Unless another technique is used to allocate space, the browser will consider the image to be of height 0 until it is loaded.
+
+This has numerous nefarious implications:
+
+1. [This causes layout shift as images start appearing one after the other.][codepenshift] Text starts flying down the page as the image pushes it down.
+2. [This breaks lazy loading.][codepenlazy] When all images have a height of 0px, every image is inside the viewport. And when everything is in the viewport, everything gets loaded. There's nothing lazy about it!
+
+The fix is easy. Make sure the `width` and `height` attribute are set on the `img` tag and that the CSS width of the image is set.
+
+Note: The width and height attributes of an image do not have  units.
+
+## Check Details
+
+This check is aimed at eliminating content layout shift in themes by enforcing the use of the `width` and `height` attributes on `img` tags.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<img alt="cat" src="cat.jpg">
+<img alt="cat" src="cat.jpg" width="100px" height="100px">
+<img alt="{{ image.alt }}" src="{{ image.src }}">
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<img alt="cat" src="cat.jpg" width="100" height="200">
+<img
+  alt="{{ image.alt }}"
+  src="{{ image.src }}"
+  width="{{ image.width }}"
+  height="{{ image.height }}"
+>
+```
+
+**NOTE:** The CSS `width` of the `img` should _also_ be set for the image to be responsive.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ImgWidthAndHeight:
+  enabled: true
+```
+
+## When Not To Use It
+
+There are some cases where you can avoid content-layout shift without needing the width and height attributes:
+
+- When the aspect-ratio of the displayed image should be independent of the uploaded image. In those cases, the solution is still the padding-top hack with an `overflow: hidden container`.
+- When you are happy with the padding-top hack.
+
+In those cases, it is fine to disable this check with the comment. 
+
+It is otherwise unwise to disable this check, since it would negatively impact the mobile search ranking of the merchants using your theme.
+
+## Version
+
+This check has been introduced in Theme Check 0.6.0.
+
+## Resources
+
+- [Cumulative Layout Shift Reference][cls]
+- [Codepen illustrating the impact of width and height on layout shift][codepenshift]
+- [Codepen illustrating the impact of width and height on lazy loading][codepenlazy]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[cls]: https://web.dev/cls/
+[codepenshift]: https://codepen.io/charlespwd/pen/YzpxPEp?editors=1100
+[codepenlazy]: https://codepen.io/charlespwd/pen/abZmqXJ?editors=0111
+[aspect-ratio]: https://caniuse.com/mdn-css_properties_aspect-ratio
+[codesource]: /lib/theme_check/checks/img_aspect_ratio.rb
+[docsource]: /docs/checks/img_aspect_ratio.md

data/docs/checks/parser_blocking_javascript.md

@@ -31,13 +31,13 @@ This check is aimed at eliminating parser-blocking JavaScript on themes.
 
 ```liquid
 <!-- Good. Using the asset_url filter + defer -->
-<script src="{{ 'theme.js' | asset_url }}" defer><script>
+<script src="{{ 'theme.js' | asset_url }}" defer></script>
 
 <!-- Also good. Using the asset_url filter + async -->
-<script src="{{ 'theme.js' | asset_url }}" async><script>
+<script src="{{ 'theme.js' | asset_url }}" async></script>
 
 <!-- Better than synchronous jQuery -->
-<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer><script>
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
 ...
 <button id="thing">Click me!</button>
 <script>

data/lib/theme_check/checks/asset_size_css.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+module ThemeCheck
+  class AssetSizeCSS < LiquidCheck
+    include RegexHelpers
+    severity :error
+    category :performance
+    doc docs_url(__FILE__)
+
+    Link = Struct.new(:href, :index)
+
+    LINK_TAG_HREF = %r{
+      <link
+        (?=[^>]+?rel=['"]?stylesheet['"]?)    # Make sure rel=stylesheet is in the link with lookahead
+        [^>]+                                 # any non closing tag character
+        href=                                 # href attribute start
+        (?<href>#{QUOTED_LIQUID_ATTRIBUTE})   # href attribute value (may contain liquid)
+        [^>]*                                 # any non closing character till the end
+      >
+    }omix
+    STYLESHEET_TAG = %r{
+      #{Liquid::VariableStart}          # VariableStart
+      (?:(?!#{Liquid::VariableEnd}).)*? # anything that isn't followed by a VariableEnd
+      \|\s*asset_url\s*                 # | asset_url
+      \|\s*stylesheet_tag\s*            # | stylesheet_tag
+      #{Liquid::VariableEnd}            # VariableEnd
+    }omix
+
+    attr_reader :threshold_in_bytes
+
+    def initialize(threshold_in_bytes: 100_000)
+      @threshold_in_bytes = threshold_in_bytes
+    end
+
+    def on_document(node)
+      @node = node
+      @source = node.template.source
+      record_offenses
+    end
+
+    def record_offenses
+      stylesheets(@source).each do |stylesheet|
+        file_size = href_to_file_size(stylesheet.href)
+        next if file_size.nil?
+        next if file_size <= threshold_in_bytes
+        add_offense(
+          "CSS on every page load exceding compressed size threshold (#{threshold_in_bytes} Bytes).",
+          node: @node,
+          markup: stylesheet.href,
+          line_number: @source[0...stylesheet.index].count("\n") + 1
+        )
+      end
+    end
+
+    def stylesheets(source)
+      stylesheet_links = matches(source, LINK_TAG_HREF)
+        .map do |m|
+          Link.new(
+            m[:href].gsub(START_OR_END_QUOTE, ""),
+            m.begin(:href),
+          )
+        end
+
+      stylesheet_tags = matches(source, STYLESHEET_TAG)
+        .map do |m|
+          Link.new(
+            m[0],
+            m.begin(0),
+          )
+        end
+
+      stylesheet_links + stylesheet_tags
+    end
+
+    def href_to_file_size(href)
+      # asset_url (+ optional stylesheet_tag) variables
+      if href =~ /^#{VARIABLE}$/o && href =~ /asset_url/ && href =~ Liquid::QuotedString
+        asset_id = Regexp.last_match(0).gsub(START_OR_END_QUOTE, "")
+        asset = @theme.assets.find { |a| a.name.ends_with?("/" + asset_id) }
+        return if asset.nil?
+        asset.gzipped_size
+
+      # remote URLs
+      elsif href =~ %r{^(https?:)?//}
+        asset = RemoteAssetFile.from_src(href)
+        asset.gzipped_size
+      end
+    end
+  end
+end

data/lib/theme_check/checks/asset_size_javascript.rb

@@ -11,17 +11,11 @@ module ThemeCheck
 
     Script = Struct.new(:src, :match)
 
-    TAG = /#{Liquid::TagStart}.*?#{Liquid::TagEnd}/om
-    VARIABLE = /#{Liquid::VariableStart}.*?#{Liquid::VariableEnd}/om
-    START_OR_END_QUOTE = /(^['"])|(['"]$)/
     SCRIPT_TAG_SRC = %r{
       <script
         [^>]+                              # any non closing tag character
         src=                               # src attribute start
-        (?<src>
-          '(?:#{TAG}|#{VARIABLE}|[^']+)*'| # any combination of tag/variable or non straight quote inside straight quotes
-          "(?:#{TAG}|#{VARIABLE}|[^"]+)*"  # any combination of tag/variable or non double quotes inside double quotes
-        )
+        (?<src>#{QUOTED_LIQUID_ATTRIBUTE}) # src attribute value (may contain liquid)
         [^>]*                              # any non closing character till the end
       >
     }omix

data/lib/theme_check/checks/img_width_and_height.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+module ThemeCheck
+  # Reports errors when trying to use parser-blocking script tags
+  class ImgWidthAndHeight < LiquidCheck
+    include RegexHelpers
+    severity :error
+    categories :liquid, :performance
+    doc docs_url(__FILE__)
+
+    # Not implemented with lookbehinds and lookaheads because performance was shit!
+    IMG_TAG = /<img#{HTML_ATTRIBUTES}>/oxim
+    SRC_ATTRIBUTE = /\s(src)=(#{QUOTED_LIQUID_ATTRIBUTE})/oxim
+    WIDTH_ATTRIBUTE = /\s(width)=(#{QUOTED_LIQUID_ATTRIBUTE})/oxim
+    HEIGHT_ATTRIBUTE = /\s(height)=(#{QUOTED_LIQUID_ATTRIBUTE})/oxim
+
+    FIELDS = [WIDTH_ATTRIBUTE, HEIGHT_ATTRIBUTE]
+    ENDS_IN_CSS_UNIT = /(cm|mm|in|px|pt|pc|em|ex|ch|rem|vw|vh|vmin|vmax|%)$/i
+
+    def on_document(node)
+      @source = node.template.source
+      @node = node
+      record_offenses
+    end
+
+    private
+
+    def record_offenses
+      matches(@source, IMG_TAG).each do |img_match|
+        next unless img_match[0] =~ SRC_ATTRIBUTE
+        record_missing_field_offenses(img_match)
+        record_units_in_field_offenses(img_match)
+      end
+    end
+
+    def record_missing_field_offenses(img_match)
+      width = WIDTH_ATTRIBUTE.match(img_match[0])
+      height = HEIGHT_ATTRIBUTE.match(img_match[0])
+      return if width.present? && height.present?
+      missing_width = width.nil?
+      missing_height = height.nil?
+      error_message = if missing_width && missing_height
+        "Missing width and height attributes"
+      elsif missing_width
+        "Missing width attribute"
+      elsif missing_height
+        "Missing height attribute"
+      end
+
+      add_offense(
+        error_message,
+        node: @node,
+        markup: img_match[0],
+        line_number: @source[0...img_match.begin(0)].count("\n") + 1
+      )
+    end
+
+    def record_units_in_field_offenses(img_match)
+      FIELDS.each do |field|
+        field_match = field.match(img_match[0])
+        next if field_match.nil?
+        value = field_match[2].gsub(START_OR_END_QUOTE, '')
+        next unless value =~ ENDS_IN_CSS_UNIT
+        value_without_units = value.gsub(ENDS_IN_CSS_UNIT, '')
+        start = img_match.begin(0) + field_match.begin(2)
+        add_offense(
+          "The #{field_match[1]} attribute does not take units. Replace with \"#{value_without_units}\".",
+          node: @node,
+          markup: value,
+          line_number: @source[0...start].count("\n") + 1
+        )
+      end
+    end
+  end
+end

data/lib/theme_check/checks/parser_blocking_javascript.rb

@@ -2,13 +2,14 @@
 module ThemeCheck
   # Reports errors when trying to use parser-blocking script tags
   class ParserBlockingJavaScript < LiquidCheck
+    include RegexHelpers
     severity :error
     categories :liquid, :performance
     doc docs_url(__FILE__)
 
     PARSER_BLOCKING_SCRIPT_TAG = %r{
       <script                                    # Find the start of a script tag
-      (?=(?:[^>]|\n|\r)+?src=)+?                 # Make sure src= is in the script with a lookahead
+      (?=[^>]+?src=)                             # Make sure src= is in the script with a lookahead
       (?:(?!defer|async|type=["']module['"]).)*? # Find tags that don't have defer|async|type="module"
       >
     }xim
@@ -33,23 +34,14 @@ module ThemeCheck
       )
     end
 
-    # The trickiness here is matching on scripts that are defined on
-    # multiple lines (or repeat matches). This makes the line_number
-    # calculation a bit weird. So instead, we traverse the string in
-    # a very imperative way.
     def record_offenses_from_regex(regex: nil, message: nil)
-      i = 0
-      while (i = @source.index(regex, i))
-        script = @source.match(regex, i)[0]
-
+      matches(@source, regex).each do |match|
         add_offense(
           message,
           node: @node,
-          markup: script,
-          line_number: @source[0...i].count("\n") + 1
+          markup: match[0],
+          line_number: @source[0...match.begin(0)].count("\n") + 1
         )
-
-        i += script.size
       end
     end
   end

data/lib/theme_check/checks/translation_key_exists.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 module ThemeCheck
+  module SystemTranslations
+    extend self
+
+    def translations
+      @translations ||= begin
+        # loaded as a Set because the include? lookup will be much faster.
+        YAML.load(File.read("#{__dir__}/../../../data/shopify_translation_keys.yml")).to_set
+      end
+    end
+
+    def include?(key)
+      translations.include?(key)
+    end
+  end
+
   class TranslationKeyExists < LiquidCheck
     severity :error
     category :translation
@@ -12,7 +27,7 @@ module ThemeCheck
       return unless (key_node = node.children.first)
       return unless key_node.value.is_a?(String)
 
-      unless key_exists?(key_node.value)
+      unless key_exists?(key_node.value) || SystemTranslations.include?(key_node.value)
         add_offense(
           "'#{key_node.value}' does not have a matching entry in '#{@theme.default_locale_json.relative_path}'",
           node: node,

data/lib/theme_check/cli.rb

@@ -7,13 +7,14 @@ module ThemeCheck
       Usage: theme-check [options] /path/to/your/theme
 
       Options:
-        -c, [--category]          # Only run this category of checks
-        -x, [--exclude-category]  # Exclude this category of checks
-        -l, [--list]              # List enabled checks
-        -a, [--auto-correct]      # Automatically fix offenses
-        --init                    # Generate a .theme-check.yml file in the current directory
-        -h, [--help]              # Show this. Hi!
-        -v, [--version]           # Print Theme Check version
+        --init                               Generate a .theme-check.yml file in the current directory
+        -C, --config <path>                  Use the config provided, overriding .theme-check.yml if present
+        -c, --category <category>            Only run this category of checks
+        -x, --exclude-category  <category>   Exclude this category of checks
+        -l, --list                           List enabled checks
+        -a, --auto-correct                   Automatically fix offenses
+        -h, --help                           Show this. Hi!
+        -v, --version                        Print Theme Check version
 
       Description:
         Theme Check helps you follow Shopify Themes & Liquid best practices by analyzing the
@@ -29,6 +30,7 @@ module ThemeCheck
       only_categories = []
       exclude_categories = []
       auto_correct = false
+      config_path = nil
 
       args = argv.dup
       while (arg = args.shift)
@@ -37,6 +39,8 @@ module ThemeCheck
           raise Abort, USAGE
         when "--version", "-v"
           command = :version
+        when "--config", "-C"
+          config_path = Pathname.new(args.shift)
         when "--category", "-c"
           only_categories << args.shift.to_sym
         when "--exclude-category", "-x"
@@ -53,7 +57,14 @@ module ThemeCheck
       end
 
       unless [:version, :init].include?(command)
-        @config = ThemeCheck::Config.from_path(@path)
+        @config = if config_path.present?
+          ThemeCheck::Config.new(
+            root: @path,
+            configuration: ThemeCheck::Config.load_file(config_path)
+          )
+        else
+          ThemeCheck::Config.from_path(@path)
+        end
         @config.only_categories = only_categories
         @config.exclude_categories = exclude_categories
         @config.auto_correct = auto_correct