@rhinostone/swig 2.5.0 → 2.5.2

package/HISTORY.md

@@ -1,3 +1,27 @@
+[2.5.2](https://github.com/gina-io/swig/tree/v2.5.2) / 2026-06-02
+-----------------------------------------------------------------
+
+* **Fixed** Dynamic `{% extends %}` paths (e.g. `{% extends layout_var %}`) now resolve on the async-loader render path (`renderFile(path, locals, cb)` with `loader.async`) in `@rhinostone/swig-twig` and `@rhinostone/swig-jinja2`, matching native swig and real Twig/Jinja2. Static string-literal extends and the synchronous render path are unchanged.
+
+* **Fixed** Dynamic `{% extends %}` paths (e.g. `{% extends layout_var %}`) now resolve on the async-loader render path (`renderFile(path, locals, cb)` with `loader.async`); previously a dynamic parent path produced a garbage template lookup. Static string-literal extends and the synchronous render path are unchanged.
+
+[2.5.1](https://github.com/gina-io/swig/tree/v2.5.1) / 2026-05-28
+-----------------------------------------------------------------
+
+* **Fixed** Restored the JSDoc blocks on the top-level Swig public API methods (setFilter, setTag, setExtension, precompile, compile, compileFile, render, renderFile, run, invalidateCache) that were inadvertently stripped from lib/swig.js when the Swig constructor body was carved into @rhinostone/swig-core/lib/engine.js. The documentation comments now sit above the corresponding exports.* re-exports where make build-docs and IDE hover tooling read them. No runtime behavior change — the published lib/ code is byte-identical and only the JSDoc surface is updated.
+
+* **Changed** Rephrased two stale internal-process tracker references in lib/tags/set.js source comments that survived the prior single-line audit sweep because the markers spanned a line wrap. The explanatory content is preserved verbatim; only the dead tracker tokens are dropped, per the in-repo no-internal-markers-in-shipping-source convention. No behavior change.
+
+* **Changed** Migrated the test toolchain from mocha 1.12.0 to the Node.js built-in test runner (node:test) with built-in line coverage, removing the mocha, blanket, and travis-cov dev dependencies. This clears all 6 npm audit advisories (4 high, 2 critical) that were rooted in mocha's transitive dependency tree; the full suite passes unchanged and the 95% coverage gate over lib/ is preserved. The published package is unaffected — its only runtime dependency remains @rhinostone/swig-core.
+
+* **Changed** Removed the unmaintained phantomjs and mocha-phantomjs browser-test toolchain, dropping the vulnerable form-data (CVE-2025-7783) and the rest of the legacy request dependency subtree from the dev dependency tree. Browser parity is verified through the production bundle build, pending a modern browser-test harness.
+
+* **Changed** Upgraded the ESLint dev dependency from 8.57.1 to 9.x and migrated the lint configuration from the deprecated .eslintrc.json (eslintrc format) to the flat-config eslint.config.js, adding the globals dev dependency. The lenient rule set is preserved exactly (no indent enforcement, eqeqeq/no-eval/no-new-func off, semi always, max-len 600, plus an explicit linterOptions.reportUnusedDisableDirectives off to match the eslintrc default). ESLint 9 raises the lint toolchain Node floor to >=18.18, which affects development and CI only; the published package is unaffected and its only runtime dependency remains @rhinostone/swig-core.
+
+* **Changed** Upgraded the example/development express dependency from the abandoned 3.x line to 4.x, dropping the vulnerable transitive morgan (CVE-2019-5413) and the legacy connect subtree from the dev dependency tree. The Express view-engine example runs unchanged. The published package is unaffected; its only runtime dependency remains @rhinostone/swig-core.
+
+* **Changed** Upgraded the development lodash dependency from 1.3.x to 4.x, dropping the prototype-pollution and command-injection advisories (affecting lodash through 4.17.23) from the dev dependency tree. lodash is a test-only utility and the full suite passes unchanged on 4.x. The published package is unaffected; its only runtime dependency remains @rhinostone/swig-core.
+
 [2.5.0](https://github.com/gina-io/swig/tree/v2.5.0) / 2026-05-27
 -----------------------------------------------------------------
 

package/README.md

@@ -3,7 +3,7 @@ Swig
 
 [![CI](https://github.com/gina-io/swig/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/gina-io/swig/actions/workflows/ci.yml) [![NPM version](http://img.shields.io/npm/v/@rhinostone/swig.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig) [![NPM Downloads](http://img.shields.io/npm/dm/@rhinostone/swig.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig)](https://socket.dev/npm/package/@rhinostone/swig)
 
-> **Multi-flavor template engine** for Node.js and browsers — native Swig syntax (Jinja2/Django-inspired) and Twig syntax via dedicated frontends sharing one IR backend. [gina-io/swig](https://github.com/gina-io/swig) started as a maintained continuation of the abandoned [paularmstrong/swig](https://github.com/paularmstrong/swig) (last released 2014) and is now a standalone project. Security and bug fixes ship here.
+> **Multi-flavor template engine** for Node.js and browsers — native Swig syntax (Jinja2/Django-inspired), Twig syntax, and Python Jinja2 syntax via dedicated frontends sharing one IR backend. [gina-io/swig](https://github.com/gina-io/swig) started as a maintained continuation of the abandoned [paularmstrong/swig](https://github.com/paularmstrong/swig) (last released 2014) and is now a standalone project. Security and bug fixes ship here.
 
 > **Part of the [Gina](https://github.com/gina-io/gina) ecosystem.** This is the built-in template engine for [Gina](https://gina.io) ([npm](https://www.npmjs.com/package/gina)), a Node.js MVC framework with HTTP/2, multi-bundle architecture, and scope-based data isolation.
 
@@ -11,6 +11,8 @@ Swig is a **Jinja2/Django-inspired** template engine for node.js and browsers. T
 
 > **Coming from Twig?** Install [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) instead — a dedicated Twig-syntax frontend with closer parity than working around incompatibilities here.
 
+> **Coming from Python Jinja2?** Install [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) — a dedicated Jinja2-syntax frontend (near-subset) with closer parity than porting to native Swig syntax here.
+
 Workspace packages
 ------------------
 
@@ -18,9 +20,10 @@ Workspace packages
 | --- | --- | --- |
 | [`@rhinostone/swig`](https://www.npmjs.com/package/@rhinostone/swig) | Native Swig syntax (Jinja2/Django-inspired). Drop-in for `@rhinostone/swig@1.x` consumers. | Upgrading from `@rhinostone/swig@1.x`, or starting fresh with Swig syntax. |
 | [`@rhinostone/swig-twig`](https://www.npmjs.com/package/@rhinostone/swig-twig) | Twig-syntax frontend with closer Twig parity. | Migrating from PHP Twig, or writing new templates in Twig syntax. |
+| [`@rhinostone/swig-jinja2`](https://www.npmjs.com/package/@rhinostone/swig-jinja2) | Python Jinja2-syntax frontend (near-subset). | Migrating from Python Jinja2, or writing new templates in Jinja2 syntax. |
 | [`@rhinostone/swig-core`](https://www.npmjs.com/package/@rhinostone/swig-core) | Shared IR, backend, and runtime primitives. | Building a custom flavor frontend. Otherwise pulled in transitively. |
 
-Each frontend pins the matching `@rhinostone/swig-core` version exactly during the alpha cycle — the IR is not stable across alpha minors. From `2.0.0` stable onward, frontends and the core release in lockstep.
+Each frontend pins the matching `@rhinostone/swig-core` version exactly (no caret, no tilde) — frontends and the core release in lockstep on every cut.
 
 Features
 --------
@@ -29,7 +32,7 @@ Features
 * [Express](http://expressjs.com/) compatible.
 * Object-Oriented template inheritance.
 * Apply filters and transformations to output in your templates.
-* **Hardened against prototype-pollution** — `__proto__` / `constructor` / `prototype` blocked at parser, tag-side, and IR-emission layers. CVE-2023-25345 fully patched. 9 regression cases under [`tests/regressions.test.js`](./tests/regressions.test.js).
+* **Hardened against prototype-pollution** — `__proto__` / `constructor` / `prototype` blocked at parser, tag-side, and IR-emission layers. CVE-2023-25345 fully patched. 11 CVE regression cases under [`tests/regressions.test.js`](./tests/regressions.test.js).
 * Automatically escapes all variable output (HTML by default; configurable per-call).
 * Lots of iteration and conditionals supported.
 * Robust without the bloat.
@@ -61,6 +64,10 @@ For Twig syntax:
 
     npm install @rhinostone/swig-twig
 
+For Python Jinja2 syntax:
+
+    npm install @rhinostone/swig-jinja2
+
 Documentation
 -------------
 
@@ -109,7 +116,7 @@ Migrating from `@rhinostone/swig@1.x`
 
 `@rhinostone/swig@2.x` is **drop-in for `1.x` consumers** — `swig.compileFile`, `swig.renderFile`, `swig.setFilter`, `swig.setTag`, and the rest of the public API are unchanged. The internal carve into [@rhinostone/swig-core](https://www.npmjs.com/package/@rhinostone/swig-core) is transparent (test gate during the alpha cycle: byte-identical compiled output against the `1.x` test suite).
 
-`2.0.0` also ships [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig), a sibling Twig-syntax frontend. Switching is opt-in — your existing `@rhinostone/swig` install keeps working.
+`2.0.0` also ships [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig), a sibling Twig-syntax frontend, and `2.5.0` adds [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) for Python Jinja2 syntax. Switching is opt-in — your existing `@rhinostone/swig` install keeps working.
 
 Migrating from Jinja2 or Django
 -------------------------------
@@ -132,7 +139,7 @@ How it works
 
 Swig reads template files and translates them into cached JavaScript functions. The pipeline is: parse → emit IR → lower IR to JS source → `new Function(...)`. At render time, the compiled function runs against a context object to produce the output string.
 
-In `2.x`, frontend parsers (native Swig syntax in [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig), Twig syntax in [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig)) emit a shared intermediate representation. The backend in [@rhinostone/swig-core](https://www.npmjs.com/package/@rhinostone/swig-core) lowers IR to JS. New flavors plug in at the frontend without touching the runtime.
+In `2.x`, frontend parsers (native Swig syntax in [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig), Twig syntax in [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig), Python Jinja2 syntax in [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2)) emit a shared intermediate representation. The backend in [@rhinostone/swig-core](https://www.npmjs.com/package/@rhinostone/swig-core) lowers IR to JS. New flavors plug in at the frontend without touching the runtime.
 
 License
 -------

package/ROADMAP.md

@@ -14,14 +14,26 @@ _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 | Async parse path for the remaining dynamic targets — runtime-resolved `{% import %}` / `{% from %}` paths on the async-codegen branch. Static-target async dispatch shipped in 2.2.0; dynamic `{% extends %}` shipped in 2.5.2 (native + Twig + Jinja2) and dynamic `{% include %}` paths already resolve (the include path has always been an expression). Dynamic `import` / `from` are on hold pending consumer 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.) |
+| Planned | Test framework migration. Replace mocha 1.x + expect.js with `node:test` + `node:assert/strict`, add a modern browser-test harness (the legacy phantomjs runner has been removed), swap blanket for `c8`. (The Node engines bump is upstream-driven by gina and is being treated as done.) |
 
 ---
 
 ## Completed
 
+### v2.5.2 (June 2026)
+
+- Dynamic `{% extends %}` paths now resolve on the async render path (`renderFile(path, locals, cb)` against a loader with `loader.async === true`) across all three frontends — native `@rhinostone/swig`, `@rhinostone/swig-twig`, and `@rhinostone/swig-jinja2`. A dynamic parent (e.g. `{% extends layout_var %}`) is lowered to a deferred IR expression and resolved at render time, matching real Twig and Jinja2; previously a dynamic parent path was rejected at parse time (Twig / Jinja2) or produced a garbage template lookup (native). Static string-literal `{% extends %}` and the synchronous render path are unchanged — on the sync path a dynamic parent still requires a string literal (dispatch the chosen parent in the caller).
+- All four packages (`@rhinostone/swig`, `@rhinostone/swig-core`, `@rhinostone/swig-twig`, `@rhinostone/swig-jinja2`) released in lockstep at `2.5.2`.
+
+### v2.5.1 (May 2026)
+
+- Restored JSDoc on the top-level `@rhinostone/swig` public API methods (`setFilter`, `setTag`, `setExtension`, `precompile`, `compile`, `compileFile`, `render`, `renderFile`, `run`, `invalidateCache`). The blocks were inadvertently stripped from `lib/swig.js` when the Swig constructor body was carved into `@rhinostone/swig-core` during the `2.0.0-alpha.1` cycle; `make build-docs` and IDE hover tooling read from `lib/swig.js`, so the documented surface for all ten methods had been missing since the carve. Doc-only restoration; `renderFile`'s block also documents the `v2.2.0` async-codegen dispatch (set `loader.async === true` on the loader to opt in).
+- Cleaned two stale internal-process tracker references from `lib/tags/set.js` source comments; the explanatory content is preserved and only the dead reference tokens were dropped.
+- Dev-tooling modernization riding the same release: retired the unmaintained `phantomjs` browser-test toolchain (also dropped the vulnerable `form-data` from the dev tree); bumped the example/development `express` dependency from `~3` to `^4` (also dropped the vulnerable `morgan` and `minimist` from the dev tree); bumped the test-utility `lodash` dependency from `~1.3.1` to `^4` (cleared five `lodash` advisories from the dev tree); migrated the test toolchain from `mocha` 1.12.0 to the Node built-in `node:test` runner with built-in line coverage (cleared the six remaining dev-tree audit findings, taking `npm audit` to zero); migrated the ESLint dev dependency from 8.x to 9.x with the new flat-config (`.eslintrc.json` → `eslint.config.js`), clearing the six "deprecated by maintainer" Socket Low alerts on the repo scan. None of this affects the published runtime — only the dev/CI toolchain.
+- All four packages (`@rhinostone/swig`, `@rhinostone/swig-core`, `@rhinostone/swig-twig`, `@rhinostone/swig-jinja2`) released in lockstep at `2.5.1`. The runtime in `@rhinostone/swig-core` / `@rhinostone/swig-twig` / `@rhinostone/swig-jinja2` is functionally identical to `2.5.0`; only `@rhinostone/swig`'s `lib/swig.js` and `lib/tags/set.js` carry source-comment changes.
+
 ### 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.

package/dist/swig.js

@@ -1,4 +1,4 @@
-/*! Swig v2.5.0 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
+/*! Swig v2.5.2 | 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;
@@ -664,11 +664,29 @@
   // lib/tags/extends.js
   var require_extends = __commonJS({
     "lib/tags/extends.js"(exports) {
+      var _t = require_tokentypes();
       exports.compile = function() {
       };
       exports.parse = function() {
         return true;
       };
+      exports.lowerExpr = function(parser, tokens) {
+        var i, tk, pathTokens = [];
+        for (i = 0; i < tokens.length; i += 1) {
+          tk = tokens[i];
+          if (tk.type === _t.WHITESPACE) {
+            continue;
+          }
+          pathTokens.push(tk);
+        }
+        if (!pathTokens.length) {
+          return void 0;
+        }
+        if (pathTokens.length === 1 && pathTokens[0].type === _t.STRING) {
+          return void 0;
+        }
+        return { file: parser.parseExpr(tokens) };
+      };
       exports.ends = false;
     }
   });
@@ -2990,7 +3008,7 @@
         source = source.replace(/\r\n/g, "\n");
         var escape = opts.autoescape, tagOpen = opts.tagControls[0], tagClose = opts.tagControls[1], varOpen = opts.varControls[0], varClose = opts.varControls[1], escapedTagOpen = escapeRegExp(tagOpen), escapedTagClose = escapeRegExp(tagClose), escapedVarOpen = escapeRegExp(varOpen), escapedVarClose = escapeRegExp(varClose), tagStrip = new RegExp("^" + escapedTagOpen + "-?\\s*|\\s*-?" + escapedTagClose + "$", "g"), tagStripBefore = new RegExp("^" + escapedTagOpen + "-"), tagStripAfter = new RegExp("-" + escapedTagClose + "$"), varStrip = new RegExp("^" + escapedVarOpen + "-?\\s*|\\s*-?" + escapedVarClose + "$", "g"), varStripBefore = new RegExp("^" + escapedVarOpen + "-"), varStripAfter = new RegExp("-" + escapedVarClose + "$"), cmtOpen = opts.cmtControls[0], cmtClose = opts.cmtControls[1], anyChar = "[\\s\\S]*?", splitter = new RegExp(
           "(" + escapedTagOpen + anyChar + escapedTagClose + "|" + escapedVarOpen + anyChar + escapedVarClose + "|" + escapeRegExp(cmtOpen) + anyChar + escapeRegExp(cmtClose) + ")"
-        ), line = 1, stack = [], parent = null, tokens = [], blocks = {}, inRaw = false, stripNext;
+        ), line = 1, stack = [], parent = null, parentExpr = null, tokens = [], blocks = {}, inRaw = false, stripNext;
         function parseVariable(str, line2) {
           var tokens2 = lexer.read(utils.strip(str)), parser, node;
           parser = new TokenParser(tokens2, filters, escape, line2, opts.filename);
@@ -3081,6 +3099,7 @@
             if (token) {
               if (token.name === "extends") {
                 parent = token.args.join("").replace(/^\'|\'$/g, "").replace(/^\"|\"$/g, "");
+                parentExpr = token.irExpr && token.irExpr.file;
               } else if (token.block && !stack.length) {
                 blocks[token.args.join("")] = token;
               }
@@ -3121,6 +3140,7 @@
         return {
           name: opts.filename,
           parent,
+          parentExpr,
           tokens,
           blocks
         };
@@ -4388,7 +4408,7 @@
           }
         });
         return ir.extendsDeferred(
-          ir.literal("string", tokens.parent),
+          tokens.parentExpr || ir.literal("string", tokens.parent),
           childBlocks,
           childIRs,
           options.filename || ""
@@ -4682,7 +4702,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.5.0";
+      exports.version = "2.5.2";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],
@@ -4917,6 +4937,15 @@
  * a tight IR keeps the shape honest for future flavor backends.
  * @private
  */
+/*!
+ * Lower a dynamic parent-path to IR so `{% extends layout_var %}`
+ * resolves at render time on the async codegen path. A lone
+ * string-literal path (`{% extends "x.html" %}`) returns undefined, so
+ * the engine keeps its existing tokens.parent string + ir.literal path
+ * unchanged; only a dynamic path is lowered. Mirrors include.js. The
+ * resulting IRExpr is read back as token.irExpr.file by the parser
+ * splitter and stashed on the sibling tokens.parentExpr slot.
+ */
 /*!
  * JSON-escape a literal text chunk for embedding inside a JS
  * double-quoted string literal in the compiled template body.