theme-check 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5543690a150f2a864a5a9900feca80286ffe4c00d545885ee31dc02c9d389b71
-  data.tar.gz: c1c518e2013a1106dc7ace3a14ef5158853e06929694503777a37c0fc695025a
+  metadata.gz: 7beb3a827afcd22a262b82b436ed03a7130a1237ab11351bf4e1b36769c62d1a
+  data.tar.gz: a92529eac6dcaa689b708ecfda3e53a6b132e61ae01f26ae3ebb0bf3ec03e962
 SHA512:
-  metadata.gz: 405832fbd93d17f3412abb83181b8c76c0aee43e2405bc7329b7ace746c20887c32ab638bf49c99adf4598532fc92d5840a46dc24d2a20b89909849b8c2813a3
-  data.tar.gz: 40316910f51d646017059d4256cba23dfcb9e20822a0987b65a04ab79c40c160c882d4bdf7e0cc4d646b08971ba04bb58999a7c5b93a4741233a8ce1c5ce4ad9
+  metadata.gz: dd4554837884b203c2bca10cdbd09e29d0f485d814c8aff72d8680d1d7f44e82e8bef74b192953aba8a61622434ff3f466a24109f6eb3bee83500585f462672f
+  data.tar.gz: 75ece7d25c463748ae1d810920b488e732e50602988f3dd40bccb25a649af4d9336d4a3dc12310dbb1b53e1492728f8900da1050759e43e826457991f0bf6a11

data/.rubocop.yml

@@ -17,3 +17,9 @@ Layout/LineLength:
 
 Lint/MissingSuper:
   Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,14 @@
 
+0.5.0 / 2021-03-12
+==================
+
+  * Add [AssetSizeJavaScript](/docs/checks/asset_size_javascript.md) check ([#194](https://github.com/Shopify/theme-check/pull/194))
+  * Add [documentation for all checks](/docs/checks)
+  * Make documentation for checks mandatory
+  * Add link to documentation from within the editor (via `codeDescription` in the Language Server) (![Demo](https://screenshot.click/10-29-cjx7r-4asor.mp4))
+  * Allow checks to have multiple categories
+  * Fix multiple occurrences of UndefinedObject not being reported ([#192](https://github.com/shopify/theme-check/issues/192))
+
 v0.4.0 / 2021-02-25
 ==================
 

data/CONTRIBUTING.md

@@ -44,7 +44,6 @@ module ThemeCheck
   # NOTE: inherit from JsonCheck to implement a JSON based check.
   class MyCheckName < LiquidCheck
     severity :suggestion # :error or :style
-    doc "https://..."    # Optional link to doc
 
     def on_document(node)
       # Called with the root node of all templates
@@ -122,7 +121,7 @@ module ThemeCheck
 end
 ```
 
-Add the new check to `config/default.yml` to enable it.
+Add the new check to `config/default.yml` to enable it. If the check is configurable, the `initialize` argument name and default values should also be duplicated inside `config/default.yml`.
 
 ```yaml
 MyCheckName:
@@ -131,4 +130,8 @@ MyCheckName:
 
 Add a corresponding test file under `test/checks`.
 
+Add a documentation file in `docs/checks/#{name_of_check}.md` based off of the [check documentation template][doctemplate].
+
 When done, run the tests with `dev test`.
+
+[doctemplate]: /docs/checks/CHECK_DOCS_TEMPLATE.md

data/README.md

@@ -32,7 +32,14 @@ Theme Check currently checks for the following:
 ✅ Deprecated filters  
 ✅ Missing `theme-check-enable` comment  
 
-And many more to come! Suggestions welcome ([create an issue](https://github.com/Shopify/theme-check/issues)).
+As well as checks that prevent easy to spot performance problems:
+
+✅ Use of [parser-blocking](/docs/checks/parser_blocking_javascript.md) JavaScript  
+✅ [Too much JavaScript](/docs/checks/asset_size_javascript.md)  
+
+For detailed descriptions and configuration options, [take a look at the complete list.](/docs/checks/)
+
+With more to come! Suggestions welcome ([create an issue](https://github.com/Shopify/theme-check/issues)).
 
 ## Requirements
 
@@ -87,7 +94,7 @@ TemplateLength:
   enabled: false
   # Or configure options
   max_length: 300
-  
+
 # Enable a custom check
 MyCustomCheck
   enabled: true

data/RELEASING.md

@@ -2,7 +2,7 @@
 
 1. Check the Semantic Versioning page for info on how to version the new release: http://semver.org
 
-2. Create a PR to update the version in `lib/theme_check/version.rb`
+2. Create a PR to update the version in `lib/theme_check/version.rb` and replace the `THEME_CHECK_VERSION` placeholder in the documentation for new rules.
 
 3. Merge your PR to master
 

data/config/default.yml

@@ -10,12 +10,14 @@ ConvertIncludeToRender:
 
 LiquidTag:
   enabled: true
+  min_consecutive_statements: 4
 
 MissingTemplate:
   enabled: true
 
 NestedSnippet:
   enabled: true
+  max_nesting_level: 2
 
 RequiredLayoutThemeObject:
   enabled: true
@@ -80,3 +82,7 @@ MissingEnableComment:
 
 ParserBlockingJavaScript:
   enabled: true
+
+AssetSizeJavaScript:
+  enabled: false
+  threshold_in_bytes: 10000

data/data/shopify_liquid/tags.yml

@@ -15,6 +15,7 @@
 - increment
 - javascript
 - layout
+- liquid
 - paginate
 - raw
 - render

data/docs/checks/CHECK_DOCS_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Check Title (`CheckClassName`)
+
+A brief paragraph explaining why the check exists.
+
+## Check Details
+
+This check is aimed at eliminating ...
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+CheckClassName:
+  enabled: true
+  some_option: 10
+```
+
+### `some_option`
+
+The `some_option` option (Default: `10`) determines ...
+
+## When Not To Use It
+
+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.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/check_class_name.rb
+[docsource]: /docs/checks/check_class_name.md

data/docs/checks/asset_size_javascript.md

@@ -0,0 +1,79 @@
+# Prevent JavaScript Abuse on Server Rendered Themes (`AssetSizeJavaScript`)
+
+For server rendered pages, it is an anti-pattern to execute large JavaScript bundles on every navigation.
+
+This doesn't mean they don't have a reason to exist. For instance, chat widgets are mini applications embedded inside web pages. Designing such an app with server rendered updates would be absurd. However, if only 10% of the users interact with the chat widget, the other 90% should not have to execute the entire bundle on every page load.
+
+The natural solution to this problem is to implement the chat widget using the [Import on Interaction Pattern][ioip].
+
+## Check Details
+
+This rule disallows the use of theme JavaScript files and external scripts to have a compressed size greater than a configured `threshold_in_bytes`.
+
+:-1: Examples of **incorrect** code for this check:
+```liquid
+<!-- Here assets/chat-widget.js is more than 10KB gzipped. -->
+<script src="{{ 'chat-widget.js' | asset_url }}" defer></script>
+
+<!-- The use of jQuery is discouraged in themes -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
+```
+
+:+1: Example of **correct** code for this check:
+```liquid
+<script>
+  const chatWidgetButton = document.getElementById('#chat-widget')
+
+  chatWidgetButton.addEventListener('click', e => {
+    e.preventDefault();
+    import("{{ 'chat-widget.js' | asset_url }}")
+      .then(module => module.default)
+      .then(ChatWidget => ChatWidget.init())
+      .catch(err => {
+        console.error(err);
+      });
+  });
+</script>
+```
+
+## Check Options
+
+The default configuration is the following.
+
+```yaml
+AssetSizeJavaScript:
+  enabled: false
+  threshold_in_bytes: 10000
+```
+
+### `threshold_in_bytes`
+
+The `threshold_in_bytes` option (default: `10000`) determines the maximum allowed compressed size in bytes that a single JavaScript file can take.
+
+This includes theme and remote scripts.
+
+## When Not To Use It
+
+When you can't do anything about it, it is preferable to disable this rule using the comment syntax:
+
+```
+{% comment %}theme-check-disable AssetSizeJavaScript{% endcomment %}
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
+{% comment %}theme-check-enable AssetSizeJavaScript{% endcomment %}
+```
+
+This makes disabling the rule an explicit affair and shows that the code is smelly.
+
+## Version
+
+This check has been introduced in Theme Check 0.5.0.
+
+## Resources
+
+- [The Import On Interaction Pattern][ioip]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[ioip]: https://addyosmani.com/blog/import-on-interaction/
+[codesource]: /lib/theme_check/checks/asset_size_javascript.rb
+[docsource]: /docs/checks/asset_size_javascript.md

data/docs/checks/convert_include_to_render.md

@@ -0,0 +1,48 @@
+# Discourage the use of `include` (`ConvertIncludeToRender`)
+
+The `include` tag is [deprecated][deprecated]. This tag exists to enforce the use of the `render` tag instead of `include`.
+
+The `include` tag works similarly to the `render` tag, but it lets the code inside of the snippet to access and overwrite the variables within its parent template. The `include` tag has been deprecated because the way that it handles variables reduces performance and makes theme code harder to both read and maintain.
+
+## Check Details
+
+This check is aimed at eliminating the use of `include` tags.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% include 'snippet' %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% render 'snippet' %}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ConvertIncludeToRender:
+  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
+
+- [Deprecated Tags Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://shopify.dev/docs/themes/liquid/reference/tags/deprecated-tags#include
+[codesource]: /lib/theme_check/checks/convert_include_to_render.rb
+[docsource]: /docs/checks/convert_include_to_render.md

data/docs/checks/default_locale.md

@@ -0,0 +1,46 @@
+# Ensure theme has a default locale (`DefaultLocale`)
+
+This check makes sure the theme has a default translation file.
+
+## Check Details
+
+This check makes sure a theme has a default locale.
+
+:-1: Example of **incorrect** theme for this check:
+
+```
+locales/
+├── en.json
+├── fr.json
+└── zh-TW.json
+```
+
+:+1: Example of **correct** theme for this check:
+
+```
+locales/
+├── en.default.json  # a default translation file is required
+├── fr.json
+└── zh-TW.json
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+DefaultLocale:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/default_locale.rb
+[docsource]: /docs/checks/default_locale.md

data/docs/checks/deprecated_filter.md

@@ -0,0 +1,46 @@
+# Discourage use of deprecated filters (`DeprecatedFilter`)
+
+This check discourages the use of [deprecated filters][deprecated].
+
+## Check Details
+
+This check is aimed at eliminating deprecated filters.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+.site-footer p {
+  color: {{ settings.color_name | hex_to_rgba: 0.5 }};
+}
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+.site-footer p {
+  color: {{ settings.color_name | color_modify: 'alpha', 0.5 }};
+}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+DeprecatedFilter:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.2.0.
+
+## Resources
+
+- [Deprecated Filters Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://shopify.dev/docs/themes/liquid/reference/filters/deprecated-filters
+[codesource]: /lib/theme_check/checks/deprecated_filter.rb
+[docsource]: /docs/checks/deprecated_filter.md

data/docs/checks/liquid_tag.md

@@ -0,0 +1,65 @@
+# Encourage use of liquid tag for consecutive statements (LiquidTag)
+
+Recommends using `{% liquid ... %}` if 4 or more consecutive liquid tags (`{% ... %}`) are found.
+
+## Check Details
+
+This check is aimed at eliminating repetitive tag markers (`{%` and `%}`) in theme files.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+{% if collection.image.size != 0 %}
+{%   assign collection_image = collection.image %}
+{% elsif collection.products.first.size != 0 and collection.products.first.media != empty %}
+{%   assign collection_image = collection.products.first.featured_media.preview_image %}
+{% else %}
+{%   assign collection_image = nil %}
+{% endif %}
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+{%- liquid
+  if collection.image.size != 0
+    assign collection_image = collection.image
+  elsif collection.products.first.size != 0 and collection.products.first.media != empty
+    assign collection_image = collection.products.first.featured_media.preview_image
+  else
+    assign collection_image = nil
+  endif
+-%}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+LiquidTag:
+  enabled: true
+  min_consecutive_statements: 4
+```
+
+### `min_consecutive_statements`
+
+The `min_consecutive_statements` option (Default: `4`) determines the maximum (inclusive) number of consecutive statements before the check recommends a refactor.
+
+## When Not To Use It
+
+It's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [`{% liquid %}` Tag Reference][liquid]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[liquid]: https://shopify.dev/docs/themes/liquid/reference/tags/theme-tags#liquid
+[codesource]: /lib/theme_check/checks/liquid_tag.rb
+[docsource]: /docs/checks/liquid_tag.md