@jigs.design/compiler 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @jigs.design/compiler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Today's Pickle compiler: the parser, the checker against a catalog, the code generator, recipe libraries, and the SEARCH/REPLACE edit helpers. `@jigs.design/server` and `@jigs.design/prompt` use it. You import it for tooling, not to run a session.
+
+It parses embedded code with [acorn](https://github.com/acornjs/acorn) in strict mode, the mode programs run in, and checks names and the JavaScript subset. It has no built-in catalog. Every caller passes one, and its prop kinds are boolean, enum, handler, number, rows and string.
+
+The [language RFC](../../docs/language-v2/rfc.md) plans its next changes. It evolves in place, behind the same server API.
+
+## Exports
+
+| Export                                                     | What it is                                                       |
+| ---------------------------------------------------------- | ---------------------------------------------------------------- |
+| `parsePickle`                                              | Source to a document tree. Tolerates a prefix cut off mid-stream |
+| `compilePickle`                                            | Checks a document against a catalog and generates its program    |
+| `compileLibrary`                                           | Compiles recipes into a library a document can use               |
+| `recipeSignature`                                          | A recipe's props and slot, as the prompt lists them              |
+| `isEditReply`, `parseEdits`, `applyEdits`, `SEARCH_MARKER` | Recognise and apply a reply made of SEARCH/REPLACE edits         |
+| `CompileCatalog`, `ComponentSpec`, `PropSpec`              | What the compiler checks against                                 |
+
+## Source
+
+- `src/parse.ts`, `src/ast.ts`: the parser and its tree.
+- `src/compile.ts`: checking, recipes and diagnostics.
+- `src/script.ts`, `src/check-code.ts`: embedded code read with acorn, and the checks on it.
+- `src/suggest.ts`: the nearest name, for "did you mean".
+- `src/codegen.ts`: the JavaScript the sandbox runs.
+- `src/patch.ts`: SEARCH/REPLACE edits.
+- `src/spec.ts`, `src/signature.ts`: catalog specs and recipe signatures.
+- `src/test-catalog.ts`: the catalog the tests run against.

package/dist/ast.d.ts

@@ -0,0 +1,78 @@
+import { OffsetMap, Range } from "./offsets.js";
+//#region src/ast.d.ts
+export type Literal = boolean | number | string;
+export type PropValue =
+/** `at` places the code in the source; a value the compiler made up has none. */
+{
+  at?: OffsetMap;
+  code: string;
+  kind: "expr";
+} | {
+  kind: "literal";
+  value: Literal;
+};
+export interface PropNode {
+  /** Just past the attribute in the source; a prop the parser made up has none. */
+  end?: number;
+  name: string;
+  /**
+   * The attribute was written without `=`. Catalog tags read that as `true`;
+   * `<define>` reads it as a required prop with no default.
+   */
+  shorthand?: boolean;
+  /** The attribute's first character in the source. */
+  start?: number;
+  value: PropValue;
+  /** The attribute as the source wrote it, such as `gap="3"`, for messages. */
+  written?: string;
+}
+/** `start` and `end` cover the opening tag, or the Markdown that made the element. */
+export interface ElementNode extends Range {
+  children: Array<PickleNode>;
+  /** Just past its closing tag, or its own end when self-closing; absent when the parser closed it. */
+  closeEnd?: number;
+  line: number;
+  name: string;
+  props: Array<PropNode>;
+  type: "element";
+}
+export interface TextNode {
+  type: "text";
+  value: string;
+}
+export interface ExprNode {
+  at: OffsetMap;
+  code: string;
+  line: number;
+  type: "expr";
+}
+/**
+ * A `{@body ...}` line: JavaScript run before rendering (state, derived
+ * values). `start` and `end` cover it from `{@body` to its closing `}`.
+ */
+export interface Statement extends Range {
+  at: OffsetMap;
+  code: string;
+  line: number;
+}
+/** A `{@body ...}` line inside a tag; it belongs to the nearest enclosing `<each>`. */
+interface StatementNode extends Statement {
+  type: "statement";
+}
+export type PickleNode = ElementNode | ExprNode | StatementNode | TextNode;
+/** Something the parser fixed or dropped so a partial document still renders. */
+export interface Repair {
+  end?: number;
+  line: number;
+  message: string;
+  start?: number;
+}
+export interface PickleDocument {
+  children: Array<PickleNode>;
+  /** Text that could not be read even though the input is complete there. */
+  errors: Array<Repair>;
+  repairs: Array<Repair>;
+  statements: Array<Statement>;
+}
+//#endregion
+export {};

package/dist/block-hoist.js

@@ -0,0 +1,237 @@
+import { analyze } from "./script.js";
+import { statementProblem } from "./codegen.js";
+//#region src/block-hoist.ts
+/** Tags whose `{@body}` lines are their own, not the enclosing body's. */
+const OWN_SCOPE = /* @__PURE__ */ new Set([
+	"define",
+	"each",
+	"if"
+]);
+/** `{@body}` lines directly in `nodes` and in tags that share the scope. */
+function ownStatements(nodes) {
+	return nodes.flatMap((node) => {
+		if (node.type === "statement") return [node];
+		return node.type === "element" && !OWN_SCOPE.has(node.name) ? ownStatements(node.children) : [];
+	});
+}
+function factsOf(statement) {
+	if (statementProblem(statement.code) !== null) return null;
+	const analysis = analyze(statement.code, "statement");
+	return analysis.ok ? analysis : null;
+}
+function literalProp(node, name) {
+	const prop = node.props.find((entry) => entry.name === name);
+	return prop?.value.kind === "literal" ? String(prop.value.value) : null;
+}
+function codeProp(node, name) {
+	const prop = node.props.find((entry) => entry.name === name);
+	if (prop === void 0) return null;
+	return prop.value.kind === "expr" ? prop.value.code : JSON.stringify(prop.value.value);
+}
+/** A line's declarations with their line, for `Body.names` and `Block.locals`. */
+function declarations(statements) {
+	return statements.flatMap((statement) => (factsOf(statement)?.declared ?? []).map((name) => ({
+		line: statement.line,
+		name
+	})));
+}
+function blockOf(node, statements) {
+	const locals = declarations(statements);
+	if (node.name === "if") return {
+		items: [],
+		kind: "if",
+		locals,
+		start: node.start,
+		test: codeProp(node, "test")
+	};
+	return {
+		items: [literalProp(node, "as") ?? "item", literalProp(node, "index")].filter((item) => item !== null),
+		kind: "each",
+		locals,
+		start: node.start,
+		test: null
+	};
+}
+/** Every candidate line in `nodes`, which belong to `body`, inside the `blocks` given. */
+function collect(nodes, body, blocks, into) {
+	for (const node of nodes) {
+		if (node.type !== "element" || node.name === "define") continue;
+		if (node.name !== "each" && node.name !== "if") {
+			collect(node.children, body, blocks, into);
+			continue;
+		}
+		const statements = ownStatements(node.children);
+		const inner = [...blocks, blockOf(node, statements)];
+		for (const statement of statements) {
+			const facts = factsOf(statement);
+			if (facts !== null && facts.declared.length > 0) into.push({
+				blocks: inner,
+				body,
+				facts,
+				statement
+			});
+		}
+		collect(node.children, body, inner, into);
+	}
+}
+/** `const name = value` or `let { a, b } = value`: what an `<if>` test can guard. */
+const SIMPLE_DECLARATION = /^(const|let)\s+([A-Za-z_$][\w$]*|\{[^={}]*\}|\[[^=[\]]*\])\s*=\s*([^=][\s\S]*)$/;
+/** The line's code, moved above its blocks: guarded by their `<if>` tests when it has any and is not a hook. */
+function movedCode(candidate, hook) {
+	const tests = candidate.blocks.flatMap((block) => block.test === null ? [] : [block.test]);
+	if (hook || tests.length === 0) return { code: candidate.statement.code };
+	const match = SIMPLE_DECLARATION.exec(candidate.statement.code);
+	if (match === null || candidate.facts.declared.length === 0) return { reason: "is not a single `const name = value` line the <if> test could guard" };
+	const [, keyword, pattern, value] = match;
+	const fallback = pattern?.startsWith("{") ? "{}" : pattern?.startsWith("[") ? "[]" : "undefined";
+	const guard = tests.map((test) => `(${test.trim()})`).join(" && ");
+	const trimmed = value?.trim() ?? "";
+	return { code: `${keyword} ${pattern} = ${guard} ? (${trimmed.includes("//") ? `${trimmed}\n` : trimmed}) : ${fallback}` };
+}
+/** The free names `code`, an expression, reads; null when it can't be read. */
+function readsOf(code) {
+	const analysis = analyze(code, "expression");
+	return analysis.ok ? analysis.references.map((reference) => reference.name) : null;
+}
+/**
+* Why `candidate` can't move out of its blocks, or null when it can: it
+* reads a loop item, a name another line of a block declares, or an
+* `<if>` test it would be guarded by does; it declares a name the body or
+* another block line declares too; or it keeps per-item state.
+*/
+function blocked(candidate, hook, elsewhere) {
+	for (const name of candidate.facts.declared) {
+		const outer = candidate.body.names.get(name);
+		if (outer !== void 0) return `declares "${name}", which line ${outer} declares outside the block too`;
+		const twin = (elsewhere.get(name) ?? []).find((other) => other.statement.start !== candidate.statement.start);
+		if (twin !== void 0) return `declares "${name}", which line ${twin.statement.line} declares inside a block too`;
+	}
+	const items = /* @__PURE__ */ new Map();
+	const locals = /* @__PURE__ */ new Map();
+	for (const block of candidate.blocks) {
+		for (const [index, item] of block.items.entries()) items.set(item, index === 0 ? "item" : "index");
+		for (const local of block.locals) if (local.line !== candidate.statement.line) locals.set(local.name, local.line);
+	}
+	const bound = (names) => {
+		for (const name of names) {
+			const item = items.get(name);
+			if (item !== void 0) return `"${name}", the loop's ${item}`;
+			const local = locals.get(name);
+			if (local !== void 0) return `"${name}", which line ${local} declares inside the block`;
+		}
+		return null;
+	};
+	const own = bound(candidate.facts.references.map((reference) => reference.name));
+	if (own !== null) return `reads ${own}`;
+	if (!hook) for (const block of candidate.blocks) {
+		if (block.test === null) continue;
+		const names = readsOf(block.test);
+		if (names === null) return "sits in an <if> whose test can't be read";
+		const read = bound(names);
+		if (read !== null) return `sits in an <if> whose test reads ${read}`;
+	}
+	return null;
+}
+/** Where a line moving out of `blocks` goes: after the last body line above them, or the body's start. */
+function insertion(body, blocks) {
+	const top = blocks[0]?.start ?? 0;
+	const above = body.statements.findLast((statement) => statement.end <= top);
+	return above === void 0 ? body.origin : {
+		offset: above.end,
+		text: (line) => `\n${line}`
+	};
+}
+function hoistOf(candidate, elsewhere) {
+	const { blocks, facts, statement } = candidate;
+	const base = {
+		block: blocks.at(-1)?.kind ?? "if",
+		declared: facts.declared,
+		line: statement.line,
+		start: statement.start
+	};
+	const hook = facts.hookCalls.length > 0;
+	const reason = blocked(candidate, hook, elsewhere);
+	if (reason !== null) return {
+		...base,
+		fix: null,
+		reason
+	};
+	if (facts.hookCalls.some((call) => call.hook === "useState") && blocks.some((block) => block.kind === "each")) return {
+		...base,
+		fix: null,
+		reason: null
+	};
+	const moved = movedCode(candidate, hook);
+	if ("reason" in moved) return {
+		...base,
+		fix: null,
+		reason: moved.reason
+	};
+	const [outer] = blocks;
+	const place = insertion(candidate.body, blocks);
+	const guarded = !hook && blocks.some((block) => block.test !== null);
+	return {
+		...base,
+		fix: {
+			edits: [{
+				end: statement.end,
+				start: statement.start,
+				text: ""
+			}, {
+				end: place.offset,
+				start: place.offset,
+				text: place.text(`{@body ${moved.code}}`)
+			}],
+			title: `Move the {@body} line on line ${statement.line} above the <${outer?.kind ?? "if"}>${guarded ? ", guarded by its test" : ""}`
+		},
+		reason: null
+	};
+}
+/**
+* The `{@body}` lines inside `<if>` and `<each>` blocks of the page and
+* its `<define>`s that declare a name, each with the fix that moves it
+* above its outermost block, or the reason it can't move: see `BlockHoist`.
+*/
+function blockHoists(document) {
+	const candidates = [];
+	const pageStatements = [...document.statements, ...ownStatements(document.children)].toSorted((a, b) => a.start - b.start);
+	const page = {
+		names: new Map(declarations(pageStatements).map((entry) => [entry.name, entry.line])),
+		origin: {
+			offset: 0,
+			text: (line) => `${line}\n`
+		},
+		statements: pageStatements
+	};
+	collect(document.children, page, [], candidates);
+	for (const node of document.children) {
+		if (node.type !== "element" || node.name !== "define") continue;
+		const statements = ownStatements(node.children);
+		const names = new Map(node.props.filter((prop) => prop.name !== "name").map((prop) => [prop.name, node.line]));
+		for (const entry of declarations(statements)) names.set(entry.name, entry.line);
+		const define = {
+			names,
+			origin: {
+				offset: node.end,
+				text: (line) => `\n${line}`
+			},
+			statements
+		};
+		collect(node.children, define, [], candidates);
+	}
+	const elsewhere = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) for (const name of candidate.facts.declared) elsewhere.set(name, [...elsewhere.get(name) ?? [], candidate]);
+	const byName = /* @__PURE__ */ new Map();
+	const byStart = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const hoist = hoistOf(candidate, elsewhere);
+		byStart.set(hoist.start, hoist);
+		for (const name of hoist.declared) byName.set(name, [...byName.get(name) ?? [], hoist]);
+	}
+	return {
+		byName,
+		byStart
+	};
+}
+//#endregion
+export { blockHoists };

package/dist/check-code.d.ts

@@ -0,0 +1,46 @@
+import { Diagnostic } from "./compile.js";
+import { ProcedureCall } from "./script.js";
+//#region src/check-code.d.ts
+/** A procedure call in the document, by line, for the server to check against its host. */
+export interface ProcedureUse extends Omit<ProcedureCall, "end" | "offset"> {
+  /** Just past the call, as an offset into the source, when the code has a place there. */
+  end?: number;
+  line: number;
+  /** The call's first character, as an offset into the source. */
+  start?: number;
+}
+/** Where a diagnostic points: a line, and a range in the source when the code has one. */
+type Place = Pick<Diagnostic, "end" | "line" | "start">;
+/** A step of `DataRead.path` into each element of an array, as an `<each>` item takes. */
+export declare const ELEMENT = "[]";
+/**
+ * Fields read from a procedure's data, as `orders.data.total` or, through
+ * `const { data } = useQuery("orders")`, `data.total`, for the server to
+ * check against the procedure's output schema. A read of an `<each>` item,
+ * as `order.total` in `<each of={orders.data} as="order">`, starts with the
+ * list's path and an `ELEMENT` step.
+ */
+export interface DataRead {
+  /** The read as written up to the data, such as `orders.data`, for messages. */
+  data: string;
+  /**
+   * For a read of an `<each>` item: its name, its list as written, such as
+   * `orders.data`, and how many steps of `path` lead to the item.
+   */
+  item?: {
+    list: string;
+    name: string;
+    steps: number;
+  };
+  /** The fields read from the data, in order, as far as they are written out. */
+  path: Array<string>;
+  /**
+   * Where the read through each field of `path` is: `places[i]` ends at
+   * `path[i]`. Null for the steps that lead to an `<each>` item, which the
+   * read in its `of` checks.
+   */
+  places: Array<Place | null>;
+  procedure: string;
+}
+//#endregion
+export {};