@kitschpatrol/cspell-config 4.7.12 → 5.0.0

package/readme.md

@@ -21,9 +21,17 @@
 
 ## Overview
 
-It's a shared [CSpell](https://cspell.org) config.
+It's a shared [CSpell](https://cspell.org) config, plus a command-line tool `kpi-cspell` to perform CSpell-related project initialization and linting. Note that automated fixes are handled via an ESLint integration provided in [@kitschpatrol/eslint-config](https://github.com/kitschpatrol/shared-config/tree/main/packages/eslint-config).
 
-**See [`@kitschpatrol/shared-config`](https://www.npmjs.com/package/@kitschpatrol/shared-config) for the recommended single-package approach.**
+<!-- recommendation -->
+
+> [!Important]
+>
+> **You can use this package on its own, but it's recommended to use [`@kitschpatrol/shared-config`](https://www.npmjs.com/package/@kitschpatrol/shared-config) instead for a single-dependency and single-package approach to linting and fixing your project.**
+>
+> This package is included as a dependency in [`@kitschpatrol/shared-config`](https://www.npmjs.com/package/@kitschpatrol/shared-config), which also automatically invokes the command line functionality in this package via its `kpi` command
+
+<!-- /recommendation -->
 
 ## Setup
 
@@ -32,7 +40,7 @@ To use just this CSpell config in isolation:
 1. Install the `.npmrc` in your project root. This is required for correct PNPM behavior:
 
    ```sh
-   pnpm dlx @kitschpatrol/repo-config --init
+   pnpm dlx @kitschpatrol/repo-config init
    ```
 
 2. Add the package:
@@ -44,7 +52,7 @@ To use just this CSpell config in isolation:
 3. Add the starter `.cspell.json` file to your project root, and add any customizations you'd like:
 
    ```sh
-   pnpm exec cspell-config --init
+   pnpm exec kpi-cspell init
    ```
 
 ## Usage
@@ -56,38 +64,34 @@ You can call it directly, or use the script bundled with the config.
 Integrate with your `package.json` scripts as you see fit, for example:
 
 ```json
-"scripts": {
-  "spellcheck": "cspell-config --check"
+{
+  "scripts": {
+    "spellcheck": "kpi-cspell lint"
+  }
 }
 ```
 
-### CLI
+### Configuration
 
-<!-- cli-help -->
+To create a `cspell.config.js` in your project root:
 
-#### Command: `cspell-config`
+```sh
+pnpm exec kpi-knip init
+```
 
-CSpell configuration for @kitschpatrol/shared-config.
+(Note that this will delete the `cspell` property in your `package.json`!)
 
-Usage:
+_Or_
 
-```txt
-cspell-config [<file|glob> ...]
-```
-
-| Option                   | Argument | Description                                                      |
-| ------------------------ | -------- | ---------------------------------------------------------------- |
-| `--check`<br>`-c`        |          | Check for and report issues. Same as `cspell-config`.            |
-| `--init`<br>`-i`         |          | Initialize by copying starter config files to your project root. |
-| `--print-config`<br>`-p` | `<path>` | Print the effective configuration at a certain path.             |
-| `--help`<br>`-h`         |          | Print this help info.                                            |
-| `--version`<br>`-v`      |          | Print the package version.                                       |
+To create a `cspell` property in `package.json`:
 
-<!-- /cli-help -->
+```sh
+pnpm exec kpi-cspell init --location package
+```
 
-## Configuration
+(Note that this will delete the `cspell.config.js` file in your project root!)
 
-### Disabling bundled dictionaries
+#### Disabling bundled dictionaries
 
 In additional to CSpell's default dictionary configuration, this shared configuration enables a number of dictionaries that ship with CSpell for all file types:
 
@@ -102,6 +106,7 @@ It also includes a number of _custom_ dictionaries distributed with this package
 
 - `kp-acronyms` Contains acronyms
 - `kp-brands` Contains proper nouns like brand names
+- `kp-eslint` Names seen in eslint rules provided by `@kitschpatrol/eslint-config`
 - `kp-files` File extensions and types
 - `kp-misc` Contains general and miscellaneous words
 - `kp-names` Human names and usernames
@@ -111,40 +116,125 @@ In your project's root `.cspell.json`, you can disable any combination of these
 
 For example, do disable the `kp-acronyms` and `kp-brands` dictionaries:
 
-```json
+```jsonc
 {
   "import": "@kitschpatrol/cspell-config",
   "dictionaries": [
     "!kp-acronyms",
-    "!kp-brands"
+    "!kp-brands",
     // ...Addtional !-prefixed dicitonary names
-  ]
+  ],
 }
 ```
 
-### Adding project-scoped words
+If you need a massive and permissive dictionary for large writing project, take a look at [@kitschpatrol/dict-en-wiktionary](https://github.com/kitschpatrol/dict-en-wiktionary).
+
+#### Adding project-scoped words
 
 In your project's root `.cspell.json`:
 
-```json
+```jsonc
 {
   "import": "@kitschpatrol/cspell-config",
   "words": [
     "mountweazel",
     "steinlaus",
     "jungftak",
-    "esquivalience"
+    "esquivalience",
     // ...Additional words
-  ]
+  ],
 }
 ```
 
+### CLI
+
+<!-- cli-help -->
+
+#### Command: `kpi-cspell`
+
+Kitschpatrol's CSpell shared configuration tools. (Automated fixes are handled by ESLint.)
+
+This section lists top-level commands for `kpi-cspell`.
+
+Usage:
+
+```txt
+kpi-cspell <command>
+```
+
+| Command        | Argument    | Description                                                                                                  |
+| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `init`         |             | Initialize by copying starter config files to your project root or to your package.json file.                |
+| `lint`         | `[files..]` | Check for spelling mistakes. Matches files below the current working directory by default.                   |
+| `print-config` |             | Print the resolved CSpell configuration. Package-scoped. Searches up to the root of a monorepo if necessary. |
+
+| Option              | Description         | Type      |
+| ------------------- | ------------------- | --------- |
+| `--help`<br>`-h`    | Show help           | `boolean` |
+| `--version`<br>`-v` | Show version number | `boolean` |
+
+_See the sections below for more information on each subcommand._
+
+#### Subcommand: `kpi-cspell init`
+
+Initialize by copying starter config files to your project root or to your package.json file.
+
+Usage:
+
+```txt
+kpi-cspell init
+```
+
+| Option              | Description         | Type                 | Default  |
+| ------------------- | ------------------- | -------------------- | -------- |
+| `--location`        | TK                  | `"file"` `"package"` | `"file"` |
+| `--help`<br>`-h`    | Show help           | `boolean`            |          |
+| `--version`<br>`-v` | Show version number | `boolean`            |          |
+
+#### Subcommand: `kpi-cspell lint`
+
+Check for spelling mistakes. Matches files below the current working directory by default.
+
+Usage:
+
+```txt
+kpi-cspell lint [files..]
+```
+
+| Positional Argument | Description                    | Type    | Default  |
+| ------------------- | ------------------------------ | ------- | -------- |
+| `files`             | Files or glob pattern to lint. | `array` | `"**/*"` |
+
+| Option              | Description         | Type      |
+| ------------------- | ------------------- | --------- |
+| `--help`<br>`-h`    | Show help           | `boolean` |
+| `--version`<br>`-v` | Show version number | `boolean` |
+
+#### Subcommand: `kpi-cspell print-config`
+
+Print the resolved CSpell configuration. Package-scoped. Searches up to the root of a monorepo if necessary.
+
+Usage:
+
+```txt
+kpi-cspell print-config
+```
+
+| Option              | Description         | Type      |
+| ------------------- | ------------------- | --------- |
+| `--help`<br>`-h`    | Show help           | `boolean` |
+| `--version`<br>`-v` | Show version number | `boolean` |
+
+<!-- /cli-help -->
+
 ## Notes
 
 This config includes a bunch of words I've happened to have needed to use. Your preferences will vary.
 
 CSpell is configured to automatically ignore files and paths in `.gitignore` (via `"useGitignore": true`), and to ignore words inside of ` ``` ` code fences in markdown and mdx files.
 
+As part of the `lint` command process, `@kitschpatrol/cspell-config` also runs a check to identify any words in your config file's `"words"` array that are _do not_ actually appear anywhere else in your project. This was inspired by [Zamiell's](https://github.com/Zamiell) [cspell-check-unused-words](https://github.com/complete-ts/cspell-check-unused-words) project.
+
 <!-- license -->
 
 ## License

package/cspell.config.json

@@ -1,101 +0,0 @@
-{
-	"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
-	"enabled": true,
-	"enableGlobDot": false,
-	"enableFiletypes": ["astro", "md", "mdx", "patch", "svelte"],
-	"dictionaryDefinitions": [
-		{
-			"name": "kp-acronyms",
-			"path": "./dictionaries/kp-acronyms.txt",
-			"addWords": true
-		},
-		{
-			"name": "kp-brands",
-			"path": "./dictionaries/kp-brands.txt",
-			"addWords": true
-		},
-		{
-			"name": "kp-files",
-			"path": "./dictionaries/kp-files.txt",
-			"addWords": true
-		},
-		{
-			"name": "kp-misc",
-			"path": "./dictionaries/kp-misc.txt",
-			"addWords": true
-		},
-		{
-			"name": "kp-names",
-			"path": "./dictionaries/kp-names.txt",
-			"addWords": true
-		},
-		{
-			"name": "kp-tech",
-			"path": "./dictionaries/kp-tech.txt",
-			"addWords": true
-		}
-	],
-	"dictionaries": [
-		"lorem-ipsum",
-		"git",
-		"gaming-terms",
-		"npm",
-		"data-science",
-		"fullstack",
-		"kp-acronyms",
-		"kp-brands",
-		"kp-files",
-		"kp-misc",
-		"kp-names",
-		"kp-tech"
-	],
-	"languageSettings": [
-		{
-			"languageId": "markdown,mdx,json",
-			"ignoreRegExpList": [
-				// TODO does regex really need to be global?
-				"/^```(?:.|\\s)+?^```/mig", // Code fences
-				"\\$\\$.*?\\$\\$", // Ignore display MathJax $$...$$
-				"\\$[^$\\n]*\\$", // Ignore inline MathJax $...$
-				"[A-Z\\d\\-]{8,}" // Probable IDs or model names, e.g. AK-68-S7KA-0004
-			]
-		}
-	],
-	"globRoot": "/",
-	"ignorePaths": [
-		"__snapshots__",
-		"*.app",
-		"*.avif",
-		"*.m4a",
-		"*.m4v",
-		"*.mp3",
-		"*.mp4",
-		"*.patch",
-		"*.scpt",
-		"*.svg",
-		"*.tif",
-		"*.tldr",
-		"*.3gp",
-		"*.aac",
-		"*.avi",
-		"*.flac",
-		"*.flv",
-		"*.mkv",
-		"*.mpeg",
-		"*.oga",
-		"*.ogg",
-		"*.ogv",
-		"*.ogx",
-		"*.opus",
-		"*.spx",
-		"*.swf",
-		"*.wav",
-		"package.json",
-		"patches/",
-		"pnpm-lock.yaml"
-	],
-	"ignoreRegExpList": ["tp-.+", "tweakpane-plugin-.+", "v2_c_\\w{21}"],
-	"language": "en,en-US",
-	"useGitignore": true,
-	"version": "0.2"
-}

package/init/.cspell.json

@@ -1,6 +0,0 @@
-{
-	"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
-	"import": "@kitschpatrol/cspell-config",
-	"ignorePaths": [],
-	"words": []
-}