@mrhenry/twig-parser 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1 +1,20 @@
 # Changelog
+
+## 0.1.2 (2026-09-26)
+
+ * Added the sandbox `render_sandboxed` function to the core function set, so it
+   can be parsed (its `output_strategy` argument is validated at compile time).
+
+ * Signature capture now defaults to off. Signature capture backs lossless
+   `Node#serialize` (it lets a node detect whether its subtree was mutated) and
+   hashes the whole tree during parsing, so it is now opt-in via
+   `{ captureSignatures: true }`. Parsers that mutate and serialize the AST
+   must now pass it; compile-only callers (like `@mrhenry/twig-js`) pay nothing.
+ * Signature computation now hashes incrementally instead of building an
+   intermediate string per node, and captures the whole tree in a single walk.
+
+ * Bounded parser recursion. `parseExpression` and `subparse` now track their
+   own depth (cap `256`) and throw a `SyntaxError` — "Expression is too deeply
+   nested." / "Template nesting is too deep." — instead of overflowing the call
+   stack. Previously a crafted template of nested `not not …`, `((( … )))`,
+   `[[[ … ]]]` or `{% if %}` tags crashed the process with a `RangeError`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mrhenry/twig-parser",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"license": "MIT",
 	"type": "module",
 	"main": "src/index.js",
@@ -8,6 +8,6 @@
 		".": "./src/index.js"
 	},
 	"dependencies": {
-		"@mrhenry/twig-tokenizer": "^0.1.1"
+		"@mrhenry/twig-tokenizer": "^0.1.2"
 	}
 }

package/src/callables.js

@@ -89,6 +89,7 @@ export const CORE_FUNCTION_NAMES = [
 	'enum_cases',
 	'enum',
 	'template_from_string',
+	'render_sandboxed',
 ];
 
 /**

package/src/expression-parser.js

@@ -21,6 +21,18 @@ import { ArrayExpression } from './array-expression.js';
 /** Name pattern used to accept word-operators as variable names. */
 const REGULAR_EXPRESSION_NAME = /^[a-zA-Z_\u007f-\uffff][a-zA-Z0-9_\u007f-\uffff]*$/;
 
+/**
+ * The deepest expression nesting the precedence-climbing parser accepts before
+ * it refuses to recurse further. Prefix chains (`not not …`, `---…`), grouped
+ * expressions and nested sequences/mappings all recurse through
+ * {@link ExpressionParser.parseExpression}; without a bound a crafted template
+ * would grow the call stack until it overflows the process.
+ *
+ * Well below the point at which a real stack overflow occurs, so the failure is
+ * a controlled {@link SyntaxError} rather than a `RangeError`.
+ */
+const MAX_EXPRESSION_DEPTH = 256;
+
 /**
  * Binary operator metadata: precedence and associativity.
  *
@@ -124,6 +136,8 @@ export class ExpressionParser {
 	constructor(parser) {
 		/** @type {import('./parser.js').Parser} */
 		this.parser = parser;
+		/** @type {number} Current recursion depth of {@link parseExpression}. */
+		this.expressionDepth = 0;
 	}
 
 	/**
@@ -147,6 +161,29 @@ export class ExpressionParser {
 	 * @returns {Node} The parsed expression node.
 	 */
 	parseExpression(precedence = 0) {
+		if (this.expressionDepth >= MAX_EXPRESSION_DEPTH) {
+			const token = this.current();
+			throw new SyntaxError(
+				'Expression is too deeply nested.',
+				token.getLine(),
+				this.getStream().getSourceContext(),
+			);
+		}
+		this.expressionDepth += 1;
+		try {
+			return this.parseExpressionInternal(precedence);
+		} finally {
+			this.expressionDepth -= 1;
+		}
+	}
+
+	/**
+	 * The unguarded recursive body of {@link parseExpression}.
+	 *
+	 * @param {number} precedence The minimum precedence of infix operators to consume.
+	 * @returns {Node} The parsed expression node.
+	 */
+	parseExpressionInternal(precedence = 0) {
 		const stream = this.getStream();
 		const token = this.current();
 		let expression;

package/src/node.js

@@ -349,43 +349,85 @@ export function n(type, children = {}, attributes = {}, lineNumber = 0, tag = nu
 }
 
 /**
- * A tiny FNV-1a hash, used to compare node subtrees cheaply.
+ * A streaming FNV-1a hasher, used to compare node subtrees cheaply.
  *
- * @param {string} text
- * @returns {string} A base-36 digest.
+ * Hashing is incremental so signatures never build intermediate strings: each
+ * code unit is folded into the running hash as it is visited.
  */
-function fnv1a(text) {
-	let hash = 0x811c9dc5;
-	for (let i = 0; i < text.length; i += 1) {
-		hash ^= text.charCodeAt(i);
-		hash = Math.imul(hash, 0x01000193) >>> 0;
+class Fnv1a {
+	constructor() {
+		/** @type {number} */
+		this.hash = 0x811c9dc5;
+	}
+
+	/**
+	 * @param {number} codeUnit
+	 */
+	byte(codeUnit) {
+		this.hash ^= codeUnit;
+		this.hash = Math.imul(this.hash, 0x01000193) >>> 0;
+	}
+
+	/**
+	 * @param {string} text
+	 */
+	str(text) {
+		for (let i = 0; i < text.length; i += 1) {
+			this.byte(text.charCodeAt(i));
+		}
+	}
+
+	/**
+	 * @returns {string} A base-36 digest.
+	 */
+	digest() {
+		return this.hash.toString(36);
 	}
-	return hash.toString(36);
 }
 
 /**
- * Computes a content signature for a value contained in a node (children or
- * attributes). Nodes are folded in via their own content signature.
+ * Folds a value contained in a node (children or attributes) into `hasher`.
+ * Nodes are folded in via their own content signature.
  *
+ * @param {Fnv1a} hasher
  * @param {unknown} value
  * @param {WeakMap<Node, string>} cache
- * @returns {string}
+ * @param {'originalSignature'|'currentSignature'|null} field The node property to capture the signature on, if any.
  */
-function valueSignature(value, cache) {
+function hashValue(hasher, value, cache, field) {
 	if (value instanceof Node) {
-		return `N${computeSignature(value, cache)}`;
+		hasher.str('N');
+		hasher.str(computeSignature(value, cache, field));
+		return;
 	}
 	if (Array.isArray(value)) {
-		return `[${value.map((item) => valueSignature(item, cache)).join(',')}]`;
+		hasher.str('[');
+		for (let i = 0; i < value.length; i += 1) {
+			if (i > 0) {
+				hasher.str(',');
+			}
+			hashValue(hasher, value[i], cache, field);
+		}
+		hasher.str(']');
+		return;
 	}
 	if (value !== null && typeof value === 'object') {
 		const object = /** @type {Record<string, unknown>} */ (value);
-		return `{${Object.keys(object)
-			.sort()
-			.map((key) => `${key}:${valueSignature(object[key], cache)}`)
-			.join(',')}}`;
+		hasher.str('{');
+		const keys = Object.keys(object).sort();
+		for (let i = 0; i < keys.length; i += 1) {
+			const key = keys[i];
+			if (i > 0) {
+				hasher.str(',');
+			}
+			hasher.str(key);
+			hasher.str(':');
+			hashValue(hasher, object[key], cache, field);
+		}
+		hasher.str('}');
+		return;
 	}
-	return String(value);
+	hasher.str(String(value));
 }
 
 /**
@@ -393,58 +435,42 @@ function valueSignature(value, cache) {
  *
  * @param {Node} node
  * @param {WeakMap<Node, string>} cache
+ * @param {'originalSignature'|'currentSignature'|null} [field] When set, the
+ *   signature is also stored on this node property, so a single traversal
+ *   captures the whole tree.
  * @returns {string}
  */
-export function computeSignature(node, cache) {
+export function computeSignature(node, cache, field = null) {
 	const cached = cache.get(node);
 	if (cached !== undefined) {
 		return cached;
 	}
-	let material = `${node.type}\u0000${node.tag ?? ''}\u0000${node.explicitParentheses}`;
+	const hasher = new Fnv1a();
+	hasher.str(node.type);
+	hasher.byte(0);
+	hasher.str(node.tag ?? '');
+	hasher.byte(0);
+	hasher.str(String(node.explicitParentheses));
 	for (const key of Object.keys(node.attributes).sort()) {
-		material += `\u0001${key}=${valueSignature(node.attributes[key], cache)}`;
+		hasher.byte(1);
+		hasher.str(key);
+		hasher.str('=');
+		hashValue(hasher, node.attributes[key], cache, field);
 	}
 	for (const key of Object.keys(node.children).sort()) {
-		material += `\u0002${key}=${valueSignature(node.children[key], cache)}`;
+		hasher.byte(2);
+		hasher.str(key);
+		hasher.str('=');
+		hashValue(hasher, node.children[key], cache, field);
 	}
-	const signature = fnv1a(material);
+	const signature = hasher.digest();
 	cache.set(node, signature);
-	return signature;
-}
-
-/**
- * Visits every node reachable from `node` through children and attributes.
- *
- * @param {Node} node
- * @param {(node: Node) => void} callback
- * @param {WeakSet<Node>} [seen]
- */
-function walkNodes(node, callback, seen = new WeakSet()) {
-	if (seen.has(node)) {
-		return;
-	}
-	seen.add(node);
-	callback(node);
-	/** @param {unknown} value */
-	const visit = (value) => {
-		if (value instanceof Node) {
-			walkNodes(value, callback, seen);
-		} else if (Array.isArray(value)) {
-			for (const item of value) {
-				visit(item);
-			}
-		} else if (value !== null && typeof value === 'object') {
-			for (const item of Object.values(/** @type {Record<string, unknown>} */ (value))) {
-				visit(item);
-			}
-		}
-	};
-	for (const value of Object.values(node.children)) {
-		visit(value);
-	}
-	for (const value of Object.values(node.attributes)) {
-		visit(value);
+	if (field === 'originalSignature') {
+		node.originalSignature = signature;
+	} else if (field === 'currentSignature') {
+		node.currentSignature = signature;
 	}
+	return signature;
 }
 
 /**
@@ -453,11 +479,7 @@ function walkNodes(node, callback, seen = new WeakSet()) {
  * @param {Node} root
  */
 export function captureSignatures(root) {
-	const cache = new WeakMap();
-	computeSignature(root, cache);
-	walkNodes(root, (node) => {
-		node.originalSignature = cache.get(node) ?? null;
-	});
+	computeSignature(root, new WeakMap(), 'originalSignature');
 }
 
 /**
@@ -466,9 +488,5 @@ export function captureSignatures(root) {
  * @param {Node} root
  */
 export function refreshSignatures(root) {
-	const cache = new WeakMap();
-	computeSignature(root, cache);
-	walkNodes(root, (node) => {
-		node.currentSignature = cache.get(node) ?? null;
-	});
+	computeSignature(root, new WeakMap(), 'currentSignature');
 }

package/src/parser.js

@@ -40,12 +40,29 @@ import {
  * @property {(name: string) => CallableDescriptor|null} getTest
  */
 
+/**
+ * Parser options.
+ *
+ * @typedef {object} ParserOptions
+ * @property {boolean} [captureSignatures] Capture original content signatures
+ *   for lossless {@link Node#serialize} support (default false). Set to true
+ *   before parsing when the resulting AST will be mutated and serialized.
+ */
+
 /** Name pattern for word-operators used as variable names. */
 const REGULAR_EXPRESSION_NAME = /^[a-zA-Z_\u007f-\uffff][a-zA-Z0-9_\u007f-\uffff]*$/;
 
 /** Reserved literal words that cannot be assigned to. */
 const RESERVED_WORDS = new Set(['true', 'TRUE', 'false', 'FALSE', 'none', 'NONE', 'null', 'NULL']);
 
+/**
+ * The deepest tag nesting {@link Parser.subparse} accepts. Every block tag
+ * (`if`, `for`, `block`, `macro`, `embed`, …) recurses back into `subparse`, so
+ * without a bound a template of nested `{% if %}` tags would overflow the call
+ * stack. The limit fails with a controlled {@link SyntaxError} first.
+ */
+const MAX_SUBPARSE_DEPTH = 256;
+
 /**
  * An imported macro symbol.
  *
@@ -81,10 +98,21 @@ const RESERVED_WORDS = new Set(['true', 'TRUE', 'false', 'FALSE', 'none', 'NONE'
 export class Parser {
 	/**
 	 * @param {ParserEnvironment} environment The parser environment.
+	 * @param {ParserOptions} [options] Parser options.
 	 */
-	constructor(environment) {
+	constructor(environment, options = {}) {
 		/** @type {ParserEnvironment} */
 		this.environment = environment;
+		/**
+		 * Whether to capture each node's original content signature while
+		 * parsing. Signatures back lossless {@link Node#serialize} (they let a
+		 * node detect whether its subtree was mutated); capturing them hashes
+		 * the whole tree during parsing, so they are opt-in for consumers that
+		 * mutate and serialize the AST.
+		 *
+		 * @type {boolean}
+		 */
+		this.captureSignatures = options.captureSignatures === true;
 		/** @type {ExpressionParser} */
 		this.expressionParser = new ExpressionParser(this);
 		/** @type {TokenStream|null} */
@@ -117,6 +145,8 @@ export class Parser {
 		this.macroDepth = 0;
 		/** @type {number} */
 		this.capturingNodeDepth = 0;
+		/** @type {number} Current recursion depth of {@link Parser.subparse}. */
+		this.subparseDepth = 0;
 		/** @type {Array<Node|null>} */
 		this.tagStack = [];
 		/** @type {string|null} */
@@ -242,7 +272,9 @@ export class Parser {
 		module.setAttribute('trailing', stream.getCurrent().leading ?? '');
 
 		this.correctnessCheck(module);
-		captureSignatures(module);
+		if (this.captureSignatures) {
+			captureSignatures(module);
+		}
 
 		// restore the previous state so an enclosing (outer) parse can resume
 		const previous = this.saveStack.pop();
@@ -275,6 +307,30 @@ export class Parser {
 	 * @returns {Node} The parsed body (single node or a `nodes` list).
 	 */
 	subparse(test = null, dropNeedle = false) {
+		if (this.subparseDepth >= MAX_SUBPARSE_DEPTH) {
+			const token = this.getCurrentToken();
+			throw new SyntaxError(
+				'Template nesting is too deep.',
+				token.getLine(),
+				this.getStream().getSourceContext(),
+			);
+		}
+		this.subparseDepth += 1;
+		try {
+			return this.parseUntil(test, dropNeedle);
+		} finally {
+			this.subparseDepth -= 1;
+		}
+	}
+
+	/**
+	 * The unguarded recursive body of {@link subparse}.
+	 *
+	 * @param {((token: Token) => boolean)|null} [test]
+	 * @param {boolean} [dropNeedle]
+	 * @returns {Node} The parsed body (single node or a `nodes` list).
+	 */
+	parseUntil(test = null, dropNeedle = false) {
 		const stream = this.getStream();
 		const lineNumber = this.getCurrentToken().getLine();
 		/** @type {Node[]} */