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 mustache templates consumed by generator.py are organised as the ores physical-space graph: a root node fanning out to technical spaces, each 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.
Technical-space doc	`ores.<space>.org`	Namespace: indexes the space's facets.
Facet doc	`ores.<space>.<facet>.org`	Literate source: prose + Archetypes table (per-template `mustache` blocks pending migration for some facets).
Archetype/Template	`<name>.mustache`	Tangled artefact consumed by `generator.py`.

The technical spaces:

Technical space	Facets	Scope
ores.cmake	2	Component `CMakeLists.txt` files across the api/core/service split.
ores.cpp	13	Domain types, repositories, mappers, Qt UI classes, services, components, enums.
ores.sql	3	Schema create/drop, notify triggers, junctions, reference-data populates.
ores.doc	4	Org-mode document scaffolds behind `compass add` (including the facet/facet_group/technical_space/archetype types).
ores.plantuml	1	Entity-relationship diagram generation from the bi-temporal SQL schema.
ores.shell	1	Service-registry shell scripts.

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; add a row for the new archetype to its facet's * Archetypes table (ores.<space>.<facet>.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.)