| // Licensed to the Software Freedom Conservancy (SFC) under one | |
| // or more contributor license agreements. See the NOTICE file | |
| // distributed with this work for additional information | |
| // regarding copyright ownership. The SFC licenses this file | |
| // to you under the Apache License, Version 2.0 (the | |
| // "License"); you may not use this file except in compliance | |
| // with the License. You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, | |
| // software distributed under the License is distributed on an | |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| // KIND, either express or implied. See the License for the | |
| // specific language governing permissions and limitations | |
| // under the License. | |
| /** | |
| * Generate the shared WebDriver BiDi artifacts and TypeScript bindings from a | |
| * merged CDDL spec, as a three-stage pipeline — one stage per invocation: | |
| * | |
| * 1. parse --cddl <f> --dump-ast <f> CDDL → AST | |
| * 2. model --ast <f> --dump-model <f> AST → command/event model | |
| * 3. generate --ast <f> --model <f> --output-dir <d> AST + model → one TS module per domain | |
| * [--spec-version <v>] | |
| */ | |
| import { parse } from 'cddl' | |
| import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs' | |
| import { dirname, join, resolve } from 'node:path' | |
| import { fileURLToPath } from 'node:url' | |
| import { parseArgs } from 'node:util' | |
| import { projectSchema } from './project_bidi_schema.mjs' | |
| // ============================================================ | |
| // Domain configuration | |
| // ============================================================ | |
| // Output filename for each domain key. | |
| const DOMAIN_FILES = { | |
| browser: 'browser.ts', | |
| browsingContext: 'browsing_context.ts', | |
| emulation: 'emulation.ts', | |
| input: 'input.ts', | |
| log: 'log.ts', | |
| network: 'network.ts', | |
| permissions: 'permissions.ts', | |
| script: 'script.ts', | |
| session: 'session.ts', | |
| speculation: 'speculation.ts', | |
| storage: 'storage.ts', | |
| userAgentClientHints: 'user_agent_client_hints.ts', | |
| webExtension: 'webextension.ts', | |
| bluetooth: 'bluetooth.ts', | |
| digitalCredentials: 'digital_credentials.ts', | |
| common: 'common.ts', | |
| } | |
| // Implementation class name for each domain key. | |
| // Domains absent from this map only receive type definitions (no class). | |
| const DOMAIN_CLASSES = { | |
| browser: 'Browser', | |
| browsingContext: 'BrowsingContext', | |
| emulation: 'Emulation', | |
| input: 'Input', | |
| log: 'Log', | |
| network: 'Network', | |
| permissions: 'Permissions', | |
| script: 'Script', | |
| session: 'Session', | |
| speculation: 'Speculation', | |
| storage: 'Storage', | |
| userAgentClientHints: 'UserAgentClientHints', | |
| webExtension: 'WebExtension', | |
| bluetooth: 'Bluetooth', | |
| digitalCredentials: 'DigitalCredentials', | |
| } | |
| // ============================================================ | |
| // Path helpers | |
| // ============================================================ | |
| /** | |
| * Resolve a path that came from a Bazel $(location …) expansion. | |
| * | |
| * When a js_binary runs inside a js_run_binary action Bazel sets BAZEL_BINDIR | |
| * and the js_binary wrapper calls process.chdir(BAZEL_BINDIR) before handing | |
| * control to the script. $(location) values are relative to the *execroot*, | |
| * so they already contain the BAZEL_BINDIR prefix. Stripping that prefix | |
| * makes them relative to the CWD, after which path.resolve() works correctly. | |
| * Outside Bazel (BAZEL_BINDIR unset) paths are resolved normally. | |
| */ | |
| function resolveInputPath(p) { | |
| if (!p) return null | |
| if (!process.env.BAZEL_BINDIR) return resolve(p) | |
| // Normalize both strings to forward slashes before prefix-stripping so that | |
| // mixed separators on Windows (BAZEL_BINDIR uses '\', $(location) uses '/') | |
| // do not cause the startsWith check to silently fail. | |
| const normalizedP = p.replaceAll('\\', '/') | |
| const normalizedBindir = process.env.BAZEL_BINDIR.replaceAll('\\', '/') | |
| const prefix = normalizedBindir + '/' | |
| return resolve(normalizedP.startsWith(prefix) ? normalizedP.slice(prefix.length) : normalizedP) | |
| } | |
| // ============================================================ | |
| // Main | |
| // ============================================================ | |
| async function main() { | |
| const { values: args } = parseArgs({ | |
| options: { | |
| cddl: { type: 'string', multiple: true }, | |
| 'override-cddl': { type: 'string', multiple: true }, | |
| 'vendor-cddl': { type: 'string', multiple: true }, | |
| ast: { type: 'string' }, | |
| model: { type: 'string' }, | |
| 'vendor-model': { type: 'string' }, | |
| 'dump-ast': { type: 'string' }, | |
| 'dump-model': { type: 'string' }, | |
| 'output-dir': { type: 'string' }, | |
| 'spec-version': { type: 'string', default: '1.0' }, | |
| }, | |
| }) | |
| // One pipeline stage per invocation; the flags select the stage. | |
| if (args['dump-ast'] && args.cddl?.length) { | |
| // The base spec is several CDDL files (webdriver-bidi + the adjacent specs); each | |
| // is parsed independently and their definitions concatenated. Top-level CDDL | |
| // productions are position-independent (refs resolve by name later), so this equals | |
| // parsing one merged file — without a separate merge step or tool. Spec-shaped Selenium | |
| // overrides are applied here; vendor overlays are NOT, so this base AST — | |
| // which feeds the model and the browser-neutral TypeScript binding — stays vendor-free. | |
| const baseAst = args.cddl.flatMap(parseCddl) | |
| writeJson(args['dump-ast'], applyOverrides(baseAst, args['override-cddl'] ?? []), 'ast') | |
| } else if (args['dump-ast'] && args.ast && args['vendor-cddl']?.length) { | |
| // The base AST plus vendor overlays, consumed ONLY by the schema projector. Applying vendor | |
| // on this separate path (rather than into the shared base AST) is what keeps the tagged | |
| // vendor fields out of cddl2ts and the model — the schema step segregates them into `vendor`. | |
| writeJson(args['dump-ast'], applyVendor(readJson(args.ast, 'AST'), args['vendor-cddl']), 'ast') | |
| } else if (args['dump-model'] && args.ast) { | |
| writeJson(args['dump-model'], buildModel(readJson(args.ast, 'AST')), 'model', true) | |
| } else if (args['output-dir'] && args.ast && args.model) { | |
| const vendorModel = args['vendor-model'] ? readJson(args['vendor-model'], 'vendor model') : null | |
| generateTypeScript(readJson(args.ast, 'AST'), readJson(args.model, 'model'), vendorModel, args) | |
| } else { | |
| console.error( | |
| 'Usage (one stage per invocation):\n' + | |
| ' generate_bidi.mjs --cddl <file> [--cddl <file>...] [--override-cddl <file>...] --dump-ast <file>\n' + | |
| ' generate_bidi.mjs --ast <file> --vendor-cddl <namespace>=<file> [...] --dump-ast <file>\n' + | |
| ' generate_bidi.mjs --ast <file> --dump-model <file>\n' + | |
| ' generate_bidi.mjs --ast <file> --model <file> [--vendor-model <file>] --output-dir <dir> [--spec-version <v>]', | |
| ) | |
| process.exit(1) | |
| } | |
| } | |
| function parseCddl(cddlArg) { | |
| const cddlPath = resolveInputPath(cddlArg) | |
| if (!existsSync(cddlPath)) { | |
| console.error(`Error: CDDL file not found: ${cddlPath}`) | |
| process.exit(1) | |
| } | |
| console.log(`Parsing CDDL: ${cddlPath}`) | |
| const ast = parse(cddlPath) | |
| console.log(` ${ast.length} top-level definitions`) | |
| return ast | |
| } | |
| /** | |
| * Apply Selenium overlay CDDL (see common/bidi/) to the parsed upstream AST: any | |
| * production an overlay defines replaces the identically named upstream one, which is | |
| * dropped. Kept here rather than in the shared CDDL merge so the overlay is a | |
| * schema-generation concern only — the upstream grammars other bindings consume are | |
| * untouched. Overlay defs are appended so downstream normalization treats them like | |
| * any other definition. | |
| */ | |
| function applyOverrides(ast, overrideArgs) { | |
| if (!overrideArgs.length) return ast | |
| const overrides = overrideArgs.flatMap((arg) => parseCddl(arg)) | |
| const names = new Set(overrides.filter((d) => d?.Name).map((d) => d.Name)) | |
| return [...ast.filter((d) => !(d?.Name && names.has(d.Name))), ...overrides] | |
| } | |
| /** | |
| * Apply Selenium vendor overlay CDDL (see common/bidi/*-extensions.cddl) to the AST. Each | |
| * `--vendor-cddl` is `<namespace>=<file>`, the namespace being the wire prefix the vendor owns | |
| * (`moz` for `moz:` fields). A vendor overlay extends a spec type through a `<Type>Extension` | |
| * group of typed browser-specific fields, which the normalizer splices into the like-named | |
| * upstream record. Unlike a plain override, every field a vendor overlay contributes is tagged | |
| * with its provenance — the namespace and the extension group it flows through — so the | |
| * projector can resolve it against the real spec type (the merge genuinely happens) yet route it | |
| * out of the shared, browser-neutral schema into a separate `vendor` section. | |
| */ | |
| function applyVendor(ast, vendorArgs) { | |
| if (!vendorArgs.length) return ast | |
| const specGroups = new Set(ast.filter((d) => d?.Type === 'group').map((d) => d.Name)) | |
| const vendorDefs = vendorArgs.flatMap((arg) => { | |
| const [namespace, file] = splitVendorArg(arg) | |
| return tagVendorDefs(parseCddl(file), namespace, specGroups) | |
| }) | |
| return [...ast, ...vendorDefs] | |
| } | |
| function splitVendorArg(arg) { | |
| const i = arg.indexOf('=') | |
| if (i <= 0) { | |
| console.error(`Error: --vendor-cddl expects <namespace>=<file>, got: ${arg}`) | |
| process.exit(1) | |
| } | |
| return [arg.slice(0, i), arg.slice(i + 1)] | |
| } | |
| const EXTENSION_SUFFIX = 'Extension' | |
| // Classify each vendor def and stamp the provenance the projector partitions on. A def named | |
| // `<Type>Extension` where `<Type>` is a spec group is an extension group in the convention | |
| // Mozilla's `Extensions.md` documents (read "as if included in that type"): the def is tagged | |
| // with the type it extends (`x-selenium-vendor-extends`, which the normalizer splices on) and | |
| // each field with `x-selenium-vendor` (namespace) and `x-selenium-vendor-via` (the group) — | |
| // the fields are what flow into the shared type. A `<Type>Extension` with no such spec group | |
| // is a mistake, not a helper type, so it fails loudly. Any other def (a helper type an | |
| // extension field references) is tagged on the def itself and stays whole. | |
| function tagVendorDefs(defs, namespace, specGroups) { | |
| for (const def of defs) { | |
| if (!def?.Name) continue | |
| if (!def.Name.endsWith(EXTENSION_SUFFIX)) { | |
| def['x-selenium-vendor'] = namespace | |
| continue | |
| } | |
| const target = def.Name.slice(0, -EXTENSION_SUFFIX.length) | |
| if (!specGroups.has(target)) { | |
| console.error(`Error: vendor extension group ${def.Name} (${namespace}) has no spec type ${target} to extend`) | |
| process.exit(1) | |
| } | |
| def['x-selenium-vendor-extends'] = target | |
| for (const p of (def.Properties ?? []).flat()) { | |
| if (!p || typeof p !== 'object' || !p.Name) continue | |
| p['x-selenium-vendor'] = namespace | |
| p['x-selenium-vendor-via'] = def.Name | |
| } | |
| } | |
| return defs | |
| } | |
| function readJson(fileArg, label) { | |
| const path = resolveInputPath(fileArg) | |
| if (!existsSync(path)) { | |
| console.error(`Error: ${label} file not found: ${path}`) | |
| process.exit(1) | |
| } | |
| return JSON.parse(readFileSync(path, 'utf8')) | |
| } | |
| function writeJson(fileArg, data, label, pretty = false) { | |
| const out = resolve(fileArg) | |
| writeFileSync(out, pretty ? JSON.stringify(data, null, 2) + '\n' : JSON.stringify(data), 'utf8') | |
| console.log(` → ${out} (${label})`) | |
| } | |
| /** Emit one TS module per domain: types and commands/events, both from bidi_schema.json. */ | |
| function generateTypeScript(ast, model, vendorModel, args) { | |
| const outputDir = resolve(args['output-dir']) | |
| const specVersion = args['spec-version'] | |
| const unmapped = Object.keys(model).filter((d) => !(d in DOMAIN_FILES)) | |
| if (unmapped.length) { | |
| throw new Error(`model domains without a DOMAIN_FILES/DOMAIN_CLASSES entry: ${unmapped.join(', ')}`) | |
| } | |
| console.log('Projecting the binding-neutral schema…') | |
| const schema = projectSchema(ast, model, {}, vendorModel) | |
| console.log( | |
| ` ${schema.commands.length} commands, ${schema.events.length} events, ${Object.keys(schema.types).length} types`, | |
| ) | |
| // A type a vendor extends keeps undeclared fields (`moz:name` on browsingContext.Info) instead of | |
| // dropping them, as the Ruby generator does; the vendor variant types only command params. | |
| for (const section of Object.values(schema.vendor ?? {})) { | |
| for (const typeName of Object.keys(section.extends ?? {})) { | |
| if (schema.types[typeName]) schema.types[typeName] = { ...schema.types[typeName], extensible: true } | |
| } | |
| } | |
| const typesByDomain = groupTypesByDomain(schema.types) | |
| const allCommands = schemaToCommands(schema) | |
| const allEvents = schemaToEvents(schema) | |
| mkdirSync(outputDir, { recursive: true }) | |
| for (const [domainKey, filename] of Object.entries(DOMAIN_FILES)) { | |
| const types = typesByDomain[domainKey] ?? {} | |
| const commands = allCommands.filter((c) => c.domain === domainKey) | |
| const events = allEvents.filter((e) => e.domain === domainKey) | |
| const className = DOMAIN_CLASSES[domainKey] | |
| const vendorModules = className ? buildVendorModules(schema, domainKey, className, commands) : [] | |
| const content = generateDomainFile({ | |
| domain: domainKey, | |
| className, | |
| types, | |
| commands, | |
| events, | |
| vendorModules, | |
| specVersion, | |
| }) | |
| const outPath = join(outputDir, filename) | |
| writeFileSync(outPath, content, 'utf8') | |
| console.log(` → ${outPath}`) | |
| } | |
| console.log('Done.') | |
| } | |
| // ============================================================ | |
| // Schema-derived domain grouping | |
| // ============================================================ | |
| /** A schema type name's domain segment, e.g. 'network.AddIntercept' -> 'network'. */ | |
| function domainForTypeName(name) { | |
| const dotIdx = name.indexOf('.') | |
| if (dotIdx === -1) return 'common' | |
| const domain = name.slice(0, dotIdx) | |
| return Object.hasOwn(DOMAIN_FILES, domain) ? domain : 'common' | |
| } | |
| /** Groups the schema's flat `types` map into `{ domain: { typeName: node } }`. */ | |
| function groupTypesByDomain(types) { | |
| const result = {} | |
| for (const [name, node] of Object.entries(types)) { | |
| const domain = domainForTypeName(name) | |
| ;(result[domain] ??= {})[name] = node | |
| } | |
| return result | |
| } | |
| // ============================================================ | |
| // Pass 2: AST analysis | |
| // ============================================================ | |
| /** | |
| * Returns the set of group names that carry no named parameters. | |
| * This includes truly empty groups AND groups whose only properties are | |
| * anonymous inclusions (e.g. `EmptyParams = { Extensible }`) — those are | |
| * extensibility markers with no protocol fields of their own. | |
| */ | |
| function buildEmptyParamTypes(ast) { | |
| const empty = new Set() | |
| for (const def of ast) { | |
| if (def.Type !== 'group' || !Array.isArray(def.Properties)) continue | |
| const flat = def.Properties.flatMap((p) => (Array.isArray(p) ? p : [p])) | |
| const hasNamedProp = flat.some((p) => p.Name && p.Name !== '') | |
| if (!hasNamedProp) empty.add(def.Name) | |
| } | |
| return empty | |
| } | |
| /** | |
| * Convert a dotted CDDL name to PascalCase TypeScript name. | |
| * "browsingContext.Info" → "BrowsingContextInfo" | |
| */ | |
| function normalizeDottedName(name) { | |
| return name | |
| .split('.') | |
| .map((part) => | |
| // A schema name segment may itself be hyphenated (e.g. the CDDL prelude | |
| // range aliases 'js-uint'/'js-int'), which isn't a valid TS identifier | |
| // character — split on '-' too so each word gets its own PascalCase turn. | |
| part | |
| .split('-') | |
| .map((word) => { | |
| const titled = word.charAt(0).toUpperCase() + word.slice(1) | |
| // Normalize acronym runs to match cddl2ts output: | |
| // CSPParameters → CspParameters HTMLCollection → HtmlCollection | |
| // Rule: 2+ uppercase letters followed by an uppercase+lowercase pair (or end | |
| // of string) → keep only the first uppercase and lowercase the rest. | |
| return titled.replace(/([A-Z]{2,})(?=[A-Z][a-z]|$)/g, (m) => m[0] + m.slice(1).toLowerCase()) | |
| }) | |
| .join(''), | |
| ) | |
| .join('') | |
| } | |
| /** | |
| * Walk the `CommandData` or `EventData` union type hierarchy and collect all | |
| * leaf definition names (the actual command/event group names). | |
| * | |
| * The CDDL AST represents union groups with Properties that can be: | |
| * - An array of choice objects (each with a Type.Value pointing to the next level) | |
| * - A single property object with Type as an array or direct object | |
| * | |
| * A leaf is a definition that itself has a `method` property (string literal). | |
| */ | |
| function collectUnionMembers(rootName, defMap, visited = new Set()) { | |
| if (visited.has(rootName)) return new Set() | |
| visited.add(rootName) | |
| const def = defMap.get(rootName) | |
| if (!def) return new Set() | |
| const members = new Set() | |
| // Flatten Properties — each element is either a choice-array or a property object. A one-member | |
| // aggregate (`MozCommand = webExtension.MozListExtensions`) parses as a variable holding a PropertyType. | |
| const rawProps = def.Properties ?? (def.Type === 'variable' ? [{ Type: def.PropertyType }] : []) | |
| const allChoices = [] | |
| for (const prop of rawProps) { | |
| if (Array.isArray(prop)) { | |
| allChoices.push(...prop) | |
| } else { | |
| allChoices.push(prop) | |
| } | |
| } | |
| for (const choice of allChoices) { | |
| // choice.Type can be a single object or an array of type alternatives. | |
| const typeEntries = Array.isArray(choice.Type) ? choice.Type : [choice.Type] | |
| for (const entry of typeEntries) { | |
| if (entry?.Type !== 'group' || !entry.Value) continue | |
| const childName = entry.Value | |
| const childDef = defMap.get(childName) | |
| if (!childDef) continue | |
| // A leaf has a `method` property — it is the actual command or event definition. | |
| const childProps = childDef.Properties ?? [] | |
| const flat = childProps.flatMap((p) => (Array.isArray(p) ? p : [p])) | |
| if (flat.some((p) => p.Name === 'method')) { | |
| members.add(childName) | |
| } else { | |
| // Intermediate union — recurse. | |
| for (const m of collectUnionMembers(childName, defMap, visited)) { | |
| members.add(m) | |
| } | |
| } | |
| } | |
| } | |
| return members | |
| } | |
| /** | |
| * Build a name → definition map from the AST (deduplicated — first wins). | |
| */ | |
| function buildDefMap(ast) { | |
| const map = new Map() | |
| for (const def of ast) { | |
| if (def.Name && !map.has(def.Name)) map.set(def.Name, def) | |
| } | |
| return map | |
| } | |
| /** Extract {domain, methodStr, operationName, paramsCddl} from a command/event leaf def. */ | |
| function parseLeafDef(def) { | |
| const flatProps = (def.Properties ?? []).flatMap((p) => (Array.isArray(p) ? p : [p])) | |
| const methodProp = flatProps.find((p) => p.Name === 'method') | |
| const paramsProp = flatProps.find((p) => p.Name === 'params') | |
| if (!methodProp || !paramsProp) return null | |
| const methodLiteral = Array.isArray(methodProp.Type) ? methodProp.Type : [methodProp.Type] | |
| if (methodLiteral[0]?.Type !== 'literal') return null | |
| const methodStr = methodLiteral[0].Value // e.g. "browser.createUserContext" | |
| const dotIdx = methodStr.indexOf('.') | |
| if (dotIdx === -1) return null | |
| const domain = methodStr.slice(0, dotIdx) | |
| const operationName = methodStr.slice(dotIdx + 1) | |
| // A vendor leaf (tagged by tagVendorDefs) carries its namespace into the model. | |
| const vendor = def['x-selenium-vendor'] | |
| const paramsTypeEntries = Array.isArray(paramsProp.Type) ? paramsProp.Type : [paramsProp.Type] | |
| let paramsCddl = null | |
| if (paramsTypeEntries[0]?.Type === 'group' && paramsTypeEntries[0]?.Value) { | |
| paramsCddl = paramsTypeEntries[0].Value | |
| } | |
| return { domain, methodStr, operationName, paramsCddl, vendor } | |
| } | |
| /** | |
| * Collect all leaf command/event names from every XxxCommand / XxxEvent | |
| * union that can be reached from either the core BiDi root (`CommandData` / | |
| * `EventData`) or from extension-spec roots (e.g. `PermissionsCommand`, | |
| * `SpeculationEvent`). Extension specs are not wired into `CommandData` / | |
| * `EventData` inside the core BiDi CDDL, so a second pass is required. | |
| */ | |
| function collectAllMembers(defMap, rootSuffix) { | |
| const members = new Set() | |
| // Primary traversal from the core BiDi root. | |
| const rootName = rootSuffix === 'Command' ? 'CommandData' : 'EventData' | |
| for (const m of collectUnionMembers(rootName, defMap)) members.add(m) | |
| // Secondary traversal: pick up any XxxCommand / XxxEvent unions in | |
| // extension specs whose members were not already found above. | |
| for (const [name, def] of defMap) { | |
| if (!name.endsWith(rootSuffix) || name === rootName) continue | |
| if (def.Type !== 'variable' && def.Type !== 'group') continue | |
| for (const m of collectUnionMembers(name, defMap)) members.add(m) | |
| } | |
| return members | |
| } | |
| /** Extract all BiDi commands by traversing CommandData and extension XxxCommand unions. */ | |
| function extractCommands(ast) { | |
| const defMap = buildDefMap(ast) | |
| const emptyParamTypes = buildEmptyParamTypes(ast) | |
| const commandNames = collectAllMembers(defMap, 'Command') | |
| const commands = [] | |
| for (const name of commandNames) { | |
| const def = defMap.get(name) | |
| if (!def) continue | |
| const parsed = parseLeafDef(def) | |
| if (!parsed) continue | |
| const { domain, methodStr, operationName: methodName, paramsCddl, vendor } = parsed | |
| // emptyParamTypes holds raw CDDL group names, so compare the raw name (not the normalized one). | |
| const hasParams = paramsCddl !== null && !emptyParamTypes.has(paramsCddl) | |
| commands.push({ | |
| domain, | |
| cddlName: name, | |
| methodStr, | |
| methodName, | |
| paramsCddl, | |
| hasParams, | |
| vendor, | |
| }) | |
| } | |
| return commands | |
| } | |
| /** Extract all BiDi events by traversing EventData and extension XxxEvent unions. */ | |
| function extractEvents(ast) { | |
| const defMap = buildDefMap(ast) | |
| const eventNames = collectAllMembers(defMap, 'Event') | |
| const events = [] | |
| for (const name of eventNames) { | |
| const def = defMap.get(name) | |
| if (!def) continue | |
| const parsed = parseLeafDef(def) | |
| if (!parsed) continue | |
| const { domain, methodStr, operationName: eventName, paramsCddl, vendor } = parsed | |
| events.push({ | |
| domain, | |
| methodStr, | |
| eventName, | |
| paramsCddl, | |
| vendor, | |
| }) | |
| } | |
| return events | |
| } | |
| // ============================================================ | |
| // Binding-neutral model | |
| // ============================================================ | |
| /** | |
| * Build the binding-neutral model from the AST. Type refs are CDDL names. | |
| * Shape per domain key: | |
| * { commands: [{ method, name, params, result }], | |
| * events: [{ method, name, params }] } | |
| * `params`/`result` are null when there are no params / no return value. | |
| */ | |
| function buildModel(ast) { | |
| const model = {} | |
| const resultTypes = buildResultTypeNames(ast) | |
| const ensure = (domain) => (model[domain] ??= { commands: [], events: [] }) | |
| // A vendor entry carries its namespace so the schema projector can file it under | |
| // `vendor.<namespace>`; spec entries carry none, so a vendor-free AST yields the same model. | |
| const provenance = (entry) => (entry.vendor ? { vendor: entry.vendor } : {}) | |
| for (const c of extractCommands(ast)) { | |
| const result = c.cddlName + 'Result' | |
| ensure(c.domain).commands.push({ | |
| method: c.methodStr, | |
| name: c.methodName, | |
| params: c.hasParams ? c.paramsCddl : null, | |
| result: resultTypes.has(result) ? result : null, | |
| ...provenance(c), | |
| }) | |
| } | |
| for (const e of extractEvents(ast)) { | |
| ensure(e.domain).events.push({ | |
| method: e.methodStr, | |
| name: e.eventName, | |
| params: e.paramsCddl || null, | |
| ...provenance(e), | |
| }) | |
| } | |
| return model | |
| } | |
| /** Result type names the spec defines with a value; an absent or `EmptyResult`-aliased result is void. */ | |
| function buildResultTypeNames(ast) { | |
| const emptyAlias = new Set() | |
| for (const d of ast) { | |
| const pt = d.PropertyType | |
| if (d.Name && d.Type === 'variable' && Array.isArray(pt) && pt.length === 1 && pt[0]?.Value === 'EmptyResult') { | |
| emptyAlias.add(d.Name) | |
| } | |
| } | |
| const names = new Set() | |
| for (const d of ast) { | |
| if (d.Name && d.Name.endsWith('Result') && !emptyAlias.has(d.Name)) names.add(d.Name) | |
| } | |
| return names | |
| } | |
| /** Map the schema's commands to the generator's command-entry shape. */ | |
| function schemaToCommands(schema) { | |
| return schema.commands.map(schemaToCommand) | |
| } | |
| function schemaToCommand(c) { | |
| return { | |
| domain: c.domain, | |
| methodStr: c.method, | |
| methodName: c.name, | |
| paramsTypeName: c.params ? normalizeDottedName(c.params.ref) : null, | |
| hasParams: c.params !== null, | |
| resultTypeName: c.result ? normalizeDottedName(c.result.ref) : null, | |
| } | |
| } | |
| // ============================================================ | |
| // Vendor variants (schema `vendor.<namespace>`) | |
| // ============================================================ | |
| /** | |
| * The vendor variants of one spec domain, one per namespace (`moz` → `MozWebExtension`), each a | |
| * subclass of the shared domain class, so a non-matching browser never sees a vendor field or | |
| * command. Mirrors Ruby's generator (bidi_generate.rb#vendor_modules_for): | |
| * | |
| * - a command whose params type a vendor extends (`webExtension.InstallParameters` + | |
| * `moz:permanent`) is overridden to take a params record of the shared fields plus the typed | |
| * vendor fields, which serialize under their exact wire keys; | |
| * - a command the vendor defines in the domain (`webExtension.moz:listExtensions`) is added, named | |
| * without its namespace (the class already scopes it), with the vendor types it reaches. | |
| * | |
| * Whole vendor domains (`moz:debugging`) are not emitted. Empty for a domain with no vendor | |
| * content, so non-vendor output is unaffected. | |
| * @returns {Array<{namespace: string, className: string, parentClassName: string, | |
| * types: Object<string, object>, commands: Array<object>}>} | |
| */ | |
| function buildVendorModules(schema, domain, parentClassName, specCommands) { | |
| const vendorTypes = Object.assign({}, ...Object.values(schema.vendor ?? {}).map((s) => s.types ?? {})) | |
| return Object.entries(schema.vendor ?? {}).flatMap(([namespace, section]) => { | |
| const stray = (section.events ?? []).find((e) => e.domain === domain) | |
| if (stray) { | |
| throw new Error(`vendor event ${stray.method} in spec domain ${domain} is unsupported`) | |
| } | |
| const types = {} | |
| const commands = [] | |
| for (const [typeName, entry] of Object.entries(section.extends ?? {})) { | |
| const cmd = schema.commands.find((c) => c.params?.ref === typeName) | |
| if (!cmd || cmd.domain !== domain) continue | |
| const base = schema.types[typeName] | |
| const taken = new Set(base.fields.map((f) => f.name)) | |
| const vendorFields = entry.fields.map((f) => ({ ...f, name: vendorFieldName(f.name, namespace, taken) })) | |
| const vendorTypeName = vendorExtendedTypeName(namespace, typeName) | |
| types[vendorTypeName] = { ...base, fields: [...base.fields, ...vendorFields] } | |
| commands.push({ ...schemaToCommand(cmd), paramsTypeName: normalizeDottedName(vendorTypeName) }) | |
| } | |
| const specNames = new Set(specCommands.map((c) => c.methodName)) | |
| for (const cmd of (section.commands ?? []).filter((c) => c.domain === domain)) { | |
| const methodName = cmd.name.replace(`${namespace}:`, '') | |
| if (specNames.has(methodName)) { | |
| throw new Error(`vendor command ${cmd.method} would override spec command ${domain}.${methodName}`) | |
| } | |
| commands.push({ ...schemaToCommand(cmd), methodName, specUrl: null }) | |
| for (const ref of [cmd.params?.ref, cmd.result?.ref].filter(Boolean)) { | |
| collectVendorTypes(ref, vendorTypes, types) | |
| } | |
| } | |
| if (commands.length === 0) return [] | |
| return [{ namespace, className: `${pascalCase(namespace)}${parentClassName}`, parentClassName, types, commands }] | |
| }) | |
| } | |
| /** Adds `name` and every vendor type it transitively references to `into`; spec types are left to their own domain. */ | |
| function collectVendorTypes(name, vendorTypes, into) { | |
| const node = vendorTypes[name] | |
| if (!node || Object.hasOwn(into, name)) return | |
| into[name] = node | |
| for (const ref of typeRefNames(node)) collectVendorTypes(ref, vendorTypes, into) | |
| } | |
| // 'webExtension.InstallParameters' → 'webExtension.MozInstallParameters', following the vendor's | |
| // own naming for the types it adds to a spec domain (webExtension.MozListExtensions). | |
| function vendorExtendedTypeName(namespace, typeName) { | |
| const dotIdx = typeName.indexOf('.') | |
| return `${typeName.slice(0, dotIdx + 1)}${pascalCase(namespace)}${typeName.slice(dotIdx + 1)}` | |
| } | |
| // A vendor field's JS name drops its namespace (`moz:permanent` → permanent): the vendor class | |
| // already scopes it. Its wire key is untouched. Keeps the namespace (`mozPermanent`) only if | |
| // dropping it would collide with a shared field on the same record. | |
| function vendorFieldName(name, namespace, taken) { | |
| const stripped = name.replace(`${namespace}:`, '') | |
| return taken.has(stripped) ? `${namespace}${pascalCase(stripped)}` : stripped | |
| } | |
| function pascalCase(word) { | |
| return word.charAt(0).toUpperCase() + word.slice(1) | |
| } | |
| /** Map the schema's events to the generator's event-entry shape. */ | |
| function schemaToEvents(schema) { | |
| return schema.events.map((e) => ({ | |
| domain: e.domain, | |
| methodStr: e.method, | |
| eventName: e.name, | |
| paramsTypeName: e.params ? normalizeDottedName(e.params.ref) : null, | |
| })) | |
| } | |
| // ============================================================ | |
| // Code generation | |
| // ============================================================ | |
| // Shared license + note text, copied next to this script by BUILD.bazel — see scripts/*.txt. | |
| const GENERATOR_DIR = dirname(fileURLToPath(import.meta.url)) | |
| const commentLines = (text) => | |
| text | |
| .split('\n') | |
| .map((line) => `// ${line}`.trimEnd()) | |
| .join('\n') | |
| const LICENSE_HEADER = commentLines(readFileSync(join(GENERATOR_DIR, 'license_header.txt'), 'utf8').replace(/\n$/, '')) | |
| const GENERATED_NOTE = commentLines( | |
| readFileSync(join(GENERATOR_DIR, 'generated_note_template.txt'), 'utf8') | |
| .replace('{generator}', 'javascript/selenium-webdriver/generate_bidi.mjs') | |
| .replace('{command}', 'bazel build //javascript/selenium-webdriver:create-bidi-src') | |
| .trim(), | |
| ) | |
| // ============================================================ | |
| // Schema type node -> TypeScript, and cross-domain imports | |
| // ============================================================ | |
| const PRIMITIVE_TS = { string: 'string', integer: 'number', number: 'number', boolean: 'boolean', null: 'null' } | |
| /** Converts a schema type-ref node into a TypeScript type expression. */ | |
| function typeNodeToTs(node) { | |
| if (!node) return 'unknown' | |
| let base | |
| // Before `primitive`: an inline literal choice (a vendor field such as `moz:scope`) carries both. | |
| if (node.enum !== undefined) { | |
| base = node.enum.map((v) => JSON.stringify(v)).join(' | ') | |
| } else if (node.primitive !== undefined) { | |
| base = PRIMITIVE_TS[node.primitive] ?? 'unknown' | |
| } else if (node.const !== undefined) { | |
| base = JSON.stringify(node.const) | |
| } else if (node.ref !== undefined) { | |
| base = normalizeDottedName(node.ref) | |
| } else if (node.list !== undefined) { | |
| base = `Array<${typeNodeToTs(node.list)}>` | |
| } else if (node.map !== undefined) { | |
| base = `Record<string, ${typeNodeToTs(node.map)}>` | |
| } else if (node.union !== undefined) { | |
| base = node.union.map((v) => typeNodeToTs(v)).join(' | ') | |
| } else { | |
| base = 'unknown' | |
| } | |
| return node.nullable ? `${base} | null` : base | |
| } | |
| /** The type-name refs a projected ref node points at (list/map/union recurse). */ | |
| function refsIn(node) { | |
| if (!node) return [] | |
| if (node.ref) return [node.ref] | |
| if (node.list) return refsIn(node.list) | |
| if (node.map) return refsIn(node.map) | |
| if (node.union) return node.union.flatMap(refsIn) | |
| return [] | |
| } | |
| /** The type-name refs a type *node* (record/union/alias) points at. */ | |
| function typeRefNames(node) { | |
| if (node.kind === 'record') { | |
| const refs = node.fields.flatMap((f) => refsIn(f.type)) | |
| if (node.map) refs.push(...refsIn(node.map)) | |
| return refs | |
| } | |
| if (node.kind === 'union') return node.variants | |
| if (node.kind === 'alias') return refsIn(node.type) | |
| return [] | |
| } | |
| /** | |
| * Import statements for every other-domain type this domain's types reference: a | |
| * type-only import for the TS names themselves, plus a plain side-effect import of | |
| * the same module. The type-only import is erased at compile time (it exists purely | |
| * for `tsc`), so it registers nothing at runtime — a caller who only imports, say, | |
| * `session.js` would never actually load `browsing_context.js`, leaving every | |
| * `browsingContext.*` type unregistered in the shared runtime registry (registry.js) | |
| * and silently skipping deep validation for any field that refs one (see | |
| * validateValue()'s `if (referenced === undefined) return value` in record.js). | |
| * The side-effect import forces that module to load — and therefore register its | |
| * types — regardless of whether this domain is used standalone. Safe even when two | |
| * domains reference each other (e.g. session <-> browsingContext): CommonJS resolves | |
| * a require() cycle by returning the other module's not-yet-complete exports, but a | |
| * bare side-effect import binds nothing, and no type here is read at define time | |
| * anyway — resolution happens lazily, at validation time (registry.js), by which | |
| * point both modules have finished loading. | |
| */ | |
| function computeCrossDomainImports(types, domain) { | |
| const bySourceDomain = new Map() | |
| for (const node of Object.values(types)) { | |
| for (const ref of typeRefNames(node)) { | |
| const sourceDomain = domainForTypeName(ref) | |
| if (sourceDomain === domain) continue | |
| if (!bySourceDomain.has(sourceDomain)) bySourceDomain.set(sourceDomain, new Set()) | |
| bySourceDomain.get(sourceDomain).add(normalizeDottedName(ref)) | |
| } | |
| } | |
| const imports = [] | |
| for (const [sourceDomain, names] of [...bySourceDomain.entries()].sort()) { | |
| const sourceFile = DOMAIN_FILES[sourceDomain].replace('.ts', '.js') | |
| imports.push(`import type { ${[...names].sort().join(', ')} } from './${sourceFile}'`) | |
| imports.push(`import './${sourceFile}'`) | |
| } | |
| return imports | |
| } | |
| /** | |
| * Emits one schema type's TS declaration plus the runtime call that registers | |
| * it for validation — see bidi/serialization/{record,enum,union}.js. Returns | |
| * the runtime binding's own name and kind too, so a command method in the | |
| * same domain can reference it directly (e.g. to validate its params before | |
| * sending, or parse its result via fromWire()) rather than only reaching | |
| * nested/cross-domain refs indirectly through the shared registry. | |
| */ | |
| function generateTypeDeclaration(name, node) { | |
| const tsName = normalizeDottedName(name) | |
| if (node.kind === 'enum') { | |
| const runtimeName = `${tsName}Enum` | |
| const literal = node.values.map((v) => JSON.stringify(v)).join(' | ') | |
| const ts = [ | |
| `export type ${tsName} = ${literal}`, | |
| `const ${runtimeName} = defineEnum<${tsName}>('${name}', ${JSON.stringify(node.values)})`, | |
| ].join('\n') | |
| return { ts, runtimeName, kind: 'enum' } | |
| } | |
| if (node.kind === 'alias') { | |
| const ts = [ | |
| `export type ${tsName} = ${typeNodeToTs(node.type)}`, | |
| `defineAlias('${name}', ${JSON.stringify(node.type)})`, | |
| ].join('\n') | |
| return { ts, runtimeName: null, kind: 'alias' } | |
| } | |
| if (node.kind === 'record') { | |
| // No suffix: an interface and a const may share one name in TS (they live in | |
| // separate type/value spaces, and only the const survives compilation to JS) — | |
| // verified this compiles clean. Two names for one concept was self-inflicted | |
| // confusion, not a real requirement; Ruby's generator uses one name too. | |
| const runtimeName = tsName | |
| const lines = [`export interface ${tsName} {`] | |
| for (const field of node.fields) { | |
| // Tolerating a missing required field's absence is no longer required — | |
| // fromWire() now rejects a missing required field the same as any other | |
| // invalid value, so a required field is always present, nullable or not. | |
| const optional = !field.required | |
| lines.push(` ${field.name}${optional ? '?' : ''}: ${typeNodeToTs(field.type)}`) | |
| } | |
| lines.push(`}`) | |
| const optionsArg = node.extensible ? `, ${JSON.stringify({ extensible: true })}` : '' | |
| lines.push(`const ${runtimeName} = defineRecord<${tsName}>('${name}', ${JSON.stringify(node.fields)}${optionsArg})`) | |
| return { ts: lines.join('\n'), runtimeName, kind: 'record' } | |
| } | |
| if (node.kind === 'union') { | |
| const runtimeName = `${tsName}Union` | |
| const memberNames = node.variants.map((v) => normalizeDottedName(v)) | |
| const options = {} | |
| if (node.objectOnly) options.objectOnly = true | |
| const optionsArg = Object.keys(options).length ? `, ${JSON.stringify(options)}` : '' | |
| const ts = [ | |
| `export type ${tsName} = ${memberNames.join(' | ')}`, | |
| `const ${runtimeName} = defineUnion<${tsName}>('${name}', ${JSON.stringify(node.selector)}${optionsArg})`, | |
| ].join('\n') | |
| return { ts, runtimeName, kind: 'union' } | |
| } | |
| return { ts: `export type ${tsName} = unknown`, runtimeName: null, kind: 'unknown' } | |
| } | |
| /** | |
| * Follows an alias chain (an alias can point at another alias) to the record/union | |
| * it ultimately resolves to, within `types` — one domain's own type map, the same | |
| * shape generateDomainFile already has, so this needs no extra generator plumbing. | |
| * Only a same-domain target is resolvable this way: a cross-domain alias (by far the | |
| * most common case — `-> EmptyResult`, used across every domain) would need the target's | |
| * runtime binding imported as a *value*, not just a type, from another domain's compiled | |
| * file — real plumbing this doesn't attempt. Left unresolved there deliberately: EmptyResult | |
| * has no required fields, so an unchecked cast catches nothing a fromWire() call would | |
| * have caught either way — there's no actual validation gap to close for that case, only | |
| * for a same-domain alias to a record/union that has real fields (or variants) to check. | |
| * @returns {{runtimeName: string, kind: 'record'|'union'}|null} | |
| */ | |
| function resolveAliasRuntime(node, types) { | |
| const seen = new Set() | |
| let current = node | |
| while (current?.kind === 'alias' && current.type?.ref && !seen.has(current.type.ref)) { | |
| seen.add(current.type.ref) | |
| const targetName = current.type.ref | |
| const target = types[targetName] | |
| if (target === undefined) return null // not in this domain — cross-domain, left unresolved | |
| if (target.kind === 'record') return { runtimeName: normalizeDottedName(targetName), kind: 'record' } | |
| if (target.kind === 'union') return { runtimeName: `${normalizeDottedName(targetName)}Union`, kind: 'union' } | |
| current = target // another alias — keep resolving | |
| } | |
| return null | |
| } | |
| function generateDomainFile({ domain, className, types, commands, events, vendorModules = [], specVersion }) { | |
| const parts = [LICENSE_HEADER, '', GENERATED_NOTE] | |
| parts.push(`// Built from the WebDriver BiDi CDDL spec (v${specVersion}).`) | |
| parts.push(`// Source: https://github.com/w3c/webref/tree/main/ed/cddl`) | |
| parts.push('') | |
| const hasImplementation = className != null && (commands.length > 0 || events.length > 0) | |
| // Vendor types follow the spec's, and are tagged with the vendor class that owns their enum constants. | |
| const vendorTypeOwner = new Map(vendorModules.flatMap((m) => Object.keys(m.types).map((name) => [name, m]))) | |
| const allTypes = Object.assign({}, types, ...vendorModules.map((m) => m.types)) | |
| const typeEntries = Object.entries(allTypes) | |
| const crossDomainImports = computeCrossDomainImports(allTypes, domain) | |
| if (crossDomainImports.length > 0) { | |
| for (const line of crossDomainImports) parts.push(line) | |
| parts.push('') | |
| } | |
| if (typeEntries.length > 0) { | |
| parts.push(`import { defineRecord, defineAlias } from '../serialization/record.js'`) | |
| parts.push(`import { defineEnum } from '../serialization/enum.js'`) | |
| parts.push(`import { defineUnion } from '../serialization/union.js'`) | |
| parts.push('') | |
| } | |
| if (hasImplementation) { | |
| // Domain.connect(driver) reaches the one BiDi connection for `driver` | |
| // through the real internal accessor (never the deprecated driver.getBidi()). | |
| parts.push(`import { Domain, event, type EventDescriptor, DOMAIN_TOKEN } from '../domain.js'`) | |
| parts.push('') | |
| } | |
| // tsName -> {runtimeName, kind, fields?}, so a command method in this same file | |
| // can validate its own params/result directly (rather than only reaching | |
| // nested/cross-domain refs indirectly through the shared registry) and document | |
| // each params field in its JSDoc from the same field list, not a second copy. | |
| const runtimeByTsName = new Map() | |
| // Enum constants owned by this domain, exposed as a discoverable static property | |
| // on the domain class (or a top-level export when there's no class to attach to) — | |
| // e.g. Network.SameSite = { STRICT: 'strict', ... }, mirroring how Ruby's generator | |
| // exposes Network::SAME_SITE as a real, inspectable constant rather than a bare string. | |
| const enumConstants = [] | |
| if (typeEntries.length > 0) { | |
| parts.push(`// --- Types ---`) | |
| parts.push('') | |
| for (const [name, node] of typeEntries) { | |
| const declared = generateTypeDeclaration(name, node) | |
| const tsName = normalizeDottedName(name) | |
| if (declared.runtimeName) { | |
| runtimeByTsName.set(tsName, { | |
| runtimeName: declared.runtimeName, | |
| kind: declared.kind, | |
| fields: node.kind === 'record' ? node.fields : undefined, | |
| }) | |
| } else if (declared.kind === 'alias') { | |
| // An alias itself has no RecordClass/UnionClass of its own (declared.runtimeName | |
| // is null, see generateTypeDeclaration) — but when it ultimately points at a | |
| // same-domain record/union, a command whose result *is* that alias (e.g. | |
| // browser.CreateUserContextResult -> browser.UserContextInfo) should still | |
| // validate inbound through fromWire(), not silently cast an unchecked response. | |
| // Resolved by naming convention (a record's runtime const is its own tsName; a | |
| // union's is `${tsName}Union`), not by depending on the target having already | |
| // been processed — types is a complete map regardless of iteration order. | |
| const resolved = resolveAliasRuntime(node, allTypes) | |
| if (resolved) runtimeByTsName.set(tsName, { ...resolved, fields: undefined }) | |
| } | |
| if (declared.kind === 'enum') { | |
| const constant = { propertyName: localSchemaName(name, tsName), values: node.values } | |
| const owner = vendorTypeOwner.get(name) | |
| if (owner) (owner.enumConstants ??= []).push(constant) | |
| else enumConstants.push(constant) | |
| } | |
| parts.push(declared.ts) | |
| parts.push('') | |
| } | |
| } | |
| if (!hasImplementation && enumConstants.length > 0) { | |
| parts.push(`// --- Enum constants ---`) | |
| parts.push('') | |
| for (const { propertyName, values } of enumConstants) { | |
| parts.push(`export const ${propertyName} = ${generateEnumConstantLiteral(values)}`) | |
| } | |
| parts.push('') | |
| } | |
| if (hasImplementation) { | |
| parts.push(`// --- Implementation ---`) | |
| parts.push('') | |
| parts.push( | |
| generateClass({ | |
| className, | |
| commands, | |
| events, | |
| runtimeByTsName, | |
| enumConstants, | |
| }), | |
| ) | |
| for (const vendor of vendorModules) { | |
| parts.push('') | |
| parts.push( | |
| generateClass({ | |
| className: vendor.className, | |
| parentClassName: vendor.parentClassName, | |
| summary: [ | |
| `${vendor.namespace}: vendor variant of ${vendor.parentClassName}, with browser-specific commands and params.`, | |
| `Construct with ${vendor.className}.create(driver) for a matching session; other sessions use ${vendor.parentClassName}.`, | |
| ], | |
| commands: vendor.commands, | |
| events: [], | |
| runtimeByTsName, | |
| enumConstants: vendor.enumConstants ?? [], | |
| }), | |
| ) | |
| } | |
| } | |
| return parts.join('\n') + '\n' | |
| } | |
| // Disclaimer attached to every generated class — matches Java's BiDiGenerator. | |
| const INTERNAL_API_DOC = [ | |
| '/**', | |
| ' * This is an unsupported API. No compatibility guarantees are provided.', | |
| ' * It tracks the W3C WebDriver BiDi specification directly. As the specification', | |
| ' * evolves, this API will change or be removed without prior notice.', | |
| ' */', | |
| ].join('\n') | |
| // camelCase -> SCREAMING_SNAKE_CASE, for event descriptor constant names | |
| // ("beforeRequestSent" -> "BEFORE_REQUEST_SENT") and enum constant keys | |
| // ("beforeRequestSent" -> "BEFORE_REQUEST_SENT", "strict" -> "STRICT"). | |
| function screamingSnakeCase(camel) { | |
| return camel.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase() | |
| } | |
| // The un-prefixed local segment of a dotted schema name, PascalCased — | |
| // 'network.InterceptPhase' -> 'InterceptPhase'. Used for a static enum constant's | |
| // property name on its owning domain class, where the class already implies the | |
| // domain (Network.InterceptPhase, not Network.NetworkInterceptPhase). | |
| function localSchemaName(name, tsNameFallback) { | |
| const dotIdx = name.indexOf('.') | |
| return dotIdx === -1 ? tsNameFallback : normalizeDottedName(name.slice(dotIdx + 1)) | |
| } | |
| // A valid JS identifier for an enum constant's key, derived from its wire value. | |
| // Unlike event/method names (always clean camelCase), some enum values are | |
| // space- or hyphen-separated (error.ErrorCode: "invalid argument", emulation. | |
| // ScreenOrientationType: "portrait-primary") or start with a character no JS | |
| // identifier can (script.SpecialNumber: "-0", "-Infinity") — normalize those | |
| // separators to underscores, and guard a still-invalid leading digit, before | |
| // screamingSnakeCase's uppercasing, so every generated key actually parses. | |
| function enumConstantKey(value) { | |
| const key = screamingSnakeCase(String(value).replace(/[-\s]+/g, '_')) | |
| return /^[0-9]/.test(key) ? `_${key}` : key | |
| } | |
| // A frozen, inspectable object literal for an enum's values — the JS-idiomatic | |
| // answer to Ruby's `Network::INTERCEPT_PHASE` constant (see | |
| // serialization.rb's Serialization module): a real value a caller can log, | |
| // autocomplete on, or iterate, instead of a bare string they have to already know. | |
| // Raw string values (e.g. 'beforeRequestSent') keep working unchanged — this is | |
| // purely an additional, discoverable way to reach the same values. | |
| function generateEnumConstantLiteral(values) { | |
| const entries = values.map((v) => `${enumConstantKey(v)}: ${JSON.stringify(v)}`).join(', ') | |
| return `Object.freeze({ ${entries} } as const)` | |
| } | |
| // The WebDriver BiDi spec's own anchor format for a command/event section | |
| // (e.g. '#command-network-addIntercept', '#event-network-beforeRequestSent') — | |
| // matches the @see links Ruby's generator emits for the same commands/events. | |
| function specSectionUrl(methodStr, kind) { | |
| const [domain, local] = methodStr.split('.') | |
| return `https://w3c.github.io/webdriver-bidi/#${kind}-${domain}-${local}` | |
| } | |
| function generateClass({ | |
| className, | |
| parentClassName = 'Domain', | |
| summary = [], | |
| commands, | |
| events, | |
| runtimeByTsName, | |
| enumConstants, | |
| }) { | |
| const lines = [] | |
| const doc = INTERNAL_API_DOC.split('\n') | |
| if (summary.length) doc.splice(1, 0, ...summary.map((line) => ` * ${line}`), ' *') | |
| lines.push(doc.join('\n')) | |
| lines.push(`export class ${className} extends ${parentClassName} {`) | |
| for (const evt of events) { | |
| lines.push('') | |
| lines.push(generateEventDescriptor(evt, runtimeByTsName)) | |
| } | |
| for (const { propertyName, values } of enumConstants) { | |
| lines.push('') | |
| lines.push(` static readonly ${propertyName} = ${generateEnumConstantLiteral(values)}`) | |
| } | |
| lines.push('') | |
| lines.push(` static async create(driver: unknown): Promise<${className}> {`) | |
| lines.push(` return new ${className}(await Domain.connect(driver), DOMAIN_TOKEN)`) | |
| lines.push(` }`) | |
| for (const cmd of commands) { | |
| lines.push('') | |
| lines.push(generateCommandMethod(cmd, runtimeByTsName)) | |
| } | |
| lines.push(`}`) | |
| return lines.join('\n') | |
| } | |
| // A static EventDescriptor<T> constant — no subscribe/dispatch method. Callers | |
| // reach events via the inherited addCallback(descriptor, handler), never a | |
| // per-event generated method. When the params type has a registered runtime | |
| // (record/union), it's passed to event() so addCallback() can validate each | |
| // delivered payload through fromWire() before the caller's handler runs. | |
| function generateEventDescriptor(evt, runtimeByTsName) { | |
| const { eventName, methodStr, paramsTypeName } = evt | |
| const paramsType = paramsTypeName ?? 'unknown' | |
| const constName = screamingSnakeCase(eventName) | |
| const paramsRuntime = paramsTypeName ? runtimeByTsName.get(paramsTypeName) : undefined | |
| const runtimeArg = | |
| paramsRuntime?.kind === 'record' || paramsRuntime?.kind === 'union' ? `, ${paramsRuntime.runtimeName}` : '' | |
| const doc = ` /** @see ${specSectionUrl(methodStr, 'event')} */` | |
| return `${doc}\n static readonly ${constName}: EventDescriptor<${paramsType}> = event('${methodStr}'${runtimeArg})` | |
| } | |
| // A JSDoc block for a generated command method — readable without any TypeScript | |
| // tooling, since a plain-JS user gets no autocomplete from the sibling .d.ts unless | |
| // their editor happens to resolve it. Unrolls each params field individually (from | |
| // the same field list defineRecord() validates against, not a second copy of it) so | |
| // required vs. optional is visible in an ordinary hover, matching what Ruby's | |
| // generator gives for free via real keyword arguments in the method signature. | |
| function generateCommandJsDoc(cmd, paramsRuntime, resultTypeName) { | |
| const { methodStr, paramsTypeName, hasParams } = cmd | |
| const lines = [' /**'] | |
| if (hasParams) { | |
| lines.push(` * @param {${paramsTypeName}} params`) | |
| for (const field of paramsRuntime?.fields ?? []) { | |
| const tsType = typeNodeToTs(field.type) | |
| const tag = field.required ? `params.${field.name}` : `[params.${field.name}]` | |
| lines.push(` * @param {${tsType}} ${tag}`) | |
| } | |
| } | |
| lines.push(` * @returns {Promise<${resultTypeName ?? 'void'}>}`) | |
| // A vendor-defined command has no section in the spec (specUrl: null). | |
| const specUrl = cmd.specUrl === undefined ? specSectionUrl(methodStr, 'command') : cmd.specUrl | |
| if (specUrl) lines.push(` * @see ${specUrl}`) | |
| lines.push(' */') | |
| return lines.join('\n') | |
| } | |
| function generateCommandMethod(cmd, runtimeByTsName) { | |
| const { methodName, methodStr, paramsTypeName, hasParams, resultTypeName } = cmd | |
| const isVoid = resultTypeName === null | |
| const returnType = isVoid ? 'void' : resultTypeName | |
| // Use a double-cast (T as unknown as Record<string,unknown>) so TypeScript | |
| // accepts the conversion even when the params type has no index signature. | |
| // Only actually used when there's no RecordClass/UnionClass to build a validated | |
| // instance from below (paramsRuntime undefined) — otherwise sendArg overrides it. | |
| const paramsCast = hasParams ? '(params as unknown as Record<string, unknown>)' : '{}' | |
| const paramsRuntime = hasParams ? runtimeByTsName.get(paramsTypeName) : undefined | |
| const resultRuntime = !isVoid ? runtimeByTsName.get(resultTypeName) : undefined | |
| const lines = [generateCommandJsDoc(cmd, paramsRuntime, isVoid ? null : resultTypeName)] | |
| if (hasParams) { | |
| lines.push(` async ${methodName}(params: ${paramsTypeName}): Promise<${returnType}> {`) | |
| } else { | |
| lines.push(` async ${methodName}(): Promise<${returnType}> {`) | |
| } | |
| // Outbound validation: constructing/building the params record throws on a violation | |
| // before anything reaches the wire. Takes the original typed `params` directly | |
| // (matching RecordClass<T>'s `new (data: T)`), not the Record<string, unknown> cast | |
| // meant only for the wire send() call below. The *validated* instance — not the | |
| // caller's original `params` — is what actually gets sent: its toJSON() is what | |
| // converts JS-facing field names (params.prefersColorScheme) to their declared wire | |
| // keys (prefers-color-scheme), including on any nested record/union field. | |
| let sendArg = paramsCast | |
| if (paramsRuntime?.kind === 'record') { | |
| lines.push(` const validatedParams = new ${paramsRuntime.runtimeName}(params)`) | |
| sendArg = '(validatedParams as unknown as Record<string, unknown>)' | |
| } else if (paramsRuntime?.kind === 'union') { | |
| lines.push(` const validatedParams = ${paramsRuntime.runtimeName}.build(params)`) | |
| sendArg = '(validatedParams as unknown as Record<string, unknown>)' | |
| } | |
| // Domain.send() already checks for an error response and throws. Inbound | |
| // validation then runs through the result's own fromWire() when one is | |
| // registered; otherwise the result is cast as before. | |
| if (isVoid) { | |
| lines.push(` await this.send('${methodStr}', ${sendArg})`) | |
| } else if (resultRuntime?.kind === 'record' || resultRuntime?.kind === 'union') { | |
| lines.push(` const result = await this.send('${methodStr}', ${sendArg})`) | |
| lines.push(` return ${resultRuntime.runtimeName}.fromWire(result) as unknown as ${resultTypeName}`) | |
| } else { | |
| lines.push(` return (await this.send('${methodStr}', ${sendArg})) as ${resultTypeName}`) | |
| } | |
| lines.push(` }`) | |
| return lines.join('\n') | |
| } | |
| // ============================================================ | |
| // Entry point | |
| // ============================================================ | |
| main().catch((err) => { | |
| console.error(err) | |
| process.exit(1) | |
| }) |