mikser-io-render-liquid 4.0.0 → 4.2.0

package/index.js

@@ -35,7 +35,7 @@ export function load({ runtime, options, config }) {
             // 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
+            // `{{ '/contacts' | href }}` with hrefUrlHelpers() missing from the
             // plugin list renders the string back, and a missing plugin is
             // indistinguishable from a working helper.
             //
@@ -122,19 +122,51 @@ export async function render({ entity, runtime, state, track }) {
 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: [] }
+        return { variables: [], partials: [], iterations: [], assigns: [], optional: [] }
     }
     const probe = new Liquid({})
     let templates
     try {
         templates = probe.parse(source)
     } catch (err) {
-        return { variables: [], partials: [], iterations: [], parseError: err.message }
+        return { variables: [], partials: [], iterations: [], assigns: [], optional: [], parseError: err.message }
     }
 
     const variables  = new Set()
-    const partials   = new Set()
+    // Paths a template only reads behind a guard. `{% if meta.backdrop %}` and
+    // everything inside that branch is OPTIONAL by construction — the layout
+    // was written to work without it — so reporting such a key as missing from
+    // a document says "probably wrong" about something that is fine.
+    const optional   = new Set()
+    // Liquid resolves these on any array or string rather than looking them up
+    // on the data: `{% if tags.size > 0 %}` asks how many, not for a key called
+    // `size`. Recording them puts engine machinery into a document's contract.
+    const LIQUID_PSEUDO = new Set(['size', 'first', 'last'])
+    // 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())
@@ -166,7 +198,32 @@ export function parseReferences(source) {
         return null
     }
 
-    function walk(nodes) {
+    // 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, guarded = false) => {
+        let resolved = deref(path, scope)
+        if (!resolved) return resolved
+        // Trim a trailing pseudo-property: `hero.tags.size` is a question about
+        // `hero.tags`, not a key of its own.
+        const parts = resolved.split('.')
+        if (parts.length > 1 && LIQUID_PSEUDO.has(parts[parts.length - 1])) {
+            parts.pop()
+            resolved = parts.join('.')
+        }
+        variables.add(resolved)
+        if (guarded) optional.add(resolved)
+        return resolved
+    }
+
+    function walk(nodes, scope = {}, guarded = false) {
         if (!Array.isArray(nodes)) return
         for (const node of nodes) {
             const kind = node?.constructor?.name
@@ -177,28 +234,88 @@ export function parseReferences(source) {
                     // variable ref.
                     const content = node.token?.content ?? ''
                     const path = extractPath(content)
-                    if (path) variables.add(path)
+                    if (path) record(path, scope, guarded)
                     break
                 }
                 case 'IncludeTag':
                 case 'RenderTag':
                 case 'LayoutTag': {
                     const file = getText(node.file)
-                    if (file) partials.add(file)
+                    if (file) {
+                        // `include` shares the CALLER's scope; `render` does
+                        // not. Liquid draws that line deliberately, and a
+                        // contract that ignores it resolves nothing inside an
+                        // included partial: the section registry reads
+                        // `section`, which only means anything because the
+                        // `for` loop that included it is still in view.
+                        const inherits = kind !== 'RenderTag'
+                        const entry = partials.get(file) ?? { name: file, args: {}, aliases: [], inherits, scope: {} }
+                        // The scope an inherited partial was included IN, which
+                        // only the parser can see. `{% include 'sections/_registry' %}`
+                        // inside `{% for section in meta.sections %}` reads
+                        // `section`, and that name means nothing without the
+                        // loop it came from. Merged across call sites, because a
+                        // partial included twice is one contract.
+                        if (inherits) Object.assign(entry.scope, scope)
+                        // 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, guarded)
+                        }
+                        // `{% 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, guarded), 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)
+                    if (Array.isArray(node.templates)) walk(node.templates, scope, guarded)
+                    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, guarded) : 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)
-                        if (path) variables.add(path)
+                        const resolved = path ? record(path, scope, guarded) : null
+                        if (resolved && node.variable) inner[node.variable] = `${resolved}[]`
                     }
-                    if (Array.isArray(node.templates))     walk(node.templates)
-                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates)
+                    if (Array.isArray(node.templates))     walk(node.templates, inner, guarded)
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates, inner, guarded)
                     break
                 }
                 case 'IfTag':
@@ -208,19 +325,38 @@ export function parseReferences(source) {
                     // 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.
+                    // A `case` dispatches on a value the document supplies and
+                    // its branches are alternatives, not guards; `if`/`unless`
+                    // are what make the content inside them optional.
+                    const guards = kind !== 'CaseTag'
+                    // A `case` reads its SUBJECT unconditionally — that is the
+                    // value the document supplies to choose a branch. The
+                    // branches hold the `when` literals, which depend on
+                    // nothing, so reading only those recorded the dispatch as
+                    // consuming no keys at all.
+                    if (kind === 'CaseTag' && node.value) {
+                        const subject = new Set()
+                        collectValuePaths(node.value, subject)
+                        for (const f of subject) record(f, scope)
+                    }
                     if (Array.isArray(node.branches)) {
                         for (const branch of node.branches) {
-                            collectValuePaths(branch.value, variables)
-                            if (Array.isArray(branch.templates)) walk(branch.templates)
+                            const found = new Set()
+                            collectValuePaths(branch.value, found)
+                            // The condition itself is read unconditionally —
+                            // the template always asks — but a document is not
+                            // wrong for answering no.
+                            for (const f of found) record(f, scope, guards)
+                            if (Array.isArray(branch.templates)) walk(branch.templates, scope, guarded || guards)
                         }
                     }
-                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates)
+                    if (Array.isArray(node.elseTemplates)) walk(node.elseTemplates, scope, guarded || guards)
                     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)
+                    if (Array.isArray(node?.templates))     walk(node.templates, scope, guarded)
+                    if (Array.isArray(node?.elseTemplates)) walk(node.elseTemplates, scope, guarded)
                     break
                 }
             }
@@ -231,8 +367,13 @@ export function parseReferences(source) {
 
     return {
         variables:  Array.from(variables).sort(),
-        partials:   Array.from(partials).sort(),
+        partials:   Array.from(partials.values()).sort((a, b) => a.name.localeCompare(b.name)),
         iterations,
+        assigns,
+        // Read only behind a guard. Reported apart rather than dropped: a
+        // consumer deciding whether a document is WRONG needs these excluded,
+        // and a consumer asking what a layout can use needs them present.
+        optional:   Array.from(optional).sort(),
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-render-liquid",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "",
   "main": "index.js",
   "type": "module",

package/test/references.test.js

@@ -0,0 +1,116 @@
+// 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' %}")
+        // `inherits` records that liquid's include shares the caller's scope,
+        // and `scope` carries what was in view at the call site.
+        assert.deepEqual(r.partials,
+            [{ name: 'chrome/nav', args: {}, aliases: [], inherits: true, scope: {} }])
+    })
+})
+
+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}`)
+            }
+        }
+    })
+})