docs(mdview): добавить описание работы и тестовые паттерны

Co-Authored-By: Oz <oz-agent@warp.dev>
2026-06-07 22:39:14 +03:00
parent 07c398a560
commit 6992c1436e
1 changed files with 188 additions and 0 deletions
@@ -0,0 +1,188 @@
+# MDView: описание работы и тестовые паттерны
+## Назначение
+`mdview` — консольный просмотрщик Markdown для текстового режима 80x32.
+Программа загружает `.MD`-файл, индексирует его на экранные сегменты и рендерит содержимое с учётом переносов, стилей и специальных блоков.
+
+## Как работает программа
+### 1) Загрузка файла
+- На старте вызывается `load_file(path)`.
+- Если путь не передан, используется `SAMPLE.MD`.
+- При ошибках загрузки программа показывает причину и завершает работу после нажатия клавиши.
+
+### 2) Индексация (`index_lines`)
+- Файл разбирается в массив сегментов для быстрого рендера.
+- Поддерживаются ключевые типы строк:
+  - заголовки `#..####`,
+  - маркированные/нумерованные списки,
+  - цитаты `>`,
+  - горизонтальные разделители,
+  - fenced code-блоки,
+  - таблицы (nowrap-режим),
+  - обычные параграфы.
+- Для list/quote/plain используется общая логика сканирования с режимами склейки строк.
+
+### 3) Рендер (`render_line`, `render_viewport`)
+- Для каждой видимой строки рисуется префикс (маркер списка, цитаты и т.д.) и текст.
+- Поддерживаются inline-стили:
+  - `**жирный**`,
+  - `*курсив*`,
+  - `_подчёркнутый_`,
+  - `~~зачёркнутый~~`,
+  - `` `code` ``.
+- Табы расширяются до фиксированного шага.
+- Для длинных nowrap-строк применяется горизонтальный сдвиг и индикаторы `<`/`>`.
+
+### 4) Навигация
+- `Up/Down` — прокрутка на 1 строку.
+- `PgUp/PgDn` — прокрутка на экран.
+- `Home/End` — начало/конец документа.
+- `Left/Right` — горизонтальная прокрутка nowrap-контента.
+- `Esc` или `F10` — выход.
+
+## Сборка и запуск
+```bash
+make -C examples/mdview
+```
+
+Запуск на целевой системе:
+```bash
+mdview.exe <путь_к_файлу.md>
+```
+
+Если путь не указан, открывается `SAMPLE.MD`.
+
+## Тестовые паттерны
+Ниже набор паттернов для ручной регрессии.
+
+### P01 — Базовый smoke-тест открытия
+Вход:
+- валидный markdown-файл среднего размера.
+
+Ожидается:
+- файл открывается без ошибок;
+- статус-бар и меню отображаются корректно;
+- прокрутка работает.
+
+### P02 — Ошибка открытия файла
+Вход:
+- несуществующий путь к файлу.
+
+Ожидается:
+- сообщение `mdview: cannot load file`;
+- корректный код причины (`open failed` и т.п.);
+- ожидание клавиши перед выходом.
+
+### P03 — Пустой файл
+Вход:
+- пустой `.md`.
+
+Ожидается:
+- сообщение `mdview: empty file`;
+- корректное завершение после нажатия клавиши.
+
+### P04 — Обычный параграф и переносы
+Шаблон:
+```md
+Это длинный абзац для проверки переноса строк в обычном тексте.
+Вторая строка должна мягко склеиться с первой.
+```
+
+Ожидается:
+- строки склеиваются как единый параграф;
+- переносы происходят по ширине экрана без потери символов.
+
+### P05 — Hard break в параграфе
+Шаблон:
+```md
+Первая строка с двумя пробелами в конце.  
+Вторая строка после hard break.
+```
+
+Ожидается:
+- между строками сохраняется принудительный разрыв;
+- inline-стиль не ломается.
+
+### P06 — Многострочный список с lazy continuation
+Шаблон:
+```md
+- Пункт списка, который продолжается
+  на следующей строке с отступом.
+```
+
+Ожидается:
+- continuation-строка склеивается с пунктом через один пробел;
+- лишние ведущие отступы continuation не попадают в итоговый текст;
+- переносы не ломают маркер списка.
+
+### P07 — Многострочная цитата
+Шаблон:
+```md
+> Первая строка цитаты
+> Вторая строка цитаты
+> Третья строка цитаты
+```
+
+Ожидается:
+- для продолжений корректно повторяется quote-префикс;
+- сырой символ `>` из исходника не «просачивается» в середину текста.
+
+### P08 — Пустая quoted-строка как разделитель
+Шаблон:
+```md
+> Первый параграф цитаты
+>
+> Второй параграф цитаты
+```
+
+Ожидается:
+- пустая quoted-строка разделяет два параграфа;
+- рендер не объединяет их в один поток.
+
+### P09 — Таблица в nowrap-режиме
+Шаблон:
+```md
+| col1 | col2 | col3 |
+|------|------|------|
+| очень длинное значение | очень длинное значение | очень длинное значение |
+```
+
+Ожидается:
+- строка таблицы не переносится по словам;
+- работает горизонтальный сдвиг `Left/Right`;
+- индикаторы `<`/`>` показывают скрытый контент.
+
+### P10 — Fenced code-block
+Шаблон:
+~~~md
+```text
+**это не жирный**
+_это не подчёркнутый_
+```
+~~~
+
+Ожидается:
+- внутри code-блока inline-разметка не применяется;
+- текст отображается как литерал.
+
+### P11 — Inline-стили на обычном тексте
+Шаблон:
+```md
+Текст с **жирным**, *курсивом*, _подчёркнутым_, ~~зачёркнутым~~ и `code`.
+```
+
+Ожидается:
+- все перечисленные стили рендерятся корректно;
+- литеральные случаи вроде `2 * 3` не превращаются в стиль.
+
+### P12 — Статус-бар и границы прокрутки
+Вход:
+- документ на несколько экранов.
+
+Ожидается:
+- корректные `L x-y / total` и `%`;
+- `Home/End` приводят к ожидаемым позициям;
+- при выходе за границы документа top-line корректно clamp-ится.
+
+## Рекомендация по регрессии
+После любых изменений в логике индексации/рендера прогонять минимум:
+- `P04`, `P05`, `P06`, `P07`, `P09`, `P10`, `P11`, `P12`.