mirror of
https://github.com/videojs/video.js.git
synced 2026-11-20 06:29:27 +01:00
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
1012 lines
38 KiB
TypeScript
1012 lines
38 KiB
TypeScript
/**
|
|
* Reads behaviors, features, and engines out of the type checker. Everything here is a fact the sources state: a
|
|
* behavior's declared keys, the slot map its setup takes, the config fields it reads, a feature's behavior list and
|
|
* `defaultConfig` literals, an engine's feature list. Nothing is inferred from naming conventions.
|
|
*/
|
|
import ts from 'typescript';
|
|
|
|
import type { EntryPoint, ReferenceProgram } from './program';
|
|
|
|
// ── Docs ─────────────────────────────────────────────────────────────────────
|
|
|
|
export interface DocTag {
|
|
name: string;
|
|
text: string;
|
|
}
|
|
|
|
export interface DocBlock {
|
|
/** The comment body, as Markdown. Empty when the symbol has no JSDoc. */
|
|
text: string;
|
|
tags: DocTag[];
|
|
}
|
|
|
|
const EMPTY_DOC: DocBlock = { text: '', tags: [] };
|
|
|
|
/** `{@link X}` and `{@link X | label}` as inline code, which GitHub Markdown can render. */
|
|
function inlineLinks(text: string): string {
|
|
return text.replace(/\{@link\s+([^}|]+?)(?:\s*\|\s*([^}]+))?\}/g, (_match, target: string, label?: string) =>
|
|
label ? label.trim() : `\`${target.trim()}\``
|
|
);
|
|
}
|
|
|
|
export function docOf(checker: ts.TypeChecker, symbol: ts.Symbol | undefined): DocBlock {
|
|
if (!symbol) return EMPTY_DOC;
|
|
|
|
const text = inlineLinks(ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim());
|
|
const tags = symbol.getJsDocTags(checker).map((tag) => ({
|
|
name: tag.name,
|
|
text: inlineLinks(ts.displayPartsToString(tag.text ?? []).trim()),
|
|
}));
|
|
|
|
return { text, tags };
|
|
}
|
|
|
|
/** The first paragraph of a doc block on one line, for index tables. */
|
|
export function firstParagraph(doc: DocBlock): string {
|
|
return (
|
|
doc.text
|
|
.split(/\n\s*\n/, 1)[0]
|
|
?.replace(/\s+/g, ' ')
|
|
.trim() ?? ''
|
|
);
|
|
}
|
|
|
|
/** The first sentence of a doc block, for inventory tables. */
|
|
export function firstSentence(doc: DocBlock): string {
|
|
const paragraph = firstParagraph(doc);
|
|
const bold = paragraph.match(/^\*\*.+?\*\*(?=\s|$)/);
|
|
if (bold) return bold[0];
|
|
|
|
const match = paragraph.match(/^.*?[.!?](?=\s+[A-Z`(]|$)/);
|
|
|
|
return match ? match[0] : paragraph;
|
|
}
|
|
|
|
/**
|
|
* A module's own description: a JSDoc block at the top of its file, before the imports, set off from the first
|
|
* statement by a blank line (or carrying `@module`), the way TypeDoc and API Extractor read one. `undefined` when the
|
|
* file opens with code, or with the JSDoc of its first declaration.
|
|
*/
|
|
export function moduleDoc(reference: ReferenceProgram, file: string): DocBlock | undefined {
|
|
const sourceFile = reference.program.getSourceFile(file);
|
|
if (!sourceFile) throw new Error(`Not in the program: ${file}`);
|
|
|
|
const text = sourceFile.getFullText();
|
|
const range = ts.getLeadingCommentRanges(text, 0)?.find((candidate) => text.startsWith('/**', candidate.pos));
|
|
if (!range) return undefined;
|
|
|
|
const comment = text.slice(range.pos, range.end);
|
|
const firstStatement = sourceFile.statements[0];
|
|
const gap = text.slice(range.end, firstStatement ? firstStatement.getStart(sourceFile) : text.length);
|
|
if (!/\n[ \t]*\n/.test(gap) && !comment.includes('@module')) return undefined;
|
|
|
|
const body = comment
|
|
.replace(/^\/\*\*\s*/, '')
|
|
.replace(/\s*\*\/$/, '')
|
|
.split('\n')
|
|
.map((line) => line.replace(/^\s*\* ?/, ''))
|
|
.filter((line) => !/^@module\b/.test(line.trim()))
|
|
.join('\n')
|
|
.trim();
|
|
|
|
return { text: inlineLinks(body), tags: [] };
|
|
}
|
|
|
|
// ── Printing ─────────────────────────────────────────────────────────────────
|
|
|
|
const TYPE_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
|
|
const printer = ts.createPrinter({ removeComments: true });
|
|
|
|
export function printType(checker: ts.TypeChecker, type: ts.Type): string {
|
|
return checker.typeToString(type, undefined, TYPE_FLAGS);
|
|
}
|
|
|
|
/** A property's type as its declaration spells it; `| undefined` from an optional marker is left off. */
|
|
function printPropertyType(checker: ts.TypeChecker, property: ts.Symbol): string {
|
|
const printed = printType(checker, checker.getTypeOfSymbol(property));
|
|
|
|
return isOptional(property) ? printed.replace(/ \| undefined$/, '') : printed;
|
|
}
|
|
|
|
/** An expression as one line of source, comments removed and the printer's multi-line bracket spacing collapsed. */
|
|
export function printExpression(node: ts.Node): string {
|
|
return printer
|
|
.printNode(ts.EmitHint.Unspecified, node, node.getSourceFile())
|
|
.replace(/\s+/g, ' ')
|
|
.replace(/\[\s+/g, '[')
|
|
.replace(/,?\s+\]/g, ']')
|
|
.replace(/\{\s+/g, '{ ')
|
|
.replace(/,?\s+\}/g, ' }')
|
|
.replace(/\{ \}/g, '{}')
|
|
.trim();
|
|
}
|
|
|
|
function isOptional(symbol: ts.Symbol): boolean {
|
|
return (symbol.flags & ts.SymbolFlags.Optional) !== 0;
|
|
}
|
|
|
|
function withoutUndefined(checker: ts.TypeChecker, type: ts.Type): ts.Type {
|
|
return type.isUnion() ? checker.getNonNullableType(type) : type;
|
|
}
|
|
|
|
// ── Symbols ──────────────────────────────────────────────────────────────────
|
|
|
|
export function resolveAlias(checker: ts.TypeChecker, symbol: ts.Symbol): ts.Symbol {
|
|
return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
|
|
}
|
|
|
|
export function moduleExports(reference: ReferenceProgram, file: string): ts.Symbol[] {
|
|
const sourceFile = reference.program.getSourceFile(file);
|
|
if (!sourceFile) throw new Error(`Not in the program: ${file}`);
|
|
|
|
const moduleSymbol = reference.checker.getSymbolAtLocation(sourceFile);
|
|
if (!moduleSymbol) throw new Error(`Not a module: ${file}`);
|
|
|
|
return reference.checker.getExportsOfModule(moduleSymbol);
|
|
}
|
|
|
|
function declarationOf(symbol: ts.Symbol): ts.Declaration | undefined {
|
|
return symbol.valueDeclaration ?? symbol.declarations?.[0];
|
|
}
|
|
|
|
/** The initializer of an exported `const`, through a trailing `as const` or `satisfies`. */
|
|
function initializerOf(symbol: ts.Symbol): ts.Expression | undefined {
|
|
const declaration = declarationOf(symbol);
|
|
if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer) return undefined;
|
|
|
|
return unwrapAssertions(declaration.initializer);
|
|
}
|
|
|
|
function unwrapAssertions(expression: ts.Expression): ts.Expression {
|
|
let current = expression;
|
|
|
|
while (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current)) {
|
|
current = current.expression;
|
|
}
|
|
|
|
return current;
|
|
}
|
|
|
|
/** The kind an export is listed under: what its declaration is. */
|
|
export function exportKind(symbol: ts.Symbol): string {
|
|
const declaration = declarationOf(symbol);
|
|
if (!declaration) return 'unknown';
|
|
|
|
if (ts.isInterfaceDeclaration(declaration)) return 'interface';
|
|
|
|
if (ts.isTypeAliasDeclaration(declaration)) return 'type';
|
|
|
|
if (ts.isFunctionDeclaration(declaration)) return 'function';
|
|
|
|
if (ts.isClassDeclaration(declaration)) return 'class';
|
|
|
|
if (ts.isEnumDeclaration(declaration)) return 'enum';
|
|
|
|
if (ts.isVariableDeclaration(declaration)) {
|
|
const list = declaration.parent;
|
|
|
|
return ts.isVariableDeclarationList(list) && list.flags & ts.NodeFlags.Const ? 'const' : 'let';
|
|
}
|
|
|
|
return ts.SyntaxKind[declaration.kind];
|
|
}
|
|
|
|
/**
|
|
* What an undocumented type export is, read off its declaration: the type a type alias names, or an interface's field
|
|
* names. `undefined` for any other kind of export.
|
|
*/
|
|
export function declaredTypeOf(
|
|
checker: ts.TypeChecker,
|
|
symbol: ts.Symbol
|
|
): { kind: 'alias' | 'fields'; text: string } | undefined {
|
|
const declaration = declarationOf(symbol);
|
|
if (!declaration) return undefined;
|
|
|
|
if (ts.isTypeAliasDeclaration(declaration)) return { kind: 'alias', text: declaration.type.getText() };
|
|
|
|
if (!ts.isInterfaceDeclaration(declaration)) return undefined;
|
|
|
|
const fields = checker
|
|
.getPropertiesOfType(checker.getDeclaredTypeOfSymbol(symbol))
|
|
.map((property) => property.name)
|
|
.sort((a, b) => a.localeCompare(b));
|
|
|
|
return { kind: 'fields', text: fields.join(', ') };
|
|
}
|
|
|
|
/** The file an export is declared in, which differs from the module's when the module re-exports it. */
|
|
export function declaringFile(symbol: ts.Symbol): string | undefined {
|
|
return declarationOf(symbol)?.getSourceFile().fileName;
|
|
}
|
|
|
|
/** A declaration's source text without its body: the signature of a function, or the whole of a type. */
|
|
export function declarationSignature(symbol: ts.Symbol): string | undefined {
|
|
const declaration = declarationOf(symbol);
|
|
if (!declaration) return undefined;
|
|
|
|
if (ts.isFunctionDeclaration(declaration) && declaration.body) {
|
|
const text = declaration.getText();
|
|
|
|
return `${text.slice(0, declaration.body.getStart() - declaration.getStart()).trimEnd()};`;
|
|
}
|
|
|
|
if (ts.isVariableDeclaration(declaration)) {
|
|
const statement = declaration.parent.parent;
|
|
|
|
return ts.isVariableStatement(statement) ? statement.getText() : declaration.getText();
|
|
}
|
|
|
|
return declaration.getText();
|
|
}
|
|
|
|
// ── Behaviors ────────────────────────────────────────────────────────────────
|
|
|
|
export interface Owner {
|
|
/** The interface or type alias that declares the field, when it is declared in one. */
|
|
name: string | undefined;
|
|
file: string;
|
|
}
|
|
|
|
export interface SlotRow {
|
|
key: string;
|
|
/** `writes` for a `Signal` slot, `reads` for a `ReadonlySignal` one. */
|
|
access: 'writes' | 'reads';
|
|
/** Whether the behavior lists the key in `stateKeys` / `contextKeys`; `undefined` when that list is not derivable. */
|
|
declared: boolean | undefined;
|
|
/** Whether the setup type marks the slot optional. */
|
|
optional: boolean;
|
|
/** Whether the row comes from an `@observes` tag rather than the setup type; its owner is the declaring behavior's. */
|
|
observed?: boolean;
|
|
type: string;
|
|
doc: DocBlock;
|
|
owner: Owner | undefined;
|
|
}
|
|
|
|
export interface ConfigRow {
|
|
key: string;
|
|
optional: boolean;
|
|
type: string;
|
|
doc: DocBlock;
|
|
/** The config field declarations behind the key, which identify the behavior as a reader of it elsewhere. */
|
|
declarations: readonly ts.Declaration[];
|
|
}
|
|
|
|
export interface BehaviorInfo {
|
|
/** The export name, or the printed expression for a behavior built inline in a feature's list. */
|
|
name: string;
|
|
/** A short name for links: the export name, or an inline behavior's factory call without its argument. */
|
|
label: string;
|
|
/** Whether `name` is an export (and so can be a heading), or an inline expression. */
|
|
exported: boolean;
|
|
/**
|
|
* Whether the entry only declares signals written from outside the composition (`defineExternalSignals`), rather than
|
|
* behavior logic.
|
|
*/
|
|
external: boolean;
|
|
file: string;
|
|
entry: EntryPoint | undefined;
|
|
doc: DocBlock;
|
|
stateKeys: string[] | undefined;
|
|
contextKeys: string[] | undefined;
|
|
state: SlotRow[];
|
|
context: SlotRow[];
|
|
config: ConfigRow[];
|
|
/** Whether the setup declares `config?:` (callers may omit it); `undefined` when the setup takes no config. */
|
|
configOptional: boolean | undefined;
|
|
/** The named interfaces and type aliases the setup's config type is, or intersects. */
|
|
configTypes: Owner[];
|
|
}
|
|
|
|
export interface Model {
|
|
behaviors: BehaviorInfo[];
|
|
features: FeatureInfo[];
|
|
engines: EngineInfo[];
|
|
}
|
|
|
|
/** Keys from a `readonly ['a', 'b']` tuple type. */
|
|
function keysFromTupleType(checker: ts.TypeChecker, type: ts.Type): string[] | undefined {
|
|
if (!checker.isTupleType(type)) return undefined;
|
|
|
|
// SAFETY: `isTupleType` narrows to a tuple, which is a `TypeReference` whose type arguments are the element types.
|
|
const elements = checker.getTypeArguments(type as ts.TypeReference);
|
|
|
|
return stringLiterals(elements.map((element) => (element.isStringLiteral() ? element.value : undefined)));
|
|
}
|
|
|
|
/** The values when every one is a string, else `undefined`. */
|
|
function stringLiterals(values: (string | undefined)[]): string[] | undefined {
|
|
const keys: string[] = [];
|
|
|
|
for (const value of values) {
|
|
if (value === undefined) return undefined;
|
|
|
|
keys.push(value);
|
|
}
|
|
|
|
return keys;
|
|
}
|
|
|
|
/** Keys from a `stateKeys: ['a', 'b']` (or external signals' `state: [...]`) property of an object literal. */
|
|
function keysFromObjectLiteral(literal: ts.ObjectLiteralExpression, names: string[]): string[] | undefined {
|
|
for (const property of literal.properties) {
|
|
if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) continue;
|
|
|
|
if (!names.includes(property.name.text) || !ts.isArrayLiteralExpression(property.initializer)) continue;
|
|
|
|
return stringLiterals(
|
|
property.initializer.elements.map((element) => (ts.isStringLiteralLike(element) ? element.text : undefined))
|
|
);
|
|
}
|
|
|
|
return undefined;
|
|
}
|
|
|
|
/**
|
|
* Keys from the array literal a behavior's initializer spells out: the object literal of a manual `Behavior<>` value,
|
|
* or the object literal passed to `defineBehavior(...)` or a curried factory such as
|
|
* `defineExternalSignals<T>()(...)`.
|
|
*/
|
|
function keysFromInitializer(initializer: ts.Expression | undefined, names: string[]): string[] | undefined {
|
|
if (!initializer) return undefined;
|
|
|
|
if (ts.isObjectLiteralExpression(initializer)) return keysFromObjectLiteral(initializer, names);
|
|
|
|
if (!ts.isCallExpression(initializer)) return undefined;
|
|
|
|
for (const argument of initializer.arguments) {
|
|
if (!ts.isObjectLiteralExpression(argument)) continue;
|
|
|
|
const keys = keysFromObjectLiteral(argument, names);
|
|
if (keys) return keys;
|
|
}
|
|
|
|
// A curried factory: the keys are on the outer call's argument.
|
|
return ts.isCallExpression(initializer.expression) ? keysFromInitializer(initializer.expression, names) : undefined;
|
|
}
|
|
|
|
function isSignalTypeNode(node: ts.TypeNode | undefined): boolean {
|
|
return (
|
|
!!node &&
|
|
ts.isTypeReferenceNode(node) &&
|
|
ts.isIdentifier(node.typeName) &&
|
|
(node.typeName.text === 'Signal' || node.typeName.text === 'ReadonlySignal')
|
|
);
|
|
}
|
|
|
|
/**
|
|
* The field a slot's type reads through an indexed access such as `Signal<State['preload']>` or, in a mapped slot map,
|
|
* `Signal<State[P]>` where `P` stands for `key`.
|
|
*/
|
|
function indexedField(checker: ts.TypeChecker, node: ts.TypeNode, key: string): ts.Symbol | undefined {
|
|
if (ts.isIndexedAccessTypeNode(node)) {
|
|
const index = node.indexType;
|
|
const name = ts.isLiteralTypeNode(index) && ts.isStringLiteralLike(index.literal) ? index.literal.text : key;
|
|
const objectType = checker.getTypeFromTypeNode(node.objectType);
|
|
|
|
return objectType.getProperty(name);
|
|
}
|
|
|
|
if (ts.isTypeReferenceNode(node) && node.typeArguments) {
|
|
for (const argument of node.typeArguments) {
|
|
const found = indexedField(checker, argument, key);
|
|
if (found) return found;
|
|
}
|
|
}
|
|
|
|
if (ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node)) {
|
|
for (const member of node.types) {
|
|
const found = indexedField(checker, member, key);
|
|
if (found) return found;
|
|
}
|
|
}
|
|
|
|
if (ts.isParenthesizedTypeNode(node)) return indexedField(checker, node.type, key);
|
|
|
|
return undefined;
|
|
}
|
|
|
|
function ownerOf(declaration: ts.Declaration): Owner {
|
|
const parent = declaration.parent;
|
|
let name: string | undefined;
|
|
|
|
if (ts.isInterfaceDeclaration(parent)) name = parent.name.text;
|
|
else if (ts.isTypeLiteralNode(parent) && ts.isTypeAliasDeclaration(parent.parent)) name = parent.parent.name.text;
|
|
else if (ts.isMappedTypeNode(parent) && ts.isTypeAliasDeclaration(parent.parent)) name = parent.parent.name.text;
|
|
|
|
return { name, file: declaration.getSourceFile().fileName };
|
|
}
|
|
|
|
/**
|
|
* Where a slot's value is declared: the field of the state or context interface the slot map types it from, and that
|
|
* field's JSDoc. A slot typed inline, with no indexed access to follow, owns its own doc.
|
|
*/
|
|
function slotOrigin(checker: ts.TypeChecker, slot: ts.Symbol, key: string): Pick<SlotRow, 'doc' | 'owner'> {
|
|
const declaration = slot.declarations?.[0];
|
|
|
|
if (declaration && ts.isPropertySignature(declaration)) {
|
|
const typeNode = declaration.type;
|
|
|
|
if (isSignalTypeNode(typeNode)) {
|
|
const field = typeNode && indexedField(checker, typeNode, key);
|
|
const fieldDeclaration = field?.declarations?.[0];
|
|
if (field && fieldDeclaration) return { doc: docOf(checker, field), owner: ownerOf(fieldDeclaration) };
|
|
}
|
|
|
|
return { doc: docOf(checker, slot), owner: ownerOf(declaration) };
|
|
}
|
|
|
|
// A member of a mapped slot map such as `{ [P in K]: Signal<State[P]> }` has no declaration of its own; the mapped
|
|
// type's template says which field it reads. `links.mappedType` is the checker's private record of that type.
|
|
// SAFETY: every field read is optional, so a symbol without that private record yields `undefined`, never a throw.
|
|
const mapped = (slot as { links?: { mappedType?: { declaration?: ts.MappedTypeNode } } }).links?.mappedType;
|
|
const template = mapped?.declaration?.type;
|
|
|
|
if (template) {
|
|
const field = indexedField(checker, template, key);
|
|
const fieldDeclaration = field?.declarations?.[0];
|
|
if (field && fieldDeclaration) return { doc: docOf(checker, field), owner: ownerOf(fieldDeclaration) };
|
|
}
|
|
|
|
return { doc: EMPTY_DOC, owner: undefined };
|
|
}
|
|
|
|
function slotRows(checker: ts.TypeChecker, map: ts.Type | undefined, declaredKeys: string[] | undefined): SlotRow[] {
|
|
if (!map) return [];
|
|
|
|
const rows: SlotRow[] = [];
|
|
|
|
for (const slot of checker.getPropertiesOfType(map)) {
|
|
const slotType = withoutUndefined(checker, checker.getTypeOfSymbol(slot));
|
|
const getter = slotType.getProperty('get');
|
|
const getSignature = getter && checker.getTypeOfSymbol(getter).getCallSignatures()[0];
|
|
if (!getSignature) continue;
|
|
|
|
rows.push({
|
|
key: slot.name,
|
|
access: slotType.getProperty('set') ? 'writes' : 'reads',
|
|
declared: declaredKeys?.includes(slot.name),
|
|
optional: isOptional(slot),
|
|
type: printType(checker, getSignature.getReturnType()),
|
|
...slotOrigin(checker, slot, slot.name),
|
|
});
|
|
}
|
|
|
|
return rows.sort((a, b) => a.key.localeCompare(b.key));
|
|
}
|
|
|
|
function configRows(checker: ts.TypeChecker, config: ts.Type | undefined): ConfigRow[] {
|
|
if (!config) return [];
|
|
|
|
return checker
|
|
.getPropertiesOfType(config)
|
|
.map((property) => ({
|
|
key: property.name,
|
|
optional: isOptional(property),
|
|
type: printPropertyType(checker, property),
|
|
doc: docOf(checker, property),
|
|
declarations: property.declarations ?? [],
|
|
}))
|
|
.sort((a, b) => a.key.localeCompare(b.key));
|
|
}
|
|
|
|
/** The interface or type-alias declarations behind a type: its own, or each member's of an intersection. */
|
|
function namedTypes(type: ts.Type): Owner[] {
|
|
if (type.isIntersection()) return type.types.flatMap(namedTypes);
|
|
|
|
const symbol = type.aliasSymbol ?? type.getSymbol();
|
|
const declaration = symbol && declarationOf(symbol);
|
|
if (!declaration || !(ts.isInterfaceDeclaration(declaration) || ts.isTypeAliasDeclaration(declaration))) return [];
|
|
|
|
return [{ name: symbol.name, file: declaration.getSourceFile().fileName }];
|
|
}
|
|
|
|
/** The deps slot `name` of a setup parameter type: its type, less `undefined`, and whether it is optional. */
|
|
function depsSlot(
|
|
checker: ts.TypeChecker,
|
|
deps: ts.Type,
|
|
name: string
|
|
): { type: ts.Type; optional: boolean } | undefined {
|
|
const property = deps.getProperty(name);
|
|
if (!property) return undefined;
|
|
|
|
return { type: withoutUndefined(checker, checker.getTypeOfSymbol(property)), optional: isOptional(property) };
|
|
}
|
|
|
|
/**
|
|
* Read a behavior from its type: `stateKeys` / `contextKeys` (a literal tuple, else the array literal `initializer`
|
|
* passes) and the slot maps and config its `setup` parameter declares. `undefined` when the type is not a behavior.
|
|
*/
|
|
function behaviorFromType(
|
|
checker: ts.TypeChecker,
|
|
type: ts.Type,
|
|
initializer: ts.Expression | undefined
|
|
): Omit<BehaviorInfo, 'name' | 'exported' | 'file' | 'entry' | 'doc'> | undefined {
|
|
const stateKeysProperty = type.getProperty('stateKeys');
|
|
const contextKeysProperty = type.getProperty('contextKeys');
|
|
const setupProperty = type.getProperty('setup');
|
|
if (!stateKeysProperty || !contextKeysProperty || !setupProperty) return undefined;
|
|
|
|
const signature = checker.getTypeOfSymbol(setupProperty).getCallSignatures()[0];
|
|
const depsParameter = signature?.getParameters()[0];
|
|
if (!signature || !depsParameter) return undefined;
|
|
|
|
const stateKeys =
|
|
keysFromTupleType(checker, checker.getTypeOfSymbol(stateKeysProperty)) ??
|
|
keysFromInitializer(initializer, ['stateKeys', 'state']);
|
|
const contextKeys =
|
|
keysFromTupleType(checker, checker.getTypeOfSymbol(contextKeysProperty)) ??
|
|
keysFromInitializer(initializer, ['contextKeys', 'context']);
|
|
|
|
const deps = checker.getTypeOfSymbol(depsParameter);
|
|
const state = depsSlot(checker, deps, 'state');
|
|
const context = depsSlot(checker, deps, 'context');
|
|
const config = depsSlot(checker, deps, 'config');
|
|
|
|
// A manual `Behavior<>` literal types its contract narrower than its setup function, which may read further slots
|
|
// optionally; those slots are part of what the setup reads, so they join the contract's rows.
|
|
const implementation = setupImplementationDeps(checker, initializer);
|
|
const implementationState = implementation && depsSlot(checker, implementation, 'state');
|
|
const implementationContext = implementation && depsSlot(checker, implementation, 'context');
|
|
|
|
return {
|
|
stateKeys,
|
|
contextKeys,
|
|
state: mergeSlotRows(
|
|
slotRows(checker, state?.type, stateKeys),
|
|
slotRows(checker, implementationState?.type, stateKeys)
|
|
),
|
|
context: mergeSlotRows(
|
|
slotRows(checker, context?.type, contextKeys),
|
|
slotRows(checker, implementationContext?.type, contextKeys)
|
|
),
|
|
config: configRows(checker, config?.type),
|
|
configOptional: config?.optional,
|
|
configTypes: config ? namedTypes(config.type) : [],
|
|
};
|
|
}
|
|
|
|
/** The contract's rows, plus the implementation's rows for keys the contract leaves out. */
|
|
function mergeSlotRows(contract: SlotRow[], implementation: SlotRow[]): SlotRow[] {
|
|
const keys = new Set(contract.map((row) => row.key));
|
|
const extra = implementation.filter((row) => !keys.has(row.key));
|
|
|
|
return [...contract, ...extra].sort((a, b) => a.key.localeCompare(b.key));
|
|
}
|
|
|
|
/** The object literal a behavior initializer builds from: the literal itself, or the one its factory call takes. */
|
|
function behaviorLiteral(initializer: ts.Expression | undefined): ts.ObjectLiteralExpression | undefined {
|
|
if (!initializer) return undefined;
|
|
|
|
if (ts.isObjectLiteralExpression(initializer)) return initializer;
|
|
|
|
if (!ts.isCallExpression(initializer)) return undefined;
|
|
|
|
const literal = initializer.arguments.find(ts.isObjectLiteralExpression);
|
|
if (literal) return literal;
|
|
|
|
return ts.isCallExpression(initializer.expression) ? behaviorLiteral(initializer.expression) : undefined;
|
|
}
|
|
|
|
/** The expression a behavior literal's `setup` property names or spells out. */
|
|
function setupExpression(initializer: ts.Expression | undefined): ts.Expression | undefined {
|
|
const literal = behaviorLiteral(initializer);
|
|
const setup = literal?.properties.find(
|
|
(property) =>
|
|
(ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) &&
|
|
ts.isIdentifier(property.name) &&
|
|
property.name.text === 'setup'
|
|
);
|
|
if (!setup) return undefined;
|
|
|
|
return ts.isPropertyAssignment(setup) ? setup.initializer : setup.name;
|
|
}
|
|
|
|
/**
|
|
* A behavior's own JSDoc, else that of the function its `setup` names: a behavior is that function plus its declared
|
|
* keys, so the function's doc describes it.
|
|
*/
|
|
function behaviorDoc(checker: ts.TypeChecker, symbol: ts.Symbol): DocBlock {
|
|
const own = docOf(checker, symbol);
|
|
if (own.text) return own;
|
|
|
|
const expression = setupExpression(initializerOf(symbol));
|
|
if (!expression || !ts.isIdentifier(expression)) return own;
|
|
|
|
const named = ts.isShorthandPropertyAssignment(expression.parent)
|
|
? checker.getShorthandAssignmentValueSymbol(expression.parent)
|
|
: checker.getSymbolAtLocation(expression);
|
|
|
|
return named ? docOf(checker, resolveAlias(checker, named)) : own;
|
|
}
|
|
|
|
/** The deps parameter type of the function a behavior's `setup` property names or spells out. */
|
|
function setupImplementationDeps(checker: ts.TypeChecker, initializer: ts.Expression | undefined): ts.Type | undefined {
|
|
const expression = setupExpression(initializer);
|
|
if (!expression) return undefined;
|
|
|
|
const declaration = setupFunction(checker, expression);
|
|
const signature = declaration && checker.getSignatureFromDeclaration(declaration);
|
|
const parameter = signature?.getParameters()[0];
|
|
|
|
return parameter && checker.getTypeOfSymbol(parameter);
|
|
}
|
|
|
|
function setupFunction(checker: ts.TypeChecker, expression: ts.Expression): ts.SignatureDeclaration | undefined {
|
|
if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) return expression;
|
|
|
|
if (!ts.isIdentifier(expression)) return undefined;
|
|
|
|
const symbol = checker.getSymbolAtLocation(expression);
|
|
const declaration = symbol && declarationOf(resolveAlias(checker, symbol));
|
|
if (!declaration) return undefined;
|
|
|
|
if (ts.isFunctionDeclaration(declaration)) return declaration;
|
|
|
|
if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
|
|
return setupFunction(checker, unwrapAssertions(declaration.initializer));
|
|
}
|
|
|
|
return undefined;
|
|
}
|
|
|
|
// ── Features and engines ─────────────────────────────────────────────────────
|
|
|
|
export interface DefaultValue {
|
|
key: string;
|
|
/** The default's source expression, with a same-file `const` followed one level to its initializer. */
|
|
text: string;
|
|
/**
|
|
* The config field declarations the literal's `satisfies` type names for the key, which identify the behaviors the
|
|
* default is written for; empty when the literal has no `satisfies` clause or the clause does not cover the key.
|
|
*/
|
|
readerDeclarations: readonly ts.Declaration[];
|
|
/** The key's type in the `satisfies` type, when the clause covers it. */
|
|
type: string | undefined;
|
|
/** The first sentence of the followed same-file `const`'s JSDoc, which names what the value means. */
|
|
note: string | undefined;
|
|
}
|
|
|
|
export interface FeatureInfo {
|
|
name: string;
|
|
entry: EntryPoint;
|
|
file: string;
|
|
doc: DocBlock;
|
|
behaviors: BehaviorInfo[];
|
|
defaults: DefaultValue[];
|
|
/** The `initialState` literal's entries. */
|
|
initial: DefaultValue[];
|
|
/** The exported `Config`, `State`, and `Context` types' fields. */
|
|
config: TypeField[];
|
|
state: TypeField[];
|
|
context: TypeField[];
|
|
composedBy: EngineInfo[];
|
|
}
|
|
|
|
export interface EngineInfo {
|
|
name: string;
|
|
entry: EntryPoint;
|
|
file: string;
|
|
doc: DocBlock;
|
|
features: FeatureInfo[];
|
|
behaviors: BehaviorInfo[];
|
|
/** The engine's own `initialState` entries, which replace its features' for the same key. */
|
|
initial: DefaultValue[];
|
|
config: TypeField[];
|
|
state: TypeField[];
|
|
context: TypeField[];
|
|
}
|
|
|
|
export interface TypeField {
|
|
key: string;
|
|
optional: boolean;
|
|
type: string;
|
|
}
|
|
|
|
function typeFields(checker: ts.TypeChecker, symbol: ts.Symbol | undefined): TypeField[] {
|
|
if (!symbol) return [];
|
|
|
|
return checker
|
|
.getPropertiesOfType(checker.getDeclaredTypeOfSymbol(symbol))
|
|
.map((property) => ({
|
|
key: property.name,
|
|
optional: isOptional(property),
|
|
type: printPropertyType(checker, property),
|
|
}))
|
|
.sort((a, b) => a.key.localeCompare(b.key));
|
|
}
|
|
|
|
/** The type a `defaultConfig` literal is checked against: the `satisfies` clause on its initializer, if any. */
|
|
function satisfiesType(checker: ts.TypeChecker, symbol: ts.Symbol): ts.Type | undefined {
|
|
const declaration = declarationOf(symbol);
|
|
if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer) return undefined;
|
|
|
|
let current = declaration.initializer;
|
|
|
|
while (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current)) {
|
|
if (ts.isSatisfiesExpression(current)) return checker.getTypeFromTypeNode(current.type);
|
|
|
|
current = current.expression;
|
|
}
|
|
|
|
return undefined;
|
|
}
|
|
|
|
/**
|
|
* The `defaultConfig` (or `initialState`) object literal's entries, each printed as source. An engine's literal may
|
|
* spread its composed features' values, which their own entries already list, so `'skip'` passes over spreads; a
|
|
* feature's literal may not, since a skipped spread would hide values.
|
|
*/
|
|
function defaultValues(
|
|
checker: ts.TypeChecker,
|
|
symbol: ts.Symbol | undefined,
|
|
spreads: 'reject' | 'skip' = 'reject'
|
|
): DefaultValue[] {
|
|
const literal = symbol && initializerOf(symbol);
|
|
if (!literal || !ts.isObjectLiteralExpression(literal)) return [];
|
|
|
|
const checked = satisfiesType(checker, symbol);
|
|
const values: DefaultValue[] = [];
|
|
|
|
const describe = (key: string, text: string, note?: string): DefaultValue => {
|
|
const field = checked?.getProperty(key);
|
|
|
|
return {
|
|
key,
|
|
text,
|
|
readerDeclarations: field?.declarations ?? [],
|
|
type: field ? printPropertyType(checker, field) : undefined,
|
|
note,
|
|
};
|
|
};
|
|
|
|
for (const property of literal.properties) {
|
|
if (ts.isSpreadAssignment(property) && spreads === 'skip') continue;
|
|
|
|
if (ts.isShorthandPropertyAssignment(property)) {
|
|
values.push(describe(property.name.text, property.name.text));
|
|
} else if (
|
|
ts.isPropertyAssignment(property) &&
|
|
(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
|
|
) {
|
|
const file = literal.getSourceFile();
|
|
|
|
values.push(
|
|
describe(
|
|
property.name.text,
|
|
printDefault(checker, property.initializer, file),
|
|
defaultNote(checker, property.initializer, file)
|
|
)
|
|
);
|
|
} else {
|
|
throw new Error(`Unsupported defaultConfig entry: ${property.getText()}`);
|
|
}
|
|
}
|
|
|
|
return values;
|
|
}
|
|
|
|
/** An exported `const`'s initializer as source, through trailing assertions; `undefined` for any other export. */
|
|
export function exportedLiteral(symbol: ts.Symbol): string | undefined {
|
|
const initializer = initializerOf(symbol);
|
|
|
|
return initializer && ts.isObjectLiteralExpression(initializer) ? printExpression(initializer) : undefined;
|
|
}
|
|
|
|
/** An identifier naming a `const` of the same file prints as that const's initializer, one level down. */
|
|
function printDefault(checker: ts.TypeChecker, expression: ts.Expression, file: ts.SourceFile): string {
|
|
const declaration = sameFileConst(checker, expression, file);
|
|
|
|
return printExpression(declaration ? unwrapAssertions(declaration.initializer!) : expression);
|
|
}
|
|
|
|
/** The JSDoc of the same-file `const` that `printDefault` follows, since printing its initializer drops its name. */
|
|
function defaultNote(checker: ts.TypeChecker, expression: ts.Expression, file: ts.SourceFile): string | undefined {
|
|
const declaration = sameFileConst(checker, expression, file);
|
|
const symbol = declaration && checker.getSymbolAtLocation(declaration.name);
|
|
|
|
return firstSentence(docOf(checker, symbol)).replace(/\.$/, '') || undefined;
|
|
}
|
|
|
|
function sameFileConst(
|
|
checker: ts.TypeChecker,
|
|
expression: ts.Expression,
|
|
file: ts.SourceFile
|
|
): ts.VariableDeclaration | undefined {
|
|
if (!ts.isIdentifier(expression)) return undefined;
|
|
|
|
const symbol = checker.getSymbolAtLocation(expression);
|
|
const declaration = symbol && declarationOf(symbol);
|
|
|
|
return declaration &&
|
|
ts.isVariableDeclaration(declaration) &&
|
|
declaration.initializer &&
|
|
declaration.getSourceFile() === file
|
|
? declaration
|
|
: undefined;
|
|
}
|
|
|
|
function arrayElements(symbol: ts.Symbol | undefined, what: string): ts.Expression[] {
|
|
const initializer = symbol && initializerOf(symbol);
|
|
if (!initializer || !ts.isArrayLiteralExpression(initializer)) throw new Error(`\`${what}\` is not an array literal`);
|
|
|
|
return initializer.elements.map(unwrapAssertions);
|
|
}
|
|
|
|
export function buildModel(reference: ReferenceProgram): Model {
|
|
const { checker, entries } = reference;
|
|
const behaviorsBySymbol = new Map<ts.Symbol, BehaviorInfo>();
|
|
const behaviors: BehaviorInfo[] = [];
|
|
const entryByFile = new Map(entries.map((entry) => [entry.file, entry]));
|
|
const observedKeys = new Map<BehaviorInfo, string[]>();
|
|
|
|
const registerBehavior = (symbol: ts.Symbol): BehaviorInfo | undefined => {
|
|
const existing = behaviorsBySymbol.get(symbol);
|
|
if (existing) return existing;
|
|
|
|
const contract = behaviorFromType(checker, checker.getTypeOfSymbol(symbol), initializerOf(symbol));
|
|
const file = declaringFile(symbol);
|
|
if (!contract || !file) return undefined;
|
|
|
|
const { doc, observes } = withoutObservesTags(behaviorDoc(checker, symbol));
|
|
const info: BehaviorInfo = {
|
|
name: symbol.name,
|
|
label: symbol.name,
|
|
exported: true,
|
|
external: false,
|
|
file,
|
|
entry: entryByFile.get(file),
|
|
doc,
|
|
...contract,
|
|
};
|
|
|
|
if (observes.length) observedKeys.set(info, observes);
|
|
|
|
behaviorsBySymbol.set(symbol, info);
|
|
behaviors.push(info);
|
|
|
|
return info;
|
|
};
|
|
|
|
// Behavior entries first, so features link to them rather than register them as strays.
|
|
for (const entry of entries) {
|
|
if (entry.layer !== 'behavior' && entry.layer !== 'behavior-dom') continue;
|
|
|
|
for (const exported of moduleExports(reference, entry.file)) {
|
|
const symbol = resolveAlias(checker, exported);
|
|
|
|
if (symbol.flags & ts.SymbolFlags.Value) registerBehavior(symbol);
|
|
}
|
|
}
|
|
|
|
const behaviorFromElement = (element: ts.Expression, where: string): BehaviorInfo => {
|
|
if (ts.isIdentifier(element)) {
|
|
const symbol = checker.getSymbolAtLocation(element);
|
|
const info = symbol && registerBehavior(resolveAlias(checker, symbol));
|
|
if (!info) throw new Error(`${where}: \`${element.text}\` is not a behavior`);
|
|
|
|
return info;
|
|
}
|
|
|
|
const contract = behaviorFromType(checker, checker.getTypeAtLocation(element), element);
|
|
if (!contract) throw new Error(`${where}: \`${printExpression(element)}\` is not a behavior`);
|
|
|
|
// `factory<T>()({ ... })` is labeled `factory<T>`; any other expression by its full text.
|
|
const callee = ts.isCallExpression(element) ? element.expression : element;
|
|
const label = ts.isCallExpression(callee) ? printExpression(callee).replace(/\(\)$/, '') : printExpression(callee);
|
|
|
|
return {
|
|
name: printExpression(element),
|
|
label,
|
|
exported: false,
|
|
external: label.startsWith('defineExternalSignals'),
|
|
file: element.getSourceFile().fileName,
|
|
entry: undefined,
|
|
doc: EMPTY_DOC,
|
|
...contract,
|
|
};
|
|
};
|
|
|
|
const features: FeatureInfo[] = [];
|
|
const featuresBySymbol = new Map<ts.Symbol, FeatureInfo>();
|
|
|
|
for (const entry of entries) {
|
|
if (entry.layer !== 'feature') continue;
|
|
|
|
const exports = new Map(moduleExports(reference, entry.file).map((symbol) => [symbol.name, symbol]));
|
|
const featureSymbol = [...exports.values()].find((symbol) => {
|
|
const initializer = initializerOf(symbol);
|
|
|
|
return initializer && ts.isCallExpression(initializer) && initializer.expression.getText() === 'defineFeature';
|
|
});
|
|
if (!featureSymbol) throw new Error(`${entry.file}: no \`defineFeature(...)\` export`);
|
|
|
|
const info: FeatureInfo = {
|
|
name: featureSymbol.name,
|
|
entry,
|
|
file: entry.file,
|
|
doc: docOf(checker, featureSymbol),
|
|
behaviors: arrayElements(exports.get('behaviors'), `${entry.key} behaviors`).map((element) =>
|
|
behaviorFromElement(element, entry.key)
|
|
),
|
|
defaults: defaultValues(checker, exports.get('defaultConfig')),
|
|
initial: defaultValues(checker, exports.get('initialState')),
|
|
config: typeFields(checker, exports.get('Config')),
|
|
state: typeFields(checker, exports.get('State')),
|
|
context: typeFields(checker, exports.get('Context')),
|
|
composedBy: [],
|
|
};
|
|
|
|
features.push(info);
|
|
featuresBySymbol.set(resolveAlias(checker, featureSymbol), info);
|
|
}
|
|
|
|
const engines: EngineInfo[] = [];
|
|
|
|
for (const entry of entries) {
|
|
if (entry.layer !== 'engine') continue;
|
|
|
|
const exports = new Map(moduleExports(reference, entry.file).map((symbol) => [symbol.name, symbol]));
|
|
const createEngine = exports.get('createEngine');
|
|
if (!createEngine) throw new Error(`${entry.file}: no \`createEngine\` export`);
|
|
|
|
const engineFeatures = arrayElements(exports.get('features'), `${entry.key} features`).map((element) => {
|
|
const symbol = ts.isIdentifier(element) ? checker.getSymbolAtLocation(element) : undefined;
|
|
const feature = symbol && featuresBySymbol.get(resolveAlias(checker, symbol));
|
|
if (!feature) throw new Error(`${entry.key}: \`${element.getText()}\` is not a feature entry`);
|
|
|
|
return feature;
|
|
});
|
|
|
|
// `flattenFeatures` composes a behavior once, at its first position.
|
|
const flattened = [...new Set(engineFeatures.flatMap((feature) => feature.behaviors))];
|
|
|
|
const info: EngineInfo = {
|
|
name: entry.name,
|
|
entry,
|
|
file: entry.file,
|
|
doc: docOf(checker, createEngine),
|
|
features: engineFeatures,
|
|
behaviors: flattened,
|
|
initial: defaultValues(checker, exports.get('initialState'), 'skip'),
|
|
config: typeFields(checker, exports.get('EngineConfig')),
|
|
state: typeFields(checker, exports.get('EngineState')),
|
|
context: typeFields(checker, exports.get('EngineContext')),
|
|
};
|
|
|
|
engines.push(info);
|
|
|
|
for (const feature of engineFeatures) feature.composedBy.push(info);
|
|
}
|
|
|
|
for (const [info, keys] of observedKeys) addObservedRows(info, keys, behaviors);
|
|
|
|
return { behaviors, features, engines };
|
|
}
|
|
|
|
/**
|
|
* A behavior's doc less its `@observes` tags, and the state keys those tags name. A behavior observes a key it reads
|
|
* without declaring, through a cast or a helper's optional parameter, which its setup type cannot show.
|
|
*/
|
|
export function withoutObservesTags(doc: DocBlock): { doc: DocBlock; observes: string[] } {
|
|
const observes = doc.tags
|
|
.filter((tag) => tag.name === 'observes')
|
|
.flatMap((tag) => tag.text.split(/[\s,]+/).filter(Boolean));
|
|
|
|
return { doc: { ...doc, tags: doc.tags.filter((tag) => tag.name !== 'observes') }, observes };
|
|
}
|
|
|
|
/** Each observed key as an optional, undeclared state read, typed and documented from the behavior that declares it. */
|
|
function addObservedRows(info: BehaviorInfo, keys: readonly string[], behaviors: readonly BehaviorInfo[]): void {
|
|
const rows = keys
|
|
.filter((key) => !info.state.some((row) => row.key === key))
|
|
.map((key) => {
|
|
const declared = behaviors.flatMap((other) => other.state.filter((row) => row.key === key && row.declared));
|
|
const origin = declared.find((row) => row.access === 'writes') ?? declared[0];
|
|
if (!origin) throw new Error(`${info.name}: \`@observes ${key}\` names a key no behavior declares`);
|
|
|
|
return { ...origin, access: 'reads' as const, declared: false, optional: true, observed: true };
|
|
});
|
|
|
|
info.state = [...info.state, ...rows].sort((a, b) => a.key.localeCompare(b.key));
|
|
}
|