gesso-vite-plugin 0.6.30 → 0.8.0

package/dist/gesso-channels.mjs

@@ -52,6 +52,8 @@ function importPath(fromDir, file) {
 var ContractReader = class {
 	api = null;
 	changed = /* @__PURE__ */ new Set();
+	created = /* @__PURE__ */ new Set();
+	deleted = /* @__PURE__ */ new Set();
 	/** Each contract's tsconfig, found once. */
 	configs = /* @__PURE__ */ new Map();
 	/**
@@ -66,39 +68,69 @@ var ContractReader = class {
 		this.cwd = cwd;
 		this.fs = fs;
 	}
-	/** A file changed on disk since the last read. */
-	invalidate(file) {
-		this.changed.add(file);
+	/**
+	* A file changed on disk since the last read. A new or deleted one is
+	* said so, because a program's list of files only changes for those:
+	* a component in a new file is otherwise not in the catalog.
+	*/
+	invalidate(file, event = "update") {
+		(event === "create" ? this.created : event === "delete" ? this.deleted : this.changed).add(file);
 	}
-	/** Every channel `file` exports, described. */
-	read(file) {
+	/**
+	* A snapshot of the projects, with what changed since the last one.
+	*
+	* The checker keeps every project it has opened, and asked to update
+	* one whose tsconfig has since been deleted it refuses the whole
+	* update ("project not found for update"). That was a dev server gone
+	* with it: a project's tsconfig removed while the server ran threw out
+	* of the catalog's read and took the process down. A refused update is
+	* a checker started afresh, which reads the disk as it now is and
+	* opens only what is asked of it again.
+	*/
+	snapshot(request) {
 		const api = this.api ??= new this.ts.API({
 			cwd: this.cwd,
 			...this.fs === void 0 ? {} : { fs: this.fs }
 		});
-		this.changed.add(file);
-		let snapshot = api.updateSnapshot({ fileChanges: { changed: [...this.changed] } });
-		this.changed.clear();
-		let config = this.configs.get(file);
-		if (config === void 0) {
-			config = api.updateSnapshot({ openFiles: [file] }).getDefaultProjectForFile(file)?.configFileName;
-			snapshot = api.updateSnapshot({
-				...config === void 0 ? {} : { openProjects: [config] },
-				closeFiles: [file]
+		try {
+			return api.updateSnapshot({
+				...request,
+				fileChanges: this.takeChanges()
 			});
-			if (config !== void 0) this.configs.set(file, config);
+		} catch {
+			this.close();
+			this.configs.clear();
+			const fresh = this.api = new this.ts.API({
+				cwd: this.cwd,
+				...this.fs === void 0 ? {} : { fs: this.fs }
+			});
+			const { fileChanges: _changes, ...rest } = request;
+			return fresh.updateSnapshot(rest);
 		}
-		const project = config === void 0 ? void 0 : snapshot.getProject(config);
-		const source = project?.program.getSourceFile(file);
-		if (project === void 0 || source === void 0) return {
+	}
+	/** What changed since the last snapshot, emptied for the next. */
+	takeChanges() {
+		const changes = {
+			changed: [...this.changed],
+			created: [...this.created],
+			deleted: [...this.deleted]
+		};
+		this.changed.clear();
+		this.created.clear();
+		this.deleted.clear();
+		return changes;
+	}
+	/** Every channel `file` exports, described. */
+	read(file) {
+		const opened = this.open(file);
+		if (typeof opened === "string") return {
 			channels: /* @__PURE__ */ new Map(),
-			warnings: [`TypeScript has no project that includes ${file}.`]
+			warnings: [opened]
 		};
-		const checker = project.checker;
-		const module = checker.getSymbolAtLocation(source);
+		const { checker, exports } = opened;
 		const describer = new Describer(this.ts, checker);
 		const channels = /* @__PURE__ */ new Map();
-		for (const exported of module === void 0 ? [] : checker.getExportsOfModule(module)) {
+		for (const exported of exports) {
 			const type = checker.getTypeOfSymbol(exported);
 			if (type === void 0 || type.getSymbol()?.name !== "ChannelToken") continue;
 			const [view, commands] = checker.getTypeArguments(type);
@@ -109,6 +141,128 @@ var ContractReader = class {
 			warnings: describer.warnings
 		};
 	}
+	/**
+	* Every component `file` exports, described: a function whose first
+	* parameter is `Inputs<P>`, or a class extending `Component`, whose
+	* inputs are its `InputCell` fields. A library's index re-exports its
+	* components, and reading it reads all of them.
+	*/
+	readComponents(file, config) {
+		const opened = this.open(file, config);
+		if (typeof opened === "string") return {
+			components: /* @__PURE__ */ new Map(),
+			warnings: [opened]
+		};
+		const { checker, exports } = opened;
+		const describer = new Describer(this.ts, checker, "component");
+		const components = /* @__PURE__ */ new Map();
+		for (const exported of exports) {
+			const symbol = exported.flags & this.ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+			const type = checker.getTypeOfSymbol(symbol);
+			const inputs = type === void 0 ? void 0 : this.inputsOf(checker, type);
+			if (inputs !== void 0) components.set(exported.name, describer.component(symbol, inputs));
+		}
+		return {
+			components,
+			warnings: describer.warnings
+		};
+	}
+	/**
+	* The source files of the project `config` describes, with their
+	* text: what the project itself wrote, so neither its dependencies
+	* nor declaration files. The project's own tsconfig decides what that
+	* is, which is the answer the person already gave their editor.
+	*/
+	sources(config) {
+		const program = this.snapshot({ openProjects: [config] }).getProject(config)?.program;
+		if (program === void 0) return [];
+		const out = [];
+		for (const file of program.getSourceFileNames()) {
+			if (file.includes("/node_modules/") || /\.d\.[cm]?ts$/.test(file)) continue;
+			const text = program.getSourceFile(file)?.text;
+			if (text !== void 0) out.push({
+				file,
+				text
+			});
+		}
+		return out;
+	}
+	/** The inputs a component's type declares, or undefined when it is not a component. */
+	inputsOf(checker, type) {
+		const { Call, Construct } = this.ts.SignatureKind;
+		const [call] = checker.getSignaturesOfType(type, Call);
+		const first = call?.getParameters()[0];
+		if (first !== void 0) {
+			const parameter = checker.getTypeOfSymbol(first);
+			const returns = checker.getReturnTypeOfSignature(call);
+			if (parameter?.getAliasSymbol()?.name === "Inputs" && returns !== void 0 && this.drawable(returns)) {
+				const [props] = parameter.getAliasTypeArguments();
+				return props === void 0 ? void 0 : {
+					kind: "props",
+					type: props
+				};
+			}
+			return;
+		}
+		const [construct] = checker.getSignaturesOfType(type, Construct);
+		const instance = construct === void 0 ? void 0 : checker.getReturnTypeOfSignature(construct);
+		if (instance === void 0 || !this.extendsComponent(instance)) return;
+		const cells = [];
+		for (const property of checker.getPropertiesOfType(instance)) {
+			const propertyType = checker.getTypeOfSymbol(property);
+			if (propertyType?.getSymbol()?.name === "InputCell") {
+				const [value] = checker.getTypeArguments(propertyType);
+				if (value !== void 0) cells.push({
+					symbol: property,
+					type: value
+				});
+			}
+		}
+		return {
+			kind: "cells",
+			cells
+		};
+	}
+	/** Whether a function returning `type` returns a child: `UiChild`, an element, or a union of them. */
+	drawable(type) {
+		if (type.getAliasSymbol()?.name === "UiChild") return true;
+		return (type.isUnionType() ? type.getTypes() ?? [] : [type]).some((member) => CHILD.has(member.getSymbol()?.name ?? ""));
+	}
+	extendsComponent(type) {
+		for (let depth = 0, current = type; current !== void 0 && depth < 16; depth++) {
+			if (current.getSymbol()?.name === "Component") return true;
+			current = current.isClassOrInterface() ? current.getBaseTypes()?.[0] : void 0;
+		}
+		return false;
+	}
+	/**
+	* The checker and the module's exports, or why there are none: read
+	* in the project `preferred` names when it includes the file (the
+	* catalog's own tsconfig, which may resolve its imports differently
+	* from any beside it), else the project TypeScript finds for it.
+	*/
+	open(file, preferred) {
+		this.changed.add(file);
+		let snapshot = this.snapshot(preferred === void 0 ? {} : { openProjects: [preferred] });
+		let config = preferred !== void 0 && snapshot.getProject(preferred)?.program.getSourceFile(file) !== void 0 ? preferred : this.configs.get(file);
+		if (config === void 0) {
+			config = this.snapshot({ openFiles: [file] }).getDefaultProjectForFile(file)?.configFileName;
+			snapshot = this.snapshot({
+				...config === void 0 ? {} : { openProjects: [config] },
+				closeFiles: [file]
+			});
+			if (config !== void 0) this.configs.set(file, config);
+		}
+		const project = config === void 0 ? void 0 : snapshot.getProject(config);
+		const source = project?.program.getSourceFile(file);
+		if (project === void 0 || source === void 0) return `TypeScript has no project that includes ${file}.`;
+		const checker = project.checker;
+		const module = checker.getSymbolAtLocation(source);
+		return {
+			checker,
+			exports: module === void 0 ? [] : checker.getExportsOfModule(module)
+		};
+	}
 	close() {
 		this.api?.close();
 		this.api = null;
@@ -175,7 +329,27 @@ const BINARY = /* @__PURE__ */ new Set([
 	"BigInt64Array",
 	"BigUint64Array"
 ]);
-/** Turns checker types into JSON Schema for one module's channels. */
+/**
+* The types a component takes as a child. `UiChild` is a union of
+* these and an Observable of them, and describing its members would
+* describe the element records a tag compiles to, which nobody writes.
+*/
+const CHILD = /* @__PURE__ */ new Set([
+	"UiElement",
+	"ComponentLikeElement",
+	"ComponentElement"
+]);
+/**
+* Turns checker types into JSON Schema for one module's channels or
+* components.
+*
+* The two differ in what is allowed. A channel's values cross a thread
+* as plain data, so a function or a class instance in one is a mistake,
+* and is reported. A component's inputs stay on the render thread, where
+* a callback is how a component talks back and a child is how it is
+* composed, so there they are described for what they are and nothing
+* is reported.
+*/
 var Describer = class {
 	warnings = [];
 	flags;
@@ -188,12 +362,86 @@ var Describer = class {
 	/** `$defs` for the schema being built. Reset per root, so each schema stands alone. */
 	defs = /* @__PURE__ */ new Map();
 	defNames = /* @__PURE__ */ new Map();
+	/** In a component, each named type's `$defs` entry, or null when it is small enough to repeat. */
+	shared = /* @__PURE__ */ new Map();
 	ts;
 	checker;
-	constructor(ts, checker) {
+	mode;
+	constructor(ts, checker, mode = "channel") {
 		this.ts = ts;
 		this.checker = checker;
 		this.flags = ts.TypeFlags;
+		this.mode = mode;
+	}
+	component(symbol, inputs) {
+		this.defs = /* @__PURE__ */ new Map();
+		this.shared = /* @__PURE__ */ new Map();
+		const checker = this.checker;
+		const properties = {};
+		const required = [];
+		const entries = inputs.kind === "cells" ? inputs.cells : checker.getPropertiesOfType(inputs.type).map((property) => ({
+			symbol: property,
+			type: checker.getTypeOfSymbol(property)
+		}));
+		const own = inputs.kind === "props" ? (inputs.type.getAliasSymbol() ?? inputs.type.getSymbol())?.name : void 0;
+		for (const { symbol: property, type: given } of entries) {
+			const path = `${symbol.name}.${property.name}`;
+			const type = given !== void 0 && this.includesUndefined(given) && !this.includesNull(given) ? checker.getNonNullableType(given) ?? given : given;
+			let schema = type === void 0 ? {} : this.describe(type, path);
+			if (type !== void 0) schema = {
+				...schema,
+				"x-gesso-type": this.typeText(type)
+			};
+			const description = checker.getDocumentationCommentOfSymbol(property);
+			if (description !== "") schema.description = description;
+			const fallback = checker.getJsDocTagsOfSymbol(property).find((tag) => tag.name === "default");
+			if (fallback?.text !== void 0) schema.default = parseDefault(fallback.text);
+			const from = property.getParent()?.name;
+			if (own !== void 0 && from !== void 0 && from !== own && !from.startsWith("__")) schema["x-gesso-from"] = from;
+			properties[property.name] = schema;
+			if (!(inputs.kind === "cells" || (property.flags & this.ts.SymbolFlags.Optional) !== 0 || given !== void 0 && this.includesUndefined(given))) required.push(property.name);
+		}
+		const schema = {
+			type: "object",
+			properties,
+			additionalProperties: false
+		};
+		if (required.length > 0) schema.required = required;
+		if (this.defs.size > 0) schema.$defs = Object.fromEntries(this.defs);
+		const out = { inputs: schema };
+		const description = this.componentDocumentation(symbol, inputs);
+		if (description !== "") {
+			out.summary = description.split(/\n\s*\n/)[0].replace(/\s+/g, " ").trim();
+			out.description = description;
+		}
+		const tags = checker.getJsDocTagsOfSymbol(symbol);
+		const examples = tags.filter((tag) => tag.name === "example" && tag.text !== void 0).map((tag) => tag.text);
+		if (examples.length > 0) out.examples = examples;
+		const deprecated = tags.find((tag) => tag.name === "deprecated");
+		if (deprecated !== void 0) out.deprecated = deprecated.text === void 0 || deprecated.text.trim() === "" ? true : deprecated.text.trim();
+		return out;
+	}
+	/**
+	* What a component is for: its own JSDoc, else its props type's. A
+	* comment elsewhere in its file is not read: no rule about which one
+	* describes the component holds across files, and a summary that is
+	* sometimes about something else is worse to an agent than none.
+	*/
+	componentDocumentation(symbol, inputs) {
+		const own = this.checker.getDocumentationCommentOfSymbol(symbol);
+		if (own !== "") return own;
+		const props = inputs.kind === "props" ? inputs.type.getAliasSymbol() ?? inputs.type.getSymbol() : void 0;
+		return props === void 0 ? "" : this.checker.getDocumentationCommentOfSymbol(props);
+	}
+	/** The type as TypeScript writes it, without the `undefined` an optional input carries. */
+	typeText(type) {
+		const defined = this.includesUndefined(type) ? this.checker.getNonNullableType(type) : type;
+		const text = this.checker.typeToString(defined ?? type);
+		return this.includesNull(type) && !/\bnull\b/.test(text) ? `${text} | null` : text;
+	}
+	includesNull(type) {
+		const isNull = (member) => (member.flags & this.flags.Null) !== 0;
+		return type.isUnionType() ? (type.getTypes() ?? []).some(isNull) : isNull(type);
 	}
 	channel(token, view, commands) {
 		const out = {
@@ -293,7 +541,30 @@ var Describer = class {
 		if (type.isUnionType()) return (type.getTypes() ?? []).some((member) => (member.flags & (Undefined | Void)) !== 0);
 		return (type.flags & (Undefined | Void)) !== 0;
 	}
+	/**
+	* In a component, a named type an input uses (`UiLength`, a props
+	* interface) is described once, in `$defs`, and referred to after.
+	* Every control takes the same layout inputs, and spelled out at each
+	* use they were most of each component's description: an agent reads
+	* these, and pays for every repetition.
+	*/
 	describe(type, path) {
+		if (this.mode !== "component") return this.describeType(type, path);
+		const known = this.shared.get(type.id);
+		if (known !== void 0) return known === null ? this.describeType(type, path) : { $ref: `#/$defs/${known}` };
+		const name = (type.getAliasSymbol() ?? type.getSymbol())?.name;
+		if (name === void 0 || name.startsWith("__") || name === "Array" || name === "ReadonlyArray") return this.describeType(type, path);
+		const schema = this.describeType(type, path);
+		if (schema.$ref !== void 0 || isSmall(schema)) {
+			this.shared.set(type.id, null);
+			return schema;
+		}
+		const defName = this.defName(type);
+		this.defs.set(defName, schema);
+		this.shared.set(type.id, defName);
+		return { $ref: `#/$defs/${defName}` };
+	}
+	describeType(type, path) {
 		const f = this.flags;
 		const flags = type.flags;
 		if (flags & (f.Any | f.Unknown)) return {};
@@ -333,6 +604,7 @@ var Describer = class {
 	union(type, path) {
 		const f = this.flags;
 		let members = (type.getTypes() ?? []).filter((member) => (member.flags & (f.Undefined | f.Void)) === 0);
+		if (this.mode === "component" && members.some((member) => CHILD.has(member.getSymbol()?.name ?? ""))) return { "x-gesso-child": true };
 		const booleans = members.filter((member) => member.flags & f.BooleanLiteral);
 		const schemas = [];
 		if (booleans.length === 2) {
@@ -376,6 +648,11 @@ var Describer = class {
 	object(type, path) {
 		const checker = this.checker;
 		const symbolName = type.getSymbol()?.name;
+		if (this.mode === "component") {
+			if (symbolName !== void 0 && CHILD.has(symbolName)) return { "x-gesso-child": true };
+			if (checker.getSignaturesOfType(type, this.ts.SignatureKind.Call).length > 0) return { "x-gesso-callback": true };
+			if (symbolName !== void 0 && NOT_PLAIN.has(symbolName) || ((type.getSymbol()?.flags ?? 0) & this.ts.SymbolFlags.Class) !== 0) return { "x-gesso-type": checker.typeToString(type) };
+		}
 		if (symbolName !== void 0 && this.inCommand && BINARY.has(symbolName)) return {
 			type: "string",
 			contentEncoding: "base64",
@@ -438,10 +715,31 @@ var Describer = class {
 		};
 	}
 	unplain(path, what) {
+		if (this.mode === "component") return {};
 		this.warnings.push(`${path} is ${what}, which is not plain data and cannot cross a channel.`);
 		return {};
 	}
 };
+/**
+* A `@default` tag's value: JSON when it is JSON (`99`, `'neutral'`
+* written with double quotes, `true`), a single-quoted string unquoted,
+* and otherwise the text as written.
+*/
+function parseDefault(text) {
+	const trimmed = text.trim();
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		const quoted = /^'(.*)'$/.exec(trimmed) ?? /^`(.*)`$/.exec(trimmed);
+		return quoted === null ? trimmed : quoted[1];
+	}
+}
+/** Whether a schema is as short as a reference to it would be. */
+function isSmall(schema) {
+	if (schema.enum !== void 0 || schema.const !== void 0) return true;
+	const keys = Object.keys(schema);
+	return keys.length === 0 || keys.length === 1 && (typeof schema.type === "string" || keys[0].startsWith("x-gesso-"));
+}
 //#endregion
 //#region bin/gesso-channels.ts
 /**