Files
gods-eye-view/src/testSupport/viewerAccess.mjs
T
Sameh Khamis 8bcaced6ad Take the input dispatcher off Cesium: pointer input from the renderer's input port, picks from the query port
The dispatcher now builds on renderer.input and the query port, with
positions as plain {x, y}. Its viewer access count is zero and it leaves
the Cesium allow-list. Layers that read the raw engine pick read the Hit,
drawHit or event.native instead, and pickRegistry's resolvePickId and
pickContact take a Hit, with the raw versions kept in the Cesium adapter.

rendererOf gains findInput, provideUnboundInput and provideNativeClick.
event.native carries the engine's pick, drill and pickWindow, and picks
through the follow helper happen inside it. An unbound input port
survives the viewer being bound until it is released.

The query port's pick memo is now per task rather than per frame,
because Cesium's own picks advance the frame number. A click on the sky
skips the depth pass when nothing is on the ray. Touch contact search
keeps its eight-deep drill in a 14x14 window.
2026-11-09 00:47:30 -08:00

275 lines
9.1 KiB
JavaScript

/**
* @module testSupport/viewerAccess
* @description What `src/render/viewerAccess.test.mjs` and
* `scripts/viewer-access-baseline.mjs` count: Cesium-shaped access through
* a viewer, in runtime files that neither import Cesium (they are not on
* `src/render/cesiumAllowList.json`) nor are the Cesium adapter
* (`src/render/cesium/`).
*
* A hit is one of:
* - a viewer member Cesium owns, on anything named `viewer` (`viewer`,
* `_viewer`, `this.viewer`, `state.mainViewer`): `entities`,
* `dataSources`, `scene`, `camera`, `clock`, `imageryLayers`,
* `terrainProvider`, `trackedEntity`, `canvas`, plain, optional (`?.`),
* in brackets (`viewer['scene']`) or off a call (`getViewer().scene`),
* and any bracket access with a computed key (`viewer[name]`);
* - a scene member Cesium owns, on anything named `scene`
* (`viewer.scene.globe`, `scene?.pick`): `primitives`, `pick`,
* `drillPick`, `pickPosition`, `globe`, `preRender`, `postRender`,
* `preUpdate`, `postUpdate`, `canvas`, `requestRender`, `camera`;
* - any of those names taken out by destructuring
* (`const { scene } = viewer`, `({ globe } = viewer.scene)`,
* `({ viewer: { scene } }) => ...`).
*
* Not hits: `viewer.container` (a DOM element; `canvasOf(viewer)` is the
* way to the canvas), comments, and access through another name
* (`const v = viewer; v.scene`), which only a type checker could follow.
* Names are matched by their ending, so a viewer that is not Cesium's
* (`panoViewer.camera`) counts too: name it otherwise.
* Runtime files are every `.js`, `.mjs`, `.cjs` and `.vue` file under
* `src/`, `server/` and `dev/`, except tests and test support (the same
* set the Cesium allow-list reads).
*/
import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { parsers } from 'prettier/plugins/babel.mjs';
import { parse as parseSfc } from 'vue/compiler-sfc';
export const ROOT = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../..',
);
export const CESIUM_LIST = 'src/render/cesiumAllowList.json';
export const BASELINE = 'src/render/viewerAccessAllowList.json';
/** How to lower the baseline once files stop reaching through the viewer. */
export const UPDATE_COMMAND = 'node scripts/viewer-access-baseline.mjs';
/** Viewer members Cesium owns. */
export const VIEWER_MEMBERS = new Set([
'entities',
'dataSources',
'scene',
'camera',
'clock',
'imageryLayers',
'terrainProvider',
'trackedEntity',
'canvas',
]);
/** Scene members Cesium owns. */
export const SCENE_MEMBERS = new Set([
'primitives',
'pick',
'drillPick',
'pickPosition',
'globe',
'preRender',
'postRender',
'preUpdate',
'postUpdate',
'canvas',
'requestRender',
'camera',
]);
const SCOPES = ['src', 'server', 'dev'];
/** Not runtime code, though not named `.test`: imported by tests only. */
const TEST_ONLY = new Set([
'src/input/testDoubles.mjs',
'src/layers/recentImagery/testDoubles.mjs',
'src/layers/weather/shellFixture.mjs',
'src/overlays/worldOverlayAllocation.worker.mjs',
]);
const isTestSupport = (file) =>
/\.test\.[cm]?js$/.test(file) ||
file.startsWith('src/testSupport/') ||
file.startsWith('src/tooling/') ||
TEST_ONLY.has(file);
const isAdapter = (file) => file.startsWith('src/render/cesium/');
const VIEWER_NAME = /viewer$/i;
const SCENE_NAME = /scene$/i;
/** A member's name when it is written out: `.x`, `['x']`, `` [`x`] ``. */
function staticKey(node, computed) {
if (!node) return undefined;
if (!computed) return node.name ?? node.value;
if (node.type === 'StringLiteral') return node.value;
if (node.type === 'TemplateLiteral' && node.expressions.length === 0)
return node.quasis[0]?.value?.cooked;
return undefined;
}
/**
* The name an expression ends in: `viewer`, `x._viewer`, `this.scene`, and
* a call's callee (`getViewer()`).
*/
function tailName(node) {
if (!node) return undefined;
if (node.type === 'Identifier') return node.name;
if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression')
return tailName(node.callee);
if (
node.type === 'MemberExpression' ||
node.type === 'OptionalMemberExpression'
)
return staticKey(node.property, node.computed);
if (
node.type === 'TSNonNullExpression' ||
node.type === 'ParenthesizedExpression'
)
return tailName(node.expression);
return undefined;
}
/** Whether `name` read off something named `owner` is a hit. */
function isHit(owner, name, computedUnknown = false) {
if (owner === undefined) return false;
if (VIEWER_NAME.test(owner))
return computedUnknown || VIEWER_MEMBERS.has(name);
if (SCENE_NAME.test(owner)) return SCENE_MEMBERS.has(name);
return false;
}
/**
* The hits in a script's source, each with its line and what it reads.
* @param {string} source
* @returns {Array<{line: number, access: string}>}
*/
export function viewerAccessHits(source) {
const hits = [];
const note = (node, owner, name) =>
hits.push({ line: node.loc?.start?.line ?? 0, access: `${owner}.${name}` });
/** Names a destructuring pattern takes out of something named `owner`. */
const destructured = (pattern, owner) => {
if (pattern?.type !== 'ObjectPattern' || owner === undefined) return;
for (const property of pattern.properties) {
if (property.type === 'RestElement') continue;
const name = staticKey(property.key, property.computed);
if (isHit(owner, name, property.computed && name === undefined))
note(property, owner, name ?? '[computed]');
}
};
/** A viewer or scene taken out and destructured in turn:
* `{ viewer: { scene } }`, `{ scene: { globe } = {} }`. */
const nested = (pattern) => {
for (const property of pattern.properties) {
if (property.type === 'RestElement') continue;
const name = staticKey(property.key, property.computed);
if (!name || !(VIEWER_NAME.test(name) || SCENE_NAME.test(name))) continue;
const value =
property.value?.type === 'AssignmentPattern'
? property.value.left
: property.value;
destructured(value, name);
}
};
function walk(node) {
if (!node || typeof node !== 'object') return;
if (Array.isArray(node)) return node.forEach(walk);
switch (node.type) {
case 'MemberExpression':
case 'OptionalMemberExpression': {
const owner = tailName(node.object);
const name = staticKey(node.property, node.computed);
if (isHit(owner, name, node.computed && name === undefined))
note(node, owner, name ?? '[computed]');
break;
}
case 'VariableDeclarator':
destructured(node.id, tailName(node.init));
break;
case 'AssignmentExpression':
// A default: `function f({ camera } = viewer)`.
case 'AssignmentPattern':
destructured(node.left, tailName(node.right));
break;
case 'ObjectPattern':
nested(node);
break;
}
for (const [key, value] of Object.entries(node)) {
if (
['loc', 'comments', 'tokens', 'extra', 'leadingComments'].includes(key)
)
continue;
if (value && typeof value === 'object') walk(value);
}
}
walk(parsers.babel.parse(source));
return hits.sort((a, b) => a.line - b.line);
}
/** The hits in a single-file component's scripts, read by Vue's own
* parser, at their lines in the file. */
function vueHits(file, source) {
const { descriptor, errors } = parseSfc(source, { filename: file });
if (errors.length) throw errors[0];
return [descriptor.script, descriptor.scriptSetup]
.filter(Boolean)
.flatMap((block) =>
viewerAccessHits(block.content).map((hit) => ({
...hit,
line: hit.line + block.loc.start.line - 1,
})),
);
}
/** The hits in a repository file. */
export function fileHits(file, root = ROOT) {
const source = readFileSync(path.join(root, file), 'utf8');
return file.endsWith('.vue')
? vueHits(file, source)
: viewerAccessHits(source);
}
/**
* The runtime files the count covers: off the Cesium list, outside the
* adapter, not tests.
*/
export function countedFiles(root = ROOT) {
const cesiumList = new Set(
JSON.parse(readFileSync(path.join(root, CESIUM_LIST), 'utf8')),
);
return execFileSync(
'git',
[
'ls-files',
'-z',
'--cached',
'--others',
'--exclude-standard',
'--',
...SCOPES,
],
{ cwd: root, encoding: 'utf8' },
)
.split('\0')
.filter(
(file) =>
file &&
/\.(?:[cm]?js|vue)$/.test(file) &&
!isTestSupport(file) &&
!isAdapter(file) &&
!cesiumList.has(file) &&
existsSync(path.join(root, file)),
);
}
/** Each counted file with hits: file → its hits. */
export function currentHits(root = ROOT) {
const out = new Map();
for (const file of countedFiles(root)) {
const hits = fileHits(file, root);
if (hits.length) out.set(file, hits);
}
return out;
}
/** The committed baseline: file → hits allowed. */
export function readBaseline(root = ROOT) {
return JSON.parse(readFileSync(path.join(root, BASELINE), 'utf8'));
}