@platformos/platformos-check-common 0.0.12 → 0.0.16

package/src/checks/metadata-params/extract-undefined-variables.spec.ts

@@ -0,0 +1,115 @@
+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).to.deep.equal(['a']);
+  });
+
+  it('should not include assigned variables', () => {
+    const source = `{% assign x = 1 %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal([]);
+  });
+
+  it('should not include captured variables', () => {
+    const source = `{% capture x %}hello{% endcapture %}{{ x }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal([]);
+  });
+
+  it('should not include for loop variables', () => {
+    const source = `{% for item in items %}{{ item }}{% endfor %}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal(['items']);
+  });
+
+  it('should not include forloop variable', () => {
+    const source = `{% for item in items %}{{ forloop.index }}{% endfor %}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal(['items']);
+  });
+
+  it('should handle function result variables', () => {
+    const source = `{% function res = 'my_partial' %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal([]);
+  });
+
+  it('should handle graphql result variables', () => {
+    const source = `{% graphql res = 'my_query' %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal([]);
+  });
+
+  it('should handle inline graphql result variables', () => {
+    const source = `{% graphql res %}{ users { id } }{% endgraphql %}{{ res }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).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).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).to.deep.equal([]);
+  });
+
+  it('should deduplicate results', () => {
+    const source = `{{ a }}{{ a }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal(['a']);
+  });
+
+  it('should return empty array if source fails to parse', () => {
+    const source = `{% invalid unclosed`;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal([]);
+  });
+
+  it('should handle increment/decrement as definitions', () => {
+    const source = `{% increment counter %}{{ counter }}`;
+    const result = extractUndefinedVariables(source);
+    expect(result).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).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).to.deep.equal(['my_job']);
+  });
+
+  it('should not include doc param names', () => {
+    const source = `
+      {% doc %}
+        @param {String} name - a name
+      {% enddoc %}
+      {{ name }}
+    `;
+    const result = extractUndefinedVariables(source);
+    expect(result).to.deep.equal(['name']);
+  });
+});

package/src/checks/metadata-params/extract-undefined-variables.ts

@@ -0,0 +1,286 @@
+import {
+  LiquidHtmlNode,
+  LiquidTag,
+  LiquidTagAssign,
+  LiquidTagCapture,
+  LiquidTagDecrement,
+  LiquidTagFor,
+  LiquidTagIncrement,
+  LiquidTagTablerow,
+  LiquidVariableLookup,
+  NamedTags,
+  NodeTypes,
+  Position,
+  FunctionMarkup,
+  LiquidTagHashAssign,
+  HashAssignMarkup,
+  LiquidTagGraphQL,
+  LiquidTagParseJson,
+  LiquidTagBackground,
+  BackgroundMarkup,
+  toLiquidHtmlAST,
+} from '@platformos/liquid-html-parser';
+
+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.
+ *
+ * This mirrors the variable tracking logic from the UndefinedObject check but
+ * packaged as a standalone synchronous function.
+ */
+export function extractUndefinedVariables(
+  source: string,
+  globalObjectNames: string[] = [],
+): string[] {
+  let ast;
+  try {
+    ast = toLiquidHtmlAST(source);
+  } catch {
+    return [];
+  }
+
+  const scopedVariables: Map<string, Scope[]> = new Map();
+  const fileScopedVariables: Set<string> = new Set(globalObjectNames);
+  const variables: LiquidVariableLookup[] = [];
+
+  function indexVariableScope(variableName: string | null, scope: Scope) {
+    if (!variableName) return;
+    const indexedScope = scopedVariables.get(variableName) ?? [];
+    scopedVariables.set(variableName, indexedScope.concat(scope));
+  }
+
+  function walk(node: LiquidHtmlNode, ancestors: LiquidHtmlNode[]) {
+    // Process definitions from LiquidTag nodes
+    if (node.type === NodeTypes.LiquidTag) {
+      handleLiquidTag(node, ancestors);
+    }
+
+    // Process definitions from LiquidBranch nodes (catch)
+    if (node.type === NodeTypes.LiquidBranch) {
+      handleLiquidBranch(node);
+    }
+
+    // Process variable usages
+    if (node.type === NodeTypes.VariableLookup) {
+      handleVariableLookup(node, ancestors);
+    }
+
+    // Recurse into children
+    const newAncestors = ancestors.concat(node);
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (isNode(item)) {
+            walk(item, newAncestors);
+          }
+        }
+      } else if (isNode(value)) {
+        walk(value, newAncestors);
+      }
+    }
+  }
+
+  function handleLiquidTag(node: LiquidTag, _ancestors: LiquidHtmlNode[]) {
+    if (isLiquidTagAssign(node) || isLiquidTagGraphQL(node) || isLiquidTagParseJson(node)) {
+      indexVariableScope(node.markup.name, {
+        start: node.blockStartPosition.end,
+      });
+    }
+
+    if (isLiquidTagHashAssign(node) && node.markup.target.name) {
+      indexVariableScope(node.markup.target.name, {
+        start: node.blockStartPosition.end,
+      });
+    }
+
+    if (isLiquidTagCapture(node)) {
+      indexVariableScope(node.markup.name, {
+        start: node.blockEndPosition?.end,
+      });
+    }
+
+    if (node.name === 'form') {
+      indexVariableScope(node.name, {
+        start: node.blockStartPosition.end,
+        end: node.blockEndPosition?.start,
+      });
+    }
+
+    if (node.name === 'function') {
+      const fnName = (node.markup as FunctionMarkup).name;
+      if (fnName.lookups.length === 0 && fnName.name !== null) {
+        indexVariableScope(fnName.name, {
+          start: node.position.end,
+        });
+      }
+    }
+
+    if ((isLiquidTagIncrement(node) || isLiquidTagDecrement(node)) && node.markup.name !== null) {
+      indexVariableScope(node.markup.name, {
+        start: node.position.start,
+      });
+    }
+
+    if (isLiquidForTag(node) || isLiquidTableRowTag(node)) {
+      indexVariableScope(node.markup.variableName, {
+        start: node.blockStartPosition.end,
+        end: node.blockEndPosition?.start,
+      });
+      indexVariableScope(node.name === 'for' ? 'forloop' : 'tablerowloop', {
+        start: node.blockStartPosition.end,
+        end: node.blockEndPosition?.start,
+      });
+    }
+
+    if (isLiquidTagBackground(node)) {
+      indexVariableScope(node.markup.jobId, {
+        start: node.position.end,
+      });
+    }
+  }
+
+  function handleLiquidBranch(node: LiquidHtmlNode & { type: typeof NodeTypes.LiquidBranch }) {
+    if (
+      node.name === NamedTags.catch &&
+      node.markup &&
+      typeof node.markup !== 'string' &&
+      'name' in node.markup &&
+      (node.markup as any).name
+    ) {
+      indexVariableScope((node.markup as any).name, {
+        start: (node as any).blockStartPosition.end,
+        end: (node as any).blockEndPosition?.start,
+      });
+    }
+  }
+
+  function handleVariableLookup(node: LiquidVariableLookup, ancestors: LiquidHtmlNode[]) {
+    const parent = ancestors[ancestors.length - 1];
+
+    if (isLiquidTag(parent) && isLiquidTagCapture(parent)) return;
+    if (isLiquidTag(parent) && isLiquidTagParseJson(parent)) return;
+    if (isFunctionMarkup(parent) && parent.name === node) return;
+    if (isLiquidBranchCatch(parent) && parent.markup === node) return;
+    if (isHashAssignMarkup(parent) && parent.target === node) return;
+
+    variables.push(node);
+  }
+
+  walk(ast, []);
+
+  // Determine undefined variables
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const variable of variables) {
+    if (!variable.name) continue;
+    if (seen.has(variable.name)) continue;
+
+    const isVariableDefined = isDefined(
+      variable.name,
+      variable.position,
+      fileScopedVariables,
+      scopedVariables,
+    );
+
+    if (!isVariableDefined) {
+      seen.add(variable.name);
+      result.push(variable.name);
+    }
+  }
+
+  return result;
+}
+
+function isNode(x: any): x is LiquidHtmlNode {
+  return x !== null && typeof x === 'object' && typeof x.type === 'string';
+}
+
+function isDefined(
+  variableName: string,
+  variablePosition: Position,
+  fileScopedVariables: Set<string>,
+  scopedVariables: Map<string, Scope[]>,
+): boolean {
+  if (fileScopedVariables.has(variableName)) {
+    return true;
+  }
+
+  const scopes = scopedVariables.get(variableName);
+  if (!scopes) {
+    return false;
+  }
+
+  return scopes.some((scope) => {
+    const start = variablePosition.start;
+    const isVariableAfterScopeStart = !scope.start || start > scope.start;
+    const isVariableBeforeScopeEnd = !scope.end || start < scope.end;
+    return isVariableAfterScopeStart && isVariableBeforeScopeEnd;
+  });
+}
+
+function isLiquidTag(node?: LiquidHtmlNode): node is LiquidTag {
+  return node?.type === NodeTypes.LiquidTag;
+}
+
+function isLiquidTagCapture(node: LiquidTag): node is LiquidTagCapture {
+  return node.name === NamedTags.capture;
+}
+
+function isLiquidTagAssign(node: LiquidTag): node is LiquidTagAssign {
+  return node.name === NamedTags.assign && typeof node.markup !== 'string';
+}
+
+function isLiquidTagHashAssign(node: LiquidTag): node is LiquidTagHashAssign {
+  return node.name === NamedTags.hash_assign && typeof node.markup !== 'string';
+}
+
+function isLiquidTagGraphQL(node: LiquidTag): node is LiquidTagGraphQL {
+  return node.name === NamedTags.graphql && typeof node.markup !== 'string';
+}
+
+function isLiquidTagParseJson(node: LiquidTag): node is LiquidTagParseJson {
+  return node.name === NamedTags.parse_json && typeof node.markup !== 'string';
+}
+
+function isLiquidForTag(node: LiquidTag): node is LiquidTagFor {
+  return node.name === NamedTags.for && typeof node.markup !== 'string';
+}
+
+function isLiquidTableRowTag(node: LiquidTag): node is LiquidTagTablerow {
+  return node.name === NamedTags.tablerow && typeof node.markup !== 'string';
+}
+
+function isLiquidTagIncrement(node: LiquidTag): node is LiquidTagIncrement {
+  return node.name === NamedTags.increment && typeof node.markup !== 'string';
+}
+
+function isLiquidTagDecrement(node: LiquidTag): node is LiquidTagDecrement {
+  return node.name === NamedTags.decrement && typeof node.markup !== 'string';
+}
+
+function isLiquidTagBackground(
+  node: LiquidTag,
+): node is LiquidTagBackground & { markup: BackgroundMarkup } {
+  return (
+    node.name === NamedTags.background &&
+    typeof node.markup !== 'string' &&
+    node.markup.type === NodeTypes.BackgroundMarkup
+  );
+}
+
+function isHashAssignMarkup(node?: LiquidHtmlNode): node is HashAssignMarkup {
+  return node?.type === NodeTypes.HashAssignMarkup;
+}
+
+function isFunctionMarkup(node?: LiquidHtmlNode): node is FunctionMarkup {
+  return node?.type === NodeTypes.FunctionMarkup;
+}
+
+function isLiquidBranchCatch(
+  node?: LiquidHtmlNode,
+): node is LiquidHtmlNode & { type: typeof NodeTypes.LiquidBranch; name: 'catch'; markup: any } {
+  return node?.type === NodeTypes.LiquidBranch && (node as any).name === NamedTags.catch;
+}

package/src/checks/metadata-params/index.spec.ts

@@ -3,14 +3,13 @@ import { MetadataParamsCheck } from '.';
 import { check } from '../../test';
 
 describe('Module: MetadataParamsCheck', () => {
-  it('should report the missing variable when not defined but passed', async () => {
+  it('should use doc tag as complete param list when present', async () => {
     const file = `
-      ---
-      metadata:
-        params:
-          variable: {}
-          variable3: {}
-      ---
+      {% doc %}
+        @param {Number} variable - param with description
+        @param {Number} variable2 - param with description
+      {% enddoc %}
+
       {% assign a = 5 | plus: variable | plus: variable2 %}
       {{ a }}
     `;
@@ -25,23 +24,21 @@ describe('Module: MetadataParamsCheck', () => {
 
     const offenses = await check(files, [MetadataParamsCheck]);
 
-    expect(offenses).to.have.length(2);
-    expect(offenses).to.containOffense('Unknown parameter variable2 passed to function call');
-    expect(offenses).to.containOffense(
-      'Required parameter variable3 must be passed to function call',
-    );
+    expect(offenses).to.have.length(0);
   });
 
-  it('should ignore if metadata not defined', async () => {
+  it('should report missing required doc params', async () => {
     const file = `
-      ---
-      metadata:
-      ---
+      {% 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 %}
+      {% function a = 'commands/call/fileToCall', variable: 2 %}
       {{ a }}
     `;
     const files = {
@@ -51,21 +48,23 @@ describe('Module: MetadataParamsCheck', () => {
 
     const offenses = await check(files, [MetadataParamsCheck]);
 
-    expect(offenses).to.have.length(0);
+    expect(offenses).to.have.length(1);
+    expect(offenses).to.containOffense(
+      'Required parameter variable2 must be passed to function call',
+    );
   });
 
-  it('should accept doc tag if metadata not defined', async () => {
+  it('should report unknown params not in doc', async () => {
     const file = `
       {% doc %}
         @param {Number} variable - param with description
-        @param {Number} variable2 - param with description
       {% enddoc %}
 
-      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {% assign a = 5 | plus: variable %}
       {{ a }}
     `;
     const file2 = `
-      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {% function a = 'commands/call/fileToCall', variable: 2, extra: 12 %}
       {{ a }}
     `;
     const files = {
@@ -75,22 +74,144 @@ describe('Module: MetadataParamsCheck', () => {
 
     const offenses = await check(files, [MetadataParamsCheck]);
 
+    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, [MetadataParamsCheck]);
+
     expect(offenses).to.have.length(0);
   });
 
-  it('should reject if doc tag is missing params', async () => {
+  it('should allow passing doc-optional params without reporting unknown', async () => {
     const file = `
       {% doc %}
-        @param {Number} variable - param with description
+        @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,
+    };
 
-      {% assign a = 5 | plus: variable | plus: variable2 %}
+    const offenses = await check(files, [MetadataParamsCheck]);
+
+    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 a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {% 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, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  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, [MetadataParamsCheck]);
+
+    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, [MetadataParamsCheck]);
+
+    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, [MetadataParamsCheck]);
+
+    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,
@@ -98,6 +219,39 @@ describe('Module: MetadataParamsCheck', () => {
 
     const offenses = await check(files, [MetadataParamsCheck]);
 
+    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, [MetadataParamsCheck]);
+
     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, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(0);
   });
 });