[build] add support for Mozilla's Commands fragment in the BiDi schema

[titusfortner]

🔗 Related Issues

Builds on #18060, adding the Commands.cddl fragment Mozilla included in the latest revision of D327393

💥 What does this PR do?

• Adds Firefox's webExtension.moz:listExtensions command to the BiDi schema's vendor section and to Ruby as web_extension.moz.list_extensions

🔧 Implementation Notes

• Commands.cddl is copied verbatim
• A vendor command inside a spec module is generated on that module's Moz variant with its namespace dropped, and only the vendor types it returns are emitted beside it.
• Generation now fails on a vendor command that would override a spec command, or on a vendor event in a spec module, since neither has routing yet.
• The shared schema sections are byte-identical; only the vendor section grows.
• Ruby now renames a field called extensions only on extensible records, the only ones that store undeclared fields under that name, so the result reads as result.extensions.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code (Fable 5.1, Opus 5.5)
  • What was generated: the analysis of why Commands.cddl failed, the generator changes, the test, and this description
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• Consider adding a method to Firefox driver implementations in each binding to list extensions

🔄 Types of changes

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

[qodo-code-review]

PR Summary by Qodo

Generate Mozilla extension-listing command in BiDi Ruby bindings

✨ Enhancement 🧪 Tests ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Adds Mozilla’s extension-listing CDDL command and projected BiDi vendor schema types.
• Generates Firefox-scoped Ruby commands, result records, and RBS signatures.
• Guards vendor routing and verifies command isolation, deserialization, and field naming.

Diagram

graph TD
  A["Commands CDDL"] -->|"parse vendor command"| B["JS projector"] -->|"emit vendor section"| C["BiDi schema"] -->|"consume schema"| D["Ruby generator"] -->|"generate command types"| E["WebExtension Moz"]
  D -->|"generate signatures"| F["Ruby RBS"]
  G["Unit specs"] -->|"verify behavior"| E

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Maintain the Ruby command manually

• ➕ Requires fewer generator changes for this single command.
• ➕ Keeps vendor-specific behavior localized to the Ruby binding.
• ➖ Generated bindings could drift from the canonical CDDL and schema.
• ➖ Future vendor commands would require repeated manual implementations.
• ➖ Ruby and RBS outputs could become inconsistent.

2. Expose a prefixed method on the shared domain

• ➕ Avoids vendor subclass routing and type-reachability changes.
• ➕ Provides a direct moz_list_extensions method.
• ➖ Exposes Firefox-only functionality to non-Firefox sessions.
• ➖ Conflicts with the existing vendor-variant design.
• ➖ Increases the risk of naming collisions with future specification commands.

Recommendation: Keep the PR’s generator-first vendor-variant approach. It preserves CDDL as the source of truth, prevents Firefox APIs from leaking into shared domains, and scales to additional vendor commands; manual or shared-domain alternatives are simpler initially but create drift and API-isolation risks.

Files changed (12) +430 / -48

Enhancement (6) +395 / -32

Commands.cddlAdd Mozilla WebExtension command definitions +30/-0

Add Mozilla WebExtension command definitions

• Adds Mozilla’s 'webExtension.moz:listExtensions' command and its extension and policy result records as a verbatim vendor CDDL fragment.

common/bidi/Commands.cddl

schema.jsonProject extension-listing command into the vendor schema +185/-0

Project extension-listing command into the vendor schema

• Adds the Mozilla command, command envelope, result record, extension metadata, and policy metadata to the generated vendor schema section.

common/bidi/schema.json

generate_bidi.mjsParse single-member CDDL command aggregates +3/-2

Parse single-member CDDL command aggregates

• Extends union-member collection to recognize one-member variable definitions represented by 'PropertyType', allowing 'MozCommand' to reference a single command.

javascript/selenium-webdriver/generate_bidi.mjs

web_extension.rbGenerate Firefox extension-listing Ruby bindings +37/-1

Generate Firefox extension-listing Ruby bindings

• Adds typed result, extension, and policy records. Exposes 'list_extensions' only through the 'WebExtension::Moz' vendor variant.

rb/lib/selenium/webdriver/bidi/protocol/web_extension.rb

bidi_generate.rbGenerate vendor commands within specification domains +112/-29

Generate vendor commands within specification domains

• Routes vendor-added commands into domain-specific vendor subclasses, emits only their reachable vendor types, and rejects unsupported events or command overrides. It also reserves 'extensions' only for extensible records and centralizes command rendering.

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb

web_extension.rbsAdd typed signatures for Mozilla extension listing +28/-0

Add typed signatures for Mozilla extension listing

• Declares RBS record types for extension-listing results and adds the 'WebExtension::Moz#list_extensions' signature.

rb/sig/lib/selenium/webdriver/bidi/protocol/web_extension.rbs

Refactor (1) +1 / -14

module.rb.erbReuse command rendering in the module template +1/-14

Reuse command rendering in the module template

• Delegates command method generation to the shared 'render_lines' implementation so standard and vendor-added commands render consistently.

rb/lib/selenium/webdriver/bidi/support/templates/module.rb.erb

Tests (2) +26 / -0

protocol_spec.rbTest Firefox-scoped extension listing +16/-0

Test Firefox-scoped extension listing

• Verifies the Mozilla command wire call, typed nested result deserialization, and absence of the command on the shared WebExtension domain.

rb/spec/unit/selenium/webdriver/bidi/protocol_spec.rb

bidi_generate_spec.rbTest context-sensitive extensions field naming +10/-0

Test context-sensitive extensions field naming

• Confirms that 'extensions' is renamed for extensible records but remains unchanged for closed records.

rb/spec/unit/selenium/webdriver/bidi/support/bidi_generate_spec.rb

Documentation (1) +1 / -1

browsing_context.rbClarify generated Mozilla variant documentation +1/-1

Clarify generated Mozilla variant documentation

• Updates the generated class comment to describe vendor variants as containing both browser-specific commands and parameters.

rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb

Other (2) +7 / -1

webref_cddl.bzlRegister Mozilla Commands.cddl as a vendor source +1/-0

Register Mozilla Commands.cddl as a vendor source

• Includes the new command fragment in the Mozilla vendor CDDL inputs used by schema generation.

common/webref_cddl.bzl

update_cddl.pyTrack Commands.cddl in schema update inputs +6/-1

Track Commands.cddl in schema update inputs

• Adds the Mozilla command fragment to the source list maintained by the CDDL update script.

scripts/update_cddl.py

[qodo-code-review]

Code Review by Qodo

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

1. Generator safety checks can regress 📘 Rule violation ☼ Reliability

Description

vendor_events and build_added_command introduce exception branches for unsupported spec-domain
events and method-name collisions, but no unit test exercises either branch. A later routing or
naming change can disable these rejections while the existing field-name and happy-path protocol
tests continue to pass.

Code

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[R594-595]

+      stray = events.reject { |e| vendor_domain?(e['domain']) }
+      raise "vendor event #{stray.first['method']} in spec domain #{stray.first['domain']} is unsupported" if stray.any?

Evidence

Compliance rule 5 requires applicable regression coverage for changed behavior. The generator adds
two explicit rejection paths, while the added generator tests cover only safe_field_name and the
protocol test covers only successful command execution; repository searches find no assertions for
either new error.

AGENTS.md: Use Small, Reliable Tests and Avoid Contract-Misrepresenting Mocks
rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[590-605]
rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[697-706]
rb/spec/unit/selenium/webdriver/bidi/support/bidi_generate_spec.rb[34-42]
rb/spec/unit/selenium/webdriver/bidi/protocol_spec.rb[135-149]

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 generator now rejects vendor events in spec domains and vendor commands that would override spec commands, but neither failure path has regression coverage.

## Fix Focus Areas
- rb/spec/unit/selenium/webdriver/bidi/support/bidi_generate_spec.rb[34-42]
- rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[590-605]
- rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[697-706]

## Recommended Fix
Add small generator unit tests using minimal schemas. Assert that a vendor event assigned to a spec domain raises the documented unsupported-event error, and that a vendor-added command whose normalized Ruby name collides with a spec command raises the override error.

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

---

Context sources

Review mode: 🧠 Deep: This changes schema parsing and multi-language code generation across several independent paths, with substantial routing, type ownership, serialization, and generated-binding logic that could harbor multiple subtle defects.

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗