@chartguard/schema-generator 0.0.0-stage → 0.1.0

package/dist/lib/types.d.mts

@@ -0,0 +1,52 @@
+/**
+ * Checked lookups into upstream declarations. Each throws with the library name when the
+ * declarations no longer have the expected shape, so an upstream change fails generation
+ * loudly instead of producing a silently different artifact.
+ */
+export function typeLookups(checker: any, library: any): {
+    checker: any;
+    property: (type: any, name: any) => any;
+    propertyType: (type: any, name: any) => any;
+    indexValueType: (type: any) => any;
+    elementType: (arrayType: any) => any;
+};
+/** The members of a union type, or the type itself. */
+export function unionMembers(type: any): any;
+/**
+ * The artifact header shared by every generator; only the library-specific parts differ. It names
+ * everything the artifact is built from: the library, the compiler that read it, and the generator.
+ */
+export function artifactOf({ library, sourceId, pin, definitions, root }: {
+    library: any;
+    sourceId: any;
+    pin: any;
+    definitions: any;
+    root: any;
+}): {
+    irVersion: number;
+    library: any;
+    libraryVersion: any;
+    coverage: string;
+    generator: {
+        name: any;
+        version: any;
+    };
+    sources: {
+        [sourceId]: {
+            kind: string;
+            locator: string;
+            integrity: any;
+            license: any;
+        };
+        typescript: {
+            kind: string;
+            locator: string;
+            integrity: any;
+            license: any;
+        };
+    };
+    definitions: any;
+    root: any;
+};
+/** The source id of the TypeScript compiler, whose lib files facts about DOM and built-in types cite. */
+export const COMPILER_SOURCE: "typescript";

package/index.mjs

@@ -0,0 +1,20 @@
+/**
+ * Generates ChartGuard schema artifacts from the chart libraries' own published declarations and
+ * runtime code. `root` is always the project whose `node_modules` holds the library; nothing from
+ * it is executed, only read.
+ */
+export { digestOf, omit, serialize, withDigest } from './lib/digest.mjs';
+export { generateArtifact, isRedistributable, LIBRARIES } from './lib/generate.mjs';
+export { buildLocalSchema } from './lib/local.mjs';
+export {
+	compilerPin,
+	contentIntegrity,
+	installedUpstream,
+	pinOf,
+	sourceDirectory,
+	UpstreamError,
+	verifiedCompiler,
+	verifiedUpstream
+} from './lib/lock.mjs';
+export { LOCAL_ARTIFACTS, localSchemaPath } from './lib/paths.mjs';
+export { untracedFacts } from './lib/trace.mjs';

package/lib/chartjs-effects.mjs

@@ -0,0 +1,36 @@
+import { runtimePointer } from './runtime.mjs';
+
+/**
+ * What Chart.js does with an option of another type than the declarations say (A73), read from the
+ * line each fact cites. `_checkEventBindings` compares `responsive` with `!==` to whether resize
+ * listeners are bound (a boolean): any other value never matches, so every update unbinds and binds
+ * every listener again, and a truthy one binds the resize listeners, which runs the resize step.
+ */
+const EFFECTS = {
+	responsive: {
+		fact: { file: 'dist/chart.js', pattern: '!!this._responsiveListeners !== options.responsive' },
+		effect:
+			'Chart.js compares responsive with !== to whether it listens for resizes (a boolean), so any other value makes every update unbind and bind all its event listeners again; a truthy one also runs its resize step each time, which can recurse when the container size follows the chart.'
+	}
+};
+
+/**
+ * The chart options of every configuration (`config.options`) with the effect of a mismatched value
+ * on each option `EFFECTS` names, its runtime line added to the option's provenance.
+ */
+export function withMismatchEffects(root, definitions, configNames) {
+	const next = { ...definitions };
+	const optionsNames = new Set(configNames.map((name) => definitions[name].properties.options.node.ref));
+	for (const name of optionsNames) {
+		const properties = { ...next[name].properties };
+		for (const [key, { fact, effect }] of Object.entries(EFFECTS)) {
+			const property = properties[key];
+			if (property === undefined) throw new Error(`chart.js types changed: ${name} has no option "${key}"`);
+			const source = { source: 'chartjs', pointer: runtimePointer(root, 'chart.js', fact) };
+			const provenance = { ...property.provenance, sources: [...property.provenance.sources, source] };
+			properties[key] = { ...property, provenance, onMismatch: effect };
+		}
+		next[name] = { ...next[name], properties };
+	}
+	return next;
+}

package/lib/chartjs-plugins.mjs

@@ -0,0 +1,41 @@
+import { runtimePointer } from './runtime.mjs';
+
+/**
+ * Built-in plugin options (`options.plugins.legend`, …) take effect only when the plugin is
+ * registered: `createDescriptors` (dist/chart.js) reads `options[plugin.id]` for registered plugins
+ * only, so the options of a missing one are silently ignored. Each namespace must be the `id` of a
+ * plugin in the pinned runtime, or generation fails.
+ */
+const DESCRIPTORS = { file: 'dist/chart.js', pattern: 'const opts = getOpts(options[id], all);' };
+/** `getOpts` turns `false` into `null` and passes `null` through; `createDescriptors` then skips the plugin. */
+const SKIPPED = { file: 'dist/chart.js', pattern: 'if (opts === null) {' };
+
+const pluginPointer = (root, id) =>
+	runtimePointer(root, 'chart.js', { file: 'dist/chart.js', pattern: `id: '${id}',` });
+
+/**
+ * The `options.plugins` definitions of the given configurations. `PluginOptionsByType` is the
+ * declaration-merging point of plugin options (dist/types/index.d.ts), so each is the
+ * `chartjs.plugins` extension point (CG-02-05): a plugin's options are added there by name.
+ */
+export function pluginDefinitions(definitions, configNames) {
+	const optionsNames = configNames.map((name) => definitions[name].properties.options.node.ref);
+	return [...new Set(optionsNames.map((name) => definitions[name].properties.plugins.node.ref))];
+}
+
+/**
+ * Every built-in plugin namespace under `options.plugins` of the given configurations, with the
+ * handler to set and the runtime lines that make it a plugin id. The generator applies the plan.
+ */
+export function planPluginHandlers(root, definitions, configNames) {
+	const descriptors = runtimePointer(root, 'chart.js', DESCRIPTORS);
+	const skipped = runtimePointer(root, 'chart.js', SKIPPED);
+	return pluginDefinitions(definitions, configNames).flatMap((definition) =>
+		Object.keys(definitions[definition].properties).map((property) => ({
+			definition,
+			property,
+			handledBy: { id: 'chartjs.plugins', name: property, enforced: false },
+			sources: [descriptors, skipped, pluginPointer(root, property)].map((pointer) => ({ source: 'chartjs', pointer }))
+		}))
+	);
+}

package/lib/chartjs-scopes.mjs

@@ -0,0 +1,96 @@
+import { compareText, resolveIn, sameNode, upstreamChanged } from './nodes.mjs';
+import { runtimePointer } from './runtime.mjs';
+
+/**
+ * Chart.js resolves element options through a scope chain that ends at the options root, and
+ * with element and hover prefixes (dist/chart.js `datasetElementScopeKeys`, `_resolveElementOptions`),
+ * so `options.radius`, `options.pointBackgroundColor` and `datasets[].radius` all reach the
+ * point elements. Per-property animations live under `options.animation`, which `animations`
+ * falls back to. The declarations describe none of this; `planOptionScopes` works out what to
+ * add, citing the runtime, and the generator applies the plan to the definitions it owns.
+ */
+export const ELEMENT_SCOPE = 'ElementOptionsInScope';
+const ELEMENTS = ['point', 'line', 'bar', 'arc'];
+
+const RUNTIME = {
+	scopes: { file: 'dist/chart.js', pattern: 'datasetElementScopeKeys(datasetType, elementType) {' },
+	prefixes: { file: 'dist/chart.js', pattern: 'const prefixes = active ? [' },
+	animations: { file: 'dist/chunks/helpers.dataset.js', pattern: "_fallback: 'animation'" }
+};
+
+const changed = upstreamChanged('chart.js');
+
+const capitalize = (name) => `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+
+/** `radius` → `pointRadius`; `hoverRadius` → `pointHoverRadius`, the `<element>Hover` prefix. */
+function prefixed(element, name) {
+	return name.startsWith('hover') && name.length > 5
+		? `${element}Hover${name.slice(5)}`
+		: `${element}${capitalize(name)}`;
+}
+
+/** Records one declared type for a name; a name shared by several elements collects each distinct type. */
+function collect(collected, key, property, sources) {
+	const entry = collected.get(key) ?? { nodes: [], sources: [...property.provenance.sources, ...sources] };
+	if (!entry.nodes.some((node) => sameNode(node, property.node))) entry.nodes.push(property.node);
+	collected.set(key, entry);
+}
+
+/** Every name an element option is read under (`n` and `<element>N`), with its declared types. */
+function elementOptionNames(elements, resolve, sources) {
+	const collected = new Map();
+	for (const element of ELEMENTS) {
+		const declared = resolve(elements.properties[element]?.node ?? { kind: 'unknown' });
+		if (declared.kind !== 'object') throw changed(`no declared options for the ${element} element`);
+		for (const [name, property] of Object.entries(declared.properties)) {
+			collect(collected, name, property, sources);
+			collect(collected, prefixed(element, name), property, sources);
+		}
+	}
+	return collected;
+}
+
+function scopeDefinition(elements, resolve, sources) {
+	const collected = elementOptionNames(elements, resolve, sources);
+	const properties = [...collected.keys()].sort(compareText).map((key) => {
+		const { nodes, sources: cited } = collected.get(key);
+		const node = nodes.length === 1 ? nodes[0] : { kind: 'union', anyOf: nodes };
+		return [key, { node, provenance: { confidence: 'authoritative', sources: cited } }];
+	});
+	return { kind: 'object', additional: 'unknown', properties: Object.fromEntries(properties) };
+}
+
+/** Dataset variants of a configuration, reached through `data.datasets[]`. */
+function datasetNames(config, resolve) {
+	const datasets = resolve(resolve(config.properties.data.node).properties.datasets.node);
+	return resolve(datasets.items).anyOf.map((member) => member.ref);
+}
+
+/**
+ * What to add for the option scopes of the given configurations: the shared element-options
+ * definition, the definitions that include it (every `options` and every dataset variant), and the
+ * animation spec definitions that become open.
+ */
+export function planOptionScopes(root, definitions, configNames) {
+	const resolve = resolveIn(definitions);
+	const sources = [RUNTIME.scopes, RUNTIME.prefixes].map((fact) => ({
+		source: 'chartjs',
+		pointer: runtimePointer(root, 'chart.js', fact)
+	}));
+	const configs = configNames.map((name) => definitions[name]);
+	const optionsNames = configs.map((config) => config.properties.options.node.ref);
+	const animationNames = optionsNames.flatMap((name) =>
+		(resolve(definitions[name].properties.animation.node).anyOf ?? [])
+			.filter((member) => resolve(member).kind === 'object')
+			.map((member) => member.ref)
+	);
+	return {
+		scope: scopeDefinition(resolve(definitions[optionsNames[0]].properties.elements.node), resolve, sources),
+		includedBy: [...new Set([...optionsNames, ...configs.flatMap((config) => datasetNames(config, resolve))])],
+		openAnimations: [...new Set(animationNames)],
+		animationProvenance: {
+			confidence: 'authoritative',
+			sources: [{ source: 'chartjs', pointer: runtimePointer(root, 'chart.js', RUNTIME.animations) }]
+		}
+	};
+}

package/lib/chartjs.mjs

@@ -0,0 +1,275 @@
+import { withMismatchEffects } from './chartjs-effects.mjs';
+import { planPluginHandlers, pluginDefinitions } from './chartjs-plugins.mjs';
+import { ELEMENT_SCOPE, planOptionScopes } from './chartjs-scopes.mjs';
+import { TypeEmitter } from './emitter.mjs';
+import { createEntryProgram, exportedAliasTypes } from './program.mjs';
+import { runtimeProvenance } from './runtime.mjs';
+import { makeOptionsScriptable } from './scriptable.mjs';
+import { artifactOf, typeLookups, unionMembers } from './types.mjs';
+
+const SOURCE_ID = 'chartjs';
+/**
+ * The runtime registries (`Chart.register`) the `type` values are looked up in: every dataset's
+ * controller (`dataset.type || config.type`) and every configured scale. The chart `type` itself is
+ * read only through its datasets: with none, an unregistered chart type renders, so it is not enforced.
+ */
+const LOOKUPS = {
+	controllers: { file: 'dist/chart.js', pattern: 'const ControllerClass = registry.getController(type);' },
+	scales: { file: 'dist/chart.js', pattern: 'const scaleClass = registry.getScale(scaleType);' }
+};
+
+/**
+ * Scales take plugin variants (`withExtensions`, CG-02-05) at their registry's name; controllers at two
+ * points of one registry, `chartjs.charts` and `chartjs.datasets`, since a controller adds a chart type
+ * and a dataset type at once (part 2, marked where the unions are built).
+ */
+function registryFacts(root) {
+	const provenance = (fact) => runtimeProvenance(root, { sourceId: SOURCE_ID, packageName: 'chart.js' }, fact);
+	const fact = (id, enforced, lookup) => ({ registry: { id, prefix: '', enforced }, provenance: provenance(lookup) });
+	return {
+		chartType: fact('chartjs.controllers', false, LOOKUPS.controllers),
+		dataset: fact('chartjs.controllers', true, LOOKUPS.controllers),
+		scale: { ...fact('chartjs.scales', true, LOOKUPS.scales), extensionPoint: 'chartjs.scales' }
+	};
+}
+
+/** `DeepPartial<T>` / `_DeepPartialObject<T>` (dist/types/utils.d.ts) map over primitives unchanged. */
+const WRAPPERS = new Set(['DeepPartial', '_DeepPartialObject']);
+
+/** Chart types as declared by the augmentable `ChartTypeRegistry`. */
+function registeredChartTypes(root) {
+	const { program, checker, entry } = createEntryProgram(
+		root,
+		"import type { ChartTypeRegistry } from 'chart.js';\nexport type Registry = keyof ChartTypeRegistry;"
+	);
+	const registry = exportedAliasTypes(checker, entry).get('Registry');
+	return {
+		program,
+		chartTypes: unionMembers(registry)
+			.map((member) => member.value)
+			.sort()
+	};
+}
+
+function entryText(chartTypes) {
+	const lines = chartTypes.flatMap((chartType) => [
+		`export type Config_${chartType} = ChartConfiguration<'${chartType}'>;`,
+		`export type Dataset_${chartType} = ChartDataset<'${chartType}'>;`
+	]);
+	return [
+		"import type { ChartConfiguration, ChartDataset, ChartOptions } from 'chart.js';",
+		// Options of every chart type at once: their `scales` take every scale type.
+		'export type AnyOptions = ChartOptions;',
+		...lines
+	].join('\n');
+}
+
+/**
+ * Positions where the declarations are narrower or wider than the runtime contract:
+ * data points depend on the caller's generic `TData`, inline plugins are user objects,
+ * `options.plugins` is extended by third-party plugins through declaration merging,
+ * `options.scales[*]` variants come from `ScaleTypeRegistry`, which plugins merge into
+ * (chartjs-plugin-streaming, chartjs-chart-matrix), and `config.data`, `data.datasets`
+ * and `dataset.data` are defaulted by the runtime (`initConfig`/`initData` in
+ * chart.js/dist/chart.js, `config.data = config.data || {}`, `data.datasets = data.datasets || []`,
+ * `_dataCheck`: `dataset.data || (dataset.data = [])`), so their absence is not an error.
+ */
+function adjustChartType(lookups, { config, datasetTypes }, into) {
+	const { property, propertyType, indexValueType, elementType } = lookups;
+	const data = propertyType(config, 'data');
+	const datasetType = elementType(propertyType(data, 'datasets'));
+	const options = propertyType(config, 'options');
+	into.opaque.add(elementType(propertyType(config, 'plugins')));
+	const plugins = propertyType(options, 'plugins');
+	into.open.add(plugins);
+	// getOpts (chart.js `PluginService`): `false` and `null` disable a plugin (`createDescriptors` skips
+	// it), `true` enables it with defaults; each plugin entry cites both lines (chartjs-plugins.mjs).
+	for (const plugin of lookups.checker.getPropertiesOfType(plugins))
+		into.widened.set(declarationOf(plugin), [{ kind: 'boolean' }, { kind: 'null' }]);
+	into.scales.add(indexValueType(propertyType(options, 'scales')));
+	into.runtimeOptional.add(property(config, 'data'));
+	into.runtimeOptional.add(property(data, 'datasets'));
+	for (const dataset of [datasetType, ...datasetTypes]) {
+		into.opaque.add(propertyType(dataset, 'data'));
+		into.runtimeOptional.add(property(dataset, 'data'));
+	}
+	into.datasetVariants.set(datasetType, [datasetType, ...datasetTypes]);
+}
+
+/**
+ * The declaration a plugin's option is widened at. `widened` is keyed by declaration: a symbol without
+ * one (a key a mapped type synthesizes) would key `undefined`, which every other declaration-less
+ * property also looks up, so it would widen them all.
+ */
+export function declarationOf(symbol) {
+	const [declaration] = symbol.declarations ?? [];
+	if (declaration === undefined)
+		throw new Error(`chart.js types changed: plugin option "${symbol.name}" has no declaration`);
+	return declaration;
+}
+
+/**
+ * Every chart type takes every scale type: the runtime looks a scale's type up in one registry,
+ * whatever the chart type (`registry.getScale(scaleType)`), and chooses an untyped scale's type by
+ * its axis (`radialLinear` on `r`, `category` or `linear` on `x` and `y`) in any chart. The
+ * declarations narrow `scales` by chart type (`ChartTypeRegistry[TType]['scales']`): a radar chart's
+ * `x` scale, which the runtime builds as `category`, would be checked as `radialLinear`. Each chart
+ * type's scale type is emitted as the scale type of `ChartOptions` over every chart type.
+ */
+function everyScaleType(lookups, anyOptions, into) {
+	const every = lookups.indexValueType(lookups.propertyType(lookups.checker.getNonNullableType(anyOptions), 'scales'));
+	return { every, own: [...into.scales].filter((own) => own !== every) };
+}
+
+/** Each chart type's scale type emitted as the one of every chart type. */
+const scaleOverrides = (emitter, { every, own }) => own.map((type) => [type, () => emitter.emit(every)]);
+
+function contractAdjustments(checker, chartTypes, aliases, facts) {
+	const into = {
+		opaque: new Set(),
+		open: new Set(),
+		registries: new Map(),
+		runtimeOptional: new Set(),
+		widened: new Map(),
+		datasetVariants: new Map(),
+		scales: new Set()
+	};
+	for (const chartType of chartTypes) {
+		const config = aliases.get(`Config_${chartType}`);
+		const datasetTypes = chartTypes
+			.filter((other) => other !== chartType)
+			.map((other) => aliases.get(`Dataset_${other}`));
+		adjustChartType(typeLookups(checker, 'chart.js'), { config, datasetTypes }, into);
+	}
+	const scales = everyScaleType(typeLookups(checker, 'chart.js'), aliases.get('AnyOptions'), into);
+	into.registries.set(scales.every, facts.scale);
+	return { ...into, scales };
+}
+
+/** Mixed charts: a dataset without `type` inherits the chart type; plugins may register more types. */
+function datasetUnions(emitter, datasetVariants, { registry, provenance }) {
+	return new Map(
+		[...datasetVariants].map(([datasetType, variants]) => [
+			datasetType,
+			() => ({
+				kind: 'union',
+				anyOf: variants.map((variant) => emitter.reference(variant)),
+				discriminator: 'type',
+				defaultVariant: 0,
+				extensible: true,
+				registry,
+				extensionPoint: 'chartjs.datasets',
+				provenance
+			})
+		])
+	);
+}
+
+/**
+ * `toFont` (dist/chunks/helpers.dataset.js) reads a font's `size` with `parseInt` when it is a string,
+ * and tests `style` against its own pattern (`unset`, `oblique 10deg` are styles too): a string is
+ * a size, and any string a style the runtime decides itself (A6: runtime-handled values are accepted).
+ */
+const FONT_FACTS = {
+	size: { file: 'dist/chunks/helpers.dataset.js', pattern: 'size = parseInt(size, 10);' },
+	style: { file: 'dist/chunks/helpers.dataset.js', pattern: "if (style && !('' + style).match(FONT_STYLE)) {" }
+};
+const STRING = { kind: 'string' };
+
+/** `node` also accepting a string; a scriptable value widens inside its callback-or-value union. */
+function withString(node) {
+	if (node.kind === 'scriptable') return { ...node, value: withString(node.value) };
+	if (node.kind === 'union') return { ...node, anyOf: [...node.anyOf, STRING] };
+	return { kind: 'union', anyOf: [node, STRING] };
+}
+
+/** Every font definition (its own `size` and `family`) with the facts of `toFont`, each citing its line. */
+function withFontFacts(root, definitions) {
+	const cite = (fact) => ({
+		source: SOURCE_ID,
+		pointer: runtimeProvenance(root, { sourceId: SOURCE_ID, packageName: 'chart.js' }, fact).sources[0].pointer
+	});
+	const next = { ...definitions };
+	for (const [name, definition] of Object.entries(definitions)) {
+		const properties = definition.properties ?? {};
+		if (properties.size === undefined || properties.family === undefined) continue;
+		const widened = Object.fromEntries(
+			Object.entries(FONT_FACTS)
+				.filter(([key]) => properties[key] !== undefined)
+				.map(([key, fact]) => {
+					const property = properties[key];
+					const provenance = { ...property.provenance, sources: [...property.provenance.sources, cite(fact)] };
+					return [key, { ...property, node: withString(property.node), provenance }];
+				})
+		);
+		next[name] = { ...definition, properties: { ...properties, ...widened } };
+	}
+	return next;
+}
+
+/**
+ * What the declarations leave out, read from the runtime: element options in every scope the
+ * runtime reads them from, open per-property animations, built-in plugin options that take effect
+ * only when the plugin is registered, the plugin extension point; then every option value becomes
+ * scriptable, fonts take what `toFont` handles, and options the runtime mishandles say how (A73).
+ */
+function withRuntimeFacts(root, definitions, configNames) {
+	const scopes = planOptionScopes(root, definitions, configNames);
+	const next = { ...definitions, [ELEMENT_SCOPE]: scopes.scope };
+	for (const name of scopes.includedBy) next[name] = { ...next[name], includes: [ELEMENT_SCOPE] };
+	for (const name of scopes.openAnimations)
+		next[name] = { ...next[name], additional: 'open', provenance: scopes.animationProvenance };
+	for (const { definition, property, handledBy, sources } of planPluginHandlers(root, definitions, configNames)) {
+		const target = next[definition].properties[property];
+		const provenance = { ...target.provenance, sources: [...target.provenance.sources, ...sources] };
+		next[definition] = {
+			...next[definition],
+			properties: { ...next[definition].properties, [property]: { ...target, handledBy, provenance } }
+		};
+	}
+	for (const name of pluginDefinitions(definitions, configNames))
+		next[name] = { ...next[name], extensionPoint: 'chartjs.plugins' };
+	makeOptionsScriptable(next, configNames);
+	return withMismatchEffects(root, withFontFacts(root, next), configNames);
+}
+
+export function generateChartjs(root, pin) {
+	const { program: registryProgram, chartTypes } = registeredChartTypes(root);
+	const { program, checker, entry } = createEntryProgram(root, entryText(chartTypes), registryProgram);
+	const aliases = exportedAliasTypes(checker, entry);
+	const facts = registryFacts(root);
+	const { datasetVariants, scales, ...adjustments } = contractAdjustments(checker, chartTypes, aliases, facts);
+	const emitter = new TypeEmitter({
+		program,
+		checker,
+		sourceId: SOURCE_ID,
+		packageName: pin.package,
+		wrappers: WRAPPERS,
+		...adjustments
+	});
+	emitter.overrides = new Map([
+		...datasetUnions(emitter, datasetVariants, facts.dataset),
+		...scaleOverrides(emitter, scales)
+	]);
+	const configs = chartTypes.map((chartType) => emitter.reference(aliases.get(`Config_${chartType}`)));
+	const definitions = withRuntimeFacts(
+		root,
+		emitter.definitions,
+		configs.map(({ ref }) => ref)
+	);
+	return artifactOf({
+		library: 'chartjs',
+		sourceId: SOURCE_ID,
+		pin,
+		definitions,
+		// A controller adds a chart type and a dataset type: two variant points of one registry (CG-02-05 part 2).
+		root: {
+			kind: 'union',
+			anyOf: configs,
+			discriminator: 'type',
+			extensible: true,
+			...facts.chartType,
+			extensionPoint: 'chartjs.charts'
+		}
+	});
+}

package/lib/deprecation.mjs

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+
+/** "Use `x` instead", "use x instead": what a deprecation notice says to use (an option name or path). */
+const REPLACEMENT = /\buse\s+`?([A-Za-z_$][\w$.]*)`?\s+instead\b/i;
+
+/**
+ * The `@deprecated` tag of a property, as the upstream declaration states it: its first sentence,
+ * and the replacement it names. Never a rename: a notice does not say the runtime reads the old
+ * option under the new name, so renaming could change what is drawn.
+ */
+export function deprecationOf(symbol) {
+	const tag = symbol.getJsDocTags().find(({ name }) => name === 'deprecated');
+	if (tag === undefined) return undefined;
+	const text = ts.displayPartsToString(tag.text).replace(/\s+/g, ' ').trim();
+	const [sentence] = text.split(/(?<=\.)\s/);
+	const replacement = REPLACEMENT.exec(text)?.[1];
+	return {
+		...(sentence === undefined || sentence === '' ? {} : { message: sentence }),
+		...(replacement === undefined ? {} : { replacement })
+	};
+}

package/lib/digest.mjs

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+
+/** The committed artifact text: tab-indented JSON with a final newline. */
+export function serialize(artifact) {
+	return `${JSON.stringify(artifact, null, '\t')}\n`;
+}
+
+/** The object without the named keys, key order kept. */
+export function omit(object, keys) {
+	return Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
+}
+
+/** `sha256-<hex>` of the canonical text with the `digest` field left out. */
+export function digestOf(artifact) {
+	return `sha256-${createHash('sha256')
+		.update(serialize(omit(artifact, ['digest'])))
+		.digest('hex')}`;
+}
+
+/** The artifact with its digest placed in the header, right after `generator`. */
+export function withDigest(artifact) {
+	const digest = digestOf(artifact);
+	return Object.fromEntries(
+		Object.entries(artifact).flatMap(([key, value]) =>
+			key === 'generator'
+				? [
+						[key, value],
+						['digest', digest]
+					]
+				: [[key, value]]
+		)
+	);
+}