@platformos/platformos-check-common 0.0.12 → 0.0.13

package/src/checks/undefined-object/index.spec.ts

@@ -541,4 +541,34 @@ describe('Module: UndefinedObject', () => {
     expect(offenses).toHaveLength(1);
     expect(offenses[0].message).toBe("Unknown object 'groups_data' used.");
   });
+
+  it('should not report an offense for catch variable inside catch block', async () => {
+    const sourceCode = `
+      {% try %}
+        {{ "something" }}
+      {% catch error %}
+        {{ error }}
+      {% endtry %}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(0);
+  });
+
+  it('should report an offense for catch variable used outside catch block', async () => {
+    const sourceCode = `
+      {% try %}
+        {{ "something" }}
+      {% catch error %}
+        {{ error }}
+      {% endtry %}
+      {{ error }}
+    `;
+
+    const offenses = await runLiquidCheck(UndefinedObject, sourceCode);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toBe("Unknown object 'error' used.");
+  });
 });

package/src/checks/undefined-object/index.ts

@@ -9,7 +9,6 @@ import {
   LiquidTagIncrement,
   LiquidTagTablerow,
   LiquidVariableLookup,
-  LiquidTagFunction,
   NamedTags,
   NodeTypes,
   Position,
@@ -23,6 +22,7 @@ import {
 import { LiquidCheckDefinition, Severity, SourceCodeType, PlatformOSDocset } from '../../types';
 import { isError, last } from '../../utils';
 import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+import yaml from 'js-yaml';
 
 type Scope = { start?: number; end?: number };
 
@@ -158,6 +158,24 @@ export const UndefinedObject: LiquidCheckDefinition = {
         }
       },
 
+      async LiquidBranch(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+
+        // {% try %} ... {% catch error %} registers the error variable
+        if (
+          node.name === NamedTags.catch &&
+          node.markup &&
+          typeof node.markup !== 'string' &&
+          'name' in node.markup &&
+          node.markup.name
+        ) {
+          indexVariableScope(node.markup.name, {
+            start: node.blockStartPosition.end,
+            end: node.blockEndPosition?.start,
+          });
+        }
+      },
+
       async VariableLookup(node, ancestors) {
         if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
 
@@ -166,6 +184,8 @@ export const UndefinedObject: LiquidCheckDefinition = {
         if (isLiquidTag(parent) && isLiquidTagParseJson(parent)) return;
         // Skip the result variable of function tags (it's a definition, not a usage)
         if (isFunctionMarkup(parent) && parent.name === node) return;
+        // Skip the error variable definition in catch branches
+        if (isLiquidBranchCatch(parent) && parent.markup === node) return;
 
         variables.push(node);
       },
@@ -313,3 +333,9 @@ function isLiquidTagBackground(
 function isFunctionMarkup(node?: LiquidHtmlNode): node is FunctionMarkup {
   return node?.type === NodeTypes.FunctionMarkup;
 }
+
+function isLiquidBranchCatch(
+  node?: LiquidHtmlNode,
+): node is LiquidHtmlNode & { type: typeof NodeTypes.LiquidBranch; name: 'catch'; markup: any } {
+  return node?.type === NodeTypes.LiquidBranch && (node as any).name === NamedTags.catch;
+}

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

@@ -56,7 +56,7 @@ describe('Module: UnusedAssign', () => {
       {{ usedVar }}
     `;
 
-    expect(suggestions).to.include(expectedFixedCode);
+    expect(suggestions).to.deep.equal([expectedFixedCode]);
   });
 
   it('should not report unused assigns for things used in a capture tag', async () => {

package/src/checks/unused-doc-param/index.spec.ts

@@ -51,14 +51,16 @@ describe('Module: UnusedDocParam', () => {
     const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
     const suggestions = applySuggestions(sourceCode, offenses[0]);
 
-    expect(suggestions).to.include(`
+    expect(suggestions).to.deep.equal([
+      `
       {% doc %}
         @param param1 - Example param
         
       {% enddoc %}
 
       {{ param1 }}
-    `);
+    `,
+    ]);
   });
 
   LoopNamedTags.forEach((tag) => {

package/src/checks/valid-doc-param-types/index.spec.ts

@@ -69,7 +69,7 @@ describe('Module: ValidDocParamTypes', () => {
       expect(offenses).to.have.length(1);
       const suggestions = applySuggestions(source, offenses[0]);
 
-      expect(suggestions).to.include(`{% doc %} @param param1 - Example param {% enddoc %}`);
+      expect(suggestions).to.deep.equal([`{% doc %} @param param1 - Example param {% enddoc %}`]);
     }
   });
 });

package/src/checks/valid-render-partial-argument-types/index.spec.ts

@@ -34,7 +34,7 @@ describe('Module: ValidRenderPartialParamTypes', () => {
           { value: "'hello'", actualType: BasicParamTypes.String },
           { value: '123', actualType: BasicParamTypes.Number },
           { value: 'true', actualType: BasicParamTypes.Boolean },
-          { value: 'empty', actualType: BasicParamTypes.Boolean },
+          { value: 'empty', actualType: BasicParamTypes.String },
         ],
       },
     ];
@@ -142,6 +142,29 @@ describe('Module: ValidRenderPartialParamTypes', () => {
       expect(offenses).toHaveLength(0);
     });
 
+    it('should not report null/nil as type mismatch for any type', async () => {
+      for (const type of ['string', 'number', 'object', 'boolean']) {
+        for (const literal of ['nil', 'null']) {
+          const sourceCode = `{% render 'card', param: ${literal} %}`;
+          const offenses = await runLiquidCheck(
+            ValidRenderPartialArgumentTypes,
+            sourceCode,
+            undefined,
+            {},
+            {
+              'app/views/partials/card.liquid': `
+                {% doc %}
+                  @param {${type}} param - Description
+                {% enddoc %}
+                <div>{{ param }}</div>
+              `,
+            },
+          );
+          expect(offenses, `${literal} should be valid for ${type}`).toHaveLength(0);
+        }
+      }
+    });
+
     it('should not enforce unsupported types', async () => {
       const sourceCode = `{% render 'card', title: 123 %}`;
       const offenses = await runLiquidCheck(

package/src/checks/valid-render-partial-argument-types/index.ts

@@ -1,7 +1,7 @@
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
 import { NodeTypes, RenderMarkup } from '@platformos/liquid-html-parser';
 import { LiquidDocParameter } from '../../liquid-doc/liquidDoc';
-import { inferArgumentType, isTypeCompatible } from '../../liquid-doc/utils';
+import { inferArgumentType, isNullLiteral, isTypeCompatible } from '../../liquid-doc/utils';
 import {
   findTypeMismatchParams,
   generateTypeMismatchSuggestions,
@@ -41,7 +41,8 @@ export const ValidRenderPartialArgumentTypes: LiquidCheckDefinition = {
       if (
         node.alias &&
         node.variable?.name &&
-        node.variable.name.type !== NodeTypes.VariableLookup
+        node.variable.name.type !== NodeTypes.VariableLookup &&
+        !isNullLiteral(node.variable.name)
       ) {
         const paramIsDefinedWithType = liquidDocParameters
           .get(node.alias.value)

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

@@ -40,7 +40,7 @@ describe('Module: VariableName', () => {
 
     const expectedFixedCode = `{% assign variable_name = "value" %}`;
 
-    expect(suggestions).to.include(expectedFixedCode);
+    expect(suggestions).to.deep.equal([expectedFixedCode]);
   });
 
   it('should not report an error for variables starting with underscore', async () => {

package/src/context-utils.ts

@@ -3,6 +3,7 @@ import {
   AbstractFileSystem,
   FileTuple,
   FileType,
+  RouteTable,
   TranslationProvider,
   UriString,
 } from '@platformos/platformos-common';
@@ -131,6 +132,31 @@ function getDefaultTranslationsFromBuffer(app: App): Translations | undefined {
   }
 }
 
+export function makeGetRouteTable(
+  fs: AbstractFileSystem,
+  rootUri: string,
+  existingTable?: RouteTable,
+): () => Promise<RouteTable> {
+  const table = existingTable ?? new RouteTable(fs);
+  let buildPromise: Promise<RouteTable> | null = null;
+  return () => {
+    if (!buildPromise) {
+      if (table.isBuilt()) {
+        buildPromise = Promise.resolve(table);
+      } else {
+        buildPromise = table
+          .build(URI.parse(rootUri))
+          .then(() => table)
+          .catch((err) => {
+            buildPromise = null;
+            throw err;
+          });
+      }
+    }
+    return buildPromise;
+  };
+}
+
 function cached<T>(fn: () => Promise<T>): () => Promise<T>;
 function cached<T>(fn: (...args: any[]) => Promise<T>): (...args: any[]) => Promise<T> {
   let cachedPromise: Promise<T>;
@@ -145,7 +171,13 @@ export async function recursiveReadDirectory(
   uri: string,
   filter: (fileTuple: FileTuple) => boolean,
 ): Promise<UriString[]> {
-  const allFiles = await fs.readDirectory(uri);
+  let allFiles: FileTuple[];
+  try {
+    allFiles = await fs.readDirectory(uri);
+  } catch (err: any) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
   const files = allFiles.filter((ft) => !isIgnored(ft) && (isDirectory(ft) || filter(ft)));
 
   const results = await Promise.all(

package/src/index.ts

@@ -5,6 +5,7 @@ import {
   makeFileSize,
   makeGetDefaultLocale,
   makeGetDefaultTranslations,
+  makeGetRouteTable,
   makeGetTranslationsForBase,
 } from './context-utils';
 import { createDisabledChecksModule } from './disabled-checks';
@@ -80,6 +81,7 @@ export * from './utils/object';
 export * from './visitor';
 export * from './liquid-doc/liquidDoc';
 export * from './liquid-doc/utils';
+export * from './url-helpers';
 
 const defaultErrorHandler = (_error: Error): void => {
   // Silently ignores errors by default.
@@ -101,6 +103,7 @@ export async function check(
     getDefaultLocale: makeGetDefaultLocale(fs, rootUri),
     getDefaultTranslations: makeGetDefaultTranslations(fs, app, rootUri),
     getTranslationsForBase: makeGetTranslationsForBase(fs, app),
+    getRouteTable: makeGetRouteTable(fs, rootUri, injectedDependencies.routeTable),
   };
 
   const { DisabledChecksVisitor, isDisabled } = createDisabledChecksModule();

package/src/liquid-doc/arguments.ts

@@ -13,6 +13,7 @@ import {
   BasicParamTypes,
   getDefaultValueForType,
   inferArgumentType,
+  isNullLiteral,
   isTypeCompatible,
 } from './utils';
 import { isLiquidString } from '../checks/utils';
@@ -133,6 +134,11 @@ export function findTypeMismatchParams(
       continue;
     }
 
+    // null/nil is compatible with any type — skip type checking
+    if (isNullLiteral(arg.value)) {
+      continue;
+    }
+
     const liquidDocParamDef = liquidDocParameters.get(arg.name);
     if (liquidDocParamDef && liquidDocParamDef.type) {
       const paramType = liquidDocParamDef.type.toLowerCase();

package/src/liquid-doc/utils.ts

@@ -18,6 +18,11 @@ export enum BasicParamTypes {
   Object = 'object',
 }
 
+/** Inferred type for null/nil literals — not a valid @param type, only used in type mismatch messages. */
+export const InferredNull = 'null' as const;
+
+export type InferredParamType = BasicParamTypes | typeof InferredNull;
+
 export enum SupportedDocTagTypes {
   Param = 'param',
   Example = 'example',
@@ -44,7 +49,7 @@ export function getDefaultValueForType(type: string | null) {
 /**
  * Casts the value of a LiquidNamedArgument to a string representing the type of the value.
  */
-export function inferArgumentType(arg: LiquidExpression | LiquidVariable): BasicParamTypes {
+export function inferArgumentType(arg: LiquidExpression | LiquidVariable): InferredParamType {
   if (arg.type === NodeTypes.LiquidVariable) {
     // A variable with filters — delegate to the base expression if there are no filters,
     // otherwise we can't statically determine the filtered output type.
@@ -59,6 +64,8 @@ export function inferArgumentType(arg: LiquidExpression | LiquidVariable): Basic
     case NodeTypes.Number:
       return BasicParamTypes.Number;
     case NodeTypes.LiquidLiteral:
+      if (arg.value === null) return InferredNull;
+      if (arg.value === '') return BasicParamTypes.String;
       return BasicParamTypes.Boolean;
     case NodeTypes.Range:
     case NodeTypes.VariableLookup:
@@ -71,12 +78,29 @@ export function inferArgumentType(arg: LiquidExpression | LiquidVariable): Basic
   }
 }
 
+/**
+ * Checks if a LiquidExpression is a null/nil literal.
+ * null/nil is compatible with any type — it represents "no value".
+ */
+export function isNullLiteral(arg: LiquidExpression | LiquidVariable): boolean {
+  if (arg.type === NodeTypes.LiquidVariable) {
+    if (arg.filters.length > 0) return false;
+    const expr = arg.expression;
+    if (expr.type === NodeTypes.BooleanExpression) return false;
+    return isNullLiteral(expr);
+  }
+  if (arg.type === NodeTypes.LiquidLiteral) {
+    return arg.value === null;
+  }
+  return false;
+}
+
 /**
  * Checks if the provided argument type is compatible with the expected type.
  * Makes certain types more permissive:
  * - Boolean accepts any value, since everything is truthy / falsy in Liquid
  */
-export function isTypeCompatible(expectedType: string, actualType: BasicParamTypes): boolean {
+export function isTypeCompatible(expectedType: string, actualType: InferredParamType): boolean {
   const normalizedExpectedType = expectedType.toLowerCase();
 
   if (normalizedExpectedType === BasicParamTypes.Boolean) {

package/src/types.ts

@@ -2,7 +2,7 @@ import { LiquidHtmlNode, NodeTypes as LiquidHtmlNodeTypes } from '@platformos/li
 
 import { Schema, Settings } from './types/schema-prop-factory';
 
-import { AbstractFileSystem, UriString } from '@platformos/platformos-common';
+import { AbstractFileSystem, RouteTable, UriString } from '@platformos/platformos-common';
 import { JSONCorrector, StringCorrector } from './fixes';
 
 import {
@@ -355,6 +355,12 @@ export interface Dependencies {
    * Returns an empty array if no files reference this file
    */
   getReferences?: (uri: string) => Promise<Reference[]>;
+
+  /**
+   * Optional pre-built RouteTable. When provided (e.g. by the LSP),
+   * the check pipeline reuses it instead of building a new one per run.
+   */
+  routeTable?: RouteTable;
 }
 
 export type ValidateJSON = (
@@ -377,6 +383,8 @@ export interface AugmentedDependencies extends Dependencies {
    * Covers both `{base}/{locale}.yml` and `{base}/{locale}/*.yml`.
    */
   getTranslationsForBase(translationBaseUri: string, locale: string): Promise<Translations>;
+  /** Lazily builds and returns a shared RouteTable for the current check run. */
+  getRouteTable(): Promise<RouteTable>;
 }
 
 type StaticContextProperties<T extends SourceCodeType> = T extends SourceCodeType

package/src/url-helpers.spec.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from 'vitest';
+import {
+  toLiquidHtmlAST,
+  NodeTypes,
+  HtmlElement,
+  LiquidTag,
+  LiquidTagAssign,
+  AssignMarkup,
+  LiquidHtmlNode,
+} from '@platformos/liquid-html-parser';
+import {
+  resolveAssignToUrlPattern,
+  extractUrlPattern,
+  isValuedAttrNode,
+  getAttrName,
+  ValuedAttrNode,
+} from './url-helpers';
+
+/** Parse a Liquid template and extract the first {% assign %} markup. */
+function parseAssign(source: string): AssignMarkup {
+  const ast = toLiquidHtmlAST(source);
+  const assignTag = ast.children.find(
+    (n: LiquidHtmlNode) => n.type === NodeTypes.LiquidTag && (n as LiquidTag).name === 'assign',
+  ) as LiquidTagAssign | undefined;
+  if (!assignTag) throw new Error('No assign tag found in: ' + source);
+  return assignTag.markup as AssignMarkup;
+}
+
+/** Parse HTML with an <a> tag and return the href attribute node. */
+function parseHrefAttr(source: string): ValuedAttrNode {
+  const ast = toLiquidHtmlAST(source);
+  const aTag = ast.children.find(
+    (n: LiquidHtmlNode) =>
+      n.type === NodeTypes.HtmlElement && (n as HtmlElement).name[0].type === NodeTypes.TextNode,
+  ) as HtmlElement | undefined;
+  if (!aTag) throw new Error('No HTML element found in: ' + source);
+  const href = (aTag.attributes as LiquidHtmlNode[]).find(
+    (a) => isValuedAttrNode(a) && getAttrName(a) === 'href',
+  );
+  if (!href || !isValuedAttrNode(href)) throw new Error('No href attribute found in: ' + source);
+  return href;
+}
+
+describe('resolveAssignToUrlPattern', () => {
+  describe('string literal base', () => {
+    it('resolves a simple string literal', () => {
+      const markup = parseAssign('{% assign url = "/about" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/about');
+    });
+
+    it('resolves a string with trailing slash', () => {
+      const markup = parseAssign('{% assign url = "/groups/" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/');
+    });
+
+    it('resolves a root path', () => {
+      const markup = parseAssign('{% assign url = "/" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/');
+    });
+  });
+
+  describe('append filter', () => {
+    it('appends a string literal', () => {
+      const markup = parseAssign('{% assign url = "/groups" | append: "/edit" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/edit');
+    });
+
+    it('appends a variable as :_liquid_ placeholder', () => {
+      const markup = parseAssign('{% assign url = "/groups/" | append: group.id %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/:_liquid_');
+    });
+
+    it('chains multiple append filters', () => {
+      const markup = parseAssign(
+        '{% assign url = "/groups/" | append: group.id | append: "/edit" %}',
+      );
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/:_liquid_/edit');
+    });
+
+    it('chains append with string and variable args', () => {
+      const markup = parseAssign(
+        '{% assign url = "/users/" | append: user.id | append: "/posts/" | append: post.id %}',
+      );
+      expect(resolveAssignToUrlPattern(markup)).toBe('/users/:_liquid_/posts/:_liquid_');
+    });
+  });
+
+  describe('prepend filter', () => {
+    it('prepends a string literal', () => {
+      const markup = parseAssign('{% assign url = "/edit" | prepend: "/groups" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/edit');
+    });
+
+    it('prepends a variable as :_liquid_ placeholder', () => {
+      const markup = parseAssign('{% assign url = "/edit" | prepend: group.id %}');
+      // Result is ":_liquid_/edit" — doesn't start with /, returns null
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('chains prepend filters', () => {
+      const markup = parseAssign(
+        '{% assign url = "/edit" | prepend: user.id | prepend: "/users/" %}',
+      );
+      expect(resolveAssignToUrlPattern(markup)).toBe('/users/:_liquid_/edit');
+    });
+  });
+
+  describe('mixed append and prepend', () => {
+    it('handles append then prepend', () => {
+      const markup = parseAssign('{% assign url = "/" | append: "edit" | prepend: "/groups" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/groups/edit');
+    });
+  });
+
+  describe('variable lookup base', () => {
+    it('resolves a variable base to :_liquid_', () => {
+      const markup = parseAssign('{% assign url = base_path %}');
+      // Result is ":_liquid_" — doesn't start with /, returns null
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('resolves a variable base with prepend to produce a valid URL', () => {
+      const markup = parseAssign('{% assign url = slug | prepend: "/" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/:_liquid_');
+    });
+
+    it('resolves a variable base with append', () => {
+      const markup = parseAssign('{% assign url = base | append: "/edit" %}');
+      // Result is ":_liquid_/edit" — doesn't start with /, returns null
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+  });
+
+  describe('returns null for unsupported patterns', () => {
+    it('returns null for << operator (array push)', () => {
+      const markup = parseAssign('{% assign arr << "/item" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('returns null for non-append/prepend filters', () => {
+      const markup = parseAssign('{% assign url = "/ABOUT" | downcase %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('returns null for unknown filter in chain', () => {
+      const markup = parseAssign('{% assign url = "/groups" | append: "/edit" | strip %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('returns null when value does not start with /', () => {
+      const markup = parseAssign('{% assign url = "about" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('returns null for number literal base', () => {
+      const markup = parseAssign('{% assign num = 42 %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+
+    it('returns null when :_liquid_ is mixed with text in a segment', () => {
+      const markup = parseAssign('{% assign url = "/groups/group-" | append: group.id %}');
+      // Result would be "/groups/group-:_liquid_" — mixed segment
+      expect(resolveAssignToUrlPattern(markup)).toBe(null);
+    });
+  });
+
+  describe('query string and fragment stripping', () => {
+    it('strips query string from resolved URL', () => {
+      const markup = parseAssign('{% assign url = "/search?q=test" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/search');
+    });
+
+    it('strips fragment from resolved URL', () => {
+      const markup = parseAssign('{% assign url = "/page#section" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/page');
+    });
+
+    it('strips both query string and fragment', () => {
+      const markup = parseAssign('{% assign url = "/page?q=1#top" %}');
+      expect(resolveAssignToUrlPattern(markup)).toBe('/page');
+    });
+  });
+});
+
+describe('extractUrlPattern with variableMap', () => {
+  it('resolves a single {{ var }} from variableMap', () => {
+    const variableMap = new Map([['url', '/about']]);
+    const attr = parseHrefAttr('<a href="{{ url }}">link</a>');
+    expect(extractUrlPattern(attr, variableMap)).toBe('/about');
+  });
+
+  it('resolves a tracked variable with :_liquid_ segments', () => {
+    const variableMap = new Map([['edit_url', '/users/:_liquid_/edit']]);
+    const attr = parseHrefAttr('<a href="{{ edit_url }}">edit</a>');
+    expect(extractUrlPattern(attr, variableMap)).toBe('/users/:_liquid_/edit');
+  });
+
+  it('falls back to :_liquid_ for untracked variables', () => {
+    const variableMap = new Map<string, string>();
+    const attr = parseHrefAttr('<a href="{{ unknown_var }}">link</a>');
+    // Single dynamic variable with no static text → fully dynamic → null
+    expect(extractUrlPattern(attr, variableMap)).toBe(null);
+  });
+
+  it('does not resolve variables with filters', () => {
+    const variableMap = new Map([['url', '/about']]);
+    const attr = parseHrefAttr('<a href="{{ url | escape }}">link</a>');
+    // Variable has a filter → not a simple variable → falls through to normal logic → fully dynamic
+    expect(extractUrlPattern(attr, variableMap)).toBe(null);
+  });
+
+  it('does not resolve variables with lookups (e.g. url.path)', () => {
+    const variableMap = new Map([['url', '/about']]);
+    const attr = parseHrefAttr('<a href="{{ url.path }}">link</a>');
+    // Variable has lookups → not a simple variable → falls through → fully dynamic
+    expect(extractUrlPattern(attr, variableMap)).toBe(null);
+  });
+
+  it('does not resolve when attr has multiple nodes (mixed static + variable)', () => {
+    const variableMap = new Map([['slug', 'about']]);
+    const attr = parseHrefAttr('<a href="/{{ slug }}">link</a>');
+    // attr.value.length > 1, so variableMap lookup is skipped; normal extraction applies
+    expect(extractUrlPattern(attr, variableMap)).toBe('/:_liquid_');
+  });
+
+  it('works without variableMap (backward compatible)', () => {
+    const attr = parseHrefAttr('<a href="/about">link</a>');
+    expect(extractUrlPattern(attr)).toBe('/about');
+  });
+
+  it('works with empty variableMap', () => {
+    const attr = parseHrefAttr('<a href="/about">link</a>');
+    expect(extractUrlPattern(attr, new Map())).toBe('/about');
+  });
+
+  it('resolves a tracked simple variable from variableMap', () => {
+    const variableMap = new Map([['url', '/about']]);
+    const attr = parseHrefAttr('<a href="{{ url }}">link</a>');
+    expect(extractUrlPattern(attr, variableMap)).toBe('/about');
+  });
+});