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:

  1. Spurious ERRORs in --component mode. When a profile is run against a component that contains entity types the profile does not support (e.g. qt against refdata-cpp, which contains table and junction models alongside domain_entity models), the generator emits one ERROR per incompatible entity and inflates the final error count. These are expected skips, not failures.
  2. No entity-level filter. --component refdata-cpp --profile qt generates 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.
  3. 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 currency and 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 from qt profile against refdata-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 qt produces zero ERROR or WARNING lines for models whose type (table, junction) is not supported by the qt profile. Those models are silently skipped. Only genuine generation failures produce ERROR output.
  • A --entity (or --entities) flag is accepted by codegen.sh regenerate. Running --component refdata-cpp --profile qt --entity rounding_type,monetary_nature,currency_market_tier generates only files for those three entities and writes no other files to disk.
  • The ores.refdata model supports an entity group or tag annotation (e.g. :group: currency or a #+group: property in the entity org file). Running codegen.sh regenerate --component refdata-cpp --profile qt --group currency regenerates all and only the entities tagged currency, 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 --help and 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 qt on a table model). In --component mode 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. --entity is for ad-hoc one-off targeting without modifying the model. --group is 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_cpp story).

Emacs 29.1 (Org mode 9.6.6)