theme-check 0.3.2 → 0.7.0

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

@@ -0,0 +1,25 @@
+# Prevent missing directories (`RequiredDirectories`)
+
+This check exists to warn theme developers about missing required directories in their structure.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+RequiredDirectories:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify Theme File Structure](https://shopify.dev/tutorials/develop-theme-files)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/required_directories.rb
+[docsource]: /docs/checks/required_directories.md

data/docs/checks/required_layout_theme_object.md

@@ -0,0 +1,28 @@
+# Prevent missing required objects in theme.liquid (`RequiredLayoutThemeObject`)
+
+## Check Details
+
+This check prevents missing `{{ content_for_header }}` and `{{ content_for_layout }}` objects in `layout/theme.liquid`.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+RequiredLayoutThemeObject:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify theme.liquid requirements][themeliquid]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/required_layout_theme_object.rb
+[docsource]: /docs/checks/required_layout_theme_object.md
+[themeliquid]: https://shopify.dev/docs/themes/theme-templates/theme-liquid

data/docs/checks/space_inside_braces.md

@@ -0,0 +1,63 @@
+# Ensure consistent spacing inside Liquid tags and variables (`SpaceInsideBraces`)
+
+Warns against inconsistent spacing inside liquid tags and variables.
+
+## Check Details
+
+This check is aimed at eliminating ugly Liquid:
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- Around braces -->
+{% assign x = 1%}
+{{ x}}
+{{x }}
+
+<!-- After commas and semicolons -->
+{% form 'type',  object, key:value %}
+{% endform %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% assign x = 1 %}
+{{ x }}
+{% form 'type', object, key: value, key2: value %}
+{% endform %}
+{{ "ignore:stuff,  indeed" }}
+{% render 'product-card',
+  product_card_product: product_recommendation,
+  show_vendor: section.settings.show_vendor,
+  media_size: section.settings.product_recommendations_image_ratio,
+  center_align_text: section.settings.center_align_text
+%}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+SpaceInsideBraces:
+  enabled: true
+```
+
+## When Not To Use It
+
+If you don't care about the look of your code.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Liquid Style Guide][styleguide]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[styleguide]: https://github.com/Shopify/liquid-style-guide
+[codesource]: /lib/theme_check/checks/space_inside_braces.rb
+[docsource]: /docs/checks/space_inside_braces.md

data/docs/checks/syntax_error.md

@@ -0,0 +1,49 @@
+# Prevent Syntax Errors (`SyntaxError`)
+
+This check exists to inform the user of Liquid syntax error earlier.
+
+## Check Details
+
+This check is aimed at eliminating syntax errors.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% include 'muffin'
+{% assign foo = 1 }}
+{% unknown %}
+{% if collection | size > 0 %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% include 'muffin' %}
+{% assign foo  = 1 %}
+{% if collection.size > 0 %}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+SyntaxError:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/syntax_error.rb
+[docsource]: /docs/checks/syntax_error.md

data/docs/checks/template_length.md

@@ -0,0 +1,50 @@
+# Discourage the use of large template files (`TemplateLength`)
+
+This check exists to discourage the use of large template files. Use snippets to componentize your theme.
+
+## Check Details
+
+This check is aimed at eliminating large template files.
+
+:-1: Examples of **incorrect** code for this check:
+
+- Files that have more lines than the threshold
+
+:+1: Examples of **correct** code for this check:
+
+- Files that have less lines than the threshold
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+TemplateLength:
+  enabled: true
+  max_length: 200
+  exclude_schema: true
+```
+
+### `max_length`
+
+The `max_length` (Default: `200`) option determines the maximum number of lines allowed inside a liquid file.
+
+### `exclude_schema`
+
+The `exclude_schema` (Default: `true`) option determines if the schema lines from a template should be excluded from the line count.
+
+## When Not To Use It
+
+If you don't care about template lengths, then it's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/template_length.rb
+[docsource]: /docs/checks/template_length.md

data/docs/checks/translation_key_exists.md

@@ -0,0 +1,63 @@
+# Prevent use of undefined translations (`TranslationKeyExists`)
+
+This check exists to prevent translation errors in themes.
+
+## Check Details
+
+This check is aimed at eliminating the use of translations that do not exist.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% comment %}locales/en.default.json{% endcomment %}
+{
+  "greetings": "Hello, world!",
+  "general": {
+    "close": "Close"
+  }
+}
+
+{% comment %}templates/index.liquid{% endcomment %}
+{{ "notfound" | t }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% comment %}locales/en.default.json{% endcomment %}
+{
+  "greetings": "Hello, world!",
+  "general": {
+    "close": "Close"
+  }
+}
+
+{% comment %}templates/index.liquid{% endcomment %}
+{{ "greetings" | t }}
+{{ "general.close" | t }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+TranslationKeyExists:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this check.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/translation_key_exists.rb
+[docsource]: /docs/checks/translation_key_exists.md

data/docs/checks/undefined_object.md

@@ -0,0 +1,53 @@
+# Prevent undefined object errors (`UndefinedObject`)
+
+This check prevents errors by making sure that no undefined variables are being used
+
+## Check Details
+
+This check is aimed at eliminating undefined object errors.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% assign greetings = "Hello" %}
+{% if greeting == "Hello" %}
+
+{{ articl }}
+{{ prodcut }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% assign greetings = "Hello" %}
+{% if greetings == "Hello" %}
+
+{{ article }}
+{{ product }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+UndefinedObject:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is discouraged to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify Object Reference](https://shopify.dev/docs/themes/liquid/reference/objects)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/undefined_object.rb
+[docsource]: /docs/checks/undefined_object.md

data/docs/checks/unknown_filter.md

@@ -0,0 +1,45 @@
+# Prevent use of unknown filters (`UnknownFilter`)
+
+This check exists to prevent user errors.
+
+## Check Details
+
+This check is aimed at preventing the use of unknown filters.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{{ x | some_unknown_filter }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{{ x | upcase }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+UnknownFilter:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify Filter Reference](https://shopify.dev/docs/themes/liquid/reference/filters)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/unknown_filter.rb
+[docsource]: /docs/checks/unknown_filter.md