refactor: consume external road compiler

This commit is contained in:
2026-08-26 09:23:46 +08:00
parent b78cb6e990
commit 5cde08090e
48 changed files with 257 additions and 15626 deletions

View File

@@ -18,6 +18,7 @@
| 改复合路口几何(`buildComplexJunctionGeometry`、车道控制避让、人行道转角) | [CLI 与阶段](./cli-and-stages.md#可编辑信号设施与运行时锚点的跨阶段消费) 的复合路口小节 |
| 改预览页生成 | [../preview/](../preview/index.md) |
| 声称"纯重构,产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
| Native road compiler CLI、输入或完成标记 | [编译器契约指针](./native-road-package.md) |
---

View File

@@ -0,0 +1,9 @@
# Native Road Compiler Contract
The native-road package is maintained in the private `road-compiler` repository:
`https://git.app.que01.top/que01/road-compiler`
This host consumes the exact git tag recorded in `package.json` and lockfile. The host owns area configuration normalization and writes `RoadCompilerInput`; the compiler owns the `native-road-package/v1` file contract and CLI. Production code must invoke the installed compiler CLI through `scripts/lib/road-compiler-cli.js`, not import compiler source files or read `packages/road-compiler`.
The completion marker is `NATIVE_ROAD_COMPILE_DONE <json>`. `build-area.js` validates the marker's count, JSON payload, area id, output path, process status, and signal before starting Blender.

View File

@@ -1 +1,4 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
{"file":".trellis/spec/pipeline/external-tools.md","reason":"检查 CLI 子进程错误、signal 与日志处理是否符合宿主管线约定。"}
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"检查编译阶段、完成标记和 stage manifest 的跨层影响。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查配置、Node pipeline、Blender 消费链的边界没有漂移。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"检查两个有效区域的严格基线 parity。"}

View File

@@ -0,0 +1,44 @@
# Phase 2独立仓库与 CLI 边界设计
## Architecture
P1 已将实现收敛到 `packages/road-compiler/`。P2 把该目录以保留历史的方式导出为独立 package 仓库,保留两个明确方向的边界:
```
宿主 area config
-> scripts/lib/area-config.js
-> RoadCompilerInput JSON宿主 staging
-> @osm-asset/road-compiler CLI子进程
-> native-road/ + NATIVE_ROAD_COMPILE_DONE
-> build-area.js / Blender / preview
```
编译器不知道区域配置、宿主仓库、Blender 或宿主输出目录约定以外的输入路径。宿主不知道 compiler 内部源文件;它只拥有输入 JSON、CLI 的完成标记和写出的契约文件。
## CLI Contract
- CLI 接收一个 JSON 文件中的 `RoadCompilerInput`,而不是宿主的 area config。
- `comparisonDir` 继续作为可选输入,以维持现有 `comparison.json` 产物和 P0 baseline 的可比性。
- 成功只打印一次 `NATIVE_ROAD_COMPILE_DONE <JSON>`。payload 必须至少含 `areaId``output``roads``endpoints``diagnostics`
- `build-area.js` 保持同步批处理模式,子进程日志对用户可见;为了验证标记,输出同时被捕获或 tee。它对启动失败、非零状态、signal、缺失/重复/非法标记和 payload 与当前输入不一致都报错。
- 产物先由 compiler 的现有 staging/atomic promotion 逻辑写入目标 `native-road/`;宿主不接管这一写入过程。
## Repository Contents
独立仓库拥有compiler source、public API、CLI、check、workbench、fixture、两个 parity baseline、契约文档、README、package lockfile 和 workbench 的 `ol` 依赖。测试和 workbench 均必须在没有宿主 checkout 的环境运行。
宿主保留area-config 读取/归一化、`RoadCompilerInput` 映射、pipeline 阶段编排、Blender/preview、区域配置、运行产物和一份升级回归 baseline。宿主 spec 仅保留指针,契约正文随 compiler 仓库维护。
## History Extraction
导出只允许 `git subtree split``git filter-repo`。必须在独立仓库验证 `git log --follow src/compile/native-road.js`;验证的是迁移前的逻辑历史,而非仅 P1 的边界移动提交。导出和验证先在临时分支/clone 完成,外部远端创建和 push 必须使用用户给出的地址和授权范围。
## Dependency and Rollout
初始发布源定为私有 `https://git.app.que01.top/que01/road-compiler.git`。仓库以带注释 tag `v0.1.0` 首发,宿主以该精确 tag 作为依赖并写入 lockfile。开发临时形态可以指向独立 checkout 的本地 `file:` 依赖;它不能成为验收时的唯一消费方式。两个区域 parity 通过后删除 `packages/road-compiler/`;回滚由 revert 宿主消费改造实现,不能让 production host 继续直接 import 该目录。
## Compatibility and Risks
这是位置和调用方式迁移,不改变 compiler 行为。两个区域的 strict content/order hash 是主要 oracle信号文档的确定性生成仍应通过 parity 覆盖。P2 不处理 `check:area` 的历史 stage-manifest freshness warning也不把 Blender/Metal 沙箱问题归因为道路产物。
若外部 CLI 无法及时使用,回滚宿主消费 commit 即可;外部仓库历史和 tag 不需要删除。对于完整 Blender 构建macOS Metal 初始化必须在提权的宿主环境运行。

View File

@@ -1 +1,4 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
{"file":".trellis/spec/pipeline/external-tools.md","reason":"CLI 子进程必须沿用管线的启动、日志和失败状态语义。"}
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"编译是 Blender 前的 pipeline 输入阶段,需保持阶段与 stdout 契约。"}
{"file":".trellis/spec/config/index.md","reason":"宿主拥有区域配置归一化及 RoadCompilerInput 映射。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"本阶段声称产物不变,必须用严格 parity 验证。"}

View File

@@ -1,74 +1,55 @@
# Phase 2 执行计划
## Step 1 — 前置
执行前提:用户已在最新 P2 规划摘要后明确批准。发布目标已定为私有 `https://git.app.que01.top/que01/road-compiler.git`,首发 tag 为 `v0.1.0`
- [ ] Phase 1 的 AC1.1AC1.8 全绿
- [ ] 定档 §「待决策」四项(仓库名 / 托管 / 分发 / 过渡期策略)
## 1. 导出并核验历史
## Step 2 — 拆出仓库(保历史)
- [ ] 创建临时 export 分支或临时 clone使用 `git subtree split --prefix=packages/road-compiler``git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:` 导出。
- [ ] 在导出仓库验证 `git log --follow src/compile/native-road.js` 包含 2026-08-13 以来的 native compiler 历史。
- [ ] 在私有 `https://git.app.que01.top/que01/road-compiler.git` 创建并推送独立仓库;创建带注释的 `v0.1.0` tag。
## 2. 使编译器仓库自持
- [ ] 将 CLI 作为 package `bin` 入口,接受由宿主写出的 `RoadCompilerInput` JSON并继续输出唯一的 `NATIVE_ROAD_COMPILE_DONE` JSON 标记。
- [ ] 补全 `package.json`、锁文件和 `ol` 依赖workbench vendor 文件从自身安装目录提供。
- [ ] 迁入 `docs/native-road-package-v1.md`、两个 baseline 和它们的测试驱动,新增独立 README。
- [ ] 在不含宿主文件的临时 clone 内执行依赖安装、单元测试、两区域 parity 与 workbench 启动测试。
- [ ] grep 验证没有 `area-config``config/areas`、宿主项目名或宿主相对路径引用。
## 3. 宿主改为外部 CLI 消费
- [ ] 将 compiler 以精确 git tag `v0.1.0` 安装到宿主并记录 lockfile禁止范围版本、`latest``*` 和裸分支。
- [ ]`toRoadCompilerInput()` 序列化到每个区域的 pipeline staging 目录,传给 compiler CLI。
- [ ]`build-area.js` 的 blender 前置阶段调用 CLI。沿用管线的 `spawnSync` / `runCommand` 失败语义启动错误、exit status、signal和直通日志缓冲或 tee stdout 后,解析恰好一个完成标记并验证其 `areaId``output` 与当前区域匹配。
- [ ] 将 host workbench 的 fresh compile 回调切换到同一 CLI不改变 fresh-process 行为。
- [ ] 把所有 host 对 `packages/road-compiler/**` 的直接 import 替换成已安装包的公开 API 或 CLI两个区域 parity 均通过后删除 in-host 副本。
- [ ] 将宿主 pipeline spec 改为指向编译器仓库所拥有的契约文档。
## 4. 验证与发布门
新仓库(干净 clone
```bash
# 方案 Asubtree split
git subtree split --prefix=packages/road-compiler -b road-compiler-export
# 在新目录初始化并拉入该分支
# 方案 Bfilter-repo更彻底推荐
git clone --no-local . /tmp/road-compiler-split
cd /tmp/road-compiler-split
git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:
npm ci
npm test
npm run test:road-parity
npm run road:workbench -- --config test/fixtures/fengshu-er-road.input.json --no-compile
```
⚠️ 注意Phase 1 的搬迁若用了 `git mv`,历史可 `--follow` 追溯;
若用了删除+新建,`filter-repo` 只能追到 Phase 1。
**Phase 1 搬迁时必须用 `git mv`** —— 这条已在 Phase 1 implement Step 3 隐含,
此处显式记录依赖。
- [ ] 拆出后验证:`git log --follow src/compile/native-road.js | tail -20`
能看到 08-13 native-road-compiler 的提交
## Step 3 — 新仓库自持化
- [ ] `package.json` 补全依赖(含 K4 的 OpenLayers
- [ ] `npm install && npm test` 在新仓库独立通过
- [ ] 基线 JSON 迁入 `test/baseline/`
- [ ] 契约文档迁入 `docs/`
- [ ] README契约摘要 + 与宿主项目关系说明
## Step 4 — 宿主改造
- [ ] `package.json` 依赖指向新仓库(开发期 `file:`
- [ ] `build-area.js` 改子进程调用 + 解析 `NATIVE_ROAD_COMPILE_DONE`
- [ ] `area-config.js``toRoadCompilerInput()` 输出改为 CLI 参数或 input JSON 文件
- [ ] 删除 `packages/road-compiler/`(或按过渡期决策保留)
- [ ] `.trellis/spec/pipeline/` 加契约指针
## Step 5 — 验证
宿主两个有效区域的逐字节 parity
```bash
# 宿主端到端
npm run build:area -- --config config/areas/fengshu-er-road.json
# 三区域 parity
for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do
node scripts/road-parity.js --config config/areas/$a.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json || echo "FAIL $a"
done
# 反向依赖为 0在新仓库内跑
grep -rn "osm2streets-qgis-workflow\|area-config" . --exclude-dir=node_modules --exclude-dir=.git \
&& echo "VIOLATION"
# 锁版本检查
node -e 'const d=require("./package.json").dependencies;console.log(d)' | grep -i road
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/fengshu-er-road.json
node scripts/road-parity.js --config config/areas/nantaizi-lake-innovation-valley.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/nantaizi-lake-innovation-valley.json
```
- [ ] 在一台未 clone 宿主的环境(或 `/tmp` 全新 clone验证 AC2.2
## Review Gate
AC2.1AC2.7 全绿。特别是 AC2.2(脱离宿主可自测)—— 这是"独立可维护"的实质。
- [ ] 为 CLI 标记成功、缺失、重复、非法 JSON、areaId 不匹配和 output 不匹配补测试。
- [ ] 跑 package 单测、宿主 native-road / workbench / traffic signals / turn-lane-arrows 测试,以及两个 parity 检查。
- [ ] 使用 `trellis-check` 做最终跨层检查Blender 完整构建需以提权方式运行,原因是 macOS Metal 初始化不能在沙箱内启动。
## Rollback
- 宿主依赖改回 `file:packages/road-compiler`(若过渡期保留了该目录)
- `git revert` 宿主侧改造 commit新仓库留着不影响宿主
- 外部仓库和已发布 tag 保留不动;在宿主 revert 消费改造即可回到 P1 边界。
- 若按决定临时保留 in-host 副本,可将依赖回指该副本以恢复;该退路不取代 host parity 验证。

View File

@@ -1,80 +1,62 @@
# Phase 2拆仓库
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
技术设计:父任务 `design.md` §1.3消费方式、§2模块清单
## Goal
`packages/road-compiler/`保留 git 历史的独立仓库,
宿主改为锁版本依赖 + 子进程调用消费。
当前 `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 历史 🔴
### R2.1 保留 Git 历史
-`git subtree split``git filter-repo` 出,**不得**用 `cp` + `git init`
- 理由(父任务 R3.21695 行几何逻辑的 blame 是踩坑记录,
丢了以后没人敢改 `compileGeometry` 里任何一行
- 验证:新仓库内 `git log --follow src/compile/native-road.js` 能看到
08-13 native-road-compiler 以来的完整历史
-`git subtree split``git filter-repo` 出,不得以复制目录再 `git init` 替代。
- 新仓库中 `git log --follow src/compile/native-road.js` 必须能追溯到 P1 之前的 native-road compiler 提交。
### R2.2 子进程为主契约
### R2.2 新仓库可独立运行
- 宿主 `build-area.js` 改为 `execFileSync` 调编译器 CLI
解析 `NATIVE_ROAD_COMPILE_DONE` stdout 标记(父任务 design §1.3
- in-process `require` 可保留为可选优化路径,但不得是唯一路径
- 与既有 QGIS / GDAL / Blender 调用方式一致
(见 `.trellis/spec/pipeline/external-tools.md`
- 新仓库拥有 compiler、CLI、check、workbench、其测试 fixture、两个 parity baseline、契约文档和 README。
- 新仓库 own `ol` 及其 workbench 所需的运行依赖workbench 不得从宿主 `node_modules` 提供浏览器资源。
- 新仓库不得引用宿主的 `area-config``config/areas``scripts/` 或本仓库绝对路径
### R2.3 锁版本依赖
### R2.3 宿主的消费边界
- 开发期:`file:` 或 workspace 依赖
- 稳定后git tag / 私有 npm宿主 `package.json` **锁具体版本,不用 `latest`**
- 契约版本 `native-road-package/v1` 与包版本分开演进:
包可以发 patch契约版本只在破坏性变更时升
- `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 K4workbench 依赖自持
### R2.4 版本与迁移
- `road-workbench` 的 OpenLayers 从新仓库自己的 `node_modules` 提供
- import map 路径相应调整
### R2.5 基线迁移
- Phase 0 的三区域基线 JSON 搬进新仓库当测试语料(父任务 R4 第三条)
- 新仓库 CI/test 能独立跑 parity无需宿主在场
- **同时**宿主保留一份,用于验证升级编译器版本后产物未变
### R2.6 契约文档迁移
- `docs/native-road-package-v1.md` 搬进新仓库
- 宿主 `.trellis/spec/pipeline/` 留指针,说明契约由编译器仓库拥有
- 宿主依赖必须锁定一个具体编译器版本,禁止 `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` 能追到搬迁前的历史
- [ ] AC2.2 新仓库 `npm test` 在**未 clone 宿主**的机器上通过
- [ ] AC2.3 宿主从锁版本依赖构建,三区域 parity 对基线全绿
- [ ] AC2.4 `build-area.js` 走子进程路径,`NATIVE_ROAD_COMPILE_DONE` 被正确解析
- [ ] AC2.5 宿主 `package.json` 依赖为具体版本,非 `latest` / 非 `*`
- [ ] AC2.6 编译器仓库对宿主反向依赖数为 0父任务 AC8grep 验证)
- [ ] AC2.7 `npm run road:workbench` 在新仓库内独立可跑
## 依赖与顺序
- **前置**Phase 1 完成且 AC1.1AC1.8 全绿
- **阻塞**Phase 3、Phase 4
## 待决策(进入本阶段时定)
| 项 | 选项 |
|---|---|
| 仓库名 | `road-compiler` / `native-road-compiler` / `osm-road-compiler` |
| 托管 | GitHub 私有 / 公开 / 内部 git |
| 分发 | git tag 依赖 / 私有 npm registry |
| 宿主过渡期 | 是否保留 `packages/road-compiler/` 一段时间做双跑对照 |
- [ ] 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
- layer manifestPhase 3
- drawtonomy 扩展Phase 4
- 任何编译器内部逻辑改动 —— 本阶段代码内容不变,只换位置与消费方式
- 编译器几何、规则或输出内容改动。
- 图层 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 或其他托管平台。

View File

@@ -3,7 +3,7 @@
"name": "rc-p2-repo-split",
"title": "Phase 2拆仓库",
"description": "保留 git 历史拆出独立仓库,宿主以锁版本依赖消费,子进程为主契约",
"status": "planning",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,