@platformos/platformos-check-common 0.0.18 → 0.0.20

package/dist/types.d.ts

@@ -231,10 +231,20 @@ export type Translations = {
  *   target: 'file:///app/views/partials/child.liquid'
  * }
  */
+/**
+ * The semantic Liquid construct that created a {@link Reference} edge.
+ *
+ * Optional/additive: older producers may omit it. Lets consumers distinguish a
+ * `{% render %}` edge from an `{% include %}` / `{% function %}` / `{% graphql %}`
+ * / `{% background %}` / asset / layout-association edge without re-parsing.
+ */
+export type ReferenceKind = 'render' | 'include' | 'function' | 'background' | 'graphql' | 'asset' | 'layout';
 export type Reference = {
     source: Location;
     target: Location;
     type: 'direct' | 'indirect';
+    /** Which Liquid construct produced this edge. Optional for backwards compatibility. */
+    kind?: ReferenceKind;
 };
 export type Range = [start: number, end: number];
 export type Location = {

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uEAAkG;AAwEzE,oGAxEa,8BAAmB,OAwEb;AAnD5C,gDAA8B;AAC9B,8DAA4C;AAC5C,iEAA+C;AAExC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAsB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC;AAA/E,QAAA,YAAY,gBAAmE;AACrF,MAAM,WAAW,GAAG,CAAC,IAAc,EAAqB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;AAA5E,QAAA,WAAW,eAAiE;AAClF,MAAM,cAAc,GAAG,CAAC,IAAc,EAAwB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,CAAC;AAArF,QAAA,cAAc,kBAAuE;AAC3F,MAAM,WAAW,GAAG,CAAC,IAAc,EAAqB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;AAA5E,QAAA,WAAW,eAAiE;AAClF,MAAM,aAAa,GAAG,CAAC,IAAc,EAAuB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC;AAAlF,QAAA,aAAa,iBAAqE;AAkB/F,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,+BAAa,CAAA;IACb,2CAAyB,CAAA;IACzB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;AACf,CAAC,EALW,cAAc,8BAAd,cAAc,QAKzB;AAkfD,gEAAgE;AAChE,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,yCAAS,CAAA;IACT,6CAAW,CAAA;IACX,uCAAQ,CAAA;AACV,CAAC,EAJW,QAAQ,wBAAR,QAAQ,QAInB;AAED,+CAA+C;AAC/C,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,2BAAW,CAAA;IACX,2CAA2B,CAAA;AAC7B,CAAC,EAHW,YAAY,4BAAZ,YAAY,QAGvB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uEAAkG;AAwEzE,oGAxEa,8BAAmB,OAwEb;AAnD5C,gDAA8B;AAC9B,8DAA4C;AAC5C,iEAA+C;AAExC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAsB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC;AAA/E,QAAA,YAAY,gBAAmE;AACrF,MAAM,WAAW,GAAG,CAAC,IAAc,EAAqB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;AAA5E,QAAA,WAAW,eAAiE;AAClF,MAAM,cAAc,GAAG,CAAC,IAAc,EAAwB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,CAAC;AAArF,QAAA,cAAc,kBAAuE;AAC3F,MAAM,WAAW,GAAG,CAAC,IAAc,EAAqB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;AAA5E,QAAA,WAAW,eAAiE;AAClF,MAAM,aAAa,GAAG,CAAC,IAAc,EAAuB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC;AAAlF,QAAA,aAAa,iBAAqE;AAkB/F,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,+BAAa,CAAA;IACb,2CAAyB,CAAA;IACzB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;AACf,CAAC,EALW,cAAc,8BAAd,cAAc,QAKzB;AAqgBD,gEAAgE;AAChE,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,yCAAS,CAAA;IACT,6CAAW,CAAA;IACX,uCAAQ,CAAA;AACV,CAAC,EAJW,QAAQ,wBAAR,QAAQ,QAInB;AAED,+CAA+C;AAC/C,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,2BAAW,CAAA;IACX,2CAA2B,CAAA;AAC7B,CAAC,EAHW,YAAY,4BAAZ,YAAY,QAGvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformos/platformos-check-common",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "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.16",
+    "@platformos/liquid-html-parser": "0.0.18",
     "graphql": "^16.12.0",
     "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",

package/src/checks/index.ts

@@ -17,6 +17,7 @@ import { MissingAsset } from './missing-asset';
 import { MissingPartial } from './missing-partial';
 import { OrphanedPartial } from './orphaned-partial';
 import { ParserBlockingScript } from './parser-blocking-script';
+import { ReservedVariableName } from './reserved-variable-name';
 import { TranslationKeyExists } from './translation-key-exists';
 import { UnclosedHTMLElement } from './unclosed-html-element';
 import { UndefinedObject } from './undefined-object';
@@ -41,6 +42,7 @@ import { NestedGraphQLQuery } from './nested-graphql-query';
 import { MissingPage } from './missing-page';
 import { ValidFrontmatter } from './valid-frontmatter';
 import { JsonLiteralQuoteStyle } from './json-literal-quote-style';
+import { MissingContentForLayout } from './missing-content-for-layout';
 
 export const allChecks: (
   | LiquidCheckDefinition
@@ -60,6 +62,7 @@ export const allChecks: (
   MissingPartial,
   OrphanedPartial,
   ParserBlockingScript,
+  ReservedVariableName,
   TranslationKeyExists,
   UnclosedHTMLElement,
   UndefinedObject,
@@ -83,6 +86,7 @@ export const allChecks: (
   MissingPage,
   ValidFrontmatter,
   JsonLiteralQuoteStyle,
+  MissingContentForLayout,
 ];
 
 /**

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

@@ -92,6 +92,55 @@ describe('detectInvalidAssignSyntax', () => {
     });
   });
 
+  describe('trailing garbage after RHS / filters (fallback)', () => {
+    // These cases have a valid `target = value` skeleton and a valid filter chain,
+    // but extra non-parseable characters trail the filters. The tolerant parser
+    // swallows the entire body as string markup, and none of the other sub-checks
+    // (MultipleAssignValues, InvalidFilterName, InvalidPipeSyntax) detects the
+    // problem — so the fallback re-parses in strict mode and surfaces it.
+    const fallbackCases: Array<[string, string]> = [
+      [
+        'stray `}` after filter array argument',
+        `{% assign name = arr | default: [ "hi", k, v] } %}`,
+      ],
+      ['trailing bare word after filter arg', `{% assign x = y | default: "z" trailing %}`],
+    ];
+
+    for (const [label, sourceCode] of fallbackCases) {
+      it(`should report: ${label} — ${sourceCode}`, async () => {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        const syntaxOffenses = offenses.filter((o) =>
+          o.message.includes("Invalid syntax for tag 'assign'"),
+        );
+        expect(syntaxOffenses).toHaveLength(1);
+      });
+    }
+
+    // These cases are already flagged by other sub-checks with different messages;
+    // the fallback must NOT also fire on them (no double-reporting).
+    const alreadyCoveredCases: Array<[string, string]> = [
+      [
+        'stray `}` after unary filter (InvalidFilterName catches it)',
+        `{% assign x = y | upcase } %}`,
+      ],
+      [
+        'stray `}` after RHS with no filter (MultipleAssignValues catches it)',
+        `{% assign x = "v" } %}`,
+      ],
+    ];
+
+    for (const [label, sourceCode] of alreadyCoveredCases) {
+      it(`should NOT double-report: ${label} — ${sourceCode}`, async () => {
+        const offenses = await runLiquidCheck(LiquidHTMLSyntaxError, sourceCode);
+        expect(offenses.length).toBeGreaterThan(0);
+        const fallbackOffenses = offenses.filter((o) =>
+          o.message.includes("Invalid syntax for tag 'assign'"),
+        );
+        expect(fallbackOffenses).toHaveLength(0);
+      });
+    }
+  });
+
   describe('valid syntax — should NOT report', () => {
     const validCases: Array<[string, string]> = [
       // primitives

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

@@ -1,6 +1,8 @@
-import { LiquidTag } from '@platformos/liquid-html-parser';
+import { LiquidTag, toLiquidAST } from '@platformos/liquid-html-parser';
 import { Problem, SourceCodeType } from '../../..';
 
+const INVALID_ASSIGN_MESSAGE = `Invalid syntax for tag 'assign'. Expected syntax: {% assign <var> = <value> %}`;
+
 /**
  * Detects structurally-invalid `assign` tags that neither `MultipleAssignValues` nor
  * `InvalidPipeSyntax`/`InvalidFilterName` catch:
@@ -38,12 +40,44 @@ export function detectInvalidAssignSyntax(
   if (!isStructurallyBroken) return;
 
   return {
-    message: `Invalid syntax for tag 'assign'. Expected syntax: {% assign <var> = <value> %}`,
+    message: INVALID_ASSIGN_MESSAGE,
     startIndex: node.position.start,
     endIndex: node.position.end,
   };
 }
 
+/**
+ * Fallback for assign tags where the tolerant parser landed in string markup even
+ * though the `target = value` skeleton looks fine — meaning the value or filter
+ * chain has parse-breaking characters (e.g. a stray `}` before `%}`) that no other
+ * dedicated sub-check (MultipleAssignValues, InvalidFilterName, InvalidPipeSyntax)
+ * surfaced. Re-parses the tag source in strict mode and reports on failure.
+ *
+ * Must run ONLY when no other sub-check already reported on this tag, otherwise
+ * it double-flags the same problem. The orchestrator enforces that gate.
+ */
+export function detectInvalidAssignFallback(
+  node: LiquidTag,
+): Problem<SourceCodeType.LiquidHtml> | undefined {
+  if (node.name !== 'assign' || typeof node.markup !== 'string') return;
+
+  // Digit-starting targets (e.g. `23_hours_ago`) are accepted by the platformOS
+  // runtime but rejected by the Ohm grammar's `variableSegment` rule. Skipping
+  // them here mirrors the intentional tolerance in isValidAssignTarget above.
+  if (/^\s*\d/.test(node.markup)) return;
+
+  const tagSource = node.source.slice(node.position.start, node.position.end);
+  try {
+    toLiquidAST(tagSource, { mode: 'strict', allowUnclosedDocumentNode: true });
+  } catch {
+    return {
+      message: INVALID_ASSIGN_MESSAGE,
+      startIndex: node.position.start,
+      endIndex: node.position.end,
+    };
+  }
+}
+
 /**
  * Rejects an LHS that is obviously not an assign target.
  *

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

@@ -194,6 +194,29 @@ describe('Module: InvalidTagSyntax', () => {
       const syntaxOffenses = offenses.filter((o) => o.message.includes('Invalid syntax for tag'));
       expect(syntaxOffenses).toHaveLength(0);
     });
+
+    it('should not report form without arguments', async () => {
+      const sourceCode = `{% form %}content{% endform %}`;
+      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 form with hyphenated keys and missing commas between attributes', async () => {
+      // The runtime scans `[\w-]+: value` pairs out of the markup, so commas
+      // between attributes are optional and keys may contain hyphens.
+      const sourceCode = `{% form html-class: "foo-form", html-submitonce: "true" html-foo-bar: "true" %}content{% endform %}`;
+      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 form with a positional model name', async () => {
+      const sourceCode = `{% form form, method: 'delete' %}content{% endform %}`;
+      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', () => {

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

@@ -1,7 +1,10 @@
 import { Severity, SourceCodeType, LiquidCheckDefinition, Problem } from '../../types';
 import { getOffset, isError } from '../../utils';
 import { detectMultipleAssignValues } from './checks/MultipleAssignValues';
-import { detectInvalidAssignSyntax } from './checks/InvalidAssignSyntax';
+import {
+  detectInvalidAssignSyntax,
+  detectInvalidAssignFallback,
+} from './checks/InvalidAssignSyntax';
 import { detectInvalidBooleanExpressions } from './checks/InvalidBooleanExpressions';
 import { detectInvalidEchoValue } from './checks/InvalidEchoValue';
 import { detectInvalidConditionalNode } from './checks/InvalidConditionalNode';
@@ -123,6 +126,14 @@ export const LiquidHTMLSyntaxError: LiquidCheckDefinition = {
           if (pipeProblems.length > 0) {
             pipeProblems.forEach((pipeProblem) => context.report(pipeProblem));
           }
+
+          // Last-chance check for assign tags whose tolerant parse fell back to
+          // string markup (e.g. stray `}` before `%}`). Gated on "nothing else
+          // reported on this tag" to avoid double-flagging.
+          if (problems.length + filterProblems.length + pipeProblems.length === 0) {
+            const fallback = detectInvalidAssignFallback(node);
+            if (fallback) context.report(fallback);
+          }
         },
 
         async LiquidBranch(node, ancestors) {

package/src/checks/missing-content-for-layout/index.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { Severity } from '../../types';
+import { applySuggestions, runLiquidCheck } from '../../test';
+import { MissingContentForLayout } from './index';
+
+const LAYOUT = 'app/views/layouts/application.liquid';
+const PAGE = 'app/views/pages/index.liquid';
+const PARTIAL = 'app/views/partials/card.liquid';
+
+describe('Module: MissingContentForLayout', () => {
+  it('flags a layout that never references content_for_layout', async () => {
+    const sourceCode = '<html><body><header>Site</header></body></html>';
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].check).toEqual('MissingContentForLayout');
+    expect(offenses[0].severity).toEqual(Severity.ERROR);
+  });
+
+  it('does not flag a layout that outputs {{ content_for_layout }}', async () => {
+    const sourceCode = '<html><body>{{ content_for_layout }}</body></html>';
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it('detects content_for_layout referenced inside a {% liquid %} block via echo', async () => {
+    const sourceCode = [
+      '<html><body>',
+      '{% liquid',
+      '  echo content_for_layout',
+      '%}',
+      '</body></html>',
+    ].join('\n');
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it('does not flag non-layout files (pages, partials)', async () => {
+    const sourceCode = '<html><body><header>Site</header></body></html>';
+
+    const pageOffenses = await runLiquidCheck(MissingContentForLayout, sourceCode, PAGE);
+    const partialOffenses = await runLiquidCheck(MissingContentForLayout, sourceCode, PARTIAL);
+
+    expect(pageOffenses).toEqual([]);
+    expect(partialOffenses).toEqual([]);
+  });
+
+  it('suggests inserting content_for_layout before the closing </body> tag', async () => {
+    const sourceCode = '<html><body><header>Site</header></body></html>';
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+    const suggestions = applySuggestions({ [LAYOUT]: sourceCode }, offenses[0]);
+
+    expect(suggestions).toEqual([
+      '<html><body><header>Site</header>{{ content_for_layout }}\n</body></html>',
+    ]);
+  });
+
+  it('suggests inserting before </body> even when <body> has attributes', async () => {
+    const sourceCode =
+      '<html><body class="theme" data-env="prod"><header>Site</header></body></html>';
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+    const suggestions = applySuggestions({ [LAYOUT]: sourceCode }, offenses[0]);
+
+    expect(suggestions).toEqual([
+      '<html><body class="theme" data-env="prod"><header>Site</header>{{ content_for_layout }}\n</body></html>',
+    ]);
+  });
+
+  it('suggests appending content_for_layout when there is no </body> tag', async () => {
+    const sourceCode = '<header>Site</header>';
+
+    const offenses = await runLiquidCheck(MissingContentForLayout, sourceCode, LAYOUT);
+    const suggestions = applySuggestions({ [LAYOUT]: sourceCode }, offenses[0]);
+
+    expect(suggestions).toEqual(['<header>Site</header>\n{{ content_for_layout }}\n']);
+  });
+});

package/src/checks/missing-content-for-layout/index.ts

@@ -0,0 +1,94 @@
+import { NodeTypes } from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { isLayout } from '../../path';
+
+/**
+ * Ensures every layout outputs `{{ content_for_layout }}`.
+ *
+ * `content_for_layout` is where platformOS injects the rendered page body. A
+ * layout that never references it renders its own chrome but drops the page
+ * entirely — a correctness defect, not a style issue. (Named slots use
+ * `{% yield 'name' %}` separately and do not substitute for it.)
+ *
+ * The check is scoped to layout files via `getFileType` (re-exported as
+ * `isLayout`) so it never fires on pages or partials. Both detection and the
+ * suggested fix are AST-based: any reference to the `content_for_layout`
+ * variable clears the check (whether emitted with `{{ … }}`, `{% echo … %}`,
+ * or inside a `{% liquid %}` block), and the fix is inserted before the
+ * `<body>` element's closing tag — using the parsed element's position, never
+ * a text scan of the raw source.
+ */
+
+const CONTENT_FOR_LAYOUT = 'content_for_layout';
+
+export const MissingContentForLayout: LiquidCheckDefinition = {
+  meta: {
+    code: 'MissingContentForLayout',
+    name: 'Missing Content For Layout',
+    docs: {
+      description:
+        'Ensures every layout references `content_for_layout` — without it the rendered page body is never output.',
+      recommended: true,
+      url: undefined,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    // Scope to layout files only; pages/partials/etc. must not be flagged.
+    if (!isLayout(context.file.uri)) return {};
+
+    let referencesContentForLayout = false;
+    // Start index of the `</body>` closing tag, captured from the AST so the
+    // fix never has to scan the raw source for it.
+    let bodyCloseIndex: number | undefined;
+
+    return {
+      async VariableLookup(node) {
+        if (node.name === CONTENT_FOR_LAYOUT) {
+          referencesContentForLayout = true;
+        }
+      },
+
+      async HtmlElement(node) {
+        if (bodyCloseIndex !== undefined) return; // first <body> wins
+        const tagName = node.name[0];
+        if (tagName?.type === NodeTypes.TextNode && tagName.value.toLowerCase() === 'body') {
+          bodyCloseIndex = node.blockEndPosition.start;
+        }
+      },
+
+      async onCodePathEnd(file) {
+        if (referencesContentForLayout) return;
+
+        // Insert before `</body>` when the layout has one (keeps it inside the
+        // body); otherwise append at the end of the document. Both positions
+        // come from the AST.
+        const hasBody = bodyCloseIndex !== undefined;
+        const insertAt = hasBody ? bodyCloseIndex! : file.ast.position.end;
+        const insertText = hasBody ? '{{ content_for_layout }}\n' : '\n{{ content_for_layout }}\n';
+        const suggestMessage = hasBody
+          ? 'Insert `{{ content_for_layout }}` before the closing </body> tag'
+          : 'Insert `{{ content_for_layout }}` at the end of the layout';
+
+        context.report({
+          message:
+            "Layout is missing `{{ content_for_layout }}`. Every layout must output it exactly once — it renders the page body. (Named slots use `{% yield 'name' %}` separately and do not replace it.)",
+          startIndex: 0,
+          endIndex: 0,
+          suggest: [
+            {
+              message: suggestMessage,
+              fix: (corrector) => {
+                corrector.insert(insertAt, insertText);
+              },
+            },
+          ],
+        });
+      },
+    };
+  },
+};

package/src/checks/missing-page/index.spec.ts

@@ -658,6 +658,100 @@ describe('Module: MissingPage', () => {
     });
   });
 
+  describe('rss format link regression (/blog/rss.rss)', () => {
+    it('does not report when the rss format page exists', async () => {
+      const sourceCode = '<a href="/blog/rss.rss">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'app/views/pages/home.html.liquid',
+        {},
+        {
+          'app/views/pages/blog/rss.rss.liquid': '<rss></rss>',
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([]);
+    });
+
+    it('does not report when the page declares format rss in frontmatter', async () => {
+      const sourceCode = '<a href="/blog/rss.rss">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'app/views/pages/home.html.liquid',
+        {},
+        {
+          'app/views/pages/blog/rss.liquid': '---\nformat: rss\n---\n<rss></rss>',
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([]);
+    });
+
+    it('reports when no page matches the rss URL', async () => {
+      const sourceCode = '<a href="/blog/rss.rss">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'app/views/pages/home.html.liquid',
+        {},
+        {
+          'app/views/pages/blog/index.html.liquid': '<h1>Blog</h1>',
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([
+        "No page found for route '/blog/rss.rss' (GET)",
+      ]);
+    });
+
+    it('reports when only an html page exists at the rss URL path', async () => {
+      const sourceCode = '<a href="/blog/rss.rss">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'app/views/pages/home.html.liquid',
+        {},
+        {
+          'app/views/pages/blog/rss.html.liquid': '<h1>Not a feed</h1>',
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([
+        "No page found for route '/blog/rss.rss' (GET)",
+      ]);
+    });
+
+    it('reports when the module page serves the feed as xml (the platformos-blog scenario)', async () => {
+      const sourceCode = '<a href="/blog/rss.rss">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'modules/blog/public/views/partials/layout/footer.liquid',
+        {},
+        {
+          'modules/blog/public/views/pages/blog/rss.liquid':
+            "---\nslug: 'blog/rss'\nformat: xml\n---\n<rss></rss>",
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([
+        "No page found for route '/blog/rss.rss' (GET)",
+      ]);
+    });
+
+    it('does not report the xml link when the module page serves the feed as xml', async () => {
+      const sourceCode = '<a href="/blog/rss.xml">RSS</a>';
+      const offenses = await runLiquidCheck(
+        MissingPage,
+        sourceCode,
+        'modules/blog/public/views/partials/layout/footer.liquid',
+        {},
+        {
+          'modules/blog/public/views/pages/blog/rss.liquid':
+            "---\nslug: 'blog/rss'\nformat: xml\n---\n<rss></rss>",
+        },
+      );
+      expect(offenses.map((o) => o.message)).toEqual([]);
+    });
+  });
+
   describe('assign variable scoping per position', () => {
     it('resolves each link against the variable value at that point in the document', async () => {
       const sourceCode =

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

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { highlightedOffenses, runLiquidCheck } from '../../test';
+import { ReservedVariableName } from './index';
+
+const message = (name: string) =>
+  `'${name}' is a reserved Liquid literal and cannot be used as a variable name — reading '${name}' always returns the literal, never the assigned value`;
+
+async function expectReservedOffense(sourceCode: string, name: string, highlight = name) {
+  const offenses = await runLiquidCheck(ReservedVariableName, sourceCode);
+
+  expect(offenses.map((offense) => offense.message)).toEqual([message(name)]);
+  expect(highlightedOffenses(sourceCode, offenses)).toEqual([highlight]);
+}
+
+describe('Module: ReservedVariableName', () => {
+  it('reports assigning to empty even when the name is referenced later', async () => {
+    const sourceCode = [
+      '{% liquid',
+      "  assign empty = '{}' | parse_json",
+      "  function invalid = 'modules/blog/commands/blog_instances/build', object: empty",
+      '%}',
+    ].join('\n');
+
+    await expectReservedOffense(sourceCode, 'empty');
+  });
+
+  it('reports every reserved literal as an assign target', async () => {
+    const sourceCode = [
+      '{% liquid',
+      "  assign true = 'a'",
+      "  assign false = 'a'",
+      "  assign nil = 'a'",
+      "  assign null = 'a'",
+      "  assign empty = 'a'",
+      "  assign blank = 'a'",
+      '%}',
+    ].join('\n');
+
+    const offenses = await runLiquidCheck(ReservedVariableName, sourceCode);
+
+    expect(offenses.map((offense) => offense.message)).toEqual([
+      message('true'),
+      message('false'),
+      message('nil'),
+      message('null'),
+      message('empty'),
+      message('blank'),
+    ]);
+    expect(highlightedOffenses(sourceCode, offenses)).toEqual([
+      'true',
+      'false',
+      'nil',
+      'null',
+      'empty',
+      'blank',
+    ]);
+  });
+
+  it('reports a reserved name as a capture target', async () => {
+    await expectReservedOffense('{% capture blank %}hello{% endcapture %}', 'blank');
+  });
+
+  it('reports a reserved name as a function result target', async () => {
+    await expectReservedOffense("{% function null = 'lib/queries/find', id: 1 %}", 'null');
+  });
+
+  it('reports a reserved name as a graphql result target', async () => {
+    await expectReservedOffense("{% graphql empty = 'my/query' %}", 'empty');
+  });
+
+  it('reports a reserved name as an inline graphql result target', async () => {
+    await expectReservedOffense(
+      '{% graphql blank %}query { records { id } }{% endgraphql %}',
+      'blank',
+    );
+  });
+
+  it('reports a reserved name as a parse_json target', async () => {
+    await expectReservedOffense('{% parse_json empty %}{ "a": 1 }{% endparse_json %}', 'empty');
+  });
+
+  it('reports a reserved name as a hash_assign target', async () => {
+    await expectReservedOffense(
+      "{% hash_assign empty['key'] = 'value' %}",
+      'empty',
+      "empty['key']",
+    );
+  });
+
+  it('reports a reserved name as a for loop variable', async () => {
+    await expectReservedOffense('{% for empty in items %}{{ empty }}{% endfor %}', 'empty');
+  });
+
+  it('reports a reserved name as a background job id', async () => {
+    await expectReservedOffense("{% background nil = 'lib/jobs/cleanup' %}", 'nil');
+  });
+
+  it('reports a reserved name as a catch error variable', async () => {
+    await expectReservedOffense('{% try %}{% catch empty %}{{ empty }}{% endtry %}', 'empty');
+  });
+
+  it('reports a reserved name as an increment target', async () => {
+    await expectReservedOffense('{% increment empty %}', 'empty');
+  });
+
+  it('does not report non-reserved variable names', async () => {
+    const sourceCode = [
+      '{% liquid',
+      "  assign my_empty = '{}' | parse_json",
+      "  function result = 'lib/queries/find', object: my_empty",
+      '  echo result',
+      '%}',
+    ].join('\n');
+
+    const offenses = await runLiquidCheck(ReservedVariableName, sourceCode);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it('does not report reading reserved literals', async () => {
+    const sourceCode = [
+      '{% liquid',
+      '  if items == empty or name == blank',
+      '    echo "nothing"',
+      '  endif',
+      '  assign flag = true',
+      '%}',
+    ].join('\n');
+
+    const offenses = await runLiquidCheck(ReservedVariableName, sourceCode);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it('does not report names that merely contain a reserved word', async () => {
+    const sourceCode = "{% assign empty_result = '{}' | parse_json %}{{ empty_result }}";
+
+    const offenses = await runLiquidCheck(ReservedVariableName, sourceCode);
+
+    expect(offenses).toEqual([]);
+  });
+});