Перейти к содержимому
Размах

F-05 Manifest validator (3 дн plan → 1.5h actual)

Outcome

  • JSON Schema 2020-12 (packages/core/src/razmakh_core/manifest/schema.json) — 280 lines, всё AG manifest spec
  • Python loader + 2-stage validator (schema + semantic)
  • Cross-module validator (orphan events, missing dependencies, duplicate names, missing cross-section targets)
  • CLI razmakh module {validate,list} через Click entry point
  • Sample hello_world manifest как baseline для tests
  • 26/26 unit tests pass (включая real hello_world manifest integration test)
  • lefthook pre-commit hook manifest-validate для packages/modules/**/module.yaml
  • All ruff + mypy strict pass

Tracking (per estimates-recalibration-2026-05-17.md template)

Plan: 3 дня (24h) Actual: 2026-05-17 — ~1.5h (started ~17:15, completed ~18:45) Speedup: 16x (plan 24h → 1.5h) Speedup category: pure code task — нет real infra waiting → ближе к F-01 16x rate

What manifest spec covers (AG decision recall)

Каждый module имеет module.yaml декларирующий:

  • Core: name, version (SemVer), title, description, label_key, release_stage (P21 lifecycle), compatible_core_version
  • Navigation: route, sidebar (label/icon/section/order)
  • Security: permissions (id, label_key, level, scope)
  • Data: data_sources (entity + access), tables (rls + partition)
  • Events: events_emitted (id + schema_ref + version), events_consumed (id + from_module + handler)
  • Cross-module: dependencies (module + version + optional), cross_section_links (target_module + context_key), accepts_context
  • Runtime: feature_flags (P22), runtime_config_keys (admin-editable), cron (schedule + handler + timezone)
  • LLM: agents (id + scope + model_tier — references netnik-state/agents/)
  • Customization: partner_overrides (enabled + allowed_keys)

Validation layers (3)

1. JSON Schema (Draft 2020-12)

  • Type/required/pattern/enum checks
  • additionalProperties=false — нет unknown fields
  • uniqueItems на permissions / events
  • Patterns: SemVer, snake_case names, dot-notation IDs

2. Semantic (within-module)

  • SemVer parse (semver lib)
  • Range syntax sanity (compatible_core_version)
  • Cron expressions valid (croniter parse)
  • No self-dependencies
  • No self-consume events (smell warning)
  • hidden + sidebar inconsistency

3. Collection (cross-module)

  • Required dependencies exist in collection
  • cross_section_links.target_module exists
  • events_consumed.from_module exists и emit’ит этот event
  • No duplicate names

CLI usage

Окно терминала
razmakh module validate hello_world           # single
razmakh module validate packages/modules/hello_world/module.yaml  # by path
razmakh module validate --all                  # all in packages/modules/
razmakh module list                            # summary table

Exit codes: 0 (OK) / 1 (validation errors) / 2 (CLI usage error).

What this enables

  • F-06 ETL Collector може ссылаться на module.yaml.data_sources чтобы знать какие entities писать
  • F-08 FastAPI startup читает manifests → builds route registry / OpenAPI / permissions
  • F-09 CI gate включает razmakh module validate --all (всегда green)
  • F-12 Admin panel читает runtime_config_keys для render config UI
  • Section completion checklist (BF 84-item) первая проверка — razmakh module validate <new_section>
  • P21 stage transitions controlled через manifest (hidden → internal → preview → published)
  • P15 partner_overrides блок enforces security — allowed_keys не может содержать permissions / RLS related

Decision (recorded ad-hoc, не отдельный decision record)

Custom validator vs jsonschema-based library: chose custom 2-stage (schema + semantic + collection). jsonschema library handles 80% (schema), нам нужны cross-module rules — write our own.

CLI framework: chose Click vs Typer / Argparse — Click stable, ecosystem mature, group/command pattern simple, type annotations work via decorators.

Sample module location: packages/modules/hello_world/ — symmetric с future real modules. NOT под tests/ чтобы tests могли load его как реальный пример.

Deferred to later

  • Cross-tenant probe тест (schema change в generator output → leak detector) — F-08 generator setup нужен, Block 1.5.5 Phase 1.5
  • CLI command razmakh module create <name> — scaffold generator (template engine) — Phase 1 F-XX когда нужны first 2-3 sections
  • CLI command razmakh module remove <name> — auto archive + DDL rollback + audit (P23) — Phase 1.5+ когда manifest registry уже online
  • Manifest schema versioning (apiVersion: razmakh.ru/v1 style) — Phase 2 когда будут breaking changes
  • Schema-driven UI generators (DataTable из tables[]) — Phase 1+ когда apps/web start
  • Runtime registry (FastAPI startup loads manifests → builds dispatchers) — F-08

Numbers

  • Lines of code: ~850 (schema 280 + loader 65 + validator 195 + CLI 165 + tests 245 + hello_world manifest 65)
  • Unit tests: 26/26 pass
  • Validator coverage: 3 layers × multiple checks per layer
  • CLI commands: 2 (validate, list) + extensible structure для create / remove
  • mypy/ruff: clean (with 3 needed type: ignore для untyped libs)
  • 0 production blockers — F-06 может стартовать сейчас