@platformos/platformos-check-common 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformos/platformos-check-common",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@platformos/liquid-html-parser": "0.0.10",
+    "@platformos/liquid-html-parser": "0.0.11",
     "graphql": "^16.12.0",
     "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",

package/src/AugmentedPlatformOSDocset.ts

@@ -35,6 +35,7 @@ const undocumentedFilters = [
   'handle_from',
   'pad_spaces',
   'paragraphize',
+  'push',
   'sentence',
   'unit',
   'weight',

package/src/checks/deprecated-filter/index.spec.ts

@@ -1,5 +1,5 @@
 import { expect, describe, it } from 'vitest';
-import { highlightedOffenses, runLiquidCheck } from '../../test';
+import { applySuggestions, highlightedOffenses, runLiquidCheck } from '../../test';
 import { DeprecatedFilter } from './index';
 
 const mockDependencies = {
@@ -99,4 +99,44 @@ describe('Module: DeprecatedFilter', () => {
     );
     expect(offenses).toHaveLength(2);
   });
+
+  it('should provide a suggestion to replace deprecated filter with recommended alternative', async () => {
+    const sourceCode = `{{ value | old_filter }}`;
+
+    const offenses = await runLiquidCheck(
+      DeprecatedFilter,
+      sourceCode,
+      'file.liquid',
+      mockDependencies,
+    );
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].suggest).toHaveLength(1);
+    expect(offenses[0].suggest![0].message).toEqual("Replace 'old_filter' with 'new_filter'");
+  });
+
+  it('should apply the suggestion to replace the filter name', async () => {
+    const sourceCode = `{{ value | old_filter }}`;
+
+    const offenses = await runLiquidCheck(
+      DeprecatedFilter,
+      sourceCode,
+      'file.liquid',
+      mockDependencies,
+    );
+    const suggestions = applySuggestions(sourceCode, offenses[0]);
+    expect(suggestions).toContain('{{ value | new_filter }}');
+  });
+
+  it('should not provide a suggestion when no replacement exists', async () => {
+    const sourceCode = `{{ value | deprecated_no_replacement }}`;
+
+    const offenses = await runLiquidCheck(
+      DeprecatedFilter,
+      sourceCode,
+      'file.liquid',
+      mockDependencies,
+    );
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].suggest).toBeUndefined();
+  });
 });

package/src/checks/deprecated-filter/index.ts

@@ -39,10 +39,27 @@ export const DeprecatedFilter: LiquidCheckDefinition = {
 
         const message = deprecatedFilterMessage(deprecatedFilter, recommendedFilter);
 
+        const filterText = node.source.slice(node.position.start, node.position.end);
+        const afterPipeIdx = filterText.indexOf('|') + 1;
+        const nameIdx =
+          afterPipeIdx + filterText.slice(afterPipeIdx).indexOf(deprecatedFilter.name);
+        const filterNameStart = node.position.start + nameIdx;
+        const filterNameEnd = filterNameStart + deprecatedFilter.name.length;
+
         context.report({
           message,
           startIndex: node.position.start + 1,
           endIndex: node.position.end,
+          suggest: recommendedFilter
+            ? [
+                {
+                  message: `Replace '${deprecatedFilter.name}' with '${recommendedFilter.name}'`,
+                  fix: (corrector) => {
+                    corrector.replace(filterNameStart, filterNameEnd, recommendedFilter.name);
+                  },
+                },
+              ]
+            : undefined,
         });
       },
     };

package/src/checks/graphql/index.spec.ts

@@ -0,0 +1,173 @@
+import { expect, describe, it } from 'vitest';
+import { GraphQLCheck, lineToRange } from './index';
+import { check } from '../../test';
+
+const SCHEMA = `
+  type Query {
+    hello: String
+    users: [User]
+  }
+
+  type User {
+    id: ID
+    name: String
+  }
+`;
+
+const mockDependencies = {
+  platformosDocset: {
+    async graphQL() {
+      return SCHEMA;
+    },
+    async filters() {
+      return [];
+    },
+    async objects() {
+      return [];
+    },
+    async liquidDrops() {
+      return [];
+    },
+    async tags() {
+      return [];
+    },
+  },
+};
+
+const noDeps = {
+  platformosDocset: {
+    async graphQL() {
+      return null;
+    },
+    async filters() {
+      return [];
+    },
+    async objects() {
+      return [];
+    },
+    async liquidDrops() {
+      return [];
+    },
+    async tags() {
+      return [];
+    },
+  },
+};
+
+describe('Module: GraphQLCheck', () => {
+  it('reports no offenses for a valid query', async () => {
+    const files = {
+      'app/graphql/my_query.graphql': '{ hello }',
+    };
+
+    const offenses = await check(files, [GraphQLCheck], mockDependencies);
+    expect(offenses).to.be.empty;
+  });
+
+  it('reports an offense for an unknown field', async () => {
+    const files = {
+      'app/graphql/my_query.graphql': '{ unknownField }',
+    };
+
+    const offenses = await check(files, [GraphQLCheck], mockDependencies);
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal('Cannot query field "unknownField" on type "Query".');
+  });
+
+  it('offense for unknown field spans only the affected line, not the entire file', async () => {
+    const query = `{
+  unknownField
+}`;
+    const files = {
+      'app/graphql/my_query.graphql': query,
+    };
+
+    const offenses = await check(files, [GraphQLCheck], mockDependencies);
+    expect(offenses).to.have.length(1);
+
+    // Should point to line 2 (1-based), which is "  unknownField"
+    // and NOT span to the end of the file
+    expect(offenses[0].start.line).to.equal(1); // 0-based: line index 1 = "  unknownField"
+    expect(offenses[0].end.line).to.equal(1);
+  });
+
+  it('reports a syntax error offense instead of swallowing it', async () => {
+    const files = {
+      'app/graphql/my_query.graphql': '{ unclosed {',
+    };
+
+    const offenses = await check(files, [GraphQLCheck], mockDependencies);
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.include('Syntax Error');
+  });
+
+  it('syntax error offense points to the actual error line, not the whole file', async () => {
+    // unclosed brace on line 3 causes a parse error — graphql-js will report the exact location
+    const query = `{
+  hello
+  unclosed {
+`;
+    const files = {
+      'app/graphql/my_query.graphql': query,
+    };
+
+    const offenses = await check(files, [GraphQLCheck], mockDependencies);
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.include('Syntax Error');
+    // Offense spans exactly one line (the error line), NOT the whole file
+    expect(offenses[0].start.line).to.equal(offenses[0].end.line);
+    // And that line is not the last line of the file (i.e. not spanning to the end)
+    expect(offenses[0].end.line).to.be.lessThan(3); // file has 4 lines (0-indexed: 0-3)
+  });
+
+  it('reports no offenses when platformosDocset.graphQL returns null', async () => {
+    const files = {
+      'app/graphql/my_query.graphql': '{ unknownField }',
+    };
+
+    const offenses = await check(files, [GraphQLCheck], noDeps);
+    expect(offenses).to.be.empty;
+  });
+});
+
+describe('Unit: lineToRange', () => {
+  const TEXT = 'line1\nline2\nline3';
+
+  it('returns correct range for line 1', () => {
+    expect(lineToRange(TEXT, 1)).to.eql([0, 5]); // "line1"
+  });
+
+  it('returns correct range for line 2', () => {
+    expect(lineToRange(TEXT, 2)).to.eql([6, 11]); // "line2"
+  });
+
+  it('returns correct range for line 3', () => {
+    expect(lineToRange(TEXT, 3)).to.eql([12, 17]); // "line3"
+  });
+
+  it('clamps line 0 to first line instead of spanning the whole file', () => {
+    const [start, end] = lineToRange(TEXT, 0);
+    expect(start).to.equal(0);
+    expect(end).to.equal(5); // "line1" length = 5, not TEXT.length (17)
+  });
+
+  it('clamps line beyond last to last line instead of spanning the whole file', () => {
+    const [start, end] = lineToRange(TEXT, 999);
+    expect(start).to.equal(12);
+    expect(end).to.equal(17); // "line3"
+  });
+
+  it('handles single-line text with line 0', () => {
+    const [start, end] = lineToRange('hello', 0);
+    expect(start).to.equal(0);
+    expect(end).to.equal(5); // entire single line, NOT text.length (which happens to be the same here)
+  });
+
+  it('does not return the whole file when line is 0', () => {
+    const longText = 'first line\nsecond line\nthird line';
+    const [, end] = lineToRange(longText, 0);
+    // Should be end of first line (10), not end of whole text (33)
+    expect(end).to.equal(10);
+    expect(end).to.not.equal(longText.length);
+  });
+});

package/src/checks/graphql/index.ts

@@ -1,20 +1,17 @@
 import { GraphQLCheckDefinition, Severity, SourceCodeType } from '../../types';
 import { parse } from 'graphql/language';
-import { buildSchema, validate } from 'graphql';
+import { buildSchema, GraphQLError, validate } from 'graphql';
 
-function lineToRange(text: string, line: number): [number, number] {
+export function lineToRange(text: string, line: number): [number, number] {
   const lines = text.split(/\r?\n/);
-
-  if (line < 1 || line > lines.length) {
-    return [0, text.length];
-  }
+  const clampedLine = Math.max(1, Math.min(line, lines.length));
 
   let start = 0;
-  for (let i = 0; i < line - 1; i++) {
+  for (let i = 0; i < clampedLine - 1; i++) {
     start += lines[i].length + 1;
   }
 
-  const end = start + lines[line - 1].length;
+  const end = start + lines[clampedLine - 1].length;
   return [start, end];
 }
 
@@ -42,11 +39,25 @@ export const GraphQLCheck: GraphQLCheckDefinition = {
 
       const graphQLSchema = buildSchema(graphQLSchemaString);
 
-      const document = parse(content);
+      let document;
+      try {
+        document = parse(content);
+      } catch (e) {
+        if (e instanceof GraphQLError) {
+          const [start, end] = lineToRange(content, e.locations?.[0]?.line ?? 1);
+          context.report({
+            message: e.message,
+            startIndex: start,
+            endIndex: end,
+          });
+        }
+        return;
+      }
+
       const errors = validate(graphQLSchema, document);
 
       errors.forEach((error) => {
-        const [start, end] = lineToRange(content, error.locations?.[0].line ?? 0);
+        const [start, end] = lineToRange(content, error.locations?.[0]?.line ?? 0);
         context.report({
           message: error.message,
           startIndex: start,

package/src/checks/invalid-hash-assign-target/index.spec.ts

@@ -119,6 +119,32 @@ describe('Module: InvalidHashAssignTarget', () => {
     expect(offenses).toHaveLength(0);
   });
 
+  it('should not report an error when hash_assign is used on a function return with variable partial', async () => {
+    const app: MockApp = {
+      'file.liquid': `
+        {% assign partial_name = 'lib/get_data' %}
+        {% function data = partial_name %}
+        {% hash_assign data['extra'] = 'value' %}
+      `,
+    };
+
+    const offenses = await check(app, [InvalidHashAssignTarget]);
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should not report an error when function uses hash-access result target and hash_assign follows', async () => {
+    const app: MockApp = {
+      'file.liquid': `
+        {% parse_json my_hash %}{}{% endparse_json %}
+        {% function my_hash['result'] = 'lib/get_data' %}
+        {% hash_assign my_hash['extra'] = 'value' %}
+      `,
+    };
+
+    const offenses = await check(app, [InvalidHashAssignTarget]);
+    expect(offenses).toHaveLength(0);
+  });
+
   it('should track reassignment and report error on new type', async () => {
     const app: MockApp = {
       'file.liquid': `

package/src/checks/invalid-hash-assign-target/index.ts

@@ -7,6 +7,7 @@ import {
   HashAssignMarkup,
   GraphQLMarkup,
   GraphQLInlineMarkup,
+  FunctionMarkup,
 } from '@platformos/liquid-html-parser';
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
 import { isError } from '../../utils';
@@ -229,12 +230,13 @@ export const InvalidHashAssignTarget: LiquidCheckDefinition = {
 
         // {% function result = 'path' %}
         if (node.name === NamedTags.function && typeof node.markup !== 'string') {
-          const markup = node.markup as { name: string };
-          if (markup.name) {
-            closeTypeRange(markup.name, node.position.start);
+          const markup = node.markup as FunctionMarkup;
+          const varName = markup.name.name;
+          if (varName) {
+            closeTypeRange(varName, node.position.start);
             // Function returns are untyped unless we can infer them
             variableTypes.push({
-              name: markup.name,
+              name: varName,
               type: 'untyped',
               range: [node.position.end],
             });

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 () => {

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