[rb] link generated BiDi elements to their spec definitions

[titusfortner]

💥 What does this PR do?

Adds a specHref to the shared BiDi schema so generated clients can link each
element to its definition in the live WebDriver BiDi spec. Types, commands, and
events each carry one, and a new domains map holds the per-domain module link.
Where the spec has a readable prose section (#type-/#command-/#event-/#module-)
the link points there; otherwise it falls back to the webref CDDL production
(#cddl-type-). The Ruby generator renders these as @see doc comments on domain
classes, command methods, and type/union/enum classes.

🔧 Implementation Notes

• Additive throughout: the projector's link input is optional and every specHref is
  present-only-when-known, so existing schema consumers are unaffected and the generated
  Ruby changes are comment-only. Other bindings can adopt specHref in follow-ups.
• The prose section ids exist only in the rendered spec (webref doesn't extract them),
  and no rule predicts which types get one. So the rendered index.html is pinned from
  w3c/webdriver-bidi's gh-pages branch (http_file, commit + sha256, like the CDDL/dfns)
  and its anchors are extracted at build — nothing fetched live, nothing generated
  committed. //scripts:update_cddl repins the HTML and refreshes the dfns hashes in
  lockstep with the CDDL.
• The prose scheme is a core-BiDi convention; adjacent specs (Web Bluetooth, Permissions,
  …) keep the CDDL fallback on their own origin.
• Links target the editor's draft, so for an older release the target drifts from the
  pinned source it was generated against.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code (Opus 4.8)
  • What was generated: schema projector changes, anchor extraction + Bazel pinning,
    Ruby generator + regenerated protocol files, update_cddl changes, tests
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• High-risk-adjacent: touches the shared schema every binding consumes and adds pinned
  http_file repos to MODULE.bazel. Additive but coordinated.
• Follow-ups: Java, .NET, and Python generators can adopt specHref the same way.

🔄 Types of changes

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

[selenium-ci]

Thank you, @titusfortner for this code suggestion.

The support packages contain example code that many users find helpful, but they do not necessarily represent
the best practices for using Selenium, and the Selenium team is not currently merging changes to them.

After reviewing the change, unless it is a critical fix or a feature that is needed for Selenium
to work, we will likely close the PR.

We actively encourage people to add the wrapper and helper code that makes sense for them to their own frameworks.
If you have any questions, please contact us

[qodo-code-review]

PR Summary by Qodo

Add specHref links to BiDi schema and emit Ruby @see docs for spec definitions

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

AI Description

• Add optional specHref links for BiDi types, commands, events, and domains in the projected
 schema.
• Pin and extract prose anchors from rendered WebDriver BiDi HTML, falling back to webref CDDL
 anchors.
• Render spec links as Ruby @see comments and add tests + Bazel wiring for pinned inputs.

Diagram

graph TD
  P["Pinned inputs (Bazel http_file)"] --> D["webref dfns.json"] --> S["project_bidi_schema.mjs"] --> B[("schema.json (specHref)")] --> R["Ruby protocol docs"]
  P --> H["Rendered spec HTML"] --> E["extract_bidi_anchors.mjs"] --> A[("anchors.json")] --> S

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Resolve anchors from live spec at generation time

• ➕ No pinned HTML/sha maintenance
• ➕ Always links to current editor’s draft structure
• ➖ Non-reproducible builds (network + drifting anchors)
• ➖ Harder to audit changes; flaky CI/offline builds

2. Maintain a curated mapping of element->spec URL in-repo

• ➕ Fully deterministic; no external HTML parsing
• ➕ Explicit review of every link change
• ➖ High ongoing maintenance burden; easy to drift from spec
• ➖ Large, noisy diffs as spec evolves

3. Use only webref CDDL (#cddl-type-*) links (no prose anchors)

• ➕ Simpler pipeline; no extra pinned repo
• ➕ Uniform behavior across all merged specs
• ➖ Links are less readable; misses command/event/domain sections entirely
• ➖ Doesn’t meet goal of pointing to prose sections when available

Recommendation: Keep the PR’s approach: it preserves reproducible/offline builds while producing higher-quality links. webref dfns provides broad type coverage with absolute per-spec hrefs; the separately pinned rendered BiDi HTML enables upgrading to readable prose anchors and adding command/event/domain links. The implementation is additive and fail-closed (unknown links omitted), minimizing risk to existing schema consumers.

Files changed (23) +1029 / -68

Enhancement (3) +261 / -29

extract_bidi_anchors.mjsExtract BiDi prose anchors into a joinable index +112/-0

Extract BiDi prose anchors into a joinable index

• Adds a new script that scans rendered spec HTML for 'module-', 'type-', 'command-', and 'event-' ids and emits an anchors.json index keyed case-insensitively. Includes Bazel-friendly path resolution and a small CLI.

javascript/selenium-webdriver/extract_bidi_anchors.mjs

project_bidi_schema.mjsAttach optional specHref links to types/commands/events/domains in schema output +119/-16

Attach optional specHref links to types/commands/events/domains in schema output

• Adds spec-link joining against webref dfns (CDDL anchors) and extracted prose anchors to populate 'specHref' on type nodes and command/event entries, and introduces a 'domains' map with per-domain module links. Extends CLI with repeatable --dfns and optional --anchors while keeping output backward compatible when omitted.

javascript/selenium-webdriver/project_bidi_schema.mjs

bidi_generate.rbPlumb schema specHref into Ruby generator IR +30/-13

Plumb schema specHref into Ruby generator IR

• Extends Ruby generator IR structs to carry 'spec_href' for commands, types, enums, unions, and domains; reads schema['domains']; and threads schema-provided specHref values through IR construction.

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

Tests (1) +147 / -1

project_bidi_schema_test.mjsAdd unit tests for spec-link building and attachment +147/-1

Add unit tests for spec-link building and attachment

• Adds tests for buildSpecHrefs/buildSpecLinks merging semantics, prose-anchor extraction, and end-to-end attachment of 'specHref' to projected schema elements while remaining optional and schema-valid.

javascript/selenium-webdriver/project_bidi_schema_test.mjs

Documentation (14) +379 / -0

bluetooth.rbAdd @see links to spec definitions (Bluetooth domain types) +21/-0

Add @see links to spec definitions (Bluetooth domain types)

• Updates generated Ruby protocol code to include '@see' links to spec anchors for Bluetooth-related types (Web Bluetooth spec).

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

browser.rbAdd @see links to spec definitions (Browser domain) +17/-0

Add @see links to spec definitions (Browser domain)

• Adds generated '@see' links for the Browser domain module section and for key type definitions, using prose anchors when available.

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

browsing_context.rbAdd @see links to spec definitions (BrowsingContext domain) +64/-0

Add @see links to spec definitions (BrowsingContext domain)

• Adds domain/module '@see' and type/enum/union '@see' links to their corresponding spec sections (prose where available, otherwise CDDL anchors).

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

emulation.rbAdd @see links to spec definitions (Emulation domain) +31/-0

Add @see links to spec definitions (Emulation domain)

• Adds generated '@see' links to relevant Emulation types/enums/records in the WebDriver BiDi spec.

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

input.rbAdd @see links to spec definitions (Input domain) +28/-0

Add @see links to spec definitions (Input domain)

• Adds generated '@see' links for Input domain module section and for associated types/enums/unions to their spec anchors.

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

log.rbAdd @see links to spec definitions (Log domain) +7/-0

Add @see links to spec definitions (Log domain)

• Adds generated '@see' links for Log domain module section plus Log enum/union/record types to their spec anchors.

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

network.rbAdd @see links to spec definitions (Network domain) +57/-0

Add @see links to spec definitions (Network domain)

• Adds generated '@see' links for Network domain module section and for many Network types to their spec anchors, preferring prose sections where present.

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

script.rbAdd @see links to spec definitions (Script domain) +84/-0

Add @see links to spec definitions (Script domain)

• Adds generated '@see' links for the Script domain module section and for Script types/enums/unions/records to their spec anchors.

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

session.rbAdd @see links to spec definitions (Session domain + commands) +25/-0

Add @see links to spec definitions (Session domain + commands)

• Adds generated '@see' links for the Session domain module section, several types, and the session command methods (e.g., subscribe/unsubscribe/new/status/end).

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

speculation.rbAdd @see links to spec definitions (Speculation types) +2/-0

Add @see links to spec definitions (Speculation types)

• Adds generated '@see' links for Speculation enums/types to the Nav Speculation spec anchors.

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

storage.rbAdd @see links to spec definitions (Storage domain) +16/-0

Add @see links to spec definitions (Storage domain)

• Adds generated '@see' links for the Storage domain module section and Storage types/unions/records to their spec anchors.

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

user_agent_client_hints.rbAdd @see links to spec definitions (UA Client Hints types) +2/-0

Add @see links to spec definitions (UA Client Hints types)

• Adds generated '@see' links for UA Client Hints types to the UA-CH spec CDDL anchors.

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

web_extension.rbAdd @see links to spec definitions (WebExtension domain + commands) +10/-0

Add @see links to spec definitions (WebExtension domain + commands)

• Adds generated '@see' links for WebExtension domain module section, types, and command methods (install/uninstall) to their spec anchors.

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

module.rb.erbRender specHref as YARD '@see' comments in generated Ruby +15/-0

Render specHref as YARD '@see' comments in generated Ruby

• Updates the Ruby template to conditionally emit '# @see <specHref>' for domains, commands, enums, and type/union classes when a link is present.

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

Other (5) +242 / -38

MODULE.bazelRegister pinned dfns + rendered BiDi spec HTML repos +6/-0

Register pinned dfns + rendered BiDi spec HTML repos

• Adds new repositories to the webref_cddl_extension use_repo list for the per-spec dfns indexes and the pinned WebDriver BiDi rendered HTML file.

MODULE.bazel

webref_cddl.bzlPin webref dfns indexes and BiDi rendered spec HTML +51/-0

Pin webref dfns indexes and BiDi rendered spec HTML

• Introduces pinned downloads for webref ed/dfns JSON indexes (for merged specs) and a separately pinned w3c/webdriver-bidi gh-pages index.html. Wires them into the existing module extension so builds have reproducible inputs for spec linking.

common/webref_cddl.bzl

BUILD.bazelAdd anchor extraction target and pass schema link inputs +22/-0

Add anchor extraction target and pass schema link inputs

• Adds a js_binary for extracting BiDi prose anchors and includes it in test data. Updates the BiDi generation rule invocation to supply dfns files and the pinned core spec HTML so the schema can be projected with spec links.

javascript/selenium-webdriver/BUILD.bazel

generate_bidi.bzlStage external dfns/spec HTML and wire anchor extraction into schema projection +58/-9

Stage external dfns/spec HTML and wire anchor extraction into schema projection

• Extends generate_bidi_library with optional dfns_files and spec_html inputs. Stages external files into the package (copy_file), runs the anchor extractor when spec_html is provided, and forwards --dfns/--anchors into the schema projector action.

javascript/selenium-webdriver/private/generate_bidi.bzl

update_cddl.pyRepin dfns indexes and rendered BiDi HTML alongside webref CDDL +105/-29

Repin dfns indexes and rendered BiDi HTML alongside webref CDDL

• Extends the repinning script to refresh hashes for merged-spec dfns indexes (from the webref commit) and to pin/hash webdriver-bidi gh-pages index.html. Updates MODULE.bazel repo-list generation to include the new repos.

scripts/update_cddl.py

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 22 rules

1. Method toLowerCase crash ✓ Resolved 🐞 Bug ☼ Reliability

Description

In projectSchema(), the new link helper calls key.toLowerCase() unconditionally, so a malformed
command/event entry with a missing/non-string method will throw a TypeError before
checkSchema/checkCompleteness can produce actionable validation errors. This makes schema generation
less diagnosable in failure scenarios.

Code

javascript/selenium-webdriver/project_bidi_schema.mjs[R474-488]

+  // Commands and events link to their own prose section (`#command-*` / `#event-*`),
+  // keyed by the wire method; domains to their `#module-*` section. Present-only-when-known.
+  const link = (map, key) => map?.[key.toLowerCase()]
  for (const [domain, entry] of Object.entries(model)) {
-    for (const c of entry.commands ?? [])
-      commands.push({
+    for (const c of entry.commands ?? []) {
+      const cmd = {
        domain,
        method: c.method,
        name: c.name,
        // Prefer the envelope's params (it captures inline params the model drops).
        params: typeRef(envelopeParams.get(c.method) ?? c.params),
        result: typeRef(c.result),
-      })
-    for (const e of entry.events ?? [])
-      events.push({ domain, method: e.method, name: e.name, params: typeRef(envelopeParams.get(e.method) ?? e.params) })
+      }
+      const href = link(links.commands, c.method)
+      if (href) cmd.specHref = href

Evidence

The helper dereferences key.toLowerCase() before any schema validation runs, and it is invoked
with c.method/e.method, so a non-string method value will throw immediately.

javascript/selenium-webdriver/project_bidi_schema.mjs[471-496]

Agent prompt

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

### Issue description
`projectSchema()` defines `link = (map, key) => map?.[key.toLowerCase()]`, which will throw if `key` is not a string (e.g., malformed `c.method`/`e.method`). This crash happens before schema validation, reducing error quality.

### Issue Context
Spec links are optional; missing methods should ideally be reported by existing schema/model validators instead of causing an unhandled exception.

### Fix Focus Areas
- javascript/selenium-webdriver/project_bidi_schema.mjs[474-495]

### Suggested change
- Update `link` to be defensive:
 - `const link = (map, key) => (typeof key === 'string' ? map?.[key.toLowerCase()] : undefined)`
- (Optional) Add a small unit test covering a model entry with a non-string `method` to ensure the projector fails gracefully (or emits validation errors).

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

---

2. Double-quote-only id parsing ✓ Resolved 🐞 Bug ☼ Reliability

Description

extractAnchors() only matches HTML ids written as id="…", so valid HTML that uses single quotes
(id='…') will be ignored, resulting in silently missing entries in anchors.json and therefore
missing specHref links. This is brittle against future changes in the pinned spec HTML serialization
and in the documented URL-based ad-hoc mode.

Code

javascript/selenium-webdriver/extract_bidi_anchors.mjs[R58-61]

+export function extractAnchors(html, base = SPEC_URL) {
+  const ids = new Set([...html.matchAll(/id="([^"]+)"/g)].map((m) => m[1]))
+  const index = { modules: {}, types: {}, commands: {}, events: {} }
+  const href = (id) => `${base.replace(/#.*$/, '').replace(/\/?$/, '/')}#${id}`

Evidence

The extractor’s regex only matches id="...", so ids expressed with single quotes are skipped and
never make it into the returned index maps.

javascript/selenium-webdriver/extract_bidi_anchors.mjs[58-72]

Agent prompt

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

### Issue description
`extractAnchors()` uses `/id="([^"]+)"/g`, which ignores `id='...'` (valid HTML). That can silently drop anchors and reduce `specHref` coverage.

### Issue Context
This tool intentionally does a lightweight extraction (not a full DOM parse), but it should still handle common quoting forms in HTML output.

### Fix Focus Areas
- javascript/selenium-webdriver/extract_bidi_anchors.mjs[58-72]
- javascript/selenium-webdriver/project_bidi_schema_test.mjs[485-513]

### Suggested change
- Expand the regex to capture both quote styles, e.g.:
 - `/id=(?:"([^"]+)"|'([^']+)')/g`
 - then pick `m[1] ?? m[2]`.
- Add/extend a unit test to include an element like `<h2 id='module-session'>` and assert it is indexed.

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

---

3. No fetch status check ✓ Resolved 🐞 Bug ☼ Reliability

Description

When --spec is a URL, extract_bidi_anchors.mjs reads response.text() without checking response.ok,
so 404/500 pages can still produce an anchors.json file and exit successfully. This can hide
failures and yield incorrect/missing anchors in ad-hoc runs.

Code

javascript/selenium-webdriver/extract_bidi_anchors.mjs[R91-99]

+  const { values: args } = parseArgs({ options: { spec: { type: 'string' }, out: { type: 'string' } } })
+  const spec = args.spec ?? SPEC_URL
+  if (!args.out) {
+    console.error('Usage: extract_bidi_anchors.mjs [--spec <url|file>] --out <anchors.json>')
+    process.exit(1)
+  }
+  const html = /^https?:/.test(spec) ? await (await fetch(spec)).text() : readFileSync(resolveInput(spec), 'utf8')
+  const index = extractAnchors(html, SPEC_URL)
+  writeFileSync(resolve(args.out), JSON.stringify(index, null, 2) + '\n', 'utf8')

Evidence

The code path for URL specs uses fetch(spec) and immediately consumes .text(); fetch does not
throw on non-2xx statuses, so failures can be silently treated as HTML.

javascript/selenium-webdriver/extract_bidi_anchors.mjs[91-101]

Agent prompt

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

### Issue description
For URL input, `fetch(spec)` is not checked for HTTP error statuses; `response.text()` will still succeed on 404/500 and the script will write output and exit 0.

### Issue Context
This affects the documented ad-hoc mode (`--spec` as a URL). Bazel uses a pinned local file, but developers running it manually can get silently bad output.

### Fix Focus Areas
- javascript/selenium-webdriver/extract_bidi_anchors.mjs[91-105]

### Suggested change
- Replace the URL branch with:
 - `const res = await fetch(spec)`
 - `if (!res.ok) throw new Error(...)`
 - `const html = await res.text()`
- Consider including the status code and URL in the thrown error message for debuggability.

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

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit 1021bc0

[Copilot]

Pull request overview

This PR adds optional specHref metadata to the shared WebDriver BiDi schema so generated clients (Ruby in this PR) can link schema elements (domains/modules, commands/events, and types) to their definitions in the living specifications. It also introduces build-time extraction of prose anchors from a pinned rendered BiDi spec HTML, and pins the needed webref dfns indexes + spec HTML via Bazel.

Changes:

• Extend the schema projector to attach optional specHref links to types/commands/events and add a per-domain domains map.
• Add a build step to extract prose anchors from pinned BiDi spec HTML and merge them with webref CDDL/dfns links.
• Update the Ruby BiDi generator/templates to render these links as @see YARD comments, and update pinning automation (update_cddl.py) + Bazel repos.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
scripts/update_cddl.py	Updates the pin-refresh script to also repin dfns indexes and the rendered BiDi spec HTML alongside CDDL.
rb/lib/selenium/webdriver/bidi/support/templates/module.rb.erb	Emits @see YARD links for domains, types/unions, enums, and commands when specHref is present.
rb/lib/selenium/webdriver/bidi/support/bidi_generate.rb	Threads specHref through the Ruby BiDi IR structs and reads per-domain links from the schema domains map.
rb/lib/selenium/webdriver/bidi/protocol/web_extension.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/user_agent_client_hints.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/storage.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/speculation.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/session.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/script.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/network.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/log.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/input.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/emulation.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/browsing_context.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/browser.rb	Regenerated Ruby BiDi protocol file with added @see links.
rb/lib/selenium/webdriver/bidi/protocol/bluetooth.rb	Regenerated Ruby BiDi protocol file with added @see links.
MODULE.bazel	Adds use_repo entries for the new dfns and rendered-spec http_file repos.
javascript/selenium-webdriver/project_bidi_schema.mjs	Adds spec-link mapping/join logic and extends projected schema output with specHref + domains.
javascript/selenium-webdriver/project_bidi_schema_test.mjs	Adds unit tests covering dfns mapping, prose anchor extraction, and schema link attachment.
javascript/selenium-webdriver/private/generate_bidi.bzl	Extends Bazel generation to stage dfns/spec HTML, extract anchors, and pass them into the schema projector.
javascript/selenium-webdriver/extract_bidi_anchors.mjs	New helper to extract prose anchor IDs from pinned BiDi spec HTML into an index for schema linking.
javascript/selenium-webdriver/BUILD.bazel	Adds the new anchors extractor binary and wires dfns/spec HTML inputs into BiDi generation.
common/webref_cddl.bzl	Adds pinned webref dfns repos and a separately pinned rendered BiDi spec HTML repo to the module extension.