@rhinostone/swig-twig 2.0.0-alpha.3

package/lib/tags/from.js

@@ -0,0 +1,217 @@
+/*!
+ * Phase 3 Session 11 — Twig `{% 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.twig" import input %}
+ *   {% from "forms.twig" import input, textarea %}
+ *   {% from "forms.twig" 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 %}`.
+ *
+ * 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 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 resulting
+ * `[{compiled, origName, aliasName}, ...]` list 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 Twig parser module (unused — body is
+ *                         lexed locally).
+ * @param  {object} types  Twig 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();
+  }
+
+  if (!swig || typeof swig.parseFile !== 'function') {
+    utils.throwError('"from" tag requires an engine context with a loader', line, opts.filename);
+  }
+
+  var path = pathTok.match.replace(/^['"]|['"]$/g, '');
+  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.
+  var macroIndex = {};
+  utils.each(parsed.tokens, function (tk) {
+    if (!tk || tk.name !== 'macro' || typeof tk.compile !== 'function') {
+      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 = 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
+ * `lib/tags/import.js` 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 Twig's "unimported macros are not available"
+ * semantic.
+ *
+ * @return {string} JS source that assigns every imported macro into
+ *                  `_ctx.<aliasName>`. Backend lifts it into
+ *                  `IRLegacyJS`.
+ */
+exports.compile = function (compiler, args) {
+  var allOrigNames = utils.map(args, function (arg) { return arg.origName; }).join('|');
+  var replacements = utils.map(args, function (arg) {
+    return {
+      ex: new RegExp('_ctx\\.' + arg.origName + '(\\W)(?!' + allOrigNames + ')', 'g'),
+      re: '_ctx.' + arg.aliasName + '$1'
+    };
+  });
+
+  var out = '  var _output = "";\n';
+  utils.each(args, function (arg) {
+    var c = arg.compiled;
+    utils.each(replacements, function (re) {
+      c = c.replace(re.ex, re.re);
+    });
+    out += c;
+  });
+
+  return out;
+};

package/lib/tags/if.js

@@ -0,0 +1,57 @@
+/*!
+ * Phase 3 Session 7 — Twig `{% if %}` tag.
+ *
+ * Twig conditional: `{% if <expr> %}…{% endif %}`. The test expression
+ * is parsed via `parser.parseExpr` and attached to `token.irExpr`; the
+ * tag's body content is captured via the parser's open-tag stack
+ * mechanism (parser.js sets `ends: true` so subsequent tokens append to
+ * `token.content` until the matching `{% endif %}` arrives).
+ *
+ * Session 7 ships a single-branch shape — `{% else %}` / `{% elseif %}`
+ * are deferred to a later session. The compile path emits one
+ * IRIfBranch carrying the test IRExpr and the recursively-compiled
+ * body wrapped in IRLegacyJS.
+ */
+
+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 %}` tag body and attach the test IRExpr to
+ * `token.irExpr`.
+ *
+ * @param  {string} str    Tag body (everything between `{%` and `%}`, tag name stripped).
+ * @param  {number} line   Source line of the opening `{%`.
+ * @param  {object} parser The Twig parser module (exposes `parseExpr`).
+ * @param  {object} types  Twig lexer token-type enum.
+ * @param  {Array}  stack  Open-tag stack (managed by parser.js).
+ * @param  {object} opts   Per-call options (honors `opts.filename` for filename-aware throws).
+ * @param  {object} swig   Swig instance (unused).
+ * @param  {object} token  In-progress TagToken. `token.irExpr` is set to the test IRExpr.
+ * @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;
+};
+
+/**
+ * Recursively compile the body content and wrap it as a single-branch
+ * IRIf node. The backend's `If` walker emits the JS `if (<test>) { … }`
+ * envelope.
+ *
+ * @return {object} IRIf node.
+ */
+exports.compile = function (compiler, args, content, parents, options, blockName, token) {
+  var bodyJS = compiler(content, parents, options, blockName);
+  return ir.ifStmt([ir.ifBranch(token.irExpr, [ir.legacyJS(bodyJS)])]);
+};

package/lib/tags/import.js

@@ -0,0 +1,170 @@
+/*!
+ * Phase 3 Session 10 — Twig `{% import %}` tag.
+ *
+ * Twig import syntax:
+ *
+ *   {% import "partial.twig" 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 lifted from the native
+ * `lib/tags/import.js`).
+ *
+ * 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.
+ *
+ * Dynamic paths (`{% import dyn as ns %}`) and the plural
+ * `{% from "file" import a, b %}` shorthand are deferred to a later
+ * Twig-specific session.
+ *
+ * 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. Lexer-folded-path bail per
+ * `.claude/conventions.md § Lexer-folded-path bail`: single-name
+ * binding slots reject any `.` in the match before the
+ * `_dangerousProps` check.
+ */
+
+var utils = require('@rhinostone/swig-core/lib/utils');
+var backend = require('@rhinostone/swig-core/lib/backend');
+var _dangerousProps = require('@rhinostone/swig-core/lib/security').dangerousProps;
+
+var lexer = require('../lexer');
+var _t = require('../tokentypes');
+
+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
+ * `{% macro %}` tokens; for each macro, invokes its `compile` to get
+ * the IRMacro node and renders that node to JS through
+ * `backend.compile`. The resulting `{compiled, name}` objects + the
+ * alias string are stashed on `token.args` — `exports.compile` pops
+ * the alias off the tail 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 Twig parser module (unused — the body is
+ *                         lexed locally).
+ * @param  {object} types  Twig 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);
+  }
+
+  if (!swig || typeof swig.parseFile !== 'function') {
+    utils.throwError('"import" tag requires an engine context with a loader', line, opts.filename);
+  }
+
+  var path = pathTok.match.replace(/^['"]|['"]$/g, '');
+  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 || tk.name !== 'macro' || typeof tk.compile !== 'function') {
+      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`, 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>`. Concatenates the rewritten
+ * bodies after the `_ctx.<alias> = {};` namespace-init line and
+ * returns the result as a JS source string (the backend lifts it into
+ * `IRLegacyJS`).
+ *
+ * @return {string} JS source that initialises `_ctx.<alias>` and
+ *                  assigns every imported macro into it.
+ */
+exports.compile = function (compiler, args) {
+  var ctx = args.pop();
+  var allMacros = utils.map(args, function (arg) { return arg.name; }).join('|');
+  var out = '_ctx.' + ctx + ' = {};\n  var _output = "";\n';
+  var replacements = utils.map(args, function (arg) {
+    return {
+      ex: new RegExp('_ctx\\.' + arg.name + '(\\W)(?!' + allMacros + ')', 'g'),
+      re: '_ctx.' + ctx + '.' + arg.name + '$1'
+    };
+  });
+
+  utils.each(args, function (arg) {
+    var c = arg.compiled;
+    utils.each(replacements, function (re) {
+      c = c.replace(re.ex, re.re);
+    });
+    out += c;
+  });
+
+  return out;
+};

package/lib/tags/include.js

@@ -0,0 +1,170 @@
+/*!
+ * Phase 3 Session 10 — Twig `{% include %}` tag.
+ *
+ * Twig include syntax:
+ *
+ *   {% include "partial.twig" %}
+ *   {% include "partial.twig" with ctx %}
+ *   {% include "partial.twig" with ctx only %}
+ *   {% include "partial.twig" ignore missing %}
+ *   {% include "partial.twig" with ctx only ignore missing %}
+ *   {% include dynamicPath %}
+ *
+ * Path is lowered through `parser.parseExpr`, so STRING literals, VAR
+ * references, member access, conditionals, and any other Twig
+ * expression all route through the same path. The context expression
+ * (after `with`) is likewise parsed via `parseExpr` — object literals,
+ * function results, ternaries all work.
+ *
+ * Three Twig-only keywords are recognised via a depth-tracked scan over
+ * the lexed token stream: `with`, `only`, `ignore missing`. Each is a
+ * bare VAR token at top-level paren/bracket/curly depth — nested
+ * occurrences inside expressions are left alone. `only` requires a
+ * preceding `with`; `ignore` must be followed by `missing`.
+ *
+ * The tag emits an `IRInclude` node. The backend's `Include` branch
+ * (packages/swig-core/lib/backend.js:310) owns the
+ * `_swig.compileFile(...)` + `resolveFrom` plumbing and the optional
+ * `try { ... } catch {}` wrapper that collapses missing-file errors to
+ * the empty string when `ignoreMissing` is set.
+ *
+ * `resolveFrom` is the template's own filename (backslash-escaped so
+ * Windows paths round-trip through the JSON-literal emit). The native
+ * parser's splitter passes it in as a trailing arg; Twig's
+ * tag-dispatch shape carries it via `opts.filename`.
+ */
+
+var ir = require('@rhinostone/swig-core/lib/ir');
+var utils = require('@rhinostone/swig-core/lib/utils');
+
+var lexer = require('../lexer');
+var _t = require('../tokentypes');
+
+exports.ends = false;
+exports.block = false;
+
+/**
+ * Parse the `{% include %}` tag body. Extracts the path expression and
+ * the optional `with <ctx>` / `only` / `ignore missing` keyword
+ * markers, then lowers each expression slice through
+ * `parser.parseExpr`. The resulting IR is attached to `token.irExpr`.
+ *
+ * @param  {string} str    Tag body.
+ * @param  {number} line   Source line of the opening `{%`.
+ * @param  {object} parser The Twig parser module (exposes `parseExpr`).
+ * @param  {object} types  Twig lexer token-type enum.
+ * @param  {Array}  stack  Open-tag stack (unused — include has no body).
+ * @param  {object} opts   Per-call options (honors `opts.filename`).
+ * @param  {object} swig   Swig instance (unused — backend owns load).
+ * @param  {object} token  In-progress TagToken. `token.irExpr` gets
+ *                         the IRInclude node.
+ * @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 depth = 0;
+  var withIdx = -1;
+  var onlyIdx = -1;
+  var ignoreIdx = -1;
+  var missingIdx = -1;
+  var i, tk;
+
+  for (i = 0; i < tokens.length; i += 1) {
+    tk = tokens[i];
+    if (tk.type === types.PARENOPEN || tk.type === types.BRACKETOPEN ||
+        tk.type === types.CURLYOPEN || tk.type === types.FUNCTION) {
+      depth += 1;
+      continue;
+    }
+    if (tk.type === types.PARENCLOSE || tk.type === types.BRACKETCLOSE ||
+        tk.type === types.CURLYCLOSE) {
+      depth -= 1;
+      continue;
+    }
+    if (depth !== 0) { continue; }
+    if (tk.type !== types.VAR) { continue; }
+
+    if (tk.match === 'with' && withIdx === -1 && missingIdx === -1) {
+      withIdx = i;
+    } else if (tk.match === 'only' && onlyIdx === -1) {
+      if (withIdx === -1) {
+        utils.throwError('"only" keyword in "include" tag requires a preceding "with"', line, opts.filename);
+      }
+      onlyIdx = i;
+    } else if (tk.match === 'ignore' && ignoreIdx === -1) {
+      ignoreIdx = i;
+    } else if (tk.match === 'missing' && ignoreIdx !== -1 && missingIdx === -1) {
+      missingIdx = i;
+    }
+  }
+
+  if (ignoreIdx !== -1 && missingIdx === -1) {
+    utils.throwError('"ignore" keyword in "include" tag must be followed by "missing"', line, opts.filename);
+  }
+
+  var pathEnd = tokens.length;
+  if (withIdx !== -1 && withIdx < pathEnd) { pathEnd = withIdx; }
+  if (ignoreIdx !== -1 && ignoreIdx < pathEnd) { pathEnd = ignoreIdx; }
+
+  var pathTokens = sliceTrim(tokens, 0, pathEnd, types);
+  if (!pathTokens.length) {
+    utils.throwError('Expected template path in "include" tag', line, opts.filename);
+  }
+  var pathExpr = parser.parseExpr(pathTokens);
+
+  var ctxExpr;
+  if (withIdx !== -1) {
+    var ctxEnd = tokens.length;
+    if (onlyIdx !== -1 && onlyIdx > withIdx && onlyIdx < ctxEnd) { ctxEnd = onlyIdx; }
+    if (ignoreIdx !== -1 && ignoreIdx > withIdx && ignoreIdx < ctxEnd) { ctxEnd = ignoreIdx; }
+    var ctxTokens = sliceTrim(tokens, withIdx + 1, ctxEnd, types);
+    if (!ctxTokens.length) {
+      utils.throwError('Expected context expression after "with" in "include" tag', line, opts.filename);
+    }
+    ctxExpr = parser.parseExpr(ctxTokens);
+  }
+
+  var resolveFrom = (opts.filename || '').replace(/\\/g, '\\\\');
+
+  token.irExpr = ir.include(
+    pathExpr,
+    ctxExpr,
+    onlyIdx !== -1,
+    ignoreIdx !== -1,
+    resolveFrom
+  );
+  return true;
+};
+
+/**
+ * Strip WHITESPACE tokens from both ends of a slice range, returning a
+ * plain array. The rest of parser.parseExpr skips whitespace itself, so
+ * interior whitespace is harmless — but leading/trailing whitespace can
+ * produce a zero-length slice that parseExpr treats as "empty
+ * expression" without the explicit empty-check here.
+ *
+ * @param  {object[]} tokens Token stream.
+ * @param  {number}   start  Inclusive start index.
+ * @param  {number}   end    Exclusive end index.
+ * @param  {object}   types  Twig lexer token-type enum.
+ * @return {object[]}        Trimmed slice.
+ * @private
+ */
+function sliceTrim(tokens, start, end, types) {
+  while (start < end && tokens[start].type === types.WHITESPACE) { start += 1; }
+  while (end > start && tokens[end - 1].type === types.WHITESPACE) { end -= 1; }
+  return tokens.slice(start, end);
+}
+
+/**
+ * Return the pre-built IRInclude node for the backend's splice-through
+ * path. The backend's `Include` branch owns all plumbing (path +
+ * context emission, isolated-vs-merged selector, resolveFrom, optional
+ * try/catch for ignoreMissing).
+ *
+ * @return {object} IRInclude node from `token.irExpr`.
+ */
+exports.compile = function (compiler, args, content, parents, options, blockName, token) {
+  return token.irExpr;
+};

package/lib/tags/index.js

@@ -0,0 +1,35 @@
+/*!
+ * Phase 3 Session 7 — Twig per-flavor tag registry.
+ *
+ * Each tag exports `{ parse, compile, ends, block }` with a Twig-tailored
+ * shape:
+ *
+ *   parse(str, line, parser, types, stack, opts, swig, token) → boolean
+ *
+ * The 8th `token` argument is the in-progress TagToken. Tag implementations
+ * call `parser.parseExpr(lexer.read(str), filters)` directly and attach the
+ * resulting IRExpr to `token.irExpr`, then return true. This avoids the
+ * native-swig `parser.on(types.X, fn)` callback indirection — Twig tags own
+ * their own arg-parsing path.
+ *
+ * Session 7 begins with an empty registry; subsequent commits within the
+ * session add `set` (assignment) and `if` (flow control) to validate the
+ * per-flavor shape. Future sessions add `for`, `block`, `extends`,
+ * `include`, `import`, `macro`, `apply`, `verbatim`, `with`,
+ * `from … import`.
+ */
+
+module.exports = {
+  'set': require('./set'),
+  'if': require('./if'),
+  'for': require('./for'),
+  'block': require('./block'),
+  'extends': require('./extends'),
+  'include': require('./include'),
+  'macro': require('./macro'),
+  'import': require('./import'),
+  'verbatim': require('./verbatim'),
+  'apply': require('./apply'),
+  'from': require('./from'),
+  'with': require('./with')
+};