@rhinostone/swig-core 2.0.0-alpha.5 → 2.0.0-alpha.8

package/README.md

@@ -0,0 +1,38 @@
+@rhinostone/swig-core
+=====================
+
+[![NPM version](http://img.shields.io/npm/v/@rhinostone/swig-core.svg?style=flat)](https://www.npmjs.org/package/@rhinostone/swig-core) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig-core)](https://socket.dev/npm/package/@rhinostone/swig-core)
+
+> **Experimental alpha — IR ABI is unstable across alpha minors.** This package is the shared runtime for the `@rhinostone/swig` family of template engines. It is not intended for direct consumption unless you are building a custom frontend. Install [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) for the default Swig (Jinja2/Django-inspired) flavor, or [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) for the Twig flavor — both pull this package in as a peer dependency pinned to the exact alpha version.
+
+Extracted from `@rhinostone/swig@1.6.0` during the Phase 1 carve (see #T14 in [ROADMAP.md](https://github.com/gina-io/swig/blob/develop/ROADMAP.md)).
+
+What lives here
+---------------
+
+* **IR types and helpers** (`lib/ir.js`) — the intermediate representation emitted by frontend parsers and consumed by the backend.
+* **Backend** (`lib/backend.js`) — lowers IR to compiled JavaScript source via `new Function(...)`.
+* **Engine wiring** (`lib/engine.js`) — `engine.install(self, frontend)` glues a frontend (tags, filters, parser, lexer) onto the shared runtime.
+* **Expression-level TokenParser** (`lib/tokenparser.js`) — IR emission for inline expressions, shared across frontends.
+* **Runtime primitives** (`lib/utils.js`, `lib/security.js`, `lib/cache.js`, `lib/loaders/`, `lib/filters.js`, `lib/dateformatter.js`, `lib/tokentypes.js`).
+
+Consumers
+---------
+
+* [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) — default Swig flavor.
+* [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) — Twig parity frontend.
+
+Versioning
+----------
+
+During the alpha cycle, every frontend that depends on `@rhinostone/swig-core` pins the **exact** alpha version (no caret, no tilde). The IR ABI is not stable until `2.0.0` stable ships. Do not upgrade `swig-core` independently of the frontend that consumes it.
+
+Repository
+----------
+
+Source lives in the `@rhinostone/swig` monorepo: [gina-io/swig/packages/swig-core](https://github.com/gina-io/swig/tree/develop/packages/swig-core). File issues and PRs at [gina-io/swig](https://github.com/gina-io/swig).
+
+License
+-------
+
+MIT. See [LICENSE](https://github.com/gina-io/swig/blob/develop/LICENSE) in the monorepo root.

package/lib/backend.js

@@ -22,8 +22,6 @@ var utils = require('./utils'),
  * is unchanged. Built-in tags migrate per session by returning IR nodes
  * directly. The `new Function(...)` wrapper stays with the native
  * frontend (filename-aware error attribution, per the seam rule).
- *
- * See .claude/architecture/multi-flavor-ir.md § Phase 2.
  */
 
 /*!
@@ -157,8 +155,7 @@ exports.compile = function (template, parents, options, blockName) {
       // dot+bracket) stay on the transitional string fragment — the
       // bracket-lvalue contract is a cross-flavor design call and is
       // deferred. The frontend's set-tag parse handler retains its own
-      // _dangerousProps guards on every LHS path segment per the
-      // duplication invariant in .claude/security.md.
+      // _dangerousProps guards on every LHS path segment.
       // `value` is an IRExpr node (Session 14b) — backward-compat string
       // fallback preserved for userland setTag tags that may still hand
       // in a raw JS fragment. Emits `<target> <op> <value>;`.
@@ -463,16 +460,15 @@ exports.compile = function (template, parents, options, blockName) {
  * The emitter enforces the CVE-2023-25345 blocklist on every {@link
  * IRVarRef} path segment and every string-literal {@link IRAccess} key,
  * mirroring the guards on the frontend's TokenParser + tag-parse paths.
- * The frontend-side guards stay live per `.claude/security.md`; the
- * duplicate is intentional defense-in-depth during the migration.
+ * The frontend-side guards stay live; the duplicate is intentional
+ * defense-in-depth during the migration.
  *
  * `deps` is an optional injection hook:
  *   - `deps.dangerousProps` — override the security blocklist. Defaults
  *     to `require('./security').dangerousProps`.
  *   - `deps.throwError(msg, line, filename)` — override the throw shape.
  *     Defaults to `utils.throwError`, matching the seam rule for
- *     filename-opaque attribution (see
- *     .claude/architecture/multi-flavor-ir.md § Filename-awareness seam).
+ *     filename-opaque attribution.
  *
  * @param  {object} node    IR expression node (any IRExpr shape).
  * @param  {object} [deps]  Optional dependency overrides.

package/lib/cache.js

@@ -6,8 +6,7 @@
  * without closure state. The native Swig constructor wires its inline
  * `self.cache` + `self.options.cache` through these at each call site.
  *
- * See .claude/architecture/multi-flavor-ir.md — cache keys are opaque
- * strings; the cache layer has no filename awareness.
+ * Cache keys are opaque strings; the cache layer has no filename awareness.
  */
 
 /**

package/lib/engine.js

@@ -24,9 +24,8 @@ function efn() { return ''; }
  * not know whether the loader's `resolve` output is a file path, a URL, or
  * a Memcached key.
  *
- * See .claude/architecture/multi-flavor-ir.md — filename-aware code
- * (utils.throwError wrapping, the engine's try/catch that attaches a
- * filename to compile errors) stays in the frontend.
+ * Filename-aware code (utils.throwError wrapping, the engine's try/catch
+ * that attaches a filename to compile errors) stays in the frontend.
  */
 
 /**

package/lib/filters.js

@@ -6,8 +6,7 @@ var utils = require('./utils');
  * Phase 1 carve — `iterateFilter` and the `.safe` flag convention live
  * here so every flavor's filter catalog (native Swig, Twig, Jinja2,
  * Django) picks up identical recursion + autoescape-bypass semantics.
- * Filter catalogs themselves stay per-flavor. See
- * .claude/architecture/multi-flavor-ir.md.
+ * Filter catalogs themselves stay per-flavor.
  */
 
 /**

package/lib/index.js

@@ -4,8 +4,7 @@
  *
  * Phase 1 scaffold. Subsequent commits move security guards, loader
  * contract, filter infra, cache, and the JS-codegen backend in from
- * @rhinostone/swig. See .claude/architecture/multi-flavor-ir.md for
- * the full design.
+ * @rhinostone/swig.
  */
 
 exports.utils = require('./utils');

package/lib/ir.js

@@ -9,9 +9,6 @@
  * Every frontend (native Swig, Twig, Jinja2, Django) must lower its
  * parse tree into these shapes. Constructs that cannot lower cleanly
  * must throw at parse time — no silent partial behavior.
- *
- * See .claude/architecture/multi-flavor-ir.md for the full design doc,
- * trade-offs considered, and open questions.
  */
 
 /**
@@ -268,8 +265,7 @@
  * functions, and built-in tags not yet migrated to real IR nodes. The
  * backend concatenates `js` verbatim into the compiled template body.
  *
- * Transitional per the Phase 2 layering decision (hybrid / option iii);
- * see .claude/architecture/multi-flavor-ir.md.
+ * Transitional per the Phase 2 layering decision (hybrid / option iii).
  *
  * @typedef {Object} IRLegacyJS
  * @property {'LegacyJS'} type
@@ -445,8 +441,7 @@
  *
  * No consumers yet — this commit introduces the schema surface only.
  * Subsequent sessions will migrate the native frontend's token-tree
- * production over to these shapes. See the Phase 2 layering notes in
- * .claude/architecture/multi-flavor-ir.md.
+ * production over to these shapes.
  * ------------------------------------------------------------------ */
 
 /*!

package/lib/security.js

@@ -12,9 +12,6 @@
  * Kept as a shared constant so any future tag that assigns to `_ctx.*`
  * or otherwise exposes an identifier as a property key picks up the
  * full blocklist without drift across copies.
- *
- * See .claude/security.md for the full attack-vector table and the
- * tags/parser checkpoints that consume this list.
  */
 
 /**

package/lib/tokenparser.js

@@ -17,15 +17,13 @@ var utils = require('./utils'),
  * Filter catalogs stay per-flavor — the caller passes its own
  * `filters` map at construction. The `.safe` autoescape-bypass check
  * is preserved verbatim and is the sole gate for the final `e` filter
- * tail-injection. See .claude/security.md § Autoescape is the only
- * default XSS protection.
+ * tail-injection.
  *
  * Error attribution (`utils.throwError(msg, line, filename)`) stays
  * intact: the filename is passed in at construction as an opaque
  * label and used only inside thrown-error messages. TokenParser does
  * not resolve, read, or path-manipulate it — so filename-awareness
- * never crosses the seam back into frontend code. See
- * .claude/architecture/multi-flavor-ir.md § Filename-awareness seam.
+ * never crosses the seam back into frontend code.
  */
 
 // CVE-2023-25345: prototype-chain properties that must never appear as
@@ -33,7 +31,6 @@ var utils = require('./utils'),
 // gives compiled template code access to Object.prototype (__proto__),
 // Object (constructor), or Function (constructor.constructor), which
 // enables arbitrary code execution inside the new Function(...) body.
-// See .claude/security.md.
 var _dangerousProps = require('./security').dangerousProps;
 
 var _reserved = ['break', 'case', 'catch', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'finally', 'for', 'function', 'if', 'in', 'instanceof', 'new', 'return', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void', 'while', 'with'];
@@ -412,8 +409,7 @@ TokenParser.prototype = {
    * VAR segments, DOTKEY matches, STRING-inside-BRACKETOPEN values,
    * FUNCTION / FUNCTIONEMPTY callee names) are mirrored verbatim from
    * {@link TokenParser#parseToken}. Both layers stay live during the
-   * migration per `.claude/security.md § _dangerousProps is duplicated
-   * across layers — DO NOT dedup`.
+   * migration.
    *
    * Parses until end of tokens or an un-nested top-level FILTER /
    * FILTEREMPTY token (filter pipes are an Output-site concern —
@@ -687,8 +683,7 @@ TokenParser.prototype = {
    * segments, STRING-in-BRACKETOPEN, DOTKEY) stay live in {@link
    * TokenParser#parseToken} and {@link TokenParser#parseExpr}. Fallback
    * path re-runs through them via `self.parse()`; IR path hits the
-   * parseExpr copies. See `.claude/security.md § _dangerousProps is
-   * duplicated across layers — DO NOT dedup`.
+   * parseExpr copies.
    *
    * @param  {object[]} tokens  LexerToken[] — the full {{ … }} token stream.
    * @return {object}           IROutput IR node.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig-core",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.8",
   "description": "Shared IR, backend, and runtime for the @rhinostone/swig family of template engines. First publish at 2.0.0-alpha.3 — see @rhinostone/swig #T14 (Phase 1 carve).",
   "keywords": [
     "template",