Name each IR dump after the pass that produced it

The -debug-ir labels had drifted from the sequence they describe. "initial"
was dumped after collapse_var_aliases rather than before it, "flatten1"
and "before-simplify-exits" each dumped a term already dumped under
another name, "simplify_alias_before" named the pass that came next
rather than the one that had run, and the output of guard_raises was
labelled simplify_lets. Every dump is now named after the pass whose
output it holds, and the three rounds of deep_flatten, simplify_alias
and simplify_exits are numbered so a dump can be placed in the sequence.

The initial dump now happens before collapse_var_aliases, so it is the
term the pipeline was handed.

Removed the commented-out scc pass with its dump label, and the
commented-out collect_info and simplify_alias that followed sroa.

The area guide linked to lam_convert.ml, which no longer exists, and said
six constructors normalize as they build. There are seven: apply, prim,
switch, stringswitch, if_, seq and not_. It now also carries the pass
sequence as a table, with which statistics each pass consumes: only
simplify_alias reads them, and a fresh collect_info runs immediately
before each of its three rounds.

Signed-off-by: Cristiano Calcagno <ccrisccris@gmail.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W8g8qwBARAcvW9MyuKQq8H

Author: cristianoc

CHANGELOG.md

@@ -76,6 +76,7 @@
 - Split `lambda.ml` into the IR and its traversals, static exits and path translation, so the module defining `Lambda.t` no longer reaches into `Env`, `Path` or `Parsetree`. https://github.com/rescript-lang/rescript/pull/8618
 - Record a record field's `@as` rename on the declaration instead of re-reading the attribute, so every place that needs the runtime name reads one field. https://github.com/rescript-lang/rescript/pull/8619
 - Record a variant constructor's `@as` tag on the declaration instead of re-interpreting its attributes, keeping the source spelling for printing. https://github.com/rescript-lang/rescript/pull/8619
+- Optimization passes now return the term they were given when they change nothing, rather than rebuilding an identical one. https://github.com/rescript-lang/rescript/pull/8620
 - Merge the duplicate Lam intermediate representation into Lambda, removing the conversion layer and obsolete supporting infrastructure. Lambda is now a single private, normalized representation, with generated JavaScript remaining semantically unchanged. https://github.com/rescript-lang/rescript/pull/8608
 - Rework the object-type representation end to end: object rows are plain field chains carrying a per-field mutability state (no phantom setter members), object literals are typed directly and property access and assignment are first-class AST and Lambda nodes shared between the Lambda and JS pipelines, and dead class-system remnants (the field-presence lattice, the class-abbreviation memo on object types, method-send typing) are removed. https://github.com/rescript-lang/rescript/pull/8597
 - Upgrade the development toolchain and primary CI builds to OCaml 5.5 while retaining OCaml 5.0 as the minimum supported version. https://github.com/rescript-lang/rescript/pull/8589

compiler/core/README.md

@@ -10,15 +10,37 @@ Typedtree translation in `compiler/ml/translcore.ml` and
 `compiler/ml/translmod.ml` produces the `Lambda` representation defined in
 `compiler/ml/lambda.mli`.
 
-[`lam_convert.ml`](lam_convert.ml)
-: Collects the modules a compilation unit depends on, read off the Lambda
-  term.
-
 `lam_pass_*.ml` and the other `lam_*.ml` modules
 : Analyze and transform Lambda. [`lam_compile_main.ml`](lam_compile_main.ml)
   coordinates the backend pass sequence; read it before inserting or
   reordering a pass.
 
+  The sequence is hand-unrolled rather than iterated to a fixed point. Only
+  `simplify_alias` reads the statistics, and a fresh `collect_info` runs
+  immediately before each of its three rounds. `simplify_lets` and `sroa`
+  compute what they need themselves. Each `-debug-ir` dump is named after the
+  pass whose output it holds.
+
+  | # | pass | statistics |
+  |---|---|---|
+  | 1 | `collapse_var_aliases` | |
+  | 2 | `deep_flatten` | |
+  | 3 | `simplify_exits` | |
+  | 4 | `simplify_alias` | reads a snapshot taken just before |
+  | 5 | `deep_flatten` | |
+  | 6 | `simplify_alias` | reads a snapshot taken just before |
+  | 7 | `deep_flatten` | |
+  | 8 | `simplify_exits` | |
+  | 9 | `simplify_alias` | reads a snapshot taken just before |
+  | 10 | `simplify_lets` | own occurrence count |
+  | 11 | `sroa` | own field-use classification |
+  | 12 | `simplify_exits` | |
+  | 13 | `guard_raises` | |
+
+  A snapshot is fresh when its pass starts, but `simplify_alias` also mutates
+  the table as it rewrites, so entries can describe an earlier version of the
+  term by the time the pass finishes.
+
 [`lam_compile.ml`](lam_compile.ml)
 : Lowers Lambda to JavaScript IR. Primitive-specific and FFI lowering is split
   into `lam_compile_primitive.ml`, `lam_compile_external_call.ml`, and related
@@ -35,7 +57,8 @@ Typedtree translation in `compiler/ml/translcore.ml` and
 ## Changing a representation
 
 `Lambda.t` is private: every term is built through the constructors in
-[`../ml/lambda.mli`](../ml/lambda.mli), six of which normalize as they build.
+[`../ml/lambda.mli`](../ml/lambda.mli), seven of which normalize as they
+build: `apply`, `prim`, `switch`, `stringswitch`, `if_`, `seq` and `not_`.
 A constructor may replace a node with an equivalent one, but may not move code
 between branches - that is what a pass is for. When adding or changing a
 constructor, search every producer, traversal, optimizer, printer, serializer,

compiler/core/lam_compile_main.ml

@@ -290,48 +290,44 @@ let compile (output_prefix : string) export_idents hoisted (lam : Lambda.t) =
     Lam_compile_env.reset ()
   in
   let may_required_modules = required_modules lam in
+  let lam = d "initial" lam in
   let lam =
     Lam_pass_collapse_var_aliases.collapse ~exports:export_ident_sets lam
   in
-
-  let lam = d "initial" lam in
+  let lam = d "collapse_var_aliases" lam in
   let lam = Lam_pass_deep_flatten.deep_flatten lam in
-  let lam = d "flatten0" lam in
+  let lam = d "deep_flatten 1" lam in
   let meta : Lam_stats.t = Lam_stats.make ~export_idents ~export_ident_sets in
   let lam =
     let lam =
-      lam |> d "flatten1" |> Lam_pass_exits.simplify_exits |> d "simplify_exits"
+      lam |> Lam_pass_exits.simplify_exits |> d "simplify_exits 1"
       |> (fun lam ->
       Lam_pass_collect.collect_info meta lam;
       if debug_ir then
         Ext_log.dwarn ~__POS__ "Before simplify_alias: %a@." Lam_stats.print
           meta;
       lam)
       |> Lam_pass_remove_alias.simplify_alias meta
-      |> d "simplify_alias" |> Lam_pass_deep_flatten.deep_flatten
-      |> d "flatten2"
+      |> d "simplify_alias 1" |> Lam_pass_deep_flatten.deep_flatten
+      |> d "deep_flatten 2"
     in
-    (* Inling happens*)
-
+    (* Inlining happens *)
     let () = Lam_pass_collect.collect_info meta lam in
     let lam = Lam_pass_remove_alias.simplify_alias meta lam in
+    let lam = d "simplify_alias 2" lam in
     let lam = Lam_pass_deep_flatten.deep_flatten lam in
+    let lam = d "deep_flatten 3" lam in
     let lam = lam |> Lam_pass_exits.simplify_exits in
     let () = Lam_pass_collect.collect_info meta lam in
 
-    lam |> d "simplify_alias_before"
+    lam |> d "simplify_exits 2"
     |> Lam_pass_remove_alias.simplify_alias meta
-    |> d "before-simplify_lets"
+    |> d "simplify_alias 3"
     (* we should investigate a better way to put different passes : )*)
     |> Lam_pass_lets_dce.simplify_lets
     |> d "simplify_lets" |> Lam_pass_sroa.simplify |> d "sroa"
-    |> d "before-simplify-exits"
-    (* |> (fun lam -> Lam_pass_collect.collect_info meta lam
-       ; Lam_pass_remove_alias.simplify_alias meta lam) *)
-    (* |> Lam_group_pass.scc_pass
-       |> d "scc" *)
-    |> Lam_pass_exits.simplify_exits
-    |> Lam_pass_guard_raises.guard_raises |> d "simplify_lets"
+    |> Lam_pass_exits.simplify_exits |> d "simplify_exits 3"
+    |> Lam_pass_guard_raises.guard_raises |> d "guard_raises"
     |> fun lam ->
     if debug_ir then
       Ext_log.dwarn ~__POS__ "Before coercion: %a@." Lam_stats.print meta;