@platformos/platformos-check-common 0.0.12 → 0.0.13

package/src/checks/missing-render-partial-arguments/index.ts

@@ -0,0 +1,44 @@
+import { RenderMarkup } from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import {
+  getLiquidDocParams,
+  getPartialName,
+  reportMissingArguments,
+} from '../../liquid-doc/arguments';
+
+export const MissingRenderPartialArguments: LiquidCheckDefinition = {
+  meta: {
+    code: 'MissingRenderPartialArguments',
+    name: 'Missing Required Render Partial Arguments',
+    aliases: ['MissingRenderPartialParams'],
+    docs: {
+      description:
+        'This check ensures that all required @param arguments declared by a partial are provided at the call site.',
+      recommended: true,
+      url: 'https://documentation.platformos.com/developer-guide/platformos-check/checks/missing-render-partial-arguments',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async RenderMarkup(node: RenderMarkup) {
+        const partialName = getPartialName(node);
+        if (!partialName) return;
+
+        const liquidDocParameters = await getLiquidDocParams(context, partialName);
+        if (!liquidDocParameters) return;
+
+        const providedNames = new Set(node.args.map((a) => a.name));
+        const missingRequired = [...liquidDocParameters.values()].filter(
+          (p) => p.required && !providedNames.has(p.name),
+        );
+
+        reportMissingArguments(context, node, missingRequired, partialName);
+      },
+    };
+  },
+};

package/src/checks/nested-graphql-query/index.spec.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck, check } from '../../test';
+import { NestedGraphQLQuery } from '.';
+
+describe('Module: NestedGraphQLQuery', () => {
+  it('should not report graphql outside a loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% graphql result = 'products/list' %}`,
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should report graphql inside a for loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for item in items %}{% graphql result = 'products/get' %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% graphql result = 'result' %} is inside a {% for %} loop. This executes at least one database request per iteration. Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should report graphql inside a tablerow loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% tablerow item in items %}{% graphql result = 'products/get' %}{% endtablerow %}`,
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% graphql result = 'result' %} is inside a {% tablerow %} loop. This executes at least one database request per iteration. Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should report graphql inside nested loops', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for a in items %}{% for b in a.children %}{% graphql result = 'foo' %}{% endfor %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(1);
+  });
+
+  it('should not report graphql inside a loop when wrapped in cache', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for item in items %}{% cache 'key' %}{% graphql result = 'foo' %}{% endcache %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should not report background tag inside a loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for item in items %}{% background %}{% graphql result = 'foo' %}{% endbackground %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should report graphql inline markup inside a for loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for item in items %}{% graphql result %}query { records { results { id } } }{% endgraphql %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% graphql result = 'result' %} is inside a {% for %} loop. This executes at least one database request per iteration. Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should report multiple graphql tags inside one loop', async () => {
+    const offenses = await runLiquidCheck(
+      NestedGraphQLQuery,
+      `{% for item in items %}{% graphql a = 'foo' %}{% graphql b = 'bar' %}{% endfor %}`,
+    );
+    expect(offenses).to.have.length(2);
+  });
+
+  it('should report function call inside loop that transitively calls graphql', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = 'my_partial' %}{% endfor %}`,
+        'app/lib/my_partial.liquid': `{% graphql result = 'products/get' %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% function 'my_partial' %} inside a {% for %} loop transitively calls a GraphQL query (my_partial). Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should report render call inside loop that transitively calls graphql', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% render 'my_partial' %}{% endfor %}`,
+        'app/views/partials/my_partial.liquid': `{% graphql result = 'products/get' %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% render 'my_partial' %} inside a {% for %} loop transitively calls a GraphQL query (my_partial). Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should report function call that transitively calls graphql through another function', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = 'outer' %}{% endfor %}`,
+        'app/lib/outer.liquid': `{% function inner_res = 'inner' %}`,
+        'app/lib/inner.liquid': `{% graphql result = 'products/get' %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "N+1 pattern: {% function 'outer' %} inside a {% for %} loop transitively calls a GraphQL query (outer \u2192 inner). Move the query before the loop and pass data as a variable.",
+    );
+  });
+
+  it('should not report function call inside loop that does not call graphql', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = 'safe_partial' %}{% endfor %}`,
+        'app/lib/safe_partial.liquid': `{{ 'hello' }}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should not report function call inside loop when partial does not exist', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = 'nonexistent' %}{% endfor %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should not report function call inside loop with cache wrapping', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% cache 'key' %}{% function res = 'my_partial' %}{% endcache %}{% endfor %}`,
+        'app/lib/my_partial.liquid': `{% graphql result = 'products/get' %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should handle circular function calls without infinite loop', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = 'partial_a' %}{% endfor %}`,
+        'app/lib/partial_a.liquid': `{% function res = 'partial_b' %}`,
+        'app/lib/partial_b.liquid': `{% function res = 'partial_a' %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should skip function calls with dynamic partial names', async () => {
+    const offenses = await check(
+      {
+        'app/views/pages/index.liquid': `{% for item in items %}{% function res = partial_name %}{% endfor %}`,
+      },
+      [NestedGraphQLQuery],
+    );
+    expect(offenses).to.have.length(0);
+  });
+});

package/src/checks/nested-graphql-query/index.ts

@@ -0,0 +1,203 @@
+import {
+  LiquidHtmlNode,
+  NamedTags,
+  NodeTypes,
+  toLiquidHtmlAST,
+} from '@platformos/liquid-html-parser';
+import { DocumentsLocator } from '@platformos/platformos-common';
+import { URI } from 'vscode-uri';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { isLoopLiquidTag } from '../utils';
+
+const SKIP_IF_ANCESTOR_TAGS = [NamedTags.cache];
+
+type GraphQLFound = {
+  type: 'graphql';
+  partialChain: string[];
+};
+
+type FunctionOrRenderFound = {
+  type: 'function' | 'render';
+  partialName: string;
+};
+
+type FoundNode = GraphQLFound | FunctionOrRenderFound;
+
+function findNodesInAST(ast: LiquidHtmlNode[]): FoundNode[] {
+  const results: FoundNode[] = [];
+  const stack: LiquidHtmlNode[] = [...ast];
+
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+
+    if (node.type === NodeTypes.LiquidTag) {
+      if (node.name === NamedTags.graphql) {
+        results.push({ type: 'graphql', partialChain: [] });
+      } else if (
+        (node.name === NamedTags.function || node.name === NamedTags.render) &&
+        typeof node.markup !== 'string' &&
+        'partial' in node.markup &&
+        node.markup.partial.type !== NodeTypes.VariableLookup
+      ) {
+        results.push({ type: node.name, partialName: node.markup.partial.value });
+      }
+
+      if ('children' in node && Array.isArray(node.children)) {
+        stack.push(...node.children);
+      }
+    } else if ('children' in node && Array.isArray((node as any).children)) {
+      stack.push(...(node as any).children);
+    }
+  }
+
+  return results;
+}
+
+async function containsGraphQLTransitively(
+  locator: DocumentsLocator,
+  fs: { readFile(uri: string): Promise<string> },
+  rootUri: URI,
+  partialName: string,
+  tagType: 'function' | 'render',
+  visited: Set<string>,
+): Promise<string[] | null> {
+  if (visited.has(partialName)) return null;
+  visited.add(partialName);
+
+  const location = await locator.locate(rootUri, tagType, partialName);
+  if (!location) return null;
+
+  let source: string;
+  try {
+    source = await fs.readFile(location);
+  } catch {
+    return null;
+  }
+
+  let ast;
+  try {
+    ast = toLiquidHtmlAST(source);
+  } catch {
+    return null;
+  }
+
+  const nodes = findNodesInAST(ast.children);
+
+  for (const found of nodes) {
+    if (found.type === 'graphql') {
+      return [partialName];
+    }
+  }
+
+  for (const found of nodes) {
+    if (found.type === 'function' || found.type === 'render') {
+      const chain = await containsGraphQLTransitively(
+        locator,
+        fs,
+        rootUri,
+        found.partialName,
+        found.type,
+        visited,
+      );
+      if (chain) {
+        return [partialName, ...chain];
+      }
+    }
+  }
+
+  return null;
+}
+
+export const NestedGraphQLQuery: LiquidCheckDefinition = {
+  meta: {
+    code: 'NestedGraphQLQuery',
+    name: 'Prevent N+1 GraphQL queries in loops',
+    docs: {
+      description:
+        'This check detects {% graphql %} tags placed inside loop tags ({% for %}, {% tablerow %}), which causes one database request per loop iteration (N+1 pattern). It also follows {% function %} and {% render %} calls transitively to detect indirect GraphQL queries.',
+      recommended: true,
+      url: 'https://documentation.platformos.com/developer-guide/platformos-check/checks/nested-graphql-query',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const locator = new DocumentsLocator(context.fs);
+    const rootUri = URI.parse(context.config.rootUri);
+
+    function isInsideLoopWithoutCacheOrBackground(ancestors: LiquidHtmlNode[]) {
+      const ancestorTags = ancestors.filter((a) => a.type === NodeTypes.LiquidTag);
+      const loopAncestor = ancestorTags.find(isLoopLiquidTag);
+      if (!loopAncestor) return null;
+
+      const inBackground = ancestorTags.some((a) => a.name === NamedTags.background);
+      if (inBackground) return null;
+
+      const shouldSkip = ancestorTags.some((a) =>
+        SKIP_IF_ANCESTOR_TAGS.map((a) => a.toString()).includes(a.name),
+      );
+      if (shouldSkip) return null;
+
+      return loopAncestor;
+    }
+
+    return {
+      async LiquidTag(node, ancestors) {
+        if (node.name === NamedTags.graphql) {
+          const loopAncestor = isInsideLoopWithoutCacheOrBackground(ancestors);
+          if (!loopAncestor) return;
+
+          let resultName = '';
+          if (
+            typeof node.markup !== 'string' &&
+            (node.markup.type === NodeTypes.GraphQLMarkup ||
+              node.markup.type === NodeTypes.GraphQLInlineMarkup)
+          ) {
+            resultName = node.markup.name ? ` result = '${node.markup.name}'` : '';
+          }
+
+          const graphqlStr = resultName ? `{% graphql${resultName} %}` : '{% graphql %}';
+          context.report({
+            message: `N+1 pattern: ${graphqlStr} is inside a {% ${loopAncestor.name} %} loop. This executes at least one database request per iteration. Move the query before the loop and pass data as a variable.`,
+            startIndex: node.position.start,
+            endIndex: node.position.end,
+          });
+        } else if (node.name === NamedTags.function || node.name === NamedTags.render) {
+          const loopAncestor = isInsideLoopWithoutCacheOrBackground(ancestors);
+          if (!loopAncestor) return;
+
+          if (
+            typeof node.markup === 'string' ||
+            !('partial' in node.markup) ||
+            node.markup.partial.type === NodeTypes.VariableLookup
+          ) {
+            return;
+          }
+
+          const partialName = node.markup.partial.value;
+          const visited = new Set<string>();
+          const chain = await containsGraphQLTransitively(
+            locator,
+            context.fs,
+            rootUri,
+            partialName,
+            node.name,
+            visited,
+          );
+
+          if (chain) {
+            const chainStr = chain.join(' → ');
+            context.report({
+              message: `N+1 pattern: {% ${node.name} '${partialName}' %} inside a {% ${loopAncestor.name} %} loop transitively calls a GraphQL query (${chainStr}). Move the query before the loop and pass data as a variable.`,
+              startIndex: node.position.start,
+              endIndex: node.position.end,
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/src/checks/parser-blocking-script/index.spec.ts

@@ -20,7 +20,9 @@ describe('Module: ParserBlockingScript', () => {
     expect(offenses).to.have.length(1);
     const { check, message, start, end } = offenses[0];
     expect(check).to.equal(ParserBlockingScript.meta.code);
-    expect(message).to.contain('Avoid parser blocking scripts by adding `defer`');
+    expect(message).to.equal(
+      'Avoid parser blocking scripts by adding `defer` or `async` on this tag',
+    );
     expect(start.index).to.equal(startIndex);
     expect(end.index).to.equal(endIndex);
   });
@@ -45,8 +47,10 @@ describe('Module: ParserBlockingScript', () => {
       });
 
       const suggestions = applySuggestions(file, offense);
-      expect(suggestions).to.include('<script src="a.js" defer></script>');
-      expect(suggestions).to.include('<script src="a.js" async></script>');
+      expect(suggestions).to.deep.equal([
+        '<script src="a.js" defer></script>',
+        '<script src="a.js" async></script>',
+      ]);
     });
   });
 

package/src/checks/translation-key-exists/index.spec.ts

@@ -38,7 +38,84 @@ describe('Module: TranslationKeyExists', () => {
     );
 
     expect(offenses).to.have.length(1);
-    expect(offenses[0].message).to.include('missing.key');
-    expect(offenses[0].message).to.include('does not have a matching translation entry');
+    expect(offenses[0].message).to.equal(
+      "'missing.key' does not have a matching translation entry",
+    );
+  });
+
+  it('should suggest nearest key when the key is a typo', async () => {
+    const offenses = await check(
+      {
+        'app/translations/en.yml': 'en:\n  general:\n    title: Hello',
+        'code.liquid': `{{"general.titel" | t}}`,
+      },
+      [TranslationKeyExists],
+    );
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].suggest).to.have.length(1);
+    expect(offenses[0].suggest![0].message).to.equal("Did you mean 'general.title'?");
+  });
+
+  it('should not add suggestions when there is no close key', async () => {
+    const offenses = await check(
+      {
+        'app/translations/en.yml': 'en:\n  general:\n    title: Hello',
+        'code.liquid': `{{"completely.different.xyz" | t}}`,
+      },
+      [TranslationKeyExists],
+    );
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].suggest ?? []).to.have.length(0);
+  });
+
+  it('should not report a module translation key that exists', async () => {
+    const offenses = await check(
+      {
+        'app/modules/user/public/translations/en.yml': 'en:\n  greeting: Hello',
+        'code.liquid': '{{"modules/user/greeting" | t}}',
+      },
+      [TranslationKeyExists],
+    );
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should report a module translation key that does not exist', async () => {
+    const offenses = await check(
+      {
+        'app/modules/user/public/translations/en.yml': 'en:\n  greeting: Hello',
+        'code.liquid': '{{"modules/user/missing" | t}}',
+      },
+      [TranslationKeyExists],
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "'modules/user/missing' does not have a matching translation entry",
+    );
+  });
+
+  it('should suggest nearest module key for typos', async () => {
+    const offenses = await check(
+      {
+        'app/modules/user/public/translations/en.yml': 'en:\n  greeting: Hello',
+        'code.liquid': '{{"modules/user/greating" | t}}',
+      },
+      [TranslationKeyExists],
+    );
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].suggest).to.have.length(1);
+    expect(offenses[0].suggest![0].message).to.equal("Did you mean 'modules/user/greeting'?");
+  });
+
+  it('should find keys in legacy modules/ path', async () => {
+    const offenses = await check(
+      {
+        'modules/core/public/translations/en.yml': 'en:\n  label: Label',
+        'code.liquid': '{{"modules/core/label" | t}}',
+      },
+      [TranslationKeyExists],
+    );
+    expect(offenses).to.have.length(0);
   });
 });

package/src/checks/translation-key-exists/index.ts

@@ -1,22 +1,6 @@
-import { TranslationProvider } from '@platformos/platformos-common';
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
-import { URI } from 'vscode-uri';
-
-function keyExists(key: string, pointer: any) {
-  for (const token of key.split('.')) {
-    if (typeof pointer !== 'object') {
-      return false;
-    }
-
-    if (!pointer.hasOwnProperty(token)) {
-      return false;
-    }
-
-    pointer = pointer[token];
-  }
-
-  return true;
-}
+import { findNearestKeys } from '../../utils/levenshtein';
+import { loadAllDefinedKeys } from '../translation-utils';
 
 export const TranslationKeyExists: LiquidCheckDefinition = {
   meta: {
@@ -35,7 +19,6 @@ export const TranslationKeyExists: LiquidCheckDefinition = {
 
   create(context) {
     const nodes: { translationKey: string; startIndex: number; endIndex: number }[] = [];
-    const translationProvider = new TranslationProvider(context.fs);
 
     return {
       async LiquidVariable(node) {
@@ -55,21 +38,29 @@ export const TranslationKeyExists: LiquidCheckDefinition = {
       },
 
       async onCodePathEnd() {
-        for (const { translationKey, startIndex, endIndex } of nodes) {
-          const translation = await translationProvider.translate(
-            URI.parse(context.config.rootUri),
-            translationKey,
-          );
+        if (nodes.length === 0) return;
+
+        // Load all defined keys (app + modules) once per file
+        const allDefinedKeys = await loadAllDefinedKeys(context);
+        const definedKeySet = new Set(allDefinedKeys);
 
-          if (!!translation) {
-            return;
-          }
+        for (const { translationKey, startIndex, endIndex } of nodes) {
+          if (definedKeySet.has(translationKey)) continue;
 
+          const nearest = findNearestKeys(translationKey, allDefinedKeys);
           const message = `'${translationKey}' does not have a matching translation entry`;
+
           context.report({
             message,
             startIndex,
             endIndex,
+            suggest:
+              nearest.length > 0
+                ? nearest.map((key) => ({
+                    message: `Did you mean '${key}'?`,
+                    fix: (fixer: any) => fixer.replace(startIndex, endIndex, `'${key}'`),
+                  }))
+                : undefined,
           });
         }
       },

package/src/checks/translation-utils.ts

@@ -0,0 +1,63 @@
+import { FileType, TranslationProvider } from '@platformos/platformos-common';
+import { flattenTranslationKeys } from '../utils/levenshtein';
+
+/**
+ * Discovers all module names by listing app/modules/ and modules/ directories.
+ * Returns a deduplicated set of module names.
+ */
+export async function discoverModules(
+  fs: { readDirectory(uri: string): Promise<[string, FileType][]> },
+  ...moduleDirUris: string[]
+): Promise<Set<string>> {
+  const modules = new Set<string>();
+  for (const dirUri of moduleDirUris) {
+    try {
+      const entries = await fs.readDirectory(dirUri);
+      for (const [entryUri, entryType] of entries) {
+        if (entryType === FileType.Directory) {
+          modules.add(entryUri.split('/').pop()!);
+        }
+      }
+    } catch (error) {
+      console.error(`[translation-utils] Failed to read module directory ${dirUri}:`, error);
+    }
+  }
+  return modules;
+}
+
+export interface TranslationContext {
+  fs: { readDirectory(uri: string): Promise<[string, FileType][]> };
+  toUri(relativePath: string): string;
+  getTranslationsForBase(uri: string, locale: string): Promise<Record<string, any>>;
+}
+
+/**
+ * Loads all defined translation keys (app-level + module-level) and returns
+ * them as a flat string array. Module keys are prefixed with `modules/{name}/`.
+ */
+export async function loadAllDefinedKeys(context: TranslationContext): Promise<string[]> {
+  const definedKeys: string[] = [];
+
+  // App-level translations
+  for (const base of TranslationProvider.getSearchPaths()) {
+    const translations = await context.getTranslationsForBase(context.toUri(base), 'en');
+    definedKeys.push(...flattenTranslationKeys(translations));
+  }
+
+  // Module translations
+  const modules = await discoverModules(
+    context.fs,
+    context.toUri('app/modules'),
+    context.toUri('modules'),
+  );
+  for (const moduleName of modules) {
+    for (const base of TranslationProvider.getSearchPaths(moduleName)) {
+      const translations = await context.getTranslationsForBase(context.toUri(base), 'en');
+      for (const key of flattenTranslationKeys(translations)) {
+        definedKeys.push(`modules/${moduleName}/${key}`);
+      }
+    }
+  }
+
+  return definedKeys;
+}