@platformos/platformos-check-common 0.0.11 → 0.0.12

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

@@ -18,7 +18,7 @@ import {
   LiquidTagGraphQL,
   LiquidTagParseJson,
   LiquidTagBackground,
-  BackgroundInlineMarkup,
+  BackgroundMarkup,
 } from '@platformos/liquid-html-parser';
 import { LiquidCheckDefinition, Severity, SourceCodeType, PlatformOSDocset } from '../../types';
 import { isError, last } from '../../utils';
@@ -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,8 @@ export const UndefinedObject: LiquidCheckDefinition = {
         }
 
         if (isLiquidTagBackground(node)) {
-          indexVariableScope(node.markup.jobId.name, {
-            start: node.blockEndPosition?.end,
+          indexVariableScope(node.markup.jobId, {
+            start: node.position.end,
           });
         }
       },
@@ -160,9 +164,8 @@ 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;
 
         variables.push(node);
       },
@@ -299,19 +302,14 @@ 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;
 }

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;

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

@@ -127,4 +127,78 @@ describe('Module: UnusedAssign', () => {
     const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
     expect(offenses).to.have.lengthOf(1);
   });
+
+  it('should not report an offense for hash mutation via assign with lookup target', async () => {
+    const sourceCode = `
+      {% assign errors = {} %}
+      {% assign errors[field] = 'value' %}
+      {{ errors }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not track assign with lookup as a new variable definition', async () => {
+    const sourceCode = `
+      {% assign errors[field_name] = field_errors %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via subscript', async () => {
+    // assign errors = contract.errors creates a reference; mutations on errors
+    // have side effects on the original, so they count as "using" errors.
+    const sourceCode = `
+      {% assign errors = contract.errors %}
+      {% assign errors[field_name] = field_errors %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via dot notation', async () => {
+    const sourceCode = `
+      {% assign data = response.data %}
+      {% assign data.status = 'ok' %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via array push', async () => {
+    const sourceCode = `
+      {% assign items = cart.items %}
+      {% assign items << new_item %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should still report when a fresh literal hash is mutated but never used', async () => {
+    const sourceCode = `
+      {% assign x = {} %}
+      {% assign x['key'] = 'value' %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(1);
+    expect(offenses[0].message).to.equal("The variable 'x' is assigned but not used");
+  });
+
+  it('should still report when a fresh literal array is pushed to but never used', async () => {
+    const sourceCode = `
+      {% assign arr = [] %}
+      {% assign arr << item %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(1);
+    expect(offenses[0].message).to.equal("The variable 'arr' is assigned but not used");
+  });
 });

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

@@ -26,6 +26,10 @@ export const UnusedAssign: LiquidCheckDefinition = {
 
   create(context) {
     const assignedVariables: Map<string, LiquidTagAssign | LiquidTagCapture> = new Map();
+    // Variables assigned from a pure variable lookup (no filters, no literals).
+    // e.g. `assign errors = contract.errors` — mutations on `errors` have side
+    // effects on the original, so they count as "using" the variable.
+    const referenceAssignedVariables: Set<string> = new Set();
     const usedVariables: Set<string> = new Set();
 
     function checkVariableUsage(node: any) {
@@ -38,7 +42,28 @@ export const UnusedAssign: LiquidCheckDefinition = {
       async LiquidTag(node, ancestors) {
         if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
         if (isLiquidTagAssign(node)) {
-          assignedVariables.set(node.markup.name, node);
+          if (node.markup.lookups.length === 0 && node.markup.operator === '=') {
+            // Simple assignment: register as a new variable
+            assignedVariables.set(node.markup.name, node);
+            // Track pure reference assignments (VariableLookup with no filters)
+            if (
+              node.markup.value.type === NodeTypes.LiquidVariable &&
+              node.markup.value.expression.type === NodeTypes.VariableLookup &&
+              node.markup.value.filters.length === 0
+            ) {
+              referenceAssignedVariables.add(node.markup.name);
+            }
+          } else {
+            // Hash/array mutation: assign x[key]=val, assign x.key=val, assign x<<val
+            // Counts as "using" x only when x is external (not locally assigned here)
+            // or was assigned as a reference alias to another variable.
+            if (
+              !assignedVariables.has(node.markup.name) ||
+              referenceAssignedVariables.has(node.markup.name)
+            ) {
+              usedVariables.add(node.markup.name);
+            }
+          }
         } else if (isLiquidTagCapture(node) && node.markup.name) {
           assignedVariables.set(node.markup.name, node);
         }

package/src/checks/variable-name/index.spec.ts

@@ -43,6 +43,15 @@ describe('Module: VariableName', () => {
     expect(suggestions).to.include(expectedFixedCode);
   });
 
+  it('should not report an error for variables starting with underscore', async () => {
+    const varNames = [`_`, `_errors`, `_temp_var`, `_myPrivateVar`];
+    for (const varName of varNames) {
+      const sourceCode = `{% assign ${varName} = "value" %}`;
+      const offenses = await runLiquidCheck(VariableName, sourceCode);
+      expect(offenses).to.be.empty;
+    }
+  });
+
   // It's impossible to make an idempotent rule that works for all cases. We
   // have to accept whatever spacing the user has input as valid.
   it('should not complain about numbers inside variable names', async () => {

package/src/checks/variable-name/index.ts

@@ -65,6 +65,11 @@ export const VariableName: LiquidCheckDefinition<typeof schema> = {
         };
       }
 
+      // Variables starting with _ are valid (used as throwaway/private variables)
+      if (node.markup.name.startsWith('_')) {
+        return { valid: true };
+      }
+
       const formatter = formatTypes[context.settings.format as FormatTypes];
       const suggestion = formatter(node.markup.name);