@rhinostone/swig-jinja2 2.5.0

package/lib/tags/with.js

@@ -0,0 +1,121 @@
+/*!
+ * Jinja2 `{% with %}` tag.
+ *
+ * Jinja2 scoped-context region with optional named assignments:
+ *
+ *   {% with %}…{% endwith %}                     (new scope, shallow copy of _ctx)
+ *   {% with x = 1 %}…{% endwith %}               (x bound in the inner scope)
+ *   {% with x = 1, y = total + 1 %}…{% endwith %}  (multiple assignments)
+ *
+ * Each assignment is `<name> = <expr>`; the value expression is lowered
+ * through `parser.parseExpr`, so object literals, variable references,
+ * conditionals, and function calls all route through the same path. The
+ * assignments are collected into an object literal that the backend
+ * merges over a shallow copy of the outer context — so an assignment's
+ * value sees the enclosing scope (not its sibling assignments), and the
+ * inner bindings do not leak past `{% endwith %}`.
+ *
+ * Unlike Twig's `{% with {ctx} only %}`, Jinja2 has no `only` keyword and
+ * the region is never isolated — the outer context stays visible inside.
+ *
+ * Each assignment target is a bare identifier — dotted paths are rejected
+ * at parse time, and CVE-2023-25345 prototype-chain names are rejected
+ * before the binding lands (a quoted `"__proto__"` object key still sets
+ * the prototype in JS).
+ */
+
+var ir = require('@rhinostone/swig-core/lib/ir');
+var utils = require('@rhinostone/swig-core/lib/utils');
+var _dangerousProps = require('@rhinostone/swig-core/lib/security').dangerousProps;
+
+var lexer = require('../lexer');
+
+exports.ends = true;
+exports.block = false;
+
+/**
+ * Parse the `{% with %}` tag body. Collects zero or more
+ * comma-separated `<name> = <expr>` assignments into an object literal on
+ * `token.irExpr`. A bare `{% with %}` leaves `token.irExpr` undefined so
+ * the backend emits a shallow copy of `_ctx`.
+ *
+ * @param  {string} str    Tag body.
+ * @param  {number} line   Source line of the opening `{%`.
+ * @param  {object} parser The Jinja2 parser module (exposes `parseExpr`).
+ * @param  {object} types  Jinja2 lexer token-type enum.
+ * @param  {Array}  stack  Open-tag stack (parser.js manages the push).
+ * @param  {object} opts   Per-call options (honors `opts.filename`).
+ * @param  {object} swig   Swig instance (unused).
+ * @param  {object} token  In-progress TagToken.
+ * @return {boolean}       Always `true` on success. Throws otherwise.
+ */
+exports.parse = function (str, line, parser, types, stack, opts, swig, token) {
+  var tokens = lexer.read(utils.strip(str));
+  var pos = 0;
+
+  function peek() {
+    while (pos < tokens.length && tokens[pos].type === types.WHITESPACE) { pos += 1; }
+    return pos < tokens.length ? tokens[pos] : null;
+  }
+  function consume() {
+    var t = peek();
+    if (t) { pos += 1; }
+    return t;
+  }
+
+  var props = [];
+
+  // Bare `{% with %}` has no assignments — the leading peek() is null and
+  // the loop is skipped, leaving token.irExpr undefined.
+  if (peek()) {
+    while (true) {
+      var nameTok = consume();
+      if (!nameTok || nameTok.type !== types.VAR) {
+        utils.throwError('Expected variable name in "with" tag', line, opts.filename);
+      }
+      if (nameTok.match.indexOf('.') !== -1) {
+        utils.throwError('"with" assignment target "' + nameTok.match + '" must be a bare identifier', line, opts.filename);
+      }
+      if (_dangerousProps.indexOf(nameTok.match) !== -1) {
+        utils.throwError('Unsafe "with" assignment to "' + nameTok.match + '" is not allowed (CVE-2023-25345)', line, opts.filename);
+      }
+
+      var eqTok = consume();
+      if (!eqTok || eqTok.type !== types.ASSIGNMENT || eqTok.match !== '=') {
+        utils.throwError('Expected "=" after "' + nameTok.match + '" in "with" tag', line, opts.filename);
+      }
+
+      // Parse a single value expression from the cursor. parseExpr stops
+      // at the next COMMA (which is not part of an expression); the
+      // out-param reports how many slice tokens it consumed.
+      var posOut = {};
+      var valExpr = parser.parseExpr(tokens.slice(pos), {}, posOut);
+      pos += posOut.pos;
+      props.push(ir.objectProperty(ir.literal('string', nameTok.match), valExpr));
+
+      var next = peek();
+      if (!next) { break; }
+      if (next.type !== types.COMMA) {
+        utils.throwError('Expected "," between assignments in "with" tag', line, opts.filename);
+      }
+      consume();
+    }
+  }
+
+  token.irExpr = props.length ? ir.objectLiteral(props) : undefined;
+  return true;
+};
+
+/**
+ * Emit an IRWith node carrying the optional context object literal (the
+ * collected assignments) and the recursively-compiled body wrapped in
+ * IRLegacyJS. The region is never isolated; the backend's `With` branch
+ * merges the context over a shallow copy of `_ctx` for the body's lexical
+ * scope.
+ *
+ * @return {object} IRWith node.
+ */
+exports.compile = function (compiler, args, content, parents, options, blockName, token) {
+  var bodyJS = compiler(content, parents, options, blockName);
+  return ir.withStmt(token.irExpr, false, [ir.legacyJS(bodyJS)]);
+};

package/lib/tests/index.js

@@ -0,0 +1,213 @@
+/**
+ * @rhinostone/swig-jinja2 — built-in test runtime helpers.
+ *
+ * Jinja2 `is <name>` / `is not <name>` expressions lower to
+ * `_ext._test_<name>(subject, ...args)` at the IR layer. The Jinja2
+ * constructor registers each export here via `self.setExtension('_test_'
+ * + name, fn)`, which installs the helper onto the per-instance
+ * `_swig.extensions` map — so Path A (`new Jinja2().render(...)`) honors
+ * per-instance overrides without leaking cross-instance.
+ *
+ * Three tests (`defined`, `none`, `undefined`) are additionally
+ * special-cased in the parser when the subject is a VarRef with no args:
+ * they route through IRVarRefExists to preserve the defined/undefined
+ * signal that `emitVarRef` coerces to "". The helpers below still run for
+ * non-VarRef subjects (literals, BinaryOp, FnCall) where the coercion is
+ * not in play. See parser.js `parseExpression` IS/ISNOT branch.
+ *
+ * JS / Python impedance notes (documented divergences):
+ *   - No int/float distinction in JS, so `is integer` / `is float` are not
+ *     provided; use `is number`.
+ *   - `is sequence` is array-or-string (ordered, integer-indexed); a dict
+ *     is `is mapping` (not `is sequence`). `is iterable` covers arrays,
+ *     strings, and objects, matching the `{% for %}` iterate-by-key rule.
+ */
+
+/*!
+ * Array detection without depending on the runtime's Array.isArray (kept
+ * browser-safe and consistent with the other per-flavor test helpers).
+ * @private
+ */
+function isArr(v) {
+  return Object.prototype.toString.call(v) === '[object Array]';
+}
+
+/*!
+ * Finite-number guard shared by the numeric tests. @private
+ */
+function isNumber(v) {
+  return typeof v === 'number' && !isNaN(v);
+}
+
+/**
+ * `foo is defined` — true when the subject is not `undefined`. The
+ * VarRef-subject path bypasses this helper and uses IRVarRefExists.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['defined'] = function (v) {
+  return typeof v !== 'undefined';
+};
+
+/**
+ * `foo is undefined` — true when the subject is `undefined`. The
+ * VarRef-subject path bypasses this helper and uses `!IRVarRefExists`.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['undefined'] = function (v) {
+  return typeof v === 'undefined';
+};
+
+/**
+ * `foo is none` — true when the subject is `null` or `undefined` (Python
+ * `None`). The VarRef-subject path bypasses this helper.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['none'] = function (v) {
+  return v === null || typeof v === 'undefined';
+};
+
+/**
+ * `foo is boolean` — true for a JS boolean.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['boolean'] = function (v) {
+  return typeof v === 'boolean';
+};
+
+/**
+ * `foo is number` — true for a finite number.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['number'] = function (v) {
+  return isNumber(v);
+};
+
+/**
+ * `foo is string` — true for a string.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['string'] = function (v) {
+  return typeof v === 'string';
+};
+
+/**
+ * `foo is mapping` — true for a plain object (a dict), excluding arrays
+ * and null.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['mapping'] = function (v) {
+  return typeof v === 'object' && v !== null && !isArr(v);
+};
+
+/**
+ * `foo is sequence` — true for an array or string (ordered,
+ * integer-indexed). A dict is `mapping`, not `sequence`.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['sequence'] = function (v) {
+  return isArr(v) || typeof v === 'string';
+};
+
+/**
+ * `foo is iterable` — true for arrays, strings, and non-null objects
+ * (mirrors the `{% for %}` rule that dicts iterate by key).
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['iterable'] = function (v) {
+  if (v === null || typeof v === 'undefined') { return false; }
+  if (isArr(v) || typeof v === 'string') { return true; }
+  return typeof v === 'object';
+};
+
+/**
+ * `foo is callable` — true for a function.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['callable'] = function (v) {
+  return typeof v === 'function';
+};
+
+/**
+ * `foo is sameas(bar)` — strict identity check (`foo === bar`).
+ *
+ * @param  {*} v
+ * @param  {*} other
+ * @return {boolean}
+ */
+exports['sameas'] = function (v, other) {
+  return v === other;
+};
+
+/**
+ * `foo is lower` — true when the subject is a string equal to its own
+ * lowercase form.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['lower'] = function (v) {
+  return typeof v === 'string' && v === v.toLowerCase();
+};
+
+/**
+ * `foo is upper` — true when the subject is a string equal to its own
+ * uppercase form.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['upper'] = function (v) {
+  return typeof v === 'string' && v === v.toUpperCase();
+};
+
+/**
+ * `n is even` — true for numbers whose remainder mod 2 is zero.
+ *
+ * @param  {number} v
+ * @return {boolean}
+ */
+exports['even'] = function (v) {
+  return isNumber(v) && v % 2 === 0;
+};
+
+/**
+ * `n is odd` — true for numbers whose remainder mod 2 is non-zero.
+ *
+ * @param  {number} v
+ * @return {boolean}
+ */
+exports['odd'] = function (v) {
+  return isNumber(v) && v % 2 !== 0;
+};
+
+/**
+ * `n is divisibleby(m)` — true when `m` is a non-zero number and `n % m
+ * === 0`.
+ *
+ * @param  {number} v
+ * @param  {number} n
+ * @return {boolean}
+ */
+exports['divisibleby'] = function (v, n) {
+  return isNumber(v) && isNumber(n) && n !== 0 && v % n === 0;
+};

package/lib/tokentypes.js

@@ -0,0 +1,89 @@
+/**
+ * Jinja2 lexer token type enum — the contract between the Jinja2 lexer and
+ * the Jinja2 parser in @rhinostone/swig-jinja2.
+ *
+ * Numeric IDs in the shared range (0–25, 100) mirror
+ * @rhinostone/swig-core/lib/tokentypes by design: Jinja2 and native Swig
+ * lower to the same swig-core IR, and aligning the IDs keeps shared
+ * consumers (e.g. CVE-2023-25345 `_dangerousProps` enforcement) flavor-
+ * agnostic. The Jinja2 parser is its own module — it does not inherit
+ * from swig-core's TokenParser — but the cognitive overhead of re-mapping
+ * IDs across flavors is not worth the freedom.
+ *
+ * Jinja2-only IDs (30+) are reserved here so later commits can add lexer
+ * rules without renumbering. Jinja2 has no range (`..`), null-coalescing
+ * (`??`), ternary (`?:`), or `#{}` string interpolation operators, so the
+ * Jinja2-only block is smaller than Twig's: `~` concat, `**` power, `//`
+ * floor-division, and the `is` / `is not` test keywords.
+ *
+ * @readonly
+ * @enum {number}
+ */
+module.exports = {
+  /** Whitespace */
+  WHITESPACE: 0,
+  /** Plain string literal */
+  STRING: 1,
+  /** Variable filter call with arguments — `|name(...)` */
+  FILTER: 2,
+  /** Variable filter call with no arguments — `|name` */
+  FILTEREMPTY: 3,
+  /** Function call with arguments — `name(...)` */
+  FUNCTION: 4,
+  /** Function call with no arguments — `name()` */
+  FUNCTIONEMPTY: 5,
+  /** Open parenthesis */
+  PARENOPEN: 6,
+  /** Close parenthesis */
+  PARENCLOSE: 7,
+  /** Comma */
+  COMMA: 8,
+  /** Variable identifier */
+  VAR: 9,
+  /** Numeric literal */
+  NUMBER: 10,
+  /** Math operator (+, -, *, /, %) */
+  OPERATOR: 11,
+  /** Open square bracket */
+  BRACKETOPEN: 12,
+  /** Close square bracket */
+  BRACKETCLOSE: 13,
+  /** Dot-key accessor — `.key` */
+  DOTKEY: 14,
+  /** Open square bracket at the start of an array literal */
+  ARRAYOPEN: 15,
+  /** Open curly brace */
+  CURLYOPEN: 17,
+  /** Close curly brace */
+  CURLYCLOSE: 18,
+  /** Colon — object-literal key/value separator, and slice subscript */
+  COLON: 19,
+  /** JavaScript-valid comparator (==, !=, <=, etc.) */
+  COMPARATOR: 20,
+  /** Boolean logic (`and`, `or`, `&&`, `||`) */
+  LOGIC: 21,
+  /** Boolean negation (`not`, `!`) */
+  NOT: 22,
+  /** Boolean literal (`true`, `false`) */
+  BOOL: 23,
+  /** Variable assignment (`=`, `+=`, `-=`, `*=`, `/=`) */
+  ASSIGNMENT: 24,
+  /** Method call open — internal */
+  METHODOPEN: 25,
+
+  /* ---- Jinja2-only token IDs (reserved; rules land in later commits) ---- */
+
+  /** Jinja2 string-concatenation operator — `~` */
+  TILDE: 30,
+  /** Jinja2 exponentiation operator — `**` */
+  POWER: 31,
+  /** Jinja2 floor-division operator — `//` */
+  FLOORDIV: 32,
+  /** Jinja2 test operator — `is` */
+  IS: 33,
+  /** Jinja2 negated test operator — `is not` */
+  ISNOT: 34,
+
+  /** Unknown token */
+  UNKNOWN: 100
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@rhinostone/swig-jinja2",
+  "version": "2.5.0",
+  "description": "Jinja2-syntax frontend for the @rhinostone/swig-core template engine. Part of the @rhinostone/swig multi-flavor family.",
+  "keywords": [
+    "template",
+    "templating",
+    "jinja2",
+    "jinja",
+    "swig",
+    "swig-jinja2",
+    "frontend"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gina-io/swig.git",
+    "directory": "packages/swig-jinja2"
+  },
+  "author": "Rhinostone <contact@gina.io>",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "engines": {
+    "node": ">=12"
+  },
+  "peerDependencies": {
+    "@rhinostone/swig-core": "2.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}