@coldsmirk/abacus-core 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -209,11 +209,14 @@ function detectDev() {
 	return process.env ? process.env.NODE_ENV !== "production" : false;
 }
 //#endregion
-//#region src/condition/compile.ts
+//#region src/condition/subject.ts
 /**
-* A subject must be a plain identifier path (`amount`, `user.age`, `items[0]`).
-* It is emitted verbatim into ZEN source, so anything else is rejected to keep
-* the condition compiler from being an expression-injection sink.
+* Shared subject-path guard for the condition compilers. A subject / left-hand
+* path is emitted **verbatim** into ZEN source, so both {@link compileCondition}
+* (which writes that source) and {@link liftConditionTree} (which reads it back)
+* gate paths through this one predicate — a single definition of "what is a safe
+* field path" that cannot drift between the writer and the reader, which matters
+* because the guard is also the compiler's injection defense.
 */
 const SUBJECT_PATTERN = /^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*|\[\d+\])*$/i;
 const ZEN_RESERVED_WORDS = new Set([
@@ -225,9 +228,15 @@ const ZEN_RESERVED_WORDS = new Set([
 	"false",
 	"null"
 ]);
+/**
+* Whether `subject` is a plain identifier path safe to emit verbatim into ZEN
+* source: dotted/indexed segments only, none of which is a ZEN reserved word.
+*/
 function isIdentifierPath(subject) {
 	return SUBJECT_PATTERN.test(subject) && (subject.match(/[A-Z_$][\w$]*/gi) ?? []).every((segment) => !ZEN_RESERVED_WORDS.has(segment));
 }
+//#endregion
+//#region src/condition/compile.ts
 /**
 * Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
 * numbers / booleans / bigints are emitted verbatim; strings are quoted via
@@ -420,6 +429,508 @@ const CONDITION_OPERATORS = [
 	"is_empty",
 	"is_not_empty"
 ];
+const CONDITION_OPERATOR_ARITIES = {
+	eq: "scalar",
+	ne: "scalar",
+	gt: "scalar",
+	gte: "scalar",
+	lt: "scalar",
+	lte: "scalar",
+	contains: "scalar",
+	not_contains: "scalar",
+	starts_with: "scalar",
+	ends_with: "scalar",
+	in: "array",
+	not_in: "array",
+	is_empty: "none",
+	is_not_empty: "none"
+};
+/**
+* The arity of `operator`'s right-hand operand (see
+* {@link ConditionOperatorArity}). One definition site next to
+* {@link CONDITION_OPERATORS}, so the tree compiler's arity enforcement and a
+* condition editor's operand controls classify operators identically instead of
+* each keeping a drift-prone copy.
+*/
+function conditionOperatorArity(operator) {
+	return CONDITION_OPERATOR_ARITIES[operator];
+}
+//#endregion
+//#region src/condition/compile-tree.ts
+/**
+* Compile a condition tree to a canonical ZEN expression, or `""` when no rule in
+* the tree is compilable (see the module note for the drop semantics).
+*/
+function compileConditionTree(tree) {
+	const normalized = normalizeNode(tree);
+	return normalized === null ? "" : emitNode(normalized, true);
+}
+/**
+* Prune a node to its compilable core: drop rules {@link compileRule} rejects, drop
+* emptied groups, and collapse a single-surviving-item group to that item (so the
+* emitted shape carries no redundant parentheses). Returns `null` when nothing in
+* the node survives.
+*/
+function normalizeNode(node) {
+	if (node.kind === "rule") return compileRule(node) === null ? null : node;
+	const items = node.items.map((item) => normalizeNode(item)).filter((item) => item !== null);
+	if (items.length === 0) return null;
+	if (items.length === 1) return items[0];
+	return {
+		kind: "group",
+		op: node.op,
+		items
+	};
+}
+/**
+* Render a normalized node. A rule emits its lowered ZEN; a group joins its items
+* with ` and ` / ` or ` and, unless it is the top-level group, wraps them in
+* parentheses so the tree structure survives ZEN's operator precedence on lift.
+*/
+function emitNode(node, topLevel) {
+	if (node.kind === "rule") return compileRule(node);
+	const joined = node.items.map((item) => emitNode(item, false)).join(node.op === "and" ? " and " : " or ");
+	return topLevel ? joined : `(${joined})`;
+}
+/**
+* Lower a leaf rule to ZEN via {@link compileCondition}, or `null` for a rule the
+* compiler cannot represent. The rule's `right` must match its operator's arity —
+* a single scalar for the comparison / string operators, an array of scalars for
+* `in` / `not_in`, absent for the emptiness operators (the contract
+* {@link ConditionTreeValue} documents); an off-arity rule is non-compilable and
+* drops. Enforcing arity here, not just relying on `compileCondition`, is what
+* keeps every emitted expression liftable: the flat compiler's lax value handling
+* would happily serialize e.g. a missing `right` as a `null` literal, which is not
+* part of the canonical grammar.
+*/
+function compileRule(rule) {
+	if (!matchesOperatorArity(rule)) return null;
+	return compileCondition({
+		kind: "field",
+		subject: rule.left,
+		operator: rule.operator,
+		value: rule.right
+	});
+}
+function matchesOperatorArity(rule) {
+	switch (conditionOperatorArity(rule.operator)) {
+		case "scalar": return isConditionScalar(rule.right);
+		case "array": return isScalarArray(rule.right);
+		case "none": return rule.right === void 0;
+	}
+}
+function isConditionScalar(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isScalarArray(value) {
+	return isArray(value) && value.every((item) => isConditionScalar(item));
+}
+//#endregion
+//#region src/condition/lift-tree.ts
+const TWO_CHAR_PUNCTUATION = new Set([
+	"==",
+	"!=",
+	"<=",
+	">="
+]);
+const ONE_CHAR_PUNCTUATION = new Set([
+	"(",
+	")",
+	"[",
+	"]",
+	",",
+	".",
+	"<",
+	">",
+	"-"
+]);
+const IDENT_START = /[a-z_$]/i;
+const IDENT_PART = /[\w$]/;
+const DIGIT = /\d/;
+const NUMBER_PATTERN = /^\d+(?:\.\d+)?(?:e[+-]?\d+)?/i;
+const INTEGER_PATTERN = /^\d+$/;
+const COMPARISON_OPERATORS = {
+	"==": "eq",
+	"!=": "ne",
+	">": "gt",
+	">=": "gte",
+	"<": "lt",
+	"<=": "lte"
+};
+const CALL_OPERATORS = {
+	contains: "contains",
+	startsWith: "starts_with",
+	endsWith: "ends_with"
+};
+const MAX_GROUP_DEPTH = 64;
+/**
+* Lift a ZEN expression to a condition tree, or `null` when it is not in the
+* canonical form {@link compileConditionTree} produces (the consumer then keeps the
+* raw expression). Groups nested deeper than 64 parenthesized levels are refused as
+* non-canonical rather than risking parser-stack overflow on adversarial input. The
+* returned root is always a group.
+*/
+function liftConditionTree(expression) {
+	const tokens = tokenize(expression);
+	if (tokens === null || tokens.length === 0) return null;
+	let pos = 0;
+	function peek(offset = 0) {
+		return tokens[pos + offset];
+	}
+	function consumePunct(value) {
+		const token = peek();
+		if (token !== void 0 && token.kind === "punct" && token.value === value) {
+			pos += 1;
+			return true;
+		}
+		return false;
+	}
+	function consumeIdent(value) {
+		const token = peek();
+		if (token !== void 0 && token.kind === "ident" && token.value === value) {
+			pos += 1;
+			return true;
+		}
+		return false;
+	}
+	function tokensMatchAt(from, expected) {
+		for (const [index, element] of expected.entries()) {
+			const actual = tokens[from + index];
+			const want = element;
+			if (actual === void 0 || actual.kind !== want.kind || actual.value !== want.value) return false;
+		}
+		return true;
+	}
+	function parsePath() {
+		const read = readPath(tokens, pos);
+		if (read === null) return null;
+		pos = read.next;
+		return read.path;
+	}
+	function parseLiteral() {
+		const token = peek();
+		if (token === void 0) return null;
+		if (token.kind === "string") {
+			pos += 1;
+			return token.value;
+		}
+		if (token.kind === "number") {
+			pos += 1;
+			return Number(token.value);
+		}
+		if (token.kind === "ident") {
+			if (token.value === "true") {
+				pos += 1;
+				return true;
+			}
+			if (token.value === "false") {
+				pos += 1;
+				return false;
+			}
+			return null;
+		}
+		if (token.kind === "punct" && token.value === "-") {
+			const digits = peek(1);
+			if (digits === void 0 || digits.kind !== "number") return null;
+			pos += 2;
+			return -Number(digits.value);
+		}
+		return null;
+	}
+	function parseArray() {
+		if (!consumePunct("[")) return null;
+		if (isPunct(peek(), "]")) {
+			pos += 1;
+			return [];
+		}
+		const first = parseLiteral();
+		if (first === null) return null;
+		const items = [first];
+		while (isPunct(peek(), ",")) {
+			pos += 1;
+			const next = parseLiteral();
+			if (next === null) return null;
+			items.push(next);
+		}
+		return consumePunct("]") ? items : null;
+	}
+	function parseCall(operator) {
+		if (!consumePunct("(")) return null;
+		const left = parsePath();
+		if (left === null || !consumePunct(",")) return null;
+		const right = parseLiteral();
+		if (right === null || !consumePunct(")")) return null;
+		return {
+			kind: "rule",
+			left,
+			operator,
+			right
+		};
+	}
+	function parseNotIn() {
+		const left = parsePath();
+		if (left === null || !consumeIdent("in")) return null;
+		const right = parseArray();
+		if (right === null || !consumePunct(")")) return null;
+		return {
+			kind: "rule",
+			left,
+			operator: "not_in",
+			right
+		};
+	}
+	function tryEmptiness() {
+		const first = peek();
+		if (first === void 0) return null;
+		let operator;
+		let pathIndex;
+		if (first.kind === "ident" && first.value === "not" && isPunct(peek(1), "(")) {
+			operator = "is_not_empty";
+			pathIndex = pos + 2;
+		} else if (first.kind === "punct" && first.value === "(") {
+			operator = "is_empty";
+			pathIndex = pos + 1;
+		} else return null;
+		const read = readPath(tokens, pathIndex);
+		if (read === null) return null;
+		const canonical = compileCondition({
+			kind: "field",
+			subject: read.path,
+			operator,
+			value: void 0
+		});
+		if (canonical === null) return null;
+		const expected = tokenize(canonical);
+		if (expected === null || !tokensMatchAt(pos, expected)) return null;
+		pos += expected.length;
+		return {
+			kind: "rule",
+			left: read.path,
+			operator
+		};
+	}
+	function parseRule() {
+		const token = peek();
+		if (token === void 0 || token.kind !== "ident") return null;
+		if (token.value === "not") {
+			const next = peek(1);
+			if (next === void 0) return null;
+			if (next.kind === "ident" && next.value === "contains" && isPunct(peek(2), "(")) {
+				pos += 2;
+				return parseCall("not_contains");
+			}
+			if (next.kind === "punct" && next.value === "(") {
+				pos += 2;
+				return parseNotIn();
+			}
+			return null;
+		}
+		if (isPunct(peek(1), "(")) {
+			const operator = CALL_OPERATORS[token.value];
+			if (operator === void 0) return null;
+			pos += 1;
+			return parseCall(operator);
+		}
+		const left = parsePath();
+		if (left === null) return null;
+		const operatorToken = peek();
+		if (operatorToken === void 0) return null;
+		if (operatorToken.kind === "ident" && operatorToken.value === "in") {
+			pos += 1;
+			const right = parseArray();
+			return right === null ? null : {
+				kind: "rule",
+				left,
+				operator: "in",
+				right
+			};
+		}
+		if (operatorToken.kind === "punct") {
+			const operator = COMPARISON_OPERATORS[operatorToken.value];
+			if (operator === void 0) return null;
+			pos += 1;
+			const right = parseLiteral();
+			return right === null ? null : {
+				kind: "rule",
+				left,
+				operator,
+				right
+			};
+		}
+		return null;
+	}
+	function parseItem(depth) {
+		const emptiness = tryEmptiness();
+		if (emptiness !== null) return emptiness;
+		if (isPunct(peek(), "(")) {
+			if (depth >= MAX_GROUP_DEPTH) return null;
+			pos += 1;
+			const inner = parseGroup(depth + 1);
+			if (inner === null || !consumePunct(")")) return null;
+			return asGroup(inner);
+		}
+		return parseRule();
+	}
+	function peekJoin() {
+		const token = peek();
+		if (token !== void 0 && token.kind === "ident" && (token.value === "and" || token.value === "or")) return token.value;
+		return null;
+	}
+	function parseGroup(depth) {
+		const first = parseItem(depth);
+		if (first === null) return null;
+		const items = [first];
+		let op = null;
+		let join = peekJoin();
+		while (join !== null) {
+			if (op === null) op = join;
+			else if (op !== join) return null;
+			pos += 1;
+			const next = parseItem(depth);
+			if (next === null) return null;
+			items.push(next);
+			join = peekJoin();
+		}
+		return items.length === 1 ? items[0] : {
+			kind: "group",
+			op: op ?? "and",
+			items
+		};
+	}
+	const parsed = parseGroup(0);
+	if (parsed === null || pos !== tokens.length) return null;
+	return asGroup(parsed);
+}
+/**
+* Read a dotted/indexed identifier path starting at `from`, validated through
+* {@link isIdentifierPath}. Pure over the token array (no cursor) so it can probe a
+* candidate path — the emptiness oracle reads the blob's subject without committing
+* the cursor. Returns the path and the index just past it, or `null`.
+*/
+function readPath(tokens, from) {
+	const head = tokens[from];
+	if (head === void 0 || head.kind !== "ident") return null;
+	let path = head.value;
+	let index = from + 1;
+	let segment = tokens[index];
+	while (segment !== void 0 && segment.kind === "punct" && (segment.value === "." || segment.value === "[")) {
+		if (segment.value === ".") {
+			const name = tokens[index + 1];
+			if (name === void 0 || name.kind !== "ident") return null;
+			path += `.${name.value}`;
+			index += 2;
+		} else {
+			const inner = tokens[index + 1];
+			if (inner === void 0 || inner.kind !== "number" || !INTEGER_PATTERN.test(inner.value)) return null;
+			const close = tokens[index + 2];
+			if (close === void 0 || close.kind !== "punct" || close.value !== "]") return null;
+			path += `[${inner.value}]`;
+			index += 3;
+		}
+		segment = tokens[index];
+	}
+	return isIdentifierPath(path) ? {
+		path,
+		next: index
+	} : null;
+}
+function asGroup(node) {
+	return node.kind === "group" ? node : {
+		kind: "group",
+		op: "and",
+		items: [node]
+	};
+}
+function isPunct(token, value) {
+	return token !== void 0 && token.kind === "punct" && token.value === value;
+}
+/**
+* Split a ZEN expression into tokens, or `null` on an unexpected character or an
+* unterminated string. Whitespace is dropped, so the parser (and the emptiness
+* oracle's token match) is insensitive to spacing. String literals are read raw
+* between matching quotes — ZEN honors no backslash escapes, mirroring the encoder
+* in {@link compileCondition}.
+*/
+function tokenize(input) {
+	const tokens = [];
+	let index = 0;
+	while (index < input.length) {
+		const char = input[index];
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			index += 1;
+			continue;
+		}
+		if (char === "'" || char === "\"") {
+			const end = input.indexOf(char, index + 1);
+			if (end === -1) return null;
+			tokens.push({
+				kind: "string",
+				value: input.slice(index + 1, end)
+			});
+			index = end + 1;
+			continue;
+		}
+		const pair = input.slice(index, index + 2);
+		if (TWO_CHAR_PUNCTUATION.has(pair)) {
+			tokens.push({
+				kind: "punct",
+				value: pair
+			});
+			index += 2;
+			continue;
+		}
+		if (ONE_CHAR_PUNCTUATION.has(char)) {
+			tokens.push({
+				kind: "punct",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (DIGIT.test(char)) {
+			const match = NUMBER_PATTERN.exec(input.slice(index));
+			if (match === null) return null;
+			tokens.push({
+				kind: "number",
+				value: match[0]
+			});
+			index += match[0].length;
+			continue;
+		}
+		if (IDENT_START.test(char)) {
+			let end = index + 1;
+			while (end < input.length && IDENT_PART.test(input[end])) end += 1;
+			tokens.push({
+				kind: "ident",
+				value: input.slice(index, end)
+			});
+			index = end;
+			continue;
+		}
+		return null;
+	}
+	return tokens;
+}
+//#endregion
+//#region src/condition/tree-types.ts
+/**
+* The visual condition **tree** model: an arbitrarily nested and/or tree of typed
+* comparison rules that {@link compileConditionTree} serializes to a single ZEN
+* boolean expression and {@link liftConditionTree} reconstructs from one. It is a
+* distinct, self-contained shape from the compiler's flat {@link ConditionInput} —
+* the tree is what a structured builder UI edits, whereas `ConditionInput` is the
+* narrowed per-condition shape the compiler consumes. The two meet only at the
+* leaf: a {@link ConditionTreeRule} lowers to a field {@link ConditionInput} so the
+* operator vocabulary, literal encoding, and injection guard have one owner.
+*/
+/**
+* The tree's operator vocabulary as a runtime list — the compiler's full
+* {@link CONDITION_OPERATORS} set under the tree name. An alias, not a second
+* hand-maintained list, so the tree vocabulary can never drift from the compiler's;
+* it gives tree code and the builder UI one tree-named import for the operators they
+* support.
+*/
+const CONDITION_TREE_OPERATORS = CONDITION_OPERATORS;
 //#endregion
 //#region src/engine/evaluate.ts
 /**
@@ -726,14 +1237,121 @@ function satisfiesTypeSync(actual, expected) {
 	return getEngineSync().satisfies(actual, expected);
 }
 //#endregion
+//#region src/engine/template.ts
+const HOLE_PATTERN = /\{\{(?<expression>[^{}]*)\}\}/g;
+/**
+* Extract every `{{ expression }}` hole from a template document, in source
+* order. Literal text outside holes is ignored. Pure string scan — no engine
+* required — matching the `@gorules/lezer-zen-template` hole grammar, so it is
+* consistent with the editor's highlighting and completion gating.
+*/
+function parseTemplateHoles(source) {
+	const holes = [];
+	HOLE_PATTERN.lastIndex = 0;
+	for (let match = HOLE_PATTERN.exec(source); match !== null; match = HOLE_PATTERN.exec(source)) {
+		const inner = match.groups?.expression ?? "";
+		const from = match.index + 2;
+		holes.push({
+			from,
+			to: from + inner.length,
+			expression: inner
+		});
+	}
+	return holes;
+}
+/**
+* The template hole whose inner expression range contains `pos` (boundaries
+* included, so a caret sitting right after `{{` or right before `}}` counts as
+* inside), or `null` when `pos` is in literal text. Drives the editor's
+* hole-scoped completion and hover: intelligence fires inside a hole, nothing in
+* the surrounding literal text.
+*/
+function templateHoleAt(source, pos) {
+	return parseTemplateHoles(source).find((hole) => pos >= hole.from && pos <= hole.to) ?? null;
+}
+function hasExpression(hole) {
+	return hole.expression.trim().length > 0;
+}
+/**
+* Type-check every hole of a template against a `variables` context and merge the
+* results into one {@link ExpressionAnalysis} whose spans are offset onto the
+* template document. Each hole is a standard ZEN value expression; literal text
+* contributes nothing. `rootKind` is the context itself (shared by every hole),
+* so top-level completion works even in an empty hole.
+*
+* Best-effort: a hole that fails to analyze (e.g. mid-edit syntax) is skipped
+* rather than discarding the spans of its siblings. Throws
+* {@link ExpressionNotReadyError} if the engine has not loaded — use only behind
+* a readiness gate.
+*/
+function analyzeTemplateSync(variables, source) {
+	if (!isEngineReady()) throw new ExpressionNotReadyError();
+	const spans = [];
+	for (const hole of parseTemplateHoles(source)) {
+		if (!hasExpression(hole)) continue;
+		try {
+			for (const span of analyzeTypesSync(variables, hole.expression, "standard").spans) spans.push({
+				...span,
+				span: [span.span[0] + hole.from, span.span[1] + hole.from]
+			});
+		} catch {}
+	}
+	return {
+		rootKind: variables,
+		spans
+	};
+}
+/**
+* Async {@link analyzeTemplateSync}, loading the engine on first use.
+*/
+async function analyzeTemplate(variables, source) {
+	await loadEngine();
+	return analyzeTemplateSync(variables, source);
+}
+/**
+* Validate every hole of a template and return their syntax diagnostics, each
+* offset onto the template document (empty holes and literal text produce none).
+* The single-expression {@link getDiagnosticsSync} yields at most one diagnostic
+* per hole, so a template with several broken holes surfaces each one.
+*
+* Throws {@link ExpressionNotReadyError} if the engine has not loaded — use only
+* behind a readiness gate.
+*/
+function getTemplateDiagnosticsSync(source) {
+	if (!isEngineReady()) throw new ExpressionNotReadyError();
+	const diagnostics = [];
+	for (const hole of parseTemplateHoles(source)) {
+		if (!hasExpression(hole)) continue;
+		const diagnostic = getDiagnosticsSync(hole.expression, "standard");
+		if (diagnostic) diagnostics.push({
+			...diagnostic,
+			from: diagnostic.from + hole.from,
+			to: diagnostic.to + hole.from
+		});
+	}
+	return diagnostics;
+}
+/**
+* Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
+*/
+async function getTemplateDiagnostics(source) {
+	await loadEngine();
+	return getTemplateDiagnosticsSync(source);
+}
+//#endregion
 exports.CONDITION_OPERATORS = CONDITION_OPERATORS;
+exports.CONDITION_TREE_OPERATORS = CONDITION_TREE_OPERATORS;
 exports.ExpressionError = ExpressionError;
 exports.ExpressionNotReadyError = ExpressionNotReadyError;
+exports.analyzeTemplate = analyzeTemplate;
+exports.analyzeTemplateSync = analyzeTemplateSync;
 exports.analyzeTypes = analyzeTypes;
 exports.analyzeTypesSync = analyzeTypesSync;
 exports.compileBranch = compileBranch;
 exports.compileCondition = compileCondition;
+exports.compileConditionTree = compileConditionTree;
 exports.compileGroup = compileGroup;
+exports.conditionOperatorArity = conditionOperatorArity;
 exports.configureEngine = configureEngine;
 exports.configureExpressionMessages = configureExpressionMessages;
 exports.enMessages = enMessages;
@@ -748,14 +1366,19 @@ exports.getDiagnosticsSync = getDiagnosticsSync;
 exports.getEngineError = getEngineError;
 exports.getEngineSync = getEngineSync;
 exports.getExpressionMessages = getExpressionMessages;
+exports.getTemplateDiagnostics = getTemplateDiagnostics;
+exports.getTemplateDiagnosticsSync = getTemplateDiagnosticsSync;
 exports.isEngineReady = isEngineReady;
+exports.liftConditionTree = liftConditionTree;
 exports.loadEngine = loadEngine;
+exports.parseTemplateHoles = parseTemplateHoles;
 exports.registerExpressionLocale = registerExpressionLocale;
 exports.resetEngine = resetEngine;
 exports.satisfiesType = satisfiesType;
 exports.satisfiesTypeSync = satisfiesTypeSync;
 exports.selectBranch = selectBranch;
 exports.selectBranchWith = selectBranchWith;
+exports.templateHoleAt = templateHoleAt;
 exports.toZenLiteral = toZenLiteral;
 exports.zhCNMessages = zhCNMessages;