Specification compilation and pipeline

Specification compilation and pipeline

Input and validation

The package-owned Mettada command resolves a consumer manifest and spec roots. The backend pipeline loads YAML, validates it against JSON Schemas, and only then hands the parsed entities/workspaces to backend-core compilers. Keep schema errors actionable and ensure tests cover invalid as well as valid specs.

Compilation and metadata

EntitySpecCompiler compiles entity identity, fields, relationships, permissions, and lifecycle flags into platform metadata. WorkspaceSpecCompiler normalizes workspace pages and sections. Metadata pipeline stages enrich, derive, link, and validate cross-spec information.

Relationship changes fan out to entity metadata, graph resolution, migration and model generation, request validation, and read/write DTOs. When changing a compiler field, search each consumer of the corresponding metadata rather than stopping at the compiler unit test.

Orchestration

DSLPipeline owns the Laravel adapter’s generation workflow. It coordinates application roots and services, invokes framework-independent compilation/metadata work, selects generators and targets, writes artifacts, then performs feature-output cleanup. MettadaSyncCommand resolves the consumer manifest and invokes the pipeline.

Test compiler semantics in packages/backend-core/tests; test adapter and generator behavior in packages/backend-laravel/tests; verify full spec fixtures in consumer projects when the change crosses package boundaries.

Adding a metadata property

1. Extend the canonical JSON schema with type, constraints, and description.
2. Update the compiler/IR/metadata model and default behavior.
3. Update every downstream reader or generator.
4. Add positive and negative validation/compiler tests.
5. Update authoring templates, consumer examples, and generated references.
6. Run the relevant package suites and the AlterationManagerExample spec lint/sync check when generated output is affected.