platformos-check 0.4.12 → 0.4.14

Sign up to get free protection for your applications and to get access to all the features.
Files changed (58) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +11 -0
  3. data/CONTRIBUTING.md +20 -18
  4. data/README.md +108 -57
  5. data/RELEASING.md +14 -7
  6. data/TROUBLESHOOTING.md +19 -10
  7. data/data/platformos_liquid/documentation/filters.json +1 -1
  8. data/data/platformos_liquid/documentation/latest.json +1 -1
  9. data/data/platformos_liquid/documentation/tags.json +1 -1
  10. data/docs/api/check.md +7 -6
  11. data/docs/api/html_check.md +12 -13
  12. data/docs/api/liquid_check.md +17 -21
  13. data/docs/api/yaml_check.md +3 -3
  14. data/docs/checks/TEMPLATE.md.erb +16 -11
  15. data/docs/checks/convert_include_to_render.md +29 -13
  16. data/docs/checks/deprecated_filter.md +5 -9
  17. data/docs/checks/form_action.md +12 -12
  18. data/docs/checks/form_authenticity_token.md +21 -15
  19. data/docs/checks/graphql_in_for_loop.md +15 -13
  20. data/docs/checks/html_parsing_error.md +12 -12
  21. data/docs/checks/img_lazy_loading.md +13 -11
  22. data/docs/checks/img_width_and_height.md +21 -23
  23. data/docs/checks/include_in_render.md +11 -11
  24. data/docs/checks/invalid_args.md +11 -11
  25. data/docs/checks/liquid_tag.md +12 -12
  26. data/docs/checks/missing_enable_comment.md +7 -7
  27. data/docs/checks/missing_template.md +14 -13
  28. data/docs/checks/parse_json_format.md +15 -14
  29. data/docs/checks/parser_blocking_javascript.md +19 -14
  30. data/docs/checks/required_layout_object.md +5 -7
  31. data/docs/checks/space_inside_braces.md +12 -12
  32. data/docs/checks/syntax_error.md +10 -10
  33. data/docs/checks/template_length.md +12 -12
  34. data/docs/checks/translation_files_match.md +10 -11
  35. data/docs/checks/translation_key_exists.md +10 -11
  36. data/docs/checks/undefined_object.md +11 -13
  37. data/docs/checks/unknown_filter.md +11 -11
  38. data/docs/checks/unreachable_code.md +11 -11
  39. data/docs/checks/unused_assign.md +11 -11
  40. data/docs/checks/unused_partial.md +7 -11
  41. data/docs/checks/valid_yaml.md +11 -11
  42. data/docs/language_server/how_to_correct_code_with_code_actions_and_execute_command.md +62 -70
  43. data/lib/platformos_check/app.rb +23 -14
  44. data/lib/platformos_check/app_file.rb +25 -4
  45. data/lib/platformos_check/asset_file.rb +1 -1
  46. data/lib/platformos_check/file_system_storage.rb +1 -1
  47. data/lib/platformos_check/form_file.rb +1 -1
  48. data/lib/platformos_check/graphql_file.rb +1 -1
  49. data/lib/platformos_check/language_server/completion_context.rb +2 -0
  50. data/lib/platformos_check/language_server/handler.rb +6 -6
  51. data/lib/platformos_check/language_server/variable_lookup_finder.rb +8 -10
  52. data/lib/platformos_check/layout_file.rb +1 -1
  53. data/lib/platformos_check/partial_file.rb +1 -1
  54. data/lib/platformos_check/platformos_liquid/documentation.rb +2 -2
  55. data/lib/platformos_check/translation_file.rb +1 -1
  56. data/lib/platformos_check/version.rb +1 -1
  57. data/platformos-check.gemspec +1 -1
  58. metadata +5 -5
@@ -1,28 +1,28 @@
1
1
  # Check Title (`<%= class_name %>`)
2
2
 
3
- _Version PLATFORMOS_CHECK_VERSION+_
3
+ [A short description of what the check does.]
4
4
 
5
- A short description of what the check does.
6
-
7
- A brief paragraph explaining why the check exists (what best practice is it enforcing, and why is it important?).
5
+ [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.]
8
6
 
9
7
  ## Examples
10
8
 
11
- The following examples contain code snippets that either fail or pass this check.
9
+ The following examples show code snippets that either fail or pass this check:
12
10
 
13
- ### &#x2717; Fail
11
+ ### &#x2717; Incorrect Code Example (Avoid using this):
14
12
 
15
13
  ```liquid
14
+ <!-- Add an example of incorrect code here -->
16
15
  ```
17
16
 
18
- ### &#x2713; Pass
17
+ ### &#x2713; Correct Code Example (Use this instead):
19
18
 
20
19
  ```liquid
20
+ <!-- Add an example of correct code here -->
21
21
  ```
22
22
 
23
- ## Options
23
+ ## Configuration Options
24
24
 
25
- The following example contains the default configuration for this check:
25
+ The default configuration for this check:
26
26
 
27
27
  ```yaml
28
28
  <%= class_name %>:
@@ -39,9 +39,14 @@ The following example contains the default configuration for this check:
39
39
 
40
40
  ## Disabling this check
41
41
 
42
- [ This check is safe to disable. You might want to disable this check if ... | Disabling this check isn't recommended because ... ].
42
+ [This check is safe to disable if ... ]
43
+ [You might want to disable this check if ...]
44
+ [Disabling this check is not recommended, because ...]
45
+ [This check is disabled by default when <condition>.]
46
+
47
+ ## Version
43
48
 
44
- [ This check is disabled by default when <condition>. ]
49
+ This check has been introduced in platformOS Check [x.x.x.]
45
50
 
46
51
  ## Resources
47
52
 
@@ -1,41 +1,57 @@
1
- # Discourage the use of `include` (`ConvertIncludeToRender`)
1
+ # Discourage the Use of `include` (`ConvertIncludeToRender`)
2
2
 
3
- The `include` tag is [deprecated][deprecated]. This tag exists to enforce the use of the `render` tag instead of `include`.
3
+ 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.
4
4
 
5
- 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.
6
5
 
7
- ## Check Details
6
+ ## Why Use `render` instead of `include`
8
7
 
9
- This check is aimed at eliminating the use of `include` tags.
8
+ 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.
10
9
 
11
- :-1: Examples of **incorrect** code for this check:
10
+ ## Examples
11
+
12
+ The following examples show code snippets that either fail or pass this check:
13
+
14
+ ### &#x2717; Incorrect Code Example (Avoid using this):
12
15
 
13
16
  ```liquid
14
17
  {% include 'snippet' %}
15
18
  ```
16
19
 
17
- :+1: Examples of **correct** code for this check:
20
+ ### &#x2713; Correct Code Example (Use this instead):
18
21
 
19
22
  ```liquid
20
23
  {% render 'snippet' %}
21
24
  ```
22
25
 
23
- ## Check Options
26
+ ## Configuration Options
24
27
 
25
- The default configuration for this check is the following:
28
+ The default configuration for this check:
26
29
 
27
30
  ```yaml
28
31
  ConvertIncludeToRender:
29
32
  enabled: true
30
33
  ```
31
34
 
32
- ## When Not To Use It
35
+ ## Disabling This Check - When Not To Use It
36
+
37
+ ### Using Variable Partial Names
38
+
39
+ 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.
40
+ Here's how you can use the include tag for this specific scenario:
41
+
42
+ ```liquid
43
+ {% liquid
44
+ # platformos-check-disable ConvertIncludeToRender
45
+ include my_variable
46
+ # platformos-check-enable ConvertIncludeToRender
47
+ %}
48
+ ```
33
49
 
34
- It is discouraged to disable this rule.
50
+ This example shows how to temporarily disable the check when you need to use `include` specifically for variable partial names.
35
51
 
36
52
  ## Version
37
53
 
38
- This check has been introduced in PlatformOS Check 0.0.1.
54
+ This check has been introduced in platformOS Check 0.0.1.
39
55
 
40
56
  ## Resources
41
57
 
@@ -45,4 +61,4 @@ This check has been introduced in PlatformOS Check 0.0.1.
45
61
 
46
62
  [deprecated]: https://documentation.platformos.com/api-reference/liquid/include
47
63
  [codesource]: /lib/platformos_check/checks/convert_include_to_render.rb
48
- [docsource]: /docs/checks/convert_include_to_render.md
64
+ [docsource]: /docs/checks/convert_include_to_render.md
@@ -1,14 +1,10 @@
1
- # Discourage use of deprecated filters (`DeprecatedFilter`)
1
+ # Discourage The Use of Deprecated filters (`DeprecatedFilter`)
2
2
 
3
- This check discourages the use of [deprecated filters][deprecated].
3
+ This check discourages the use of [deprecated filters][deprecated] and aims at eliminating them.
4
4
 
5
- ## Check Details
5
+ ## Configuration Options
6
6
 
7
- This check is aimed at eliminating deprecated filters.
8
-
9
- ## Check Options
10
-
11
- The default configuration for this check is the following:
7
+ The default configuration for this check:
12
8
 
13
9
  ```yaml
14
10
  DeprecatedFilter:
@@ -17,7 +13,7 @@ DeprecatedFilter:
17
13
 
18
14
  ## Version
19
15
 
20
- This check has been introduced in PlatformOS Check 0.1.0.
16
+ This check has been introduced in platformOS Check 0.1.0.
21
17
 
22
18
  ## Resources
23
19
 
@@ -1,14 +1,14 @@
1
- # Form action (`FormAction`)
1
+ # Form Action (`FormAction`)
2
2
 
3
- Form action defines the endpoint to which browser will make a request after submitting it.
3
+ 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.
4
4
 
5
- As a general rule you should use relative path like `action="/my/path"` instead of for example `action="my/path"` to avoid errors.
5
+ This check ensures that the path correctly begins with a forward slash (`/`), which means it always refers to the root directory.
6
6
 
7
- ## Check Details
7
+ ## Examples
8
8
 
9
- This check is aimed at ensuring you have not forgotten to start the path with /.
9
+ The following examples show code snippets that either fail or pass this check:
10
10
 
11
- :-1: Examples of **incorrect** code for this check:
11
+ ### &#x2717; Incorrect Code Example (Avoid using this):
12
12
 
13
13
  ```liquid
14
14
  <form action="dummy/create">
@@ -16,7 +16,7 @@ This check is aimed at ensuring you have not forgotten to start the path with /.
16
16
  </form>
17
17
  ```
18
18
 
19
- :+1: Examples of **correct** code for this check:
19
+ ### &#x2713; Correct Code Example (Use this instead):
20
20
 
21
21
  ```liquid
22
22
  <form action="/dummy/create">
@@ -36,22 +36,22 @@ This check is aimed at ensuring you have not forgotten to start the path with /.
36
36
  </form>
37
37
  ```
38
38
 
39
- ## Check Options
39
+ ## Configuration Options
40
40
 
41
- The default configuration for this check is the following:
41
+ The default configuration for this check:
42
42
 
43
43
  ```yaml
44
44
  FormAction:
45
45
  enabled: true
46
46
  ```
47
47
 
48
- ## When Not To Use It
48
+ ## Disabling This Check
49
49
 
50
- There should be no cases where disabling this rule is needed.
50
+ Disabling this check is not recommended.
51
51
 
52
52
  ## Version
53
53
 
54
- This check has been introduced in PlatformOS Check 0.4.5.
54
+ This check has been introduced in platformOS Check 0.4.5.
55
55
 
56
56
  ## Resources
57
57
 
@@ -1,22 +1,29 @@
1
- # Form authenticity token (`FormAuthenticityToken`)
1
+ # Form Authenticity Token (`FormAuthenticityToken`)
2
2
 
3
- In platformOS all POST/PATCH/PUT/DELETE requests are protected from [CSRF Attacks][csrf-attack] through [authenticity_token][page-csrf]
4
- Form action defines the endpoint to which browser will make a request after submitting it.
3
+ This check ensures that the `authenticity_token` is included in each form to keep the session safe and protect against CSRF.
5
4
 
6
- 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.
5
+ 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.
7
6
 
8
- ## Check Details
7
+ It's important to add a hidden input field with the authenticity token in every form. The tag should look like this:
9
8
 
10
- This check is aimed at ensuring you have not forgotten to include authenticity_token in a form.
9
+ ```liquid
10
+ <input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}">
11
+ ```
12
+
13
+ If this token is missing from a form, the session will end and the user will be logged out automatically.
11
14
 
12
- :-1: Examples of **incorrect** code for this check:
15
+ ## Examples
16
+
17
+ The following examples show code snippets that either fail or pass this check:
18
+
19
+ ### &#x2717; Incorrect Code Example (Avoid using this):
13
20
 
14
21
  ```liquid
15
22
  <form action="/dummy/create" method="post">
16
23
  </form>
17
24
  ```
18
25
 
19
- :+1: Examples of **correct** code for this check:
26
+ ### &#x2713; Correct Code Example (Use this instead):
20
27
 
21
28
  With token:
22
29
  ```liquid
@@ -43,22 +50,22 @@ For parameterized request:
43
50
  </form>
44
51
  ```
45
52
 
46
- ## Check Options
53
+ ## Configuration Options
47
54
 
48
- The default configuration for this check is the following:
55
+ The default configuration for this check:
49
56
 
50
57
  ```yaml
51
58
  FormAuthenticityToken:
52
59
  enabled: true
53
60
  ```
54
61
 
55
- ## When Not To Use It
62
+ ## Disabling This Check
56
63
 
57
- There should be no cases where disabling this rule is needed.
64
+ Disabling this check is not recommended.
58
65
 
59
66
  ## Version
60
67
 
61
- This check has been introduced in PlatformOS Check 0.4.6.
68
+ This check has been introduced in platformOS Check 0.4.6.
62
69
 
63
70
  ## Resources
64
71
 
@@ -70,5 +77,4 @@ This check has been introduced in PlatformOS Check 0.4.6.
70
77
  [codesource]: /lib/platformos_check/checks/form_authenticity_token.rb
71
78
  [docsource]: /docs/checks/form_authenticity_token.md
72
79
  [page-csrf]: https://documentation.platformos.com/developer-guide/pages/pages#post-put-patch-delete-methods-and-cross-site-request-forgery-attacks
73
- [csrf-attack]: https://owasp.org/www-community/attacks/csrf
74
-
80
+ [csrf-attack]: https://owasp.org/www-community/attacks/csrf
@@ -1,16 +1,18 @@
1
- # GraphQL in for loop (`GraphqlInForLoop`)
1
+ # GraphQL in For Loop (`GraphqlInForLoop`)
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
- 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].
7
+ 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.
8
8
 
9
- ## Check Details
9
+ 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].
10
10
 
11
- This check is aimed towards identifying GraphQL queries invoked within a for loop.
11
+ ## Examples
12
12
 
13
- :-1: Examples of **incorrect** code for this check:
13
+ The following examples show code snippets that either fail or pass this check:
14
+
15
+ ### &#x2717; Incorrect Code Example (Avoid using this):
14
16
 
15
17
  ```liquid
16
18
  {% assign arr = 'a,b,c' | split: ','}
@@ -21,29 +23,29 @@ This check is aimed towards identifying GraphQL queries invoked within a for loo
21
23
 
22
24
  ```
23
25
 
24
- :+1: Examples of **correct** code for this check:
26
+ ### &#x2713; Correct Code Example (Use this instead):
25
27
 
26
28
  ```liquid
27
29
  {% assign arr = 'a,b,c' | split: ','}
28
30
  {% graphql g = 'my/graphql', arr: arr %}
29
31
  ```
30
32
 
31
- ## Check Options
33
+ ## Configuration Options
32
34
 
33
- The default configuration for this check is the following:
35
+ The default configuration for this check:
34
36
 
35
37
  ```yaml
36
38
  GraphqlInForLoop:
37
39
  enabled: true
38
40
  ```
39
41
 
40
- ## When Not To Use It
42
+ ## Disabling This Check
41
43
 
42
- 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.
44
+ 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.
43
45
 
44
46
  ## Version
45
47
 
46
- This check has been introduced in PlatformOS Check 0.4.9.
48
+ This check has been introduced in platformOS Check 0.4.9.
47
49
 
48
50
  ## Resources
49
51
 
@@ -1,14 +1,14 @@
1
- # Report HTML parsing errors (`HtmlParsingError`)
1
+ # Report HTML Parsing Errors (`HtmlParsingError`)
2
2
 
3
- Report errors preventing the HTML from being parsed and analyzed by PlatformOS Check.
3
+ 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.
4
4
 
5
- ## Check Details
5
+ 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.
6
6
 
7
- This check is aimed at reporting HTML errors that prevent a file from being analyzed.
7
+ ## Examples
8
8
 
9
- 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.
9
+ The following examples show code snippets that either fail or pass this check:
10
10
 
11
- :-1: Examples of **incorrect** code for this check:
11
+ ### &#x2717; Incorrect Code Example (Avoid using this):
12
12
 
13
13
  ```liquid
14
14
  <img src="muffin.jpeg"
@@ -18,28 +18,28 @@ The HTML parser limits the number of attributes per element to 400, and the maxi
18
18
  data-attrbute-400="">
19
19
  ```
20
20
 
21
- :+1: Examples of **correct** code for this check:
21
+ ### &#x2713; Correct Code Example (Use this instead):
22
22
 
23
23
  ```liquid
24
24
  <img src="muffin.jpeg">
25
25
  ```
26
26
 
27
- ## Check Options
27
+ ## Configuration Options
28
28
 
29
- The default configuration for this check is the following:
29
+ The default configuration for this check:
30
30
 
31
31
  ```yaml
32
32
  HtmlParsingError:
33
33
  enabled: true
34
34
  ```
35
35
 
36
- ## When Not To Use It
36
+ ## Disabling This Check
37
37
 
38
- If you don't care about HTML offenses.
38
+ This check is safe to disable if identifying HTML errors is not a priority.
39
39
 
40
40
  ## Version
41
41
 
42
- This check has been introduced in PlatformOS Check 0.0.1.
42
+ This check has been introduced in platformOS Check 0.0.1.
43
43
 
44
44
  ## Resources
45
45
 
@@ -1,4 +1,6 @@
1
- # Lazy loading image tags (`ImgLazyLoading`)
1
+ # Lazy Loading Image Tags (`ImgLazyLoading`)
2
+
3
+ This check is designed to ensure that non-critical images are deferred for loading, improving page load times and overall performance.
2
4
 
3
5
  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.
4
6
 
@@ -8,13 +10,13 @@ Very often, webpages contain many images that contribute to data-usage and how f
8
10
 
9
11
  _Quoted from [MDN - Lazy loading][mdn]_
10
12
 
11
- 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.
13
+ 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.
12
14
 
13
- ## Check Details
15
+ ## Examples
14
16
 
15
- This check is aimed at deferring loading non-critical images.
17
+ The following examples show code snippets that either fail or pass this check:
16
18
 
17
- :-1: Examples of **incorrect** code for this check:
19
+ ### &#x2717; Incorrect Code Example (Avoid using this):
18
20
 
19
21
  ```liquid
20
22
  <img src="a.jpg">
@@ -26,7 +28,7 @@ This check is aimed at deferring loading non-critical images.
26
28
  <img src="a.jpg" loading="auto">
27
29
  ```
28
30
 
29
- :+1: Examples of **correct** code for this check:
31
+ ### &#x2713; Correct Code Example (Use this instead):
30
32
 
31
33
  ```liquid
32
34
  <img src="a.jpg" loading="lazy">
@@ -35,22 +37,22 @@ This check is aimed at deferring loading non-critical images.
35
37
  <img src="a.jpg" loading="eager">
36
38
  ```
37
39
 
38
- ## Check Options
40
+ ## Configuration Options
39
41
 
40
- The default configuration for this check is the following:
42
+ The default configuration for this check:
41
43
 
42
44
  ```yaml
43
45
  ImgLazyLoading:
44
46
  enabled: true
45
47
  ```
46
48
 
47
- ## When Not To Use It
49
+ ## Disabling This Check
48
50
 
49
- 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.
51
+ 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.
50
52
 
51
53
  ## Version
52
54
 
53
- This check has been introduced in PlatformOS Check 0.10.0.
55
+ This check has been introduced in platformOS Check 0.10.0.
54
56
 
55
57
  ## Resources
56
58
 
@@ -1,23 +1,23 @@
1
1
  # Width and height attributes on image tags (`ImgWidthAndHeight`)
2
2
 
3
- This check exists to prevent [cumulative layout shift][cls] (CLS) in themes.
3
+ 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.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
- This has numerous nefarious implications:
7
+ This leads to several problems:
8
8
 
9
- 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.
10
- 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!
9
+ 1. [Layout shift occurs as images load][codepenshift]. Text and other content get pushed down the page as the images load one after another.
10
+ 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.
11
11
 
12
- 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.
12
+ 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.
13
13
 
14
- Note: The width and height attributes of an image do not have units.
14
+ **Note:** The `width` and `height` attributes should not include units.
15
15
 
16
- ## Check Details
16
+ ## Examples
17
17
 
18
- This check is aimed at eliminating content layout shift in themes by enforcing the use of the `width` and `height` attributes on `img` tags.
18
+ The following examples show code snippets that either fail or pass this check:
19
19
 
20
- :-1: Examples of **incorrect** code for this check:
20
+ ### &#x2717; Incorrect Code Example (Avoid using this):
21
21
 
22
22
  ```liquid
23
23
  <img alt="cat" src="cat.jpg">
@@ -25,7 +25,7 @@ This check is aimed at eliminating content layout shift in themes by enforcing t
25
25
  <img alt="{{ image.alt }}" src="{{ image.src }}">
26
26
  ```
27
27
 
28
- :+1: Examples of **correct** code for this check:
28
+ ### &#x2713; Correct Code Example (Use this instead):
29
29
 
30
30
  ```liquid
31
31
  <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
39
39
 
40
40
  **NOTE:** The CSS `width` of the `img` should _also_ be set for the image to be responsive.
41
41
 
42
- ## Check Options
42
+ ## Configuration Options
43
43
 
44
- The default configuration for this check is the following:
44
+ The default configuration for this check:
45
45
 
46
46
  ```yaml
47
47
  ImgWidthAndHeight:
48
48
  enabled: true
49
49
  ```
50
50
 
51
- ## When Not To Use It
51
+ ## Disabling This Check - When Not To Use It
52
52
 
53
- There are some cases where you can avoid content-layout shift without needing the width and height attributes:
53
+ You can avoid content layout shift without `width` and `height` attributes in certain cases:
54
54
 
55
- - 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`.
56
- - When you are happy with the padding-top hack.
55
+ - 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.
56
+ - When you are satisfied with the padding-top hack.
57
57
 
58
- In those cases, it is fine to disable this check with the comment.
59
-
60
- It is otherwise unwise to disable this check, since it would negatively impact the mobile search ranking of the merchants using your theme.
58
+ Otherwise, it’s unwise to disable this check as it can negatively impact the mobile search ranking of the merchants using your platformOS application.
61
59
 
62
60
  ## Version
63
61
 
64
- This check has been introduced in PlatformOS Check 0.6.0.
62
+ This check has been introduced in platformOS Check 0.6.0.
65
63
 
66
64
  ## Resources
67
65
 
@@ -75,5 +73,5 @@ This check has been introduced in PlatformOS Check 0.6.0.
75
73
  [codepenshift]: https://codepen.io/charlespwd/pen/YzpxPEp?editors=1100
76
74
  [codepenlazy]: https://codepen.io/charlespwd/pen/abZmqXJ?editors=0111
77
75
  [aspect-ratio]: https://caniuse.com/mdn-css_properties_aspect-ratio
78
- [codesource]: /lib/platformos_check/checks/img_aspect_ratio.rb
79
- [docsource]: /docs/checks/img_aspect_ratio.md
76
+ [codesource]: /lib/platformos_check/checks/img_width_and_height.rb
77
+ [docsource]: /docs/checks/img_width_and_height.md
@@ -1,12 +1,12 @@
1
- # Reports usage of `include` tag inside `render` (`IncludeInRender`)
1
+ # Report usage of `include` tag inside `render` (`IncludeInRender`)
2
2
 
3
- Runtime error is used when `include` tag is used inside `render` tag.
3
+ A runtime error occurs when an `include` tag is used inside a `render` tag. This check aims to eliminate and report these occurrences.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at eliminating the use of `include` tags `render` tag.
7
+ The following examples show code snippets that either fail or pass this check:
8
8
 
9
- :-1: Examples of **incorrect** code for this check:
9
+ ### &#x2717; Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  {% liquid
@@ -20,7 +20,7 @@ This check is aimed at eliminating the use of `include` tags `render` tag.
20
20
  %}
21
21
  ```
22
22
 
23
- :+1: Examples of **correct** code for this check:
23
+ ### &#x2713; Correct Code Example (Use this instead):
24
24
 
25
25
  ```liquid
26
26
  {% liquid
@@ -34,22 +34,22 @@ This check is aimed at eliminating the use of `include` tags `render` tag.
34
34
  %}
35
35
  ```
36
36
 
37
- ## Check Options
37
+ ## Configuration Options
38
38
 
39
- The default configuration for this check is the following:
39
+ The default configuration for this check:
40
40
 
41
41
  ```yaml
42
42
  IncludeInRender:
43
43
  enabled: true
44
44
  ```
45
45
 
46
- ## When Not To Use It
46
+ ## Disabling This Check
47
47
 
48
- It is discouraged to disable this rule.
48
+ Disabling this check is not recommended.
49
49
 
50
50
  ## Version
51
51
 
52
- This check has been introduced in PlatformOS Check 0.4.9.
52
+ This check has been introduced in platformOS Check 0.4.9.
53
53
 
54
54
  ## Resources
55
55