[web_generator] Add Support for Parsing IDL Files (#377)

* integrated IDL single file parsing and integration testing

* modified interface idl input

* Completed support for Single IDL File Parsing
Fixes #374

* fixed suffix naming

* moved actual output from temp to `.dart_tool`

* made minor fixes

* Add newline to end of files

* Code resolution

* updated integration test suite

* Resolved all standing fixes to the integration test suite

* Update translator.dart

Author: nikeokoronkwo

web_generator/bin/update_idl_bindings.dart

@@ -67,12 +67,17 @@ $_usage''');
 
   // Run app with `node`.
   final generateAll = argResult['generate-all'] as bool;
+  final inputFiles = argResult['input'] as List<String>;
   await runProc(
     'node',
     [
       'main.mjs',
       '--idl',
-      '--output=${p.join(_webPackagePath, 'lib', 'src')}',
+      for (String inputFile in inputFiles) '--input=$inputFile',
+      if (inputFiles.isEmpty)
+        '--output=${p.join(_webPackagePath, 'lib', 'src')}'
+      else
+        '--output=${argResult['output'] as String? ?? p.current}',
       if (generateAll) '--generate-all',
     ],
     workingDirectory: bindingsGeneratorPath,
@@ -89,16 +94,17 @@ $_usage''');
   // delete context file
   await contextFile.delete();
 
-  // Update readme.
-  final readmeFile =
-      File(p.normalize(p.fromUri(Platform.script.resolve('../README.md'))));
+  if (inputFiles.isEmpty) {
+    // Update readme.
+    final readmeFile =
+        File(p.normalize(p.fromUri(Platform.script.resolve('../README.md'))));
 
-  final sourceContent = readmeFile.readAsStringSync();
+    final sourceContent = readmeFile.readAsStringSync();
 
-  final cssVersion = _packageLockVersion(_webRefCss);
-  final elementsVersion = _packageLockVersion(_webRefElements);
-  final idlVersion = _packageLockVersion(_webRefIdl);
-  final versions = '''
+    final cssVersion = _packageLockVersion(_webRefCss);
+    final elementsVersion = _packageLockVersion(_webRefElements);
+    final idlVersion = _packageLockVersion(_webRefIdl);
+    final versions = '''
 $_startComment
 | Item | Version |
 | --- | --: |
@@ -107,15 +113,16 @@ $_startComment
 | `$_webRefIdl` | [$idlVersion](https://www.npmjs.com/package/$_webRefIdl/v/$idlVersion) |
 ''';
 
-  final newContent =
-      sourceContent.substring(0, sourceContent.indexOf(_startComment)) +
-          versions +
-          sourceContent.substring(sourceContent.indexOf(_endComment));
-  if (newContent == sourceContent) {
-    print(ansi.styleBold.wrap('No update for readme.'));
-  } else {
-    print(ansi.styleBold.wrap('Updating readme for IDL version $idlVersion'));
-    readmeFile.writeAsStringSync(newContent, mode: FileMode.writeOnly);
+    final newContent =
+        sourceContent.substring(0, sourceContent.indexOf(_startComment)) +
+            versions +
+            sourceContent.substring(sourceContent.indexOf(_endComment));
+    if (newContent == sourceContent) {
+      print(ansi.styleBold.wrap('No update for readme.'));
+    } else {
+      print(ansi.styleBold.wrap('Updating readme for IDL version $idlVersion'));
+      readmeFile.writeAsStringSync(newContent, mode: FileMode.writeOnly);
+    }
   }
 }
 
@@ -161,23 +168,26 @@ final _endComment =
     '<!-- END updated by $_scriptPOSIXPath. Do not modify by hand -->';
 
 final _usage = '''
-Global Options:
-${_parser.usage}
-
-${ansi.styleBold.wrap('IDL Command')}: $_thisScript idl [options]
-
-Usage:
-${_parser.commands['idl']?.usage}
+${ansi.styleBold.wrap('WebIDL Gen')}:
+$_thisScript [options]
 
-${ansi.styleBold.wrap('Typescript Gen Command')}: $_thisScript dts <.d.ts file> [options]
+If no IDL file is provided, defaults to the WebIDL definitions needed for package:web
 
 Usage:
-${_parser.commands['dts']?.usage}''';
+${_parser.usage}''';
 
 final _parser = ArgParser()
   ..addFlag('help', negatable: false, help: 'Show help information')
   ..addFlag('update', abbr: 'u', help: 'Update npm dependencies')
   ..addFlag('compile', defaultsTo: true)
+  ..addOption('output',
+      abbr: 'o',
+      help: 'Output directory where bindings will be generated to '
+          '(defaults to `lib/src` in the web package when no IDL file is provided)')
+  ..addMultiOption('input',
+      abbr: 'i',
+      help: 'The input IDL file(s) to read and generate bindings for. '
+          'If not provided, the default WebIDL definitions will be used.')
   ..addFlag('generate-all',
       negatable: false,
       help: 'Generate bindings for all IDL definitions, including experimental '

web_generator/lib/src/dart_main.dart

@@ -32,7 +32,10 @@ void main(List<String> args) async {
 
   if (argResult.wasParsed('idl')) {
     await generateIDLBindings(
-      outputDirectory: argResult['output'] as String,
+      input: (argResult['input'] as List<String>).isEmpty
+          ? null
+          : argResult['input'] as Iterable<String>,
+      output: argResult['output'] as String,
       generateAll: argResult['generate-all'] as bool,
       languageVersion: Version.parse(languageVersionString),
     );
@@ -72,22 +75,46 @@ Future<void> generateJSInteropBindings({
 }
 
 Future<void> generateIDLBindings({
-  required String outputDirectory,
+  Iterable<String>? input,
+  required String output,
   required bool generateAll,
   required Version languageVersion,
 }) async {
-  const librarySubDir = 'dom';
+  if (input == null) {
+    // parse dom library as normal
+    const librarySubDir = 'dom';
+
+    ensureDirectoryExists('$output/$librarySubDir');
 
-  ensureDirectoryExists('$outputDirectory/$librarySubDir');
+    final bindings = await generateBindings(packageRoot, librarySubDir,
+        generateAll: generateAll);
 
-  final bindings = await generateBindings(packageRoot, librarySubDir,
-      generateAll: generateAll);
-  for (var entry in bindings.entries) {
-    final libraryPath = entry.key;
-    final library = entry.value;
+    for (var entry in bindings.entries) {
+      final libraryPath = entry.key;
+      final library = entry.value;
 
-    final contents = _emitLibrary(library, languageVersion).toJS;
-    fs.writeFileSync('$outputDirectory/$libraryPath'.toJS, contents);
+      final contents = _emitLibrary(library, languageVersion).toJS;
+      fs.writeFileSync('$output/$libraryPath'.toJS, contents);
+    }
+  } else {
+    // parse individual files
+    ensureDirectoryExists(output);
+
+    final bindings = await generateBindingsForFiles({
+      for (final file in input)
+        file: (fs.readFileSync(
+                    file.toJS, JSReadFileOptions(encoding: 'utf-8'.toJS))
+                as JSString)
+            .toDart
+    }, output);
+
+    for (var entry in bindings.entries) {
+      final libraryPath = entry.key;
+      final library = entry.value;
+
+      final contents = _emitLibrary(library, languageVersion).toJS;
+      fs.writeFileSync('$output/$libraryPath'.toJS, contents);
+    }
   }
 }
 

web_generator/lib/src/generate_bindings.dart

@@ -4,6 +4,9 @@
 
 import 'dart:js_interop';
 
+import 'package:path/path.dart' as p;
+
+import 'js/webidl2.dart' as webidl2;
 import 'js/webidl_api.dart' as webidl;
 import 'js/webref_css_api.dart';
 import 'js/webref_elements_api.dart';
@@ -74,8 +77,8 @@ Future<TranslationResult> generateBindings(
   final cssStyleDeclarations = await _generateCSSStyleDeclarations();
   final elementHTMLMap = await _generateElementTagMap();
   final translator = Translator(
-      packageRoot, librarySubDir, cssStyleDeclarations, elementHTMLMap,
-      generateAll: generateAll);
+      librarySubDir, cssStyleDeclarations, elementHTMLMap,
+      generateAll: generateAll, packageRoot: packageRoot);
   final array = objectEntries(await idl.parseAll().toDart);
   for (var i = 0; i < array.length; i++) {
     final entry = array[i] as JSArray<JSAny?>;
@@ -86,3 +89,21 @@ Future<TranslationResult> generateBindings(
   translator.addInterfacesAndNamespaces();
   return translator.translate();
 }
+
+Future<TranslationResult> generateBindingsForFiles(
+    Map<String, String> fileContents, String output) async {
+  // generate CSS style declarations and element tag map incase they are
+  // needed for the input files.
+  final cssStyleDeclarations = await _generateCSSStyleDeclarations();
+  final elementHTMLMap = await _generateElementTagMap();
+  final translator = Translator(output, cssStyleDeclarations, elementHTMLMap,
+      generateAll: true, generateForWeb: false);
+
+  for (final file in fileContents.entries) {
+    final ast = webidl2.parse(file.value);
+    translator.collect(p.basenameWithoutExtension(file.key), ast);
+  }
+
+  translator.addInterfacesAndNamespaces();
+  return translator.translate();
+}

web_generator/lib/src/js/webidl2.dart

@@ -0,0 +1,12 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+@JS('webidl2')
+library;
+
+import 'dart:js_interop';
+
+import 'webidl_api.dart' as idl;
+
+@JS()
+external JSArray<idl.Node> parse(String contents);

web_generator/lib/src/main.mjs

@@ -8,6 +8,7 @@ import { createRequire } from 'module';
 import * as css from '@webref/css';
 import * as elements from '@webref/elements';
 import * as idl from '@webref/idl';
+import * as webidl2 from "webidl2";
 import * as ts from 'typescript';
 
 const require = createRequire(import.meta.url);
@@ -19,6 +20,7 @@ globalThis.css = css;
 globalThis.elements = elements;
 globalThis.fs = fs;
 globalThis.idl = idl;
+globalThis.webidl2 = webidl2;
 globalThis.ts = ts;
 globalThis.location = { href: `file://${process.cwd()}/` }
 

web_generator/lib/src/package-lock.json

@@ -13,9 +13,7 @@
     "@webref/css": "^6.11.0",
     "@webref/elements": "^2.2.2",
     "@webref/idl": "^3.43.1",
-    "typescript": "^5.8.3"
-  },
-  "devDependencies": {
-    "webidl2": "^24.2.2"
+    "typescript": "^5.8.3",
+    "webidl2": "^24.4.1"
   }
 }