@platformos/platformos-check-common 0.0.16 → 0.0.18

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;
+}

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.",
+      ]);
+    });
+  });
 });