Story: Codegen developer experience improvements
Table of Contents
This page documents a story in Sprint 21. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Fix three interrelated friction points in the codegen.sh regenerate workflow
that were observed repeatedly during sprint 21 currency auxiliary work. All
three make targeted codegen runs unnecessarily noisy, error-prone, and hard to
scope to a logical entity group:
- Spurious ERRORs in
--componentmode. When a profile is run against a component that contains entity types the profile does not support (e.g.qtagainstrefdata-cpp, which containstableandjunctionmodels alongsidedomain_entitymodels), the generator emits one ERROR per incompatible entity and inflates the final error count. These are expected skips, not failures. - No entity-level filter.
--component refdata-cpp --profile qtgenerates Qt files for all 25+ entities in the component. There is no way to restrict generation to a named subset (e.g.rounding_type,monetary_nature, currency_market_tier). Every targeted run generates 20+ extra files for out-of-scope entities that the caller must manually discard. - No logical entity group / scope concept. A task such as "sync Qt codegen for
currency auxiliaries" involves a well-defined set of entities that share a
domain boundary (the currency domain). There is currently no concept of an
entity group or tag in the model that the codegen CLI could use to select
--scope currencyand regenerate only the relevant entities across any profile without listing them by name. This also means it is impossible to run the codegen targeting "only currency entities" in a single command — you either regenerate the whole component (too wide) or enumerate entity names manually (fragile, must be updated when the domain grows).
Together these three gaps mean every focused codegen iteration in a task produces output the developer must manually inspect, filter, and clean up. The goal of this story is to eliminate that friction so that a targeted codegen run produces exactly what was requested — no more, no less — with a clean exit code.
Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent sprint | Sprint 21 |
| Now | Not yet started. |
| Waiting on | Nothing; no blockers. |
| Next | Break into tasks; prioritise error downgrade first (cheapest). |
| Last touched | 2026-06-25 |
Background
The three issues were surfaced during three separate codegen sessions in the
commission_currency sprint:
task_sync_cpp_messaging_codegen_currency_auxiliaries— first observation of the component-wide over-generation and untracked-file cleanup burden.task_sync_qt_codegen_currency_auxiliaries— second observation of over-generation (Qt profile); also first observation of the 13 spurious ERROR lines fromqtprofile againstrefdata-cpp(5 table + 8 junction models).- Both tasks — the impossibility of expressing "regenerate only currency entities" in a single command without listing all three entity names explicitly.
The --entity filter shortcoming was previously captured in
codegen –component run generates all entities not just the target. The
profile/type ERROR downgrade was captured in
Downgrade profile/model-type incompatibility from error to skip in –component mode.
This story groups both with the related entity-group feature into one
deliverable.
Acceptance
- Running
codegen.sh regenerate --component refdata-cpp --profile qtproduces zero ERROR or WARNING lines for models whose type (table,junction) is not supported by theqtprofile. Those models are silently skipped. Only genuine generation failures produce ERROR output. - A
--entity(or--entities) flag is accepted bycodegen.sh regenerate. Running--component refdata-cpp --profile qt --entity rounding_type,monetary_nature,currency_market_tiergenerates only files for those three entities and writes no other files to disk. - The
ores.refdatamodel supports an entity group or tag annotation (e.g.:group: currencyor a#+group:property in the entity org file). Runningcodegen.sh regenerate --component refdata-cpp --profile qt --group currencyregenerates all and only the entities taggedcurrency, with no manual enumeration required. The currency group initially covers:currency,rounding_type,monetary_nature,currency_market_tier. - All existing codegen runs (
--component,--profile, without new flags) are unaffected and produce identical output to today. codegen.sh --helpand the profile documentation list the new flags and the group annotation syntax.- CI passes; no production source files are changed by this story.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Downgrade profile/model-type incompatibility to skip in –component mode | BACKLOG | In generator.py, detect model-type/profile incompatibility in –component mode and skip silently (DEBUG log) rather than emitting ERROR and incrementing the error counter. Keep ERROR for explicit single-entity invocations. | ||
| Task: Add –entity filter flag to codegen.sh regenerate | BACKLOG | Implement an –entity (or –entities) flag that restricts a –component run to the named entities only. No other entity files are generated or written to disk. | ||
| Task: Add entity group / tag system to model and codegen CLI | BACKLOG | Design and implement a group annotation (e.g. :group: in entity org files or a groups section in the component manifest). Expose –group flag on codegen.sh regenerate. Define the initial currency group in ores.refdata. |
Decisions
- Error vs. skip boundary. Incompatible-type encounters are an error only when
the caller explicitly names an entity (
--entity rounding_type --profile qton atablemodel). In--componentmode the codegen discovers entities automatically and must handle heterogeneous types gracefully. - Group granularity. The group concept should live in the entity model (org file property or a manifest section), not in the codegen CLI, so that it is co-located with the model and does not require CLI changes when the group membership changes.
- –entity vs. –group. Both flags are needed.
--entityis for ad-hoc one-off targeting without modifying the model.--groupis for repeatable domain-scoped regeneration that reflects how the business thinks about entity ownership.
Out of scope
- Changing which profiles support which model types (that is a profile design question, not a DX question).
- Per-entity profile overrides (specifying a different profile for individual entities within a component run).
- Automatic discovery of which entities in a component have drifted (that belongs
to the
refactor_codegen_cppstory).