npm package: @rotcetihra/ts-template-project
Description: Шаблонный преднастроенный TypeScript проект.
Author: Arhitector
Latest version: 0.4.0

# @rotcetihra/ts-template-project

Шаблон преднастроенного **TypeScript**-проекта для библиотек под **Node.js**
**(ESM)**. Включает строгий `tsconfig`, сборку с `tsc`, тесты на **Jest**
**(ESM + TS)**, документирование через **TypeDoc**, линтинг (**ESLint** +
**Prettier** + **CSpell**), `pre-commit` хуки (**Husky** + **lint-staged** +
**commitlint**), автоматическое ведение `CHANGELOG.md` (**standard-version**) и
готовые **CI/CD**-воркфлоу для **GitHub Actions** (сборка, релиз,
версионированные docs, публикация в **npm** и **GitHub Packages**).

---

## Содержание

- [@rotcetihra/ts-template-project](#rotcetihrats-template-project)
    - [Содержание](#содержание)
    - [Возможности](#возможности)
    - [Требования](#требования)
    - [Установка](#установка)
    - [Быстрый старт](#быстрый-старт)
    - [Скрипты npm](#скрипты-npm)
    - [Структура проекта](#структура-проекта)
    - [Типы и сборка (TypeScript)](#типы-и-сборка-typescript)
    - [Тестирование (Jest)](#тестирование-jest)
    - [Документация (TypeDoc)](#документация-typedoc)
    - [Код-стайл: ESLint, Prettier, CSpell](#код-стайл-eslint-prettier-cspell)
    - [Коммиты: Conventional Commits и commitlint](#коммиты-conventional-commits-и-commitlint)
    - [Автоверсионирование и CHANGELOG (standard-version)](#автоверсионирование-и-changelog-standard-version)
    - [CI/CD (GitHub Actions)](#cicd-github-actions)
        - [CI (`.github/workflows/ci.yml`)](#ci-githubworkflowsciyml)
        - [Release (`.github/workflows/release.yml`)](#release-githubworkflowsreleaseyml)
        - [Docs (versioned) (`.github/workflows/docs-versioned.yml`)](#docs-versioned-githubworkflowsdocs-versionedyml)
    - [Публикация](#публикация)
    - [Импорт из CJS](#импорт-из-cjs)
    - [Диагностика проблем](#диагностика-проблем)
    - [Лицензия](#лицензия)

---

## Возможности

- ✔️ **ESM + NodeNext**: современные импорты, строгая конфигурация TS.
- ✔️ **Jest + ts-jest**: юнит-тесты в ESM-окружении.
- ✔️ **TypeDoc**: генерация HTML-документации + версияция на GitHub Pages.
- ✔️ **ESLint (flat) + typescript-eslint + Prettier + CSpell**: статанализ,
  форматирование и проверка орфографии.
- ✔️ **Husky + lint-staged + commitlint**: pre-commit/commit-msg хуки и
  Conventional Commits.
- ✔️ **standard-version**: автоматическое обновление версии и CHANGELOG.
- ✔️ **GitHub Actions**: CI (линт, тип-чек, тесты, сборка), Release (GitHub
  Release → npm → GitHub Packages), Docs (версионированные).
- ✔️ **Tree-shaking**: `sideEffects: false`.
- ✔️ **Пути-алиасы**: `@/*` (через `tsc-alias` в сборке).

---

## Требования

- **Node.js** **≥ 18**.
- **npm** (или **pnpm/yarn** — при необходимости адаптируйте команды).

---

## Установка

```bash
# как зависимость (потребитель пакета):
npm i @rotcetihra/ts-template-project
```

> Пакет публикуется в **npm** и в **GitHub Packages**. Для установки из GitHub
> Packages настройте `~/.npmrc` с auth-токеном и реестром для scope
> `@rotcetihra`.

---

## Быстрый старт

```ts
// TypeScript / ESM
// Конкретные экспортируемые сущности см. в API-документации.
import * as Lib from '@rotcetihra/ts-template-project';

// пример вызова (подставьте реальные API):
// const result = Lib.doSomething();
```

> Проект **ESM**-только (`"type": "module"`). В исходниках **NodeNext** требует
> указывать суффиксы `.js` в импортах; **Jest** маппит их обратно на `.ts` в
> тестах.

---

## Скрипты npm

Наиболее востребованные:

```bash
npm run build        # сборка исходников + генерация docs (если так настроено)
npm run src:build    # только сборка TS -> dist (c tsc + tsc-alias)
npm run clean        # очистка dist и docs
npm test             # юнит-тесты (ESM+TS)
npm run docs:build   # генерация HTML-документации в ./docs
npm run docs:serve   # локальный просмотр документации
npm run lint         # ESLint
```

> В проекте также используются **pre-commit/commit-msg** хуки **Husky**: перед
> коммитом запускаются форматирование/линтинг/проверка орфографии, а сообщение
> коммита проверяется **commitlint**.

---

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

```
├─ src/                   # исходный код (TS)
│  └─ index.ts            # корневой экспорт API для TypeDoc и потребителей
├─ tests/                 # юнит-тесты (TS)
├─ dist/                  # сборка (JS, d.ts, sourcemaps) — создаётся tsc
├─ docs/                  # HTML-документация (TypeDoc)
├─ typedoc.json           # конфигурация TypeDoc
├─ tsconfig.base.json     # базовый TS-конфиг (NodeNext, strict, paths)
├─ tsconfig.json          # конфиг для IDE / локальной разработки (noEmit)
├─ tsconfig.build.json    # конфиг сборки (outDir=dist, declaration=true)
├─ eslint.config.js       # ESLint (flat, typescript-eslint, Prettier)
├─ prettier.config.cjs    # Prettier
├─ cspell.json            # CSpell (en, ru + пользовательский словарь)
├─ commitlint.config.cjs  # commitlint (Conventional Commits)
└─ .github/workflows/     # CI/CD (CI, Release, Docs versioned)
```

---

## Типы и сборка (TypeScript)

- **NodeNext** (`module`/`moduleResolution`) и строгие проверки (`strict`,
  `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` и т.д.).
- **Пути-алиасы**: `@/* → src/*` (см. `tsconfig.base.json`). На этапе сборки
  алиасы переписываются в относительные пути **tsc-alias**.
- **Сборка**: `tsc -p tsconfig.build.json` генерирует `dist` (JS + `d.ts` +
  sourcemaps).
- **Советы**:
    - экспортируйте публичный API через `src/index.ts` — это упростит
      документацию и “surface area”.

---

## Тестирование (Jest)

- Настроен `jest` + `ts-jest` для **ESM + TypeScript**.
- Маппинг `.js` суффиксов (NodeNext) обратно на `.ts` в тестах, а также резолв
  `@/*` алиаса.
- Запуск:

```bash
npm test
```

> Покрытие кода собирается провайдером V8. Папка `coverage` прикладывается
> артефактом в CI.

---

## Документация (TypeDoc)

- Конфигурация: `typedoc.json` (тема `typedoc-github-theme`, плагины MDN links,
  rename-defaults).
- Сборка:

```bash
npm run docs:build
npm run docs:serve  # локальный просмотр
```

- **Версионирование документации**: отдельный workflow публикует каждую версию
  под `/vX.Y.Z` на ветку `gh-pages` и поддерживает переключатель версий (список
  хранится в `versions.json` на страницах).

---

## Код-стайл: ESLint, Prettier, CSpell

- **ESLint** (flat config) + `typescript-eslint`:
    - быстрый проход без type-info и выборочный строгий проход с type-info по
      `src/` и `tests/`;
    - пресеты `recommended`, `recommendedTypeChecked`, `stylisticTypeChecked`;
    - конфликты с форматированием глушатся `eslint-config-prettier`.

- **Prettier**: единый стиль форматирования; конфиг в `prettier.config.cjs`.
- **CSpell**: орфография (en, ru) + пользовательские слова; конфиг
  `cspell.json`.

---

## Коммиты: Conventional Commits и commitlint

- Проверка сообщений коммитов через **commitlint** (hook `commit-msg`), базовый
  конфиг — `@commitlint/config-conventional`.
- Рекомендуемые типы: `feat`, `fix`, `perf`, `refactor`, `docs`, `style`,
  `test`, `build`, `ci`, `chore`, `revert` + расширения `deps`, `security`,
  `release` (при необходимости).
- Пример:

```
feat(core): добавить поддержку X

описание изменений и мотивация

Refs: #123
```

---

## Автоверсионирование и CHANGELOG (standard-version)

- Генерация CHANGELOG и bump версии на основе Conventional Commits:

```bash
# автоматически выбрать тип версии по истории
npx standard-version

# либо явно
npx standard-version --release-as minor | major | patch
# или точной версией
npx standard-version --release-as 0.3.2
```

- После генерации выполните:

```bash
git push --follow-tags origin main
```

> В Release-воркфлоу CHANGELOG-секция заполняет описание GitHub Release.

---

## CI/CD (GitHub Actions)

### CI (`.github/workflows/ci.yml`)

- Триггеры: `push`, `pull_request` в `main`.
- Матрица Node 18/20/22: линт, type-check, тесты, сборка, TypeDoc.
- Загружает артефакты: `coverage`, `dist`, `docs`.

### Release (`.github/workflows/release.yml`)

- Триггер: `push` тега `v*` или ручной запуск.
- Шаги:
    1. Проверка соответствия `tag` ↔ `package.json version`.
    2. Создание **GitHub Release** (тело из CHANGELOG за версию).
    3. Публикация в **npm** (только при успешном Release; `NODE_AUTH_TOKEN` =
       `NPM_TOKEN`).
    4. Публикация в **GitHub Packages** (при успешном Release; токен
       `GITHUB_TOKEN`).

> Секреты: `NPM_TOKEN` (automation token из npm). Разрешения в workflow уже
> настроены.

### Docs (versioned) (`.github/workflows/docs-versioned.yml`)

- Триггер: `push` тега `v*`.
- Генерирует docs и выкладывает на `gh-pages` с версионными подпапками и
  переключателем версий.

---

## Публикация

- **npmjs**: происходит автоматически из Release-воркфлоу при успешном GitHub
  Release.
- **GitHub Packages**: публикуется в `https://npm.pkg.github.com` (scope
  `@rotcetihra`).
- Локально (при необходимости):

```bash
# проверка, что опубликуется (dry-run)
npm publish --access public --provenance --dry-run
# публикация
npm publish --access public --provenance
```

---

## Импорт из CJS

Пакет — ESM. В CommonJS подключайте через динамический `import()` или
`createRequire`:

```js
// CJS
(async () => {
    const lib = await import('@rotcetihra/ts-template-project');
    // lib.default / именованные экспорты
})();
```

---

## Диагностика проблем

- **“Cannot use import statement outside a module” при тестах** Используйте
  настроенный `npm test` (Jest запущен с ESM-поддержкой).
- **Алиасы `@/*` не разрешаются в рантайме** Убедитесь, что сборка выполнялась
  через `npm run src:build` (включает `tsc-alias`).
- **Release не публикует в реестры** Проверяйте логи шага “Create GitHub
  Release”: публикации выполняются **только** при его успехе и совпадении тега с
  `package.json`.
- **CSpell мешает коммиту** Добавляйте служебные слова в `cspell.json → words`
  либо исключайте пути через `ignorePaths`.

---

## Лицензия

MIT. Дополнительный неофициальный перевод лицензии — в `LICENSE.ru.md`.