@platformos/platformos-check-common 0.0.19 → 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.19",
+  "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.17",
+    "@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/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/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([]);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { LiquidVariableLookup, NamedTags, NodeTypes } from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { RESERVED_VARIABLE_NAMES } from '../utils';
+
+export const ReservedVariableName: LiquidCheckDefinition = {
+  meta: {
+    code: 'ReservedVariableName',
+    name: 'Reserved variable name',
+    docs: {
+      description:
+        "Disallows using reserved Liquid literals ('true', 'false', 'nil', 'null', 'empty', 'blank') as variable names. Reading such a name always returns the built-in literal, never the assigned value.",
+      recommended: true,
+      url: undefined,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const report = (name: string, startIndex: number, endIndex: number) => {
+      context.report({
+        message: `'${name}' is a reserved Liquid literal and cannot be used as a variable name — reading '${name}' always returns the literal, never the assigned value`,
+        startIndex,
+        endIndex,
+      });
+    };
+
+    // Targets whose name is a plain string always sit at the start of their markup node
+    const checkStringTarget = (name: string, markup: { position: { start: number } }) => {
+      if (RESERVED_VARIABLE_NAMES.has(name)) {
+        report(name, markup.position.start, markup.position.start + name.length);
+      }
+    };
+
+    const checkLookupTarget = (lookup: LiquidVariableLookup | null) => {
+      if (lookup?.name && RESERVED_VARIABLE_NAMES.has(lookup.name)) {
+        report(lookup.name, lookup.position.start, lookup.position.end);
+      }
+    };
+
+    return {
+      async LiquidTag(node) {
+        if (typeof node.markup === 'string') return;
+
+        switch (node.name) {
+          case NamedTags.assign:
+            checkStringTarget(node.markup.name, node.markup);
+            break;
+          case NamedTags.capture:
+          case NamedTags.parse_json:
+          case NamedTags.increment:
+          case NamedTags.decrement:
+            checkLookupTarget(node.markup);
+            break;
+          case NamedTags.function:
+            checkLookupTarget(node.markup.name);
+            break;
+          case NamedTags.graphql:
+            checkStringTarget(node.markup.name, node.markup);
+            break;
+          case NamedTags.hash_assign:
+            checkLookupTarget(node.markup.target);
+            break;
+          case NamedTags.for:
+          case NamedTags.tablerow:
+            checkStringTarget(node.markup.variableName, node.markup);
+            break;
+          case NamedTags.background:
+            if (node.markup.type === NodeTypes.BackgroundMarkup) {
+              checkStringTarget(node.markup.jobId, node.markup);
+            }
+            break;
+        }
+      },
+
+      async LiquidBranch(node) {
+        if (node.name === NamedTags.catch && typeof node.markup !== 'string') {
+          checkLookupTarget(node.markup);
+        }
+      },
+    };
+  },
+};

package/src/checks/unused-assign/index.spec.ts

@@ -236,6 +236,19 @@ describe('Module: UnusedAssign', () => {
     expect(offenses).to.have.lengthOf(0);
   });
 
+  it('should not report assignments to reserved literal names (handled by ReservedVariableName)', async () => {
+    const sourceCode = `
+      {% liquid
+        assign empty = '{}' | parse_json
+        function invalid = 'modules/blog/commands/blog_instances/build', object: empty
+        echo invalid
+      %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).toEqual([]);
+  });
+
   it('should not report variables referenced in a string-markup fallback assign (parse failure)', async () => {
     // The stray `}` before `%}` causes the tolerant parser to fall back to
     // string markup. The AST contains no VariableLookup nodes for k/v, so

package/src/checks/unused-assign/index.ts

@@ -6,7 +6,7 @@ import {
   NodeTypes,
 } from '@platformos/liquid-html-parser';
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
-import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+import { isWithinRawTagThatDoesNotParseItsContents, RESERVED_VARIABLE_NAMES } from '../utils';
 
 export const UnusedAssign: LiquidCheckDefinition = {
   meta: {
@@ -95,6 +95,9 @@ export const UnusedAssign: LiquidCheckDefinition = {
         }
 
         for (const [variable, node] of assignedVariables.entries()) {
+          // Reserved literal names are reported by ReservedVariableName instead —
+          // "unused" would be misleading when the source visibly references the name.
+          if (RESERVED_VARIABLE_NAMES.has(variable)) continue;
           if (!usedVariables.has(variable) && !variable.startsWith('_')) {
             context.report({
               message: `The variable '${variable}' is assigned but not used`,