mikser-io-render-liquid 4.2.1 → 4.2.3

package/index.js

@@ -142,6 +142,12 @@ export function parseReferences(source) {
     // 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'])
+    // A filter that supplies a fallback is a guard, exactly as `{% if %}` is:
+    // `{{ hero.title | default: meta.title }}` renders correctly for a document
+    // that omits hero.title, so calling it required would report a working page
+    // as wrong.
+    const FALLBACK_FILTERS = new Set(['default'])
+    const hasFallback = (value) => (value?.filters ?? []).some(f => FALLBACK_FILTERS.has(f.name))
     // 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.
@@ -234,7 +240,17 @@ export function parseReferences(source) {
                     // variable ref.
                     const content = node.token?.content ?? ''
                     const path = extractPath(content)
-                    if (path) record(path, scope, guarded)
+                    if (path) record(path, scope, guarded || hasFallback(node.value))
+                    // A filter's ARGUMENTS are read too. `{{ a | default: b }}`
+                    // reads b, and unconditionally — it is the fallback, so it
+                    // is what renders when a is absent. Leaving it unrecorded
+                    // made it look like a key nothing consumes.
+                    for (const filter of node.value?.filters ?? []) {
+                        for (const arg of filter.args ?? []) {
+                            const argPath = pathOfToken(arg)
+                            if (argPath) record(argPath, scope, guarded)
+                        }
+                    }
                     break
                 }
                 case 'IncludeTag':
@@ -262,6 +278,16 @@ export function parseReferences(source) {
                         // 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.
+                        // Whether a given argument carries a fallback filter,
+                        // read from the RAW tag text: liquidjs parses a hash
+                        // value down to a bare path token and drops the filter
+                        // from the structured form, so there is nothing else to
+                        // look at. Best-effort by necessity, and wrong only in
+                        // the direction of calling something optional.
+                        const rawArgs = String(node.token?.args ?? node.token?.content ?? '')
+                        const argHasFallback = (name) => new RegExp(
+                            `\\b${name}\\s*:\\s*[A-Za-z_$][\\w$.]*\\s*\\|\\s*(?:${[...FALLBACK_FILTERS].join('|')})\\b`,
+                        ).test(rawArgs)
                         for (const [name, token] of Object.entries(node.hash?.hash ?? {})) {
                             const path = pathOfToken(token)
                             if (!path) continue
@@ -269,7 +295,7 @@ export function parseReferences(source) {
                             // 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)
+                            entry.args[name] = record(path, scope, guarded || argHasFallback(name))
                         }
                         // `{% render 'x' with item as t %}` — the same binding
                         // written positionally.
@@ -293,10 +319,23 @@ export function parseReferences(source) {
                     const raw = [...found][0] ?? null
                     const from = raw ? record(raw, scope, guarded) : null
                     if (node.key) {
-                        assigns.push({ key: node.key, from })
+                        // `derived` travels with it: the closure walker applies
+                        // these assigns as bindings too, and it has no other way
+                        // to know the value went through a filter.
+                        const derived = !!(node.value?.filters ?? []).length
+                        assigns.push({ key: node.key, from, ...(derived ? { derived } : {}) })
                         // Bound for the REST of this template, which is what
                         // `assign` means — everything after it sees the alias.
-                        if (from) scope[node.key] = from
+                        //
+                        // NOT bound when the value passed through a filter: the
+                        // result is DERIVED, so a read on it says nothing about
+                        // the source. `{% assign rows = c.specs | split: '|' %}`
+                        // turns a string into a list, and binding it would let a
+                        // loop over `rows` report `specs[]` — a key the document
+                        // does not have and cannot be given, since specs is the
+                        // string being split. The source itself is still
+                        // recorded above, which is the true dependency.
+                        if (from && !derived) scope[node.key] = from
                     }
                     break
                 }

package/package.json

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

package/test/references.test.js

@@ -161,3 +161,99 @@ describe('liquid parseReferences: aliases through nesting', () => {
         assert.ok(r.variables.includes('data.meta.hero.tagRows'))
     })
 })
+
+// A fallback filter is a guard.
+//
+// `{{ hero.title | default: meta.title }}` renders correctly for a document
+// that omits hero.title — the layout was written to work without it, exactly as
+// with `{% if %}`. Calling it required reports a working page as wrong, and
+// `missing` is the one list that must only ever mean "probably wrong".
+describe('liquid parseReferences: default: as a guard', () => {
+    it('marks a defaulted output as optional', () => {
+        const r = parseReferences('{{ data.meta.hero.title | default: data.meta.title }}')
+        assert.ok(r.optional.includes('data.meta.hero.title'),
+            `optional: ${r.optional.join(', ')}`)
+    })
+
+    it('still records it as consumed — optional is not unread', () => {
+        const r = parseReferences('{{ data.meta.hero.title | default: data.meta.title }}')
+        assert.ok(r.variables.includes('data.meta.hero.title'))
+        // The fallback's own source is read too, and unconditionally.
+        assert.ok(r.variables.includes('data.meta.title'))
+        assert.ok(!r.optional.includes('data.meta.title'))
+    })
+
+    it('leaves an undefaulted sibling required', () => {
+        const r = parseReferences(
+            '{{ data.meta.hero.title | default: data.meta.title }}{{ data.meta.hero.subtitle }}')
+        assert.ok(r.optional.includes('data.meta.hero.title'))
+        assert.ok(!r.optional.includes('data.meta.hero.subtitle'))
+    })
+
+    it('does not treat an ordinary filter as a guard', () => {
+        const r = parseReferences('{{ data.meta.hero.title | upcase }}')
+        assert.deepEqual(r.optional, [])
+    })
+
+    it('marks a defaulted PARTIAL ARGUMENT as optional', () => {
+        // liquidjs parses a hash value down to a bare path token and drops the
+        // filter, so this is read from the raw tag text — the only place it
+        // survives.
+        const r = parseReferences(
+            "{% render 'ui/tag', label: data.meta.after | default: 'x', other: data.meta.plain %}")
+        assert.ok(r.optional.includes('data.meta.after'), `optional: ${r.optional.join(', ')}`)
+        assert.ok(!r.optional.includes('data.meta.plain'), 'an undefaulted argument stays required')
+    })
+
+    it('resolves the defaulted argument through scope, like any other', () => {
+        const r = parseReferences(
+            '{% assign r = data.meta.results %}'
+            + "{% render 'ui/tag', label: r.afterLabel | default: 'x' %}")
+        assert.ok(r.optional.includes('data.meta.results.afterLabel'),
+            `optional: ${r.optional.join(', ')}`)
+    })
+})
+
+// A filtered value is DERIVED, not an alias.
+//
+// `{% assign rows = c.specs | split: '|' %}` turns a string into a list, so a
+// read of `rows[0]` says nothing about `specs` having members. Treating it as an
+// alias reports `specs[]` as a required key of a document whose `specs` IS the
+// string being split — a key no document can ever satisfy, on a page that
+// renders correctly.
+describe('liquid parseReferences: derived values are not aliases', () => {
+    it('records the source but does not extend paths under it', () => {
+        const r = parseReferences(
+            "{% assign rows = data.meta.specs | split: '|' %}"
+            + '{% for row in rows %}{{ row.name }}{% endfor %}')
+        assert.ok(r.variables.includes('data.meta.specs'), 'the real dependency is still recorded')
+        assert.ok(!r.variables.some(v => v.startsWith('data.meta.specs[')),
+            `fabricated a member of a string: ${r.variables.join(', ')}`)
+    })
+
+    it('marks the assign derived so a closure walker knows too', () => {
+        // The walker applies these as bindings as well, and has no other way to
+        // know the value went through a filter.
+        const r = parseReferences("{% assign rows = data.meta.specs | split: '|' %}")
+        assert.equal(r.assigns.find(a => a.key === 'rows')?.derived, true)
+    })
+
+    it('leaves an UNFILTERED alias working', () => {
+        const r = parseReferences('{% assign hero = data.meta.hero %}{{ hero.title }}')
+        assert.ok(r.variables.includes('data.meta.hero.title'))
+        assert.ok(!r.assigns.find(a => a.key === 'hero')?.derived)
+    })
+
+    it('handles the real shape: split, loop, split again', () => {
+        // Verbatim from the project that surfaced this.
+        const r = parseReferences(
+            "{% assign rows = data.meta.results.cases | split: '|' %}"
+            + '{% for row in rows %}'
+            + "{% assign kv = row | split: ':' %}"
+            + '<dt>{{ kv[0] }}</dt>'
+            + '{% endfor %}')
+        assert.ok(r.variables.includes('data.meta.results.cases'))
+        assert.ok(!r.variables.some(v => /results\.cases\[/.test(v)),
+            `fabricated: ${r.variables.filter(v => v.includes('cases')).join(', ')}`)
+    })
+})