Igor20264
187 lines
16 KiB
Markdown
187 lines
16 KiB
Markdown
# Незакрытые задачи после аудита
|
||
|
||
Состояние на 10 сентября 2026. Всё перечисленное — то, что осталось после прохода по плану оптимизации. Что уже сделано, см. [audit-report.md](audit-report.md).
|
||
|
||
Тесты сейчас: **320 passed, 1 skipped, 174 subtests**, полный прогон 11.85 с. Ничего не закоммичено — всё лежит в staging и рабочем дереве.
|
||
|
||
---
|
||
|
||
## P0 — сломает сборку, если не сделать
|
||
|
||
### `mdexport/` не добавлен в git
|
||
|
||
Пакет `mdexport/` (общий обходчик AST для `md2latex` и `md2fodt`) создан, но остался **untracked**, при этом на него уже завязаны:
|
||
|
||
- `pyproject.toml` — перечислен в `[tool.hatch.build.targets.wheel].packages`
|
||
- `md2latex/emitter.py`, `md2latex/escape.py`
|
||
- `md2fodt/emitter.py`, `md2fodt/escape.py`
|
||
|
||
На свежем клоне оба конвертера упадут с `ModuleNotFoundError`, сборка колеса тоже. Локально работает только потому, что файлы лежат на диске.
|
||
|
||
```powershell
|
||
git add mdexport/blocks.py mdexport/inline.py mdexport/labels.py mdexport/__init__.py
|
||
git status --short mdexport
|
||
```
|
||
|
||
Скомпилированные `.pyc` внутри уже покрыты правилом `__pycache__/`, добавлять их не нужно.
|
||
|
||
---
|
||
|
||
## P1 — найденный баг, теряет данные
|
||
|
||
### `word2md` выбрасывает пункты списка при смене его типа
|
||
|
||
Найден при разборе `_handle_paragraph`. Баг **существовал и до рефакторинга**, его сохранили намеренно, чтобы правка осталась поведенчески нейтральной.
|
||
|
||
`word2md/walker.py`, строки 406-429. Оба обработчика списков заканчиваются на `return []`, выбрасывая накопленный `out` — притом что `_flush_code(out)` и `_flush_list(out)` внутри уже успели в него дописать:
|
||
|
||
```python
|
||
def _as_numbered_list_item(self, para: _Para, out: list[Block]) -> list[Block] | None:
|
||
if not paragraph_has_numpr(para.paragraph):
|
||
return None
|
||
self._flush_code(out) # может дописать в out
|
||
...
|
||
self._append_list_item(ordered, body, out) # внутри вызывает _flush_list(out)
|
||
return [] # <- out выброшен
|
||
```
|
||
|
||
`_append_list_item` (строки 431-437) при смене типа списка вызывает `_flush_list(out)`, который сбрасывает накопленные пункты в `out`. После чего `return []` их теряет. Соседний `_as_plain_paragraph` (строка 439) в такой же ситуации корректно делает `return out`.
|
||
|
||
Воспроизведение: два упорядоченных пункта с `numPr`, за ними пункт-буллет. Оба упорядоченных пропадают из результата. Тот же механизм теряет и забуференный код, если он был.
|
||
|
||
Порядок работ: сначала красный тест на исчезающие пункты, потом замена `return []` на `return out` в обоих обработчиках, потом проверка, что побайтовая сверка вывода на остальных документах не поехала (она поедет только там, где баг срабатывал).
|
||
|
||
---
|
||
|
||
## P1 — решено, но не выполнено
|
||
|
||
### Калибровка Courier New 10 пт
|
||
|
||
Ты выбрал вариант «10 пт канон по табл. 4.1, добавить калибровку и перевести тест-фикстуру». **Не сделано** — я не успел запустить задачу до конца сессии.
|
||
|
||
Что именно нужно, в `md2gost/renderable/paragraph_sizer.py`, метод `Font.get_line_height` (строки 78-83):
|
||
|
||
```python
|
||
# TODO: make it work for all fonts
|
||
if "Times" in str(self._face.family_name) and self._freetypefont.size == 14:
|
||
return Pt(16.05)
|
||
if "Courier" in str(self._face.family_name) and self._freetypefont.size == 12:
|
||
return Pt(13.61)
|
||
```
|
||
|
||
Сейчас калиброванная ветка есть только для Courier 12 пт. Замеры, снятые в ходе аудита:
|
||
|
||
| Размер | Возвращает сейчас | Фактическая высота |
|
||
|---|---|---|
|
||
| Courier 10 пт | 11.000 | ≈ 11.34 |
|
||
| Courier 11 пт | 12.000 | — |
|
||
| Courier 12 пт | 13.610 (калибровка) | 13.61 |
|
||
| Courier 14 пт | 16.000 | — |
|
||
|
||
Целые числа выдаёт округление FreeType; калибровочные ветки существуют ровно затем, чтобы подменить округление реальным значением Word. Пропорция от 13.61 при переходе 12 → 10 пт даёт примерно 11.34.
|
||
|
||
Итог: пока ветки для 10 пт нет, **каждая строка листинга меряется примерно на 3% короче**, и на длинных листингах разъезжаются разрывы страниц.
|
||
|
||
Порядок работ:
|
||
|
||
1. Добавить ветку `Courier` + размер 10 → `Pt(11.34)`. Лучше сначала подтвердить число замером в Word через COM, а не принимать пропорцию на веру.
|
||
2. Перевести `tests/__init__.py` (строка 27) с `Pt(12)` на `Pt(10)`, чтобы фикстура совпадала с `style_config.py:305` и табл. 4.1.
|
||
3. Прогнать `tests/test_paragraph_sizer.py` — серия `test_count_lines_courier1..10` завязана на текущую высоту, ожидаемые значения поедут.
|
||
|
||
Не делай пункт 2 без пункта 1 — иначе калиброванная ветка перестанет срабатывать, и замер станет хуже, чем сейчас.
|
||
|
||
### `Other_Code/` — 59 файлов, 1158 КБ
|
||
|
||
Это была Фаза 4.2 плана, и я её просто не назначил ни одному исполнителю при раскладке работ. Каталог до сих пор полностью в git.
|
||
|
||
Ни одного импорта из `md2gost`, `word2md`, `md2latex`, `md2fodt`, `tests/`; не упоминается в `.spec`, `.bat`, `.github/workflows/`, `pyproject.toml`. Единственные ссылки — раздел 12 в `PROJECT.md` и внутренние перекрёстные ссылки самого каталога.
|
||
|
||
Команды и три варианта действий расписаны в [git-cleanup.md](git-cleanup.md), раздел 1.
|
||
|
||
### Личные документы в корне
|
||
|
||
`ТарасовИА_КР_v3.docx` (2326 КБ) и `Практическая_работа_6.docx` (42 КБ) — ФИО прямо в имени файла. Ты сказал, что уберёшь руками; команды и предупреждение про ловушку с `md2gost/Template.docx` в [git-cleanup.md](git-cleanup.md), раздел 2.
|
||
|
||
---
|
||
|
||
## P2 — открытые вопросы по методичке
|
||
|
||
### «С новой страницы» для надписи листинга
|
||
|
||
Табл. 4.1 (`docs/reference/method-mirea-2022.txt`, строки 714-715) в блоке «Положение на странице» перечисляет и «Не отрывать от следующего», и «С новой страницы».
|
||
|
||
В `md2gost/style_config.py` у стиля `Caption Listing` (строки 278-291) есть `keep_with_next=True`, но нет `page_break_before=True`. Вопрос не праздный: в репозитории есть целая система режимов `--listing-continuation`, так что отсутствие разрыва может быть осознанным выбором. Плюс `Caption.__init__` теперь явно ставит `page_break_before = False`, чтобы не плодить пустые страницы при сочетании с `keep_with_next` — то есть менять придётся согласованно в двух местах.
|
||
|
||
Решение нужно принять до того, как кто-то «починит» это по табл. 4.1 в лоб.
|
||
|
||
### Правило `heading.empty` ложно срабатывает внутри листингов
|
||
|
||
Новое правило в `md2gost/checker/__init__.py` не вырезает fenced-блоки, поэтому одинокая строка `#` внутри блока кода будет засчитана как пустой заголовок. Поведение консистентно с уже существующим `HEADING_RE` в том же файле, то есть это общая для checker'а проблема, а не привнесённая. Чинить имеет смысл сразу для всех проверок заголовков.
|
||
|
||
---
|
||
|
||
## P3 — не начатое из Фазы 6
|
||
|
||
Всё это помечено в плане как опциональное. Ничего из перечисленного не сделано, кроме общего обходчика AST и разбора `word2md/_handle_paragraph`.
|
||
|
||
### Разбиение `idef0.py`
|
||
|
||
1935 строк (сейчас 74 КБ). God-функции: `_parse_arrow_line` (~177 строк), `_draw_kit_form` (~121), `_route_icom` (~110), `_draw_arrow` (~83), `_layout_arrow_label` (~80).
|
||
|
||
Предлагаемая раскладка в пакет `idef0/`: `model.py`, `parse.py`, `layout.py`, `routing.py`, `scene.py`, `draw.py`, `render.py`, с реэкспортом публичного API из `__init__.py` ради тестов. Выигрыша в скорости не даёт, только читаемость.
|
||
|
||
Отдельно там же: `_Scene.to_png()` и `_Scene.to_svg()` дважды обходят один и тот же список операций. Можно сгенерировать SVG и растеризовать его в PNG.
|
||
|
||
### Разбиение `gui.py`
|
||
|
||
1695 строк (82 КБ) в одном классе `Md2GostApp`: главное окно, шесть диалогов, редактор UML-схем на ~270 строк, композер промптов, логика перезаписи файлов, потоки конвертации, загрузка ассетов.
|
||
|
||
Раскладка: `gui/windows/`, `gui/widgets.py`, `gui/convert_runner.py`, а `Md2GostApp` оставить тонкой оболочкой.
|
||
|
||
### Ленивые импорты
|
||
|
||
`md2gost/pipeline.py` (строки 15-19) и `md2gost/gui.py` (строки 11-32) тянут весь конвейер на старте: `docx`, pygments, PIL, lxml. `python -m md2gost --help` платит за это полную цену. Matplotlib и playwright уже ленивые — сделать так же с остальным.
|
||
|
||
### Общий сборщик `ConvertRequest`
|
||
|
||
`gui.py` (строки 1730-1760) и `__main__.py` (строки 272-317) дублируют маппинг примерно двадцати полей и уже разошлись: дефолт типа документа в GUI `coursework`, в CLI `practice`.
|
||
|
||
### Флаг `--open`
|
||
|
||
`__main__.py` строки 315-316: `open_when_done=bool(args.debug)`. Открытие готового файла привязано к дебагу, отдельного флага нет, хотя в GUI есть галочка.
|
||
|
||
### Скачивание PlantUML блокирует Tk
|
||
|
||
`gui.py` строка 1537 — синхронный вызов `fetch_plantuml_jar`, тогда как Graphviz (1576) и Chromium (1622) рядом уже качаются в отдельном потоке.
|
||
|
||
---
|
||
|
||
## P3 — документация не догоняет код
|
||
|
||
### Таблицы модулей в `PROJECT.md` не знают про `mdexport`
|
||
|
||
Новый пакет `mdexport` не попал в разделы с картой репозитория и перечнем модулей — исполнитель не владел этим файлом и намеренно его не трогал. Заодно стоит убрать оттуда упоминания удалённых прототипов, если раздел 12 их ещё перечисляет.
|
||
|
||
---
|
||
|
||
## P4 — замечания исполнителей, оставленные как есть
|
||
|
||
- **`uv.lock` в порядке.** `uv lock` отработал с сетью, добавил matplotlib 3.11.1 с транзитивными зависимостями, `uv lock --check` проходит. Лок синхронен и по matplotlib, и по `pywin32` — пересобирать не нужно.
|
||
- **Playwright закрывается в конце `convert()`.** Это и было целью Фазы 3.4, но у GUI-сценария появилась плата: при каждой следующей конвертации браузер поднимается заново вместо переиспользования. Если mermaid-диаграммы конвертируются часто, стоит подумать про пул с таймаутом.
|
||
- **Кастомный `--plantuml-jar` другой версии не отражается в ключе кэша.** Префикс использует прибитую константу `PLANTUML_VERSION`. Фингерпринт самого файла закрыл бы дыру, но заставлял бы кэш протухать при каждом появлении и исчезновении jar.
|
||
- **Версия jar в ключе кэша задевает и Kroki-рендеры**, потому что не-mermaid типы делят один путь кэша между бэкендами. Бамп версии обесценит и записи, отрисованные через Kroki. Это лишняя перерисовка, не более.
|
||
- **Если одна диаграмма роняет батч-JVM, отбрасывается вся пачка** и каждая диаграмма уходит на свою JVM. Корректно, но стоит одной впустую потраченной JVM.
|
||
- **`--syntax-highlighting --strict --check` теперь завершается с кодом 1**, потому что новое правило `listing.syntax_highlighting` под `--strict` становится ошибкой. Это ровно то поведение, которое закладывалось, но про него надо помнить в скриптах.
|
||
- **Playwright изредка печатает `Task was destroyed but it is pending`** на выходе интерпретера при большом комбинированном прогоне. Не воспроизвелось повторно, все тесты проходят, тот же путь закрытия вызывался и до правок.
|
||
- **Правила игнора `/tmp_*.png` и `/tmp_*.puml`** захватили рабочие черновики `tmp_org_full.*`, `tmp_org_uml.*`, `tmp_arch.*`. Файлы на диске целы, но из `git status` пропали.
|
||
- **`todo.txt` в корне** остался нетронутым — это твой личный блокнот, я его не трогал и не сливал с этим файлом.
|
||
|
||
---
|
||
|
||
## Что стоит сделать перед коммитом
|
||
|
||
1. `git add mdexport/` — иначе всё сломается на свежем клоне.
|
||
2. Просмотреть `git diff --cached` и `git diff` — там 34 файла изменений плюс 8095 удалённых строк.
|
||
3. Прогнать `.venv\Scripts\python.exe -m pytest -q` ещё раз после `git add`.
|
||
4. Собрать exe одним из `build-exe*.bat` — ни один из билд-скриптов в ходе аудита не проверялся, а `pyproject.toml` и состав пакетов поменялись.
|