chore: language cleanup + textlint setup

Author: rigor789

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
           node-version: 19
           cache: 'npm'
       - run: npm ci
-      - run: npm run lint:check --if-present
+      - run: npm run lint --if-present
       - run: npm run build --if-present
         env:
           NODE_OPTIONS: "--max_old_space_size=4096"

.textlintrc

@@ -0,0 +1,94 @@
+{
+  "rules": {
+    "terminology": {
+      "severity" : "warning",
+      "defaultTerms": false,
+      // Some terms borrowed from https://github.com/cypress-io/cypress-documentation/blob/main/.textlintrc
+      "terms": [
+        // Brands and Technologies
+        "JavaScript",
+        "TypeScript",
+        "NativeScript",
+        "GitHub",
+        ["VSCode", "VS Code"],
+        "webpack",
+        ["WebSocket(s?)", "WebSocket$1"],
+        "WiFi",
+        "API",
+        ["API['’]?s", "APIs"],
+        "CLI",
+        "CSS",
+
+        // Words and phrases
+        ["\\(s\\)he", "they"],
+        ["he or she", "they"],
+        ["he/she", "they"],
+        ["crazy", "complex"],
+        ["crazier", "more complex"],
+        ["craziest", "most complex"],
+        ["dumb", "unintended"],
+        ["insane", "outrageous"],
+        ["blacklist", "block"],
+        ["whitelist", "allow"],
+
+        // Prefer American spelling
+        ["behaviour", "behavior"],
+        ["cancelled", "canceled"],
+        ["cancelling", "canceling"],
+        ["centre", "center"],
+        ["colour", "color"],
+        ["customise", "customize"],
+        ["customisation", "customization"],
+        ["favourite", "favorite"],
+        ["labelled", "labeled"],
+        ["licence", "license"],
+        ["organise", "organize"],
+
+        // Common misspellings
+        ["gaurantee", "guarantee"],
+
+        // Words we would like to not use altogether
+        ["obviously", ""],
+        ["basically", ""],
+        ["simply", ""],
+        ["of( )?course", ""],
+        ["clearly", ""],
+        ["just", ""],
+        ["everyone knows", ""],
+        ["easy", ""],
+
+        // Words we would like to not use at the start of a sentence
+        ["^so", ""],
+        ["^and", ""],
+        ["^but", ""],
+        ["^however", ""],
+
+        // Single word
+        ["change[- ]log(s?)", "changelog$1"],
+        ["code[- ]base(es?)", "codebase$1"],
+        ["e[- ]mail(s?)", "email$1"],
+        ["end[- ]point(s?)", "endpoint$1"],
+        ["file[- ]name(s?)", "filename$1"],
+        ["can[- ]not", "cannot$1"],
+        ["back-?end(s?)", "backend$1"],
+        ["front-?end(s?)", "frontend$1"],
+        ["full-?stack(s?)", "fullstack$1"],
+
+        // Multiple words
+        ["open-?source(ed?)", "open source$1"],
+
+        // Hyphenated
+        ["end ?to ?end", "end-to-end"],
+        ["retryability", "retry-ability"],
+        ["retriability", "retry-ability"],
+
+        // Shortened words
+        ["repo\\b", "repository"],
+        ["repos\\b", "repositories"]
+      ]
+    }
+  },
+  "filters": {
+    "comments": true
+  }
+}

content/configuration/nativescript.md

@@ -9,7 +9,7 @@ contributors:
 The `nativescript.config.ts` is a central place to configure your project. It allows you to configure your project structure, application id, runtime related flags and more.
 
 ::: info Note about the `.ts` extension
-You can author the config file as plain `.js` file as well, however we recommend sticking with the `.ts` extension even if your project doesn't use TypeScript, because most editors will provide autocompletion in the `.ts` file.
+You can author the config file as plain `.js` file as well. We recommend sticking with the `.ts` extension even if your project doesn't use TypeScript, because most editors will provide autocompletion in the `.ts` file.
 :::
 
 By default a config looks somewhat like the following
@@ -98,7 +98,7 @@ TODO: document or remove?
 webpackConfigPath: string = 'custom-webpack.config.js'
 ```
 
-Specifies the [webpack config](/webpack) location. The default is `webpack.config.js` in the root however you can use a custom name and place elsewhere.
+Specifies the [webpack config](/webpack) location. The default is `webpack.config.js` in the root.
 
 ### profiling
 
@@ -126,8 +126,12 @@ ignoredNativeDependencies: string[] = ['@nativescript/imagepicker']
 
 A list of npm package names to ignore when attaching native dependencies to the build.
 
+<!-- textlint-disable -->
+
 ### cli
 
+<!-- textlint-enable -->
+
 ```ts
 cli: Object = {}
 ```
@@ -172,7 +176,7 @@ cli.packageManager: 'npm' | 'yarn' | 'pnpm' | 'yarn2' = 'yarn';
 
 Sets the package manager to use for this project.
 
-Defaults to the package manager set with the cli (`ns package-manager set yarn`), or `npm` if not set.
+Defaults to the package manager set with the CLI (`ns package-manager set yarn`), or `npm` if not set.
 
 ### cli.pathsToClean
 
@@ -208,7 +212,7 @@ See also [ios.id](#ios-id).
 android.discardUncaughtJsExceptions: boolean = true;
 ```
 
-Discard any uncaught JS exceptions. This can be very useful in production environments where you don't want your app to crash in case an unexpected JS exception is thrown.
+Discard any uncaught JS exceptions. This can be useful in production environments where you don't want your app to crash in case an unexpected JS exception is thrown.
 
 ### android.v8Flags
 
@@ -256,7 +260,13 @@ Trigger a gc periodically (in `ms`). Defaults to `0` (disabled).
 android.markingMode: 'none' | 'full';
 ```
 
-Sets the default gc marking mode, defaults to `none`. `full` has been deprecated and it's not recommended.
+Sets the default gc marking mode, defaults to `none`.
+
+::: warning Deprecated value
+
+`full` has been deprecated and it's not recommended.
+
+:::
 
 ### android.handleTimeZoneChanges
 
@@ -272,7 +282,7 @@ Notify the app when the timezone changes, defaults to `false`.
 android.maxLogcatObjectSize: number = 9999;
 ```
 
-Sets the maximum lenght of a single output string. Defaults to `1024`.
+Sets the max length of a single output string. Defaults to `1024`.
 
 ### android.forceLog
 
@@ -336,7 +346,7 @@ See also [android.id](#android-id).
 ios.discardUncaughtJsExceptions: boolean = true;
 ```
 
-Discard any uncaught JS exceptions. This can be very useful in production environments where you don't want your app to crash in case an unexpected JS exception is thrown.
+Discard any uncaught JS exceptions. This can be useful in production environments where you don't want your app to crash in case an unexpected JS exception is thrown.
 
 ### ios.SPMPackages
 
@@ -396,7 +406,7 @@ Avaialable hooks (prefix with `before-` or `after-`):
 - `install` - Application installed to device/emulator
 - `prepare` - Compiles webpack and prepares native app in platforms folder
 - `prepareNativeApp` - Preparing the actual native app, runs during prepare/watch hook
-- `resolveCommand` - Resolves command and arguments, runs before all cli commands
+- `resolveCommand` - Resolves command and arguments, runs before all CLI commands
 - `watch` - Setup watchers for live sync, runs during prepare hook
 - `watchPatterns` - Setup watch patterns, runs during watch hook
 

content/configuration/webpack.md

@@ -127,7 +127,7 @@ We define a few useful globally available variables that you can use to alter lo
 - `__NS_WEBPACK__` - always `true` when building with webpack
 - `__NS_ENV_VERBOSE__` - `true` when `--env.verbose` is set
 - `__NS_DEV_HOST_IPS__` - an array of IP addresses of the host machine (the machine running the build) when in `development` mode, and an empty array in production mode.
-- `__CSS_PARSER__` - the css parser used by NativeScript Core. The value is set based on the `cssParser` value in the `nativescript.config.ts` and defaults to `css-tree`
+- `__CSS_PARSER__` - the CSS parser used by NativeScript Core. The value is set based on the `cssParser` value in the `nativescript.config.ts` and defaults to `css-tree`
 - `__UI_USE_XML_PARSER__` - a flag used by NativeScript Core to disable the XML parser when it's not used
 - `__UI_USE_EXTERNAL_RENDERER__` - a flag used by NativeScript Core to disable registering global modules when an external renderer is used.
 
@@ -486,7 +486,7 @@ module.exports = (env) => {
 
 In some cases, you may want to explicitly set which base config should be used.
 
-For example in the NativeScript-Vue repo, the `sample` app doesn't have `nativescript-vue` listed as a dependency, so we have to specify the base config we want to use.
+For example in the NativeScript-Vue repository, the `sample` app doesn't have `nativescript-vue` listed as a dependency, so we have to specify the base config we want to use.
 
 ```js
 const webpack = require('@nativescript/webpack')
@@ -528,6 +528,8 @@ module.exports = (env) => {
 
 ### Merging options into the config
 
+<!--alex ignore simple-->
+
 For simple things, you can merge objects into the final config instead of using `chainWebpack`
 
 ```js

content/guide/code-sharing.md

@@ -10,7 +10,7 @@ JavaScript provides opportunities of immense scalability if architectured proper
 **The NativeScript TSC's 5 fundamental lessons about good code sharing**:
 
 1. If you can share your code easily with other paradigms, other disciplines, other runtimes even, then you have a good code sharing approach that will continue to provide you and your team joy. No developer or team willingly gets into code sharing hoping to find themselves in a corner later. You always want to share now to more easily maintain and scale the code later.
-2. A good code sharing approach should fit naturally in with well supported community standards and not require any extra build tooling just for the sharability to support itself. It should, in other words, stand firmly on it's own in scope of the language it is written in.
+2. A good code sharing approach should fit naturally in with well supported community standards and not require any extra build tooling for the sharability to support itself. It should, in other words, stand firmly on it's own in scope of the language it is written in.
 3. A good code sharing approach should not have to introduce new file extensions purely for sake of sharability (outside of those naturally supported by the framework) to deal with. All team's organize code by folders naturally and the same should be matched with good code sharing approaches avoiding new file extensions and concepts that go beyond general code organization.
 4. A good code sharing approach should clearly identify deployment/distribution lines as well as distinct platform separation allowing various shared code segments to have clear designated deployment targets allowing teams to control their own sophisticated build pipelines as they desire. Further the shared code should live within a thoughtful organizational structure that supports the ability to scale and adapt to future needs aside from the deployment targets that use the shared code.
 5. Within the specific scope of NativeScript's viewpoint, JavaScript is the universal language which provides the opportunity to share code effectively and responsibly. An approach that is based fundamentally on the strengths of JavaScript (and inherently TypeScript) is a good code sharing approach.
@@ -32,7 +32,7 @@ Here are a few solitions to **code-sharing**, each having their pros and cons.
 **Pros:**
 
 - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- Uses standard build tooling like TypeScript or webpack to build code (lesson 2 above)
 - No custom file extensions to deal with (lesson 3 above)
 - Nx splits up "apps" and "libs" clearly identifying deployment/distribution targets "apps" that consume shared code "libs" (lesson 4 above)
 
@@ -47,7 +47,7 @@ Here are a few solitions to **code-sharing**, each having their pros and cons.
 **Pros:**
 
 - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- Uses standard build tooling like TypeScript or webpack to build code (lesson 2 above)
 - No custom file extensions to deal with (lesson 3 above)
 - Nx splits up "apps" and "libs" clearly identifying deployment/distribution targets "apps" that consume shared code "libs" (lesson 4 above)
 - It builds upon @nativescript/nx to further scale it across more paradigms so it's a natural extension when needed if already working in Nx with @nativescript/nx
@@ -66,7 +66,7 @@ Here are a few solitions to **code-sharing**, each having their pros and cons.
 **Pros:**
 
 - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- Uses standard build tooling like TypeScript or webpack to build code (lesson 2 above)
 - No custom file extensions to deal with (lesson 3 above)
 - Can link/share dependencies
 
@@ -82,7 +82,7 @@ Here are a few solitions to **code-sharing**, each having their pros and cons.
 **Pros:**
 
 - It's centered around JavaScript/TypeScript (lesson 1 and 5 above)
-- Uses standard build tooling like typescript or webpack to build code (lesson 2 above)
+- Uses standard build tooling like TypeScript or webpack to build code (lesson 2 above)
 - No custom file extensions to deal with (lesson 3 above)
 
 **Cons:**

content/guide/creating-a-project.md

@@ -62,7 +62,7 @@ ns create myCoolApp --template @nativescript/template-blank
 
 ### Drawer Template
 
-A simple template with a side drawer.
+A template with a side drawer.
 
 <!-- TODO: make nicer images -->
 
@@ -81,7 +81,7 @@ ns create myCoolApp --template @nativescript/template-drawer-navigation
 
 ### Tabs Template
 
-A simple template with multiple tabs.
+A template with multiple tabs.
 
 <!-- TODO: make nicer images -->
 
@@ -100,7 +100,8 @@ ns create myCoolApp --template @nativescript/template-tab-navigation
 
 ### List & Details Template
 
-A simple template with a ListView and a details screen.
+A template with a ListView and a details screen.
+
 <DeviceFrame type="ios">
 <img src="https://raw.githubusercontent.com/NativeScript/nativescript-app-templates/master/packages/template-master-detail/tools/assets/appTemplate-ios.png">
 </DeviceFrame>

content/guide/debugging.md

@@ -85,12 +85,12 @@ If you are new to JavaScript debugging, we recommend reading the following resou
 | Memory Profiling           | :white_check_mark:             | :white_check_mark:             |
 | Timeline and CPU Profiling | :white_check_mark:             | :white_check_mark:             |
 
-## Debugging with VSCode
+## Debugging with VS Code
 
-VSCode uses the same protocol as the Chrome DevTools, in order to start a debugging session in VSCode you need to install the [NativeScript extension for VS Code](https://marketplace.visualstudio.com/items?itemName=NativeScript.nativescript).
+VS Code uses the same protocol as the Chrome DevTools, in order to start a debugging session in VS Code you need to install the [NativeScript extension for VS Code](https://marketplace.visualstudio.com/items?itemName=NativeScript.nativescript).
 
 ::: warning Note
-The VSCode extension for NativeScript is currently outdated and may not work. We are planning on revamping the project and bring it up-to-date with all the latest features soon.
+The VS Code extension for NativeScript is currently outdated and may not work. We are planning on revamping the project and bring it up-to-date with all the latest features soon.
 :::
 
 ## Debugging with XCode

content/guide/multithreading.md

@@ -15,7 +15,7 @@ The Workers API in NativeScript is loosely based on the [Web Workers API](https:
 For optimal results when using the Workers API, follow these guidelines:
 
 - Always make sure you close the worker threads, using the appropriate API (`terminate()` or `close()`), when the worker's finished its job. If Worker instances become unreachable in the scope you are working in before you are able to terminate it, you will be able to close it only from inside the worker script itself by calling the `close()` function.
-- Workers are not a general solution for all performance-related problems. Starting a Worker has an overhead of its own, and may sometimes be slower than just processing a quick task. Optimize DB queries, or rethink complex application logic before resorting to workers.
+- Workers are not a general solution for all performance-related problems. Starting a Worker has an overhead of its own, and may sometimes be slower than processing a quick task. Optimize DB queries, or rethink complex application logic before resorting to workers.
 - Since worker threads have access to the entire native SDK, the NativeScript developer must take care of all the synchronization when calling APIs which are not guaranteed to be thread-safe from more than one thread.
 
 ## Using Workers

content/guide/running.md

@@ -72,7 +72,7 @@ If any of the above failed, we recommend checking out the [Android ADB documenta
 
 ### Preparing an iOS device for development
 
-Before the NativeScript cli can run apps on a physical iOS device, the device must be set up and registered.
+Before the NativeScript CLI can run apps on a physical iOS device, the device must be set up and registered.
 
 Use a USB cable to connect the device. Navigate to the `platforms/ios` folder in your project, then open the `.xcworkspace` file in Xcode.
 

content/guide/shared-element-transitions.md

@@ -81,7 +81,7 @@ page.showModal('views/modal', {
 
 ### Independent shared elements
 
-In some cases you might not have an element present on both "ends", or just need to animate additional elements during the transition. That's what "independent" shared elements solve.
+In some cases you might not have an element present on both "ends", or need to animate additional elements during the transition. That's what "independent" shared elements solve.
 
 Consider the following example:
 
@@ -420,7 +420,7 @@ Used internally to finish the state after a transition has completed. Provided i
 
 ## Troubleshooting
 
-- It's easy to accidentally provide mismatching `sharedTransitionTag` values between two different pages. Always check for matching tags when encountering issues with Shared Element Transitions.
+- It's common to accidentally provide mismatching `sharedTransitionTag` values between two different pages. Always check for matching tags when encountering issues with Shared Element Transitions.
 - Try avoiding `sharedTransitionTag` on Labels since they usually won't exhibit expected behavior.
 
 ## Acknowledgements

content/project-structure/app-resources.md

@@ -203,7 +203,7 @@ To change the mode of the TimePicker from the default `spinner` style, change `a
 
 ### Enabling force Dark Mode
 
-On API29+ apps can opt-in to a default Dark Mode when the system is set to use Dark Mode. This is disabled by default as it can lead to visual issues, since the automatic conversion may not display correctly in all cases.
+On API29+ apps can opt-in to a default Dark Mode when the system is set to use Dark Mode. This is turned off by default as it can lead to visual issues, since the automatic conversion may not display correctly in all cases.
 
 To opt-in, change the `android:forceDarkAllowed` value to `true` in `App_Resources/Android/src/main/res/values-v29/styles.xml`:
 

content/project-structure/webpack-config.md

@@ -26,6 +26,6 @@ module.exports = (env) => {
 
 ::: tip Read More
 
-:point_right: [NativeScript Webpack Reference](/configuration/webpack)
+:point_right: [NativeScript webpack Reference](/configuration/webpack)
 
 :::

content/setup/linux.md

@@ -10,7 +10,7 @@ contributors:
 
 You will need Node, NativeScript CLI (command line interface), Android Studio and a JDK (java development kit).
 
-**Android Studio** is not strictly necessary — however it provides an easy to use interface for installing and managing the Android SDKs.
+**Android Studio** is not strictly necessary — however it provides an easy-to-use interface for installing and managing the Android SDKs.
 
 To install **Node** follow the [instructions specific to your Linux distribution](https://nodejs.org/en/download/package-manager/). We recommend using the latest version, however anything above **Node 12** should be fine.