63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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, `manifest.json`, and GeoJSON layers under `outDir`. Since `native-road-package/v1.1`, `manifest.json` is required: it declares every GeoJSON source, whether its role is renderable (`surface` / `marking`) or semantic, and the host material slot for renderable layers. The Blender adapter rejects a missing or invalid manifest, a declared/published GeoJSON mismatch, and an unknown material slot. 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:
|
|
|
|
```js
|
|
require("../packages/road-compiler/src/compile/compiler");
|
|
```
|
|
|
|
Correct:
|
|
|
|
```js
|
|
spawnSync(process.execPath, [compilerCli(), "--input", inputFile]);
|
|
```
|