diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d9e8060d..fad301d94 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -138,6 +138,7 @@ The highest-leverage places to jump in: - **Vue 3 + Pinia for the interface,** [CesiumJS](https://cesium.com/platform/cesiumjs/) for the globe and [Vite](https://vitejs.dev/) to build. See [Building UI](#building-ui). - **Assembly lives in `src/app/`; standalone defaults live in `src/standalone/`.** UI controllers live in `src/ui/`, layer factories in `src/layers/`, portable sources in `src/sources/`, and application operations in `src/services/`. Existing `src/data/.js` entries retain compatibility; new code belongs with its focused owner. +- **Reach the renderer through its contract** ([docs/RENDERER-CONTRACT.md](docs/RENDERER-CONTRACT.md#moving-code-onto-the-contract)): `findDraw`, `findCamera` and the other ports in `src/render/rendererOf.js`, not Cesium or the viewer's `scene`, `camera` or `entities`. Two ratchet tests hold this: only files on `src/render/cesiumAllowList.json` may import Cesium, and `src/render/viewerAccessAllowList.json` caps the viewer accesses each other file still makes. Neither list may grow; when you port code off them, shrink them (`node scripts/viewer-access-baseline.mjs` lowers the second). - Sources acquire records; renderers own Cesium resources. Import `gods-eye-view/layers//source` when only a source factory is needed. Common voice controls consume the session interface; protocol adapters own connection details. - **Secrets stay server-side.** Anything needing a private key goes through a local proxy under `server/providers/`. The browser only ever sees the Google Maps key (which you restrict) and ephemeral tokens. - `docs/CURRENT-STATE.md` is the authoritative runtime reference — read it first. diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index b5b296721..8e4d6a970 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -72,6 +72,34 @@ and each capability member present without its capability. `contract.test.mjs` type-checks the contract under strict TypeScript, and fails when `PORTS` and the types disagree on a single member. +## Moving code onto the contract + +Two ratchet tests keep code that has moved onto the contract from drifting +back to Cesium. Both lists only ever shrink. + +- `src/render/cesiumAllowList.json` lists the files outside the Cesium + adapter (`src/render/cesium/`) that may still import or be handed Cesium + (`src/render/noCesiumOutsideRender.test.mjs`). A file leaves the list + when it no longer drives Cesium at all; nothing is added. +- `src/render/viewerAccessAllowList.json` counts, per file off that list, + the Cesium-shaped accesses through the viewer it still makes + (`src/render/viewerAccess.test.mjs`): the viewer's `entities`, + `dataSources`, `scene`, `camera`, `clock`, `imageryLayers`, + `terrainProvider`, `trackedEntity` and `canvas`, and the scene's + `primitives`, `pick`, `drillPick`, `pickPosition`, `globe`, `preRender`, + `postRender`, `preUpdate`, `postUpdate`, `canvas`, `requestRender` and + `camera`, written plainly, with `?.`, in brackets or destructured. + `viewer.container` is a DOM element and does not count; reach the canvas + through `canvasOf(viewer)`. Comments and tests do not count. + `src/testSupport/viewerAccess.mjs` is the matcher. + A file may not make more accesses than recorded (a file not listed may + make none), and a count higher than the file now needs fails too. So a + file that leaves the Cesium list must port its viewer accesses in the + same change: it cannot be added to the count. After + porting accesses away, run `node scripts/viewer-access-baseline.mjs` (or + `--check` to see what it would change): it lowers counts and drops + entries, and never adds or raises one. + ## The stub renderer `createStubRenderer({ capabilities, viewport, time })` implements every port diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 7652b5ea2..3a0fedb0c 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -690,6 +690,10 @@ "src/render/cesium/appRenderer.test.mjs", "src/render/noCesiumOutsideRender.test.mjs", "src/render/cesiumAllowList.json", + "src/render/viewerAccess.test.mjs", + "src/render/viewerAccessAllowList.json", + "src/testSupport/viewerAccess.mjs", + "scripts/viewer-access-baseline.mjs", "src/geo/geo.test.mjs", "src/geo/celestial.test.mjs", "src/geo/quaternion.test.mjs", diff --git a/scripts/viewer-access-baseline.mjs b/scripts/viewer-access-baseline.mjs new file mode 100644 index 000000000..4a2614a9b --- /dev/null +++ b/scripts/viewer-access-baseline.mjs @@ -0,0 +1,63 @@ +/** + * Lower `src/render/viewerAccessAllowList.json` to the Cesium-shaped viewer + * accesses the files off the Cesium list still hold + * (`src/render/viewerAccess.test.mjs`). It only lowers counts and drops + * entries (files with none left, gone, or back on the Cesium list); it never + * adds a file or raises a count. A file over its count is reported and the + * script exits 1: port that access instead. + * + * `--check` reports what it would change without writing, and exits 1 when + * there is anything to lower. + */ +import { writeFileSync } from 'node:fs'; +import path from 'node:path'; +import { + BASELINE, + countedFiles, + currentHits, + readBaseline, + ROOT, +} from '../src/testSupport/viewerAccess.mjs'; + +const check = process.argv.includes('--check'); +const baseline = readBaseline(); +const hits = currentHits(); +const counted = new Set(countedFiles()); + +const next = {}; +const changes = []; +for (const [file, allowed] of Object.entries(baseline)) { + const found = counted.has(file) ? (hits.get(file)?.length ?? 0) : 0; + const count = Math.min(allowed, found); + if (count > 0) next[file] = count; + if (count !== allowed) changes.push(`${file}: ${allowed} → ${count}`); +} +const over = [...hits] + .filter(([file, found]) => found.length > (baseline[file] ?? 0)) + .map( + ([file, found]) => + `${file}: ${found.length} found, ${baseline[file] ?? 0} recorded`, + ); + +if (changes.length) { + console.log( + `${check ? 'Would lower' : 'Lowered'}:\n ${changes.join('\n ')}`, + ); + if (!check) { + const sorted = Object.fromEntries( + Object.keys(next) + .sort() + .map((file) => [file, next[file]]), + ); + writeFileSync( + path.join(ROOT, BASELINE), + `${JSON.stringify(sorted, null, 2)}\n`, + ); + } else process.exitCode = 1; +} else console.log(`${BASELINE} is as low as it goes.`); +if (over.length) { + console.error( + `Over their counts (never raised; port these):\n ${over.join('\n ')}`, + ); + process.exitCode = 1; +} diff --git a/src/render/viewerAccess.test.mjs b/src/render/viewerAccess.test.mjs new file mode 100644 index 000000000..5eb6b6665 --- /dev/null +++ b/src/render/viewerAccess.test.mjs @@ -0,0 +1,161 @@ +/** + * The second ratchet, beside `noCesiumOutsideRender.test.mjs`: files off + * the Cesium allow-list may not import Cesium, and they may not drive it + * through the viewer either (`viewer.scene`, `scene.primitives`, + * `viewer.trackedEntity`...). `viewerAccessAllowList.json` records, per + * file, how many such accesses each still has; a file may have no more + * than recorded (none, unrecorded), and a recorded count that is now too + * high fails too, so the record only ever shrinks. What counts is in + * `src/testSupport/viewerAccess.mjs`; `node scripts/viewer-access-baseline.mjs` + * lowers the record to what the files now hold (it never raises it). + */ +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import test from 'node:test'; +import { + BASELINE, + countedFiles, + currentHits, + readBaseline, + ROOT, + UPDATE_COMMAND, + viewerAccessHits, +} from '../testSupport/viewerAccess.mjs'; + +const baseline = readBaseline(); +const hits = currentHits(); + +const describe = (file) => + (hits.get(file) ?? []) + .map(({ line, access }) => ` ${file}:${line} ${access}`) + .join('\n'); + +test('the matcher catches Cesium-shaped access through a viewer', () => { + const caught = { + 'viewer.scene.requestRender();': 2, + 'viewer?.scene?.globe?.show;': 2, + 'this.viewer.camera.flyTo(x);': 1, + 'layerState._viewer.entities.add(e);': 1, + 'state.mainViewer.dataSources;': 1, + 'viewer.clock.currentTime;': 1, + 'viewer.imageryLayers.add(l);': 1, + 'viewer.terrainProvider;': 1, + 'viewer.trackedEntity = undefined;': 1, + "viewer['scene'];": 1, + 'viewer[`camera`];': 1, + 'viewer?.["entities"];': 1, + 'viewer[name];': 1, + 'scene.primitives.add(p);': 1, + 'scene?.pick(position);': 1, + 'scene.drillPick(p, 8);': 1, + 'scene.preRender.addEventListener(f);': 1, + 'scene.postRender;': 1, + 'scene.preUpdate;': 1, + 'scene.postUpdate;': 1, + 'scene.canvas.style;': 1, + 'scene.camera;': 1, + 'this._scene.globe;': 1, + 'const { scene } = viewer;': 1, + 'const { scene: s, camera } = viewer;': 2, + 'let g; ({ globe: g } = viewer.scene);': 2, + 'const { primitives } = this.scene;': 1, + '(viewer).scene;': 1, + 'viewer.canvas.style;': 1, + 'scene.pickPosition(p);': 1, + 'getViewer().scene;': 1, + 'this.getViewer?.().camera;': 1, + 'const { viewer: { scene } } = state;': 1, + 'function f({ viewer: { camera } }) {}': 1, + 'const { scene: { globe } = {} } = viewer;': 2, + 'const { [key]: e } = viewer;': 1, + 'function f({ camera } = viewer) {}': 1, + 'const { value: { camera } = viewer } = options;': 1, + }; + for (const [source, count] of Object.entries(caught)) + assert.equal(viewerAccessHits(source).length, count, source); + const allowed = [ + 'viewer.container.append(el);', + 'viewer?.container;', + 'const { container } = viewer;', + '// viewer.scene.requestRender();', + '/* scene.primitives.add(p) */', + "const s = 'viewer.scene';", + 'viewers[0];', + 'viewer.isDestroyed();', + 'scenes.camera;', + 'sceneDoc.camera;', + 'renderer.canvas;', + 'const v = viewer; v.something;', + 'camera.pose();', + 'cameraOf(viewer).flyTo(x);', + 'const { scene } = options;', + 'const { viewer: { container } } = state;', + 'getViewer().container;', + ]; + for (const source of allowed) + assert.deepEqual(viewerAccessHits(source), [], source); +}); + +test('off-list files reach through the viewer no more than recorded', () => { + const over = []; + for (const [file, found] of hits) { + const allowed = baseline[file] ?? 0; + if (found.length > allowed) + over.push( + ` ${file}: ${found.length} accesses, ${allowed} recorded\n${describe(file)}`, + ); + } + assert.deepEqual( + over, + [], + `Cesium-shaped access through the viewer in files off the Cesium list.\n` + + `Reach the renderer through its ports (src/render/rendererOf.js) instead;\n` + + `${BASELINE} is never raised. A file that has just left the Cesium list\n` + + `must port these in the same change.\n${over.join('\n')}`, + ); +}); + +test('the record holds no file that now has fewer accesses', () => { + const counted = new Set(countedFiles()); + const stale = []; + for (const [file, allowed] of Object.entries(baseline)) { + const found = hits.get(file)?.length ?? 0; + if (!counted.has(file)) + stale.push(` ${file}: gone, a test, or on the Cesium list`); + else if (found < allowed) + stale.push(` ${file}: ${allowed} recorded, ${found} found`); + } + assert.deepEqual( + stale, + [], + `Lower ${BASELINE} to what the files hold (\`${UPDATE_COMMAND}\`):\n${stale.join('\n')}`, + ); +}); + +test('the record is sorted, with positive counts', () => { + const files = Object.keys(baseline); + assert.deepEqual(files, [...files].sort()); + for (const [file, count] of Object.entries(baseline)) + assert.ok(Number.isInteger(count) && count > 0, `${file}: ${count}`); +}); + +test('the record only shrinks', (t) => { + // As for the Cesium list: only the record's confirmed absence on + // origin/main (before it lands) skips this. + const git = (...args) => + execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }); + const base = git('merge-base', 'HEAD', 'origin/main').trim(); + if (!git('ls-tree', '--name-only', base, '--', BASELINE).trim()) { + t.skip(`${BASELINE} is not on origin/main yet`); + return; + } + const before = JSON.parse(git('show', `${base}:${BASELINE}`)); + const raised = Object.entries(baseline) + .filter(([file, count]) => count > (before[file] ?? 0)) + .map(([file, count]) => `${file}: ${before[file] ?? 0} → ${count}`); + assert.deepEqual( + raised, + [], + `Raised in ${BASELINE} since ${base}: it is never raised; port the access instead.`, + ); +}); diff --git a/src/render/viewerAccessAllowList.json b/src/render/viewerAccessAllowList.json new file mode 100644 index 000000000..6115ebfef --- /dev/null +++ b/src/render/viewerAccessAllowList.json @@ -0,0 +1,27 @@ +{ + "src/agent/worldPacket.js": 2, + "src/annotations/drawTool.js": 1, + "src/annotations/resolver.js": 1, + "src/annotations/screenAnnotationRenderer.js": 1, + "src/cameraVerbs.js": 1, + "src/celestialRing.js": 1, + "src/data/bhoteKoshiEmbeddedMedia.js": 1, + "src/data/followed.js": 5, + "src/data/osmOverlays.js": 2, + "src/data/pickRegistry.js": 3, + "src/data/spriteOrder.js": 2, + "src/layers/cctv/geometry.js": 1, + "src/layers/cctv/ground.js": 2, + "src/layers/flights/motion.js": 1, + "src/layers/military/motion.js": 1, + "src/layers/streetLevel/view.js": 1, + "src/layers/submarineCables/lifecycle.js": 2, + "src/layers/submarineCables/surface.js": 2, + "src/layers/vessels/lifecycle.js": 1, + "src/layers/weather/imageryHost.js": 3, + "src/maps/imageryHost.js": 4, + "src/overlays/worldOverlay.js": 1, + "src/ui/shareRestoration.js": 4, + "src/ui/visualEffects.js": 1, + "src/voice/gevActions.js": 1 +} diff --git a/src/testSupport/viewerAccess.mjs b/src/testSupport/viewerAccess.mjs new file mode 100644 index 000000000..3ddc56c63 --- /dev/null +++ b/src/testSupport/viewerAccess.mjs @@ -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')); +}