feat: Add a template-optimizer pipeline for REST-connector templates

[Claude]

Adds an element-template-optimizer module that compacts conditional properties in generated Camunda element templates. REST-based templates frequently emit dozens of near-identical conditional properties per multi-operation API; collapsing them is a ~45% property-count reduction on real specs without any change in applied behaviour.

Closes #7357.

What the optimizer does

Four passes run in sequence, each taking an ElementTemplate and returning a new one:

• merge-by-identity — groups properties by (binding, value, presentation) and collapses each group whose members differ only in their condition's discriminator value into one property with a oneOf condition over the union.
• totalize — drops conditions that cover every value of their discriminator (currently scoped to Dropdown discriminators).
• strength-reduce — rewrites singleton oneOf as equals.
• reorder — emits properties in a stable canonical order (group → visibility → id) so regenerations produce review-friendly diffs.

How it's integrated

congen-cli's generate command runs the default pipeline before serializing each template, so generated templates always ship in their compacted form.

A standalone element-template-optimizer binary is also provided for one-shot cleanup of hand-maintained templates that bypass the generator (with --skip-passes, --dry-run, and a list-passes subcommand).

Branch layout

Three commits:

1. Add element-template-optimizer module — the four passes, the Optimizer library entrypoint, the PropertyUtils rebuilder, polymorphism-aware deserializers for the sealed Property / PropertyBinding / PropertyCondition hierarchies, and the test suite.
2. Add element-template-optimizer standalone CLI — Main + OptimizerCommand.
3. Wire element-template-optimizer into congen-cli generate command — runs the default pipeline unconditionally before serialization, with try/catch and a dedicated OPTIMIZATION_FAILED return code.

Behavioural equivalence

The core DSL is sealed without Jackson polymorphism annotations, so this module ships strict deserializers for Property, PropertyBinding, and PropertyCondition. They fail loud on missing or conflicting discriminators, non-string equals values, empty binding identifiers, unknown feel modes, and unknown generatedValue.type.

OptimizerPropertyTest enumerates 36 multi-operation template shapes (operations × shared params × unshared params × unconditional) and asserts XMLUnit-level BPMN equivalence per discriminator value by applying both the original and optimized templates via the npm-published @camunda/element-templates-cli. The test is gated by @EnabledIf; when CI=true or OPTIMIZER_REQUIRE_CLI=true is set and the CLI binary is missing, the gate is a hard failure rather than a silent skip.

Out of scope / follow-ups

• TotalizePass currently considers only Dropdown properties as discriminators; a constant-valued hidden property would also be a tautological discriminator. Documented in the module README; can be widened in a follow-up.
• A golden-file regression test on the existing OpenAPI / Postman generators would catch surprising behaviour changes on real templates beyond the parameterized equivalence suite.

[vringar]

@claude[agent] Left comments focussed on the overall structure. Don't assume the rest is good but focus on getting the architecture right first. Also how do we integrate this with the congen CLI. Note the PR you are likely to be blocked by.

[vringar]

#7354 is required for the CLI to be runable again. I'd like this pipeline to be a postprocessing step before the file gets written out to disk, so that for generated templates we only expose the compacted form. In this context none of the disable flags are relevant.

[Copilot]

Pull request overview

Adds a new element-template-optimizer Maven module under element-template-generator/ that compacts conditional properties in generated Camunda element templates via four sequential passes (merge-by-identity, totalize, strength-reduce, reorder) operating on the typed ElementTemplate IR. The optimizer is exposed both as a library entrypoint (Optimizer.defaultPipeline()), as a standalone CLI binary (element-template-optimizer), and is wired unconditionally into congen-cli's generate command before serialization. Strict polymorphic Jackson deserializers for the sealed Property / PropertyBinding / PropertyCondition hierarchies are added because the core DSL ships serializers only.

Changes:

• New element-template-optimizer module: four passes, Optimizer entrypoint, PropertyUtils builder-based rebuilder, strict polymorphic deserializers, and a standalone CLI (OptimizerCommand + ListPassesCommand).
• congen-cli generate runs Optimizer.defaultPipeline() after generation and before JSON-schema validation, with a new OPTIMIZATION_FAILED(4) return code.
• Test coverage: per-pass unit tests, deserializer round-trip and rejection tests, optimizer-level pipeline tests, and a CI-gated end-to-end BPMN-equivalence suite using the npm @camunda/element-templates-cli.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
element-template-generator/pom.xml	Register new optimizer submodule.
element-template-generator/optimizer/pom.xml	New module POM: Java 21, picocli + appassembler, slf4j-nop, xmlunit (test).
element-template-generator/optimizer/README.md	Documents passes, reorder side effects, CLI usage, and equivalence-test gating.
optimizer/core/Pass.java	Pass interface: id, apply, description.
optimizer/core/Optimizer.java	Library entrypoint with default pipeline and defaultPipelineExcept that hard-fails on unknown ids.
optimizer/core/PropertyUtils.java	Builder-based copy helpers (withId, withCondition, withValue, withoutCondition) with exhaustive sealed switch.
optimizer/core/TemplateLoader.java	ObjectMapper that registers ElementTemplateModule + strict deserializers, plus load/save/toString helpers.
optimizer/core/PropertyDeserializer.java	Discriminates on type, dispatches to concrete DSL builders, validates feel/optional/generatedValue/choices.
optimizer/core/PropertyConditionDeserializer.java	Requires exactly one of equals/oneOf/isActive/allMatch; validates value types.
optimizer/core/PropertyBindingDeserializer.java	Dispatches on binding type; rejects missing/empty identifier fields.
optimizer/pass/MergeByIdentityPass.java	Groups by binding+value+presentation; merges equals/oneOf on same discriminator; refuses non-string equals; chooses neutral id via longest common suffix with collision disambiguation.
optimizer/pass/TotalizePass.java	Drops a top-level equals/oneOf condition when its values cover every choice of its Dropdown discriminator.
optimizer/pass/StrengthReducePass.java	Rewrites singleton oneOf as equals.
optimizer/pass/ReorderPass.java	Sorts properties by group, then Hidden-first, then id.
optimizer/Main.java	picocli bootstrap.
optimizer/command/OptimizerCommand.java	CLI: positional input, -o, --dry-run, --skip-passes; distinct exit codes 1/2/3/4; list-passes subcommand.
optimizer/test/.../TestTemplates.java	Test DSL helper factories for templates/properties/conditions/bindings.
optimizer/test/.../MergeByIdentityPassTest.java	Coverage incl. collision and non-string-equals refusal.
optimizer/test/.../TotalizePassTest.java	Coverage for full-coverage drop, partial keep, equals, unknown discriminator.
optimizer/test/.../StrengthReducePassTest.java	Singleton vs. multi vs. no condition.
optimizer/test/.../ReorderPassTest.java	Group→visibility→id ordering.
optimizer/test/.../core/OptimizerTest.java	Default pipeline collapse, skip behavior, unknown-id rejection.
optimizer/test/.../core/TemplateLoaderTest.java	Round-trip + strict rejection of malformed JSON.
optimizer/test/.../OptimizerPropertyTest.java	CI-gated end-to-end equivalence via element-templates-cli over 36 parametric template shapes.
congen-cli/pom.xml	Add element-template-optimizer dependency.
congen-cli/.../command/Generate.java	Run Optimizer.defaultPipeline() after generation; map failures to OPTIMIZATION_FAILED.
congen-cli/.../ReturnCodes.java	New OPTIMIZATION_FAILED(4).

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[ztefanie]

Hi @vringar

Thanks for your contribution.

Some comments:

• We want to have this optimizer as a separate module and do not want to apply it to the OOTB connectors for now
• The optimizer is changing the ids of properties. Can you verify if this breaks migration to higher version of the element templates? In the team call we were assumed the bindings are used for this, but it would be good if you can verify changing ids is safe.
• Can you please revert the reordering as this breaks conditions. Properties need to be declared before they can be used.

[ztefanie]

@vringar have you seen my comments above?

Comment 1: "Separate module, don't apply to OOTB connectors"

Half-addressed. The optimizer was correctly extracted into its own Maven module (element-template-generator/optimizer/). But the second half — "do not apply it to OOTB connectors" — was not addressed.
Generate.java:97-101 unconditionally runs Optimizer.defaultPipeline() on every congen generate invocation, which is exactly what generates OOTB connector templates. The README even says explicitly: "There is no
flag — compaction is the default." This directly contradicts the reviewer's instruction.

---

Comment 2: "Verify changing property IDs doesn't break template migration"

Not addressed at all. There is no mention of migration anywhere in the optimizer module — not in the README, not in tests, not in comments. The reviewer's specific concern (changing merged property IDs and whether
that's safe for version migration) has no response. Given the docs/connector-template-versioning.md file exists in the repo, there's clearly an established versioning story — but this PR makes no reference to it.

Some more comments:

1. Wrong package namespace — All new source files use io.camunda.connector.optimizer.* instead of io.camunda.connector.generator.optimizer.. Every other module in element-template-generator/ lives under
   io.camunda.connector.generator.. This is a structural inconsistency across the entire module (AGENTS.md §1).
2. xmlunit-core:2.11.0 version hardcoded in optimizer/pom.xml — Not present in any parent BOM. Per AGENTS.md §6, external dependency versions must be governed by in the parent POM.
3. picocli / picocli-codegen version re-declared in the module — optimizer/pom.xml pins 4.7.7 locally instead of lifting it to the parent element-template-generator BOM. If congen-cli also uses picocli, the two
   will drift (AGENTS.md §6).
4. ExitCode as a private inner enum — congen-cli uses a top-level ReturnCodes class. The optimizer buries its equivalent as a package-private inner type, making exit codes invisible to callers without opening the
   source.
5. ListPassesCommand.call() returns bare 0 — Inconsistent with every other return site in the same file; should return ExitCode.SUCCESS.code.