docs(specs): archive frontend quality guardrails

2026-08-24 13:07:25 +03:00
parent 8897bd9585
commit 20295190dd
7 changed files with 400 additions and 0 deletions
@@ -0,0 +1,79 @@
+# 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 завершается с ошибкой по этой метрике