Files
gods-eye-view/src/render/contract/contract.test.mjs
T

261 lines
9.2 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import ts from 'typescript';
import {
CAPABILITIES,
CONTRACT_VERSION,
FRAME_STEPS,
PORTS,
ROLES,
roleOf,
QUALITY_KEYS,
checkPortShape,
checkRendererShape,
} from './index.js';
const DIR = path.dirname(fileURLToPath(import.meta.url));
const INDEX = path.join(DIR, 'index.d.ts');
const program = ts.createProgram([INDEX], {
strict: true,
noEmit: true,
target: ts.ScriptTarget.ES2022,
lib: ['lib.es2022.d.ts', 'lib.dom.d.ts'],
skipLibCheck: false,
types: [],
});
const checker = program.getTypeChecker();
const contractFiles = program
.getSourceFiles()
.filter((file) => path.dirname(file.fileName) === DIR);
/** The named interface or type alias declared in the contract files. */
function declared(name) {
for (const file of contractFiles)
for (const statement of file.statements)
if (
(ts.isInterfaceDeclaration(statement) ||
ts.isTypeAliasDeclaration(statement)) &&
statement.name.text === name
)
return statement;
throw new Error(`${name} is not declared in the contract`);
}
const PORT_INTERFACES = {
renderer: 'Renderer',
frame: 'FramePort',
globe: 'GlobePort',
draw: 'DrawPort',
camera: 'CameraPort',
query: 'QueryPort',
input: 'InputPort',
effects: 'EffectsPort',
credits: 'CreditsPort',
quality: 'QualityPort',
drawSet: 'DrawSet',
imageryLayer: 'ImageryLayer',
flight: 'Flight',
lease: 'Lease',
};
const PORT_NAMES = new Set(Object.values(PORT_INTERFACES));
/** Whether a property's type is one of the contract's own object shapes to list member by member. */
function nestedShape(type) {
if (type.isUnion() || type.getCallSignatures().length) return null;
const symbol = type.aliasSymbol ?? type.getSymbol();
const declaration = symbol?.declarations?.[0];
if (!declaration) return null;
const inContract = path.dirname(declaration.getSourceFile().fileName) === DIR;
if (!inContract) return null;
if (ts.isTypeLiteralNode(declaration)) return type;
if (ts.isInterfaceDeclaration(declaration))
return PORT_NAMES.has(declaration.name.text) ? null : type;
return null;
}
/**
* `[member, optional]` for every member, nested shapes dotted; a member of
* an optional shape is as optional as the shape.
*/
function members(type, prefix = '', inOptional = false) {
const out = [];
for (const property of checker.getPropertiesOfType(type)) {
const name = `${prefix}${property.name}`;
const optional =
inOptional || Boolean(property.flags & ts.SymbolFlags.Optional);
out.push([name, optional]);
const declaration = property.valueDeclaration ?? property.declarations?.[0];
const declared = checker.getTypeOfSymbolAtLocation(property, declaration);
// An optional member's shape, without the `undefined` its `?` adds.
const propertyType =
property.flags & ts.SymbolFlags.Optional
? checker.getNonNullableType(declared)
: declared;
const nested = nestedShape(propertyType);
if (nested) out.push(...members(nested, `${name}.`, optional));
}
return out;
}
function unionLiterals(name) {
const type = checker.getTypeAtLocation(declared(name).name);
return (type.isUnion() ? type.types : [type]).map((t) => t.value).sort();
}
test('the contract type-checks under strict TypeScript', () => {
const diagnostics = ts.getPreEmitDiagnostics(program).map((d) => {
const where = d.file
? `${path.relative(DIR, d.file.fileName)}:${d.file.getLineAndCharacterOfPosition(d.start).line + 1}`
: '';
return `${where} ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}`;
});
assert.deepEqual(diagnostics, []);
});
test('PORTS lists every member of every port, required exactly when the type requires it', () => {
for (const [port, interfaceName] of Object.entries(PORT_INTERFACES)) {
const type = checker.getTypeAtLocation(declared(interfaceName).name);
const typed = Object.fromEntries(members(type));
const described = PORTS[port];
assert.deepEqual(
Object.keys(described).sort(),
Object.keys(typed).sort(),
`${port} members`,
);
for (const [member, capability] of Object.entries(described))
assert.equal(
capability !== null,
typed[member],
`${port}.${member}: optional in the type exactly when a capability adds it`,
);
}
});
test('every member of every port has one role, and each role names real members', () => {
const ids = ROLES.map((r) => r.id);
assert.equal(new Set(ids).size, ids.length);
// No entry is claimed by two roles, so the most specific entry is never a tie.
const entries = ROLES.flatMap((r) => r.members);
assert.equal(new Set(entries).size, entries.length, 'an entry in two roles');
for (const [port, members] of Object.entries(PORTS))
for (const member of Object.keys(members))
assert.ok(
ids.includes(roleOf(port, member)),
`${port}.${member} has no role`,
);
// An entry is a port, or a member (or a prefix of dotted members) of one.
for (const role of ROLES)
for (const entry of role.members) {
const [port, ...rest] = entry.split('.');
const member = rest.join('.');
assert.ok(PORTS[port], `${role.id}: ${entry} names no port`);
if (member)
assert.ok(
Object.keys(PORTS[port]).some(
(m) => m === member || m.startsWith(`${member}.`),
),
`${role.id}: ${entry} names no member`,
);
}
// The most specific entry wins.
assert.equal(roleOf('globe', 'setBase'), 'surface');
assert.equal(roleOf('globe', 'sky.set'), 'look');
assert.equal(roleOf('globe', 'setSurfaceShading'), 'look');
assert.equal(roleOf('nowhere', 'x'), undefined);
assert.equal(roleOf('globe', 'bogus'), undefined);
assert.equal(roleOf('globe'), 'surface');
assert.equal(roleOf('imageryLayer', 'lit'), 'look');
});
test('the capability and frame-step lists are the types’ own', () => {
assert.deepEqual([...CAPABILITIES].sort(), unionLiterals('Capability'));
assert.deepEqual([...FRAME_STEPS].sort(), unionLiterals('FrameStep'));
for (const port of Object.values(PORTS))
for (const capability of Object.values(port))
if (capability !== null) assert.ok(CAPABILITIES.includes(capability));
assert.equal(CONTRACT_VERSION, '0');
const settings = checker.getTypeAtLocation(declared('QualitySettings').name);
assert.deepEqual(
[...QUALITY_KEYS].sort(),
checker
.getPropertiesOfType(settings)
.map((p) => p.name)
.sort(),
);
});
test('a draw set’s events: ready with the id, loadFailed with the id and why', () => {
const on = checker
.getTypeAtLocation(declared('DrawSet').name)
.getProperty('on');
const signatures = checker
.getTypeOfSymbolAtLocation(on, declared('DrawSet'))
.getCallSignatures();
const events = Object.fromEntries(
signatures.map((signature) => {
const [event, cb] = signature.getParameters();
const callback = checker
.getTypeOfSymbolAtLocation(cb, cb.valueDeclaration)
.getCallSignatures()[0];
return [
checker.getTypeOfSymbolAtLocation(event, event.valueDeclaration).value,
callback
.getParameters()
.map((p) =>
checker.typeToString(
checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration),
),
),
];
}),
);
assert.deepEqual(events, {
ready: ['string'],
loadFailed: ['string', 'string'],
});
});
test('members added to version 0 later are optional, each behind its capability', () => {
// A renderer written before an addition still conforms without it.
assert.equal(PORTS.globe.isGlobeVisible, 'globeVisibility');
assert.equal(PORTS.camera.followFrame, 'followFrame');
// Item fields added later are optional too.
const optional = (shape, field) =>
Object.fromEntries(
members(checker.getTypeAtLocation(declared(shape).name)),
)[field];
assert.equal(optional('LineItem', 'depthFail'), true);
// And on one kind of a union: the rectangle's rotation.
const rectangle = checker
.getTypeAtLocation(declared('ShapeGeometry').name)
.types.find((kind) => checker.getPropertyOfType(kind, 'rect'));
assert.equal(Object.fromEntries(members(rectangle)).rotation, true);
});
test('the shape check names what is missing and what a capability does not allow', () => {
assert.deepEqual(checkRendererShape(null), ['renderer is not an object']);
assert.deepEqual(checkRendererShape({}), [
'renderer.capabilities is not a Set',
]);
const problems = checkRendererShape({
capabilities: new Set(['warp']),
contractVersion: '0',
});
assert.ok(problems.includes('unknown capability warp'));
assert.ok(problems.includes('renderer.frame is missing'));
const set = Object.fromEntries(
Object.keys(PORTS.drawSet).map((member) => [member, () => {}]),
);
assert.deepEqual(checkPortShape(set, 'drawSet', new Set()), [
'drawSet.setColumns is present without columns',
]);
delete set.setColumns;
assert.deepEqual(checkPortShape(set, 'drawSet', new Set(['columns'])), [
'drawSet.setColumns is missing with columns',
]);
assert.deepEqual(checkPortShape(set, 'drawSet', new Set()), []);
});