From bec63972b69122f8bb0c415bbdc9163cbb144624 Mon Sep 17 00:00:00 2001 From: ANTON MAHOMEDOV Date: Mon, 27 Jul 2026 07:55:06 +0300 Subject: [PATCH] docs: add project catalog and validation --- AGENTS.md | 4 +- CONTRIBUTING.md | 2 + README.md | 4 +- START_HERE.md | 31 +++--- docs/CODEX_HANDOFF.md | 2 +- docs/PROJECT_CATALOG.md | 224 ++++++++++++++++++++++++++++++++++++++ docs/README.md | 105 ++++++++++++++++++ docs/TEST_PLAN.md | 16 ++- package.json | 3 +- tools/docs/check-docs.mjs | 123 +++++++++++++++++++++ 10 files changed, 492 insertions(+), 22 deletions(-) create mode 100644 docs/PROJECT_CATALOG.md create mode 100644 docs/README.md create mode 100644 tools/docs/check-docs.mjs diff --git a/AGENTS.md b/AGENTS.md index 59351f18..e467547d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Начало любой новой сессии -Первым прочитать `START_HERE.md`, затем `docs/CODEX_HANDOFF.md`. +Первым прочитать `START_HERE.md`, затем `docs/CODEX_HANDOFF.md`. Для навигации по остальным материалам использовать `docs/README.md`, а для карты каталогов и модулей — `docs/PROJECT_CATALOG.md`. Новый чат, Codex Work или другой агент не должен опираться на память предыдущей сессии или предполагать состояние проекта. Перед изменениями нужно прочитать фактические файлы, ветки, Pull Request, issues, tags, Releases и GitHub Actions. @@ -154,4 +154,4 @@ ## English summary -Read `START_HERE.md` and `docs/CODEX_HANDOFF.md` first, then verify the actual GitHub state. Keep calculation logic pure, derive backs from validated fronts, reject underproduction, preserve every feasible alternative inside the stated search scope, and never claim global completeness for a bounded solver. Use feature branches, exact-head PR checks, factual Chromium evidence, immutable release checkpoints, and immediate uNews publication assets. +Read `START_HERE.md` and `docs/CODEX_HANDOFF.md` first, use `docs/README.md` as the documentation index and `docs/PROJECT_CATALOG.md` as the repository map, then verify the actual GitHub state. Keep calculation logic pure, derive backs from validated fronts, reject underproduction, preserve every feasible alternative inside the stated search scope, and never claim global completeness for a bounded solver. Use feature branches, exact-head PR checks, factual Chromium evidence, immutable release checkpoints, and immediate uNews publication assets. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9d02e6c..7ec73ec7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,7 @@
  • новые параметры добавляются в конфигурацию;
  • производственные формулы не меняются без объяснения;
  • недопечатка и неправильный оборот недопустимы;
    • +
  • новые документы добавляются в docs/README.md, а локальные ссылки проверяются командой npm run check:docs;
  • изменения должны сопровождаться тестами.
    • @@ -52,6 +53,7 @@
  • new settings belong in the central configuration;
  • production formulas must not change without explanation;
  • underproduction and invalid back forms are prohibited;
    • +
  • new documents must be listed in docs/README.md, and local links must pass npm run check:docs;
  • changes should include appropriate tests.
    • diff --git a/README.md b/README.md index eb69c3fe..5cead015 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

    Расчёт офсетных монтажей · Offset Imposition Planner

    Version checkpoint / Версия проекта: 0.7.0-alpha.5

    M7.5 · пользовательские production plans, выбор, экспорт и приоритеты

    -

    Начать здесь / Start here · Передача в Codex / Codex handoff

    +

    Начать здесь / Start here · Документация / Documentation · Каталог проекта / Project catalog

    ## Назначение @@ -184,6 +184,8 @@ uImposition — статический браузерный калькулято ## Документация +- [Полный каталог документации](docs/README.md) +- [Карта каталогов и модулей проекта](docs/PROJECT_CATALOG.md) - [Начать здесь](START_HERE.md) - [Codex handoff](docs/CODEX_HANDOFF.md) - [Текущее состояние](docs/CURRENT_STATE.md) diff --git a/START_HERE.md b/START_HERE.md index 8be05d1e..dbf04067 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -14,6 +14,8 @@ - publication merge commit: `546f637a25b51f72706ebbe7346acb2df9819af8`; - следующий функциональный milestone: **M7.6 / `0.7.0-alpha.6`**; - основной документ передачи в Codex: `docs/CODEX_HANDOFF.md`; +- полный каталог документации: `docs/README.md`; +- карта каталогов и модулей: `docs/PROJECT_CATALOG.md`; - полный актуальный остаток: `docs/REMAINING_WORK.md`. Последние объединённые функциональные PR: @@ -31,20 +33,21 @@ PR `#46` прошёл `173/173` теста, полный Chromium/PDF workflow 1. `AGENTS.md`; 2. `START_HERE.md`; 3. `docs/CODEX_HANDOFF.md`; -4. `VERSION.json`, `VERSION.md`, `CHANGELOG.md`; -5. `docs/CURRENT_STATE.md`; -6. `docs/REMAINING_WORK.md`; -7. `docs/TECHNICAL_SPECIFICATION_RU.md`; -8. `docs/ARCHITECTURE.md`; -9. `docs/M7_4_WORK_AND_TURN.md`; -10. `docs/M7_5_USER_UNIFORM_PRODUCTION_PLANS.md`; -11. `docs/M7_5_USER_PLAN_SELECTION_EXPORT.md`; -12. `docs/M7_5_OBJECTIVE_PRIORITY_EDITOR.md`; -13. `docs/PRODUCTION_COSTING.md`; -14. `docs/TEST_PLAN.md`; -15. `docs/GITHUB_ONLY_DEVELOPMENT.md`; -16. `docs/VERSIONING.md`; -17. последние PR, Actions, branches, tags, Releases и issues. +4. `docs/README.md` и `docs/PROJECT_CATALOG.md`; +5. `VERSION.json`, `VERSION.md`, `CHANGELOG.md`; +6. `docs/CURRENT_STATE.md`; +7. `docs/REMAINING_WORK.md`; +8. `docs/TECHNICAL_SPECIFICATION_RU.md`; +9. `docs/ARCHITECTURE.md`; +10. `docs/M7_4_WORK_AND_TURN.md`; +11. `docs/M7_5_USER_UNIFORM_PRODUCTION_PLANS.md`; +12. `docs/M7_5_USER_PLAN_SELECTION_EXPORT.md`; +13. `docs/M7_5_OBJECTIVE_PRIORITY_EDITOR.md`; +14. `docs/PRODUCTION_COSTING.md`; +15. `docs/TEST_PLAN.md`; +16. `docs/GITHUB_ONLY_DEVELOPMENT.md`; +17. `docs/VERSIONING.md`; +18. последние PR, Actions, branches, tags, Releases и issues. ## Что уже работает diff --git a/docs/CODEX_HANDOFF.md b/docs/CODEX_HANDOFF.md index 83e4b5db..c49dbe22 100644 --- a/docs/CODEX_HANDOFF.md +++ b/docs/CODEX_HANDOFF.md @@ -455,4 +455,4 @@ Codex должен сообщить: ## English operational summary -Start from `main` commit `009451cce94d5cde05ee72305f30447aa65a646c`. The published checkpoint is still `0.7.0-alpha.4`, while `main` contains unreleased M7.5 user-plan generation, explicit selection/export, and an accessible objective-priority editor. First publish a complete `0.7.0-alpha.5` checkpoint. Then implement M7.6 as a compact lossless comparison table before expanding plan families, general work-and-turn search, mixed-format packing, per-row order parameters, persistence, profitability, and heavy-search workers. Never hide feasible alternatives, never accept underproduction, and never claim global completeness outside an explicitly bounded search space. +The verified functional M7.5 baseline is PR `#46` at merge commit `009451cce94d5cde05ee72305f30447aa65a646c`. M7.5 is published as prerelease `0.7.0-alpha.5`; its immutable release commit is `195d6496a291095a69cc9089a64154561ffbb1fa`, while later publication and documentation commits remain on `main`. Verify the live `main` head before changing files. The next functional milestone is M7.6: begin with a pure, lossless comparison-table model and tests before UI work or any search-space expansion. Never hide feasible alternatives, never accept underproduction, and never claim global completeness outside an explicitly bounded search space. diff --git a/docs/PROJECT_CATALOG.md b/docs/PROJECT_CATALOG.md new file mode 100644 index 00000000..9746c34e --- /dev/null +++ b/docs/PROJECT_CATALOG.md @@ -0,0 +1,224 @@ +# Каталог проекта uImposition / Project catalog + +Последняя структурная сверка: **27 июля 2026**, checkpoint `0.7.0-alpha.5`. + +Этот документ объясняет назначение каталогов и активных групп файлов. Он не заменяет [`ARCHITECTURE.md`](ARCHITECTURE.md): архитектура описывает зависимости и поток расчёта, а каталог отвечает на вопрос «где что лежит и куда добавлять новое». + +## 1. Корень репозитория + +| Путь | Назначение | +|---|---| +| `index.html` | Основная страница GitHub Pages и стабильные DOM anchors | +| `styles.css` | Базовые стили страницы | +| `m3.css` … `m7-*.css`, `user-*.css` | Стили milestone- и feature-панелей, подключаемые соответствующими UI-модулями | +| `decision-profile-demo.html` | Изолированная демонстрация decision profile | +| `site.js` | Вспомогательный ранний browser script; текущий `index.html` его не загружает | +| `VERSION.json`, `VERSION.md`, `CHANGELOG.md` | Версия, человекочитаемый checkpoint и история изменений | +| `README.md`, `START_HERE.md`, `AGENTS.md` | Публичное описание, точка входа и обязательные правила агента | +| `CONTRIBUTING.md`, `LICENSE.md` | Участие в проекте и лицензирование | +| `package.json` | Node-команды проверок; runtime сайта не требует build step | + +Root CSS пока не переносится массово: пути динамически подключаются из UI-модулей и покрыты Chromium-сценариями. Возможная будущая консолидация стилей должна быть отдельным UI/architecture patch. + +## 2. Основные каталоги + +| Каталог | Что хранится | Правило | +|---|---|---| +| `src/` | Production ES modules и UI coordinators | Расчётная логика остаётся чистой и не прячется в DOM | +| `tests/` | Node unit/integration/regression tests | Имя теста соответствует модулю или milestone | +| `data/` | Контрольные и regression fixtures | Fixture не выдаётся за automatic solver | +| `tools/` | Release, documentation, screenshot и PDF tooling | Инструменты не меняют production-формулы | +| `docs/` | Текущие, нормативные, milestone и исторические документы | Полный индекс находится в [`README.md`](README.md) | +| `docs/codex-tasks/` | Полные задания и completion records для передачи сессий | Не использовать для коротких временных заметок | +| `news/` | Patchnotes и реальные release images | Один release — свой текст и своё изображение | +| `archive/development/` | Постоянные evidence-пакеты опубликованных версий | Не переписывать задним числом | +| `.github/workflows/` | Quality, Chromium/PDF, uNews и release automation | PR объединяется только после exact-head checks | + +## 3. Карта `src/` + +### Configuration и ввод + +```text +config.js +config.example.js +geometry.js +orders.js +orientation.js +print-specification.js +``` + +Здесь находятся presets/limits, лист и печатная область, строки заказов, направления и спецификация печати. + +### Лицо, оборот, кандидаты и validation + +```text +front-layout.js +back-layout.js +imposition-validation.js +imposition-candidate.js +candidate-generator.js +imposition-distribution.js +mixed-format-layout.js +paper-minimizer.js +``` + +`mixed-format-layout.js` проверяет переданную раскладку и не является automatic packing solver. Оборот создаётся только из лица. + +### Production, стоимость и метрики + +```text +production-metrics.js +production-validation.js +production-report.js +production-cost.js +production-solution-metrics.js +solution-metrics.js +paper-solution-metrics.js +``` + +Layout-формы и цветовые пластины остаются разными метриками. Отсутствующая цена не становится нулём. + +### Решения и каталог вариантов + +```text +optimization-objectives.js +decision-profile.js +pareto-alternatives.js +pareto-display-set.js +feasible-solution-catalog.js +production-alternative-set.js +alternative-explanations.js +alternatives-runtime.js +alternatives-controller.js +``` + +Исходный каталог остаётся lossless; filtering, Pareto и recommendation являются представлением и аннотациями. + +### Пользовательский M7.5 pipeline + +```text +user-uniform-production-plans.js +user-production-plans-runtime.js +user-objective-priority.js +user-production-plans-ui.js +user-objective-priority-ui.js +user-production-plan-details-ui.js +``` + +Модель, runtime и UI разделены. Selection оператора не подменяется recommendation, а reranking не регенерирует планы. + +### Duplex и work-and-turn + +```text +duplex-strategies.js +work-and-turn-layout.js +work-and-turn-control-case.js +work-and-turn-runtime.js +work-and-turn-ui.js +``` + +Текущий контур ограничен задокументированным симметричным контрольным случаем и не доказывает совместимость с конкретной машиной. + +### Представление и PDF + +```text +paper-solution-view.js +paper-solution-renderer.js +production-report-renderer.js +scheme-renderer.js +pdf-document-model.js +pdf-binary.js +pdf-scheme-renderer.js +pdf-report-renderer.js +pdf-export-ui.js +pricing-ui.js +alternatives-ui.js +app.js +``` + +Renderer получает готовую проверенную модель и не пересчитывает производственные формулы. `app.js` остаётся DOM-координатором. + +### Исторические demo entrypoints + +```text +m3-demo.js +m7-decision-demo.js +``` + +Эти модули поддерживают демонстрационные и regression-контуры. Удаление или объединение требует отдельной проверки их HTML/scenario consumers. + +## 4. Тесты и fixtures + +`tests/` сгруппирован по ответственности: + +- geometry/orders/front-back; +- M4 production report; +- M5 PDF model, writer и renderers; +- M6 candidates и paper minimizer; +- M7 objectives, pricing, Pareto и alternatives; +- user plan generation, runtime, selection/export и objective persistence; +- work-and-turn; +- production regression fixtures. + +`data/` содержит: + +- `control-case.json` — основной исторический контрольный набор; +- `control-layout-m3.json` — контрольная раскладка M3; +- `m7-decision-cases.json` — decision fixtures; +- `production-regression-cases.json` — производственные regression cases. + +Команда полного source/unit контроля: + +```text +npm run check +``` + +## 5. Automation + +### GitHub Actions + +| Workflow | Назначение | +|---|---| +| `quality.yml` | Source, documentation и Node tests | +| `capture-screenshots.yml` | Real Chromium, desktop/mobile screenshots, PDF download, `pdfinfo` и Poppler | +| `validate-unews.yml` | Проверка patchnote и очереди публикации | +| `prepare-release-news.yml` | Сбор focused release evidence и manifest | +| `publish-version-release.yml` | Recovery branch, immutable tag и GitHub Release/prerelease | + +### Локальные инструменты + +| Путь | Назначение | +|---|---| +| `tools/docs/check-docs.mjs` | Локальные Markdown-ссылки и полнота каталога документации | +| `tools/screenshots/` | Playwright scenarios, capture manifest и подготовка artifacts | +| `tools/news/prepare-release.mjs` | Patchnote, evidence archive, hashes и release manifest | + +## 6. Releases, news и история + +- `news/README.md` задаёт формат patchnote. +- `news/*.{md,png,jpg}` хранит опубликованный текст и focused image конкретной версии. +- `archive/development/{version}/release.json` хранит manifest. +- Evidence ZIP и SHA-256 принадлежат конкретному immutable checkpoint. +- Старые milestone/evidence документы индексируются в [`docs/README.md`](README.md), но не становятся текущими инструкциями. + +## 7. Куда добавлять новый файл + +| Новый материал | Правильное место | +|---|---| +| Чистая расчётная модель | `src/{responsibility}.js` + соответствующий `tests/*.test.js` | +| DOM/UI renderer | отдельный `src/*-ui.js` или `src/*-renderer.js`; стили — связанный CSS | +| Fixture | `data/` с явным описанием границы | +| Chromium scenario | `tools/screenshots/scenarios/` | +| Текущее состояние | существующий `CURRENT_STATE.md`, `REMAINING_WORK.md` или handoff | +| Устойчивое правило/справочник | отдельный нормативный файл в `docs/` и запись в `docs/README.md` | +| Полное задание передачи | `docs/codex-tasks/` | +| Release note | `news/` | +| Immutable release evidence | `archive/development/{version}/` и GitHub Release assets | + +Не создавать новый документ, если достаточно обновить существующий источник истины. Не переносить и не удалять исторические файлы массово без отдельного решения владельца. + +--- + +## English summary + +This catalog maps repository locations to their responsibilities and file-placement rules. Production logic belongs in pure `src/` modules with matching tests; UI stays separate; fixtures remain explicit; documentation is indexed by status; news and release evidence are version-specific and immutable; and historical files are retained until the owner approves a separate archive migration. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..73d3d775 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,105 @@ +# Документация uImposition / Documentation index + +Этот файл — единый каталог документации проекта. Он помогает отличить текущие источники истины от нормативных справочников, завершённых milestone-документов и исторических evidence-материалов. + +GitHub остаётся единственным источником истины. Перед разработкой сначала прочитайте [`../AGENTS.md`](../AGENTS.md), [`../START_HERE.md`](../START_HERE.md) и [`CODEX_HANDOFF.md`](CODEX_HANDOFF.md), затем проверьте фактические `main`, Pull Request, Actions, tags, Releases и issues. + +## Статусы документов + +- **Актуальный** — обязан описывать фактическое текущее состояние проекта. +- **Нормативный** — задаёт устойчивые правила, требования или процесс. +- **Milestone** — фиксирует границы и решения конкретного этапа; может быть завершённым. +- **История / evidence** — сохраняет факты прошлого релиза или задания и не заменяет текущий handoff. + +Исторические файлы могут намеренно содержать старые версии и прежние планы. Их нужно читать вместе с указанным статусом, а не «осовременивать» задним числом. + +## 1. Начало работы и текущее состояние + +| Документ | Статус | Назначение | +|---|---|---| +| [`CODEX_HANDOFF.md`](CODEX_HANDOFF.md) | Актуальный | Полная передача проекта, текущие границы search space и следующий этап | +| [`CURRENT_STATE.md`](CURRENT_STATE.md) | Актуальный | Проверенное фактическое состояние функций и release checkpoint | +| [`REMAINING_WORK.md`](REMAINING_WORK.md) | Актуальный | Остаток до 1.0 и порядок следующих milestone | +| [`ROADMAP.md`](ROADMAP.md) | Актуальный ориентир | Укрупнённая последовательность развития | +| [`PROJECT_CATALOG.md`](PROJECT_CATALOG.md) | Актуальный | Карта каталогов, исходных модулей, тестов, automation и правил размещения файлов | + +## 2. Требования, архитектура и расчёты + +| Документ | Статус | Назначение | +|---|---|---| +| [`TECHNICAL_SPECIFICATION_RU.md`](TECHNICAL_SPECIFICATION_RU.md) | Нормативный | Основное полное техническое задание на русском | +| [`TECHNICAL_SPECIFICATION_EN.md`](TECHNICAL_SPECIFICATION_EN.md) | Нормативный | Профессиональная английская версия технического задания | +| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Актуальный | Архитектурные слои, зависимости и карта текущего M7.5 pipeline | +| [`ALGORITHM_AND_OPTIMIZATION.md`](ALGORITHM_AND_OPTIMIZATION.md) | Нормативный | Алгоритмические принципы и честные границы оптимизации | +| [`CONFIG_REFERENCE.md`](CONFIG_REFERENCE.md) | Нормативный | Действующие настройки, presets и limits | +| [`PRODUCTION_COSTING.md`](PRODUCTION_COSTING.md) | Нормативный | Модель производственной себестоимости и защита отсутствующих цен | +| [`BUSINESS_MODEL.md`](BUSINESS_MODEL.md) | Справочный | Возможная коммерческая модель; не является текущей production-логикой | +| [`BILINGUAL_LAYOUT.md`](BILINGUAL_LAYOUT.md) | Нормативный | Правила русско-английского интерфейса и документации | + +## 3. Разработка, качество и публикация + +| Документ | Статус | Назначение | +|---|---|---| +| [`GITHUB_ONLY_DEVELOPMENT.md`](GITHUB_ONLY_DEVELOPMENT.md) | Нормативный | Ветки, draft PR, exact-head checks и GitHub-only процесс | +| [`TEST_PLAN.md`](TEST_PLAN.md) | Нормативный | Unit, integration, Chromium, PDF и документационные проверки | +| [`SCREENSHOT_AUTOMATION.md`](SCREENSHOT_AUTOMATION.md) | Нормативный | Реальные Chromium screenshots и PDF evidence | +| [`VERSIONING.md`](VERSIONING.md) | Нормативный | Version checkpoint, recovery branch, immutable tag и GitHub Release | +| [`NEWS_PUBLISHING.md`](NEWS_PUBLISHING.md) | Нормативный | Patchnote, focused image и очередь uNews/Telegram | +| [`DEVELOPMENT_HISTORY_POLICY.md`](DEVELOPMENT_HISTORY_POLICY.md) | Нормативный | Сохранение полезной истории и правила будущей архивации | +| [`GITHUB_PAGES.md`](GITHUB_PAGES.md) | Справочный | Публикация статического сайта | +| [`REPOSITORY_SETUP.md`](REPOSITORY_SETUP.md) | Справочный | Метаданные и первоначальное оформление репозитория | + +## 4. Текущий цикл M7 + +| Документ | Статус | Назначение | +|---|---|---| +| [`M7_IMPLEMENTATION_PLAN.md`](M7_IMPLEMENTATION_PLAN.md) | Milestone | Общая иерархия решений M7 | +| [`M7_4_WORK_AND_TURN.md`](M7_4_WORK_AND_TURN.md) | Завершённый milestone | Контрольный work-and-turn контур и его ограничения | +| [`M7_5_FEASIBLE_SOLUTION_CATALOG.md`](M7_5_FEASIBLE_SOLUTION_CATALOG.md) | Завершённый milestone | Lossless-каталог допустимых вариантов | +| [`M7_5_USER_UNIFORM_PRODUCTION_PLANS.md`](M7_5_USER_UNIFORM_PRODUCTION_PLANS.md) | Завершённый milestone | Пользовательские uniform production plans | +| [`M7_5_USER_PLAN_SELECTION_EXPORT.md`](M7_5_USER_PLAN_SELECTION_EXPORT.md) | Завершённый milestone | Явный выбор, схемы, report и PDF | +| [`M7_5_OBJECTIVE_PRIORITY_EDITOR.md`](M7_5_OBJECTIVE_PRIORITY_EDITOR.md) | Завершённый milestone | Приоритеты оператора и reranking без regeneration | + +Следующий функциональный milestone описан в актуальных [`CODEX_HANDOFF.md`](CODEX_HANDOFF.md) и [`REMAINING_WORK.md`](REMAINING_WORK.md). Отдельного M7.6 implementation-документа пока нет. + +## 5. Завершённые milestone и release evidence + +Эти документы сохраняют историю. Они не заменяют `CURRENT_STATE.md`. + +| Документ | Статус | +|---|---| +| [`M3_IMPLEMENTATION_PLAN.md`](M3_IMPLEMENTATION_PLAN.md) | История M3 | +| [`M4_IMPLEMENTATION_PLAN.md`](M4_IMPLEMENTATION_PLAN.md) | История M4 | +| [`M4_RELEASE_EVIDENCE.md`](M4_RELEASE_EVIDENCE.md) | Evidence M4 | +| [`M5_IMPLEMENTATION_PLAN.md`](M5_IMPLEMENTATION_PLAN.md) | История M5 | +| [`M5_RELEASE_EVIDENCE.md`](M5_RELEASE_EVIDENCE.md) | Evidence M5 | +| [`M6_IMPLEMENTATION_PLAN.md`](M6_IMPLEMENTATION_PLAN.md) | История M6 | +| [`M6_RELEASE_EVIDENCE.md`](M6_RELEASE_EVIDENCE.md) | Evidence M6 | +| [`M7_1_RELEASE_EVIDENCE.md`](M7_1_RELEASE_EVIDENCE.md) | Evidence M7.1 | +| [`M7_3_PRODUCTION_ALTERNATIVES.md`](M7_3_PRODUCTION_ALTERNATIVES.md) | История M7.3 production alternatives | +| [`M7_3_DISPLAY_ALTERNATIVES.md`](M7_3_DISPLAY_ALTERNATIVES.md) | История M7.3 display set | +| [`M7_3_ALTERNATIVE_EXPLANATIONS.md`](M7_3_ALTERNATIVE_EXPLANATIONS.md) | История M7.3 explanations | +| [`M7_3_RUNTIME_UI.md`](M7_3_RUNTIME_UI.md) | История первого M7.3 runtime UI | +| [`M7_3_RUNTIME_ALTERNATIVES_UI.md`](M7_3_RUNTIME_ALTERNATIVES_UI.md) | История уточнённого M7.3 runtime UI | + +## 6. Задания Codex + +| Документ | Статус | Назначение | +|---|---|---| +| [`codex-tasks/2026-07-27_01_HANDOFF_AND_ALPHA5_RELEASE.md`](codex-tasks/2026-07-27_01_HANDOFF_AND_ALPHA5_RELEASE.md) | Выполненная история | Полное задание и completion record релиза `0.7.0-alpha.5` | + +Новые задания сохраняются в `docs/codex-tasks/` только когда их полный текст и completion record нужны для передачи между сессиями. Короткие текущие действия должны отражаться в PR и актуальных status-документах, а не создавать лишние дубли. + +## 7. Проверка каталога + +```text +npm run check:docs +``` + +Проверка подтверждает, что локальные Markdown-ссылки не сломаны и каждый Markdown-файл внутри `docs/` присутствует в этом каталоге. + +--- + +## English summary + +This is the canonical documentation index. It separates current operational truth from stable policies, completed milestones, and historical evidence. Start with `AGENTS.md`, `START_HERE.md`, and `CODEX_HANDOFF.md`; verify live GitHub state before making changes; use `PROJECT_CATALOG.md` for the repository map; and run `npm run check:docs` to validate local links and catalog coverage. diff --git a/docs/TEST_PLAN.md b/docs/TEST_PLAN.md index 3e194f3f..24222fd2 100644 --- a/docs/TEST_PLAN.md +++ b/docs/TEST_PLAN.md @@ -16,7 +16,8 @@ 6. проверка браузерного скачивания; 7. структурная PDF-проверка; 8. полный Poppler-render; -9. ручная проверка доказательных изображений и PDF-страниц. +9. ручная проверка доказательных изображений и PDF-страниц; +10. проверка локальных Markdown-ссылок и полноты каталога документации. ### Базовые сценарии @@ -121,6 +122,13 @@ - смешанный regression проверяет заданную раскладку, но не автоматический mixed-format packing; - поле `forms` исторически означает layout-формы сторон; цветовые пластины 4+4 считаются отдельно. +### Документация + +- `npm run check:docs` проверяет локальные Markdown-ссылки; +- каждый Markdown-файл внутри `docs/` должен быть перечислен в `docs/README.md`; +- исторические документы сохраняют факты своего milestone и не обязаны повторять текущую версию; +- актуальные status/handoff-документы не должны противоречить опубликованному checkpoint. + @@ -128,7 +136,7 @@ ### Test levels -Unit tests, calculation integration, front/back rematerialisation, independent production reporting, browser visual checks, PDF download verification, structural checks, complete Poppler rendering, and manual evidence review. +Unit tests, calculation integration, front/back rematerialisation, independent production reporting, browser visual checks, PDF download verification, structural checks, complete Poppler rendering, manual evidence review, and documentation link/catalog validation. ### M6 verification @@ -150,6 +158,8 @@ Unit tests, calculation integration, front/back rematerialisation, independent p The 32-page tests do not claim folded-signature pagination, and the mixed-format test validates a supplied packing rather than automatic rectangle packing. +`npm run check:docs` verifies local Markdown links and requires every Markdown file under `docs/` to be listed in `docs/README.md`. Historical milestone documents may retain their original version facts. + @@ -167,4 +177,4 @@ The 32-page tests do not claim folded-signature pagination, and the mixed-format - автоматический перетираж пар / automatic pair overrun: 10; - PDF схем / scheme PDF: 8 pages; - PDF отчёта / report PDF: 6 pages; -- всего проверенных PDF-страниц / total verified PDF pages: 14. \ No newline at end of file +- всего проверенных PDF-страниц / total verified PDF pages: 14. diff --git a/package.json b/package.json index 676b99e2..54584f2b 100644 --- a/package.json +++ b/package.json @@ -6,8 +6,9 @@ "description": "Browser-based offset imposition planner.", "scripts": { "test": "node --test tests/*.test.js", + "check:docs": "node tools/docs/check-docs.mjs", "check:source": "node --check src/config.js && node --check src/geometry.js && node --check src/orders.js && node --check src/orientation.js && node --check src/front-layout.js && node --check src/back-layout.js && node --check src/imposition-validation.js && node --check src/imposition-candidate.js && node --check src/candidate-generator.js && node --check src/paper-minimizer.js && node --check src/paper-solution-view.js && node --check src/paper-solution-renderer.js && node --check src/imposition-distribution.js && node --check src/mixed-format-layout.js && node --check src/print-specification.js && node --check src/duplex-strategies.js && node --check src/work-and-turn-layout.js && node --check src/work-and-turn-control-case.js && node --check src/work-and-turn-runtime.js && node --check src/work-and-turn-ui.js && node --check src/production-cost.js && node --check src/production-solution-metrics.js && node --check src/paper-solution-metrics.js && node --check src/production-alternative-set.js && node --check src/alternative-explanations.js && node --check src/alternatives-runtime.js && node --check src/alternatives-controller.js && node --check src/alternatives-ui.js && node --check src/solution-metrics.js && node --check src/pricing-ui.js && node --check src/optimization-objectives.js && node --check src/decision-profile.js && node --check src/pareto-alternatives.js && node --check src/pareto-display-set.js && node --check src/feasible-solution-catalog.js && node --check src/user-uniform-production-plans.js && node --check src/user-production-plans-ui.js && node --check src/user-production-plans-runtime.js && node --check src/user-objective-priority.js && node --check src/user-objective-priority-ui.js && node --check src/user-production-plan-details-ui.js && node --check src/m7-decision-demo.js && node --check src/production-metrics.js && node --check src/production-validation.js && node --check src/production-report.js && node --check src/pdf-document-model.js && node --check src/pdf-binary.js && node --check src/pdf-scheme-renderer.js && node --check src/pdf-report-renderer.js && node --check src/pdf-export-ui.js && node --check src/production-report-renderer.js && node --check src/scheme-renderer.js && node --check src/m3-demo.js && node --check src/app.js", - "check": "npm run check:source && npm test" + "check": "npm run check:docs && npm run check:source && npm test" }, "engines": { "node": ">=22" diff --git a/tools/docs/check-docs.mjs b/tools/docs/check-docs.mjs new file mode 100644 index 00000000..917afbec --- /dev/null +++ b/tools/docs/check-docs.mjs @@ -0,0 +1,123 @@ +import fs from "node:fs"; +import path from "node:path"; +import process from "node:process"; + +const repositoryRoot = process.cwd(); +const docsRoot = path.join(repositoryRoot, "docs"); +const catalogPath = path.join(docsRoot, "README.md"); +const errors = []; + +function listMarkdownFiles(directory) { + const files = []; + + for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { + if (entry.name === ".git" || entry.name === "node_modules") { + continue; + } + + const entryPath = path.join(directory, entry.name); + if (entry.isDirectory()) { + files.push(...listMarkdownFiles(entryPath)); + } else if (entry.isFile() && entry.name.endsWith(".md")) { + files.push(entryPath); + } + } + + return files; +} + +function extractLocalTargets(markdown, sourcePath) { + const targets = []; + const linkPattern = /!?\[[^\]]*]\(([^)]+)\)/g; + + for (const match of markdown.matchAll(linkPattern)) { + const rawTarget = match[1].trim().replace(/^<|>$/g, ""); + if ( + rawTarget === "" || + rawTarget.startsWith("#") || + /^(?:https?:|mailto:|tel:|data:)/i.test(rawTarget) + ) { + continue; + } + + const targetWithoutFragment = rawTarget.split("#", 1)[0].split("?", 1)[0]; + if (targetWithoutFragment === "") { + continue; + } + + const resolvedTarget = path.resolve( + path.dirname(sourcePath), + decodeURIComponent(targetWithoutFragment), + ); + targets.push(resolvedTarget); + } + + return targets; +} + +if (!fs.existsSync(catalogPath)) { + errors.push("Missing canonical documentation catalog: docs/README.md"); +} + +const markdownFiles = listMarkdownFiles(repositoryRoot); + +for (const markdownPath of markdownFiles) { + const markdown = fs.readFileSync(markdownPath, "utf8"); + const localTargets = extractLocalTargets(markdown, markdownPath); + + for (const localTarget of localTargets) { + const relativeTarget = path.relative(repositoryRoot, localTarget); + if ( + relativeTarget.startsWith(`..${path.sep}`) || + path.isAbsolute(relativeTarget) + ) { + errors.push( + `${path.relative(repositoryRoot, markdownPath)} links outside the repository: ${relativeTarget}`, + ); + continue; + } + + if (!fs.existsSync(localTarget)) { + errors.push( + `${path.relative(repositoryRoot, markdownPath)} has a broken local link: ${relativeTarget}`, + ); + } + } +} + +if (fs.existsSync(catalogPath)) { + const catalog = fs.readFileSync(catalogPath, "utf8"); + const catalogTargets = new Set( + extractLocalTargets(catalog, catalogPath).map((target) => + path.normalize(target), + ), + ); + const uncataloguedDocs = markdownFiles + .filter( + (markdownPath) => + markdownPath.startsWith(`${docsRoot}${path.sep}`) && + markdownPath !== catalogPath, + ) + .filter((markdownPath) => !catalogTargets.has(path.normalize(markdownPath))) + .map((markdownPath) => path.relative(repositoryRoot, markdownPath)) + .sort(); + + for (const uncataloguedDoc of uncataloguedDocs) { + errors.push(`Documentation file is missing from docs/README.md: ${uncataloguedDoc}`); + } +} + +if (errors.length > 0) { + console.error(`Documentation check failed with ${errors.length} error(s):`); + for (const error of errors) { + console.error(`- ${error}`); + } + process.exitCode = 1; +} else { + const documentedFiles = markdownFiles.filter((markdownPath) => + markdownPath.startsWith(`${docsRoot}${path.sep}`), + ).length; + console.log( + `Documentation check passed: ${markdownFiles.length} Markdown files, ${documentedFiles} files under docs/, no broken local links, full catalog coverage.`, + ); +}