[adr] Java CDDL generator proposal

[pujagani]

🔗 Related Issues

💥 What does this PR do?

Adds ADR recording the decision to generate Java WebDriver BiDi bindings from the CDDL spec.

🔧 Implementation Notes

The three cross-binding decisions recorded here : factory construction, subscription cancellation handles, and unified modules. These have user-visible consequences that needed to be settled before implementation begins. Python and JavaScript already generate from the same CDDL source. This record closes the loop on the Java binding's approach and captures the rejected alternatives (static utility pattern, raw listener IDs, split command/event classes) so they don't resurface in review.

Full generator design proposal: https://gist.github.com/pujagani/0a62197fd7c9b6d120e3a658fd7381d0

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude
  • What was generated: The spec and the ADR
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

The @beta annotation on all existing hand-written BiDi classes ships in the next release, giving users one release of warning before the cutover PR removes them.

🔄 Types of changes

• New feature (non-breaking change which adds functionality and tests!)

[qodo-code-review]

PR Summary by Qodo

Add ADR for generating Java WebDriver BiDi bindings from CDDL
📝 Documentation 🕐 10-20 Minutes

Description

• Document decision to generate Java BiDi bindings from shared CDDL-derived JSON artifacts.
• Standardize Java BiDi API shape: factory-created modules, unified domains, cancellable
 subscriptions.
• Record rejected alternatives and outline migration/breaking changes under @Beta.

Diagram

graph TD
  A["CDDL BiDi spec"] --> B["JS pipeline"] --> C[("bidi-ast.json / bidi-model.json")] --> D["Java generator"] --> E["Generated Java BiDi"]
  E --> F["Factory modules"] --> G["Unified domains"] --> H["Subscription handles"]

  subgraph Legend
    direction LR
    _db[(Artifact)] ~~~ _proc[Process] ~~~ _out[Output]
  end

Loading

High-Level Assessment

The PR’s approach is appropriate for an ADR: it clearly records the key cross-binding API-shape decisions (generation from CDDL-derived JSON, unified domain modules, factory construction, and cancellable subscription handles) and captures the main rejected alternatives to prevent re-litigating them during implementation.

Files changed (1) +204 / -0

Documentation (1) +204 / -0

17692-java-bidi-cddl-generator.mdAdd ADR proposing Java BiDi generation from CDDL-derived JSON model +204/-0

Add ADR proposing Java BiDi generation from CDDL-derived JSON model

• Introduces an architecture decision record to move Java WebDriver BiDi bindings from hand-written code to generated sources driven by CDDL-derived JSON artifacts. Defines API-shape standards (factory creation with HasBiDi checks, unified command/event domain modules, and AutoCloseable subscription cancellation handles) and documents migration consequences and rejected alternatives.

docs/decisions/17692-java-bidi-cddl-generator.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Instance ChroneDriver Error: ConnectFailure 🎫 2.48 doesn't trigger javascript in link's href on click()

✅ Compliance rules (platform): 11 rules

1. Unnumbered ADR title 🐞 Bug ⚙ Maintainability

Description

The new decision record’s top-level heading omits the decision number, diverging from the
repository’s ADR template convention and making cross-referencing inconsistent. This is a
documentation hygiene issue (not a functional/code defect).

Code

docs/decisions/17692-java-bidi-cddl-generator.md[1]

+# Java WebDriver BiDi CDDL generator proposal

Evidence

The ADR template explicitly shows decision records should have a numbered heading, while the newly
added ADR uses an unnumbered heading.

docs/decisions/0000-template.md[1-8]
docs/decisions/17692-java-bidi-cddl-generator.md[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR template in `docs/decisions/0000-template.md` indicates decision records should have a numbered H1 heading (`# NNNN. ...`). The new ADR’s H1 lacks the number, which reduces consistency when people cite decisions.

## Issue Context
- File is already numbered in its filename (`17692-java-bidi-cddl-generator.md`), but the H1 header does not include `17692.`.

## Fix Focus Areas
- docs/decisions/17692-java-bidi-cddl-generator.md[1-1]

### Suggested change
Update line 1 to something like:
- `# 17692. Java WebDriver BiDi CDDL generator proposal`

(Or whatever numbering convention you want to standardize on, but keep it consistent with the template.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---