# MoonPortCheck：跨平台路径预检工具

**2026 年十月 MoonBit 活动申报草稿 · `v0.1.0` 历史候选 · 未报名、未发布正式包**

本页保留初版申报草稿。本轮已批准的公开仓库及 v0.2 开发范围见 [V02_PLAN.md](V02_PLAN.md)，执行状态见 [V02_PROGRESS.md](V02_PROGRESS.md)。

## 解决的问题

Linux 上能够创建的文件名，交付给 Windows 用户时可能发生保留名、尾点或大小写冲突。问题经常到解压、复制或复现实验时才被发现。MoonPortCheck 在交付前检查目录或路径清单，给出稳定规则编号、受影响路径和可解释原因，适用于源码、数据集和实验成果归档。

## 作品与实现

作品由 **MoonBit 核心库＋离线 Node.js CLI** 组成。规则判断、清单解析、层级索引、冲突分组和报告渲染都由 MoonBit 实现；Node 仅承担文件系统和进程适配。核心仅依赖标准库，同时验证 JS 与 wasm-gc 目标。

固定配置 `portable-windows-v1` 覆盖名称与路径结构、重复路径、ASCII 大小写冲突以及文件／目录冲突。中间目录也参与检查：`Data/a.csv` 与 `data/b.csv` 无需显式列出目录，即可发现冲突。诊断按组输出、排序稳定，避免大量重复输入产生两两展开的报告。

CLI 提供 `scan ROOT` 与 `check MANIFEST`，支持文本和 JSON。目录扫描包含隐藏项，不读取文件内容，不跟随链接；任何跳过或读取失败都报告扫描不完整。退出码区分通过、规则问题、输入错误和扫描失败，方便接入 CI。

## 演示与交付

运行 `run_demo.ps1` 或 `run_demo.sh` 可查看三组真实 CLI 演示，并自动核对退出码和诊断：

1. 中文、空格和隐藏目录名称正常通过。
2. `results/A.csv` / `results/a.csv`、`assets/CON.txt`、`notes/report.md.` 显示三类交付问题。
3. 三次重复、隐含目录碰撞及文件／目录前缀冲突按组报告。

交付包括源码、Apache-2.0 许可证、规则说明、构建与检查脚本、测试、规模验证入口和上述样例。验收以实际测试、跨平台运行、独立库消费和打包 CLI 结果为准，不以文件存在代替可用性。

## 边界与申报状态

首版不自动改名，不解析压缩包，不承诺完整 Unicode 等价、长路径及全部文件系统兼容性。定位是明确覆盖范围的交付前预检工具。

当前只有本地候选版本，GitHub 仓库、Mooncakes 版本、公开 CI 和官方报名链接均待后续授权发布及核验，不填写虚构地址。目标在 **10 月 24 日前**完成候选交付，余下时间用于修复与赛事验收；正式提交前复核[活动当月规则](https://moonbitlang.github.io/Hackathon2026/)。