@rhinostone/swig-django 2.7.0

package/README.md

@@ -0,0 +1,57 @@
+@rhinostone/swig-django
+=======================
+
+[![NPM version](https://img.shields.io/npm/v/@rhinostone/swig-django.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig-django) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig-django)](https://socket.dev/npm/package/@rhinostone/swig-django)
+
+Django Template Language frontend for the [@rhinostone/swig-core](https://www.npmjs.com/package/@rhinostone/swig-core) template engine. Part of the multi-flavor architecture introduced in `2.0.0` — see [ROADMAP.md](https://github.com/gina-io/swig/blob/develop/ROADMAP.md) for the release narrative.
+
+Installation
+------------
+
+    npm install @rhinostone/swig-django
+
+This pulls in `@rhinostone/swig-core` as a peer dependency, pinned to the matching version. Frontends and the core release in lockstep — do not mix versions.
+
+Basic example
+-------------
+
+```js
+var swig = require('@rhinostone/swig-django');
+
+var out = swig.render('Hello, {{ name|upper }}!', {
+  locals: { name: 'world' }
+});
+// => Hello, WORLD!
+```
+
+Supported surface (as of 2.7.0)
+-------------------------------
+
+Renders real Django templates — everything below was cross-checked against Django 5.2.
+
+* **Tags** — `if` / `elif` / `else`, `for` / `empty` (with `forloop`), `block`, `extends`, `include`, `with`, `autoescape`, `spaceless`, `comment`, `verbatim`, `cycle`, `firstof`.
+* **Variable resolution** — Django-faithful attribute / dictionary / index lookup. Callable attributes are auto-called (honoring `alters_data` / `do_not_call_in_templates`), numeric indexing works (`{{ list.0 }}`), and dicts iterate via `.keys` / `.values` / `.items`.
+* **Filter arguments** — Django colon syntax (`{{ value|date:"Y-m-d" }}`).
+* **Filters** — 42 built-ins (`add`, `addslashes`, `capfirst`, `center`, `cut`, `date`, `default`, `default_if_none`, `divisibleby`, `escape` / `e`, `escapejs`, `filesizeformat`, `first`, `floatformat`, `force_escape`, `get_digit`, `iriencode`, `join`, `last`, `length`, `linebreaks`, `linebreaksbr`, `linenumbers`, `ljust`, `lower`, `make_list`, `phone2numeric`, `pluralize`, `rjust`, `safe`, `slice`, `slugify`, `striptags`, `time`, `title`, `truncatechars`, `truncatewords`, `upper`, `urlencode`, `wordcount`, `wordwrap`, `yesno`). See `lib/filters.js` for the full list.
+* **Async** — `renderFileAsync` / `compileFileAsync` for async loaders, plus `renderFile(path, locals, cb)` against a loader with `async === true`.
+
+Explicitly unsupported (parse-time throw or absent)
+---------------------------------------------------
+
+* No sandboxed-rendering mode — template source is trusted.
+* `{% load %}` and custom tag libraries — no code-loading.
+* `{% url %}`, `{% static %}`, `{% csrf_token %}`, `{% trans %}`, `{% blocktrans %}` — framework infrastructure, out of scope.
+* No whitespace-control (`{%- … -%}`) — not part of the Django Template Language.
+* No `is` tests — Django's `is` is identity comparison, not Jinja2-style tests.
+* `{{ block.super }}`, `{% for … reversed %}`, and one-variable `{% for x in dict.items %}` are deferred (clear parse-time errors).
+* Deferred filters — `dictsort` / `dictsortreversed`, `stringformat`, `random`, `urlize` / `urlizetrunc`, `timesince` / `timeuntil`, `unordered_list`, `json_script`, `truncatechars_html` / `truncatewords_html`, `safeseq`, `pprint`.
+
+Repository
+----------
+
+Source: [gina-io/swig/packages/swig-django](https://github.com/gina-io/swig/tree/develop/packages/swig-django). 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/async/pre-walker.js

@@ -0,0 +1,261 @@
+var utils = require('@rhinostone/swig-core/lib/utils');
+
+/*!
+ * Makes a string safe for a regular expression. Mirrors swig-django's parser.
+ * @private
+ */
+function escapeRegExp(str) {
+  return str.replace(/[\-\/\\\^$*+?.()|\[\]{}]/g, '\\$&');
+}
+
+/*!
+ * Build the splitter regex from the controls trio. Mirrors the regex the
+ * Django parser builds at parse-time so the pre-walker chunks the same way
+ * the real parser would.
+ * @private
+ */
+function buildSplitter(controls) {
+  var anyChar = '[\\s\\S]*?',
+    varOpen = escapeRegExp(controls.varControls[0]),
+    varClose = escapeRegExp(controls.varControls[1]),
+    tagOpen = escapeRegExp(controls.tagControls[0]),
+    tagClose = escapeRegExp(controls.tagControls[1]),
+    cmtOpen = escapeRegExp(controls.cmtControls[0]),
+    cmtClose = escapeRegExp(controls.cmtControls[1]);
+  return new RegExp(
+    '(' +
+      tagOpen + anyChar + tagClose + '|' +
+      varOpen + anyChar + varClose + '|' +
+      cmtOpen + anyChar + cmtClose +
+    ')'
+  );
+}
+
+/*!
+ * Strip tag controls from a tag chunk, returning the trimmed tag body (e.g.
+ * <code>extends "x.html"</code>). Django has no whitespace-control markers,
+ * so there is nothing to strip beyond the controls + surrounding space.
+ * @private
+ */
+function stripTagBody(chunk, tagOpen, tagClose) {
+  var body = chunk.substr(tagOpen.length, chunk.length - tagOpen.length - tagClose.length);
+  return body.replace(/^\s+|\s+$/g, '');
+}
+
+/**
+ * Scan Django template source for static <code>{% extends|include "..." %}</code>
+ * targets. Pure function; performs no I/O.
+ *
+ * The scanner mirrors the Django parser's chunk-splitter so it agrees on
+ * chunk boundaries even under non-default control characters. Dynamic
+ * paths (<code>{% extends parent_var %}</code>) and tag bodies whose
+ * first token isn't a string literal are silently skipped — they remain
+ * on the sync path, which throws appropriately at parse time.
+ *
+ * @example
+ * preWalker.scan('{% include "partial.html" %}', {
+ *   varControls: ['{{', '}}'],
+ *   tagControls: ['{%', '%}'],
+ *   cmtControls: ['{#', '#}'],
+ *   rawTag: 'verbatim',
+ *   keywords: ['extends', 'include']
+ * });
+ * // => [{ kind: 'include', path: 'partial.html' }]
+ *
+ * @param  {string} source
+ * @param  {object} opts
+ * @param  {array}  opts.varControls
+ * @param  {array}  opts.tagControls
+ * @param  {array}  opts.cmtControls
+ * @param  {string} opts.rawTag       Tag name that opens verbatim regions
+ *                                    (<code>verbatim</code> for Django).
+ * @param  {array}  opts.keywords     Keywords whose first quoted argument
+ *                                    is a template path. Django:
+ *                                    <code>['extends', 'include']</code>.
+ * @return {array}                    List of <code>{ kind, path }</code> entries.
+ */
+exports.scan = function (source, opts) {
+  source = source.replace(/\r\n/g, '\n');
+
+  var splitter = buildSplitter(opts),
+    tagOpen = opts.tagControls[0],
+    tagClose = opts.tagControls[1],
+    rawTag = opts.rawTag,
+    endRawTag = 'end' + rawTag,
+    keywordRegex = new RegExp(
+      '^(' + opts.keywords.join('|') + ')\\s+["\\\']([^"\\\']+)["\\\']'
+    ),
+    chunks = source.split(splitter),
+    results = [],
+    inRaw = false,
+    i,
+    chunk,
+    body,
+    name,
+    m;
+
+  for (i = 0; i < chunks.length; i += 1) {
+    chunk = chunks[i];
+    if (typeof chunk !== 'string' || !chunk) {
+      continue;
+    }
+
+    if (!utils.startsWith(chunk, tagOpen) || !utils.endsWith(chunk, tagClose)) {
+      continue;
+    }
+
+    body = stripTagBody(chunk, tagOpen, tagClose);
+    name = body.split(/\s+/)[0];
+
+    if (name === rawTag) {
+      inRaw = true;
+      continue;
+    }
+    if (name === endRawTag) {
+      inRaw = false;
+      continue;
+    }
+    if (inRaw) {
+      continue;
+    }
+
+    m = keywordRegex.exec(body);
+    if (m) {
+      results.push({ kind: m[1], path: m[2] });
+    }
+  }
+
+  return results;
+};
+
+/**
+ * Walk the dependency graph asynchronously starting from <var>entryPath</var>.
+ *
+ * Repeatedly loads, scans, and resolves child template paths in parallel
+ * via the user's async loader, until the dep graph closes. Returns a
+ * Promise resolving to a populated <code>{ resolvedPath: source }</code>
+ * map suitable for backing a memory loader.
+ *
+ * Cycles in the graph are tolerated — once a path is in the map or
+ * pending, subsequent enqueue requests are dropped. The synchronous
+ * renderer's existing circular-extends guard handles cycles at parse
+ * time on the second pass.
+ *
+ * @param  {string}  entryPath  Resolved path of the entry template.
+ * @param  {object}  loader     User loader. Must expose:
+ *                              <code>resolve(to, from)</code> (sync, returns
+ *                              string) and
+ *                              <code>load(id, cb)</code> (async, calls
+ *                              <code>cb(err, source)</code>).
+ * @param  {object}  scanOpts   Pass-through to {@link scan}.
+ * @return {Promise}            Resolves to the populated memory map.
+ */
+exports.walk = function (entryPath, loader, scanOpts) {
+  var memMap = {};
+  var pending = {};
+
+  return new Promise(function (resolve, reject) {
+    var inFlight = 0;
+    var queue = [];
+    var hasError = false;
+
+    function enqueue(path) {
+      if (memMap.hasOwnProperty(path) || pending[path]) {
+        return;
+      }
+      pending[path] = true;
+      queue.push(path);
+    }
+
+    function drain() {
+      while (queue.length > 0 && !hasError) {
+        var path = queue.shift();
+        inFlight += 1;
+        startLoad(path);
+      }
+      if (inFlight === 0 && !hasError && queue.length === 0) {
+        resolve(memMap);
+      }
+    }
+
+    function startLoad(resolvedPath) {
+      loader.load(resolvedPath, function (err, src) {
+        if (hasError) {
+          return;
+        }
+        if (err) {
+          hasError = true;
+          reject(err);
+          return;
+        }
+        if (typeof src !== 'string') {
+          hasError = true;
+          reject(new Error('Async loader returned non-string source for "' + resolvedPath + '"'));
+          return;
+        }
+        memMap[resolvedPath] = src;
+
+        var targets;
+        try {
+          targets = exports.scan(src, scanOpts);
+        } catch (e) {
+          hasError = true;
+          reject(e);
+          return;
+        }
+
+        var i, resolvedChild;
+        for (i = 0; i < targets.length; i += 1) {
+          try {
+            resolvedChild = loader.resolve(targets[i].path, resolvedPath);
+          } catch (e) {
+            hasError = true;
+            reject(e);
+            return;
+          }
+          enqueue(resolvedChild);
+        }
+
+        inFlight -= 1;
+        drain();
+      });
+    }
+
+    enqueue(entryPath);
+    drain();
+  });
+};
+
+/**
+ * Build a sync memory wrapper around a pre-populated
+ * <code>{ resolvedPath: source }</code> map. Delegates <code>resolve</code>
+ * to the user loader so cache keys match what the pre-walker produced.
+ *
+ * @param  {object} userLoader  Original async loader (used for resolve).
+ * @param  {object} memMap      Pre-populated source map.
+ * @return {object}             A loader exposing <code>resolve</code> and
+ *                              <code>load</code>.
+ */
+exports.makeMemoryWrapper = function (userLoader, memMap) {
+  return {
+    resolve: function (to, from) {
+      return userLoader.resolve(to, from);
+    },
+    load: function (id, cb) {
+      var src = memMap[id];
+      if (typeof src !== 'string') {
+        var err = new Error('Pre-walked map missing path: "' + id + '"');
+        if (cb) {
+          cb(err);
+          return;
+        }
+        throw err;
+      }
+      if (cb) {
+        cb(null, src);
+        return;
+      }
+      return src;
+    }
+  };
+};