@rhinostone/swig 2.4.2 → 2.5.0

package/HISTORY.md

@@ -1,3 +1,13 @@
+[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
+-----------------------------------------------------------------
+
+* **Fixed** Native `import` no longer leaks an imported file's own import aliases into the importing template's context. A file-level `{% import %}` inside an imported file is now re-homed under the importing alias instead of emitted bare, so it cannot clobber a same-named variable in the caller, corrupt a macro when the caller later reassigns that name, or cascade across import depth. Macros still resolve their own file's imports at call time.
+
 [2.4.2](https://github.com/gina-io/swig/tree/v2.4.2) / 2026-05-22
 -----------------------------------------------------------------
 
@@ -52,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,22 @@ _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.
+
 ### v2.4.2 (May 2026)
 
 - Fixed the same empty-render bug in `@rhinostone/swig-twig`: a macro that calls a macro imported at the top of its own defining file — via either `{% import %}` or `{% from %}` — now resolves at call time instead of rendering empty. The imported file's own imports stay local to the template that declares them (they are not leaked bare into the importing template's scope), matching Twig's macro/import scoping rule. Resolves recursively across import depth.

package/dist/swig.js

@@ -1,4 +1,4 @@
-/*! Swig v2.4.2 | 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,
@@ -3074,14 +3158,30 @@
             re: "_ctx." + ctx + "." + arg.name + "$1"
           };
         });
+        var innerReplacements = [];
         utils.each(nestedImports, function(arg) {
-          out += arg.compiled;
+          utils.each(arg.boundNames, function(nm) {
+            innerReplacements.push({
+              ex: new RegExp("_ctx\\." + nm + "(\\W)", "g"),
+              re: "_ctx." + ctx + "." + nm + "$1"
+            });
+          });
+        });
+        utils.each(nestedImports, function(arg) {
+          var c = arg.compiled;
+          utils.each(innerReplacements, function(re) {
+            c = c.replace(re.ex, re.re);
+          });
+          out += c;
         });
         utils.each(macros, function(arg) {
           var c = arg.compiled;
           utils.each(replacements, function(re) {
             c = c.replace(re.ex, re.re);
           });
+          utils.each(innerReplacements, function(re) {
+            c = c.replace(re.ex, re.re);
+          });
           out += c;
         });
         return out;
@@ -3107,7 +3207,11 @@
             if (token2.name === "import") {
               self.out.push({
                 compiled: token2.compile(compiler, token2.args.slice(), token2.content, [], compileOpts) + "\n",
-                isImport: true
+                isImport: true,
+                // The nested import binds one namespace alias (the tail of its
+                // parsed args). compile() re-homes it under THIS import's alias so
+                // it never leaks bare into the parent _ctx.
+                boundNames: [token2.args[token2.args.length - 1]]
               });
               return;
             }
@@ -4578,7 +4682,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.4.2";
+      exports.version = "2.5.0";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],