Обновить доки по закрытию остатков код-стайла

Аудит §2 переписан под решения (var-гейт, LF, дедуп закрыт — дублей нет); backlog: TD-COMMENTS-IFACE п.1–3 закрыты, TD-STYLE-ANALYZERS закрыт; STATUS.md — новый блок захода, устаревший блок «Осталось (в backlog)» в шапке удалён; план и ledger захода.
2026-09-11 19:01:42 +03:00
parent 713d554dc2
commit a7e38846d7
245 changed files with 32225 additions and 32151 deletions
@@ -0,0 +1,23 @@
+# Ledger: codestyle-residue (2026-09-11, вечер)
+
+План: `docs/superpowers/plans/2026-09-11-codestyle-остатки.md`
+
+## Итог
+
+- Замер: дубли `<summary>` (текст и имя члена) — 0; var-литералы/касты в src — 0; латинских комментариев — 18
+  (из них англоязычных 3); членов интерфейсов без дока — 4; TODO — 0; CRLF-файлов — 1029 из 1445
+  (все 42 .sh — CRLF).
+- `.editorconfig`: `csharp_style_var_for_built_in_types = false:warning`; `end_of_line = lf`.
+- `dotnet format style --diagnostics IDE0008 --severity warn` по 5 sln — 51 файл (только встроенные типы).
+- `.gitattributes` добавлен (`* text=auto eol=lf` + бинарные исключения); 1029 файлов конвертированы в LF;
+  `git add --renormalize .`.
+- `fix_private_docs.py --apply` — 12 блоков; `<summary>` добавлены: `IContainerRules.Keywords/Stack`,
+  `ITenantContext.TenantId/HasTenant`; переведены 3 комментария (SettingsKeys, OperatorAuthService,
+  ConversionRecomputerTests); `.pyc` из индекса убраны; STATUS.md — устаревший блок удалён.
+- Явные реализации интерфейсов — владельцу на точечное ревью (не автоматизировано сознательно).
+
+## Проверка
+
+- `dotnet build` 5 sln (core, telegram, ai, ml, storage): 0 warnings / 0 errors.
+- `sh scripts/test.sh`: все 5 тест-проектов зелёные (счётчики — STATUS.md), `lint:i18n` — зелёный.
+- Фронт содержательно не менялся.
@@ -16,8 +16,8 @@
 | BL-RECLASS-SSE | **Сделано (2026-09-11):** пакетная переклассификация отдаёт промежуточный прогресс через SSE `cards_reclassified` (`{progress:true,done,total,moved,kept,trashed,skipped}`) и финальное событие (`{progress:false,reclassified,moved}`); `CardReclassifier.ReclassifyInboxAsync` принимает `IProgress<ReclassifyProgressDto>`; в UI — индикатор `done/total` в шапке «Неразобранного» | этап 12, D | P3 | DONE |
 | TD-CARD-MERGE | Полное слияние внутренних DTO карточки в единый `CardDto`. **Решение (2026-09-11): DEFERRED.** Наружный контракт единый; внутренние DTO (read/write/DB/patch) намеренно разделены по слоям, слияние — риск без пользы | этап 9/11 | P3 | DEFERRED |
 | TD-PROTO-COMMENTS | **Сделано (2026-09-11):** из комментариев убраны ссылки на процесс/прототип (`Task/Ruling/этап/python L…/main.py/прототип/LEADRADAR_*`), удалены блоки `<remarks>`, `<summary>` сжаты до короткой фразы; `//`-комментарии со ссылками удалены, в `.proto` — тоже. Строк комментариев 27 210 → ~19 100 | запрос владельца 2026-09-11 | P2 | DONE |
-| TD-COMMENTS-IFACE | Привести код к правилам код-стайла (`docs/spec/Код-стайл-Дейл.md`). **Сделано (2026-09-11):** (1) `<summary>` только блочно — исправлено 5286 шт. в 833 файлах; (2) комментарии только на public/protected — понижено 2028 XML-доков с private/internal (359 файлов); (3) codemod `scripts/dedup_summary_inheritdoc.py` (dry-run) — в продакшн-коде простых дублей `<summary>` уже нет (интерфейсные реализации используют `<inheritdoc/>`). **Осталось:** блоки с `<param>`+дублирующим summary (нужен Roslyn) и (4) явная реализация интерфейсов (61 интерфейс, точечный ревью). Скрипты: `scripts/fix_summary_blocks.py`, `scripts/fix_private_docs.py`, `scripts/dedup_summary_inheritdoc.py`. Детали — `docs/spec/Код-стайл-аудит-2026-09-11.md` | запрос владельца 2026-09-11 | P2 | TECHDEBT (1,2 — DONE; 3 — проверено codemod'ом; 4 — BACKLOG) |
-| TD-STYLE-ANALYZERS | Остаток мягких правил код-стайла: `var` для встроенных/неочевидных типов (1529, сейчас `silent`), дедупликация `<summary>`→`<inheritdoc/>` (Roslyn), решение по переводам строк (`.editorconfig` = CRLF, фактически 231 CRLF / 697 LF). Уже закрыто в `.editorconfig` (+build-проверка): запрет `this.` и именование приватных полей (`_camelCase`; `const`/`static readonly` — Pascal). Детали — `docs/spec/Код-стайл-аудит-2026-09-11.md` | аудит 2026-09-11 | P3 | BACKLOG |
+| TD-COMMENTS-IFACE | Привести код к правилам код-стайла (`docs/spec/Код-стайл-Дейл.md`). **Сделано (2026-09-11):** (1) `<summary>` только блочно — исправлено 5286 шт. в 833 файлах; (2) комментарии только на public/protected — понижено 2028 XML-доков с private/internal (359 файлов), повторный прогон — ещё 12; (3) дедупликация `<summary>`→`<inheritdoc/>`: **закрыто — дублей нет** (проверено сканами по тексту и по имени члена: 39 интерфейсов, 229 членов, случаев `<param>`+дубль не существует); (4) явная реализация интерфейсов — **остаётся точечным ревью владельца** (54 интерфейса с doc, 43 с реализациями, массовая правка не автоматизируется). Попутно: добавлены 4 недостающих `<summary>` членам интерфейсов, переведены 3 англоязычных комментария. Скрипты: `scripts/fix_summary_blocks.py`, `scripts/fix_private_docs.py`, `scripts/dedup_summary_inheritdoc.py`. Детали — `docs/spec/Код-стайл-аудит-2026-09-11.md` | запрос владельца 2026-09-11 | P2 | TECHDEBT (1–3 — DONE; 4 — ревью владельца) |
+| TD-STYLE-ANALYZERS | Остаток мягких правил код-стайла. **Закрыто (2026-09-11):** (1) `var` — включён ломающий сборку гейт только для встроенных типов (`csharp_style_var_for_built_in_types = false:warning`), остаток выправлен `dotnet format style --diagnostics IDE0008` по 5 sln; режимы «очевидный/прочий тип» — silent осознанно (~1600 субъективных замен); (2) дедупликация `<summary>` — дублей нет (см. TD-COMMENTS-IFACE); (3) переводы строк — **решено: LF** (`.gitattributes` `* text=auto eol=lf`, `.editorconfig` → lf, 1029 файлов нормализовано, `git add --renormalize`; попутно починены 42 CRLF-.sh — до этого первый прогон удалённого CI падал бы). `this.` и именование приватных полей уже закрыты в `.editorconfig` | аудит 2026-09-11 | P3 | DONE |

 ## 2. Инфраструктура и эксплуатация

@@ -28,23 +28,30 @@
 - Тесты: core **1275/1275**, telegram **125/125**, ai **52/52**, ml **38/38** — все пройдены.
 - Повторный прогон renamer: `this.` — 0, полей к переименованию — 0 (идемпотентно).

-## 2. Осталось — требует решения владельца
+## 2. Остатки — решения (закрыто 2026-09-11, вечер)

-1. **`var` — 1529 употреблений.** Правило §4: не использовать для встроенных типов и при неочевидном типе.
-   В `.editorconfig` `csharp_style_var_* = false:silent`. Замена требует семантики (вывод типа).
-   **Рекомендация:** включить анализатор (`:warning`) + `dotnet format` с проверкой.
+1. **`var` — закрыто.** В `.editorconfig` включён ломающий сборку гейт `csharp_style_var_for_built_in_types = false:warning`
+   (запрет только для встроенных типов — как в §4); режимы «очевидный тип» и «прочие» оставлены `silent`
+   осознанно: правка субъективна и потребовала бы ~1600 механических замен. Остаток встроенных типов
+   выправлен `dotnet format style --diagnostics IDE0008` по всем 5 решениям (51 файл); сборка 5 sln — 0/0.
+2. **Явная реализация интерфейсов (§11) — остаётся точечным ревью владельца.** Замер: 54 интерфейса с XML-doc,
+   из них 43 имеют реализации в src (в основном store-порты с одной реализацией). Массовая правка не
+   автоматизируется сознательно (см. рекомендацию выше).
+3. **Дедупликация `<summary>` через `<inheritdoc/>` — закрыто: дублей нет.** Проверено двумя независимыми
+   сканами (сопоставление по тексту и по имени члена интерфейса: 39 интерфейсов, 229 задокументированных
+   членов) — реализаций, дублирующих summary интерфейсного члена, в продакшн-коде нет; случаев
+   «`<param>` + дублирующий summary» не существует.
+4. **Переводы строк — решено: LF.** Обоснование: инструменты проекта (Python/Node-скрипты, codemod'ы) пишут LF;
+   shell-скрипты с CRLF не работают на Linux CI (`sh scripts/ci.sh` в GitHub Actions); фактическое большинство
+   файлов уже было LF. Применено: `.gitattributes` (`* text=auto eol=lf` + бинарные исключения),
+   `.editorconfig` → `end_of_line = lf`, конвертировано 1029 трекаемых файлов, `git add --renormalize`.
+   Побочный эффект: починены 42 CRLF-.sh (9 в `scripts/` — до этого первый удалённый прогон CI падал бы).

-2. **Явная реализация интерфейсов (§11).** Субъективное «где возможно» — массовая правка может сломать
-   DI/прямые вызовы и тесты. **Рекомендация:** точечный ревью по 61 интерфейсу, без автоматизации.
+### Попутно исправлено (2026-09-11, вечер)

-3. **Дедупликация `<summary>` в реализациях через `/// <inheritdoc/>` (§11).** Надёжно детектируется только
-   по семантической модели (сопоставление интерфейс↔класс). В коде уже 674 `<inheritdoc/>`.
-   **Рекомендация:** Roslyn-анализатор, если нужно добить остаток.
-
-4. **Переводы строк.** `.editorconfig` требует `end_of_line = crlf`, фактически: **231 файл CRLF / 697 LF**
-   (смешанно). Правка объёмная. **Рекомендация:** решить — нормализовать под CRLF или зафиксировать LF.
-
-## 3. Примечание
-
-Пункты 2.1, 2.3 можно закрыть анализаторами Roslyn в `Directory.Build.props` — это даст автоматическую
-проверку на новом коде. Пункт 2.4 — разовое решение по политике переводов строк.
+- Повторный прогон `scripts/fix_private_docs.py --apply`: понижено 12 XML-доков на private/internal (extension-файлы).
+- Добавлены недостающие `<summary>`: `IContainerRules.Keywords`/`Stack`, `ITenantContext.TenantId`/`HasTenant`.
+- Переведены на русский англоязычные `//`-комментарии (3 шт. из 18 найденных; остальные — имена
+  сущностей/заголовки секций тестов, не англоязычный текст).
+- Из индекса убраны случайно закоммиченные `archive/**/__pycache__/*.pyc` (2 шт., уже в `.gitignore`).
+- STATUS.md: удалён устаревший блок «Осталось (в backlog)» в шапке (пункты закрытыgeneric-контрактом источника).
@@ -17,9 +17,18 @@
 > единый CI (`scripts/ci.sh`). Ядро: build 5 sln 0/0, `Deal.Tests.Unit` **1326/1326 PASS**,
 > telegram **130/130**, ai **52/52**, ml **38/38**, storage **9/9**, фронт `build` + `lint:i18n` зелёные.
 > Детали — `docs/superpowers/specs/2026-09-11-source-contract-design.md`.
-> Осталось (в backlog): `GET /api/cards/{id}/source` + `ISourceContentProvider`, выгрузка вложений
-> telegram-адаптером в Storage, `TelegramSourceContentProvider`, перенос оставшейся Telegram-специфики
-> (`TelegramStore`, `Dialogs`/`TgMessages`, Discovery) в telegram-сервис.
+>
+> **2026-09-11 (вечер) — закрыты остатки код-стайла (TD-COMMENTS-IFACE, TD-STYLE-ANALYZERS).** Дедупликация
+> `<summary>`: дублей нет (сканы по тексту и по имени члена — 39 интерфейсов/229 членов). `var`: гейт
+> `csharp_style_var_for_built_in_types = false:warning` (ломает сборку), остаток выправлен `dotnet format`
+> по 5 sln (51 файл), «очевидный/прочий тип» — silent осознанно. Переводы строк: решено LF — `.gitattributes`
+> (`* text=auto eol=lf`), `.editorconfig` → lf, нормализовано 1029 файлов; попутно починены 42 CRLF-.sh
+> (первый прогон удалённого CI падал бы). Понижено 12 новых private XML-доков; добавлены 4 `<summary>`
+> членам интерфейсов; переведены 3 англоязычных комментария; из индекса убраны 2 `__pycache__/*.pyc`;
+> STATUS.md — удалён устаревший блок «Осталось (в backlog)» в шапке. Явные реализации интерфейсов (§11) —
+> остались точечным ревью владельца (43 интерфейса с реализациями, массовая правка не автоматизируется).
+> Сборка 5 sln 0/0; тесты: core **1340/1340**, telegram **130/130**, ai **52/52**, ml **38/38**, storage **9/9** — зелёные.
+> Детали — `docs/spec/Код-стайл-аудит-2026-09-11.md`, §2.

 **Все этапы 0–12 выполнены (100%)** — см. roadmap
 > `docs/superpowers/plans/2026-09-05-deal-roadmap.md`, план этапа 10
@@ -0,0 +1,35 @@
+# План: закрытие остатков код-стайла (2026-09-11, вечер)
+
+> Источник: `backlog.md` — `TD-COMMENTS-IFACE` (п.3, п.4), `TD-STYLE-ANALYZERS`, найденное при проверке
+> проекта. Правила — `docs/spec/Код-стайл-Дейл.md`, отчёт — `docs/spec/Код-стайл-аудит-2026-09-11.md` §2.
+> Ограничения захода: без поднятия Docker-стека и без внешних кредов.
+
+## Задачи
+
+1. **Замер остатков** (dry-run, без правок): сканами по тексту и по имени члена проверить дубли
+   `<summary>` реализации ↔ интерфейса; разбивку `var`; латинские комментарии; членов интерфейсов без
+   дока; TODO; переводы строк по расширениям.
+2. **`var` для встроенных типов**: `.editorconfig` → `csharp_style_var_for_built_in_types = false:warning`
+   (гейт ломает сборку), остаток выправить `dotnet format style --diagnostics IDE0008` по 5 решениям.
+   «Очевидный тип» и «прочие» — оставить `silent` (субъективно, ~1600 замен).
+3. **Дедупликация `<summary>`→`<inheritdoc/>`**: по результатам замера — либо codemod, либо закрытие «дублей нет».
+4. **Переводы строк**: решение политики + нормализация (`.gitattributes`, `.editorconfig`, конверсия файлов,
+   `git add --renormalize`); проверить, что `.sh` — LF (Linux CI).
+5. **Попутные доки/комментарии**: недостающие `<summary>` членам интерфейсов; англоязычные `//`-комментарии;
+   повторный прогон `fix_private_docs.py`; устаревший блок в `STATUS.md`; трекаемые `.pyc` из индекса.
+6. **Приёмка**: build 5 sln 0/0, все тесты зелёные; обновить `backlog.md`/`STATUS.md`.
+
+## Решения
+
+- Явные реализации интерфейсов (§11) — **не автоматизировать**: остаётся точечным ревью владельца
+  (замер: 54 интерфейса с XML-doc, 43 с реализациями; массовая правка ломает публичную поверхность классов).
+- Переводы строк — **LF** (инструменты проекта пишут LF; CRLF-.sh ломают `sh scripts/ci.sh` на Linux CI;
+  большинство файлов уже LF). Откат — `git revert` нормализации.
+- Гейт `var` — только на встроенные типы: правило §4 запрет говорит про встроенные/неочевидные,
+  «неочевидность» не проверяется машиной.
+
+## Приёмка
+
+- build 5 sln: 0 warnings / 0 errors (гейт IDE0008 проходит).
+- Тесты: core / telegram / ai / ml / storage — зелёные, счётчики в `STATUS.md`.
+- Фронт не менялся содержательно (только концы строк) — `build`/`lint:i18n` не прогонялись.