@uzum-tech/cspell

Единообразный корпоративный CSpell-конфиг для проектов Uzum Tech.
Включает все словари команды, ignore-паттерны/регекспы, overrides и готовую интеграцию с VSCode/Cursor/WebStorm.

Установка

pnpm add -D @uzum-tech/cspell

Пакет автоматически предоставляет бинарник cspell и cspell-checkstaged — отдельно устанавливать cspell не нужно.

Использование

1. Создай cspell.config.mts в корне проекта

Vue / Nuxt

import { defineCspellVue } from '@uzum-tech/cspell';

const allowedWords: string[] = [
  // слова специфичные для проекта
];

export default defineCspellVue({ allowedWords });

Node / Backend

import { defineCspellNode } from '@uzum-tech/cspell';

const allowedWords: string[] = [];

export default defineCspellNode({ allowedWords });

2. Добавь скрипты в package.json

{
  "scripts": {
    "spell:check": "cspell '**/*.{js,ts,vue,mjs,mts}'",
    "spell:check-changed": "cspell-checkstaged"
  }
}

• spell:check — полная проверка всех файлов проекта
• spell:check-changed — проверка только новых строк в staged-файлах (для ручного запуска)

3. Добавь cspell-checkstaged в lint-staged

// .lintstagedrc
{
  "*.{js,jsx,vue,ts,tsx}": [
    "eslint --fix",
    "cspell-checkstaged"
  ]
}

cspell-checkstaged проверяет только добавленные строки в staged-файлах — не весь файл. Это гарантирует, что в коммит не попадают новые орфографические ошибки, не затрагивая уже существующие.

Опции

Обе функции принимают один опциональный объект типа CspellOptions.

import type { CspellOptions } from '@uzum-tech/cspell';

allowedWords?: string[]

Добавляет слова в словарь cspell для конкретного проекта поверх базового allowed-words.txt.

export default defineCspellVue({
  allowedWords: ['uzum', 'kapital', 'mylib'],
});

ignores?: string[]

Добавляет дополнительные пути в ignorePaths поверх базовых.

Базовые игноры уже включены: node_modules, dist, build, .nuxt, .output, coverage, lock-файлы, *.log.

export default defineCspellVue({
  ignores: ['src/generated/**', 'public/**'],
});

overrides?: CspellOverride[]

Добавляет кастомные overrides поверх базовых (по паттернам файлов).

import type { CspellOptions, CspellOverride } from '@uzum-tech/cspell';

const overrides: CspellOverride[] = [
  {
    filename: '**/migrations/**',
    ignoreRegExpList: ['/.*$/gm'],
  },
];

export default defineCspellNode({ overrides });

Бинарники

cspell

Стандартный CLI cspell, предоставляется пакетом — устанавливать отдельно не нужно.

cspell '**/*.{js,ts,vue,mjs,mts}'

Конфиг cspell.config.mts в корне проекта подхватывается автоматически.

cspell-checkstaged

Проверяет орфографию только в новых строках staged-файлов (анализирует git diff --cached).

cspell-checkstaged
# или с явным конфигом:
cspell-checkstaged --config path/to/cspell.config.mts

Принимает список файлов как аргументы (lint-staged передаёт их автоматически). Если аргументов нет — сам забирает staged-файлы через git.

При ошибке выводит:

  src/components/MyComponent.vue:
    - Unknown word: myword

  Add valid words to cspell.config.mts (allowedWords)

Базовые overrides

По умолчанию включены следующие overrides:

| Тип | Паттерн файлов | Описание | |----------------|-----------------------------------------|-----------------------------------------------| | SCRIPTS | **/*.{js,mjs,cjs,ts,mts,cts,vue} | TS/JS словари, игнор import/require строк | | VUE | **/*.vue (только defineCspellVue) | HTML/CSS/TS словари для Vue-шаблонов | | TESTS | **/*.{spec,test}.{js,ts} | Добавлены vitest/jest/mocha/chai/sinon | | CONFIGS | **/*.config.{js,ts,mjs,mts} | Добавлены vite/eslint/prettier/tailwind | | MARKDOWN | **/*.md | Locale en,ru | | PACKAGE_JSON | **/package.json | Весь контент игнорируется |

Структура пакета

src/
  bin/
    cspell.ts                    — обёртка над cspell CLI (bin: "cspell")
  custom-rules/
    check-new-errors.ts          — логика cspell-checkstaged (bin: "cspell-checkstaged")
  constants/
    cspell-config.mts            — словари, игноры, regex-паттерны, типы overrides
    check-new-errors.ts          — расширения файлов для staged-проверки
  utils/
    create-overrides.mts         — генерация overrides по типам
  types/
    cspell-config.types.mts      — CspellOverrideType, CspellOverride
    cspell-options.types.ts      — CspellOptions (публичный тип)
    check-new-errors.types.ts    — внутренние типы для cspell-checkstaged
  base.ts                        — ядро: сборка конфига через defineConfig()
  vue.ts                         — defineCspellVue()
  node.ts                        — defineCspellNode()
  index.ts                       — публичный API
allowed-words.txt                — общий словарь разрешённых слов (~320 слов)

FAQ

Почему VSCode/Cursor не показывает ошибки?

Должно быть установлено расширение Code Spell Checker. После установки — полностью перезапусти редактор.

Добавь в .vscode/settings.json:

{
  "cSpell.enabled": true,
  "cSpell.useGitignore": true
}

Нужно ли устанавливать cspell отдельно?

Нет. Пакет @uzum-tech/cspell предоставляет cspell как бинарник через bin поле — он доступен в node_modules/.bin/cspell сразу после установки.

Можно ли переопределить базовые overrides?

Нет — базовые overrides зафиксированы. Через опцию overrides можно только добавить свои поверх.

Чем cspell-checkstaged отличается от cspell?

cspell проверяет файлы целиком. cspell-checkstaged смотрит только на добавленные строки через git diff --cached — это позволяет внедрять проверку в проект с существующими ошибками: старые не блокируют коммит, новые — блокируют.