platformos-check 0.0.1

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 theme file. 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 PlatformOS Check 0.0.1.
+
+## Resources
+
+- [Deprecated Tags Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://documentation.platformos.com/api-reference/liquid/include
+[codesource]: /lib/platformos_check/checks/convert_include_to_render.rb
+[docsource]: /docs/checks/convert_include_to_render.md

data/docs/checks/deprecated_filter.md

@@ -0,0 +1,30 @@
+# 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.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+DeprecatedFilter:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in PlatformOS Check 0.1.0.
+
+## Resources
+
+- [Deprecated Filters Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://documentation.platformos.com/api-reference/liquid/platformos-filters
+[codesource]: /lib/platformos_check/checks/deprecated_filter.rb
+[docsource]: /docs/checks/deprecated_filter.md

data/docs/checks/html_parsing_error.md

@@ -0,0 +1,50 @@
+# Report HTML parsing errors (`HtmlParsingError`)
+
+Report errors preventing the HTML from being parsed and analyzed by PlatformOS Check.
+
+## Check Details
+
+This check is aimed at reporting HTML errors that prevent a file from being analyzed.
+
+The HTML parser limits the number of attributes per element to 400, and the maximum depth of the DOM tree to 400 levels. If any one of those limits is reached, parsing stops, and all HTML offenses on this file are ignored.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<img src="muffin.jpeg"
+     data-attrbute-1=""
+     data-attrbute-2=""
+     ... up to
+     data-attrbute-400="">
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<img src="muffin.jpeg">
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+HtmlParsingError:
+  enabled: true
+```
+
+## When Not To Use It
+
+If you don't care about HTML offenses.
+
+## Version
+
+This check has been introduced in PlatformOS Check 0.0.1.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/platformos_check/checks/html_parsing_error.rb
+[docsource]: /docs/checks/html_parsing_error.md

data/docs/checks/img_lazy_loading.md

@@ -0,0 +1,63 @@
+# 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]_
+
+As a general rule you should apply `loading="lazy"` to elements that are **not initially visible** when the page loads. Only images that require user interaction (scrolling, hovering, clicking etc.) to be seen can be safely lazy loaded without negatively impacting the rendering performance.
+
+## Check Details
+
+This check is aimed at deferring loading non-critical images.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<img src="a.jpg">
+
+<!-- Replaces lazysizes.js -->
+<img data-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 -->
+<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
+
+There should be no cases where disabling this rule is needed. When it comes to rendering performance, it is generally better to specify `loading="eager"` as a default. You may want to do that for sections that are often placed in different parts of the page (top, middle, bottom), which makes it hard to reason about which value should be used.
+
+## Version
+
+This check has been introduced in PlatformOS Check 0.10.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+- [MDN - Lazy loading][mdn]
+
+[codesource]: /lib/platformos_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/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 PlatformOS 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/platformos_check/checks/img_aspect_ratio.rb
+[docsource]: /docs/checks/img_aspect_ratio.md

data/docs/checks/invalid_args.md

@@ -0,0 +1,56 @@
+# Prevent providing invalid arguments in function, render and graphql tags Liquid (`InvalidArgs`)
+
+This check exists to prevent providing invalid arguments via `function`, `render` and `graphql` tags.
+
+## Examples
+
+The following examples contain code snippets that either fail or pass this check.
+
+### ✗ Fail
+
+```liquid
+{% comment %}app/graphql/my-query does not define invalid_argument{% endcomment %}
+{% graphql res = 'my-query', invalid_argument: 10 %}
+```
+
+```liquid
+{% function res = 'my-function', arg: 1, arg: 2 %}
+```
+
+```liquid
+{% render res = 'my-partial', context: context %}
+```
+
+### ✓ Pass
+
+```liquid
+{% comment %}app/graphql/my-query defines defined_argument{% endcomment %}
+{% graphql res = 'my-query', defined_argument: 10 %}
+```
+
+## Options
+
+The following example contains the default configuration for this check:
+
+```yaml
+InvalidArgs:
+  enabled: true
+```
+
+| Parameter | Description |
+| --- | --- |
+| enabled | Whether the check is enabled. |
+| severity | The [severity](https://documentation.platformos.com/developer-guide/platformos-check/platformos-check#check-severity) of the check. |
+
+## When Not To Use It
+
+It is not safe to disable this rule.
+
+## Resources
+
+- [platformOS GraphQL Reference](https://documentation.platformos.com/api-reference/graphql/glossary)
+- [Rule source][codesource]
+- [Documentation source][docsource]
+
+[codesource]: /lib/platformos_check/checks/graphql_args.rb
+[docsource]: /docs/checks/graphql_args.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: 5
+```
+
+### `min_consecutive_statements`
+
+The `min_consecutive_statements` option (Default: `5`) 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 PlatformOS Check 0.0.1.
+
+## Resources
+
+- [`{% liquid %}` Tag Reference][liquid]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[liquid]: https://documentation.platformos.com/api-reference/liquid/platformos-tags
+[codesource]: /lib/platformos_check/checks/liquid_tag.rb
+[docsource]: /docs/checks/liquid_tag.md

data/docs/checks/missing_enable_comment.md

@@ -0,0 +1,50 @@
+# Prevent missing platformos-check-enable comments (`MissingEnableComment`)
+
+When `platformos-check-disable` is used in the middle of a theme file, the corresponding `platformos-check-enable` comment should also be included.
+
+## Check Details
+
+This check aims at eliminating missing `platformos-check-enable` comments.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+<!doctype html>
+<html>
+  <head>
+    {% # platformos-check-disable ParserBlockingJavaScript %}
+    <script src="https://cdnjs.com/jquery.min.js"></script>
+  </head>
+  <body>
+    <!-- ... -->
+  </body>
+</html>
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+<!doctype html>
+<html>
+  <head>
+    {% # platformos-check-disable ParserBlockingJavaScript %}
+    <script src="https://cdnjs.com/jquery.min.js"></script>
+    {% # platformos-check-enable ParserBlockingJavaScript %}
+  </head>
+  <body>
+    <!-- ... -->
+  </body>
+</html>
+```
+
+## Version
+
+This check has been introduced in PlatformOS Check 0.3.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/platformos_check/checks/missing_enable_comment.rb
+[docsource]: /docs/checks/missing_enable_comment.md

data/docs/checks/missing_template.md

@@ -0,0 +1,65 @@
+# Prevent missing templates (`MissingTemplate`)
+
+This check exists to prevent rendering resources with the `render` tag, `function` tag (and the deprecated `include` tag) that do not exist.
+
+## Check Details
+
+This check is aimed at preventing liquid rendering errors.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+{% render 'partial-that-does-not-exist' %}
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+{% render 'partial-that-exists' %}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+MissingTemplate:
+  enabled: true
+  ignore_missing: []
+```
+
+### `ignore_missing`
+
+Specify a list of patterns of missing template files to ignore.
+
+While the `ignore` option will ignore all occurrences of `MissingTemplate` according to the file in which they appear, `ignore_missing` allows ignoring all occurrences of `MissingTemplate` based on the target template, the template being rendered.
+
+For example:
+
+```yaml
+MissingTemplate:
+  ignore_missing:
+  - icon-*
+```
+
+Would ignore offenses on `{% render 'icon-missing' %}` across app files.
+
+```yaml
+MissingTemplate:
+  ignore:
+  - modules/private-module/index.liquid
+```
+
+Would ignore all `MissingTemplate` in `modules/private-module/index.liquid`, no mater the file being rendered.
+
+## Version
+
+This check has been introduced in PlatformOS Check 0.0.1.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/platformos_check/checks/missing_template.rb
+[docsource]: /docs/checks/missing_template.md

data/docs/checks/parse_json_format.md

@@ -0,0 +1,76 @@
+# Prevent unformatted parse_json tags (`ParseJsonFormat`)
+
+_Version 1.9.0+_
+
+This check exists to ensure the JSON in your parses is pretty.
+
+It exists as a facilitator for its auto-correction. This way you can right-click fix the problem.
+
+## Examples
+
+The following examples contain code snippets that either fail or pass this check.
+
+### ✗ Fail
+
+```liquid
+{% parse_json my_json %}
+{
+  "locales": {
+"en": {
+  "title": "Welcome", "product": "Product"
+},
+          "fr": { "title": "Bienvenue", "product": "Produit" }
+  }
+}
+{% endparse_json %}
+```
+
+### ✓ Pass
+
+```liquid
+{% parse_json my_json %}
+{
+  "locales": {
+    "en": {
+      "title": "Welcome",
+      "product": "Product"
+    },
+    "fr": {
+      "title": "Bienvenue",
+      "product": "Produit"
+    }
+  }
+}
+{% endparse_json %}
+```
+
+## Options
+
+The following example contains the default configuration for this check:
+
+```yaml
+ParseJsonFormat:
+  enabled: true
+  severity: style
+  start_level: 0
+  indent: '  '
+```
+
+| Parameter | Description |
+| --- | --- |
+| enabled | Whether the check is enabled. |
+| severity | The [severity](https://documentation.platformos.com/developer-guide/platformos-check/platformos-check#check-severity) of the check. |
+| start_level | The indentation level. If you prefer an indented parse_json, set this to 1. |
+| indent | The character(s) used for indentation levels. |
+
+## Disabling this check
+
+ This check is safe to disable. You might want to disable this check if you do not care about the visual appearance of your parse_json tags.
+
+## Resources
+
+- [Rule source][codesource]
+- [Documentation source][docsource]
+
+[codesource]: /lib/platformos_check/checks/parse_json_format.rb
+[docsource]: /docs/checks/parse_json_format.md

data/docs/checks/parser_blocking_javascript.md

@@ -0,0 +1,97 @@
+# Discourage use of parser-blocking JavaScript (`ParserBlockingJavaScript`)
+
+The `defer` or `async` attributes are extremely important on script tags. When neither of those attributes are used, a script tag will block the construction and rendering of the DOM until the script is _loaded_, _parsed_ and _executed_. It also creates congestion on the Network, messes with the resource priorities and significantly delays the rendering of the page.
+
+Considering that JavaScript on platformOS apps should always be used to progressively _enhance_ the experience of the site, app should never make use of parser-blocking script tags.
+
+As a general rule, use `defer` if the order of execution matters, `async` otherwise. When in doubt, choose either one and get 80/20 of the benefits.
+
+## Check Details
+
+This check is aimed at eliminating parser-blocking JavaScript on app.
+
+:-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 }}
+
+<!-- jQuery is typically loaded synchronously because inline scripts depend on $, don't do that. -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
+...
+<button id="thing">Click me!</button>
+<script>
+  $('#thing').click(() => {
+    alert('Oh. Hi Mark!');
+  });
+</script>
+```
+
+:+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>
+
+<!-- Better than synchronous jQuery -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
+...
+<button id="thing">Click me!</button>
+<script>
+  // Because we're using `defer`, jQuery is guaranteed to
+  // be loaded when DOMContentLoaded fires. This technique
+  // could be used as a first step to refactor an old theme
+  // that inline depends on jQuery.
+  document.addEventListener('DOMContentLoaded', () => {
+    $('#thing').click(() => {
+      alert('Oh. Hi Mark!');
+    });
+  });
+</script>
+
+<!-- Even better. Web Native (no jQuery). -->
+<button id="thing">Click Me</button>
+<script>
+  const button = document.getElementById('thing');
+  button.addEventListener('click', () => {
+    alert('Oh. Hi Mark!');
+  });
+</script>
+
+<!-- Best -->
+<script src="{{ 'theme.js' | asset_url }}" defer></script>
+...
+<button id="thing">Click Me</button>
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ParserBlockingJavaScript:
+  enabled: true
+```
+
+## When Not To Use It
+
+This should only be turned off with the `platformos-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 PlatformOS Check 0.0.1.
+
+## Resources
+
+- [Lighthouse Render-Blocking Resources Audit][render-blocking]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[render-blocking]: https://web.dev/render-blocking-resources/
+[codesource]: /lib/platformos_check/checks/parser_blocking_javascript.rb
+[docsource]: /docs/checks/parser_blocking_javascript.md