@platformos/platformos-check-common 0.0.11 → 0.0.13

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

@@ -145,6 +145,116 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
+  it('should report an offense when function result variable is used before its definition', async () => {
+    const sourceCode = `
+      {{ a }}
+      {% function a = 'test' %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'a' used.");
+  });
+
+  it('should not report an offense for multiple function result variables', async () => {
+    const sourceCode = `
+      {% function result1 = 'partial_one' %}
+      {% function result2 = 'partial_two' %}
+      {{ result1 }}
+      {{ result2 }}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should not register a scope variable when function target is a hash/array access', async () => {
+    const sourceCode = `
+      {% parse_json my_hash %}{"key": "value"}{% endparse_json %}
+      {% function my_hash['result'] = 'test' %}
+      {{ my_hash }}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    // my_hash is defined via parse_json; function hash-access target does not shadow it
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense when a variable partial in include is undefined', async () => {
+    const sourceCode = `
+      {% include undefined_partial %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'undefined_partial' used.");
+  });
+
+  it('should not report an offense when a variable partial in include is defined', async () => {
+    const sourceCode = `
+      {% assign partial_name = 'some/partial' %}
+      {% include partial_name %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense when a variable partial in function is undefined', async () => {
+    const sourceCode = `
+      {% function result = undefined_partial %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'undefined_partial' used.");
+  });
+
+  it('should not report an offense for the result variable itself in function tag', async () => {
+    const sourceCode = `
+      {% function result = undefined_partial %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    // only 'undefined_partial' should be reported, not 'result'
+    expect(offenses.every((o) => o.message !== "Unknown object 'result' used.")).toBe(true);
+  });
+
+  it('should report offenses for lookup key variables in function result target and partial', async () => {
+    const sourceCode = `
+      {% parse_json my_hash %}{}{% endparse_json %}
+      {% function my_hash[lookup_key] = my_hash[path_var] %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    const messages = offenses.map((o) => o.message);
+    // lookup_key and path_var are undefined; my_hash is defined
+    expect(messages).toContain("Unknown object 'lookup_key' used.");
+    expect(messages).toContain("Unknown object 'path_var' used.");
+    expect(messages).not.toContain("Unknown object 'my_hash' used.");
+  });
+
+  it('should check the partial variable in function but not the hash-access result target base', async () => {
+    const sourceCode = `
+      {% parse_json my_hash %}{}{% endparse_json %}
+      {% function my_hash['key'] = undefined_partial %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    const messages = offenses.map((o) => o.message);
+    expect(messages).toContain("Unknown object 'undefined_partial' used.");
+    expect(messages).not.toContain("Unknown object 'my_hash' used.");
+  });
+
   it('should report an offense when object is defined in a for loop but used outside of the scope (in scenarios where the same variable has multiple scopes in the file)', async () => {
     const sourceCode = `
       {% for c in collections %}
@@ -359,10 +469,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses[0].message).toBe("Unknown object 'my_var' used.");
   });
 
-  it('should report an offense when job_id is used inside background block', async () => {
+  it('should report an offense when undefined variable is used inside background block', async () => {
     const sourceCode = `
-      {% background job_id %}
-        {{ job_id }}
+      {% background source_type: 'some form' %}
+        {{ undefined_var }}
       {% endbackground %}
     `;
 
@@ -371,12 +481,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(1);
   });
 
-  it('should not report an offense when job_id is used after background block', async () => {
+  it('should not report an offense when job_id is used after background file-based tag', async () => {
     const sourceCode = `
-      {% background job_id %}
-        {% assign a = 5 %}
-      {% endbackground %}
-      {{ job_id }}
+      {% background my_job = 'some_partial' %}
+      {{ my_job }}
     `;
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
@@ -384,12 +492,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should not report an offense when job_id is used after background block with args', async () => {
+  it('should not report an offense when job_id is used after background file-based tag with named args', async () => {
     const sourceCode = `
-      {% background job_id, priority: 'low' %}
-        {% assign a = 5 %}
-      {% endbackground %}
-      {{ job_id }}
+      {% background my_job = 'some_partial', source_type: 'some form' %}
+      {{ my_job }}
     `;
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
@@ -397,18 +503,16 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when job_id is used before background block', async () => {
+  it('should report an offense when job_id is used before background file-based tag', async () => {
     const sourceCode = `
-      {{ job_id }}
-      {% background job_id %}
-        {% assign a = 5 %}
-      {% endbackground %}
+      {{ my_job }}
+      {% background my_job = 'some_partial' %}
     `;
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
 
     expect(offenses).toHaveLength(1);
-    expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'job_id' used."]);
+    expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'my_job' used."]);
   });
 
   it('should not report an offense when object is defined with a parse_json tag', async () => {
@@ -437,4 +541,34 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(1);
     expect(offenses[0].message).toBe("Unknown object 'groups_data' used.");
   });
+
+  it('should not report an offense for catch variable inside catch block', async () => {
+    const sourceCode = `
+      {% try %}
+        {{ "something" }}
+      {% catch error %}
+        {{ error }}
+      {% endtry %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense for catch variable used outside catch block', async () => {
+    const sourceCode = `
+      {% try %}
+        {{ "something" }}
+      {% catch error %}
+        {{ error }}
+      {% endtry %}
+      {{ error }}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'error' used.");
+  });
 });

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

@@ -9,7 +9,6 @@ import {
   LiquidTagIncrement,
   LiquidTagTablerow,
   LiquidVariableLookup,
-  LiquidTagFunction,
   NamedTags,
   NodeTypes,
   Position,
@@ -18,11 +17,12 @@ import {
   LiquidTagGraphQL,
   LiquidTagParseJson,
   LiquidTagBackground,
-  BackgroundInlineMarkup,
+  BackgroundMarkup,
 } from '@platformos/liquid-html-parser';
 import { LiquidCheckDefinition, Severity, SourceCodeType, PlatformOSDocset } from '../../types';
 import { isError, last } from '../../utils';
 import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+import yaml from 'js-yaml';
 
 type Scope = { start?: number; end?: number };
 
@@ -108,9 +108,13 @@ export const UndefinedObject: LiquidCheckDefinition = {
         }
 
         if (node.name === 'function') {
-          indexVariableScope((node.markup as FunctionMarkup).name, {
-            start: node.position.end,
-          });
+          const fnName = (node.markup as FunctionMarkup).name;
+          // Only register simple variable names (not hash/array mutations like hash['key'])
+          if (fnName.lookups.length === 0 && fnName.name !== null) {
+            indexVariableScope(fnName.name, {
+              start: node.position.end,
+            });
+          }
         }
 
         if (node.name === 'layout') {
@@ -148,8 +152,26 @@ export const UndefinedObject: LiquidCheckDefinition = {
         }
 
         if (isLiquidTagBackground(node)) {
-          indexVariableScope(node.markup.jobId.name, {
-            start: node.blockEndPosition?.end,
+          indexVariableScope(node.markup.jobId, {
+            start: node.position.end,
+          });
+        }
+      },
+
+      async LiquidBranch(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+
+        // {% try %} ... {% catch error %} registers the error variable
+        if (
+          node.name === NamedTags.catch &&
+          node.markup &&
+          typeof node.markup !== 'string' &&
+          'name' in node.markup &&
+          node.markup.name
+        ) {
+          indexVariableScope(node.markup.name, {
+            start: node.blockStartPosition.end,
+            end: node.blockEndPosition?.start,
           });
         }
       },
@@ -160,9 +182,10 @@ export const UndefinedObject: LiquidCheckDefinition = {
         const parent = last(ancestors);
         if (isLiquidTag(parent) && isLiquidTagCapture(parent)) return;
         if (isLiquidTag(parent) && isLiquidTagParseJson(parent)) return;
-
-        // Skip the jobId variable in background tag markup - it's being defined, not used
-        if (isBackgroundInlineMarkup(parent) && parent.jobId === node) return;
+        // Skip the result variable of function tags (it's a definition, not a usage)
+        if (isFunctionMarkup(parent) && parent.name === node) return;
+        // Skip the error variable definition in catch branches
+        if (isLiquidBranchCatch(parent) && parent.markup === node) return;
 
         variables.push(node);
       },
@@ -299,19 +322,20 @@ function isLiquidTagDecrement(node: LiquidTag): node is LiquidTagDecrement {
 
 function isLiquidTagBackground(
   node: LiquidTag,
-): node is LiquidTagBackground & { markup: BackgroundInlineMarkup } {
+): node is LiquidTagBackground & { markup: BackgroundMarkup } {
   return (
     node.name === NamedTags.background &&
     typeof node.markup !== 'string' &&
-    node.markup.type === NodeTypes.BackgroundInlineMarkup
+    node.markup.type === NodeTypes.BackgroundMarkup
   );
 }
 
-function isBackgroundInlineMarkup(node: unknown): node is BackgroundInlineMarkup {
-  return (
-    typeof node === 'object' &&
-    node !== null &&
-    'type' in node &&
-    node.type === NodeTypes.BackgroundInlineMarkup
-  );
+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/unknown-property/index.spec.ts

@@ -212,6 +212,139 @@ query {
       // This is expected behavior without schema - we can't know users is an array
       expect(offenses).toHaveLength(1);
     });
+
+    it('should not report an offense for result.errors (GraphQL responses always have errors)', async () => {
+      const sourceCode = `{% graphql r %}
+query {
+  user {
+    id
+  }
+}
+{% endgraphql %}
+{% if r.errors %}
+  {{ r.errors }}
+{% endif %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report file-based graphql result.errors', async () => {
+      const sourceCode = `{% graphql r = 'my_query' %}
+{% if r.errors %}{{ r.errors }}{% endif %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+  });
+
+  describe('graphql errors field', () => {
+    it('should not report r.errors on graphql results (protocol-level field)', async () => {
+      const sourceCode = `{% graphql r %}
+query {
+  user {
+    id
+  }
+}
+{% endgraphql %}
+{% if r.errors %}error{% endif %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report errors on mutation results without errors in selection set', async () => {
+      const sourceCode = `{% graphql r %}
+mutation ($id: ID!) {
+  user: user_delete(id: $id) {
+    id
+    email
+  }
+}
+{% endgraphql %}
+{% unless r.errors %}ok{% endunless %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should still report genuinely unknown properties on graphql results', async () => {
+      const sourceCode = `{% graphql r %}
+query {
+  user {
+    id
+  }
+}
+{% endgraphql %}
+{{ r.user.bogus }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toContain("Unknown property 'bogus'");
+    });
+  });
+
+  describe('dig filter shape tracking', () => {
+    it('should infer shape after dig on a parse_json variable', async () => {
+      const sourceCode = `{% assign data = '{"user": {"name": "John", "age": 30}}' | parse_json %}
+{% assign user = data | dig: "user" %}
+{{ user.name }}
+{{ user.missing }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toContain("Unknown property 'missing'");
+    });
+
+    it('should infer array shape after dig and allow .size', async () => {
+      const sourceCode = `{% assign data = '{"results": [{"id": 1}, {"id": 2}]}' | parse_json %}
+{% assign items = data | dig: "results" %}
+{{ items.size }}
+{{ items.first.id }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should infer shape after multiple dig filters', async () => {
+      const sourceCode = `{% assign data = '{"a": {"b": {"c": 1}}}' | parse_json %}
+{% assign val = data | dig: "a" | dig: "b" %}
+{{ val.c }}
+{{ val.missing }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toContain("Unknown property 'missing'");
+    });
+
+    it('should not track dig when source has no known shape', async () => {
+      const sourceCode = `{% assign val = dynamic_var | dig: "key" %}
+{{ val.anything }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should infer shape after dig on inline graphql result', async () => {
+      const sourceCode = `{% graphql result | dig: 'user' %}
+query {
+  user {
+    id
+    email
+  }
+}
+{% endgraphql %}
+{{ result.id }}
+{{ result.email }}
+{{ result.missing }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toContain("Unknown property 'missing'");
+    });
+
+    it('should allow full shape when no dig filter on inline graphql', async () => {
+      const sourceCode = `{% graphql result %}
+query {
+  user {
+    id
+  }
+}
+{% endgraphql %}
+{{ result.user.id }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
   });
 
   describe('error message formatting', () => {

package/src/checks/unknown-property/index.ts

@@ -4,6 +4,7 @@ import {
   LiquidVariableLookup,
   LiquidVariable,
   LiquidExpression,
+  LiquidFilter,
   LiquidString,
   NodeTypes,
   NamedTags,
@@ -125,6 +126,50 @@ export const UnknownProperty: LiquidCheckDefinition = {
               }
             }
           }
+
+          // {% assign x = y | dig: "key1" | dig: "key2" %}
+          // Follow the dig path through the source variable's known shape.
+          const digFilters =
+            markup.value.filters?.filter((f: { name: string }) => f.name === 'dig') ?? [];
+          if (digFilters.length > 0 && markup.value.expression.type === NodeTypes.VariableLookup) {
+            const expr = markup.value.expression as LiquidVariableLookup;
+            if (expr.name) {
+              const digPath: string[] = [];
+              let validDigPath = true;
+              for (const digFilter of digFilters) {
+                const arg = digFilter.args?.[0];
+                if (arg?.type === NodeTypes.String) {
+                  digPath.push(arg.value);
+                } else {
+                  validDigPath = false;
+                  break;
+                }
+              }
+
+              if (validDigPath && digPath.length > 0) {
+                // Combine any lookups on the source expression (e.g. y.a | dig: "b")
+                // with the dig path to get the full navigation path.
+                const sourceLookupPath = buildLookupPath(expr.lookups);
+                const fullPath = sourceLookupPath ? [...sourceLookupPath, ...digPath] : digPath;
+
+                const sourceIdx = findLastApplicableShapeIndex(
+                  expr.name,
+                  node.position.start,
+                  variableShapes,
+                );
+                if (sourceIdx !== -1) {
+                  const result = lookupPropertyPath(variableShapes[sourceIdx].shape, fullPath);
+                  if (result.shape && !result.error) {
+                    variableShapes.push({
+                      name: markup.name,
+                      shape: result.shape,
+                      range: [node.position.end],
+                    });
+                  }
+                }
+              }
+            }
+          }
         }
 
         // {% parse_json x %}{"a": 5}{% endparse_json %}
@@ -162,11 +207,14 @@ export const UnknownProperty: LiquidCheckDefinition = {
                 const schema = await getGraphQLSchema();
                 const shape = inferShapeFromGraphQL(content, schema);
                 if (shape) {
-                  variableShapes.push({
-                    name: markup.name,
-                    shape,
-                    range: [node.position.end],
-                  });
+                  const resultShape = applyDigFilters(shape, markup.filters);
+                  if (resultShape) {
+                    variableShapes.push({
+                      name: markup.name,
+                      shape: resultShape,
+                      range: [node.position.end],
+                    });
+                  }
                 }
               } catch {
                 // File read error - skip
@@ -186,11 +234,14 @@ export const UnknownProperty: LiquidCheckDefinition = {
             const schema = await getGraphQLSchema();
             const shape = inferShapeFromGraphQL(textContent, schema);
             if (shape) {
-              variableShapes.push({
-                name: markup.name,
-                shape,
-                range: [node.blockEndPosition?.end ?? node.position.end],
-              });
+              const resultShape = applyDigFilters(shape, markup.filters);
+              if (resultShape) {
+                variableShapes.push({
+                  name: markup.name,
+                  shape: resultShape,
+                  range: [node.blockEndPosition?.end ?? node.position.end],
+                });
+              }
             }
           }
         }
@@ -361,6 +412,29 @@ function buildLookupPath(lookups: LiquidExpression[]): string[] | undefined {
   return path;
 }
 
+/**
+ * Navigate a shape using the `dig` filters from a tag's result filters.
+ * Returns the navigated shape, or the original shape if no dig filters are present.
+ * Returns null if the dig path is dynamic or navigates to an unknown property.
+ */
+function applyDigFilters(shape: PropertyShape, filters: LiquidFilter[]): PropertyShape | null {
+  const digFilters = filters.filter((f) => f.name === 'dig');
+  if (digFilters.length === 0) return shape;
+
+  const digPath: string[] = [];
+  for (const filter of digFilters) {
+    const arg = filter.args?.[0];
+    if (arg?.type === NodeTypes.String) {
+      digPath.push(arg.value);
+    } else {
+      return null;
+    }
+  }
+
+  const result = lookupPropertyPath(shape, digPath);
+  return result.error || !result.shape ? null : result.shape;
+}
+
 /**
  * Extract the lookup path from a hash_assign target.
  * For {% hash_assign a['key1']['key2'] = value %}, returns ['key1', 'key2']

package/src/checks/unknown-property/property-shape.ts

@@ -216,7 +216,21 @@ export function inferShapeFromGraphQL(
           }
         }
 
-        return selectionSetToShape(definition.selectionSet, rootType);
+        const shape = selectionSetToShape(definition.selectionSet, rootType);
+
+        // platformOS always exposes a top-level 'errors' array on graphql results
+        // (GraphQL protocol-level errors), regardless of what's in the selection set.
+        const properties = new Map(shape.properties);
+        if (!properties.has('errors')) {
+          properties.set('errors', {
+            kind: 'array',
+            itemShape: {
+              kind: 'object',
+              properties: new Map([['message', { kind: 'primitive', primitiveType: 'string' }]]),
+            },
+          });
+        }
+        return { kind: 'object', properties };
       }
     }
     return undefined;