/** * The ratchet: outside `src/render/cesium/`, only the files on * `cesiumAllowList.json` may reach Cesium, and every file on it must still * do so. Porting a file to the renderer contract removes it from the list; * nothing is ever added (checked against the list on `origin/main`). * * A file reaches Cesium when it: * - imports `cesium` or `@cesium/*`, by name or by a path into * `node_modules` (relative or Vite root-relative `/x`, any query ignored); * - imports the Cesium adapter (`src/render/cesium/`); * - is handed the namespace: a parameter or binding named `Cesium`/`cesium` * however destructured, a property of that name (`deps.cesium`, * `window.Cesium`), or member access on an unbound `Cesium`; * - in a `.vue` file, does any of these in a script block, or names Cesium * in `', ).external.some((s) => reachesCesium('src/ui/a.vue', s)), ); }); test('every allow-listed file still reaches Cesium', () => { const present = new Set(runtimeFiles); const stale = allowList.filter( (file) => !present.has(file) || !reachesCesiumFile(file), ); assert.deepEqual(stale, [], `Remove these from ${LIST}.`); }); test('the files that name the adapter by design import exactly what they are allowed', () => { const present = new Set(runtimeFiles); for (const [file, modules] of Object.entries(ADAPTER_ENTRIES)) { assert.ok(present.has(file), `${file} is gone: drop it from the list`); assert.ok(!allowList.includes(file), `${file} is on ${LIST} too`); const { imports } = scan(readFileSync(path.join(root, file), 'utf8')); const named = new Set(imports.map((s) => targetOf(file, s))); for (const module of modules) assert.ok(named.has(module), `${file} no longer imports ${module}`); } }); /** Every node under `node`, with its parent. */ function* nodesOf(node, parent = null) { if (!node || typeof node !== 'object') return; if (Array.isArray(node)) { for (const child of node) yield* nodesOf(child, parent); return; } if (typeof node.type === 'string') yield [node, parent]; for (const [key, value] of Object.entries(node)) if (!['loc', 'comments', 'tokens', 'extra'].includes(key)) yield* nodesOf(value, typeof node.type === 'string' ? node : parent); } test('the files that name the adapter by design take named exports, never Cesium itself', () => { for (const [file, modules] of Object.entries(ADAPTER_ENTRIES)) { const parsed = parsers.babel.parse( readFileSync(path.join(root, file), 'utf8'), ); // A static import by name only: no namespace or default binding, no // dynamic import, and no forwarding of the module. for (const [node] of nodesOf(parsed.program)) { const source = node.source?.value; if (typeof source !== 'string') continue; if (!modules.includes(targetOf(file, source))) continue; assert.equal( node.type, 'ImportDeclaration', `${file} must import ${source} statically and not forward it`, ); assert.deepEqual( node.specifiers .filter((s) => s.type !== 'ImportSpecifier') .map((s) => s.local.name), [], `${file} must import ${source} by name`, ); } // The allowed modules hand out no Cesium namespace: no export from the // package, and no exported value that is the namespace itself (members // of it, such as `Cesium.Math`, are the adapter's own business). for (const module of modules) { const program = parsers.babel.parse( readFileSync(path.join(root, module), 'utf8'), ).program; const fromCesium = ({ source }) => { if (typeof source?.value !== 'string') return false; const bare = source.value.replace(/[?#].*$/, ''); const target = targetOf(module, bare) ?? ''; return /^(?:(?:node_modules\/)?(?:cesium|@cesium\/[^/]+))(?:\/|$)/.test( target || bare, ); }; const namespaces = new Set( program.body .filter((n) => n.type === 'ImportDeclaration' && fromCesium(n)) .flatMap((n) => n.specifiers.map((s) => s.local.name)), ); for (const node of program.body) { if (!node.type.startsWith('Export')) continue; assert.ok(!fromCesium(node), `${module} must not re-export Cesium`); for (const [inner, parent] of nodesOf(node)) { if (inner.type !== 'Identifier' || !namespaces.has(inner.name)) continue; // Handing the namespace to the adapter's own functions is fine; // giving it out as a value is not. const handedOut = [ 'ExportSpecifier', 'ExportDefaultDeclaration', 'ReturnStatement', 'SpreadElement', 'ArrayExpression', ].includes(parent?.type) || (parent?.type === 'VariableDeclarator' && parent.init === inner) || (parent?.type === 'ObjectProperty' && parent.value === inner) || (parent?.type === 'ArrowFunctionExpression' && parent.body === inner) || (parent?.type === 'AssignmentExpression' && parent.right === inner); assert.ok( !handedOut, `${module} must not export ${inner.name} itself`, ); } } } } }); test('the allow-list only shrinks', (t) => { // Any git failure fails the check: only the list's confirmed absence on // origin/main (before it lands) skips it. const base = git('merge-base', 'HEAD', 'origin/main').trim(); const atBase = git('ls-tree', '--name-only', base, '--', LIST).trim(); if (!atBase) { t.skip(`${LIST} is not on origin/main yet`); return; } const before = new Set(JSON.parse(git('show', `${base}:${LIST}`))); const added = allowList.filter((file) => !before.has(file)); assert.deepEqual( added, [], `Files added to ${LIST} since ${base} (a moved file needs its old entry removed).`, ); }); test('the allow-list is sorted and has no duplicates', () => { assert.deepEqual(allowList, [...new Set(allowList)].sort()); }); test('no runtime file is in a language the ratchet cannot read', () => { const unread = tracked.filter( (file) => /\.(?:[cm]?tsx?|jsx)$/.test(file) && !/\.d\.[cm]?ts$/.test(file) && !isTestSupport(file), ); assert.deepEqual(unread, [], 'Teach the ratchet to read these first.'); }); test('the renderer contract, stub, input router and conformance suite stay Cesium-free', () => { const engineFree = tracked.filter( (file) => /^src\/render\/(?:contract|stub|input|conformance)\//.test(file) && /\.[cm]?js$/.test(file) && !/\.test\.[cm]?js$/.test(file), ); assert.ok(engineFree.length > 0); assert.deepEqual(engineFree.filter(reachesCesiumFile), []); });