@lucidkiln/language-server 1.1.0 → 1.2.0

package/dist/main.js

@@ -411,7 +411,7 @@ const splitParameters = (list) => {
 const DOCS = {
 	tags: {
 		"add": {
-			"markdown": "- Content goes to the outlet with the same name, in the order it was added. It doesn't matter whether `add to` runs before or after the outlet.\n- The content lines up with the outlet's indentation.\n- The content can read the variables around it. Variables you `set` inside it stay inside it.\n- Content for an outlet the page doesn't have is dropped. A component still works on a page without that outlet, and when you [render one block](https://kilnlang.com/docs/api/rendering/#rendering-one-block).",
+			"markdown": "- Content goes to the outlet with the same name, in the order it was added. It doesn't matter whether `add to` runs before or after the outlet.\n- The content can read the variables around it. Variables you `set` inside it stay inside it.\n- Content for an outlet the page doesn't have is dropped. A component still works on a page without that outlet, and when you [render one block](https://kilnlang.com/docs/api/rendering/#rendering-one-block).",
 			"url": "https://kilnlang.com/docs/tags/outlet/#adding-content"
 		},
 		"apply": {
@@ -1412,19 +1412,26 @@ const bindingsAt = (scopes, offset) => {
 *
 * - `Get`: `a.b` and `a[0]`, reading a property, a map's value or a list's item.
 * - `Item`, `Key`: what `for` gives for each pass.
-* - `Result`: what a call gives once Kiln waits for it. `Params` and `Returns` describe the function for hover.
+* - `Params` and `Returns` describe a function for hover. A function made with `withRender` is an object whose `call`
+*   takes `RenderInfo` first, so `Params` leaves that out.
+* - `arg`, `plain`, `aware`, `dropRender`, `Called`: a call to a host function, written as a real call so TypeScript
+*   works out a generic function's type parameters from the arguments. See `typeWriter`.
 * - `Members`: the values whose properties a template can read, so lists, maps and primitives complete nothing.
 * - `Last`: a function's last parameter, which named arguments are gathered into.
 * - `Fits`, `NamedFit`: whether an argument fits its parameter. Unknown types always fit, so the editor never guesses.
 */
-const PRELUDE = `import type { KilnFilters, KilnFunctions, KilnGlobals, KilnTests, KilnTypes, Markup, RenderAware } from "@lucidkiln/core";
+const PRELUDE = `import type { KilnFilters, KilnFunctions, KilnGlobals, KilnTests, KilnTypes, Markup } from "@lucidkiln/core";
 type Named<N extends string> = N extends keyof KilnTypes ? KilnTypes[N] : unknown;
 type Get<V, K> = NonNullable<V> extends infer O ? O extends ReadonlyMap<unknown, infer M> ? M : O extends readonly (infer I)[] ? (K extends number ? I : unknown) : K extends keyof O ? O[K] : unknown : never;
 type Item<V> = NonNullable<V> extends infer O ? O extends string ? unknown : O extends readonly (infer I)[] ? I : O extends ReadonlyMap<unknown, infer M> ? M : O extends ReadonlySet<infer S> ? S : O extends Iterable<infer I> ? I : O extends object ? O[keyof O] : unknown : never;
 type Key<V> = NonNullable<V> extends infer O ? O extends string ? unknown : O extends readonly unknown[] | ReadonlySet<unknown> ? number : O extends ReadonlyMap<infer K, unknown> ? K : O extends object ? keyof O & string : unknown : never;
-type Returns<F> = F extends RenderAware<any, any, infer R> ? R : F extends (...args: any) => infer R ? R : unknown;
-type Result<F> = Awaited<Returns<F>>;
-type Params<F> = F extends RenderAware<any, infer A, any> ? A : F extends (...args: infer A) => any ? A : never;
+type Returns<F> = F extends (...args: never) => infer R ? R : F extends { readonly call: (...args: never) => infer R } ? R : unknown;
+type Params<F> = F extends (...args: infer A) => unknown ? A : F extends { readonly call: (render: never, ...args: infer A) => unknown } ? A : never;
+declare function arg<T>(): T;
+declare function plain<F>(fn: F): F extends (...args: never) => unknown ? F : never;
+declare function aware<F>(fn: F): F extends (...args: never) => unknown ? never : F extends { readonly call: infer C } ? C : never;
+declare function dropRender<A extends unknown[], R>(fn: (render: never, ...args: A) => R): (...args: A) => R;
+type Called<F, Plain, Aware> = unknown extends F ? unknown : F extends (...args: never) => unknown ? Awaited<Plain> : F extends { readonly call: unknown } ? Awaited<Aware> : unknown;
 type Tail<A> = A extends readonly [unknown?, ...infer R] ? R : A;
 type Last<A> = Required<A> extends readonly [...unknown[], infer L] ? L : A extends readonly (infer E)[] ? E : unknown;
 type Fits<A, P> = [P] extends [never] ? true : unknown extends P ? true : unknown extends A ? true : [Exclude<A, Markup>] extends [P] ? true : false;
@@ -1513,88 +1520,135 @@ const ITEM_PARAMS = {
 	reduce: [1]
 };
 const MAX_DEPTH = 32;
-/** The TypeScript type of a variable, from where its value comes from. */
-const bindingType = (source, context, depth = 0) => {
-	const of = (expression) => expressionType(expression, context, depth + 1);
-	switch (source.kind) {
-		case "prop": return propType(source.type);
-		case "rest": return "Readonly<Record<string, unknown>>";
-		case "set": return of(source.value);
-		case "capture": return "Markup";
-		case "item": return `Item<${of(source.iterable)}>`;
-		case "key": return `Key<${of(source.iterable)}>`;
-		case "arrow": return ITEM_PARAMS[source.filter]?.includes(source.index) ? `Item<${of(source.input)}>` : "unknown";
-		case "with": return `Get<${of(source.value)}, ${JSON.stringify(source.key)}>`;
-		default: return "unknown";
-	}
-};
 const union = (types) => types.length === 0 ? "never" : [...new Set(types)].join(" | ");
 const literalKey = (expression) => expression.type === "Literal" && (typeof expression.value === "string" || typeof expression.value === "number") ? JSON.stringify(expression.value) : null;
-/** Writes the TypeScript type of a Kiln expression, using the helper types in `PRELUDE`. */
-const expressionType = (expression, context, depth = 0) => {
-	if (depth > MAX_DEPTH) return "unknown";
-	const of = (inner) => expressionType(inner, context, depth + 1);
-	const args = (list) => list.map((arg) => arg.type === "Spread" ? "unknown" : of(arg.value));
-	switch (expression.type) {
-		case "Literal": return expression.value === null ? "null" : typeof expression.value;
-		case "Interpolation": return "string";
-		case "Array": return `(${union(expression.elements.map((element) => element.type === "Spread" ? `Item<${of(element.value)}>` : of(element)))})[]`;
-		case "Hash": return `{ ${expression.entries.flatMap((entry) => {
-			if (entry.type === "Spread") return [];
-			const key = entry.key.type === "Name" ? JSON.stringify(entry.key.name) : literalKey(entry.key);
-			return key ? [`${key}: ${of(entry.value)}`] : [];
-		}).join("; ")} }`;
-		case "Unary": return expression.operator === "not" ? "boolean" : "number";
-		case "Binary": switch (expression.operator) {
-			case "??":
-			case "?:": return `NonNullable<${of(expression.left)}> | ${of(expression.right)}`;
-			case "~": return "string";
-			case "..": return "number[]";
-			case "+":
-			case "-":
-			case "*":
-			case "/":
-			case "//":
-			case "%":
-			case "**": return "number";
-			default: return "boolean";
-		}
-		case "Conditional": return union([of(expression.consequent), expression.alternate ? of(expression.alternate) : "null"]);
-		case "Member": {
-			const key = literalKey(expression.property) ?? "string";
-			return `Get<${of(expression.object)}, ${key}>`;
+/**
+* Writes the types of a template's values. A literal's type is its value, so `"page"` is `"page"`. A call to a host
+* function or filter becomes a real call in `statements`, so TypeScript works out a generic function's type parameters
+* from the arguments:
+*
+* ```ts
+* declare const $fn0: Get<KilnFunctions, "document">;
+* const $plain0 = plain($fn0)(arg<"page">());
+* const $aware0 = dropRender(aware($fn0))(arg<"page">());
+* ```
+*
+* The call's type is `Called<typeof $fn0, typeof $plain0, typeof $aware0>`: the first call for a plain function, the
+* second for one made with `withRender`. Each expression is written once, however often a template reads it.
+*/
+const typeWriter = (context) => {
+	const statements = [];
+	const written = /* @__PURE__ */ new Map();
+	/** Writes a call to `callee`, a TypeScript type, with the types of its arguments, and returns the result's type. */
+	const call = (callee, args) => {
+		const id = statements.length;
+		const list = args.join(", ");
+		statements.push(`declare const $fn${id}: ${callee};\nconst $plain${id} = plain($fn${id})(${list});\nconst $aware${id} = dropRender(aware($fn${id}))(${list});\n`);
+		return `Called<typeof $fn${id}, typeof $plain${id}, typeof $aware${id}>`;
+	};
+	/** A call's arguments as TypeScript: named arguments are gathered into one hash at the end, as Kiln does. */
+	const callArgs = (list, depth, input) => {
+		const named = list.flatMap((item) => item.type === "Named" ? [`${JSON.stringify(item.name)}: ${expression(item.value, depth)}`] : []);
+		return [
+			...input ? [`arg<${input}>()`] : [],
+			...list.flatMap((item) => {
+				if (item.type === "Named") return [];
+				const type = expression(item.value, depth);
+				return [item.type === "Spread" ? `...arg<Item<${type}>[]>()` : `arg<${type}>()`];
+			}),
+			...named.length > 0 ? [`arg<{ ${named.join("; ")} }>()`] : []
+		];
+	};
+	const binding = (source, depth) => {
+		const of = (value) => expression(value, depth + 1);
+		switch (source.kind) {
+			case "prop": return propType(source.type);
+			case "rest": return "Readonly<Record<string, unknown>>";
+			case "set": return of(source.value);
+			case "capture": return "Markup";
+			case "item": return `Item<${of(source.iterable)}>`;
+			case "key": return `Key<${of(source.iterable)}>`;
+			case "arrow": return ITEM_PARAMS[source.filter]?.includes(source.index) ? `Item<${of(source.input)}>` : "unknown";
+			case "with": return `Get<${of(source.value)}, ${JSON.stringify(source.key)}>`;
+			default: return "unknown";
 		}
-		case "Call": {
-			const { callee } = expression;
-			if (callee.type === "Member") {
-				const key = literalKey(callee.property) ?? "string";
-				return `Result<Get<${of(callee.object)}, ${key}>>`;
+	};
+	const expression = (node, depth) => {
+		if (depth > MAX_DEPTH) return "unknown";
+		const known = written.get(node);
+		if (known) return known;
+		const type = write(node, depth + 1);
+		written.set(node, type);
+		return type;
+	};
+	const write = (node, depth) => {
+		const of = (inner) => expression(inner, depth);
+		switch (node.type) {
+			case "Literal": return typeof node.value === "string" ? JSON.stringify(node.value) : String(node.value);
+			case "Interpolation": return "string";
+			case "Array": return `(${union(node.elements.map((element) => element.type === "Spread" ? `Item<${of(element.value)}>` : of(element)))})[]`;
+			case "Hash": return `{ ${node.entries.flatMap((entry) => {
+				if (entry.type === "Spread") return [];
+				const key = entry.key.type === "Name" ? JSON.stringify(entry.key.name) : literalKey(entry.key);
+				return key ? [`${key}: ${of(entry.value)}`] : [];
+			}).join("; ")} }`;
+			case "Unary": return node.operator === "not" ? "boolean" : "number";
+			case "Binary": switch (node.operator) {
+				case "??":
+				case "?:": return `NonNullable<${of(node.left)}> | ${of(node.right)}`;
+				case "~": return "string";
+				case "..": return "number[]";
+				case "+":
+				case "-":
+				case "*":
+				case "/":
+				case "//":
+				case "%":
+				case "**": return "number";
+				default: return "boolean";
 			}
-			if (callee.type !== "Name") return "unknown";
-			const name = callee.name;
-			if (context.macros.has(name)) return "Markup";
-			const builtin = BUILTIN_FUNCTIONS[name];
-			if (builtin && !context.functions.includes(name)) return builtin;
-			return `Result<Get<KilnFunctions, ${JSON.stringify(name)}>>`;
-		}
-		case "Filter": {
-			const input = of(expression.input);
-			const builtin = BUILTIN_FILTERS[expression.name];
-			if (!builtin || context.filters.includes(expression.name)) return `Result<Get<KilnFilters, ${JSON.stringify(expression.name)}>>`;
-			const arrow = expression.args[0]?.value;
-			if (expression.name === "map" && arrow?.type === "Arrow") return `(${of(arrow.body)})[]`;
-			return builtin(input, args(expression.args));
-		}
-		case "Test": return "boolean";
-		case "OptionalChain": return of(expression.expression);
-		case "Name": {
-			if (expression.name === "loop") return "unknown";
-			const binding = bindingAt(context.scopes, expression.name, expression.span.start);
-			if (binding) return bindingType(binding.source, context, depth + 1);
-			return `Get<KilnGlobals, ${JSON.stringify(expression.name)}>`;
+			case "Conditional": return union([of(node.consequent), node.alternate ? of(node.alternate) : "null"]);
+			case "Member": {
+				const key = literalKey(node.property) ?? "string";
+				return `Get<${of(node.object)}, ${key}>`;
+			}
+			case "Call": {
+				const { callee } = node;
+				if (callee.type === "Member") {
+					const key = literalKey(callee.property) ?? "string";
+					return call(`Get<${of(callee.object)}, ${key}>`, callArgs(node.args, depth));
+				}
+				if (callee.type !== "Name") return "unknown";
+				const name = callee.name;
+				if (context.macros.has(name)) return "Markup";
+				const builtin = BUILTIN_FUNCTIONS[name];
+				if (builtin && !context.functions.includes(name)) return builtin;
+				return call(`Get<KilnFunctions, ${JSON.stringify(name)}>`, callArgs(node.args, depth));
+			}
+			case "Filter": {
+				const input = of(node.input);
+				const builtin = BUILTIN_FILTERS[node.name];
+				if (!builtin || context.filters.includes(node.name)) return call(`Get<KilnFilters, ${JSON.stringify(node.name)}>`, callArgs(node.args, depth, input));
+				const arrow = node.args[0]?.value;
+				if (node.name === "map" && arrow?.type === "Arrow") return `(${of(arrow.body)})[]`;
+				return builtin(input, node.args.map((item) => item.type === "Spread" ? "unknown" : of(item.value)));
+			}
+			case "Test": return "boolean";
+			case "OptionalChain": return of(node.expression);
+			case "Name": {
+				if (node.name === "loop") return "unknown";
+				const found = bindingAt(context.scopes, node.name, node.span.start);
+				if (found) return binding(found.source, depth);
+				return `Get<KilnGlobals, ${JSON.stringify(node.name)}>`;
+			}
+			default: return "unknown";
 		}
-		default: return "unknown";
-	}
+	};
+	return {
+		expression: (node) => expression(node, 0),
+		binding: (source) => binding(source, 0),
+		statements
+	};
 };
 /** The registries a project describes in TypeScript, by the kind of name the language server looks up. */
 const REGISTRIES = {
@@ -1603,9 +1657,12 @@ const REGISTRIES = {
 	test: "KilnTests",
 	global: "KilnGlobals"
 };
-/** Checks a file of `type name = type` aliases with the project's TypeScript, and reads it with `use`. */
-const withTypes = (typescript, aliases, use) => {
-	const source = PRELUDE + Object.entries(aliases).map(([name, type]) => `type ${name} = ${type};\n`).join("");
+/**
+* Checks a file of `type name = type` aliases with the project's TypeScript, and reads it with `use`. `statements` are
+* what the aliases read, from a `TypeWriter`.
+*/
+const withTypes = (typescript, aliases, use, statements = []) => {
+	const source = PRELUDE + statements.join("") + Object.entries(aliases).map(([name, type]) => `type ${name} = ${type};\n`).join("");
 	return typescript.query(source, use);
 };
 /** The TypeScript type of a registered function, filter or test, by kind and name. */
@@ -1639,8 +1696,11 @@ const describeCallable = (typescript, kind, name) => withTypes(typescript, {
 });
 /** The names a function or filter takes as named arguments: the properties of its last parameter. */
 const namedOptions = (typescript, kind, name) => withTypes(typescript, { Options: `Members<Last<${parametersType(kind, name)}>>` }, (read) => read.members("Options")) ?? [];
-/** Checks arguments against their parameters with one TypeScript query. Null for an argument that fits. */
-const checkArguments = (typescript, checks) => {
+/**
+* Checks arguments against their parameters with one TypeScript query. Null for an argument that fits. `statements` are
+* what the argument types read, from a `TypeWriter`.
+*/
+const checkArguments = (typescript, checks, statements = []) => {
 	if (checks.length === 0) return [];
 	const aliases = {};
 	checks.forEach((check, index) => {
@@ -1658,7 +1718,7 @@ const checkArguments = (typescript, checks) => {
 			expected: read.describe(`Expected${index}`) ?? "unknown",
 			actual: read.describe(`Actual${index}`) ?? "unknown"
 		};
-	})) ?? checks.map(() => null);
+	}), statements) ?? checks.map(() => null);
 };
 //#endregion
 //#region src/features.ts
@@ -1703,7 +1763,7 @@ const builtinItems = (builtins, docKind, kind, extra) => [...Object.entries(buil
 	kind,
 	detail: "From your project"
 }))];
-/** Parses a template and finds its variables, with what `expressionType` needs to work out their types. */
+/** Parses a template and finds its variables, with what `typeWriter` needs to work out their types. */
 const templateTypes = (open, text) => {
 	const manifest = open.project.manifest;
 	const scopes = templateScopes(text, (name) => name in TESTS || (manifest?.tests.includes(name) ?? false));
@@ -1739,8 +1799,9 @@ const memberDocs = (member) => [member.docs, ...member.tags.map((tag) => `*@${ta
 const membersOf = async (open, object, context) => {
 	const typescript = await open.project.typescript();
 	if (!typescript) return [];
-	const type = expressionType(object, context);
-	return withTypes(typescript, { Value: `Members<${type}>` }, (read) => read.members("Value")) ?? [];
+	const types = typeWriter(context);
+	const type = types.expression(object);
+	return withTypes(typescript, { Value: `Members<${type}>` }, (read) => read.members("Value"), types.statements) ?? [];
 };
 /** A function, filter, test or global the project describes in TypeScript. */
 const registered = async (open, kind, name) => {
@@ -1962,7 +2023,8 @@ const hover = async (open, offset) => {
 				value = sections(codeBlock(prop ? describeProp(prop) : `...${symbol.name}`), BINDING_NOTES[binding.source.kind]);
 			} else if (binding) {
 				const typescript = await project.typescript();
-				const type = typescript ? withTypes(typescript, { Value: bindingType(binding.source, types.context) }, (read) => read.describe("Value")) : null;
+				const writer = typeWriter(types.context);
+				const type = typescript ? withTypes(typescript, { Value: writer.binding(binding.source) }, (read) => read.describe("Value"), writer.statements) : null;
 				value = sections(codeBlock(type && type !== "unknown" ? `${symbol.name}: ${type}` : symbol.name, "ts"), BINDING_NOTES[binding.source.kind]);
 			} else {
 				const global = await registered(open, "global", symbol.name);
@@ -2263,6 +2325,7 @@ const argumentWarnings = async (open) => {
 	if (!typescript) return [];
 	const text = open.document.getText();
 	const { scopes, context } = templateTypes(open, text);
+	const types = typeWriter(context);
 	/**
 	* Each check, with what it's for: a filter's input, a positional or a named argument. A wrong type is reported on
 	* the value, and a named argument the function doesn't take on its name.
@@ -2284,7 +2347,7 @@ const argumentWarnings = async (open) => {
 		const parameters = parametersType(kind, name, true);
 		[...node.type === "Filter" ? [node.input] : [], ...node.args.flatMap((arg) => arg.type === "Positional" ? [arg.value] : [])].forEach((value, index) => {
 			checks.push({
-				type: expressionType(value, context),
+				type: types.expression(value),
 				parameters,
 				index,
 				span: value.span,
@@ -2295,7 +2358,7 @@ const argumentWarnings = async (open) => {
 		for (const arg of node.args) {
 			if (arg.type !== "Named") continue;
 			checks.push({
-				type: expressionType(arg.value, context),
+				type: types.expression(arg.value),
 				parameters,
 				name: arg.name,
 				span: arg.value.span,
@@ -2308,7 +2371,7 @@ const argumentWarnings = async (open) => {
 			});
 		}
 	}
-	return checkArguments(typescript, checks).flatMap((problem, index) => {
+	return checkArguments(typescript, checks, types.statements).flatMap((problem, index) => {
 		const check = checks[index];
 		if (!problem || !check) return [];
 		if (problem.kind === "missing") {