[build] track the generated BiDi schema

[titusfortner]

🔗 Related Issues

• See [adr] Behavioral contract for the low-level WebDriver BiDi layer #17786 - the ADR says to validate against the shared schema, so we need to publish the shared schema instead of just using it within the build process

💥 What does this PR do?

• Checks in the generated binding-neutral BiDi schema as common/bidi/schema.json (follows the precedent of checking in the CDP pdl files)

🔧 Implementation Notes

• The schema serializes deterministically in spec/CDDL source order, so the checked-in file only changes when the pin (or the emitter) does, and repins diff cleanly.
• bazel run //common/bidi:update-schema refreshes it, and a staleness test fails with that command when the checked-in copy drifts from the built artifact.
• Provenance is top-level generatedBy / regenerateWith keys emitted by the projector itself, since JSON can't carry a comment header and appending one after the fact would break byte-equality with the built artifact.
• write_source_files (aspect_bazel_lib, already a dependency) provides the update target and the staleness test from one declaration.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: the consumption analysis, implementation, and this description
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• Follow-up: point the rb/py schema consumers at the checked-in file, removing the node toolchain and external CDDL fetches from their build graphs.

🔄 Types of changes

• New feature (build/tooling only — no user-facing behavior change)

[qodo-code-review]

PR Summary by Qodo

Check in generated BiDi schema with staleness validation

✨ Enhancement 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Publishes deterministic, binding-neutral BiDi schema at common/bidi/schema.json.
• Adds Bazel update and staleness targets for the checked-in schema.
• Embeds generator provenance and regeneration instructions in schema output.

Diagram

graph TD
  A["BiDi CDDL"] --> B["Schema projector"] --> C["Bazel artifact"] --> D["Source updater"] --> E["Checked-in schema"] --> F["Staleness test"]
  C --> F

Loading

High-Level Assessment

The chosen approach is appropriate: it reuses the existing deterministic schema projector and aspect_bazel_lib's established source-update/staleness mechanism instead of introducing a custom synchronization script. Embedding provenance in the generated JSON preserves byte equality while making regeneration discoverable.

Files changed (4) +16997 / -2

Enhancement (2) +16987 / -2

schema.jsonPublish the generated binding-neutral BiDi schema +16977/-0

Publish the generated binding-neutral BiDi schema

• Checks in the deterministic schema containing BiDi commands, events, types, domains, vendor extensions, specification links, and generation provenance. This gives bindings and external consumers a stable shared artifact without requiring the JavaScript generation toolchain.

common/bidi/schema.json

project_bidi_schema.mjsEmbed schema generation provenance +10/-2

Embed schema generation provenance

• Adds top-level 'generatedBy' and 'regenerateWith' fields to every projected schema and updates the documented return shape. Provenance is emitted directly to keep generated and checked-in JSON byte-identical.

javascript/selenium-webdriver/project_bidi_schema.mjs

Other (2) +10 / -0

BUILD.bazelAdd schema update and staleness targets +9/-0

Add schema update and staleness targets

• Declares a 'write_source_files' target that copies the canonical generated BiDi schema into 'common/bidi/schema.json'. The macro also supplies staleness validation and reports the regeneration command when the source copy drifts.

common/bidi/BUILD.bazel

generate_bidi.bzlExpose generated schema to the common BiDi package +1/-0

Expose generated schema to the common BiDi package

• Extends generated artifact visibility so '//common/bidi' can consume the schema output for source synchronization and staleness validation.

javascript/selenium-webdriver/private/generate_bidi.bzl

[qodo-code-review]

Code Review by Qodo

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

1. Schema remains package-private ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new schema.json destination is referenced by write_source_files but omitted from
exports_files, so Bazel 9 treats //common/bidi:schema.json as private and Python/Ruby or other
packages cannot consume the published schema. This defeats the shared-schema purpose and the stated
follow-up cannot switch consumers to the checked-in file without another BUILD change.

Code

common/bidi/BUILD.bazel[11]

+        "schema.json": "//javascript/selenium-webdriver:create-bidi-src_schema",

Evidence

The package exports only CDDL files, while the added schema name appears solely as the update
destination. The analogous checked-in CDP JSON artifacts are explicitly exported to JavaScript,
Python, and Ruby, and Bazel documents that cross-package source files require exports_files; with
no implicit export they are private.

common/bidi/BUILD.bazel[3-12]
common/devtools/BUILD.bazel[3-12]
MODULE.bazel[1-5]
🌐 Bazel states that a package may refer directly to another package's source file only when it is explicitly exported with exports_files().

Agent prompt

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

## Issue description
`common/bidi/schema.json` is generated locally but is not exported as a cross-package Bazel source target.

## Issue Context
Bazel source files must be explicitly exported for use by other packages. Add `schema.json` to an `exports_files` declaration with visibility covering the intended shared-schema consumers, following the checked-in CDP JSON precedent.

## Fix Focus Areas
- common/bidi/BUILD.bazel[3-12]

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

---

2. projectSchema provenance untested ✗ Dismissed 📘 Rule violation ☼ Reliability

Description

projectSchema now exposes generatedBy and regenerateWith, but the focused projector tests do
not assert either field or the regeneration command. This leaves the new schema provenance contract
without regression coverage.

Code

javascript/selenium-webdriver/project_bidi_schema.mjs[R686-687]

+    generatedBy: 'javascript/selenium-webdriver/project_bidi_schema.mjs',
+    regenerateWith: 'bazel run //common/bidi:update-schema',

Evidence

Compliance rule 5 requires focused tests for changed behavior. The PR adds two externally serialized
schema fields, while the existing bare-projection test checks type links, commands, domains, and
schema integrity without asserting either provenance value.

AGENTS.md: Add Focused Tests and Prefer Real API Contracts Over Mocks
javascript/selenium-webdriver/project_bidi_schema.mjs[684-694]
javascript/selenium-webdriver/project_bidi_schema_test.mjs[753-759]

Agent prompt

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

## Issue description
Add focused regression coverage for the new `generatedBy` and `regenerateWith` fields emitted by `projectSchema`.

## Issue Context
The checked-in schema relies on these values to identify its generator and provide the correct refresh command. Existing projector tests validate schema structure but do not assert this new contract.

## Fix Focus Areas
- javascript/selenium-webdriver/project_bidi_schema.mjs[686-687]
- javascript/selenium-webdriver/project_bidi_schema_test.mjs[753-759]

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

---

Context sources

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

Code review by qodo was updated up to the latest commit 65c6e3a

[qodo-code-review]

Code review by qodo was updated up to the latest commit 6b14d7f