@platformos/platformos-check-common 0.0.17 → 0.0.19

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,10 @@
 import { Severity, SourceCodeType, LiquidCheckDefinition, Problem } from '../../types';
 import { getOffset, isError } from '../../utils';
 import { detectMultipleAssignValues } from './checks/MultipleAssignValues';
+import {
+  detectInvalidAssignSyntax,
+  detectInvalidAssignFallback,
+} from './checks/InvalidAssignSyntax';
 import { detectInvalidBooleanExpressions } from './checks/InvalidBooleanExpressions';
 import { detectInvalidEchoValue } from './checks/InvalidEchoValue';
 import { detectInvalidConditionalNode } from './checks/InvalidConditionalNode';
@@ -11,6 +15,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 +80,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),
@@ -112,6 +126,14 @@ export const LiquidHTMLSyntaxError: LiquidCheckDefinition = {
           if (pipeProblems.length > 0) {
             pipeProblems.forEach((pipeProblem) => context.report(pipeProblem));
           }
+
+          // Last-chance check for assign tags whose tolerant parse fell back to
+          // string markup (e.g. stray `}` before `%}`). Gated on "nothing else
+          // reported on this tag" to avoid double-flagging.
+          if (problems.length + filterProblems.length + pipeProblems.length === 0) {
+            const fallback = detectInvalidAssignFallback(node);
+            if (fallback) context.report(fallback);
+          }
         },
 
         async LiquidBranch(node, ancestors) {
@@ -129,6 +151,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']);
+  });
+});

package/src/checks/{metadata-params → partial-call-arguments}/extract-undefined-variables.ts

@@ -8,6 +8,7 @@ import {
   LiquidTagIncrement,
   LiquidTagTablerow,
   LiquidVariableLookup,
+  LiquidVariable,
   NamedTags,
   NodeTypes,
   Position,
@@ -25,7 +26,10 @@ type Scope = { start?: number; end?: number };
 
 /**
  * Parses a Liquid source string and returns a deduplicated list of variable names
- * that are used but never defined. Returns [] on parse errors.
+ * that are used but never defined. Returns `{ required: [], optional: [] }` on parse errors.
+ *
+ * Variables used exclusively with `| default` filter (e.g. `assign x = x | default: val`)
+ * are returned in `optional` — the partial handles the missing-argument case itself.
  *
  * This mirrors the variable tracking logic from the UndefinedObject check but
  * packaged as a standalone synchronous function.
@@ -33,17 +37,18 @@ type Scope = { start?: number; end?: number };
 export function extractUndefinedVariables(
   source: string,
   globalObjectNames: string[] = [],
-): string[] {
+): { required: string[]; optional: string[] } {
   let ast;
   try {
     ast = toLiquidHtmlAST(source);
   } catch {
-    return [];
+    return { required: [], optional: [] };
   }
 
   const scopedVariables: Map<string, Scope[]> = new Map();
   const fileScopedVariables: Set<string> = new Set(globalObjectNames);
   const variables: LiquidVariableLookup[] = [];
+  const variablesWithDefault: Set<string> = new Set();
 
   function indexVariableScope(variableName: string | null, scope: Scope) {
     if (!variableName) return;
@@ -166,13 +171,25 @@ export function extractUndefinedVariables(
     if (isHashAssignMarkup(parent) && parent.target === node) return;
 
     variables.push(node);
+
+    // Detect `x | default: ...` — the variable is the expression of a LiquidVariable
+    // that has a `default` filter, meaning the partial handles the missing case itself.
+    if (
+      node.name &&
+      isLiquidVariable(parent) &&
+      parent.expression === node &&
+      parent.filters.some((f) => f.name === 'default')
+    ) {
+      variablesWithDefault.add(node.name);
+    }
   }
 
   walk(ast, []);
 
   // Determine undefined variables
   const seen = new Set<string>();
-  const result: string[] = [];
+  const required: string[] = [];
+  const optional: string[] = [];
 
   for (const variable of variables) {
     if (!variable.name) continue;
@@ -187,11 +204,15 @@ export function extractUndefinedVariables(
 
     if (!isVariableDefined) {
       seen.add(variable.name);
-      result.push(variable.name);
+      if (variablesWithDefault.has(variable.name)) {
+        optional.push(variable.name);
+      } else {
+        required.push(variable.name);
+      }
     }
   }
 
-  return result;
+  return { required, optional };
 }
 
 function isNode(x: any): x is LiquidHtmlNode {
@@ -284,3 +305,7 @@ function isLiquidBranchCatch(
 ): node is LiquidHtmlNode & { type: typeof NodeTypes.LiquidBranch; name: 'catch'; markup: any } {
   return node?.type === NodeTypes.LiquidBranch && (node as any).name === NamedTags.catch;
 }
+
+function isLiquidVariable(node?: LiquidHtmlNode): node is LiquidVariable {
+  return node?.type === NodeTypes.LiquidVariable;
+}