@bonesofspring/ai-rules 0.1.36 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/cursor/next/rules/README.md

@@ -36,6 +36,7 @@
 | `code-review-mr.mdc` | Чеклист ревью MR, в т.ч. HTTP‑клиент и тесты |
 | `tests-unit.mdc` | Unit‑тесты и behavior‑тесты HTTP‑клиента |
 | `playwright-agents.mdc`, `tests-e2e-structure.mdc` | E2E |
+| `react-ui.mdc` | React/Next UI: структура компонентов, соседние `ComponentName.data.ts` / `.utils.ts`, стили, пропсы |
 
 **Коллизии формулировок:** если в разных `.mdc` расходятся детали **импорта типов**, источник правды — **`types-public-imports.mdc`** (`@/types`, `@/types/enums`); по **импорту из API‑слоя** (store, UI, прочий код вне `app/src/api/**`) — **`api-public-imports.mdc`** (`@/api`), в том же смысле что правило ESLint `no-restricted-imports` в `app/eslint.config.mjs`.
 

package/presets/cursor/next/rules/code-quality-and-refactoring.mdc

@@ -35,6 +35,12 @@ alwaysApply: true
   - сначала локально улучшить архитектуру минимальными шагами;
   - оставить код в консистентном состоянии.
 
+# ESLint и плагины
+
+- Учитывать **все активные правила ESLint** и **подключённые плагины** проекта (конфиг: `app/eslint.config.mjs`, базовые пресеты в т.ч. `@sh/eslint-config-react`, `@sh/eslint-config-boundaries` и локальные overrides).
+- Новый или изменённый код не должен нарушать эти правила. Перед завершением правок по возможности прогонять ESLint на затронутых файлах.
+- Отключение правила (`eslint-disable`) — только **точечно** (строка/небольшой блок) и с **кратким комментарием**, зачем это нужно; отключать «на весь файл» без веской причины не следует.
+
 # Требование к агенту
 
 При каждом изменении:

package/presets/cursor/next/rules/css-property-order-stylelint.mdc

@@ -0,0 +1,25 @@
+---
+description: Порядок CSS-свойств по Stylelint (idiomatic-order) — для любых стилей в проекте
+alwaysApply: true
+---
+
+# Порядок CSS-свойств (как в Stylelint)
+
+Действует для **любого** CSS в репозитории: `.css`, стилевые блоки в `styles.ts` / `styles.tsx`, `styled` / Linaria и другой CSS-in-JS в `.ts` / `.tsx`, если этот код попадает под `yarn lint:css`.
+
+Источник: `app/.stylelintrc` → `@sh/stylelint-config-react` → пакет **`stylelint-config-idiomatic-order`** (правило `order/properties-order`). Свойства, не попавшие в список, идут **в конце блока в алфавитном порядке** (`unspecified: bottomAlphabetical`).
+
+Пиши объявления в **одном** блоке в такой последовательности групп:
+
+1. **`composes`** — только для CSS Modules (если есть).
+2. **`all`**
+3. **Позиционирование:** `position`, `z-index`, затем `top`, `right`, `bottom`, `left`.
+4. **Отображение и раскладка:** `display`, `overflow`.
+5. **Размеры:** `width`, `min-width`, `max-width`, `height`, `min-height`, `max-height`, `box-sizing`.
+6. **Flex:** `flex`, `flex-basis`, `flex-direction`, `flex-flow`, `flex-grow`, `flex-shrink`, `flex-wrap`, `align-content`, `align-items`, `align-self`, `justify-content`, `order`.
+7. **Внутренние отступы:** `padding-top`, `padding-right`, `padding-bottom`, `padding-left`.
+8. **Рамка:** общие `border`, `border-width`, `border-style`, `border-color`, `border-radius`; затем для сторон **сверху по часовой** — `border-top` и его `-width`, `-style`, `-color`, `-radius`, то же для `right`, `bottom`, `left`.
+9. **Внешние отступы:** `margin-top`, `margin-right`, `margin-bottom`, `margin-left`.
+10. **Остальные свойства** — после перечисленных, **по алфавиту** (типографика, фон, анимации, `cursor`, и т.д.).
+
+Автоисправление из каталога `app`: `yarn lint:css --fix` (проверяет `**/*.{css,ts}`).

package/presets/cursor/next/rules/no-cross-component-styles-import.mdc

@@ -0,0 +1,55 @@
+---
+description: Стили компонентов — колокация, импорты, корневой styled как Root
+alwaysApply: true
+---
+
+# Стили только рядом с компонентом
+
+## Имя корневого styled-элемента: `Root`
+
+- В `styles.ts` (или аналоге) **корневой** styled-элемент — тот, что оборачивает весь JSX компонента — экспортируется как **`Root`**.
+- В разметке: `<s.Root>...</s.Root>` при `import * as s from './styles'`.
+- Вложенные и соседние примитивы именуются по смыслу: `Title`, `List`, `Item`, `Header` и т.д.
+- Если нет одной styled-обёртки на весь компонент (только фрагмент или один нативный тег без своего styled), экспорта `Root` может не быть. Когда вводится **одна** внешняя styled-обёртка всего JSX — она называется **`Root`**, а не `Container`, `Wrapper`, `Block` и т.п.
+
+```tsx
+// ✅ Хорошо
+export const Root = styled.div` ... `
+// в компоненте: <s.Root>...</s.Root>
+
+// ❌ Плохо для единственной обёртки всего компонента
+export const Service = styled.div` ... `
+```
+
+## Правило
+
+**Запрещено** импортировать модули стилей, которые лежат в каталоге **другого** UI-компонента или блока (не в том же каталоге, что и текущий файл).
+
+Под «модулями стилей» имеются в виду в первую очередь:
+
+- `styles.ts` / `styles.tsx` рядом с компонентом;
+- `*.module.css`, `*.module.scss` и аналоги, принадлежащие конкретному компоненту;
+- любые файлы, которые **экспортируют только styled-примитивы** для одного компонента.
+
+## Разрешено
+
+- `import * as s from './styles'` — стили **в той же папке**, что и компонент.
+- Импорты **общих** примитивов дизайн-системы, токенов, общих UI из `@/ui/components/...` или пакетов, если это **не** приватный `styles` чужой фичи.
+- Повторное использование визуала через **сам компонент** (композиция), а не через его `styles`.
+
+## Примеры
+
+```tsx
+// ✅ Хорошо — локальный styles
+import * as s from './styles'
+
+// ❌ Плохо — стили родителя/соседа
+import * as s from '../../styles'
+import * as s from '../RequestForAnalysisServices/styles'
+```
+
+## Почему
+
+- Единое имя **`Root`** ускоряет чтение: сразу видно входную точку разметки компонента.
+- Стили и разметка компонента должны меняться вместе, без скрытой связи через чужие файлы.
+- Упрощается рефакторинг и поиск владельца стилей.

package/presets/cursor/next/rules/no-props-spread.mdc

@@ -1,11 +1,14 @@
 ---
 description: Избегать спред-а пропов при передаче в компоненты
 alwaysApply: true
+globs: app/src/**/*.tsx
 ---
 
 # Не использовать спред пропов при передаче в компоненты
 
-При вызове React-компонентов **передавать пропы явно**, а не через spread (`{...props}`).
+При вызове **пользовательских** React-компонентов (имя с заглавной буквы: `IconBox`, `TextField`, ваши `FooBar`) **передавать пропы явно**, а не через spread (`{...props}`, `{...obj}`).
+
+**Агентам и при ревью:** не «упрощать» JSX через объект с последующим spread — это нарушение. Если ветвление по пропам длинное, используйте два явных JSX-блока (`condition ? <A … /> : <B … />`) или отдельные маленькие компоненты, а не `{...mergedProps}`.
 
 ## Почему
 
@@ -13,6 +16,11 @@ alwaysApply: true
 - Упрощает рефакторинг и поиск использований.
 - Снижает риск случайно пробросить лишние или устаревшие пропы.
 
+## Проверка в репозитории
+
+- Для файлов `app/src/ui/**/*.tsx` включено ESLint-правило `react/jsx-props-no-spreading` (`app/eslint.config.mjs`): несоблюдение увидит линтер и CI.
+- Легитимное исключение в конкретном месте — **однострочный** `eslint-disable-next-line react/jsx-props-no-spreading` с кратким комментарием «почему»; для редких обёрток допустим disable на файл (как в `PromocodeInput`).
+
 ## Примеры
 
 ```tsx
@@ -23,6 +31,10 @@ return <Child {...commonProps} />
 // ❌ Плохо
 return <Child {...props} />
 
+// ❌ Плохо (spread из соседнего модуля стилей тоже не оправдание)
+const iconProps = cond ? { name, size: 'm' } : { name, size: 'm', ...styles.IconBoxAccent }
+return <IconBox {...iconProps} />
+
 // ✅ Хорошо
 return (
   <Child
@@ -31,9 +43,20 @@ return (
     c={c}
   />
 )
+
+// ✅ Хорошо — явные пропсы по веткам
+return cond ? (
+  <IconBox name={name} size="m" variant="warning" />
+) : (
+  <IconBox
+    customColors={styles.IconBoxAccent.customColors}
+    name={name}
+    size="m"
+  />
+)
 ```
 
 ## Исключения
 
-- Передача всех пропов в нативный DOM-элемент (`<div {...rest} />`) допустима, если `rest` содержит только валидные HTML-атрибуты.
-- Делегирование пропов в обёртку (wrapper) допустимо, если это явно документировано и обосновано.
+- Передача пропов в **нативный** DOM-элемент (`<div {...rest} />`) допустима, если `rest` содержит только валидные HTML-атрибуты.
+- Делегирование пропов в обёртку (wrapper) допустимо, если это явно документировано и обосновано; при необходимости пометьте файл или строку через ESLint-disable, как выше.

package/presets/cursor/next/rules/react-ui.mdc

@@ -1,6 +1,6 @@
 ---
 description: Паттерны React/Next UI и стилей (preset)
-globs: app/src/ui/**/*.tsx
+globs: app/src/ui/**/*.tsx,app/src/ui/**/*.ts
 alwaysApply: false
 ---
 
@@ -26,10 +26,28 @@ alwaysApply: false
 - Папка с именем компонента:
   - `ComponentName.tsx`
   - файлы стилей по принятой схеме;
-  - опционально: `types.ts`, `hooks.ts`.
+  - опционально: `types.ts`, `ComponentName.hooks.ts` (см. ниже про префикс).
+
+## Вспомогательные модули рядом с компонентом (именование)
+
+**Префикс имени файла = публичное имя компонента** (как у `ComponentName.tsx` в этой папке), в **PascalCase**. Не вводить отдельные «говорящие» имена файлов по смыслу содержимого (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts` и т.п.) — так теряется связь с компонентом и плодятся одноразовые названия.
+
+**Суффикс по роли:**
+
+| Суффикс | Назначение | Примеры содержимого |
+|--------|------------|---------------------|
+| `ComponentName.data.ts` | Статические данные и конфигурация для UI | мапы `id → иконка/лейбл`, константы списков, таблицы соответствий для отображения |
+| `ComponentName.utils.ts` | Чистые функции без React | форматирование, предобработка пропсов/данных для рендера, `build…`/`map…`‑хелперы |
+| `ComponentName.hooks.ts` | Хуки, используемые только этим блоком | локальные `use…` (если не вынесены в `src/ui/hooks/**`) |
+
+- Несколько констант/мапов или несколько функций — **по-прежнему один** `.data.ts` и один `.utils.ts`, не дробить по «темам» отдельными файлами без веской причины (размер, разные зоны ответственности на уровне подкомпонентов).
+- Если логика принадлежит **подкомпоненту** в подпапке (`components/Child/Child.tsx`), те же правила применяются к **`Child.data.ts`**, **`Child.utils.ts`** относительно этого подкомпонента.
+- Тесты для утилит и данных — рядом в `__tests__/` или с суффиксом `.test.ts`, согласно `tests-unit.mdc`, с тем же префиксом (`RequestForAnalysisRecommendations.utils.test.ts` и т.д.).
 
 # Стили и дизайн‑токены
 
+- **Корневой** styled-элемент компонента в соседнем `styles` — **`Root`** (`<s.Root>`). Подробнее: `no-cross-component-styles-import.mdc`.
+- Порядок объявлений в CSS / `styled` — как требует Stylelint: см. `css-property-order-stylelint.mdc`.
 - Для визуала использовать **тот стек стилей и токенов, который уже в проекте** (переменные, тема, общие классы, дизайн‑пакет).
 - Избегать:
   - inline‑стилей, кроме простых случаев;
@@ -39,6 +57,7 @@ alwaysApply: false
 
 # Пропсы и типизация
 
+- **Не передавать пропы в компоненты через spread** (`<Foo {...x} />`). Только явные атрибуты; подробности и исключения — `no-props-spread.mdc` (в `app/src/ui` это дополнительно ловит ESLint).
 - Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
 - Не использовать `any`; при необходимости:
   - обобщения (`<T>`), `unknown`, тип‑предикаты и user‑defined type guards.

package/presets/cursor/next/rules/tests-unit.mdc

@@ -15,6 +15,7 @@ alwaysApply: false
 - **Именование unit‑тестов** (строки в `describe` / `it` / `test`):
   - формулировки **только на русском языке** — понятные бизнес‑фразы (что проверяется и какой ожидается результат);
   - **каждое предложение** в названии **начинается с заглавной буквы** (в том числе после `.`, `!`, `?` и при нескольких предложениях в одной строке); первая буква всей строки — тоже заглавная.
+  - **Проверка в CI:** ESLint (`jest/valid-title` в `app/eslint.config.mjs`) требует, чтобы строка начиналась с русской заглавной (А–Я, Ё), и запрещает пробел после точки, за которым сразу идёт строчная буква (типичный случай нарушения «с заглавной после точки»).
 
 ```typescript
 // ✅ Хорошо