Files
gods-eye-view/src/render/unboundCamera.test.mjs
T
Sameh Khamis 6c1f91014c Draw imported files through the draw port, off Cesium
Import no longer loads KML, KMZ, GeoJSON and GPX through Cesium's data
source loaders. geoImportFeatures.js reads the sanitized file into plain
pins, lines, walls, polygons and ground overlays with the looks those
loaders gave them: icon, scale, colour, heading and hot spot, the shared
and inline style precedence, line and polygon colours and widths,
extruded and clamped geometry, rotated boxes and quads, and GeoJSON's
48 px pins, draped lines along rhumb lines and quarter-opacity fills.
geoImportPins.js draws them in three draw sets per file, places ground
pins through the height service (0 on the bare ellipsoid, whose coarse
tiles sag below it; the mesh nearby on photoreal maps), follows a
double-clicked pin, frames Fly-to, and shows, hides and removes them.

The Cesium adapter now draws two members the contract already had: an
icon's pixel offset and the wall shape. Image fills draw in the
translucent pass, so an overlay's own alpha blends as it did.

The Cesium allow-list is now empty; the ratchet test checks that its
scan still sees each way of reaching Cesium. The QA scripts read what a
file drew through the import's drawn(id), and the large-file check
compares it with Cesium's own reading of the same KML. A file the
renderer refuses to draw is refused by itself, without stopping its
batch. Two translations no longer used are dropped.
2026-11-09 15:50:53 -08:00

443 lines
18 KiB
JavaScript

/**
* A public entry that reaches the renderer bridge (`rendererOf.js`) may hand
* `cameraOf` a viewer of the caller's own, with no renderer bound. The
* bridge builds a camera port for it with the factory the Cesium adapter
* provides as `render/cesium/camera.js` loads, so every such entry must load
* that module too. It loads `render/cesium/credits.js`, whose factory
* builds `findCredits`' port for such a viewer the same way.
* Likewise an entry that reaches a caller of `findEffects` must load
* `render/cesium/effects.js`, which provides the effects factory, and one
* that reaches a caller of `findGlobe` must load `render/cesium/globe.js`,
* or be such a Cesium-free entry (below).
* An entry that reaches a caller of `findDraw` or `drawOf` loads
* `render/cesium/draw.js` the same way (the camera factory loads it),
* unless it is Cesium-free: then it is listed in `DRAW_FROM_CALLER`, and
* a caller handing it a viewer with no renderer bound loads the package's
* `./render/cesium/unbound` export once. An entry that reaches a caller of
* `findQuery` or `queryOf` loads `render/cesium/query.js`, and one that
* reaches a caller of `findFrame` or `frameOf` loads
* `render/cesium/frame.js` (the camera factory loads both), or is such a
* Cesium-free entry.
*
* The graph is every static import, re-export and literal dynamic import of
* the entry's module and those it reaches, read by the parsers the Cesium
* ratchet uses; bare specifiers (packages) end the walk.
*/
import assert from 'node:assert/strict';
import { existsSync, readFileSync, statSync } from 'node:fs';
import path from 'node:path';
import test from 'node:test';
import { fileURLToPath } from 'node:url';
import { parsers } from 'prettier/plugins/babel.mjs';
import { parse as parseSfc } from 'vue/compiler-sfc';
const root = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../..',
);
const BRIDGE = 'src/render/rendererOf.js';
const FACTORY = 'src/render/cesium/camera.js';
const EFFECTS_FACTORY = 'src/render/cesium/effects.js';
const GLOBE_FACTORY = 'src/render/cesium/globe.js';
const DRAW_FACTORY = 'src/render/cesium/draw.js';
const QUERY_FACTORY = 'src/render/cesium/query.js';
const FRAME_FACTORY = 'src/render/cesium/frame.js';
const INPUT_FACTORY = 'src/render/cesium/input.js';
const NATIVE_CLICK = 'src/render/cesium/nativeClick.js';
const UNBOUND = 'src/render/cesium/unbound.js';
/**
* Entries that take their Cesium code injected: the module named here is
* GEV's Cesium side for them, and must load the factories. Given another, the
* entry's flight finds no camera (`findCamera`) and does nothing. None is
* left: visual settings, once given their viewer by the application shell,
* now leave the factories to their caller as the shell does.
*/
const INJECTED = {};
/**
* Modules whose use of the bridge holds up without the factory: with no
* port they read Cesium's `trackedEntity` instead, which is all an unbound
* viewer can follow by.
*/
const FALLS_BACK = new Set(['src/data/followed.js']);
/**
* Cesium-free entries that draw through `drawOf`: their own modules cannot
* load the Cesium adapter (the Cesium ratchet), so a viewer with no
* renderer bound draws once its owner has loaded `./render/cesium/unbound`;
* until then `drawOf` throws, naming it, rather than draw nothing. That
* export loads the camera factory too, so these entries' camera is the
* caller's to load the same way.
*/
const DRAW_FROM_CALLER = new Set([
'./layers/earthquakes',
'./layers/bikeshare',
'./layers/gnss',
'./layers/perimeters',
'./layers/awareness',
'./layers/submarine-cables',
'./layers/alpr',
'./layers/vessels',
'./layers/street-level',
'./layers/street-level/mapillary',
'./layers/street-level/kartaview',
'./layers/street-level/panoramax',
'./layers/air-quality',
'./layers/directions',
// Its icons, wireframes, volumes, plane and gizmo draw through `drawOf`;
// it picks, projects and reads the eye and the globe through the ports.
'./layers/cctv',
// Its heat cells and fire glows draw through `drawOf`; its cards and LOD
// watcher read the eye, projection and frames through the ports.
'./layers/firms',
// Its station dots, clusters and selected marker draw through `drawOf`;
// it clusters them on screen through the camera and query ports.
'./layers/radio',
// Its site dots, outlines and selected fill draw through `drawOf`; it
// follows a site and reads the globe through the camera and globe ports.
'./layers/installations',
// Its dots, tracked dot and orbit rings draw through `drawOf`; it follows,
// ticks, projects and reads the eye through the ports.
'./layers/satellites',
// Its data packs draw through `drawOf`; its flights ask `cameraOf`, which
// throws until then too.
'./scenes',
// Asks `findQuery` instead, and answers null rather than throw until the
// caller has loaded the factory.
'./queries/heights',
// Their fleet icons draw through `drawOf`; they take clicks through the
// dispatcher (`findInput`, `findQuery`).
'./layers/flights',
'./layers/military',
// Its layers draw, size, fly and take clicks through the ports alone.
'./infrastructure',
'./infrastructure/geojson',
// Its missions draw, pick and fly through the ports alone.
'./layers/launches',
// Its world marks draw through `drawOf` and probe heights through
// `heightsOf`; its screen marks project through the camera and query ports.
'./annotations',
// Its pins, footprints and outlines draw through `drawOf`; its horizon
// cull reads the camera and frame ports.
'./layers/ghostmaps',
// Its moving and still vehicle icons draw through `drawOf`; it projects,
// culls, follows and samples floors through the ports.
'./layers/transit',
// Its layer draws and reads the view through the ports alone, and its mesh
// floor sampler asks the camera, globe and query ports.
'./layers/transit/standalone',
// Its dots and heat-lines draw through `drawOf`; it reads the eye, the
// surface (its identity and whether it has loaded) and heights through
// the camera, globe and query ports.
'./layers/traffic',
// It configures the sources of layers, the traffic layer's among them,
// that draw and read the surface through the ports alone.
'./application/sources',
// The layer catalog and the standalone catalog over it: their layers, the
// weather shells and the wind flow and relief among them, draw, read the
// eye and shade the globe through the ports alone.
'./application/layers',
'./standalone/catalog',
// The application's tools (scene director, annotations, embed views,
// Import): they draw, fly and take clicks through the ports.
'./application/tools',
]);
/**
* Cesium-free entries that reach the camera port but draw nothing: given a
* viewer with no renderer bound, they find no camera
* (`findCamera` is null) and leave it alone until the caller loads
* `./render/cesium/unbound`.
*/
const CAMERA_FROM_CALLER = new Set([
// The click dispatcher: it takes input, picks and grounds through
// `findInput`, `findQuery` and the adapter's native clicks.
'./input',
// It loads no factory: Cockpit moves the camera on the frame port's
// preUpdate, and
// `frameOf` throws, naming the export, until the caller has loaded it.
'./ui/cockpit',
'./ui/navigation',
'./voice/commands',
'./voice/controller',
// It loaded the camera factory only through the CCTV layer it took a
// constant from.
'./voice/actions',
'./voice/realtime-session',
// It flies through `findCamera` and drapes through `findGlobe`; the
// renderer the application gives it (`rendering.js`, which draws the box
// preview through `drawOf`) is Cesium-free too.
'./layers/recent-imagery',
// Its ground snap, mesh floor sampler, annotation resolver and location
// framing ask the camera, globe and query ports; it loads no factory.
'./application/operations',
// It shows its source's credit through `findCredits`, and switches stacks
// through the map engine that `./render/cesium/unbound` provides too.
'./maps/controller',
// The application shell and what assembles it: their controls fly, read
// the eye, shade the globe and set styles through the ports alone; the
// application's renderer is bound to its viewer, and a viewer of the
// renderer bound gets its ports from `./render/cesium/unbound`.
'./ui/shell',
'./ui/composition',
'./ui/hud',
'./ui/visual-settings',
'./application/controls',
'./application/data',
]);
const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
/** The browser module an export resolves to, or null for Node-only ones. */
function browserTarget(declaration) {
if (typeof declaration === 'string') return declaration;
if (!declaration || typeof declaration !== 'object') return null;
for (const condition of ['browser', 'import', 'default']) {
const target = browserTarget(declaration[condition]);
if (target) return target;
}
return null;
}
function specifiersOf(file) {
let code = readFileSync(path.join(root, file), 'utf8');
if (file.endsWith('.vue')) {
const { descriptor } = parseSfc(code, { filename: file });
code = [descriptor.script, descriptor.scriptSetup]
.filter(Boolean)
.map((block) => block.content)
.join('\n');
}
const found = [];
const walk = (node) => {
if (!node || typeof node !== 'object') return;
if (Array.isArray(node)) return node.forEach(walk);
if (
(node.type === 'ImportDeclaration' ||
node.type === 'ExportNamedDeclaration' ||
node.type === 'ExportAllDeclaration') &&
node.source
)
found.push({ specifier: node.source.value, lazy: false });
if (
node.type === 'ImportExpression' &&
node.source?.type === 'StringLiteral'
)
found.push({ specifier: node.source.value, lazy: true });
if (
node.type === 'CallExpression' &&
node.callee?.type === 'Import' &&
node.arguments[0]?.type === 'StringLiteral'
)
found.push({ specifier: node.arguments[0].value, lazy: true });
for (const key of Object.keys(node))
if (key !== 'loc' && key !== 'start' && key !== 'end') walk(node[key]);
};
walk(parsers.babel.parse(code));
return found;
}
/** A relative specifier as a repository file, or null when it is a package. */
function resolve(from, specifier) {
const bare = specifier.split('?')[0];
if (!bare.startsWith('.')) return null;
const base = path.join(path.dirname(from), bare);
const candidates = ['', '.js', '.mjs', '.vue', '/index.js', '/index.mjs'];
for (const suffix of candidates) {
const full = path.join(root, base + suffix);
if (existsSync(full) && statSync(full).isFile())
return path.normalize(base + suffix);
}
// A subgraph dropped here would hide a missing factory.
throw new Error(`${from}: cannot resolve ${specifier}`);
}
/**
* The modules `entry` reaches. With `eager`, only through static imports:
* what has loaded once the entry has, before any lazy import resolves.
*/
function reachable(entry, { eager = false } = {}) {
const seen = new Set([entry]);
const queue = [entry];
while (queue.length) {
const file = queue.pop();
if (!/\.(m?js|vue)$/.test(file)) continue;
for (const { specifier, lazy } of specifiersOf(file)) {
if (eager && lazy) continue;
const next = resolve(file, specifier);
if (next === BRIDGE && FALLS_BACK.has(file)) continue;
if (next && !seen.has(next)) {
seen.add(next);
queue.push(next);
}
}
}
return seen;
}
test('the unbound camera factory loads the unbound credits factory', () => {
assert.ok(
reachable(FACTORY, { eager: true }).has('src/render/cesium/credits.js'),
);
});
test('every public entry that reaches the renderer bridge loads the unbound camera factory', () => {
const missing = [];
let bridged = 0;
for (const [key, declaration] of Object.entries(pkg.exports)) {
const target = browserTarget(declaration);
if (typeof target !== 'string' || !target.startsWith('./src/')) continue;
const entry = path.normalize(target.slice(2));
const graph = reachable(entry);
// Any path to the bridge counts, lazy or not; only an eager one loads
// the factory in time for the first `cameraOf`.
if (!graph.has(BRIDGE)) continue;
bridged += 1;
const carrier = INJECTED[key];
const loads = (file) => reachable(file, { eager: true }).has(FACTORY);
if (DRAW_FROM_CALLER.has(key)) continue;
if (CAMERA_FROM_CALLER.has(key)) {
assert.ok(!loads(entry), `${key} loads the factory: unlist it`);
continue;
}
if (!loads(entry) && !(carrier && loads(carrier))) missing.push(key);
}
assert.ok(bridged > 0, 'no entry reaches the bridge: the walk is broken');
assert.deepEqual(
missing,
[],
`These entries can reach cameraOf without ${FACTORY}; import it where the entry first reaches the bridge.`,
);
});
/**
* Every public entry reaching a caller of `lookup` loads `factory`. With
* `reached`, at least one entry must reach one, or the walk is broken.
* With `fromCaller`, the Cesium-free entries listed in
* `DRAW_FROM_CALLER` may leave the factory to their caller.
*/
function checkLookupFactory(
lookup,
factory,
{ reached = true, fromCaller = false } = {},
) {
const missing = [];
let reaching = 0;
const calls = (file) =>
!file.startsWith('src/render/') &&
/\.(m?js|vue)$/.test(file) &&
new RegExp(`\\b${lookup}\\b`).test(
readFileSync(path.join(root, file), 'utf8'),
);
for (const [key, declaration] of Object.entries(pkg.exports)) {
const target = browserTarget(declaration);
if (typeof target !== 'string' || !target.startsWith('./src/')) continue;
const entry = path.normalize(target.slice(2));
if (![...reachable(entry)].some(calls)) continue;
reaching += 1;
if (
fromCaller &&
(DRAW_FROM_CALLER.has(key) || CAMERA_FROM_CALLER.has(key))
)
continue;
const carrier = INJECTED[key];
const loads = (file) => reachable(file, { eager: true }).has(factory);
if (!loads(entry) && !(carrier && loads(carrier))) missing.push(key);
}
if (reached)
assert.ok(reaching > 0, `no entry reaches ${lookup}: the walk is broken`);
assert.deepEqual(
missing,
[],
`These entries can reach ${lookup} without ${factory}; import it where the entry first reaches the lookup.`,
);
}
test('every public entry that reaches a findEffects caller loads the unbound effects factory, or its caller can', () => {
checkLookupFactory('findEffects', EFFECTS_FACTORY, { fromCaller: true });
});
test('every public entry that reaches a findGlobe caller loads the unbound globe factory', () => {
// A caller may take `findGlobe` as a default rather than call it, so any
// use of the name counts. A Cesium-free entry with no globe port (its
// caller has not loaded `./render/cesium/unbound`) reads the globe as
// unknown.
checkLookupFactory('findGlobe', GLOBE_FACTORY, { fromCaller: true });
});
test('every public entry that reaches a findQuery or queryOf caller loads the unbound query factory, or its caller can', () => {
checkLookupFactory('findQuery', QUERY_FACTORY, { fromCaller: true });
checkLookupFactory('queryOf', QUERY_FACTORY, {
reached: false,
fromCaller: true,
});
});
test('every public entry that reaches a findFrame or frameOf caller loads the unbound frame factory, or its caller can', () => {
checkLookupFactory('findFrame', FRAME_FACTORY, { fromCaller: true });
checkLookupFactory('frameOf', FRAME_FACTORY, {
reached: false,
fromCaller: true,
});
});
test('every public entry that reaches a findInput or nativeClickOf caller loads the unbound input factory and native clicks, or its caller can', () => {
checkLookupFactory('findInput', INPUT_FACTORY, { fromCaller: true });
checkLookupFactory('nativeClickOf', NATIVE_CLICK, { fromCaller: true });
});
test('the unbound camera factory loads the unbound query, frame and input factories and native clicks', () => {
const loaded = reachable(FACTORY, { eager: true });
assert.ok(loaded.has(QUERY_FACTORY));
assert.ok(loaded.has(FRAME_FACTORY));
assert.ok(loaded.has(INPUT_FACTORY));
assert.ok(loaded.has(NATIVE_CLICK));
});
test('the unbound export brings every unbound factory', () => {
const loaded = reachable(UNBOUND, { eager: true });
for (const factory of [
FACTORY,
EFFECTS_FACTORY,
DRAW_FACTORY,
QUERY_FACTORY,
FRAME_FACTORY,
INPUT_FACTORY,
NATIVE_CLICK,
'src/render/cesium/credits.js',
])
assert.ok(loaded.has(factory), factory);
});
test('every public entry that reaches a findDraw caller loads the unbound draw factory, or its caller can', () => {
const missing = [];
const callsFindDraw = (file) =>
!file.startsWith('src/render/') &&
/\.(m?js|vue)$/.test(file) &&
/\b(findDraw|drawOf)\(/.test(readFileSync(path.join(root, file), 'utf8'));
assert.equal(
pkg.exports['./render/cesium/unbound'],
`./${UNBOUND}`,
'the factory loads through this export',
);
for (const [key, declaration] of Object.entries(pkg.exports)) {
const target = browserTarget(declaration);
if (typeof target !== 'string' || !target.startsWith('./src/')) continue;
const entry = path.normalize(target.slice(2));
if (![...reachable(entry)].some(callsFindDraw)) continue;
const carrier = INJECTED[key];
const loads = (file) => reachable(file, { eager: true }).has(DRAW_FACTORY);
if (DRAW_FROM_CALLER.has(key)) {
assert.ok(!loads(entry), `${key} loads the factory: unlist it`);
continue;
}
if (!loads(entry) && !(carrier && loads(carrier))) missing.push(key);
}
assert.deepEqual(
missing,
[],
`These entries can reach findDraw without ${DRAW_FACTORY}; import it, or list a Cesium-free entry in DRAW_FROM_CALLER.`,
);
});