Ratchet Cesium-shaped viewer access in files off the Cesium list

A second ratchet beside the Cesium allow-list: files off that list (and
outside the Cesium adapter) may no longer reach Cesium through the viewer
either. src/render/viewerAccessAllowList.json records, per file, how many
such accesses it still makes (the viewer's entities, dataSources, scene,
camera, clock, imageryLayers, terrainProvider, trackedEntity and canvas;
the scene's primitives, pick, drillPick, pickPosition, globe, frame
events, canvas, requestRender and camera), read from the parsed source in
their plain, optional, bracketed, call-result and destructured forms.
viewer.container, comments and tests do not count.

The test fails when a file makes more accesses than recorded, when a
recorded count is higher than the file now needs or names a file gone or
back on the Cesium list, and when the record grows against origin/main.
scripts/viewer-access-baseline.mjs lowers the record to what the files
hold; it never adds or raises an entry. The record starts with 25 files
and 50 accesses.
This commit is contained in:
Sameh Khamis committed 2026-11-07 19:44:15 -08:00
1 parent 0f9bd23829
commit 396e7f0deb
7 files changed
+557

No files matched your search

+273
View File
@@ -0,0 +1,273 @@
/**
* @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/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'));
}