@stll/template-conditions 0.3.0 → 0.4.0

package/dist/index.js

@@ -192,11 +192,12 @@ const COMPARE_SYMBOL_TO_OP = {
 };
 const escapeRegexLiteral = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 const COMPARE_SYMBOL_PATTERN = Object.keys(COMPARE_SYMBOL_TO_OP).sort((left, right) => right.length - left.length).map(escapeRegexLiteral).join("|");
-const NON_STRING_TOKEN_RE = new RegExp(String.raw`(?<token>${COMPARE_SYMBOL_PATTERN}|!(?!=)|and\b|or\b|contains\b|[()]|-?\d[\p{N}_.]*|[\p{L}\p{N}_.]+(?:-[\p{L}\p{N}_.]+)*)`, "uy");
+const NON_STRING_TOKEN_RE = new RegExp(String.raw`(?<token>${COMPARE_SYMBOL_PATTERN}|and\b|or\b|not\b|in\b|is\b|defined\b|[()]|-?\d[\p{N}_.]*|[\p{L}\p{N}_.]+(?:-[\p{L}\p{N}_.]+)*)`, "uy");
 const STARTS_WITH_DIGIT_RE = /^-?\d/u;
 const isCompareSymbol = (raw) => Object.hasOwn(COMPARE_SYMBOL_TO_OP, raw);
 /**
-* Scan a `"..."` literal starting at `expr[start]` (the opening quote),
+* Scan a `"..."` or `'...'` literal starting at `expr[start]` (the opening
+* quote),
 * honoring `\\`-escapes without interpreting them. A single linear pass:
 * each character is visited at most once, so this is safe on adversarial
 * input regardless of how many `"` or `\\` characters it contains.
@@ -206,9 +207,10 @@ const isCompareSymbol = (raw) => Object.hasOwn(COMPARE_SYMBOL_TO_OP, raw);
 * closing quote simply closes at end of input.
 */
 const scanString = (expr, start) => {
+	const quote = expr[start];
 	let i = start + 1;
 	while (i < expr.length) {
-		if (expr[i] === "\"") return {
+		if (expr[i] === quote) return {
 			content: expr.slice(start + 1, i),
 			end: i + 1
 		};
@@ -222,8 +224,11 @@ const scanString = (expr, start) => {
 const classifyNonString = (raw) => {
 	if (raw === "and") return { type: "and" };
 	if (raw === "or") return { type: "or" };
-	if (raw === "!") return { type: "not" };
-	if (raw === "contains" || isCompareSymbol(raw)) return {
+	if (raw === "not") return { type: "not" };
+	if (raw === "in") return { type: "in" };
+	if (raw === "is") return { type: "is" };
+	if (raw === "defined") return { type: "defined" };
+	if (isCompareSymbol(raw)) return {
 		type: "op",
 		raw
 	};
@@ -238,11 +243,11 @@ const tokenize = (expr) => {
 	const tokens = [];
 	let pos = 0;
 	while (pos < expr.length) {
-		if (expr[pos] === "\"") {
+		if (expr[pos] === "\"" || expr[pos] === "'") {
 			const { content, end } = scanString(expr, pos);
 			tokens.push({
 				type: "string",
-				raw: content.replace(/\\"/gu, "\"")
+				raw: content.replace(/\\(?<quote>["'])/gu, "$<quote>")
 			});
 			pos = end;
 			continue;
@@ -289,9 +294,9 @@ const operandFromToken = (token) => {
 		path: token.raw
 	};
 };
-/** `contains` carries a literal payload (`string`), not an operand: render the
-*  right-hand token as a string. */
-const containsValue = (token) => {
+/** `"x" in path` carries a literal payload (`string`), not an operand: render
+*  the left-hand token as a string. */
+const membershipValue = (token) => {
 	const operand = operandFromToken(token);
 	return operand.type === "literal" ? String(operand.value) : token.raw;
 };
@@ -358,6 +363,39 @@ const parseCondition = (expression) => {
 		}
 		pos += 1;
 		const left = operandFromToken(leftTok);
+		if (peek()?.type === "is") {
+			pos += 1;
+			const negated = peek()?.type === "not";
+			if (negated) pos += 1;
+			if (peek()?.type === "defined") pos += 1;
+			return {
+				type: "predicate",
+				operand: left,
+				op: negated ? "is_empty" : "is_not_empty"
+			};
+		}
+		if (peek()?.type === "in") {
+			pos += 1;
+			const rightTok = peek();
+			if (!rightTok || rightTok.type !== "value" && rightTok.type !== "string") return {
+				type: "predicate",
+				operand: left,
+				op: "is_truthy"
+			};
+			pos += 1;
+			const right = operandFromToken(rightTok);
+			if (right.type !== "path") return {
+				type: "predicate",
+				operand: right,
+				op: "is_truthy"
+			};
+			return {
+				type: "predicate",
+				operand: right,
+				op: "contains",
+				value: membershipValue(leftTok)
+			};
+		}
 		const opTok = peek();
 		if (opTok?.type !== "op") return {
 			type: "predicate",
@@ -372,12 +410,6 @@ const parseCondition = (expression) => {
 			op: "is_truthy"
 		};
 		pos += 1;
-		if (opTok.raw === "contains") return {
-			type: "predicate",
-			operand: left,
-			op: "contains",
-			value: containsValue(rightTok)
-		};
 		return {
 			type: "compare",
 			left,
@@ -387,51 +419,187 @@ const parseCondition = (expression) => {
 	};
 	return parseOr();
 };
+//#endregion
+//#region src/referenced-paths.ts
+const operandsOf = (node) => node.type === "compare" ? [node.left, node.right] : [node.operand];
+/** Every field path the tree reads, or `null` when an operand names something
+*  whose own references cannot be enumerated (a formula over other fields). */
+const nodePaths = (node) => {
+	if (node.type === "group") {
+		const paths = [];
+		for (const child of node.children) {
+			const childPaths = nodePaths(child);
+			if (childPaths === null) return null;
+			paths.push(...childPaths);
+		}
+		return paths;
+	}
+	const paths = [];
+	for (const operand of operandsOf(node)) {
+		if (operand.type === "formula") return null;
+		if (operand.type === "path") paths.push(operand.path);
+	}
+	return paths;
+};
+/**
+* Every field path an expression reads, in source order.
+*
+* `null` says the expression does not answer the question: it did not parse,
+* or it reads an operand whose own references cannot be enumerated. A caller
+* deciding what a condition depends on must not read that as "depends on
+* nothing".
+*/
+const referencedConditionPaths = (expression) => {
+	const node = parseCondition(expression);
+	return node === null ? null : nodePaths(node);
+};
+//#endregion
+//#region src/markers.ts
+/**
+* Canonical grammar for the docxtpl dialect of Jinja — the single source of
+* truth shared by the fill pipeline (api), the editor highlighter (folio), and
+* the read-only preview (web).
+*
+* Two spans carry meaning: an output marker `{{ ... }}` prints a value, and a
+* tag `{% ... %}` opens or closes a block. A tag may carry a docxtpl placement
+* prefix — `{%p ... %}` owns its paragraph, `{%tr ... %}` owns its table row —
+* and a bare tag is placed by the leniency rules the consumer applies.
+*
+* Add a new directive to `MarkerMeta` and teach {@link classifyMarker} to
+* recognize it. Compile-time totality checks then require its ordered runtime
+* value and its block/inline disposition, while exhaustive consumer switches
+* fail until they handle it.
+*
+* No consumer should define its own marker regex. The low-level pattern
+* factories below exist so handlers that mutate raw XML/text reuse the exact
+* same literals; recognizers should prefer the high-level scanner.
+*/
+/** The loop properties addressable inside a `{% for %}` body. */
+const LOOP_PROPERTIES = [
+	"index",
+	"index0",
+	"first",
+	"last",
+	"length"
+];
 const DIRECTIVE_KINDS = [
 	"placeholder",
 	"clause",
 	"num",
 	"ref",
-	"index",
-	"count",
+	"loop",
 	"if",
-	"elseif",
+	"elif",
 	"else",
 	"endif",
-	"each",
-	"endeach"
+	"for",
+	"endfor"
 ];
 /** Directives that occupy their own paragraph, in canonical grammar order. */
 const BLOCK_DIRECTIVE_KINDS = [
 	"if",
-	"elseif",
+	"elif",
 	"else",
 	"endif",
-	"each",
-	"endeach"
+	"for",
+	"endfor"
 ];
 const isBlockDirectiveKind = (kind) => typeof kind === "string" && BLOCK_DIRECTIVE_KINDS.some((blockKind) => blockKind === kind);
-/** Any `{{...}}` marker; group 1 is the inner text (untrimmed — callers trim). */
-const markerPattern = () => /\{\{(?<inner>[^{}]*)\}\}/gu;
-/** Inline field / clause / numbering marker (inner allows the directive sigils). */
-const placeholderPattern = () => /\{\{\s*(?<name>[\p{L}\p{N}_.@:-]+)\s*\}\}/gu;
-/** `{{@clause:Name}}` / `{{@clause:Name:v3}}` — `name` and `modifier` groups. */
-const clauseSlotPattern = () => /\{\{\s*@clause:(?<name>[^:}\s]+)(?::(?<modifier>[^}\s]+))?\s*\}\}/gu;
-/** `{{@num:Key}}` — the `key` group. */
-const numPattern = () => /\{\{\s*@num:(?<key>[\p{L}\p{N}_.-]+)\s*\}\}/gu;
-/** `{{@ref:Key}}` — the `key` group. */
-const refPattern = () => /\{\{\s*@ref:(?<key>[\p{L}\p{N}_.-]+)\s*\}\}/gu;
-/** `{{@index}}` — the 1-based position within the innermost enclosing loop. */
-const indexPattern = () => /\{\{\s*@index\s*\}\}/gu;
-/** `{{@count}}` — the item count of the innermost enclosing loop. */
-const countPattern = () => /\{\{\s*@count\s*\}\}/gu;
+/** Callable forms inside `{{ }}` that address document machinery rather than a
+*  fill value. */
+const FUNCTION_NAMES = [
+	"clause",
+	"num",
+	"ref"
+];
+/**
+* Every filter the dialect accepts on a fillable value. The names are the
+* grammar's; which manifest property each one writes is decided by the field
+* catalogue in the api, which is total over BOTH this list and the manifest
+* keys, so neither side can gain an entry the other has not decided.
+*/
+const FILTER_NAMES = [
+	"text",
+	"number",
+	"date",
+	"checkbox",
+	"select",
+	"options_from",
+	"label",
+	"hint",
+	"required",
+	"pattern",
+	"min",
+	"max",
+	"min_length",
+	"max_length",
+	"min_items",
+	"max_items",
+	"ai",
+	"lookup",
+	"matter",
+	"contact",
+	"party",
+	"attorney",
+	"firm",
+	"formula",
+	"condition"
+];
+const isFilterName = (value) => FILTER_NAMES.some((name) => name === value);
+const isFunctionName = (value) => FUNCTION_NAMES.some((name) => name === value);
+const SMART_DOUBLE_QUOTES = /[“”„«»]/gu;
+const SMART_SINGLE_QUOTES = /[‘’‚]/gu;
+const FIXED_SPACES = /[    ]/gu;
+/** Normalise one marker's inner text: typographic quotes become straight
+*  quotes, fixed-width spaces become ordinary ones. */
+const normalizeMarkerInner = (inner) => inner.replace(SMART_DOUBLE_QUOTES, "\"").replace(SMART_SINGLE_QUOTES, "'").replace(FIXED_SPACES, " ");
+/**
+* What an output marker holds between its braces: anything but a brace or a
+* double quote, plus whole double-quoted arguments, whose braces are content
+* rather than the marker's own delimiters — `pattern("^[0-9]{5}$")` is a regex,
+* not a nested marker. An apostrophe stays an ordinary character, so
+* `label("Owner's")` reads as it always did.
+*
+* The alternatives cannot overlap (the plain one excludes every character the
+* quoted one may start with) and a quoted run's end is forced by its body, so
+* the scan stays linear on adversarial input: a `{{` with no closing `}}`
+* costs one failed pass, not a polynomial retry.
+*/
+const MARKER_OUTPUT_BODY = String.raw`(?:[^{}"“”„«»]|["“„«][^"”»]*["”»])*`;
+/** What a tag holds between `{%` and `%}`: anything but a brace, and a `%`
+*  only where it does not close the tag. */
+const MARKER_STATEMENT_BODY = String.raw`(?:[^{}%]|%(?!\}))*`;
+/**
+* Any marker span: an output `{{...}}` (group `output`) or a tag `{%...%}`
+* (group `statement`, with the docxtpl placement in group `prefix`).
+*/
+const markerPattern = () => new RegExp(String.raw`\{\{(?<output>${MARKER_OUTPUT_BODY})\}\}|\{%(?:(?<prefix>tr|p)(?=\s))?(?<statement>${MARKER_STATEMENT_BODY})%\}`, "gu");
+/** Inline value marker, including its filter chain; group `name` is the path
+*  the value comes from and group `filters` the untouched chain. */
+const placeholderPattern = () => new RegExp(String.raw`\{\{\s*(?<name>[\p{L}\p{N}_.-]+)\s*(?<filters>\|${MARKER_OUTPUT_BODY})?\}\}`, "gu");
+/** Any character that opens a quoted function argument. */
+const OPEN_QUOTE = String.raw`["'“„«‘‚]`;
+/** Any character that closes one. */
+const CLOSE_QUOTE = String.raw`["'”»’]`;
+/** Everything a quoted argument may hold: no quote of either shape. */
+const QUOTED_BODY = String.raw`[^"'“”„«»‘’‚]*`;
+/** `{{ clause("Name") }}` / `{{ clause("Name", "v3") }}`. */
+const clauseSlotPattern = () => new RegExp(String.raw`\{\{\s*clause\(\s*${OPEN_QUOTE}(?<name>${QUOTED_BODY})${CLOSE_QUOTE}\s*(?:,\s*${OPEN_QUOTE}(?<modifier>${QUOTED_BODY})${CLOSE_QUOTE}\s*)?\)\s*\}\}`, "gu");
+const numberingPattern = (fn) => new RegExp(String.raw`\{\{\s*${fn}\(\s*${OPEN_QUOTE}(?<key>[\p{L}\p{N}_.-]+)${CLOSE_QUOTE}\s*\)\s*\}\}`, "gu");
+/** `{{ num("key") }}` — the `key` group. */
+const numPattern = () => numberingPattern("num");
+/** `{{ ref("key") }}` — the `key` group. */
+const refPattern = () => numberingPattern("ref");
+/** `{{ loop.index }}` and its siblings — the `property` group. */
+const loopPattern = () => /\{\{\s*loop\.(?<property>index0|index|first|last|length)\s*\}\}/gu;
 /** Cheap presence test for any numbering marker (no capture). */
-const hasNumberingPattern = () => /\{\{\s*@(?:num|ref):/u;
-/** Cheap presence test for any block directive (no capture). */
-const hasBlockDirectivePattern = () => /\{\{\s*[#/]/u;
-/** A whole line that is a single block directive — `tag` and `expr` groups. */
-const blockDirectiveLinePattern = () => /^\s*\{\{\s*(?<tag>#if|#elseif|#else|#each|\/if|\/each)\b(?<expr>[^{}]*)\}\}\s*$/u;
+const hasNumberingPattern = () => /\{\{\s*(?:num|ref)\s*\(/u;
+/** Cheap presence test for any tag (no capture). */
+const hasBlockDirectivePattern = () => /\{%/u;
+/** A whole line that is a single block tag — `prefix`, `tag` and `expr`. */
+const blockDirectiveLinePattern = () => /^\s*\{%(?:(?<prefix>tr|p)(?=\s))?\s*(?<tag>if|elif|else|endif|for|endfor)\b(?<expr>(?:[^{}%]|%(?!\}))*)%\}\s*$/u;
 const FIELD_PATH_RE = /^[\p{L}\p{N}_.-]+$/u;
+const IDENTIFIER_RE = /^[\p{L}_][\p{L}\p{N}_-]*$/u;
 const UNSAFE_FIELD_PATH_SEGMENTS = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
@@ -443,130 +611,483 @@ const isFieldPath = (value) => FIELD_PATH_RE.test(value);
 /** Whether `value` is safe to use as a dotted object path. */
 const isSafeFieldPath = (value) => isFieldPath(value) && value.split(".").every((segment) => !UNSAFE_FIELD_PATH_SEGMENTS.has(segment));
 const CLAUSE_SLOT_NAME_RE = /^[\p{L}\p{N}_.-]+$/u;
-/** Whether `value` is a valid name for authoring a `{{@clause:NAME}}` slot:
-*  the intersection of the clause-slot parse grammar and the fill pipeline's
-*  placeholder charset, so every accepted name round-trips through fill. */
+/** Whether `value` is a valid name for authoring a `clause("NAME")` slot. */
 const isClauseSlotName = (value) => CLAUSE_SLOT_NAME_RE.test(value);
-const CLAUSE_INNER_RE = /^@clause:(?<name>[^:}\s]+)(?::(?<version>[^}\s]+))?$/u;
-const NUM_INNER_RE = /^@num:(?<key>[\p{L}\p{N}_.-]+)$/u;
-const REF_INNER_RE = /^@ref:(?<key>[\p{L}\p{N}_.-]+)$/u;
-const INDEX_INNER_RE = /^@index$/u;
-const COUNT_INNER_RE = /^@count$/u;
-const BLOCK_INNER_RE = /^(?<token>#if|#elseif|#else|#each|\/if|\/each)\b(?<expr>.*)$/u;
-/**
-* Classify the inner text of a `{{...}}` marker. Returns `null` when the text is
-* not a recognized directive (so a recognizer can leave stray braces alone).
-*/
-const classifyMarker = (innerRaw) => {
-	const inner = innerRaw.trim();
-	const block = BLOCK_INNER_RE.exec(inner);
-	if (block) {
-		const token = block.groups?.["token"] ?? "";
-		const expr = (block.groups?.["expr"] ?? "").trim();
-		if (token === "#if") return {
+const isLoopProperty = (value) => LOOP_PROPERTIES.some((property) => property === value);
+const NUMBER_LITERAL_RE = /^-?\d+(?:\.\d+)?$/u;
+const literalFromBareToken = (raw) => {
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	if (NUMBER_LITERAL_RE.test(raw)) return Number(raw);
+	return null;
+};
+/**
+* Scan a `"..."` / `'...'` literal starting at the opening quote, honouring
+* `\`-escapes. One linear pass; an unterminated literal closes at end of
+* input, matching the degrade-gracefully policy of the condition parser.
+*/
+const scanQuoted = (text, start) => {
+	const quote = text[start];
+	let i = start + 1;
+	let value = "";
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === quote) return {
+			value,
+			end: i + 1
+		};
+		if (ch === "\\" && i + 1 < text.length) {
+			value += text[i + 1];
+			i += 2;
+			continue;
+		}
+		value += ch;
+		i += 1;
+	}
+	return {
+		value,
+		end: text.length
+	};
+};
+/**
+* Scan a parenthesised argument list starting at `(`. Arguments are string,
+* number or boolean literals, optionally named (`adapt=true`). Anything else
+* (an identifier, an operator, a nested call) fails the scan, which is what
+* makes `min(a + 1)` a rejected expression rather than a silently odd filter.
+*/
+const scanArguments = (text, start) => {
+	const args = [];
+	let i = start + 1;
+	let expectValue = true;
+	let pendingName;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === void 0) break;
+		if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
+			i += 1;
+			continue;
+		}
+		if (ch === ")") {
+			if (pendingName !== void 0) return null;
+			if (!expectValue || args.length === 0) return {
+				args,
+				end: i + 1
+			};
+			return null;
+		}
+		if (ch === ",") {
+			if (expectValue) return null;
+			expectValue = true;
+			i += 1;
+			continue;
+		}
+		if (!expectValue) return null;
+		if (ch === "\"" || ch === "'") {
+			const { value, end } = scanQuoted(text, i);
+			args.push(pendingName === void 0 ? {
+				kind: "positional",
+				value
+			} : {
+				kind: "keyword",
+				name: pendingName,
+				value
+			});
+			pendingName = void 0;
+			expectValue = false;
+			i = end;
+			continue;
+		}
+		let j = i;
+		while (j < text.length && /[\p{L}\p{N}_.-]/u.test(text[j] ?? "")) j += 1;
+		if (j === i) return null;
+		const raw = text.slice(i, j);
+		if (text[j] === "=" && text[j + 1] !== "=") {
+			if (pendingName !== void 0 || !IDENTIFIER_RE.test(raw)) return null;
+			pendingName = raw;
+			i = j + 1;
+			continue;
+		}
+		const value = literalFromBareToken(raw);
+		if (value === null) return null;
+		args.push(pendingName === void 0 ? {
+			kind: "positional",
+			value
+		} : {
+			kind: "keyword",
+			name: pendingName,
+			value
+		});
+		pendingName = void 0;
+		expectValue = false;
+		i = j;
+	}
+	return null;
+};
+/**
+* Parse the `| name | name(args)` tail of an output marker. Returns the named
+* unknown filter instead of a chain when one step is not in the catalogue, so
+* the rejection can quote it.
+*/
+const scanFilterChain = (tail) => {
+	const filters = [];
+	let i = 0;
+	while (i < tail.length) {
+		while (i < tail.length && /\s/u.test(tail[i] ?? "")) i += 1;
+		if (i >= tail.length) break;
+		if (tail[i] !== "|") return null;
+		i += 1;
+		while (i < tail.length && /\s/u.test(tail[i] ?? "")) i += 1;
+		let j = i;
+		while (j < tail.length && /[\p{L}\p{N}_]/u.test(tail[j] ?? "")) j += 1;
+		const name = tail.slice(i, j);
+		if (name === "") return null;
+		if (!isFilterName(name)) return { unknownFilter: name };
+		i = j;
+		while (i < tail.length && /\s/u.test(tail[i] ?? "")) i += 1;
+		if (tail[i] === "(") {
+			const scanned = scanArguments(tail, i);
+			if (scanned === null) return null;
+			filters.push({
+				name,
+				args: scanned.args
+			});
+			i = scanned.end;
+			continue;
+		}
+		filters.push({
+			name,
+			args: []
+		});
+	}
+	return { filters };
+};
+const PREFIX_BY_TOKEN = {
+	p: "paragraph",
+	tr: "row"
+};
+const readPrefix = (token) => token === "p" || token === "tr" ? PREFIX_BY_TOKEN[token] : "none";
+const TAG_RE = /^(?<tag>[\p{L}_][\p{L}\p{N}_]*)\b(?<rest>[\s\S]*)$/u;
+const FOR_RE = /^(?<alias>[\p{L}_][\p{L}\p{N}_-]*)\s+in\s+(?<path>[\p{L}\p{N}_.-]+)\s*(?<filters>\|[\s\S]*)?$/u;
+const CALL_RE = /^(?<name>[\p{L}_][\p{L}\p{N}_]*)\s*\(/u;
+/** Classify a `{% ... %}` tag. */
+const classifyStatement = (inner) => {
+	const match = TAG_RE.exec(inner);
+	if (!match) return null;
+	const tag = match.groups?.["tag"] ?? "";
+	const rest = (match.groups?.["rest"] ?? "").trim();
+	switch (tag) {
+		case "if": return {
 			kind: "if",
-			expr
+			expr: rest
 		};
-		if (token === "#elseif") return {
-			kind: "elseif",
-			expr
+		case "elif": return {
+			kind: "elif",
+			expr: rest
 		};
-		if (token === "#each") return {
-			kind: "each",
-			expr
+		case "else": return rest === "" ? { kind: "else" } : null;
+		case "endif": return rest === "" ? { kind: "endif" } : null;
+		case "endfor": return rest === "" ? { kind: "endfor" } : null;
+		case "for": {
+			const loop = FOR_RE.exec(rest);
+			if (!loop) return null;
+			const tail = loop.groups?.["filters"];
+			const chain = tail === void 0 ? { filters: [] } : scanFilterChain(tail);
+			if (chain === null || "unknownFilter" in chain) return null;
+			return {
+				kind: "for",
+				alias: loop.groups?.["alias"] ?? "",
+				path: loop.groups?.["path"] ?? "",
+				filters: chain.filters
+			};
+		}
+		default: return null;
+	}
+};
+/** Classify a `{{ ... }}` output marker. */
+const classifyOutput = (inner) => {
+	const call = CALL_RE.exec(inner);
+	if (call) {
+		const name = call.groups?.["name"] ?? "";
+		if (!isFunctionName(name)) return null;
+		const scanned = scanArguments(inner, inner.indexOf("("));
+		if (scanned === null) return null;
+		if (inner.slice(scanned.end).trim() !== "") return null;
+		const positional = scanned.args.filter((arg) => arg.kind === "positional" && typeof arg.value === "string");
+		if (positional.length !== scanned.args.length) return null;
+		const [first, second] = positional.map((arg) => String(arg.value));
+		if (first === void 0) return null;
+		if (name === "clause") return scanned.args.length <= 2 ? {
+			kind: "clause",
+			name: first,
+			version: second
+		} : null;
+		if (scanned.args.length !== 1 || !isFieldPath(first)) return null;
+		return name === "num" ? {
+			kind: "num",
+			key: first
+		} : {
+			kind: "ref",
+			key: first
 		};
-		if (token === "#else") return { kind: "else" };
-		if (token === "/if") return { kind: "endif" };
-		if (token === "/each") return { kind: "endeach" };
 	}
-	const clause = CLAUSE_INNER_RE.exec(inner);
-	if (clause) return {
-		kind: "clause",
-		name: clause.groups?.["name"] ?? "",
-		version: clause.groups?.["version"]
-	};
-	const num = NUM_INNER_RE.exec(inner);
-	if (num) return {
-		kind: "num",
-		key: num.groups?.["key"] ?? ""
-	};
-	const ref = REF_INNER_RE.exec(inner);
-	if (ref) return {
-		kind: "ref",
-		key: ref.groups?.["key"] ?? ""
+	const pipe = inner.indexOf("|");
+	const head = (pipe === -1 ? inner : inner.slice(0, pipe)).trim();
+	const tail = pipe === -1 ? "" : inner.slice(pipe);
+	const loopMatch = /^loop\.(?<property>[\p{L}\p{N}_]+)$/u.exec(head);
+	if (loopMatch) {
+		const property = loopMatch.groups?.["property"] ?? "";
+		return isLoopProperty(property) && tail === "" ? {
+			kind: "loop",
+			property
+		} : null;
+	}
+	if (!FIELD_PATH_RE.test(head)) return null;
+	if (tail === "") return {
+		kind: "placeholder",
+		expr: head,
+		filters: []
 	};
-	if (INDEX_INNER_RE.test(inner)) return { kind: "index" };
-	if (COUNT_INNER_RE.test(inner)) return { kind: "count" };
-	if (FIELD_PATH_RE.test(inner)) return {
+	const chain = scanFilterChain(tail);
+	if (chain === null || "unknownFilter" in chain) return null;
+	return {
 		kind: "placeholder",
-		expr: inner
+		expr: head,
+		filters: chain.filters
 	};
-	return null;
 };
 /**
-* Find every recognized `{{...}}` marker in `text`, in document order, with
-* offsets and classified metadata. Unrecognized `{{...}}` spans are skipped.
+* Classify the inner text of one marker. Returns `null` when the text is not a
+* recognized directive (so a recognizer can leave stray braces alone).
 */
-const scanMarkers = (text) => {
+const classifyMarker = (innerRaw, form = "output") => {
+	const inner = normalizeMarkerInner(innerRaw).trim();
+	return form === "statement" ? classifyStatement(inner) : classifyOutput(inner);
+};
+/** Every marker-shaped span in `text`, in document order, before classification. */
+const scanSpans = (text) => {
 	const re = markerPattern();
-	const out = [];
+	const spans = [];
 	let match = re.exec(text);
 	while (match !== null) {
-		const inner = (match[1] ?? "").trim();
-		const meta = classifyMarker(inner);
-		if (meta) out.push({
+		const output = match.groups?.["output"];
+		const statement = match.groups?.["statement"];
+		const raw = match[0];
+		const form = output === void 0 ? "statement" : "output";
+		spans.push({
 			start: match.index,
-			end: match.index + match[0].length,
-			raw: match[0],
-			inner,
-			meta
+			end: match.index + raw.length,
+			raw,
+			inner: normalizeMarkerInner(output ?? statement ?? "").trim(),
+			form,
+			prefix: readPrefix(match.groups?.["prefix"])
 		});
 		match = re.exec(text);
 	}
+	return spans;
+};
+/**
+* Find every recognized marker in `text`, in document order, with offsets and
+* classified metadata. Unrecognized spans are skipped.
+*/
+const scanMarkers = (text) => {
+	const out = [];
+	for (const span of scanSpans(text)) {
+		const meta = classifyMarker(span.inner, span.form);
+		if (meta) out.push({
+			...span,
+			meta
+		});
+	}
 	return out;
 };
 /**
-* Find every `{{...}}` span whose inner text is NOT a recognized directive —
-* near-misses an author clearly meant as markers but that every recognizer
-* skips, so they print literally at fill time (e.g. `{{my field}}` with a
-* space, `{{@clause:}}` with no name). Offsets and raw text are shaped like
-* {@link scanMarkers} results, minus the classified `meta`. This is the exact
+* Rewrite every `{{ ... }}` output marker in `text` through `replace`, which
+* receives the whole marker and its raw inner text and returns the replacement.
+* Tags are left untouched. The single scan is the same one the classifier uses,
+* so a caller that rewrites marker text never needs its own regex.
+*/
+const replaceOutputMarkers = (text, replace) => {
+	let out = "";
+	let cursor = 0;
+	for (const span of scanSpans(text)) {
+		if (span.form !== "output") continue;
+		out += text.slice(cursor, span.start) + replace(span.raw, span.inner);
+		cursor = span.end;
+	}
+	return out + text.slice(cursor);
+};
+/**
+* The values-map key one marker substitutes from, or `null` when the marker is
+* not a substitution target (a tag, or a `loop.*` token the loop expander
+* resolves first). One function so the key discovery writes is the key the
+* patcher reads.
+*/
+const substitutionKey = (meta) => {
+	switch (meta.kind) {
+		case "placeholder": return meta.expr;
+		case "clause": return meta.version === void 0 ? `${CLAUSE_KEY_PREFIX}${meta.name}` : `${CLAUSE_KEY_PREFIX}${meta.name}:${meta.version}`;
+		case "num":
+		case "ref":
+		case "loop":
+		case "if":
+		case "elif":
+		case "else":
+		case "endif":
+		case "for":
+		case "endfor": return null;
+		default: return assertNever(meta);
+	}
+};
+/** Namespace of the synthetic clause-slot key, kept out of the field-path
+*  charset so it can never collide with an author's path. */
+const CLAUSE_KEY_PREFIX = "@clause:";
+/** The values-map key for one clause slot. */
+const clauseSlotKey = (name, version) => version === void 0 ? `${CLAUSE_KEY_PREFIX}${name}` : `${CLAUSE_KEY_PREFIX}${name}:${version}`;
+/**
+* Find every marker-shaped span whose inner text is NOT a recognized
+* directive — near-misses an author clearly meant as markers but that every
+* recognizer skips, so they print literally at fill time. This is the exact
 * complement of {@link scanMarkers}: a span is in one list or the other.
 */
 const scanInvalidMarkers = (text) => {
-	const re = markerPattern();
 	const out = [];
-	let match = re.exec(text);
-	while (match !== null) {
-		const inner = (match[1] ?? "").trim();
-		if (classifyMarker(inner) === null) out.push({
-			start: match.index,
-			end: match.index + match[0].length,
-			raw: match[0],
-			inner
-		});
-		match = re.exec(text);
-	}
+	for (const { prefix: _prefix, ...span } of scanSpans(text)) if (classifyMarker(span.inner, span.form) === null) out.push(span);
 	return out;
 };
-const MARKER_DEFECT_KINDS = ["unknown_directive", "bracket_index"];
-/** A `{{#...}}` / `{{/...}}` shape: an author reaching for a block directive. */
-const DIRECTIVE_SHAPE_RE = /^[#/]/u;
+const LEGACY_BLOCK_RE = /^(?<token>#if|#elseif|#else|#each|\/if|\/each)\b(?<expr>[\s\S]*)$/u;
+const LEGACY_CLAUSE_RE = /^@clause:(?<name>[^:}\s]+)(?::(?<version>[^}\s]+))?$/u;
+const LEGACY_NUM_RE = /^@(?<fn>num|ref):(?<key>[\p{L}\p{N}_.-]+)$/u;
+/** Singular of a plain-word path segment, for a generated loop alias. */
+const singularize = (segment) => {
+	if (segment.endsWith("ies") && segment.length > 3) return `${segment.slice(0, -3)}y`;
+	if (/(?:s|ss|sh|ch|x|z)es$/u.test(segment)) return segment.slice(0, -2);
+	if (/[^s]s$/u.test(segment)) return segment.slice(0, -1);
+	return segment;
+};
+/** The loop alias the codemod (and the legacy-marker message) generates for a
+*  `{{#each path}}`: the singular of the last plain-word segment, else `item`. */
+const legacyLoopAlias = (path) => {
+	const segment = path.split(".").at(-1) ?? "";
+	if (!IDENTIFIER_RE.test(segment)) return "item";
+	const alias = singularize(segment);
+	return alias === "" || alias === segment ? "item" : alias;
+};
+/** Translate an old-dialect condition expression to the Jinja surface:
+*  `!a` becomes `not a`, `a contains "x"` becomes `"x" in a`. */
+const translateLegacyExpression = (expr) => expr.replace(/(?<![\p{L}\p{N}_.-])(?<path>[\p{L}\p{N}_.-]+)\s+contains\s+(?<value>"[^"]*"|[\p{L}\p{N}_.-]+)/gu, (_m, path, value) => `${value.startsWith("\"") ? value : `"${value}"`} in ${path}`).replace(/!(?!=)\s*/gu, "not ");
+/**
+* The Jinja marker that replaces one old-dialect marker's inner text, or
+* `null` when the text is not old-dialect. Shared by the rejection message and
+* the codemod, so the fix an author is told to make is the fix the script
+* would have made.
+*/
+const legacyMarkerReplacement = (innerRaw) => {
+	const inner = normalizeMarkerInner(innerRaw).trim();
+	const block = LEGACY_BLOCK_RE.exec(inner);
+	if (block) {
+		const token = block.groups?.["token"] ?? "";
+		const expr = translateLegacyExpression((block.groups?.["expr"] ?? "").trim());
+		switch (token) {
+			case "#if": return `{% if ${expr} %}`;
+			case "#elseif": return `{% elif ${expr} %}`;
+			case "#else": return "{% else %}";
+			case "/if": return "{% endif %}";
+			case "#each": return `{% for ${legacyLoopAlias(expr)} in ${expr} %}`;
+			case "/each": return "{% endfor %}";
+			default: return null;
+		}
+	}
+	const clause = LEGACY_CLAUSE_RE.exec(inner);
+	if (clause) {
+		const name = clause.groups?.["name"] ?? "";
+		const version = clause.groups?.["version"];
+		return version === void 0 ? `{{ clause("${name}") }}` : `{{ clause("${name}", "${version}") }}`;
+	}
+	const numbering = LEGACY_NUM_RE.exec(inner);
+	if (numbering) return `{{ ${numbering.groups?.["fn"] ?? ""}("${numbering.groups?.["key"] ?? ""}") }}`;
+	if (inner === "@index") return "{{ loop.index }}";
+	if (inner === "@count") return "{{ loop.length }}";
+	return null;
+};
+const MARKER_DEFECT_KINDS = [
+	"legacy_marker",
+	"unsupported_tag",
+	"unknown_filter",
+	"python_expression",
+	"bracket_index"
+];
 /** Bracket indexing (`items[0].name`), which no directive kind admits. */
 const BRACKET_INDEX_RE = /[[\]]/u;
+/** A legacy directive sigil at the head of an output marker. */
+const LEGACY_SHAPE_RE = /^[#/@]/u;
 /**
-* Name the authoring mistake behind one marker's inner text, or `null` when the
-* text is a recognized directive ({@link classifyMarker} accepts it) or an
-* unrecognizable span with no specific diagnosis (`{{my field}}`). The
-* recognized-directive check is what makes `DIRECTIVE_KINDS` the single
-* authority on which `{{#...}}` tokens exist: adding a directive to the grammar
-* stops it being reported here, with no list to update.
-*/
-const classifyMarkerDefect = (innerRaw) => {
-	const inner = innerRaw.trim();
-	if (classifyMarker(inner) !== null) return null;
-	if (DIRECTIVE_SHAPE_RE.test(inner)) return "unknown_directive";
-	if (BRACKET_INDEX_RE.test(inner)) return "bracket_index";
+* Arithmetic, a call, a quoted string or a Python literal inside `{{ }}`. A
+* span that merely holds a space (`{{my field}}`) is a mistyped path, not an
+* expression, and stays undiagnosed so the check reports it as an unreadable
+* marker rather than guessing at Python.
+*/
+const PYTHON_SHAPE_RE = /["'()+*/%]|\bNone\b|\bTrue\b|\bFalse\b/u;
+/**
+* Name the authoring mistake behind one marker's inner text, or `null` when
+* the text is a recognized directive ({@link classifyMarker} accepts it) or an
+* unrecognizable span with no specific diagnosis (`{{my field}}`).
+*/
+const classifyMarkerDefect = (innerRaw, form = "output") => {
+	const inner = normalizeMarkerInner(innerRaw).trim();
+	if (classifyMarker(inner, form) !== null) return null;
+	if (form === "statement") {
+		const tag = TAG_RE.exec(inner)?.groups?.["tag"];
+		if (tag === void 0) return null;
+		const legacy = legacyMarkerReplacement(inner);
+		if (legacy !== null) return {
+			kind: "legacy_marker",
+			construct: inner,
+			replacement: legacy
+		};
+		return {
+			kind: "unsupported_tag",
+			construct: tag
+		};
+	}
+	const legacy = legacyMarkerReplacement(inner);
+	if (legacy !== null) return {
+		kind: "legacy_marker",
+		construct: inner,
+		replacement: legacy
+	};
+	if (LEGACY_SHAPE_RE.test(inner)) return {
+		kind: "legacy_marker",
+		construct: inner
+	};
+	if (BRACKET_INDEX_RE.test(inner)) return {
+		kind: "bracket_index",
+		construct: inner
+	};
+	const pipe = inner.indexOf("|");
+	if (pipe !== -1) {
+		const chain = scanFilterChain(inner.slice(pipe));
+		if (chain !== null && "unknownFilter" in chain) return {
+			kind: "unknown_filter",
+			construct: chain.unknownFilter
+		};
+	}
+	const call = CALL_RE.exec(inner);
+	if (call) {
+		const name = call.groups?.["name"] ?? "";
+		if (!isFunctionName(name)) return {
+			kind: "python_expression",
+			construct: `${name}(...)`
+		};
+		return {
+			kind: "python_expression",
+			construct: inner
+		};
+	}
+	const head = (pipe === -1 ? inner : inner.slice(0, pipe)).trim();
+	if (head !== "" && !FIELD_PATH_RE.test(head) && PYTHON_SHAPE_RE.test(head)) return {
+		kind: "python_expression",
+		construct: head
+	};
 	return null;
 };
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
@@ -650,7 +1171,7 @@ const formatDate = (value, dateFormat) => {
 * value are left as-is (a visible authoring artifact, not a render error), so
 * a partially filled composite previews exactly as the fill engine renders it.
 */
-const renderComposite = (parts, format, partValues) => format.replace(markerPattern(), (raw, inner) => {
+const renderComposite = (parts, format, partValues) => replaceOutputMarkers(format, (raw, inner) => {
 	const key = inner.trim();
 	if (!parts.some((part) => part.key === key)) return raw;
 	return partValues[key] ?? raw;
@@ -732,8 +1253,10 @@ const serializePredicate = (node) => {
 	const operand = serializeOperand(node.operand);
 	if (node.op === "contains") {
 		const value = Array.isArray(node.value) ? node.value.join(",") : node.value ?? "";
-		return `${operand} contains ${serializeLiteral(value)}`;
+		return `${serializeLiteral(value)} in ${operand}`;
 	}
+	if (node.op === "is_not_empty") return `${operand} is defined`;
+	if (node.op === "is_empty") return `${operand} is not defined`;
 	return operand;
 };
 const serializeGroup = (group, top) => {
@@ -744,7 +1267,7 @@ const serializeGroup = (group, top) => {
 	}
 	if (parts.length === 0) return "";
 	const body = parts.length === 1 ? parts[0] ?? "" : parts.join(group.combinator === "and" ? " and " : " or ");
-	if (group.negated) return `!(${body})`;
+	if (group.negated) return `not (${body})`;
 	if (parts.length === 1) return body;
 	return top ? body : `(${body})`;
 };
@@ -770,7 +1293,7 @@ const serializeCondition = (node) => serializeNode(node, true);
 * an author instead types the opener in front of the first cell's text and the
 * closer behind the last cell's text:
 *
-*     | {{#each deliverables}}{{deliverables.item}} | {{deliverables.fee}}{{/each}} |
+*     | {% for d in deliverables %}{{ d.item }} | {{ d.fee }}{% endfor %} |
 *
 * Both placements mean the same thing — the `w:tr` is the unit — so this
 * module recognizes the row form purely from text, and the consumer rewrites
@@ -781,18 +1304,18 @@ const serializeCondition = (node) => serializeNode(node, true);
 * and neither can drift from the other's idea of what a row block is.
 */
 const CLOSER_OF = {
-	each: "endeach",
+	for: "endfor",
 	if: "endif"
 };
-const isOpenKind = (kind) => kind === "each" || kind === "if";
+const isOpenKind = (kind) => kind === "for" || kind === "if";
 /**
 * Block markers in one paragraph that do not pair inside it. A pair that opens
-* and closes within the paragraph is an inline span (`the Buyer{{#if x}} and
-* spouse{{/if}}`), which the inline engine already owns; only what is left
+* and closes within the paragraph is an inline span (`the Buyer{% if x %} and
+* spouse{% endif %}`), which the inline engine already owns; only what is left
 * over can reach across cells.
 *
-* A branch marker (`{{#elseif}}`, `{{#else}}`) counts as left over unless its
-* `{{#if}}` also closes in this paragraph. Only the opener and the closer of a
+* A branch marker (`{% elif %}`, `{% else %}`) counts as left over unless its
+* `{% if %}` also closes in this paragraph. Only the opener and the closer of a
 * row block are hoisted, so a branch marker stranded between them would stay
 * buried in the cell text: a false condition would drop the whole row and the
 * branch that should have rendered with it, and a true one would leave the
@@ -816,13 +1339,13 @@ const danglingBlockMarkers = (text) => {
 			});
 			continue;
 		}
-		if (kind === "endeach" || kind === "endif") {
+		if (kind === "endfor" || kind === "endif") {
 			const innermost = open.at(-1);
 			if (innermost && CLOSER_OF[innermost.kind] === kind) open.pop();
 			else dangling.push(marker);
 			continue;
 		}
-		if (kind === "elseif" || kind === "else") {
+		if (kind === "elif" || kind === "else") {
 			const innermost = open.at(-1);
 			if (innermost?.kind === "if") innermost.branches.push(marker);
 			else dangling.push(marker);
@@ -847,7 +1370,7 @@ const suffixesCell = (paragraphs, { marker, paragraphIndex }) => paragraphIndex
 * paragraph, they are a matching opener/closer pair, the closer sits in a LATER
 * cell than the opener, the opener prefixes its cell and the closer suffixes
 * its cell. Everything else — one half of a pair, two nested pairs, a stray
-* `{{#else}}`, a pair wrapping the paragraphs of a single cell — is left to the
+* `{% else %}`, a pair wrapping the paragraphs of a single cell — is left to the
 * engine's existing structure errors rather than guessed at.
 */
 const detectRowBlockPair = (cells) => {
@@ -878,7 +1401,7 @@ const detectRowBlockPair = (cells) => {
 *
 * Boolean conditions are evaluated through the canonical `@stll/conditions`
 * AST and its single evaluator, so view filters, AI-extraction gating, and
-* template `{{#if ...}}` conditionals share one set of operators and semantics
+* template `{% if ... %}` conditionals share one set of operators and semantics
 * and never drift apart. This module owns the template surface: the string
 * parser (`./parse`), the named-condition resolver, and the no-code builder
 * serializer (`./condition-builder`).
@@ -892,7 +1415,7 @@ const MAX_CONDITION_DEPTH = 50;
 /**
 * Normalize a fill-bag value into a `ConditionValue` the shared evaluator
 * accepts: arrays become string arrays (multi-select fields hold their options
-* as strings, so membership tests like `parties contains "guarantor"` work
+* as strings, so membership tests like `"guarantor" in parties` work
 * even when an element is numeric), primitives pass through, anything else is
 * stringified.
 */
@@ -905,7 +1428,7 @@ const toConditionValue = (raw) => {
 * Build the operand resolver for one evaluation. Only `path` operands need
 * resolving (the evaluator handles literals). A path is first matched against
 * the named conditions: a hit evaluates that condition's expression — so
-* `{{#if isCompany}}` and `{{#if isCompany and signed}}` both work — guarded
+* `{% if isCompany %}` and `{% if isCompany and signed %}` both work — guarded
 * against cycles (`resolved`) and runaway chains (`MAX_CONDITION_DEPTH`).
 * Otherwise the path resolves against the fill data.
 */
@@ -927,12 +1450,13 @@ const makeResolver = (data, namedConditions, resolved, depth) => {
 	return resolve;
 };
 /**
-* Evaluate a template `{{#if ...}}` condition. The expression is parsed into
+* Evaluate a template `{% if ... %}` condition. The expression is parsed into
 * the canonical `@stll/conditions` AST and evaluated by the shared evaluator.
 *
-* Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), `contains`,
-* truthiness, negation (`!`), logical operators (`and`, `or`), parentheses,
-* dotted paths, numeric underscores, and named-condition references.
+* Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), membership
+* (`"x" in path`), presence (`is defined` / `is not defined`), truthiness,
+* negation (`not`), logical operators (`and`, `or`), parentheses, dotted
+* paths, numeric underscores, and named-condition references.
 *
 * An empty or unparseable expression is `false` ("no condition" never gates a
 * branch true).
@@ -943,4 +1467,4 @@ const evaluateCondition = (expression, data, namedConditions, _resolved = /* @__
 	return evaluateCondition$1(node, makeResolver(data, namedConditions, _resolved, _depth));
 };
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, MARKER_DEFECT_KINDS, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };
+export { BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, FILTER_NAMES, LOOP_PROPERTIES, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, refPattern, referencedConditionPaths, renderComposite, renderDeterministicFieldValue, replaceOutputMarkers, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression };