@kitschpatrol/cspell-config/readme.md

CSpell configuration for @kitschpatrol/shared-config.

<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->

<!-- title -->

# @kitschpatrol/cspell-config

<!-- /title -->

<!-- badges -->

[![NPM Package @kitschpatrol/cspell-config](https://img.shields.io/npm/v/@kitschpatrol/cspell-config.svg)](https://npmjs.com/package/@kitschpatrol/cspell-config)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- /badges -->

<!-- description -->

**CSpell configuration for @kitschpatrol/shared-config.**

<!-- /description -->

## Overview

It's a shared [CSpell](https://cspell.org) config, plus a command-line tool `ksc-cspell` to perform CSpell-related project initialization and linting.

In addition to basic CSpell functionality, this package bundles a few extra features: It identifies "unused" words in your local CSpell configuration's ignore list that don't actually appear anywhere in your project, and it incorporates [Case Police](https://github.com/antfu/case-police) to enforce case consistency.

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).

<!-- 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 `ksc` command

<!-- /recommendation -->

## Setup

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 --package=@kitschpatrol/repo-config dlx ksc-repo init
   ```

2. Add the package:

   ```sh
   pnpm add -D @kitschpatrol/cspell-config
   ```

3. Add the starter `.cspell.json` file to your project root, and add any customizations you'd like:

   ```sh
   pnpm exec ksc-cspell init
   ```

## Usage

The CSpell binary should be picked up automatically by VS Code plugins.

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": "ksc-cspell lint"
  }
}
```

### Configuration

To create a `cspell.config.js` in your project root:

```sh
pnpm exec ksc-knip init
```

(Note that this will delete the `cspell` property in your `package.json`!)

_Or_

To create a `cspell` property in `package.json`:

```sh
pnpm exec ksc-cspell init --location package
```

(Note that this will delete the `cspell.config.js` file in your project root!)

#### Ignoring files

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.

Additional ignore patterns may be added to your project's CSpell config via the `ignorePaths` key.

Ignored files are automatically excluded from Case Police checks as well.

To exclude a specific file from Case Police checks, but to still check it with CSpell, include a comment:

`// @case-police-disable`

#### Ignoring specific words

Many words are included in the bundled dictionaries used by the shared configuration.

Additional words may be added to your project's CSpell config via the `words` key.

Specific words may be ignored on a per-file basis by including a comment:

`/* spell-checker: ignore $WORD, $ANOTHER_WORD, $YET_ANOTHER_WORD*/`

Likewise to ignore certain Case Police words:

`// @case-police-ignore $WORD, $ANOTHER_WORD, $YET_ANOTHER_WORD`

#### Ignoring code

See [the CSpell documentation](https://cspell.org/docs/Configuration/document-settings).

Blocks:

`/* spell-checker:disable */ ...  /* spell-checker:enable */`

#### 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:

- [`lorem-ipsum`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/lorem-ipsum/dict/lorem.txt)
- [`git`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/git/cspell-ext.json)
- [`gaming-terms`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/gaming-terms/dict/gaming-terms.txt)
- [`npm`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/npm/dict/npm.txt)
- [`data-science`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/data-science/dict/data-science.txt)
- [`fullstack`](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/fullstack/dict/fullstack.txt)

It also includes a number of _custom_ dictionaries distributed with this package, all of which are enabled by default:

- `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
- `kp-tech` Tech-specific terminology, some ambiguity vs. "brands"

In your project's root `.cspell.json`, you can disable any combination of these dictionaries by adding them to the `dictionaries` array with a `!` prefix.

For example, do disable the `kp-acronyms` and `kp-brands` dictionaries:

```jsonc
{
  "import": "@kitschpatrol/cspell-config",
  "dictionaries": [
    "!kp-acronyms",
    "!kp-brands",
    // ...Addtional !-prefixed dicitonary names
  ],
}
```

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`:

```jsonc
{
  "import": "@kitschpatrol/cspell-config",
  "words": [
    "mountweazel",
    "steinlaus",
    "jungftak",
    "esquivalience",
    // ...Additional words
  ],
}
```

### CLI

<!-- cli-help -->

#### Command: `ksc-cspell`

Kitschpatrol's CSpell shared configuration tools. (Automated fixes are handled by ESLint.)

This section lists top-level commands for `ksc-cspell`.

Usage:

```txt
ksc-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: `ksc-cspell init`

Initialize by copying starter config files to your project root or to your package.json file.

Usage:

```txt
ksc-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: `ksc-cspell lint`

Check for spelling mistakes. Matches files below the current working directory by default.

Usage:

```txt
ksc-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: `ksc-cspell print-config`

Print the resolved CSpell configuration. Package-scoped. Searches up to the root of a monorepo if necessary.

Usage:

```txt
ksc-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.

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

[MIT](license.txt) © Eric Mika

<!-- /license -->