mikser-io-render-liquid 2.1.0 → 4.0.0

package/README.md

@@ -14,16 +14,21 @@ npm install mikser-io-render-liquid
 
 ```js
 // mikser.config.js
+import { layouts } from 'mikser-io'
+import { renderLiquid } from 'mikser-io-render-liquid'
+
 export default {
-  renderer: 'liquid',
-  'render-liquid': {
-    jsTruthy: true,
-    strictFilters: false
-  }
+  plugins: [
+    layouts(),
+    renderLiquid({
+      jsTruthy: true,
+      strictFilters: false
+    }),
+  ]
 }
 ```
 
-The `render-liquid` config object is passed through to the `Liquid` constructor — see [LiquidJS options](https://liquidjs.com/api/interfaces/LiquidOptions.html). Defaults applied by the plugin:
+The options object is passed through to the `Liquid` constructor — see [LiquidJS options](https://liquidjs.com/api/interfaces/LiquidOptions.html). Defaults applied by the plugin:
 
 - `root: options.layoutsFolder`
 - `extname: '.liquid'`

package/index.js

@@ -1,7 +1,23 @@
 import { Liquid } from 'liquidjs'
+import { AsyncLocalStorage } from 'node:async_hooks'
 
 let engine
 
+// Per-render context propagated through LiquidJS's async chain via
+// Node's AsyncLocalStorage. The render() function below sets the
+// context; the wrapped _parsePartialFile / _parseLayoutFile (called
+// by IncludeTag.render, RenderTag.render, LayoutTag.render for each
+// include/render/layout invocation) read it back to report partial
+// usage to the engine.
+const renderContext = new AsyncLocalStorage()
+
+function trackPartial(name) {
+    const ctx = renderContext.getStore()
+    if (!ctx?.track || !ctx.layouts || !name) return
+    const layout = ctx.layouts[name]
+    if (layout?.id) ctx.track.partial(layout.id)
+}
+
 export function load({ runtime, options, config }) {
     if (!engine) {
         // `root` still points at the layouts folder so LiquidJS's own
@@ -14,23 +30,65 @@ export function load({ runtime, options, config }) {
             root: options.layoutsFolder,
             extname: '.liquid',
             cache: !options.watch,
+            // LiquidJS defaults strictFilters to false, which makes an
+            // unknown filter a no-op that returns its input unchanged.
+            // That is a bad default HERE specifically, because which
+            // filters exist depends on which render plugins are loaded:
+            // every function on `runtime` is registered as one below. So
+            // `{{ '/contacts' | href }}` with renderHref() missing from the
+            // plugin list renders the string back, and a missing plugin is
+            // indistinguishable from a working helper.
+            //
+            // strictVariables is deliberately NOT set. It would throw on
+            // any undefined variable, which templates legitimately rely on
+            // being empty — a far larger change than this issue is about.
+            strictFilters: true,
+            // Spread last, so a project can put either back.
             ...config,
         })
+
+        // Wrap LiquidJS's per-invocation partial/layout loaders.
+        // IncludeTag.render and RenderTag.render call
+        // engine._parsePartialFile(filepath, …) for each `{% include %}` /
+        // `{% render %}`; LayoutTag.render calls
+        // engine._parseLayoutFile(filepath, …) for `{% layout %}`.
+        // These fire on every invocation — even when the partial's
+        // parse is cache-hit — so they're the right granularity for
+        // tracking per-render usage.
+        const _parsePartialFile = engine._parsePartialFile.bind(engine)
+        engine._parsePartialFile = function (file, sync, currentFile) {
+            trackPartial(file)
+            return _parsePartialFile(file, sync, currentFile)
+        }
+        const _parseLayoutFile = engine._parseLayoutFile.bind(engine)
+        engine._parseLayoutFile = function (file, sync, currentFile) {
+            trackPartial(file)
+            return _parseLayoutFile(file, sync, currentFile)
+        }
     }
     runtime.liquid = (source, data) => engine.parseAndRender(source, data)
 }
 
-export async function render({ entity, runtime }) {
-    // Expose every function on runtime as a Liquid filter,
-    // so render-helper plugins (markdown, href, ...) keep working without per-plugin glue.
+export async function render({ entity, runtime, state, track }) {
+    // Expose every function on runtime as a Liquid filter, so render-
+    // helper plugins (markdown, href, ...) keep working without per-
+    // plugin glue.
     for (let key in runtime) {
         if (typeof runtime[key] === 'function') {
             engine.registerFilter(key, (input, ...args) => runtime[key](input, ...args))
         }
     }
     const source = entity.layout.content ?? ''
+    const layouts = state?.layouts?.layouts ?? {}
     try {
-        return await runtime.liquid(source, runtime)
+        // Establish the render context BEFORE parsing/rendering. Any
+        // internal partial or layout resolution inherits it through
+        // the async chain and reports the resolved name to the
+        // engine's track via the wrapped methods above.
+        return await renderContext.run(
+            { track, layouts },
+            () => runtime.liquid(source, runtime),
+        )
     } catch (err) {
         // LiquidJS RenderError/ParseError carry a `token` with file/line/col.
         const token = err?.token
@@ -40,3 +98,145 @@ export async function render({ entity, runtime }) {
         throw err
     }
 }
+
+// Static reference scan for `mikser-io-layouts`'s inspect() primitive.
+// Uses LiquidJS's own parser to walk the template AST. Returns the
+// variables, partials, and iterations the source mentions — the
+// authoring-time view of "what could this template reference."
+// The runtime-precise answer ("what did each render actually touch")
+// lives in mikser-io's manifest refClosure.
+//
+// AST nodes we care about:
+//   - Output      → output expression, e.g. {{ post.title | filter }}
+//   - IncludeTag  → {% include 'name' %} — partial reference
+//   - RenderTag   → {% render 'name' %}  — partial reference
+//   - LayoutTag   → {% layout 'name' %}  — partial reference (the
+//                   parent the current template extends)
+//   - ForTag      → {% for x in y %}     — iteration
+//   - IfTag       → recurse into branches for variable refs
+//   - UnlessTag   → same
+//   - CaseTag     → same
+//
+// Other tag types are walked-through (their nested templates are
+// scanned) but don't produce a top-level entry.
+const LIQUID_IDENT_PATH = /([a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*)/
+export function parseReferences(source) {
+    if (typeof source !== 'string' || !source) {
+        return { variables: [], partials: [], iterations: [] }
+    }
+    const probe = new Liquid({})
+    let templates
+    try {
+        templates = probe.parse(source)
+    } catch (err) {
+        return { variables: [], partials: [], iterations: [], parseError: err.message }
+    }
+
+    const variables  = new Set()
+    const partials   = new Set()
+    const iterations = []
+
+    function extractPath(expr) {
+        const m = LIQUID_IDENT_PATH.exec(String(expr ?? '').trim())
+        return m?.[1] ?? null
+    }
+
+    // Walk a LiquidJS Value (used in {% if %}, {% case %}, etc.) and
+    // collect identifier paths. Value has `.initial.postfix[]`; each
+    // postfix item with `props` represents one identifier path; props
+    // are PropertyAccessToken[] whose `.content` joins to the path.
+    function collectValuePaths(value, sink) {
+        const postfix = value?.initial?.postfix
+        if (!Array.isArray(postfix)) return
+        for (const item of postfix) {
+            if (!Array.isArray(item?.props) || !item.props.length) continue
+            const segments = item.props
+                .map(p => typeof p?.content === 'string' ? p.content : null)
+                .filter(Boolean)
+            if (segments.length) sink.add(segments.join('.'))
+        }
+    }
+
+    function getText(maybeWrapped) {
+        if (maybeWrapped == null) return null
+        if (typeof maybeWrapped === 'string') return maybeWrapped
+        if (typeof maybeWrapped.getText === 'function') {
+            try { return maybeWrapped.getText() } catch { return null }
+        }
+        return null
+    }
+
+    function walk(nodes) {
+        if (!Array.isArray(nodes)) return
+        for (const node of nodes) {
+            const kind = node?.constructor?.name
+            switch (kind) {
+                case 'Output': {
+                    // Token content is everything between `{{` and `}}`,
+                    // including filters. Leading identifier path is the
+                    // variable ref.
+                    const content = node.token?.content ?? ''
+                    const path = extractPath(content)
+                    if (path) variables.add(path)
+                    break
+                }
+                case 'IncludeTag':
+                case 'RenderTag':
+                case 'LayoutTag': {
+                    const file = getText(node.file)
+                    if (file) partials.add(file)
+                    // Render/include accept a body in some dialects; walk it.
+                    if (Array.isArray(node.templates)) walk(node.templates)
+                    break
+                }
+                case 'ForTag': {
+                    const collection = getText(node.collection)
+                    if (collection) {
+                        const item = node.variable ?? '(for)'
+                        iterations.push({ item, collection })
+                        const path = extractPath(collection)
+                        if (path) variables.add(path)
+                    }
+                    if (Array.isArray(node.templates))     walk(node.templates)
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates)
+                    break
+                }
+                case 'IfTag':
+                case 'UnlessTag':
+                case 'CaseTag': {
+                    // Branches live on .branches (each has .templates) and .elseTemplates.
+                    // Branch condition is a LiquidJS Value whose `.initial.postfix[]`
+                    // expresses identifier paths; walk them rather than relying on
+                    // string forms that aren't reliably exposed.
+                    if (Array.isArray(node.branches)) {
+                        for (const branch of node.branches) {
+                            collectValuePaths(branch.value, variables)
+                            if (Array.isArray(branch.templates)) walk(branch.templates)
+                        }
+                    }
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates)
+                    break
+                }
+                default: {
+                    // Generic walk — many tags expose nested .templates.
+                    if (Array.isArray(node?.templates))     walk(node.templates)
+                    if (Array.isArray(node?.elseTemplates)) walk(node.elseTemplates)
+                    break
+                }
+            }
+        }
+    }
+
+    walk(templates)
+
+    return {
+        variables:  Array.from(variables).sort(),
+        partials:   Array.from(partials).sort(),
+        iterations,
+    }
+}
+
+// v9 factory — ADR-0010.
+export function renderLiquid(options = {}) {
+    return { name: options.name ?? 'liquid', options, load, render, parseReferences }
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "mikser-io-render-liquid",
-  "version": "2.1.0",
+  "version": "4.0.0",
   "description": "",
   "main": "index.js",
   "type": "module",
-  "scripts": {},
+  "scripts": {
+    "test": "node --no-warnings --test --test-reporter=spec test/**/*.test.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/almero-digital-marketing/mikser-io-render-liquid.git"
@@ -16,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-render-liquid#readme",
   "peerDependencies": {
-    "mikser-io": "^7.12.0"
+    "mikser-io": "^9.0.0"
   },
   "dependencies": {
     "liquidjs": "^10.27.0"

package/test/strict-filters.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { Liquid } from 'liquidjs'
+
+// Why this file exists: every function on `runtime` is registered as a Liquid
+// filter, so WHICH filters exist depends on which render plugins are loaded.
+// With LiquidJS's default strictFilters:false, an unknown filter is a no-op
+// that returns its input — making a missing plugin indistinguishable from a
+// working helper. `{{ '/contacts' | href }}` renders "/contacts" either way.
+describe('strictFilters', () => {
+    // The engine options this plugin builds, mirrored so the behavioural
+    // claims below are about LiquidJS itself, not about a mock.
+    const engine = (over = {}) => new Liquid({ extname: '.liquid', strictFilters: true, ...over })
+
+    it('an unknown filter throws instead of passing the input through', async () => {
+        await assert.rejects(
+            () => engine().parseAndRender("{{ '/contacts' | href }}"),
+            /undefined filter/i,
+        )
+    })
+
+    it('a registered filter still works', async () => {
+        const e = engine()
+        e.registerFilter('href', (input) => `../${String(input).replace(/^\//, '')}`)
+        assert.equal(await e.parseAndRender("{{ '/contacts' | href }}"), '../contacts')
+    })
+
+    it('shows what the old default did — the reason for the change', async () => {
+        // Silent pass-through: the string comes back unchanged and nothing
+        // anywhere reports that `href` does not exist.
+        const loose = new Liquid({ strictFilters: false })
+        assert.equal(await loose.parseAndRender("{{ '/contacts' | href }}"), '/contacts')
+    })
+
+    it('strictVariables is NOT enabled — undefined variables stay empty', async () => {
+        // Deliberate: templates legitimately rely on this, and turning it on
+        // is a far larger change than the filter issue.
+        assert.equal(await engine().parseAndRender('[{{ nope }}]'), '[]')
+    })
+
+    it('a project can put the old behaviour back', async () => {
+        // `...config` is spread after the defaults in load(), so userland wins.
+        const e = engine({ strictFilters: false })
+        assert.equal(await e.parseAndRender("{{ '/x' | href }}"), '/x')
+    })
+})
+
+describe('the plugin sets it', () => {
+    it('index.js enables strictFilters, and spreads config afterwards', async () => {
+        const src = await readFile(new URL('../index.js', import.meta.url), 'utf8')
+        assert.match(src, /strictFilters: true/)
+        // Order is load-bearing: config must come last to remain an override.
+        assert.ok(src.indexOf('strictFilters: true') < src.indexOf('...config'),
+                  'config must be spread AFTER the defaults')
+    })
+
+    it('does not enable strictVariables', async () => {
+        const src = await readFile(new URL('../index.js', import.meta.url), 'utf8')
+        assert.ok(!/strictVariables:\s*true/.test(src))
+    })
+})