@jigs.design/compiler 0.0.0-stage → 0.1.0

package/dist/codegen.d.ts

@@ -0,0 +1,8 @@
+//#region src/codegen.d.ts
+/** What the sandbox runs: a JavaScript program plus the text it displays. */
+export interface ProgramOutput {
+  code: string;
+  /** Static text, kept out of `code` so growing text doesn't change the program. */
+  constants: Readonly<Record<string, string>>;
+}
+//#endregion

package/dist/codegen.js

@@ -0,0 +1,219 @@
+import { analyze, isValidBinding } from "./script.js";
+//#region src/codegen.ts
+/**
+* Adds `{ key }` to single-argument `useState(...)` and `useMutation(...)`
+* calls, bare or with `Pickle.`, named after the declaration, so state and a
+* mutation's status survive recompiles and reordering. The calls come from the
+* parser, so text that only looks like one, in a string or a comment, is left
+* alone.
+*/
+function injectStateKeys(code, baseKey) {
+	const analysis = analyze(code, "statement");
+	if (!analysis.ok) return code;
+	const counts = /* @__PURE__ */ new Map();
+	const inserts = [];
+	for (const call of analysis.keyed.toSorted((a, b) => a.start - b.start)) {
+		const calls = counts.get(call.hook) ?? 0;
+		counts.set(call.hook, calls + 1);
+		if (call.arguments > 1) continue;
+		const key = JSON.stringify(calls === 0 ? baseKey : `${baseKey}#${calls}`);
+		inserts.push({
+			at: call.insertAt,
+			text: `${call.arguments === 0 ? "undefined" : ""}, { key: ${key} }`
+		});
+	}
+	let result = "";
+	let cursor = 0;
+	for (const insert of inserts.toSorted((a, b) => a.at - b.at)) {
+		result += code.slice(cursor, insert.at) + insert.text;
+		cursor = insert.at;
+	}
+	return result + code.slice(cursor);
+}
+/** Names a spec may not declare: the runtime's own bindings. */
+const RESERVED = /* @__PURE__ */ new Set([
+	"Pickle",
+	"useMutation",
+	"useQuery",
+	"useState"
+]);
+const isReserved = (name) => RESERVED.has(name) || name.startsWith("__pickle");
+/** Whether `name` can be bound as a loop variable without hiding the runtime's own names. */
+function isBindingName(name) {
+	return !isReserved(name) && isValidBinding(name);
+}
+/** Why a `{@body}` line is removed, or null when it is kept. */
+function statementProblem(code) {
+	const analysis = analyze(code, "statement");
+	if (!analysis.ok) return analysis.message.includes("'return' outside of function") ? "`return` can't be used in a {@body} line: the page always renders. To hide markup, wrap it in <if test={…}>. The line was removed" : `{@body} line is not valid JavaScript (${analysis.message}); it was removed`;
+	const reserved = analysis.declared.find(isReserved);
+	return reserved === void 0 ? null : `{@body} line declares "${reserved}", a name Pickle uses itself; rename it. The line was removed`;
+}
+/** Why `code` can't be spliced in as an expression, or null when it can. */
+function expressionProblem(code) {
+	const analysis = analyze(code, "expression");
+	return analysis.ok ? null : analysis.message;
+}
+const fragment = (children) => `__pickle.jsx(${[
+	"__pickle.Fragment",
+	"null",
+	...children
+].join(", ")})`;
+const documentLines = { line: String };
+const libraryLines = { line: () => "__pickleAt" };
+function generateProgram(statements, tree, defines = []) {
+	const diagnostics = [];
+	const constants = {};
+	let nextConstant = 0;
+	const invalid = (code, line, message) => {
+		diagnostics.push({
+			code,
+			line,
+			message,
+			severity: "warning"
+		});
+	};
+	/** Statement lines, run in order, plus a `let` for every name they declare. */
+	const genStatements = (list, lines) => {
+		const declared = /* @__PURE__ */ new Set();
+		const body = [];
+		for (const statement of list) {
+			const problem = statementProblem(statement.code);
+			const analysis = analyze(statement.code, "statement");
+			if (problem !== null || !analysis.ok) {
+				invalid("invalid_statement", statement.line, problem ?? "");
+				continue;
+			}
+			const names = analysis.declared;
+			for (const name of names) declared.add(name);
+			const code = injectStateKeys(statement.code, names[0] ?? `statement:${statement.line}`);
+			const run = names.length === 0 ? `(() => {\n${code}\n})();` : `({ ${names.join(", ")} } = (() => {\n${code}\nreturn { ${names.join(", ")} };\n})());`;
+			body.push(`try {\n${run}\n} catch (error) { Pickle.reportError(${lines.line(statement.line)}, error); }`);
+		}
+		return declared.size > 0 ? [`let ${[...declared].join(", ")};`, ...body] : body;
+	};
+	const genPropEntries = (entries, line, label) => {
+		let dynamic = false;
+		const props = [];
+		for (const [name, value] of Object.entries(entries)) {
+			if (value.kind === "literal") {
+				props.push(`${JSON.stringify(name)}: ${JSON.stringify(value.value)}`);
+				continue;
+			}
+			const problem = expressionProblem(value.code);
+			if (problem === null) {
+				dynamic = true;
+				props.push(`${JSON.stringify(name)}: (${value.code}\n)`);
+			} else invalid("invalid_expression", line, `<${label} ${name}={${value.code}}> is not a valid expression (${problem}); the prop was removed`);
+		}
+		return {
+			dynamic,
+			props
+		};
+	};
+	const genChildren = (nodes, lines) => nodes.map((child) => genNode(child, lines)).filter((child) => child !== null);
+	const genNode = (node, lines) => {
+		switch (node.type) {
+			case "each": {
+				const problem = expressionProblem(node.items);
+				if (problem !== null) {
+					invalid("invalid_expression", node.line, `<each of={${node.items}}> is not a valid expression (${problem}); it was removed`);
+					return null;
+				}
+				const params = [node.item, ...node.index === null ? [] : [node.index]];
+				const iteration = [...genStatements(node.statements, lines), `return ${fragment(genChildren(node.children, lines))};`].join("\n");
+				const at = lines.line(node.line);
+				return `__pickleSafe(() => __pickle.each((${node.items}\n), (${params.join(", ")}) => {\n${iteration}\n}, ${at}), null, ${at})`;
+			}
+			case "if": {
+				const problem = expressionProblem(node.test);
+				if (problem !== null) {
+					invalid("invalid_expression", node.line, `<if test={${node.test}}> is not a valid expression (${problem}); it was removed`);
+					return null;
+				}
+				const shown = node.statements.length === 0 ? fragment(genChildren(node.children, lines)) : `(() => {\n${[...genStatements(node.statements, lines), `return ${fragment(genChildren(node.children, lines))};`].join("\n")}\n})()`;
+				const at = lines.line(node.line);
+				return `__pickleSafe(() => (${node.test}\n) ? ${shown} : null, null, ${at})`;
+			}
+			case "text": {
+				const key = String(nextConstant++);
+				constants[key] = node.value;
+				return `__pickleConstants[${JSON.stringify(key)}]`;
+			}
+			case "expr": {
+				const problem = expressionProblem(node.code);
+				if (problem !== null) {
+					invalid("invalid_expression", node.line, `{${node.code}} is not a valid expression (${problem}); it was removed`);
+					return null;
+				}
+				return `__pickleSafe(() => (${node.code}\n), null, ${lines.line(node.line)})`;
+			}
+			case "element": {
+				const propEntries = genPropEntries(node.props, node.line, node.component);
+				const children = genChildren(node.children, lines);
+				const element = `__pickle.jsx(${[
+					JSON.stringify(node.component),
+					`{ ${propEntries.props.join(", ")} }`,
+					...children
+				].join(", ")})`;
+				return propEntries.dynamic ? `__pickleSafe(() => ${element}, null, ${lines.line(node.line)})` : element;
+			}
+			case "slot": return "__pickleChildren";
+			case "call": {
+				const at = lines.line(node.line);
+				const entries = node.key === null ? node.props : {
+					...node.props,
+					key: node.key
+				};
+				const props = genPropEntries(entries, node.line, node.name).props;
+				const childExprs = genChildren(node.children, lines);
+				const children = childExprs.length === 0 ? "null" : childExprs.length === 1 ? childExprs[0] ?? "null" : fragment(childExprs);
+				const library = node.origin === "library" ? ", true" : "";
+				return `__pickleSafe(() => __pickle.call(__pickleDef_${node.name}, { ${props.join(", ")} }, ${children}, ${at}, ${node.ordinal}, ${JSON.stringify(node.name)}${library}), null, ${at})`;
+			}
+		}
+	};
+	const genBinding = (prop, lines, line) => {
+		const read = `__pickleProps.${prop.name}`;
+		if (prop.required || prop.defaultValue === null) return `const ${prop.name} = ${read};`;
+		if (prop.defaultValue.kind === "literal") return `const ${prop.name} = ${read} !== undefined ? ${read} : ${JSON.stringify(prop.defaultValue.value)};`;
+		const problem = expressionProblem(prop.defaultValue.code);
+		if (problem !== null) {
+			invalid("invalid_expression", line, `<define ${prop.name}={${prop.defaultValue.code}}> is not a valid expression (${problem}); the default was removed`);
+			return `const ${prop.name} = ${read};`;
+		}
+		return `const ${prop.name} = ${read} !== undefined ? ${read} : __pickleSafe(() => (${prop.defaultValue.code}\n), undefined, ${lines.line(line)});`;
+	};
+	const genDefine = (def) => {
+		const lines = def.origin === "library" ? libraryLines : documentLines;
+		const bindings = def.props.map((prop) => genBinding(prop, lines, def.line));
+		const view = fragment(genChildren(def.body, lines));
+		const bodyStatements = genStatements(def.statements, lines);
+		const body = bodyStatements.length === 0 ? `return ${view};` : `return (() => {\n${bodyStatements.join("\n")}\nreturn ${view};\n})();`;
+		return `function __pickleDef_${def.name}(__pickleProps, __pickleChildren, __pickleAt) {\n${[...bindings, body].join("\n")}\n}`;
+	};
+	const functions = defines.map((def) => genDefine(def));
+	const children = genChildren(tree, documentLines);
+	return {
+		diagnostics,
+		output: {
+			code: [
+				"\"use strict\";",
+				"const __pickleConstants = Pickle.useConstants();",
+				"const useState = Pickle.useState, useQuery = Pickle.useQuery, useMutation = Pickle.useMutation;",
+				...functions,
+				"Pickle.render(__pickle.jsx(() => {",
+				...genStatements(statements, documentLines),
+				`return __pickle.jsx(${[
+					"__pickle.Fragment",
+					"null",
+					...children
+				].join(",\n")});`,
+				"}, { key: \"body\" }));"
+			].filter((line) => line !== "").join("\n"),
+			constants
+		}
+	};
+}
+//#endregion
+export { generateProgram, injectStateKeys, isBindingName, statementProblem };

package/dist/compile.d.ts

@@ -0,0 +1,177 @@
+import { OffsetMap } from "./offsets.js";
+import { ExprNode, PropValue, Statement, TextNode } from "./ast.js";
+import { CompileCatalog } from "./spec.js";
+import { ProgramOutput } from "./codegen.js";
+import { DataRead, ProcedureUse } from "./check-code.js";
+//#region src/compile.d.ts
+type DiagnosticCode = "coerced" | "handle_field" | "hook_placement" | "invalid_control" | "invalid_define" | "invalid_expression" | "invalid_literal" | "invalid_statement" | "missing_declarations" | "missing_prop" | "mutate_in_render" | "outer_reference" | "query_options" | "repaired" | "shadows_library" | "unclosed" | "undefined_compare" | "undefined_reference" | "unexpected_children" | "unknown_component" | "unknown_prop" | "unstable_input" | "unsupported_syntax" | "use_before_declare";
+/** Replace `[start, end)` of the source with `text`. */
+interface FixEdit {
+  end: number;
+  start: number;
+  text: string;
+}
+/**
+ * A rewrite that makes a diagnostic's problem go away. The compiler attaches
+ * one only when there is a single way to write it, and applies it itself:
+ * see `compilePickle`.
+ */
+export interface Fix {
+  edits: Array<FixEdit>;
+  /** What the fix does, such as "Replace with `q.status === "pending"`". */
+  title: string;
+}
+export interface Diagnostic {
+  code: DiagnosticCode;
+  /** The 1-based column of `start` on its line. */
+  column?: number;
+  /** Just past what the diagnostic is about, as an offset into the source. */
+  end?: number;
+  fix?: Fix;
+  /** The line of `start` when there is one. */
+  line: number;
+  message: string;
+  severity: "info" | "warning";
+  /** The first character of what the diagnostic is about, as an offset into the source. */
+  start?: number;
+}
+interface RenderElement {
+  children: Array<RenderNode>;
+  component: string;
+  line: number;
+  props: Record<string, PropValue>;
+  type: "element";
+}
+/** `<each of={items} as="item" index="i">`: children repeated per item. */
+interface RenderEach {
+  children: Array<RenderNode>;
+  index: string | null;
+  item: string;
+  /** JavaScript expression for the list (or a count). */
+  items: string;
+  /** Places `items` in the source; a literal list has no place. */
+  itemsAt: OffsetMap | undefined;
+  line: number;
+  /** `{@body}` lines inside the block, run at the start of every iteration. */
+  statements: Array<Statement>;
+  type: "each";
+}
+/** `<if test={condition}>`: children shown only when the condition is truthy. */
+interface RenderIf {
+  children: Array<RenderNode>;
+  line: number;
+  /** `{@body}` lines inside the block, run only when the test passes. */
+  statements: Array<Statement>;
+  test: string;
+  /** Places `test` in the source; a literal test has no place. */
+  testAt: OffsetMap | undefined;
+  type: "if";
+}
+/** `<statCard ...>`: one call to a document-local or library component. */
+interface RenderCall {
+  children: Array<RenderNode>;
+  /** Instance identity. Stripped before the body runs; not a define prop. */
+  key: PropValue | null;
+  line: number;
+  name: string;
+  /** 0-based source-order index of this name in the enclosing body. */
+  ordinal: number;
+  origin: "doc" | "library";
+  props: Record<string, PropValue>;
+  type: "call";
+}
+/** `<slot/>` inside a `<define>`: where the instance's children are inserted. */
+interface RenderSlot {
+  line: number;
+  type: "slot";
+}
+export type RenderNode = ExprNode | RenderCall | RenderEach | RenderElement | RenderIf | RenderSlot | TextNode;
+type PropKind = "boolean" | "number" | "string";
+/** A prop on a `<define>` signature. */
+export interface DefineProp {
+  defaultValue: PropValue | null;
+  kind: PropKind | null;
+  name: string;
+  required: boolean;
+}
+/** A component function the program can call. `body` sees its props and its own state. */
+export interface CompiledDefine {
+  body: Array<RenderNode>;
+  hasSlot: boolean;
+  /** Still streaming in (the parser closed it), so its `<slot/>` may not have arrived yet. */
+  incomplete?: boolean;
+  line: number;
+  name: string;
+  origin: "doc" | "library";
+  /**
+   * The procedure calls in a library recipe's source, by its lines. Empty
+   * for a document's own define: those are on the document's result.
+   */
+  procedures: ReadonlyArray<ProcedureUse>;
+  props: Array<DefineProp>;
+  statements: Array<Statement>;
+}
+/** One component the document actually renders, and how often it is written. */
+interface DefineUse {
+  instances: number;
+  name: string;
+  origin: "doc" | "library";
+}
+/** Validated output: every element and literal prop is known to the catalog. */
+export interface Program {
+  defines: Array<DefineUse>;
+  statements: Array<Statement>;
+  tree: Array<RenderNode>;
+}
+/** A reusable component written in Pickle: source with exactly one `<define>`. */
+export interface Recipe {
+  name: string;
+  source: string;
+}
+/** Recipes compiled against one catalog, ready to use in documents. */
+export type Library = ReadonlyMap<string, CompiledDefine>;
+export interface CompileOptions {
+  /** The components a document may use. */
+  catalog: CompileCatalog;
+  /** Recipes in scope, from `compileLibrary` with the same catalog. */
+  library?: Library;
+}
+export interface CompileResult {
+  defines: ReadonlyArray<CompiledDefine>;
+  diagnostics: Array<Diagnostic>;
+  /** The recipes this document was compiled against. */
+  library: ReadonlyMap<string, CompiledDefine>;
+  output: ProgramOutput;
+  /**
+   * Every `useQuery`, `useMutation` and `useAction` call in the parsed
+   * code of the document and its defines, in line order: nothing in
+   * prose or in string literals. Recipes' calls are on the library's
+   * defines.
+   */
+  procedures: ReadonlyArray<ProcedureUse>;
+  program: Program;
+  /** Fields the document reads from procedures' data, for the server to check. */
+  reads: ReadonlyArray<DataRead>;
+  /**
+   * The source `program` was compiled from: the one passed in, or that
+   * source with the fixes applied. It names every tag the program draws.
+   */
+  source: string;
+}
+/**
+ * Compiles `recipes` against `catalog`, in order: a recipe may use the ones
+ * before it. Throws when a recipe has any diagnostic. Cached per catalog and
+ * recipe list.
+ */
+export declare function compileLibrary(recipes: ReadonlyArray<Recipe>, catalog: CompileCatalog): Library;
+/**
+ * Compiles a document. A warning that carries a fix is applied rather than
+ * sent to the model: the fixed source is compiled again, and when it has
+ * exactly the problems left that the fixes did not cover, its program is
+ * used and those warnings become `info`, as a quoted number on a number prop
+ * already is. Diagnostics, procedures and their spans stay those of `source`,
+ * which is what the model wrote and what the session keeps.
+ */
+export declare function compilePickle(source: string, options: CompileOptions): CompileResult;
+//#endregion
+export {};