td-ai-tools 1.2.0 → 1.2.2

package/skills/shopify-lint/theme-check-theory/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "theme-check-theory",
+  "version": "0.1.0",
+  "description": "Theory Digital's custom Shopify Theme Check rules",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "configs",
+    ".theme-check.example.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "shopify",
+    "theme-check",
+    "liquid",
+    "lint"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@shopify/theme-check-common": ">=3.21.0 <4"
+  },
+  "dependencies": {
+    "@shopify/liquid-html-parser": "2.9.2",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "@shopify/theme-check-common": "3.27.0",
+    "@types/node": "24.0.15",
+    "typescript": "5.8.3",
+    "vitest": "3.2.7"
+  }
+}

package/skills/shopify-lint/theme-check-theory/src/checks/unguarded-text-setting.test.ts

@@ -0,0 +1,198 @@
+import {
+  check,
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { liquidSection } from '../test-utils';
+import {
+  DEFAULT_TEXTUAL_SETTING_TYPES,
+  UnguardedTextSetting,
+} from './unguarded-text-setting';
+
+describe('UnguardedTextSetting', () => {
+  it('reports raw outputs of all default text-like section and block setting types', async () => {
+    const settings = DEFAULT_TEXTUAL_SETTING_TYPES.map((type) => ({
+      type,
+      id: `section_${type}`,
+    }));
+    const blockSettings = DEFAULT_TEXTUAL_SETTING_TYPES.map((type) => ({
+      type,
+      id: `block_${type}`,
+    }));
+    const outputs = [
+      ...settings.map(({ id }) => `{{ section.settings.${id} }}`),
+      ...blockSettings.map(({ id }) => `{{ block.settings.${id} }}`),
+    ].join('\n');
+    const source = liquidSection(outputs, settings, [
+      { type: 'card', name: 'Card', settings: blockSettings },
+    ]);
+
+    const offenses = await runLiquidCheck(UnguardedTextSetting, source);
+
+    expect(offenses).toHaveLength(DEFAULT_TEXTUAL_SETTING_TYPES.length * 2);
+    expect(offenses[0].message).toBe(
+      "The text-like setting 'section_text' is output without a presence guard or default",
+    );
+  });
+
+  it('ignores non-textual settings by default', async () => {
+    const source = liquidSection(
+      `
+        {{ section.settings.enabled }}
+        {{ section.settings.spacing }}
+        {{ section.settings.image }}
+      `,
+      [
+        { type: 'checkbox', id: 'enabled' },
+        { type: 'range', id: 'spacing' },
+        { type: 'image_picker', id: 'image' },
+      ],
+    );
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it.each([
+    [
+      'if',
+      '{% if section.settings.heading %}{{ section.settings.heading }}{% endif %}',
+    ],
+    [
+      'unless',
+      '{% unless section.settings.heading == blank %}{{ section.settings.heading }}{% endunless %}',
+    ],
+    [
+      'elsif',
+      '{% if product %}x{% elsif section.settings.heading %}{{ section.settings.heading }}{% endif %}',
+    ],
+    [
+      'case',
+      '{% case section.settings.heading %}{% when "Hello" %}{{ section.settings.heading }}{% endcase %}',
+    ],
+  ])('accepts a setting tested in an %s conditional', async (_, liquid) => {
+    const source = liquidSection(liquid, [{ type: 'text', id: 'heading' }]);
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it('accepts logical and comparison presence tests', async () => {
+    const source = liquidSection(
+      `
+        {% if section.settings.heading != blank and section.settings.subtitle %}
+          {{ section.settings.heading }} {{ section.settings.subtitle }}
+        {% endif %}
+      `,
+      [
+        { type: 'text', id: 'heading' },
+        { type: 'textarea', id: 'subtitle' },
+      ],
+    );
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it('does not mistake an unrelated enclosing condition for a setting presence guard', async () => {
+    const source = liquidSection(
+      '{% if product.available %}{{ section.settings.heading }}{% endif %}',
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedTextSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('accepts output with a default filter', async () => {
+    const source = liquidSection(
+      "{{ section.settings.heading | strip | default: 'Welcome' }}",
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it('does not treat use as another expression default as handling the setting', async () => {
+    const source = liquidSection(
+      "{{ product.title | default: section.settings.heading }} {{ section.settings.heading }}",
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedTextSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('applies handling coarsely to every output of that setting in the file', async () => {
+    const source = liquidSection(
+      `
+        {{ section.settings.heading }}
+        {% if section.settings.heading %}{{ section.settings.heading }}{% endif %}
+        {{ section.settings.heading }}
+      `,
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it('reports every raw output when the setting is never handled', async () => {
+    const source = liquidSection(
+      '{{ section.settings.heading }} / {{ section.settings.heading | escape }}',
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedTextSetting, source);
+
+    expect(offenses).toHaveLength(2);
+  });
+
+  it('only considers variable output tags, not assignments or echo tags', async () => {
+    const source = liquidSection(
+      '{% assign heading = section.settings.heading %}{% echo section.settings.heading %}',
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+
+  it('supports textualSettingTypes configuration', async () => {
+    const source = liquidSection('{{ section.settings.image }}', [
+      { type: 'image_picker', id: 'image' },
+    ]);
+
+    const offenses = await check(
+      { 'sections/test.liquid': source },
+      [UnguardedTextSetting],
+      {},
+      {
+        UnguardedTextSetting: {
+          enabled: true,
+          textualSettingTypes: ['image_picker'],
+        },
+      },
+    );
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('ignores dynamic output while still checking statically known outputs', async () => {
+    const source = liquidSection(
+      '{{ section.settings[key] }} {{ section.settings.heading }}',
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedTextSetting, source);
+
+    expect(offenses).toHaveLength(1);
+    expect(offenses[0].message).toContain("'heading'");
+  });
+
+  it.each([
+    ['a file without schema', '{{ section.settings.heading }}'],
+    ['an invalid schema', '{{ section.settings.heading }}{% schema %}{ nope {% endschema %}'],
+  ])('stays silent for %s', async (_, source) => {
+    expect(await runLiquidCheck(UnguardedTextSetting, source)).toEqual([]);
+  });
+});
+

package/skills/shopify-lint/theme-check-theory/src/checks/unguarded-text-setting.ts

@@ -0,0 +1,143 @@
+import {
+  LiquidCheckDefinition,
+  SchemaProp,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidHtmlNode,
+  LiquidVariableOutput,
+  LiquidVariableLookup,
+} from '@shopify/liquid-html-parser';
+
+import {
+  getSettingDeclarations,
+  getSettingReference,
+  settingKey,
+} from '../utils/ast';
+import type { SettingDeclaration } from '../utils/ast';
+
+export const DEFAULT_TEXTUAL_SETTING_TYPES = [
+  'text',
+  'textarea',
+  'richtext',
+  'inline_richtext',
+  'html',
+  'liquid',
+  'url',
+] as const;
+
+const schema = {
+  textualSettingTypes: SchemaProp.array(
+    SchemaProp.string(),
+    [...DEFAULT_TEXTUAL_SETTING_TYPES],
+  ),
+};
+
+export const UnguardedTextSetting: LiquidCheckDefinition<typeof schema> = {
+  meta: {
+    code: 'UnguardedTextSetting',
+    name: 'Require guards for text-like settings',
+    docs: {
+      description: 'Reports text-like settings output without a presence guard or default filter.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema,
+  },
+  create(context) {
+    const declarations: SettingDeclaration[] = [];
+    const handledSettings = new Set<string>();
+    const outputs: Array<{
+      id: string;
+      key: string;
+      node: LiquidVariableOutput;
+    }> = [];
+
+    return {
+      async LiquidRawTag(node) {
+        const schemaDeclarations = getSettingDeclarations(node);
+        if (schemaDeclarations) declarations.push(...schemaDeclarations);
+      },
+
+      async LiquidVariableOutput(node) {
+        if (typeof node.markup === 'string') return;
+
+        const expression = node.markup.expression;
+        if (expression.type !== NodeTypes.VariableLookup) return;
+
+        const reference = getSettingReference(expression);
+        if (!reference || reference.dynamic || !reference.id) return;
+
+        const key = settingKey({ id: reference.id, scope: reference.scope });
+        outputs.push({ id: reference.id, key, node });
+
+        if (node.markup.filters.some(({ name }) => name === 'default')) {
+          handledSettings.add(key);
+        }
+      },
+
+      async VariableLookup(node, ancestors) {
+        const reference = getSettingReference(node);
+        if (!reference || reference.dynamic || !reference.id) return;
+        if (!isConditionalTest(node, ancestors)) return;
+
+        handledSettings.add(settingKey({ id: reference.id, scope: reference.scope }));
+      },
+
+      async onCodePathEnd() {
+        const textualTypes = new Set(context.settings.textualSettingTypes);
+        const textualSettings = new Set(
+          declarations
+            .filter(({ type }) => textualTypes.has(type))
+            .map(settingKey),
+        );
+
+        for (const output of outputs) {
+          if (!textualSettings.has(output.key) || handledSettings.has(output.key)) continue;
+
+          context.report({
+            message:
+              `The text-like setting '${output.id}' is output without a presence guard or default`,
+            startIndex: output.node.position.start,
+            endIndex: output.node.position.end,
+          });
+        }
+      },
+    };
+  },
+};
+
+function isConditionalTest(node: LiquidVariableLookup, ancestors: LiquidHtmlNode[]): boolean {
+  return ancestors.some((ancestor) => {
+    if (ancestor.type === NodeTypes.LiquidTag) {
+      if (!['if', 'unless', 'case'].includes(ancestor.name)) return false;
+      return containsNode(ancestor.markup, node);
+    }
+
+    if (ancestor.type === NodeTypes.LiquidBranch && ancestor.name === 'elsif') {
+      return containsNode(ancestor.markup, node);
+    }
+
+    return false;
+  });
+}
+
+function containsNode(markup: unknown, node: LiquidVariableLookup): boolean {
+  if (!markup || typeof markup !== 'object' || !('position' in markup)) return false;
+
+  const position = (markup as { position?: { start: number; end: number } }).position;
+  return Boolean(
+    position &&
+      position.start <= node.position.start &&
+      position.end >= node.position.end,
+  );
+}
+
+// v1 intentionally records a guard for the entire file. A branch-precise
+// version can use the visitor `ancestors` argument to bind handling to the live
+// LiquidBranch containing each output.

package/skills/shopify-lint/theme-check-theory/src/checks/unused-section-settings.test.ts

@@ -0,0 +1,137 @@
+import { runLiquidCheck } from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { liquidSection } from '../test-utils';
+import { UnusedSectionSettings } from './unused-section-settings';
+
+describe('UnusedSectionSettings', () => {
+  it('reports unused section and block settings', async () => {
+    const source = liquidSection(
+      `
+        <h2>{{ section.settings.heading }}</h2>
+        {% for block in section.blocks %}
+          <h3>{{ block.settings.block_heading }}</h3>
+        {% endfor %}
+      `,
+      [
+        { type: 'text', id: 'heading', label: 'Heading' },
+        { type: 'textarea', id: 'subtitle', label: 'Subtitle' },
+      ],
+      [
+        {
+          type: 'card',
+          name: 'Card',
+          settings: [
+            { type: 'text', id: 'block_heading', label: 'Heading' },
+            { type: 'url', id: 'block_link', label: 'Link' },
+          ],
+        },
+      ],
+    );
+
+    const offenses = await runLiquidCheck(
+      UnusedSectionSettings,
+      source,
+      'sections/test.liquid',
+    );
+
+    expect(offenses.map(({ message }) => message)).toEqual([
+      "The setting 'subtitle' is declared but never referenced",
+      "The setting 'block_link' is declared but never referenced",
+    ]);
+    expect(offenses.every(({ check }) => check === 'UnusedSectionSettings')).toBe(true);
+  });
+
+  it('counts static references in outputs, tags, conditions, and bracket notation', async () => {
+    const source = liquidSection(
+      `
+        {% assign heading = section.settings.heading %}
+        {% if section.settings['subtitle'] %}
+          {{ heading }} — {{ section.settings["subtitle"] }}
+        {% endif %}
+        {% assign href = block.settings.link %}
+      `,
+      [
+        { type: 'text', id: 'heading' },
+        { type: 'textarea', id: 'subtitle' },
+      ],
+      [
+        {
+          type: 'card',
+          name: 'Card',
+          settings: [{ type: 'url', id: 'link' }],
+        },
+      ],
+    );
+
+    const offenses = await runLiquidCheck(UnusedSectionSettings, source);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it.each([
+    ['section', '{{ section.settings[key] }}'],
+    ['block', '{{ block.settings[key] }}'],
+  ])('stays silent for the whole file when %s settings use dynamic access', async (_, liquid) => {
+    const source = liquidSection(
+      liquid,
+      [{ type: 'text', id: 'unused_section_setting' }],
+      [
+        {
+          type: 'card',
+          name: 'Card',
+          settings: [{ type: 'text', id: 'unused_block_setting' }],
+        },
+      ],
+    );
+
+    const offenses = await runLiquidCheck(UnusedSectionSettings, source);
+
+    expect(offenses).toEqual([]);
+  });
+
+  it('stays silent when the settings object itself escapes static analysis', async () => {
+    const source = liquidSection(
+      "{% render 'card', settings: section.settings %}",
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    expect(await runLiquidCheck(UnusedSectionSettings, source)).toEqual([]);
+  });
+
+  it('reports each repeated declaration when a shared block setting id is unused', async () => {
+    const source = liquidSection('', [], [
+      {
+        type: 'card',
+        name: 'Card',
+        settings: [{ type: 'text', id: 'heading' }],
+      },
+      {
+        type: 'slide',
+        name: 'Slide',
+        settings: [{ type: 'text', id: 'heading' }],
+      },
+    ]);
+
+    const offenses = await runLiquidCheck(UnusedSectionSettings, source);
+
+    expect(offenses).toHaveLength(2);
+  });
+
+  it('ignores non-setting schema entries without ids', async () => {
+    const source = liquidSection('', [
+      { type: 'header', content: 'Content' } as never,
+      { type: 'paragraph', content: 'Help text' } as never,
+    ]);
+
+    expect(await runLiquidCheck(UnusedSectionSettings, source)).toEqual([]);
+  });
+
+  it.each([
+    ['a file without schema', '{{ section.settings.heading }}'],
+    ['an invalid schema', '{% schema %}{ nope {% endschema %}'],
+  ])('stays silent for %s', async (_, source) => {
+    expect(await runLiquidCheck(UnusedSectionSettings, source)).toEqual([]);
+  });
+});
+

package/skills/shopify-lint/theme-check-theory/src/checks/unused-section-settings.ts

@@ -0,0 +1,64 @@
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+import {
+  getSettingDeclarations,
+  getSettingReference,
+  settingKey,
+} from '../utils/ast';
+import type { SettingDeclaration } from '../utils/ast';
+
+export const UnusedSectionSettings: LiquidCheckDefinition = {
+  meta: {
+    code: 'UnusedSectionSettings',
+    name: 'Prevent unused section settings',
+    docs: {
+      description: 'Reports section and block settings that are never referenced in their file.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    const declarations: SettingDeclaration[] = [];
+    const references = new Set<string>();
+    let hasDynamicAccess = false;
+
+    return {
+      async LiquidRawTag(node) {
+        const schemaDeclarations = getSettingDeclarations(node);
+        if (schemaDeclarations) declarations.push(...schemaDeclarations);
+      },
+
+      async VariableLookup(node) {
+        const reference = getSettingReference(node);
+        if (!reference) return;
+
+        if (reference.dynamic) {
+          hasDynamicAccess = true;
+          return;
+        }
+
+        references.add(settingKey(reference));
+      },
+
+      async onCodePathEnd() {
+        if (hasDynamicAccess) return;
+
+        for (const declaration of declarations) {
+          if (references.has(settingKey(declaration))) continue;
+
+          context.report({
+            message: `The setting '${declaration.id}' is declared but never referenced`,
+            startIndex: declaration.startIndex,
+            endIndex: declaration.endIndex,
+          });
+        }
+      },
+    };
+  },
+};

package/skills/shopify-lint/theme-check-theory/src/index.test.ts

@@ -0,0 +1,20 @@
+import { Severity, SourceCodeType } from '@shopify/theme-check-common';
+import { describe, expect, it } from 'vitest';
+
+import { checks } from './index';
+
+describe('theme-check-theory module', () => {
+  it('exports both warning-level Liquid checks for Theme Check to load', () => {
+    expect(checks.map(({ meta }) => meta.code)).toEqual([
+      'UnusedSectionSettings',
+      'UnguardedTextSetting',
+    ]);
+
+    for (const check of checks) {
+      expect(check.meta.type).toBe(SourceCodeType.LiquidHtml);
+      expect(check.meta.severity).toBe(Severity.WARNING);
+      expect(check.meta.docs.recommended).toBe(true);
+    }
+  });
+});
+

package/skills/shopify-lint/theme-check-theory/src/index.ts

@@ -0,0 +1,11 @@
+import { UnusedSectionSettings } from './checks/unused-section-settings';
+import { UnguardedTextSetting } from './checks/unguarded-text-setting';
+
+export { UnusedSectionSettings } from './checks/unused-section-settings';
+export {
+  DEFAULT_TEXTUAL_SETTING_TYPES,
+  UnguardedTextSetting,
+} from './checks/unguarded-text-setting';
+
+export const checks = [UnusedSectionSettings, UnguardedTextSetting];
+

package/skills/shopify-lint/theme-check-theory/src/test-utils.ts

@@ -0,0 +1,31 @@
+export type Setting = {
+  type: string;
+  id?: string;
+  label?: string;
+};
+
+export type Block = {
+  type: string;
+  name: string;
+  settings?: Setting[];
+};
+
+export function liquidSection(
+  liquid: string,
+  settings: Setting[] = [],
+  blocks: Block[] = [],
+): string {
+  const schema = JSON.stringify(
+    {
+      name: 'Test section',
+      settings,
+      blocks,
+      presets: [{ name: 'Test section' }],
+    },
+    null,
+    2,
+  );
+
+  return `${liquid}\n{% schema %}\n${schema}\n{% endschema %}`;
+}
+