mikser-io-render-liquid 4.2.0 → 4.2.2

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.

package/package.json

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

package/test/references.test.js

@@ -114,3 +114,102 @@ describe('liquid parseReferences: shape', () => {
         }
     })
 })
+
+// Aliases nested more than one level deep.
+//
+// A read is only useful as provenance if it names the SOURCE path. Each of
+// these rebinds a value to a new name, twice, and the recorded path has to
+// survive both hops — a contract naming `field.label` describes nothing a
+// document author can act on.
+describe('liquid parseReferences: aliases through nesting', () => {
+    it('follows a loop binding inside a loop', () => {
+        const r = parseReferences(
+            '{% for case in data.meta.results.cases %}'
+            + '{% for spec in case.specs %}{{ spec.name }}{% endfor %}'
+            + '{% endfor %}')
+        assert.ok(r.variables.includes('data.meta.results.cases[].specs[].name'),
+            `got: ${r.variables.join(', ')}`)
+        assert.ok(!r.variables.some(v => v.startsWith('spec.')), 'the local name must not survive')
+    })
+
+    it('follows a loop binding through an assign and back into a loop', () => {
+        const r = parseReferences(
+            '{% assign block = data.meta.enquiry %}'
+            + '{% for field in block.fields %}{{ field.label }}{{ field.type }}{% endfor %}')
+        assert.ok(r.variables.includes('data.meta.enquiry.fields[].label'),
+            `got: ${r.variables.join(', ')}`)
+        assert.ok(r.variables.includes('data.meta.enquiry.fields[].type'))
+    })
+
+    it('resolves a render argument written inside two loops', () => {
+        const r = parseReferences(
+            '{% for group in data.meta.groups %}'
+            + '{% for item in group.items %}'
+            + "{% render 'ui/tag', label: item.title %}"
+            + '{% endfor %}{% endfor %}')
+        const args = r.partials.find(p => p.name === 'ui/tag')?.args ?? {}
+        assert.deepEqual(args, { label: 'data.meta.groups[].items[].title' })
+    })
+
+    it('resolves an argument whose value is itself an alias', () => {
+        const r = parseReferences(
+            '{% assign hero = data.meta.hero %}'
+            + "{% render 'ui/tags', tags: hero.tags, rows: hero.tagRows %}")
+        const args = r.partials.find(p => p.name === 'ui/tags')?.args ?? {}
+        assert.deepEqual(args, { tags: 'data.meta.hero.tags', rows: 'data.meta.hero.tagRows' })
+        assert.ok(r.variables.includes('data.meta.hero.tags'))
+        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(', ')}`)
+    })
+})