Skip to content

Resolve FFI externals during type checking - #8728

Open
cknitt wants to merge 1 commit into
masterfrom
codex/resolve-external-in-typedecl
Open

cknitt wants to merge 1 commit into
masterfrom
codex/resolve-external-in-typedecl

Conversation

@cknitt

@cknitt cknitt commented Oct 6, 2026 •

Copy link
Copy Markdown
Member

Why

Parsetree is the AST that PPXs see, that -bs-ast serializes, and that #8624 wants to freeze as "v1". A principle there is that the parsetree describes source code only.

Externals broke that. After the built-in PPX had read an external's FFI attributes (@send, @module, @as, @inline, …), it replaced the primitive string with the computed specification:

and primitive_repr =
  | Prim_name of string
  | Prim_ffi of {name: string; spec: External_ffi_types.t}
  | Prim_inline_const of External_ffi_types.inline_const

So parsetree.ml depended on the compiler's internal FFI representation, the type had two cases no PPX can observe, and the v0 bridge needed an error branch for them.

What changes

pval_prim is the string as written: string option. The attributes stay where the user put them, and the type checker interprets them. The frontend no longer resolves them too.

For

@send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
@inline let answer = 42

the tree after the built-in PPX (bsc -only-parse -dparsetree) changes from

value_description "on"
  core_type
    Ptyp_arrow        (* arity 2: the @as argument already erased *)
    …
  "addEventListener"
  <ffi spec>
value_description "answer"
  core_type
    Ptyp_constr "int"
  <inline const>

to

value_description "on"
  attribute "send"
  core_type
    Ptyp_arrow        (* arity 3, with the Parg_fixed "click" argument *)
    …
  "addEventListener"
value_description "answer"
  attribute "inline"
    [ Pstr_eval (Pexp_constant PConst_int (42,None)) ]
  core_type
    Ptyp_constr "int"
  "#rescript-inline"

How the pieces fit:

  • Type checker resolves. Typedecl.transl_value_decl calls Primitive.resolve_external, a hook that returns the resolved type, the attributes resolution did not consume, the primitive name and its kind (Kind_intrinsic, Kind_external spec, Kind_inline_const c). It types the resolved type, so .cmi/.cmj and the generated JavaScript are what they were.
  • The hook. The resolver (Ast_external.resolve) lives above compiler/ml, so it is a hook; Ppx_entry, which every compiler driver links, registers it at module initialization, like the Oprint hooks. The syntax test runner type checks without Ppx_entry, so it registers the hook itself. It runs in the type checker because -bs-ast writes the parsetree after the built-in PPX and a later bsc process reads it back: the specification must be recomputable from the tree.
  • Diagnostics come from the type checker. The resolver reports an external's errors and warnings, and checks unused attributes on the resolved form (Bs_ast_invariant's pass skips FFI externals). It runs inside the declaration's @warning scope, so @warning("-101") on an external, or a @@warning("-101") anywhere above it in the file, now silences its unused-attribute warning. Before, only a @@warning at the top of the file did. Errors and warning 101 now come in source order with type errors rather than in the parse step; the reprint path and -bs-ast alone no longer report them.
  • Relative @module paths. Such an external must not be inlined in other modules, since its path is relative to the declaring file. The built-in PPX used to wrap it in include (struct external … end : {let …}). Now the type checker does the equivalent: in a signature, Typedecl gives it Val_reg; in a structure, Typemod builds that constrained include in the typed tree, whose coercion (Tcoerce_primitive) emits the exported function. Primitive.no_cross_module_inline reads relativeness off the resolved spec (External_ffi_types.is_relative, split out of check_decl), so Ast_external_process.resolution loses its no_inline_cross_module flag. The JavaScript is unchanged, and so are hover, references and definition in the editor.
  • Recursive modules. A module rec signature is typed twice, the first time with warnings off, so its externals are resolved twice but reported once.
  • "#rescript-inline" is reserved. external x: int = "#rescript-inline" written by hand is an error now; it used to compile to nothing.
  • Each unused attribute is reported once. A relative @module external used to keep its resolved form as a val in the wrapper's interface, which was checked as well, so its unused attributes were reported twice.
  • @inline constants become external answer: int = "#rescript-inline" with the @inline(<literal>) attribute kept; Ast_external_mk has the helpers that build and read such a declaration, and Bs_builtin_ppx shrinks to one case per item instead of one per literal kind. A structural node for them is a separate Stamp parsetree v1: what remains before the AST can be frozen for PPXs #8624 item.
  • @inline let bigint constants are inlined now, like the other literals and like bigint constants in signatures. Before, a let skipped them: @inline let big = 10n stayed an exported binding, with warning 53 saying @inline cannot appear there.
  • Ast_external_process.handle_attributes is resolve, returning a resolution record (pval_type, spec, pval_attributes) instead of a tuple and a second wrapper.
  • Printers. Outcometree.oval_prim is the value's resolved Primitive.description, so hover and interface output still render the FFI attributes, and Primitive.print is gone. Printast, Pprintast and the ReScript printer print the string as written.
  • Typed tree. Typedtree.val_prim is gone: its two readers, the typed tree printer and gentype, use the value's val_kind (Val_prim), which has the resolved primitive.
  • v0 bridge. v0's pval_prim is a string list: Ast_mapper_to0 writes the one string, with no error branch any more, and Ast_mapper_from0 reads it back.
  • Ast_attributes.rs_externals is renamed is_ffi_external and takes the primitive name. Bs_ast_invariant loses a Bs_ffi_warning branch that could not fire.

Under -bs-no-builtin-ppx, a plain-named external is now resolved as an FFI external by the type checker, where it used to be typed as an intrinsic of that name.

Cost

Each external is resolved in the compile step, which now reads it as written. The unused-attribute check walks the resolved form only when it checks one of the attributes or the type has a form the quick check doesn't look into; most resolved externals have neither. Allocated words for the parse and compile steps together, measured locally against master:

File master this PR
Stdlib_Math.resi 333,661 331,506 (−0.65%)
Stdlib_String.resi 503,725 500,975 (−0.55%)
Stdlib_Date.res 572,567 573,138 (+0.10%)
Pervasives.res 240,152 240,630 (+0.20%)
Stdlib_Math.res 332,813 334,116 (+0.39%)
Stdlib_Object.res 245,471 247,664 (+0.89%)
Stdlib_Symbol.res 146,116 148,200 (+1.43%)

Stdlib_Symbol.res is a small file of @val @scope("Symbol") constants: its .ast now carries each one's attributes as written.

Tests

  • tests/syntax_tests/data/ast-mapping/Externals.res: intrinsic, @val, @send, relative @module, @scope, @obj, @as and @variadic externals print back unchanged after the v0 round trip.
  • ounit_ast_mapper0_tests: an external's primitive string and @send attribute survive Ast_mapper_to0 and Ast_mapper_from0.
  • ounit_string_literal_tests builds its inline constants with Ast_external_mk.inline_const_of_expression.
  • tests/build_tests/super_errors/fixtures/warning_101_external_arg_attribute.res: an @as on a non-_ argument of a @send external still reports warning 101, once per external, in source order, also under a doc comment and inside a type argument.
  • tests/build_tests/super_errors/fixtures/warning_101_relative_module_external.res: the same on a relative @module external is reported once, where it used to be reported twice, and @warning("-101") on an external silences it.
  • tests/build_tests/super_errors/fixtures/warning_101_recursive_module.res: an unused attribute in a module rec signature is reported once.
  • tests/build_tests/super_errors/fixtures/warning_101_floating_attribute.res: a @@warning("-101") in the middle of a file silences the externals after it.
  • tests/build_tests/super_errors/fixtures/external_reserved_inline_primitive.res: the "#rescript-inline" error.
  • tests/syntax_tests/data/oprint/oprint.res: the outcome printer test types @val, @send and relative @module externals.
  • tests/tests/src/relative_path_use.res: another module calls relative externals (top level, nested module, functor, in a module rec, declared in a .resi as external or as let) through the exported values, and inlines only the non-relative one.
  • tests/analysis_tests/tests/src/RelativeExternal.res: hover, references and definition on relative externals.
  • tests/tests/src/inline_const.res: @inline let bigint constants, positive and negative, are inlined.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kbf3gGqcYiyMeZgs8UzT5G

@codecov

codecov Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 86.98225% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.09%. Comparing base (9523348) to head (4114973).
⚠️ Report is 1 commits behind head on master.

Files with missing lines Patch % Lines
compiler/frontend/bs_ast_invariant.ml 76.00% 6 Missing ⚠️
compiler/ml/printtyped.ml 0.00% 4 Missing ⚠️
compiler/frontend/bs_builtin_ppx.ml 91.66% 2 Missing ⚠️
compiler/gentype/translate_signature.ml 50.00% 2 Missing ⚠️
compiler/frontend/ast_external_mk.ml 93.75% 1 Missing ⚠️
compiler/ml/external_ffi_types.ml 92.30% 1 Missing ⚠️
compiler/ml/primitive.ml 75.00% 1 Missing ⚠️
compiler/ml/printast.ml 0.00% 1 Missing ⚠️
compiler/syntax/src/res_outcome_printer.ml 66.66% 1 Missing ⚠️
compiler/syntax/src/res_printer.ml 50.00% 1 Missing ⚠️
... and 2 more
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #8728      +/-   ##
==========================================
+ Coverage   82.06%   82.09%   +0.02%     
==========================================
  Files         455      455              
  Lines       65399    65396       -3     
==========================================
+ Hits        53672    53686      +14     
+ Misses      11727    11710      -17     
Files with missing lines Coverage Δ
compiler/core/lam_compile_external_call.ml 92.98% <ø> (ø)
compiler/frontend/ast_attributes.ml 94.20% <100.00%> (+2.42%) ⬆️
compiler/frontend/ast_exp_handle_external.ml 80.48% <100.00%> (ø)
compiler/frontend/ast_external.ml 100.00% <100.00%> (+23.80%) ⬆️
compiler/frontend/ast_external_process.ml 77.51% <100.00%> (-0.15%) ⬇️
compiler/frontend/ast_literal.ml 100.00% <100.00%> (ø)
compiler/frontend/ppx_entry.ml 91.66% <ø> (ø)
compiler/gentype/translation.ml 92.85% <100.00%> (+1.42%) ⬆️
compiler/ml/ast_iterator.ml 94.61% <ø> (ø)
compiler/ml/ast_mapper_from0.ml 79.46% <100.00%> (ø)
... and 19 more

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch from 36bd95a to b71e398 Compare October 7, 2026 04:59
@pkg-pr-new

pkg-pr-new Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript@8728

@rescript/belt

npm i https://pkg.pr.new/@rescript/belt@8728

@rescript/darwin-arm64

npm i https://pkg.pr.new/@rescript/darwin-arm64@8728

@rescript/linux-arm64

npm i https://pkg.pr.new/@rescript/linux-arm64@8728

@rescript/linux-x64

npm i https://pkg.pr.new/@rescript/linux-x64@8728

@rescript/runtime

npm i https://pkg.pr.new/@rescript/runtime@8728

@rescript/win32-x64

npm i https://pkg.pr.new/@rescript/win32-x64@8728

commit: 4114973

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown

@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch 3 times, most recently from e2110a3 to 17bf46b Compare October 13, 2026 20:15
cknitt added a commit that referenced this pull request Oct 16, 2026
`pval_prim` is the primitive string as written, with its location. The
frontend still checks each FFI external, but `Typedecl` gets its spec through
`Primitive.resolve_external`, so the parsetree no longer depends on
`External_ffi_types`.

Review: Why does the frontend resolve each external at all? It reports the
errors and warnings where they were reported before, and decides whether a
relative `@module` keeps other modules from inlining the external. The type
checker's second resolution runs without warnings.

Review: How do `@inline` constants work without `Prim_inline_const`? The
built-in PPX turns them into an external with the internal primitive
`#rescript-inline` that keeps the `@inline(<literal>)` attribute.

Review: Is the global `Primitive.resolve_external` safe with parallel
requests? `Ast_external` sets it once during module initialization, like the
`Oprint` hooks, and it is only read afterwards.

Area: frontend typechecker syntax gentype tests
Output: unchanged, generated JS of the test suites is byte-identical
Formatting: unchanged
Formats: ast cmt
PPX: unchanged, an external's primitive string reaches v0 as before
Editor: unchanged
Errors: none, the new fixture follows the warning_<NN> naming convention
Tests: +tests/syntax_tests/data/ast-mapping/Externals.res
 +tests/build_tests/super_errors/fixtures/warning_101_external_arg_attribute.res
 ~tests/ounit_tests/ounit_ast_mapper0_tests.ml
 ~tests/ounit_tests/ounit_string_literal_tests.ml
PR: #8728
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018oLiCQjGFSE2qwfYqCMF9e
Signed-off-by: Christoph Knittel <ck@cca.io>
@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch from 17bf46b to 0527e03 Compare October 16, 2026 19:29
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Changelog

🐛 Bug fix

  • Report an unused attribute on a relative @module external once instead of twice.
  • Inline @inline let bigint constants like other literals, instead of warning that @inline cannot appear there.

🏠 Internal

Semantic Diff

5 commits · Full page

✨ Resolve an external's FFI attributes in the type checker

9d69d5d · cknitt + Claude · Oct 16, 2026, 19:28 UTC · new

Why

The parsetree is what PPXs see and what -bs-ast serializes, and #8624 wants it to describe source only. After the built-in PPX had read an external's @send, @module, @as… attributes, it replaced the primitive string with the computed FFI specification (Prim_ffi, Prim_inline_const), so Parsetree depended on External_ffi_types and carried cases no PPX can observe. Now pval_prim is the string as written, with its location, and Typedecl resolves the attributes through Primitive.resolve_external, a hook the frontend registers since the resolver lives above compiler/ml. The generated JavaScript is unchanged.

AST modified (externals after the built-in PPX)

type t
@send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
@inline let answer = 42

expanded

 …
 structure_item
   Pstr_primitive
   value_description "on"
+    attribute  "send"
+      []
     core_type
       Ptyp_arrow
-      arity = 2
+      arity = 3
       Nolabel
       core_type
         Ptyp_constr "t"
         []
       Nolabel
+      Parg_fixed
+        value
+          Pfixed_string (source="click", semantic="click")
+      Nolabel
       core_type
         Ptyp_arrow
         …
       core_type
         Ptyp_constr "unit"
         []
     "addEventListener"
-    <ffi spec>
 structure_item
   Pstr_primitive
   value_description "answer"
+    attribute  "inline"
+        structure_item
+          Pstr_eval
+          expression
+            Pexp_constant PConst_int (42,None)
     core_type
       Ptyp_constr "int"
       []
-    <inline const>
+    "#rescript-inline"

Typedtree modified (externals)

type t
@send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
@inline let answer = 42

typed

 …
 structure_item
   Tstr_primitive
   value_description on/1002
     core_type
       Ttyp_arrow
       Nolabel
       core_type
         Ttyp_constr "t/1001"
         []
       Nolabel
       core_type
         Ttyp_arrow
         …
       core_type
         Ttyp_constr "unit/5"
         []
     "addEventListener"
-    <ffi spec>
 structure_item
   Tstr_primitive
   value_description answer/1003
     core_type
       Ttyp_constr "int/1"
       []
-    <inline const>
+    "#rescript-inline"

Review

  • Why does the frontend still read the attributes? To report errors and warnings where they were reported, to check unused attributes on the resolved form, and to learn whether a relative @module path keeps other modules from inlining the external, which wraps it in a constrained include as before. The type checker resolves again with warnings off, so nothing is reported twice.
  • Why a hook rather than passing the result along? -bs-ast writes the parsetree after the built-in PPX and a later bsc process reads it back, so the specification has to be recomputable from the tree; Ast_external registers the resolver at module initialization, as the Oprint hooks are, and every entry point that type checks links it.
  • What is "#rescript-inline"? The primitive of an @inline constant's declaration, which keeps its @inline(<literal>) attribute; the resolver turns it into Kind_inline_const. A structural form is a separate Stamp parsetree v1: what remains before the AST can be frozen for PPXs #8624 item.
  • Do PPXs see a difference? No: they run before the built-in PPX, and the v0 bridge carries the string as before; its error branch for already-resolved externals is gone.
  • What changes under -bs-no-builtin-ppx? An external with a plain name is now resolved as an FFI external by the type checker; before, it was typed as an intrinsic of that name.
✨ Check an external's unused attributes where it is resolved

548eab4 · cknitt + Claude · Nov 02, 2026, 19:49 UTC · new

Why

The frontend resolved each FFI external twice, once to validate it and once more for the unused-attribute check after the built-in PPX, and the resolved val that a relative @module external keeps for its interface was checked as well, so its unused attributes were reported twice. Ast_external.validate now runs the check on the form it has just resolved, the later pass skips FFI externals, and an attribute is reported at most once. The structure mapper maps each item before the rest, so these diagnostics stay in source order.

Diagnostic modified (unused attribute on a relative @module external)

@module("./local") external relative: (@as("v") int) => unit = "relative"

diagnostic

 Warning number 101
 A.res:1:40-42
 Unused attribute: @as
-
-Warning number 101
-A.res:1:40-42
-Unused attribute: @as

Review

  • Does the order of warnings change? Between externals, no: the mapper now maps items left to right (the right operand of :: was evaluated first, which had reversed them). An external's unused attributes are reported while it is mapped, so they come before the later pass's warnings for other items, such as integer overflow.
✨ Read a value's primitive from its kind, not copies of it

3cd7c05 · cknitt + Claude · Nov 02, 2026, 19:51 UTC · new

Typedtree.val_prim kept the primitive string as written, but its two readers (the typed tree printer and gentype) only need the resolved primitive, which the value's val_kind already has; the field is gone. Outcometree.oval_prim is that Primitive.description too, instead of out_primitive, a copy of its kind with the name, so Primitive.print is gone as well.

✨ Inline @inline let bigint constants like other literals

59a5808 · cknitt + Claude · Nov 02, 2026, 19:53 UTC · new

Why

An @inline bigint constant in a signature was inlined, but in a let the built-in PPX skipped bigints, so the binding stayed an ordinary exported value and the attribute was reported as misplaced. Both forms now read the constant the same way.

JS modified (@inline let with a bigint)

@inline let big = 10n
let use = () => big

js

 function use() {
   return 10n;
 }
-let big = 10n;
-exports.big = big;
 exports.use = use;

Diagnostic removed (@inline on a bigint let)

@inline let big = 10n

diagnostic · Before

Warning number 53
the @inline attribute cannot appear in this context
✨ Pass an FFI external's primitive name to the code that resolves it

d7f09dd · cknitt + Claude · Nov 02, 2026, 19:54 UTC · new

Ast_attributes.is_ffi_external takes the primitive name rather than pval_prim, so each caller matches Some {txt = prim_name} once and hands the name on, and Ast_external.validate loses an "empty primitive string" error it could not reach. Primitive.resolve_external keeps its string argument for the same reason: Typedecl has already matched it.

@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch 3 times, most recently from 02f4919 to d7f09dd Compare November 2, 2026 19:56
@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch from d7f09dd to e642cee Compare November 10, 2026 16:57
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Changelog

🐛 Bug fix

  • Report an unused attribute on a relative @module external once instead of twice.
  • @warning on an external, or a @@warning anywhere before it in the file, now applies to the warnings about its FFI attributes, such as an unused @as.
  • Inline @inline let bigint constants like other literals, instead of warning that @inline cannot appear there.

🏠 Internal

  • Keep resolved FFI specifications out of the parsetree, which now holds an external's primitive string as written. The type checker resolves each external once.

Semantic Diff

1 commit · Full page

✏️ Resolve an external's FFI attributes in the type checker

4114973 · cknitt + Claude · Nov 10, 2026, 19:24 UTC · edited

Why

The parsetree is what PPXs see and what -bs-ast serializes, and #8624 wants it to describe source only. After the built-in PPX had read an external's @send, @module, @as… attributes, it replaced the primitive string with the computed FFI specification (Prim_ffi, Prim_inline_const), so Parsetree depended on External_ffi_types and carried cases no PPX can observe. Now pval_prim is the string as written (string option), and Typedecl resolves the attributes through Primitive.resolve_external, a hook the frontend registers since the resolver lives above compiler/ml. The frontend no longer resolves them as well. The resolver also reports the external's errors and warnings, inside the declaration's @warning scope, and after any @@warning above it in the file. The generated JavaScript is unchanged.

AST modified (externals after the built-in PPX)

type t
@send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
@inline let answer = 42

expanded

 …
 structure_item
   Pstr_primitive
   value_description "on"
+    attribute  "send"
+      []
     core_type
       Ptyp_arrow
-      arity = 2
+      arity = 3
       Nolabel
       core_type
         Ptyp_constr "t"
         []
       Nolabel
+      Parg_fixed
+        value
+          Pfixed_string (source="click", semantic="click")
+      Nolabel
       core_type
         Ptyp_arrow
         …
       core_type
         Ptyp_constr "unit"
         []
     "addEventListener"
-    <ffi spec>
 structure_item
   Pstr_primitive
   value_description "answer"
+    attribute  "inline"
+        structure_item
+          Pstr_eval
+          expression
+            Pexp_constant PConst_int (42,None)
     core_type
       Ptyp_constr "int"
       []
-    <inline const>
+    "#rescript-inline"

AST modified (an external with a relative path after the built-in PPX)

@module("./local") external relative: int => int = "relative"

expanded

 structure_item
-  Pstr_include
-  module_expr
-    Pmod_constraint
-    module_expr
-      Pmod_structure
-        structure_item
-          Pstr_primitive
-          value_description "relative"
-            attribute  "module"
-              …
-            core_type
-              …
-            "relative"
-    module_type
-      Pmty_signature
-        signature_item
-          Psig_value
-          value_description "relative"
-            core_type
-              …
+  Pstr_primitive
+  value_description "relative"
+    attribute  "module"
+      …
+    core_type
+      …
+    "relative"

Typedtree modified (an external with a relative path)

@module("./local") external relative: int => int = "relative"

typed · Before: the constraint the built-in PPX wrote · After: the constraint Typemod adds, implicit

 structure_item
   Tstr_include
   module_expr
-    Tmod_constraint
     module_expr
       Tmod_structure
         structure_item
           Tstr_primitive
           value_description relative/1001
             …
             "relative"
-    module_type
-      Tmty_signature
-        signature_item
-          Tsig_value
-          value_description relative/1002
-            …

Typedtree modified (externals)

type t
@send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
@inline let answer = 42

typed

 …
 structure_item
   Tstr_primitive
   value_description on/1002
     core_type
       Ttyp_arrow
       …
     "addEventListener"
-    <ffi spec>
 structure_item
   Tstr_primitive
   value_description answer/1003
     core_type
       Ttyp_constr "int/1"
       []
-    <inline const>
+    "#rescript-inline"

Diagnostic modified (unused attribute on a relative @module external)

@module("./local") external relative: @as("v") int => unit = "relative"

diagnostic

 Warning number 101
 A.res:1:39-41
 Unused attribute: @as
-
-Warning number 101
-A.res:1:39-41
-Unused attribute: @as

Diagnostic removed (unused attribute under a @warning that disables it)

@warning("-101") @module("./local")
external silenced: @as("w") int => unit = "silenced"

diagnostic · Before

Warning number 101
A.res:2:21-23
Unused attribute: @as

Diagnostic removed (unused attribute after a @@warning that disables it)

@send external first: (string, @as("x") int) => unit = "first"
@@warning("-101")
@send external second: (string, @as("y") int) => unit = "second"

diagnostic

 Warning number 101
 A.res:1:32-34
 Unused attribute: @as
-
-Warning number 101
-A.res:3:33-35
-Unused attribute: @as

Diagnostic added (an external that names the inline-constant primitive)

external answer: int = "#rescript-inline"

diagnostic · After

"#rescript-inline" is reserved for @inline constants

JS modified (@inline let with a bigint)

@inline let big = 10n
let use = () => big

js

 function use() {
   return 10n;
 }
-let big = 10n;
-exports.big = big;
 exports.use = use;

Diagnostic removed (@inline on a bigint let)

@inline let big = 10n

diagnostic · Before

Warning number 53
the @inline attribute cannot appear in this context

Review

  • How does an external with a relative path stay out of other modules? Its path is relative to the file that declares it, so other modules call the value its module exports. In a signature, Typedecl gives it Val_reg. In a structure, Typemod types it as include (struct external … end : {let …}), the wrapper the built-in PPX used to write, whose coercion (Tcoerce_primitive) emits the exported function. Primitive.no_cross_module_inline reads relativeness off the resolved spec (External_ffi_types.is_relative, split out of check_decl).
  • Why a hook rather than passing the result along? -bs-ast writes the parsetree after the built-in PPX and a later bsc process reads it back, so the specification has to be recomputable from the tree. Ppx_entry, which every compiler driver links, registers the resolver at module initialization, as the Oprint hooks are.
  • What do diagnostics look like now? An external's errors and warning 101 come during type checking, in source order with the type errors, instead of in the parse step; an earlier type error hides them until it is fixed. The reprint path and -bs-ast alone no longer report them.
  • Is each external resolved once? Yes, except in a recursive module's signature, which the type checker types twice, the first time with warnings off, so its diagnostics come once.
  • What does this cost? Each external is resolved in the compile step, which reads it as written, attributes and all. The unused-attribute walk on the resolved form is skipped unless it checks one of the attributes, which is the common case. Parse and compile steps together allocate 0.65% fewer words than before on Stdlib_Math.resi, 0.39% more on Stdlib_Math.res, and 1.4% more on Stdlib_Symbol.res, a small file of @val @scope(...) constants.
  • What is "#rescript-inline"? The primitive of an @inline constant's declaration, which keeps its @inline(<literal>) attribute; the resolver turns it into Kind_inline_const. A structural form is a separate Stamp parsetree v1: what remains before the AST can be frozen for PPXs #8624 item.
  • Do PPXs see a difference? No: they run before the built-in PPX, and the v0 bridge carries the string as before; its error branch for already-resolved externals is gone.
  • What changes under -bs-no-builtin-ppx? An external with a plain name is now resolved as an FFI external by the type checker; before, it was typed as an intrinsic of that name.
  • What else goes? Typedtree.val_prim, a copy of the primitive string whose readers only need the value's resolved kind, and Primitive.print: Outcometree.oval_prim is the Primitive.description itself.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

⚠️ Compiler benchmarks

Allocated words

In total: 640,953,118 → 640,828,139 (-0.02%).

Generated projects: 920,898,058 → 920,898,825 (±0.00%).

⚠️ Regression: 1 benchmark allocates more than 1% more.

Benchmark Base Head Change
packages/@rescript/runtime/Stdlib_Symbol.res 144,093 146,153 +1.43%
packages/@rescript/runtime/Stdlib_Object.res 244,958 247,112 +0.88%
packages/@rescript/runtime/Stdlib_Console.resi 414,802 411,754 -0.73%
packages/@rescript/runtime/Stdlib_Date.resi 618,515 613,972 -0.73%
packages/@rescript/runtime/Stdlib_Math.resi 330,668 328,455 -0.67%
packages/@rescript/runtime/Stdlib_DataView.resi 269,452 267,737 -0.64%
packages/@rescript/runtime/Stdlib_String.resi 500,056 497,237 -0.56%
packages/@rescript/runtime/Stdlib_Array.resi 731,799 728,370 -0.47%
packages/@rescript/runtime/Stdlib_Set.resi 229,602 228,644 -0.42%
packages/@rescript/runtime/Stdlib_Promise.resi 357,183 355,752 -0.40%
46 more changes
Benchmark Base Head Change
packages/@rescript/runtime/Stdlib_Temporal_ZonedDateTime.res 572,213 574,425 +0.39%
packages/@rescript/runtime/Stdlib_Map.resi 217,646 216,817 -0.38%
packages/@rescript/runtime/Stdlib_IteratorObject.resi 235,063 234,185 -0.37%
packages/@rescript/runtime/Stdlib_Temporal_PlainDateTime.res 436,952 438,473 +0.35%
packages/@rescript/runtime/Stdlib_Math.res 326,844 327,968 +0.34%
packages/@rescript/runtime/Stdlib_Temporal_PlainDate.res 402,875 404,153 +0.32%
packages/@rescript/runtime/Stdlib_RegExp.res 162,824 163,321 +0.31%
packages/@rescript/runtime/Stdlib_TypedArray.res 782,668 785,036 +0.30%
packages/@rescript/runtime/Stdlib_Temporal_Duration.res 372,680 373,786 +0.30%
packages/@rescript/runtime/Stdlib_Global.resi 155,748 155,286 -0.30%
packages/@rescript/runtime/Stdlib_Ordering.res 152,140 152,589 +0.30%
packages/@rescript/runtime/Dom_storage2.res 119,500 119,846 +0.29%
packages/@rescript/runtime/Stdlib_Intl_Locale.res 197,104 197,655 +0.28%
packages/@rescript/runtime/Stdlib_RegExp.resi 188,008 187,488 -0.28%
packages/@rescript/runtime/JsxEvent.res 1,088,126 1,091,106 +0.27%
packages/@rescript/runtime/Stdlib_Temporal_PlainYearMonth.res 381,518 382,521 +0.26%
packages/@rescript/runtime/Stdlib_Promise.res 351,730 352,597 +0.25%
packages/@rescript/runtime/Stdlib_Float.res 218,563 219,089 +0.24%
packages/@rescript/runtime/Stdlib_Temporal_PlainTime.res 319,810 320,526 +0.22%
packages/@rescript/runtime/Pervasives.res 238,946 239,469 +0.22%
packages/@rescript/runtime/Stdlib_Temporal_Now.res 142,914 143,212 +0.21%
packages/@rescript/runtime/Stdlib_Temporal_Instant.res 307,218 307,857 +0.21%
packages/@rescript/runtime/Dom_storage.res 166,901 167,248 +0.21%
packages/@rescript/runtime/Stdlib_JsError.resi 185,017 184,667 -0.19%
packages/@rescript/runtime/Stdlib_Dict.res 319,618 320,198 +0.18%
packages/@rescript/runtime/Stdlib_Dict.resi 241,025 240,597 -0.18%
packages/@rescript/runtime/Stdlib_Float.resi 194,410 194,076 -0.17%
packages/@rescript/runtime/Stdlib_Temporal_PlainMonthDay.res 268,042 268,461 +0.16%
packages/@rescript/runtime/Stdlib_WeakSet.res 122,602 122,783 +0.15%
packages/@rescript/runtime/Stdlib_Nullable.resi 199,645 199,919 +0.14%
packages/@rescript/runtime/RescriptTools.res 104,127 104,260 +0.13%
packages/@rescript/runtime/Primitive_object_extern.res 114,249 114,393 +0.13%
packages/@rescript/runtime/Stdlib_WeakMap.res 134,943 135,113 +0.13%
packages/@rescript/belt/src/Belt_Int.res 165,430 165,630 +0.12%
packages/@rescript/runtime/Stdlib_Console.res 369,774 370,218 +0.12%
packages/@rescript/runtime/Stdlib_Null.resi 204,329 204,574 +0.12%
packages/@rescript/runtime/Stdlib_Intl_NumberFormat.res 403,726 404,207 +0.12%
packages/@rescript/runtime/Stdlib_BigInt.res 206,835 207,079 +0.12%
packages/@rescript/runtime/Stdlib_Intl_PluralRules.res 201,187 201,422 +0.12%
packages/@rescript/runtime/Stdlib_Bool.resi 116,439 116,567 +0.11%
packages/@rescript/runtime/Stdlib_Int.res 457,244 457,736 +0.11%
packages/@rescript/runtime/Stdlib_Intl_Segments.res 116,128 116,252 +0.11%
packages/@rescript/belt/src/Belt_Float.resi 150,850 151,011 +0.11%
packages/@rescript/belt/src/Belt_Int.resi 149,374 149,531 +0.11%
packages/@rescript/runtime/Stdlib_String.res 504,429 504,947 +0.10%
packages/@rescript/runtime/Stdlib_Intl_Segmenter.res 153,928 154,086 +0.10%

Instructions

In total: 9,209,714,214 → 9,212,707,712 (+0.03%).

Benchmark Base Head Change
packages/@rescript/runtime/Stdlib_Math.resi 21,221,638 21,419,852 +0.93%
packages/@rescript/runtime/Stdlib_Temporal_ZonedDateTime.res 31,091,935 31,323,311 +0.74%
packages/@rescript/runtime/Stdlib_TypedArray.res 41,141,872 41,435,088 +0.71%
packages/@rescript/runtime/Stdlib_Temporal_PlainDate.res 24,023,929 24,191,589 +0.70%
packages/@rescript/runtime/Stdlib_Date.resi 34,160,689 34,394,144 +0.68%
packages/@rescript/runtime/Stdlib_Temporal_PlainDateTime.res 25,458,858 25,632,740 +0.68%
packages/@rescript/runtime/Stdlib_String.resi 29,383,596 29,575,904 +0.65%
packages/@rescript/runtime/Stdlib_Array.resi 39,993,449 40,228,166 +0.59%
packages/@rescript/runtime/Stdlib_List.resi 24,554,458 24,637,942 +0.34%
parse/RedBlackTreeNoComments.res 14,518,349 14,555,058 +0.25%
5 more changes
Benchmark Base Head Change
parse/RedBlackTree.res 14,921,007 14,958,301 +0.25%
packages/@rescript/belt/src/Belt_Array.resi 33,741,503 33,820,743 +0.23%
packages/@rescript/belt/src/Belt_List.resi 39,012,206 39,093,314 +0.21%
format/RedBlackTreeNoComments.res 24,092,449 24,133,223 +0.17%
format/RedBlackTree.res 24,437,510 24,478,284 +0.17%

Output size

In total: 25,843,406 → 25,817,284 (-0.10%).

🎉 Improvement: 1 output is more than 1% smaller.

Benchmark Base Head Change
output/tests/*.cmti 176,053 173,922 -1.21%
output/runtime/*.cmti 1,118,869 1,115,134 -0.33%
output/runtime/*.cmt 3,044,137 3,035,903 -0.27%
output/belt/*.cmti 981,298 980,059 -0.13%

Pull request 4114973 compared with base 1efa212 in this run.

@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch 2 times, most recently from 282e6dd to 85671c0 Compare November 10, 2026 19:28
@cknitt

cknitt commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-10T20:35:30.698807Z 85671c0 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 85671c0d59

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Why:
    The parsetree is what PPXs see and what `-bs-ast` serializes, and
    #8624 wants it to describe source only. After the built-in PPX had
    read an external's `@send`, `@module`, `@as`… attributes, it replaced
    the primitive string with the computed FFI specification
    (`Prim_ffi`, `Prim_inline_const`), so `Parsetree` depended on
    `External_ffi_types` and carried cases no PPX can observe. Now
    `pval_prim` is the string as written (`string option`), and
    `Typedecl` resolves the attributes through
    `Primitive.resolve_external`, a hook the frontend registers since the
    resolver lives above `compiler/ml`. The frontend no longer resolves them
    as well. The resolver also reports the
    external's errors and warnings, inside the declaration's `@warning`
    scope, and after any `@@warning` above it in the file. The generated
    JavaScript is unchanged.

AST modified (externals after the built-in PPX):
Example:
    type t
    @send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
    @inline let answer = 42
Before (expanded):
    …
    structure_item
      Pstr_primitive
      value_description "on"
        core_type
          Ptyp_arrow
          arity = 2
          Nolabel
          core_type
            Ptyp_constr "t"
            []
          Nolabel
          core_type
            Ptyp_arrow
            …
          core_type
            Ptyp_constr "unit"
            []
        "addEventListener"
        <ffi spec>
    structure_item
      Pstr_primitive
      value_description "answer"
        core_type
          Ptyp_constr "int"
          []
        <inline const>
After (expanded):
    …
    structure_item
      Pstr_primitive
      value_description "on"
        attribute  "send"
          []
        core_type
          Ptyp_arrow
          arity = 3
          Nolabel
          core_type
            Ptyp_constr "t"
            []
          Nolabel
          Parg_fixed
            value
              Pfixed_string (source="click", semantic="click")
          Nolabel
          core_type
            Ptyp_arrow
            …
          core_type
            Ptyp_constr "unit"
            []
        "addEventListener"
    structure_item
      Pstr_primitive
      value_description "answer"
        attribute  "inline"
          [
            structure_item
              Pstr_eval
              expression
                Pexp_constant PConst_int (42,None)
          ]
        core_type
          Ptyp_constr "int"
          []
        "#rescript-inline"

AST modified (an external with a relative path after the built-in PPX):
Example:
    @module("./local") external relative: int => int = "relative"
Before (expanded):
    structure_item
      Pstr_include
      module_expr
        Pmod_constraint
        module_expr
          Pmod_structure
          [
            structure_item
              Pstr_primitive
              value_description "relative"
                attribute  "module"
                  …
                core_type
                  …
                "relative"
          ]
        module_type
          Pmty_signature
          [
            signature_item
              Psig_value
              value_description "relative"
                core_type
                  …
          ]
After (expanded):
    structure_item
      Pstr_primitive
      value_description "relative"
        attribute  "module"
          …
        core_type
          …
        "relative"

Typedtree modified (an external with a relative path):
Example:
    @module("./local") external relative: int => int = "relative"
Before (typed): the constraint the built-in PPX wrote
    structure_item
      Tstr_include
      module_expr
        Tmod_constraint
        module_expr
          Tmod_structure
          [
            structure_item
              Tstr_primitive
              value_description relative/1001
                …
                "relative"
          ]
        module_type
          Tmty_signature
          [
            signature_item
              Tsig_value
              value_description relative/1002
                …
          ]
After (typed): the constraint Typemod adds, implicit
    structure_item
      Tstr_include
      module_expr
        module_expr
          Tmod_structure
          [
            structure_item
              Tstr_primitive
              value_description relative/1001
                …
                "relative"
          ]

Typedtree modified (externals):
Example:
    type t
    @send external on: (t, @as("click") _, unit => unit) => unit = "addEventListener"
    @inline let answer = 42
Before (typed):
    …
    structure_item
      Tstr_primitive
      value_description on/1002
        core_type
          Ttyp_arrow
          …
        "addEventListener"
        <ffi spec>
    structure_item
      Tstr_primitive
      value_description answer/1003
        core_type
          Ttyp_constr "int/1"
          []
        <inline const>
After (typed):
    …
    structure_item
      Tstr_primitive
      value_description on/1002
        core_type
          Ttyp_arrow
          …
        "addEventListener"
    structure_item
      Tstr_primitive
      value_description answer/1003
        core_type
          Ttyp_constr "int/1"
          []
        "#rescript-inline"

Diagnostic modified (unused attribute on a relative @module external):
Example:
    @module("./local") external relative: @as("v") int => unit = "relative"
Before (diagnostic):
    Warning number 101
    A.res:1:39-41
    Unused attribute: @as

    Warning number 101
    A.res:1:39-41
    Unused attribute: @as
After (diagnostic):
    Warning number 101
    A.res:1:39-41
    Unused attribute: @as

Diagnostic removed (unused attribute under a @warning that disables it):
Example:
    @warning("-101") @module("./local")
    external silenced: @as("w") int => unit = "silenced"
Before (diagnostic):
    Warning number 101
    A.res:2:21-23
    Unused attribute: @as

Diagnostic removed (unused attribute after a @@warning that disables it):
Example:
    @send external first: (string, @as("x") int) => unit = "first"
    @@warning("-101")
    @send external second: (string, @as("y") int) => unit = "second"
Before (diagnostic):
    Warning number 101
    A.res:1:32-34
    Unused attribute: @as

    Warning number 101
    A.res:3:33-35
    Unused attribute: @as
After (diagnostic):
    Warning number 101
    A.res:1:32-34
    Unused attribute: @as

Diagnostic added (an external that names the inline-constant primitive):
Example:
    external answer: int = "#rescript-inline"
After (diagnostic):
    "#rescript-inline" is reserved for @inline constants

JS modified (@inline let with a bigint):
Example:
    @inline let big = 10n
    let use = () => big
Before (js):
    function use() {
      return 10n;
    }
    let big = 10n;
    exports.big = big;
    exports.use = use;
After (js):
    function use() {
      return 10n;
    }
    exports.use = use;

Diagnostic removed (@inline on a bigint let):
Example:
    @inline let big = 10n
Before (diagnostic):
    Warning number 53
    the @inline attribute cannot appear in this context

Review: How does an external with a relative path stay out of other
    modules? Its path is relative to the file that declares it, so other
    modules call the value its module exports. In a signature, `Typedecl`
    gives it `Val_reg`. In a structure, `Typemod` types it as
    `include (struct external … end : {let …})`, the wrapper the built-in
    PPX used to write, whose coercion (`Tcoerce_primitive`) emits the
    exported function. `Primitive.no_cross_module_inline` reads
    relativeness off the resolved spec (`External_ffi_types.is_relative`,
    split out of `check_decl`).
Review: Why a hook rather than passing the result along? `-bs-ast` writes
    the parsetree after the built-in PPX and a later `bsc` process reads
    it back, so the specification has to be recomputable from the tree.
    `Ppx_entry`, which every compiler driver links, registers the resolver
    at module initialization, as the `Oprint` hooks are.
Review: What do diagnostics look like now? An external's errors and
    warning 101 come during type checking, in source order with the type
    errors, instead of in the parse step; an earlier type error hides
    them until it is fixed. The reprint path and `-bs-ast` alone no longer
    report them.
Review: Is each external resolved once? Yes, except in a recursive
    module's signature, which the type checker types twice, the first time
    with warnings off, so its diagnostics come once.
Review: What does this cost? Each external is resolved in the compile
    step, which reads it as written, attributes and all. The
    unused-attribute walk on the resolved form is skipped unless it checks
    one of the attributes, which is the common case. Parse and compile
    steps together allocate 0.65% fewer words than before on
    Stdlib_Math.resi, 0.39% more on Stdlib_Math.res, and 1.4% more on
    Stdlib_Symbol.res, a small file of `@val @scope(...)` constants.
Review: What is `"#rescript-inline"`? The primitive of an `@inline`
    constant's declaration, which keeps its `@inline(<literal>)`
    attribute; the resolver turns it into `Kind_inline_const`. A
    structural form is a separate #8624 item.
Review: Do PPXs see a difference? No: they run before the built-in PPX,
    and the v0 bridge carries the string as before; its error branch for
    already-resolved externals is gone.
Review: What changes under `-bs-no-builtin-ppx`? An external with a plain
    name is now resolved as an FFI external by the type checker; before,
    it was typed as an intrinsic of that name.
Review: What else goes? `Typedtree.val_prim`, a copy of the primitive
    string whose readers only need the value's resolved kind, and
    `Primitive.print`: `Outcometree.oval_prim` is the
    `Primitive.description` itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018oLiCQjGFSE2qwfYqCMF9e
Claude-Session: https://claude.ai/code/session_01Kbf3gLpf7RN1MiRcubPgRn
Claude-Session: https://claude.ai/code/session_01Kbf3gJFAva9685fjvkajub
Claude-Session: https://claude.ai/code/session_01Kbf3gGqcYiyMeZgs8UzT5G
Signed-off-by: Christoph Knittel <ck@cca.io>
@cknitt
cknitt force-pushed the codex/resolve-external-in-typedecl branch from c3bf716 to 4114973 Compare November 14, 2026 08:53
@cknitt
cknitt marked this pull request as ready for review November 14, 2026 09:17
@cknitt
cknitt requested a review from cristianoc November 14, 2026 09:17

@cristianoc cristianoc left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sweet

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.

2 participants