企业官网建设流程全解析

本文以 Roc 语言编译器仓库中的快照测试 can_import_aliased_conflicts.md 为核心，深入解析"两个模块被导入为同一个别名"时编译器的完整诊断行为。你将理解 Roc 导入系统的命名空间规则、Duplicate Definition与Name Not In Scope两类诊断的语义差异，掌握快照测试（Snapshot Test）的格式与执行方式，并学会用zig build run-snapshot-tool复现与验证编译器各阶段输出。

一、场景复现：同一个别名，两个模块

Roc 允许通过as关键字为导入的模块起别名，但别名必须在当前作用域内唯一。下面这段代码正是该快照测试的原始用例（见 can_import_aliased_conflicts.md 的SOURCE段）：

import json.Json as MyMod import http.Client as MyMod main = { x = MyMod.parse x }

第一行把json.Json绑定到别名MyMod；第二行又把http.Client绑定到同名别名MyMod。随后main中通过MyMod.parse尝试访问模块成员。

这段代码在语义上是自相矛盾的：MyMod到底指向json.Json还是http.Client？parse又属于哪个模块？编译器无法消解这种歧义，因此产生了一连串连锁诊断。

二、快照测试是什么：一文件锁定整个编译流水线

在深入诊断之前，先理解该文件的载体。Roc 的 test/snapshots/README.md 明确指出：快照测试通过捕捉源码经过每个编译阶段后的输出来验证编译器行为——包括词法分析（tokenization）、解析（parsing）、规范化（canonicalization）与类型检查（type checking）。

每个快照文件由若干个以#开头的段组成，本文件的段结构如下：

该 README 还强调：普通快照（type=snippet等）的PROBLEMS段只承载诊断语义，回答"编译器是否产生了正确的诊断"；而渲染器输出（终端布局、Markdown、HTML、LSP）由reporting/下的另一类快照单独锁定。因此本文件展示的正是诊断语义层面的权威预期。

三、诊断详解：两条错误一条链

EXPECTED段给出了整个用例的诊断摘要：

DUPLICATE DEFINITION - can_import_aliased_conflicts.md:2:1:2:28 NAME NOT IN SCOPE - can_import_aliased_conflicts.md:5:9:5:20

位置格式为文件:起始行:起始列:结束行:结束列。两条诊断一前一后、互为因果：

3.1 第一条：Duplicate Definition（warning 级别）

位置2:1 - 2:28正好覆盖第二行import http.Client as MyMod整条语句。PROBLEMS段的对应报告说明了一切：

• 标题为"Duplicate Definition"，严重级别warning；
• 核心信息："The nameMyModis being redeclared here"（名称在此被重复声明）；
• 它引用了此前的位置：In this scope, MyMod was already defined in ... line 1——即第一行import json.Json as MyMod；
• 第一行源码在报告中以(annotation dim)弱化显示，作为"既有定义"的证据，第二行以(annotation error)标注。

也就是说：导入语句向当前作用域注入的模块名，与普通值、类型声明一样受到"作用域内名称唯一"约束。当第二条import ... as MyMod尝试重复声明MyMod时，编译器立刻判定冲突。

3.2 第二条：Name Not In Scope（runtime_error 级别）

位置5:9 - 5:20精确圈住main块内的MyMod.parse表达式。其报告内容：

• 标题"Name Not In Scope"，严重级别runtime_error；
• 信息："Nothing is namedparsein this scope."（当前作用域中不存在名为parse的东西）；
• 附带修复提示："Is it misspelled, or is there an import missing?"（是否拼写错误，或缺少导入？）。

这条错误的根因可以从诊断链推断：MyMod的声明本身因冲突而失效，编译器无法确定它绑定到哪个模块，因而也无法在MyMod名下解析成员parse。注意报告标注的是成员名parse而非MyMod——因为MyMod至少被声明过（虽然冲突），而parse从未被引入当前作用域。

值得对比的是 can_import_comprehensive.md：该用例中Json、Http、Str等别名各自唯一，但代码引用了模块中并不存在的成员（如Json.utf8、Str.trim、未暴露的get/post），编译器只报Name Not In Scope而不报Duplicate Definition。两相对照可以得出结论：别名唯一是前置条件，成员解析失败是独立诊断。

四、编译流水线视角：从 token 到类型的完整证据

快照文件的TOKENS、PARSE、CANONICALIZE、TYPES四段，从编译器内部视角完整复现了该用例的遭遇：

4.1 TOKENS：词法层别名解析

KwImport,LowerIdent,NoSpaceDotUpperIdent,KwAs,UpperIdent, KwImport,LowerIdent,NoSpaceDotUpperIdent,KwAs,UpperIdent,

两条 import 语句被词法分析为完全对称的结构：KwImport（import 关键字）、LowerIdent（小写模块路径json）、NoSpaceDotUpperIdent（点号连接的大写类型名Json）、KwAs（as 关键字）、UpperIdent（大写别名MyMod）。词法阶段不关心名称是否冲突，它只负责把源码切分为 token。

4.2 PARSE：语法层如实记录

(s-import (raw "json.Json") (alias "MyMod")) (s-import (raw "http.Client") (alias "MyMod"))

AST 中两条s-import节点都被解析为(alias "MyMod")，语法上完全合法。同时MyMod.parse被解析为(e-ident (raw "MyMod.parse"))——一个限定标识符（qualified identifier）。冲突不在语法层暴露，语法分析对重复别名毫无异议，这正说明冲突检测发生在更深层的语义阶段。

4.3 CANONICALIZE：规范化层"降级"为错误表达式

(can-ir (d-let (p-assign (ident "main")) (e-runtime-error (tag "erroneous_value_expr"))) (s-import (mod "json.Json") (exposes)) (s-import (mod "http.Client") (exposes)))

这是全文件最有信息量的一段：在规范化阶段，main的整体定义被替换为e-runtime-error (tag "erroneous_value_expr")——一个运行时错误哨兵表达式。从源码结构可以推断，这是编译器在无法可靠消解名称时的兜底策略：与其输出一个可能被错误解读的 IR，不如显式标记"此处已出错"，把诊断留给报告阶段。同时两条 import 仍被保留在 Can IR 中（(s-import (mod ...) (exposes))），但不再向作用域注入任何可解析的符号。

4.4 TYPES：类型系统全线飘红

(defs (patt (type "Error"))) (expressions (expr (type "Error")))

类型推断阶段，main的模式与表达式类型全部为"Error"。这是类型系统对erroneous_value_expr的标准响应：错误表达式在类型层面用统一的Error类型占位，避免类型错误进一步污染后续推断。

五、同类冲突全景：exposing 与类型别名的边界

导入别名冲突并非孤立场景。仓库中同目录的快照测试构成了完整的"导入冲突"测试矩阵：

• can_import_exposing_conflicts.md：import json.Json exposing [parse]后本地再定义parse = 42，Duplicate Definition覆盖整条 import 语句（1:1 - 1:34）。值得注意的是，本地定义parse = 42仍然生效——Can IR 中它是正常的(d-let ... (e-num (value "42")))，即本地定义优先，导入的暴露项让位。
• can_import_type_alias_conflict.md：import json.Json exposing [JsonValue]与本地类型JsonValue : U64冲突，同样触发Duplicate Definition。类型名与值名共享同一命名空间约束。
• can_import_comprehensive.md：综合用例，同时覆盖别名访问、exposing访问、限定访问三种模式，展示"名称唯一"与"成员存在性"是两套独立检查。

从这三个变体可以归纳 Roc 导入冲突的完整规则：凡是通过 import（含as别名与exposing暴露项）注入作用域的名称，都与现有声明竞争同一个命名空间；冲突总是以Duplicate Definition报告并指向重复声明位置，而被遮挡的成员访问则以Name Not In Scope呈现。

六、实战：运行与更新快照

快照是"活的文档"——你可以直接用命令让编译器重新生成该文件的所有阶段输出。依据 test/snapshots/README.md 的用法说明：

# 生成全部快照 zig build run-snapshot-tool # 只更新指定快照文件（本例即别名冲突用例） zig build run-snapshot-tool -- test/snapshots/can_import_aliased_conflicts.md # 依据当前诊断结果更新 EXPECTED 段（当编译器行为有意变更时） zig build run-snapshot-tool -- test/snapshots/can_import_aliased_conflicts.md --update-expected

注意事项：

• 命令基于 Zig 构建系统（仓库根目录的 build.zig 定义了run-snapshot-tool任务），需先具备 Zig 工具链；
• --update-expected会改写快照的EXPECTED/PROBLEMS段，仅应在诊断语义有意变更时使用，日常开发中它正是回归检测的守门员——当编译器行为意外改变时，快照对比会立刻暴露差异；
• 快照测试的价值在于"跨阶段一致性"：同一份源码的 token、AST、Can IR、类型与诊断必须彼此吻合，任何阶段的改动都会在快照 diff 中原形毕露。

七、小结：给 Roc 开发者的三条实践要点

1. 别名必须唯一：import ... as Alias注入的别名与普通声明共享作用域命名空间，重复声明必然触发Duplicate Definition（warning）。若多个模块需要同名访问，请改用不同别名，或借助exposing精确引入所需成员。
2. 区分两类诊断：Duplicate Definition指出"名字撞车"，Name Not In Scope指出"成员不存在"。别名冲突时后者是前者的次生灾害——修复前者，后者通常自动消失。
3. 快照是调试利器：遇到导入相关疑难杂症，用zig build run-snapshot-tool -- <file> --update-expected刷新快照，对照TOKENS、PARSE、CANONICALIZE、TYPES四段，即可定位语义层在哪个阶段、以何种方式拒绝了你的代码。