@chartguard/schema-generator 0.0.0-stage → 0.1.0

package/lib/local.mjs

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { generateArtifact, isRedistributable } from './generate.mjs';
+import { installedUpstream, pinOf, UpstreamError } from './lock.mjs';
+import { localSchemaPath } from './paths.mjs';
+
+/**
+ * Builds the schema of `library` from the project's own install and writes it next to it. Only for
+ * libraries whose schema cannot ship with their adapter; the generator must find every declaration
+ * shape and runtime fact it relies on in that install, or nothing is written.
+ * @param {string} root
+ * @param {string} library
+ * @returns {{ path: string, version: string, digest: string, integrity: string }}
+ */
+export function buildLocalSchema(root, library) {
+	if (isRedistributable(pinOf(library)))
+		throw new UpstreamError(`${library} ships its schema with its adapter; there is nothing to build.`);
+	const pin = installedUpstream(root, library);
+	let generated;
+	try {
+		generated = generateArtifact(root, library, pin);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new UpstreamError(
+			`${pin.package} ${pin.version} could not be read by this generator (it was verified against ${pinOf(library).version}): ${reason}`
+		);
+	}
+	const path = localSchemaPath(root, library, pin.version);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, generated.text);
+	return { path, version: pin.version, digest: generated.artifact.digest, integrity: pin.integrity };
+}

package/lib/lock.mjs

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, sep } from 'node:path';
+
+/** The upstream pins this generator was written and verified against (one exact version per library). */
+const PINS = JSON.parse(readFileSync(new URL('../upstream-sources.json', import.meta.url), 'utf8'));
+
+/**
+ * The project's install cannot be used: not installed, another major than the generator supports,
+ * a library whose schema ships with its adapter, or declarations and runtime the generator cannot
+ * read. A situation for the user to resolve, not a defect of the generator.
+ */
+export class UpstreamError extends Error {
+	name = 'UpstreamError';
+}
+
+/** The upstream pin for `library` from upstream-sources.json; throws `UpstreamError` when there is none. */
+export function pinOf(library) {
+	const pin = PINS.libraries.find((entry) => entry.library === library);
+	if (pin === undefined) throw new UpstreamError(`No upstream pin for ${library}`);
+	return pin;
+}
+
+/**
+ * The TypeScript this generator was verified with. Its lib files decide the members of the DOM and
+ * built-in types the declarations name, so another version builds another artifact (CG-07-06).
+ */
+export function compilerPin() {
+	return PINS.compiler;
+}
+
+/** Throws `UpstreamError` unless `version` (the TypeScript the generator loaded) is the pinned compiler. */
+export function verifiedCompiler(version) {
+	const pin = compilerPin();
+	if (version !== pin.version)
+		throw new UpstreamError(
+			`typescript ${version} is loaded, but this generator builds schemas only with typescript ${pin.version}: another version reads the declarations differently.`
+		);
+	return pin;
+}
+
+/**
+ * The directory of a package an artifact names as a source: the pinned compiler is the TypeScript
+ * this generator loads (its own exact dependency); a library is the project's install under `root`.
+ */
+export function sourceDirectory(root, packageName) {
+	if (packageName === compilerPin().package)
+		return dirname(createRequire(import.meta.url).resolve(`${packageName}/package.json`));
+	return join(root, 'node_modules', packageName);
+}
+
+function installedVersion(root, packageName) {
+	try {
+		return JSON.parse(readFileSync(join(root, 'node_modules', packageName, 'package.json'), 'utf8')).version;
+	} catch {
+		throw new UpstreamError(`${packageName} is not installed in ${root}`);
+	}
+}
+
+function lockfileEntry(root, packageName) {
+	try {
+		return JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8')).packages?.[`node_modules/${packageName}`];
+	} catch {
+		return undefined;
+	}
+}
+
+/** Upstream pin from upstream-sources.json, verified against what npm installed in this repository. */
+export function verifiedUpstream(root, library) {
+	const pin = pinOf(library);
+	const installed = installedVersion(root, pin.package);
+	const locked = lockfileEntry(root, pin.package);
+	if (installed !== pin.version || locked?.version !== pin.version)
+		throw new UpstreamError(`${pin.package}: installed ${installed}, pinned ${pin.version}`);
+	if (locked.integrity !== pin.integrity)
+		throw new UpstreamError(`${pin.package}: lockfile integrity differs from the pin`);
+	return pin;
+}
+
+function packageFiles(directory, root = directory) {
+	return readdirSync(directory, { withFileTypes: true })
+		.flatMap((entry) => {
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : packageFiles(path, root);
+			return entry.isFile() ? [relative(root, path).split(sep).join('/')] : [];
+		})
+		.sort();
+}
+
+/** `sha256-<base64>` over every file of an installed package, path and content: what the schema was derived from. */
+export function contentIntegrity(directory) {
+	const hash = createHash('sha256');
+	for (const file of packageFiles(directory))
+		hash
+			.update(file)
+			.update('\0')
+			.update(readFileSync(join(directory, file)))
+			.update('\0');
+	return `sha256-${hash.digest('base64')}`;
+}
+
+const major = (version) => version.split('.')[0];
+
+/**
+ * The pin for the version a project actually installed: the same major as this generator's pin,
+ * with the integrity of that install (its npm lockfile entry, or a hash of its files), so the
+ * facts derived from it stay traceable to exactly what was read.
+ */
+export function installedUpstream(root, library) {
+	const pin = pinOf(library);
+	const version = installedVersion(root, pin.package);
+	if (major(version) !== major(pin.version))
+		throw new UpstreamError(
+			`${pin.package} ${version} is not supported: this generator reads ${major(pin.version)}.x (pinned ${pin.version}).`
+		);
+	const locked = lockfileEntry(root, pin.package);
+	const integrity =
+		locked?.version === version && typeof locked.integrity === 'string'
+			? locked.integrity
+			: contentIntegrity(join(root, 'node_modules', pin.package));
+	return { ...pin, version, integrity };
+}

package/lib/nodes.mjs

@@ -0,0 +1,17 @@
+/** IR helpers every generator module shares. */
+
+/** `node`, or the definition it references. */
+export const resolveIn = (definitions) => (node) => (node.kind === 'ref' ? definitions[node.ref] : node);
+
+/** Two IR nodes are the same when they serialize the same (generated nodes keep a fixed key order). */
+export const sameNode = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+/** Code-point order: `localeCompare` depends on the machine's locale, generated output must not. */
+export const compareText = (left, right) => (left < right ? -1 : Number(left > right));
+
+/**
+ * The error generation fails with when the upstream no longer has the shape a generator reads
+ * (`upstreamChanged('echarts types')('no "series" property')`): an upstream change fails loudly, never
+ * into a silently different artifact.
+ */
+export const upstreamChanged = (subject) => (what) => new Error(`${subject} changed: ${what}`);

package/lib/paths.mjs

@@ -0,0 +1,50 @@
+import { join } from 'node:path';
+
+// Imported, never read from beside this file: bundles (the VS Code extension's server) hold this module without them.
+import GENERATOR from '../package.json' with { type: 'json' };
+import PINS from '../upstream-sources.json' with { type: 'json' };
+
+const COMPILER = PINS.compiler;
+
+/**
+ * Where schemas that may not be redistributed (Highcharts) are written: under the project's own
+ * node_modules, so never tracked by git and never inside a package's `files`. A module of its own,
+ * so tools that only look a schema up (the CLI) do not load the generator and the TypeScript compiler.
+ */
+export const LOCAL_ARTIFACTS = 'node_modules/.cache/chartguard';
+
+/**
+ * The schema built for `library` at `version` in the project at `root`.
+ * @param {string} root
+ * @param {string} library
+ * @param {string} version
+ * @returns {string}
+ */
+export function localSchemaPath(root, library, version) {
+	return join(root, LOCAL_ARTIFACTS, `${library}-${version}.json`);
+}
+
+const text = (value) => (typeof value === 'string' ? value : undefined);
+
+/** `@chartguard/schema-generator 0.1.0 with typescript@5.9.3`, as a schema's header records it. */
+function builder(header) {
+	const generator = header.generator !== null && typeof header.generator === 'object' ? header.generator : {};
+	const sources = header.sources !== null && typeof header.sources === 'object' ? header.sources : {};
+	const compiler = sources.typescript !== null && typeof sources.typescript === 'object' ? sources.typescript : {};
+	const name = text(generator.name) ?? 'an unnamed generator';
+	const version = text(generator.version) ?? 'of no recorded version';
+	return `${name} ${version} with ${text(compiler.locator) ?? 'no recorded compiler'}`;
+}
+
+/**
+ * Why a schema built on the user's machine cannot be used by this ChartGuard, or `undefined` when its
+ * own generator built it with its own compiler: another generator or TypeScript reads the same install
+ * differently, so its schema is rebuilt, never used as if it were this one's (CG-07-06).
+ * @param {unknown} artifact the parsed schema file
+ * @returns {string | undefined}
+ */
+export function otherBuild(artifact) {
+	const built = builder(artifact !== null && typeof artifact === 'object' ? artifact : {});
+	const ours = `${GENERATOR.name} ${GENERATOR.version} with typescript@${COMPILER.version}`;
+	return built === ours ? undefined : `it was built by ${built}; this ChartGuard builds with ${ours}`;
+}

package/lib/program.mjs

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+
+import ts from 'typescript';
+
+const COMPILER_OPTIONS = {
+	strict: true,
+	noEmit: true,
+	skipLibCheck: true,
+	target: ts.ScriptTarget.ES2022,
+	module: ts.ModuleKind.NodeNext,
+	moduleResolution: ts.ModuleResolutionKind.NodeNext,
+	lib: ['lib.es2022.d.ts', 'lib.dom.d.ts'],
+	types: []
+};
+
+/**
+ * Type-checks a generated in-memory entry file against installed declarations.
+ * Declarations are only parsed and type-checked; nothing is executed.
+ * A previous program for the same root lets TypeScript reuse its parsed declaration files.
+ */
+export function createEntryProgram(root, entryText, previous) {
+	const entryPath = resolve(root, '__chartguard_schema_entry__.ts');
+	const host = ts.createCompilerHost(COMPILER_OPTIONS);
+	const readSourceFile = host.getSourceFile.bind(host);
+	const fileExists = host.fileExists.bind(host);
+	// TypeScript hands the host its own spelling of a path (`D:/a/b.ts` for `D:\a\b.ts` on Windows):
+	// a name is the entry when it resolves to the same path, never by its text.
+	const isEntry = (fileName) => resolve(fileName) === entryPath;
+	host.getSourceFile = (fileName, languageVersion, ...rest) =>
+		isEntry(fileName)
+			? ts.createSourceFile(fileName, entryText, languageVersion, true)
+			: readSourceFile(fileName, languageVersion, ...rest);
+	host.fileExists = (fileName) => isEntry(fileName) || fileExists(fileName);
+	const program = ts.createProgram([entryPath], COMPILER_OPTIONS, host, previous);
+	const entry = program.getSourceFile(entryPath);
+	return { program, checker: program.getTypeChecker(), entry };
+}
+
+/** The type named by each `export type Name = ...` alias in the entry file. */
+export function exportedAliasTypes(checker, entry) {
+	return new Map(
+		entry.statements
+			.filter((statement) => ts.isTypeAliasDeclaration(statement))
+			.map((statement) => [statement.name.text, checker.getTypeAtLocation(statement.name)])
+	);
+}

package/lib/provenance.mjs

@@ -0,0 +1,100 @@
+import ts from 'typescript';
+
+import { COMPILER_SOURCE } from './types.mjs';
+
+const PACKAGE_PATH = /^.*\/node_modules\//;
+
+/** `chart.js/dist/types/index.d.ts` for a file under node_modules, else undefined. */
+function packageRelative(fileName) {
+	return PACKAGE_PATH.test(fileName) ? fileName.replace(PACKAGE_PATH, '') : undefined;
+}
+
+/** `typescript/lib/lib.dom.d.ts:12`-style pointer: a package-relative file and the line a declaration starts on. */
+function pointerOf(path, declaration) {
+	const file = declaration.getSourceFile();
+	const { line } = file.getLineAndCharacterOfPosition(declaration.getStart(file));
+	return `${path}:${String(line + 1)}`;
+}
+
+/**
+ * Which published declaration a fact cites, and how that becomes a provenance record.
+ * Pointers are package-relative (`chart.js/dist/types/index.d.ts:12`); local paths never leak.
+ * Only declarations inside the pinned package count: TypeScript's own lib (`Pick`, `Partial`)
+ * and other installed packages are not evidence for the pinned source. A fact TypeScript's lib
+ * declares (the members of `Array` or of the DOM's event map) cites that lib, as `derived` (CG-07-06).
+ */
+export class Provenance {
+	constructor(checker, { sourceId, packageName }) {
+		this.checker = checker;
+		this.sourceId = sourceId;
+		this.prefix = `${packageName}/`;
+	}
+
+	/** The pinned-package-relative path of a symbol's declaration, if it is declared there. */
+	pinnedPath(symbol) {
+		const fileName = symbol?.declarations?.[0]?.getSourceFile().fileName;
+		const relative = fileName === undefined ? undefined : packageRelative(fileName);
+		return relative?.startsWith(this.prefix) === true ? relative : undefined;
+	}
+
+	isPublished = (symbol) => this.pinnedPath(symbol) !== undefined;
+
+	/**
+	 * The published symbol an object type should cite: its alias when published, else its own
+	 * symbol, else what it is composed from, else the published type its (generator-local) alias names.
+	 */
+	ownerOf(type) {
+		if (this.isPublished(type.aliasSymbol)) return type.aliasSymbol;
+		const own = type.getSymbol();
+		if (this.isPublished(own)) return own;
+		return this.ownerOfComposite(type) ?? this.aliasTarget(type) ?? own;
+	}
+
+	/**
+	 * `A & { … }` cites its first published member; a lib mapped type over a package type
+	 * (`Pick<LabelOption, …>`, `Omit<…>`) cites that type. Each property still cites its own declaration.
+	 */
+	ownerOfComposite(type) {
+		const parts = type.isIntersection() ? type.types : (type.aliasTypeArguments ?? []).slice(0, 1);
+		return parts.map((part) => this.ownerOf(part)).find(this.isPublished);
+	}
+
+	/** `export type Dataset_bar = ChartDataset<'bar'>` in the entry file names `ChartDataset`. */
+	aliasTarget(type) {
+		const declaration = type.aliasSymbol?.declarations?.[0];
+		if (
+			declaration === undefined ||
+			!ts.isTypeAliasDeclaration(declaration) ||
+			!ts.isTypeReferenceNode(declaration.type)
+		)
+			return undefined;
+		const referenced = this.checker.getSymbolAtLocation(declaration.type.typeName);
+		if (referenced === undefined) return undefined;
+		// An `import type { X }` binding is itself an alias symbol; follow it to the declaration.
+		return (referenced.flags & ts.SymbolFlags.Alias) !== 0 ? this.checker.getAliasedSymbol(referenced) : referenced;
+	}
+
+	/** The `typescript/lib/…` path of a symbol declared in TypeScript's own lib files. */
+	libPath(symbol) {
+		const fileName = symbol?.declarations?.[0]?.getSourceFile().fileName;
+		const relative = fileName === undefined ? undefined : packageRelative(fileName);
+		return relative?.startsWith(`${COMPILER_SOURCE}/lib/`) === true ? relative : undefined;
+	}
+
+	/** A fact without a declaration in the pinned package cannot claim authority: it is `derived`. */
+	of(symbol) {
+		const path = this.pinnedPath(symbol);
+		if (path !== undefined)
+			return {
+				confidence: 'authoritative',
+				sources: [{ source: this.sourceId, pointer: pointerOf(path, symbol.declarations[0]) }]
+			};
+		const lib = this.libPath(symbol);
+		if (lib !== undefined)
+			return {
+				confidence: 'derived',
+				sources: [{ source: COMPILER_SOURCE, pointer: pointerOf(lib, symbol.declarations[0]) }]
+			};
+		return { confidence: 'derived', sources: [{ source: this.sourceId }] };
+	}
+}

package/lib/runtime.mjs

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Facts the declarations leave out are read from the pinned package's runtime code and cite the
+ * line they come from (`echarts/lib/component/dataZoom/installCommon.js:52`). A pattern that is no
+ * longer found fails generation: the runtime changed, and the fact must be re-established.
+ */
+function locate(root, packageName, { file, pattern }) {
+	const lines = readFileSync(join(root, 'node_modules', packageName, file), 'utf8').split('\n');
+	const index = lines.findIndex((line) => line.includes(pattern));
+	if (index === -1) throw new Error(`${packageName} runtime changed: "${pattern}" not found in ${file}`);
+	return { lines, index, pointer: `${packageName}/${file}:${String(index + 1)}` };
+}
+
+export function runtimePointer(root, packageName, fact) {
+	return locate(root, packageName, fact).pointer;
+}
+
+/**
+ * The lines after the one matching `pattern`, up to (not including) the first that starts with
+ * `end`, and `pointerAt(i)` citing the i-th of them.
+ */
+export function runtimeSection(root, packageName, { end, ...fact }) {
+	const { lines, index, pointer } = locate(root, packageName, fact);
+	const length = lines.slice(index + 1).findIndex((line) => line.trimStart().startsWith(end));
+	if (length === -1) throw new Error(`${packageName} runtime changed: no "${end}" after ${pointer}`);
+	const pointerAt = (offset) => `${packageName}/${fact.file}:${String(index + 2 + offset)}`;
+	return { pointer, lines: lines.slice(index + 1, index + 1 + length), pointerAt };
+}
+
+/** An authoritative provenance record citing one runtime line of the pinned package. */
+export function runtimeProvenance(root, { sourceId, packageName }, fact) {
+	return {
+		confidence: 'authoritative',
+		sources: [{ source: sourceId, pointer: runtimePointer(root, packageName, fact) }]
+	};
+}

package/lib/scriptable.mjs

@@ -0,0 +1,57 @@
+import { resolveIn } from './nodes.mjs';
+
+/**
+ * Chart.js resolves every option through its scriptable resolver (`_descriptors` in
+ * helpers.dataset.js defaults to `scriptable: true`; the root descriptor is
+ * `_scriptable: (name) => !name.startsWith('on')`), so a function is accepted wherever an option
+ * value is, whether or not the declarations say `Scriptable<…>`. The few options a plugin marks
+ * non-scriptable (`spacing`, callbacks that are functions anyway) are over-accepted: a false
+ * negative, never a false rejection.
+ *
+ * This pass rewrites the IR reachable from each configuration's `options`: every property whose
+ * node does not already accept a function becomes `scriptable`. Union discriminators (`type`)
+ * stay literal so variants can still be selected.
+ */
+export function makeOptionsScriptable(definitions, configRefs) {
+	const discriminators = new Set();
+	const collect = (node) => {
+		if (node === null || typeof node !== 'object') return;
+		if (node.kind === 'union' && node.discriminator !== undefined) discriminators.add(node.discriminator);
+		for (const child of Object.values(node)) collect(child);
+	};
+	collect(definitions);
+
+	const resolve = resolveIn(definitions);
+	const acceptsFunction = (node, seen = new Set()) => {
+		if (node.kind === 'ref') {
+			if (seen.has(node.ref)) return false;
+			seen.add(node.ref);
+		}
+		const target = resolve(node);
+		if (['function', 'scriptable', 'unknown'].includes(target.kind)) return true;
+		return target.kind === 'union' && target.anyOf.some((member) => acceptsFunction(member, seen));
+	};
+
+	/** Nodes below `target`: included definitions, then members, items, values; a literal's `value` is not a node. */
+	const childrenOf = (target) => {
+		const included = Array.isArray(target.includes) ? target.includes.map((ref) => ({ kind: 'ref', ref })) : [];
+		const nested = [...(target.anyOf ?? []), target.items, target.values, target.value];
+		return [...included, ...nested.filter((candidate) => typeof candidate?.kind === 'string')];
+	};
+
+	const visited = new Set();
+	const visit = (node) => {
+		if (node.kind === 'ref') {
+			if (visited.has(node.ref)) return;
+			visited.add(node.ref);
+		}
+		const target = resolve(node);
+		for (const [name, property] of target.kind === 'object' ? Object.entries(target.properties) : []) {
+			visit(property.node);
+			if (!discriminators.has(name) && !acceptsFunction(property.node))
+				property.node = { kind: 'scriptable', value: property.node };
+		}
+		for (const child of childrenOf(target)) visit(child);
+	};
+	for (const ref of configRefs) visit(definitions[ref].properties.options.node);
+}

package/lib/trace.mjs

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { sourceDirectory } from './lock.mjs';
+
+const POINTER = /^(?<path>[^:]+):(?<line>[1-9]\d*)$/u;
+/** The name a property declaration line starts with (`readonly 'name'?: …`, `name(…)`). */
+const DECLARED = /^\s*(?:readonly\s+)?['"]?(?<name>[\w$]+)['"]?\??\s*[:(<]/u;
+/** A mapped type (`[P in keyof T]`): the keys it synthesizes cite it, not a line of their own. */
+const MAPPED = /\[\s*[\w$]+\s+in\s/u;
+const IDENTIFIER = /[\w$]/u;
+
+/** `chart.js` for `chart.js@4.5.1`, `@scope/name` for `@scope/name@1.0.0`. */
+const packageOf = (locator) => locator.slice(0, locator.lastIndexOf('@'));
+
+/** Whether `line` names `name` as a whole word (not inside a longer identifier). */
+function names(line, name) {
+	for (let at = line.indexOf(name); at !== -1; at = line.indexOf(name, at + 1)) {
+		const before = line[at - 1] ?? ' ';
+		const after = line[at + name.length] ?? ' ';
+		if (!IDENTIFIER.test(before) && !IDENTIFIER.test(after)) return true;
+	}
+	return false;
+}
+
+/**
+ * Whether the declaration a property cites at `index` declares `name`: the line names it, or a key
+ * remapping derives it (`pointRadius` from `radius` under `point${Capitalize<K>}`), or a mapped type
+ * there synthesizes it.
+ */
+function declares(lines, index, name) {
+	const line = lines[index];
+	if (names(line, name)) return true;
+	const declared = DECLARED.exec(line)?.groups?.name;
+	if (declared !== undefined && name.endsWith(declared[0].toUpperCase() + declared.slice(1))) return true;
+	return MAPPED.test(`${line}\n${lines[index + 1] ?? ''}`);
+}
+
+/** The child nodes of a node, by its kind (D17: structure comes from kinds and known fields, never from key names). */
+function childrenOf(node, path) {
+	switch (node.kind) {
+		case 'record':
+			return [{ node: node.values, path: `${path}.values` }];
+		case 'array':
+			return [{ node: node.items, path: `${path}.items` }];
+		case 'scriptable':
+			return [{ node: node.value, path: `${path}.value` }];
+		case 'union':
+			return node.anyOf.map((member, index) => ({ node: member, path: `${path}.anyOf[${String(index)}]` }));
+		default:
+			return [];
+	}
+}
+
+/** Every provenance record of an artifact (of a node, or of a property with its name). */
+function* records(artifact) {
+	const stack = [
+		{ node: artifact.root, path: 'root' },
+		...Object.entries(artifact.definitions).map(([name, node]) => ({ node, path: `definitions.${name}` }))
+	];
+	while (stack.length > 0) {
+		const { node, path } = stack.pop();
+		if (node.provenance !== undefined) yield { provenance: node.provenance, path };
+		for (const [name, property] of node.kind === 'object' ? Object.entries(node.properties) : []) {
+			yield { provenance: property.provenance, path: `${path}.properties.${name}`, name };
+			stack.push({ node: property.node, path: `${path}.properties.${name}.node` });
+		}
+		stack.push(...childrenOf(node, path));
+	}
+}
+
+/** Reads each file once; `undefined` for one that does not exist. */
+function fileLines() {
+	const files = new Map();
+	return (path) => {
+		if (!files.has(path)) files.set(path, existsSync(path) ? readFileSync(path, 'utf8').split('\n') : undefined);
+		return files.get(path);
+	};
+}
+
+/** The lines of the file a pointer names and the index of its line, or why it names none. */
+function citedLine({ source, pointer }, recorded, linesOf) {
+	const parts = POINTER.exec(pointer)?.groups;
+	if (parts === undefined || recorded === undefined || !parts.path.startsWith(`${recorded.name}/`))
+		return { problem: `is not a line of a file of source "${source}"` };
+	const relative = parts.path.slice(recorded.name.length + 1);
+	const lines = relative.split('/').includes('..') ? undefined : linesOf(join(recorded.directory, relative));
+	const index = Number(parts.line) - 1;
+	if (lines === undefined || index >= lines.length) return { problem: `names no line of ${recorded.name}` };
+	return { lines, index, declaration: relative.endsWith('.d.ts') };
+}
+
+/** The problem of one source reference, if any. `name`: the property it is the provenance of, when held to its line. */
+function problemOf(reference, recorded, linesOf, name) {
+	const { problem, lines, index, declaration } = citedLine(reference, recorded, linesOf);
+	if (problem !== undefined) return problem;
+	return name !== undefined && declaration && !declares(lines, index, name) ? `does not declare "${name}"` : undefined;
+}
+
+/**
+ * The provenance problems of `artifact`, built from the install under `root` (CG-07-06). Each pointer
+ * must name a file of the package its source records (the library under `root`, the compiler this
+ * generator loads) and a line in it; the declaration an authoritative property cites first must
+ * declare that property. A generated artifact is never written with one (D19).
+ * @returns {string[]}
+ */
+export function untracedFacts(root, artifact) {
+	const recorded = new Map(
+		Object.entries(artifact.sources).map(([id, { locator }]) => {
+			const name = packageOf(locator);
+			return [id, { name, directory: sourceDirectory(root, name) }];
+		})
+	);
+	const linesOf = fileLines();
+	const problems = [];
+	for (const { provenance, path, name } of records(artifact))
+		for (const [index, reference] of provenance.sources.entries()) {
+			if (reference.pointer === undefined) continue;
+			const held = index === 0 && provenance.confidence === 'authoritative' ? name : undefined;
+			const problem = problemOf(reference, recorded.get(reference.source), linesOf, held);
+			if (problem !== undefined) problems.push(`${path}: ${reference.pointer} ${problem}`);
+		}
+	return problems;
+}

package/lib/types.mjs

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+
+import ts from 'typescript';
+
+import { verifiedCompiler } from './lock.mjs';
+import { upstreamChanged } from './nodes.mjs';
+
+const GENERATOR = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+/** The source id of the TypeScript compiler, whose lib files facts about DOM and built-in types cite. */
+export const COMPILER_SOURCE = 'typescript';
+
+/**
+ * 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, library) {
+	const changed = upstreamChanged(`${library} types`);
+	const property = (type, name) => {
+		const symbol = checker.getPropertyOfType(type, name);
+		if (symbol === undefined) throw changed(`no "${name}" property`);
+		return symbol;
+	};
+	const propertyType = (type, name) => checker.getNonNullableType(checker.getTypeOfSymbol(property(type, name)));
+	const indexValueType = (type) => {
+		const info = checker.getIndexInfoOfType(type, ts.IndexKind.String);
+		if (info === undefined) throw changed('expected a string index signature');
+		return info.type;
+	};
+	const elementType = (arrayType) => {
+		const [element] = checker.getTypeArguments(arrayType);
+		if (element === undefined) throw changed('expected an array type');
+		return element;
+	};
+	return { checker, property, propertyType, indexValueType, elementType };
+}
+
+/** The members of a union type, or the type itself. */
+export function unionMembers(type) {
+	return type.isUnion() ? type.types : [type];
+}
+
+/**
+ * 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 }) {
+	const compiler = verifiedCompiler(ts.version);
+	return {
+		irVersion: 1,
+		library,
+		libraryVersion: pin.version,
+		// Not full until official examples pass against the runtime (CG-01-08).
+		coverage: 'partial',
+		generator: { name: GENERATOR.name, version: GENERATOR.version },
+		sources: {
+			[sourceId]: {
+				kind: 'npm-package',
+				locator: `${pin.package}@${pin.version}`,
+				integrity: pin.integrity,
+				license: pin.license.spdx
+			},
+			[COMPILER_SOURCE]: {
+				kind: 'npm-package',
+				locator: `${compiler.package}@${compiler.version}`,
+				integrity: compiler.integrity,
+				license: compiler.license.spdx
+			}
+		},
+		definitions,
+		root
+	};
+}