[CLI & Architecture] Consolidate target-specific boolean flags into unified options (--backend, --style, --feature)

[nth-bailey]

🎯 Motivation & Background

As PolyXML has expanded across 7 target languages (Rust, C++, Java, C#, Go, Python, TypeScript), polyxml-cli has started accumulating one-off, language-specific boolean flags:

• --zod (TypeScript only)
• --source-gen (C# only)
• --zero-copy (Rust only)
• --rkyv (Rust only)

Without a unified convention, upcoming features (--phf, --builder, --slots, --aot, --valibot, --typebox, --jackson) will balloon polyxml generate --help into 40+ disjoint flags, the majority of which are silently ignored or invalid when targeting another language.

---

🛠️ Proposed Solution

Consolidate all code generation flags into a clean, orthogonal, and predictable 3-tier taxonomy:

1. --backend <name> (Serialization / Runtime Library)

Controls the data-binding, serialization, or validation engine:

• TypeScript: interfaces (default), zod, valibot, typebox
• Python: dataclass (default), pydantic
• Java: standard (default), jackson
• C#: standard (default), source-gen
• C++: standard (default)

2. --style <name> (Type Representation & Mutability)

Controls the generated class/struct archetype across languages:

• Java: record (default, immutable), pojo (mutable JavaBean)
• C#: class (default), struct, record-class, record-struct
• Python: dataclass (default), class

3. --feature <name> (Repeatable Opt-In Enhancements)

Replaces disparate single-purpose booleans with a unified feature flag (similar to cargo --features):

# Enable multiple features cleanly:
polyxml generate schema.xsd --lang rust --feature zero-copy --feature rkyv --feature phf
polyxml generate schema.xsd --lang java --style pojo --feature builder --feature direct-codec
polyxml generate schema.xsd --lang python --feature slots

4. Manifest (polyxml.toml) Parity

Ensure polyxml.toml maps 1:1 with the new taxonomy:

[[generate]]
target = "java"
backend = "jackson"
style = "pojo"
features = ["builder", "direct-codec"]

[[generate]]
target = "rust"
features = ["zero-copy", "rkyv", "phf"]

---

Compatibility policy (decision in #58)

The unified options introduced by #56 replace the old one-off flags and manifest keys directly. The project has very few users, so no compatibility aliases, deprecation warnings, or migration guide are planned. The CLI rejects removed flags and unknown manifest keys. --zero-copy and manifest zero_copy remain first-class options because they can express false, which --feature zero-copy cannot. Target-specific validation still fails early with an actionable error.

---

🔬 Ergonomics & CLI Benchmarking

To ensure the CLI remains responsive and provides clear developer feedback:

1. Startup & Parsing Latency:
   • Measure polyxml --help and arg parsing time using hyperfine (target: $< 5\text{ ms}$ cold start).
2. Tab Completion Generation:
   • Verify that shell autocompletion (polyxml completions bash|zsh|fish) accurately filters --backend values based on selected --lang.
3. Usability Testing:
   • Verify that clear, colorized error diagnostics are produced for misspelled backends or incompatible flags.

---

✅ Acceptance Criteria

• Refactor GenerateArgs in crates/polyxml-cli to introduce --backend, --style, and --feature <name>.
• Apply the [CLI] Decide compatibility policy for unified options #58 compatibility decision: removed flags and manifest keys fail clearly; --zero-copy remains available as a first-class option.
• Implement target-specific argument validation in polyxml-cli preventing invalid flag combinations.
• Update WorkspaceManifest in polyxml.toml to support backend, style, and features = [...].
• Update documentation in docs/guides/compiler.md and README CLI examples.
• Add CLI integration tests verifying removed flag rejection and cross-language validation errors.
• Split the remaining generator and measurement proposals into focused follow-ups: [Python Codegen] Support plain class style with runtime XML/JSON binding #60, [C# Codegen] Support mutable struct style #61, and [CLI] Measure cold startup and verify interactive error diagnostics #62.

Resolution

The unified CLI taxonomy, validation, manifest parity, completions, and integration tests landed in PR #56. The direct-removal compatibility decision is recorded in #58; PR #59 corrected the documentation wording. This issue covers the CLI consolidation and is complete.

Future work is tracked separately:

• [Python Codegen] Support plain class style with runtime XML/JSON binding #60: Python plain-class generation and runtime binding.
• [C# Codegen] Support mutable struct style #61: C# mutable structs (distinct from supported record-struct and the mutable classes in [Codegen: Java & C#] Support traditional mutable classes/POJOs with getters, setters, and builders (--style pojo / --builder) #46).
• [CLI] Measure cold startup and verify interactive error diagnostics #62: genuinely cold startup measurement and interactive error colors.

The currently supported options remain documented in docs/guides/compiler.md; these future styles are rejected until their generators support them.

Startup target clarification: The <5 ms cold-start figure above was an aspirational proposal, not a release requirement. #62 measured about 1.5 ms warm and 7.6 ms after executable-page eviction on one WSL2 host, with no user-facing startup bug found. No fixed cold-start target is currently planned.

[nth-bailey]

The unified CLI option work landed in PR #56 and the compatibility policy was settled in #58 / PR #59. This issue now records that completed scope. The remaining proposals are tracked in #60 (Python plain classes), #61 (C# mutable structs), and #62 (cold startup and interactive diagnostics).