[build] generate the BiDi schema vendor section from Mozilla's Firefox CDDL

[titusfortner]

🔗 Related Issues

Update to #17840
Support the expected shape of the Firefox vendor CDDL based on https://phabricator.services.mozilla.com/D327393

💥 What does this PR do?

• Replaces original expected implementation of w3c spec change and vendored cddl file format
• Includes all vendored definitions from Firefox
• Updates the Ruby generator to emit the vendor modules and their types

🔧 Implementation Notes

• Lists vendor grammars in the generated common/webref_cddl.bzl, so update_cddl.py can pin them from mozilla-central once D327393 lands with no downstream change.
• New convention does not include marking things extensible or additive, so schema generation needs to locate the definition that is being extended to extend it.
• webExtension.InstallParameters loses extensible: true, which only the Release 2.48.1 and 2.48.2 not reporting version and commit properly #1140 override had given it; Ruby keeps a vendor-extended record open so its Moz variants still work.
• Vendor modules reuse the spec's model extraction and Ruby's module template; they keep their wire domain (moz:debugging), and validation runs across the shared and vendor sections together.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code (Fable 5.1)
  • What was generated: the generator, normalizer, and projector changes, the Ruby vendor-module generation, their tests, and this description
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• Update the Python generator as part of [py] Install web extensions from the driver #17970 to consume the vendor definitions
• Update the Java generator in/after [java][bidi] Add BiDi code generator #17777, to consume the vendor definitions
• Consider a follow-up PR to separate the schema pipeline from the TypeScript (cddl2ts) path to simplify/remove the duplicate vendor AST and model targets

🔄 Types of changes

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

[qodo-code-review]

PR Summary by Qodo

Generate Firefox BiDi vendor schema and Ruby protocol modules

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

AI Description

• Vendors Firefox extension fields and debugging/profiler grammars from Mozilla CDDL.
• Projects namespaced vendor commands, events, types, and extensions into the generated BiDi schema.
• Generates typed Ruby Firefox modules while preserving browser-neutral shared protocol models.

Diagram

graph TD
  A["Mozilla CDDL"] --> B["Bazel Pipeline"] --> C["Vendor AST"] --> D["AST Normalizer"] --> E["Schema Projector"] --> F["BiDi Schema"] --> G["Ruby Generator"] --> H["Ruby Modules"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Separate vendor-only schema pipeline

• ➕ Avoids duplicating shared definitions in the vendor AST and model.
• ➕ Creates a clearer boundary between standard and browser-specific generation.
• ➖ Requires explicit cross-schema reference resolution.
• ➖ Broadens this PR beyond the immediate Firefox grammar integration.

2. Hand-maintain Firefox Ruby APIs

• ➕ Avoids extending the shared generator pipeline.
• ➕ Allows binding-specific API design independent of schema constraints.
• ➖ Duplicates Mozilla protocol definitions and increases drift risk.
• ➖ Loses automatic schema validation and regeneration across vendor updates.

Recommendation: Use the PR's provenance-based integration now because it reuses established parsing, normalization, validation, and Ruby templates while keeping shared schema output browser-neutral. A follow-up should consider a vendor-only projection stage to remove the duplicated base AST/model once all bindings consume the vendor schema consistently.

Files changed (27) +3367 / -169

Enhancement (17) +3013 / -146

Debugging.cddlAdd Firefox debugging vendor grammar +202/-0

Add Firefox debugging vendor grammar

• Adds Mozilla's moz:debugging commands, results, events, breakpoint structures, paused-state data, and shared protocol references.

common/bidi/Debugging.cddl

Fields.cddlAdd Firefox vendor extension fields +32/-0

Add Firefox vendor extension fields

• Defines Mozilla extension groups for browsing contexts, session capabilities, and web extension installation. It also adds the Firefox options helper record.

common/bidi/Fields.cddl

Profiler.cddlAdd Firefox profiler vendor grammar +56/-0

Add Firefox profiler vendor grammar

• Defines moz:profiler activity, start, and stop commands with their parameter and result types.

common/bidi/Profiler.cddl

schema.jsonRegenerate schema with Firefox vendor sections +1660/-17

Regenerate schema with Firefox vendor sections

• Adds Firefox extension fields, 12 vendor commands, two debugging events, and their supporting types under vendor.moz. The shared webExtension.InstallParameters record now reflects upstream shape without schema-level extensibility.

common/bidi/schema.json

generate_bidi.mjsTag vendor grammars and model entries +63/-44

Tag vendor grammars and model entries

• Accepts namespace-qualified vendor inputs, classifies extension groups versus vendor-owned definitions, and propagates vendor provenance into command and event models. Invalid extension targets fail generation.

javascript/selenium-webdriver/generate_bidi.mjs

normalize_bidi_ast.mjsNormalize vendor extension groups +56/-4

Normalize vendor extension groups

• Splices tagged <Type>Extension groups into matching shared records and preserves vendor provenance on synthesized definitions. Inline extension-field enums remain attached to their target fields.

javascript/selenium-webdriver/normalize_bidi_ast.mjs

project_bidi_schema.mjsProject complete namespaced vendor schema sections +132/-42

Project complete namespaced vendor schema sections

• Routes vendor extensions, commands, events, and types into vendor namespaces while preserving browser-neutral shared sections. Validation, completeness, directionality, and correlated-result analysis now include vendor content.

javascript/selenium-webdriver/project_bidi_schema.mjs

protocol.rbLoad generated Firefox protocol domains +2/-0

Load generated Firefox protocol domains

• Requires the generated MozDebugging and MozProfiler protocol modules from the Ruby BiDi entry point.

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

browsing_context.rbGenerate Firefox browsing-context extensions +21/-2

Generate Firefox browsing-context extensions

• Keeps Firefox-extended records open and adds a Moz subclass exposing the moz:scope getTree parameter.

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

moz_debugging.rbGenerate Ruby moz:debugging protocol API +334/-0

Generate Ruby moz:debugging protocol API

• Adds typed Ruby records, unions, events, and methods for Firefox script inspection, breakpoints, debugger control, stepping, and pause notifications.

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

moz_profiler.rbGenerate Ruby moz:profiler protocol API +108/-0

Generate Ruby moz:profiler protocol API

• Adds typed Ruby APIs for checking profiler activity, starting preset or custom profiles, and stopping profiles.

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

web_extension.rbRegenerate web-extension install parameters +8/-8

Regenerate web-extension install parameters

• Regenerates InstallParameters from the new upstream/vendor schema arrangement while retaining an extension bag for Firefox variants.

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

bidi_generate.rbGenerate Ruby modules from vendor schema content +54/-21

Generate Ruby modules from vendor schema content

• Folds vendor messages and types into domain generation, supports colon-delimited wire domains, and determines vendor-owned types. Shared records extended by vendors remain open for composed fields.

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

browsing_context.rbsAdd browsing-context vendor extension signatures +9/-2

Add browsing-context vendor extension signatures

• Adds extension bags to Firefox-extended records and types the Moz browsing-context variant and its scoped get_tree method.

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

moz_debugging.rbsGenerate moz:debugging RBS declarations +204/-0

Generate moz:debugging RBS declarations

• Defines signatures for Firefox debugging commands, events, records, unions, and referenced shared script values.

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

moz_profiler.rbsGenerate moz:profiler RBS declarations +66/-0

Generate moz:profiler RBS declarations

• Defines signatures for Firefox profiler commands, parameter variants, and result records.

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

web_extension.rbsRegenerate web-extension install signatures +6/-6

Regenerate web-extension install signatures

• Regenerates the extensible InstallParameters signature from the vendor-aware Ruby generation path.

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

Refactor (1) +1 / -1

module.rb.erbFormat generated presence selectors consistently +1/-1

Format generated presence selectors consistently

• Uses the generator's word-array helper when rendering union presence requirements, satisfying generated-code style rules.

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

Tests (4) +278 / -1

normalize_bidi_ast_test.mjsTest vendor AST normalization +96/-0

Test vendor AST normalization

• Covers extension-group splicing, duplicate target records, missing targets, provenance inheritance, input immutability, and inline vendor enums.

javascript/selenium-webdriver/normalize_bidi_ast_test.mjs

project_bidi_schema_test.mjsTest vendor schema projection and validation +170/-0

Test vendor schema projection and validation

• Verifies shared-schema isolation, extension routing, vendor modules, type directionality, cross-section references, correlated results, and completeness checks.

javascript/selenium-webdriver/project_bidi_schema_test.mjs

protocol_spec.rbTest generated Firefox profiler execution +11/-0

Test generated Firefox profiler execution

• Verifies that MozProfiler serializes the vendor command and deserializes its typed stop result.

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

serialization_spec.rbClarify vendor-extended record behavior +1/-1

Clarify vendor-extended record behavior

• Updates the serialization test rationale to reflect generator-managed vendor openness instead of the removed #1140 override.

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

Other (5) +75 / -21

webref_cddl.bzlRegister namespace-keyed vendor CDDL inputs +10/-0

Register namespace-keyed vendor CDDL inputs

• Introduces BIDI_VENDOR_CDDL_FILES and registers the copied Mozilla debugging, fields, and profiler grammars under the moz namespace.

common/webref_cddl.bzl

BUILD.bazelWire Firefox grammars into BiDi generation +7/-9

Wire Firefox grammars into BiDi generation

• Uses the centralized vendor CDDL map and removes the obsolete #1140 override and local web-extension overlay inputs.

javascript/selenium-webdriver/BUILD.bazel

generate_bidi.bzlBuild namespace-aware vendor AST and models +32/-12

Build namespace-aware vendor AST and models

• Changes vendor inputs to a namespace-keyed map and creates a vendor model from the overlaid AST. The projector receives both the shared and vendor models.

javascript/selenium-webdriver/private/generate_bidi.bzl

.rubocop.ymlPermit generated predicate-style protocol methods +4/-0

Permit generated predicate-style protocol methods

• Excludes generated BiDi protocol files from Naming/PredicatePrefix enforcement for wire-derived method names such as is_active.

rb/.rubocop.yml

update_cddl.pyPreserve vendor grammar configuration during updates +22/-0

Preserve vendor grammar configuration during updates

• Adds the namespace-keyed Mozilla CDDL list to generated webref_cddl.bzl output, preparing future pinning from mozilla-central.

scripts/update_cddl.py

[qodo-code-review]

Code Review by Qodo

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

1. Other bindings miss Firefox commands ✗ Dismissed 📘 Rule violation ≡ Correctness

Description

protocol.rb now loads generated MozDebugging and MozProfiler domains, while
generate_bidi.mjs deliberately keeps the JavaScript binding vendor-free and Python's Schema
reads only the shared types, commands, and events sections. When Firefox users need the new
debugging or profiling methods stored under schema.vendor.moz, only Ruby produces callable domains
for them; the corresponding generated APIs are absent from Python and JavaScript.

Code

rb/lib/selenium/webdriver/bidi/protocol.rb[R36-37]

+require 'selenium/webdriver/bidi/protocol/moz_debugging'
+require 'selenium/webdriver/bidi/protocol/moz_profiler'

Evidence

Rule 4 requires user-visible protocol behavior to remain consistent with another binding unless a
binding-specific requirement justifies divergence. The PR loads the Firefox vendor domains in Ruby
and adds their commands to the shared schema, while the JavaScript pipeline explicitly remains
vendor-free and Python's schema consumer ignores vendor.

AGENTS.md: Maintain Cross-Binding Consistency for User-Visible Behavior
rb/lib/selenium/webdriver/bidi/protocol.rb[36-37]
common/bidi/schema.json[17849-17864]
javascript/selenium-webdriver/generate_bidi.mjs[148-156]
py/generate_bidi_protocol.py[271-276]

Agent prompt

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

## Issue description
Firefox vendor commands and types are generated as callable Ruby domains, but the Python and JavaScript binding pipelines omit the schema's vendor section. This creates binding-specific protocol coverage without a documented requirement for that divergence.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/protocol.rb[36-37]
- py/generate_bidi_protocol.py[271-276]
- py/BUILD.bazel[762-773]
- javascript/selenium-webdriver/generate_bidi.mjs[148-156]

## Recommended Fix
Wire the vendor CDDL or projected vendor schema into at least one additional binding generator, emit equivalent Firefox debugging and profiling commands and types, and add generator-level tests covering command serialization and result projection. If these modules must remain Ruby-specific, remove their exposure from this change until the binding-specific requirement is documented and approved.

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

---

2. Firefox options lack generated types ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Schema#owned_types excludes vendor-owned types from the ordinary session domain, while
type_prefixes discovers vendor types only through vendor command and event references. When
callers construct session.new capabilities, moz:firefoxOptions and its nested values therefore
reach only the generic untyped extensions hash instead of generated records with runtime and static
validation.

Code

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[R729-731]

+      vendor = domain.include?(':')
+      prefixes = type_prefixes(domain).map { |prefix| "#{prefix}." }
+      @types.select { |name, _| prefixes.any? { |p| name.start_with?(p) } && @vendor_types.key?(name) == vendor }

Evidence

The schema includes an outbound Firefox-options record and nested helper references, but the
generator's new ownership filter excludes vendor types from session. The resulting Ruby and RBS
session bindings expose only the generic extensions bag and contain none of the declared
Firefox-options types.

rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[724-740]
common/bidi/schema.json[17773-17781]
common/bidi/schema.json[18923-19004]
rb/lib/selenium/webdriver/bidi/protocol/session.rb[42-62]
rb/sig/lib/selenium/webdriver/bidi/protocol/session.rbs[28-42]

Agent prompt

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

## Issue description
Vendor types referenced by extension fields, such as `session.CapabilityRequestFirefoxOptions`, are excluded from generated Ruby and RBS because they are not referenced by a vendor command or event.

## Fix Focus Areas
- rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb[724-740]

## Recommended Fix
Extend vendor type ownership discovery to include types referenced by vendor extension fields and recursively include their referenced helper types. Emit those types in an appropriate reachable Ruby domain and generate matching constructors and RBS declarations rather than requiring callers to use `Hash[String, untyped]`.

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

---

Context sources

Review mode: 🧠 Deep: This cross-cutting schema and multi-language generator change has substantial new logic across many independent edit sites, making multiple subtle defects plausible.

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗