Opt-in generation cache and incremental writes

[pidtchay]

Описание (RU)

Цель

Выпустить 2.1.0-beta.6 с opt-in кэшем генерации и инкрементальной записью файлов для ускорения повторных прогонов локально и в CI.

Объём работ

• Реализовать управление кэшем генерации:
  • CLI: --cache, --cachePath, --cacheStrategy, --cacheDebug
  • конфиг: cache, cachePath, cacheStrategy, cacheDebug
• Добавить GenerationCache с persisted cache-entries (fingerprint + список сгенерированных файлов).
• Добавить writeFileIfChanged — запись только при изменении содержимого.
• Переработать очистку output:
  • убрать полный wipe перед генерацией каждого item;
  • удалять stale-файлы после генерации на основе expected output set.
• Поддержать стратегии кэша:
  • entity — пропуск неизменённых items при совпадении fingerprint;
  • content — полная генерация, но без перезаписи неизменённых файлов.
• Выводить статистику записи (written, unchanged) и групповое предупреждение при общем output без кэша.
• Исправить validateAndMigrateConfigData для legacy array-конфигов (strip undefined после convertArrayToObject).

Документация

• Обновить CHANGELOG.md / CHANGELOG.RU.md (версия 2.1.0-beta.6, дата 2026-05-23).
• Обновить README.md / README.rus.md.
• Добавить раздел в MIGRATION.md / MIGRATION.RU.md про кэш генерации.
• Рекомендовать добавлять .openapi-codegen-cache.json в .gitignore.

Критерии приёмки

• Повторный прогон с --cache --cacheStrategy entity не перезаписывает неизменённые файлы.
• Изменение OpenAPI spec инвалидирует кэш и обновляет output.
• Multi-item конфиг с общим output работает стабильно при включённом кэше.
• Покрытие unit-тестами сценариев кэша в test/cacheGeneration.test.ts.

---

Description (EN)

Goal

Ship 2.1.0-beta.6 with an opt-in generation cache and content-aware file writes to speed up repeat runs in local and CI workflows.

Scope

• Implement generation cache controls:
  • CLI: --cache, --cachePath, --cacheStrategy, --cacheDebug
  • config: cache, cachePath, cacheStrategy, cacheDebug
• Add GenerationCache with persisted entries (fingerprint + generated files list).
• Add writeFileIfChanged to skip rewriting unchanged files.
• Redesign output cleanup:
  • remove full directory wipe before each item;
  • remove stale files after generation based on the expected output set.
• Support cache strategies:
  • entity — skip unchanged items when fingerprint matches;
  • content — always generate, but skip unchanged writes.
• Log write statistics (written, unchanged) and emit a grouped warning when multiple items share one output with cache disabled.
• Fix validateAndMigrateConfigData for legacy array-format configs (strip undefined after convertArrayToObject).

Documentation

• Update CHANGELOG.md / CHANGELOG.RU.md (version 2.1.0-beta.6, date 2026-05-23).
• Update README.md / README.rus.md.
• Add a generation cache subsection to MIGRATION.md / MIGRATION.RU.md.
• Recommend adding .openapi-codegen-cache.json to .gitignore.

Acceptance criteria

• A repeat run with --cache --cacheStrategy entity does not rewrite unchanged files.
• Changing the OpenAPI spec invalidates the cache and updates output.
• Multi-item configs with a shared output directory remain stable when cache is enabled.
• Cache scenarios are covered by unit tests in test/cacheGeneration.test.ts.