hunspell -> cspell

.claude/rules/documentation.md

@@ -71,44 +71,57 @@ blocks stripped out. This is what the spell checker runs over.
 | Script | Output | Source |
 |--------|--------|--------|
 | `gen_reference_doc.py` | `reference-*.rst`, `reference.rst`, `single-page-ref.rst`, `plain_text_out.txt` | public headers |
-| `gen_settings_doc.py` | `settings.rst` + appends settings names to `hunspell/settings.dic` | `settings_pack.hpp` |
+| `gen_settings_doc.py` | `settings.rst` + appends settings names to `settings.dic` | `settings_pack.hpp` |
 | `gen_stats_doc.py` | `stats_counters.rst` | `session_stats.cpp`, `performance_counters.hpp` |
 | `gen_todo.py` | `todo.html` | `src/*.cpp`, headers |
 | `filter-rst.py` | `*-plain.txt` (prose-only) | a hand-written `.rst` file |
 
 `gen_settings_doc.py` doubles as a dictionary source: it splits every setting
-name on `_` and adds the parts to `hunspell/settings.dic`, so setting-name
+name on `_` and adds the parts to `settings.dic`, so setting-name
 fragments are not flagged as misspellings.
 
-## Spell Checking (hunspell)
+## Spell Checking (cspell)
 
-Spell checking uses **hunspell**, run via `make spell-check` from `docs/`:
+Spell checking uses **[cspell](https://cspell.org/)**, run via `make spell-check`
+from `docs/`. cspell is pinned to an exact version via `docs/package.json` +
+`docs/package-lock.json` (the lockfile records a sha512 integrity hash for
+every package in cspell's dependency tree, not just cspell itself), so
+install it once with `npm ci` before running the checker for the first time
+or after the pin changes:
 
 ```sh
+cd docs && npm ci
 cd docs && make spell-check
 ```
 
+`docs/makefile` invokes the locally-installed binary at
+`node_modules/.bin/cspell` (overridable via `make CSPELL=cspell spell-check`
+to use a system-wide install instead).
+
 The flow:
 1. Generated reference prose is in `plain_text_out.txt` (from
    `gen_reference_doc.py --plain-output`).
 2. Hand-written manuals are converted to prose-only text with
    `filter-rst.py` (e.g. `manual.rst` -> `manual-plain.txt`). `filter-rst.py`
    strips RST directives (`.. ` lines) and indented literal/code blocks so
    only natural-language text remains.
-3. `hunspell -l` lists misspelled words from each plain-text file into
-   `hunspell-report.txt`, using dictionary `hunspell/en_US` plus the project
-   word list `hunspell/libtorrent.dic` (settings text uses the generated
-   `hunspell/settings.dic`). HTML manuals are checked with `-H` (HTML mode).
-4. If `hunspell-report.txt` is non-empty the target **fails** and prints the
-   offending words.
+3. `cspell` checks every plain-text file plus the built HTML manuals in one
+   invocation, using `docs/cspell.json` (which loads the project word list
+   `settings.dic`, a superset of `libtorrent.dic` with
+   setting-name fragments added). cspell reports each misspelling as
+   `file:line:col`, unlike the old hunspell-based check, which only produced a
+   flat, location-less word list.
+4. `cspell` exits non-zero on any misspelling, which fails the `make` target
+   directly.
 
 ### Fixing spell-check failures
 
 Either correct the typo in the source, or -- if the word is a real term,
-identifier, or acronym -- add it to **`docs/hunspell/libtorrent.dic`** (one
-word per line). `hunspell/en_US.{aff,dic}` is the stock English dictionary and
-should not be edited. `hunspell/settings.dic` is generated (en_US + the
-settings names + a copy of `libtorrent.dic`); do not hand-edit it.
+identifier, or acronym -- add it to **`docs/libtorrent.dic`** (one
+word per line). `docs/settings.dic` is generated (setting-name
+fragments + a copy of `libtorrent.dic`); do not hand-edit it. cspell's stock
+English dictionaries are bundled with the tool and are not vendored in the
+repo.
 
 ## Building the HTML
 
@@ -125,10 +138,11 @@ the checked-in hand-written `.rst` manuals).
 
 ## CI
 
-`.github/workflows/docs.yml` installs `python3-docutils`, `hunspell`,
-`graphviz`, `imagemagick`, `aafigure`, etc., then runs
-`make spell-check html`. A documentation warning, an undocumented public
-symbol, a `TODO:` in a doc comment, or a spelling error all fail the build.
+`.github/workflows/docs.yml` installs `python3-docutils`, `graphviz`,
+`imagemagick`, `aafigure`, etc., runs `npm ci` in `docs/` to install the
+pinned `cspell`, then runs `make spell-check html`. A documentation warning,
+an undocumented public symbol, a `TODO:` in a doc comment, or a spelling
+error all fail the build.
 
 ## Key Files
 
@@ -139,6 +153,8 @@ symbol, a `TODO:` in a doc comment, or a spelling error all fail the build.
 | `docs/gen_stats_doc.py` | `stats_counters.rst` |
 | `docs/filter-rst.py` | strip RST markup to prose for spell checking |
 | `docs/makefile` | `html`, `rst`, `spell-check`, `stage`, `clean` targets |
-| `docs/hunspell/libtorrent.dic` | project word list (edit to whitelist terms) |
-| `docs/hunspell/en_US.{aff,dic}` | stock English dictionary (do not edit) |
+| `docs/cspell.json` | cspell config (loads `settings.dic`) |
+| `docs/package.json` / `docs/package-lock.json` | pins cspell + its dependency tree by version and integrity hash |
+| `docs/libtorrent.dic` | project word list (edit to whitelist terms) |
+| `docs/settings.dic` | generated: `libtorrent.dic` + setting-name fragments |
 | `.github/workflows/docs.yml` | CI: spell-check + build |

.github/workflows/docs.yml

@@ -30,10 +30,15 @@ jobs:
 
       - name: install dependencies
         run: |
-          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-docutils python3-pygments python3-pil gsfonts inkscape icoutils graphviz hunspell imagemagick
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-docutils python3-pygments python3-pil gsfonts inkscape icoutils graphviz imagemagick
           python3 -m pip install aafigure
           ~/.local/bin/aafigure --version
 
+      - name: install cspell
+        run: |
+          cd docs
+          npm ci
+
       - name: spell-check
         run: |
           cd docs

.github/workflows/release.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: install dependencies
         run: |
-          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-docutils python3-pygments python3-pil gsfonts inkscape icoutils graphviz hunspell imagemagick rsync
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-docutils python3-pygments python3-pil gsfonts inkscape icoutils graphviz imagemagick rsync
           sudo DEBIAN_FRONTEND=noninteractive apt-get install -y libboost-tools-dev libboost-python-dev libboost-dev libboost-system-dev libboost-json-dev python3-setuptools
           python3 -m pip install aafigure
           python3 -m pip install websockets

.gitignore

@@ -73,6 +73,9 @@ dist
 # python binary
 bindings/python/compile_cmd
 
+# node/npm
+docs/node_modules
+
 # binaries in the examples directory
 examples/bt_get
 examples/bt_get2

.pre-commit-config.yaml

@@ -5,7 +5,8 @@ exclude: |
     (?x)^(
         # These files are vendored from elsewhere, don't process them
         LICENSE|
-        docs/hunspell/.*|
+        docs/libtorrent\.dic|
+        docs/version\.dic|
         src/ed25519/.*|
         include/libtorrent/aux_/route\.h|
         test/.*\.xml|

Makefile

@@ -92,6 +92,12 @@ DOCS_PAGES = \
   docs/python_binding.html        \
   docs/tuning-ref.html            \
   docs/settings.rst               \
+  docs/settings.dic               \
+  docs/libtorrent.dic             \
+  docs/version.dic                \
+  docs/cspell.json                \
+  docs/package.json               \
+  docs/package-lock.json          \
   docs/stats_counters.rst         \
   docs/troubleshooting.html       \
   docs/udp_tracker_protocol.html  \

docs/contributing.rst

@@ -39,9 +39,10 @@ enumerated on this page, please contact arvid@libtorrent.org or the `mailing lis
 	against the documentation.
 
 	For updates, please submit a `pull request`_. All documentation is in
-	restructured text (rst_). All documentation is spell checked with hunspell
-	which can be invoked via ``make spell-check`` in the docs directory. If
-	words are missing, please add them to ``docs/hunspell/libtorrent.dic``
+	restructured text (rst_). All documentation is spell checked with cspell_
+	which can be invoked via ``make spell-check`` in the docs directory (run
+	``npm ci`` there first, to install the pinned cspell). If words are
+	missing, please add them to ``docs/libtorrent.dic``
 
 3. Code
 	Contributing code for new features or bug-fixes is highly welcome. If you're interested
@@ -60,4 +61,5 @@ For outstanding things to do, see the `todo list`_.
 .. _`pull request`: https://github.com/arvidn/libtorrent
 .. _`todo list`: todo.html
 .. _rst: https://docutils.sourceforge.io/rst.html
+.. _cspell: https://cspell.org/
 

docs/cspell.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+    "version": "0.2",
+    "language": "en",
+    "dictionaryDefinitions": [
+        {
+            "name": "libtorrent-terms",
+            "path": "./settings.dic",
+            "addWords": false
+        },
+        {
+            "name": "libtorrent-version",
+            "path": "./version.dic",
+            "addWords": false
+        }
+    ],
+    "dictionaries": [
+        "libtorrent-terms",
+        "libtorrent-version"
+    ]
+}

docs/gen_settings_doc.py

@@ -139,7 +139,7 @@ def render_section(
 
         names.append(line)
 
-dictionary = open("hunspell/settings.dic", "w+")
+dictionary = open("settings.dic", "w+")
 for w in sorted(all_names):
     dictionary.write(w + "\n")
 dictionary.close()