@rhinostone/swig-jinja2 2.5.0

package/lib/tags/from.js

@@ -0,0 +1,305 @@
+/*!
+ * Jinja2 `{% from "file" import a, b as c %}` tag.
+ *
+ * Selective macro import syntax — binds a named subset of an imported
+ * template's macros into the current context, optionally renaming each
+ * via `as <alias>`:
+ *
+ *   {% from "forms.html" import input %}
+ *   {% from "forms.html" import input, textarea %}
+ *   {% from "forms.html" import input as field, textarea %}
+ *
+ * Differs from `{% import %}` in that each entry lands at top-level
+ * `_ctx.<alias-or-name>` rather than inside a shared namespace object.
+ * Macros not listed in the `import` clause are not surfaced.
+ *
+ * Stays on `IRLegacyJS` per the same flavor-invariant test that keeps
+ * `{% import %}` on IRLegacyJS — the regex-surgery rewrite of a compiled
+ * macro body (`_ctx\.<origName>` → `_ctx\.<aliasName>`) is swig-specific
+ * coupling on the exact JS source shape the Macro IR emits. When the
+ * macro-name → alias rewrite moves into the IR emitter itself, this tag
+ * collapses to a dedicated `IRFromImport` node.
+ *
+ * Dynamic paths (`{% from dynPath import foo %}`) are rejected at parse
+ * time — same rationale as `{% import %}` + `{% extends %}`. Context
+ * modifiers (`with` / `without context`) are not honored — imported
+ * macros always see the caller context (swig's macro model; a documented
+ * divergence from Jinja2's without-context import default).
+ *
+ * Every requested macro name and every alias is a bare identifier —
+ * dotted paths are rejected per the lexer-folded-path bail pattern, and
+ * CVE-2023-25345 prototype-chain names are rejected on both slots before
+ * the assignment lands on `_ctx`.
+ */
+
+var utils = require('@rhinostone/swig-core/lib/utils');
+var ir = require('@rhinostone/swig-core/lib/ir');
+var backend = require('@rhinostone/swig-core/lib/backend');
+var _dangerousProps = require('@rhinostone/swig-core/lib/security').dangerousProps;
+
+var lexer = require('../lexer');
+
+exports.ends = false;
+exports.block = true;
+
+/**
+ * Parse the `{% from %}` tag body. Extracts the STRING literal path,
+ * the `import` keyword, and the comma-separated entry list (each entry
+ * is `<name>` or `<name> as <alias>`); validates every name and alias
+ * against the bare-identifier rule and the CVE-2023-25345
+ * `_dangerousProps` blocklist.
+ *
+ * Walks the imported template's token list (via `swig.parseFile`) and
+ * for each requested macro, invokes its `compile` to get the IRMacro
+ * node and renders that node to JS through `backend.compile`. A
+ * macro requested by name but not found in the imported template
+ * raises a filename-aware throw. The imported file's own nested
+ * `{% import %}` / `{% from %}` tokens are carried through (flagged
+ * `isImport`, with `boundNames` + a synthesized private `slot`) so the
+ * requested macros can reference them at call time. The resulting list
+ * (nested entries + `[{compiled, origName, aliasName}, ...]`) is stashed
+ * on `token.args` for the compile step to rewrite.
+ *
+ * @param  {string} str    Tag body.
+ * @param  {number} line   Source line of the opening `{%`.
+ * @param  {object} parser The Jinja2 parser module (unused — body is
+ *                         lexed locally).
+ * @param  {object} types  Jinja2 lexer token-type enum.
+ * @param  {Array}  stack  Open-tag stack (unused — from has no body).
+ * @param  {object} opts   Per-call options. Honors `opts.filename` for
+ *                         `resolveFrom` + filename-aware throws.
+ * @param  {object} swig   Swig instance. Must expose `parseFile`.
+ * @param  {object} token  In-progress TagToken. `token.args` gets the
+ *                         `[{compiled, origName, aliasName}, ...]` list.
+ * @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;
+  }
+  function guardName(name, role) {
+    if (name.indexOf('.') !== -1) {
+      utils.throwError(role + ' "' + name + '" must be a bare identifier in "from" tag', line, opts.filename);
+    }
+    if (_dangerousProps.indexOf(name) !== -1) {
+      utils.throwError('Unsafe ' + role.toLowerCase() + ' "' + name + '" is not allowed (CVE-2023-25345)', line, opts.filename);
+    }
+  }
+
+  var pathTok = consume();
+  if (!pathTok) {
+    utils.throwError('Expected template path in "from" tag', line, opts.filename);
+  }
+  if (pathTok.type !== types.STRING) {
+    utils.throwError('Dynamic "from" is not supported — path must be a string literal', line, opts.filename);
+  }
+
+  var importTok = consume();
+  if (!importTok || importTok.type !== types.VAR || importTok.match !== 'import') {
+    utils.throwError('Expected "import" keyword after path in "from" tag', line, opts.filename);
+  }
+
+  // Collect requested macro entries — each is `<name>` or
+  // `<name> as <alias>`. At least one entry is required.
+  var entries = [];
+  while (true) {
+    var nameTok = consume();
+    if (!nameTok || nameTok.type !== types.VAR) {
+      utils.throwError('Expected macro name in "from" tag', line, opts.filename);
+    }
+    guardName(nameTok.match, 'Macro name');
+
+    var origName = nameTok.match;
+    var aliasName = origName;
+
+    var next = peek();
+    if (next && next.type === types.VAR && next.match === 'as') {
+      consume();
+      var aliasTok = consume();
+      if (!aliasTok || aliasTok.type !== types.VAR) {
+        utils.throwError('Expected alias after "as" in "from" tag', line, opts.filename);
+      }
+      guardName(aliasTok.match, 'Import alias');
+      aliasName = aliasTok.match;
+      next = peek();
+    }
+
+    entries.push({ origName: origName, aliasName: aliasName });
+
+    if (!next) { break; }
+    if (next.type !== types.COMMA) {
+      utils.throwError('Unexpected token "' + next.match + '" in "from" tag import list', line, opts.filename);
+    }
+    consume();
+  }
+
+  var path = pathTok.match.replace(/^['"]|['"]$/g, '');
+
+  if (opts && opts.codegenMode === 'async') {
+    // Async mode skips parse-time parseFile + macro pre-render. compile()
+    // emits IRFromImportDeferred; runtime resolves the template via
+    // _swig.getTemplate and binds each entry on _ctx.
+    token.args = [{ path: path, entries: entries }];
+    return true;
+  }
+
+  if (!swig || typeof swig.parseFile !== 'function') {
+    utils.throwError('"from" tag requires an engine context with a loader', line, opts.filename);
+  }
+
+  var parseOpts = { resolveFrom: opts.filename };
+  var compileOpts = utils.extend({}, opts, parseOpts);
+  var parsed = swig.parseFile(path, parseOpts);
+
+  // Index the imported template's macros by name so we can look up
+  // each requested entry once. Raises a filename-aware throw if an
+  // entry names a macro that doesn't exist in the imported template.
+  //
+  // The imported file may have its own `{% import %}` / `{% from %}`.
+  // Unlike `{% import %}`, `{% from %}` binds bare names with no namespace
+  // alias to hang those nested imports under, so they re-home under a
+  // synthesized private slot keyed off the path (compile() applies the
+  // rewrite). This keeps the inner names out of the parent's bare scope —
+  // bare `{{ name }}` in the parent stays undefined, matching Jinja2's rule
+  // that imports are local to the importing template.
+  var privateSlot = '__nsfrom_' + path.replace(/[^a-zA-Z0-9]/g, '_');
+  var nested = [];
+  var macroIndex = {};
+  utils.each(parsed.tokens, function (tk) {
+    if (!tk || typeof tk.compile !== 'function') {
+      return;
+    }
+    if (tk.name === 'import' || tk.name === 'from') {
+      var bn = (tk.name === 'import')
+        ? [tk.args[tk.args.length - 1]]
+        : utils.map(tk.args, function (a) { return a.aliasName; });
+      nested.push({
+        compiled: tk.compile(null, tk.args.slice(), tk.content, [], compileOpts) + '\n',
+        isImport: true,
+        boundNames: bn,
+        slot: privateSlot
+      });
+      return;
+    }
+    if (tk.name !== 'macro') {
+      return;
+    }
+    macroIndex[tk.args[0]] = tk;
+  });
+
+  var resolved = [];
+  for (var i = 0; i < entries.length; i += 1) {
+    var entry = entries[i];
+    var macroTok = macroIndex[entry.origName];
+    if (!macroTok) {
+      utils.throwError('Macro "' + entry.origName + '" not found in "' + path + '"', line, opts.filename);
+    }
+    var macroIR = macroTok.compile(backend.compile, macroTok.args, macroTok.content, [], compileOpts);
+    var compiled = backend.compile([macroIR], [], compileOpts) + '\n';
+    resolved.push({
+      compiled: compiled,
+      origName: entry.origName,
+      aliasName: entry.aliasName
+    });
+  }
+
+  token.args = nested.concat(resolved);
+  return true;
+};
+
+/**
+ * Emit the selective-import rewrite. For each imported entry, rewrites
+ * every occurrence of `_ctx.<origName>` in the compiled macro body to
+ * `_ctx.<aliasName>`, including sibling-macro references to any other
+ * imported name. The `(?!<allOrigNames>)` negative lookahead matches
+ * `{% import %}` behaviour — guards against the edge case where a
+ * rewritten `_ctx.<aliasName>` fragment would itself be re-matched by a
+ * later replacement whose `origName` happens to be a prefix of the alias
+ * tail.
+ *
+ * Sibling references to a macro that was NOT in the import list are
+ * left as-is — those expand to `_ctx.<origName>` lookups at render time
+ * and will either read a user-provided context value or evaluate to
+ * `undefined`, matching Jinja2's "unimported macros are not available"
+ * semantic.
+ *
+ * The imported file's own nested imports (flagged `isImport`) are emitted
+ * first, re-homed under a private slot (`_ctx.<boundName>` ->
+ * `_ctx.<slot>.<boundName>`) so they resolve for the imported macros at
+ * call time without leaking into the parent's bare scope.
+ *
+ * @return {string} JS source that assigns every imported macro into
+ *                  `_ctx.<aliasName>`. Backend lifts it into
+ *                  `IRLegacyJS`.
+ */
+exports.compile = function (compiler, args, content, parents, options) {
+  // Async-codegen branch. Parse stashed a single bundle
+  // `[{path, entries: [{origName, aliasName}, ...]}]` in async mode (no
+  // macro pre-render); emit IRFromImportDeferred so the backend's
+  // `_swig.getTemplate` + per-entry `_ctx.<bind>` assignment happens at
+  // runtime.
+  if (options && options.codegenMode === 'async') {
+    var bundle = args[0];
+    var imports = utils.map(bundle.entries, function (e) {
+      return {
+        name: e.origName,
+        alias: e.aliasName === e.origName ? null : e.aliasName
+      };
+    });
+    return ir.fromImportDeferred(
+      ir.literal('string', bundle.path),
+      imports,
+      options.filename || ''
+    );
+  }
+  var macros = [];
+  var nested = [];
+  utils.each(args, function (a) { (a.isImport ? nested : macros).push(a); });
+  var allOrigNames = utils.map(macros, function (arg) { return arg.origName; }).join('|');
+  var replacements = utils.map(macros, function (arg) {
+    return {
+      ex: new RegExp('_ctx\\.' + arg.origName + '(\\W)(?!' + allOrigNames + ')', 'g'),
+      re: '_ctx.' + arg.aliasName + '$1'
+    };
+  });
+  // The imported file's own nested imports re-home under a private slot so
+  // they never leak into the parent's bare scope: `_ctx.<boundName>` ->
+  // `_ctx.<slot>.<boundName>`, applied to the nested setup JS and to every
+  // imported macro body that references a bound name.
+  var innerReplacements = [];
+  utils.each(nested, function (a) {
+    utils.each(a.boundNames, function (nm) {
+      innerReplacements.push({
+        ex: new RegExp('_ctx\\.' + nm + '(\\W)', 'g'),
+        re: '_ctx.' + a.slot + '.' + nm + '$1'
+      });
+    });
+  });
+
+  var out = '  var _output = "";\n';
+  // Nested imports first (under the private slot), so the imported macros
+  // below resolve them at call time.
+  utils.each(nested, function (a) {
+    out += '_ctx.' + a.slot + ' = _ctx.' + a.slot + ' || {};\n';
+    var c = a.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;
+};

package/lib/tags/if.js

@@ -0,0 +1,82 @@
+/*!
+ * Jinja2 `{% if %}` / `{% elif %}` / `{% else %}` tag.
+ *
+ * Conditional: `{% if <expr> %}…{% elif <expr> %}…{% else %}…{% endif %}`.
+ * The test expression is parsed via `parser.parseExpr` and attached to
+ * `token.irExpr`. The body content is captured via the parser's open-tag
+ * stack (this tag sets `ends: true`).
+ *
+ * `{% elif %}` and `{% else %}` lex as their own tags (`ends: false`,
+ * registered in tags/index.js) and so appear as marker tokens inside this
+ * tag's `content`. The compile path walks `content`, splitting at those
+ * markers into one IRIfBranch per segment — the backend's `If` walker then
+ * emits the `if (…) { … } else if (…) { … } else { … }` envelope.
+ */
+
+var ir = require('@rhinostone/swig-core/lib/ir');
+var utils = require('@rhinostone/swig-core/lib/utils');
+
+var lexer = require('../lexer');
+
+exports.ends = true;
+exports.block = false;
+
+/**
+ * Parse the `{% if %}` test expression onto `token.irExpr`.
+ *
+ * @param  {string} str    Tag body (tag name stripped).
+ * @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 (managed by parser.js).
+ * @param  {object} opts   Per-call options (honors `opts.filename`).
+ * @param  {object} swig   Swig instance (unused).
+ * @param  {object} token  In-progress TagToken. `token.irExpr` is set.
+ * @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));
+  if (!tokens.length) {
+    utils.throwError('Expected conditional expression in "if" tag', line, opts.filename);
+  }
+  token.irExpr = parser.parseExpr(tokens);
+  return true;
+};
+
+/**
+ * Split `content` at `elif` / `else` marker tokens and emit a multi-branch
+ * IRIf node.
+ *
+ * @return {object} IRIf node.
+ */
+exports.compile = function (compiler, args, content, parents, options, blockName, token) {
+  var branches = [],
+    currentTest = token.irExpr,
+    currentBody = [],
+    sawElse = false,
+    filename = options && options.filename;
+
+  function flush() {
+    branches.push(ir.ifBranch(currentTest, [ir.legacyJS(compiler(currentBody, parents, options, blockName))]));
+  }
+
+  utils.each(content, function (child) {
+    if (child && child.name === 'elif') {
+      if (sawElse) { utils.throwError('"elif" after "else" in "if" tag', null, filename); }
+      flush();
+      currentTest = child.irExpr;
+      currentBody = [];
+    } else if (child && child.name === 'else') {
+      if (sawElse) { utils.throwError('Multiple "else" branches in "if" tag', null, filename); }
+      flush();
+      currentTest = null;
+      currentBody = [];
+      sawElse = true;
+    } else {
+      currentBody.push(child);
+    }
+  });
+  flush();
+
+  return ir.ifStmt(branches);
+};

package/lib/tags/import.js

@@ -0,0 +1,250 @@
+/*!
+ * Jinja2 `{% import %}` tag.
+ *
+ * Jinja2 import syntax:
+ *
+ *   {% import "partial.html" as form %}
+ *
+ * Loads a template and imports every `{% macro %}` it defines into a
+ * namespace bound to `_ctx.<alias>`. Each imported macro is rendered
+ * to JS via `backend.compile`; the compile step performs regex surgery
+ * on that rendered JS to rewrite `_ctx.<macroName>` →
+ * `_ctx.<alias>.<macroName>`, including sibling-macro references
+ * (the `(?!<allMacros>)` negative lookahead).
+ *
+ * The regex surgery is swig-specific coupling on the exact JS source
+ * shape a Macro IR emits — it fails the flavor-invariant test and stays
+ * on `IRLegacyJS`. The tag returns a JS source string from `compile`; the
+ * backend lifts it into `IRLegacyJS` at emit time. When the macro-name →
+ * namespace rewrite moves into the emitter itself, the tag collapses to a
+ * dedicated `IRImport` node.
+ *
+ * The plural `{% from "file" import a, b %}` shorthand is the sibling
+ * `from` tag. Dynamic paths (`{% import dyn as ns %}`) are deferred.
+ * Context modifiers (`with` / `without context`) are not honored here —
+ * imported macros always see the caller context (swig's macro model;
+ * a documented divergence from Jinja2's without-context import default).
+ *
+ * The alias is a bare identifier — dotted paths are rejected at parse
+ * time, and CVE-2023-25345 prototype-chain names are rejected before
+ * the namespace assignment. Single-name binding slots reject any `.`
+ * in the match before the `_dangerousProps` check.
+ */
+
+var utils = require('@rhinostone/swig-core/lib/utils');
+var ir = require('@rhinostone/swig-core/lib/ir');
+var backend = require('@rhinostone/swig-core/lib/backend');
+var _dangerousProps = require('@rhinostone/swig-core/lib/security').dangerousProps;
+
+var lexer = require('../lexer');
+
+exports.ends = false;
+exports.block = true;
+
+/**
+ * Parse the `{% import %}` tag body. Extracts the STRING literal path,
+ * the `as` keyword, and the bare-identifier alias; validates the alias
+ * against the bare-identifier rule and the CVE-2023-25345
+ * `_dangerousProps` blocklist.
+ *
+ * Walks the imported template's token list (via `swig.parseFile`). For
+ * each `{% macro %}` token, invokes its `compile` to get the IRMacro node
+ * and renders it to JS through `backend.compile`. For each nested
+ * `{% import %}` / `{% from %}` token (the imported file's own imports),
+ * carries its compiled setup through flagged `isImport` (with `boundNames`)
+ * so macros defined here can reference it at call time. The resulting
+ * entries + the alias string are stashed on `token.args` —
+ * `exports.compile` pops the alias off the tail, re-homes any nested
+ * imports under it, and performs the namespace-prefix rewrite on each
+ * macro's compiled JS.
+ *
+ * @param  {string} str    Tag body.
+ * @param  {number} line   Source line of the opening `{%`.
+ * @param  {object} parser The Jinja2 parser module (unused — the body is
+ *                         lexed locally).
+ * @param  {object} types  Jinja2 lexer token-type enum.
+ * @param  {Array}  stack  Open-tag stack (unused — import has no body).
+ * @param  {object} opts   Per-call options. Honors `opts.filename` for
+ *                         `resolveFrom` + filename-aware throws.
+ * @param  {object} swig   Swig instance. Must expose `parseFile`.
+ * @param  {object} token  In-progress TagToken. `token.args` gets the
+ *                         `[{compiled, name}, ..., alias]` list.
+ * @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 pathTok = consume();
+  if (!pathTok) {
+    utils.throwError('Expected template path in "import" tag', line, opts.filename);
+  }
+  if (pathTok.type !== types.STRING) {
+    utils.throwError('Dynamic "import" is not supported — path must be a string literal', line, opts.filename);
+  }
+
+  var asTok = consume();
+  if (!asTok || asTok.type !== types.VAR || asTok.match !== 'as') {
+    utils.throwError('Expected "as" keyword after path in "import" tag', line, opts.filename);
+  }
+
+  var aliasTok = consume();
+  if (!aliasTok || aliasTok.type !== types.VAR) {
+    utils.throwError('Expected namespace alias after "as" in "import" tag', line, opts.filename);
+  }
+  if (aliasTok.match.indexOf('.') !== -1) {
+    utils.throwError('Import alias "' + aliasTok.match + '" must be a bare identifier in "import" tag', line, opts.filename);
+  }
+  if (_dangerousProps.indexOf(aliasTok.match) !== -1) {
+    utils.throwError('Unsafe import alias "' + aliasTok.match + '" is not allowed (CVE-2023-25345)', line, opts.filename);
+  }
+
+  if (peek()) {
+    utils.throwError('Unexpected token "' + peek().match + '" after alias in "import" tag', line, opts.filename);
+  }
+
+  var path = pathTok.match.replace(/^['"]|['"]$/g, '');
+
+  if (opts && opts.codegenMode === 'async') {
+    // Async mode skips the parse-time parseFile + macro pre-render.
+    // compile() emits IRImportDeferred; runtime resolves the template via
+    // _swig.getTemplate and binds .exports under the alias.
+    token.args = [path, aliasTok.match];
+    return true;
+  }
+
+  if (!swig || typeof swig.parseFile !== 'function') {
+    utils.throwError('"import" tag requires an engine context with a loader', line, opts.filename);
+  }
+
+  var parseOpts = { resolveFrom: opts.filename };
+  var compileOpts = utils.extend({}, opts, parseOpts);
+  var parsed = swig.parseFile(path, parseOpts);
+  var macros = [];
+
+  utils.each(parsed.tokens, function (tk) {
+    if (!tk || typeof tk.compile !== 'function') {
+      return;
+    }
+    // The imported file may itself import macros, via `{% import "x" as y %}`
+    // or `{% from "x" import a, b %}`. Carry those nested imports through so
+    // a macro defined here that references a name they bind resolves at call
+    // time — without them the call compiles against a namespace/binding that
+    // was never set up, and silently renders empty.
+    //
+    // Imports stay local to their defining template: compile() re-homes
+    // every bound name under THIS import's alias (`_ctx.<alias>.<boundName>`),
+    // so none is visible bare in the parent scope. `tk.args` is already
+    // parsed; slice() avoids the pop() in compile() mutating the cached token.
+    if (tk.name === 'import' || tk.name === 'from') {
+      // Names the nested import binds into _ctx: `{% import %}` binds one
+      // namespace alias (the tail of args); `{% from %}` binds one per
+      // requested entry (its alias name).
+      var boundNames = (tk.name === 'import')
+        ? [tk.args[tk.args.length - 1]]
+        : utils.map(tk.args, function (a) { return a.aliasName; });
+      macros.push({
+        compiled: tk.compile(null, tk.args.slice(), tk.content, [], compileOpts) + '\n',
+        isImport: true,
+        boundNames: boundNames
+      });
+      return;
+    }
+    if (tk.name !== 'macro') {
+      return;
+    }
+    var macroName = tk.args[0];
+    var macroIR = tk.compile(backend.compile, tk.args, tk.content, [], compileOpts);
+    var compiled = backend.compile([macroIR], [], compileOpts) + '\n';
+    macros.push({ compiled: compiled, name: macroName });
+  });
+
+  token.args = macros.concat([aliasTok.match]);
+  return true;
+};
+
+/**
+ * Emit the namespace-prefix rewrite. Pops the alias off the tail of
+ * `args` and splits the rest into macros and nested imports (flagged
+ * `isImport` by parse()). Builds a `_ctx.<name>(\\W)(?!<allMacros>)`
+ * regex for each imported macro and rewrites every occurrence in each
+ * macro's compiled JS to `_ctx.<alias>.<name>`. Nested imports are
+ * emitted first, re-homed under the alias (`_ctx.<boundName>` ->
+ * `_ctx.<alias>.<boundName>`) so a file's own imports stay local and
+ * never leak bare into the parent scope; the same re-homing is applied
+ * to macro bodies that reference any bound name. Concatenates after the
+ * `_ctx.<alias> = {};` namespace-init line and returns a JS source string
+ * (the backend lifts it into `IRLegacyJS`).
+ *
+ * @return {string} JS source that initialises `_ctx.<alias>`, re-homes
+ *                  any nested imports under it, and assigns every
+ *                  imported macro into it.
+ */
+exports.compile = function (compiler, args, content, parents, options) {
+  // Async-codegen branch. Parse stashed `[path, alias]` in async mode (no
+  // macro pre-render); emit IRImportDeferred so the backend's
+  // `_swig.getTemplate` + `.exports` bind happens at runtime.
+  if (options && options.codegenMode === 'async') {
+    return ir.importDeferred(
+      ir.literal('string', args[0]),
+      args[args.length - 1],
+      options.filename || ''
+    );
+  }
+  var ctx = args.pop();
+  var macros = [];
+  var nested = [];
+  utils.each(args, function (a) {
+    (a.isImport ? nested : macros).push(a);
+  });
+  var allMacros = utils.map(macros, function (arg) { return arg.name; }).join('|');
+  var out = '_ctx.' + ctx + ' = {};\n  var _output = "";\n';
+  var replacements = utils.map(macros, function (arg) {
+    return {
+      ex: new RegExp('_ctx\\.' + arg.name + '(\\W)(?!' + allMacros + ')', 'g'),
+      re: '_ctx.' + ctx + '.' + arg.name + '$1'
+    };
+  });
+  // Re-home every name a nested import binds under THIS alias so it stays
+  // local to the imported file (Jinja2 scoping) and never leaks bare into the
+  // parent: `_ctx.<boundName>` -> `_ctx.<alias>.<boundName>`, applied to both
+  // the nested setup JS and every macro body below that references it.
+  // Compounds across import depth (a 3-level chain re-homes at each layer
+  // with no special-casing).
+  var innerReplacements = [];
+  utils.each(nested, function (a) {
+    utils.each(a.boundNames, function (nm) {
+      innerReplacements.push({
+        ex: new RegExp('_ctx\\.' + nm + '(\\W)', 'g'),
+        re: '_ctx.' + ctx + '.' + nm + '$1'
+      });
+    });
+  });
+
+  // Nested imports first, re-homed under the alias, so the macros defined
+  // below resolve them at call time.
+  utils.each(nested, function (a) {
+    var c = a.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;
+};