Skip to content

Reject an external @scope whose global JavaScript cannot name - #9310

Open
tsnobip wants to merge 1 commit into
module-instanceoffrom
external-scope-global
Open

tsnobip wants to merge 1 commit into
module-instanceoffrom
external-scope-global

Conversation

@tsnobip

@tsnobip tsnobip commented Nov 16, 2026

Copy link
Copy Markdown
Member

Stacked on #9309 (branch module-instanceof), as suggested in its review: the @scope parsing that #9309 added for @instanceOf types is now shared with externals, which never checked the global their @scope starts at.

What changes

Ast_payload.scopes_of_payload reads a @scope payload for both externals and @instanceOf types: a non-empty string or tuple of strings, whose first property, when it is a global, must be an identifier not named like a keyword. Without @module, the first property of an external @val or @new is a global that the JavaScript output prints as is, so

@scope("class") @val external b: int = "b"
@scope("foo-bar") @val external d: int = "d"
let x = b + d

compiled to let x = class.b + foo-bar.d | 0;, a syntax error and a subtraction. Each external is now an error at its @scope:

Without @module, the first property of @scope is a global, which cannot be named like the keyword "class". To read a property of the global object of that name, put "globalThis" first in @scope.
Without @module, the first property of @scope is a global, so it must be an identifier, and "foo-bar" is not one. To read a property of the global object of that name, put "globalThis" first in @scope.

Following the advice gives globalThis.class.b + globalThis["foo-bar"].d | 0. A @scope that is not strings now says what it expects instead of "Illegal attributes" or "expect string tuple list".

Decisions

  • Later properties stay free-form for externals. The printer reads them with a computed access where needed (E.dot → a["foo-bar"]), which is valid JavaScript, so @scope(("a", "foo-bar")) still compiles to a["foo-bar"].e. A class still needs every property to be an identifier, since its path is a dotted string.
  • Only a @val or @new without @module starts at a global. A @module scope is a property of the module (M["foo-bar"]), and a @send, @get, @set, @get_index or @set_index scope a property of the object (o.class.f()), so those are only checked for being strings. @scope("globalThis") stays valid on externals.
  • import.meta is accepted. @scope(("import", "meta")) starts with a keyword but is valid JavaScript and a common binding (tests/docstring_tests/Node.res uses it). A class rejects it at its @scope.
  • The keyword list is the class check's (Js_reserved_map.is_js_keyword). It also contains this, true, false, null, eval and arguments, so @scope("this") (this.x), which printed valid JavaScript, is now rejected too, as is a global with a non-ASCII name. The commit notes these under Breaking:, while the changelog entry is a fix since they read no global or are very rare. If you would rather keep them compiling, the check can be narrowed to the keywords that make kw.x a syntax error.

The external's @scope is now read once the kind of external is known, since @module may come after it.

Tests

  • New super_errors fixtures: external_scope_keyword, external_scope_not_identifier, external_new_scope_keyword, external_scope_not_strings, and instance_of_scope_import_meta. bs_illegal_attribute_scope gets the new message.
  • The existing class fixtures (instance_of_invalid_scope, instance_of_scope_keyword, instance_of_scope_global_this, instance_of_scope_not_strings, instance_of_scope_without_payload, scope_without_instance_of) produce the same output.
  • tests/tests/src/external_scope_properties.res pins the JavaScript of the forms that stay valid.
  • make test passes except the Temporal docstring tests (the local Node has no Temporal global); make test-analysis passes.

🤖 Generated with Claude Code

Why:
    An external's `@scope` was only checked for being strings, and without
    `@module` the first one names a global, printed as is: `@scope("class")`
    and `@scope("foo-bar")` on a `@val` emitted `class.b`, a syntax error,
    and `foo-bar.d`, a subtraction. #9309 checks the `@scope` of an
    `@instanceOf` type, and its review suggested sharing that parsing with
    externals. `Ast_payload.scopes_of_payload` now reads the payload for both
    and checks the global the properties start at.

Diagnostic added (an external @scope whose global JavaScript cannot name):
Example:
    @scope("class") @Val external b: int = "b"
    @scope("foo-bar") @Val external d: int = "d"
    let x = b + d
Before (js):
    let x = class.b + foo-bar.d | 0;
After (diagnostic): one error per external, each compiled alone
    Without @module, the first property of @scope is a global, which cannot be named like the keyword "class". To read a property of the global object of that name, put "globalThis" first in @scope.
    Without @module, the first property of @scope is a global, so it must be an identifier, and "foo-bar" is not one. To read a property of the global object of that name, put "globalThis" first in @scope.

Following the advice, `@scope(("globalThis", "class"))` and
`@scope(("globalThis", "foo-bar"))` compile to
`globalThis.class.b + globalThis["foo-bar"].d | 0`.

Diagnostic modified (an external @scope that is not strings):
Example:
    @scope @Val external x: int = "x"
    @scope(("window", 3)) @Val external y: int = "y"
Before (diagnostic): one error per external, each compiled alone
    Illegal attributes
    expect string tuple list
After (diagnostic): one error per external, each compiled alone
    @scope on an external expects the properties its value is read through, such as @scope("document") or @scope(("window", "location")).
    @scope on an external expects the properties its value is read through, such as @scope("document") or @scope(("window", "location")).

Representation modified (which properties of a @scope are checked):
Before (representation): Ast_external_process.parse_external_attributes, Ast_untagged_variants.strings_of_payload
    @Val @scope("class") ↦ class.v, a syntax error
    @Val @scope("foo-bar") ↦ foo-bar.v, a subtraction
    @new @scope("default") ↦ new (default.K)(), a syntax error
    @Val @scope(("import", "meta")) ↦ import.meta.v
    @Val @scope(("a", "foo-bar")) ↦ a["foo-bar"].v
    @module("m") @scope("foo-bar") ↦ M["foo-bar"].v
    @send @scope("class") ↦ o.class.f()
    note: an external's properties are only checked for being strings
After (representation): Ast_payload.scopes_of_payload
    @Val @scope("class") ↦ error: a global named like a keyword
    @Val @scope("foo-bar") ↦ error: a global that is not an identifier
    @new @scope("default") ↦ error: a global named like a keyword
    @Val @scope(("import", "meta")) ↦ import.meta.v
    @Val @scope(("a", "foo-bar")) ↦ a["foo-bar"].v
    @module("m") @scope("foo-bar") ↦ M["foo-bar"].v
    @send @scope("class") ↦ o.class.f()
    @scope(("import", "meta")) @instanceof("C") ↦ error: a global named like a keyword
    note: the first property is a global for a @Val or @new without @module, and for an @instanceof type without @module
    note: a class also needs every property to be an identifier, and no "globalThis" first

The properties after the global may be any string for an external, as
before: they are read with a computed access where they need one, as in
`a["foo-bar"]`. A class keeps its own rules: its path is a string of
identifiers and dots, and `globalThis` in front would give one class two
identities. `@scope("globalThis")` stays valid on an external. Class
errors are unchanged, except that `@scope(("import", "meta"))`, which an
external may use, is reported at the `@scope` of a class rather than as an
invalid `@instanceOf`. The external's `@scope` is now read once the kind of
external is known, since `@module` can follow it.

Review: Why accept `import` as the first property of an external's @scope? `@scope(("import", "meta"))` reads `import.meta`, which is valid JavaScript and how bindings read `import.meta.url` or `import.meta.env` (tests/docstring_tests/Node.res does).
Review: Why is the first property of a @send, @get or @set not checked? It is a property of the object the external is called on, as in `o.class.f()`, never a global.

Breaking: an external `@val` or `@new` without `@module` whose `@scope` starts with a string that is not an ASCII identifier, or with a JavaScript keyword other than the `import` of `import.meta`, no longer compiles. Most of these emitted invalid JavaScript. Those that did not, such as `@scope("eval")` or a global with a non-ASCII name, read the same global with "globalThis" first in `@scope`; `@scope("this")` or `@scope("true")` read no global.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Paul Tsnobiladzé <2479216+tsnobip@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown

Changelog

🐛 Bug fix

  • Report an error for an external whose @scope starts at a global that JavaScript cannot name, such as @scope("class") or @scope("foo-bar") on a @val or @new without @module, instead of emitting invalid JavaScript.

💥 A commit says what it breaks (Breaking:), but no changelog entry is a breaking change.

Semantic Diff

1 commit · Full page

Reject an external @scope whose global JavaScript cannot name

1605436 · tsnobip + Claude · Nov 16, 2026, 13:40 UTC

Why

An external's @scope was only checked for being strings, and without @module the first one names a global, printed as is: @scope("class") and @scope("foo-bar") on a @val emitted class.b, a syntax error, and foo-bar.d, a subtraction. #9309 checks the @scope of an @instanceOf type, and its review suggested sharing that parsing with externals. Ast_payload.scopes_of_payload now reads the payload for both and checks the global the properties start at.

Diagnostic added (an external @scope whose global JavaScript cannot name)

@scope("class") @val external b: int = "b"
@scope("foo-bar") @val external d: int = "d"
let x = b + d

js · Before

let x = class.b + foo-bar.d | 0;

diagnostic · After · one error per external, each compiled alone

Without @module, the first property of @scope is a global, which cannot be named like the keyword "class". To read a property of the global object of that name, put "globalThis" first in @scope.
Without @module, the first property of @scope is a global, so it must be an identifier, and "foo-bar" is not one. To read a property of the global object of that name, put "globalThis" first in @scope.

Following the advice, @scope(("globalThis", "class")) and @scope(("globalThis", "foo-bar")) compile to globalThis.class.b + globalThis["foo-bar"].d | 0.

Diagnostic modified (an external @scope that is not strings)

@scope @val external x: int = "x"
@scope(("window", 3)) @val external y: int = "y"

diagnostic · one error per external, each compiled alone

-Illegal attributes
-expect string tuple list
+@scope on an external expects the properties its value is read through, such as @scope("document") or @scope(("window", "location")).
+@scope on an external expects the properties its value is read through, such as @scope("document") or @scope(("window", "location")).

Representation modified (which properties of a @scope are checked)

representation · Before: Ast_external_process.parse_external_attributes, Ast_untagged_variants.strings_of_payload · After: Ast_payload.scopes_of_payload

-@val @scope("class")                        ↦ class.v, a syntax error
-@val @scope("foo-bar")                      ↦ foo-bar.v, a subtraction
-@new @scope("default")                      ↦ new (default.K)(), a syntax error
+@val @scope("class")                        ↦ error: a global named like a keyword
+@val @scope("foo-bar")                      ↦ error: a global that is not an identifier
+@new @scope("default")                      ↦ error: a global named like a keyword
 @val @scope(("import", "meta"))             ↦ import.meta.v
 @val @scope(("a", "foo-bar"))               ↦ a["foo-bar"].v
 @module("m") @scope("foo-bar")              ↦ M["foo-bar"].v
 @send @scope("class")                       ↦ o.class.f()
-note: an external's properties are only checked for being strings
+@scope(("import", "meta")) @instanceOf("C") ↦ error: a global named like a keyword
+note: the first property is a global for a @val or @new without @module, and for an @instanceOf type without @module
+note: a class also needs every property to be an identifier, and no "globalThis" first

The properties after the global may be any string for an external, as before: they are read with a computed access where they need one, as in a["foo-bar"]. A class keeps its own rules: its path is a string of identifiers and dots, and globalThis in front would give one class two identities. @scope("globalThis") stays valid on an external. Class errors are unchanged, except that @scope(("import", "meta")), which an external may use, is reported at the @scope of a class rather than as an invalid @instanceOf. The external's @scope is now read once the kind of external is known, since @module can follow it.

⚠️ Breaking: an external @val or @new without @module whose @scope starts with a string that is not an ASCII identifier, or with a JavaScript keyword other than the import of import.meta, no longer compiles. Most of these emitted invalid JavaScript. Those that did not, such as @scope("eval") or a global with a non-ASCII name, read the same global with "globalThis" first in @scope; @scope("this") or @scope("true") read no global.

Review

  • Why accept import as the first property of an external's @scope? @scope(("import", "meta")) reads import.meta, which is valid JavaScript and how bindings read import.meta.url or import.meta.env (tests/docstring_tests/Node.res does).
  • Why is the first property of a @send, @get or @set not checked? It is a property of the object the external is called on, as in o.class.f(), never a global.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant