@chartguard/schema-generator 0.0.0-stage → 0.1.1

package/lib/emitter.mjs

@@ -0,0 +1,333 @@
+import { createHash } from 'node:crypto';
+
+import ts from 'typescript';
+
+import { deprecationOf } from './deprecation.mjs';
+import { Provenance } from './provenance.mjs';
+
+const MAX_DEFINITIONS = 50_000;
+/** Longer printed types are abbreviated with a content hash so distinct types never share a name. */
+const NAME_LENGTH = 120;
+const NAME_PREFIX = 80;
+const NAME_FLAGS = ts.TypeFormatFlags.NoTruncation;
+/** Platform objects (CanvasGradient, HTMLElement, …) are checked only as "some object". */
+/** An object TypeScript's library declares: opaque; a platform class adds `host`, which a plain object never is. */
+const HOST_OBJECT = { kind: 'object', additional: 'open', properties: {} };
+/**
+ * TypeScript's global function interfaces declare no call signature, so they would pass for
+ * platform objects; a value of these types is a function (`(Function | Options)` in Highcharts).
+ */
+const GLOBAL_FUNCTIONS = new Set(['Function', 'CallableFunction', 'NewableFunction']);
+/** A union whose emitted node is larger than this is stored once as a definition and referenced. */
+const SHARED_UNION_BYTES = 300;
+
+function isFlag(type, flag) {
+	return (type.flags & flag) !== 0;
+}
+
+function withoutUndefined(types) {
+	return types.filter((type) => !isFlag(type, ts.TypeFlags.Undefined | ts.TypeFlags.Void));
+}
+
+const PRIMITIVE_FLAGS = ts.TypeFlags.StringLike | ts.TypeFlags.NumberLike | ts.TypeFlags.BooleanLike;
+
+function isPrimitiveLike(type) {
+	return isFlag(type, PRIMITIVE_FLAGS);
+}
+
+/** Symbol-keyed members (`[Symbol.iterator]`) cannot occur in a configuration object. */
+function isStringKeyed(symbol) {
+	return !symbol.escapedName.startsWith('__@');
+}
+
+/**
+ * A readable, collision-free definition name. The full printed type is kept when short;
+ * otherwise a prefix plus a hash of the whole text, so unrelated types never collapse into one name.
+ */
+function definitionName(printed) {
+	const name = printed.replace(/\s+/g, ' ').trim();
+	if (name.length <= NAME_LENGTH) return name;
+	const digest = createHash('sha256').update(name).digest('hex').slice(0, 10);
+	return `${name.slice(0, NAME_PREFIX)}…#${digest}`;
+}
+
+/**
+ * Converts TypeScript types into SchemaIR nodes. Object types become shared
+ * definitions so recursive and repeated types stay finite.
+ */
+export class TypeEmitter {
+	constructor({
+		program,
+		checker,
+		sourceId,
+		packageName,
+		opaque = new Set(),
+		open = new Set(),
+		registries = new Map(),
+		runtimeOptional = new Set(),
+		widened = new Map(),
+		wrappers = new Set()
+	}) {
+		this.program = program;
+		this.checker = checker;
+		this.provenance = new Provenance(checker, { sourceId, packageName });
+		/** Types whose contents the declarations do not describe (caller-chosen data). */
+		this.opaque = opaque;
+		/** Object types that are documented extension points. */
+		this.open = open;
+		/**
+		 * Union type → `{ registry, provenance }`: the runtime registry its variants are looked up in,
+		 * which plugins extend, so the union is extensible and checked against the caller's registry.
+		 */
+		this.registries = registries;
+		/** Property symbols the declarations require but the runtime defaults. */
+		this.runtimeOptional = runtimeOptional;
+		/**
+		 * Property declaration node → extra IR nodes the runtime also accepts there. Keyed by the
+		 * declaration, because a property reached through an intersection is a transient symbol.
+		 */
+		// A key without a declaration would widen every declaration-less property (keys a mapped type synthesizes).
+		if (widened.has(undefined)) throw new Error('widened: a property without a declaration cannot be widened');
+		this.widened = widened;
+		/** Alias names of homomorphic mapped wrappers (`DeepPartial`) that pass primitives through unchanged. */
+		this.wrappers = wrappers;
+		/** Type → builder of a replacement node, for positions the declarations do not describe faithfully. */
+		this.overrides = new Map();
+		this.definitions = {};
+		this.names = new Map();
+		this.usedNames = new Set();
+		this.sharedUnions = new Map();
+	}
+
+	emit(type) {
+		const override = this.overrides.get(type);
+		if (override !== undefined) return override();
+		if (this.opaque.has(type)) return { kind: 'unknown' };
+		const primitive = this.emitPrimitive(type);
+		if (primitive !== undefined) return primitive;
+		if (type.isUnion()) return this.emitUnion(type);
+		if (isFlag(type, ts.TypeFlags.Object | ts.TypeFlags.Intersection)) return this.emitObjectLike(type);
+		return { kind: 'unknown' };
+	}
+
+	emitPrimitive(type) {
+		if (isFlag(type, ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) return { kind: 'unknown' };
+		if (isFlag(type, ts.TypeFlags.StringLike & ~ts.TypeFlags.StringLiteral)) return { kind: 'string' };
+		if (isFlag(type, ts.TypeFlags.NumberLike & ~ts.TypeFlags.NumberLiteral)) return { kind: 'number' };
+		if (type.isStringLiteral() || type.isNumberLiteral()) return { kind: 'literal', value: type.value };
+		if (isFlag(type, ts.TypeFlags.BooleanLiteral))
+			return { kind: 'literal', value: type === this.checker.getTrueType() };
+		if (isFlag(type, ts.TypeFlags.Null)) return { kind: 'null' };
+		return undefined;
+	}
+
+	/**
+	 * Distinct TypeScript types can emit the same node (`string[]` twice via different wrappers); keep one.
+	 * A large union the package names (`AnimationEasing`) is emitted once as a definition and referenced.
+	 */
+	emitUnion(type) {
+		const node = this.buildUnion(type);
+		return node.kind === 'union' ? this.share(node, type) : node;
+	}
+
+	/**
+	 * Large unions recur under many properties (an easing name list, a color union). Keyed by
+	 * their emitted content, so the same union reached through `T` or an optional `T | undefined`
+	 * is stored once; the first type that produced it names the definition.
+	 */
+	share(node, type) {
+		const content = JSON.stringify(node);
+		if (content.length <= SHARED_UNION_BYTES) return node;
+		const existing = this.sharedUnions.get(content);
+		if (existing !== undefined) return { kind: 'ref', ref: existing };
+		const printed = this.checker.typeToString(type, undefined, NAME_FLAGS).replace(/ \| undefined$/, '');
+		const name = this.uniqueName(definitionName(printed));
+		this.sharedUnions.set(content, name);
+		this.definitions[name] = node;
+		return { kind: 'ref', ref: name };
+	}
+
+	buildUnion(type) {
+		const members = withoutUndefined(type.types);
+		const booleans = members.filter((member) => isFlag(member, ts.TypeFlags.BooleanLiteral));
+		const rest = members.filter((member) => !isFlag(member, ts.TypeFlags.BooleanLiteral));
+		const nodes = [...(booleans.length === 2 ? [{ kind: 'boolean' }] : booleans.map((b) => this.emit(b)))];
+		nodes.push(...rest.map((member) => this.emit(member)));
+		const unique = [...new Map(nodes.map((node) => [JSON.stringify(node), node])).values()];
+		if (unique.length === 1) return unique[0];
+		return this.withDiscriminator({ kind: 'union', anyOf: unique }, rest, this.registryOf(type));
+	}
+
+	/** Callers may name either `T` or the `T | undefined` of an optional property. */
+	registryOf(type) {
+		return this.registries.get(type) ?? this.registries.get(this.checker.getNonNullableType(type));
+	}
+
+	withDiscriminator(union, members, registered) {
+		const discriminator = this.discriminatorOf(members);
+		if (discriminator === undefined) return union;
+		if (registered === undefined) return { ...union, discriminator };
+		return {
+			...union,
+			discriminator,
+			extensible: true,
+			registry: registered.registry,
+			...(registered.extensionPoint === undefined ? {} : { extensionPoint: registered.extensionPoint }),
+			provenance: registered.provenance
+		};
+	}
+
+	/**
+	 * A property present in every object member whose literal values are disjoint. Array members
+	 * are left out: the engine tells arrays from objects by runtime kind, so `T | T[]` (which
+	 * TypeScript flattens into one union) still discriminates its object members.
+	 */
+	discriminatorOf(members) {
+		const objects = members.filter((member) => !this.checker.isArrayType(member) && !this.checker.isTupleType(member));
+		if (
+			objects.length < 2 ||
+			!objects.every((member) => isFlag(member, ts.TypeFlags.Object | ts.TypeFlags.Intersection))
+		)
+			return undefined;
+		const [first] = objects;
+		const candidates = this.checker.getPropertiesOfType(first).map((symbol) => symbol.name);
+		return candidates.find((name) => this.isDiscriminator(objects, name));
+	}
+
+	isDiscriminator(members, name) {
+		const seen = new Set();
+		for (const member of members) {
+			const symbol = this.checker.getPropertyOfType(member, name);
+			if (symbol === undefined) return false;
+			const type = this.checker.getTypeOfSymbol(symbol);
+			const literals = withoutUndefined(type.isUnion() ? type.types : [type]);
+			if (literals.length === 0 || !literals.every((literal) => literal.isStringLiteral())) return false;
+			for (const literal of literals) {
+				if (seen.has(literal.value)) return false;
+				seen.add(literal.value);
+			}
+		}
+		return true;
+	}
+
+	/**
+	 * What TypeScript's default library declares a type to be, also when wrapped in a generic such as
+	 * `DeepPartial<T>`: `{ host: name }` for a platform class (an interface with a global constructor:
+	 * `Date`, `CanvasGradient`, `HTMLElement`), `{}` for an options dictionary it declares (`Intl.
+	 * NumberFormatOptions`), opaque either way since the library's own types are no pinned source (D5);
+	 * undefined for anything else. A mapped type (`Partial<T>`, `Pick`, `Omit`, `Record`) is declared
+	 * there too, as an anonymous type literal, but it is an object with the properties it maps (D3, D6).
+	 */
+	libraryType(type) {
+		const symbol = type.getSymbol();
+		const declared = (symbol?.declarations ?? []).some((declaration) =>
+			this.program.isSourceFileDefaultLibrary(declaration.getSourceFile())
+		);
+		const named = symbol !== undefined && (symbol.flags & (ts.SymbolFlags.Interface | ts.SymbolFlags.Class)) !== 0;
+		if (declared && named) {
+			const constructed = (symbol.flags & (ts.SymbolFlags.Variable | ts.SymbolFlags.Class)) !== 0;
+			return constructed ? { host: symbol.name } : {};
+		}
+		const [wrapped, ...rest] = type.aliasTypeArguments ?? [];
+		return wrapped !== undefined && rest.length === 0 ? this.libraryType(wrapped) : undefined;
+	}
+
+	emitObjectLike(type) {
+		if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) return { kind: 'function' };
+		if (GLOBAL_FUNCTIONS.has(type.getSymbol()?.escapedName) && this.isLibraryDeclared(type.getSymbol()))
+			return { kind: 'function' };
+		if (this.checker.isArrayType(type) || this.checker.isTupleType(type)) return this.emitArray(type);
+		const unwrapped = this.emitUnwrapped(type);
+		if (unwrapped !== undefined) return unwrapped;
+		const library = this.libraryType(type);
+		if (library !== undefined) return this.reference(type, () => ({ ...HOST_OBJECT, ...library }));
+		return this.reference(type);
+	}
+
+	isLibraryDeclared(symbol) {
+		return (symbol?.declarations ?? []).some((declaration) =>
+			this.program.isSourceFileDefaultLibrary(declaration.getSourceFile())
+		);
+	}
+
+	/**
+	 * Homomorphic wrappers such as `DeepPartial<T>` also map over primitives and arrays. A wrapped
+	 * array is recognized by its numeric index plus the built-in `length`, and keeps its
+	 * (partial) element type; a wrapped primitive is still that primitive. Only the wrappers
+	 * named in `wrappers` qualify: `Wrap<T> = { v: T }` is an object, whatever `T` is.
+	 */
+	emitUnwrapped(type) {
+		const array = this.emitWrappedArray(type);
+		if (array !== undefined) return array;
+		if (!this.wrappers.has(type.aliasSymbol?.name)) return undefined;
+		const [wrapped, ...rest] = type.aliasTypeArguments ?? [];
+		if (wrapped === undefined || rest.length > 0) return undefined;
+		const members = wrapped.isIntersection() ? wrapped.types : [wrapped];
+		const primitive = members.find(isPrimitiveLike);
+		return primitive === undefined ? undefined : this.emit(primitive);
+	}
+
+	emitWrappedArray(type) {
+		const element = this.checker.getIndexInfoOfType(type, ts.IndexKind.Number)?.type;
+		if (element === undefined || !this.isLibraryDeclared(this.checker.getPropertyOfType(type, 'length')))
+			return undefined;
+		return { kind: 'array', items: this.emit(element) };
+	}
+
+	emitArray(type) {
+		const elements = this.checker.getTypeArguments(type);
+		if (elements.length === 1) return { kind: 'array', items: this.emit(elements[0]) };
+		const items = this.checker.getUnionType(elements);
+		return { kind: 'array', items: this.emit(items) };
+	}
+
+	/** One shared definition per type, so repeated and recursive types stay finite. */
+	reference(type, build = () => this.emitObject(type)) {
+		const existing = this.names.get(type);
+		if (existing !== undefined) return { kind: 'ref', ref: existing };
+		if (this.names.size >= MAX_DEFINITIONS) return { kind: 'unknown' };
+		const name = this.uniqueName(definitionName(this.checker.typeToString(type, undefined, NAME_FLAGS)));
+		this.names.set(type, name);
+		this.definitions[name] = { kind: 'unknown' };
+		this.definitions[name] = build();
+		return { kind: 'ref', ref: name };
+	}
+
+	uniqueName(base) {
+		let name = base;
+		for (let suffix = 2; this.usedNames.has(name); suffix++) name = `${base}~${String(suffix)}`;
+		this.usedNames.add(name);
+		return name;
+	}
+
+	emitObject(type) {
+		const [index] = this.checker.getIndexInfosOfType(type);
+		const properties = this.checker.getPropertiesOfType(type).filter(isStringKeyed);
+		if (index !== undefined && properties.length === 0) return { kind: 'record', values: this.emit(index.type) };
+		const owner = this.provenance.ownerOf(type);
+		const entries = properties.map((symbol) => [symbol.name, this.emitProperty(symbol, owner)]);
+		return {
+			kind: 'object',
+			additional: index === undefined && !this.open.has(type) ? 'closed' : 'open',
+			provenance: this.provenance.of(owner),
+			properties: Object.fromEntries(entries)
+		};
+	}
+
+	/** Keys synthesized by mapped types have no declaration of their own; they cite their owner type. */
+	emitProperty(symbol, owner) {
+		const declared = this.emit(this.checker.getTypeOfSymbol(symbol));
+		const declaration = symbol.declarations?.[0];
+		const extra = declaration === undefined ? undefined : this.widened.get(declaration);
+		const node = extra === undefined ? declared : { kind: 'union', anyOf: [declared, ...extra] };
+		const optional = (symbol.flags & ts.SymbolFlags.Optional) !== 0 || this.runtimeOptional.has(symbol);
+		const provenance = this.provenance.of(declaration === undefined ? owner : symbol);
+		const deprecated = deprecationOf(symbol);
+		return {
+			node,
+			provenance,
+			...(optional ? {} : { required: true }),
+			...(deprecated === undefined ? {} : { deprecated })
+		};
+	}
+}

package/lib/generate.mjs

@@ -0,0 +1,35 @@
+import { checkArtifact } from '@chartguard/config-core';
+
+import { generateChartjs } from './chartjs.mjs';
+import { serialize, withDigest } from './digest.mjs';
+import { generateEcharts } from './echarts.mjs';
+import { generateHighcharts } from './highcharts.mjs';
+import { untracedFacts } from './trace.mjs';
+
+const GENERATORS = { chartjs: generateChartjs, echarts: generateEcharts, highcharts: generateHighcharts };
+
+/** The libraries this generator builds schema artifacts for: `chartjs`, `echarts`, `highcharts`. */
+export const LIBRARIES = Object.keys(GENERATORS);
+
+/** Upstream licenses under which a derived artifact may be committed and published. */
+const REDISTRIBUTABLE = new Set(['allowed-with-attribution', 'allowed-with-license-and-notice']);
+
+/** Whether the pin's upstream license lets an artifact derived from it be committed and published. */
+export function isRedistributable(pin) {
+	return REDISTRIBUTABLE.has(pin.license.redistribution);
+}
+
+/**
+ * The artifact for `library` from the install under `root`, as deterministic text carrying the
+ * digest of its own content; never a malformed one, nor one with a fact that does not trace to its source.
+ */
+export function generateArtifact(root, library, pin) {
+	const artifact = withDigest(GENERATORS[library](root, pin));
+	const { problems } = checkArtifact(artifact);
+	if (problems.length > 0)
+		throw new Error(`${library}: generated artifact is malformed:\n${problems.slice(0, 20).join('\n')}`);
+	const untraced = untracedFacts(root, artifact);
+	if (untraced.length > 0)
+		throw new Error(`${library}: generated facts do not trace to their source:\n${untraced.slice(0, 20).join('\n')}`);
+	return { artifact, text: serialize(artifact) };
+}

package/lib/highcharts-runtime.mjs

@@ -0,0 +1,198 @@
+import { sameNode, upstreamChanged } from './nodes.mjs';
+import { runtimePointer } from './runtime.mjs';
+
+/**
+ * What the Highcharts declarations leave narrower than the runtime, found by running the official
+ * demos (CG-01-05 part 4) and read from the pinned runtime code, each fact citing its line:
+ *
+ * - options are read with `pick()`, which skips `null` like `undefined`: a `null` optional option
+ *   is unset (`chart.plotBackgroundColor: null`, `yAxis.title.text: null` in the demos);
+ * - `dashstyleSetter` lower-cases the value and turns words and comma lists into a dash array;
+ * - category labels are `categories[pos] ?? names[pos] ?? pos`: numbers label as well as strings;
+ * - `optionsToObject` maps a number, `null` or any array to a point by the series' `keys` or
+ *   `pointArrayMap`, whatever tuples the declarations list; `getX` parses a string `x` as a date,
+ *   and x-range points parse `x2` the same way and take `partialFill` as a bare amount;
+ * - radial axes take `labels.rotation: 'auto'`; organization charts, like every sankey-based
+ *   series, take `nodeWidth: 'auto'`; `time.useUTC` is a boolean, as its own documentation says;
+ * - `dataMapping` keys are point properties (the declaration is an empty interface that says so);
+ * - a text's `style.width` is read with `pInt`, so a CSS length (`'90px'`) is a width as well as a number;
+ * - `plotOptions.series` is merged into every series, so it takes the options of every series type.
+ */
+const FACTS = {
+	pick: { file: 'highcharts.src.js', pattern: "if (typeof arg !== 'undefined' && arg !== null) {" },
+	dashStyle: { file: 'highcharts.src.js', pattern: 'value = value.toLowerCase();' },
+	categories: { file: 'highcharts.src.js', pattern: '(categories[pos] ?? names[pos] ?? pos) :' },
+	points: { file: 'highcharts.src.js', pattern: 'pointArrayMap = keys || series.pointArrayMap' },
+	pointX: { file: 'highcharts.src.js', pattern: '// If x is a string, try to parse it to a datetime' },
+	pointX2: { file: 'modules/xrange.src.js', pattern: 'this.x2 = this.series.chart.time.parse(this.x2);' },
+	partialFill: { file: 'modules/xrange.src.js', pattern: 'partialFill = point.partialFill ?? 0;' },
+	rotation: { file: 'highcharts-more.src.js', pattern: "if (labelOptions.rotation === 'auto') {" },
+	nodeWidth: { file: 'modules/sankey.src.js', pattern: "if (nodeWidth === 'auto') {" },
+	useUTC: { file: 'highcharts.d.ts', pattern: 'Setting `useUTC` to true is equivalent to setting `time.timezone` to' },
+	dataMapping: { file: 'highcharts.d.ts', pattern: 'export interface DataMappingOptionsObject {}' },
+	plotSeries: { file: 'highcharts.src.js', pattern: 'const options = merge(typeOptions, plotOptions.series,' },
+	cssWidth: { file: 'highcharts.src.js', pattern: 'textWidth = this.textWidth = pInt(styles.width);' }
+};
+
+const ANY_ARRAY = { kind: 'array', items: { kind: 'unknown' } };
+const changed = upstreamChanged('highcharts types');
+
+/** The provenance with one more runtime source; a node without provenance gets the runtime fact as its own. */
+const withSource = (provenance, source) =>
+	provenance === undefined
+		? { confidence: 'authoritative', sources: [source] }
+		: { ...provenance, sources: [...provenance.sources, source] };
+
+/** `node` also accepting `extra` members it does not have yet. */
+function widened(node, extra) {
+	const members = node.kind === 'union' ? node.anyOf : [node];
+	const added = extra.filter((member) => !members.some((known) => sameNode(known, member)));
+	return added.length === 0 ? node : { kind: 'union', anyOf: [...members, ...added] };
+}
+
+/** A step: the `key` property of the definitions `owners` names, transformed and citing the fact. */
+function property(owners, key, transform) {
+	return (definitions, source) => {
+		const changes = owners(definitions).flatMap((name) => {
+			const definition = definitions[name];
+			const known = definition?.properties?.[key];
+			if (known === undefined) throw changed(`${name}.${key}`);
+			const next = { ...known, node: transform(known.node), provenance: withSource(known.provenance, source) };
+			return [[name, { ...definition, properties: { ...definition.properties, [key]: next } }]];
+		});
+		return { ...definitions, ...Object.fromEntries(changes) };
+	};
+}
+
+/** Object definitions with a `key` property whose definition name and node pass `test`. */
+const objectsWith =
+	(key, test = () => true) =>
+	(definitions) =>
+		Object.keys(definitions).filter((name) => {
+			const known = definitions[name].kind === 'object' ? definitions[name].properties[key] : undefined;
+			return known !== undefined && test(name, known.node);
+		});
+
+/** Every object definition: a null optional option is unset. */
+function nullAsAbsent(definitions, source) {
+	const entries = Object.entries(definitions).map(([name, node]) =>
+		node.kind === 'object'
+			? [name, { ...node, nullAsAbsent: true, provenance: withSource(node.provenance, source) }]
+			: [name, node]
+	);
+	return Object.fromEntries(entries);
+}
+
+/** A list of points: a number, `null` and any array are points too; object members stay as declared. */
+function points(node) {
+	if (node.kind !== 'array') return node;
+	const members = node.items.kind === 'union' ? node.items.anyOf : [node.items];
+	const declared = members.filter((member) => member.kind !== 'array');
+	return {
+		kind: 'array',
+		items: widened({ kind: 'union', anyOf: declared }, [{ kind: 'number' }, { kind: 'null' }, ANY_ARRAY])
+	};
+}
+
+const categories = (node) =>
+	node.kind === 'array' ? { kind: 'array', items: widened(node.items, [{ kind: 'number' }]) } : node;
+
+function dashStyle(definitions, source) {
+	const union = definitions.DashStyleValue;
+	if (union?.kind !== 'union' || !union.anyOf.every((member) => member.kind === 'literal'))
+		throw changed('DashStyleValue');
+	return { ...definitions, DashStyleValue: { kind: 'string', provenance: withSource(union.provenance, source) } };
+}
+
+function dataMapping(definitions, source) {
+	const mapping = definitions.DataMappingOptionsObject;
+	if (mapping?.kind !== 'object' || Object.keys(mapping.properties).length > 0)
+		throw changed('DataMappingOptionsObject');
+	return {
+		...definitions,
+		DataMappingOptionsObject: { ...mapping, additional: 'open', provenance: withSource(mapping.provenance, source) }
+	};
+}
+
+/** `plotOptions.series`: its own options, then every option of every series type, a name taking each distinct type. */
+function anySeriesOptions(definitions, plotOptions, source) {
+	const own = definitions[plotOptions.properties.series.node.ref];
+	const collected = new Map(
+		Object.entries(own.properties).map(([key, known]) => [key, { known, nodes: [known.node] }])
+	);
+	for (const [key, entry] of Object.entries(plotOptions.properties)) {
+		const options = key === 'series' || entry.node.kind !== 'ref' ? undefined : definitions[entry.node.ref];
+		for (const [name, known] of Object.entries(options?.properties ?? {})) {
+			const found = collected.get(name) ?? { known, nodes: [] };
+			if (!found.nodes.some((node) => sameNode(node, known.node))) found.nodes.push(known.node);
+			collected.set(name, found);
+		}
+	}
+	const properties = [...collected].map(([name, { known, nodes }]) => [
+		name,
+		{
+			...known,
+			node: nodes.length === 1 ? nodes[0] : { kind: 'union', anyOf: nodes },
+			provenance: withSource(known.provenance, source)
+		}
+	]);
+	return { ...own, properties: Object.fromEntries(properties) };
+}
+
+/** `plotOptions.series` pointing at the merged options of every series type. */
+function anySeries(definitions, optionName, source) {
+	const name = definitions[optionName].properties.plotOptions.node.ref;
+	const plotOptions = definitions[name];
+	const series = { ...plotOptions.properties.series, node: { kind: 'ref', ref: 'AnySeriesPlotOptions' } };
+	return {
+		...definitions,
+		AnySeriesPlotOptions: anySeriesOptions(definitions, plotOptions, source),
+		[name]: { ...plotOptions, properties: { ...plotOptions.properties, series } }
+	};
+}
+
+/** A step: the `key` property of the definitions `owners` names also accepts `extra`. */
+const alsoAccepts = (owners, key, ...extra) => property(owners, key, (node) => widened(node, extra));
+const named =
+	(...names) =>
+	() =>
+		names;
+const STRING = { kind: 'string' };
+
+/** The facts in the order they apply; later steps see what earlier ones produced. */
+function steps({ optionName, seriesVariants }) {
+	const isPointX = (name, node) => name.endsWith('PointOptionsObject') && node.kind === 'number';
+	// Indicator series (`abands`, …) take their data from `linkedTo` and declare none.
+	const withData = (defs) => seriesVariants.filter((name) => defs[name].properties.data !== undefined);
+	return [
+		['pick', nullAsAbsent],
+		[
+			'categories',
+			property(
+				objectsWith('categories', (_, node) => node.kind === 'array'),
+				'categories',
+				categories
+			)
+		],
+		['points', property(withData, 'data', points)],
+		['pointX', alsoAccepts(objectsWith('x', isPointX), 'x', STRING)],
+		['pointX2', alsoAccepts(named('XrangePointOptionsObject'), 'x2', STRING)],
+		['partialFill', alsoAccepts(named('XrangePointOptionsObject'), 'partialFill', { kind: 'number' })],
+		[
+			'rotation',
+			alsoAccepts(named('XAxisLabelsOptions', 'YAxisLabelsOptions'), 'rotation', { kind: 'literal', value: 'auto' })
+		],
+		['nodeWidth', alsoAccepts(objectsWith('nodeWidth'), 'nodeWidth', STRING)],
+		['useUTC', alsoAccepts((defs) => [defs[optionName].properties.time.node.ref], 'useUTC', { kind: 'boolean' })],
+		['dashStyle', dashStyle],
+		['dataMapping', dataMapping],
+		['cssWidth', alsoAccepts(named('CSSObject'), 'width', STRING)],
+		['plotSeries', (defs, source) => anySeries(defs, optionName, source)]
+	];
+}
+
+/** New definitions with the runtime facts above applied, one step after the other, each citing its line. */
+export function withHighchartsRuntimeFacts(root, definitions, shape) {
+	const cite = (fact) => ({ source: 'highcharts', pointer: runtimePointer(root, 'highcharts', FACTS[fact]) });
+	return steps(shape).reduce((defs, [fact, step]) => step(defs, cite(fact)), definitions);
+}

package/lib/highcharts.mjs

@@ -0,0 +1,105 @@
+import { omit } from './digest.mjs';
+import { TypeEmitter } from './emitter.mjs';
+import { withHighchartsRuntimeFacts } from './highcharts-runtime.mjs';
+import { upstreamChanged } from './nodes.mjs';
+import { createEntryProgram, exportedAliasTypes } from './program.mjs';
+import { runtimePointer, runtimeSection } from './runtime.mjs';
+import { artifactOf } from './types.mjs';
+
+const SOURCE_ID = 'highcharts';
+
+/**
+ * `Options` from `highcharts.d.ts`, which imports the option declarations of every series type
+ * (`options/*.d.ts`): the full option set, like the ECharts full bundle.
+ */
+const ENTRY = ["import type { Options } from 'highcharts';", 'export type Option = Options;'].join('\n');
+
+/**
+ * `Chart#initSeries` resolves `options.type || chart.type` in the series registry and throws error
+ * #17 for a type no loaded module registered. A series without `type` (the declarations'
+ * `UnknownSeriesOptions`) takes `chart.type`, which `ChartDefaults` sets to `'line'`.
+ */
+const SERIES_LOOKUP = { file: 'highcharts.src.js', pattern: 'error(17, true, chart, { missingModuleFor: type });' };
+const SERIES_TYPE = {
+	file: 'highcharts.src.js',
+	pattern: 'optionsChart.type), SeriesClass = Chart_seriesTypes[type];'
+};
+const CHART_DEFAULTS = { file: 'highcharts.src.js', pattern: 'const ChartDefaults = {', end: '};' };
+/** A member of the `ChartDefaults` object itself, not of a nested one: four spaces of indentation. */
+const DEFAULT_TYPE = /^ {4}type: '(\w+)',$/;
+
+const changed = upstreamChanged('highcharts types');
+
+function typeLiteral(definitions, member) {
+	const target = member.kind === 'ref' ? definitions[member.ref] : member;
+	const type = target?.kind === 'object' ? target.properties.type?.node : undefined;
+	return type?.kind === 'literal' ? type.value : undefined;
+}
+
+/** The runtime's default chart type, and the lines that make it the default of a series without type. */
+function seriesDefault(root) {
+	const defaults = runtimeSection(root, 'highcharts', CHART_DEFAULTS);
+	const index = defaults.lines.findIndex((line) => DEFAULT_TYPE.test(line));
+	if (index === -1) throw new Error(`highcharts runtime changed: no default chart type at ${defaults.pointer}`);
+	const pointers = [
+		runtimePointer(root, 'highcharts', SERIES_LOOKUP),
+		runtimePointer(root, 'highcharts', SERIES_TYPE),
+		defaults.pointerAt(index)
+	];
+	return {
+		fallback: DEFAULT_TYPE.exec(defaults.lines[index])[1],
+		provenance: { confidence: 'authoritative', sources: pointers.map((pointer) => ({ source: SOURCE_ID, pointer })) }
+	};
+}
+
+/**
+ * A series variant whose `type` is no longer required: the runtime takes it from `chart.type`
+ * (the declarations say so themselves with `UnknownSeriesOptions = Omit<…, "type">`).
+ */
+function withOptionalType(variant, provenance) {
+	const type = { ...omit(variant.properties.type, ['required']), provenance };
+	return { ...variant, properties: { ...variant.properties, type } };
+}
+
+/** The series item union: one variant per registered series type, told apart by `type`, which defaults to chart.type. */
+function seriesUnion(root, definitions, option) {
+	const name = option.properties.series?.node.items?.ref;
+	const union = definitions[name];
+	if (union?.kind !== 'union') throw changed('series is no longer Array<SeriesOptionsType | UnknownSeriesOptions>');
+	const typed = union.anyOf.filter((member) => typeLiteral(definitions, member) !== undefined);
+	if (union.anyOf.length - typed.length !== 1)
+		throw changed('expected exactly one series member without a type literal');
+	if (typed.some((member) => member.kind !== 'ref')) throw changed('expected every series variant to be a definition');
+	const { fallback, provenance } = seriesDefault(root);
+	const variants = Object.fromEntries(
+		typed.map((member) => [member.ref, withOptionalType(definitions[member.ref], provenance)])
+	);
+	return {
+		name,
+		variants,
+		definition: {
+			kind: 'union',
+			anyOf: typed,
+			discriminator: 'type',
+			extensible: true,
+			defaultFrom: { path: ['chart', 'type'], fallback },
+			registry: { id: 'highcharts.series', prefix: '', enforced: true },
+			extensionPoint: 'highcharts.series',
+			provenance
+		}
+	};
+}
+
+export function generateHighcharts(root, pin) {
+	const { program, checker, entry } = createEntryProgram(root, ENTRY);
+	const aliases = exportedAliasTypes(checker, entry);
+	const emitter = new TypeEmitter({ program, checker, sourceId: SOURCE_ID, packageName: pin.package });
+	const optionRef = emitter.reference(aliases.get('Option'));
+	const series = seriesUnion(root, emitter.definitions, emitter.definitions[optionRef.ref]);
+	const declared = { ...emitter.definitions, ...series.variants, [series.name]: series.definition };
+	const definitions = withHighchartsRuntimeFacts(root, declared, {
+		optionName: optionRef.ref,
+		seriesVariants: Object.keys(series.variants)
+	});
+	return artifactOf({ library: 'highcharts', sourceId: SOURCE_ID, pin, definitions, root: optionRef });
+}