itube-specs 0.0.781 → 0.0.782

package/README.md

@@ -1,15 +1,132 @@
-Пакет является nuxt layer проектов itube;
-https://bitbucket.org/luckytube/specs/src/master/  
-Как работать:  
-1) коммитим, проверяем актуальная ли версия, потом `npm run patch` - патчим версию, пушим, принимаем мерж;     
-2) `npm i itube-specs` ставим пакет в проекте;  
-3) Если не первый раз то обновляем пакет `npm install @test/test@latest` или `npm run spec`;  
-4) `npx nuxi prepare` при необходимости (могут не подсасаться композиблы или компоненты в автоимпорте);  
-5) если есть проблемы с runtime запустить в пакете npm run dev он перегенерирует tsconfig и eslint.config.mjs;  
-6) для дебага, в простых случаях импортим напрямую с диска нужную сущность, прям буквально `import {test} from '../../../../specs/runtime/utils'`  
-в сложных случаях (например сложные компоненты с вложенными компонентами) в проекте есть папка `/components/debug` копируем нужные компоненты туда все с которыми собираемся работать, правим там если надо путь до утилит (на типы пофиг они не сломают ниче), пересобираем автоимпорты командой `npx nuxi prepare` и дальше запускаем проект как всегда. После работы не забываем очищать папку debug и копировать обратно в спеку, комитить и патчить фиксы.
+# itube-specs
+
+Общий **Nuxt Layer** для сайтов itube. Держит единую базу: компоненты, composables, сервисы, утилиты,
+runtime-хелперы, типы и lib-данные. Приложения расширяют слой (`extends: ['itube-specs']`) и форкаются
+под разные сайты одной ниши — поэтому слой должен оставаться **самодостаточным и site-agnostic**.
+
+> Bitbucket: https://bitbucket.org/luckytube/specs/src/master/
+
+---
+
+## Стек
+
+- **Nuxt 3** + **Vue 3.5**, TypeScript
+- **@nuxt/icon**, **@nuxtjs/i18n**, **@nuxt/eslint** — как модули слоя
+- **ESLint** + **Stylelint** (гейтят на ноль варнингов), **Vitest** (юнит)
+- Публикуется в npm; приложения ставят опубликованную версию
+
+**Требования:** Node `>=22.12`.
+
+---
+
+## Как работать со слоем
+
+Слой публикуется в npm, приложения используют **опубликованную** копию (`node_modules/itube-specs`).
+**Локальные правки не видны приложению, пока не опубликована новая версия.**
+
+1. Коммитим правки в слое.
+2. `npm run patch` — патчим версию → пуш → мерж.
+3. В проекте: `npm run spec` (`npm install itube-specs@latest`), при необходимости `npx nuxi prepare`
+   (если не подхватились автоимпорты composables/компонентов).
+4. При runtime-проблемах — `npm run dev` в слое перегенерит `tsconfig` и `eslint.config.mjs`.
+
+> **npm install и другие команды, меняющие зависимости, в этом репозитории не запускаем** — зависимости
+> и публикацию ведёт мейнтейнер вручную. Править `package.json` можно, ставить пакеты — нет.
+
+### Отладка из приложения
+
+Правим слой прямо здесь (по `LAYER_PATH`), затем `npm run patch` + `npm run spec` в приложении.
+
+Чтобы видеть изменения без публикации — **локальный оверрайд** в приложении: копируем компонент/composable
+в проект по **тому же относительному пути** (`components/<...>.vue` / `composables/<...>.ts`), `npx nuxi prepare`
+— копия перекрывает слой на рантайме (приложение выше слоя по приоритету; при `pathPrefix` имя совпадает
+со слоевым). Правим копию, после — переносим в слой, `npm run patch` + `npm run spec`, копию удаляем.
+Импорты в копии чиним на пакетные (`itube-specs/runtime|types|lib|services|utils`).
+
+Для мелких утилит/runtime можно и грубее — временный disk-импорт с диска
+(`import { test } from '../../../../specs/runtime/utils'`), только для локальной отладки, в коммит не идёт.
+
+---
+
+## Команды
+
+```bash
+npm run lint         # ESLint (гейтит на ноль варнингов)
+npm run lint:fix     # ESLint --fix
+npm run lint:css     # Stylelint по **/*.{scss,vue}
+npm run lint:css:fix # Stylelint --fix
+npm run test         # vitest однократно
+npm run patch        # npm version patch — бамп версии перед публикацией
 ```
-import type { IUser } from '@test/test/types'
+
+Pre-commit (husky + lint-staged): на закоммиченных файлах прогоняются `eslint --fix` и `stylelint --fix`.
+
+---
+
+## Структура
+
 ```
-Types не импортируются автоматически, каждый тип в свою очередь экспортируется в index.d.ts (обязательно указывать расширение при эскпорте d.ts) общий файл откуда уже и берутся все типы в проект.  
-Все что кроме nuxt сущностей (composables, components) устанавливается прописывается вручную.  
+components/    # общие компоненты (pathPrefix: имя = папка + файл)
+composables/   # автоимпортируемые composables (+ fetch/, __tests__/)
+services/      # синглтон-клиенты внешнего API (services/api/*) + SiteDataService
+utils/         # доменные утилиты (file = function, co-located __tests__/)
+runtime/       # runtime-значения и хелперы (barrel index.ts)
+  constants/   # доменные `as const` (Niche, PlaylistType, AdSpotType, …)
+  utils/       # чистые хелперы, cleaners/, converters/
+types/         # .d.ts типы (barrel index.d.ts — с расширением .d.ts в реэкспортах)
+lib/           # статические scheme/config-данные (barrel index.ts)
+```
+
+---
+
+## Импорты
+
+Внутри слоя — **относительные пути** (`../../runtime`, `../types`, `../../services/api/...`), никогда не
+через имя пакета. Приложения импортируют как `itube-specs/runtime`, `itube-specs/services/...`,
+`itube-specs/utils/...`, а типы — `itube-specs/types`.
+
+Алиасы `~/…`/`@/…` в файле слоя резолвятся на **приложение**, не на слой — для кода слоя их не используем
+(допустимо только для намеренных app-зависимостей, например рекламный компонент → `~/config`/`~/utils`).
+
+### `files` / `exports`
+
+`package.json` определяет, что публикуется и как резолвится. Добавляя новую top-level папку, которую
+импортируют приложения:
+- добавь её в **`files`** (иначе код не попадёт в пакет);
+- добавь **`exports`**: barrel'ы (`types`/`runtime`/`lib`) — явные index-энтри; extensionless-сабпасы
+  (`services`/`composables`/`utils`) — паттерн с `.ts` (`"./services/*": "./services/*.ts"`); компоненты
+  импортятся с `.vue` и идут через `"./*": "./*"`.
+
+Типы экспортируются из `types/index.d.ts` — **обязательно с расширением `.d.ts`** в реэкспортах.
+
+---
+
+## Что живёт в слое, а что в приложении
+
+- **Слой:** переиспользуемые компоненты, composables, API-сервисы, доменные утилиты, runtime-константы/хелперы,
+  типы, scheme/lib-данные — всё site-agnostic.
+- **Приложение:** фича-флаги и прочий `config/`, `assets/scss` (токены), плагины (`$features`, реклама,
+  sentry), страницы, i18n-локали, BFF-хендлеры `server/` — всё site-specific и завязанное на окружение.
+
+---
+
+## Конвенции
+
+Полные правила — в [**CLAUDE.md**](./CLAUDE.md). Кратко:
+
+- **Компоненты** — `pathPrefix: true`: имя = папка + файл (`ui/icon.vue` → `<UiIcon>`), BEM-класс = kebab
+  тега. Корень папки — `index.vue` (или `main.vue`, если иначе имя было бы односложным).
+- **`as const`** вместо `enum` — доменные наборы в `runtime/constants/`.
+- **Стили** — co-location в `<style lang="scss">` без `scoped`, flat-BEM, только дизайн-токены.
+  ⚠️ Токены (`vars`/`mixins`) инжектит **приложение** — в слое нет `assets/scss` и `sass`, стили компонентов
+  компилируются только внутри приложения.
+- **Разметка** — семантические теги, `<div>` только когда ничего не подходит.
+- **TS/JS** — всегда точка с запятой, без лишних комментариев.
+
+---
+
+## Тесты
+
+Vitest через `@nuxt/test-utils`. В слое — **только тесты без app-специфичного окружения** (чистая логика
+composables/utils/runtime). Компонентные тесты с монтированием SFC и всё, что требует app-инжектов
+(`$features`, SCSS-токены), живёт в **приложении** — в слое нет ни scss-инъекции, ни плагинов приложения.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.781",
+  "version": "0.0.782",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {