refactor(dce): extract configuration into explicit value (Task 2)

Replace global config reads with explicit ~config parameter threading
throughout the DCE analysis pipeline. This makes the analysis pure
and testable with different configurations.

## Changes

### New module
- DceConfig: Encapsulates DCE configuration (cli + run config)
  - DceConfig.current() captures global state once
  - All analysis functions now take explicit ~config parameter

### DCE Analysis (fully pure - no global reads)
- DeadCode: threads config to all Dead* modules
- DeadValue: replaced ~15 !Cli.debug reads with config.cli.debug
- DeadType: replaced ~7 !Cli.debug reads with config.cli.debug
- DeadOptionalArgs: takes ~config, passes to Log_.warning
- DeadModules: uses config.run.transitive
- DeadCommon: threads config through reporting pipeline
- WriteDeadAnnotations: uses config.cli.write/json
- ProcessDeadAnnotations: uses config.cli.live_names/live_paths

### Logging infrastructure
- Log_.warning: now requires ~config (no optional)
- Log_.logIssue: now requires ~config (no optional)
- Log_.Stats.report: now requires ~config (no optional)
- Consistent API - no conditional logic on Some/None

### Non-DCE analyses (call DceConfig.current() at use sites)
- Exception: 4 call sites updated
- Arnold: 7 call sites updated
- TODO: Thread config through these for full purity

### Other
- Common.ml: removed unused lineAnnotationStr field
- Reanalyze: single DceConfig.current() call at entry point
- DEADCODE_REFACTOR_PLAN.md: updated Task 2, added verification task

## Impact

✅ DCE analysis is now pure - takes explicit config, no global reads
✅ All config parameters required (zero 'config option' types)
✅ Can run analysis with different configs without mutating globals
✅ All tests pass - no regressions

## Remaining Work (Task 2)

- Thread config through Exception/Arnold to eliminate DceConfig.current()
- Verify zero DceConfig.current() calls in analysis code

Signed-off-by: Cursor AI <ai@cursor.com>
Signed-off-by: Cristiano Calcagno <cristianoc@users.noreply.github.com>

Author: cristianoc

AGENTS.md

@@ -44,6 +44,8 @@ The Makefile’s targets build on each other in this order:
 - **Use underscore patterns carefully** - Don't use `_` patterns as lazy placeholders for new language features that then get forgotten. Only use them when you're certain the value should be ignored for that specific case. Ensure all new language features are handled correctly and completely across all compiler layers
 - **Avoid `let _ = …` for side effects** - If you need to call a function only for its side effects, use `ignore expr` (or bind the result and thread state explicitly). Do not write `let _ = expr in ()`, and do not discard stateful results—plumb them through instead.
 
+- **Don't use unit `()` with mandatory labeled arguments** - When a function has a mandatory labeled argument (like `~config`), don't add a trailing `()` parameter. The labeled argument already prevents accidental partial application. Only use `()` when all parameters are optional and you need to force evaluation. Example: `let forceDelayedItems ~config = ...` not `let forceDelayedItems ~config () = ...`
+
 - **Be careful with similar constructor names across different IRs** - Note that `Lam` (Lambda IR) and `Lambda` (typed lambda) have variants with similar constructor names like `Ltrywith`, but they represent different things in different compilation phases.
 
 - **Avoid warning suppressions** - Never use `[@@warning "..."]` to silence warnings. Instead, fix the underlying issue properly

analysis/reanalyze/DEADCODE_REFACTOR_PLAN.md

@@ -149,13 +149,17 @@ Each task should:
 **Value**: Can run analysis with different configs without mutating globals. Can test with different configs.
 
 **Changes**:
-- [ ] Use the `DceConfig.t` already created, thread it through analysis functions
-- [ ] Replace all `!Common.Cli.debug`, `runConfig.transitive`, etc. reads with `config.debug`, `config.run.transitive`
-- [ ] Only `DceConfig.current()` reads globals; everything else uses explicit config
+- [x] ~~Use the `DceConfig.t` already created, thread it through DCE analysis functions~~
+- [x] ~~Replace all DCE code's `!Common.Cli.debug`, `runConfig.transitive`, etc. reads with `config.debug`, `config.run.transitive`~~
+- [x] ~~Make all config parameters required (not optional) - no `config option` anywhere~~
+- [ ] **Thread config through Exception and Arnold analyses** - they currently call `DceConfig.current()` at each use site
+- [ ] **Single entry point**: Only `Reanalyze.runAnalysisAndReport` should call `DceConfig.current()` once, then pass explicit config everywhere
+
+**Status**: DCE code complete ✅. Exception/Arnold still need threading.
 
 **Test**: Create two configs with different settings, run analysis with each - should respect the config, not read globals.
 
-**Estimated effort**: Medium (many small changes across multiple files)
+**Estimated effort**: Medium (DCE done; Exception/Arnold similar effort)
 
 ### Task 3: Make `ProcessDeadAnnotations` state explicit (P3)
 
@@ -253,7 +257,20 @@ Each task should:
 
 **Estimated effort**: Small (single module)
 
-### Task 10: Integration and order-independence verification
+### Task 10: Verify zero `DceConfig.current()` calls in analysis code
+
+**Value**: Enforce purity - no hidden global reads.
+
+**Changes**:
+- [ ] Verify `DceConfig.current()` only called in `Reanalyze.runAnalysisAndReport` (entry point)
+- [ ] Verify no calls to `DceConfig.current()` in `Dead*.ml`, `Exception.ml`, `Arnold.ml` analysis code
+- [ ] All analysis functions take explicit `~config` parameter
+
+**Test**: `grep -r "DceConfig.current" analysis/reanalyze/src/{Dead,Exception,Arnold}.ml` returns zero results.
+
+**Estimated effort**: Trivial (verification only, assuming Task 2 complete)
+
+### Task 11: Integration and order-independence verification
 
 **Value**: Verify the refactor achieved its goals.
 
@@ -271,13 +288,15 @@ Each task should:
 
 ## Execution Strategy
 
-**Recommended order**: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10
+**Recommended order**: 1 → 2 (complete all analyses) → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 (verify) → 11 (test)
 
 **Why this order?**
 - Tasks 1-2 remove implicit dependencies (file context, config) - these are foundational
+- Task 2 must be **fully complete** (DCE + Exception + Arnold) before proceeding
 - Tasks 3-7 localize global state - can be done incrementally once inputs are explicit
 - Tasks 8-9 separate pure/impure - can only do this once state is local
-- Task 10 validates everything
+- Task 10 verifies no global config reads remain
+- Task 11 validates everything
 
 **Alternative**: Could do 3-7 in any order (they're mostly independent).
 
@@ -295,6 +314,7 @@ After all tasks:
 ✅ **No global mutable state in analysis path**
 - No `ref` or mutable `Hashtbl` in `Dead*.ml` modules
 - All state is local or explicitly threaded
+- **Zero `DceConfig.current()` calls in analysis code** - only at entry point
 
 ✅ **Order independence**
 - Processing files in any order gives identical results

analysis/reanalyze/src/Arnold.ml

@@ -111,7 +111,7 @@ module Stats = struct
     incr nCacheChecks;
     if hit then incr nCacheHits;
     if !Common.Cli.debug then
-      Log_.warning ~forStats:false ~loc
+      Log_.warning ~config:(DceConfig.current ()) ~forStats:false ~loc
         (Termination
            {
              termination = TerminationAnalysisInternal;
@@ -125,7 +125,7 @@ module Stats = struct
 
   let logResult ~functionCall ~loc ~resString =
     if !Common.Cli.debug then
-      Log_.warning ~forStats:false ~loc
+      Log_.warning ~config:(DceConfig.current ()) ~forStats:false ~loc
         (Termination
            {
              termination = TerminationAnalysisInternal;
@@ -610,7 +610,7 @@ module ExtendFunctionTable = struct
             then (
               functionTable |> FunctionTable.addFunction ~functionName;
               if !Common.Cli.debug then
-                Log_.warning ~forStats:false ~loc
+                Log_.warning ~config:(DceConfig.current ()) ~forStats:false ~loc
                   (Termination
                      {
                        termination = TerminationAnalysisInternal;
@@ -632,7 +632,8 @@ module ExtendFunctionTable = struct
                  functionTable
                  |> FunctionTable.addLabelToKind ~functionName ~label;
                  if !Common.Cli.debug then
-                   Log_.warning ~forStats:false ~loc
+                   Log_.warning ~config:(DceConfig.current ()) ~forStats:false
+                     ~loc
                      (Termination
                         {
                           termination = TerminationAnalysisInternal;
@@ -699,7 +700,8 @@ module CheckExpressionWellFormed = struct
                        functionTable
                        |> FunctionTable.addLabelToKind ~functionName ~label;
                        if !Common.Cli.debug then
-                         Log_.warning ~forStats:false ~loc:body.exp_loc
+                         Log_.warning ~config:(DceConfig.current ())
+                           ~forStats:false ~loc:body.exp_loc
                            (Termination
                               {
                                 termination = TerminationAnalysisInternal;
@@ -873,7 +875,7 @@ module Compile = struct
         newFunctionName;
       newFunctionDefinition.body <- Some (vb_expr |> expression ~ctx:newCtx);
       if !Common.Cli.debug then
-        Log_.warning ~forStats:false ~loc:pat_loc
+        Log_.warning ~config:(DceConfig.current ()) ~forStats:false ~loc:pat_loc
           (Termination
              {
                termination = TerminationAnalysisInternal;

analysis/reanalyze/src/DceConfig.ml

@@ -0,0 +1,34 @@
+(** Configuration for dead code elimination analysis.
+    
+    This module encapsulates all configuration needed for DCE,
+    gathered from RunConfig and CLI flags. *)
+
+type cli_config = {
+  debug: bool;
+  ci: bool;
+  json: bool;
+  write: bool;
+  live_names: string list;
+  live_paths: string list;
+  exclude_paths: string list;
+}
+
+type t = {run: RunConfig.t; cli: cli_config}
+
+(** Capture the current DCE configuration from global state.
+    
+    This reads from [RunConfig.runConfig] and [Common.Cli] refs
+    to produce a single immutable configuration value. *)
+let current () =
+  let cli =
+    {
+      debug = !Common.Cli.debug;
+      ci = !Common.Cli.ci;
+      json = !Common.Cli.json;
+      write = !Common.Cli.write;
+      live_names = !Common.Cli.liveNames;
+      live_paths = !Common.Cli.livePaths;
+      exclude_paths = !Common.Cli.excludePaths;
+    }
+  in
+  {run = Common.runConfig; cli}

analysis/reanalyze/src/DeadCode.ml

@@ -1,32 +1,33 @@
 open DeadCommon
 
-let processSignature ~doValues ~doTypes (signature : Types.signature) =
+let processSignature ~config ~doValues ~doTypes (signature : Types.signature) =
   signature
   |> List.iter (fun sig_item ->
-         DeadValue.processSignatureItem ~doValues ~doTypes
+         DeadValue.processSignatureItem ~config ~doValues ~doTypes
            ~moduleLoc:Location.none
            ~path:[!Common.currentModuleName]
            sig_item)
 
-let processCmt ~cmtFilePath (cmt_infos : Cmt_format.cmt_infos) =
+let processCmt ~config ~cmtFilePath (cmt_infos : Cmt_format.cmt_infos) =
   (match cmt_infos.cmt_annots with
   | Interface signature ->
-    ProcessDeadAnnotations.signature signature;
-    processSignature ~doValues:true ~doTypes:true signature.sig_type
+    ProcessDeadAnnotations.signature ~config signature;
+    processSignature ~config ~doValues:true ~doTypes:true signature.sig_type
   | Implementation structure ->
     let cmtiExists =
       Sys.file_exists ((cmtFilePath |> Filename.remove_extension) ^ ".cmti")
     in
-    ProcessDeadAnnotations.structure ~doGenType:(not cmtiExists) structure;
-    processSignature ~doValues:true ~doTypes:false structure.str_type;
+    ProcessDeadAnnotations.structure ~config ~doGenType:(not cmtiExists)
+      structure;
+    processSignature ~config ~doValues:true ~doTypes:false structure.str_type;
     let doExternals =
       (* This is already handled at the interface level, avoid issues in inconsistent locations
          https://github.com/BuckleScript/syntax/pull/54
          Ideally, the handling should be less location-based, just like other language aspects. *)
       false
     in
-    DeadValue.processStructure ~doTypes:true ~doExternals
+    DeadValue.processStructure ~config ~doTypes:true ~doExternals
       ~cmt_value_dependencies:cmt_infos.cmt_value_dependencies structure
   | _ -> ());
-  DeadType.TypeDependencies.forceDelayedItems ();
+  DeadType.TypeDependencies.forceDelayedItems ~config;
   DeadType.TypeDependencies.clear ()