Support global-only declaration packages such as @webgpu/types

[jagguji]

Problem

@webgpu/types is a type-only package whose dist/index.d.ts declares WebGPU browser globals such as GPUDevice, GPUBuffer, GPUTexture, and additions to Navigator/canvas interfaces. It is not an importable JavaScript module.

After fixing the Windows scratch-cache path in #193, the package installs and its declaration entry resolves correctly, but extraction stops at the module boundary:

$ npx @juspay/rescript-bindgen --pkg @webgpu/types --out webgpu-types
[bindgen] entry: .../.bindgen-cache/node_modules/@webgpu/types/dist/index.d.ts
[bindgen] @module("@webgpu/types")
[bindgen] error: No module symbol for .../@webgpu/types/dist/index.d.ts

Tested with @webgpu/types@0.1.71.

Root cause

The extractor currently starts from either:

• a source file with top-level module exports; or
• an ambient declare module "..." block.

It then emits React components, exported functions, and exported classes, with runtime access generally rooted in @module(...).

A global-script declaration file has neither kind of module symbol. Even if it were allowed past that check, @module("@webgpu/types") would be incorrect because the package has no runtime module to import, and top-level type/interface declarations are not currently treated as generation roots.

Proposed support

Add a global-declarations extraction/emission mode for global-only .d.ts packages:

• detect an entry containing global declarations but no external/ambient module symbol;
• traverse relevant top-level global interfaces, type aliases, variables, constructors, and functions;
• emit browser-global runtime bindings with the appropriate @val, @new, @get, @set, and @send annotations instead of @module;
• make referenced type aliases and interfaces available as generated ReScript types;
• preserve declaration merging/augmentations such as Navigator, HTMLCanvasElement, and OffscreenCanvas additions;
• report unsupported global declarations explicitly rather than silently dropping them.

Whether this is auto-detected or enabled through an explicit flag can be decided during implementation, but normal importable-package behavior must remain unchanged.

Acceptance criteria

• @webgpu/types gets past resolution and extraction without No module symbol.
• Generated bindings never attempt to import a runtime @webgpu/types module.
• A representative slice of WebGPU globals is usable from ReScript and compiles under the supported ReScript version.
• Global constructors/constants and instance methods/properties use correct interop annotations.
• A self-contained global-only golden fixture covers the mode without requiring network access.
• Existing module and ambient-module fixtures remain byte-identical unless intentionally updated.

Related

• Freeze public type names across bindgen upgrades #193 fixes the separate Windows C:\\C:\\... scratch-cache path problem exposed before extraction begins.