@platformos/platformos-check-common 0.0.7 → 0.0.9

package/src/checks/liquid-html-syntax-error/checks/InvalidTagSyntax.spec.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck, highlightedOffenses } from '../../../test';
+import { LiquidHTMLSyntaxError } from '../index';
+
+describe('Module: InvalidTagSyntax', () => {
+  describe('render tag', () => {
+    it('should report render without quoted template name', async () => {
+      const sourceCode = `{% render %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'render'");
+    });
+
+    it('should not report valid render', async () => {
+      const sourceCode = `{% render 'partial' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid render with arguments', async () => {
+      const sourceCode = `{% render 'partial', var1: 'hello', var2: 123 %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should highlight the entire invalid render tag', async () => {
+      const sourceCode = `Hello {% render %} world`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      const highlights = highlightedOffenses(sourceCode, syntaxOffenses);
+      expect(highlights).toContain('{% render %}');
+    });
+  });
+
+  describe('function tag', () => {
+    it('should report function without = operator', async () => {
+      const sourceCode = `{% function res 'path/to/function' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'function'");
+    });
+
+    it('should not report valid function', async () => {
+      const sourceCode = `{% function res = 'path/to/function' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid function with arguments', async () => {
+      const sourceCode = `{% function res = 'path/to/function', arg1: "hello" %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('graphql tag', () => {
+    it('should report invalid graphql syntax', async () => {
+      const sourceCode = `{% graphql %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'graphql'");
+    });
+
+    it('should not report valid graphql file-based syntax', async () => {
+      const sourceCode = `{% graphql result = 'path/to/query' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report graphql with named argument value using a filter', async () => {
+      const sourceCode = `{% graphql consumers = 'modules/core/events/consumers', name: name | fetch: "admin_liquid_partials" %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report graphql with named argument value using chained filters', async () => {
+      const sourceCode = `{% graphql consumers = 'modules/core/events/consumers', name: name | fetch: "admin_liquid_partials" | fetch: "results" %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report graphql with multiple named arguments where one uses a filter', async () => {
+      const sourceCode = `{% graphql consumers = 'modules/core/events/consumers', name: name | fetch: "admin_liquid_partials" | fetch: "results", limit: 10 %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('include tag', () => {
+    it('should report include without template name', async () => {
+      const sourceCode = `{% include %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'include'");
+    });
+
+    it('should not report valid include', async () => {
+      const sourceCode = `{% include 'partial' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('platformOS-specific tags', () => {
+    it('should not report valid log syntax', async () => {
+      const sourceCode = `{% log x %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid export syntax', async () => {
+      const sourceCode = `{% export data, namespace: "my_namespace" %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid redirect_to syntax', async () => {
+      const sourceCode = `{% redirect_to '/path' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid print syntax', async () => {
+      const sourceCode = `{% print x %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report valid yield syntax', async () => {
+      const sourceCode = `{% yield 'content' %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('inside {% liquid %} blocks', () => {
+    it('should report invalid render syntax inside liquid block', async () => {
+      const sourceCode = `{% liquid
+  render
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'render'");
+    });
+
+    it('should not report valid tags inside liquid block', async () => {
+      const sourceCode = `{% liquid
+  render 'partial'
+  function res = 'path/to/function'
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('should NOT fire on tags with dedicated sub-checks', () => {
+    it('should not fire InvalidTagSyntax on assign (has MultipleAssignValues)', async () => {
+      const sourceCode = `{% assign x abc %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not fire InvalidTagSyntax on echo (has InvalidEchoValue)', async () => {
+      const sourceCode = `{% echo = %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('should not report tags without expected markup', () => {
+    it('should not report else as invalid syntax', async () => {
+      const sourceCode = `{% if true %}a{% else %}b{% endif %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report break as invalid syntax', async () => {
+      const sourceCode = `{% for item in array %}{% break %}{% endfor %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+
+    it('should not report continue as invalid syntax', async () => {
+      const sourceCode = `{% for item in array %}{% continue %}{% endfor %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('tags with whitespace-trimming delimiters', () => {
+    it('should report invalid syntax with trimming delimiters', async () => {
+      const sourceCode = `{%- render -%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Invalid syntax for tag 'render'");
+    });
+
+    it('should not report valid syntax with trimming delimiters', async () => {
+      const sourceCode = `{%- render 'partial' -%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('docset syntax hint', () => {
+    it('should include syntax hint from docset when available', async () => {
+      const sourceCode = `{% render %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode, 'file.liquid', {
+        platformosDocset: {
+          async filters() {
+            return [];
+          },
+          async objects() {
+            return [];
+          },
+          async liquidDrops() {
+            return [];
+          },
+          async tags() {
+            return [{ name: 'render', syntax: "{% render 'partial' %}" }];
+          },
+          async graphQL() {
+            return null;
+          },
+        },
+      });
+      const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
+      expect(syntaxOffenses).toHaveLength(1);
+      expect(syntaxOffenses[0].message).toContain("Expected syntax: {% render 'partial' %}");
+    });
+  });
+});

package/src/checks/liquid-html-syntax-error/checks/InvalidTagSyntax.ts

@@ -0,0 +1,89 @@
+import { LiquidTag, NamedTags, TAGS_WITHOUT_MARKUP } from '@platformos/liquid-html-parser';
+import { Problem, SourceCodeType, TagEntry } from '../../..';
+
+/**
+ * Tags that use no markup at all — they are valid as `{% else %}`, `{% break %}`, etc.
+ * When their markup is a string, it's always '' (empty), so they should not trigger this check.
+ */
+const TAGS_WITH_NO_EXPECTED_MARKUP = new Set<string>(TAGS_WITHOUT_MARKUP);
+
+/**
+ * Tags that have dedicated sub-checks handling their string-markup cases with
+ * more specific error messages and autofixes. This check should NOT fire on these
+ * to avoid double-reporting or overriding their nuanced decisions.
+ *
+ * - assign → MultipleAssignValues, InvalidFilterName, InvalidPipeSyntax
+ * - echo → InvalidEchoValue, InvalidFilterName, InvalidPipeSyntax
+ * - if/elsif/unless → InvalidConditionalNode, InvalidConditionalNodeParenthesis
+ * - for/tablerow → InvalidLoopRange, InvalidLoopArguments
+ */
+const TAGS_WITH_DEDICATED_CHECKS = new Set<string>([
+  NamedTags.assign,
+  NamedTags.echo,
+  NamedTags.if,
+  NamedTags.elsif,
+  NamedTags.unless,
+  NamedTags.for,
+  NamedTags.tablerow,
+  NamedTags.when,
+]);
+
+/**
+ * All tag names in the NamedTags enum — these have specific grammar rules for their markup.
+ * If a NamedTag's markup is a string (instead of a parsed object), it means the strict grammar
+ * rule failed and the tag fell through to the base case.
+ */
+const NAMED_TAGS = new Set<string>(Object.values(NamedTags));
+
+/**
+ * Detects known tags whose markup couldn't be parsed by the grammar.
+ *
+ * When the tolerant parser encounters a known tag name (e.g. "render") but can't parse
+ * the markup with the strict grammar rule, it falls back to the base case and stores
+ * the markup as a raw string. This function detects that situation.
+ *
+ * This check only applies to tags that DON'T have more specific sub-checks.
+ * Tags like assign, echo, if, for etc. have dedicated checks that provide
+ * better error messages and autofixes for their specific syntax patterns.
+ *
+ * Examples:
+ *   {% graphql %}              → name: 'graphql', markup: '' (string — invalid)
+ *   {% render %}               → name: 'render', markup: '' (string — invalid)
+ *   {% function res 'path' %}  → name: 'function', markup: "res 'path'" (string — invalid)
+ */
+export function detectInvalidTagSyntax(
+  node: LiquidTag,
+  tags: TagEntry[] = [],
+): Problem<SourceCodeType.LiquidHtml> | undefined {
+  const tagName = node.name;
+
+  // Only check tags known to the grammar with specific markup rules
+  if (!NAMED_TAGS.has(tagName)) {
+    return;
+  }
+
+  // Tags without expected markup (else, break, continue, etc.) always have string markup
+  if (TAGS_WITH_NO_EXPECTED_MARKUP.has(tagName)) {
+    return;
+  }
+
+  // Skip tags that have dedicated sub-checks with more specific error handling
+  if (TAGS_WITH_DEDICATED_CHECKS.has(tagName)) {
+    return;
+  }
+
+  // If markup is not a string, it was parsed successfully — no error
+  if (typeof node.markup !== 'string') {
+    return;
+  }
+
+  // Build a helpful hint from the docset if available
+  const tagEntry = tags.find((t) => t.name === tagName);
+  const syntaxHint = tagEntry?.syntax ? ` Expected syntax: ${tagEntry.syntax}` : '';
+
+  return {
+    message: `Invalid syntax for tag '${tagName}'${syntaxHint}`,
+    startIndex: node.position.start,
+    endIndex: node.position.end,
+  };
+}

package/src/checks/liquid-html-syntax-error/checks/UnknownTag.spec.ts

@@ -0,0 +1,293 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck, highlightedOffenses } from '../../../test';
+import { LiquidHTMLSyntaxError } from '../index';
+
+describe('Module: UnknownTag', () => {
+  describe('standalone unknown tags', () => {
+    it('should report an unknown inline tag', async () => {
+      const sourceCode = `{% dsjkds %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(1);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'dsjkds'");
+    });
+
+    it('should report an unknown tag with markup', async () => {
+      const sourceCode = `{% foobar some_arg %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(1);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'foobar'");
+    });
+
+    it('should highlight the entire unknown tag', async () => {
+      const sourceCode = `Hello {% unknown_tag %} world`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      const highlights = highlightedOffenses(sourceCode, unknownTagOffenses);
+      expect(highlights).toContain('{% unknown_tag %}');
+    });
+
+    it('should report multiple unknown tags', async () => {
+      const sourceCode = `{% foo %} {% bar %} {% baz %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(3);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'foo'");
+      expect(unknownTagOffenses[1].message).toBe("Unknown tag 'bar'");
+      expect(unknownTagOffenses[2].message).toBe("Unknown tag 'baz'");
+    });
+  });
+
+  describe('unknown tags inside {% liquid %} blocks', () => {
+    it('should report an unknown tag inside a liquid block', async () => {
+      const sourceCode = `{% liquid
+  assign x = "abc"
+  dasjkdjkas
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(1);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'dasjkdjkas'");
+    });
+
+    it('should report multiple unknown tags inside a liquid block', async () => {
+      const sourceCode = `{% liquid
+  assign x = "abc"
+  foo
+  echo x
+  bar
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(2);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'foo'");
+      expect(unknownTagOffenses[1].message).toBe("Unknown tag 'bar'");
+    });
+
+    it('should not report valid tags inside a liquid block', async () => {
+      const sourceCode = `{% liquid
+  assign x = "hello"
+  echo x
+  assign y = x | upcase
+%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('should NOT report known tags', () => {
+    it('should not report standard liquid tags', async () => {
+      const validTags = [
+        `{% assign x = "hello" %}`,
+        `{% echo "hello" %}`,
+        `{% increment counter %}`,
+        `{% decrement counter %}`,
+        `{% cycle "a", "b", "c" %}`,
+        `{% break %}`,
+        `{% continue %}`,
+        `{% layout 'application' %}`,
+        `{% render 'partial' %}`,
+        `{% include 'partial' %}`,
+      ];
+
+      for (const sourceCode of validTags) {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+        expect(
+          unknownTagOffenses,
+          `Expected no unknown tag offense for: ${sourceCode}`,
+        ).toHaveLength(0);
+      }
+    });
+
+    it('should not report block tags', async () => {
+      const validBlocks = [
+        `{% if true %}hello{% endif %}`,
+        `{% unless false %}hello{% endunless %}`,
+        `{% for item in array %}{{ item }}{% endfor %}`,
+        `{% capture var %}hello{% endcapture %}`,
+        `{% case x %}{% when 1 %}one{% endcase %}`,
+      ];
+
+      for (const sourceCode of validBlocks) {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+        expect(
+          unknownTagOffenses,
+          `Expected no unknown tag offense for: ${sourceCode}`,
+        ).toHaveLength(0);
+      }
+    });
+
+    it('should not report platformOS-specific tags', async () => {
+      const validTags = [
+        `{% log x %}`,
+        `{% print x %}`,
+        `{% yield 'content' %}`,
+        `{% redirect_to '/path' %}`,
+        `{% export x, namespace: "ns" %}`,
+        `{% return x %}`,
+        `{% response_status 200 %}`,
+        `{% response_headers 'Content-Type': 'text/html' %}`,
+        `{% sign_in user %}`,
+        `{% spam_protection "recaptcha_v2" %}`,
+        `{% theme_render_rc 'rc' %}`,
+      ];
+
+      for (const sourceCode of validTags) {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+        expect(
+          unknownTagOffenses,
+          `Expected no unknown tag offense for: ${sourceCode}`,
+        ).toHaveLength(0);
+      }
+    });
+
+    it('should not report platformOS block tags', async () => {
+      const validBlocks = [
+        `{% cache 'key' %}hello{% endcache %}`,
+        `{% parse_json var %}{}{% endparse_json %}`,
+        `{% try %}hello{% catch err %}{{ err }}{% endtry %}`,
+        `{% content_for 'pagetitle' %}<title>Hello</title>{% endcontent_for %}`,
+        `{% background source_name: 'my_task' %}echo "hello"{% endbackground %}`,
+      ];
+
+      for (const sourceCode of validBlocks) {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+        expect(
+          unknownTagOffenses,
+          `Expected no unknown tag offense for: ${sourceCode}`,
+        ).toHaveLength(0);
+      }
+    });
+
+    it('should not report raw tags', async () => {
+      const sourceCode = `{% raw %}{{ not liquid }}{% endraw %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+
+    it('should not report comment tags', async () => {
+      const sourceCode = `{% comment %}this is a comment{% endcomment %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+
+    it('should not report inline comment tags', async () => {
+      const sourceCode = `{% # this is an inline comment %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+
+    it('should not report else/elsif tags', async () => {
+      const sourceCode = `{% if true %}a{% elsif false %}b{% else %}c{% endif %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('tags known via docset', () => {
+    it('should not report tags from the docset', async () => {
+      const sourceCode = `{% custom_docset_tag %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode, 'file.liquid', {
+        platformosDocset: {
+          async filters() {
+            return [];
+          },
+          async objects() {
+            return [];
+          },
+          async liquidDrops() {
+            return [];
+          },
+          async tags() {
+            return [{ name: 'custom_docset_tag' }];
+          },
+          async graphQL() {
+            return null;
+          },
+        },
+      });
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(0);
+    });
+  });
+
+  describe('mixed valid and unknown tags', () => {
+    it('should only report the unknown tags in mixed content', async () => {
+      const sourceCode = `
+        {% assign x = "hello" %}
+        {% unknown_one %}
+        {% if true %}
+          {% bogus_tag %}
+        {% endif %}
+      `;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(2);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'unknown_one'");
+      expect(unknownTagOffenses[1].message).toBe("Unknown tag 'bogus_tag'");
+    });
+  });
+
+  describe('real-world file patterns', () => {
+    it('should catch unknown tags in a real platformOS page with liquid block and standalone tag', async () => {
+      const sourceCode = `---
+method: post
+slug: users
+layout: 'modules/community/blank'
+---
+
+{% liquid
+  function current_profile = 'modules/user/helpers/current_profile'
+
+  include 'modules/user/helpers/can_do_or_redirect', requester: current_profile, do: 'users.register', redirect_url: "/"
+
+  function object = 'modules/user/commands/user/create', first_name: params.first_name
+
+  dsk
+
+  if object.valid
+    function _ = 'modules/user/commands/session/create', user_id: object.id
+    include 'modules/core/helpers/redirect_to', url: '/onboarding'
+  else
+    assign values = object | default: null
+    render 'modules/user/users/new', errors: object.errors, values: values
+  endif
+%}
+
+{% jakdsajk %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(2);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'dsk'");
+      expect(unknownTagOffenses[1].message).toBe("Unknown tag 'jakdsajk'");
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should report unknown tags with underscores', async () => {
+      const sourceCode = `{% my_custom_tag %}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(1);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'my_custom_tag'");
+    });
+
+    it('should report unknown tags with whitespace-trimming delimiters', async () => {
+      const sourceCode = `{%- unknown_tag -%}`;
+      const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+      const unknownTagOffenses = offenses.filter((o) => o.message.includes('Unknown tag'));
+      expect(unknownTagOffenses).toHaveLength(1);
+      expect(unknownTagOffenses[0].message).toBe("Unknown tag 'unknown_tag'");
+    });
+  });
+});

package/src/checks/liquid-html-syntax-error/checks/UnknownTag.ts

@@ -0,0 +1,43 @@
+import {
+  LiquidTag,
+  NamedTags,
+  TAGS_WITHOUT_MARKUP,
+  BLOCKS,
+  RAW_TAGS,
+} from '@platformos/liquid-html-parser';
+import { Problem, SourceCodeType, TagEntry } from '../../..';
+
+/**
+ * All tag names known to the grammar (NamedTags enum + TAGS_WITHOUT_MARKUP + BLOCKS + RAW_TAGS).
+ * These are tags that the parser recognizes with specific grammar rules.
+ */
+const GRAMMAR_KNOWN_TAGS = new Set<string>([
+  ...Object.values(NamedTags),
+  ...TAGS_WITHOUT_MARKUP,
+  ...BLOCKS,
+  ...RAW_TAGS,
+  '#', // inline comment: {% # this is a comment %}
+]);
+
+export function detectUnknownTag(
+  node: LiquidTag,
+  tags: TagEntry[] = [],
+): Problem<SourceCodeType.LiquidHtml> | undefined {
+  const tagName = node.name;
+
+  // If the tag is known to the grammar, it's not unknown
+  if (GRAMMAR_KNOWN_TAGS.has(tagName)) {
+    return;
+  }
+
+  // If the tag is known to the docset, it's not unknown
+  if (tags.some((tag) => tag.name === tagName)) {
+    return;
+  }
+
+  return {
+    message: `Unknown tag '${tagName}'`,
+    startIndex: node.position.start,
+    endIndex: node.position.end,
+  };
+}