@platformos/platformos-check-common 0.0.13 → 0.0.16

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

@@ -1,31 +1,9 @@
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
-import yaml from 'js-yaml';
 import { DocumentsLocator, DocumentType } from '@platformos/platformos-common';
 import { URI } from 'vscode-uri';
 import { LiquidNamedArgument, Position } from '@platformos/liquid-html-parser';
 import { relative } from '../../path';
-
-type Metadata = {
-  metadata: {
-    params: Record<string, unknown>;
-  };
-};
-
-function extractMetadataParams(source: string): string[] | null {
-  source = source.trim();
-  if (!source.startsWith('---')) return null;
-
-  const end = source.indexOf('---', 3);
-  if (end === -1) return null;
-
-  const yamlBlock = source.slice(3, end).trim();
-  try {
-    const result = yaml.load(yamlBlock) as Metadata;
-    return Object.keys(result.metadata.params);
-  } catch (e) {
-    return null;
-  }
-}
+import { extractUndefinedVariables } from './extract-undefined-variables';
 
 export const MetadataParamsCheck: LiquidCheckDefinition = {
   meta: {
@@ -33,7 +11,7 @@ export const MetadataParamsCheck: LiquidCheckDefinition = {
     name: 'Metadata Params Check',
     docs: {
       description:
-        'Ensures that parameters referenced in the document exist in metadata.params or in the doc tag.',
+        'Ensures that parameters referenced in the document exist in the doc tag or are inferred from undefined variables.',
       recommended: true,
       url: undefined,
     },
@@ -61,21 +39,60 @@ export const MetadataParamsCheck: LiquidCheckDefinition = {
       if (!locatedFile) {
         return;
       }
-      let params = extractMetadataParams(await context.fs.readFile(locatedFile));
-      if (!params) {
-        if (!context.getDocDefinition) return;
-        const relativePath = relative(locatedFile, context.config.rootUri);
-        const docDef = await context.getDocDefinition(relativePath);
-        if (!docDef?.liquidDoc?.parameters) return;
-        const liquidDocParameters = new Map(docDef.liquidDoc.parameters.map((p) => [p.name, p]));
 
-        params = Array.from(liquidDocParameters.values())
+      const source = await context.fs.readFile(locatedFile);
+      const relativePath = relative(locatedFile, context.config.rootUri);
+
+      let requiredParams: string[];
+      let allowedParams: string[];
+
+      // Check for @doc tag first — if present, it's the complete param list
+      const docDef = context.getDocDefinition
+        ? await context.getDocDefinition(relativePath)
+        : undefined;
+
+      if (docDef?.liquidDoc?.parameters) {
+        const globalObjectNames: string[] = [];
+        if (context.platformosDocset) {
+          const objects = await context.platformosDocset.objects();
+          for (const obj of objects) {
+            if (!obj.access || obj.access.global === true || obj.access.template.length > 0) {
+              globalObjectNames.push(obj.name);
+            }
+          }
+        }
+        const undefinedVars = extractUndefinedVariables(source, globalObjectNames);
+        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
+        const globalObjectNames: string[] = [];
+        if (context.platformosDocset) {
+          const objects = await context.platformosDocset.objects();
+          for (const obj of objects) {
+            if (!obj.access || obj.access.global === true || obj.access.template.length > 0) {
+              globalObjectNames.push(obj.name);
+            }
+          }
+        }
+        if (relativePath.includes('views/partials/') || relativePath.includes('/lib/')) {
+          if (!globalObjectNames.includes('app')) {
+            globalObjectNames.push('app');
+          }
+        }
+
+        const undefinedVars = extractUndefinedVariables(source, globalObjectNames);
+        if (undefinedVars.length === 0) return;
+
+        requiredParams = undefinedVars;
+        allowedParams = undefinedVars;
       }
 
       args
-        .filter((arg) => !params.includes(arg.name))
+        .filter((arg) => !allowedParams.includes(arg.name))
         .forEach((arg) => {
           context.report({
             message: `Unknown parameter ${arg.name} passed to ${nodeType} call`,
@@ -84,7 +101,7 @@ export const MetadataParamsCheck: LiquidCheckDefinition = {
           });
         });
 
-      params
+      requiredParams
         .filter((param) => !args.find((arg) => arg.name === param))
         .forEach((param) => {
           context.report({

package/src/checks/translation-utils.ts

@@ -1,4 +1,4 @@
-import { FileType, TranslationProvider } from '@platformos/platformos-common';
+import { AbstractFileSystem, FileType, TranslationProvider } from '@platformos/platformos-common';
 import { flattenTranslationKeys } from '../utils/levenshtein';
 
 /**
@@ -6,7 +6,7 @@ import { flattenTranslationKeys } from '../utils/levenshtein';
  * Returns a deduplicated set of module names.
  */
 export async function discoverModules(
-  fs: { readDirectory(uri: string): Promise<[string, FileType][]> },
+  fs: AbstractFileSystem,
   ...moduleDirUris: string[]
 ): Promise<Set<string>> {
   const modules = new Set<string>();
@@ -18,15 +18,15 @@ export async function discoverModules(
           modules.add(entryUri.split('/').pop()!);
         }
       }
-    } catch (error) {
-      console.error(`[translation-utils] Failed to read module directory ${dirUri}:`, error);
+    } catch {
+      // Directory doesn't exist or isn't accessible — skip
     }
   }
   return modules;
 }
 
 export interface TranslationContext {
-  fs: { readDirectory(uri: string): Promise<[string, FileType][]> };
+  fs: AbstractFileSystem;
   toUri(relativePath: string): string;
   getTranslationsForBase(uri: string, locale: string): Promise<Record<string, any>>;
 }

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

@@ -4,13 +4,25 @@ import { runLiquidCheck, highlightedOffenses } from '../../test';
 import { Offense } from '../../types';
 
 describe('Module: UndefinedObject', () => {
-  it('should report an offense when object is undefined', async () => {
+  it('should not report offenses when no doc tag is present', async () => {
     const sourceCode = `
       {{ my_var }}
     `;
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
 
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense when object is undefined and doc tag is present', async () => {
+    const sourceCode = `
+      {% doc %}
+      {% enddoc %}
+      {{ my_var }}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
     expect(offenses).toHaveLength(1);
     expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'my_var' used."]);
 
@@ -18,8 +30,10 @@ describe('Module: UndefinedObject', () => {
     expect(highlights).toEqual(['my_var']);
   });
 
-  it('should report an offense when object with an attribute is undefined', async () => {
+  it('should report an offense when object with an attribute is undefined and doc tag is present', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ my_var.my_attr }}
     `;
 
@@ -29,8 +43,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'my_var' used."]);
   });
 
-  it('should report an offense when undefined object is used as an argument', async () => {
+  it('should report an offense when undefined object is used as an argument with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ product[my_object] }}
       {{ product[my_object] }}
 
@@ -47,12 +63,14 @@ describe('Module: UndefinedObject', () => {
     ]);
   });
 
-  it('should report an offense when object is undefined in a Liquid tag', async () => {
+  it('should report an offense when object is undefined in a Liquid tag with doc tag', async () => {
     const sourceCode = `
-    {% liquid
-      echo my_var
-    %}
-  `;
+      {% doc %}
+      {% enddoc %}
+      {% liquid
+        echo my_var
+      %}
+    `;
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
 
@@ -121,8 +139,11 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when object is defined in a for loop but used outside of the scope', async () => {
+  it('should report an offense when object is defined in a for loop but used outside of the scope with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+        @param {Array} collections
+      {% enddoc %}
       {% for c in collections %}
         {{ c }}
       {% endfor %}{{ c }}
@@ -145,8 +166,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when function result variable is used before its definition', async () => {
+  it('should report an offense when function result variable is used before its definition with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ a }}
       {% function a = 'test' %}
     `;
@@ -183,15 +206,14 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when a variable partial in include is undefined', async () => {
+  it('should not report offenses for undefined partials without doc tag', 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.");
+    expect(offenses).toHaveLength(0);
   });
 
   it('should not report an offense when a variable partial in include is defined', async () => {
@@ -205,19 +227,20 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when a variable partial in function is undefined', async () => {
+  it('should not report offenses for undefined function partials without doc tag', 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.");
+    expect(offenses).toHaveLength(0);
   });
 
   it('should not report an offense for the result variable itself in function tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% function result = undefined_partial %}
     `;
 
@@ -227,8 +250,10 @@ describe('Module: UndefinedObject', () => {
     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 () => {
+  it('should report offenses for lookup key variables in function result target and partial with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% parse_json my_hash %}{}{% endparse_json %}
       {% function my_hash[lookup_key] = my_hash[path_var] %}
     `;
@@ -242,8 +267,10 @@ describe('Module: UndefinedObject', () => {
     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 () => {
+  it('should check the partial variable in function but not the hash-access result target base with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% parse_json my_hash %}{}{% endparse_json %}
       {% function my_hash['key'] = undefined_partial %}
     `;
@@ -255,8 +282,11 @@ describe('Module: UndefinedObject', () => {
     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 () => {
+  it('should report an offense when object is defined in a for loop but used outside of the scope (multiple scopes) with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+        @param {Array} collections
+      {% enddoc %}
       {% for c in collections %}
         {% comment %} -- Scope 1 -- {% endcomment %}
         {{ c }}
@@ -278,8 +308,10 @@ describe('Module: UndefinedObject', () => {
     ]);
   });
 
-  it('should report an offense when undefined object defines another object', async () => {
+  it('should report an offense when undefined object defines another object with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% assign my_object = my_var %}
       {{ my_object }}
     `;
@@ -302,8 +334,11 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when object is defined in a tablerow loop but used outside of the scope', async () => {
+  it('should report an offense when object is defined in a tablerow loop but used outside of the scope with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+        @param {Array} collections
+      {% enddoc %}
       {% tablerow c in collections %}
         {{ c }}
       {% endtablerow %}{{ c }}
@@ -315,8 +350,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'c' used."]);
   });
 
-  it('should contextually report on the undefined nature of the form object (defined in form tag, undefined outside)', async () => {
+  it('should contextually report on the undefined nature of the form object with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% form "cart" %}
         {{ form }}
       {% endform %}{{ form }}
@@ -328,8 +365,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'form' used."]);
   });
 
-  it('should support {% layout none %}', async () => {
+  it('should support {% layout none %} with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% layout none %}
       {{ none }}
     `;
@@ -352,7 +391,7 @@ describe('Module: UndefinedObject', () => {
     }
   });
 
-  it('should report an offense when object is undefined in a "partial" file with doc tags that are missing the associated param', async () => {
+  it('should report an offense when object is undefined in a partial file with empty doc tag', async () => {
     const sourceCode = `
     {% doc %}
     {% enddoc %}
@@ -384,8 +423,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when object is not global', async () => {
+  it('should report an offense when object is not global with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ image }}
     `;
 
@@ -409,19 +450,21 @@ describe('Module: UndefinedObject', () => {
     }
   });
 
-  it('should support contextual exceptions for partials', async () => {
+  it('should not report offenses for contextual objects without doc tag', async () => {
     let offenses: Offense[];
     const contexts: [string, string][] = [['app', 'app/views/partials/theme-app-extension.liquid']];
     for (const [object, goodPath] of contexts) {
       offenses = await runLiquidCheck(UndefinedObject, `{{ ${object} }}`, goodPath);
       expect(offenses).toHaveLength(0);
       offenses = await runLiquidCheck(UndefinedObject, `{{ ${object} }}`, 'file.liquid');
-      expect(offenses).toHaveLength(1);
+      expect(offenses).toHaveLength(0);
     }
   });
 
-  it('should report an offense for forloop/tablerowloop used outside of context', async () => {
+  it('should report an offense for forloop/tablerowloop used outside of context with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ forloop }}
       {{ tablerowloop }}
     `;
@@ -458,8 +501,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when assigning an undefined variable to itself', async () => {
+  it('should report an offense when assigning an undefined variable to itself with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% assign my_var = my_var | default: "fallback" %}
     `;
 
@@ -469,7 +514,7 @@ describe('Module: UndefinedObject', () => {
     expect(offenses[0].message).toBe("Unknown object 'my_var' used.");
   });
 
-  it('should report an offense when undefined variable is used inside background block', async () => {
+  it('should not report offenses for undefined variables inside background block without doc tag', async () => {
     const sourceCode = `
       {% background source_type: 'some form' %}
         {{ undefined_var }}
@@ -478,7 +523,7 @@ describe('Module: UndefinedObject', () => {
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
 
-    expect(offenses).toHaveLength(1);
+    expect(offenses).toHaveLength(0);
   });
 
   it('should not report an offense when job_id is used after background file-based tag', async () => {
@@ -503,7 +548,7 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when job_id is used before background file-based tag', async () => {
+  it('should not report offenses for job_id used before background tag without doc tag', async () => {
     const sourceCode = `
       {{ my_job }}
       {% background my_job = 'some_partial' %}
@@ -511,8 +556,7 @@ describe('Module: UndefinedObject', () => {
 
     const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
 
-    expect(offenses).toHaveLength(1);
-    expect(offenses.map((e) => e.message)).toEqual(["Unknown object 'my_job' used."]);
+    expect(offenses).toHaveLength(0);
   });
 
   it('should not report an offense when object is defined with a parse_json tag', async () => {
@@ -528,8 +572,10 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense when parse_json variable is used before the tag', async () => {
+  it('should report an offense when parse_json variable is used before the tag with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {{ groups_data }}
       {% parse_json groups_data %}
         { "hello": "world" }
@@ -556,8 +602,91 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(0);
   });
 
-  it('should report an offense for catch variable used outside catch block', async () => {
+  it('should report an offense for undefined variables in a page file even without doc tag', async () => {
+    const sourceCode = `
+      {{ my_var }}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UndefinedObject,
+      sourceCode,
+      'app/views/pages/home.liquid',
+    );
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'my_var' used.");
+  });
+
+  it('should report an offense for undefined variables in a module page file even without doc tag', async () => {
+    const sourceCode = `
+      {{ my_var }}
+    `;
+
+    const modulePaths = [
+      'modules/my_module/public/views/pages/home.liquid',
+      'modules/my_module/private/views/pages/home.liquid',
+      'app/modules/my_module/public/views/pages/home.liquid',
+      'app/modules/my_module/private/views/pages/home.liquid',
+    ];
+
+    for (const pagePath of modulePaths) {
+      const offenses = await runLiquidCheck(UndefinedObject, sourceCode, pagePath);
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe("Unknown object 'my_var' used.");
+    }
+  });
+
+  it('should not report offenses for global objects in a page file without doc tag', async () => {
+    const sourceCode = `
+      {{ collections }}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UndefinedObject,
+      sourceCode,
+      'app/views/pages/home.liquid',
+    );
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should not report offenses for assigned variables in a page file without doc tag', async () => {
+    const sourceCode = `
+      {% assign my_var = "hello" %}
+      {{ my_var }}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UndefinedObject,
+      sourceCode,
+      'app/views/pages/home.liquid',
+    );
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should respect @param in a page file with doc tag', async () => {
+    const sourceCode = `
+      {% doc %}
+        @param {string} text
+      {% enddoc %}
+      {{ text }}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UndefinedObject,
+      sourceCode,
+      'app/views/pages/home.liquid',
+    );
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense for catch variable used outside catch block with doc tag', async () => {
     const sourceCode = `
+      {% doc %}
+      {% enddoc %}
       {% try %}
         {{ "something" }}
       {% catch error %}

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

@@ -22,6 +22,7 @@ import {
 import { LiquidCheckDefinition, Severity, SourceCodeType, PlatformOSDocset } from '../../types';
 import { isError, last } from '../../utils';
 import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+import { isPage } from '../../path';
 import yaml from 'js-yaml';
 
 type Scope = { start?: number; end?: number };
@@ -58,6 +59,7 @@ export const UndefinedObject: LiquidCheckDefinition = {
     const scopedVariables: Map<string, Scope[]> = new Map();
     const fileScopedVariables: Set<string> = new Set();
     const variables: LiquidVariableLookup[] = [];
+    let hasDocTag = false;
 
     function indexVariableScope(variableName: string | null, scope: Scope) {
       if (!variableName) return;
@@ -74,6 +76,12 @@ export const UndefinedObject: LiquidCheckDefinition = {
         }
       },
 
+      async LiquidRawTag(node) {
+        if (node.name === 'doc') {
+          hasDocTag = true;
+        }
+      },
+
       async LiquidTag(node, ancestors) {
         if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
 
@@ -191,6 +199,11 @@ export const UndefinedObject: LiquidCheckDefinition = {
       },
 
       async onCodePathEnd() {
+        const fileIsPage = isPage(context.file.uri);
+
+        // If no @doc tag and not a page, assume undefined variables are params from caller
+        if (!hasDocTag && !fileIsPage) return;
+
         const objects = await globalObjects(platformosDocset, relativePath);
 
         objects.forEach((obj) => fileScopedVariables.add(obj.name));

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

@@ -347,6 +347,68 @@ query {
     });
   });
 
+  describe('JSON literal validation', () => {
+    it('should report unknown property on hash literal', async () => {
+      const sourceCode = `{% assign a = {x: 5} %}{{ a.b }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'b' on 'a'.");
+    });
+
+    it('should not report for valid property on hash literal', async () => {
+      const sourceCode = `{% assign a = {x: 5, y: 10} %}{{ a.x }}{{ a.y }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should handle nested hash literals', async () => {
+      const sourceCode = `{% assign a = {x: {y: 1}} %}{{ a.x.y }}{{ a.x.z }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'z' on 'a.x'.");
+    });
+
+    it('should report unknown property access on array literal', async () => {
+      const sourceCode = `{% assign a = [2, 3] %}{{ a.asd }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'asd' on 'a'.");
+    });
+
+    it('should allow first/last/size on array literals', async () => {
+      const sourceCode = `{% assign a = [2, 3] %}{{ a.first }}{{ a.last }}{{ a.size }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should allow numeric index on array literals', async () => {
+      const sourceCode = `{% assign a = [2, 3] %}{{ a[0] }}{{ a[1] }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should report primitive access on array item from hash literal items', async () => {
+      const sourceCode = `{% assign a = [{x: 1}, {x: 2}] %}{{ a.first.x }}{{ a.first.y }}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'y' on 'a.first'.");
+    });
+
+    it('should report unknown property when assigning from known-shape variable', async () => {
+      const sourceCode = `{% assign a = [2, 3] %}{% assign b = a.asd %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'asd' on 'a'.");
+    });
+
+    it('should report unknown property on hash literal assigned via another variable', async () => {
+      const sourceCode = `{% assign a = {a: 5} %}{% assign b = a.b %}`;
+      const offenses = await runLiquidCheck(UnknownProperty, sourceCode);
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toEqual("Unknown property 'b' on 'a'.");
+    });
+  });
+
   describe('error message formatting', () => {
     it('should include variable name in error message', async () => {
       const sourceCode = `{% assign myVar = '{"a": 1}' | parse_json %}