@rhinostone/swig 2.4.3 → 2.5.0

package/HISTORY.md

@@ -1,3 +1,8 @@
+[2.5.0](https://github.com/gina-io/swig/tree/v2.5.0) / 2026-05-27
+-----------------------------------------------------------------
+
+* **Added** @rhinostone/swig-jinja2 — a Python Jinja2-syntax frontend on the shared swig-core engine (13 tags, 39 filters, 16 is-tests, async loader support, autoescape and CVE-2023-25345 guards inherited from swig-core). Releases in lockstep with @rhinostone/swig, @rhinostone/swig-core, and @rhinostone/swig-twig.
+
 [2.4.3](https://github.com/gina-io/swig/tree/v2.4.3) / 2026-05-22
 -----------------------------------------------------------------
 
@@ -57,7 +62,7 @@
 [2.0.0](https://github.com/gina-io/swig/tree/v2.0.0) / 2026-05-06
 -----------------------------------------------------------------
 
-* **Fixed** Refreshed stale external URL references across documentation surfaces from the 2026-04-13 link-health audit (gina-io/gina#18). `README.md`, `packages/swig-core/README.md`, `packages/swig-twig/README.md` — swapped `www.npmjs.org` for the canonical `www.npmjs.com` in the NPM badges (the old `.org` form now redirects). `README.md` — rewrote the "Swig v0.x → v1.x migration notes" bullet, since the `paularmstrong/swig/wiki/Migrating-from-...` page was deleted upstream (302s to repo root). `HISTORY.md` — dropped the three dead upstream-wiki links around the v1.0.0 / v1.0.0-pre1 entries; the breaking-change prose stays intact. `browser/comments.js` — updated the DateZ `@license` URL from `TomoUniversalis/DateZ` to `ocrybit/DateZ` (the upstream GitHub user was renamed). `packages/swig-core/lib/dateformatter.js` — dropped the dead `http://tomouniversalis.com` parenthetical from the DateZ copyright comment (domain NXDOMAINs). `.changes/v1.0.0.md` and `.changes/v1.0.0-pre1.md` synced to match the rewritten `HISTORY.md` lines so future `changie merge` runs stay idempotent. Documentation and comment-only; no runtime or API change.
+* **Fixed** Refreshed stale external URL references across documentation surfaces from the 2026-04-13 link-health audit (gina-io/gina#18). `README.md`, `packages/swig-core/README.md`, `packages/swig-twig/README.md` — swapped `www.npmjs.org` for the canonical `www.npmjs.com` in the NPM badges (the old `.org` form now redirects). `README.md` — rewrote the "Swig v0.x → v1.x migration notes" bullet, since the `paularmstrong/swig/wiki/Migrating-from-...` page was deleted upstream (302s to repo root). `HISTORY.md` — dropped the three dead upstream-wiki links around the v1.0.0 / v1.0.0-pre1 entries; the breaking-change prose stays intact. `browser/comments.js` — updated the DateZ `@license` URL from `TomoUniversalis/DateZ` to `ocrybit/DateZ` (the upstream GitHub user was renamed). `packages/swig-core/lib/dateformatter.js` — dropped the dead `tomouniversalis.com` parenthetical from the DateZ copyright comment (domain NXDOMAINs). `.changes/v1.0.0.md` and `.changes/v1.0.0-pre1.md` synced to match the rewritten `HISTORY.md` lines so future `changie merge` runs stay idempotent. Documentation and comment-only; no runtime or API change.
 
 * **Changed** `2.0.0` stable. Multi-flavor architecture (introduced across `2.0.0-alpha.1` through `2.0.0-alpha.5`) is the production-ready cut. No functional or API changes since `2.0.0-alpha.5`; the `alpha.6`–`alpha.8` cycle was metadata republishes plus removal of the soft-deprecated `exports.parse` Path B wrapper from `@rhinostone/swig-twig`. IR ABI is stable from this release onward; cross-package dependencies pin exact versions and frontends + core release in lockstep. README messaging refreshed across all three packages to reflect production-ready status; package descriptions cleaned of historical internal-tracking references.
 

package/README.md

@@ -64,7 +64,7 @@ For Twig syntax:
 Documentation
 -------------
 
-User-facing documentation lives in the Gina Docusaurus site under the [Swig Template Engine](https://gina.io/docs/swig) section, maintained in [gina-io/docs](https://github.com/gina-io/docs) at `docs/swig/`. The JSDoc blocks in `lib/swig.js`, `lib/filters.js`, `lib/tags/`, and `lib/loaders/` remain the canonical source-of-truth for the public API and are mirrored into the Docusaurus pages.
+User-facing documentation lives in the Gina Docusaurus site under the [Swig Template Engine](https://gina.io/docs/swig) section, maintained in [gina-io/docs](https://github.com/gina-io/docs) at `docs/templating/swig/`. The JSDoc blocks in `lib/swig.js`, `lib/filters.js`, `lib/tags/`, and `lib/loaders/` remain the canonical source-of-truth for the public API and are mirrored into the Docusaurus pages.
 
 Basic Example
 -------------

package/ROADMAP.md

@@ -15,13 +15,18 @@ _No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upco
 | Status | Item |
 | --- | --- |
 | Planned | Async parse path for dynamic targets — full support for `{% extends parent_var %}`, `{% include user_template %}`, and runtime-resolved `import` / `from` paths on the async-codegen branch. Static-target async dispatch shipped in 2.2.0; dynamic-target support is on hold pending consumer demand. |
-| Planned | Ship Jinja2 and Django frontends as additional `@rhinostone/swig-*` packages. On demand — when there's concrete user demand. |
+| Planned | Ship a Django frontend as an additional `@rhinostone/swig-*` package. On demand — when there's concrete user demand. (The Jinja2 frontend shipped in `2.5.0`.) |
 | Planned | Test framework migration. Replace mocha 1.x + expect.js with `node:test` + `node:assert/strict`, swap mocha-phantomjs for a modern browser-test harness, swap blanket for `c8`. (The Node engines bump is upstream-driven by gina and is being treated as done.) |
 
 ---
 
 ## Completed
 
+### v2.5.0 (May 2026)
+
+- Added `@rhinostone/swig-jinja2`, a Python Jinja2-syntax frontend on the shared `@rhinostone/swig-core` engine — the third dialect in the multi-flavor family alongside native swig and `@rhinostone/swig-twig`. Ships 13 tags (`set`, `if` / `elif` / `else`, `for` with `else`, `block`, `extends`, `include`, `macro`, `import`, `from`, `raw`, `filter`, `with`, `autoescape`), 39 filters, and 16 `is` tests, plus the `**` / `//` / `~` operators, inline-if, Python slicing, and `{{- … -}}` whitespace control. Async loader support via `renderFileAsync` / `compileFileAsync`. Autoescape and the CVE-2023-25345 guards are inherited from `@rhinostone/swig-core`. Every filter and is-test was cross-checked against Python Jinja2 3.x; the behavioural differences (where the JavaScript runtime diverges from CPython) and the explicit non-goals (no sandboxed rendering, `{% call %}` / `{% do %}` / `{% trans %}`, the `map` / `select` filter family, macro kwargs) are documented in the Jinja2 templating guide.
+- All four packages (`@rhinostone/swig`, `@rhinostone/swig-core`, `@rhinostone/swig-twig`, `@rhinostone/swig-jinja2`) released in lockstep at `2.5.0`. `@rhinostone/swig-core` gained additive `slice` and `coerceOutput` runtime helpers consumed by the Jinja2 frontend; native swig and Twig are functionally unchanged.
+
 ### v2.4.3 (May 2026)
 
 - Fixed native `import` leaking an imported file's own import aliases into the importing template's scope. The `{% import %}` carry-through added in `2.4.1` emitted those nested imports bare into the caller's context, where the leaked alias could clobber a same-named caller variable, corrupt a macro when the caller later reassigned that name (macros read the live context at call time), or cascade across import depth. The nested imports are now re-homed under the importing alias and kept local to the file that declares them — matching `@rhinostone/swig-twig`'s scoping and the Jinja2/Twig import contract. Macros still resolve their own file's imports at call time.

package/dist/swig.js

@@ -1,4 +1,4 @@
-/*! Swig v2.4.3 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
+/*! Swig v2.5.0 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
 /*! DateZ (c) 2011 Tomo Universalis | @license https://github.com/ocrybit/DateZ/blob/master/LISENCE */
 (() => {
   var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -139,6 +139,68 @@
         }
         return out;
       };
+      exports.slice = function(obj, start, stop, step) {
+        var isString = typeof obj === "string", length, lower, upper, s, e, result = [], i;
+        function toInt(n) {
+          n = Number(n);
+          if (isNaN(n)) {
+            return NaN;
+          }
+          return n < 0 ? Math.ceil(n) : Math.floor(n);
+        }
+        function clamp(v, dflt) {
+          if (v === null || v === void 0) {
+            return dflt;
+          }
+          v = toInt(v);
+          if (isNaN(v)) {
+            return dflt;
+          }
+          if (v < 0) {
+            v += length;
+            if (v < lower) {
+              v = lower;
+            }
+          } else if (v > upper) {
+            v = upper;
+          }
+          return v;
+        }
+        if (obj === null || obj === void 0 || typeof obj.length !== "number") {
+          return isString ? "" : [];
+        }
+        length = obj.length;
+        if (step === null || step === void 0) {
+          step = 1;
+        } else {
+          step = toInt(step);
+          if (isNaN(step) || step === 0) {
+            step = 1;
+          }
+        }
+        if (step < 0) {
+          lower = -1;
+          upper = length - 1;
+        } else {
+          lower = 0;
+          upper = length;
+        }
+        s = clamp(start, step < 0 ? upper : lower);
+        e = clamp(stop, step < 0 ? lower : upper);
+        if (step > 0) {
+          for (i = s; i < e; i += step) {
+            result.push(obj[i]);
+          }
+        } else {
+          for (i = s; i > e; i += step) {
+            result.push(obj[i]);
+          }
+        }
+        return isString ? result.join("") : result;
+      };
+      exports.coerceOutput = function(v) {
+        return v === null || v === void 0 ? "" : v;
+      };
     }
   });
 
@@ -1366,7 +1428,22 @@
                 return;
               }
             });
-            out += "(function () {\n  var __l = " + forIterable + ', __len = (_utils.isArray(__l) || typeof __l === "string") ? __l.length : _utils.keys(__l).length;\n  if (!__l) { return; }\n    var ' + ctxloopcache + " = { loop: " + ctxloop + ", " + forVal + ": " + ctx + forVal + ", " + forKey + ": " + ctx + forKey + " };\n    " + ctxloop + " = { first: false, index: 1, index0: 0, revindex: __len, revindex0: __len - 1, length: __len, last: false };\n  _utils.each(__l, function (" + forVal + ", " + forKey + ") {\n    " + ctx + forVal + " = " + forVal + ";\n    " + ctx + forKey + " = " + forKey + ";\n    " + ctxloop + ".key = " + forKey + ";\n    " + ctxloop + ".first = (" + ctxloop + ".index0 === 0);\n    " + ctxloop + ".last = (" + ctxloop + ".revindex0 === 0);\n    " + forBodyJS + "    " + ctxloop + ".index += 1; " + ctxloop + ".index0 += 1; " + ctxloop + ".revindex -= 1; " + ctxloop + ".revindex0 -= 1;\n  });\n  " + ctxloop + " = " + ctxloopcache + ".loop;\n  " + ctx + forVal + " = " + ctxloopcache + "." + forVal + ";\n  " + ctx + forKey + " = " + ctxloopcache + "." + forKey + ";\n  " + ctxloopcache + " = undefined;\n})();\n";
+            var forEmptyCheck = "  if (!__l) { return; }\n";
+            if (node.emptyBody) {
+              var forEmptyJS = "";
+              utils.each(node.emptyBody, function(b) {
+                if (b.type === "LegacyJS") {
+                  forEmptyJS += b.js;
+                  return;
+                }
+                if (b.type === "Text" || b.type === "Raw") {
+                  forEmptyJS += '_output += "' + escapeTextValue(b.value) + '";\n';
+                  return;
+                }
+              });
+              forEmptyCheck = "  if (!__l || !__len) {\n" + forEmptyJS + "  return;\n  }\n";
+            }
+            out += "(function () {\n  var __l = " + forIterable + ', __len = (_utils.isArray(__l) || typeof __l === "string") ? __l.length : _utils.keys(__l).length;\n' + forEmptyCheck + "    var " + ctxloopcache + " = { loop: " + ctxloop + ", " + forVal + ": " + ctx + forVal + ", " + forKey + ": " + ctx + forKey + " };\n    " + ctxloop + " = { first: false, index: 1, index0: 0, revindex: __len, revindex0: __len - 1, length: __len, last: false };\n  _utils.each(__l, function (" + forVal + ", " + forKey + ") {\n    " + ctx + forVal + " = " + forVal + ";\n    " + ctx + forKey + " = " + forKey + ";\n    " + ctxloop + ".key = " + forKey + ";\n    " + ctxloop + ".first = (" + ctxloop + ".index0 === 0);\n    " + ctxloop + ".last = (" + ctxloop + ".revindex0 === 0);\n    " + forBodyJS + "    " + ctxloop + ".index += 1; " + ctxloop + ".index0 += 1; " + ctxloop + ".revindex -= 1; " + ctxloop + ".revindex0 -= 1;\n  });\n  " + ctxloop + " = " + ctxloopcache + ".loop;\n  " + ctx + forVal + " = " + ctxloopcache + "." + forVal + ";\n  " + ctx + forKey + " = " + ctxloopcache + "." + forKey + ";\n  " + ctxloopcache + " = undefined;\n})();\n";
             return;
           }
           if (node.type === "Macro") {
@@ -1381,11 +1458,14 @@
                 return;
               }
             });
-            var macroParams = node.params || [], macroSigJS, macroIndexOfJS;
+            var macroParams = node.params || [], macroSigJS, macroIndexOfJS, macroDefaultsJS = "";
             if (macroParams.length && typeof macroParams[0] === "object" && macroParams[0] !== null && typeof macroParams[0].name === "string") {
               var macroNames = [];
               utils.each(macroParams, function(p) {
                 macroNames.push(p.name);
+                if (p["default"]) {
+                  macroDefaultsJS += "  if (" + p.name + " === undefined) { " + p.name + " = " + exports.emitExpr(p["default"]) + "; }\n";
+                }
               });
               macroSigJS = macroNames.join(", ");
               var macroJsonNames = [];
@@ -1397,7 +1477,7 @@
               macroSigJS = macroParams.join("");
               macroIndexOfJS = '"' + macroParams.join('","') + '"';
             }
-            out += "_ctx." + node.name + " = function (" + macroSigJS + ') {\n  var _output = "",\n    __ctx = _utils.extend({}, _ctx);\n  _utils.each(_ctx, function (v, k) {\n    if ([' + macroIndexOfJS + "].indexOf(k) !== -1) { delete _ctx[k]; }\n  });\n" + macroBodyJS + "\n _ctx = _utils.extend(_ctx, __ctx);\n  return _output;\n};\n_ctx." + node.name + ".safe = true;\n";
+            out += "_ctx." + node.name + " = function (" + macroSigJS + ') {\n  var _output = "",\n    __ctx = _utils.extend({}, _ctx);\n' + macroDefaultsJS + "  _utils.each(_ctx, function (v, k) {\n    if ([" + macroIndexOfJS + "].indexOf(k) !== -1) { delete _ctx[k]; }\n  });\n" + macroBodyJS + "\n _ctx = _utils.extend(_ctx, __ctx);\n  return _output;\n};\n_ctx." + node.name + ".safe = true;\n";
             if (options && options.codegenMode === "async") {
               if (_security.dangerousProps.indexOf(node.name) !== -1) {
                 throw new Error('Macro name "' + node.name + '" is reserved.');
@@ -1625,7 +1705,11 @@
                 outExprJS = '_filters["' + fc.name + '"](' + outExprJS + fcArgsJS + ")";
               });
             }
-            out += "_output += " + outExprJS + ";\n";
+            if (node.coerce) {
+              out += "_output += _utils.coerceOutput(" + outExprJS + ");\n";
+            } else {
+              out += "_output += " + outExprJS + ";\n";
+            }
             return;
           }
           if (node.type === "Filter") {
@@ -2356,9 +2440,9 @@
          * `parseExpr` emits structured IR that {@link backend.emitExpr}
          * later lowers into an equivalent JS-source fragment. `.parse()` is
          * unchanged and remains the production path; `parseExpr` is the
-         * incoming target shape for Phase 2 (#T15), introduced additively in
-         * Session 14b so the IR grammar can be proven against real lexer
-         * output before consumers are flipped in Commits 3-8.
+         * incoming target shape for the IR migration, introduced additively
+         * so the IR grammar can be proven against real lexer output before
+         * consumers are flipped over to it.
          *
          * The CVE-2023-25345 prototype-chain guards (`_dangerousProps` on
          * VAR segments, DOTKEY matches, STRING-inside-BRACKETOPEN values,
@@ -4598,7 +4682,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.4.3";
+      exports.version = "2.5.0";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],