td-ai-tools 1.2.4 → 1.2.6

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

@@ -0,0 +1,301 @@
+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_NULLABLE_SETTING_TYPES,
+  UnguardedNullableSetting,
+} from './unguarded-nullable-setting';
+
+describe('UnguardedNullableSetting', () => {
+  it('reports raw outputs of all default nullable section and block setting types', async () => {
+    const settings = DEFAULT_NULLABLE_SETTING_TYPES.map((type) => ({
+      type,
+      id: `section_${type}`,
+    }));
+    const blockSettings = DEFAULT_NULLABLE_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(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(DEFAULT_NULLABLE_SETTING_TYPES.length * 2);
+    expect(offenses[0].message).toBe(
+      "The setting 'section_number' can be blank and is output without a presence guard or default",
+    );
+  });
+
+  it('covers every input type documented as potentially empty, blank, or nil', () => {
+    expect(DEFAULT_NULLABLE_SETTING_TYPES).toEqual([
+      'number',
+      'text',
+      'textarea',
+      'article',
+      'article_list',
+      'blog',
+      'collection',
+      'collection_list',
+      'image_picker',
+      'link_list',
+      'metaobject',
+      'metaobject_list',
+      'page',
+      'product',
+      'product_list',
+      'richtext',
+      'inline_richtext',
+      'html',
+      'liquid',
+      'url',
+      'video',
+      'video_url',
+    ]);
+  });
+
+  it('ignores settings with guaranteed or ambiguous empty values by default', async () => {
+    const source = liquidSection(
+      `
+        {{ section.settings.enabled }}
+        {{ section.settings.spacing }}
+        {{ section.settings.alignment }}
+        {{ section.settings.layout }}
+        {{ section.settings.color }}
+        {{ section.settings.background }}
+        {{ section.settings.color_scheme }}
+        {{ section.settings.palette }}
+        {{ section.settings.schemes }}
+        {{ section.settings.font }}
+        {{ section.settings.text_alignment }}
+      `,
+      [
+        { type: 'checkbox', id: 'enabled' },
+        { type: 'range', id: 'spacing' },
+        { type: 'radio', id: 'alignment' },
+        { type: 'select', id: 'layout' },
+        { type: 'color', id: 'color' },
+        { type: 'color_background', id: 'background' },
+        { type: 'color_scheme', id: 'color_scheme' },
+        { type: 'color_palette', id: 'palette' },
+        { type: 'color_scheme_group', id: 'schemes' },
+        { type: 'font_picker', id: 'font' },
+        { type: 'text_alignment', id: 'text_alignment' },
+      ],
+    );
+
+    expect(await runLiquidCheck(UnguardedNullableSetting, 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(UnguardedNullableSetting, 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(UnguardedNullableSetting, 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(UnguardedNullableSetting, 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(UnguardedNullableSetting, 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(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('only accepts outputs inside the branch that guards the setting', async () => {
+    const source = liquidSection(
+      `
+        {{ section.settings.heading }}
+        {% if section.settings.heading %}{{ section.settings.heading }}{% endif %}
+        {{ section.settings.heading }}
+      `,
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(2);
+  });
+
+  it('only applies a default filter to the output that uses it', async () => {
+    const source = liquidSection(
+      "{{ section.settings.heading }} / {{ section.settings.heading | default: 'Welcome' }}",
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('does not let an elsif guard apply to an output in a sibling branch', async () => {
+    const source = liquidSection(
+      `
+        {% if product %}
+          {{ section.settings.heading }}
+        {% elsif section.settings.heading %}
+          {{ section.settings.heading }}
+        {% endif %}
+      `,
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('does not treat a case else branch as guarded by the case expression', async () => {
+    const source = liquidSection(
+      `
+        {% case section.settings.heading %}
+          {% when 'Welcome' %}{{ section.settings.heading }}
+          {% else %}{{ section.settings.heading }}
+        {% endcase %}
+      `,
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    const offenses = await runLiquidCheck(UnguardedNullableSetting, source);
+
+    expect(offenses).toHaveLength(1);
+  });
+
+  it('accepts an output nested within the guarded branch', async () => {
+    const source = liquidSection(
+      `
+        {% if section.settings.heading %}
+          {% if product.available %}
+            <h2>{{ section.settings.heading }}</h2>
+          {% endif %}
+        {% endif %}
+      `,
+      [{ type: 'text', id: 'heading' }],
+    );
+
+    expect(await runLiquidCheck(UnguardedNullableSetting, 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(UnguardedNullableSetting, 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(UnguardedNullableSetting, source)).toEqual([]);
+  });
+
+  it('supports nullableSettingTypes configuration', async () => {
+    const source = liquidSection('{{ section.settings.enabled }}', [
+      { type: 'checkbox', id: 'enabled' },
+    ]);
+
+    const offenses = await check(
+      { 'sections/test.liquid': source },
+      [UnguardedNullableSetting],
+      {},
+      {
+        UnguardedNullableSetting: {
+          enabled: true,
+          nullableSettingTypes: ['checkbox'],
+        },
+      },
+    );
+
+    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(UnguardedNullableSetting, 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(UnguardedNullableSetting, source)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,129 @@
+import {
+  LiquidCheckDefinition,
+  SchemaProp,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidVariableOutput,
+  LiquidVariableLookup,
+} from '@shopify/liquid-html-parser';
+
+import {
+  getSettingDeclarations,
+  getSettingReference,
+  settingKey,
+} from '../utils/ast';
+import type { SettingDeclaration } from '../utils/ast';
+import { isOutputGuarded } from '../utils/null-guard';
+
+export const DEFAULT_NULLABLE_SETTING_TYPES = [
+  'number',
+  'text',
+  'textarea',
+  'article',
+  'article_list',
+  'blog',
+  'collection',
+  'collection_list',
+  'image_picker',
+  'link_list',
+  'metaobject',
+  'metaobject_list',
+  'page',
+  'product',
+  'product_list',
+  'richtext',
+  'inline_richtext',
+  'html',
+  'liquid',
+  'url',
+  'video',
+  'video_url',
+] as const;
+
+const schema = {
+  nullableSettingTypes: SchemaProp.array(
+    SchemaProp.string(),
+    [...DEFAULT_NULLABLE_SETTING_TYPES],
+  ),
+};
+
+export const UnguardedNullableSetting: LiquidCheckDefinition<typeof schema> = {
+  meta: {
+    code: 'UnguardedNullableSetting',
+    name: 'Require guards for nullable settings',
+    docs: {
+      description: 'Reports potentially blank settings output without a presence guard or default filter.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema,
+  },
+  create(context) {
+    const declarations: SettingDeclaration[] = [];
+    const outputs: Array<{
+      id: string;
+      key: string;
+      node: LiquidVariableOutput;
+      guarded: boolean;
+    }> = [];
+
+    return {
+      async LiquidRawTag(node) {
+        const schemaDeclarations = getSettingDeclarations(node);
+        if (schemaDeclarations) declarations.push(...schemaDeclarations);
+      },
+
+      async LiquidVariableOutput(node, ancestors) {
+        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 });
+        const guarded = isOutputGuarded(
+          node,
+          ancestors,
+          key,
+          getSettingReferenceKey,
+        );
+        outputs.push({ id: reference.id, key, node, guarded });
+      },
+
+      async onCodePathEnd() {
+        const nullableTypes = new Set(context.settings.nullableSettingTypes);
+        const nullableSettings = new Set(
+          declarations
+            .filter(({ type }) => nullableTypes.has(type))
+            .map(settingKey),
+        );
+
+        for (const output of outputs) {
+          if (!nullableSettings.has(output.key) || output.guarded) continue;
+
+          context.report({
+            message:
+              `The setting '${output.id}' can be blank and is output without a presence guard or default`,
+            startIndex: output.node.position.start,
+            endIndex: output.node.position.end,
+          });
+        }
+      },
+    };
+  },
+};
+
+function getSettingReferenceKey(node: LiquidVariableLookup): string | undefined {
+  const reference = getSettingReference(node);
+  if (!reference || reference.dynamic || !reference.id) return undefined;
+
+  return settingKey(reference);
+}

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

@@ -17,7 +17,7 @@ export const UnusedSectionSettings: LiquidCheckDefinition = {
     name: 'Prevent unused section settings',
     docs: {
       description: 'Reports section and block settings that are never referenced in their file.',
-      recommended: true,
+      recommended: false,
     },
     type: SourceCodeType.LiquidHtml,
     severity: Severity.WARNING,

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

@@ -4,17 +4,30 @@ 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', () => {
+  it('exports all warning-level Liquid checks for Theme Check to load', () => {
     expect(checks.map(({ meta }) => meta.code)).toEqual([
+      'DisallowedScriptOrStyleTag',
+      'HardcodedText',
       'UnusedSectionSettings',
-      'UnguardedTextSetting',
+      'UnguardedNullableSetting',
+      'UnguardedMetafield',
+      'UnguardedMetaobject',
     ]);
 
     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);
     }
+
+    expect(
+      Object.fromEntries(checks.map(({ meta }) => [meta.code, meta.docs.recommended])),
+    ).toEqual({
+      DisallowedScriptOrStyleTag: true,
+      HardcodedText: true,
+      UnusedSectionSettings: false,
+      UnguardedNullableSetting: true,
+      UnguardedMetafield: true,
+      UnguardedMetaobject: true,
+    });
   });
 });
-

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

@@ -1,11 +1,25 @@
+import { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
+import { HardcodedText } from './checks/hardcoded-text';
 import { UnusedSectionSettings } from './checks/unused-section-settings';
-import { UnguardedTextSetting } from './checks/unguarded-text-setting';
+import { UnguardedMetafield } from './checks/unguarded-metafield';
+import { UnguardedMetaobject } from './checks/unguarded-metaobject';
+import { UnguardedNullableSetting } from './checks/unguarded-nullable-setting';
 
+export { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
+export { HardcodedText } from './checks/hardcoded-text';
 export { UnusedSectionSettings } from './checks/unused-section-settings';
+export { UnguardedMetafield } from './checks/unguarded-metafield';
+export { UnguardedMetaobject } from './checks/unguarded-metaobject';
 export {
-  DEFAULT_TEXTUAL_SETTING_TYPES,
-  UnguardedTextSetting,
-} from './checks/unguarded-text-setting';
-
-export const checks = [UnusedSectionSettings, UnguardedTextSetting];
+  DEFAULT_NULLABLE_SETTING_TYPES,
+  UnguardedNullableSetting,
+} from './checks/unguarded-nullable-setting';
 
+export const checks = [
+  DisallowedScriptOrStyleTag,
+  HardcodedText,
+  UnusedSectionSettings,
+  UnguardedNullableSetting,
+  UnguardedMetafield,
+  UnguardedMetaobject,
+];

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

@@ -0,0 +1,79 @@
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidHtmlNode,
+  LiquidVariableLookup,
+  LiquidVariableOutput,
+} from '@shopify/liquid-html-parser';
+
+export type ReferenceKeyGetter = (
+  node: LiquidVariableLookup,
+) => string | undefined;
+
+/**
+ * Applies the output-level guards shared by nullable settings and objects.
+ * The caller defines reference identity so a condition on an object can guard
+ * output of one of that object's descendant properties.
+ */
+export function isOutputGuarded(
+  node: LiquidVariableOutput,
+  ancestors: LiquidHtmlNode[],
+  key: string,
+  getReferenceKey: ReferenceKeyGetter,
+): boolean {
+  if (typeof node.markup === 'string') return false;
+
+  return (
+    node.markup.filters.some(({ name }) => name === 'default') ||
+    isGuardedByConditional(key, ancestors, getReferenceKey)
+  );
+}
+
+function isGuardedByConditional(
+  key: string,
+  ancestors: LiquidHtmlNode[],
+  getReferenceKey: ReferenceKeyGetter,
+): boolean {
+  return ancestors.some((ancestor, index) => {
+    if (ancestor.type !== NodeTypes.LiquidBranch) return false;
+
+    const parent = ancestors[index - 1];
+    if (!parent || parent.type !== NodeTypes.LiquidTag) return false;
+
+    if (
+      ancestor.name === null &&
+      (parent.name === 'if' || parent.name === 'unless')
+    ) {
+      return containsReference(parent.markup, key, getReferenceKey);
+    }
+
+    if (ancestor.name === 'elsif') {
+      return containsReference(ancestor.markup, key, getReferenceKey);
+    }
+
+    if (ancestor.name === 'when' && parent.name === 'case') {
+      return containsReference(parent.markup, key, getReferenceKey);
+    }
+
+    return false;
+  });
+}
+
+function containsReference(
+  value: unknown,
+  key: string,
+  getReferenceKey: ReferenceKeyGetter,
+  visited = new Set<object>(),
+): boolean {
+  if (!value || typeof value !== 'object' || visited.has(value)) return false;
+  visited.add(value);
+
+  if ('type' in value && value.type === NodeTypes.VariableLookup) {
+    return getReferenceKey(value as LiquidVariableLookup) === key;
+  }
+
+  return Object.values(value).some((child) =>
+    containsReference(child, key, getReferenceKey, visited),
+  );
+}

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

@@ -0,0 +1,90 @@
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidVariableLookup,
+} from '@shopify/liquid-html-parser';
+
+import { isOutputGuarded } from './null-guard';
+
+export type NullableObjectReference = {
+  key: string;
+  name: string;
+};
+
+export type NullableObjectReferenceGetter = (
+  node: LiquidVariableLookup,
+) => NullableObjectReference | undefined;
+
+type NullableOutputCheckOptions = {
+  code: string;
+  name: string;
+  description: string;
+  objectName: string;
+  getReference: NullableObjectReferenceGetter;
+};
+
+/**
+ * Builds checks for nullable Liquid objects whose identity is fully encoded in
+ * a variable lookup. Schema-backed settings use the same guard analysis but
+ * retain their separate declaration-aware check.
+ */
+export function createNullableOutputCheck({
+  code,
+  name,
+  description,
+  objectName,
+  getReference,
+}: NullableOutputCheckOptions): LiquidCheckDefinition {
+  return {
+    meta: {
+      code,
+      name,
+      docs: {
+        description,
+        recommended: true,
+      },
+      type: SourceCodeType.LiquidHtml,
+      severity: Severity.WARNING,
+      schema: {},
+    },
+    create(context) {
+      return {
+        async LiquidVariableOutput(node, ancestors) {
+          if (typeof node.markup === 'string') return;
+
+          const expression = node.markup.expression;
+          if (expression.type !== NodeTypes.VariableLookup) return;
+
+          const reference = getReference(expression);
+          if (!reference) return;
+
+          const getReferenceKey = (lookup: LiquidVariableLookup) =>
+            getReference(lookup)?.key;
+          if (
+            isOutputGuarded(
+              node,
+              ancestors,
+              reference.key,
+              getReferenceKey,
+            )
+          ) {
+            return;
+          }
+
+          context.report({
+            message:
+              `The ${objectName} '${reference.name}' can be nil and is output without a presence guard or default`,
+            startIndex: node.position.start,
+            endIndex: node.position.end,
+          });
+        },
+      };
+    },
+  };
+}