platformos-check 0.4.11 → 0.4.13

data/docs/checks/TEMPLATE.md.erb

@@ -1,28 +1,28 @@
 # Check Title (`<%= class_name %>`)
 
-_Version PLATFORMOS_CHECK_VERSION+_
+[A short description of what the check does.]
 
-A short description of what the check does.
-
-A brief paragraph explaining why the check exists (what best practice is it enforcing, and why is it important?).
+[A brief explanation of why the check exists, including the best practice it enforces and the importance of following this best practice. This section should help users understand how adhering to this check can improve their code quality, performance, or maintainability.]
 
 ## Examples
 
-The following examples contain code snippets that either fail or pass this check.
+The following examples show code snippets that either fail or pass this check:
 
-### &#x2717; Fail
+### &#x2717; Incorrect Code Example (Avoid using this):
 
 ```liquid
+<!-- Add an example of incorrect code here -->
 ```
 
-### &#x2713; Pass
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
+<!-- Add an example of correct code here -->
 ```
 
-## Options
+## Configuration Options
 
-The following example contains the default configuration for this check:
+The default configuration for this check:
 
 ```yaml
 <%= class_name %>:
@@ -39,9 +39,14 @@ The following example contains the default configuration for this check:
 
 ## Disabling this check
 
-[ This check is safe to disable. You might want to disable this check if ... | Disabling this check isn't recommended because ... ].
+[This check is safe to disable if ... ]
+[You might want to disable this check if ...]
+[Disabling this check is not recommended, because ...]
+[This check is disabled by default when <condition>.] 
+
+## Version
 
-[ This check is disabled by default when <condition>. ]
+This check has been introduced in platformOS Check [x.x.x.]
 
 ## Resources
 

data/docs/checks/convert_include_to_render.md

@@ -1,41 +1,57 @@
-# Discourage the use of `include` (`ConvertIncludeToRender`)
+# 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 purpose of this check is to discourage the use of `include` tags and ensure the use of `render` tags instead. The `include` tag is now considered [deprecated][deprecated], and it is recommended to use the `render` tag to help maintain the efficiency and readability of your code.
 
-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
+## Why Use `render` instead of `include`
 
-This check is aimed at eliminating the use of `include` tags.
+While the `include` tag functions similarly to the `render` tag by inserting snippets of code into files, there's a key difference: `include` allows the code within the snippet to access and overwrite the variables in its parent platformOS file. This can make your website slower and your code harder to read and maintain. That’s why it’s recommended to use the simpler `render` tag instead.
 
-:-1: Examples of **incorrect** code for this check:
+## Examples
+
+The following examples show code snippets that either fail or pass this check:
+
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% include 'snippet' %}
 ```
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% render 'snippet' %}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 ConvertIncludeToRender:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check - When Not To Use It
+
+### Using Variable Partial Names
+
+There is an exception to using the `render` tag: if you need to use a variable as a partial name. In such cases, the `include` tag remains necessary because the `render` tag does not support variable partial names.
+Here's how you can use the include tag for this specific scenario:
+
+```liquid
+{% liquid 
+  # platformos-check-disable ConvertIncludeToRender
+  include my_variable 
+  # platformos-check-enable ConvertIncludeToRender
+%}
+```
 
-It is discouraged to disable this rule.
+This example shows how to temporarily disable the check when you need to use `include` specifically for variable partial names.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.0.1.
+This check has been introduced in platformOS Check 0.0.1.
 
 ## Resources
 
@@ -45,4 +61,4 @@ This check has been introduced in PlatformOS Check 0.0.1.
 
 [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
+[docsource]: /docs/checks/convert_include_to_render.md

data/docs/checks/deprecated_filter.md

@@ -1,14 +1,10 @@
-# Discourage use of deprecated filters (`DeprecatedFilter`)
+# Discourage The Use of Deprecated filters (`DeprecatedFilter`)
 
-This check discourages the use of [deprecated filters][deprecated].
+This check discourages the use of [deprecated filters][deprecated] and aims at eliminating them.
 
-## Check Details
+## Configuration Options
 
-This check is aimed at eliminating deprecated filters.
-
-## Check Options
-
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 DeprecatedFilter:
@@ -17,7 +13,7 @@ DeprecatedFilter:
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.1.0.
+This check has been introduced in platformOS Check 0.1.0.
 
 ## Resources
 

data/docs/checks/form_action.md

@@ -1,14 +1,14 @@
-# Form action (`FormAction`)
+# Form Action (`FormAction`)
 
-Form action defines the endpoint to which browser will make a request after submitting it.
+The form action defines the endpoint to which the browser will make a request after submitting the form. As a general rule, you should use an absolute path, such as `action="/my/path"`, instead of a relative path like `action="my/path"`, to avoid errors. Using an absolute path ensures that the form submission always targets the correct endpoint, regardless of the current page's location. In contrast, a relative path could result in the form submitting to an unintended endpoint based on the current URL. 
 
-As a general rule you should use relative path like `action="/my/path"` instead of for example `action="my/path"` to avoid errors.
+This check ensures that the path correctly begins with a forward slash (`/`), which means it always refers to the root directory.
 
-## Check Details
+## Examples
 
-This check is aimed at ensuring you have not forgotten to start the path with /.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 <form action="dummy/create">
@@ -16,7 +16,7 @@ This check is aimed at ensuring you have not forgotten to start the path with /.
 </form>
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <form action="/dummy/create">
@@ -36,22 +36,22 @@ This check is aimed at ensuring you have not forgotten to start the path with /.
 </form>
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 FormAction:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-There should be no cases where disabling this rule is needed.
+Disabling this check is not recommended.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.4.5.
+This check has been introduced in platformOS Check 0.4.5.
 
 ## Resources
 

data/docs/checks/form_authenticity_token.md

@@ -1,22 +1,29 @@
-# Form authenticity token (`FormAuthenticityToken`)
+# Form Authenticity Token (`FormAuthenticityToken`)
 
-In platformOS all POST/PATCH/PUT/DELETE requests are protected from [CSRF Attacks][csrf-attack] through [authenticity_token][page-csrf]
-Form action defines the endpoint to which browser will make a request after submitting it.
+This check ensures that the `authenticity_token` is included in each form to keep the session safe and protect against CSRF.
 
-As a general rule you should include hidden input `<input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}">` in every form. Missing it will result in session invalidation and the logged in user will be automatically logged out.
+In platformOS, all POST, PATCH, PUT, and DELETE requests are protected from [CSRF Attacks][csrf-attack] by using an [authenticity_token][page-csrf]. This token verifies that the person submitting the form is the one who initially requested the web page.
 
-## Check Details
+It's important to add a hidden input field with the authenticity token in every form. The tag should look like this: 
 
-This check is aimed at ensuring you have not forgotten to include authenticity_token in a form.
+```liquid
+<input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}">
+```
+
+If this token is missing from a form, the session will end and the user will be logged out automatically.
 
-:-1: Examples of **incorrect** code for this check:
+## Examples
+
+The following examples show code snippets that either fail or pass this check:
+
+### &#x2717; Incorrect Code Example (Avoid using this):
 
 ```liquid
 <form action="/dummy/create" method="post">
 </form>
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 With token:
 ```liquid
@@ -43,22 +50,22 @@ For parameterized request:
 </form>
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 FormAuthenticityToken:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-There should be no cases where disabling this rule is needed.
+Disabling this check is not recommended.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.4.6.
+This check has been introduced in platformOS Check 0.4.6.
 
 ## Resources
 
@@ -70,5 +77,4 @@ This check has been introduced in PlatformOS Check 0.4.6.
 [codesource]: /lib/platformos_check/checks/form_authenticity_token.rb
 [docsource]: /docs/checks/form_authenticity_token.md
 [page-csrf]: https://documentation.platformos.com/developer-guide/pages/pages#post-put-patch-delete-methods-and-cross-site-request-forgery-attacks
-[csrf-attack]: https://owasp.org/www-community/attacks/csrf
-
+[csrf-attack]: https://owasp.org/www-community/attacks/csrf

data/docs/checks/graphql_in_for_loop.md

@@ -1,16 +1,18 @@
-# GraphQL in for loop (`GraphqlInForLoop`)
+# GraphQL in For Loop (`GraphqlInForLoop`)
 
-This check is aimed towards identifying performance problems before they arise. Invoking GraphQL queries/mutations inside the `for loop` can lead to performance issues such as increased database load, higher latency, and inefficient use of network resources. It is particularly problematic when dealing with large datasets or when the number of entities grows.
+This check is designed to prevent performance issues by identifying GraphQL queries or mutations executed within a `for loop`. By doing so, it helps prevent performance problems before they start.
 
-Invoking a GraphQL query within a `for loop` might also be a sign of a so called N+1 problem. The N+1 pattern often arises when dealing with relationships between entities. In an attempt to retrieve related data, developers may inadvertently end up executing a large number of queries, resulting in a significant performance overhead.
+Invoking GraphQL queries/mutations inside for loops can lead to **performance issues** such as increased database load, higher latency, and inefficient use of network resources. This issue becomes even more noticeable with large datasets or as the number of entities processed grows.
 
-To address this problem, developers can use techniques like eager loading, which involves fetching the related data in a single query instead of issuing separate queries for each entity. This helps reduce the number of database round-trips and improves overall system performance. In platformOS the most common technique to fix the N+1 issue is by [using related_records][relalted_records].
+Invoking a GraphQL query within a `for loop` might also be a sign of a so called **N+1 problem**. The N+1 pattern often arises when dealing with relationships between entities. In an attempt to retrieve related data, developers may inadvertently end up executing a large number of queries, resulting in a significant performance overhead.
 
-## Check Details
+To address this problem, developers can use techniques like eager loading, which involves fetching the related data in a single query instead of issuing separate queries for each entity. This helps reduce the number of database round-trips and improves overall system performance. In platformOS, the N+1 issue is commonly handled by [using related_records][related_records].
 
-This check is aimed towards identifying GraphQL queries invoked within a for loop.
+## Examples
 
-:-1: Examples of **incorrect** code for this check:
+The following examples show code snippets that either fail or pass this check:
+
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% assign arr = 'a,b,c' | split: ','}
@@ -21,29 +23,29 @@ This check is aimed towards identifying GraphQL queries invoked within a for loo
 
 ```
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% assign arr = 'a,b,c' | split: ','}
 {% graphql g = 'my/graphql', arr: arr %}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 GraphqlInForLoop:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-In the perfect world, there should be no cases where disabling this rule is needed - platformOS most likely already has a way to solve a problem without using GraphQL query / mutation in the for loop.
+Ideally, there should be no need to disable this rule, as platformOS likely offers alternative solutions to handle scenarios without using a GraphQL query or mutation inside a for loop.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.4.9.
+This check has been introduced in platformOS Check 0.4.9.
 
 ## Resources
 

data/docs/checks/html_parsing_error.md

@@ -1,14 +1,14 @@
-# Report HTML parsing errors (`HtmlParsingError`)
+# Report HTML Parsing Errors (`HtmlParsingError`)
 
-Report errors preventing the HTML from being parsed and analyzed by PlatformOS Check.
+This check reports errors that prevent HTML from being properly parsed and analyzed by PlatformOS Check. It focuses on identifying HTML errors that hinder file analysis.
 
-## Check Details
+The HTML parser limits the number of attributes per element to 400 and the maximum depth of the Document Object Model (DOM) tree to 400 levels. If either of these limits is reached, parsing stops, and all HTML errors in the file are ignored.
 
-This check is aimed at reporting HTML errors that prevent a file from being analyzed.
+## Examples
 
-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.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 <img src="muffin.jpeg"
@@ -18,28 +18,28 @@ The HTML parser limits the number of attributes per element to 400, and the maxi
      data-attrbute-400="">
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <img src="muffin.jpeg">
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 HtmlParsingError:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-If you don't care about HTML offenses.
+This check is safe to disable if identifying HTML errors is not a priority.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.0.1.
+This check has been introduced in platformOS Check 0.0.1.
 
 ## Resources
 

data/docs/checks/img_lazy_loading.md

@@ -1,4 +1,6 @@
-# Lazy loading image tags (`ImgLazyLoading`)
+# Lazy Loading Image Tags (`ImgLazyLoading`)
+
+This check is designed to ensure that non-critical images are deferred for loading, improving page load times and overall performance.
 
 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.
 
@@ -8,13 +10,13 @@ Very often, webpages contain many images that contribute to data-usage and how f
 
 _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.
+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
+## Examples
 
-This check is aimed at deferring loading non-critical images.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 <img src="a.jpg">
@@ -26,7 +28,7 @@ This check is aimed at deferring loading non-critical images.
 <img src="a.jpg" loading="auto">
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <img src="a.jpg" loading="lazy">
@@ -35,22 +37,22 @@ This check is aimed at deferring loading non-critical images.
 <img src="a.jpg" loading="eager">
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 ImgLazyLoading:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-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.
+There should be no cases where disabling this rule is needed. For optimal rendering performance, it is generally better to specify `loading="eager"` as a default. This is especially useful for sections that are often placed in different parts of the page (top, middle, bottom), making it difficult to determine the appropriate `loading` valued. be used.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.10.0.
+This check has been introduced in platformOS Check 0.10.0.
 
 ## Resources
 

data/docs/checks/img_width_and_height.md

@@ -1,23 +1,23 @@
 # Width and height attributes on image tags (`ImgWidthAndHeight`)
 
-This check exists to prevent [cumulative layout shift][cls] (CLS) in themes.
+This check aims to prevent [cumulative layout shift][cls] (CLS) in your platformOS application by enforcing the use of `width` and `height` attributes on `img` tags.
 
-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.
+When `width` and `height` attributes are missing on an `img` tag, the browser doesn’t know the image’s aspect ratio until the image is fully loaded. Without this information, the browser treats the image as having a height of 0 until it loads.
 
-This has numerous nefarious implications:
+This leads to several problems:
 
-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!
+1. [Layout shift occurs as images load][codepenshift]. Text and other content get pushed down the page as the images load one after another.
+2. [Lazy loading fails][codepenlazy]. When all images appear to have a height of 0px, the browser assumes they are all in the viewport and loads them immediately, defeating the purpose of lazy loading.
 
-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.
+To fix this, ensure the `width` and `height` attributes are set on the `img` tag and that the CSS width of the image is defined.
 
-Note: The width and height attributes of an image do not have  units.
+**Note:** The `width` and `height` attributes should not include units.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating content layout shift in themes by enforcing the use of the `width` and `height` attributes on `img` tags.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 <img alt="cat" src="cat.jpg">
@@ -25,7 +25,7 @@ This check is aimed at eliminating content layout shift in themes by enforcing t
 <img alt="{{ image.alt }}" src="{{ image.src }}">
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <img alt="cat" src="cat.jpg" width="100" height="200">
@@ -39,29 +39,27 @@ This check is aimed at eliminating content layout shift in themes by enforcing t
 
 **NOTE:** The CSS `width` of the `img` should _also_ be set for the image to be responsive.
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 ImgWidthAndHeight:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check - When Not To Use It
 
-There are some cases where you can avoid content-layout shift without needing the width and height attributes:
+You can avoid content layout shift without `width` and `height` attributes in certain cases:
 
-- 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.
+- When the aspect ratio of the displayed image should be independent of the uploaded image. In these cases, use the padding-top hack with an `overflow: hidden` container.
+- When you are satisfied 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.
+Otherwise, it’s unwise to disable this check as it can negatively impact the mobile search ranking of the merchants using your platformOS application.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.6.0.
+This check has been introduced in platformOS Check 0.6.0.
 
 ## Resources
 
@@ -75,5 +73,5 @@ This check has been introduced in PlatformOS Check 0.6.0.
 [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
+[codesource]: /lib/platformos_check/checks/img_width_and_height.rb
+[docsource]: /docs/checks/img_width_and_height.md

data/docs/checks/include_in_render.md

@@ -1,12 +1,12 @@
-# Reports usage of `include` tag inside `render` (`IncludeInRender`)
+# Report usage of `include` tag inside `render` (`IncludeInRender`)
 
-Runtime error is used when `include` tag is used inside `render` tag.
+A runtime error occurs when an `include` tag is used inside a `render` tag. This check aims to eliminate and report these occurrences.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating the use of `include` tags `render` tag.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% liquid
@@ -20,7 +20,7 @@ This check is aimed at eliminating the use of `include` tags `render` tag.
 %}
 ```
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% liquid
@@ -34,22 +34,22 @@ This check is aimed at eliminating the use of `include` tags `render` tag.
 %}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 IncludeInRender:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-It is discouraged to disable this rule.
+Disabling this check is not recommended.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.4.9.
+This check has been introduced in platformOS Check 0.4.9.
 
 ## Resources