Accept extra dictionaries via `CSPELL_DICT_PATH` env var and `--dict-path`

[jraygauthier]

Would facilitate packaging in distros and reproducible run in CIs.

I am attempting to find a nice way to package cspell on nix / nixpkgs / nixos in such a way that it is easy for users to add extra dictionaries (already packaged) without having to resort to convoluted hijacks of --config, XDG_HOME or NODE_PATH or even worst being forced into generating a node_modules that contains both cspell and all the dicts (which would require users to provide a new hash for each possible permutation).

It should be easy to add extra dictionaries without mutating the user's filesystem (the case for cspell link which mutates ~/.config/cspell/cspell.json).

Here's a more detailed description of the rough idea (AI generated via the https://chatgpt.com/share/e/68c4180e-02a8-800a-a2c6-0e90c9f17e43 conversation):

---

CSPELL(1) – Dictionary Path Options

NAME

CSPELL_DICT_PATH, --dict-path – extend dictionary package search paths for cspell imports

SYNOPSIS

cspell [OPTIONS] [FILES...]
cspell --dict-path <dir> [--dict-path <dir> ...] [FILES...]

Environment:

export CSPELL_DICT_PATH="<dir1>:<dir2>:..."

On Windows:

$env:CSPELL_DICT_PATH="C:\dicts;D:\extra-dicts"

DESCRIPTION

When a cspell configuration file contains import entries that refer to dictionary
packages (e.g. @cspell/dict-fr-fr/cspell-ext.json), cspell must resolve those
packages to an actual location on disk.

By default, resolution uses Node’s standard algorithm relative to the current
working directory (node_modules lookup).
The --dict-path option and the CSPELL_DICT_PATH environment variable
extend this search.

Each specified directory is treated as the root of a node_modules tree that
may contain one or more @cspell/dict-* packages. The cspell-ext.json inside
each package describes the dictionary and points to its word list.

Option Precedence

1. Paths given by --dict-path (in the order provided).
2. Paths listed in CSPELL_DICT_PATH (left to right, separated by : or ;).
3. Default Node resolution from the current project tree.

The first match wins. If no match is found, cspell reports a missing import.

OPTIONS

--dict-path

    Add a directory to the dictionary search path.
    May be repeated.

Example:

cspell --dict-path ./vendor/lib/node_modules \
       --dict-path /opt/cspell-dicts/lib/node_modules \
       "src/**/*.ts"

ENVIRONMENT

CSPELL_DICT_PATH
    A list of directories to search for dictionary packages.
    On POSIX systems, entries are separated by :.
    On Windows, entries are separated by ;.

Example:

export CSPELL_DICT_PATH="/nix/store/…-dict-fr-fr/lib/node_modules:/nix/store/…-dict-python/lib/node_modules"

DIRECTORY CONTENTS

Each directory listed in --dict-path or CSPELL_DICT_PATH is expected to
contain a structure equivalent to the top of a node_modules tree, with
scoped packages for dictionaries. For example:

<dir>/
└── @cspell/
    ├── dict-fr-fr/
    │   ├── cspell-ext.json
    │   ├── fr_FR.trie.gz
    │   └── package.json
    └── dict-python/
        ├── cspell-ext.json
        ├── python.txt.gz
        └── package.json

• cspell-ext.json defines the dictionary (name, path to word list, etc.).
• The .trie.gz or .txt.gz file is the actual word list.
• package.json is included for compatibility with Node package layout.

A single directory may contain multiple dictionary packages under
@cspell/….

EXAMPLES

Use environment variable in a Nix shell:

addToSearchPath CSPELL_DICT_PATH "$out/lib/node_modules"
cspell "**/*.ts"

Run with an explicit extra dictionary path:

cspell --dict-path ./local-dicts/node_modules "**/*.md"

SEE ALSO

cspell(1), cspell.json configuration schema, cspell-ext.json in
@cspell/dict-* packages.

---

Note that it would be nice if in addition to the above, there was a way to request for the dict to be automatically imported and usable in the same way as when I install a dict via a vscode extension.