企业官网建设流程全解析

• 编译器
• 编程语言
• 开发工具

本篇指南以 ReScript 编译器仓库中 reanalyze 死代码分析（Dead Code Elimination, DCE）的纯管道重构计划为核心，系统讲解如何把一项全局可变状态驱动的分析器改造成输入→输出透明、副作用只在边缘、处理顺序无关、可增量更新的纯函数式管道。读者将掌握其三大设计原则（局部可变→不可变、清晰阶段边界、增量更新）、"map → list → merge"可复用模式，以及 Task 1–11 的完整重构拆解、执行顺序与验证方法，可直接用于理解和改进 reanalyze 乃至其他同类静态分析器的架构。

为什么需要这次重构：全局可变状态的四宗罪

在重构之前，reanalyze 的死代码分析依赖大量全局可变状态（全局 ref、全局 Hashtbl、延迟队列），这带来了四个难以逾越的架构缺陷：

1. 增量/响应式分析不可能——无法只重处理一个文件，因为每个文件的分析结果都被写入共享全局状态，无法单独替换；
2. 测试困难——全局状态在多个测试用例之间残留，导致用例相互污染，必须靠模块重载来清理；
3. 并行化不可能——所有分析函数共享可变状态，无法并发执行；
4. 推理困难——存在大量依赖处理顺序的隐藏副作用，同一批文件换一种顺序处理，结果可能不同。

重构计划的目标非常明确：让分析成为输入 → 结果的纯函数，消除全局可变状态，把日志、文件 I/O 等副作用限制在管道边缘，从而同时解锁增量分析、并行化和可测试性。

三大核心设计原则

原则一：AST 处理期使用局部可变状态，处理完立即冻结为不可变

重构计划并不排斥可变状态本身，而是划定明确的边界：

• AST 处理阶段（逐文件）：允许使用局部可变状态（Hashtbl 等）换取性能，但函数返回时冻结为不可变file_data；该阶段天然是逐文件顺序执行的；
• 分析阶段（项目级）：只操作不可变数据结构，必须是可并行、可重排的，从这一节点开始获得静态保证。

计划的参考代码把这一边界表达得非常清晰：

(* AST processing: local mutable state OK, returns immutable *) let process_file config cmt_infos : file_data = let local_state = Hashtbl.create 256 in (* local mutable *) ... traverse AST, mutate local_state ... freeze_to_file_data local_state (* return immutable *) (* Analysis: immutable in, immutable out - parallelizable *) let solve_deadness config (files : file_data list) : analysis_result = ... pure computation on immutable data ...

原则二：清晰的阶段边界

整个分析被拆成四个阶段，每个阶段对输入、可变性、输出、可并行性都有明确约束：

原则三：不可变数据结构让增量更新成为可能

当文件 F 发生变化时：

1. 只对 F 重新执行 AST 处理，得到新的file_data；
2. 在以文件名为 key 的file_data映射中替换 F 的条目；
3. 重新执行合并与分析（都基于不可变数据）。

关键在于——不可变数据结构支持安全的增量更新：你可以替换一个文件的数据而不影响其他文件，这正是 reanalyze 后续响应式管道（analysis/reactive/）得以建立的基础。

被修复的六大问题（P1–P6）

重构计划把要解决的问题编号为 P1–P6，全部来自真实代码中的全局状态，每一项都有具体的消除路径与完成状态。

P1：全局"当前文件"上下文

Common.currentSrc、currentModule、currentModuleName是全局 ref，在处理每个文件之前被设置。每个函数都隐式依赖"当前正在处理哪个文件"，这使并发或增量处理多个文件成为不可能。

使用方：DeadCommon.addDeclaration_、DeadType.addTypeDependenciesAcrossFiles、DeadValue的路径构造。

状态：✅ 已在 Task 1 修复——显式file_context被贯穿所有分析函数。在现行源码中，DeadCommon.File_context.t以记录形式携带source_path、module_name、is_interface三个字段（见 dead_common.ml），而Dce_file_processing也维护了同构的file_context类型（见 dce_file_processing.mli）。

P2：全局分析表

所有分析结果累积在全局 Hashtbl 中：

• DeadCommon.decls—— 全部声明
• ValueReferences.table—— 全部值引用
• TypeReferences.table—— 全部类型引用
• FileReferences.table—— 跨文件依赖

影响：无法只分析文件子集而不重分析全部；无法在测试用例之间清理状态（除非重载模块）。这些全局表现在均已被删除——源码中的注释明确写道 "Global decls removed - now using Declarations.builder/t pattern"、"Global ValueReferences removed - now using References.builder/t pattern"（见 dead_common.ml）。

P3：跨文件处理队列

多种分析依赖全局队列、"稍后统一 flush"：

• DeadOptionalArgs.delayedItems—— 跨文件可选参数分析 → 已删除，改为CrossFileItems
• DeadException.delayedItems—— 跨文件异常检查 → 已删除，改为CrossFileItems
• DeadType.TypeDependencies.delayedItems—— 逐文件类型依赖（原本就是逐文件处理的）
• ProcessDeadAnnotations.positionsAnnotated—— 注解跟踪

其中positionsAnnotated还有一个额外问题：它把输入（来自 AST 的源码注解）和输出（求解器判定为 dead 的位置）混在同一个表中，求解器在分析过程中直接改写它，破坏了纯度。

影响：结果依赖顺序——队列在任意时刻被处理，换一种文件处理顺序可能得到不同结果；输入输出混用则使增量分析无法进行。

P4：全局配置读取

分析代码散落着!Common.Cli.debug、RunConfig.runConfig.transitive等直接读取，无法在不改写全局的前提下用不同配置运行分析。

状态：✅ 已在 Task 2 修复——显式config贯穿所有分析函数。现行实现中 dce_config.ml 的DceConfig.current ()一次性从全局Clirefs 与RunConfig捕获出一个不可变的Dce_config.t值，之后分析代码只接受显式参数：

type cli_config = { debug: bool; ci: bool; json: bool; live_names: string list; live_paths: string list; exclude_paths: string list; } type t = {run: Run_config.t; cli: cli_config} let current () = ... (* 从全局捕获，生成单个不可变配置值 *)

P5：副作用与分析混杂

分析函数直接调用Log_.warning（日志）、EmitJson（JSON 输出）、WriteDeadAnnotations（文件 I/O，后已删除），并直接改写结果数据结构。

影响：无法把分析结果当数据取回；测试必须捕获 I/O；分析逻辑无法复用到不同输出格式。这正是 Task 8 系列要解决的核心问题。

P6：绑定/报告状态

DeadCommon.Current.bindings、lastBinding、maxValuePosEnd是存储在全局的逐文件状态。

状态：✅ 在更早的工作中已修复——现在通过显式状态贯穿遍历。

目标终态：四层不可变数据类型与编排

重构计划的终态定义了一整套不可变数据类型，以及一个把四个阶段串起来的编排函数：

(* ===== IMMUTABLE DATA TYPES ===== *) (* Configuration: immutable *) type config = { ... } (* Per-file data - IMMUTABLE, returned by AST processing *) type file_data = { source_path : string; module_name : Name.t; is_interface : bool; source_annotations : AnnotationMap.t; (* immutable map *) decls : DeclMap.t; (* immutable map *) value_refs : RefMap.t; (* immutable map *) type_refs : RefMap.t; file_deps : StringSet.t; (* files this depends on *) } (* Project-wide merged view - IMMUTABLE *) type merged_view = { all_annotations : AnnotationMap.t; all_decls : DeclMap.t; all_value_refs : RefMap.t; all_type_refs : RefMap.t; file_graph : FileGraph.t; } (* Analysis results - IMMUTABLE *) type analysis_result = { dead_decls : decl list; issues : issue list; annotations_to_write : (string * line_annotation list) list; }

对应的编排参考实现（含增量更新版本）：

let run_analysis ~config ~cmt_files = (* Phase 1: Process files (can parallelize per-file) *) let files = cmt_files |> List.map (fun path -> (path, process_file config (load_cmt path))) |> StringMap.of_list in (* Phase 2: Merge *) let merged = merge_files files in (* Phase 3: Analyze *) let result = solve_deadness config merged in (* Phase 4: Report (side effects) *) report result (* Incremental: only re-process changed file *) let update_file ~config ~files ~changed_file = let new_data = process_file config (load_cmt changed_file) in let files = StringMap.add changed_file new_data files in let merged = merge_files files in solve_deadness config merged

这一终态在现行源码中已经基本落地。以 dce_file_processing.mli 为例，真实的file_data记录包含五个可合并的 builder：

type file_data = { annotations: File_annotations.builder; decls: Declarations.builder; refs: References.builder; cross_file: Cross_file_items.builder; file_deps: File_deps.builder; }

而 analysis_result.mli 提供了不可变结果类型及其构造器（empty、add_issue、add_issues、get_issues、make_dead_issue、make_dead_module_issue）。

贯穿始终的"map → list → merge"可复用模式

Task 3–7 反复使用同一个模式，计划将其抽象为 reanalyze 的核心范式：map（逐文件）→ list（有序无关）→ merge → 不可变结果。

builder 与 t 的双类型设计

每个数据域都提供两个类型：

(* Two types: mutable builder, immutable result *) type builder (* mutable - for AST processing *) type t (* immutable - for solver *) (* Builder API *) val create_builder : unit -> builder val annotate_* : builder -> ... -> unit (* Merge: list of builders → immutable result *) val merge_all : builder list -> t (* Read-only API for t *) val is_annotated_* : t -> ... -> bool

源码中的实际 API 印证

• 源注解：file_annotations.mli 定义annotated_as = GenType | Dead | Live，builder 提供annotate_gentype/annotate_dead/annotate_live，merge_all : builder list -> t之后，求解器只能通过is_annotated_dead、is_annotated_gentype_or_live等只读查询接口访问；
• 声明：declarations.mli 的 builder 提供add/find_opt_builder/replace_builder，不可变t只暴露find_opt/fold/iter/length；
• 引用：references.mli 以refs_from方向存储（posFrom -> 目标集合），恰好适配前向活性（liveness）算法，并提供freeze_builder把 builder 冻结为t；
• 文件依赖：file_deps.mli 提供add_file/add_dep与iter_files_from_roots_to_leaves（按拓扑序从根到叶遍历）；
• 跨文件项：cross_file_items.mli 把跨文件的exception_ref、optional_arg_call、function_ref、optional_arg_value_escape统一收进 builder，合并后由纯函数process_exception_refs处理。

关键性质：顺序无关（builder 按任意顺序收集结果一致）、可并行（map 阶段可并发）、可增量（替换列表中的单个 builder 后重新 merge）、类型安全（t的 API 中根本没有可变函数）。

该模式在Reanalyze.runAnalysis的合并段中得到完整落地——所有file_data的 builder 分别经过FileAnnotations.merge_all、Declarations.merge_all、CrossFileItems.merge_all、References.freeze_builder后交给求解器（见 reanalyze.ml）。

重构任务拆解（Task 1–11）

每个任务都遵循三条验收标准：✅ 修复上面列出的一个真实问题；✅ 让代码进入可度量的更好状态；✅ 行为保持可测试（行为不变，架构改进）；❌ 不添加立即可用的脚手架。

Task 1：移除全局"当前文件"上下文（P1）— ✅ 完成

• 创建DeadCommon.FileContext.t类型，含source_path、module_name、is_interface字段；
• 贯穿DeadCode.processCmt、DeadValue、DeadType、DeadCommon.addDeclaration_；
• 贯穿Exception.processCmt、Arnold.processCmt；
• 从 DCE 代码中移除所有Common.currentSrc、currentModule、currentModuleName读取；
• 从Common.ml删除这三个全局量。

价值：使文件可以并发或乱序处理。测试：对同一批文件改变处理顺序，结果应完全一致。工作量：中等（约触及 10 个函数，多为机械性改动）。

Task 2：把配置提取为显式值（P4）— ✅ 完成

• 使用已创建的DceConfig.t贯穿 DCE 分析函数；
• 把所有!Common.Cli.debug、runConfig.transitive等读取替换为config.debug、config.run.transitive；
• 所有配置参数必填（任何地方都不再有config option）；
• 配置贯穿 Exception 与 Arnold 分析（分析代码中不再出现DceConfig.current()）；
• 单一入口：只有 CLI/入口包装层（runAnalysisAndReport、DceCommand）调用一次DceConfig.current()，然后把显式 config 传遍各处。

测试：构造两个不同配置分别运行分析，应各自遵循自己的配置而不是读取全局。工作量：中等（已完成）。

Task 3：源注解采用 map → list → merge 模式（P3）— ✅ 完成

• 创建FileAnnotations模块，含builder（可变，供 AST 处理）与t（不可变，供求解器只读）；
• DceFileProcessing.process_cmt_file返回builder；
• processCmtFiles把 builders 收集成列表（顺序无关）；
• FileAnnotations.merge_all : builder list -> t合并为不可变结果；
• 求解器只拿到t（API 中没有任何可变函数）；
• 移除求解器改写：resolveRecursiveRefs不再调用annotate_dead；
• 直接使用decl.resolvedDead：已解析的声明直接使用其存储结果。

价值：为一种数据类型示范"局部可变 → 不可变"架构，确立 Task 4–7 可复用的模式。

Task 4：声明采用 map → list → merge 模式（P2）— ✅ 完成

• 创建Declarations模块（builder/t）；
• process_cmt_file返回同时含 annotations 与 decls builder 的file_data；
• 删除全局DeadCommon.decls；
• DeadOptionalArgs.forceDelayedItems改为接收~decls:Declarations.t。

价值：声明在 AST 处理后不可变，分析可并行。工作量：中等（核心数据结构，调用点多）。

Task 5：引用采用 map → list → merge 模式（P2）— ✅ 完成

• 创建References模块（builder/t）；
• 通过~refs:References.builder贯穿addValueReference、addTypeReference；
• 合并 refs 进 builder、处理延迟项、再冻结；
• 求解器通过find_value_refs、find_type_refs访问References.t；
• 删除全局ValueReferences.table与TypeReferences.table。

Task 6：跨文件项采用 map → list → merge 模式（P3）— ✅ 完成

• 创建CrossFileItems模块（builder/t）；
• process_exception_refs与process_optional_args变成作用于合并后t的纯函数；
• 删除DeadException与DeadOptionalArgs中的全局delayedItemsrefs。

关键洞察：跨文件项本质上是跨越文件边界的引用，应当与其他数据遵循完全相同的模式。（DeadType.TypeDependencies原本就是逐文件处理，无需纳入。）

Task 7：文件依赖采用 map → list → merge 模式（P2+P3）— ✅ 完成

• 创建FileDeps模块（builder/t）；
• iter_files_from_roots_to_leaves : t -> (string -> unit) -> unit（纯函数）；
• 删除Common.ml中的全局FileReferences。

Task 8：分析阶段纯化（P5）— ✅ 完成

目标架构：merged_view（不可变）→ solve_deadness（纯函数）→ analysis_result（不可变）→ report（副作用仅在此处）。方法：拆成一系列小而行为保持的步骤，每步验证后再推进，关键手法是"先改返回类型，然后在调用点立刻打日志"，保证行为逐字节不变。

Task 8.1：创建AnalysisResult模块，type t = { issues: Common.issue list }，构造器empty/add_issue/get_issues及 issue 构造器make_dead_issue/make_dead_module_issue。✅

Task 8.2：emitWarning改为内部使用makeDeadIssue（纯函数）。验证：make test-analysis输出一致。✅

Task 8.3：Decl.report签名改为返回issue option，在reportDead调用点立即记录返回的 issue。✅

Task 8.4：DeadOptionalArgs.check改为返回issue list（新增foldUnused、foldAlwaysUsed），调用点立即记录。✅

Task 8.5：不正确的@dead注解 issue 改用makeDeadIssue，调用点立即记录，删除已无用的emitWarning。✅

Task 8.6：DeadModules.checkModuleDead改为返回issue option，调用点立即记录。✅

Task 8.7：Decl.report改为返回issue list（含 dead module issues），用List.concat_map汇总，在reportDead末尾统一记录。✅

Task 8.8：reportDead改为返回AnalysisResult.t，把日志从reportDead移到调用方Reanalyze.ml。✅

关键保证：分析阶段（reportDead）现在返回包含全部死代码 issue 的不可变AnalysisResult.t，副作用（日志）只发生在调用方（Reanalyze.runAnalysis）。

Task 8b：把所有 issue 收进AnalysisResult.t— ✅ 完成

解决 Task 8 遗留的内联日志问题：resolveRecursiveRefs曾直接通过Log_.warning记录两类 issue（可选参数 issue 与不正确的@dead注解 issue），绕过了AnalysisResult.t。修复方式：通过~issues:(Common.issue list ref)贯穿resolveRecursiveRefs收集这两类 issue，加入reportDead的AnalysisResult.t，并移除其中所有Log_.warning调用。最终保证：resolveRecursiveRefs中不存在任何Log_.warning。

Task 9：把注解计算与文件写入分离（P5）— 已移除

WriteDeadAnnotations功能被整体删除：-write标志（自动向源文件插入@dead注解）因引入显著复杂度（全局状态、分析期文件 I/O、额外类型）而移除，而该功能使用率很低。需要抑制死代码警告的用户可以手动添加@dead注解。

Task 10：验证分析代码中零DceConfig.current()调用 — ✅ 完成

• 验证DceConfig.current()只在入口包装层（CLI /runAnalysisAndReport）被调用；
• 验证Dead*.ml、Exception.ml、Arnold.ml中无DceConfig.current()；
• 所有分析函数都接受显式~config参数。

验证命令（文档给出的 grep 检查）：grep -r "DceConfig.current" analysis/reanalyze/src/{Dead,Exception,Arnold}.ml返回零结果。✅ 工作量：琐碎（已完成）。

Task 11：集成与顺序无关性验证 — ✅ 完成

• 编写属性测试：随机打乱文件处理顺序，验证结果一致；
• 新增-test-shuffleCLI 标志随机化文件处理顺序；
• 新增test-order-independence.sh脚本，运行 3 轮打乱迭代并比较输出；
• 通过make test-reanalyze-order-independence运行（不属于默认测试集）；
• 求解器接受显式输入（无全局状态）——由架构验证；
• 在架构文档中新增"架构图"章节。

测试即任务本身。工作量：小（主要是写测试）。

执行策略：先隐性依赖、后数据平面、再输出平面

计划给出的完成状态与剩余顺序为：

已完成：Task 1 ✅、Task 2 ✅、Task 3 ✅、Task 10 ✅、Task 11 ✅

剩余顺序：4 → 5 → 6 → 7 → 8 → 9 → 11（测试）

为什么是这个顺序：

• Task 1–2 先移除隐性依赖（文件上下文、配置）——✅ DONE；
• Task 3 让源注解只读（求解器不再改写）——✅ DONE；
• Task 4–7 让状态逐文件化，支撑增量更新；
• Task 8 让报告纯化，返回不可变结果；
• Task 9 分离注解计算与文件写入；
• Task 10 验证不再有全局配置读取——✅ DONE；
• Task 11 全面验证，包括增量更新。

关键架构里程碑：

1. Task 7 之后：所有状态逐文件化，以文件名为 key；
2. Task 8 之后：求解器纯化，返回不可变结果；
3. Task 11 之后：增量更新验证通过。

时间估算（文档原估）：顺利 2–3 天；现实（含 bug/复杂情况）1 周；最坏（重大架构问题）2 周。

可选后续任务：OptionalArgs 跟踪不可变化 — ✅ 完成

• OptionalArgs.t完全不可变（无可变字段）；
• 新增纯函数apply_call、combine_pair；
• 在Common.ml创建OptionalArgsState模块承载状态映射；
• compute_optional_args_state返回不可变状态映射；
• DeadOptionalArgs.check从映射中查状态。

架构：声明的optionalArgs字段 = 初始状态（有哪些参数）；OptionalArgsState.t= 计算后状态（所有调用/组合之后）；求解器用OptionalArgsState.find_opt取得最终状态。

验证手段：顺序无关性测试与架构文档

顺序无关性是整个重构的核心验收指标，仓库为其提供了双保险：

1. 测试专用 CLI 标志-test-shuffle：在 cli.ml 声明let test_shuffle = ref false，在 reanalyze.ml 注册为-test-shuffle标志（"Test flag: shuffle file processing order to verify order-independence"）。启用后run_analysis会在合并前用 Fisher–Yates 洗牌算法打乱dce_data_list（见 reanalyze.ml）；
2. make test-reanalyze-order-independence：驱动test-order-independence.sh脚本运行 3 轮打乱迭代，比较输出是否一致。

各阶段还可独立做单元测试：Phase 1 处理单个.cmt验证file_data；Phase 2 合并已知 builders 验证合并结果；Phase 3 用已知输入调用求解器验证 issues——由于数据不可变，测试无需任何 mock，只需传入不可变数据。这些内容在 ARCHITECTURE.md 的 Testing 章节有完整描述。

下图展示了重构后管道的整体架构（来源：batch-pipeline.svg，源文件 batch-pipeline.mmd）：

重构后的能力兑现：增量更新与响应式管道

纯管道架构的直接成果是增量更新的可行性与落地：

• 标准路径：Reanalyze.runAnalysis依次执行"收集 cmt 路径 → 逐文件处理 → 合并 → 求解 → 报告"（见 reanalyze.ml），Timing.time_phase分别统计FileLoading/Merging/Solving/Reporting各阶段耗时；
• 响应式路径（-reactive）：analysis/reactive/目录基于同一份不可变架构实现了增量管道。当文件变化时，只有受影响条目被重算，未触及的条目保持稳定；没有任何文件变化时，所有响应式集合稳定，唯一的工作是遍历预计算好的 issues 集合。

据 ARCHITECTURE.md 记录的基准数据：冷启动（约 4900 个文件）时 Solving 约 2ms、Reporting 约 3ms；缓存命中（0 文件变化）时 Solving 约 1–5ms、Reporting 约 3–8ms；单个文件变化时求解复杂度为 O(受影响声明数)、报告为 O(issues)。README 中给出的反应式模式实测示例为：标准模式 CMT 处理 0.78s / 总计 1.01s，而反应式暖运行 CMT 处理 0.01s / 总计 0.20s（见 README.md）。响应式管道还通过-mermaid标志输出完整的 Mermaid 管线图，-timing标志输出每个响应式节点的增量统计（d_recv、e_recv、d_emit、runs、time_ms等）。

成功标准清单

重构完成后，计划定义了六项可验证的成功标准：

✅局部可变 → 不可变边界——AST 处理用局部可变状态（性能考量），返回不可变file_data；分析阶段只操作不可变数据。

✅纯分析阶段——solve_deadness : merged_view -> analysis_result是纯函数；分析中无副作用（日志、I/O）；可并行、可记忆化、可重排。

✅增量更新——替换一个文件的file_data不影响其他文件；重新合并与重新分析都是不可变数据上的纯函数。

✅顺序无关——任意顺序处理文件 → 相同的file_data；任意顺序合并 → 相同的merged_view；由属性测试验证。

✅静态保证——类型系统在 AST 处理之后强制执行不可变性；分析阶段 API 中看不到ref或可变Hashtbl；编译器捕获违规。

✅可测试——AST 处理、合并、分析均可隔离测试；无需 mock，直接传入不可变数据即可。

这六项标准不仅是这次重构的验收指标，也为 reanalyze 后续的响应式服务（reanalyze-server 的透明代理、-churn增量正确性测试、-runs缓存有效性基准等）奠定了架构基础。读者若要深入源码，可从 reanalyze.ml（编排入口）、dce_file_processing.mli（Phase 1）、analysis_result.mli（Phase 3 输出）与 ARCHITECTURE.md（完整架构文档）入手。

• 编译器
• 编程语言
• 开发工具