chore: add linting in CI (#475)

* chore: add linting in CI

* fix some spelling

* Fix some more

* Fix spelling and vocabulary errors in samples dir (#476)

Exclude vocab text files from license check.

---------

Co-authored-by: Brent Eritou <brent.eritou@lightbend.com>

.github/workflows/linting.yml

@@ -0,0 +1,29 @@
+name: Linting
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags-ignore: [ v.* ]
+
+jobs:
+  prose:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        # https://github.com/actions/checkout/releases
+        # v3.5.0
+        uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
+
+      # https://vale.sh
+      - name: Vale
+        # https://github.com/errata-ai/vale-action/releases
+        # v2.0.1
+        uses: errata-ai/vale-action@c4213d4de3d5f718b8497bd86161531c78992084
+        with:
+          files: '["docs/dev", "docs/src", "samples"]'
+          fail_on_error: true
+          filter_mode: nofilter
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,21 @@
+StylesPath = styles
+
+MinAlertLevel = error
+Vocab = Base
+
+Packages = Microsoft, write-good
+
+[*.{md,adoc}]
+BasedOnStyles = Vale, Lightbend, write-good
+
+# Override the alert level of certain styles
+Vale.Repetition = warning
+Lightbend.Contractions = suggestion
+Lightbend.Avoid = warning
+write-good.So = suggestion
+write-good.ThereIs = suggestion
+Lightbend.Foreign = warning
+Lightbend.HeadingColons = warning
+Lightbend.RangeFormat = suggestion
+Lightbend.URLFormat = suggestion
+Lightbend.Auto = warning

build/license.json

@@ -12,6 +12,7 @@
     "**/*.yml",
     "samples/*/*/lib/generated",
     "sdk/test/*.desc",
+    "styles/Vocab/Base/",
     "tck/generated",
     "testkit/integration-test/proto.*"
   ],

docs/src/modules/javascript/pages/actions-publishing-subscribing.adoc

@@ -25,7 +25,7 @@ To achieve this, create an xref:actions.adoc[Action] that subscribes to a journa
 
 .Use case: external calls
 ****
-A service might need to trigger other systems when certain events happened to an Entity. An Action can be connected to the Entity's journal and react on certain events to issue calls (eg. via HTTP or gRPC).
+A service might need to trigger other systems when certain events happened to an Entity. An Action can be connected to the Entity's journal and react on certain events to issue calls (e.g. via HTTP or gRPC).
 To achieve this, create an xref:actions.adoc[Action] that subscribes to a journal and let the implementation call other services.
 ****
 
@@ -56,7 +56,7 @@ include::example$eventing-shopping-cart/proto/cart/shopping_cart_analytics.proto
 <1> annotate the Protobuf rpc method with `(kalix.method).eventing`
 <2> use `in` and `topic` to subscribe to a topic
 
-There is nothing specific required in the implementation of `ProcessAdded`. The implementation will in most cases be an Action and forward a converted message to a different component (eg. an Event Sourced Entity).
+There is nothing specific required in the implementation of `ProcessAdded`. The implementation will in most cases be an Action and forward a converted message to a different component (e.g. an Event Sourced Entity).
 
 == Receiving messages from an external Topic
 

docs/src/modules/javascript/pages/call-another-service.adoc

@@ -6,7 +6,7 @@ In some cases it is useful to call a component in another service, for example i
 
 Calling other Kalix services in the same project from an Action is done by invoking them over gRPC much like how an external client would. The service is however identified only by the name it has been deployed as, Kalix takes care of routing requests to the service and keeping the data safe by encrypting the connection for us.
 
-In this sample we will show an action that does two sequential calls to the xref:value-entity.adoc[Value Entity Counter] service, deployed with the service name "counter".
+In this sample we will show an action that does two sequential calls to the xref:value-entity.adoc[Value Entity Counter] service, deployed with the service name "counter."
 
 We start by adding the public API of the counter to the `src/main/proto` directory of our project.
 
@@ -33,15 +33,15 @@ In our delegating service implementation:
 include::example$js-doc-snippets/src/delegatingservice.js[tag=delegating-action]
 ----
 <1> Include the `proto` file of the other service in the action service descriptors.
-<2> Create the client using the provided creators to get async methods. Defaults to a cleartext connection as TLS is handled transparently for us.
+<2> Create the client using the provided creators to get async methods. Defaults to a clear text connection as TLS is handled transparently for us.
 <3> Use the name that the other Kalix service was deployed as, in this case `counter`.
 <4> We can now call the various methods on the other service with their method names directly on the client. The calls return promises so we can use `await/async` to interact with them.
 
 NOTE: The client can only be created once the service has been started by Kalix, for example triggered by a call, not from the constructor.
 
 == External gRPC services
 
-Calling a Kalix service in another project, or an arbitrary external gRPC service is done the same way as described above, with the difference that it will use the full public hostname of the service and TLS/HTTPS to encrypt the connection.
+Calling a Kalix service in another project, or an arbitrary external gRPC service is done the same way as described above, with the difference that it will use the full public hostname of the service and TLS/https to encrypt the connection.
 
 [source,javascript,indent=0]
 .src/main/java/com/example/delegatingservice.js
@@ -51,4 +51,4 @@ include::example$js-doc-snippets/src/delegatingservice.js[tag=public-grpc]
 <1> Import `grpc-js`, to provide credentials when creating the client.
 <2> Create the client using the provided creators to get async methods.
 <3> Use the full public hostname of the service.
-<4> Enable TLS/HTTPS to encrypt the connection.
+<4> Enable TLS/https to encrypt the connection.

docs/src/modules/javascript/pages/developer-tools.adoc

@@ -1,6 +1,6 @@
 = Developer Tools
 
-The Javascript tooling is published to the npm registry under the https://www.npmjs.com/org/kalix-io[`@kalix-io` organisation].
+The JavaScript tooling is published to the npm registry under the https://www.npmjs.com/org/kalix-io[`@kalix-io` organisation].
 
 == Kickstart
 

docs/src/modules/javascript/pages/index.adoc

@@ -69,9 +69,9 @@ The following shows a minimal `package.json` configuration for a shopping cart s
 
 Descriptors for gRPC are defined in `protobuf` files. You can place `protobuf` files in your project wherever you like, for example, in the root directory, or in a directory named `protos`. In the `package.json` example, above we've placed the service descriptor in a file in the root folder called `shoppingcart.proto`. See xref:proto.adoc[] for more details.
 
-=== Precompile the protobuf descriptor set
+=== Pre-compile the protobuf descriptor set
 
-The gRPC descriptor is serialized to binary using the Protobuf https://developers.google.com/protocol-buffers/docs/techniques#self-description[`FileDescriptorSet` message type]. Kalix requires that you precompile this descriptor using `protoc`. We provide a utility that does this for you. It downloads the `protoc` binary for your platform, and runs it with the necessary arguments and include paths. You can run the utility manually, or we recommend adding it as a script to the build.
+The gRPC descriptor is serialized to binary using the Protobuf https://developers.google.com/protocol-buffers/docs/techniques#self-description[`FileDescriptorSet` message type]. Kalix requires that you pre-compile this descriptor using `protoc`. We provide a utility that does this for you. It downloads the `protoc` binary for your platform, and runs it with the necessary arguments and include paths. You can run the utility manually, or we recommend adding it as a script to the build.
 
 To run the utility manually, invoke `node_modules/@kalix-io/kalix-javascript-sdk/bin/compile-descriptor.js`.
 

docs/src/modules/javascript/pages/quickstart/sc-eventsourced-entity-javascript.adoc

@@ -194,7 +194,7 @@ include::javascript:example$js-shopping-cart-quickstart/src/shoppingcart.js[tag=
 +
 --
 * This function takes the current internal state and converts it to the external API model.
-* The conversion between the domain and the external API is straigtforward, as they have the same fields.
+* The conversion between the domain and the external API is straightforward, as they have the same fields.
 --
 +
 [source, javascript, indent=0]

docs/src/modules/javascript/pages/quickstart/sc-eventsourced-entity-typescript.adoc

@@ -202,7 +202,7 @@ include::javascript:example$ts-shopping-cart-quickstart/src/shoppingcart.ts[tag=
 +
 --
 * This function takes the current internal state and converts it to the external API model.
-* The conversion between the domain and the external API is straigtforward, as they have the same fields.
+* The conversion between the domain and the external API is straightforward, as they have the same fields.
 --
 +
 [source, typescript, indent=0]

docs/src/modules/javascript/pages/serialization.adoc

@@ -4,7 +4,7 @@
 include::ROOT:partial$include.adoc[]
 include::partial$serialization.adoc[]
 
-As a JavaScript developer, JSON is likely more familiar to you. When creating Event Sourced Entities, you can configure serialization for primitives or for Json, using `serializeAllowPrimitives` or `serializeFallbacktoJson`, respectively.
+As a JavaScript developer, JSON is likely more familiar to you. When creating Event Sourced Entities, you can configure serialization for primitives or for JSON, using `serializeAllowPrimitives` or `serializeFallbacktoJson`, respectively.
 
 == Setting the serialization flag
 

docs/src/modules/javascript/pages/value-entity.adoc

@@ -27,7 +27,7 @@ The following `counter_domain.proto` file defines a "Counter" Value Entity. The
 include::example$valueentity-counter/proto/counter_domain.proto[]
 ----
 
-<1> Any classes generated from this protobuf file will be nested in the package heirarchy of: `com.example.domain`.
+<1> Any classes generated from this protobuf file will be nested in the package hierarchy of: `com.example.domain`.
 <2> The `CounterState` protobuf message is what Kalix stores for this entity.
 
 The `counter_api.proto` file defines the commands we can send to the Counter service to manipulate or access the Counter`s state. They make up the service API:
@@ -37,15 +37,15 @@ The `counter_api.proto` file defines the commands we can send to the Counter ser
 include::example$valueentity-counter/proto/counter_api.proto[]
 ----
 <1> Import the Kalix protobuf annotations, or options.
-<2> Any classes generated from this protobuf file will be be nested in the package heirarchy: `com.example`.
+<2> Any classes generated from this protobuf file will be be nested in the package hierarchy: `com.example`.
 
 <3> Protobuf messages describe the Commands that the service handles. They may contain other messages to represent structured data.
 <4> Every Command must contain a `string` field that contains the entity ID and is marked with the `(kalix.field).entity_key` option.
 <5> Messages describe the return value for the API. For methods that don't have return values, you should use `google.protobuf.Empty`.
 <6> The service descriptor shows the API of the entity. It lists the methods a client can use to issue Commands to the entity.
 <7> The protobuf option `(kalix.codegen).value_entity` is specific to code-generation as provided by the Kalix plugin.
 <8> `name` denotes the base name for the Value entity, the code-generation will create initial sources `CounterImpl`, `CounterTest` and `CounterIntegrationTest`. Once these files exist, they are not overwritten, so you can freely add logic to them.
-<9> `entity_type` is a unique identifier of the "state storage". The entity name may be changed even after data has been created, the `entity_type` can't. This value shows in the `@ValueEnity` annotation of your entity implementation.
+<9> `entity_type` is a unique identifier of the "state storage." The entity name may be changed even after data has been created, the `entity_type` can't. This value shows in the `@ValueEnity` annotation of your entity implementation.
 <10> `state` points to the protobuf message representing the Value entity's state which is kept by Kalix
 
 == Creating an Entity
@@ -74,7 +74,7 @@ include::example$ts-valueentity-counter/src/counter.ts[tag=entity-class]
 
 == Using protobuf types
 
-When passing state to Kalix  the persisted data must be serialized and accessable.  To request state types, lookup the protobuf type then use the `create` method.
+When passing state to Kalix  the persisted data must be serialized and accessible.  To request state types, lookup the protobuf type then use the `create` method.
 
 Use the `ValueEntity` link:{attachmentsdir}/api/classes/ValueEntity.html#lookupType[`lookupType`{tab-icon}, window="new"] helper to look up these types so we can use them later.
 

docs/src/modules/javascript/partials/json.adoc

@@ -25,11 +25,11 @@ service ShoppingCartTopicService {
 
 == Publishing JSON messages to a topic
 
-By default when publishig a message to a topic, the protobuf message is serialized to bytes and published with the `content-type`/`ce-datacontenttype` `application/protobuf`, and will also contain the metadata entry `ce-type` specifying the specific protobuf message type.
+By default, when publishing a message to a topic, the protobuf message is serialized to bytes and published with the `content-type`/`ce-datacontenttype` `application/protobuf`, and will also contain the metadata entry `ce-type` specifying the specific protobuf message type.
 
 This is convenient when the consumer is another Kalix service that can handle protobuf messages.
 
-In many cases the consumer may be an external service though, and in such a case another serialization format for the messages can make sense. For such a use case the Kalix Javascript SDK supports emitting JSON messages.
+In many cases the consumer may be an external service though, and in such a case another serialization format for the messages can make sense. For such a use case the Kalix JavaScript SDK supports emitting JSON messages.
 
 To publish JSON messages to a topic, mark the return type of the message as `google.protobuf.Any`. The object returned with `replies.message()` will be serialized to string format and published to the topic with content type `Content-Type` attribute stating `application/json`.
 

docs/src/modules/javascript/partials/topic-eventing-cloudevent.adoc

@@ -12,7 +12,7 @@ To allow proper reading of Protobuf messages from topics, the messages need to s
 
 - `Content-Type` = `application/protobuf`
 - `ce-specversion` = `1.0`
-- `ce-type` = fully qualified protobuf message name (eg. `shopping.cart.api.TopicOperation`)
+- `ce-type` = fully qualified protobuf message name (e.g. `shopping.cart.api.TopicOperation`)
 
 (The `ce-` prefixed attributes are part of the CloudEvents specification.)
 

samples/ts/ts-eventsourced-shopping-cart/README.md

@@ -96,5 +96,5 @@ You will need to update the `config.dockerImage` property in the `package.json`
 
 Finally, you can use the [Kalix Console](https://console.kalix.io)
 to create a project and then deploy your service into the project either by using `npm run deploy`,
-through the `kalix` CLI or via the web interface. When using `npm run deploy`, NPM will also
+through the `kalix` CLI or via the web interface. When using `npm run deploy`, npm will also
 conveniently package and publish your docker image prior to deployment.

samples/ts/ts-valueentity-counter/README.md

@@ -97,5 +97,5 @@ for more information on how to make your docker image available to Kalix.
 
 Finally you can or use the [Kalix Console](https://console.kalix.io)
 to create a project and then deploy your service into the project either by using `npm run deploy`,
-through the `kalix` CLI or via the web interface. When using `npm run deploy`, NPM will also
+through the `kalix` CLI or via the web interface. When using `npm run deploy`, npm will also
 conveniently package and publish your docker image prior to deployment.

styles/Lightbend/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: Use 'AM' or 'PM' (preceded by a space).
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M'
+  - '\d{1,2} ?[ap]m'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

styles/Lightbend/Accessibility.yml

@@ -0,0 +1,25 @@
+extends: existence
+message: "Don't use language (such as '%s') that defines people by their disability."
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms
+level: suggestion
+ignorecase: true
+tokens:
+  - a victim of
+  - able-bodied
+  - affected by
+  - an epileptic
+  - crippled
+  - disabled
+  - dumb
+  - handicapped
+  - handicaps
+  - healthy
+  - lame
+  - maimed
+  - missing a limb
+  - mute
+  - normal
+  - sight-impaired
+  - stricken with
+  - suffers from
+  - vision-impaired

styles/Lightbend/Acronyms.yml

@@ -0,0 +1,65 @@
+extends: conditional
+message: "'%s' has no definition."
+link: https://docs.microsoft.com/en-us/style-guide/acronyms
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - CA
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP