eggpipe 0.3.0__tar.gz

eggpipe-0.3.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+venv/
+ENV/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Output (сгенерированные файлы)
+/output/
+/outputs/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Distribution
+MANIFEST
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# Eggpipe runtime (lock, manifest, staging)
+.eggpipe/
+
+# Logs
+*.log
+
+# Local notes (not tracked)
+/.local/
+
+# Docs site
+site/
+
+# OS
+.DS_Store
+Thumbs.db

eggpipe-0.3.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+Все заметные изменения проекта. Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+версионирование — [SemVer](https://semver.org/lang/ru/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-13
+
+### Changed
+
+- ТЗ v2.2: English-only source code, comments, docstrings, CLI help и diagnostics.
+- Диагностические коды `MGxxx` → `EGxxx`; номера сохранены (ADR-0013).
+- `GeneratorRules`/`GeneratorRulesLoader` → `ProjectConfig`/`ProjectConfigLoader`;
+  `config/generator_rules.py` → `config/project_config.py`.
+- Удалён `InputSlice`; публичный тип выбора входа — `InputSelection`.
+- Удалены legacy-поля `CompositionResult.format`/`version`.
+- Унифицированы ignore-константы; `WIN_RESERVED` → `WINDOWS_RESERVED_NAMES`.
+- Translation memory русских сообщений и docstrings: `engineering/i18n/`.
+- ADR-0012 (English-only) и ADR-0013 (EG-коды).
+- Проект объявлен beta (0.x): до 1.0 breaking changes возможны (ADR-0014).
+- CI-матрица расширена до Python 3.11–3.15.
+- Проект переименован в **Eggpipe**: CLI `eggpipe`, конфиг `.eggpipe.yaml`, state `.eggpipe/`,
+  package/import `eggpipe`.
+- ТЗ v2.0: breaking changes, решения v1.4 вошли без изменения смысла.
+- CLI/UX, diagnostics и JSON-отчёт v2 зафиксированы.
+- Переименование кода/пакета выполнено: `eggpipe`, `eggpipe.*`, `.eggpipe*`.
+- Реализованы форматы/наследование, model units и слои, resources, decorator API,
+  `input_formats`/EG033, глобальный manifest/ownership/cleanup, CLI и JSON v2.
+- TPC-H example переведён на `directory-per-model` и decorator API.
+
+## [0.1.0] - 2026-11-11
+
+### Added
+
+- Ядро v0.1, первый слой: `ModelDocument`/`SourceModel`/`ModelSlice`, `FieldDef`, `EnumDef`,
+  `CustomType`, `UNSET`, YAML-парсер на `ruamel.yaml`, формат `entity-model`, семантический
+  валидатор, срезы с замыканием по enums/types и naming-утилиты.
+- Writer: ownership, per-generator manifest, atomic write, lock, `--plan`/`--check`.
+- `Engine` (`build()`/`generate()`/`check()`), `GeneratorPlugin` и контракты генераторов.
+- CLI `mg`: `generate`, `init`, `config show/validate`, `model validate`, `gen list/info`,
+  `format list`, `clean`.
+- Reference-плагин `examples/reference-generator` и golden-тест.
+- v0.2: composition — `imports`, `entity.extends`, discovery каталогов, merge по ADR-0001,
+  project-root boundary и `--allow-outside-imports`.
+- Cleanup owned-артефактов (`off|prompt|enabled`), `--clean`, MG050.
+- `sources[].input` и MG014 (`updated_at`).
+- v0.3: format-плагины из entry points, `mg watch`, JSON-отчёт, provenance-утилита,
+  `--plugin` для локальной разработки.
+- Стабилизация: integration-тест watch, contract-тесты плагинов, security-тест symlink,
+  руководство `docs/plugin-guide.md`.
+- ADR-0003 (null-семантика/UNSET), ADR-0004 (ownership/cleanup), ADR-0005 (library API),
+  ADR-0006 (format extension) и индекс ADR.
+- `UNSET` больше не сериализуется как `default: null` — ключ опускается.
+- `on_conflict: error` теперь даёт MG041 для любого существующего файла; `mg clean` берёт lock.
+- Provenance на уровне entity: `Entity.source` заполняется парсером, исключён из сериализации;
+  `git_provenance()` доступен плагинам.
+- Docs-site: `mkdocs.yml`, `docs/index.md`, сборка `mkdocs build --strict` в CI.
+- Property-based тесты (Hypothesis) для парсера и round-trip; determinism-тест повторной генерации.
+- Backlog P1/P2: `mg model schema`, `mg config schema`, единая точка logging,
+  интерактивный `mg clean --yes`, устойчивый plugin loader с issues, флаги watch.
+- ТЗ v1.3: зарегистрированы MG030/MG300, диапазоны кодов и публичный API синхронизированы
+  с реализацией; `Entity.source` и fallback `cleanup: prompt`.
+- TPC-H example: 8 таблиц, PostgreSQL DDL и Pydantic-модели; варианты одного/split генератора
+  на одном наборе `model/`; Jinja2-шаблоны с `options.templates_dir`.
+- Опциональный `metadata_generator.templating` (extra `[jinja]`): загрузка Jinja2-окружения
+  и `render_template`, ядро не импортирует Jinja2 при старте.
+- Каталог диагностик `docs/reference/diagnostics.md`.
+- ТЗ v1.2: модель `ModelDocument` → `SourceModel` → `ModelSlice`, контракты плагинов,
+  ownership/manifest, CLI и диагностики.
+- System Design v1.2 и ADR-0001 (семантика композиции).
+- Agent harness: `AGENTS.md`, `opencode.json`, команды, skills и read-only `spec-reviewer`.
+- Python-чекер документации `tools/check_docs.py` и docs-CI.
+- Test harness: `pyproject.toml`, `uv.lock`, ruff, Pyrefly (strict), pytest, coverage.
+- ADR-0002: Pyrefly вместо mypy.
+- Delivery harness: сборка wheel/sdist, проверка артефактов и release-workflow.
+- MIT License.
+
+### Fixed
+
+- `Entity.updated_at` сохраняет `datetime` при JSON round-trip, включая значения на полночь.

eggpipe-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Спасибо за интерес к `eggpipe`. Проект развивается по ТЗ и System Design, поэтому
+изменения должны быть согласованы с документацией.
+
+## Перед началом
+
+1. Прочитай [README](./README.md), [ТЗ](./engineering/requirements/index.md) и
+   [System Design](./engineering/system-design/index.md).
+2. Проверь принятые решения в [ADR](./engineering/adr/).
+3. Для агентов действуют дополнительные правила в [AGENTS.md](./AGENTS.md).
+
+## Окружение
+
+Проект использует Python 3.11+ и [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync --extra dev
+```
+
+`uv.lock` коммитится. Для установки пакета пользователями остаётся `pip install eggpipe`.
+
+Для basedpyright/Pyright в корне есть `pyrightconfig.json`: он задаёт src-layout, `extraPaths` и `.venv`.
+Перед проверкой убедитесь, что окружение создано через `uv sync --extra dev`.
+
+## Проверки
+
+Перед pull request:
+
+```bash
+uv run ruff check .
+uv run ruff format --check src tests tools examples
+uv run pyrefly check
+uv run pytest --cov
+uv run python tools/check_docs.py --strict
+uv build
+uv run python tools/check_wheel.py dist
+```
+
+Все проверки должны проходить. Покрытие ядра — не ниже 80%.
+
+## Документация
+
+- `engineering/requirements/v1.0.md`–`v1.4.md` — история, не редактировать.
+- Новое поведение оформляется новой версией ТЗ `vX.Y`, а не правкой текущей.
+- Архитектурные решения — новый ADR в `engineering/adr/`, существующие ADR не переписываются.
+- При изменении версии обнови `engineering/requirements/index.md`, System Design, README,
+  `.session-context.md` и harness-файлы, где указана актуальная версия.
+
+## Pull request
+
+- Один PR — одна логическая задача.
+- Добавляй тесты на новое поведение и запись в `CHANGELOG.md`.
+- Не коммить `dist/`, `.venv/`, `.eggpipe/` и сгенерированные артефакты.
+- Для изменений публичного API или контрактов плагинов — сначала обнови ТЗ и ADR.

eggpipe-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The metadata-generator Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eggpipe-0.3.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: eggpipe
+Version: 0.3.0
+Summary: CLI tool and library for metadata-driven code generation
+Project-URL: Homepage, https://github.com/SpiGit/eggpipe
+Project-URL: Documentation, https://github.com/SpiGit/eggpipe/tree/main/docs
+Project-URL: Repository, https://github.com/SpiGit/eggpipe
+Project-URL: Changelog, https://github.com/SpiGit/eggpipe/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/SpiGit/eggpipe/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-generation,metadata,pydantic,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: ruamel-yaml>=0.18.6
+Requires-Dist: typer>=0.12.0
+Requires-Dist: typing-extensions>=4.10.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
+Requires-Dist: jinja2>=3.1.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
+Requires-Dist: pyrefly>=1.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: watchdog>=4.0.0; extra == 'dev'
+Provides-Extra: jinja
+Requires-Dist: jinja2>=3.1.0; extra == 'jinja'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# Eggpipe
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SpiGit/eggpipe/main/docs/assets/brand/lockup/eggpipe-wordmark-dark.png">
+    <img src="https://raw.githubusercontent.com/SpiGit/eggpipe/main/docs/assets/brand/lockup/eggpipe-wordmark-light.png" alt="Eggpipe" width="420">
+  </picture>
+</p>
+
+> Инструмент для генерации артефактов (SQL, Python, TypeScript, etc.) из YAML-описания модели данных.
+
+> **Статус: beta (0.x).** Проект находится в стадии бета-тестирования. До версии 1.0
+> публичный API, CLI, формат `.eggpipe.yaml`, JSON-отчёт и генерируемые артефакты могут
+> меняться без сохранения обратной совместимости. Для production фиксируйте версию и
+> читайте `CHANGELOG.md`. Подробнее — [Статус и совместимость](https://github.com/SpiGit/eggpipe/blob/main/docs/user/status.md).
+
+## Концепция
+
+**Один источник истины → произвольные форматы вывода.**
+
+Описываете структуру данных один раз в YAML — получаете:
+- SQL-миграции и схемы
+- Python-модели (Pydantic, Django, SQLAlchemy, dataclasses)
+- TypeScript-типы и Zod-схемы
+- OpenAPI-спецификации
+- Go-структуры
+- И всё остальное через плагинную систему
+
+Ключевые свойства:
+
+- **Сущности изолированы**: базовая модель не знает о связях между ними — ядро остаётся нейтральным.
+- **Нет встроенных генераторов**: все генераторы и все форматы (кроме базового `entity-model`) — плагины.
+- **Модель — просто данные**: метаконфиг решает, что, из чего и куда генерировать.
+
+## Режимы использования
+
+### Как CLI
+
+```bash
+pip install eggpipe
+eggpipe generate model.yaml
+eggpipe watch model.yaml
+```
+
+### Как библиотека
+
+```python
+from eggpipe import Engine, AppConfig, ProjectConfigLoader
+
+rules = ProjectConfigLoader().load(".eggpipe.yaml")
+engine = Engine(AppConfig(), rules)
+
+report = engine.build()        # парсинг/валидация/генерация без записи
+report = engine.generate()     # build + запись артефактов
+report = engine.check()        # проверить актуальность без записи
+
+if not report.success:
+    for d in report.diagnostics:
+        print(d.code, d.message)
+```
+
+`Engine` не вызывает `sys.exit`, не настраивает root-logger и не пишет файлы в `build()` — это обычная библиотека. Детали — System Design §2.8.
+
+### Как библиотека + CLI (рекомендуемый сценарий)
+
+**Сценарий:** Проект N подключает eggpipe как библиотеку, пишет свои плагины генерации, запускает через CLI.
+
+1. Подключение как зависимость:
+   ```toml
+   # pyproject.toml проекта N
+   [project]
+   dependencies = ["eggpipe"]
+   ```
+
+2. Плагин генерации:
+   ```python
+   # my_project/plugins.py
+   from eggpipe import Artifact, GeneratorConfig, GenerationContext, ModelSlice, generator
+
+   @generator(id="my-project-generator", input_formats={"entity-model"})
+   def my_project_generator(
+       model: ModelSlice,
+       context: GenerationContext,
+       config: GeneratorConfig,
+   ) -> list[Artifact]:
+       # model — замкнутый срез модели (entities/enums/types)
+       # context — variables, naming_hint, formats, импортированные файлы
+       # config — блок этого генератора из .eggpipe.yaml
+       return [Artifact(path="user.py", content=render(model.entities))]
+   ```
+
+3. Регистрация через entry points:
+   ```toml
+   # pyproject.toml проекта N
+   [project.entry-points."eggpipe.generators"]
+   my-project-generator = "my_project.plugins:my_project_generator"
+   ```
+
+4. Запуск:
+   - CLI: `eggpipe generate` — обнаруживает плагины из entry points
+   - Library: `engine.generate()` — тот же результат
+
+**Примеры инструментов с такой архитектурой:** ruff, pytest, mypy.
+
+Плагин также может регистрировать **формат документа** (например `sql-model` с SQL-спецификой и собственными правилами) — группа entry points `eggpipe.formats`.
+
+## Быстрый старт
+
+```bash
+pip install eggpipe
+
+# Для watch-режима
+pip install "eggpipe[watch]"
+
+# Для Jinja2-helper в плагинах
+pip install "eggpipe[jinja]"
+
+# Инициализация конфигурации
+eggpipe init
+
+# Генерация
+eggpipe generate model.yaml
+eggpipe generate --plan            # посмотреть план без записи
+eggpipe generate --check           # проверить актуальность (CI)
+
+# Режим watch
+eggpipe watch model.yaml
+
+# Разработка своего плагина — editable install
+pip install -e ./plugins/my-generator
+eggpipe gen list
+
+# JSON Schema
+eggpipe model schema
+eggpipe config schema
+
+# Очистка owned-артефактов
+eggpipe clean --dry-run
+eggpipe clean --yes
+
+# Локальный плагин без установки
+eggpipe generate --plugin ./my_plugin.py
+```
+
+## Разработка
+
+```bash
+uv sync --extra dev
+
+uv run ruff check .
+uv run ruff format --check src tests tools examples
+uv run pyrefly check
+uv run pytest --cov
+uv run python tools/check_docs.py --strict
+uv build
+uv run python tools/check_wheel.py dist
+```
+
+Dev/CI используют [uv](https://docs.astral.sh/uv/) и закоммиченный `uv.lock`.
+Для установки пакета пользователями остаётся `pip install eggpipe`.
+
+Типизация — [Pyrefly](https://pyrefly.org/) в strict-режиме (встроенная поддержка Pydantic v2).
+mypy не входит в блокирующий CI; решение зафиксировано в
+[ADR-0002](./engineering/adr/0002-type-checker-pyrefly.md).
+
+Для basedpyright/Pyright в корне лежит `pyrightconfig.json` (src-layout, `extraPaths`, `.venv`).
+Перед проверкой выполните `uv sync --extra dev`.
+
+## Документация
+
+Проверка согласованности документации:
+
+```bash
+uv run python tools/check_docs.py --strict
+```
+
+- [Документация](./docs/index.md) — пользователям и AI-агентам
+- [Инженерная документация](./engineering/index.md) — ТЗ, ADR, System Design, ревью
+- [Быстрый старт](./docs/user/quickstart.md)
+- [Плагины](./docs/user/plugins.md)
+- [Техническое задание](./engineering/requirements/index.md) — актуальная версия v2.2
+- [System Design](./engineering/system-design/index.md)
+- [ADR index](./engineering/adr/index.md)
+- [ADR-0001: семантика композиции](./engineering/adr/0001-composition-merge-semantics.md)
+- [ADR-0002: type checker — Pyrefly](./engineering/adr/0002-type-checker-pyrefly.md)
+- [ADR-0003: null-семантика](./engineering/adr/0003-null-semantics.md)
+- [ADR-0004: ownership и cleanup](./engineering/adr/0004-ownership-manifest-cleanup.md)
+- [ADR-0005: library API](./engineering/adr/0005-library-api.md)
+- [ADR-0006: расширение формата](./engineering/adr/0006-format-extension.md)
+- [ADR-0007: наследование форматов](./engineering/adr/0007-format-inheritance.md)
+- [ADR-0008: model units и раскладки источников](./engineering/adr/0008-model-units-and-source-layouts.md)
+- [ADR-0009: глобальный manifest](./engineering/adr/0009-global-manifest-ownership.md)
+- [ADR-0010: decorator API генераторов](./engineering/adr/0010-decorator-generator-api.md)
+- [Ревью проекта (2026-11-10)](./engineering/reviews/2026-11-10-project-review.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Changelog](./CHANGELOG.md)
+- [Каталог диагностик](./docs/user/reference/diagnostics.md)
+- [Релиз](./engineering/release.md)
+- [TPC-H example](./examples/tpc-h/README.md)
+- [Reference generator](./examples/reference-generator/README.md)
+
+## Лицензия
+
+[MIT](./LICENSE).
+
+## Статус
+
+**Стадия:** Eggpipe 0.3.0, ТЗ v2.2. Реализованы E0–E8 и E9: пакет/CLI/config/state,
+форматы и слои, decorator API, глобальный manifest, CLI/JSON v2, CI и release workflow.

eggpipe-0.3.0/README.md

@@ -0,0 +1,209 @@
+# Eggpipe
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SpiGit/eggpipe/main/docs/assets/brand/lockup/eggpipe-wordmark-dark.png">
+    <img src="https://raw.githubusercontent.com/SpiGit/eggpipe/main/docs/assets/brand/lockup/eggpipe-wordmark-light.png" alt="Eggpipe" width="420">
+  </picture>
+</p>
+
+> Инструмент для генерации артефактов (SQL, Python, TypeScript, etc.) из YAML-описания модели данных.
+
+> **Статус: beta (0.x).** Проект находится в стадии бета-тестирования. До версии 1.0
+> публичный API, CLI, формат `.eggpipe.yaml`, JSON-отчёт и генерируемые артефакты могут
+> меняться без сохранения обратной совместимости. Для production фиксируйте версию и
+> читайте `CHANGELOG.md`. Подробнее — [Статус и совместимость](https://github.com/SpiGit/eggpipe/blob/main/docs/user/status.md).
+
+## Концепция
+
+**Один источник истины → произвольные форматы вывода.**
+
+Описываете структуру данных один раз в YAML — получаете:
+- SQL-миграции и схемы
+- Python-модели (Pydantic, Django, SQLAlchemy, dataclasses)
+- TypeScript-типы и Zod-схемы
+- OpenAPI-спецификации
+- Go-структуры
+- И всё остальное через плагинную систему
+
+Ключевые свойства:
+
+- **Сущности изолированы**: базовая модель не знает о связях между ними — ядро остаётся нейтральным.
+- **Нет встроенных генераторов**: все генераторы и все форматы (кроме базового `entity-model`) — плагины.
+- **Модель — просто данные**: метаконфиг решает, что, из чего и куда генерировать.
+
+## Режимы использования
+
+### Как CLI
+
+```bash
+pip install eggpipe
+eggpipe generate model.yaml
+eggpipe watch model.yaml
+```
+
+### Как библиотека
+
+```python
+from eggpipe import Engine, AppConfig, ProjectConfigLoader
+
+rules = ProjectConfigLoader().load(".eggpipe.yaml")
+engine = Engine(AppConfig(), rules)
+
+report = engine.build()        # парсинг/валидация/генерация без записи
+report = engine.generate()     # build + запись артефактов
+report = engine.check()        # проверить актуальность без записи
+
+if not report.success:
+    for d in report.diagnostics:
+        print(d.code, d.message)
+```
+
+`Engine` не вызывает `sys.exit`, не настраивает root-logger и не пишет файлы в `build()` — это обычная библиотека. Детали — System Design §2.8.
+
+### Как библиотека + CLI (рекомендуемый сценарий)
+
+**Сценарий:** Проект N подключает eggpipe как библиотеку, пишет свои плагины генерации, запускает через CLI.
+
+1. Подключение как зависимость:
+   ```toml
+   # pyproject.toml проекта N
+   [project]
+   dependencies = ["eggpipe"]
+   ```
+
+2. Плагин генерации:
+   ```python
+   # my_project/plugins.py
+   from eggpipe import Artifact, GeneratorConfig, GenerationContext, ModelSlice, generator
+
+   @generator(id="my-project-generator", input_formats={"entity-model"})
+   def my_project_generator(
+       model: ModelSlice,
+       context: GenerationContext,
+       config: GeneratorConfig,
+   ) -> list[Artifact]:
+       # model — замкнутый срез модели (entities/enums/types)
+       # context — variables, naming_hint, formats, импортированные файлы
+       # config — блок этого генератора из .eggpipe.yaml
+       return [Artifact(path="user.py", content=render(model.entities))]
+   ```
+
+3. Регистрация через entry points:
+   ```toml
+   # pyproject.toml проекта N
+   [project.entry-points."eggpipe.generators"]
+   my-project-generator = "my_project.plugins:my_project_generator"
+   ```
+
+4. Запуск:
+   - CLI: `eggpipe generate` — обнаруживает плагины из entry points
+   - Library: `engine.generate()` — тот же результат
+
+**Примеры инструментов с такой архитектурой:** ruff, pytest, mypy.
+
+Плагин также может регистрировать **формат документа** (например `sql-model` с SQL-спецификой и собственными правилами) — группа entry points `eggpipe.formats`.
+
+## Быстрый старт
+
+```bash
+pip install eggpipe
+
+# Для watch-режима
+pip install "eggpipe[watch]"
+
+# Для Jinja2-helper в плагинах
+pip install "eggpipe[jinja]"
+
+# Инициализация конфигурации
+eggpipe init
+
+# Генерация
+eggpipe generate model.yaml
+eggpipe generate --plan            # посмотреть план без записи
+eggpipe generate --check           # проверить актуальность (CI)
+
+# Режим watch
+eggpipe watch model.yaml
+
+# Разработка своего плагина — editable install
+pip install -e ./plugins/my-generator
+eggpipe gen list
+
+# JSON Schema
+eggpipe model schema
+eggpipe config schema
+
+# Очистка owned-артефактов
+eggpipe clean --dry-run
+eggpipe clean --yes
+
+# Локальный плагин без установки
+eggpipe generate --plugin ./my_plugin.py
+```
+
+## Разработка
+
+```bash
+uv sync --extra dev
+
+uv run ruff check .
+uv run ruff format --check src tests tools examples
+uv run pyrefly check
+uv run pytest --cov
+uv run python tools/check_docs.py --strict
+uv build
+uv run python tools/check_wheel.py dist
+```
+
+Dev/CI используют [uv](https://docs.astral.sh/uv/) и закоммиченный `uv.lock`.
+Для установки пакета пользователями остаётся `pip install eggpipe`.
+
+Типизация — [Pyrefly](https://pyrefly.org/) в strict-режиме (встроенная поддержка Pydantic v2).
+mypy не входит в блокирующий CI; решение зафиксировано в
+[ADR-0002](./engineering/adr/0002-type-checker-pyrefly.md).
+
+Для basedpyright/Pyright в корне лежит `pyrightconfig.json` (src-layout, `extraPaths`, `.venv`).
+Перед проверкой выполните `uv sync --extra dev`.
+
+## Документация
+
+Проверка согласованности документации:
+
+```bash
+uv run python tools/check_docs.py --strict
+```
+
+- [Документация](./docs/index.md) — пользователям и AI-агентам
+- [Инженерная документация](./engineering/index.md) — ТЗ, ADR, System Design, ревью
+- [Быстрый старт](./docs/user/quickstart.md)
+- [Плагины](./docs/user/plugins.md)
+- [Техническое задание](./engineering/requirements/index.md) — актуальная версия v2.2
+- [System Design](./engineering/system-design/index.md)
+- [ADR index](./engineering/adr/index.md)
+- [ADR-0001: семантика композиции](./engineering/adr/0001-composition-merge-semantics.md)
+- [ADR-0002: type checker — Pyrefly](./engineering/adr/0002-type-checker-pyrefly.md)
+- [ADR-0003: null-семантика](./engineering/adr/0003-null-semantics.md)
+- [ADR-0004: ownership и cleanup](./engineering/adr/0004-ownership-manifest-cleanup.md)
+- [ADR-0005: library API](./engineering/adr/0005-library-api.md)
+- [ADR-0006: расширение формата](./engineering/adr/0006-format-extension.md)
+- [ADR-0007: наследование форматов](./engineering/adr/0007-format-inheritance.md)
+- [ADR-0008: model units и раскладки источников](./engineering/adr/0008-model-units-and-source-layouts.md)
+- [ADR-0009: глобальный manifest](./engineering/adr/0009-global-manifest-ownership.md)
+- [ADR-0010: decorator API генераторов](./engineering/adr/0010-decorator-generator-api.md)
+- [Ревью проекта (2026-11-10)](./engineering/reviews/2026-11-10-project-review.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Changelog](./CHANGELOG.md)
+- [Каталог диагностик](./docs/user/reference/diagnostics.md)
+- [Релиз](./engineering/release.md)
+- [TPC-H example](./examples/tpc-h/README.md)
+- [Reference generator](./examples/reference-generator/README.md)
+
+## Лицензия
+
+[MIT](./LICENSE).
+
+## Статус
+
+**Стадия:** Eggpipe 0.3.0, ТЗ v2.2. Реализованы E0–E8 и E9: пакет/CLI/config/state,
+форматы и слои, decorator API, глобальный manifest, CLI/JSON v2, CI и release workflow.