@platformos/platformos-check-common 0.0.17 → 0.0.19

package/src/checks/partial-call-arguments/index.spec.ts

@@ -0,0 +1,436 @@
+import { expect, describe, it } from 'vitest';
+import { PartialCallArguments } from '.';
+import { check } from '../../test';
+
+describe('Module: PartialCallArguments', () => {
+  // ─── @doc-based validation ───────────────────────────────────────────────
+
+  it('should use doc tag as complete param list when present', async () => {
+    const file = `
+      {% doc %}
+        @param {Number} variable - param with description
+        @param {Number} variable2 - param with description
+      {% enddoc %}
+
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should report missing required doc params', async () => {
+    const file = `
+      {% doc %}
+        @param {Number} variable - param with description
+        @param {Number} variable2 - param with description
+      {% enddoc %}
+
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense(
+      'Required parameter variable2 must be passed to function call',
+    );
+  });
+
+  it('should report unknown params not in doc', async () => {
+    const file = `
+      {% doc %}
+        @param {Number} variable - param with description
+      {% enddoc %}
+
+      {% assign a = 5 | plus: variable %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, extra: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense('Unknown parameter extra passed to function call');
+  });
+
+  it('should allow doc-optional params without requiring them', async () => {
+    const file = `
+      {% doc %}
+        @param {String} a - required
+        @param {String} [b] - optional
+      {% enddoc %}
+      {{ a }}{{ b }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should allow passing doc-optional params without reporting unknown', async () => {
+    const file = `
+      {% doc %}
+        @param {String} a - required
+        @param {String} [b] - optional
+      {% enddoc %}
+      {{ a }}{{ b }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello', b: 'world' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should not require doc params that are not used in source', async () => {
+    const file = `
+      {% doc %}
+        @param {String} a - required param
+        @param {String} unused - required but not used in source
+      {% enddoc %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should still require a doc-required param even when implementation uses | default', async () => {
+    // The @doc annotation is the public API contract; internal fallbacks do not change it.
+    const file = `
+      {% doc %}
+        @param {String} message - required by contract
+      {% enddoc %}
+      {% assign message = message | default: 'fallback' %}
+      {{ message }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense(
+      'Required parameter message must be passed to function call',
+    );
+  });
+
+  // ─── Inferred validation (no @doc) ───────────────────────────────────────
+
+  it('should infer required params from undefined variables when no doc', async () => {
+    const file = `
+      {% assign b = a %}
+      {{ b }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should report missing inferred params when no doc', async () => {
+    const file = `
+      {% assign b = a %}
+      {{ b }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense('Required parameter a must be passed to function call');
+  });
+
+  it('should report unknown params when passing args not in inferred set', async () => {
+    const file = `
+      {% assign b = a %}
+      {{ b }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello', extra: 'world' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense('Unknown parameter extra passed to function call');
+  });
+
+  it('should not include global objects like context in inferred params', async () => {
+    const file = `
+      {{ context.session }}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', a: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should work with render tags too', async () => {
+    const file = `{{ a }}`;
+    const file2 = `{% render 'fileToRender' %}`;
+    const files = {
+      'app/views/partials/fileToRender.liquid': file,
+      'app/views/pages/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense('Required parameter a must be passed to render call');
+  });
+
+  it('should skip validation when no doc and no undefined vars', async () => {
+    const file = `
+      {% assign a = 5 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', extra: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  // ─── | default — inferred optional params ────────────────────────────────
+
+  it('should treat assign x = x | default: val as optional (no error when omitted)', async () => {
+    const file = `
+      {% assign message = message | default: null %}
+      {% assign required_param = required_param %}
+      {{ message }}{{ required_param }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', required_param: 'hello' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should allow passing inferred optional params without reporting unknown', async () => {
+    const file = `
+      {% assign message = message | default: null %}
+      {% assign required_param = required_param %}
+      {{ message }}{{ required_param }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', required_param: 'hello', message: 'hi' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should treat inline output {{ x | default: val }} as optional', async () => {
+    const file = `{{ message | default: 'fallback' }}`;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should treat assign y = x | default: val as x optional (different lhs/rhs)', async () => {
+    const file = `{% assign label = title | default: 'Untitled' %}{{ label }}`;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should still report unknown when caller passes arg not in optional or required set', async () => {
+    const file = `
+      {% assign message = message | default: null %}
+      {{ message }}
+    `;
+    const file2 = `
+      {% function res = 'commands/call/fileToCall', unknown_param: 'oops' %}
+      {{ res }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense('Unknown parameter unknown_param passed to function call');
+  });
+
+  it('should handle the real register_error pattern: required + optional params', async () => {
+    const file = `
+      {% 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 file2 = `
+      {% function c = 'helpers/register_error', contract: c, field_name: field_name, key: key %}
+    `;
+    const files = {
+      'app/lib/helpers/register_error.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should still require required params even when optional ones are present', async () => {
+    const file = `
+      {% liquid
+        assign key = key | default: null
+        assign errors = contract.errors
+        assign field_errors = errors[field_name] | default: blank
+        return contract
+      %}
+    `;
+    // omits both required: contract and field_name
+    const file2 = `
+      {% function c = 'helpers/register_error', key: 'some_key' %}
+    `;
+    const files = {
+      'app/lib/helpers/register_error.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [PartialCallArguments]);
+
+    expect(offenses).to.have.length(2);
+    expect(offenses).to.containOffense(
+      'Required parameter contract must be passed to function call',
+    );
+    expect(offenses).to.containOffense(
+      'Required parameter field_name must be passed to function call',
+    );
+  });
+});

package/src/checks/{metadata-params → partial-call-arguments}/index.ts

@@ -5,15 +5,16 @@ import { LiquidNamedArgument, Position } from '@platformos/liquid-html-parser';
 import { relative } from '../../path';
 import { extractUndefinedVariables } from './extract-undefined-variables';
 
-export const MetadataParamsCheck: LiquidCheckDefinition = {
+export const PartialCallArguments: LiquidCheckDefinition = {
   meta: {
-    code: 'MetadataParamsCheck',
-    name: 'Metadata Params Check',
+    code: 'PartialCallArguments',
+    aliases: ['MetadataParamsCheck'],
+    name: 'Partial Call Arguments',
     docs: {
       description:
-        'Ensures that parameters referenced in the document exist in the doc tag or are inferred from undefined variables.',
+        'Ensures that all required arguments are passed at render/function call sites, and that no unknown arguments are passed. Required vs optional is determined from the {% doc %} block when present, or inferred from undefined variables in the partial source otherwise. Variables used with | default are treated as optional.',
       recommended: true,
-      url: undefined,
+      url: 'https://documentation.platformos.com/developer-guide/platformos-check/checks/partial-call-arguments',
     },
     type: SourceCodeType.LiquidHtml,
     severity: Severity.ERROR,
@@ -61,14 +62,17 @@ export const MetadataParamsCheck: LiquidCheckDefinition = {
             }
           }
         }
-        const undefinedVars = extractUndefinedVariables(source, globalObjectNames);
+        const { required: undefinedRequiredVars, optional: undefinedOptionalVars } =
+          extractUndefinedVariables(source, globalObjectNames);
+        const undefinedVars = [...undefinedRequiredVars, ...undefinedOptionalVars];
         const docRequiredNames = docDef.liquidDoc.parameters
           .filter((p) => p.required)
           .map((p) => p.name);
         requiredParams = docRequiredNames.filter((name) => undefinedVars.includes(name));
         allowedParams = docDef.liquidDoc.parameters.map((p) => p.name);
       } else {
-        // No @doc — scan for undefined variables, treat all as required
+        // No @doc — infer required vs optional from undefined variables in the source.
+        // Variables used with `| default` are treated as optional.
         const globalObjectNames: string[] = [];
         if (context.platformosDocset) {
           const objects = await context.platformosDocset.objects();
@@ -84,11 +88,14 @@ export const MetadataParamsCheck: LiquidCheckDefinition = {
           }
         }
 
-        const undefinedVars = extractUndefinedVariables(source, globalObjectNames);
-        if (undefinedVars.length === 0) return;
+        const { required: requiredVars, optional: optionalVars } = extractUndefinedVariables(
+          source,
+          globalObjectNames,
+        );
+        if (requiredVars.length === 0 && optionalVars.length === 0) return;
 
-        requiredParams = undefinedVars;
-        allowedParams = undefinedVars;
+        requiredParams = requiredVars;
+        allowedParams = [...requiredVars, ...optionalVars];
       }
 
       args

package/src/checks/undefined-object/index.spec.ts

@@ -700,4 +700,105 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(1);
     expect(offenses[0].message).toBe("Unknown object 'error' used.");
   });
+
+  describe('JSON literals in assign tag', () => {
+    it('should report undefined bare key AND bare value in a hash literal', async () => {
+      // bare keys and bare values are both VariableLookups in platformOS semantics —
+      // they are evaluated at runtime, so both are subject to undefined-object checks
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign hash = { bare_key: bare_val } %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses.map((o) => o.message).sort()).toEqual([
+        "Unknown object 'bare_key' used.",
+        "Unknown object 'bare_val' used.",
+      ]);
+    });
+
+    it('should NOT report string keys in a hash literal (they are literals, not variables)', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign hash = { "key": "val" } %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should report undefined bare value under a string key', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign hash = { "key": undefined_var } %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe("Unknown object 'undefined_var' used.");
+    });
+
+    it('should report undefined elements in an array literal', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign arr = [a, undefined_var] %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses.map((o) => o.message).sort()).toEqual([
+        "Unknown object 'a' used.",
+        "Unknown object 'undefined_var' used.",
+      ]);
+    });
+
+    it('should NOT report string elements in an array literal', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign arr = ["a", "b", "c"] %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should NOT report bare keys/values when they refer to defined variables', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign bare_key = "k" %}
+        {% assign bare_val = "v" %}
+        {% assign hash = { bare_key: bare_val } %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should report undefined bare keys/values in nested hash literals', async () => {
+      const sourceCode = `
+        {% doc %}
+        {% enddoc %}
+        {% assign hash = { outer: { inner: value } } %}
+      `;
+
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+      expect(offenses.map((o) => o.message).sort()).toEqual([
+        "Unknown object 'inner' used.",
+        "Unknown object 'outer' used.",
+        "Unknown object 'value' used.",
+      ]);
+    });
+  });
 });

package/src/checks/unused-assign/index.spec.ts

@@ -201,4 +201,52 @@ describe('Module: UnusedAssign', () => {
     expect(offenses).to.have.lengthOf(1);
     expect(offenses[0].message).to.equal("The variable 'arr' is assigned but not used");
   });
+
+  it('should not report variables used inside a filter array-literal argument', async () => {
+    const sourceCode = `
+      {% assign k = "key" %}
+      {% assign v = "value" %}
+      {% assign name = arr | default: [ "hi", k, v] %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report variables used inside a filter hash-literal argument', async () => {
+    const sourceCode = `
+      {% assign k = 1 %}
+      {% assign name = arr | default: { a: k } %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report variables used inside a named-argument value', async () => {
+    const sourceCode = `
+      {% assign k = 0 %}
+      {% assign name = arr | slice: start: k %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report variables referenced in a string-markup fallback assign (parse failure)', async () => {
+    // The stray `}` before `%}` causes the tolerant parser to fall back to
+    // string markup. The AST contains no VariableLookup nodes for k/v, so
+    // without a textual fallback scan the check would wrongly flag them.
+    const sourceCode = `
+      {% assign k = "key" %}
+      {% assign v = "value" %}
+      {% assign name = arr | default: [ "hi", k, v] } %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
 });

package/src/checks/unused-assign/index.ts

@@ -31,6 +31,12 @@ export const UnusedAssign: LiquidCheckDefinition = {
     // effects on the original, so they count as "using" the variable.
     const referenceAssignedVariables: Set<string> = new Set();
     const usedVariables: Set<string> = new Set();
+    // Concatenated markup of LiquidTags whose parsing fell back to a raw string
+    // (e.g. a typo like `{% assign name = x | default: [...] } %}`). The AST has
+    // no VariableLookup nodes to traverse inside them, so onCodePathEnd scans
+    // this text for assigned-variable names — avoids compounding the user's
+    // syntax error with false "unused" warnings.
+    let fallbackText = '';
 
     function checkVariableUsage(node: any) {
       if (node.type === NodeTypes.VariableLookup) {
@@ -66,6 +72,8 @@ export const UnusedAssign: LiquidCheckDefinition = {
           }
         } else if (isLiquidTagCapture(node) && node.markup.name) {
           assignedVariables.set(node.markup.name, node);
+        } else if (typeof node.markup === 'string' && node.markup) {
+          fallbackText += '\n' + node.markup;
         }
       },
 
@@ -79,6 +87,13 @@ export const UnusedAssign: LiquidCheckDefinition = {
       },
 
       async onCodePathEnd() {
+        if (fallbackText) {
+          for (const name of assignedVariables.keys()) {
+            if (usedVariables.has(name)) continue;
+            if (new RegExp(`\\b${name}\\b`).test(fallbackText)) usedVariables.add(name);
+          }
+        }
+
         for (const [variable, node] of assignedVariables.entries()) {
           if (!usedVariables.has(variable) && !variable.startsWith('_')) {
             context.report({