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.

Scope / Trigger

This contract applies to native-road compilation from scripts/build-area.js, scripts/compile-native-roads.js, and the road workbench fresh-compile callback.

Signatures

road-compiler --input <RoadCompilerInput.json>

RoadCompilerInput contains areaId, absolute osmFile, outDir, stagingDir, overridesFile, trafficSignalsFile, optional comparisonDir, and options.

Contracts

The compiler writes compiled.json, diagnostics.json, comparison.json, signal runtime files, and GeoJSON layers under outDir. On success stdout contains exactly one marker whose JSON includes areaId, roads, endpoints, diagnostics, and output.

Validation & Error Matrix

Condition	Required result
CLI cannot start	throw the spawn error
non-zero exit or signal	fail with status/signal
zero completion markers	fail
multiple completion markers	fail
malformed marker JSON	fail
marker `areaId` or `output` mismatch	fail

Good / Base / Bad Cases

Good: host writes an absolute input JSON, runs the installed exact-tag CLI, validates one marker, then starts Blender.
Base: compiler emits deterministic files and no optional comparison source exists.
Bad: host imports compiler source, reads config/areas inside the package, or accepts a missing/duplicate marker.

Tests Required

scripts/test-road-compiler-cli.js asserts marker success, missing, duplicate, malformed, area mismatch, and output mismatch cases.
scripts/road-parity.js compares contentHash, orderHash, feature counts, and byte counts for both supported areas.
npm run test:road-workbench asserts the workbench is loaded from the installed package.

Wrong vs Correct

Wrong:

require("../packages/road-compiler/src/compile/compiler");

Correct:

spawnSync(process.execPath, [compilerCli(), "--input", inputFile]);

2.6 KiB Raw Blame History