mikser-io-render-liquid 3.0.0 → 4.0.0

package/index.js

@@ -30,6 +30,20 @@ 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,
         })
 
@@ -85,7 +99,144 @@ export async function render({ entity, runtime, state, track }) {
     }
 }
 
+// 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 }
+    return { name: options.name ?? 'liquid', options, load, render, parseReferences }
 }

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "mikser-io-render-liquid",
-  "version": "3.0.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"

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))
+    })
+})