63 lines
4.3 KiB
Markdown
63 lines
4.3 KiB
Markdown
# Phase 2：拆仓库
|
||
|
||
父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
|
||
|
||
## Goal
|
||
|
||
把当前 `packages/road-compiler/` 拆为保留 git 历史、可脱离宿主独立测试和运行的仓库；宿主改为消费一个锁定版本的编译器 CLI。这样道路编译器可以独立演进，宿主依然通过版本化文件契约稳定构建场景。
|
||
|
||
## Confirmed Facts
|
||
|
||
- P1 已完成：编译器实现和 workbench 的所有权在 `packages/road-compiler/`；宿主负责将区域配置映射为 `RoadCompilerInput`。
|
||
- `git log --follow packages/road-compiler/src/compile/native-road.js` 已能追溯到 2026-08-13 的 native-road compiler 历史。
|
||
- 契约为 `native-road-package/v1`，完成标记为 `NATIVE_ROAD_COMPILE_DONE <json>`；`comparisonDir` 是可选输入，继续保留 `comparison.json`。
|
||
- 当前宿主远端为内部 Git 服务 `https://git.app.que01.top/que01/osmWorkflow.git`；P2 独立编译器仓库定为私有 `https://git.app.que01.top/que01/road-compiler.git`。
|
||
- 可维护范围只有 `fengshu-er-road` 和 `nantaizi-lake-innovation-valley`。`hanyang-block` 是废案，不参与基线、测试、验收或迁移语料。
|
||
|
||
## Requirements
|
||
|
||
### R2.1 保留 Git 历史
|
||
|
||
- 用 `git subtree split` 或 `git filter-repo` 导出，不得以复制目录再 `git init` 替代。
|
||
- 新仓库中 `git log --follow src/compile/native-road.js` 必须能追溯到 P1 之前的 native-road compiler 提交。
|
||
|
||
### R2.2 新仓库可独立运行
|
||
|
||
- 新仓库拥有 compiler、CLI、check、workbench、其测试 fixture、两个 parity baseline、契约文档和 README。
|
||
- 新仓库 own `ol` 及其 workbench 所需的运行依赖；workbench 不得从宿主 `node_modules` 提供浏览器资源。
|
||
- 新仓库不得引用宿主的 `area-config`、`config/areas`、`scripts/` 或本仓库绝对路径。
|
||
|
||
### R2.3 宿主的消费边界
|
||
|
||
- `scripts/lib/area-config.js` 继续是唯一的区域配置归一化与 `RoadCompilerInput` 映射位置。
|
||
- `scripts/build-area.js` 用已安装编译器的 CLI 子进程编译，继承 stdout/stderr，检查启动错误、退出状态和 signal，并解析且校验唯一的 `NATIVE_ROAD_COMPILE_DONE` 标记。
|
||
- 宿主只依赖 CLI、写入的文件和版本化输入 JSON；不再以相对路径 import 编译器内部模块。保留的宿主 signal 文件 I/O 适配层改为只调用公开包 API。
|
||
- `road-workbench` 保持每次编译均启动新进程的语义，但改为调用已安装 CLI。
|
||
|
||
### R2.4 版本与迁移
|
||
|
||
- 宿主依赖必须锁定一个具体编译器版本，禁止 `latest` 或 `*`；包版本与 `native-road-package/v1` 的契约版本独立演进。
|
||
- 初始分发使用带注释的 git tag `v0.1.0`；宿主锁定该 tag。完整 parity 验证后移除 `packages/road-compiler/`，不保留 in-host 副本作为正常消费路径。
|
||
- 宿主保留两份 baseline，用来验证今后升级编译器版本后没有产物漂移。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] AC2.1 独立仓库的 `git log --follow src/compile/native-road.js` 可见 P1 前的 compiler 历史。
|
||
- [ ] AC2.2 在未 clone 宿主的干净目录中，新仓库 `npm ci`（或等价锁文件安装）和 `npm test` 均通过。
|
||
- [ ] AC2.3 新仓库的两区域 parity（`fengshu-er-road`、`nantaizi-lake-innovation-valley`）均与迁入 baseline 完全一致。
|
||
- [ ] AC2.4 宿主用锁版本依赖运行 CLI；`build-area.js` 成功解析一个有效的 `NATIVE_ROAD_COMPILE_DONE` 标记，缺失、重复或非法标记会失败。
|
||
- [ ] AC2.5 宿主的两个区域 parity 均对保留 baseline 全绿。
|
||
- [ ] AC2.6 宿主 `package.json` 的 compiler 依赖是具体、可复现版本，不是 `latest`、`*` 或裸分支。
|
||
- [ ] AC2.7 编译器仓库对宿主反向依赖为 0，且其 workbench 可独立启动。
|
||
|
||
## Out of Scope
|
||
|
||
- 编译器几何、规则或输出内容改动。
|
||
- 图层 manifest 和道路/建筑渲染分离（Phase 3）。
|
||
- drawtonomy 扩展（Phase 4）。
|
||
- `hanyang-block` 修复、迁移或作为验收样本。
|
||
|
||
## Release Decision
|
||
|
||
独立仓库为私有 `https://git.app.que01.top/que01/road-compiler.git`。首发以带注释 tag `v0.1.0` 发布，宿主依赖精确锁定该 tag；两个区域 parity 均通过后删除 `packages/road-compiler/`。该决定授权 P2 在该内部远端创建和推送仓库，但不授权发布到 npm 或其他托管平台。
|