specs/openspec/specs/frontend-quality-guardrails/spec.md

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