# 开发说明

核心模块不访问文件系统、不调用 shell。分层为文档解析、变量展开、参数分词、依赖表达式；文件访问集中在 `cli` 加载层，使用 `moonbitlang/x/fs`，不把平台 IO 混入核心接口。

代码以 `moon fmt` 格式化；提交前运行 `moon check --target all --deny-warn`、`moon build --target all --deny-warn`、`moon test --target all --deny-warn` 和 `moon run cmd/demo`。四目标为 wasm、wasm-gc、js、native。验证证据写入 `docs/verification.md`，失败不能记为通过。

复现使用固定的 `0.10.20+65efd5b93` 工具链，避免滚动下载改变格式和语言语法。升级工具链时应单独完成迁移和全套验证，再调整固定版本。

Ubuntu 与 Windows CI 分别显示工具链版本、四目标检查、构建和测试；另从 MoonCakes 安装已发布的0.3.1，验证其公开接口。注册表报告与归档报告一起保存在各平台的 `package-install` 附件中，便于区分主分支归档与正式发布包。

命令行实现集中在 `cli/commands`，`cmd/inspect`、`cmd/query`、`cmd/check` 与统一 `cmd/moonpkgconfig` 只负责传入参数。`python scripts/verify-cli.py` 从当前源码安装到隔离目录，在仓库外、清除 MoonBit 环境的进程中执行实际命令，验证目录 JSON、路径顺序、错误退出码和旧入口兼容性；报告为 `_build/verification/cli.json`。新增 CLI 尚未包含在注册表0.3.1中。

CLI 层的版本化 JSON 外层报告与核心库序列化分开维护；原有 `flags/diagnostics`、`entries/diagnostics` 内容保留。非帮助模式指定 `--json` 后，读取和用法错误也必须可解析；新增状态不能伪装成无诊断成功。元数据、条件与 `--explain` 的协议见 [CLI JSON 接口](docs/cli-json.md)。

文本失败的诊断、用法、IO 信息及目录检查汇总写入 stderr；失败的参数查询不能在 stdout 留下部分参数。显式帮助使用 stdout。JSON schema 保持1，保留核心返回的参数内容，调用者必须判断状态与退出码。`--exists` 和三个版本条件包含私有依赖，版本和变量读取不包含私有依赖。

`python scripts/package-cli.py` 从实际安装程序生成独立 ZIP，再从 ZIP 解压到仓库外，清除工具链环境后执行端到端验证。包内保留 MIT 与依赖许可证、提交与工具链信息、哈希；报告为 `_build/verification/cli-package.json`，下载文件在 `_build/cli`。CI 使用 `--require-clean` 拒绝未提交源码，附件保留30天；本地允许开发状态但必须在构建信息中标明。平台范围和下载方法见 [命令行下载指南](docs/cli-download.md)。

Windows 可运行 `scripts/verify.ps1`，接受可选的 `-MoonHome`；默认使用用户目录中的 `.moon` 安装。脚本遇到第一个失败立即退出，不修改全局 PATH。

可将固定版本工具链单独安装到忽略的 `.tools` 目录，并通过 `-MoonHome` 传入该安装的绝对路径。源码按固定版本执行格式化；生成的 `pkg.generated.mbti` 是本地接口视图，不纳入版本控制和发行归档。

发行验证使用 `python scripts/verify-install.py --package`：提取实际 ZIP，以独立 `moon.work` 连接归档源码和消费者，执行公开接口测试。默认不传参数时从 MoonCakes 安装当前模块版本，不设置本地依赖覆盖；此模式仅在版本已发布后运行。消费者目录保留在忽略的 `.tmp` 中，便于核对下载内容。

`moon.mod` 当前版本为0.3.1，主分支后续修复仍属未发布变更。发行前运行归档模式，上传成功后运行注册表模式；正式状态见 `docs/release.md`。复验旧版本需显式指定 `--version 0.3.0` 或 `--version 0.2.0`。0.3.1消费者新增2项诊断映射验证，四目标各运行6项；0.3.0运行原4项，0.2.0运行原3项。归档模式另从提取源码运行文件加载场景，实际数量与平台跳过项记录在报告中。可加 `--report <路径>` 保存版本、归档哈希和命令结果；失败报告不会标记为通过。

参数分类的端到端检查为 `python scripts/verify-flag-selection.py`，需要 Python 3；Windows 验证脚本和 Ubuntu CI 均会执行。它检查 JSON 与文本参数边界、来源解释、静态参数及诊断退出码，独立工具对照由 `scripts/compare-pkgconf.*` 执行。

`python scripts/verify-load-diagnostics.py` 构建原生命令，验证内容损坏、单文件读取/UTF-8 失败、目录优先级、虚拟提供者和目录 IO 错误，报告为 `_build/verification/load-diagnostics.json`。可传 `--target-dir` 和 `--report` 使用隔离构建与报告目录；符号链接和权限场景按平台执行，跳过原因必须记录。适配层应把 `diagnostics_by_package` 传给0.3.1的可选 `unavailable` 参数；不要解析诊断文本来推断包名，也不要把无关损坏文件加入单包查询。0.3.0不提供这个参数。

`cli.read_document` 严格解码 UTF-8，解码失败返回 `PC020`，不再追加缺少字段的假诊断。目录加载将单文件读取失败转为该包的 `PC019`；首个条目即使损坏也占据优先级。搜索目录读取失败继续抛 IO 错误并指出实际目录，不能把未完成扫描当成空成功。加载器只在调用方未覆盖时提供空的 `pc_sysrootdir` 展开值；CLI 显式 sysroot 覆盖它，默认值不能伪造成源码条目。

`python scripts/verify-performance.py` 构建原生 release 基准并验证大图及展开边界，不设机器相关的耗时门槛。详细测量使用 `scripts/benchmark.py`，范围、命令和原始记录见 `docs/performance.md`。修改遍历时必须保留深图安全性、最短路径选择以及诊断顺序；批量解释应复用一次 `dependency_paths` 快照。

查询期间的提供者索引和依赖步骤放在内部 `QueryContext`，不得跨公开调用复用，因为 `PackageSet` 和文档由调用方持有。目录优化仅复用能够证明无诊断且无冲突字段的子图；问题根保持完整遍历。提供者顺序、精确包优先、文档修改可见性和每根冲突范围由回归测试保护。后续测量及剩余边界见 `docs/query-performance.md`。

链接参数单独使用迭代逆后序，把依赖者放在其依赖之前；Cflags 的广度优先声明顺序保持原行为，不能共用链接次序来改写它。回归覆盖三角、跨层共享与深图；实际静态库检查由 `scripts/verify-link-order.py --reference <pkgconf-3.0.7>` 执行，需要 GNU 兼容 `cc`/`ar`，报告为 `_build/verification/link-order.json`。固定 pkgconf 对照由55项基础查询与124项模板/静态顺序查询组成，共179项；158个固定种子输入另行计数。

Ubuntu GNU 用户空间可用 `scripts/verify-system-packages.py --reference <pkgconf-3.0.7> --directory <目录> --remove-package zlib` 检查实际安装语料及删除依赖后的副本；目录可重复指定，`--package` 限定根，`--cli` 复用已构建程序。报告记录文件哈希、展开总量、环境、参数集合、退出码、版本、变量、谓词及依赖者优先顺序。完整 Libs 另要求规范化序列相等；规范化只按 CLI 实际连续来源段构造线性元数据，由固定参考工具处理重复片段，不依据预期顺序重排。编译及分类模式的序列一致率单独记录。副本检查必须产生原本成功、删除后失败的依赖查询，并核对原文件未变；报告为 `_build/verification/system-packages.json`。

`PackageSet::select` 只验证并返回所选根，用于版本和变量读取；它不遍历依赖。CLI 的动态链接模式先验证含私有边的完整图，再调用只收集公开链接参数的核心 API，不能把验证范围等同于参数输出范围。

完整依赖图有效时，动态链接次序也使用私有边的约束，再过滤掉只经私有边可达的包；隐藏中间包不能使共享库提前出现。核心动态 API 遇到私有图错误时回退公开图排序，不引入私有诊断；CLI 已在前置验证中拒绝这类错误。直接边、隐藏链、虚拟提供者、私有环和错误回退由专用测试保护。

`python scripts/verify-resource-limits.py` 用真实 CLI 子进程检查重复超限、大量诊断和150文件展开输入。每场景单独测量墙钟时间、峰值工作集及输出规模，默认15秒终止门槛与500 MiB内存门槛用于回归保护；它们不等同于库对任意输入的性能保证。报告为 `_build/verification/resource-limits.json`，双平台 CI 保留该附件。

展开预算按 UTF-16 code units 计数：单值及每文档累计均为1 Mi；覆盖值不能绕过预算，首次 `PC009` 停止该文档。解析器保留前100条诊断，遇下一条时追加 `PC021` 并停止；合并诊断用完整内容作为哈希键，保持首次出现顺序。展开预算不是文件大小或进程内存上限。公开文档和包 Map 仍可变，查询不得假设插入时校验永久有效；缺失/无效 Version 与缺失包引用应返回诊断，不能用 `unwrap` 中止进程。字段大小写、未知扩展字段与循环的严格边界见 README。

真实 zlib 和 libpng 的 MoonBit FFI 示例使用独立模块，在 Linux CI 中构建和运行。zlib 另有 Windows MSVC CI，执行 `python scripts/verify-zlib-windows.py`；本地完整检查可加 `scripts/verify.ps1 -WithWindowsZlib -CMake <路径>`。命令及前置条件见各自示例的 README；它们不加入核心库的四目标依赖。两个运行脚本共用 `scripts/native_ffi.py`，修改共用代码时必须重跑 Linux 的两条集成流程以及 Windows zlib。

`python scripts/test-native-ffi.py` 在 Windows 本地验证及两个 CI 平台执行。MSVC 参数适配仅属于示例脚本：保留 JSON 参数和来源边界，未知选项必须报错，静态库名差异由调用方显式映射。不能把示例成功表述为核心库已实现完整的 Windows 参数转换或自动重定位。

`examples/zlib-consumer` 是自包含的消费项目，固定依赖 MoonCakes 0.2.0。`python scripts/verify-zlib-consumer.py --pc-dir <目录>` 将它复制到仓库之外，检查缺失/版本错误和修复后的文件工具；Windows CMake 安装另传 `--msvc-lib z=zlibstatic.lib`。不要通过 `moon.work` 或本地主分支替换来让该检查通过。Windows zlib 准备脚本加 `--with-consumer` 可复用安装执行此检查；完整验证的 `-WithWindowsZlib` 已包含它。构建程序与演示可使用本地包缓存，但必须是指定的已发布版本。

仓库只保留与 MoonPkgConfig 有关的源码、测试和开发记录。提交应说明实际改动，不为数量拆分无意义修改。

`examples/native-consumer` 固定使用 MoonCakes 0.3.1，规划器将加载诊断映射传入参数和依赖路径查询。`python scripts/verify-native-consumer.py --library zlib --pc-dir <目录>` 与 `--library expat` 分别在仓库外验证同一模板的缺包、版本错误、损坏依赖定位、修复与真实运行；Windows zlib 另传库名映射。`python scripts/verify-native-file-tool.py --pc-dir <目录>` 复用同一适配器构建实际文件工具，并与 Python zlib 双向对照。

`python scripts/review-native.py` 自动准备固定的静态 zlib、Expat，再运行三个消费者；提供两个安装目录时可跳过准备。总报告要求三个消费者使用相同的规划器和适配代码。已有自定义应用构建设置会被拒绝，避免生成配置时丢失设置。完整运行方式见 `docs/native-walkthrough.md`。

`examples/project-integration` 提供保留现有多包构建配置的另一条接入路径。它使用固定工具链的实验性 pre-build 钩子：配置阶段先构建独立的0.3.1规划器，钩子只运行规划器并输出构建 JSON。`python scripts/verify-project-integration.py` 验证真实库包链接、配置保留、失败修复及元数据更新；CI 传入 `--prepared-report _build/verification/native-walkthrough.json` 复用已准备的安装。Windows 完整验证可加 `-WithProjectIntegration`。报告为 `_build/verification/project-integration.json`；不能把该实验性适配路径表述为任意工具链都稳定支持。

真实 Expat 验证为 `python scripts/verify-expat.py`，构建固定2.6.2静态库后调用 `verify-expat-ffi.py`；Linux 与 Windows CI 均执行。本地可加 `scripts/verify.ps1 -WithExpat -CMake <路径>`，既有 `-WithWindowsZlib` 可同时指定。Windows MSVC 环境发现已放入共用 `native_ffi.py`，修改时必须重跑两种 Windows 库及 Linux 的既有 FFI 集成。Expat 的私有宏必须来自查询结果，不得在 C 包装或构建脚本中补写；负对照要求真实导入符号链接失败。

后续兼容性测试必须有独立预期值或官方工具依据；不能仅对实现输出生成快照并称之为正确性证明。遇到 pkgconf 与 pkg-config 差异时，记录所选兼容策略。

`python scripts/verify-compatibility.py` 校验六个真实上游模板及许可证的固定哈希，执行声明预期、124项 pkgconf 3.0.7 对照与158个固定种子输入。参考工具可由 `--reference` 或 `PKGCONF` 指定；默认种子及重现方法见 `docs/compatibility.md`。Windows 完整流程及 Ubuntu CI 执行该检查，报告保存在 `_build/verification/compatibility.json`。新增语料必须保留完整许可证、固定提交与配置替换值，不得通过刷新预期输出掩盖差异。