Linting, Formatting & Pre-commit Hooks

Обзор Pipeline

Проект использует комплексный pipeline для автоматической проверки качества кода:

Git Commit
    ↓
Husky (pre-commit hook)
    ↓
lint-staged
    ↓
1. Remove Comments Script
    ↓
2. Remove Return Types Script
    ↓
3. ESLint --fix
    ↓
4. Prettier --write
    ↓
Changes staged
    ↓
Commit allowed

---

Компоненты

1. Husky

Назначение: Управление Git hooks

Конфигурация: .husky/pre-commit

pnpm exec lint-staged

Установка:

# Автоматически выполняется при pnpm install
pnpm prepare

2. lint-staged

Назначение: Запуск linters только на измененные файлы

Конфигурация: package.json

"lint-staged": {
  "*.{ts,tsx}": [
    "tsx scripts/remove-comments.script.ts --no-backup",
    "tsx scripts/remove-return-types.script.ts --no-backup",
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}

3. Remove Comments Script

Файл: scripts/remove-comments.script.ts

Назначение: Автоматическое удаление всех комментариев из кода

Логика:

• Удаляет однострочные (//) и многострочные (/* */) комментарии
• Сохраняет shebang (#!)
• Заменяет многострочные комментарии пробелами (сохраняет позиции)
• Удаляет однострочные целиком

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

# Все файлы
pnpm tsx scripts/remove-comments.script.ts

# Конкретные файлы
pnpm tsx scripts/remove-comments.script.ts src/app.ts src/index.ts

# Режимы
--dry-run       # Показать что будет изменено без изменения
--no-backup     # Не создавать резервные копии
--verbose       # Подробный вывод

4. Remove Return Types Script

Файл: scripts/remove-return-types.script.ts

Назначение: Удаление явных return type аннотаций

Логика:

• Удаляет return types из функций, методов, arrow функций
• Работает через TypeScript AST
• Проверяет что после типа идёт {, ; или =>

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

# Все файлы
pnpm tsx scripts/remove-return-types.script.ts

# Конкретные файлы
pnpm tsx scripts/remove-return-types.script.ts src/app.ts

# Режимы
--dry-run       # Показать что будет изменено
--no-backup     # Не создавать резервные копии
--verbose       # Подробный вывод с изменениями
--debug         # Отладочная информация

5. ESLint

Файл: eslint.config.js

Ключевые правила:

Правило	Значение	Назначение
@typescript-eslint/explicit-function-return-type	off	Не требуем явные return types (удаляются скриптом)
@typescript-eslint/no-unused-vars	["error", { argsIgnorePattern: "^_" }]	Неиспользуемые переменные, но _ игнорируем
no-multiple-empty-lines	["error", { max: 1 }]	Максимум 1 пустая строка подряд
eol-last	["error", "always"]	Новая строка в конце файла
no-trailing-spaces	error	Нет пробелов в конце строк
semi	["error", "always"]	Точка с запятой обязательна
@typescript-eslint/no-explicit-any	warn	Warning на any (не блокирует)

Запуск:

# Проверка
pnpm lint

# Автоисправление
pnpm lint:fix

# Конкретный пакет
pnpm --filter sofa lint

6. Prettier

Назначение: Автоматическое форматирование кода

Файл: .prettierrc (или default конфиг)

Форматирует:

• TypeScript файлы (.ts, .tsx)
• JSON, YAML, Markdown

Запуск:

# Форматирование всех файлов
pnpm format

# Проверка без изменений
pnpm prettier --check .

---

Workflow при коммите

Нормальный поток (успешно)

$ git commit -m "feat: add feature"

husky > pre-commit (node_modules/.bin/husky)
husky > Running lint-staged

  ✔ Preparing files...
  ✔ Running tasks for staged files...
  ↓ src/handlers/agent-init.ts
    ✔ Remove comments
    ✔ Remove return types
    ✔ ESLint
    ✔ Prettier
  ✔ Reverting any changes from tasks...
  ✔ Cleaning up temporary files...

[feature-branch 1a2b3c4] feat: add feature
 1 file changed, 10 insertions(+), 5 deletions(-)

Ошибка линтера (блокирует коммит)

$ git commit -m "feat: add feature"

↓ src/app.ts
  ✔ Remove comments
  ✔ Remove return types
  ✖ ESLint fix

✖ 1 lint issue found
✖ 1 lint issue preventing commit

  src/app.ts:25:1  error  'unusedVar' is assigned a value but never used  @typescript-eslint/no-unused-vars

Решение:

# Исправить вручную или переименовать в _unusedVar
# Попробовать коммит снова
git add src/app.ts
git commit -m "feat: add feature"

---

Полезные команды

Команда	Описание
pnpm lint	Проверка всех файлов
pnpm lint:fix	Автоисправление всех файлов
pnpm format	Форматирование всех файлов
pnpm clean:code	Удалить комментарии и return types
pnpm clean:comments	Только удалить комментарии
pnpm clean:return-types	Только удалить return types
pnpm pre-deploy	Выполнить полную подготовку: clean:code + lint:fix + format

---

Пропуск Pre-commit Hook

Иногда нужно пропустить проверки (не рекомендуется):

# Пропустить Husky check
git commit --no-verify

# Или
git commit -n

⚠️ Используйте осторожно - нарушает качество кода

---

Настройка в IDE

VSCode

Установите расширения:

• ESLint
• Prettier

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

{
	"editor.formatOnSave": true,
	"editor.defaultFormatter": "esbenp.prettier-vscode",
	"[typescript]": {
		"editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"eslint.validate": ["typescript", "typescriptreact"]
}

WebStorm / IntelliJ IDEA

1. Settings → Languages & Frameworks → TypeScript → Linters → ESLint
2. Settings → Languages & Frameworks → TypeScript → Code Quality Tools → Prettier

---

Troubleshooting

"pnpm: command not found" в Husky

Убедитесь что pnpm установлен глобально:

npm install -g pnpm

Husky не запускается

# Переустановить Husky
rm -rf .husky
pnpm install

# Или явно запустить prepare
pnpm prepare

Changes не стагируются после lint-staged

Это нормально - lint-staged автоматически добавляет исправленные файлы. Просто повторите коммит:

git commit -m "feat: message"

"Remove return types" удалил нужный тип

Типы всё ещё в коде TypeScript и ESLint их проверяет. Return types удаляются для выпуска, но IDE и тестирование полностью типизированы.

---

Связанные документы

• CODE_RULES.md - правила написания кода
• DEVELOPMENT.md - разработка
• QUICK_START.md - быстрый старт