mikser-io-render-liquid 3.0.0 → 4.1.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 hrefUrlHelpers() 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,232 @@ 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: [], assigns: [] }
+    }
+    const probe = new Liquid({})
+    let templates
+    try {
+        templates = probe.parse(source)
+    } catch (err) {
+        return { variables: [], partials: [], iterations: [], assigns: [], parseError: err.message }
+    }
+
+    const variables  = new Set()
+    // Keyed by partial name and MERGED across call sites: `ui/btn` rendered
+    // eight times with different labels is one partial with the union of what
+    // it is ever passed, which is the question a contract answers.
+    const partials   = new Map()
+    const iterations = []
+    const assigns    = []
+
+    // The path a tag ARGUMENT refers to, or null if it is a literal.
+    //
+    // Type, not text: LIQUID_IDENT_PATH is unanchored, so run over the source
+    // of `variant: 'secondary'` it happily returns `secondary` — a variable
+    // that does not exist, reported as a dependency. A QuotedToken is a value
+    // the template supplied and depends on nothing.
+    function pathOfToken(token) {
+        const kind = token?.constructor?.name
+        if (kind === 'PropertyAccessToken') return token.getText?.() ?? null
+        // A filtered or otherwise compound argument arrives as a Value, whose
+        // identifier paths the branch walker already knows how to read.
+        if (token?.initial) {
+            const found = new Set()
+            collectValuePaths(token, found)
+            return found.size ? [...found][0] : null
+        }
+        return null
+    }
+
+    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
+    }
+
+    // An alias resolved through the scopes in view. Only the first segment can
+    // be one: `c.specs` where `c` is the item of `for c in r.cases` is
+    // `r.cases[].specs`, and the tail is property access on whatever that was.
+    function deref(path, scope) {
+        if (!path) return path
+        const [head, ...rest] = String(path).split('.')
+        const base = scope[head]
+        return base ? [base, ...rest].join('.') : path
+    }
+
+    const record = (path, scope) => {
+        const resolved = deref(path, scope)
+        if (resolved) variables.add(resolved)
+        return resolved
+    }
+
+    function walk(nodes, scope = {}) {
+        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) record(path, scope)
+                    break
+                }
+                case 'IncludeTag':
+                case 'RenderTag':
+                case 'LayoutTag': {
+                    const file = getText(node.file)
+                    if (file) {
+                        const entry = partials.get(file) ?? { name: file, args: {}, aliases: [] }
+                        // The arguments a partial is called WITH. Dropping
+                        // these was the hole: `{% render 'ui/btn', label:
+                        // r.more %}` makes this template depend on `r.more`,
+                        // and nothing recorded that — so a contract built from
+                        // one file could not see a key consumed one file down.
+                        for (const [name, token] of Object.entries(node.hash?.hash ?? {})) {
+                            const path = pathOfToken(token)
+                            if (!path) continue
+                            // Resolved HERE, in the scope the call sits in,
+                            // before the partial ever runs — so a partial
+                            // rendered inside a loop reports what the loop
+                            // hands it, not the loop variable's local name.
+                            entry.args[name] = record(path, scope)
+                        }
+                        // `{% render 'x' with item as t %}` — the same binding
+                        // written positionally.
+                        const withPath = node.with ? pathOfToken(node.with.value) : null
+                        if (withPath) {
+                            entry.aliases.push({ from: record(withPath, scope), to: node.with.alias ?? null })
+                        }
+                        partials.set(file, entry)
+                    }
+                    // Render/include accept a body in some dialects; walk it.
+                    if (Array.isArray(node.templates)) walk(node.templates, scope)
+                    break
+                }
+                case 'AssignTag': {
+                    // `{% assign hero = data.meta.hero %}` renames a path. A
+                    // contract that reports `hero.tags` names a variable local
+                    // to one file; resolving the alias reports
+                    // `data.meta.hero.tags`, which is what the AUTHOR writes.
+                    const found = new Set()
+                    collectValuePaths(node.value, found)
+                    const raw = [...found][0] ?? null
+                    const from = raw ? record(raw, scope) : null
+                    if (node.key) {
+                        assigns.push({ key: node.key, from })
+                        // Bound for the REST of this template, which is what
+                        // `assign` means — everything after it sees the alias.
+                        if (from) scope[node.key] = from
+                    }
+                    break
+                }
+                case 'ForTag': {
+                    const collection = getText(node.collection)
+                    // `[]` marks an element rather than the collection itself.
+                    // Without it `for c in r.cases` reports `r.cases.specs`,
+                    // which is not a key anyone can write — the specs are on
+                    // each case, not on the list.
+                    const inner = { ...scope }
+                    if (collection) {
+                        const item = node.variable ?? '(for)'
+                        iterations.push({ item, collection })
+                        const path = extractPath(collection)
+                        const resolved = path ? record(path, scope) : null
+                        if (resolved && node.variable) inner[node.variable] = `${resolved}[]`
+                    }
+                    if (Array.isArray(node.templates))     walk(node.templates, inner)
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates, inner)
+                    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) {
+                            const found = new Set()
+                            collectValuePaths(branch.value, found)
+                            for (const f of found) record(f, scope)
+                            if (Array.isArray(branch.templates)) walk(branch.templates, scope)
+                        }
+                    }
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates, scope)
+                    break
+                }
+                default: {
+                    // Generic walk — many tags expose nested .templates.
+                    if (Array.isArray(node?.templates))     walk(node.templates, scope)
+                    if (Array.isArray(node?.elseTemplates)) walk(node.elseTemplates, scope)
+                    break
+                }
+            }
+        }
+    }
+
+    walk(templates)
+
+    return {
+        variables:  Array.from(variables).sort(),
+        partials:   Array.from(partials.values()).sort((a, b) => a.name.localeCompare(b.name)),
+        iterations,
+        assigns,
+    }
+}
+
 // 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.1.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/references.test.js

@@ -0,0 +1,113 @@
+// What a liquid template DEPENDS ON — the raw material for the layout contract
+// that mikser_layouts_inspect reports.
+//
+// Two things used to be dropped, and both broke the contract exactly where it
+// becomes useful, at the boundary between one file and the next:
+//
+//   - the ARGUMENTS a partial is called with. `{% render 'ui/tags', tags:
+//     hero.tags %}` makes this template depend on `hero.tags`; recording only
+//     the partial's NAME left a key consumed one file down invisible.
+//   - aliases. A section that opens `{% assign hero = data.meta.hero %}` and
+//     then says `hero.tags` names a key that appears in no document.
+//
+// Aliases are resolved HERE because this is the only place their scope is
+// known: the closure walker downstream sees paths, not tags.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { parseReferences } from '../index.js'
+
+const argsOf = (r, name) => r.partials.find(p => p.name === name)?.args ?? null
+
+describe('liquid parseReferences: partial arguments', () => {
+    it('records the arguments a partial is called with', () => {
+        const r = parseReferences("{% render 'ui/tags', tags: data.meta.hero.tags, rows: data.meta.hero.tagRows %}")
+        assert.deepEqual(argsOf(r, 'ui/tags'), {
+            tags: 'data.meta.hero.tags',
+            rows: 'data.meta.hero.tagRows',
+        })
+    })
+
+    it('counts them as references of the CALLING template', () => {
+        const r = parseReferences("{% render 'ui/btn', label: data.meta.cta %}")
+        assert.ok(r.variables.includes('data.meta.cta'))
+    })
+
+    it('ignores literal arguments, which depend on nothing', () => {
+        // The path regex is unanchored, so a naive reading of `variant:
+        // 'secondary'` yields `secondary` — a variable that does not exist,
+        // reported as a dependency.
+        const r = parseReferences("{% render 'ui/btn', variant: 'secondary', label: data.meta.cta %}")
+        assert.deepEqual(argsOf(r, 'ui/btn'), { label: 'data.meta.cta' })
+        assert.ok(!r.variables.includes('secondary'))
+    })
+
+    it('merges call sites, so one partial is one entry', () => {
+        const r = parseReferences("{% render 'ui/btn', label: a.one %}{% render 'ui/btn', href: a.two %}")
+        assert.equal(r.partials.length, 1)
+        assert.deepEqual(argsOf(r, 'ui/btn'), { label: 'a.one', href: 'a.two' })
+    })
+
+    it('records `with ... as` as an alias', () => {
+        const r = parseReferences("{% render 'ui/card' with data.meta.hero as card %}")
+        assert.deepEqual(r.partials.find(p => p.name === 'ui/card').aliases,
+            [{ from: 'data.meta.hero', to: 'card' }])
+    })
+
+    it('reports a plain include with no arguments', () => {
+        const r = parseReferences("{% include 'chrome/nav' %}")
+        assert.deepEqual(r.partials, [{ name: 'chrome/nav', args: {}, aliases: [] }])
+    })
+})
+
+describe('liquid parseReferences: aliases', () => {
+    it('resolves an assign back to the path it renames', () => {
+        const r = parseReferences('{% assign hero = data.meta.hero %}{{ hero.title }}')
+        assert.ok(r.variables.includes('data.meta.hero.title'),
+            `expected the resolved path, got: ${r.variables.join(', ')}`)
+        assert.ok(!r.variables.includes('hero.title'), 'the local name must not survive')
+    })
+
+    it('reports the assign itself, so a caller can see the renaming', () => {
+        const r = parseReferences('{% assign hero = data.meta.hero %}')
+        assert.deepEqual(r.assigns, [{ key: 'hero', from: 'data.meta.hero' }])
+    })
+
+    it('resolves an assign written in terms of another assign', () => {
+        const r = parseReferences(
+            '{% assign hero = data.meta.hero %}{% assign o = hero.origin %}{{ o.label }}')
+        assert.ok(r.variables.includes('data.meta.hero.origin.label'))
+    })
+
+    it('marks a for-item as an ELEMENT, not as the collection', () => {
+        // `cases.specs` would be a key that exists on no document — the specs
+        // are on each case, not on the list of them.
+        const r = parseReferences('{% for c in data.meta.cases %}{{ c.specs }}{% endfor %}')
+        assert.ok(r.variables.includes('data.meta.cases[].specs'))
+        assert.ok(!r.variables.includes('data.meta.cases.specs'))
+    })
+
+    it('resolves arguments through the loop they are written in', () => {
+        const r = parseReferences(
+            "{% for c in data.meta.cases %}{% render 'ui/tag', label: c.title %}{% endfor %}")
+        assert.deepEqual(argsOf(r, 'ui/tag'), { label: 'data.meta.cases[].title' })
+    })
+
+    it('does NOT leak a loop item past the end of its loop', () => {
+        const r = parseReferences('{% for c in data.meta.cases %}{{ c.a }}{% endfor %}{{ c.b }}')
+        assert.ok(r.variables.includes('data.meta.cases[].a'))
+        assert.ok(r.variables.includes('c.b'), 'outside the loop it is a different, unresolved name')
+        assert.ok(!r.variables.includes('data.meta.cases[].b'))
+    })
+})
+
+describe('liquid parseReferences: shape', () => {
+    it('returns the same keys as every other engine, so no caller branches', () => {
+        for (const source of ['', '{{ a }}', '{% if %}']) {
+            const r = parseReferences(source)
+            for (const key of ['variables', 'partials', 'iterations', 'assigns']) {
+                assert.ok(key in r, `${JSON.stringify(source)} is missing ${key}`)
+            }
+        }
+    })
+})

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