platformos-check 0.4.11 → 0.4.13

data/docs/checks/invalid_args.md

@@ -1,12 +1,12 @@
-# Prevent providing invalid arguments in function, render and graphql tags Liquid (`InvalidArgs`)
+# 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.
+This check ensures that invalid arguments are not provided in `function`, `render`, and `graphql` tags in Liquid files.
 
 ## 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:
 
-### ✗ Fail
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% comment %}app/graphql/my-query does not define invalid_argument{% endcomment %}
@@ -21,16 +21,16 @@ The following examples contain code snippets that either fail or pass this check
 {% render res = 'my-partial', context: context %}
 ```
 
-### ✓ Pass
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% comment %}app/graphql/my-query defines defined_argument{% endcomment %}
 {% graphql res = 'my-query', defined_argument: 10 %}
 ```
 
-## Options
+## Configuration Options
 
-The following example contains the default configuration for this check:
+The default configuration for this check:
 
 ```yaml
 InvalidArgs:
@@ -42,9 +42,9 @@ InvalidArgs:
 | 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
+## Disabling This Check
 
-It is not safe to disable this rule.
+Disabling this check is not recommended.
 
 ## Resources
 
@@ -52,5 +52,5 @@ It is not safe to disable this rule.
 - [Rule source][codesource]
 - [Documentation source][docsource]
 
-[codesource]: /lib/platformos_check/checks/graphql_args.rb
-[docsource]: /docs/checks/graphql_args.md
+[codesource]: /lib/platformos_check/checks/invalid_args.rb
+[docsource]: /docs/checks/invalid_args.md

data/docs/checks/liquid_tag.md

@@ -1,12 +1,12 @@
-# Encourage use of liquid tag for consecutive statements (LiquidTag)
+# Encourage Use of `{% liquid ... %}` Tag for Consecutive Statements (`LiquidTag`)
 
-Recommends using `{% liquid ... %}` if 4 or more consecutive liquid tags (`{% ... %}`) are found.
+This check recommends using the `{% liquid ... %}` tag when four or more consecutive Liquid tags (`{% ... %}`) are found. The purpose of this check is to eliminate repetitive tag markers (`{%` and `%}`) in your platformOS application files for improved readability and maintainability.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating repetitive tag markers (`{%` and `%}`) in theme files.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Example of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% if collection.image.size != 0 %}
@@ -18,7 +18,7 @@ This check is aimed at eliminating repetitive tag markers (`{%` and `%}`) in the
 {% endif %}
 ```
 
-:+1: Example of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {%- liquid
@@ -32,9 +32,9 @@ This check is aimed at eliminating repetitive tag markers (`{%` and `%}`) in the
 -%}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 LiquidTag:
@@ -44,15 +44,15 @@ LiquidTag:
 
 ### `min_consecutive_statements`
 
-The `min_consecutive_statements` option (Default: `5`) determines the maximum (inclusive) number of consecutive statements before the check recommends a refactor.
+The `min_consecutive_statements` option (Default: `5`) determines the maximum (inclusive) number of consecutive statements required before the check recommends refactoring to use the `{% liquid ... %}` tag.
 
-## When Not To Use It
+## Disabling This Check
 
-It's safe to disable this rule.
+This check is safe to disable if it does not align with your coding standards.
 
 ## 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/missing_enable_comment.md

@@ -1,12 +1,12 @@
-# Prevent missing platformos-check-enable comments (`MissingEnableComment`)
+# 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.
+This check ensures that when `platformos-check-disable` is used in your platformOS application, a corresponding `platformos-check-enable` comment is included to re-enable the checks.
 
-## Check Details
+## Examples
 
-This check aims at eliminating missing `platformos-check-enable` comments.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Example of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 <!doctype html>
@@ -21,7 +21,7 @@ This check aims at eliminating missing `platformos-check-enable` comments.
 </html>
 ```
 
-:+1: Example of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <!doctype html>
@@ -39,7 +39,7 @@ This check aims at eliminating missing `platformos-check-enable` comments.
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.3.0.
+This check has been introduced in platformOS Check 0.3.0.
 
 ## Resources
 

data/docs/checks/missing_template.md

@@ -1,26 +1,26 @@
-# Prevent missing templates (`MissingTemplate`)
+# 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.
+This check ensures that resources specified with the `render` tag, `function` tag, and the deprecated `include` tag actually exist. It aims to prevent Liquid rendering errors caused by referencing non-existent templates.
 
-## Check Details
+## Examples
 
-This check is aimed at preventing liquid rendering errors.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Example of **incorrect** code for this check:
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% render 'partial-that-does-not-exist' %}
 ```
 
-:+1: Example of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% render 'partial-that-exists' %}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 MissingTemplate:
@@ -30,9 +30,10 @@ MissingTemplate:
 
 ### `ignore_missing`
 
-Specify a list of patterns of missing template files to ignore.
+Specify a list of patterns for 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.
+- The `ignore` option ignores all occurrences of `MissingTemplate` according to the file in which they appear.
+- The `ignore_missing` option ignores all occurrences of `MissingTemplate` based on the target template, the template being rendered.
 
 For example:
 
@@ -42,7 +43,7 @@ MissingTemplate:
   - icon-*
 ```
 
-Would ignore offenses on `{% render 'icon-missing' %}` across app files.
+This configuration ignores offenses on `{% render 'icon-missing' %}` across all app files.
 
 ```yaml
 MissingTemplate:
@@ -50,11 +51,11 @@ MissingTemplate:
   - modules/private-module/index.liquid
 ```
 
-Would ignore all `MissingTemplate` in `modules/private-module/index.liquid`, no mater the file being rendered.
+This configuration ignores all `MissingTemplate` offenses in `modules/private-module/index.liquid`, regardless of the file being rendered.
 
 ## 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/parse_json_format.md

@@ -1,16 +1,12 @@
-# Prevent unformatted parse_json tags (`ParseJsonFormat`)
+# 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.
+This check ensures that the JSON in your `parse_json` tags is properly formatted (pretty) for better readability. It facilitates auto-correction, allowing you to right-click and fix formatting issues easily.
 
 ## 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:
 
-### ✗ Fail
+### ✗ Incorrect Code Example (Avoid using this):
 
 ```liquid
 {% parse_json my_json %}
@@ -25,7 +21,7 @@ The following examples contain code snippets that either fail or pass this check
 {% endparse_json %}
 ```
 
-### ✓ Pass
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% parse_json my_json %}
@@ -44,9 +40,9 @@ The following examples contain code snippets that either fail or pass this check
 {% endparse_json %}
 ```
 
-## Options
+## Configuration Options
 
-The following example contains the default configuration for this check:
+The default configuration for this check:
 
 ```yaml
 ParseJsonFormat:
@@ -60,12 +56,17 @@ ParseJsonFormat:
 | --- | --- |
 | 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. |
+| start_level | The base indentation level. Set this to 1 if you prefer an indented `parse_json`. |
 | 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.
+## Disabling This Check
+
+This check is safe to disable if you do not care about the visual formatting of your `parse_json` tags.
+
+## Version
+
+This check has been introduced in platformOS Check 1.9.0.
 
 ## Resources
 

data/docs/checks/parser_blocking_javascript.md

@@ -1,16 +1,21 @@
-# Discourage use of parser-blocking JavaScript (`ParserBlockingJavaScript`)
+# 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.
+This check aims to eliminate parser-blocking JavaScript in your app.
 
-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.
+Using the `defer` or `async` attributes is 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_. This can create network congestion, interfere with resource priorities, and significantly delay page rendering.
 
-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.
+JavaScript in platformOS apps should always be used to progressively _enhance_ the user experience. Therefore, parser-blocking script tags should never be used.
 
-## Check Details
+As a general rule:
+- Use `defer` if the order of execution matters.
+- Use `async` if the order of execution does not matter.
+- When in doubt, using either will provide 80/20 of the benefits.
 
-This check is aimed at eliminating parser-blocking JavaScript on app.
+## 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
 <!-- The script_tag filter outputs a parser-blocking script -->
@@ -27,7 +32,7 @@ This check is aimed at eliminating parser-blocking JavaScript on app.
 </script>
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 <!-- Good. Using the asset_url filter + defer -->
@@ -67,24 +72,24 @@ This check is aimed at eliminating parser-blocking JavaScript on app.
 <button id="thing">Click Me</button>
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 ParserBlockingJavaScript:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-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.
+This check should only be disabled with the `platformos-check-disable` comment if there is no better way to achieve the desired outcome than using a parser-blocking script.
 
-It is discouraged to turn this rule off.
+Disabling this check is generally not recommended.
 
 ## 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/required_layout_object.md

@@ -1,12 +1,10 @@
-# Prevent missing required objects in layouts (`RequiredLayoutThemeObject`)
+# Prevent Missing Required Objects in Layouts (`RequiredLayoutThemeObject`)
 
-## Check Details
+This check ensures that the `{{ content_for_layout }}` object is present in layouts, preventing rendering issues due to missing objects.
 
-This check prevents missing `{{ content_for_layout }}` objects in layouts.
+## Configuration Options
 
-## Check Options
-
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 RequiredLayoutObject:
@@ -15,7 +13,7 @@ RequiredLayoutObject:
 
 ## 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/space_inside_braces.md

@@ -1,12 +1,12 @@
-# Ensure consistent spacing inside Liquid tags and variables (`SpaceInsideBraces`)
+# Ensure Consistent Spacing Inside Liquid Tags and Variables (`SpaceInsideBraces`)
 
-Warns against inconsistent spacing inside liquid tags and variables.
+This check warns against and aims to eliminate inconsistent spacing inside Liquid tags and variables, ensuring cleaner and more readable Liquid code.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating ugly Liquid:
+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
 <!-- Around braces -->
@@ -27,7 +27,7 @@ This check is aimed at eliminating ugly Liquid:
 {%- if product.featured_media.width >=165 -%}
 ```
 
-:+1: Examples of **correct** code for this check:
+### &#x2713; Correct Code Example (Use this instead):
 
 ```liquid
 {% assign x = 1 %}
@@ -47,9 +47,9 @@ This check is aimed at eliminating ugly Liquid:
 {%- if product.featured_media.width >= 165 -%}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 SpaceInsideBraces:
@@ -58,7 +58,7 @@ SpaceInsideBraces:
 
 ## Auto-correction
 
-This check can automatically trim or add spaces around `{{ ... }}`.
+This check can automatically correct spacing around `{{ ... }}`. For example:
 
 ```liquid
 {{ x}}
@@ -72,13 +72,13 @@ Can all be auto-corrected with the `--auto-correct` option to:
 {{ x }}
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-If you don't care about the look of your code.
+This check is safe to disable if you do not prioritize the visual consistency of your code.
 
 ## 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/syntax_error.md

@@ -1,12 +1,12 @@
 # Prevent Syntax Errors (`SyntaxError`)
 
-This check exists to inform the user of Liquid syntax error earlier.
+This check helps inform the user of Liquid syntax errors early, aiming to eliminate syntax errors in Liquid code.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating syntax errors.
+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
 {% include 'muffin'
@@ -15,7 +15,7 @@ This check is aimed at eliminating syntax errors.
 {% if collection | size > 0 %}
 ```
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```liquid
 {% include 'muffin' %}
@@ -23,22 +23,22 @@ This check is aimed at eliminating syntax errors.
 {% if collection.size > 0 %}
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 SyntaxError:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-It is not safe to disable this rule.
+Disabling this check is not recommended.
 
 ## 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/template_length.md

@@ -1,22 +1,22 @@
-# Discourage the use of large template files (`TemplateLength`)
+# Discourage the Use of Large Template Files (`TemplateLength`)
 
-This check exists to discourage the use of large template files. Use partials and functions to componentize your app.
+This check aims to eliminate the use of large template files by encouraging a modular approach - using partials and functions to componentize your app instead.
 
-## Check Details
+## Examples
 
-This check is aimed at eliminating large template files.
+The following examples show code snippets that either fail or pass this check:
 
-:-1: Examples of **incorrect** code for this check:
+### ✗ Incorrect Example (Avoid using this):
 
 - Files that have more lines than the threshold
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Example (Use this instead):
 
 - Files that have less lines than the threshold
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 TemplateLength:
@@ -26,15 +26,15 @@ TemplateLength:
 
 ### `max_length`
 
-The `max_length` (Default: `200`) option determines the maximum number of lines allowed inside a liquid file.
+The `max_length` (Default: `600`) option determines the maximum number of lines allowed inside a liquid file.
 
-## When Not To Use It
+## Disabling This Check
 
-If you don't care about template lengths, then it's safe to disable this rule.
+This check is safe to disable if you do not prioritize template length management.
 
 ## 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/translation_files_match.md

@@ -1,12 +1,12 @@
 # Translation Files Match (`TranslationFilesMatch`)
 
-Checks if translation files for different language have the same keys.
+This check ensures that translation files for different languages have the same keys, aiming to avoid inconsistencies, making it easier to spot errors and maintain the code.
 
-## Check Details
+## Examples
 
-This check is aimed at avoiding inconsistences between translation files to avoid errors hard to spot and make maintenance easier.
+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):
 
 ```yaml
 # app/translations/en/item.yml
@@ -25,7 +25,7 @@ This check is aimed at avoiding inconsistences between translation files to avoi
 
 Missing "title" in de/item.yml
 
-:+1: Examples of **correct** code for this check:
+### ✓ Correct Code Example (Use this instead):
 
 ```yaml
 # app/translations/en/item.yml
@@ -43,23 +43,22 @@ Missing "title" in de/item.yml
         description: "Beschreibung"
 ```
 
-## Check Options
+## Configuration Options
 
-The default configuration for this check is the following:
+The default configuration for this check:
 
 ```yaml
 TranslationFilesMatch:
   enabled: true
 ```
 
-## When Not To Use It
+## Disabling This Check
 
-There should be no cases where disabling this rule is needed. For keys that are set via UI, and hence should not be part of the codebase,
-use proper configuration option in [app/config.yml](https://documentation.platformos.com/developer-guide/platformos-workflow/codebase/config)
+There should be no need to disable this rule. For keys set via the UI and not intended to be part of the codebase, use the appropriate configuration option in [app/config.yml](https://documentation.platformos.com/developer-guide/platformos-workflow/codebase/config).
 
 ## Version
 
-This check has been introduced in PlatformOS Check 0.4.10.
+This check has been introduced in platformOS Check 0.4.10.
 
 ## Resources