@expofp/wayfinding-compiler 0.0.0-bootstrap.0

package/dist/lib/diagnostics.js

@@ -0,0 +1,634 @@
+import { planDecimals } from './scale.js';
+/**
+ * A stage point in plan units, rounded as the emit rounds.
+ * @param at The point, in meters.
+ * @param unit Plan units per meter.
+ * @returns The point in plan units.
+ */
+function planPoint(at, unit) {
+    const decimals = planDecimals(unit);
+    return [+(at[0] * unit).toFixed(decimals), +(at[1] * unit).toFixed(decimals)];
+}
+/**
+ * One POI's key among the facts: its floor and its place in that floor's source list.
+ * @param layer The floor.
+ * @param index The source position.
+ * @returns The key.
+ */
+export function poiKey(layer, index) {
+    return `${layer}\u0000${index}`;
+}
+/**
+ * The kind of source object a validator code is about, read off the code's own prefix.
+ * @param code The validator code.
+ * @returns The kind of object it names.
+ */
+function refKindOf(code) {
+    if (code.startsWith('destination-'))
+        return 'destination';
+    if (code.startsWith('transition-'))
+        return 'transition';
+    return 'layer';
+}
+/**
+ * The validator's findings as facts of the input stage.
+ * @param issues What `validateWayfindingSource` returned.
+ * @returns One diagnostic per issue, in the validator's order.
+ */
+export function fromSourceIssues(issues) {
+    return issues.map((issue) => {
+        const ref = {
+            kind: refKindOf(issue.code),
+            ...(issue.layer !== undefined && { layer: issue.layer }),
+            ...(issue.index !== undefined && { index: issue.index }),
+            ...(issue.id !== undefined && { id: issue.id }),
+        };
+        return {
+            code: issue.code,
+            severity: issue.severity,
+            stage: 'input',
+            message: issue.message,
+            ...(issue.layer !== undefined && { layer: issue.layer }),
+            ...(issue.layer !== undefined || issue.id !== undefined || issue.index !== undefined
+                ? { ref }
+                : {}),
+        };
+    });
+}
+/**
+ * The scale the plan was read at, when the plan did not state one.
+ * @param unitsPerMeter The source's `unitsPerMeter`.
+ * @returns A fact when the plan was read as meters by default.
+ */
+export function fromScale(unitsPerMeter) {
+    if (unitsPerMeter !== undefined)
+        return [];
+    return [
+        {
+            code: 'units-assumed-meters',
+            severity: 'info',
+            stage: 'scale',
+            message: 'the plan states no units per meter; it is read as meters',
+        },
+    ];
+}
+/** What each way of reading a footprint's shape says, one sentence per {@link FootprintShape}. */
+const SHAPE_MESSAGES = {
+    traced: 'the footprint outline is traced from its drawn pieces',
+    hull: 'the drawn pieces fill their convex hull, which stands in for the outline',
+    rectilinear: 'the drawn pieces join into a short axis-aligned outline',
+    bounds: 'the drawn pieces trace no simple outline, so their bounding box stands in',
+    'bounds-oversized': 'the mesh is too fine to trace, so its bounding box stands in for the shape',
+    dock: 'the drawn pieces enclose no area, so the dock stands in for the footprint',
+};
+/**
+ * What normalization did to one layer's drawing before any geometry was built off it.
+ * @param source The layer as given.
+ * @param facts What the layer's normalization returned.
+ * @param ids The id each source position compiled under.
+ * @param unit Plan units per meter, for the facts' geometry.
+ * @returns Wall facts in entry order, then POI facts in source order.
+ */
+export function fromNormalize(source, facts, ids, unit = 1) {
+    const layer = source.layer;
+    const out = [];
+    const openings = new Map(facts.openings.map((o) => [o.id, o]));
+    const unopened = new Set(facts.entrancesUnopened);
+    for (const { entry, runs, oddTail } of facts.wallEntries) {
+        if (runs === 0)
+            out.push({
+                code: 'wall-entry-empty',
+                severity: 'warning',
+                stage: 'normalize',
+                message: 'the wall entry cleans to no wall piece and is dropped',
+                layer,
+                ref: { kind: 'wall', layer, index: entry },
+            });
+        if (runs > 1)
+            out.push({
+                code: 'wall-entry-split',
+                severity: 'info',
+                stage: 'normalize',
+                message: `the wall entry describes ${runs} separate runs, not one polyline`,
+                layer,
+                ref: { kind: 'wall', layer, index: entry },
+                facts: { runs },
+            });
+        if (oddTail)
+            out.push({
+                code: 'wall-entry-odd-length',
+                severity: 'warning',
+                stage: 'normalize',
+                message: 'the wall entry holds an odd count of numbers; the last one names no point and is dropped',
+                layer,
+                ref: { kind: 'wall', layer, index: entry },
+            });
+    }
+    const shapes = new Map(facts.shapes.map((shape) => [shape.id, shape]));
+    const clipped = new Set(facts.clipped);
+    const crossable = new Map(facts.crossable.map((cross) => [cross.id, cross]));
+    source.destinations.forEach((destination, index) => {
+        const id = ids[index];
+        const ref = { kind: 'destination', layer, index, id: destination.id };
+        const shape = shapes.get(id);
+        const cross = crossable.get(id);
+        if (shape)
+            out.push({
+                code: 'footprint-shape',
+                severity: shape.how === 'bounds-oversized' ? 'warning' : 'info',
+                stage: 'normalize',
+                message: SHAPE_MESSAGES[shape.how],
+                layer,
+                ref,
+                facts: { how: shape.how, parts: shape.parts },
+            });
+        if (clipped.has(id))
+            out.push({
+                code: 'footprint-clipped',
+                severity: 'info',
+                stage: 'normalize',
+                message: 'the footprint ran over its walls and is cut back to the largest piece they leave',
+                layer,
+                ref,
+            });
+        const opening = openings.get(id);
+        if (opening)
+            out.push({
+                code: 'entrance-openings',
+                severity: 'info',
+                stage: 'normalize',
+                message: opening.by === 'crossing'
+                    ? `routes reach the entrance through the wall inside its bounds, at ${opening.at.length} place(s)`
+                    : opening.by === 'doorway'
+                        ? `the entrance stands ${opening.distance ?? 0} m outside the building; routes reach it through the doorway the walls leave`
+                        : `the entrance stands ${opening.distance ?? 0} m outside the building; routes reach it through the nearest wall with floor behind it`,
+                layer,
+                ref,
+                geometry: opening.at.map((at) => ({ type: 'point', layer, at: planPoint(at, unit) })),
+                facts: {
+                    by: opening.by,
+                    openings: opening.at.length,
+                    ...(opening.distance !== undefined && { distance: opening.distance }),
+                },
+            });
+        if (unopened.has(id))
+            out.push({
+                code: 'entrance-no-wall',
+                severity: 'info',
+                stage: 'normalize',
+                message: 'the entrance stands across no wall and is reached like any POI',
+                layer,
+                ref,
+            });
+        if (cross)
+            out.push({
+                code: 'crossable-inferred',
+                severity: 'warning',
+                stage: 'normalize',
+                message: cross.by === 'holds-another'
+                    ? 'the footprint holds other destinations, so it is walked in, not around'
+                    : 'the footprint stands before the only way into another destination, so routes may cross it',
+                layer,
+                ref,
+                facts: { by: cross.by, ...(cross.victims && { victims: cross.victims }) },
+            });
+    });
+    return out;
+}
+/**
+ * A floor too large to build routes over: it is left unbuilt rather than run the compile out of memory.
+ * @param layer The layer id.
+ * @param width The floor's extent across, in meters.
+ * @param height The floor's extent down, in meters.
+ * @param destinations How many POI the source puts on this floor.
+ * @returns One fact about the floor.
+ */
+export function fromOversize(layer, width, height, destinations) {
+    return [
+        {
+            code: 'floor-too-large',
+            severity: 'warning',
+            stage: 'walkable',
+            message: 'the floor spans more than routes are built over, so no floor is built',
+            layer,
+            ref: { kind: 'layer', layer },
+            facts: { widthM: +width.toFixed(1), heightM: +height.toFixed(1), destinations },
+        },
+    ];
+}
+/**
+ * What the walkable stage made of one floor, decided by the stage's counts rather than the rounded area.
+ * @param layer The layer id.
+ * @param stats The walkable stage's counts.
+ * @param destinations How many POI the source puts on this floor.
+ * @returns One fact about the floor.
+ */
+export function fromWalkable(layer, stats, destinations) {
+    const ref = { kind: 'layer', layer };
+    const counts = { walls: stats.walls, outerContours: stats.outerContours, rings: stats.rings };
+    if (stats.walls === 0) {
+        // A floor with nothing drawn on it at all is an empty draft, not a failure.
+        if (destinations === 0)
+            return [];
+        return [
+            {
+                code: 'layer-no-walls',
+                severity: 'warning',
+                stage: 'walkable',
+                message: 'the layer has POI but no walls, so no floor is built',
+                layer,
+                ref,
+                facts: { ...counts, destinations },
+            },
+        ];
+    }
+    if (stats.outerContours === 0)
+        return [
+            {
+                code: 'layer-no-outer-contour',
+                severity: 'warning',
+                stage: 'walkable',
+                message: 'no wall run closes into an outer contour, so no floor is built',
+                layer,
+                ref,
+                facts: { ...counts, destinations },
+            },
+        ];
+    if (stats.rings === 0)
+        return [
+            {
+                code: 'floor-carved-away',
+                severity: 'warning',
+                stage: 'walkable',
+                message: 'the outer contour closes, but walls and footprints cover all of it',
+                layer,
+                ref,
+                facts: { ...counts, destinations },
+            },
+        ];
+    return [
+        {
+            code: 'floor-built',
+            severity: 'info',
+            stage: 'walkable',
+            message: 'the floor is built',
+            layer,
+            ref,
+            facts: { ...counts, areaM2: stats.areaExact ?? stats.area },
+        },
+    ];
+}
+/**
+ * What the route-network stage reported for one floor: POI left without a dock, and the part count
+ * before the emit.
+ * @param source The layer as given.
+ * @param stats The network stage's counts.
+ * @param unit Plan units per meter, for the facts' geometry.
+ * @param ids The id each source position compiled under; the source ids by default.
+ * @returns The facts, POI in source order.
+ */
+export function fromNetwork(source, stats, unit = 1, ids = source.destinations.map(({ id }) => id)) {
+    const layer = source.layer;
+    const unreached = new Map(stats.unreached.map((u) => [u.id, u]));
+    const out = [];
+    // Matched by the id each POI compiled under. Transition pads are not in the source: their loss is
+    // reported as the shaft's orphan.
+    source.destinations.forEach((destination, index) => {
+        const fact = unreached.get(ids[index]);
+        if (fact === undefined)
+            return;
+        // The stub tip, in plan units like every emitted point.
+        const at = fact.at && planPoint(fact.at, unit);
+        out.push({
+            code: 'destination-unreached',
+            severity: 'warning',
+            stage: 'network',
+            message: `the POI got no dock a route can end at (${fact.reason})`,
+            layer,
+            ref: { kind: 'destination', layer, index, id: destination.id },
+            ...(at && { geometry: [{ type: 'point', layer, at }] }),
+            facts: {
+                reason: fact.reason,
+                ...(fact.outside !== undefined && { outside: fact.outside }),
+                ...(fact.nearestWall !== undefined && { nearestWall: fact.nearestWall }),
+                ...(fact.floorBehind !== undefined && { floorBehind: fact.floorBehind }),
+                ...(fact.by !== undefined && { by: fact.by }),
+            },
+        });
+    });
+    const layerRef = { kind: 'layer', layer };
+    if (stats.doorways !== undefined)
+        out.push({
+            code: 'doorways-found',
+            severity: 'info',
+            stage: 'network',
+            message: `the walls leave ${stats.doorways} doorway(s) on the layer`,
+            layer,
+            ref: layerRef,
+            facts: { count: stats.doorways },
+        });
+    if (stats.shortcuts !== undefined && stats.shortcuts > 0)
+        out.push({
+            code: 'network-shortcuts',
+            severity: 'info',
+            stage: 'network',
+            message: `${stats.shortcuts} shortcut link(s) are cut in where the network sent a route the long way round`,
+            layer,
+            ref: layerRef,
+            facts: { count: stats.shortcuts },
+        });
+    if (stats.untiedPieces !== undefined && stats.untiedPieces > 0)
+        out.push({
+            code: 'network-pieces-untied',
+            severity: 'warning',
+            stage: 'network',
+            message: `the layer's network is left in ${stats.untiedPieces + 1} pieces: the growth found no lawful link and no floor path between them`,
+            layer,
+            ref: layerRef,
+            facts: { pieces: stats.untiedPieces + 1 },
+        });
+    if (stats.unservedFloorPieces !== undefined && stats.unservedFloorPieces > 0)
+        out.push({
+            code: 'floor-pieces-unserved',
+            severity: 'info',
+            stage: 'network',
+            message: `${stats.unservedFloorPieces} walkable floor piece(s) hold no destination and no doorway, so no network is built over them`,
+            layer,
+            ref: layerRef,
+            facts: { count: stats.unservedFloorPieces },
+        });
+    if (stats.components !== undefined)
+        out.push({
+            code: 'network-parts-before-emit',
+            severity: 'info',
+            stage: 'network',
+            message: `the layer's network has ${stats.components} part(s) before the emit, shafts not counted`,
+            layer,
+            ref: { kind: 'layer', layer },
+            facts: { count: stats.components },
+        });
+    return out;
+}
+/**
+ * What collapsed on the centimeter grid as one layer's network was emitted as v1 edges.
+ * @param source The layer as given.
+ * @param collapsed What `emitLayerV1` returned.
+ * @param collapsed.collapsedSegments Path segments skipped: both ends snap to one node.
+ * @param collapsed.collapsedDocks Docks whose line is lost while their `lineEnd` still stands.
+ * @param ids The id each source position compiled under; the source ids by default.
+ * @returns One fact for the segments, then one per collapsed dock, in dock order.
+ */
+export function fromEmit(source, collapsed, ids = source.destinations.map(({ id }) => id)) {
+    const layer = source.layer;
+    const out = [];
+    if (collapsed.collapsedSegments > 0)
+        out.push({
+            code: 'path-segment-collapsed',
+            severity: 'info',
+            stage: 'emit',
+            message: `${collapsed.collapsedSegments} path segment(s) collapse to a point on the centimeter grid and emit no line`,
+            layer,
+            ref: { kind: 'layer', layer },
+            facts: { count: collapsed.collapsedSegments },
+        });
+    // Matched by the id each POI compiled under, like `fromNetwork`; a transition pad has no source
+    // position and keeps the compile id alone.
+    for (const id of collapsed.collapsedDocks) {
+        const index = ids.indexOf(id);
+        const destination = source.destinations[index];
+        out.push({
+            code: 'dock-collapsed',
+            severity: 'warning',
+            stage: 'emit',
+            message: 'the dock collapses to a point on the centimeter grid: its line end is emitted with no line of its own',
+            layer,
+            ref: {
+                kind: 'destination',
+                layer,
+                ...(index >= 0 && { index }),
+                id: destination?.id ?? id,
+            },
+        });
+    }
+    return out;
+}
+/**
+ * The stops of a shaft that never reached the graph, and the shafts left joining nothing.
+ * @param orphans The orphans, in plan units.
+ * @param singleFloor Shafts whose attached stops all stand on one floor.
+ * @param unit Plan units per meter, for the shafts' geometry.
+ * @returns One fact per stop, then one per such shaft.
+ */
+export function fromTransitions(orphans, singleFloor = [], unit = 1) {
+    const stops = orphans.map((orphan) => {
+        const known = orphan.reason === 'no-dock';
+        return {
+            code: known ? 'transition-stop-no-dock' : 'transition-stop-unknown-layer',
+            severity: 'warning',
+            stage: 'transitions',
+            message: known
+                ? 'a transition stop got no dock on its layer, so the shaft does not reach that floor'
+                : 'a transition stop names a layer the plan does not have',
+            layer: orphan.layer,
+            ref: {
+                kind: 'transition-stop',
+                layer: orphan.layer,
+                ...(orphan.transitionId !== undefined && { id: orphan.transitionId }),
+            },
+            ...(known && {
+                geometry: [
+                    { type: 'point', layer: orphan.layer, at: [orphan.x, orphan.y] },
+                ],
+            }),
+            facts: {
+                reason: orphan.reason,
+                ...(orphan.pointId !== undefined && { pointId: orphan.pointId }),
+            },
+        };
+    });
+    const shafts = singleFloor.map(({ transition, layer, at }) => ({
+        code: 'transition-single-floor',
+        severity: 'warning',
+        stage: 'transitions',
+        message: 'the shaft docked on one floor only, so it connects nothing',
+        layer,
+        ref: {
+            kind: 'transition',
+            layer,
+            ...(transition.id !== undefined && { id: transition.id }),
+        },
+        geometry: at.map((tip) => ({ type: 'point', layer, at: planPoint(tip, unit) })),
+        facts: { kind: transition.kind },
+    }));
+    return [...stops, ...shafts];
+}
+/**
+ * Where each transition stop rides in: on the dock of the destination it stands in, or on a pad of its
+ * own; and a stop standing in several destinations, which rides in on the smallest.
+ * @param plan The stops as `planTransitions` resolved them, in meters.
+ * @param unit Plan units per meter, for the geometry.
+ * @returns One fact per stop, and a warning per ambiguous one.
+ */
+export function fromStops(plan, unit) {
+    // A repeated name compiles under a suffixed key; the plan knows it by the name.
+    const named = (id) => id.split('\u0000')[0];
+    return plan.stops.flatMap(({ transition, point, destinationId, pad, alsoIn }) => {
+        const where = {
+            layer: point.layer,
+            ref: {
+                kind: 'transition-stop',
+                layer: point.layer,
+                ...(transition.id !== undefined && { id: transition.id }),
+            },
+            geometry: [
+                {
+                    type: 'point',
+                    layer: point.layer,
+                    at: [point.x * unit, point.y * unit],
+                },
+            ],
+        };
+        const pointId = point.id !== undefined ? { pointId: point.id } : {};
+        const bound = {
+            code: 'transition-stop-bound',
+            severity: 'info',
+            stage: 'transitions',
+            message: pad
+                ? 'the transition stop stands in the open and gets a pad of its own'
+                : `the transition stop rides in on the dock of "${named(destinationId)}"`,
+            ...where,
+            facts: { ...pointId, pad, ...(!pad && { destination: named(destinationId) }) },
+        };
+        if (!alsoIn.length)
+            return [bound];
+        return [
+            bound,
+            {
+                code: 'transition-stop-ambiguous',
+                severity: 'warning',
+                stage: 'transitions',
+                message: `the transition stop stands in ${alsoIn.length + 1} destinations and rides in on the smallest`,
+                ...where,
+                facts: { ...pointId, destinations: [destinationId, ...alsoIn].map(named) },
+            },
+        ];
+    });
+}
+/**
+ * What the emitted graph connects, as facts: parts, POI off the main part, POI bound to nothing, and the
+ * ends the binding cannot settle.
+ * @param reachability What `readReachability` read off the graph.
+ * @param facts The input and stage facts so far, to check the binding against.
+ * @returns The facts, in part order and then POI order.
+ */
+export function fromReachability(reachability, facts) {
+    const out = [];
+    const unreached = new Set(facts
+        .filter(({ code }) => code === 'destination-unreached')
+        .map(({ ref }) => poiKey(ref?.layer ?? '', ref?.index ?? -1)));
+    // Floors the network stage never ran on report no POI either way — over size, or over a
+    // layer-scoped input error: the same rule the compile skips them by.
+    const skipped = new Set(facts
+        .filter(({ code, stage, severity, layer }) => code === 'floor-too-large' ||
+        (stage === 'input' && severity === 'error' && layer !== undefined))
+        .map(({ layer }) => layer));
+    // POI the compile left out over a coordinate that is not a number: the input fact says it all.
+    const excluded = new Set(facts
+        .filter(({ code }) => code === 'destination-coordinate-not-finite')
+        .map(({ ref }) => poiKey(ref?.layer ?? '', ref?.index ?? -1)));
+    if (reachability.parts.length > 1)
+        out.push({
+            code: 'network-split',
+            severity: 'warning',
+            stage: 'reachability',
+            message: `the emitted graph falls into ${reachability.parts.length} parts`,
+            facts: {
+                nodes: reachability.parts.map((part) => part.nodes),
+                poi: reachability.parts.map((part) => part.poi.length),
+            },
+        });
+    for (const { ref, part, split } of reachability.poi) {
+        const where = { layer: ref.layer, ref: { kind: 'destination', ...ref } };
+        const reported = unreached.has(poiKey(ref.layer, ref.index));
+        if (part > 0)
+            out.push({
+                code: 'destination-on-detached-part',
+                severity: 'warning',
+                stage: 'reachability',
+                message: 'the POI is bound to a part of the graph the main part does not reach',
+                ...where,
+                facts: { part },
+            });
+        if (part < 0)
+            out.push({
+                code: 'destination-unbound',
+                severity: 'warning',
+                stage: 'reachability',
+                message: 'no line end lies inside the POI',
+                ...where,
+            });
+        if (split)
+            out.push({
+                code: 'destination-split-across-parts',
+                severity: 'warning',
+                stage: 'reachability',
+                message: 'the POI has line ends on more than one part',
+                ...where,
+            });
+        // The stage decides by name and the binding by ring: when they disagree, one of them is wrong.
+        if (reported !== part < 0 &&
+            !skipped.has(ref.layer) &&
+            !excluded.has(poiKey(ref.layer, ref.index)))
+            out.push({
+                code: 'binding-mismatch',
+                severity: 'warning',
+                stage: 'reachability',
+                message: reported
+                    ? 'the network stage reports the POI unreached, yet a line end lies inside it'
+                    : 'the network stage reports the POI reached, yet no line end lies inside it',
+                ...where,
+            });
+    }
+    if (reachability.unownedEnds.length)
+        out.push({
+            code: 'line-end-unowned',
+            severity: 'warning',
+            stage: 'reachability',
+            message: `${reachability.unownedEnds.length} line end(s) lie inside no POI and start no shaft`,
+            facts: { ends: reachability.unownedEnds },
+        });
+    if (reachability.sharedEnds.length)
+        out.push({
+            code: 'line-end-shared',
+            severity: 'warning',
+            stage: 'reachability',
+            message: `${reachability.sharedEnds.length} line end(s) lie inside more than one POI`,
+            facts: { ends: reachability.sharedEnds.map(({ end }) => end) },
+        });
+    return out;
+}
+/** What each breached invariant says, one sentence per {@link InvariantFinding}'s code. */
+const INVARIANT_MESSAGES = {
+    'line-crosses-wall': 'the line crosses a wall of its layer',
+    'line-crosses-poi': 'the line passes through a destination it is not serving',
+    'dock-outside-ring': 'the dock ends inside no ring a destination is bound by',
+};
+/**
+ * The emitted graph's breached invariants as facts of the graph stage; debug mode only.
+ * @param findings What `checkGraphInvariants` found.
+ * @returns One diagnostic per finding, in the checker's order.
+ */
+export function fromGraphInvariants(findings) {
+    return findings.map(({ code, layer, lines, at }) => ({
+        code,
+        severity: 'warning',
+        stage: 'graph',
+        message: INVARIANT_MESSAGES[code],
+        layer,
+        ref: { kind: 'layer', layer },
+        geometry: [
+            { type: 'lines', layer, lines },
+            ...(at ? [{ type: 'point', layer, at }] : []),
+        ],
+    }));
+}