🌸 ayame-spell
日本語 README · Documentation · Design notes · Contributing
Fast, low-noise spell checker for code and prose — English & Japanese. One config file drives the CLI (CI), the LSP server, and the VS Code extension.
$ ayame-spell
docs/design.md:4:3: サーバ → サーバー [ja-variant]
docs/design.md:5:1: ABC123 → ABC123 [fullwidth-alnum]
src/main.rs:1:4: recieve → receive [typo]
src/main.rs:2:20: Nmae → Name [typo]
4 issue(s) in 2 file(s) — 214 file(s) checked
Why another spell checker?
Every existing tool picks one side of a trade-off:
| corrections-table tools(typos, codespell) | dictionary tools(cSpell, Harper) | |
|---|---|---|
| False positives | ~zero | constant (Kadane, heapq, …) |
| False negatives | misses unknown typos | ~zero |
| Best at | CI | interactive editing |
| Shared dictionaries | ✗ | ✓ (cSpell) |
| Bulk add/ignore | ✗ | weak (one word at a time) |
| Huge files | fast | cSpell silently stops at ~500 KB |
| Japanese | ✗ | ✗ |
ayame-spell unifies both modes behind one config, adds first-class bulk workflows, a shared dictionary registry, and Japanese notation checking — in a single fast Rust binary.
- corrections mode (default) — only known misspellings are flagged (built on the 95k-entry typos-dict table). Safe for CI, zero setup.
- dictionary mode (opt-in) — additionally flags words not in the active wordlists, with Levenshtein suggestions. Made livable by bulk triage.
- Japanese — 表記ゆれ detection that is quiet by default: it only reports when one document mixes two spellings of the same katakana word (サーバ vs サーバー). Plus fullwidth-alphanumeric, halfwidth-katakana, and fullwidth-space checks.
- Measured — the reproducible 35 MiB / 400k-line benchmark currently runs in 1.60 s (21.90 MiB/s); see the full environment, memory, and comparison results. No silent truncation, ever: skipped files are counted and reported.
Install
|
VS Code: install the ayame-spell extension. Platform-specific VSIX builds from GitHub Releases include the native server, so no Rust installation is required. See the extension guide. Homebrew, Scoop, PowerShell, Docker, AUR, archives, and checksum details are in the installation guide.
Shell completions
Generate a completion script for bash, zsh, fish, PowerShell, or Elvish:
# bash (bash-completion)
# zsh (add ~/.zfunc to fpath before running compinit in ~/.zshrc)
# ~/.zshrc:
fpath=(/.zfunc )
&&
# fish
For PowerShell, add the following line to $PROFILE:
ayame-spell completions powershell | Out-String | Invoke-Expression
For Elvish, add the following line to ~/.config/elvish/rc.elv:
eval (ayame-spell completions elvish | slurp)
Release archives also contain pre-generated scripts in completions/.
Dictionary names and words use local caches populated by dict list /
dict add and words collect; pressing Tab never waits for the network.
Quick start
# dictionary mode with shared wordlists:
ayame-spell words triage is the answer to "I don't want to restart for every
large batch": search and page through the findings, then add, ignore, fix, or
skip each word in one pass. The final summary names every changed file.
In VS Code the same flow is ayame-spell: Review Flagged Words.
For an existing repository, run ayame-spell baseline . and commit
ayame-spell-baseline.json. Normal checks then report only new findings;
check --no-baseline audits everything and baseline --prune removes entries
that no longer exist.
CI can be as small as uses: hjosugi/ayame-spell@v0.4.0; a composite Action,
pre-commit check/fix hooks, SARIF upload, GitLab, and CircleCI recipes are in the
CI guide.
Configuration
ayame-spell.toml (or .ayame-spell.toml) at the project root, merged
over the per-user global config ~/.config/ayame-spell/config.toml.
All keys are optional; the defaults are what you saw above.
See the complete configuration reference
for every key, default, merge rule, and override precedence rule.
Editor completion is available through the published
JSON Schema;
use ayame-spell config --validate to catch unknown keys with suggestions.
[]
= "corrections" # "corrections" | "dictionary" | "off"
= "any" # "any" | "en-US" | "en-GB"
= "auto" # syntax-aware "auto" | "prose" | "source" | "all"
= 3
= 40 # longer digit-bearing tokens = hashes, skipped
[]
= ["vendor/**"] # on top of .gitignore + built-in lock-file excludes
= false
= 0 # bytes; 0 = unlimited (skips are always reported)
[]
= "ayame-words.txt" # team dictionary, committed to git
= ["exmaple"] # never flagged, any mode
= ["registry:en-base", "./team-words.txt"]
[]
= true # 95k-entry English table (typos-dict)
= ["registry:my-corrections", "./fixes.tsv"] # typo<TAB>fix[,fix]
[]
= "the" # inline corrections
= "neet" # fix == typo → whitelist
[]
= true
= "consistency" # "consistency" | "long" | "short" | "off"
= ["registry:ja-tech-variants"]
= true # 123ABC → 123ABC
= true # カタカナ → カタカナ
= "code" # "code" | "always" | "never"
= true # ㎏ → kg, ㎡ → m2
= true
= true
= true
[]
= "インターフェース"
[[]] # per-glob settings; later entries win
= ["docs/**"]
= "dictionary"
= "prose"
Where do added words go?
| Action | File | Shared with |
|---|---|---|
| Add to project words | ayame-words.txt (committed) |
your team |
| Add to global words | ~/.config/ayame-spell/words.txt |
all your projects |
| Ignore | [words].ignore in ayame-spell.toml |
your team |
One rule everywhere: matching is case-insensitive, fixes preserve case
(Teh → The, TEH → THE).
Inline directives
ayame-spell:ignore-line (anywhere in the line)
ayame-spell:ignore-next-line
ayame-spell:ignore-file (anywhere in the file)
Dictionary registry
Shared dictionaries are plain text files served from
GitHub Pages, sha256-verified on
download and cached in ~/.cache/ayame-spell/:
$ ayame-spell dict list
en-base en wordlist 120531 English base wordlist (SCOWL ≤60)
python en wordlist 126 Python ecosystem terms
rust en wordlist 81 Rust ecosystem terms
web en wordlist 101 Web development terms
ja-variants ja variants 3173 Katakana notation variants (SudachiDict)
ja-tech-variants ja variants 42 Curated tech-writing katakana rules
$ ayame-spell dict add en-base # downloads + writes config and lockfile
$ ayame-spell dict update --check # reports available unlocked updates
$ ayame-spell dict vendor en-base # copies locked bytes into ./dict
Commit both ayame-spell.toml and ayame-spell.lock: teammates then resolve
the same version and sha256-verified bytes. Use registry:en-base@1.0.0 for an
explicit pin, or dict vendor for a network-independent project copy.
Registry URL is overridable with $AYAME_SPELL_REGISTRY or
dict --registry URL (for example, an internal index).
Japanese checks in detail
| Check | Example | Default |
|---|---|---|
| 表記ゆれ (consistency) | doc mixes サーバ & サーバー → flag minority | on |
| 表記ゆれ (style) | enforce long (サーバー) or short (サーバ) | opt-in |
| variant rules | インタフェース → インターフェース | via dictionaries |
| fullwidth alnum | 123ABC → 123ABC | on |
| halfwidth kana | データ → データ | on |
| fullwidth space | U+3000 in source code | on (code files only) |
The consistency default follows JIS Z 8301:2019 (which abolished the old "omit the long vowel" rule): ayame-spell does not impose a direction unless you ask for one.
Exit codes & output formats
0 clean · 1 issues found · 2 error.
--format human (default), brief, json (JSON Lines), github (workflow
annotations), and sarif (SARIF 2.1.0) are available. In GitHub Actions the
unspecified format automatically becomes github; pass --format human to
override it.
Use ayame-spell explain typo for a rule's rationale and configuration, or
ayame-spell rules to list every stable code.
License
MIT OR Apache-2.0. Bundled/derived data: see NOTICE.md (typos-dict, SCOWL, SudachiDict synonym dictionary).