platformos-check 0.4.12 → 0.4.13

Sign up to get free protection for your applications and to get access to all the features.
Files changed (48) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +6 -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/language_server/handler.rb +6 -6
  44. data/lib/platformos_check/language_server/variable_lookup_finder.rb +8 -10
  45. data/lib/platformos_check/platformos_liquid/documentation.rb +2 -2
  46. data/lib/platformos_check/version.rb +1 -1
  47. data/platformos-check.gemspec +1 -1
  48. metadata +5 -5
data/docs/checks/translation_key_exists.md CHANGED
@@ -1,39 +1,38 @@
1
1
  # Translation Key Exists (`TranslationKeyExists`)
2
2
 
3
- Checks if translation key is defined in the default language
3
+ This check ensures that translation keys are defined in the default language, aiming to prevent missing translation errors.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at avoiding missing translation error.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  {{ 'undefined.key' | t }}
13
13
  ```
14
14
 
15
- :+1: Examples of **correct** code for this check:
15
+ ### ✓ Correct Code Example (Use this instead):
16
16
 
17
17
  ```liquid
18
18
  {{ 'defined.key' | t }}
19
19
 
20
- ## Check Options
20
+ ## Configuration Options
21
21
 
22
- The default configuration for this check is the following:
22
+ The default configuration for this check:
23
23
 
24
24
  ```yaml
25
25
  TranslationKeyExists:
26
26
  enabled: true
27
27
  ```
28
28
 
29
- ## When Not To Use It
29
+ ## Disabling This Check
30
30
 
31
- 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,
32
- use proper configuration option in [app/config.yml](https://documentation.platformos.com/developer-guide/platformos-workflow/codebase/config)
31
+ 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).
33
32
 
34
33
  ## Version
35
34
 
36
- This check has been introduced in PlatformOS Check 0.4.10.
35
+ This check has been introduced in platformOS Check 0.4.10.
37
36
 
38
37
  ## Resources
39
38
 
data/docs/checks/undefined_object.md CHANGED
@@ -1,12 +1,12 @@
1
- # Prevent undefined object errors (`UndefinedObject`)
1
+ # Prevent Undefined Object Errors (`UndefinedObject`)
2
2
 
3
- This check prevents errors by making sure that no undefined variables are being used
3
+ This check ensures that no undefined variables are used, preventing errors in your Liquid code. It aims to eliminate undefined object errors and additionally reports any missing or unused attributes in `render`, `function`, and `background` tags.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at eliminating undefined object errors. Additionally it reports any missing or unused attributes in render, function and background tags.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  {% if greeting == "Hello" %}
@@ -14,7 +14,7 @@ This check is aimed at eliminating undefined object errors. Additionally it repo
14
14
  {% endif %}
15
15
  ```
16
16
 
17
- :+1: Examples of **correct** code for this check:
17
+ ### ✓ Correct Code Example (Use this instead):
18
18
 
19
19
  ```liquid
20
20
  {% assign greetings = "Hello" %}
@@ -35,24 +35,22 @@ This check is aimed at eliminating undefined object errors. Additionally it repo
35
35
  %}
36
36
  ```
37
37
 
38
+ ## Configuration Options
38
39
 
39
-
40
- ## Check Options
41
-
42
- The default configuration for this check is the following:
40
+ The default configuration for this check:
43
41
 
44
42
  ```yaml
45
43
  UndefinedObject:
46
44
  enabled: true
47
45
  ```
48
46
 
49
- ## When Not To Use It
47
+ ## Disabling This Check
50
48
 
51
- It is discouraged to disable this rule.
49
+ Disabling this check is not recommended.
52
50
 
53
51
  ## Version
54
52
 
55
- This check has been introduced in Theme Check 0.1.0.
53
+ This check has been introduced in platformOS Check 0.1.0.
56
54
 
57
55
  ## Resources
58
56
 
data/docs/checks/unknown_filter.md CHANGED
@@ -1,39 +1,39 @@
1
- # Prevent use of unknown filters (`UnknownFilter`)
1
+ # Prevent Use of Unknown Filters (`UnknownFilter`)
2
2
 
3
- This check exists to prevent user errors.
3
+ This check prevents errors caused by using unknown filters in Liquid code and aims to eliminate the use of such filters.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at preventing the use of unknown filters.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  {{ x | some_unknown_filter }}
13
13
  ```
14
14
 
15
- :+1: Examples of **correct** code for this check:
15
+ ### ✓ Correct Code Example (Use this instead):
16
16
 
17
17
  ```liquid
18
18
  {{ x | upcase }}
19
19
  ```
20
20
 
21
- ## Check Options
21
+ ## Configuration Options
22
22
 
23
- The default configuration for this check is the following:
23
+ The default configuration for this check:
24
24
 
25
25
  ```yaml
26
26
  UnknownFilter:
27
27
  enabled: true
28
28
  ```
29
29
 
30
- ## When Not To Use It
30
+ ## Disabling This Check
31
31
 
32
- It is not safe to disable this rule.
32
+ Disabling this check is not recommended, as it helps prevent user errors.
33
33
 
34
34
  ## Version
35
35
 
36
- This check has been introduced in PlatformOS Check 0.0.1.
36
+ This check has been introduced in platformOS Check 0.0.1.
37
37
 
38
38
  ## Resources
39
39
 
data/docs/checks/unreachable_code.md CHANGED
@@ -1,12 +1,12 @@
1
- # Unreachable code (`UnreachableCode`)
1
+ # Unreachable Code (`UnreachableCode`)
2
2
 
3
- Unreachable code reports code that will never be reached, no matter what.
3
+ This check detects and ensures that you do not accidentally write code that will never be executed because it is unreachable.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at ensuring you will not accidentally write code that will never be reached.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  assign x = "hello"
@@ -23,7 +23,7 @@ This check is aimed at ensuring you will not accidentally write code that will n
23
23
  endif
24
24
  ```
25
25
 
26
- :+1: Examples of **correct** code for this check:
26
+ ### ✓ Correct Code Example (Use this instead):
27
27
 
28
28
  ```liquid
29
29
  assign x = "hello"
@@ -40,22 +40,22 @@ This check is aimed at ensuring you will not accidentally write code that will n
40
40
  endif
41
41
  ```
42
42
 
43
- ## Check Options
43
+ ## Configuration Options
44
44
 
45
- The default configuration for this check is the following:
45
+ The default configuration for this check:
46
46
 
47
47
  ```yaml
48
48
  UnreachableCode:
49
49
  enabled: true
50
50
  ```
51
51
 
52
- ## When Not To Use It
52
+ ## Disabling This Check
53
53
 
54
- There should be no cases where disabling this rule is needed.
54
+ Disabling this check is not recommended.
55
55
 
56
56
  ## Version
57
57
 
58
- This check has been introduced in PlatformOS Check 0.4.7.
58
+ This check has been introduced in platformOS Check 0.4.7.
59
59
 
60
60
  ## Resources
61
61
 
data/docs/checks/unused_assign.md CHANGED
@@ -1,12 +1,12 @@
1
- # Prevent unused assigns (`UnusedAssign`)
1
+ # Prevent Unused Assigns (`UnusedAssign`)
2
2
 
3
- This check exists to prevent bloat in themes by surfacing variable definitions that are not used.
3
+ This check helps prevent bloat in your platformOS application by identifying variable definitions that are not used, aiming to eliminate unnecessary code in apps and highlight user errors.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at eliminating bloat in apps and highlight user errors.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```liquid
12
12
  {% assign this_variable_is_not_used = 1 %}
@@ -16,7 +16,7 @@ This check is aimed at eliminating bloat in apps and highlight user errors.
16
16
  {% function this_variable_is_not_used = 'my_function' %}
17
17
  ```
18
18
 
19
- :+1: Examples of **correct** code for this check:
19
+ ### ✓ Correct Code Example (Use this instead):
20
20
 
21
21
  ```liquid
22
22
  {% assign this_variable_is_used = 1 %}
@@ -37,22 +37,22 @@ This check is aimed at eliminating bloat in apps and highlight user errors.
37
37
  {% function _ignore_this_var = 'my_function' %}
38
38
  ```
39
39
 
40
- ## Check Options
40
+ ## Configuration Options
41
41
 
42
- The default configuration for this check is the following:
42
+ The default configuration for this check:
43
43
 
44
44
  ```yaml
45
45
  UnusedAssign:
46
46
  enabled: true
47
47
  ```
48
48
 
49
- ## When Not To Use It
49
+ ## Disabling This Check
50
50
 
51
- It's safe to disable this rule.
51
+ This check is safe to disable if you do not prioritize eliminating unused variables.
52
52
 
53
53
  ## Version
54
54
 
55
- This check has been introduced in PlatformOS Check 0.0.1.
55
+ This check has been introduced in platformOS Check 0.0.1.
56
56
 
57
57
  ## Resources
58
58
 
data/docs/checks/unused_partial.md CHANGED
@@ -1,27 +1,23 @@
1
- # Remove unused partials in app (`UnusedPartial`)
1
+ # Remove Unused Partials in App (`UnusedPartial`)
2
2
 
3
- This check warns the user about partials that are not used (Could not find a `render` or `function` tag that uses that partial)
3
+ This check warns the user about partials that are not used, specifically when no `render` or `function` tag references the partial, and aims to eliminate these unused partials from your app.
4
4
 
5
- ## Check Details
5
+ ## Configuration Options
6
6
 
7
- This check is aimed at eliminating unused partials.
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
  UnusedPartial:
15
11
  enabled: true
16
12
  ```
17
13
 
18
- ## When Not To Use It
14
+ ## Disabling This Check
19
15
 
20
- It's safe to disable this rule.
16
+ This check is safe to disable if managing unused partials is not a priority.
21
17
 
22
18
  ## Version
23
19
 
24
- This check has been introduced in PlatformOS Check 0.0.1.
20
+ This check has been introduced in platformOS Check 0.0.1.
25
21
 
26
22
  ## Resources
27
23
 
data/docs/checks/valid_yaml.md CHANGED
@@ -1,12 +1,12 @@
1
- # Enforce valid YAML (`ValidYaml`)
1
+ # Enforce Valid YAML (`ValidYaml`)
2
2
 
3
- This check exists to prevent invalid Yaml files in app.
3
+ This check ensures that YAML files in the app are valid and aims to eliminate errors in these files.
4
4
 
5
- ## Check Details
5
+ ## Examples
6
6
 
7
- This check is aimed at eliminating errors in YAML files.
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
+ ### ✗ Incorrect Code Example (Avoid using this):
10
10
 
11
11
  ```yaml
12
12
  ---
@@ -14,7 +14,7 @@ hello: world
14
14
  invalid
15
15
  ```
16
16
 
17
- :+1: Examples of **correct** code for this check:
17
+ ### ✓ Correct Code Example (Use this instead):
18
18
 
19
19
  ```yaml
20
20
  ---
@@ -22,22 +22,22 @@ hello: world
22
22
  invalid:
23
23
  ```
24
24
 
25
- ## Check Options
25
+ ## Configuration Options
26
26
 
27
- The default configuration for this check is the following:
27
+ The default configuration for this check:
28
28
 
29
29
  ```yaml
30
30
  Validyaml:
31
31
  enabled: true
32
32
  ```
33
33
 
34
- ## When Not To Use It
34
+ ## Disabling This Check
35
35
 
36
- It is not safe to disable this rule.
36
+ Disabling this check is not recommended.
37
37
 
38
38
  ## Version
39
39
 
40
- This check has been introduced in PlatformOS Check 0.0.1.
40
+ This check has been introduced in platformOS Check 0.0.1.
41
41
 
42
42
  ## Resources
43
43
 
data/docs/language_server/how_to_correct_code_with_code_actions_and_execute_command.md CHANGED
@@ -1,16 +1,14 @@
1
- # How to correct code with Code Actions, Commands and Workspace Edits
1
+ # How to Correct Code with Code Actions, Commands, and Workspace Edits
2
2
 
3
- The [Language Server Protocol (LSP)][lsp] empowers Language Server developers to offer refactorings, quick fixes and the execution of commands to their users. In PlatformOS Check, we take advantage of this to offer quick fixes and autocorrection to users.
4
-
5
- This document exists to give you an overview of how that works.
3
+ The [Language Server Protocol (LSP)][lsp] empowers Language Server developers to provide tools like refactorings, quick fixes, and command executions to their users. PlatformOS Check utilizes this protocol to offer quick fixes and auto-correction capabilities to users.
6
4
 
7
5
  ## Overview
8
6
 
9
- It goes like this:
7
+ The process of correcting code using platformOS Check:
10
8
 
11
- 1. The Client (VS Code, vim, etc.) asks the Server for [Code Actions](#code-actions) at a character position, and the server responds with available `quickfix` and `source.fixAll` code actions.
12
- 2. The User _may_ select one of the code actions by interacting with the UI (see [visual examples](#code-actions)). The selection triggers the Client to asks the Server to execute a `correction` [Command](#Commands) for certain [Diagnostics](#diagnostic) on behalf of the user.
13
- 3. The Server asks the Client to apply a [Workspace Edit](#workspace-edits) to fix the diagnostics.
9
+ 1. **Request Code Actions**: The Client (e.g., VS Code, vim) requests [Code Actions](#code-actions) from the Server based on the user's current cursor position or selection. The server returns actions categorized as `quickfix` or `source.fixAll`, which are available for the given text location.
10
+ 2. **User Selection**: The user selects a desired code action from the UI (see [visual examples](#code-actions)). This selection asks the Client to send a `correction` request to the Server to execute a specific action based on the identified [Diagnostics](#diagnostic).
11
+ 3. **Apply Edits**: The Server calculates the necessary changes and requests the Client to apply a [Workspace Edit](#workspace-edits) which adjusts the code to resolve the issues.
14
12
 
15
13
  ## Sequence Diagram
16
14
 
@@ -19,64 +17,64 @@ It goes like this:
19
17
  <details>
20
18
  <summary>Sequence Diagram Explanation</summary>
21
19
 
22
- 1. The Client asks the Server for [code actions](#code-actions) for the current file and character range.
23
- 2. The Server responds with a list of code actions that can be applied for this location and character range. (`quickfix` and `source.fixAll`)
24
- 3. ...Wait for user input...
25
- 4. The User selects one of the code actions
26
- 5. The Client sends a `workspace/executeCommand` request to the Server for this code action.
27
- 6. The Server figures out the [workspace edit](#workspace-edits) for the command and arguments.
28
- 7. The Server sends a `workspace/applyEdit` request for the file modifications that would fix the diagnostics.
29
- 8. The Client responds with the status of the `applyEdit`.
30
- 9. The Server cleans up its internal representation of the diagnostics and updates the client with the latest diagnostics.
31
- 11. The Server responds to the `workspace/executeCommand` request.
20
+ 1. **Request Code Actions**: The Client requests [code actions](#code-actions) from the Server, specifying the file and the exact location (character range) within it.
21
+ 2. **Server Response**: The Server responds with available code actions for that location, such as `quickfix` and `source.fixAll`.
22
+ 3. **Awaiting User Input**: The system pauses while waiting for the user to select a desired code action.
23
+ 4. **User Selection**: The User chooses a code action from the provided options.
24
+ 5. **Execute Command**: Following the selection, the Client requests the Server to execute the chosen code action by sending a `workspace/executeCommand`.
25
+ 6. **Calculate Edits**: The Server calculates the necessary changes, or [workspace edits](#workspace-edits), required to implement the command.
26
+ 7. **Apply Edits**: The Server requests the Client to apply these edits through a `workspace/applyEdit` command, which adjusts the file to resolve the issues.
27
+ 8. **Client Confirmation**: The Client confirms whether the edits were successfully applied (`applyEdit`).
28
+ 9. **Diagnostics Update**: The Server updates its internal diagnostics based on the changes and informs the Client of the latest diagnostic state.
29
+ 10. **Complete Execution**: The Server finalizes the process by responding to the `workspace/executeCommand` request, confirming the completion of the action.
32
30
 
33
31
  </details>
34
32
 
35
- ## What it's like in the code
33
+ ## Code Action and Command Handling
36
34
 
37
- We handle two Client->Server LSP requests:
35
+ platformOS Check handles two types of Client-to-Server LSP requests:
38
36
 
39
- 1. On `textDocument/codeAction`, our `CodeActionEngine` returns the results obtained from all `CodeActionProvider`.
40
- 2. On `workspace/executeCommand`, our `ExecuteCommandEngine` dispatches the command and arguments to appropriate `ExecuteCommandProvider`.
37
+ 1. **Code Actions**: On `textDocument/codeAction`, our `CodeActionEngine` returns the results obtained from all `CodeActionProvider`.
38
+ 2. **Execute Commands**: On `workspace/executeCommand`, our `ExecuteCommandEngine` dispatches the command and arguments to appropriate `ExecuteCommandProvider`.
41
39
 
42
- We define providers:
40
+ ### Providers Defined:
43
41
 
44
- - Two `CodeActionProvider`:
45
- 1. [`QuickFixCodeActionProvider`](/lib/platformos_check/language_server/code_action_providers/quickfix_code_action_provider.rb) - This one provides code actions that fix _one_ diagnostic.
46
- 2. [`SourceFixAllCodeActionProvider`](/lib/platformos_check/language_server/code_action_providers/source_fix_all_code_action_provider.rb) - This one provides code actions that fix _all diagnostics in the current file_.
47
- - One `ExecuteCommandProvider`:
48
- 1. [`CorrectionExecuteCommandProvider`](/lib/platformos_check/language_server/execute_command_providers/correction_execute_command_provider.rb) - This one takes a list of diagnostics as arguments, turns them into a [WorkspaceEdit](#workspace-edit) and tries to apply them with the server->client `workspace/applyEdit` request.
42
+ - **CodeAction Providers**
43
+ 1. [`QuickFixCodeActionProvider`](/lib/platformos_check/language_server/code_action_providers/quickfix_code_action_provider.rb) - Provides code actions that fix _one_ diagnostic.
44
+ 2. [`SourceFixAllCodeActionProvider`](/lib/platformos_check/language_server/code_action_providers/source_fix_all_code_action_provider.rb) - Provides code actions that fix _all_ diagnostics in the current file.
45
+ - **ExecuteCommand Provider**:
46
+ 1. [`CorrectionExecuteCommandProvider`](/lib/platformos_check/language_server/execute_command_providers/correction_execute_command_provider.rb) - Takes a list of diagnostics as arguments, turns them into a [WorkspaceEdit](#workspace-edit) and requests the Client to apply them (`workspace/applyEdit`).
49
47
 
50
- We define a [`DocumentChangeCorrector`](/lib/platformos_check/language_server/document_change_corrector.rb) (an LSP analog to our [`Corrector`](/lib/platformos_check/corrector.rb) class). This class turns corrector calls into document changes supported by the LSP. For more details, see the [LSP reference on resource changes][lspresourcechange].
48
+ ### Additional Details
51
49
 
52
- ## Definitions
50
+ We define a [`DocumentChangeCorrector`](/lib/platformos_check/language_server/document_change_corrector.rb) (an LSP analog to our [`Corrector`](/lib/platformos_check/corrector.rb) class). This class turns corrector calls into document changes supported by the LSP. For more details, refer to the [LSP reference on resource changes][lspresourcechange].
53
51
 
54
- ### Code Actions
52
+ ## Definitions and Examples
55
53
 
56
- A [CodeAction][lspcodeaction] is the Language Server Protocol construct for "stuff you might want to do on the code."
54
+ ### Code Actions
57
55
 
58
- Think refactoring, running tests, fixing lint errors, etc.
56
+ A [CodeAction][lspcodeaction] is a suggestion for a change to the code that the User can apply directly. It could include refactorings, fixes for linting errors, or test executions.
59
57
 
60
- The client figures out which one it can run by executing the client->server `textDocument/codeAction` request.
58
+ The Client determines which actions it can perform by sending a `textDocument/codeAction` request from the client to the server.
61
59
 
62
60
  <details>
63
61
  <summary>Visual Examples</summary>
64
62
 
65
- In VS Code, code actions of different kinds have special meanings and are mapped to multiple places in the UI.
63
+ In VS Code, different types of code actions are represented and accessed differently within the user interface:
66
64
 
67
- * `Quick Fix...` button on diagnostic hover
65
+ - **`Quick Fix...` button**: Appears when you hover over a diagnostic marker.
68
66
 
69
67
  <img src="code-action-quickfix.png" width=500>
70
68
 
71
- * Diagnostic right click in the problems tab
69
+ - **Right-click on a diagnostic in the problems tab**:
72
70
 
73
71
  <img src="code-action-problem.png" width=500>
74
72
 
75
- * Command palette `Quick Fix...` and `Fix All`
73
+ - **Command palette entries for `Quick Fix...` and `Fix All`**:
76
74
 
77
75
  <img src="code-action-command-palette.png" width=500>
78
76
 
79
- * Keyboard shortcuts
77
+ - **Keyboard shortcuts**:
80
78
 
81
79
  <img src="code-action-keyboard.png" width=700>
82
80
  </details>
@@ -86,27 +84,27 @@ In VS Code, code actions of different kinds have special meanings and are mapped
86
84
 
87
85
  ```ts
88
86
  interface CodeAction {
89
- title: string; // UI string, human readable for the action
90
- kind?: CodeActionKind; // OPTIONAL, for filtering
91
- diagnostics?: Diagnostic[]; // The diagnostics that the action SOLVES.
87
+ title: string; // Human-readable display name of the action, shown in the UI.
88
+ kind?: CodeActionKind; // OPTIONAL, used to filter actions based on type.
89
+ diagnostics?: Diagnostic[]; // List of diagnostics that the action SOLVES.
92
90
  isPreferred?: boolean; // Are used by auto fix and can be targetted by keybindings.
93
- // Shown as faded out in the code action menu when the user request a more specific type of code action
91
+ // Shown as faded out in the code action menu when the user request a more specific type of code action.
94
92
  disabled?: {
95
93
  reason: string;
96
94
  },
97
95
 
98
- // if both edit and command are present, edit is run first then command.
99
- // I think edit is used so the client performs the change, wheras the command
100
- // would be done by the server
101
- edit?: WorkspaceEdit; // what this action does ??!!
102
- command?: Command; // the command that it executes
103
- data?: any; // sent from the CodeAction to the codeAction/resolve.
96
+ // If both an edit and a command are present, the edit is applied first, followed by the command.
97
+ // Generally, the edit is intended to be executed by the client to make changes to the document,
98
+ // while the command is executed by the server to perform additional actions.
99
+ edit?: WorkspaceEdit; // Describes the document changes to be made by the action.
100
+ command?: Command; // The command to be executed by the server.
101
+ data?: any; // Additional data sent from the CodeAction to the codeAction/resolve.
104
102
  }
105
103
 
106
104
  interface Command {
107
- title: string; // Title of the command, like `save`
108
- command: string; // id
109
- arguments?: any[]
105
+ title: string; // Display name of the command, like 'Save'.
106
+ command: string; // ID of the command.
107
+ arguments?: any[] // Optional arguments for the command.
110
108
  }
111
109
  ```
112
110
  </details>
@@ -115,20 +113,18 @@ In VS Code, code actions of different kinds have special meanings and are mapped
115
113
 
116
114
  ### Commands
117
115
 
118
- A [Command][lspcommand] is the Language Server Protocol representation of a command that can be executed by the Server.
116
+ A [Command][lspcommand] in the Language Server Protocol (LSP) is a representation of a function that can be executed by the server, based on instructions sent from the client.
119
117
 
120
- Think of them as data representation of function calls that can be made by the Client.
121
-
122
- Typically, a command is associated with a Code Action. If the Client wants to perform this Code Action, it will make a Client->Server `workspace/executeCommand` request.
118
+ Think of commands as actionable requests - similar to function calls — that the client can initiate. These commands are often linked to a Code Action. When a client initiates a specific Code Action, it sends a `workspace/executeCommand` request from the client to the server.
123
119
 
124
120
  <details>
125
121
  <summary>TypeScript Interface</summary>
126
122
 
127
123
  ```ts
128
124
  interface Command {
129
- title: string; // Title of the command, like `save`
130
- command: string; // id
131
- arguments?: any[]
125
+ title: string; // Display name of the command, like 'Save'.
126
+ command: string; // ID of the command.
127
+ arguments?: any[] // Optional arguments for the command.
132
128
  }
133
129
  ```
134
130
  </details>
@@ -137,9 +133,7 @@ Typically, a command is associated with a Code Action. If the Client wants to pe
137
133
 
138
134
  ### Workspace Edits
139
135
 
140
- A [WorkspaceEdit][lspworkspaceedit] is the Language Server Protocol construct that abstracts code changes as data.
141
-
142
- Think edit file, create file, delete file but as data.
136
+ A [WorkspaceEdit][lspworkspaceedit] is a Language Server Protocol (LSP) construct designed to represent code changes in a structured data format. This approach allows operations like editing, creating, or deleting files to be described as data transactions.
143
137
 
144
138
  <details>
145
139
  <summary>TypeScript Interface</summary>
@@ -151,7 +145,7 @@ Think edit file, create file, delete file but as data.
151
145
  changeAnnotations?: { [id: string]: ChangeAnnotation }
152
146
  }
153
147
 
154
- // see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#resourceChanges
148
+ // See https://microsoft.github.io/language-server-protocol/specifications/specification-current/#resourceChanges.
155
149
  interface CreateFile {
156
150
  kind: 'create';
157
151
  uri: DocumentUri;
@@ -161,7 +155,7 @@ Think edit file, create file, delete file but as data.
161
155
 
162
156
  interface TextEdit {
163
157
  range: Range;
164
- newText: string; // can be empty to delete
158
+ newText: string; // The new text to replace the specified range. An empty string indicates deletion.
165
159
  }
166
160
 
167
161
  interface TextDocumentEdit {
@@ -171,7 +165,7 @@ Think edit file, create file, delete file but as data.
171
165
 
172
166
  interface OptionalVersionedTextDocumentIdentifier {
173
167
  uri: TextDocumentURI;
174
- // null is for when the file wasn't open from the client
168
+ // null is for when the file wasn't open from the client.
175
169
  // integer is for when you know what it was.
176
170
  version: integer | null;
177
171
  }
@@ -182,16 +176,14 @@ Think edit file, create file, delete file but as data.
182
176
 
183
177
  ### Diagnostic
184
178
 
185
- A [Diagnostic][lspdiagnostic] is the Language Server Protocol construct for errors, warnings and information bubbles.
186
-
187
- In our case, diagnostics are PlatformOS Check offenses.
179
+ A [Diagnostic][lspdiagnostic] is a construct within the Language Server Protocol (LSP) used to represent issues within the code, such as errors, warnings, and informational messages.
188
180
 
189
- They appear in the Problems tab and in the gutter of the editor.
181
+ In platformOS Check, diagnostics highlight ode offenses that need addressing, such as errors or warnings. They are shown in the _Problems_ tab and next to the code in the editor's gutter, helping developers quickly locate and understand the issues detected by the system.
190
182
 
191
183
  [lsp]: https://microsoft.github.io/language-server-protocol/specification
192
184
  [lspcodeaction]: https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction
193
185
  [lspcommand]: https://microsoft.github.io/language-server-protocol/specification#command
194
186
  [lspexecutecommand]: https://microsoft.github.io/language-server-protocol/specification#workspace_executeCommand
195
187
  [lspworkspaceedit]: https://microsoft.github.io/language-server-protocol/specification#workspaceEdit
196
- [lspdiagnostic]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#diagnostic
188
+ [lspdiagnostic]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic
197
189
  [lspresourcechange]: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#resourceChanges