CDS Lint rules: edit (#2068)

Co-authored-by: Christian Georgi <[email protected]>
Co-authored-by: Daniel O'Grady <[email protected]>
Co-authored-by: Daniel O'Grady <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: ecklie <[email protected]>
Co-authored-by: Christian Georgi <[email protected]>

Author: 5 people

tools/cds-lint/rules/assoc2many-ambiguous-key.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-In general an [association/composition to/of `MANY`](../../../cds/cdl#to-many-associations) that targets an entity without `ON` condition is not allowed (as it is an `n:1` relationship). Here, one should always specify an `ON` condition following the canonical expression pattern `<assoc>.<backlink> = $self`. The backlink can be any managed to-one association on the many side pointing back to the one side.
+An [association/composition to/of `MANY`](../../../cds/cdl#to-many-associations) that targets an entity without an `ON` condition is not allowed because it is an `n:1` relationship. Always specify an `ON` condition following the canonical expression pattern `<assoc>.<backlink> = $self`. The backlink can be any managed to-one association on the many side pointing back to the one side.
 
 ## Examples
 
@@ -34,7 +34,7 @@ In the following example, we define a unique association from `Authors` to `Book
 
 #### ❌ &nbsp; Incorrect example
 
-If we extend this example by creating a view `AuthorView` with a key `ID` and the element `bookIDs` without an `ON` condition, the rule is triggered since the key is no longer unique and `bookIDs` leads to multiple entries:
+If you extend this example by creating a view `AuthorView` with a key `ID` and the element `bookIDs` without an `ON` condition, the rule is triggered because the key is no longer unique and `bookIDs` leads to multiple entries:
 
 ::: code-group
 <<< ../examples/assoc2many-ambiguous-key/incorrect/db/schema.cds#snippet{cds:line-numbers} [db/schema.cds]

tools/cds-lint/rules/auth-no-empty-restrictions.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-The [`@requires` annotation](../../../guides/security/authorization#requires) is a convenience shortcut for `@restrict`. You can use it to control which rule a user needs to have in order to access a given resource. Leaving this field empty is dangerous as it leads to unrestricted access to that service which is a security risk.
+The [`@requires` annotation](../../../guides/security/authorization#requires) is a convenience shortcut for `@restrict`. You can use it to control which rule a user needs to access a given resource. Leaving this field empty is dangerous because it leads to unrestricted access to that service, which is a security risk.
 
 ## Examples
 
@@ -34,8 +34,7 @@ In the following example, the `AdminService` is correctly setup with `@requires`
 
 #### ❌   Incorrect example
 
-If we were to replace the `admin` role by an empty string or provide an empty role array as shown in the next example,
-we now have unrestricted access to that service, which the rule makes us aware of:
+If you replace the `admin` role with an empty string or provide an empty role array as shown in the next example, you now have unrestricted access to that service, which the rule makes you aware of:
 
 ::: code-group
 <<< ../examples/auth-no-empty-restrictions/incorrect/srv/admin-service.cds#snippet{cds:line-numbers} [srv/admin-service.cds]

tools/cds-lint/rules/auth-restrict-grant-service.md

@@ -14,9 +14,9 @@ status: released
 
 ## Rule Details
 
-Restrictions can be defined on different types of CDS resources, but there are some limitations with regard to supported privileges (see [limitations](../../../guides/security/authorization#supported-combinations-with-cds-resources)).
+Restrictions can be defined on different types of CDS resources, but there are some limitations regarding supported privileges (see [limitations](../../../guides/security/authorization#supported-combinations-with-cds-resources)).
 
-Unsupported privilege properties are ignored by the runtime. Especially, for bound or unbound actions, the `grant` property is implicitly removed (assuming `grant: '*'` instead). The same is true for functions. This rule ensures that `@restrict.grant` on service level and for bound/unbound actions and functions is limited to `grant: '*'`.
+Unsupported privilege properties are ignored by the runtime. For bound or unbound actions, the `grant` property is implicitly removed (assuming `grant: '*'` instead). The same is true for functions. This rule ensures that `@restrict.grant` on service level and for bound/unbound actions and functions is limited to `grant: '*'`.
 
 ## Examples
 
@@ -36,8 +36,7 @@ Let's consider the following example with the `CatalogService` where the functio
 
 #### ❌   Incorrect example
 
-If we were to slightly modify the above example and use `grant: ['WRITE']` in the privilege of the function, the rule would be
-triggered to inform us that the value of `grant` is limited to `'*'`:
+If you modify the above example and use `grant: ['WRITE']` in the privilege of the function, the rule would be triggered to inform you that the value of `grant` is limited to `'*'`:
 
 ::: code-group
 <<< ../examples/auth-restrict-grant-service/incorrect/srv/cat-service.cds#snippet{cds:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/auth-use-requires.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-Some annotations such as `@requires` or `@readonly` are just convenience shortcuts for `@restrict`. In actions and services with unrestricted events, it is recommended to use `@requires` instead of `@restrict.to`, which this rule enforces.
+Some annotations such as `@requires` or `@readonly` are convenience shortcuts for `@restrict`. In actions and services with unrestricted events, it is recommended to use `@requires` instead of `@restrict.to`, which this rule enforces.
 
 ## Examples
 
@@ -34,7 +34,7 @@ In the following example, the `CatalogService` action `addRating` correctly uses
 
 #### ❌   Incorrect example
 
-In the following example, the `CatalogService` uses `@restrict` to assign unrestricted events (`grant: *`) to the `Admin` role (`to: Admin`). This which could be written more clearly using `@requires` and so the rule reports a warning:
+In the following example, the `CatalogService` uses `@restrict` to assign unrestricted events (`grant: *`) to the `Admin` role (`to: Admin`). This could be written more clearly using `@requires` and so the rule reports a warning:
 
 ::: code-group
 <<< ../examples/auth-use-requires/incorrect/srv/cat-service.cds#snippet{cds:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/auth-valid-restrict-grant.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-The `grant` property of a `@restrict` privilege defines one or more events that the privilege applies. This rule checks for valid values of `@restrict.grant`, that is, all standard CDS events (such as `READ`, `CREATE`, `UPDATE`, and `DELETE`) on entities. It also suggests to use `*` only when listing events including `*` and to use `WRITE` only when using solely standard CDS events with write semantics (`CREATE`, `DELETE`, `UPDATE`, `UPSERT`).
+The `grant` property of a `@restrict` privilege defines one or more events that the privilege applies to. This rule checks for valid values of `@restrict.grant`, that is, all standard CDS events (such as `READ`, `CREATE`, `UPDATE`, and `DELETE`) on entities. It also suggests using `*` only when listing events including `*` and using `WRITE` only when using solely standard CDS events with write semantics (`CREATE`, `DELETE`, `UPDATE`, `UPSERT`).
 
 ## Examples
 
@@ -34,7 +34,7 @@ In the following example, `CatalogService.ListOfBooks` is restricted to the `REA
 
 #### ❌   Incorrect example
 
-In the next example, the `@restrict.grant` has a typo in the event (that is, `REAAD` instead of `READ`) for the `Viewer` role, which is not a valid value for `@restrict.grant` so the rule will report a warning:
+This example shows the `@restrict.grant` with a typo in the event (that is, `REAAD` instead of `READ`) for the `Viewer` role, which is not a valid value for `@restrict.grant` so the rule will report a warning:
 
 ::: code-group
 <<< ../examples/auth-valid-restrict-grant/incorrect/srv/cat-service.cds#snippet{cds:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/auth-valid-restrict-keys.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-To define authorizations on a fine-grained level, the `@restrict` annotation allows you to add all kinds of restrictions that are based on static user roles, the request operation, and instance filters. The building block of such a restriction is a single privilege. This rule checks that the privileges defined in `@restrict` have properly spelled `to`, `grant`, and `where` keys.
+To define authorizations on a fine-grained level, the `@restrict` annotation allows you to add all kinds of restrictions based on static user roles, the request operation, and instance filters. The building block of such a restriction is a single privilege. This rule checks that the privileges defined in `@restrict` have properly spelled `to`, `grant`, and `where` keys.
 
 ## Examples
 
@@ -34,7 +34,7 @@ In the following example, the `@restrict` annotation on `CatalogService.ListOfBo
 
 #### ❌   Incorrect example
 
-In the next example, the `@restrict` annotation on `CatalogService.ListOfBooks` has typos in the `grant` key (`grants` instead of `grant`), the `to` key (`too` instead of `to`), and the `where` key (`were` instead of `where`) and the rule will report them as a warning:
+This example shows the `@restrict` annotation on `CatalogService.ListOfBooks` with typos in the `grant` key (`grants` instead of `grant`), the `to` key (`too` instead of `to`), and the `where` key (`were` instead of `where`) and the rule will report them as a warning:
 
 ::: code-group
 <<< ../examples/auth-valid-restrict-keys/incorrect/srv/cat-service.cds#snippet{ts:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/auth-valid-restrict-to.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-The `to` property of a `@restrict` privilege defines one or more [user roles](../../../guides/security/authorization#roles) or [pseudo roles](../../../guides/security/authorization#pseudo-roles) that the privilege applies to. This rule checks that the values of `@restrict.to` are valid, that is, roles cannot be missing, misspelled and that roles including `any` should be simplified to just `any`.
+The `to` property of a `@restrict` privilege defines one or more [user roles](../../../guides/security/authorization#roles) or [pseudo roles](../../../guides/security/authorization#pseudo-roles) that the privilege applies to. This rule checks that the values of `@restrict.to` are valid, that is, roles cannot be missing or misspelled and that roles including `any` should be simplified to just `any`.
 
 ## Examples
 
@@ -34,7 +34,7 @@ The following example shows a correct usage of the `@restrict.to` annotation, wh
 
 #### ❌   Incorrect example
 
-The next example shows the `@restrict.to` annotation being left empty, which is a violation of this rule and a warning is raised:
+This example shows the `@restrict.to` annotation being left empty, which is a violation of this rule and a warning is raised:
 
 ::: code-group
 <<< ../examples/auth-valid-restrict-to/incorrect/srv/cat-service.cds#snippet{cds:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/auth-valid-restrict-where.md

@@ -14,7 +14,7 @@ status: released
 
 ## Rule Details
 
-The `where` property of a [`@restrict`](/guides/security/authorization#restrict-annotation) privilege defines a filter expression that restricts the access on an instance level (optional). This rule checks that the values of `@restrict.where` are valid, that is, the filter expression must be a valid expression that compiles without any errors.
+The `where` property of a [`@restrict`](/guides/security/authorization#restrict-annotation) privilege defines a filter expression that restricts access on an instance level (optional). This rule checks that the values of `@restrict.where` are valid, that is, the filter expression must be a valid expression that compiles without any errors.
 
 ## Examples
 
@@ -34,7 +34,7 @@ In the following example, the `@restrict` privilege is defined with a valid `whe
 
 #### ❌   Incorrect example
 
-In the next example, the `@restrict` privilege is defined with an invalid `where` property `CreatedBy === $user`. Since this is not a valid filter expression according to the CDS compiler, the rule reports a warning:
+This example shows the `@restrict` privilege defined with an invalid `where` property `CreatedBy === $user`. Since this is not a valid filter expression according to the CDS compiler, the rule reports a warning:
 
 ::: code-group
 <<< ../examples/auth-valid-restrict-where/incorrect/srv/cat-service.cds#snippet{cds:line-numbers} [srv/cat-service.cds]

tools/cds-lint/rules/extension-restrictions.md

@@ -14,10 +14,7 @@ status: released
 
 ## Rule Details
 
-CAP provides intrinsic extensibility, which means all your entities and services are extensible by default.
-Your SaaS app becomes the base app for extensions by your customers, and your data model the base model. Normally,
-you'll want to restrict which services or entities your SaaS customers are allowed to extend and to what degree they may do so.
-This rule ensures that extensions do not violate any restrictions set by the extended SaaS app.
+CAP provides intrinsic extensibility, which means all your entities and services are extensible by default. Your SaaS app becomes the base app for extensions by your customers, and your data model becomes the base model. Normally, you want to restrict which services or entities your SaaS customers are allowed to extend and to what degree they may do so. This rule ensures that extensions do not violate any restrictions set by the extended SaaS app.
 
 ## Examples
 

tools/cds-lint/rules/index.md

@@ -16,16 +16,13 @@ Below you can find all rules of the `@sap/eslint-plugin-cds` ESLint plugin.
 
 They are grouped by categories [Model Validation](#model-validation), [JavaScript](#javascript), and [Environment](#environment) to help you understand their purpose.
 
-Your standard CDS project configuration turns on a subset of these rules by default, namely the *recommended*
-( ✅ ) rules to ensure basic standards are met.
+Your standard CDS project configuration turns on a subset of these rules by default, namely the *recommended* ( ✅ ) rules to ensure basic standards are met.
 
 ## Model Validation
 
-Model Validation rules are used to validate CDS models within projects.
-They are used to enforce security, naming conventions, or other best practices.
+Model Validation rules are used to validate CDS models within projects. They are used to enforce security, naming conventions, or other best practices.
 
-Note, that while all recommended ( ✅ ) model rules run with the CLI, only a number of them are
-enabled and visible in the editor by default ( 👀 ).
+Note that while all recommended ( ✅ ) model rules run with the CLI, only a number of them are enabled and visible in the editor by default ( 👀 ).
 ::: details
 * *Editor default* rules: Rules that are enabled in the editor by default only rely on the current file as their rule context. These are quick to execute and
 can react on file changes.
@@ -37,9 +34,7 @@ slow or expensive processes. These are slow to execute and by default only run w
 
 ## Environment
 
-Environment rules are used to check for proper and up-to-date CDS project environments.
-These are only run via the command line and are not available in the editor as they often can't be
-pinpointed to any particular file.
+Environment rules are used to check for proper and up-to-date CDS project environments. These run only via the command line and are not available in the editor because they often cannot be pinpointed to any particular file.
 
 <RulesRefTable category="Environment"/>