Codegen template library

Summary
The hierarchy
Tangling and the drift check
Adding a new template
Status
See also

This page is the top of the literate template hierarchy — the "groups overview" level of template ← facet doc ← group doc ← groups overview. It explains how the codegen template library is organised and maintained; the group docs index the facets, and the facet docs hold the template sources themselves.

Summary

The 116 mustache templates consumed by generator.py are organised into five template groups — cmake, cpp, sql, doc and assets — each corresponding to a technical space and containing one or more facets in the MASD sense: coherent families of artefacts projected from a model element. Every facet is a literate org document in this directory whose mustache blocks tangle to the sibling .mustache artefacts; the .mustache files are generated and carry a {{! GENERATED FILE }} header naming their source.

The hierarchy

Level	Document	Role
Groups overview	this page	How the library is organised and maintained.
Group doc	`<group>_group.org`	Namespace: indexes the group's facets, holds shared conventions.
Facet doc	`<facet>.org`	Literate source: prose + `mustache` blocks per template.
Template	`<name>.mustache`	Tangled artefact consumed by `generator.py`.

The groups:

Group	Templates	Scope
cmake	8	Component `CMakeLists.txt` files across the api/core/service split.
cpp	58	Domain types, repositories, mappers, Qt UI classes, services, components, enums.
sql	26	Schema create/drop, notify triggers, junctions, reference-data populates.
doc	20	Org-mode document scaffolds behind `compass add` (including the facet/facet_group types).
assets	4	Singleton families: Qt Designer `.ui` XML, PlantUML ER, shell service vars.

Tangling and the drift check

The org documents are the single source of truth. To regenerate the .mustache artefacts:

./compass.sh build --direct tangle_codegen_templates
# or via the equivalent CMake target in a full environment:
# cmake --build <build-dir> --target tangle_codegen_templates

The script tangles every .org file in this directory; docs without :tangle blocks (this page, the group docs) are no-ops. Drift is detected by running the tangle and checking the tree is clean:

git diff --exit-code -- projects/ores.codegen/library/templates

Adding a new template

Find (or create with compass add facet) the facet doc for the template's family; new groups are scaffolded with compass add facet_group.
Add a section: prose first (role, model inputs, output artefact, profiles), then the mustache block with an explicit :tangle <name>.mustache header and the {{! GENERATED FILE }} first line.
Run the tangle; wire the template into facet_catalogue.org.
Update the group doc's * Facets table if the facet is new.

Status

Fully literate: all 116 templates across the five groups are tangled from facet docs. (Historical note: early story documents counted "140" templates — that figure accidentally included pystache's test fixtures from an untracked venv.)