From 6fb4b8335de7d1bc277b393833851948e0517544 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Thu, 19 Nov 2026 14:25:30 -0800 Subject: [PATCH 1/2] chore: generate the API from the upstream docs with a TypeScript script scripts/generate_java_api.mts parses docs/src/api/*.md of the upstream checkout with the upstream parser and writes the Java interfaces, options classes and enums. It replaces tools/api-generator and the intermediate api.json. The generated files do not change. --- .claude/skills/playwright-roll/SKILL.md | 17 +- .github/workflows/verify_api.yml | 2 - AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- scripts/generate_api.sh | 14 +- scripts/generate_java_api.mts | 1090 ++++++++++++ tools/api-generator/pom.xml | 41 - .../playwright/tools/ApiGenerator.java | 1500 ----------------- .../src/main/resources/.gitignore | 1 - 9 files changed, 1104 insertions(+), 1565 deletions(-) create mode 100644 scripts/generate_java_api.mts delete mode 100644 tools/api-generator/pom.xml delete mode 100644 tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java delete mode 100644 tools/api-generator/src/main/resources/.gitignore diff --git a/.claude/skills/playwright-roll/SKILL.md b/.claude/skills/playwright-roll/SKILL.md index 9649b9eed..000e37a19 100644 --- a/.claude/skills/playwright-roll/SKILL.md +++ b/.claude/skills/playwright-roll/SKILL.md @@ -32,7 +32,7 @@ new=$(cat scripts/DRIVER_VERSION) List the upstream commits between the two commits that changed a path the Java client depends on: -- `docs/src/api/` — the source of `api.json`. A new or removed method or option, or a changed `langs:` filter, comes from here. +- `docs/src/api/` — the input of the API generator. A new or removed method or option, or a changed `langs:` filter, comes from here. - `packages/playwright-core/src/client/` — the JS client. The Java client is a port of it. - `packages/isomorphic/` — selector engines, locator generation and parsing, and the aria snapshot code. The client and the server share this code. A change here can change client helpers such as `getByRoleSelector`. - `packages/playwright/src/matchers/matchers.ts` — the assertion methods. A change here is usually a new option of `LocatorAssertions` or `PageAssertions`. @@ -108,26 +108,25 @@ Key translation rules: After running `./scripts/roll_driver.sh`, the build often fails because the generated Java interfaces reference new types or methods that the generator doesn't know how to handle yet, and the `*Impl` classes don't implement new interface methods. -### ApiGenerator.java fixes (tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java) +### API generator fixes (scripts/generate_java_api.mts) -The generator has hardcoded lists that control which imports are added to each generated file. When new classes appear in the API, add them to the relevant lists in `Interface.writeTo`: +The generator has hardcoded lists that control which imports are added to each generated file. When new classes appear in the API, add them to the relevant lists in `INTERFACE_IMPORTS`: - `options.*` import list — add new classes that use types from the options package - `java.util.*` import list — add new classes that use `List`, `Map`, etc. - `java.util.function.Consumer` list — add new classes with `Consumer`-typed event handlers -Type mapping: when JS-only types (like `Disposable`) are used as return types in Java-compatible methods, add a mapping in `convertBuiltinType`. For example, `Disposable` → `AutoCloseable`. +Type mapping: when JS-only types (like `Disposable`) are used as return types in Java-compatible methods, add a mapping in `BUILTIN_TYPES`. For example, `Disposable` → `AutoCloseable`. Event handler generation: events with `void` type generate invalid `Consumer`. Handle this case in `Event.writeListenerMethods` by emitting `Runnable` instead. Type names: give every new object type an explicit alias upstream. When a roll brings in a new object type (an option or return value written as `<[Object]>` in `docs/src/api/`), it should usually have its own `* alias: ` line. Without one, each language's generator makes up a name, and the Java one can be vague (e.g. `Style`) or differ between Java and .NET. - Prefer a plain `alias:` so every language gets the same name. Use `alias-java:` / `alias-csharp:` only when a language really needs a different name. -- Add the aliases in a small upstream docs PR (e.g. microsoft/playwright#43164, `Style` → `ScreencastActionStyle`). Don't special-case names in `ApiGenerator`. +- Add the aliases in a small upstream docs PR (e.g. microsoft/playwright#43164, `Style` → `ScreencastActionStyle`). Don't special-case names in the generator. - After the upstream change lands, roll to a driver that includes it. Don't hand-edit the generated files. -After editing the generator, recompile and re-run it: +After editing the generator, re-run it. Node.js runs the TypeScript file as is: ``` -mvn -f tools/api-generator/pom.xml compile -q -mvn -f tools/api-generator/pom.xml exec:java -Dexec.mainClass=com.microsoft.playwright.tools.ApiGenerator +node scripts/generate_java_api.mts .upstream ``` ### Impl class fixes (playwright/src/main/java/com/microsoft/playwright/impl/) @@ -161,7 +160,7 @@ Common patterns: ## Rebuilding the driver modules after a roll -`./scripts/roll_driver.sh` does the full roll. It moves `scripts/DRIVER_VERSION` to the new commit. It builds the driver from `.upstream/` into `driver/src/main/resources/driver/package/` and `driver-bundle/src/main/resources/driver//`. It generates `api.json` and the Java interfaces, and it updates the README. If all steps pass, the next `mvn` command uses the new driver. +`./scripts/roll_driver.sh` does the full roll. It moves `scripts/DRIVER_VERSION` to the new commit. It builds the driver from `.upstream/` into `driver/src/main/resources/driver/package/` and `driver-bundle/src/main/resources/driver//`. It generates the Java interfaces from the upstream docs, and it updates the README. If all steps pass, the next `mvn` command uses the new driver. If a step fails, the script stops before Maven installs the new driver. The most frequent cause is the API generator, which fails on a new type (see *Fixing generator and compilation errors*). After that, the test JVM loads the **old** driver from `target/classes` or from the installed jar, although the source resources already hold the new driver. diff --git a/.github/workflows/verify_api.yml b/.github/workflows/verify_api.yml index 1c6025d26..d450ee716 100644 --- a/.github/workflows/verify_api.yml +++ b/.github/workflows/verify_api.yml @@ -6,14 +6,12 @@ on: - release-* paths: - 'scripts/*' - - 'api-generator/*' pull_request: branches: - main - release-* paths: - 'scripts/**' - - 'api-generator/**' jobs: verify: timeout-minutes: 30 diff --git a/AGENTS.md b/AGENTS.md index 21dbae869..598051faa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Paths such as `~/code/playwright` in this file assume that you check the repos o - **The driver.** The Java client talks to the Node.js driver. The driver is the `playwright-core` package of `microsoft/playwright`. We build it from source at the commit in `scripts/DRIVER_VERSION`. `scripts/build_driver.sh` clones `microsoft/playwright` into `.upstream/` (gitignored), checks out that commit, builds it and puts the package into `driver/src/main/resources/driver/package/`. Do not edit, commit or switch branches in `.upstream/`. `scripts/roll_driver.sh` moves the commit: to the tip of upstream `main`, to the tip of an upstream `release-1.X` branch, or to an exact commit. We do not use the published npm packages or their versions. `git show v1.X.0:scripts/DRIVER_VERSION` prints the upstream commit of a release. For releases up to 1.65, it prints the `playwright-core` version of the driver. - **Upstream code.** In `.upstream/`, at the commit of the driver, or in `~/code/playwright`, which may be ahead of it: the client in `packages/playwright-core/src/client/`, the API docs in `docs/src/api/`, the tests in `tests/page/` and `tests/library/`. Its `AGENTS.md` says how to build it and run a test. - **Where a bug is.** When the same calls fail in a Node.js test upstream too, the cause is in the driver or a browser, and the fix lands in `microsoft/playwright`. When Node.js passes, the bug is in the Java client: compare the `*Impl.java` with its JavaScript counterpart, and fix it here. -- **The generated API.** `scripts/generate_api.sh` runs `utils/doclint/generateApiJson.js` of `.upstream/`, and `tools/api-generator` writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `assertions/PlaywrightAssertions.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream. +- **The generated API.** `scripts/generate_api.sh` runs `scripts/generate_java_api.mts`. It parses `docs/src/api/*.md` of `.upstream/` with the upstream parser (`utils/doclint/api_parser.js`) and writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `assertions/PlaywrightAssertions.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream. ## Build and test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85b707fce..1e4d1c2c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,7 @@ with a `@Fixture` method reading its `@Parameter` field to run the same tests wi ### Generating API -Public Java API is generated from api.json, which is generated from `.upstream/`, the `microsoft/playwright` checkout at the commit in [scripts/DRIVER_VERSION](scripts/DRIVER_VERSION) that the driver is built from (run `scripts/build_driver.sh` first). Set `PW_SRC_DIR` to generate from another `microsoft/playwright` checkout instead, to try a change to the upstream docs; the committed files must come from `.upstream/`. To regenerate Java interfaces for the current driver run: +Public Java API is generated by [scripts/generate_java_api.mts](scripts/generate_java_api.mts) from the API docs (`docs/src/api/*.md`) in `.upstream/`, the `microsoft/playwright` checkout at the commit in [scripts/DRIVER_VERSION](scripts/DRIVER_VERSION) that the driver is built from (run `scripts/build_driver.sh` first). Set `PW_SRC_DIR` to generate from another `microsoft/playwright` checkout instead, to try a change to the upstream docs; the committed files must come from `.upstream/`. The generator is a TypeScript file that Node.js runs as is, so it needs Node.js 22.18 or newer. To regenerate Java interfaces for the current driver run: ```bash ./scripts/generate_api.sh diff --git a/scripts/generate_api.sh b/scripts/generate_api.sh index 805915540..c909bf31e 100755 --- a/scripts/generate_api.sh +++ b/scripts/generate_api.sh @@ -8,8 +8,8 @@ cd "$(dirname "$0")/.." DRIVER_VERSION=$(head -1 ./scripts/DRIVER_VERSION) -# The script generates api.json from .upstream/. This is the microsoft/playwright checkout -# at the commit in scripts/DRIVER_VERSION. scripts/build_driver.sh makes it. +# The script generates the API from the docs in .upstream/ (docs/src/api/*.md). This is the +# microsoft/playwright checkout at the commit in scripts/DRIVER_VERSION. scripts/build_driver.sh makes it. # To try a change to the upstream docs or to the generator, set PW_SRC_DIR to a different # checkout. Do not commit files that come from PW_SRC_DIR: CI generates the files again # from .upstream/ and fails if they are different. @@ -24,14 +24,8 @@ else fi fi -echo "Updating api.json from $UPSTREAM_DIR" -API_JSON_MODE=1 node "$UPSTREAM_DIR/utils/doclint/generateApiJson.js" \ - > ./tools/api-generator/src/main/resources/api.json - -mvn compile -f ./tools/api-generator --no-transfer-progress - -echo "Regenerating Java interfaces" -mvn exec:java --f ./tools/api-generator -D exec.mainClass=com.microsoft.playwright.tools.ApiGenerator +echo "Regenerating Java interfaces from $UPSTREAM_DIR" +node ./scripts/generate_java_api.mts "$UPSTREAM_DIR" # The protocol types are generated last: they avoid names of the public API types generated above. # utils/protocol_spec.js needs the 'yaml' package. .upstream/ has it after scripts/build_driver.sh. diff --git a/scripts/generate_java_api.mts b/scripts/generate_java_api.mts new file mode 100644 index 000000000..729ac3b60 --- /dev/null +++ b/scripts/generate_java_api.mts @@ -0,0 +1,1090 @@ +#!/usr/bin/env node +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed 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. + */ + +// Generates the public Java API (the interfaces, the options classes and the enums) from the +// upstream API docs, docs/src/api/*.md. The docs and the modules that parse them stay in +// microsoft/playwright: the script reads both from the same checkout. +// +// Node.js runs this file as is, it needs no build step and no dependencies. +// +// Usage: node scripts/generate_java_api.mts + +import fs from 'node:fs'; +import { createRequire } from 'node:module'; +import path from 'node:path'; + +// The subset of the upstream model (utils/doclint/documentation.js) that the generator reads. + +type MarkdownNode = { + type: string, + text?: string, + liType?: string, + codeLang?: string, + lines?: string[], + children?: MarkdownNode[], +}; + +type Langs = { + only?: string[], + aliases?: Record, + types?: Record, +}; + +type DocType = { + name: string, + union?: DocType[], + templates?: DocType[], + args?: DocType[], + returnType?: DocType, + properties?: DocMember[], + langAliases?: Record, +}; + +type DocMember = { + kind: 'method' | 'property' | 'event', + name: string, + // The name in the docs, when `name` is the Java alias. + originalName?: string, + type: DocType | null, + argsArray: DocMember[], + required: boolean, + langs: Langs, + spec?: MarkdownNode[], + since?: string, + deprecated?: string, +}; + +type DocClass = { + name: string, + extends: string | null, + membersArray: DocMember[], + langs: Langs, + spec?: MarkdownNode[], +}; + +type LinkRenderer = (item: { clazz?: DocClass, param?: { alias: string }, option?: { alias: string } }) => string | undefined; + +type Documentation = { + classesArray: DocClass[], + setLinkRenderer(renderer: LinkRenderer): void, +}; + +const LANG = 'java'; +const ROOT_DIR = path.join(import.meta.dirname, '..'); +const API_DIR = path.join(ROOT_DIR, 'playwright', 'src', 'main', 'java', 'com', 'microsoft', 'playwright'); +const API_PACKAGE = 'com.microsoft.playwright'; + +const LICENSE_HEADER = `/* + * Copyright (c) Microsoft Corporation. + * + * Licensed 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. + */ +`; + +// These classes are written by hand. +const HANDWRITTEN_CLASSES = ['PlaywrightException', 'TimeoutError']; +// These interfaces go to the options package. +const OPTIONS_PACKAGE_INTERFACES = ['RequestOptions', 'FormData']; +const BASE_INTERFACES = ['Browser', 'JSHandle', 'BrowserContext']; +const AUTO_CLOSEABLE_INTERFACES = ['Playwright', 'Browser', 'BrowserContext', 'Page']; +// The interfaces with a static create() method that calls the implementation class. +const FACTORY_INTERFACES = ['Playwright', 'FormData', 'RequestOptions']; +const BROWSER_CHANNEL_OPTIONS = ['BrowserType.launch.options.channel', 'BrowserType.launchPersistentContext.options.channel']; + +// The imports of a generated interface, in the order of the output. When a roll brings in an +// interface that uses one of these types, add the interface to the list. +const INTERFACE_IMPORTS: [imports: string[], interfaces: string[]][] = [ + [['com.microsoft.playwright.options.*'], ['Page', 'Request', 'Response', 'APIRequestContext', 'APIRequest', 'APIResponse', 'FileChooser', 'Frame', 'FrameLocator', 'ElementHandle', 'Locator', 'Browser', 'BrowserContext', 'BrowserType', 'Mouse', 'Keyboard', 'Tracing', 'Video', 'Debugger', 'Screencast', 'WebError', 'Credentials', 'WebStorage', 'WebMCP']], + [['java.io.InputStream'], ['Download']], + [['java.nio.file.Path'], ['Page', 'Frame', 'ElementHandle', 'Locator', 'FormData', 'APIRequest', 'APIRequestContext', 'FileChooser', 'Browser', 'BrowserContext', 'BrowserType', 'Download', 'Route', 'Selectors', 'Tracing', 'Video', 'Screencast']], + [['java.util.Date'], ['Clock']], + [['java.util.*'], ['Page', 'Frame', 'ElementHandle', 'Locator', 'LocatorAssertions', 'APIRequest', 'APIRequestContext', 'Browser', 'BrowserContext', 'BrowserType', 'Route', 'Request', 'Response', 'JSHandle', 'ConsoleMessage', 'APIResponse', 'Playwright', 'Debugger', 'Screencast', 'WebSocketRoute', 'Credentials', 'WebStorage', 'WebMCP']], + [['java.util.function.BiConsumer'], ['WebSocketRoute']], + [['java.util.function.Consumer'], ['Page', 'Browser', 'BrowserContext', 'WebSocket', 'Worker', 'CDPSession', 'WebSocketRoute', 'Screencast']], + [['java.util.function.BooleanSupplier'], ['Page', 'BrowserContext']], + [['java.util.function.Predicate'], ['Page', 'Frame', 'BrowserContext', 'WebSocket', 'Worker']], + [['java.util.regex.Pattern'], ['Page', 'Frame', 'FrameLocator', 'Locator', 'APIRequestContext', 'Browser', 'BrowserType', 'BrowserContext', 'PageAssertions', 'LocatorAssertions', 'Tracing']], + [['com.google.gson.JsonObject'], ['CDPSession']], + [['com.microsoft.playwright.options.AriaRole', 'com.microsoft.playwright.options.PseudoElement'], ['LocatorAssertions']], + [[ + 'com.microsoft.playwright.APIResponse', + 'com.microsoft.playwright.Locator', + 'com.microsoft.playwright.Page', + 'com.microsoft.playwright.impl.APIResponseAssertionsImpl', + 'com.microsoft.playwright.impl.AssertionsTimeout', + 'com.microsoft.playwright.impl.LocatorAssertionsImpl', + 'com.microsoft.playwright.impl.PageAssertionsImpl', + ], ['PlaywrightAssertions']], +]; +const CUSTOM_CLASS_IMPORTS: Record = { + ClientCertificate: 'java.nio.file.Path', + DropPayload: 'java.util.Map', +}; + +// The static methods with a body. The key is the path of the method. A method with overloads +// has an entry for the name of each overload in the docs. +const STATIC_METHODS: Record> = { + 'FormData.create': { + create: [ + 'static FormData create() {', + ' return new FormDataImpl();', + '}', + ], + }, + 'RequestOptions.create': { + create: [ + 'static RequestOptions create() {', + ' return new RequestOptionsImpl();', + '}', + ], + }, + 'PlaywrightAssertions.assertThat': { + expectPage: [ + 'static PageAssertions assertThat(Page page) {', + ' return new PageAssertionsImpl(page);', + '}', + '', + ], + expectLocator: [ + 'static LocatorAssertions assertThat(Locator locator) {', + ' return new LocatorAssertionsImpl(locator);', + '}', + '', + ], + expectAPIResponse: [ + 'static APIResponseAssertions assertThat(APIResponse response) {', + ' return new APIResponseAssertionsImpl(response);', + '}', + '', + ], + }, + 'PlaywrightAssertions.setDefaultAssertionTimeout': { + setDefaultAssertionTimeout: [ + 'static void setDefaultAssertionTimeout(double timeout) {', + ' AssertionsTimeout.setDefaultTimeout(timeout);', + '}', + '', + ], + }, +}; + +const BUILTIN_TYPES: Record = { + 'int': 'int', + 'float': 'double', + 'string': 'String', + 'void': 'void', + 'path': 'Path', + 'EvaluationArgument': 'Object', + 'Serializable': 'Object', + 'any': 'Object', + 'Readable': 'InputStream', + 'Buffer': 'byte[]', + 'Disposable': 'AutoCloseable', + 'URL': 'String', + 'RegExp': 'Pattern', +}; + +const BOXED_TYPES: Record = { + 'int': 'Integer', + 'double': 'Double', + 'boolean': 'Boolean', +}; + +// `Class.member` in the docs => `Class.alias`, for the members with a Java alias. +const memberAliases = new Map(); + +// --------------------------------------------------------------------------------------------- +// Filtering the docs for Java. + +function isSupported(item: { langs?: Langs }): boolean { + return !item.langs?.only || item.langs.only.includes(LANG); +} + +// Renames the member to its Java alias and replaces its type with the Java one. Removes +// everything that is for other languages, at any depth. +function filterMember(member: DocMember) { + const alias = member.langs?.aliases?.[LANG]; + if (alias) { + member.originalName = member.name; + member.name = alias; + } + const type = member.langs?.types?.[LANG]; + if (type) + member.type = type; + if (member.type) + filterType(member.type); + member.argsArray = member.argsArray.filter(isSupported); + member.argsArray.forEach(filterMember); +} + +function filterType(type: DocType) { + if (type.properties) { + type.properties = type.properties.filter(isSupported); + type.properties.forEach(filterMember); + } + for (const nested of [...type.union || [], ...type.templates || [], ...type.args || []]) + filterType(nested); + if (type.returnType) + filterType(type.returnType); +} + +function filterForJava(documentation: Documentation): DocClass[] { + const classes = documentation.classesArray.filter(isSupported); + for (const clazz of classes) { + const className = clazz.name; + const alias = clazz.langs?.aliases?.[LANG]; + if (alias) + clazz.name = alias; + clazz.membersArray = clazz.membersArray.filter(isSupported); + for (const member of clazz.membersArray) { + const memberName = member.name; + filterMember(member); + if (member.name !== memberName) + memberAliases.set(`${className}.${memberName}`, `${className}.${member.name}`); + } + } + return classes; +} + +// --------------------------------------------------------------------------------------------- +// Javadoc. + +function toTitle(name: string): string { + return name[0].toUpperCase() + name.substring(1); +} + +function isAssertionClass(className: string): boolean { + return className.toLowerCase().includes('assert'); +} + +// Splits as String.split() of Java does: without the trailing empty strings. +function splitDroppingTrailingEmpty(text: string, separator: string): string[] { + const parts = text.split(separator); + if (parts.length === 1) + return parts; + while (parts.length && !parts[parts.length - 1]) + parts.pop(); + return parts; +} + +function writeJavadoc(output: string[], offset: string, text: string) { + if (!text) + return; + output.push(offset + '/**'); + for (const line of splitDroppingTrailingEmpty(text, '\n')) + output.push((offset + ' *' + (line ? ' ' : '') + line).replaceAll('*/', '*\\/')); + output.push(offset + ' */'); +} + +function linkifyMemberRefs(paragraph: string): string { + return paragraph.replace(/\[`(event|property|method): ([^`]+)`]/g, (match, kind: string, ref: string) => { + let name = memberAliases.get(ref) ?? ref; + if (kind === 'event') { + const parts = name.split('.'); + name = parts[0] + '.on' + toTitle(parts[1]); + } + const packagePrefix = isAssertionClass(name.split('.')[0]) ? `${API_PACKAGE}.assertions.` : `${API_PACKAGE}.`; + return `{@link ${packagePrefix}${name.replaceAll('.', '#')} ${name}()}`; + }); +} + +function updateExternalLinks(paragraph: string): string { + return paragraph.replace(/\[([^\]]+)\]\(([^\)]+)\)/g, (match, text: string, url: string) => { + // ../actionability.md#editable => https://playwright.dev/java/docs/actionability#editable + if (url.startsWith('../')) + url = url.replaceAll('.md', '').replaceAll('../', 'https://playwright.dev/java/docs/'); + // ./class-tracing.md => https://playwright.dev/java/docs/api/class-tracing + if (url.startsWith('./')) + url = url.replaceAll('.md', '').replaceAll('./', 'https://playwright.dev/java/docs/api/'); + return `${text}`; + }).replaceAll('[Promise]', `Promise`); +} + +// Splits the text into words. A link in square brackets is not split. +function tokenizeNoBreakLinks(text: string): string[] { + const links: string[] = []; + const sanitized = text.replace(/\[[^\]]+\]/g, link => { + links.push(link); + return `[${links.length - 1}]`; + }); + let tokens = splitDroppingTrailingEmpty(sanitized, ' '); + links.forEach((link, index) => { + tokens = tokens.map(token => token.replaceAll(`[${index}]`, () => link)); + }); + return tokens; +} + +function wrapText(text: string, maxColumns: number): string { + // A table row. + if (/^[\u0000- ]*\|/.test(text)) + return text; + const lines: string[] = []; + let line = ''; + for (const word of tokenizeNoBreakLinks(text)) { + if (line && line.length + word.length < maxColumns) { + line += ' ' + word; + } else { + if (line) + lines.push(line); + line = word; + } + } + if (line) + lines.push(line); + return lines.join('\n'); +} + +function beautify(paragraph: string): string { + const text = updateExternalLinks(linkifyMemberRefs(paragraph)) + .replaceAll('↵', ' ') + .replace(/`'([^`]+)'`/g, '{@code "$1"}') + .replace(/`([^`]+)`/g, '{@code $1}'); + return wrapText(text, 120); +} + +function formatSpec(spec: MarkdownNode[]): string { + const out: string[] = []; + let currentList: string | null = null; + const closeList = () => { + if (currentList) + out.push(``); + currentList = null; + }; + for (const node of spec) { + if (node.type === 'li') { + if (node.text!.startsWith('extends: ')) + continue; + if (!currentList) { + currentList = node.liType === 'ordinal' ? 'ol' : 'ul'; + out.push(`<${currentList}>`); + } + out.push(`
  • ${beautify(node.text!)}
  • `); + continue; + } + closeList(); + const paragraphPrefix = out.length ? '\n

    ' : ''; + if (node.type === 'code') { + // This is true for javascript too: the code of all languages that have 'java' in the name is in the comment. + if (!node.codeLang?.includes('java')) + continue; + out.push('

    {@code', ...node.lines!, '}
    '); + } else if (node.type === 'note') { + const text = node.children!.filter(child => child.type === 'text').map(child => beautify(child.text!)).join(''); + out.push(`${paragraphPrefix}NOTE: ${text}`); + } else { + // **Usage**, **Details** and other titles are bold text. + const title = node.text!.match(/^\*\*(.+)\*\*$/); + const paragraph = title ? `${title[1]}` : beautify(node.text!); + out.push(paragraphPrefix + paragraph); + } + } + closeList(); + return out.join('\n'); +} + +function memberComment(member: DocMember): string { + if (!member.spec) + return ''; + if (member.deprecated !== undefined) + return '@deprecated ' + beautify(member.deprecated); + return formatSpec(member.spec); +} + +// --------------------------------------------------------------------------------------------- +// The model of the generated code. + +abstract class Element { + readonly parent: Element | null; + readonly name: string; + // The names from the interface to this element, for example `BrowserType.launch.options.channel`. + readonly path: string; + + constructor(parent: Element | null, name: string, path?: string) { + this.parent = parent; + this.name = name; + this.path = path ?? (parent ? `${parent.path}.${name}` : name); + } + + typeScope(): TypeDefinition { + return this.parent!.typeScope(); + } + + // All types that go to files of their own, by name. The first definition of a type wins. + topLevelTypes(): Map { + return this.parent!.topLevelTypes(); + } +} + +function nullable(javaType: string): string { + if (javaType.endsWith('[]')) + return javaType.substring(0, javaType.length - 2) + ' @Nullable []'; + return '@Nullable ' + javaType; +} + +// The Java alias of the type in the docs (`alias-java: Cookie`), or the alias for all languages. +function javaAlias(type: DocType): string | undefined { + return type.langAliases?.[LANG] ?? type.langAliases?.default; +} + +// The return type of a method, the type of a method param or the type of a field. +class TypeRef extends Element { + readonly type: DocType | null; + // The name of the class generated for the `Object` in this type. + customType: string | null = null; + + constructor(parent: Element, type: DocType | null) { + super(parent, type?.name ?? '', parent.path); + this.type = type; + if (type) + this.createClassesAndEnums(type); + } + + private createClassesAndEnums(type: DocType) { + if (type.union) { + if (type.name) + this.typeScope().createEnum(type); + else + type.union.forEach(item => this.createClassesAndEnums(item)); + return; + } + if (type.templates) { + type.templates.forEach(item => this.createClassesAndEnums(item)); + return; + } + if (type.name === 'function' && type.args) { + for (const arg of type.args) { + const alias = javaAlias(arg); + if (arg.name === 'Object' && alias) + this.typeScope().createTopLevelInterface(alias, this, arg); + } + return; + } + if (type.name !== 'Object') + return; + // The same type may be `Object` in several union values, for example Object|Array. + if (this.customType) + return; + if (this.parent instanceof Param && this.parent.name === 'options') { + this.customType = toTitle(this.parent.parent!.name) + toTitle(this.parent.name); + this.typeScope().createNestedClass(this.customType, this, type); + } else { + this.customType = javaAlias(type) ?? toTitle(this.parent!.name); + this.typeScope().createTopLevelClass(this.customType, this, type); + } + } + + toJava(): string { + if (!this.type) + return 'void'; + return this.convertType(this.stripNullable()); + } + + toJavaWithNullability(): string { + return this.withNullability(this.toJava(), false); + } + + // Adds @Nullable when the type admits null, or when it is the type of an optional parameter or field. + withNullability(javaType: string, optional: boolean): string { + // Serializable is Object in Java, and the JSON null is a value of it. + const isNullable = this.isNullable() || this.stripNullable()?.name === 'Serializable'; + return optional || isNullable ? nullable(javaType) : javaType; + } + + isCustomClass(): boolean { + return this.stripNullable()?.name === 'Object' && !this.type!.templates; + } + + // A union of types, that is not an enum and not `null|T`. + isTypeUnion(): boolean { + return !!this.type?.union && !this.type.name && !this.isNullable(); + } + + private supportedUnionTypes(): DocType[] { + return this.type!.union!.filter(type => type.name !== 'null' && (type.name !== 'function' || type.args)); + } + + unionSize(): number { + return this.supportedUnionTypes().length; + } + + // True for Object|Array, where both are the same custom class. + isCustomClassOrListUnion(): boolean { + if (!this.customType || !this.isTypeUnion()) + return false; + const types = this.supportedUnionTypes(); + const isObjectList = (type: DocType) => type.name === 'Array' && type.templates?.length === 1 && type.templates[0].name === 'Object'; + return types.length === 2 && types.some(type => type.name === 'Object') && types.some(isObjectList); + } + + formatTypeFromUnion(index: number): string { + return this.convertType(this.supportedUnionTypes()[index]); + } + + // True for `null|T`. + isNullable(): boolean { + const type = this.type; + return !!type?.union && !type.name && type.union.length === 2 && type.union.some(item => item.name === 'null'); + } + + private stripNullable(): DocType { + if (!this.isNullable()) + return this.type!; + return this.type!.union!.find(item => item.name !== 'null')!; + } + + private convertType(type: DocType): string { + const name = type.name; + if (type.union) { + if (name) + return name; + if (this.parent instanceof Field) + return 'Object'; + throw new Error(`Unexpected union without name in ${this.path}`); + } + if (Object.hasOwn(BUILTIN_TYPES, name)) + return BUILTIN_TYPES[name]; + if (name === 'Array') { + const elementType = this.convertTemplateParams(type); + // After the type erasure all lists are the same type, so the overloads take arrays. + if (this.parent instanceof Param && this.isTypeUnion() && this.supportedUnionTypes().filter(item => item.name === 'Array').length > 1) + return elementType + '[]'; + return `List<${elementType}>`; + } + if (name === 'Object') { + // An `Object` in an argument of a function has no class of this type reference. + const className = this.customType ?? javaAlias(type); + if (className) + return className; + return `Map<${this.convertTemplateParams(type)}>`; + } + if (name === 'Map') + return `Map<${this.convertTemplateParams(type)}>`; + if (name === 'Promise') + return this.convertTemplateParams(type); + if (name === 'function') { + const alias = javaAlias(type); + if (alias) + return alias; + if (!type.args) + throw new Error(`Missing mapping for ${this.path}`); + if (this.path === 'WebSocketRoute.onClose.handler') + return 'BiConsumer'; + if (type.args.length === 1) { + const paramType = this.convertType(type.args[0]); + const returnTypeName = type.returnType?.name; + if (returnTypeName === 'boolean') + return `Predicate<${paramType}>`; + if (!returnTypeName || returnTypeName === 'Promise' || returnTypeName === 'void') + return `Consumer<${paramType}>`; + throw new Error(`Missing mapping for the return type ${returnTypeName} in ${this.path}`); + } + } + return name; + } + + private convertTemplateParams(type: DocType): string { + return (type.templates || []).map(item => this.convertType(item)).join(', '); + } +} + +abstract class TypeDefinition extends Element { + // The options classes of the methods. + readonly nestedClasses: CustomClass[] = []; + + override typeScope(): TypeDefinition { + return this; + } + + abstract writeTo(output: string[], offset: string): void; + + // Constructs the type in any case: it registers the types of its fields. + private createTopLevelType(name: string, type: T, kind: Function) { + const types = this.topLevelTypes(); + const existing = types.get(name); + if (!existing) + types.set(name, type); + else if (!(existing instanceof kind)) + throw new Error(`Two types with the name ${name} are of different kinds, the second one is ${type.path}`); + return existing as T | undefined; + } + + createEnum(type: DocType) { + const newEnum = new Enum(this, type); + const existing = this.createTopLevelType(newEnum.name, newEnum, Enum); + if (existing && existing.values.join() !== newEnum.values.join()) + throw new Error(`Two enums with the name ${newEnum.name} have different values: ${existing.values} and ${newEnum.values}`); + } + + createTopLevelClass(name: string, parent: TypeRef, type: DocType) { + this.createTopLevelType(name, new CustomClass(parent, name, type), CustomClass); + } + + createTopLevelInterface(name: string, parent: TypeRef, type: DocType) { + this.createTopLevelType(name, new CustomInterface(parent, name, type), CustomInterface); + } + + createNestedClass(name: string, parent: TypeRef, type: DocType) { + if (!this.nestedClasses.some(c => c.name === name)) + this.nestedClasses.push(new CustomClass(parent, name, type)); + } +} + +class Event extends Element { + private readonly member: DocMember; + private readonly type: TypeRef; + + constructor(parent: Interface, member: DocMember) { + super(parent, member.name); + this.member = member; + this.type = new TypeRef(this, member.type); + } + + writeListenerMethods(output: string[], offset: string) { + writeJavadoc(output, offset, memberComment(this.member)); + const name = toTitle(this.name); + const paramType = this.type.toJavaWithNullability(); + const listenerType = paramType === 'void' ? 'Runnable' : `Consumer<${paramType}>`; + output.push(`${offset}void on${name}(${listenerType} handler);`); + writeJavadoc(output, offset, `Removes handler that was previously added with {@link #on${name} on${name}(handler)}.`); + output.push(`${offset}void off${name}(${listenerType} handler);`); + } +} + +class Param extends Element { + readonly member: DocMember; + readonly type: TypeRef; + + constructor(method: Method, member: DocMember) { + super(method, member.name); + this.member = member; + this.type = new TypeRef(this, member.type); + } + + isOptional(): boolean { + return !this.member.required; + } + + // The declaration of the param. `overloadIndex` picks the type from the union, when the type is a union. + toJava(overloadIndex: number): string { + const javaType = this.type.isTypeUnion() ? this.type.formatTypeFromUnion(overloadIndex) : this.type.toJava(); + return `${this.type.withNullability(javaType, this.isOptional())} ${this.name}`; + } +} + +// A method or a property of an interface: all properties are methods in Java. +class Method extends Element { + private readonly member: DocMember; + private readonly returnType: TypeRef; + private readonly params: Param[]; + + constructor(parent: Interface, member: DocMember) { + super(parent, member.name); + this.member = member; + this.returnType = new TypeRef(this, member.type); + this.params = member.argsArray + .filter(arg => arg.name !== 'options' || arg.type?.properties?.length) + .map(arg => new Param(this, arg)); + } + + writeTo(output: string[], offset: string) { + if (this.path === 'Playwright.create') { + this.writeJavadoc(this.params, output, offset); + output.push( + `${offset}static Playwright create(${this.params[0].toJava(0)}) {`, + `${offset} return PlaywrightImpl.create(options);`, + `${offset}}`, + '', + `${offset}static Playwright create() {`, + `${offset} return create(null);`, + `${offset}}`); + return; + } + const staticMethod = STATIC_METHODS[this.path]; + if (staticMethod) { + const originalName = this.member.originalName ?? this.name; + const body = staticMethod[originalName]; + if (!body) + throw new Error(`Unexpected overload of ${this.path}: ${originalName}`); + this.writeJavadoc(this.params, output, offset); + output.push(...body.map(line => line && offset + line)); + return; + } + // Each type of the first param with a union type makes an overload. + const unionParam = this.params.find(p => p.type.isTypeUnion()); + const numOverloads = unionParam ? unionParam.type.unionSize() : 1; + for (let i = 0; i < numOverloads; i++) + this.writeOverloadedMethods(i, output, offset); + } + + private writeOverloadedMethods(overloadIndex: number, output: string[], offset: string) { + for (let i = this.params.length - 1; i >= 0; i--) { + const param = this.params[i]; + if (!param.isOptional()) + continue; + // An optional param with a union type has one overload without the param. + if (param.type.isTypeUnion() && overloadIndex !== 0) + continue; + this.writeDefaultOverloadedMethod(overloadIndex, i, output, offset); + } + const params = this.params.map(p => p.toJava(overloadIndex)).join(', '); + this.writeJavadoc(this.params, output, offset); + output.push(`${offset}${this.returnType.toJavaWithNullability()} ${this.name}(${params});`); + } + + // Writes the default method without the optional params that start at `firstNullOptional`. + private writeDefaultOverloadedMethod(overloadIndex: number, firstNullOptional: number, output: string[], offset: string) { + const params: Param[] = []; + const args: string[] = []; + this.params.forEach((param, i) => { + if (i === firstNullOptional) { + if (param.type.isTypeUnion()) { + const type = param.type.formatTypeFromUnion(overloadIndex); + args.push(type === 'int' ? '0' : `(${type}) null`); + } else { + // TODO: it should probably be done for all methods that have name#1, name#2 etc overloads. + args.push(this.path === 'LocatorAssertions.hasAttribute' ? `(${param.type.toJava()}) null` : 'null'); + } + return; + } + if (param.isOptional() && i > firstNullOptional) + return; + params.push(param); + args.push(param.name); + }); + const returns = this.returnType.toJava() === 'void' ? '' : 'return '; + this.writeJavadoc(params, output, offset); + output.push( + `${offset}default ${this.returnType.toJavaWithNullability()} ${this.name}(${params.map(p => p.toJava(overloadIndex)).join(', ')}) {`, + `${offset} ${returns}${this.name}(${args.join(', ')});`, + `${offset}}`); + } + + private writeJavadoc(params: Param[], output: string[], offset: string) { + const tags: string[] = []; + for (const param of params) { + const comment = memberComment(param.member); + if (comment) + tags.push(`@param ${param.name} ${comment}`); + } + if (this.member.since !== undefined) + tags.push(`@since ${this.member.since}`); + const sections = [memberComment(this.member)]; + if (tags.length) + sections.push('', ...tags); + writeJavadoc(output, offset, sections.join('\n')); + } +} + +class Field extends Element { + private readonly member: DocMember; + readonly type: TypeRef; + + constructor(parent: TypeDefinition, member: DocMember) { + super(parent, member.name); + this.member = member; + this.type = new TypeRef(this, member.type); + } + + isRequired(): boolean { + return !!this.member.required; + } + + comment(): string { + return memberComment(this.member); + } + + writeTo(output: string[], offset: string) { + writeJavadoc(output, offset, this.comment()); + let type = this.type.toJava(); + if (this.type.isNullable()) + type = `Optional<${type}>`; + if (this.isBrowserChannelOption()) + type = 'Object'; + // An optional field has a boxed type: it can be null. + if (!this.isRequired()) + type = nullable(BOXED_TYPES[type] ?? type); + output.push(`${offset}public ${type} ${this.name};`); + } + + writeBuilderMethod(output: string[], offset: string, parentClass: string) { + if (this.type.isTypeUnion() && (!this.type.customType || this.type.isCustomClassOrListUnion())) { + // A union of a custom class and its list, for example Object|Array of httpCredentials, + // has the setter with the required fields too. + if (this.type.customType) + this.writeRequiredFieldsBuilderMethod(output, offset, parentClass); + for (let i = 0; i < this.type.unionSize(); i++) + this.writeGenericBuilderMethod(output, offset, parentClass, this.type.formatTypeFromUnion(i)); + return; + } + if (this.type.isCustomClass()) + this.writeRequiredFieldsBuilderMethod(output, offset, parentClass); + if (this.isBrowserChannelOption()) { + output.push(`${offset}@Deprecated`); + this.writeGenericBuilderMethod(output, offset, parentClass, 'BrowserChannel'); + } + this.writeGenericBuilderMethod(output, offset, parentClass, this.type.toJava()); + } + + // The setter that takes the required fields of the custom class, for example setHttpCredentials(username, password). + private writeRequiredFieldsBuilderMethod(output: string[], offset: string, parentClass: string) { + const customType = this.topLevelTypes().get(this.type.customType!); + if (!(customType instanceof CustomClass)) + return; + const requiredFields = customType.fields.filter(f => f.isRequired()); + if (!requiredFields.length) + return; + const params = requiredFields.map(f => `${f.type.toJavaWithNullability()} ${f.name}`).join(', '); + const args = requiredFields.map(f => f.name).join(', '); + writeJavadoc(output, offset, this.comment()); + output.push( + `${offset}public ${parentClass} set${toTitle(this.name)}(${params}) {`, + `${offset} return set${toTitle(this.name)}(new ${this.type.customType}(${args}));`, + `${offset}}`); + } + + private writeGenericBuilderMethod(output: string[], offset: string, parentClass: string, paramType: string) { + writeJavadoc(output, offset, this.comment()); + const value = this.type.isNullable() ? `Optional.ofNullable(${this.name})` : this.name; + output.push( + `${offset}public ${parentClass} set${toTitle(this.name)}(${this.type.withNullability(paramType, false)} ${this.name}) {`, + `${offset} this.${this.name} = ${value};`, + `${offset} return this;`, + `${offset}}`); + } + + private isBrowserChannelOption(): boolean { + return BROWSER_CHANNEL_OPTIONS.includes(this.path); + } +} + +// An interface of the API, made from a class of the docs. +class Interface extends TypeDefinition { + private readonly clazz: DocClass; + private readonly types: Map; + private readonly methods: Method[] = []; + private readonly events: Event[] = []; + + constructor(clazz: DocClass, topLevelTypes: Map) { + super(null, clazz.name); + this.clazz = clazz; + this.types = topLevelTypes; + for (const member of clazz.membersArray) { + if (member.kind === 'event') + this.events.push(new Event(this, member)); + else + this.methods.push(new Method(this, member)); + } + } + + override topLevelTypes(): Map { + return this.types; + } + + writeTo(output: string[], offset: string) { + if (FACTORY_INTERFACES.includes(this.name) && this.methods.some(m => m.name === 'create')) + output.push(`import ${API_PACKAGE}.impl.${this.name}Impl;`); + for (const [imports, interfaces] of INTERFACE_IMPORTS) { + if (interfaces.includes(this.name)) + output.push(...imports.map(name => `import ${name};`)); + } + output.push(''); + + const superInterfaces: string[] = []; + if (this.clazz.extends && BASE_INTERFACES.includes(this.clazz.extends)) + superInterfaces.push(this.clazz.extends); + if (AUTO_CLOSEABLE_INTERFACES.includes(this.name)) + superInterfaces.push('AutoCloseable'); + const extendsClause = superInterfaces.length ? ` extends ${superInterfaces.join(', ')}` : ''; + + writeJavadoc(output, offset, this.clazz.spec ? formatSpec(this.clazz.spec) : ''); + output.push(`public interface ${this.name}${extendsClause} {`); + const bodyOffset = ' '; + for (const event of this.events) { + output.push(''); + event.writeListenerMethods(output, bodyOffset); + } + if (this.events.length) + output.push(''); + for (const nestedClass of this.nestedClasses) + nestedClass.writeTo(output, bodyOffset); + for (const method of this.methods) + method.writeTo(output, bodyOffset); + output.push('}', '\n'); + } +} + +// A class with fields and setters, made from an `Object` type with properties. It is the options +// of a method, nested in the interface, or a type in a file of its own. +class CustomClass extends TypeDefinition { + readonly fields: Field[]; + + constructor(parent: TypeRef, name: string, type: DocType) { + super(parent, name, parent.path); + this.fields = (type.properties || []).map(property => new Field(this, property)); + } + + writeTo(output: string[], offset: string) { + if (CUSTOM_CLASS_IMPORTS[this.name]) + output.push(`import ${CUSTOM_CLASS_IMPORTS[this.name]};`, ''); + const access = this.topLevelTypes().has(this.name) ? 'public ' : ''; + output.push(`${offset}${access}class ${this.name} {`); + const bodyOffset = offset + ' '; + for (const field of this.fields) + field.writeTo(output, bodyOffset); + output.push(''); + // The return value of a method is not created by the user: it has no constructor and no setters. + const isReturnType = this.parent!.parent instanceof Method; + if (!isReturnType) { + this.writeConstructor(output, bodyOffset); + for (const field of this.fields) { + if (!field.isRequired()) + field.writeBuilderMethod(output, bodyOffset, this.name); + } + } + output.push(`${offset}}`); + } + + private writeConstructor(output: string[], offset: string) { + const requiredFields = this.fields.filter(f => f.isRequired()); + if (!requiredFields.length) + return; + const params = requiredFields.map(f => `${f.type.toJavaWithNullability()} ${f.name}`).join(', '); + output.push( + `${offset}public ${this.name}(${params}) {`, + ...requiredFields.map(f => `${offset} this.${f.name} = ${f.name};`), + `${offset}}`); + } +} + +// An interface with getters, made from an `Object` argument of a callback. +class CustomInterface extends TypeDefinition { + private readonly fields: Field[]; + + constructor(parent: TypeRef, name: string, type: DocType) { + super(parent, name, parent.path); + this.fields = (type.properties || []).map(property => new Field(this, property)); + } + + writeTo(output: string[], offset: string) { + output.push(`${offset}public interface ${this.name} {`); + const bodyOffset = offset + ' '; + this.fields.forEach((field, index) => { + if (index) + output.push(''); + writeJavadoc(output, bodyOffset, field.comment()); + output.push(`${bodyOffset}${field.type.withNullability(field.type.toJava(), !field.isRequired())} ${field.name}();`); + }); + output.push(`${offset}}`); + } +} + +class Enum extends TypeDefinition { + readonly values: string[]; + + constructor(parent: TypeDefinition, type: DocType) { + super(parent, type.name); + // The values are in quotes: "load", "domcontentloaded". + this.values = type.union!.map(item => item.name.substring(1, item.name.length - 1).replaceAll('-', '_').toUpperCase()); + // Firefox stable 'channel' was removed in 1.12.0 + if (this.name === 'BrowserChannel') + this.values.push('@Deprecated FIREFOX_STABLE'); + } + + writeTo(output: string[], offset: string) { + output.push(`public enum ${this.name} {\n ${this.values.join(',\n ')}\n}`); + } +} + +// --------------------------------------------------------------------------------------------- +// Writing the files. + +function writeFile(dir: string, packageName: string, type: TypeDefinition) { + const body: string[] = []; + type.writeTo(body, ''); + const lines = [LICENSE_HEADER, `package ${packageName};`, '']; + if (body.some(line => line.includes('@Nullable'))) { + lines.push('import org.jspecify.annotations.Nullable;'); + if (body[0] && !body[0].startsWith('import ')) + lines.push(''); + } + lines.push(...body); + fs.writeFileSync(path.join(dir, `${type.name}.java`), lines.join('\n')); +} + +function generateInterfaces(classes: DocClass[], dir: string, packageName: string, topLevelTypes: Map) { + for (const clazz of classes) { + const iface = new Interface(clazz, topLevelTypes); + // The file is written before the next interface is read: a nested class is `public` when + // a type with its name is among the top-level types found so far. + if (OPTIONS_PACKAGE_INTERFACES.includes(clazz.name)) + topLevelTypes.set(clazz.name, iface); + else + writeFile(dir, packageName, iface); + } +} + +function parseDocs(upstreamDir: string): Documentation { + const require = createRequire(import.meta.url); + const { parseApi } = require(path.join(upstreamDir, 'utils', 'doclint', 'api_parser')); + const documentation: Documentation = parseApi(path.join(upstreamDir, 'docs', 'src', 'api')); + // The links to params, options and classes become code. The links to members stay: + // linkifyMemberRefs() makes {@link} tags of them. + documentation.setLinkRenderer(({ clazz, param, option }) => { + if (param) + return `\`${param.alias}\``; + if (option) + return `\`${option.alias}\``; + if (clazz) + return `\`${clazz.name}\``; + }); + return documentation; +} + +function main() { + if (process.argv.length !== 3) { + console.error(`Usage: node ${path.relative(process.cwd(), process.argv[1])} `); + console.error('For example: node scripts/generate_java_api.mts .upstream'); + process.exit(1); + } + const classes = filterForJava(parseDocs(path.resolve(process.argv[2]))) + .filter(clazz => !HANDWRITTEN_CLASSES.includes(clazz.name)); + + const topLevelTypes = new Map(); + generateInterfaces(classes.filter(clazz => !isAssertionClass(clazz.name)), API_DIR, API_PACKAGE, topLevelTypes); + // TODO: generate SoftAssertions once they are implemented. + generateInterfaces(classes.filter(clazz => isAssertionClass(clazz.name) && !clazz.name.includes('SoftAssertions')), + path.join(API_DIR, 'assertions'), `${API_PACKAGE}.assertions`, topLevelTypes); + for (const type of topLevelTypes.values()) { + if (type instanceof CustomInterface) + writeFile(API_DIR, API_PACKAGE, type); + else + writeFile(path.join(API_DIR, 'options'), `${API_PACKAGE}.options`, type); + } + console.log(`Generated the Java API in ${path.relative(process.cwd(), API_DIR)}`); +} + +main(); diff --git a/tools/api-generator/pom.xml b/tools/api-generator/pom.xml deleted file mode 100644 index 2e75e4c4e..000000000 --- a/tools/api-generator/pom.xml +++ /dev/null @@ -1,41 +0,0 @@ - - - 4.0.0 - - com.microsoft.playwright - api-generator - 1.50.0-SNAPSHOT - Playwright - API Generator - - This is an internal module used to generate Java API from the upstream Playwright - definitions. It's an internal development module not intended for external use. - - - 1.8 - 2.8.9 - UTF-8 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.12.1 - - ${compiler.version} - ${compiler.version} - - - - - - - com.google.code.gson - gson - ${gson.version} - - - diff --git a/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java b/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java deleted file mode 100644 index 81e48a0fb..000000000 --- a/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java +++ /dev/null @@ -1,1500 +0,0 @@ -/* - * Copyright (c) Microsoft Corporation. - * - * Licensed 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. - */ - -package com.microsoft.playwright.tools; - -import com.google.gson.Gson; -import com.google.gson.JsonArray; -import com.google.gson.JsonElement; -import com.google.gson.JsonObject; - -import java.io.*; -import java.nio.file.FileSystems; -import java.util.*; -import java.util.function.Predicate; -import java.util.regex.Matcher; -import java.util.regex.Pattern; -import java.util.stream.Collectors; - -import static java.util.Arrays.asList; -import static java.util.Collections.reverse; -import static java.util.stream.Collectors.joining; -import static java.util.stream.Collectors.toList; - -abstract class Element { - final String jsonName; - final String jsonPath; - final JsonElement jsonElement; - final Element parent; - - Element(Element parent, JsonElement jsonElement) { - this(parent, false, jsonElement); - } - - Element(Element parent, boolean useParentJsonPath, JsonElement jsonElement) { - this.parent = parent; - if (jsonElement != null && jsonElement.isJsonObject()) { - this.jsonName = jsonElement.getAsJsonObject().get("name").getAsString(); - } else { - this.jsonName = ""; - } - if (useParentJsonPath) { - this.jsonPath = parent.jsonPath; - } else { - this.jsonPath = parent == null ? jsonName : parent.jsonPath + "." + jsonName ; - } - this.jsonElement = jsonElement; - } - - - TypeDefinition typeScope() { - return parent.typeScope(); - } - - Map topLevelTypes() { - return parent.topLevelTypes(); - } - - static String toTitle(String name) { - return Character.toUpperCase(name.charAt(0)) + name.substring(1); - } - - void writeJavadoc(List output, String offset, String text) { - if (text.isEmpty()) { - return; - } - output.add(offset + "/**"); - String[] lines = text.split("\\n"); - for (String line : lines) { - output.add((offset + " *" + (line.isEmpty() ? "" : " ") + line) - .replace("*/", "*\\/")); - } - output.add(offset + " */"); - } - - String comment() { - JsonObject json = jsonElement.getAsJsonObject(); - if (!json.has("spec")) { - return ""; - } - if (json.has("deprecated")) { - return "@deprecated " + beautify(json.get("deprecated").getAsString()); - } - return formatSpec(json.getAsJsonArray("spec")); - } - - private static String formatSpec(JsonArray spec) { - List out = new ArrayList<>(); - String currentItemList = null; - for (JsonElement item : spec) { - JsonObject node = item.getAsJsonObject(); - String type = node.get("type").getAsString(); - if ("li".equals(type)) { - String text = node.get("text").getAsString(); - if (text.startsWith("extends: ")) { - continue; - } - if (currentItemList == null) { - String liType = node.get("liType").getAsString(); - if ("ordinal".equals(liType)) { - currentItemList = "ol"; - out.add("
      "); - } else { - currentItemList = "ul"; - out.add("
        "); - } - } - out.add("
      • " + beautify(text) + "
      • "); - continue; - } else { - if (currentItemList != null) { - out.add(""); - currentItemList = null; - } - } - if ("code".equals(type)) { - if (!node.get("codeLang").getAsString().contains("java")) { - continue; - } - out.add("
        {@code");
        -        for (JsonElement line : node.getAsJsonArray("lines")) {
        -          out.add(line.getAsString());
        -        }
        -        out.add("}
        "); - } else if ("note".equals(type)) { - StringBuilder paragraph = new StringBuilder(); - if (!out.isEmpty()) - paragraph.append("\n

        "); - paragraph.append("NOTE: "); - for (JsonElement text : node.getAsJsonArray("children")) { - if (!"text".equals(text.getAsJsonObject().get("type").getAsString())) { - continue; - } - paragraph.append(beautify(text.getAsJsonObject().get("text").getAsString())); - } - out.add(paragraph.toString()); - } else { - String paragraph = node.get("text").getAsString(); - Matcher matcher = Pattern.compile("^\\*\\*(.+)\\*\\*$").matcher(paragraph); - // Format **Usage**, **Details** as bold text. - if (matcher.matches()) { - String title = matcher.group(1); - paragraph = "" + title + ""; - } else { - paragraph = beautify(paragraph); - } - if (!out.isEmpty()) - paragraph = "\n

        " + paragraph; - out.add(paragraph); - } - } - if (currentItemList != null) { - out.add(""); - currentItemList = null; - } - - return String.join("\n", out); - } - - private static String beautify(String paragraph) { - String linkified = linkifyMemberRefs(paragraph); - linkified = updateExternalLinks(linkified) - .replaceAll("↵", " ") - .replaceAll("`'([^`]+)'`", "{@code \"$1\"}") - .replaceAll("`([^`]+)`", "{@code $1}"); - return wrapText(linkified, 120, ""); - } - - private static String linkifyMemberRefs(String paragraph) { - Matcher matcher = Pattern.compile("\\[`(event|property|method): ([^`]+)`]").matcher(paragraph); - String linkified = ""; - int start = 0; - while (matcher.find()) { - linkified += paragraph.substring(start, matcher.start()); - String name = matcher.group(2); - if (ApiGenerator.aliases.containsKey(name)) { - name = ApiGenerator.aliases.get(name); - } - if ("event".equals(matcher.group(1))) { - String[] parts = name.split("\\."); - name = parts[0] + ".on" + toTitle(parts[1]); - } - String packagePrefix = ""; - if (ApiGenerator.isAssertionClass(name.split("\\.")[0])) { - packagePrefix = "com.microsoft.playwright.assertions."; - } else { - packagePrefix = "com.microsoft.playwright."; - } - linkified += "{@link " + packagePrefix + name.replace(".", "#") + " " + name + "()}"; - start = matcher.end(); - } - linkified += paragraph.substring(start); - return linkified; - } - - private static String updateExternalLinks(String paragraph) { - Matcher matcher = Pattern.compile("\\[([^\\]]+)\\]\\(([^\\)]+)\\)").matcher(paragraph); - String linkified = ""; - int start = 0; - while (matcher.find()) { - String url = matcher.group(2); - if (url.startsWith("../")) { - // ../actionability.md#editable => https://playwright.dev/java/docs/actionability/#editable - url = url.replace(".md", ""); - url = url.replace("../", "https://playwright.dev/java/docs/"); - } - if (url.startsWith("./")) { - // ./class-tracing.md => https://playwright.dev/java/docs/api/class-tracing - url = url.replace(".md", ""); - url = url.replace("./", "https://playwright.dev/java/docs/api/"); - } - String link = "" + matcher.group(1) + ""; - linkified += paragraph.substring(start, matcher.start()); - linkified += link; - start = matcher.end(); - } - linkified += paragraph.substring(start); - linkified = linkified.replaceAll("\\[Promise\\]", - "Promise"); - return linkified; - } - - - private static List tokenizeNoBreakLinks(String text) { - List links = new ArrayList<>(); - // Don't wrap simple links with spaces. - Matcher mather = Pattern.compile("\\[[^\\]]+\\]").matcher(text); - String sanitized = ""; - int start = 0; - while (mather.find()) { - sanitized += text.substring(start, mather.start()); - sanitized += "[" + links.size() + "]"; - start = mather.end(); - links.add(mather.group()); - } - sanitized += text.substring(start, text.length()); - List tokens = Arrays.asList(sanitized.split(" ")); - for (int i = 0; i < links.size(); i++) { - int index = i; - tokens = tokens.stream().map(s -> s.replace("[" + index + "]", links.get(index))).collect(Collectors.toList()); - } - return tokens; - } - - private static String wrapText(String text, int maxColumns, String prefix) { - if (maxColumns == 0) - return prefix + text; - if (text.trim().startsWith("|")) - return prefix + text; - String indent = prefix; - List lines = new ArrayList<>(); - maxColumns -= indent.length(); - List words = tokenizeNoBreakLinks(text); - String line = ""; - for (String word : words) { - if (!line.isEmpty() && line.length() + word.length() < maxColumns) { - line += " " + word; - } else { - if (!line.isEmpty()) - lines.add(line); - line = (!lines.isEmpty() ? indent : prefix) + word; - } - } - if (!line.isEmpty()) - lines.add(line); - return String.join("\n", lines); - } -} - -// Represents return type of a method, type of a method param or type of a field. -class TypeRef extends Element { - String customType; - - // Returns the Java-specific type alias declared in the api docs (e.g. `alias-java: Cookie`), - // falling back to the language-agnostic `alias` if no Java-specific override is provided. - private static String javaAlias(JsonObject jsonType) { - if (!jsonType.has("langAliases")) { - return null; - } - JsonObject langAliases = jsonType.getAsJsonObject("langAliases"); - if (langAliases.has("java")) { - return langAliases.get("java").getAsString(); - } - if (langAliases.has("default")) { - return langAliases.get("default").getAsString(); - } - return null; - } - - TypeRef(Element parent, JsonElement jsonElement) { - super(parent, true, jsonElement); - - createClassesAndEnums(jsonElement.getAsJsonObject()); - } - - private void createClassesAndEnums(JsonObject jsonObject) { - if (jsonObject.has("union")) { - if (jsonObject.get("name").getAsString().isEmpty()) { - for (JsonElement item : jsonObject.getAsJsonArray("union")) { - if (item.isJsonObject()) { - createClassesAndEnums(item.getAsJsonObject()); - } - } - } else { - typeScope().createEnum(jsonObject); - } - return; - } - if (jsonObject.has("templates")) { - for (JsonElement item : jsonObject.getAsJsonArray("templates")) { - if (item.isJsonObject()) { - createClassesAndEnums(item.getAsJsonObject()); - } - } - return; - } - if ("function".equals(jsonObject.get("name").getAsString()) && jsonObject.has("args")) { - for (JsonElement item : jsonObject.getAsJsonArray("args")) { - if (!item.isJsonObject()) { - continue; - } - JsonObject argObject = item.getAsJsonObject(); - if (!"Object".equals(argObject.get("name").getAsString())) { - continue; - } - String alias = javaAlias(argObject); - if (alias != null) { - typeScope().createTopLevelInterface(alias, this, argObject); - } - } - return; - } - if ("Object".equals(jsonObject.get("name").getAsString())) { - if (customType != null) { - // Same type maybe referenced as 'Object' in several union values, e.g. Object|Array - return; - } - if (parent instanceof Param && "options".equals(parent.jsonName)) { - customType = toTitle(parent.parent.jsonName) + toTitle(parent.jsonName); - typeScope().createNestedClass(customType, this, jsonObject); - } else { - String alias = javaAlias(jsonObject); - if (alias != null) { - customType = alias; - } else { - customType = toTitle(parent.jsonName); - } - typeScope().createTopLevelClass(customType, this, jsonObject); - } - } - } - - String toJava() { - if (jsonElement.isJsonNull()) { - return "void"; - } - return convertBuiltinType(stripNullable()); - } - - String toJavaWithNullability() { - return withNullability(toJava(), false); - } - - // Adds @Nullable to the given Java rendering of this type when the type itself admits null - // or when it is used in an optional slot (parameter or field). - String withNullability(String javaType, boolean optional) { - return optional || isNullableInJava() ? nullable(javaType) : javaType; - } - - // Serializable is mapped to Object and JSON null is a valid value for it. - private boolean isNullableInJava() { - return isNullable() || "Serializable".equals(stripNullable().get("name").getAsString()); - } - - static String nullable(String javaType) { - if (javaType.endsWith("[]")) { - return javaType.substring(0, javaType.length() - 2) + " @Nullable []"; - } - return "@Nullable " + javaType; - } - - // Primitive types produced by convertBuiltinType and their boxed counterparts. - private static final Map BOXED_TYPES = new HashMap<>(); - static { - BOXED_TYPES.put("int", "Integer"); - BOXED_TYPES.put("double", "Double"); - BOXED_TYPES.put("boolean", "Boolean"); - } - - static String boxed(String javaType) { - return BOXED_TYPES.getOrDefault(javaType, javaType); - } - - boolean isCustomClass() { - JsonObject jsonObject = stripNullable(); - if (!"Object".equals(jsonObject.get("name").getAsString())) { - return false; - } - return !jsonElement.getAsJsonObject().has("templates"); - } - - boolean isTypeUnion() { - if (isNullable()) { - return false; - } - if (!jsonElement.getAsJsonObject().has("union")) { - return false; - } - return jsonElement.getAsJsonObject().get("name").getAsString().isEmpty(); - } - - private List supportedUnionTypes() { - List result = new ArrayList<>(); - for (JsonElement item : jsonElement.getAsJsonObject().getAsJsonArray("union")) { - JsonObject o = item.getAsJsonObject(); - if (o.get("name").getAsString().equals("function") && !o.has("args")) { - continue; - } - if (o.get("name").getAsString().equals("null")) { - continue; - } - result.add(o); - } - return result; - } - - int unionSize() { - return supportedUnionTypes().size(); - } - - // True for Object|Array unions where both refer to the same custom class. - boolean isCustomClassOrListUnion() { - if (customType == null || !isTypeUnion()) { - return false; - } - List types = supportedUnionTypes(); - if (types.size() != 2) { - return false; - } - boolean hasObject = false; - boolean hasList = false; - for (JsonObject o : types) { - String name = o.get("name").getAsString(); - if ("Object".equals(name)) { - hasObject = true; - } else if ("Array".equals(name) && o.has("templates") && o.getAsJsonArray("templates").size() == 1 - && "Object".equals(o.getAsJsonArray("templates").get(0).getAsJsonObject().get("name").getAsString())) { - hasList = true; - } - } - return hasObject && hasList; - } - - String formatTypeFromUnion(int i) { - JsonElement overloadedType = supportedUnionTypes().get(i); - return convertBuiltinType(overloadedType.getAsJsonObject()); - } - - boolean isNullable() { - JsonObject jsonType = jsonElement.getAsJsonObject(); - if (!jsonType.has("union")) { - return false; - } - if (!jsonType.get("name").getAsString().isEmpty()) { - return false; - } - JsonArray values = jsonType.getAsJsonArray("union"); - if (values.size() != 2) { - return false; - } - for (JsonElement item : values) { - JsonObject o = item.getAsJsonObject(); - if ("null".equals(o.get("name").getAsString())) { - return true; - } - } - return false; - } - - private JsonObject stripNullable() { - JsonObject jsonType = jsonElement.getAsJsonObject(); - if (!isNullable()) { - return jsonType; - } - if (!jsonType.has("union")) { - return jsonType; - } - if (!jsonType.get("name").getAsString().isEmpty()) { - return jsonType; - } - JsonArray values = jsonType.getAsJsonArray("union"); - if (values.size() != 2) { - return jsonType; - } - for (JsonElement item : values) { - JsonObject o = item.getAsJsonObject(); - if (!"null".equals(o.get("name").getAsString())) { - return o; - } - } - throw new RuntimeException("Unexpected union " + jsonPath + ": " + jsonType); - } - - private String convertBuiltinType(JsonObject jsonType) { - String name = jsonType.get("name").getAsString(); - if (jsonType.has("union")) { - if (name.isEmpty()) { - if (parent instanceof Field) { - return "Object"; - } - throw new RuntimeException("Unexpected union without name: " + jsonType); - } - return name; - } - if ("int".equals(name)) { - return "int"; - } - if ("float".equals(name)) { - return "double"; - } - if ("string".equals(name)) { - return "String"; - } - if ("void".equals(name)) { - return "void"; - } - if ("path".equals(name)) { - return "Path"; - } - if ("EvaluationArgument".equals(name)) { - return "Object"; - } - if ("Serializable".equals(name)) { - return "Object"; - } - if ("any".equals(name)) { - return "Object"; - } - if ("Readable".equals(name)) { - return "InputStream"; - } - if ("Buffer".equals(name)) { - return "byte[]"; - } - if ("Disposable".equals(name)) { - return "AutoCloseable"; - } - if ("URL".equals(name)) { - return "String"; - } - if ("RegExp".equals(name)) { - return "Pattern"; - } - if ("Array".equals(name)) { - String elementType = convertTemplateParams(jsonType); - if (parent instanceof Param && isTypeUnion()) { - long numArrayOverloads = supportedUnionTypes().stream().filter( - jsonObject -> "Array".equals(jsonObject.get("name").getAsString())).count(); - if (numArrayOverloads > 1) { - // Use array instead of List as after type erasure all lists are indistinguishable and wouldn't allow overloads. - return elementType + "[]"; - } - } - return "List<" + elementType + ">"; - } - if ("Object".equals(name)) { - if (customType != null) { - return customType; - } - // Inner Objects without langAliases (e.g. unaliased function arguments) are not visited - // by createClassesAndEnums, so resolve their Java type name from langAliases here. - String alias = javaAlias(jsonType); - if (alias != null) { - return alias; - } - return "Map<" + convertTemplateParams(jsonType) + ">"; - } - if ("Map".equals(name)) { - return "Map<" + convertTemplateParams(jsonType) + ">"; - } - if ("Promise".equals(name)) { - return convertTemplateParams(jsonType); - } - if ("function".equals(name)) { - String alias = javaAlias(jsonType); - if (alias != null) { - return alias; - } - if (!jsonType.has("args")) { - throw new RuntimeException("Missing mapping for " + jsonPath); - } - if ("WebSocketRoute.onClose.handler".equals(jsonPath)) { - return "BiConsumer"; - } - if (jsonType.getAsJsonArray("args").size() == 1) { - String paramType = convertBuiltinType(jsonType.getAsJsonArray("args").get(0).getAsJsonObject()); - if (!jsonType.has("returnType") || jsonType.get("returnType").isJsonNull()) { - return "Consumer<" + paramType + ">"; - } - String returnTypeName = jsonType.getAsJsonObject("returnType").get("name").getAsString(); - if ("boolean".equals(returnTypeName)) { - return "Predicate<" + paramType + ">"; - } - if ("Promise".equals(returnTypeName) || "void".equals(returnTypeName)) { - return "Consumer<" + paramType + ">"; - } - throw new RuntimeException("Missing mapping for " + jsonType); - } - } - return name; - } - - private String convertTemplateParams(JsonObject jsonType) { - if (!jsonType.has("templates")) { - return ""; - } - List params = new ArrayList<>(); - for (JsonElement item : jsonType.getAsJsonArray("templates")) { - params.add(convertBuiltinType(item.getAsJsonObject())); - } - return String.join(", ", params); - } -} - -abstract class TypeDefinition extends Element { - final List classes = new ArrayList<>(); - - TypeDefinition(Element parent, JsonObject jsonElement) { - super(parent, jsonElement); - } - - TypeDefinition(Element parent, boolean useParentJsonPath, JsonObject jsonElement) { - super(parent, useParentJsonPath, jsonElement); - } - - String name() { - return jsonName; - } - - @Override - TypeDefinition typeScope() { - return this; - } - - void createEnum(JsonObject jsonObject) { - Enum newEnum = new Enum(this, jsonObject); - if (newEnum.jsonName == null) { - throw new RuntimeException("Enum without name: " + jsonObject); - } - Map enumMap = topLevelTypes(); - TypeDefinition existing = enumMap.putIfAbsent(newEnum.jsonName, newEnum); - if (existing != null && (!(existing instanceof Enum) || !((Enum) existing).hasSameValues(newEnum))) { - throw new RuntimeException("Two enums with same name have different values:\n" + jsonObject + "\n" + existing.jsonElement); - } - } - - void createTopLevelClass(String name, Element parent, JsonObject jsonObject) { - Map map = topLevelTypes(); - TypeDefinition existing = map.putIfAbsent(name, new CustomClass(parent, name, jsonObject)); - if (existing != null && (!(existing instanceof CustomClass))) { - throw new RuntimeException("Two classes with same name have different values:\n" + jsonObject + "\n" + existing.jsonElement); - } - } - - void createTopLevelInterface(String name, Element parent, JsonObject jsonObject) { - Map map = topLevelTypes(); - TypeDefinition existing = map.putIfAbsent(name, new CustomInterface(parent, name, jsonObject)); - if (existing != null && !(existing instanceof CustomInterface)) { - throw new RuntimeException("Two interfaces with same name have different values:\n" + jsonObject + "\n" + existing.jsonElement); - } - } - - void createNestedClass(String name, Element parent, JsonObject jsonObject) { - for (CustomClass c : classes) { - if (c.name.equals(name)) { - return; - } - } - classes.add(new CustomClass(parent, name, jsonObject)); - } - - void writeTo(List output, String offset) { - for (CustomClass c : classes) { - c.writeTo(output, offset); - } - } -} - -class Event extends Element { - private final TypeRef type; - - Event(Element parent, JsonObject jsonElement) { - super(parent, jsonElement); - type = new TypeRef(this, jsonElement.get("type")); - } - - void writeListenerMethods(List output, String offset) { - writeJavadoc(output, offset, comment()); - String name = toTitle(jsonName); - String paramType = type.toJavaWithNullability(); - String listenerType = "void".equals(paramType) ? "Runnable" : "Consumer<" + paramType + ">"; - output.add(offset + "void on" + name + "(" + listenerType + " handler);"); - writeJavadoc(output, offset, "Removes handler that was previously added with {@link #on" + name + " on" + name + "(handler)}."); - output.add(offset + "void off" + name + "(" + listenerType + " handler);"); - } -} - -class Method extends Element { - final TypeRef returnType; - final List params = new ArrayList<>(); - - Method(TypeDefinition parent, JsonObject jsonElement) { - super(parent, jsonElement); - returnType = new TypeRef(this, jsonElement.get("type")); - if (jsonElement.has("args")) { - for (JsonElement arg : jsonElement.getAsJsonArray("args")) { - JsonObject paramObj = arg.getAsJsonObject(); - if (paramObj.get("name").getAsString().equals("options") && - paramObj.getAsJsonObject("type").getAsJsonArray("properties").size() == 0) { - continue; - } - params.add(new Param(this, arg.getAsJsonObject())); - } - } - } - - void writeTo(List output, String offset) { - if ("Playwright.create".equals(jsonPath)) { - writeJavadoc(params, output, offset); - output.add(offset + "static Playwright create(" + params.get(0).toJava() + ") {"); - output.add(offset + " return PlaywrightImpl.create(options);"); - output.add(offset + "}"); - output.add(""); - output.add(offset + "static Playwright create() {"); - output.add(offset + " return create(null);"); - output.add(offset + "}"); - return; - } - if ("FormData.create".equals(jsonPath)) { - writeJavadoc(params, output, offset); - output.add(offset + "static FormData create() {"); - output.add(offset + " return new FormDataImpl();"); - output.add(offset + "}"); - return; - } - if ("RequestOptions.create".equals(jsonPath)) { - writeJavadoc(params, output, offset); - output.add(offset + "static RequestOptions create() {"); - output.add(offset + " return new RequestOptionsImpl();"); - output.add(offset + "}"); - return; - } - if ("PlaywrightAssertions.assertThat".equals(jsonPath)) { - writeJavadoc(params, output, offset); - String originalName = jsonElement.getAsJsonObject().get("originalName").getAsString(); - if ("expectPage".equals(originalName)) { - output.add(offset + "static PageAssertions assertThat(Page page) {"); - output.add(offset + " return new PageAssertionsImpl(page);"); - output.add(offset + "}"); - output.add(""); - } else if ("expectLocator".equals(originalName)) { - output.add(offset + "static LocatorAssertions assertThat(Locator locator) {"); - output.add(offset + " return new LocatorAssertionsImpl(locator);"); - output.add(offset + "}"); - output.add(""); - } else if ("expectAPIResponse".equals(originalName)) { - output.add(offset + "static APIResponseAssertions assertThat(APIResponse response) {"); - output.add(offset + " return new APIResponseAssertionsImpl(response);"); - output.add(offset + "}"); - output.add(""); - } else { - throw new RuntimeException("Unexpected originalName: " + originalName); - } - return; - } - if ("PlaywrightAssertions.setDefaultAssertionTimeout".equals(jsonPath)) { - writeJavadoc(params, output, offset); - output.add(offset + "static void setDefaultAssertionTimeout(double timeout) {"); - output.add(offset + " AssertionsTimeout.setDefaultTimeout(timeout);"); - output.add(offset + "}"); - output.add(""); - return; - } - int numOverloads = 1; - for (int i = 0; i < params.size(); i++) { - if (params.get(i).type.isTypeUnion()) { - numOverloads = params.get(i).type.unionSize(); - break; - } - } - - for (int i = 0; i < numOverloads; i++) { - writeOverloadedMethods(i, output, offset); - } - } - - private void writeOverloadedMethods(int overloadIndex, List output, String offset) { - for (int i = params.size() - 1; i >= 0; i--) { - Param p = params.get(i); - if (!p.isOptional()) { - continue; - } - // For optional overloaded params generate only overload without the param. - if (p.type.isTypeUnion() && overloadIndex != 0) { - continue; - } - writeDefaultOverloadedMethod(overloadIndex, i, output, offset); - } - - List paramList = params.stream().map(p -> p.type.isTypeUnion() ? p.toJavaOverload(overloadIndex) : p.toJava()).collect(toList()); - writeJavadoc(params, output, offset); - output.add(offset + returnType.toJavaWithNullability() + " " + jsonName + "(" + String.join(", ", paramList) + ");"); - } - - - private void writeDefaultOverloadedMethod(int overloadIndex, int firstNullOptional, List output, String offset) { - List paramList = new ArrayList<>(); - List argList = new ArrayList<>(); - for (int i = 0; i < params.size(); i++) { - Param p = params.get(i); - if (i == firstNullOptional) { - if (p.type.isTypeUnion()) { - String type = p.type.formatTypeFromUnion(overloadIndex); - argList.add("int".equals(type) ? "0" : "(" + type + ") null"); - } else { - String defaultValue = "null"; - // TODO: it should probably be done for all methods that have name#1, name#2 etc overloads. - if ("LocatorAssertions.hasAttribute".equals(jsonPath)) { - defaultValue = "(" + p.type.toJava() + ") " + defaultValue; - } - argList.add(defaultValue); - } - continue; - } - if (p.isOptional() && i > firstNullOptional) { - continue; - } - paramList.add(p); - argList.add(p.jsonName); - } - String paramsStr = paramList.stream().map(p -> p.type.isTypeUnion() ? p.toJavaOverload(overloadIndex) : p.toJava()) - .collect(joining(", ")); - String returns = returnType.toJava().equals("void") ? "" : "return "; - writeJavadoc(paramList, output, offset); - output.add(offset + "default " + returnType.toJavaWithNullability() + " " + jsonName + "(" + paramsStr + ") {"); - output.add(offset + " " + returns + jsonName + "(" + String.join(", ", argList) + ");"); - output.add(offset + "}"); - } - - private void writeJavadoc(List paramList, List output, String offset) { - List sections = new ArrayList<>(); - sections.add(comment()); - boolean hasBlankLine = false; - if (!paramList.isEmpty()) { - for (Param p : paramList) { - String comment = p.comment(); - if (comment.isEmpty()) { - continue; - } - if (!hasBlankLine) { - sections.add(""); - hasBlankLine = true; - } - sections.add("@param " + p.jsonName + " " + comment); - } - } - if (jsonElement.getAsJsonObject().has("returnComment")) { - if (!hasBlankLine) { - sections.add(""); - hasBlankLine = true; - } - String returnComment = jsonElement.getAsJsonObject().get("returnComment").getAsString(); - sections.add("@return " + returnComment); - } - if (jsonElement.getAsJsonObject().has("since")) { - if (!hasBlankLine) { - sections.add(""); - hasBlankLine = true; - } - String since = jsonElement.getAsJsonObject().get("since").getAsString(); - sections.add("@since " + since); - } - writeJavadoc(output, offset, String.join("\n", sections)); - } -} - -class Param extends Element { - final TypeRef type; - - Param(Method method, JsonObject jsonElement) { - super(method, jsonElement); - type = new TypeRef(this, jsonElement.get("type").getAsJsonObject()); - } - - boolean isOptional() { - return !jsonElement.getAsJsonObject().get("required").getAsBoolean(); - } - - String toJavaOverload(int overoadIndex) { - return type.withNullability(type.formatTypeFromUnion(overoadIndex), isOptional()) + " " + jsonName; - } - - String toJava() { - return type.withNullability(type.toJava(), isOptional()) + " " + jsonName; - } -} - -class Field extends Element { - final String name; - final TypeRef type; - - Field(TypeDefinition parent, String name, JsonObject jsonElement) { - super(parent, jsonElement); - this.name = name; - this.type = new TypeRef(this, jsonElement.getAsJsonObject().get("type")); - } - - boolean isRequired() { - return jsonElement.getAsJsonObject().has("required") && - jsonElement.getAsJsonObject().get("required").getAsBoolean(); - } - - void writeTo(List output, String offset) { - writeJavadoc(output, offset, comment()); - String typeStr = type.toJava(); - if (type.isNullable()) { - typeStr = "Optional<" + typeStr + ">"; - } - if (isBrowserChannelOption()) { - typeStr = "Object"; - } - // Optional fields are boxed so that they can hold null. - if (!isRequired()) { - typeStr = TypeRef.nullable(TypeRef.boxed(typeStr)); - } - output.add(offset + "public " + typeStr + " " + name + ";"); - } - - void writeBuilderMethod(List output, String offset, String parentClass) { - if (type.isTypeUnion() && (type.customType == null || type.isCustomClassOrListUnion())) { - // Union of a custom class and its list, e.g. Object|Array for httpCredentials, - // gets the convenience setter with the required fields in addition to the overloads. - if (type.customType != null) { - writeRequiredFieldsBuilderMethod(output, offset, parentClass); - } - for (int i = 0; i < type.unionSize(); i++) { - writeGenericBuilderMethod(output, offset, parentClass, type.formatTypeFromUnion(i)); - } - return; - } - if (type.isCustomClass()) { - writeRequiredFieldsBuilderMethod(output, offset, parentClass); - } - - if (isBrowserChannelOption()) { - output.add(offset + "@Deprecated"); - writeGenericBuilderMethod(output, offset, parentClass, "BrowserChannel"); - } - - writeGenericBuilderMethod(output, offset, parentClass, type.toJava()); - } - - // Convenience setter taking the required fields of the custom class, e.g. setHttpCredentials(username, password). - private void writeRequiredFieldsBuilderMethod(List output, String offset, String parentClass) { - TypeDefinition customType = topLevelTypes().get(type.customType); - if (!(customType instanceof CustomClass)) { - return; - } - CustomClass clazz = (CustomClass) customType; - List params = new ArrayList<>(); - List args = new ArrayList<>(); - for (Field f : clazz.fields) { - if (!f.isRequired()) { - continue; - } - params.add(f.type.toJavaWithNullability() + " " + f.name); - args.add(f.name); - } - if (params.isEmpty()) { - return; - } - writeJavadoc(output, offset, comment()); - output.add(offset + "public " + parentClass + " set" + toTitle(name) + "(" + String.join(", ", params) + ") {"); - output.add(offset + " return set" + toTitle(name) + "(new " + type.customType + "(" + String.join(", ", args) + "));"); - output.add(offset + "}"); - } - - private void writeGenericBuilderMethod(List output, String offset, String parentClass, String paramType) { - writeJavadoc(output, offset, comment()); - String param = type.withNullability(paramType, false); - output.add(offset + "public " + parentClass + " set" + toTitle(name) + "(" + param + " " + name + ") {"); - String rvalue = type.isNullable() ? "Optional.ofNullable(" + name + ")" : name; - output.add(offset + " this." + name + " = " + rvalue + ";"); - output.add(offset + " return this;"); - output.add(offset + "}"); - } - - private boolean isBrowserChannelOption() { - return asList("BrowserType.launch.options.channel", "BrowserType.launchPersistentContext.options.channel").contains(jsonPath); - } -} - -class Interface extends TypeDefinition { - private final List methods = new ArrayList<>(); - private final List events = new ArrayList<>(); - private final Map topLevelTypes; - static final String header = "/*\n" + - " * Copyright (c) Microsoft Corporation.\n" + - " *\n" + - " * Licensed under the Apache License, Version 2.0 (the \"License\");\n" + - " * you may not use this file except in compliance with the License.\n" + - " * You may obtain a copy of the License at\n" + - " *\n" + - " * http://www.apache.org/licenses/LICENSE-2.0\n" + - " *\n" + - " * Unless required by applicable law or agreed to in writing, software\n" + - " * distributed under the License is distributed on an \"AS IS\" BASIS,\n" + - " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" + - " * See the License for the specific language governing permissions and\n" + - " * limitations under the License.\n" + - " */\n"; - - private static Set allowedBaseInterfaces = new HashSet<>(asList("Browser", "JSHandle", "BrowserContext")); - private static Set autoCloseableInterfaces = new HashSet<>(asList("Playwright", "Browser", "BrowserContext", "Page")); - - Interface(JsonObject jsonElement, Map topLevelTypes) { - super(null, jsonElement); - this.topLevelTypes = topLevelTypes; - for (JsonElement item : jsonElement.getAsJsonArray("members")) { - JsonObject memberJson = item.getAsJsonObject(); - switch (memberJson.get("kind").getAsString()) { - case "method": - // All properties are converted to methods in Java. - case "property": - methods.add(new Method(this, memberJson)); - break; - case "event": - events.add(new Event(this, memberJson)); - break; - default: - throw new RuntimeException("Unexpected member kind: " + memberJson.toString()); - } - } - } - - @Override - Map topLevelTypes() { - return topLevelTypes; - } - - void writeTo(List output, String offset) { - // Interfaces with a static factory method, see Method.writeTo. - if (asList("Playwright", "FormData", "RequestOptions").contains(jsonName) && methods.stream().anyMatch(m -> "create".equals(m.jsonName))) { - output.add("import com.microsoft.playwright.impl." + jsonName + "Impl;"); - } - if (asList("Page", "Request", "Response", "APIRequestContext", "APIRequest", "APIResponse", "FileChooser", "Frame", "FrameLocator", "ElementHandle", "Locator", "Browser", "BrowserContext", "BrowserType", "Mouse", "Keyboard", "Tracing", "Video", "Debugger", "Screencast", "WebError", "Credentials", "WebStorage", "WebMCP").contains(jsonName)) { - output.add("import com.microsoft.playwright.options.*;"); - } - if ("Download".equals(jsonName)) { - output.add("import java.io.InputStream;"); - } - if (asList("Page", "Frame", "ElementHandle", "Locator", "FormData", "APIRequest", "APIRequestContext", "FileChooser", "Browser", "BrowserContext", "BrowserType", "Download", "Route", "Selectors", "Tracing", "Video", "Screencast").contains(jsonName)) { - output.add("import java.nio.file.Path;"); - } - if ("Clock".equals(jsonName)) { - output.add("import java.util.Date;"); - } - if (asList("Page", "Frame", "ElementHandle", "Locator", "LocatorAssertions", "APIRequest", "APIRequestContext", "Browser", "BrowserContext", "BrowserType", "Route", "Request", "Response", "JSHandle", "ConsoleMessage", "APIResponse", "Playwright", "Debugger", "Screencast", "WebSocketRoute", "Credentials", "WebStorage", "WebMCP").contains(jsonName)) { - output.add("import java.util.*;"); - } - if (asList("WebSocketRoute").contains(jsonName)) { - output.add("import java.util.function.BiConsumer;"); - } - if (asList("Page", "Browser", "BrowserContext", "WebSocket", "Worker", "CDPSession", "WebSocketRoute", "Screencast").contains(jsonName)) { - output.add("import java.util.function.Consumer;"); - } - if (asList("Page", "BrowserContext").contains(jsonName)) { - output.add("import java.util.function.BooleanSupplier;"); - } - - if (asList("Page", "Frame", "BrowserContext", "WebSocket", "Worker").contains(jsonName)) { - output.add("import java.util.function.Predicate;"); - } - if (asList("Page", "Frame", "FrameLocator", "Locator", "APIRequestContext", "Browser", "BrowserType", "BrowserContext", "PageAssertions", "LocatorAssertions", "Tracing").contains(jsonName)) { - output.add("import java.util.regex.Pattern;"); - } - if ("CDPSession".equals(jsonName)) { - output.add("import com.google.gson.JsonObject;"); - } - if ("LocatorAssertions".equals(jsonName)) { - output.add("import com.microsoft.playwright.options.AriaRole;"); - output.add("import com.microsoft.playwright.options.PseudoElement;"); - } - if ("PlaywrightAssertions".equals(jsonName)) { - output.add("import com.microsoft.playwright.APIResponse;"); - output.add("import com.microsoft.playwright.Locator;"); - output.add("import com.microsoft.playwright.Page;"); - output.add("import com.microsoft.playwright.impl.APIResponseAssertionsImpl;"); - output.add("import com.microsoft.playwright.impl.AssertionsTimeout;"); - output.add("import com.microsoft.playwright.impl.LocatorAssertionsImpl;"); - output.add("import com.microsoft.playwright.impl.PageAssertionsImpl;"); - } - output.add(""); - - List superInterfaces = new ArrayList<>(); - if (jsonElement.getAsJsonObject().has("extends")) { - String base = jsonElement.getAsJsonObject().get("extends").getAsString(); - if (allowedBaseInterfaces.contains(base)) { - superInterfaces.add(base); - } - } - if (autoCloseableInterfaces.contains(jsonName)) { - superInterfaces.add("AutoCloseable"); - } - String implementsClause = superInterfaces.isEmpty() ? "" : " extends " + String.join(", ", superInterfaces); - - writeJavadoc(output, offset, comment()); - output.add("public interface " + jsonName + implementsClause + " {"); - offset = " "; - writeEvents(output, offset); - super.writeTo(output, offset); - for (Method m : methods) { - m.writeTo(output, offset); - } - output.add("}"); - output.add("\n"); - } - - private void writeEvents(List output, String offset) { - if (events.isEmpty()) { - return; - } - for (Event e : events) { - output.add(""); - e.writeListenerMethods(output, offset); - } - output.add(""); - } -} - -class CustomClass extends TypeDefinition { - final String name; - final List fields = new ArrayList<>(); - - CustomClass(Element parent, String name, JsonObject jsonElement) { - super(parent, true, jsonElement); - this.name = name; - - JsonObject jsonType = jsonElement; - if (jsonType.has("union")) { - if (!jsonName.isEmpty()) { - throw new RuntimeException("Unexpected named union: " + jsonElement); - } - for (JsonElement item : jsonType.getAsJsonArray("union")) { - if (!"null".equals(item.getAsJsonObject().get("name").getAsString())) { - jsonType = item.getAsJsonObject(); - break; - } - } - } - - while (jsonType.has("templates")) { - JsonArray params = jsonType.getAsJsonArray("templates"); - if (params.size() != 1) { - throw new RuntimeException("Unexpected number of parameters for " + jsonPath + ": " + jsonElement); - } - jsonType = params.get(0).getAsJsonObject(); - } - - if (jsonType.has("properties")) { - for (JsonElement item : jsonType.getAsJsonArray("properties")) { - JsonObject propertyJson = item.getAsJsonObject(); - String propertyName = propertyJson.get("name").getAsString(); - fields.add(new Field(this, propertyName, propertyJson)); - } - } - } - - @Override - String name() { - return name; - } - - @Override - void writeTo(List output, String offset) { - if (asList("ClientCertificate").contains(name)) { - output.add("import java.nio.file.Path;"); - output.add(""); - } - if (asList("DropPayload").contains(name)) { - output.add("import java.util.Map;"); - output.add(""); - } - String access = (parent.typeScope() instanceof CustomClass) || topLevelTypes().containsKey(name) ? "public " : ""; - output.add(offset + access + "class " + name + " {"); - String bodyOffset = offset + " "; - super.writeTo(output, bodyOffset); - - boolean isReturnType = parent.parent instanceof Method; - for (Field f : fields) { - f.writeTo(output, bodyOffset); - } - output.add(""); - if (!isReturnType) { - writeConstructor(output, bodyOffset); - writeBuilderMethods(output, bodyOffset); - } - output.add(offset + "}"); - } - - private void writeBuilderMethods(List output, String bodyOffset) { - for (Field f : fields) { - if (!f.isRequired()) { - f.writeBuilderMethod(output, bodyOffset, name); - } - } - } - - private void writeConstructor(List output, String bodyOffset) { - List requiredFields = fields.stream().filter(f -> f.isRequired()).collect(toList()); - if (requiredFields.isEmpty()) { - return; - } - List args = requiredFields.stream().map(f -> f.type.toJavaWithNullability() + " " + f.name).collect(toList()); - output.add(bodyOffset + "public " + name + "(" + String.join(", ", args) + ") {"); - requiredFields.forEach(f -> output.add(bodyOffset + " this." + f.name + " = " + f.name + ";")); - output.add(bodyOffset + "}"); - } -} - -class CustomInterface extends TypeDefinition { - final String name; - final List fields = new ArrayList<>(); - - CustomInterface(Element parent, String name, JsonObject jsonElement) { - super(parent, true, jsonElement); - this.name = name; - if (jsonElement.has("properties")) { - for (JsonElement item : jsonElement.getAsJsonArray("properties")) { - JsonObject propertyJson = item.getAsJsonObject(); - fields.add(new Field(this, propertyJson.get("name").getAsString(), propertyJson)); - } - } - } - - @Override - String name() { - return name; - } - - @Override - void writeTo(List output, String offset) { - output.add(offset + "public interface " + name + " {"); - String bodyOffset = offset + " "; - boolean first = true; - for (Field f : fields) { - if (!first) { - output.add(""); - } - first = false; - writeJavadoc(output, bodyOffset, f.comment()); - String returnType = f.type.withNullability(f.type.toJava(), !f.isRequired()); - output.add(bodyOffset + returnType + " " + f.name + "();"); - } - output.add(offset + "}"); - } -} - -class Enum extends TypeDefinition { - final List enumValues; - - Enum(TypeDefinition parent, JsonObject jsonObject) { - super(parent, jsonObject); - enumValues = new ArrayList<>(); - for (JsonElement item : jsonObject.getAsJsonArray("union")) { - String value = item.getAsJsonObject().get("name").getAsString(); - if ("null".equals(value)) { - throw new RuntimeException("Unexpected null: " + jsonObject); - } - enumValues.add(value.substring(1, value.length() - 1).replace("-", "_").toUpperCase()); - } - if ("BrowserChannel".equals(jsonName)) { - // Firefox stable 'channel' was removed in 1.12.0 - enumValues.add("@Deprecated FIREFOX_STABLE"); - } - } - - @Override - void writeTo(List output, String offset) { - output.add("public enum " + jsonName + " {\n " + String.join(",\n ", enumValues) + "\n}"); - } - - boolean hasSameValues(Enum other) { - return enumValues.equals(other.enumValues); - } -} - -public class ApiGenerator { - // TODO: make it an instance field. - static final Map aliases = new HashMap<>(); - - ApiGenerator(Reader reader) throws IOException { - JsonArray api = new Gson().fromJson(reader, JsonArray.class); - File cwd = FileSystems.getDefault().getPath(".").toFile(); - filterOtherLangs(api, new Stack<>()); - - File dir = new File(cwd, "playwright/src/main/java/com/microsoft/playwright"); - File optionsDir = new File(dir, "options"); - System.out.println("Writing files to: " + dir.getCanonicalPath()); - Map sharedTypes = new HashMap<>(); - generate(api, dir, "com.microsoft.playwright", isAssertion().negate(), sharedTypes); - - File assertionsDir = new File(cwd,"playwright/src/main/java/com/microsoft/playwright/assertions"); - System.out.println("Writing assertion files to: " + dir.getCanonicalPath()); - generate(api, assertionsDir, "com.microsoft.playwright.assertions", isAssertion().and(isSoftAssertion().negate()), sharedTypes); - - writeTopLevelTypes(sharedTypes, dir, optionsDir, "com.microsoft.playwright"); - } - - private void writeTopLevelTypes(Map topLevelTypes, File dir, File optionsDir, String packageName) throws IOException { - for (TypeDefinition e : topLevelTypes.values()) { - List body = new ArrayList<>(); - e.writeTo(body, ""); - if (e instanceof CustomInterface) { - writeFile(new File(dir, e.name() + ".java"), packageName, body); - } else { - writeFile(new File(optionsDir, e.name() + ".java"), packageName + ".options", body); - } - } - } - - private static void writeFile(File file, String packageName, List body) throws IOException { - List lines = new ArrayList<>(); - lines.add(Interface.header); - lines.add("package " + packageName + ";"); - lines.add(""); - if (body.stream().anyMatch(line -> line.contains("@Nullable"))) { - lines.add("import org.jspecify.annotations.Nullable;"); - String first = body.get(0); - if (!first.isEmpty() && !first.startsWith("import ")) { - lines.add(""); - } - } - lines.addAll(body); - try (FileWriter writer = new FileWriter(file)) { - writer.write(String.join("\n", lines)); - } - } - - private static Predicate isAssertion() { - return className -> isAssertionClass(className); - } - - static boolean isAssertionClass(String className) { - return className.toLowerCase().contains("assert"); - } - - // TODO: Remove this predicate once SoftAssertions are implemented. - private static Predicate isSoftAssertion() { - return className -> className.contains("SoftAssertions"); - } - - private void generate(JsonArray api, File dir, String packageName, Predicate classFilter, Map topLevelTypes) throws IOException { - for (JsonElement entry: api) { - String name = entry.getAsJsonObject().get("name").getAsString(); - // We write this one manually. - if (asList("PlaywrightException", "TimeoutError").contains(name)) { - continue; - } - if (!classFilter.test(name)) { - continue; - } - Interface iface = new Interface(entry.getAsJsonObject(), topLevelTypes); - if (asList("RequestOptions", "FormData").contains(name)) { - topLevelTypes.put(name, iface); - continue; - } - List body = new ArrayList<>(); - iface.writeTo(body, ""); - writeFile(new File(dir, name + ".java"), packageName, body); - } - - } - - private static void filterOtherLangs(JsonElement json, Stack path) { - if (json.isJsonArray()) { - List toRemove = new ArrayList<>(); - JsonArray array = json.getAsJsonArray(); - for (int i = 0; i < array.size(); i++) { - JsonElement item = array.get(i); - if (isSupported(item)) { - filterOtherLangs(item, path); - } else { - toRemove.add(i); - } - } - reverse(toRemove); - for (int index : toRemove) { - array.remove(index); - } - } else if (json.isJsonObject()) { - List toRemove = new ArrayList<>(); - JsonObject object = json.getAsJsonObject(); - path.push(object.has("name") ? object.get("name").getAsString() : ""); - String alias = alias(object); - if (alias != null) { - List aliasPath = new ArrayList<>(path); - aliasPath.set(aliasPath.size() - 1, alias); - aliases.put(String.join(".", path), String.join(".", aliasPath)); - // Save original name. - object.addProperty("originalName", object.get("name").getAsString()); - // Rename in place. - object.addProperty("name", alias); - } - overrideType(object); - - for (Map.Entry entry : object.entrySet()) { - if (isSupported(entry.getValue())) { - filterOtherLangs(entry.getValue(), path); - } else { - toRemove.add(entry.getKey()); - } - } - path.pop(); - for (String key : toRemove) { - object.remove(key); - } - } - } - - private static void overrideType(JsonObject jsonObject) { - if (!jsonObject.has("langs")) { - return; - } - JsonObject langs = jsonObject.getAsJsonObject("langs"); - if (!langs.has("types")) { - return; - } - JsonElement type = langs.getAsJsonObject("types").get("java"); - if (type == null) { - return; - } - jsonObject.add("type", type); - } - - private static String alias(JsonObject jsonObject) { - if (!jsonObject.has("langs")) { - return null; - } - JsonObject langs = jsonObject.getAsJsonObject("langs"); - if (!langs.has("aliases")) { - return null; - } - JsonElement javaAlias = langs.getAsJsonObject("aliases").get("java"); - if (javaAlias == null) { - return null; - } - return javaAlias.getAsString(); - } - - private static boolean isSupported(JsonElement json) { - if (!json.isJsonObject()) { - return true; - } - JsonObject jsonObject = json.getAsJsonObject(); - if (!jsonObject.has("langs")) { - return true; - } - JsonObject langs = jsonObject.getAsJsonObject("langs"); - if (!langs.has("only")) { - return true; - } - JsonArray only = langs.getAsJsonArray("only"); - for (JsonElement lang : only) { - if ("java".equals(lang.getAsString())) { - return true; - } - } - return false; - } - - public static void main(String[] args) throws IOException { - File cwd = FileSystems.getDefault().getPath(".").toFile(); - File file = new File(cwd, "tools/api-generator/src/main/resources/api.json"); - System.out.println("Reading from: " + file.getCanonicalPath()); - new ApiGenerator(new FileReader(file)); - } -} diff --git a/tools/api-generator/src/main/resources/.gitignore b/tools/api-generator/src/main/resources/.gitignore deleted file mode 100644 index 1a11577de..000000000 --- a/tools/api-generator/src/main/resources/.gitignore +++ /dev/null @@ -1 +0,0 @@ -api.json From 1ede122bbe37395b1d4e28d852293c0a6c444a4c Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Thu, 19 Nov 2026 14:35:57 -0800 Subject: [PATCH 2/2] chore: simplify the API generator Render the member links in the upstream link renderer, wrap the text with the upstream wrapText, keep the top-level types in one registry and drop the dead special cases. The generated files do not change. --- AGENTS.md | 2 +- scripts/generate_api.sh | 6 + scripts/generate_java_api.mts | 314 +++++++++++++--------------------- 3 files changed, 128 insertions(+), 194 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 598051faa..cdf233e20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Paths such as `~/code/playwright` in this file assume that you check the repos o - **The driver.** The Java client talks to the Node.js driver. The driver is the `playwright-core` package of `microsoft/playwright`. We build it from source at the commit in `scripts/DRIVER_VERSION`. `scripts/build_driver.sh` clones `microsoft/playwright` into `.upstream/` (gitignored), checks out that commit, builds it and puts the package into `driver/src/main/resources/driver/package/`. Do not edit, commit or switch branches in `.upstream/`. `scripts/roll_driver.sh` moves the commit: to the tip of upstream `main`, to the tip of an upstream `release-1.X` branch, or to an exact commit. We do not use the published npm packages or their versions. `git show v1.X.0:scripts/DRIVER_VERSION` prints the upstream commit of a release. For releases up to 1.65, it prints the `playwright-core` version of the driver. - **Upstream code.** In `.upstream/`, at the commit of the driver, or in `~/code/playwright`, which may be ahead of it: the client in `packages/playwright-core/src/client/`, the API docs in `docs/src/api/`, the tests in `tests/page/` and `tests/library/`. Its `AGENTS.md` says how to build it and run a test. - **Where a bug is.** When the same calls fail in a Node.js test upstream too, the cause is in the driver or a browser, and the fix lands in `microsoft/playwright`. When Node.js passes, the bug is in the Java client: compare the `*Impl.java` with its JavaScript counterpart, and fix it here. -- **The generated API.** `scripts/generate_api.sh` runs `scripts/generate_java_api.mts`. It parses `docs/src/api/*.md` of `.upstream/` with the upstream parser (`utils/doclint/api_parser.js`) and writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `assertions/PlaywrightAssertions.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream. +- **The generated API.** `scripts/generate_api.sh` runs `scripts/generate_java_api.mts`. It parses `docs/src/api/*.md` of `.upstream/` with the upstream parser (`utils/doclint/api_parser.js`) and writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `options/Annotate.java`, `options/BindingCallback.java`, `options/BrowserChannel.java`, `options/FunctionCallback.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream. ## Build and test diff --git a/scripts/generate_api.sh b/scripts/generate_api.sh index c909bf31e..bdebe58cf 100755 --- a/scripts/generate_api.sh +++ b/scripts/generate_api.sh @@ -24,6 +24,12 @@ else fi fi +# Node.js runs the TypeScript file of the generator as is. Older versions cannot. +if ! node -e 'process.exit(process.features.typescript ? 0 : 1)'; then + echo "The API generator needs Node.js 22.18 or newer, got $(node --version)" + exit 1 +fi + echo "Regenerating Java interfaces from $UPSTREAM_DIR" node ./scripts/generate_java_api.mts "$UPSTREAM_DIR" diff --git a/scripts/generate_java_api.mts b/scripts/generate_java_api.mts index 729ac3b60..b81cb6fc1 100644 --- a/scripts/generate_java_api.mts +++ b/scripts/generate_java_api.mts @@ -66,6 +66,8 @@ type DocMember = { spec?: MarkdownNode[], since?: string, deprecated?: string, + // The class of a member of a class. + clazz?: DocClass, }; type DocClass = { @@ -76,13 +78,23 @@ type DocClass = { spec?: MarkdownNode[], }; -type LinkRenderer = (item: { clazz?: DocClass, param?: { alias: string }, option?: { alias: string } }) => string | undefined; +type LinkRenderer = (item: { clazz?: DocClass, member?: DocMember, param?: { alias: string }, option?: { alias: string } }) => string | undefined; type Documentation = { classesArray: DocClass[], setLinkRenderer(renderer: LinkRenderer): void, }; +if (process.argv.length !== 3) { + console.error(`Usage: node ${path.relative(process.cwd(), process.argv[1])} `); + console.error('For example: node scripts/generate_java_api.mts .upstream'); + process.exit(1); +} +const UPSTREAM_DIR = path.resolve(process.argv[2]); +const require = createRequire(import.meta.url); +const { parseApi } = require(path.join(UPSTREAM_DIR, 'utils', 'doclint', 'api_parser')) as { parseApi(apiDir: string): Documentation }; +const md = require(path.join(UPSTREAM_DIR, 'utils', 'markdown')) as { wrapText(text: string, options: { maxColumns: number }, prefix: string): string }; + const LANG = 'java'; const ROOT_DIR = path.join(import.meta.dirname, '..'); const API_DIR = path.join(ROOT_DIR, 'playwright', 'src', 'main', 'java', 'com', 'microsoft', 'playwright'); @@ -109,10 +121,7 @@ const LICENSE_HEADER = `/* const HANDWRITTEN_CLASSES = ['PlaywrightException', 'TimeoutError']; // These interfaces go to the options package. const OPTIONS_PACKAGE_INTERFACES = ['RequestOptions', 'FormData']; -const BASE_INTERFACES = ['Browser', 'JSHandle', 'BrowserContext']; const AUTO_CLOSEABLE_INTERFACES = ['Playwright', 'Browser', 'BrowserContext', 'Page']; -// The interfaces with a static create() method that calls the implementation class. -const FACTORY_INTERFACES = ['Playwright', 'FormData', 'RequestOptions']; const BROWSER_CHANNEL_OPTIONS = ['BrowserType.launch.options.channel', 'BrowserType.launchPersistentContext.options.channel']; // The imports of a generated interface, in the order of the output. When a roll brings in an @@ -148,6 +157,17 @@ const CUSTOM_CLASS_IMPORTS: Record = { // The static methods with a body. The key is the path of the method. A method with overloads // has an entry for the name of each overload in the docs. const STATIC_METHODS: Record> = { + 'Playwright.create': { + create: [ + 'static Playwright create(@Nullable CreateOptions options) {', + ' return PlaywrightImpl.create(options);', + '}', + '', + 'static Playwright create() {', + ' return create(null);', + '}', + ], + }, 'FormData.create': { create: [ 'static FormData create() {', @@ -214,8 +234,10 @@ const BOXED_TYPES: Record = { 'boolean': 'Boolean', }; -// `Class.member` in the docs => `Class.alias`, for the members with a Java alias. -const memberAliases = new Map(); +// All types that go to files of their own, by name. The first definition of a type wins. +const topLevelTypes = new Map(); +// The names of the generated interfaces. +const interfaceNames = new Set(); // --------------------------------------------------------------------------------------------- // Filtering the docs for Java. @@ -255,17 +277,11 @@ function filterType(type: DocType) { function filterForJava(documentation: Documentation): DocClass[] { const classes = documentation.classesArray.filter(isSupported); for (const clazz of classes) { - const className = clazz.name; const alias = clazz.langs?.aliases?.[LANG]; if (alias) clazz.name = alias; clazz.membersArray = clazz.membersArray.filter(isSupported); - for (const member of clazz.membersArray) { - const memberName = member.name; - filterMember(member); - if (member.name !== memberName) - memberAliases.set(`${className}.${memberName}`, `${className}.${member.name}`); - } + clazz.membersArray.forEach(filterMember); } return classes; } @@ -300,18 +316,6 @@ function writeJavadoc(output: string[], offset: string, text: string) { output.push(offset + ' */'); } -function linkifyMemberRefs(paragraph: string): string { - return paragraph.replace(/\[`(event|property|method): ([^`]+)`]/g, (match, kind: string, ref: string) => { - let name = memberAliases.get(ref) ?? ref; - if (kind === 'event') { - const parts = name.split('.'); - name = parts[0] + '.on' + toTitle(parts[1]); - } - const packagePrefix = isAssertionClass(name.split('.')[0]) ? `${API_PACKAGE}.assertions.` : `${API_PACKAGE}.`; - return `{@link ${packagePrefix}${name.replaceAll('.', '#')} ${name}()}`; - }); -} - function updateExternalLinks(paragraph: string): string { return paragraph.replace(/\[([^\]]+)\]\(([^\)]+)\)/g, (match, text: string, url: string) => { // ../actionability.md#editable => https://playwright.dev/java/docs/actionability#editable @@ -324,46 +328,12 @@ function updateExternalLinks(paragraph: string): string { }).replaceAll('[Promise]', `Promise`); } -// Splits the text into words. A link in square brackets is not split. -function tokenizeNoBreakLinks(text: string): string[] { - const links: string[] = []; - const sanitized = text.replace(/\[[^\]]+\]/g, link => { - links.push(link); - return `[${links.length - 1}]`; - }); - let tokens = splitDroppingTrailingEmpty(sanitized, ' '); - links.forEach((link, index) => { - tokens = tokens.map(token => token.replaceAll(`[${index}]`, () => link)); - }); - return tokens; -} - -function wrapText(text: string, maxColumns: number): string { - // A table row. - if (/^[\u0000- ]*\|/.test(text)) - return text; - const lines: string[] = []; - let line = ''; - for (const word of tokenizeNoBreakLinks(text)) { - if (line && line.length + word.length < maxColumns) { - line += ' ' + word; - } else { - if (line) - lines.push(line); - line = word; - } - } - if (line) - lines.push(line); - return lines.join('\n'); -} - function beautify(paragraph: string): string { - const text = updateExternalLinks(linkifyMemberRefs(paragraph)) + const text = updateExternalLinks(paragraph) .replaceAll('↵', ' ') .replace(/`'([^`]+)'`/g, '{@code "$1"}') .replace(/`([^`]+)`/g, '{@code $1}'); - return wrapText(text, 120); + return md.wrapText(text, { maxColumns: 120 }, ''); } function formatSpec(spec: MarkdownNode[]): string { @@ -428,15 +398,6 @@ abstract class Element { this.name = name; this.path = path ?? (parent ? `${parent.path}.${name}` : name); } - - typeScope(): TypeDefinition { - return this.parent!.typeScope(); - } - - // All types that go to files of their own, by name. The first definition of a type wins. - topLevelTypes(): Map { - return this.parent!.topLevelTypes(); - } } function nullable(javaType: string): string { @@ -450,6 +411,12 @@ function javaAlias(type: DocType): string | undefined { return type.langAliases?.[LANG] ?? type.langAliases?.default; } +// The type `T` of `null|T`. +function nullableInnerType(type: DocType): DocType | undefined { + if (type.union && !type.name && type.union.length === 2 && type.union.some(item => item.name === 'null')) + return type.union.find(item => item.name !== 'null'); +} + // The return type of a method, the type of a method param or the type of a field. class TypeRef extends Element { readonly type: DocType | null; @@ -457,7 +424,7 @@ class TypeRef extends Element { customType: string | null = null; constructor(parent: Element, type: DocType | null) { - super(parent, type?.name ?? '', parent.path); + super(parent, '', parent.path); this.type = type; if (type) this.createClassesAndEnums(type); @@ -466,7 +433,7 @@ class TypeRef extends Element { private createClassesAndEnums(type: DocType) { if (type.union) { if (type.name) - this.typeScope().createEnum(type); + registerTopLevelType(new Enum(type)); else type.union.forEach(item => this.createClassesAndEnums(item)); return; @@ -479,7 +446,7 @@ class TypeRef extends Element { for (const arg of type.args) { const alias = javaAlias(arg); if (arg.name === 'Object' && alias) - this.typeScope().createTopLevelInterface(alias, this, arg); + registerTopLevelType(new CustomInterface(this, alias, arg)); } return; } @@ -489,18 +456,19 @@ class TypeRef extends Element { if (this.customType) return; if (this.parent instanceof Param && this.parent.name === 'options') { - this.customType = toTitle(this.parent.parent!.name) + toTitle(this.parent.name); - this.typeScope().createNestedClass(this.customType, this, type); + const method = this.parent.parent as Method; + this.customType = toTitle(method.name) + toTitle(this.parent.name); + (method.parent as Interface).createNestedClass(this.customType, this, type); } else { this.customType = javaAlias(type) ?? toTitle(this.parent!.name); - this.typeScope().createTopLevelClass(this.customType, this, type); + registerTopLevelType(new CustomClass(this, this.customType, type)); } } toJava(): string { if (!this.type) return 'void'; - return this.convertType(this.stripNullable()); + return this.convertType(this.stripNullable()!); } toJavaWithNullability(): string { @@ -546,14 +514,11 @@ class TypeRef extends Element { // True for `null|T`. isNullable(): boolean { - const type = this.type; - return !!type?.union && !type.name && type.union.length === 2 && type.union.some(item => item.name === 'null'); + return !!this.type && !!nullableInnerType(this.type); } - private stripNullable(): DocType { - if (!this.isNullable()) - return this.type!; - return this.type!.union!.find(item => item.name !== 'null')!; + private stripNullable(): DocType | null { + return this.type && (nullableInnerType(this.type) ?? this.type); } private convertType(type: DocType): string { @@ -591,17 +556,19 @@ class TypeRef extends Element { return alias; if (!type.args) throw new Error(`Missing mapping for ${this.path}`); - if (this.path === 'WebSocketRoute.onClose.handler') - return 'BiConsumer'; - if (type.args.length === 1) { - const paramType = this.convertType(type.args[0]); - const returnTypeName = type.returnType?.name; - if (returnTypeName === 'boolean') - return `Predicate<${paramType}>`; - if (!returnTypeName || returnTypeName === 'Promise' || returnTypeName === 'void') - return `Consumer<${paramType}>`; - throw new Error(`Missing mapping for the return type ${returnTypeName} in ${this.path}`); - } + const argTypes = type.args.map(arg => { + const argType = this.convertType(nullableInnerType(arg) ?? arg); + return BOXED_TYPES[argType] ?? argType; + }).join(', '); + const returnTypeName = type.returnType?.name; + const isVoid = !returnTypeName || returnTypeName === 'Promise' || returnTypeName === 'void'; + if (type.args.length === 1 && returnTypeName === 'boolean') + return `Predicate<${argTypes}>`; + if (type.args.length === 1 && isVoid) + return `Consumer<${argTypes}>`; + if (type.args.length === 2 && isVoid) + return `BiConsumer<${argTypes}>`; + throw new Error(`Missing mapping for the function in ${this.path}`); } return name; } @@ -611,46 +578,21 @@ class TypeRef extends Element { } } +// A type of the generated code: an interface, a class or an enum. abstract class TypeDefinition extends Element { - // The options classes of the methods. - readonly nestedClasses: CustomClass[] = []; - - override typeScope(): TypeDefinition { - return this; - } - abstract writeTo(output: string[], offset: string): void; +} - // Constructs the type in any case: it registers the types of its fields. - private createTopLevelType(name: string, type: T, kind: Function) { - const types = this.topLevelTypes(); - const existing = types.get(name); - if (!existing) - types.set(name, type); - else if (!(existing instanceof kind)) - throw new Error(`Two types with the name ${name} are of different kinds, the second one is ${type.path}`); - return existing as T | undefined; - } - - createEnum(type: DocType) { - const newEnum = new Enum(this, type); - const existing = this.createTopLevelType(newEnum.name, newEnum, Enum); - if (existing && existing.values.join() !== newEnum.values.join()) - throw new Error(`Two enums with the name ${newEnum.name} have different values: ${existing.values} and ${newEnum.values}`); - } - - createTopLevelClass(name: string, parent: TypeRef, type: DocType) { - this.createTopLevelType(name, new CustomClass(parent, name, type), CustomClass); - } - - createTopLevelInterface(name: string, parent: TypeRef, type: DocType) { - this.createTopLevelType(name, new CustomInterface(parent, name, type), CustomInterface); - } - - createNestedClass(name: string, parent: TypeRef, type: DocType) { - if (!this.nestedClasses.some(c => c.name === name)) - this.nestedClasses.push(new CustomClass(parent, name, type)); - } +// The caller constructs the type even when a type with its name exists: the constructor +// registers the types of the fields. +function registerTopLevelType(type: TypeDefinition) { + const existing = topLevelTypes.get(type.name); + if (!existing) + topLevelTypes.set(type.name, type); + else if (existing.constructor !== type.constructor) + throw new Error(`Two types with the name ${type.name} are of different kinds, the second one is ${type.path}`); + else if (existing instanceof Enum && type instanceof Enum && existing.values.join() !== type.values.join()) + throw new Error(`Two enums with the name ${type.name} have different values: ${existing.values} and ${type.values}`); } class Event extends Element { @@ -711,18 +653,6 @@ class Method extends Element { } writeTo(output: string[], offset: string) { - if (this.path === 'Playwright.create') { - this.writeJavadoc(this.params, output, offset); - output.push( - `${offset}static Playwright create(${this.params[0].toJava(0)}) {`, - `${offset} return PlaywrightImpl.create(options);`, - `${offset}}`, - '', - `${offset}static Playwright create() {`, - `${offset} return create(null);`, - `${offset}}`); - return; - } const staticMethod = STATIC_METHODS[this.path]; if (staticMethod) { const originalName = this.member.originalName ?? this.name; @@ -765,7 +695,7 @@ class Method extends Element { const type = param.type.formatTypeFromUnion(overloadIndex); args.push(type === 'int' ? '0' : `(${type}) null`); } else { - // TODO: it should probably be done for all methods that have name#1, name#2 etc overloads. + // The overloads of hasAttribute make a plain null ambiguous. args.push(this.path === 'LocatorAssertions.hasAttribute' ? `(${param.type.toJava()}) null` : 'null'); } return; @@ -810,13 +740,18 @@ class Field extends Element { } isRequired(): boolean { - return !!this.member.required; + return this.member.required; } comment(): string { return memberComment(this.member); } + // The declaration of the constructor param of a required field. + toJavaParam(): string { + return `${this.type.toJavaWithNullability()} ${this.name}`; + } + writeTo(output: string[], offset: string) { writeJavadoc(output, offset, this.comment()); let type = this.type.toJava(); @@ -851,18 +786,14 @@ class Field extends Element { // The setter that takes the required fields of the custom class, for example setHttpCredentials(username, password). private writeRequiredFieldsBuilderMethod(output: string[], offset: string, parentClass: string) { - const customType = this.topLevelTypes().get(this.type.customType!); - if (!(customType instanceof CustomClass)) - return; - const requiredFields = customType.fields.filter(f => f.isRequired()); + const customType = topLevelTypes.get(this.type.customType!) as CustomClass; + const requiredFields = customType.requiredFields(); if (!requiredFields.length) return; - const params = requiredFields.map(f => `${f.type.toJavaWithNullability()} ${f.name}`).join(', '); - const args = requiredFields.map(f => f.name).join(', '); writeJavadoc(output, offset, this.comment()); output.push( - `${offset}public ${parentClass} set${toTitle(this.name)}(${params}) {`, - `${offset} return set${toTitle(this.name)}(new ${this.type.customType}(${args}));`, + `${offset}public ${parentClass} set${toTitle(this.name)}(${requiredFields.map(f => f.toJavaParam()).join(', ')}) {`, + `${offset} return set${toTitle(this.name)}(new ${this.type.customType}(${requiredFields.map(f => f.name).join(', ')}));`, `${offset}}`); } @@ -884,14 +815,14 @@ class Field extends Element { // An interface of the API, made from a class of the docs. class Interface extends TypeDefinition { private readonly clazz: DocClass; - private readonly types: Map; private readonly methods: Method[] = []; private readonly events: Event[] = []; + // The options classes of the methods. + private readonly nestedClasses: CustomClass[] = []; - constructor(clazz: DocClass, topLevelTypes: Map) { + constructor(clazz: DocClass) { super(null, clazz.name); this.clazz = clazz; - this.types = topLevelTypes; for (const member of clazz.membersArray) { if (member.kind === 'event') this.events.push(new Event(this, member)); @@ -900,12 +831,14 @@ class Interface extends TypeDefinition { } } - override topLevelTypes(): Map { - return this.types; + createNestedClass(name: string, parent: TypeRef, type: DocType) { + if (!this.nestedClasses.some(c => c.name === name)) + this.nestedClasses.push(new CustomClass(parent, name, type)); } writeTo(output: string[], offset: string) { - if (FACTORY_INTERFACES.includes(this.name) && this.methods.some(m => m.name === 'create')) + // The static create() method calls the implementation class. + if (Object.hasOwn(STATIC_METHODS, `${this.name}.create`)) output.push(`import ${API_PACKAGE}.impl.${this.name}Impl;`); for (const [imports, interfaces] of INTERFACE_IMPORTS) { if (interfaces.includes(this.name)) @@ -914,7 +847,7 @@ class Interface extends TypeDefinition { output.push(''); const superInterfaces: string[] = []; - if (this.clazz.extends && BASE_INTERFACES.includes(this.clazz.extends)) + if (this.clazz.extends && interfaceNames.has(this.clazz.extends)) superInterfaces.push(this.clazz.extends); if (AUTO_CLOSEABLE_INTERFACES.includes(this.name)) superInterfaces.push('AutoCloseable'); @@ -950,7 +883,8 @@ class CustomClass extends TypeDefinition { writeTo(output: string[], offset: string) { if (CUSTOM_CLASS_IMPORTS[this.name]) output.push(`import ${CUSTOM_CLASS_IMPORTS[this.name]};`, ''); - const access = this.topLevelTypes().has(this.name) ? 'public ' : ''; + // A class nested in an interface is public without the modifier. + const access = offset ? '' : 'public '; output.push(`${offset}${access}class ${this.name} {`); const bodyOffset = offset + ' '; for (const field of this.fields) @@ -968,13 +902,16 @@ class CustomClass extends TypeDefinition { output.push(`${offset}}`); } + requiredFields(): Field[] { + return this.fields.filter(f => f.isRequired()); + } + private writeConstructor(output: string[], offset: string) { - const requiredFields = this.fields.filter(f => f.isRequired()); + const requiredFields = this.requiredFields(); if (!requiredFields.length) return; - const params = requiredFields.map(f => `${f.type.toJavaWithNullability()} ${f.name}`).join(', '); output.push( - `${offset}public ${this.name}(${params}) {`, + `${offset}public ${this.name}(${requiredFields.map(f => f.toJavaParam()).join(', ')}) {`, ...requiredFields.map(f => `${offset} this.${f.name} = ${f.name};`), `${offset}}`); } @@ -1005,13 +942,10 @@ class CustomInterface extends TypeDefinition { class Enum extends TypeDefinition { readonly values: string[]; - constructor(parent: TypeDefinition, type: DocType) { - super(parent, type.name); + constructor(type: DocType) { + super(null, type.name); // The values are in quotes: "load", "domcontentloaded". this.values = type.union!.map(item => item.name.substring(1, item.name.length - 1).replaceAll('-', '_').toUpperCase()); - // Firefox stable 'channel' was removed in 1.12.0 - if (this.name === 'BrowserChannel') - this.values.push('@Deprecated FIREFOX_STABLE'); } writeTo(output: string[], offset: string) { @@ -1035,11 +969,9 @@ function writeFile(dir: string, packageName: string, type: TypeDefinition) { fs.writeFileSync(path.join(dir, `${type.name}.java`), lines.join('\n')); } -function generateInterfaces(classes: DocClass[], dir: string, packageName: string, topLevelTypes: Map) { +function generateInterfaces(classes: DocClass[], dir: string, packageName: string) { for (const clazz of classes) { - const iface = new Interface(clazz, topLevelTypes); - // The file is written before the next interface is read: a nested class is `public` when - // a type with its name is among the top-level types found so far. + const iface = new Interface(clazz); if (OPTIONS_PACKAGE_INTERFACES.includes(clazz.name)) topLevelTypes.set(clazz.name, iface); else @@ -1047,37 +979,33 @@ function generateInterfaces(classes: DocClass[], dir: string, packageName: strin } } -function parseDocs(upstreamDir: string): Documentation { - const require = createRequire(import.meta.url); - const { parseApi } = require(path.join(upstreamDir, 'utils', 'doclint', 'api_parser')); - const documentation: Documentation = parseApi(path.join(upstreamDir, 'docs', 'src', 'api')); - // The links to params, options and classes become code. The links to members stay: - // linkifyMemberRefs() makes {@link} tags of them. - documentation.setLinkRenderer(({ clazz, param, option }) => { +function parseDocs(): Documentation { + const documentation = parseApi(path.join(UPSTREAM_DIR, 'docs', 'src', 'api')); + // The renderer runs before the docs are filtered for Java: the names are the names in the docs. + documentation.setLinkRenderer(({ clazz, member, param, option }) => { if (param) return `\`${param.alias}\``; if (option) return `\`${option.alias}\``; if (clazz) return `\`${clazz.name}\``; + if (member) { + const className = member.clazz!.name; + const alias = member.langs.aliases?.[LANG] ?? member.name; + const name = member.kind === 'event' ? 'on' + toTitle(alias) : alias; + const packageName = isAssertionClass(className) ? `${API_PACKAGE}.assertions` : API_PACKAGE; + return `{@link ${packageName}.${className}#${name} ${className}.${name}()}`; + } }); return documentation; } function main() { - if (process.argv.length !== 3) { - console.error(`Usage: node ${path.relative(process.cwd(), process.argv[1])} `); - console.error('For example: node scripts/generate_java_api.mts .upstream'); - process.exit(1); - } - const classes = filterForJava(parseDocs(path.resolve(process.argv[2]))) - .filter(clazz => !HANDWRITTEN_CLASSES.includes(clazz.name)); - - const topLevelTypes = new Map(); - generateInterfaces(classes.filter(clazz => !isAssertionClass(clazz.name)), API_DIR, API_PACKAGE, topLevelTypes); - // TODO: generate SoftAssertions once they are implemented. - generateInterfaces(classes.filter(clazz => isAssertionClass(clazz.name) && !clazz.name.includes('SoftAssertions')), - path.join(API_DIR, 'assertions'), `${API_PACKAGE}.assertions`, topLevelTypes); + const classes = filterForJava(parseDocs()).filter(clazz => !HANDWRITTEN_CLASSES.includes(clazz.name)); + for (const clazz of classes) + interfaceNames.add(clazz.name); + generateInterfaces(classes.filter(clazz => !isAssertionClass(clazz.name)), API_DIR, API_PACKAGE); + generateInterfaces(classes.filter(clazz => isAssertionClass(clazz.name)), path.join(API_DIR, 'assertions'), `${API_PACKAGE}.assertions`); for (const type of topLevelTypes.values()) { if (type instanceof CustomInterface) writeFile(API_DIR, API_PACKAGE, type);