theme-check 0.5.0 → 0.7.3

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/docs/checks/remote_asset.md

@@ -0,0 +1,82 @@
+# Discourage use of third party domains for hosting assets (`RemoteAsset`)
+
+Years ago, loading jQuery from a common CDN was good for performance because the browser cache could be reused across website. This is no longer true because browsers now include the domain from which the request was made in the cache key.
+
+Therefore, this technique now makes things worse. Here's why:
+
+* **The benefits of HTTP/2 prioritization are lost.** HTTP/2 prioritization is a mechanism used by servers. If different servers are used to deliver assets, there's no way to prioritize.
+* **A new connection dance (DNS, TCP, TLS) must be done to start downloading the resource.** With HTTPS, this takes 5 round trips to achieve. The farther away the buyer is from that domain, the longer it takes.
+* **The [slow start][slowstart] part of the Internet's TCP congestion control strategy must happen on every connection.** This means that the download "acceleration" we commonly observe must be repeated many times over.
+
+The fix? Deliver as much as you can from a small number of connections. In a Shopify context, this is done by leveraging the `assets/` folder and the [URL filters][url_filters].
+
+## Check Details
+
+This check is aimed at eliminating unnecessary HTTP connections.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- Using multiple CDNs -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js" defer></script>
+{{ "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" | stylesheet_tag }}
+<img src="https://example.com/heart.png" ...>
+
+<!-- Missing img_url filter -->
+<img src="{{ image }}" ...>
+```
+
+In the examples above, multiple connections are competing for resources, are accelerating download independently and are improperly prioritized.
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<!-- Good -->
+<script src="{{ 'jquery.min.js' | asset_url }}" defer></script>
+{{ 'bootstrap.min.css' | asset_url | stylesheet_tag }}
+
+<!-- Better -->
+<script src="{{ 'theme.js' | asset_url }}" defer></script>
+{{ 'theme.css' | asset_url | stylesheet_tag }}
+
+<!-- Images -->
+<img src="{{ image | img_url }}" ...>
+```
+
+In the above, the JavaScript, CSS and images are all loading from the same connection. Making it so the browser and CDN can properly prioritize which assets are downloaded first while maintaining a "hot" connection that downloads fast.
+
+This can be done by downloading the files from those CDNs directly into your theme's `assets/` folder.
+
+Use the [`img_url` filter][img_url] for images.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+RemoteAsset:
+  enabled: true
+```
+
+## When Not To Use It
+
+When the remote content is highly dynamic.
+
+## Version
+
+This check has been introduced in Theme Check 0.7.0.
+
+## Resources
+
+- [Announcement by Google][googleprivacy]
+- [HTTP Cache Partioning Explainer](https://github.com/shivanigithub/http-cache-partitioning)
+- [Slow Start][slowstart]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[googleprivacy]: https://developers.google.com/web/updates/2020/10/http-cache-partitioning#resources
+[codesource]: /lib/theme_check/checks/remote_asset.rb
+[docsource]: /docs/checks/remote_asset.md
+[slowstart]: https://en.wikipedia.org/wiki/TCP_congestion_control#Slow_start
+[url_filters]: https://shopify.dev/docs/themes/liquid/reference/filters/url-filters
+[img_url]: https://shopify.dev/docs/themes/liquid/reference/filters/url-filters#img_url

data/exe/theme-check

@@ -3,4 +3,4 @@
 
 require "theme_check"
 
-ThemeCheck::Cli.new.run!(ARGV)
+ThemeCheck::Cli.parse_and_run(ARGV)

data/lib/theme_check.rb

@@ -22,6 +22,7 @@ require_relative "theme_check/offense"
 require_relative "theme_check/printer"
 require_relative "theme_check/shopify_liquid"
 require_relative "theme_check/storage"
+require_relative "theme_check/string_helpers"
 require_relative "theme_check/file_system_storage"
 require_relative "theme_check/in_memory_storage"
 require_relative "theme_check/tags"

data/lib/theme_check/check.rb

@@ -82,7 +82,7 @@ module ThemeCheck
     end
 
     def code_name
-      self.class.name.demodulize
+      StringHelpers.demodulize(self.class.name)
     end
 
     def ignore!

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.end_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
@@ -62,7 +56,7 @@ module ThemeCheck
       # More complicated liquid statements are not in scope.
       if src =~ /^#{VARIABLE}$/o && src =~ /asset_url/ && src =~ Liquid::QuotedString
         asset_id = Regexp.last_match(0).gsub(START_OR_END_QUOTE, "")
-        asset = @theme.assets.find { |a| a.name.ends_with?("/" + asset_id) }
+        asset = @theme.assets.find { |a| a.name.end_with?("/" + asset_id) }
         return if asset.nil?
         asset.gzipped_size
       elsif src =~ %r{^(https?:)?//}

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 = %r{<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 && height
+      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