feat: publish native road layer manifest

docs/native-road-package-v1.md

@@ -1,4 +1,8 @@
-# Native Road Package v1
+# Native Road Package v1.1
+
+`native-road-package/v1.1` adds a required `manifest.json` to the v1 output.
+Consumers may ignore this file when reading legacy v1 packages, but v1.1
+consumers must validate and consume it.
 
 `native-road-package/v1` defines the boundary between the host area pipeline
 and the native road compiler. The compiler accepts only the input below; it
@@ -35,6 +39,12 @@ shape and owns all path derivation.
 
 `outDir` contains these JSON documents:
 
+- `manifest.json`: `{ contract: "native-road-package/v1.1", areaId, layers }`.
+  `layers` declares exactly the twelve GeoJSON sources. Renderable entries have
+  `role` (`surface` or `marking`) and `materialLayer`; semantic entries have
+  `role: "semantic"` and no material. Optional `splitBy` contains one property
+  and exact-match cases plus one default case.
+
 - `compiled.json`: top-level keys are `schema`, `areaId`, `source`, `model`,
   `movements`, `trafficSignals`, `diagnostics`, and `layers`. `source` has
   `osm`, `overrides`, and `trafficSignals` paths.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osm-asset/road-compiler",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "type": "commonjs",
   "main": "src/index.js",

src/compile/compiler.js

@@ -4,6 +4,7 @@
 const fs = require("fs");
 const path = require("path");
 const { compileRoadModel, compileGeometry, loadOverrides, validateOverrides, writeJsonAtomic } = require("./native-road");
+const { LAYER_REGISTRY, manifestForArea, validatePublishedLayers } = require("./layer-manifest");
 const { loadOrGenerate, runtime } = require("../native-traffic-signals");
 
 function compileInput(input) {
@@ -53,7 +54,7 @@ function compileInput(input) {
       movements: compiled.movements,
       trafficSignals: { assemblies: "traffic-signal-assemblies.json", runtime: "traffic-signals.json", count: signalRuntime.signals.length },
       diagnostics: compiled.diagnostics,
-      layers: { roadSurface: "layers/road_surface.geojson", edgeLines: "layers/edge_lines.geojson", sidewalkSurface: "layers/sidewalk_surface.geojson", intersectionSurface: "layers/intersection_surface.geojson", laneCenterlines: "layers/lane_centerlines.geojson", laneSeparators: "layers/lane_separators.geojson", centerLines: "layers/center_lines.geojson", directionArrows: "layers/direction_arrows.geojson", turnArrows: "layers/turn_arrows.geojson", crosswalks: "layers/crosswalks.geojson", vehicleStopLines: "layers/vehicle_stop_lines.geojson", connectors: "layers/connectors.geojson" },
+      layers: Object.fromEntries(LAYER_REGISTRY.map((layer) => [layer.key, `layers/${layer.source}.geojson`])),
     };
     const comparison = compareOsm2Streets(area, result.model, compiled);
     writeJsonAtomic(path.join(staging, "compiled.json"), result);
@@ -61,18 +62,10 @@ function compileInput(input) {
     writeJsonAtomic(path.join(staging, "comparison.json"), comparison);
     writeJsonAtomic(path.join(staging, "traffic-signal-assemblies.json"), signalDocument.assemblies);
     writeJsonAtomic(path.join(staging, "traffic-signals.json"), signalRuntime);
-    writeJsonAtomic(path.join(staging, "layers", "road_surface.geojson"), compiled.roadSurface);
+    for (const layer of LAYER_REGISTRY) writeJsonAtomic(path.join(staging, "layers", `${layer.source}.geojson`), compiled[layer.key]);
-    writeJsonAtomic(path.join(staging, "layers", "edge_lines.geojson"), compiled.edgeLines);
+    const manifest = manifestForArea(area.id);
-    writeJsonAtomic(path.join(staging, "layers", "sidewalk_surface.geojson"), compiled.sidewalkSurface);
+    validatePublishedLayers(staging, manifest);
-    writeJsonAtomic(path.join(staging, "layers", "intersection_surface.geojson"), compiled.intersectionSurface);
+    writeJsonAtomic(path.join(staging, "manifest.json"), manifest);
-    writeJsonAtomic(path.join(staging, "layers", "lane_centerlines.geojson"), compiled.laneCenterlines);
-    writeJsonAtomic(path.join(staging, "layers", "lane_separators.geojson"), compiled.laneSeparators);
-    writeJsonAtomic(path.join(staging, "layers", "center_lines.geojson"), compiled.centerLines);
-    writeJsonAtomic(path.join(staging, "layers", "direction_arrows.geojson"), compiled.directionArrows);
-    writeJsonAtomic(path.join(staging, "layers", "turn_arrows.geojson"), compiled.turnArrows);
-    writeJsonAtomic(path.join(staging, "layers", "crosswalks.geojson"), compiled.crosswalks);
-    writeJsonAtomic(path.join(staging, "layers", "vehicle_stop_lines.geojson"), compiled.vehicleStopLines);
-    writeJsonAtomic(path.join(staging, "layers", "connectors.geojson"), compiled.connectors);
     fs.rmSync(area.outputs.nativeRoadDir, { recursive: true, force: true });
     fs.renameSync(staging, area.outputs.nativeRoadDir);
     return { area, result, comparison };

src/compile/layer-manifest.js

@@ -0,0 +1,49 @@
+"use strict";
+
+// The compiler's layer registry is the single source of truth for published
+// GeoJSON files and the Blender-facing manifest. Keep rendering details limited
+// to material slot names; the host owns the actual material definitions.
+const LAYER_REGISTRY = Object.freeze([
+  { key: "roadSurface", source: "road_surface", role: "surface", materialLayer: "road_surface" },
+  { key: "intersectionSurface", source: "intersection_surface", role: "surface", materialLayer: "intersection_surface" },
+  { key: "sidewalkSurface", source: "sidewalk_surface", role: "surface", materialLayer: "sidewalks" },
+  { key: "edgeLines", source: "edge_lines", role: "marking", materialLayer: "lane_separators" },
+  { key: "laneSeparators", source: "lane_separators", role: "marking", materialLayer: "lane_separators", splitBy: { prop: "color", cases: [{ match: "yellow", material: "native_lane_separator_yellow" }, { default: true, material: "lane_separators" }] } },
+  { key: "centerLines", source: "center_lines", role: "marking", materialLayer: "center_lines", splitBy: { prop: "color", cases: [{ match: "white", material: "native_center_line_white" }, { default: true, material: "center_lines" }] } },
+  { key: "crosswalks", source: "crosswalks", role: "marking", materialLayer: "crosswalks" },
+  { key: "vehicleStopLines", source: "vehicle_stop_lines", role: "marking", materialLayer: "vehicle_stop_lines" },
+  { key: "directionArrows", source: "direction_arrows", role: "marking", materialLayer: "lane_arrows_webscale" },
+  { key: "turnArrows", source: "turn_arrows", role: "marking", materialLayer: "lane_arrows_webscale" },
+  { key: "laneCenterlines", source: "lane_centerlines", role: "semantic" },
+  { key: "connectors", source: "connectors", role: "semantic" },
+]);
+
+function manifestForArea(areaId) {
+  return {
+    contract: "native-road-package/v1.1",
+    areaId,
+    layers: LAYER_REGISTRY.map(({ source, role, materialLayer, splitBy }) => ({
+      source,
+      role,
+      ...(materialLayer ? { materialLayer } : {}),
+      ...(splitBy ? { splitBy } : {}),
+    })),
+  };
+}
+
+function validatePublishedLayers(directory, manifest) {
+  const declared = new Set();
+  for (const layer of manifest.layers) {
+    if (!layer || typeof layer.source !== "string" || declared.has(layer.source)) throw new Error("Manifest has duplicate or invalid source.");
+    declared.add(layer.source);
+    const file = require("path").join(directory, "layers", `${layer.source}.geojson`);
+    if (!require("fs").existsSync(file)) throw new Error(`Manifest source is missing: ${layer.source}`);
+  }
+  const files = require("fs").existsSync(require("path").join(directory, "layers"))
+    ? require("fs").readdirSync(require("path").join(directory, "layers")).filter((name) => name.endsWith(".geojson")).map((name) => name.slice(0, -8))
+    : [];
+  const extras = files.filter((source) => !declared.has(source));
+  if (extras.length) throw new Error(`Unmanifested GeoJSON source: ${extras.join(", ")}`);
+}
+
+module.exports = { LAYER_REGISTRY, manifestForArea, validatePublishedLayers };

src/index.js

@@ -9,6 +9,7 @@ module.exports = {
   trafficSignals: require("./traffic-signals"),
   nativeTrafficSignals: require("./native-traffic-signals"),
   nativeRoad: require("./compile/native-road"),
+  layerManifest: require("./compile/layer-manifest"),
   compiler: require("./compile/compiler"),
   check: require("./check"),
 };

test/index.js

@@ -11,6 +11,12 @@ assert.equal(typeof compiler.turnLaneArrows.buildCustomTurnLaneArrows, "function
 assert.equal(typeof compiler.complexJunction.buildComplexJunctionGeometry, "function");
 assert.equal(typeof compiler.nativeRoad.compileRoadModel, "function");
 assert.equal(typeof compiler.check.checkOutput, "function");
+assert.equal(typeof compiler.layerManifest.manifestForArea, "function");
+const manifest = compiler.layerManifest.manifestForArea("fixture");
+assert.equal(manifest.contract, "native-road-package/v1.1");
+assert.equal(manifest.layers.length, 12);
+assert.deepEqual(manifest.layers.filter((layer) => layer.role === "semantic").map((layer) => layer.source), ["lane_centerlines", "connectors"]);
+assert.equal(manifest.layers.find((layer) => layer.source === "center_lines").splitBy.cases[0].match, "white");
 const fixture = path.join(__dirname, "fixtures", "fengshu-er-road.osm");
 assert.ok(fs.existsSync(fixture));
 assert.throws(() => compiler.compiler.validateInput({ id: "area" }), /RoadCompilerInput/);