# 路线图

MoonUpgradeGuard 是一个针对 EVM 合约升级的升级前兼容性检查器。本页记录已经交付的能力、接下来要验证的产物形态，以及后续方向。它只描述工程优先级与产品行为：这不是排期，也不构成带时间的承诺。

## 优先级如何决定

1. 可能把结论错判为"兼容"的规则，优先于只改善措辞的改动。
2. 每条比较规则都配一个能复现它所要捕获变化的 fixture，以及一个在缺少该规则时会失败的测试。
3. 不受支持的输入必须显式失败，并以退出码 `2` 结束；它永远不会变成静默放行。
4. 范围按规则增长，而不是按界面增长。
5. 任何改变诊断含义的改动——诊断码、严重度或 JSON 结构——都属于契约变更，必须明确声明。

## 已交付

- **产物摄取**：原始 `storageLayout` 对象、Foundry 写出的平铺 artifact、solc
  Standard JSON 输出、Hardhat build info，并提供 `--contract` 选择器处理包含多个合约的文档。歧义与不受支持的形态会被报告，而不是被猜测。
- **存储**：无损的 slot 与 byte offset、打包字段、定长与动态数组、mapping、struct、
  递归类型图，以及被缩减或整体替换的 `__gap` 数组。
- **transient storage**：使用同一套规则比较，位于它自己的 `transientStorage[...]`
  命名空间。
- **ABI**：规范化签名、Keccak-256 selector 与 event topic（已对公开向量校验）、删除、
  返回值列表变化、indexed 与 anonymous 变化、mutability 变化，以及两个版本之间的
  selector 或 topic 冲突。
- **诊断**：带严重度、位置与被比较的旧值和新值的稳定诊断码；确定性的文本与 JSON
  输出；可供流水线判定的退出码 `0`、`1`、`2`。
- **证据**：包含针对生成布局的不变量检查的单元测试、CLI 进程级检查、每条规则一对
  fixture，以及与 OpenZeppelin Upgrades Core 的差分对比记录。
- **CI**：每次 push 与 pull request 都执行格式检查、类型检查、测试、生成物是否已提交
  （接口与诊断码手册）、空白检查、端到端 CLI 脚本与发布包文件清单检查。
- **版本报告**：CLI 的 `--version` 输出版本号，端到端测试核对它与模块清单一致。
- **原生发布产物**：[v0.2.0](https://github.com/snorfyang/moon-upgrade-guard/releases/tag/v0.2.0)
  提供 Linux x86_64 与 macOS arm64 可执行文件；两个平台均在发布 CI 中构建并通过端到端检查。
- **诊断码手册**：一页列出全部诊断码、严重度、是否阻断与含义，由源码生成，CI 重新生成后若与提交内容不一致即失败，因此新诊断码不可能没有文档。
- **可复现走查**：中英两版实战教程都能从全新 clone 走到一次通过检查与一次失败检查，
  其中每一条命令、输出与退出码都由 CI 对真实二进制逐条核对。
- **双语文档**：公开文档以中文为主、英文镜像（`X.md` 与 `X.en.md`，顶部互相链接）：README、
  诊断码手册、差分对比记录、参考与许可页、fixture 说明都有英文版；路线图目前只有中文。两份诊断码手册由同一份源码生成，翻译缺失会被生成器直接拒绝，中英结构一致性由 `scripts/check_docs.py`
  在 CI 中校验。
- **参考与许可**：规则依据的一手规范、依赖许可证（MoonBit 标准库与 `moonbitlang/async` 为
  Apache-2.0；OpenZeppelin Upgrades Core 为 MIT 且仅用于开发期行为对比；solc 仅使用其输出）、
  fixture 来源与上游关系，记录在 `docs/references.md` 及其英文镜像中。
- **真实编译产物回归矩阵**：仓库自有源码生成 solc Standard JSON、Foundry 平铺 artifact
  与 Hardhat build info，覆盖兼容、不兼容及无布局输入的退出码 `0`、`1`、`2`；另用 solc
  真实产物验证打包字段、mapping、struct、`__gap` 与 transient storage 的组合变化。
- **诊断来源标注**：单侧输入诊断带有 `old` 或 `new` 来源；两侧无效时仍能分辨每条错误，
  比较诊断不归属于单侧产物。这是 JSON 报告结构的公开变更。

## 更晚

- **命名空间存储与非结构化 slot。** 编译器的 `storageLayout` 只列出状态变量，因此
  ERC-7201 命名空间成员与 EIP-1967 这类非结构化 slot 对它不可见。读取它们需要抽象语法树，而命名空间成员的位置还需要一次本工具刻意不执行的重新编译。在这一层出现之前，提到命名空间的产物会被拒绝，而不是被报告为兼容。
- **严格重命名模式。** 同一位置的重命名不会移动任何字节，因此目前是警告。有些团队可能希望它阻断升级；那会是一个可选项，且必须公开记录，而不是静默改变默认行为。
- **更多目标平台。** 库与目标平台无关，而 CLI 仅支持 native。只有在 CI 覆盖之后才会声明更多目标。
- **包注册表发布**，使 CLI 无需从源码构建即可安装。

## 稳定性

- 诊断码及其严重度是稳定的，JSON 报告结构也是稳定的。新增内容会在发布说明中公布。
- 在 `0.x` 版本之间，库 API 仍可能变动；命令行与退出码是更稳定的接触面。
- 报告是确定性的：相同输入产生字节一致的输出，诊断始终按稳定顺序排序。

## 如何提供反馈

请提交 issue，并附上能复现该情况的 artifact 对、该规则应当遵循的规范或 EIP，以及你期望的行为。请不要附带私钥、个人地址或任何无法公开分享的内容。