[cknitt]

Supersedes #222. (The CI fix it was stacked on, #223, is merged.)

Running DCE over the ReScript compiler's OCaml sources (OCaml 5.5.2, dune, native and browser profiles) produced several kinds of wrong reports. This PR fixes them. With it, the compiler's codebase analyzes to 0 findings (rescript-lang/rescript#9173, make dead-code).

Fixes

Each item: the wrong report, then its cause and the fix.

1. Exceptions "never raised" on macOS/Windows. raise (Lib.Mod.Exn ...) from another module of a dune wrapped library didn't count.
Cause: sibling .cmt files are probed as both Unit.cmt and unit.cmt. On a case-insensitive file system both exist, so one file showed up under two paths and the lookup gave up as "ambiguous".
Fix: a probed sibling must exist under its exact name.

2. Type re-exports.

type t = Orig.t = A | B      (* or: module Child = Orig  type t = Child.t = A | B *)

Building Reexp.A left Orig.A "never constructed"; reading x.field on Orig.t left the re-export's label "never read".
Fix: the re-exported declaration is resolved through shapes (OCaml ≥ 5.3), and same-named constructors and labels are linked both ways. A link applies only when both ends are declarations of the analysis, so re-exporting a stdlib type (type 'a node = 'a Seq.node = Nil | Cons …) doesn't make its constructors live. This also works when the path goes through a local module alias, whose shape carries no uid, so the alias target is followed.

3. Types in a submodule of an interface.

module Color : sig type setting = Auto | Never end   (* in an .mli *)

The constructors were registered as setting.Auto instead of Color.setting.Auto, so they never matched the .ml, and the implementation's constructors looked unused.
Fix: signature traversal passes the submodule path to type declarations.

4. Analyzing two build trees together. Needed so that a use in only one configuration counts, e.g. the ReScript playground, which only exists in the browser profile.

• Dune writes source paths relative to the build root (and normalizes cmt_builddir). Generated sources that exist only in a build tree were skipped. They're now also looked up in the directories above the .cmt, and reports and -write read them from there.
• A module compiled from the same source in both trees has two copies of its .cmt, which was treated as ambiguous. Now the copy in the consumer's own build tree is used (strictly closest path). Ties, and copies of different sources, stay ambiguous as before.
• Declarations are identified by source position, so two trees holding different files under one name (e.g. a per-platform file copied to the same name) can't be told apart. That case is now detected and warned about on stderr (with a hint to use dune's copy#), instead of silently merging their declarations. A file that is also found from the current directory is compared with each tree's copy too; a difference there means the build is out of date, and the warning says so.
• Each .cmt is parsed once and shared. On the ReScript compiler with two trees, peak memory goes from 5.0 GB to 1.65 GB.

5. Optional arguments "never used" or "always supplied" by mistake.

• let assert_equal = OUnit.assert_equal: an alias or partial application was reported for optional parameters it can't drop. A binding whose body is an identifier or an application of one is now an alias when its optional parameters are exactly those the applied function leaves (its declared type after the applied arguments, skipped optional ones included). So let g = wrap f with wrap : ?x:_ -> 'a -> 'a is not an alias of wrap: its ?x comes from f. let g = f is always an alias, also with a constraint naming its type (let g : fn = f), and so is a nested application (let p = 1 |> f ~x:1, typed as (f ~x:1) 1). That holds also when it's exported through an .mli. A function body (including let f = let y = … in fun ?x -> …) owns its optional parameters as before; any other application owns none, so calls through it are never "always supplied" for it, and a function among its arguments that has all of them (f in wrap f) may receive them. Each call through a partial application that is an alias is a call of the function with the arguments the application passes (let p = f ~x:1); the application itself counts as a call only when nothing calls through p.
• let lookup_value = lookup proj1 proj2: calls through an alias now count for the function it stands for. Aliases are resolved before calls are attributed to implementations, so this also works for values of modules constrained by a signature.
• find_component Env.lookup_type, where find_component (lookup : ?loc:_ -> _) calls lookup ~loc: a function passed as an argument to a parameter that the callee declares as a function with optional parameters, or as a named type (type lookup = ?loc:int -> int -> int), now counts them as possibly supplied. Passing it to a parameter of type 'a (ignore f, ref f) or storing it in a list supplies nothing, as the existing Unused_import.Victim test expects.
• OptionalArgs.empty was a single mutable record shared by every function without optional parameters, so a call through one of them changed the state of all of them (spurious "always supplied" reports). It is now created fresh each time.
• type fn = ?x:int -> unit -> int: calls through a value whose type is such an abbreviation were not recorded (the callee's type shows no labels), and a val f : fn in an interface hid all reports for the implementation. Calls are now recorded by their own optional labels, and such an interface item stands for the implementation. On the ReScript compiler this finds a real one: Ast_literal.type_bool's ?loc is never passed.

Known limits, documented in Changes.md: an alias that escapes (ignore p) counts as not called through, so with a chained alias the arguments only the chain passes are reported as always supplied; an alias needs the applied function to be an identifier (let q = (fun x -> x) p does not stand for p, though p may receive what calls through q pass); a function passed directly to a callee that is not an identifier is not credited; and calls through an alias of a functor parameter's value count for every implementation of the parameter's signature.

New tests

In examples/regression, with assertions in scripts/run_integration_tests.js:

• Type_reexport*: re-exports through another module and through a local alias. The assertions are gated on OCaml ≥ 5.3.
• Nested_sig_type*: types in an .mli submodule.
• Type_reexport_stdlib: a re-export of a type outside the analysis.
• Optional_arg_alias, Optional_arg_iface*, Optional_arg_passed*, Optional_arg_more: aliases (also through an .mli and of signature-constrained values), partial applications (also skipping an optional parameter, and passing one that is then always supplied), wrapped functions (wrap f, (fun h -> h) f, and an unrelated argument that stays reported), a partial application nobody calls through (also of a signature-constrained value, and an uncalled chain counting once), an operand starting where the alias's application starts (h ~y:2 1 |> mk), a pipe into a partial application (1 |> f ~x:1), functions passed as arguments (also to a named function type), and the cases that must stay reported (let … in fun, ignore f, ref f, a label that only shares a name with the applied function's).
• Optional_arg_abbrev*: an interface naming a function's type with an abbreviation; Optional_arg_more also has a constrained alias.

New script test scripts/test_build_trees.js: one library built in two trees, each with its own generated module, analyzed together. It also checks the warning for the differing generated file, also when a copy is in the current directory.

Each assertion fails without its fix (checked against 6309f4b and with the closest-copy rule disabled). Unused declarations in the same fixtures are still reported.

Fix 1 has no automated test: CI is Linux-only, and a case-insensitive file system can't be simulated there. On a macOS-backed mount, a wrapped-library repro went from 4 wrong "never raised" reports to 0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kbf3gLDo8mBJKpNE25WAwT

[cristianoc]

Approving, with one possible follow-up gap in optional-argument alias tracking:

type fn = ?x:int -> unit -> int
let plain ?x () = match x with Some x -> x | None -> 0
let first : fn = plain
let second = first
let () = print_int (second ~x:1 ())

In DeadValue.ml, the Texp_ident branch registers an alias only when hasOptionalArgs vd.val_type succeeds, but that helper does not expand Tconstr. If first retains the abbreviated type fn, the second -> first link appears to be missed, potentially leaving plain's x reported as never used. Aliasing a value exported as val f : fn may have the same issue.

This is a source-level trace, not an executed reproduction. A regression test combining the abbreviated type with a second alias would help confirm it. Not blocking approval.

[cknitt]

Thanks! Both cases reproduced (let second = first with first : fn, and an alias of a val f : fn export): x was reported as never used. Fixed in b2e4306: a binding that is just an identifier is now always an alias, whatever its type shows (an alias of a value without optional parameters receives none, so it changes nothing). Fixtures for both cases were added, and they fail on the previous commit.