# frontend-quality-guardrails Specification

## Purpose

Гарантирует, что frontend сохраняет проверяемые structural, startup-size и
test-coverage свойства при последующих изменениях React client.

## Requirements

### Requirement: Frontend сохраняет structural boundaries slice public API

Frontend MUST не содержать cycles в import graph `src` и MUST обращаться к
другому FSD slice только через его public `index.ts`, независимо от слоя,
включая `app` и test source. Generated source MAY быть исключён только при
документированном вынужденном исключении в dependency configuration.

#### Scenario: Добавлен import cycle

- **WHEN** исходный или test module в `src` создаёт прямой либо косвенный
  import cycle
- **THEN** documented frontend dependency gate завершается с ошибкой до
  передачи изменения

#### Scenario: Slice обходит public API другого slice

- **WHEN** module одного slice импортирует внутренний file другого slice,
  минуя его public `index.ts`
- **THEN** documented frontend dependency gate завершается с ошибкой и
  сообщает boundary violation

#### Scenario: Application использует public route API

- **WHEN** application container использует route-level component
- **THEN** import проходит через public API routes slice и dependency gate
  завершается успешно при отсутствии остальных violations

### Requirement: Frontend ограничивает initial JavaScript payload

Production frontend MUST lazy-load route page boundaries. Сумма minified
JavaScript entry bundle и всех его eagerly loaded JavaScript dependencies MUST
NOT превышать 500 kB. Lazy route chunks MUST иметь зафиксированный baseline
для последующих регрессий; bundle policy MUST NOT требовать ручного vendor
chunking.

#### Scenario: Production build укладывается в initial budget

- **WHEN** frontend production build создаёт entry bundle и eagerly loaded
  JavaScript dependencies суммарным размером не более 500 kB minified
- **THEN** documented bundle gate завершается успешно

#### Scenario: Production build превышает initial budget

- **WHEN** frontend production build создаёт entry bundle и eagerly loaded
  JavaScript dependencies суммарным размером более 500 kB minified
- **THEN** documented bundle gate завершается с ошибкой и сообщает measured
  initial payload

#### Scenario: Изменён lazy route chunk

- **WHEN** lazy-loaded route chunk превышает свой зафиксированный baseline
- **THEN** documented bundle gate завершается с ошибкой до передачи изменения

### Requirement: Frontend coverage является anti-regression gate

Documented frontend coverage command MUST завершаться с ошибкой, если global
coverage committed source ниже 82% statements, 75% branches, 75% functions
или 83% lines. Эти пороги SHALL служить только сигналом регрессии и MUST NOT
заменять scenario-based tests.

#### Scenario: Coverage сохраняет каждый baseline floor

- **WHEN** frontend test suite достигает либо превышает все четыре coverage
  floors
- **THEN** documented coverage command завершается успешно

#### Scenario: Coverage опускается ниже floor

- **WHEN** frontend test suite опускается ниже хотя бы одного coverage floor
- **THEN** documented coverage command завершается с ошибкой по этой метрике

### Requirement: Frontend проверяет автоматически проверяемый стиль React components

Authored frontend source MUST сохранять автоматически проверяемую часть
документированного стиля React components внутри документированного frontend
verification gate. Gate MUST отклонять default exports в authored frontend
source, named React components, объявленные вне документированной const-valued
component form, и module exports, размещённые перед declarations тела module.
Style preferences, для которых нет детерминированной локальной проверки, MUST
оставаться review conventions и MUST NOT описываться как gate-blocking hard
guardrails.

#### Scenario: Authored source соблюдает проверяемый component style

- **WHEN** authored frontend source объявляет named React components через
  документированную const-valued component form, не использует default exports
  и держит exports после declarations тела module
- **THEN** документированный frontend verification gate не падает из-за React
  component style

#### Scenario: Named component использует запрещённую форму объявления

- **WHEN** authored frontend source объявляет named React component вне
  документированной const-valued component form
- **THEN** документированный frontend verification gate падает и сообщает
  нарушение React component style

#### Scenario: Authored source использует default export

- **WHEN** authored frontend source открывает module API через default export
- **THEN** документированный frontend verification gate падает и сообщает
  нарушение module export style

#### Scenario: Authored source экспортирует до declarations тела module

- **WHEN** authored frontend source размещает module export перед
  non-exported declarations тела module
- **THEN** документированный frontend verification gate падает и сообщает
  нарушение module export ordering

#### Scenario: Convention не имеет детерминированной проверки

- **WHEN** documented frontend style convention нельзя проверить existing
  deterministic local tooling
- **THEN** frontend documentation трактует её как mandatory review convention,
  а не как gate-blocking hard guardrail