2.6 KiB
Phase 1 Technical Design
Boundary
packages/road-compiler/ becomes the single implementation owner for native
road compilation. It is a CommonJS workspace package with explicit public
entrypoints for compiler APIs, traffic-signal schema, turn-lane helpers, OSM
parsing, reference conversion, and CLIs. It never imports area-config, reads
config/areas, or derives host paths.
The host owns scripts/lib/area-config.js and maps normalized configuration to
the v1 RoadCompilerInput shape using toRoadCompilerInput(area). During P1,
build-area.js calls the package in-process; P2 is the only phase that changes
that call to a child process.
Source Ownership and Compatibility
The following current scripts/lib implementations move into package src:
native-road, complex-junction, turn-lane-arrows, lane-geometry,
gaode-junction-reference, native-traffic-signals, and osm.
Some moved modules also serve legacy host paths: QGIS uses turn-lane arrows, vehicle preview and reimport use OSM parsing, and preview tests use lane geometry. Those consumers import the package entrypoints after the move. This preserves one implementation while allowing host -> package dependency.
Traffic signal ownership follows the matrix in
research/traffic-signals-split-matrix.md: schema, geometry, validation, and
runtime construction move to the package. The host retains only two file-I/O
adapters, readTrafficSignalFeatures() and readTrafficSignals(), both
delegating to package exports. No duplicated schema code remains.
Input and Path Handling
The package compiler API accepts only RoadCompilerInput from
docs/native-road-package-v1.md. Package CLI commands accept an explicit JSON
input file (--input) and never load area configuration. The compatibility
host CLI still accepts --config, but immediately maps it through
toRoadCompilerInput() before entering the package.
junctionTemplates.*.referenceFile changes to a path relative to its area
configuration. readAreaConfig() resolves it while normalizing configuration;
the package receives an absolute path and does no path resolution.
Tests and Rollout
The package receives the required Fengshu OSM fixture plus migrated unit tests.
Its npm test must run from the package directory without reading host inputs
or outputs. After each source batch, run the two Phase 0 parity baselines. The
existing host command names remain compatibility wrappers through P1.
Rollback is a normal Git revert of the latest batch commit. No module has a parallel host copy after its batch lands, preventing divergence.