@platformos/platformos-check-common 0.0.16 → 0.0.18

package/src/checks/liquid-html-syntax-error/checks/InvalidAssignSyntax.ts

@@ -0,0 +1,63 @@
+import { LiquidTag } from '@platformos/liquid-html-parser';
+import { Problem, SourceCodeType } from '../../..';
+
+/**
+ * Detects structurally-invalid `assign` tags that neither `MultipleAssignValues` nor
+ * `InvalidPipeSyntax`/`InvalidFilterName` catch:
+ *
+ *   {% assign %}             — empty markup
+ *   {% assign x %}           — target only, no operator
+ *   {% assign x "var" %}     — missing `=`
+ *   {% assign = 'v' %}       — missing target
+ *   {% assign x = %}         — empty RHS
+ *   {% assign 'str' = 'v' %} — target is a literal
+ *   {% assign x := 'v' %}    — operator is not `=`
+ *
+ * When the strict grammar rule `liquidTagAssignMarkup` fails, the parser falls back to
+ * the base case and stores markup as a raw string. That string almost always still
+ * contains `=`-plus-RHS with a filter or pipe issue (handled elsewhere). This check
+ * targets the cases where the `target = value` skeleton itself is broken, so it
+ * complements rather than duplicates the other sub-checks.
+ */
+export function detectInvalidAssignSyntax(
+  node: LiquidTag,
+): Problem<SourceCodeType.LiquidHtml> | undefined {
+  if (node.name !== 'assign') return;
+  if (typeof node.markup !== 'string') return;
+
+  const markup = node.markup.trim();
+
+  const eqIndex = markup.indexOf('=');
+  const hasEquals = eqIndex !== -1;
+  const lhs = hasEquals ? markup.slice(0, eqIndex).trim() : markup;
+  const rhs = hasEquals ? markup.slice(eqIndex + 1).trim() : '';
+
+  const isStructurallyBroken =
+    markup === '' || !hasEquals || lhs === '' || rhs === '' || !isValidAssignTarget(lhs);
+
+  if (!isStructurallyBroken) return;
+
+  return {
+    message: `Invalid syntax for tag 'assign'. Expected syntax: {% assign <var> = <value> %}`,
+    startIndex: node.position.start,
+    endIndex: node.position.end,
+  };
+}
+
+/**
+ * Rejects an LHS that is obviously not an assign target.
+ *
+ * NOTE: the parser's `variableSegment` rule is stricter than the platformOS runtime —
+ * Liquify (see assign_tag_test.rb "allow variable names to start with digit") accepts
+ * `23_hours_ago` as a valid name, but our grammar requires `(letter | "_")` at the
+ * start and falls back to the base case for digit-starting names. To avoid
+ * false-positive lint errors on code that runs fine, this shape check only rejects
+ * LHS forms that are never valid: literal delimiters at the start (`'`, `"`, `[`, `{`)
+ * and stray operator characters (`:` or a second `=`) that indicate the operator
+ * itself is malformed (e.g. `:=`).
+ */
+function isValidAssignTarget(lhs: string): boolean {
+  if (/^['"[{]/.test(lhs)) return false;
+  if (/[:=]/.test(lhs)) return false;
+  return true;
+}

package/src/checks/liquid-html-syntax-error/checks/InvalidOutputPush.spec.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck } from '../../../test';
+import { LiquidHTMLSyntaxError } from '../index';
+
+// Runtime-aligned via pos-cli sync against a live staging instance:
+//   {{ arr << "el" }}             → sync rejects (parse error in output position)
+//   {% echo arr << "el" %}        → same
+//   {% assign arr << "el" %}      → sync accepts (only valid position for `<<`)
+
+describe('detectInvalidOutputPush', () => {
+  describe('{{ }} output position', () => {
+    const invalidCases: Array<[string, string]> = [
+      ['string value', `{{ arr << "el" }}`],
+      ['single-quoted value', `{{ arr << 'el' }}`],
+      ['variable value', `{{ arr << other }}`],
+      ['with filter chain', `{{ arr << "el" | upcase }}`],
+      ['whitespace-trim delimiters', `{{- arr << "el" -}}`],
+    ];
+
+    for (const [label, sourceCode] of invalidCases) {
+      it(`should report: ${label} — ${sourceCode}`, async () => {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+        expect(pushOffenses).toHaveLength(1);
+      });
+    }
+
+    it('should not fire on plain output without `<<`', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ arr }}`);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not fire on output with filters', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ arr | upcase }}`);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not fire when `<<` is inside a quoted string', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ "a << b" }}`);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not fire when `<<` is inside a single-quoted string', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ 'a << b' }}`);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not fire when `<<` appears only inside a filter-argument string', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ a | append: " << " }}`);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should suppress the generic InvalidEchoValue duplicate', async () => {
+      // Without the dedicated check, InvalidEchoValue would also report "Syntax is not supported".
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{{ arr << "el" }}`);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toContain("'<<' (push) operator");
+    });
+  });
+
+  describe('{% echo %} tag', () => {
+    it('should report push in echo tag', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{% echo arr << "el" %}`);
+      const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+      expect(pushOffenses).toHaveLength(1);
+    });
+
+    it('should not fire on valid echo', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{% echo arr %}`);
+      expect(offenses).toHaveLength(0);
+    });
+  });
+
+  describe('assign tag — `<<` remains valid here', () => {
+    it('should NOT fire on bare push in assign', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{% assign arr << "el" %}`);
+      const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+      expect(pushOffenses).toHaveLength(0);
+    });
+
+    it('should NOT fire on bare push with variable', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{% assign arr << v %}`);
+      const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+      expect(pushOffenses).toHaveLength(0);
+    });
+
+    it('should NOT fire on bare push with filter', async () => {
+      const offenses = await runLiquidCheck(
+        LiquidHTMLSyntaxError,
+        `{% assign arr << "el" | upcase %}`,
+      );
+      const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+      expect(pushOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('other tags', () => {
+    it('should not fire for non-echo tags', async () => {
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, `{% render 'p' %}`);
+      const pushOffenses = offenses.filter((o) => o.message.includes("'<<' (push) operator"));
+      expect(pushOffenses).toHaveLength(0);
+    });
+  });
+});

package/src/checks/liquid-html-syntax-error/checks/InvalidOutputPush.ts

@@ -0,0 +1,39 @@
+import { LiquidTag, LiquidVariableOutput, NodeTypes } from '@platformos/liquid-html-parser';
+import { Problem, SourceCodeType } from '../../..';
+
+const PUSH_OPERATOR_MESSAGE =
+  "The '<<' (push) operator is only valid inside '{% assign target << value %}'. Remove it or move the expression into an assign tag.";
+
+/**
+ * Detects misuse of the `<<` (array push) operator inside output positions:
+ *
+ *   {{ arr << "el" }}             — invalid
+ *   {% echo arr << "el" %}        — invalid
+ *
+ * `<<` is only accepted as the top-level operator in an assign tag:
+ *
+ *   {% assign arr << "el" %}      — valid (pushes "el" onto arr)
+ *
+ * Runtime rejects output-position push with a hard syntax error; this check
+ * mirrors that with a clearer, actionable message than the generic
+ * `InvalidEchoValue` fallback ("Syntax is not supported").
+ */
+export function detectInvalidOutputPush(
+  node: LiquidTag | LiquidVariableOutput,
+): Problem<SourceCodeType.LiquidHtml> | undefined {
+  if (node.type === NodeTypes.LiquidTag && node.name !== 'echo') return;
+
+  const markup = node.markup;
+  if (typeof markup !== 'string' || !markup) return;
+
+  // Strip quoted strings so literal `<<` inside a string doesn't trigger the check
+  // (e.g. `{{ "a << b" }}` is a harmless string with no push operator).
+  const stripped = markup.replace(/'[^']*'|"[^"]*"/g, '');
+  if (!/<</.test(stripped)) return;
+
+  return {
+    message: PUSH_OPERATOR_MESSAGE,
+    startIndex: node.position.start,
+    endIndex: node.position.end,
+  };
+}

package/src/checks/liquid-html-syntax-error/checks/InvalidTagSyntax.spec.ts

@@ -57,6 +57,51 @@ describe('Module: InvalidTagSyntax', () => {
       const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
       expect(syntaxOffenses).toHaveLength(0);
     });
+
+    it('should not report valid function with JSON array argument', async () => {
+      const sourceCode = `{% function res = 'path/to/function', items: ["a", "b"] %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid function with JSON hash argument', async () => {
+      const sourceCode = `{% function res = 'path/to/function', config: { key: "val" } %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid multi-line function with JSON arguments inside liquid block', async () => {
+      const sourceCode = `{% liquid
+  function res = 'path/to/function',
+    array: [],
+    hash: {}
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should report function with missing partial after =', async () => {
+      const sourceCode = `{% function res = %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'function'");
+    });
+
+    it('should not report valid function with nested multi-line hash argument', async () => {
+      const sourceCode = `{% liquid
+  function res = 'path/to/function',
+    config: {
+      key: "val"
+    }
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
   });
 
   describe('graphql tag', () => {
@@ -166,6 +211,43 @@ describe('Module: InvalidTagSyntax', () => {
       const sourceCode = `{% liquid
   render 'partial'
   function res = 'path/to/function'
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid multi-line return with JSON hash in liquid block', async () => {
+      const sourceCode = `{% liquid
+  return {
+    "key": val
+  }
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid multi-line return with JSON array in liquid block', async () => {
+      const sourceCode = `{% liquid
+  return [
+    "a",
+    "b"
+  ]
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid multi-line assign with JSON array followed by render', async () => {
+      // assign is excluded from this check (has dedicated sub-checks), but parsing
+      // the multi-line liquid block must not corrupt subsequent tags
+      const sourceCode = `{% liquid
+  assign x = [
+    "a"
+  ]
+  render 'partial'
 %}`;
       const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
       const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
@@ -174,8 +256,10 @@ describe('Module: InvalidTagSyntax', () => {
   });
 
   describe('should NOT fire on tags with dedicated sub-checks', () => {
-    it('should not fire InvalidTagSyntax on assign (has MultipleAssignValues)', async () => {
-      const sourceCode = `{% assign x abc %}`;
+    it('should not fire InvalidTagSyntax on assign when MultipleAssignValues fires', async () => {
+      // MultipleAssignValues reports "Syntax is not supported"; InvalidTagSyntax is suppressed
+      // by the `problems.length === 0` guard in the parent pipeline.
+      const sourceCode = `{% assign foo = '123' 555 text %}`;
       const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
       const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
       expect(syntaxOffenses).toHaveLength(0);

package/src/checks/liquid-html-syntax-error/checks/InvalidTagSyntax.ts

@@ -12,7 +12,7 @@ const TAGS_WITH_NO_EXPECTED_MARKUP = new Set<string>(TAGS_WITHOUT_MARKUP);
  * more specific error messages and autofixes. This check should NOT fire on these
  * to avoid double-reporting or overriding their nuanced decisions.
  *
- * - assign → MultipleAssignValues, InvalidFilterName, InvalidPipeSyntax
+ * - assign → MultipleAssignValues, InvalidAssignSyntax, InvalidFilterName, InvalidPipeSyntax
  * - echo → InvalidEchoValue, InvalidFilterName, InvalidPipeSyntax
  * - if/elsif/unless → InvalidConditionalNode, InvalidConditionalNodeParenthesis
  * - for/tablerow → InvalidLoopRange, InvalidLoopArguments

package/src/checks/liquid-html-syntax-error/index.ts

@@ -1,6 +1,7 @@
 import { Severity, SourceCodeType, LiquidCheckDefinition, Problem } from '../../types';
 import { getOffset, isError } from '../../utils';
 import { detectMultipleAssignValues } from './checks/MultipleAssignValues';
+import { detectInvalidAssignSyntax } from './checks/InvalidAssignSyntax';
 import { detectInvalidBooleanExpressions } from './checks/InvalidBooleanExpressions';
 import { detectInvalidEchoValue } from './checks/InvalidEchoValue';
 import { detectInvalidConditionalNode } from './checks/InvalidConditionalNode';
@@ -11,6 +12,7 @@ import { detectInvalidFilterName } from './checks/InvalidFilterName';
 import { detectInvalidPipeSyntax } from './checks/InvalidPipeSyntax';
 import { detectUnknownTag } from './checks/UnknownTag';
 import { detectInvalidTagSyntax } from './checks/InvalidTagSyntax';
+import { detectInvalidOutputPush } from './checks/InvalidOutputPush';
 import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
 
 type LineColPosition = {
@@ -75,9 +77,18 @@ export const LiquidHTMLSyntaxError: LiquidCheckDefinition = {
             return;
           }
 
+          // Push-operator misuse in `{% echo … << … %}` — dedicated message.
+          // Short-circuit so InvalidEchoValue doesn't duplicate with a generic message.
+          const outputPushProblem = detectInvalidOutputPush(node);
+          if (outputPushProblem) {
+            context.report(outputPushProblem);
+            return;
+          }
+
           // Run specific sub-checks first — they provide better error messages and autofixes.
           const problems = [
             detectMultipleAssignValues(node),
+            detectInvalidAssignSyntax(node),
             detectInvalidEchoValue(node),
             detectInvalidLoopRange(node),
             detectInvalidLoopArguments(node, tags),
@@ -129,6 +140,14 @@ export const LiquidHTMLSyntaxError: LiquidCheckDefinition = {
         async LiquidVariableOutput(node, ancestors) {
           if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
 
+          // Push-operator misuse in `{{ … << … }}` — dedicated message.
+          // Short-circuit so InvalidEchoValue doesn't duplicate with a generic message.
+          const outputPushProblem = detectInvalidOutputPush(node);
+          if (outputPushProblem) {
+            context.report(outputPushProblem);
+            return;
+          }
+
           const filterProblems = await detectInvalidFilterName(node, (await filtersPromise) ?? []);
           if (filterProblems.length > 0) {
             filterProblems.forEach((problem) => context.report(problem));

package/src/checks/partial-call-arguments/extract-undefined-variables.spec.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from 'vitest';
+import { extractUndefinedVariables } from './extract-undefined-variables';
+
+describe('extractUndefinedVariables', () => {
+  it('should return variables used but not defined', () => {
+    const source = `{% liquid
+      assign b = a
+    %}
+    {{ b }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['a']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include assigned variables', () => {
+    const source = `{% assign x = 1 %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include captured variables', () => {
+    const source = `{% capture x %}hello{% endcapture %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include for loop variables', () => {
+    const source = `{% for item in items %}{{ item }}{% endfor %}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['items']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include forloop variable', () => {
+    const source = `{% for item in items %}{{ forloop.index }}{% endfor %}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['items']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle function result variables', () => {
+    const source = `{% function res = 'my_partial' %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle graphql result variables', () => {
+    const source = `{% graphql res = 'my_query' %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle inline graphql result variables', () => {
+    const source = `{% graphql res %}{ users { id } }{% endgraphql %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle parse_json result variables', () => {
+    const source = `{% parse_json data %}{"a":1}{% endparse_json %}{{ data }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include global objects', () => {
+    const source = `{{ context.session }}`;
+    const result = extractUndefinedVariables(source, [
+      'context',
+      'null',
+      'true',
+      'false',
+      'blank',
+      'empty',
+    ]);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should deduplicate results', () => {
+    const source = `{{ a }}{{ a }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['a']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should return empty arrays if source fails to parse', () => {
+    const source = `{% invalid unclosed`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle increment/decrement as definitions', () => {
+    const source = `{% increment counter %}{{ counter }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle background file-based result variables', () => {
+    const source = `{% background my_job = 'some_partial' %}{{ my_job }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle inline background tag without job_id', () => {
+    const source = `{% background source_name: 'my_task' %}echo "hello"{% endbackground %}{{ my_job }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['my_job']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not include doc param names', () => {
+    const source = `
+      {% doc %}
+        @param {String} name - a name
+      {% enddoc %}
+      {{ name }}
+    `;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['name']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  // | default filter detection
+
+  it('should treat assign x = x | default: val as optional', () => {
+    const source = `{% assign message = message | default: null %}{{ message }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal(['message']);
+  });
+
+  it('should treat inline output with | default as optional', () => {
+    const source = `{{ message | default: 'fallback' }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal(['message']);
+  });
+
+  it('should treat only the defaulted variable as optional, not others', () => {
+    const source = `
+      {% liquid
+        assign message = message | default: null
+        assign name = name
+      %}
+      {{ message }}{{ name }}
+    `;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['name']);
+    expect(result.optional).to.deep.equal(['message']);
+  });
+
+  it('should treat x as optional when assign y = x | default: val (different lhs/rhs)', () => {
+    // x is the optional input; y is the local alias defined by the assign
+    const source = `{% assign label = title | default: 'Untitled' %}{{ label }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal(['title']);
+  });
+
+  it('should treat variable as optional when default filter is not first in the chain', () => {
+    const source = `{% assign x = x | strip | default: '' %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal(['x']);
+  });
+
+  it('should not classify a variable as optional when default is applied to a literal, not the variable', () => {
+    // default is applied to the result of upcase, not directly to the VariableLookup
+    // The parent of `x` lookup here is LiquidVariable; default is still in filters — optional
+    // This is the same as any other filter chain: x | upcase | default: '' → x is optional
+    const source = `{% assign x = x | upcase | default: '' %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal(['x']);
+  });
+
+  it('should not treat a variable as optional when it has no default filter', () => {
+    const source = `{% assign x = x | upcase %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['x']);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should not classify a defined variable as optional even when | default is used later', () => {
+    // x is defined by the assign, so the later {{ x | default: '' }} does not make x an input
+    const source = `{% assign x = 'hello' %}{{ x | default: 'fallback' }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal([]);
+    expect(result.optional).to.deep.equal([]);
+  });
+
+  it('should handle multiple optional params from the real register_error pattern', () => {
+    const source = `
+      {% liquid
+        assign key = key | default: null
+        assign message = message | default: null
+        assign errors = contract.errors
+        assign field_errors = errors[field_name] | default: blank
+        assign field_errors << message
+        assign errors[field_name] = field_errors
+        assign contract.valid = false
+        return contract
+      %}
+    `;
+    const result = extractUndefinedVariables(source);
+    expect(result.required).to.deep.equal(['contract', 'field_name']);
+    expect(result.optional).to.deep.equal(['key', 'message']);
+  });
+});