@docspring/cspell-lockfile-dicts

A tool that extracts package names from various lockfiles and adds them to a CSpell dictionary file.

Requirements

| Tool | Version | | ------------------------------------------------------------------------------------------------------------------------------------ | ------- | | cspell | >= 6 | | Code Spell Checker - Visual Studio Code | >= 2 |

Why lockfiles? Why not package.json, Gemfile, etc?

• Package files are edited by humans (or AI). This is where we need spellchecking!
• Package lockfiles are generated by tools that are 100% accurate. They have a defined structure that is easy to parse
• Package files can include comments or even custom code (e.g. Gemfile). They are harder to parse consistently and accurately.
• Published package names and organizations generally don't contain any spelling mistakes
• Sometimes we do need to reference packages that are a dependency of a dependency.
• CSpell performance isn't affected by the number of words. It's fine to add all the nested dependencies to your dictionary even if you will never use those words.

Installation

npm install -g @docspring/cspell-lockfile-dicts

Usage

Step 1: Generate the Dictionary

Run the CLI tool to generate a dictionary from your lockfiles:

npx @docspring/cspell-lockfile-dicts

This will:

1. Scan your project for lockfiles (package-lock.json, yarn.lock, Gemfile.lock, composer.lock, Cargo.lock, etc.)
2. Extract package names from those lockfiles
3. Generate a .cspell/lockfile-words.txt file in your project root

Step 2: Add the Dictionary to CSpell

After generating the dictionary, add it to your CSpell configuration (e.g., .cspell.json or cspell.json):

{
  "dictionaryDefinitions": [
    {
      "name": "lockfile-words",
      "path": "./.cspell/lockfile-words.txt",
      "description": "Dictionary of words extracted from lockfiles"
    }
  ],
  "dictionaries": ["lockfile-words"]
}

This will include the generated dictionary in your spell checking.

Important: You need to run the cspell-lockfile-dicts command whenever your dependencies change to keep the dictionary up-to-date.

CLI Options

The tool supports the following command-line options:

Options:
  -p, --path <path>                   Path to save the dictionary file (default: ".cspell/lockfile-words.txt")
  -l, --lockfiles <files...>          Specific lockfiles to process (comma-separated)
  --no-auto-detect                    Disable auto-detection of lockfiles in the project
  -a, --auto-detect-patterns <patterns...>  Glob patterns for auto-detecting lockfiles (comma-separated)
  -d, --debug                         Enable debug logging
  -h, --help                          Display help for command

Examples

Generate dictionary with debug logging:

npx @docspring/cspell-lockfile-dicts --debug

Specify custom output path:

npx @docspring/cspell-lockfile-dicts --path ./custom-dict.txt

Process specific lockfiles:

npx @docspring/cspell-lockfile-dicts --lockfiles package-lock.json yarn.lock

Supported Lockfiles

| Lockfile | Language/Package Manager | Status | | -------------------- | --------------------------- | ------------ | | package-lock.json | JavaScript/npm | ✅ Supported | | yarn.lock | JavaScript/Yarn | ✅ Supported | | Gemfile.lock | Ruby/Bundler | ✅ Supported | | composer.lock | PHP/Composer | ✅ Supported | | Cargo.lock | Rust/Cargo | ✅ Supported | | poetry.lock | Python/Poetry | ✅ Supported | | Pipfile.lock | Python/Pipenv | ✅ Supported | | go.sum | Go | ✅ Supported | | go.mod | Go | ✅ Supported | | pnpm-lock.yaml | JavaScript/pnpm | ✅ Supported | | *.gradle.lockfile | Java/Gradle | 🔄 Pending | | build.sbt.lock | Scala/SBT | 🔄 Pending | | pom.xml.lock | Java/Maven | 🔄 Pending | | packages.lock.json | .NET/NuGet | 🔄 Pending | | Podfile.lock | Swift/CocoaPods | 🔄 Pending | | cocoapods.lock | Swift/CocoaPods | 🔄 Pending | | mix.lock | Elixir | 🔄 Pending | | Cartfile.resolved | Swift/Carthage | 🔄 Pending | | Package.resolved | Swift/Swift Package Manager | 🔄 Pending |

Please feel free to open a PR to add support for other lockfiles. (AI is pretty good at implementing them!)

Adding to CI/CD

It's recommended to run this tool as part of your CI/CD pipeline or pre-commit hooks to keep the dictionary up-to-date with your dependencies.

Example GitHub Actions workflow:

name: Update CSpell Dictionary

on:
  push:
    paths:
      - '**/package-lock.json'
      - '**/yarn.lock'
      - '**/Gemfile.lock'

jobs:
  update-dict:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm install -g @docspring/cspell-lockfile-dicts
      - run: cspell-lockfile-dicts
      - name: Update CSpell config
        run: |
          if [ ! -f .cspell.json ]; then
            echo '{
              "version": "0.2",
              "language": "en",
              "dictionaryDefinitions": [
                {
                  "name": "lockfile-words",
                  "path": "./.cspell/lockfile-words.txt",
                  "description": "Dictionary of words extracted from lockfiles"
                }
              ],
              "dictionaries": ["lockfile-words"]
            }' > .cspell.json
          else
            # Check if the dictionary is already configured
            if ! grep -q "lockfile-words" .cspell.json; then
              # This is a simple approach - for production use, consider using a JSON parser
              sed -i 's/"dictionaries": \[/"dictionaries": \["lockfile-words", /g' .cspell.json
              sed -i 's/"dictionaryDefinitions": \[/"dictionaryDefinitions": \[{"name": "lockfile-words", "path": "./.cspell\/lockfile-words.txt", "description": "Dictionary of words extracted from lockfiles"}, /g' .cspell.json
            fi
          fi
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: 'chore: update cspell lockfile dictionary'
          file_pattern: '.cspell/lockfile-words.txt .cspell.json'

License

MIT