docs: establish workspace engineering conventions

2026-09-15 05:42:02 +03:00
parent 2567a75556
commit 93dd5539ad
11 changed files with 504 additions and 25 deletions
@@ -0,0 +1,48 @@
+# Conventions → deterministic guardrails
+
+Читай при выборе проверки или изменении tooling. Команды выполняются из repo
+владельца после `nvm use --silent`. Config/manifest задаёт фактический scope;
+таблица не заменяет semantic review и не утверждает, что все checks уже запущены.
+
+| Convention | Существующий check | Достаточность / следующий шаг |
+| --- | --- | --- |
+| Git multi-repo tracking | root `python3 test-workspace-tracking.py`, `.gitignore` | Проверяет exact allowlist и сохранность fictional data/nested Git; обновлять вместе с allowlist |
+| Conventional Commits | local commitlint + commits workflow | Syntax покрыт; атомарность и scope — review |
+| Dependencies | exact manifest/lockfile, `npm ci`, security workflows (audit/Gitleaks) | Reuse, peer compatibility, ценность dependency — review; новый analyzer не нужен |
+| Frontend types/style/literals | TypeScript strict, `erasableSyntaxOnly`; Biome `npm run lint` | Props profile, i18n и symbolic strings требуют review; literals exclusions — в Biome |
+| Frontend FSD | dependency-cruiser `npm run deps` | Upward imports, cycles, public entry points покрыты; same-layer запрет неполный, semantic ownership не проверяется |
+| Unused frontend code/deps | `npm run knip`, TS unused locals/params | Existing tool достаточно; не добавлять второй unused analyzer |
+| API generation | frontend `openapi:check`; backend `test:openapi-contract` | Первый сравнивает generated types со snapshot; второй — Nest schema со snapshot. Ни один не доказывает runtime validation errors |
+| Query/auth/error/finance behavior | Vitest + RTL/MSW; backend Jest/SQLite/HTTP | Test Intent выбирает риск и уровень, без автоматического теста для каждого файла |
+| Storybook | `typecheck`, `deps:storybook`, `build:catalog` | Imports/types/build покрыты; `play`, visual/keyboard/browser behavior проверять отдельно |
+| Backend types/style | ESLint/Prettier, app/test TypeScript | Zero-warning gate; `no-explicit-any` отключён, часть unsafe rules включена. Не обещать полного запрета `any` |
+| Backend modules/domain | TypeScript и semantic review | Отдельного architecture analyzer нет. При повторных нарушениях сначала рассмотреть existing ESLint `no-restricted-imports`, без нового custom analyzer |
+| DB ownership/atomicity | Prisma schema/constraints, `test:sqlite`, `test:e2e`, `test:durability` | Mock Prisma недостаточно. Relevant suites на disposable DB, без reset пользовательской базы |
+| Logging/security | Logging/auth/access tests, configured HTTP tests, Gitleaks | Allowlist/redaction имеют границы. Встроенный ESLint `no-console` можно включить отдельно; semantic security review обязателен |
+| Markdown/routing | docs markdownlint-cli2 + relative-links, `git diff --check` | Existing docs gate охватывает docs, а не соседние `.ai`; для них запустить тот же установленный CLI с явным списком путей и docs config |
+
+## Ratchet без новой инфраструктуры
+
+- Existing error gates остаются обязательными; не ослабляй их ради legacy.
+- До расширения FSD rule получи candidate violations существующим depcruise.
+  Его `--ignore-known` допускает native baseline; сначала проверь формат через
+  `--help`. Не игнорируй целые directories. Обновление baseline принимается
+  только с evidence закрытия/явным обоснованием нового исключения.
+- Semantic findings учитываются stable IDs в
+  [inventory](../migrations/conventions-v1/audit.md) и закрываются vertical slices
+  по [plan](../migrations/conventions-v1/plan.md). Это reviewed inventory,
+  не автоматический полный счётчик нарушений.
+- Новый analyzer/custom baseline CI не создаётся. Если существующей проверки
+  недостаточно, сначала сформулируй повторяющийся regression и стоимость
+  поддержки предлагаемого rule.
+
+## Выбор финального gate
+
+Markdown/routing-only: проверить все новые/изменённые Markdown, ссылки/якоря,
+достижимость тем, смысл и `git diff --check`. Root allowlist change дополнительно
+требует tracking-тест. Не запускать application builds/coverage только ради текста.
+
+Code/dependency changes: full `npm run verify` affected repo после lockfile install;
+targeted tests ускоряют итерацию, но не подменяют required gate. Wire changes
+дополнительно требуют backend contract check, HTTP/DB changes — relevant isolated
+suites по local Testing. Форматирующие `lint:fix`/`format` — mutations, не proof.