Semantic Diff

#9309 Read the class of an @instanceOf type from its @module and @scope

3 commits

a531dc3ae031fa9468e2825dfc32bafe76178169..pr-9309

e13e98ed6 · tsnobip + Claude · Nov 15, 2026, 17:43 UTC

Read the class of an @instanceOf type from its @module and @scope

Why

@module and @scope on an @instanceOf type were silently ignored (#9239), so the class check of an untagged variant read a global of the class's name. For a class of a JavaScript library or a local file that global does not exist, and the check threw a ReferenceError. Like an external, the type now says where its class is found: @module("m") reads it among the exports of m, "default" for the default export, imported as a @module external imports it, and @scope puts its properties in front of the path.

modifiedJS class check of an @instanceOf type

@instanceOf("Object3D") type object3D@module("three") @instanceOf("Mesh") type mesh = private object3D@scope("THREE") @instanceOf("Line") type line = private object3D @unboxedtype shape = Mesh(mesh) | Line(line) | Other(object3D) let kind = s =>  switch s {  | Mesh(_) => "mesh"  | Line(_) => "line"  | Other(_) => "other"  }
js
Before
After
let Three = require("three"); function kind(s) {function kind(s) { if (s instanceof Mesh) { if (s instanceof Three.Mesh) { return "mesh"; return "mesh"; } else if (s instanceof Line) { } else if (s instanceof THREE.Line) { return "line"; return "line"; } else { } else { return "other"; return "other"; } }}}

modifiedRepresentation where the class of an @instanceOf type is found

representation
Before Ast_untagged_variants.process_runtime_annotation
After Ast_untagged_variants.class_of_attributes, Lam_compile_external_call.class_constructor
@instanceOf("Mesh") ↦ the global Mesh@instanceOf("Mesh") ↦ the global Mesh@module("three") @instanceOf("Mesh") ↦ the global Mesh@scope("THREE") @instanceOf("Mesh") ↦ the global Mesh
notea class is identified by its path
@module("three") @instanceOf("Mesh") ↦ Three.Mesh, with Three the import of "three"@module("./shape.js") @instanceOf("default") ↦ the default import of "./shape.js"@scope("THREE") @instanceOf("Mesh") ↦ the global THREE.Mesh, as @instanceOf("THREE.Mesh")@module("lib") @notUndefined ↦ never undefined, @module ignored as before
notea class is identified by its path and its module

removedDiagnostic two classes of one name in a variant

@instanceOf("Mesh") type globalMesh@module("three") @instanceOf("Mesh") type mesh @unboxedtype t = Global(globalMesh) | Three(mesh) | Plain({"plain": bool}) let kind = x =>  switch x {  | Global(_) => "global"  | Three(_) => "three"  | Plain(_) => "plain"  }
diagnostic
Before
This untagged variant definition is invalid: At most one case can be an instance of Mesh.
js
After
let Three = require("three"); function kind(x) {  if (x instanceof Mesh) {    return "global";  } else if (x instanceof Three.Mesh) {    return "three";  } else {    return "plain";  }}

addedDiagnostic an interface that states another module

module M: {  @module("three") @instanceOf("Mesh") type mesh} = {  @instanceOf("Mesh") type mesh}
diagnostic
Before
After
none, both declarations stated the global Mesh Signature mismatch: Actual declaration (Example.res:4:23-31): @instanceOf("Mesh") type mesh Expected declaration (Example.res:2:40-48): @module("three") @instanceOf("Mesh") type mesh Their runtime representations differ: Actual declaration: instances of Mesh Expected declaration: instances of Mesh from "three"

modifiedDiagnostic an @instanceOf payload that is not a string

@module("three") @instanceOf(Mesh) type mesh
diagnostic
Before
After
@instanceOf expects the name of a global class, such as @instanceOf("Date") or @instanceOf("Intl.Locale").@instanceOf expects the name of a class that "three" exports, such as @instanceOf("Mesh"), or @instanceOf("default") for its default export.

addedDiagnostic a @scope that cannot lead to a class

@scope("default") @instanceOf("Mesh") type mesh
diagnostic
Before
After
none, @scope was ignored and the check read the global MeshWithout @module, the first property of @scope is a global, which cannot be named like the keyword "default".

addedDiagnostic a @module that names no module

@module(("three", "THREE")) @instanceOf("Mesh") type mesh
diagnostic
Before
After
none, @module was ignored and the check read the global Mesh@module on an @instanceOf type expects the module that exports the class, such as @module("three") or @module("./shapes.js").

Review

  • Why are @module and @scope still ignored on a @typeOf or @notUndefined type? @notUndefined shipped in v12, so an error there would break bindings that compile today, and without a class the attributes cannot make a check read the wrong value, which was the harm in #9239.
  • Where is a relative path such as @module("./x.js") resolved? It is emitted as written, relative to the module that compiles the check, as for a @module external used from another module.
  • Why does a class of a module skip the checks of global paths such as Object or Array? Those name the builtin classes only as globals; an export can be named anything, also like a keyword such as default.
2b4c744ae · tsnobip + Claude · Nov 15, 2026, 18:07 UTC

Test the tuple @scope and the remaining @instanceOf payload errors

Codecov's patch report on #9309 listed 10 uncovered lines in ast_untagged_variants.ml. Five were real gaps, now tested: the tuple form of @scope (the runtime test reads a class through two properties), a @scope with a non-string or no payload, @module(""), and a non-string @instanceOf without @module. The other five were covered but not measurable. The @scope errors went through a helper that always raises, so bisect never reached the point after the call; they now raise directly. The fallback for attributes without a location, which source code never reaches, is now one shared function instead of three copies.

3dcad0a27 · tsnobip + Claude · Nov 16, 2026, 07:57 UTC

Reject @module and @scope on a type without @instanceOf

Why

@module and @scope on a type declaration without @instanceOf had no effect and were ignored without a word. The same silence on an @instanceOf type is how #9239 went unnoticed. Now that the two attributes say where the class of an @instanceOf type is found, they are an error on any other type, as suggested in the review of #9309.

addedDiagnostic @module or @scope on a type without @instanceOf

@module("three") type mesh@scope("THREE") @notUndefined type line@module("x") type record = {a: int}
diagnostic
Before
After one error per declaration, each compiled alone
none, the attributes were ignored @module on a type declaration names the module a class is imported from, so it needs @instanceOf too. Add @instanceOf with the name of the class, or remove @module.@scope on a type declaration names the properties a class is read through, so it needs @instanceOf, and this type has @notUndefined instead. Remove @scope, or write @instanceOf instead of @notUndefined if its values are instances of a class.@module on a type declaration names the module a class is imported from, so it needs @instanceOf, which only abstract types and type abbreviations can have. Remove @module.

The advice depends on the declaration, since adding @instanceOf only works on an abstract type or an abbreviation without another annotation. A record with both @typeOf and @module still reports the misplaced @typeOf first. The @instanceOf completion doc no longer calls the class global, since it can come from a module.

Review

  • Does an interface compiled by an older compiler still load? Yes: the check runs in Typedecl.transl_declaration, where a declaration is type-checked, and process_runtime_annotation, which also reads declarations from .cmi files, does not raise it.