@platformos/platformos-check-common 0.0.18 → 0.0.20

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

@@ -201,4 +201,65 @@ describe('Module: UnusedAssign', () => {
     expect(offenses).to.have.lengthOf(1);
     expect(offenses[0].message).to.equal("The variable 'arr' is assigned but not used");
   });
+
+  it('should not report variables used inside a filter array-literal argument', async () => {
+    const sourceCode = `
+      {% assign k = "key" %}
+      {% assign v = "value" %}
+      {% assign name = arr | default: [ "hi", k, v] %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report variables used inside a filter hash-literal argument', async () => {
+    const sourceCode = `
+      {% assign k = 1 %}
+      {% assign name = arr | default: { a: k } %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report variables used inside a named-argument value', async () => {
+    const sourceCode = `
+      {% assign k = 0 %}
+      {% assign name = arr | slice: start: k %}
+      {{ name }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    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
+    // without a textual fallback scan the check would wrongly flag them.
+    const sourceCode = `
+      {% assign k = "key" %}
+      {% assign v = "value" %}
+      {% assign name = arr | default: [ "hi", k, v] } %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
 });

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: {
@@ -31,6 +31,12 @@ export const UnusedAssign: LiquidCheckDefinition = {
     // effects on the original, so they count as "using" the variable.
     const referenceAssignedVariables: Set<string> = new Set();
     const usedVariables: Set<string> = new Set();
+    // Concatenated markup of LiquidTags whose parsing fell back to a raw string
+    // (e.g. a typo like `{% assign name = x | default: [...] } %}`). The AST has
+    // no VariableLookup nodes to traverse inside them, so onCodePathEnd scans
+    // this text for assigned-variable names — avoids compounding the user's
+    // syntax error with false "unused" warnings.
+    let fallbackText = '';
 
     function checkVariableUsage(node: any) {
       if (node.type === NodeTypes.VariableLookup) {
@@ -66,6 +72,8 @@ export const UnusedAssign: LiquidCheckDefinition = {
           }
         } else if (isLiquidTagCapture(node) && node.markup.name) {
           assignedVariables.set(node.markup.name, node);
+        } else if (typeof node.markup === 'string' && node.markup) {
+          fallbackText += '\n' + node.markup;
         }
       },
 
@@ -79,7 +87,17 @@ export const UnusedAssign: LiquidCheckDefinition = {
       },
 
       async onCodePathEnd() {
+        if (fallbackText) {
+          for (const name of assignedVariables.keys()) {
+            if (usedVariables.has(name)) continue;
+            if (new RegExp(`\\b${name}\\b`).test(fallbackText)) usedVariables.add(name);
+          }
+        }
+
         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`,

package/src/checks/utils.ts

@@ -9,6 +9,7 @@ import {
   AttrUnquoted,
   LiquidHtmlNode,
   LiquidBranch,
+  LiquidLiteralValues,
   LiquidTagFor,
   LiquidTagTablerow,
   LiquidTag,
@@ -16,6 +17,16 @@ import {
 } from '@platformos/liquid-html-parser';
 import { LiquidHtmlNodeOfType as NodeOfType } from '../types';
 
+/**
+ * Names that Liquid resolves as built-in literals before looking up variables
+ * (Liquid::Expression::LITERALS in the backend, `LiquidLiteralValues` in the
+ * parser grammar). Assigning to them succeeds silently, but reading them
+ * always returns the literal, never the assigned value.
+ */
+export const RESERVED_VARIABLE_NAMES: ReadonlySet<string> = new Set(
+  Object.keys(LiquidLiteralValues),
+);
+
 type ElementType<T> = T extends (infer E)[] ? E : never;
 
 export type ValuedHtmlAttribute = AttrSingleQuoted | AttrDoubleQuoted | AttrUnquoted;

package/src/find-root.ts

@@ -3,13 +3,28 @@ import * as path from './path';
 
 type FileExists = (uri: string) => Promise<boolean>;
 
+function isInsideApp(dir: UriString): boolean {
+  let current = dir;
+  while (true) {
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    if (path.basename(parent) === 'app') return true;
+    current = parent;
+  }
+}
+
 async function isRoot(dir: UriString, fileExists: FileExists) {
   return or(
     fileExists(path.join(dir, '.pos')),
     fileExists(path.join(dir, '.platformos-check.yml')),
     fileExists(path.join(dir, 'app')),
-    // modules/ is a root indicator only when not inside app/ (app/modules/ is a valid subdirectory)
-    and(fileExists(path.join(dir, 'modules')), Promise.resolve(path.basename(dir) !== 'app')),
+    // modules/ is a root indicator only when not inside an app/ subtree.
+    // app/modules/ is a valid subdirectory, and app/views/partials/modules/ is a
+    // legitimate partial organization that should not be mistaken for a project root.
+    and(
+      fileExists(path.join(dir, 'modules')),
+      Promise.resolve(path.basename(dir) !== 'app' && !isInsideApp(dir)),
+    ),
   );
 }
 

package/src/index.ts

@@ -60,11 +60,13 @@ export {
   isFormConfiguration,
   isKnownGraphQLFile,
   isKnownLiquidFile,
+  isKnownYAMLFile,
   isLayout,
   isMigration,
   isPage,
   isPartial,
   isSms,
+  isSupportedSourceFile,
   PlatformOSFileType,
 } from '@platformos/platformos-common';
 export * from './frontmatter';

package/src/types.ts

@@ -315,6 +315,22 @@ 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;
@@ -322,6 +338,9 @@ export type Reference = {
   type:
     | 'direct' // explicit dependency, e.g. {% render 'partial' %}
     | 'indirect'; // indirect dependency
+
+  /** Which Liquid construct produced this edge. Optional for backwards compatibility. */
+  kind?: ReferenceKind;
 };
 
 export type Range = [start: number, end: number]; // represents a range in the source code