@jigs.design/compiler 0.0.0-stage → 0.1.0

package/dist/check-code.js

@@ -0,0 +1,700 @@
+import { analyze, lineOf } from "./script.js";
+import { statementProblem } from "./codegen.js";
+import { sourceRange } from "./offsets.js";
+import { nearest } from "./suggest.js";
+//#region src/check-code.ts
+/** A step of `DataRead.path` into each element of an array, as an `<each>` item takes. */
+const ELEMENT = "[]";
+/**
+* Names that do not throw ReferenceError in the sandbox: the language's
+* built-ins, the worker's own globals that `LOCKED_GLOBALS` in
+* `@jigs.design/runtime/frame` leaves in place, and Pickle's bindings. Kept by
+* hand, since the compiler runs on the server; `checks.test.ts` fails if a
+* name here is one the worker locks, or exists in no JavaScript runtime.
+* `Function`, `Proxy`, `Reflect`, `WeakRef`, `FinalizationRegistry` and
+* `Atomics` are left out and locked: no UI needs them.
+*/
+const KNOWN_GLOBALS = /* @__PURE__ */ new Set([
+	"AbortController",
+	"AbortSignal",
+	"AggregateError",
+	"Array",
+	"ArrayBuffer",
+	"BigInt",
+	"BigInt64Array",
+	"BigUint64Array",
+	"Blob",
+	"Boolean",
+	"DOMException",
+	"DataView",
+	"Date",
+	"Error",
+	"EvalError",
+	"Float16Array",
+	"Float32Array",
+	"Float64Array",
+	"Infinity",
+	"Int16Array",
+	"Int32Array",
+	"Int8Array",
+	"Intl",
+	"Iterator",
+	"JSON",
+	"Map",
+	"Math",
+	"NaN",
+	"Number",
+	"Object",
+	"Pickle",
+	"Promise",
+	"RangeError",
+	"ReferenceError",
+	"RegExp",
+	"Set",
+	"String",
+	"Symbol",
+	"SyntaxError",
+	"TextDecoder",
+	"TextEncoder",
+	"TypeError",
+	"URIError",
+	"URL",
+	"URLSearchParams",
+	"Uint16Array",
+	"Uint32Array",
+	"Uint8Array",
+	"Uint8ClampedArray",
+	"WeakMap",
+	"WeakSet",
+	"__pickle",
+	"__pickleConstants",
+	"__pickleSafe",
+	"arguments",
+	"atob",
+	"btoa",
+	"console",
+	"crypto",
+	"decodeURI",
+	"decodeURIComponent",
+	"encodeURI",
+	"encodeURIComponent",
+	"escape",
+	"globalThis",
+	"isFinite",
+	"isNaN",
+	"parseFloat",
+	"parseInt",
+	"structuredClone",
+	"undefined",
+	"unescape",
+	"useMutation",
+	"useQuery",
+	"useState"
+]);
+/** Undefined names the server reports with its own advice, from the host's procedures. */
+const NAMED_BY_SERVER = /* @__PURE__ */ new Set(["useAction"]);
+/** Browser globals a model reaches for; the sandbox has none of them. */
+const BROWSER_GLOBALS = /* @__PURE__ */ new Set([
+	"alert",
+	"clearInterval",
+	"clearTimeout",
+	"confirm",
+	"document",
+	"fetch",
+	"localStorage",
+	"location",
+	"navigator",
+	"performance",
+	"prompt",
+	"queueMicrotask",
+	"requestAnimationFrame",
+	"sessionStorage",
+	"setInterval",
+	"setTimeout",
+	"window"
+]);
+const HANDLE_FIELDS = {
+	useMutation: {
+		fields: /* @__PURE__ */ new Set([
+			"data",
+			"error",
+			"input",
+			"mutate",
+			"status"
+		]),
+		instead: /* @__PURE__ */ new Map([
+			["isError", "compare `NAME.status === \"error\"`"],
+			["isIdle", "compare `NAME.status === \"idle\"`"],
+			["isLoading", "compare `NAME.status === \"pending\"`"],
+			["isPending", "compare `NAME.status === \"pending\"`"],
+			["isSuccess", "compare `NAME.status === \"success\"`"],
+			["mutateAsync", "call `NAME.mutate(input)` from a handler; `status` and `data` update when it settles"],
+			["reset", "the handle resets when `mutate` is called again"]
+		]),
+		written: "{ status, data, error, input, mutate }"
+	},
+	useQuery: {
+		fields: /* @__PURE__ */ new Set([
+			"data",
+			"error",
+			"status"
+		]),
+		instead: /* @__PURE__ */ new Map([
+			["isError", "compare `NAME.status === \"error\"`"],
+			["isFetching", "compare `NAME.status === \"pending\"`"],
+			["isLoading", "compare `NAME.status === \"pending\"`"],
+			["isPending", "compare `NAME.status === \"pending\"`"],
+			["isSuccess", "compare `NAME.status === \"success\"`"],
+			["refetch", "a query reloads by itself when its input changes, or when a mutation that lists it under Refreshes succeeds"]
+		]),
+		written: "{ status, data, error }"
+	}
+};
+/**
+* TanStack's status flags, and the status each one compares. Each has one
+* way to write it, so the compiler rewrites it. `refetch` and `mutateAsync`
+* have none: a query refetches by itself, and code may await what
+* `mutateAsync` returns, which `mutate` does not.
+*/
+const STATUS_FLAGS = /* @__PURE__ */ new Map([
+	["isError", "error"],
+	["isFetching", "pending"],
+	["isIdle", "idle"],
+	["isLoading", "pending"],
+	["isPending", "pending"],
+	["isSuccess", "success"]
+]);
+function quoteCode(snippet) {
+	switch (snippet.place.type) {
+		case "attribute": return `<${snippet.place.tag} ${snippet.place.attribute}={${snippet.code}}>`;
+		case "statement": return "This {@body} line";
+		case "text": return `"{${snippet.code}}"`;
+	}
+}
+/**
+* The chain an `<each of>` is, when it is one alone or with `?? []` or
+* `|| []` after it: `orders.data`, `data.items ?? []`. A bare name is a
+* chain with no fields.
+*/
+function listChain(code) {
+	const analysis = analyze(code, "expression");
+	if (!analysis.ok || analysis.chains.length > 1) return null;
+	const [chain] = analysis.chains;
+	const name = /^\s*([A-Za-z_$][\w$]*)/.exec(code);
+	if (chain === void 0) return name?.[1] === void 0 || !FALLBACK.test(code.slice(name[0].length)) ? null : {
+		object: name[1],
+		path: []
+	};
+	const end = chain.ends.at(-1) ?? chain.offset;
+	return code.slice(0, chain.offset).trim() === "" && FALLBACK.test(code.slice(end)) ? {
+		object: chain.object,
+		path: chain.path
+	} : null;
+}
+/** What may follow a list's chain in `<each of>`: nothing, or an empty fallback. */
+const FALLBACK = /^\s*(?:(?:\?\?|\|\|)\s*\[\s*\]\s*)?$/;
+/** The procedure data an `<each of>` lists, when its code is a chain into it. */
+function itemSource(code, body, scope) {
+	const chain = listChain(code);
+	if (chain === null) return null;
+	const list = [chain.object, ...chain.path].join(".");
+	const outer = scope.items.get(chain.object);
+	if (outer !== void 0) return {
+		data: outer.data,
+		list,
+		path: [
+			...outer.path,
+			...chain.path,
+			"[]"
+		],
+		procedure: outer.procedure
+	};
+	const source = scope.inner.has(chain.object) ? void 0 : body.sources.get(chain.object);
+	const skip = source?.field === "handle" ? 1 : 0;
+	if (source === void 0 || skip === 1 && chain.path[0] !== "data" || chain.path.length < skip) return null;
+	return {
+		data: skip === 1 ? `${chain.object}.data` : chain.object,
+		list,
+		path: [...chain.path.slice(skip), "[]"],
+		procedure: source.procedure
+	};
+}
+function factsOf(snippet) {
+	if (snippet.kind === "statement" && statementProblem(snippet.code) !== null) return null;
+	const analysis = analyze(snippet.code, snippet.kind);
+	return analysis.ok ? analysis : null;
+}
+/** The names a body's top-level statements declare, and its query and mutation handles. */
+function readBody(statements, define, outer) {
+	const declaredAt = /* @__PURE__ */ new Map();
+	const handles = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const mutateFns = /* @__PURE__ */ new Set();
+	const maybeUndefined = /* @__PURE__ */ new Set();
+	for (const statement of statements) {
+		const facts = factsOf({
+			at: statement.at,
+			code: statement.code,
+			kind: "statement",
+			line: statement.line,
+			place: {
+				nested: false,
+				type: "statement"
+			}
+		});
+		for (const name of facts?.declared ?? []) if (!declaredAt.has(name)) declaredAt.set(name, statement.line);
+		for (const name of facts?.maybeUndefined ?? []) maybeUndefined.add(name);
+		for (const binding of facts?.hooks ?? []) {
+			if (binding.hook === "useState") continue;
+			if (binding.property === null) {
+				handles.set(binding.name, binding.hook);
+				if (binding.procedure !== null) sources.set(binding.name, {
+					field: "handle",
+					procedure: binding.procedure
+				});
+			} else if (binding.hook === "useMutation" && binding.property === "mutate") mutateFns.add(binding.name);
+			else if (binding.property === "data" && binding.procedure !== null) sources.set(binding.name, {
+				field: "data",
+				procedure: binding.procedure
+			});
+		}
+	}
+	return {
+		declaredAt,
+		define,
+		early: [],
+		handles,
+		late: [],
+		maybeUndefined,
+		missing: [],
+		mutateFns,
+		outer,
+		reported: /* @__PURE__ */ new Set(),
+		sources
+	};
+}
+/**
+* Checks every piece of code in the page and its defines, adding to
+* `diagnostics`, and returns the procedure calls it saw, in source order.
+*/
+function checkCode(tree, defines, pageStatements, diagnostics, hoists, dropped = /* @__PURE__ */ new Set()) {
+	const procedures = [];
+	const reads = [];
+	const report = (place, code, message, fix) => {
+		const diagnostic = {
+			code,
+			...place,
+			message,
+			severity: "warning"
+		};
+		if (fix !== void 0) diagnostic.fix = fix;
+		diagnostics.push(diagnostic);
+	};
+	const checkSnippet = (snippet, body, scope) => {
+		const facts = factsOf(snippet);
+		if (facts === null) return;
+		/** The place of `[offset, end)` in the snippet's code. */
+		const placeAt = (offset, end) => {
+			const line = lineOf(snippet.code, snippet.line, offset);
+			return snippet.at === void 0 ? { line } : {
+				line,
+				...sourceRange(snippet.at, offset, end)
+			};
+		};
+		for (const { end, offset, ...call } of facts.procedures) procedures.push({
+			...call,
+			...placeAt(offset, end)
+		});
+		const once = (key) => {
+			if (body.reported.has(key)) return false;
+			body.reported.add(key);
+			return true;
+		};
+		const shadowed = (name) => scope.inner.has(name);
+		for (const compare of facts.nullCompares) {
+			if (!body.maybeUndefined.has(compare.name) || shadowed(compare.name)) continue;
+			const loose = compare.operator === "!==" ? "!=" : "==";
+			const operator = placeAt(compare.operatorOffset, compare.operatorEnd);
+			report(placeAt(compare.offset, compare.end), "undefined_compare", `\`${compare.name} ${compare.operator} null\` misses undefined, which \`${compare.name}\` is when \`find\`, \`at\` or an index finds nothing: compare \`${compare.name} ${loose} null\``, operator.start === void 0 || operator.end === void 0 ? void 0 : {
+				edits: [{
+					end: operator.end,
+					start: operator.start,
+					text: loose
+				}],
+				title: `Replace with \`${compare.name} ${loose} null\``
+			});
+		}
+		for (const chain of facts.chains) {
+			const item = scope.items.get(chain.object);
+			if (item !== void 0) {
+				reads.push({
+					data: item.data,
+					item: {
+						list: item.list,
+						name: chain.object,
+						steps: item.path.length
+					},
+					path: [...item.path, ...chain.path],
+					places: [...item.path.map(() => null), ...chain.ends.map((end) => placeAt(chain.offset, end))],
+					procedure: item.procedure
+				});
+				continue;
+			}
+			const source = shadowed(chain.object) ? void 0 : body.sources.get(chain.object);
+			const skip = source?.field === "handle" ? 1 : 0;
+			if (source === void 0 || skip === 1 && chain.path[0] !== "data" || chain.path.length <= skip) continue;
+			reads.push({
+				data: skip === 1 ? `${chain.object}.data` : chain.object,
+				path: chain.path.slice(skip),
+				places: chain.ends.slice(skip).map((end) => placeAt(chain.offset, end)),
+				procedure: source.procedure
+			});
+		}
+		for (const issue of facts.issues) report(placeAt(issue.offset, issue.end), issue.code, issue.message);
+		const seen = /* @__PURE__ */ new Set();
+		const callsFetch = facts.calls.some((call) => call.callee === "fetch");
+		for (const reference of facts.references) {
+			const { name } = reference;
+			if (scope.names.has(name) || KNOWN_GLOBALS.has(name)) {
+				const declared = body.declaredAt.get(name);
+				if (declared !== void 0 && declared > snippet.line && !reference.deferred && !shadowed(name) && once(`order:${name}`)) {
+					if (snippet.place.type === "statement" && !snippet.place.nested) body.late.push({
+						message: `This {@body} line reads "${name}" before line ${declared} declares it, so it sees undefined. Move the declaration up`,
+						place: placeAt(reference.offset, reference.end)
+					});
+					else body.early.push({
+						declared,
+						name,
+						place: placeAt(reference.offset, reference.end)
+					});
+				}
+				continue;
+			}
+			if (seen.has(name)) continue;
+			seen.add(name);
+			if (body.outer.has(name)) {
+				if (once(`outer:${name}`)) report(placeAt(reference.offset, reference.end), "outer_reference", `<define name="${body.define ?? ""}"> uses "${name}" from the page; components can't see page state. Pass it in as a prop`);
+				continue;
+			}
+			if (name === "fetch" && callsFetch || NAMED_BY_SERVER.has(name) || dropped.has(name)) continue;
+			const inBlocks = hoists.byName.get(name) ?? [];
+			const [hoist] = inBlocks;
+			if (hoist !== void 0) {
+				const entry = {
+					message: blockMessage(snippet, name, inBlocks),
+					name,
+					own: true,
+					place: placeAt(reference.offset, reference.end)
+				};
+				if (inBlocks.length === 1 && hoist.fix !== null) entry.fix = hoist.fix;
+				body.missing.push(entry);
+				continue;
+			}
+			body.missing.push({
+				message: undefinedMessage(snippet, name, scope.names),
+				name,
+				own: BROWSER_GLOBALS.has(name) || nearest(name, scope.names, 1).length > 0,
+				place: placeAt(reference.offset, reference.end)
+			});
+		}
+		for (const member of facts.members) {
+			const hook = shadowed(member.object) ? void 0 : body.handles.get(member.object);
+			if (hook === void 0) continue;
+			const written = `${member.object}.${member.property}`;
+			if (hook === "useMutation" && member.property === "mutate" && member.called && !member.deferred) {
+				report(placeAt(member.offset, member.end), "mutate_in_render", mutateMessage(written));
+				continue;
+			}
+			const fields = HANDLE_FIELDS[hook];
+			if (fields.fields.has(member.property)) continue;
+			const place = placeAt(member.offset, member.end);
+			const status = STATUS_FLAGS.get(member.property);
+			const fix = status !== void 0 && fields.instead.has(member.property) && !member.called && place.start !== void 0 && place.end !== void 0 && snippet.code.slice(member.offset, member.end) === written ? statusFix(member.object, status, place.start, place.end) : void 0;
+			report(place, "handle_field", handleFieldMessage(hook, member.object, member.property, member.called), fix);
+		}
+		for (const call of facts.calls) if (body.mutateFns.has(call.callee) && !shadowed(call.callee) && !call.deferred) report(placeAt(call.offset, call.end), "mutate_in_render", mutateMessage(call.callee));
+		for (const binding of facts.hooks) {
+			if (binding.hook === "useState" || binding.property === null) continue;
+			if (!HANDLE_FIELDS[binding.hook].fields.has(binding.property)) report(placeAt(0, snippet.code.length), "handle_field", handleFieldMessage(binding.hook, "handle", binding.property, false));
+		}
+	};
+	const walk = (nodes, body, scope) => {
+		const attribute = (tag, name, code, line, at) => {
+			checkSnippet({
+				at,
+				code,
+				kind: "expression",
+				line,
+				place: {
+					attribute: name,
+					tag,
+					type: "attribute"
+				}
+			}, body, scope);
+		};
+		for (const node of nodes) switch (node.type) {
+			case "expr":
+				checkSnippet({
+					at: node.at,
+					code: node.code,
+					kind: "expression",
+					line: node.line,
+					place: { type: "text" }
+				}, body, scope);
+				break;
+			case "element":
+			case "call": {
+				const tag = node.type === "element" ? node.component : node.name;
+				for (const [name, value] of Object.entries(node.props)) if (value.kind === "expr") attribute(tag, name, value.code, node.line, value.at);
+				if (node.type === "call" && node.key?.kind === "expr") attribute(tag, "key", node.key.code, node.line, node.key.at);
+				walk(node.children, body, scope);
+				break;
+			}
+			case "if":
+				attribute("if", "test", node.test, node.line, node.testAt);
+				block(node.statements, node.children, body, scope, []);
+				break;
+			case "each": {
+				attribute("each", "of", node.items, node.line, node.itemsAt);
+				const item = itemSource(node.items, body, scope);
+				block(node.statements, node.children, body, scope, node.index === null ? [node.item] : [node.item, node.index], item === null ? void 0 : {
+					name: node.item,
+					source: item
+				});
+				break;
+			}
+		}
+	};
+	const block = (statements, children, body, scope, bound, item) => {
+		const lines = [];
+		for (const statement of statements) {
+			const facts = factsOf({
+				at: statement.at,
+				code: statement.code,
+				kind: "statement",
+				line: statement.line,
+				place: {
+					nested: true,
+					type: "statement"
+				}
+			});
+			lines.push(...facts?.declared ?? []);
+		}
+		const declared = [...bound, ...lines];
+		const items = new Map(scope.items);
+		for (const name of declared) items.delete(name);
+		if (item !== void 0 && !lines.includes(item.name)) items.set(item.name, item.source);
+		const inner = {
+			inner: /* @__PURE__ */ new Set([...scope.inner, ...declared]),
+			items,
+			names: /* @__PURE__ */ new Set([...scope.names, ...declared])
+		};
+		for (const statement of statements) checkSnippet({
+			at: statement.at,
+			code: statement.code,
+			kind: "statement",
+			line: statement.line,
+			place: {
+				nested: true,
+				type: "statement"
+			}
+		}, body, inner);
+		walk(children, body, inner);
+	};
+	const checkBody = (statements, children, body, names) => {
+		const scope = {
+			inner: /* @__PURE__ */ new Set(),
+			items: /* @__PURE__ */ new Map(),
+			names: /* @__PURE__ */ new Set([...names, ...body.declaredAt.keys()])
+		};
+		for (const statement of statements) checkSnippet({
+			at: statement.at,
+			code: statement.code,
+			kind: "statement",
+			line: statement.line,
+			place: {
+				nested: false,
+				type: "statement"
+			}
+		}, body, scope);
+		const reorder = body.late.length > 0 ? reorderFix(statements) : void 0;
+		for (const entry of body.late) report(entry.place, "use_before_declare", entry.message, reorder);
+		walk(children, body, scope);
+		reportMissing(body);
+		const [first] = body.early;
+		if (first !== void 0) {
+			const quoted = body.early.map((entry) => `"${entry.name}"`);
+			const listed = quoted.length > 4 ? `${quoted.slice(0, 3).join(", ")} and ${quoted.length - 3} more` : quoted.join(", ");
+			const from = Math.min(...body.early.map((entry) => entry.declared));
+			const subject = quoted.length === 1 ? `${listed} is used above its {@body} declaration on line ${from}` : `${listed} are used above their {@body} declarations, the first on line ${from}`;
+			report(first.place, "use_before_declare", `${subject}. Declare state, queries and values at the top, above the markup that uses them: the page renders while it streams in, and until a declaration arrives its name is undefined`);
+		}
+	};
+	/**
+	* Reports the names `body` reads and never declares. A page that declares
+	* fewer names than it misses, at least `MISSING_AT_ONCE` of them, was
+	* written as markup alone: it gets one diagnostic that lists them all,
+	* rather than one per name and snippet. Browser globals and names close
+	* to a declared one keep their own messages, which say more.
+	*/
+	const reportMissing = (body) => {
+		const grouped = [...new Set(body.missing.flatMap((entry) => entry.own ? [] : [entry.name]))];
+		const group = body.define === null && grouped.length >= MISSING_AT_ONCE && body.declaredAt.size < grouped.length;
+		const first = body.missing.find((entry) => !entry.own);
+		if (group && first !== void 0) report(first.place, "missing_declarations", `This page reads ${grouped.length} names it never declares: ${grouped.map((name) => `"${name}"`).join(", ")}. Declare state, queries and helpers in {@body} lines at the top, above the markup that uses them`);
+		for (const entry of body.missing) if (!group || entry.own) report(entry.place, "undefined_reference", entry.message, entry.fix);
+	};
+	const page = readBody(pageStatements, null, /* @__PURE__ */ new Set());
+	checkBody(pageStatements, tree, page, /* @__PURE__ */ new Set());
+	const pageNames = new Set(page.declaredAt.keys());
+	for (const def of defines) {
+		if (def.origin !== "doc") continue;
+		const body = readBody(def.statements, def.name, pageNames);
+		const props = new Set(def.props.map((prop) => prop.name));
+		const scope = {
+			inner: /* @__PURE__ */ new Set(),
+			items: /* @__PURE__ */ new Map(),
+			names: /* @__PURE__ */ new Set([...props, ...body.declaredAt.keys()])
+		};
+		for (const prop of def.props) if (prop.defaultValue?.kind === "expr") checkSnippet({
+			at: prop.defaultValue.at,
+			code: prop.defaultValue.code,
+			kind: "expression",
+			line: def.line,
+			place: {
+				attribute: prop.name,
+				tag: "define",
+				type: "attribute"
+			}
+		}, body, scope);
+		checkBody(def.statements, def.body, body, props);
+	}
+	return {
+		procedures: procedures.toSorted((a, b) => a.line - b.line),
+		reads
+	};
+}
+/**
+* An order for `{@body}` lines in which each runs after the lines whose names
+* it reads: a stable topological sort, which keeps the written order
+* wherever it can, as indexes into `statements`. Every read counts, a read
+* inside a callback too, since `rows.map(...)` calls it at once. Lines that
+* read a name in common keep their order, as one may change what the other
+* reads (`items.push(1)`), and so do lines with a hook, whose state slots go
+* by call order; a line that declares nothing stays where it is, with
+* nothing moving across it. Undefined when that leaves no order, or a line
+* cannot be read, or a name is declared twice.
+*/
+function statementOrder(statements) {
+	const facts = statements.flatMap((statement) => {
+		const fact = factsOf({
+			at: statement.at,
+			code: statement.code,
+			kind: "statement",
+			line: statement.line,
+			place: {
+				nested: false,
+				type: "statement"
+			}
+		});
+		return fact === null ? [] : [fact];
+	});
+	if (facts.length !== statements.length) return;
+	const declaredBy = /* @__PURE__ */ new Map();
+	const reads = [];
+	for (const [index, fact] of facts.entries()) {
+		for (const name of fact.declared) {
+			if (declaredBy.has(name)) return;
+			declaredBy.set(name, index);
+		}
+		reads.push(new Set(fact.references.map((reference) => reference.name).filter((name) => !KNOWN_GLOBALS.has(name))));
+	}
+	/** `after[i]`: the lines that must run before line `i`. */
+	const after = facts.map(() => /* @__PURE__ */ new Set());
+	for (const [index, names] of reads.entries()) for (const name of names) {
+		const by = declaredBy.get(name);
+		if (by !== void 0 && by !== index) after[index]?.add(by);
+	}
+	/** Whether lines `a` and `b`, in written order, must stay in it. */
+	const keepsOrder = (a, b) => {
+		const first = facts[a];
+		const second = facts[b];
+		if (first === void 0 || second === void 0) return true;
+		return first.declared.length === 0 || second.declared.length === 0 || first.hookCalls.length > 0 && second.hookCalls.length > 0 || [...reads[a] ?? []].some((name) => reads[b]?.has(name));
+	};
+	for (let b = 0; b < statements.length; b++) for (let a = 0; a < b; a++) if (keepsOrder(a, b)) after[b]?.add(a);
+	const placed = [];
+	const done = /* @__PURE__ */ new Set();
+	while (placed.length < statements.length) {
+		const next = after.findIndex((needs, index) => !done.has(index) && [...needs].every((need) => done.has(need)));
+		if (next === -1) return;
+		placed.push(next);
+		done.add(next);
+	}
+	return placed;
+}
+/**
+* Moves top-level `{@body}` lines into `statementOrder`, each into the place
+* of another, so markup stays where it is. Undefined when there is no such
+* order or the lines are in it already.
+*/
+function reorderFix(statements) {
+	const edits = (statementOrder(statements) ?? []).flatMap((from, slot) => {
+		const moved = statements[from];
+		const place = statements[slot];
+		return from === slot || moved === void 0 || place === void 0 ? [] : [{
+			end: place.end,
+			start: place.start,
+			text: `{@body ${moved.code}}`
+		}];
+	});
+	return edits.length === 0 ? void 0 : {
+		edits,
+		title: "Reorder the {@body} lines so each comes after the lines it reads"
+	};
+}
+/** How many undeclared names make a page that declares fewer than that one problem. */
+const MISSING_AT_ONCE = 2;
+function undefinedMessage(snippet, name, names) {
+	if (BROWSER_GLOBALS.has(name)) return `${quoteCode(snippet)} reads "${name}", which doesn't exist in a spec: there are no browser globals. Keep values in state, and read data with useQuery`;
+	const near = nearest(name, names, 1)[0];
+	const hint = near === void 0 ? "" : ` Did you mean "${near}"?`;
+	if (snippet.place.type === "text") return `${quoteCode(snippet)} reads "${name}", which isn't defined.${hint} Braces always run code, even inside backticks: declare "${name}" in a {@body} line, or write a formula without braces, e.g. x^(n) instead of x^{n}`;
+	return `${quoteCode(snippet)} reads "${name}", which isn't defined.${hint} Declare it in a {@body} line`;
+}
+/**
+* The message for a name that `{@body}` lines inside blocks declare: one
+* line that can move above its block, one that can't and why, or several.
+*/
+function blockMessage(snippet, name, hoists) {
+	const [first] = hoists;
+	if (first === void 0 || hoists.length > 1) {
+		const lines = hoists.map((hoist) => hoist.line).join(" and ");
+		return `${quoteCode(snippet)} reads "${name}", which lines ${lines} declare inside blocks, where only those blocks see it. Declare it once, in a {@body} line above them`;
+	}
+	const where = `which line ${first.line} declares inside <${first.block}>, where only that block sees it`;
+	return first.reason === null ? `${quoteCode(snippet)} reads "${name}", ${where}. Declare it in a {@body} line above the block` : `${quoteCode(snippet)} reads "${name}", ${where}, and it can't move out by itself, as it ${first.reason}. Declare it above the block, or read it inside`;
+}
+function mutateMessage(written) {
+	return `\`${written}(…)\` runs while the page renders, where it does nothing. Call it from an event handler, e.g. \`onClick={() => ${written}(…)}\``;
+}
+/** The rewrite of a status flag at `[start, end)` to the comparison it stands for. */
+function statusFix(object, status, start, end) {
+	const text = `${object}.status === "${status}"`;
+	return {
+		edits: [{
+			end,
+			start,
+			text: `(${text})`
+		}],
+		title: `Replace with \`${text}\``
+	};
+}
+function handleFieldMessage(hook, object, property, called) {
+	const written = `\`${object}.${property}${called ? "()" : ""}\``;
+	const instead = HANDLE_FIELDS[hook].instead.get(property);
+	if (instead !== void 0) return `${written} does not exist: ${instead.replaceAll("NAME", object)}`;
+	return hook === "useQuery" ? `${written} is undefined: \`${object}\` is a useQuery handle, ${HANDLE_FIELDS.useQuery.written}. Read \`${object}.data.${property}\` once \`${object}.status === "success"\`` : `${written} is undefined: \`${object}\` is a useMutation handle, ${HANDLE_FIELDS.useMutation.written}`;
+}
+//#endregion
+export { ELEMENT, KNOWN_GLOBALS, checkCode, statementOrder };