td-ai-tools 1.2.4 → 1.2.6

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

@@ -0,0 +1,171 @@
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  AttributeNode,
+  LiquidHtmlNode,
+  LiquidRawTag,
+  LiquidVariable,
+  TextNode,
+} from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+const EXEMPT_RAW_TAGS = new Set([
+  'comment',
+  'javascript',
+  'schema',
+  'stylesheet',
+]);
+
+const TEXT_ATTRIBUTES = new Set([
+  'alt',
+  'aria-description',
+  'aria-label',
+  'aria-placeholder',
+  'placeholder',
+  'title',
+]);
+
+const TRANSLATION_FILTERS = new Set(['t', 'translate']);
+
+type ValuedAttribute = Extract<AttributeNode, { value: unknown }>;
+
+function isValuedAttribute(node: LiquidHtmlNode): node is ValuedAttribute {
+  return (
+    node.type === NodeTypes.AttrDoubleQuoted ||
+    node.type === NodeTypes.AttrSingleQuoted ||
+    node.type === NodeTypes.AttrUnquoted
+  );
+}
+
+function staticAttributeName(node: ValuedAttribute): string | undefined {
+  if (
+    node.name.length !== 1 ||
+    node.name[0].type !== NodeTypes.TextNode
+  ) {
+    return undefined;
+  }
+
+  return node.name[0].value.toLowerCase();
+}
+
+function rawTagAncestor(
+  ancestors: LiquidHtmlNode[],
+): LiquidRawTag | undefined {
+  for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+    const ancestor = ancestors[index];
+    if (ancestor.type === NodeTypes.LiquidRawTag) return ancestor;
+  }
+
+  return undefined;
+}
+
+function hasMeaningfulText(value: string): boolean {
+  return /[\p{L}\p{N}]/u.test(value);
+}
+
+function isHtmlElementName(node: TextNode, parent: LiquidHtmlNode): boolean {
+  if (
+    parent.type !== NodeTypes.HtmlElement &&
+    parent.type !== NodeTypes.HtmlSelfClosingElement
+  ) {
+    return false;
+  }
+
+  return parent.name.some((part) => part === node);
+}
+
+function isTranslation(variable: LiquidVariable): boolean {
+  return variable.filters.some(({ name }) => TRANSLATION_FILTERS.has(name));
+}
+
+export const HardcodedText: LiquidCheckDefinition = {
+  meta: {
+    code: 'HardcodedText',
+    name: 'Prevent hard-coded storefront text',
+    docs: {
+      description:
+        'Reports rendered text that should come from a setting, translation, metafield, or metaobject.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    function report(startIndex: number, endIndex: number) {
+      context.report({
+        message:
+          'Replace hard-coded text with a section setting, translation key, metafield, or metaobject',
+        startIndex,
+        endIndex,
+      });
+    }
+
+    function reportLiteralOutput(variable: LiquidVariable) {
+      if (
+        variable.expression.type !== NodeTypes.String ||
+        !hasMeaningfulText(variable.expression.value) ||
+        isTranslation(variable)
+      ) {
+        return;
+      }
+
+      report(
+        variable.expression.position.start,
+        variable.expression.position.end,
+      );
+    }
+
+    return {
+      async TextNode(node, ancestors) {
+        if (!hasMeaningfulText(node.value)) return;
+
+        const rawTag = rawTagAncestor(ancestors);
+        if (rawTag) {
+          if (EXEMPT_RAW_TAGS.has(rawTag.name.toLowerCase())) return;
+          report(node.position.start, node.position.end);
+          return;
+        }
+
+        const parent = ancestors.at(-1);
+        if (!parent || isHtmlElementName(node, parent)) return;
+
+        if (isValuedAttribute(parent)) {
+          if (!parent.value.some((part) => part === node)) return;
+
+          const attributeName = staticAttributeName(parent);
+          if (attributeName && TEXT_ATTRIBUTES.has(attributeName)) {
+            report(node.position.start, node.position.end);
+          }
+          return;
+        }
+
+        if (parent.type === NodeTypes.RawMarkup) return;
+
+        if (
+          parent.type === NodeTypes.Document ||
+          parent.type === NodeTypes.HtmlElement ||
+          parent.type === NodeTypes.LiquidBranch ||
+          parent.type === NodeTypes.LiquidTag
+        ) {
+          report(node.position.start, node.position.end);
+        }
+      },
+
+      async LiquidVariableOutput(node) {
+        if (typeof node.markup === 'string') return;
+        reportLiteralOutput(node.markup);
+      },
+
+      async LiquidTag(node) {
+        if (node.name !== 'echo' || typeof node.markup === 'string') return;
+        reportLiteralOutput(node.markup);
+      },
+    };
+  },
+};

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

@@ -0,0 +1,76 @@
+import {
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { UnguardedMetafield } from './unguarded-metafield';
+
+describe('UnguardedMetafield', () => {
+  it('reports metafield objects and their descendant values', async () => {
+    const source = `
+      {{ product.metafields.details.subtitle }}
+      {{ product.metafields.details.subtitle.value }}
+      {{ collection.metafields['details']['hero'].value }}
+    `;
+
+    const offenses = await runLiquidCheck(UnguardedMetafield, source);
+
+    expect(offenses).toHaveLength(3);
+    expect(offenses[0].message).toBe(
+      "The metafield 'product.metafields.details.subtitle' can be nil and is output without a presence guard or default",
+    );
+  });
+
+  it.each([
+    [
+      'if',
+      '{% if product.metafields.details.subtitle %}{{ product.metafields.details.subtitle.value }}{% endif %}',
+    ],
+    [
+      'unless',
+      '{% unless product.metafields.details.subtitle == blank %}{{ product.metafields.details.subtitle.value }}{% endunless %}',
+    ],
+    [
+      'descendant value',
+      '{% if product.metafields.details.subtitle.value %}{{ product.metafields.details.subtitle.value }}{% endif %}',
+    ],
+  ])('accepts a metafield tested in an %s guard', async (_, source) => {
+    expect(await runLiquidCheck(UnguardedMetafield, source)).toEqual([]);
+  });
+
+  it('accepts a default filter on the output', async () => {
+    const source =
+      "{{ product.metafields.details.subtitle.value | default: 'Not provided' }}";
+
+    expect(await runLiquidCheck(UnguardedMetafield, source)).toEqual([]);
+  });
+
+  it('does not mistake a different metafield guard for the output guard', async () => {
+    const source = `
+      {% if product.metafields.details.title %}
+        {{ product.metafields.details.subtitle.value }}
+      {% endif %}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetafield, source)).toHaveLength(1);
+  });
+
+  it('ignores namespace collections and dynamic accesses', async () => {
+    const source = `
+      {{ product.metafields }}
+      {{ product.metafields.details }}
+      {{ product.metafields[namespace][key].value }}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetafield, source)).toEqual([]);
+  });
+
+  it('only considers variable output tags', async () => {
+    const source = `
+      {% assign subtitle = product.metafields.details.subtitle.value %}
+      {% echo product.metafields.details.subtitle.value %}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetafield, source)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,49 @@
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidVariableLookup,
+} from '@shopify/liquid-html-parser';
+
+import {
+  createNullableOutputCheck,
+} from '../utils/nullable-output-check';
+import type {
+  NullableObjectReference,
+} from '../utils/nullable-output-check';
+
+export const UnguardedMetafield = createNullableOutputCheck({
+  code: 'UnguardedMetafield',
+  name: 'Require guards for metafields',
+  description:
+    'Reports metafield output without a presence guard or default filter.',
+  objectName: 'metafield',
+  getReference: getMetafieldReference,
+});
+
+function getMetafieldReference(
+  node: LiquidVariableLookup,
+): NullableObjectReference | undefined {
+  if (!node.name) return undefined;
+
+  const [metafields, namespace, key] = node.lookups;
+  if (
+    metafields?.type !== NodeTypes.String ||
+    metafields.value !== 'metafields' ||
+    namespace?.type !== NodeTypes.String ||
+    key?.type !== NodeTypes.String
+  ) {
+    return undefined;
+  }
+
+  const name = `${node.name}.metafields.${namespace.value}.${key.value}`;
+  return {
+    key: JSON.stringify([
+      'metafield',
+      node.name,
+      namespace.value,
+      key.value,
+    ]),
+    name,
+  };
+}

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

@@ -0,0 +1,77 @@
+import {
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { UnguardedMetaobject } from './unguarded-metaobject';
+
+describe('UnguardedMetaobject', () => {
+  it('reports metaobject entries and their descendant fields', async () => {
+    const source = `
+      {{ metaobjects.testimonials.homepage }}
+      {{ metaobjects.testimonials.homepage.title }}
+      {{ metaobjects['highlights']['washable'].image.value }}
+    `;
+
+    const offenses = await runLiquidCheck(UnguardedMetaobject, source);
+
+    expect(offenses).toHaveLength(3);
+    expect(offenses[0].message).toBe(
+      "The metaobject 'metaobjects.testimonials.homepage' can be nil and is output without a presence guard or default",
+    );
+  });
+
+  it.each([
+    [
+      'if',
+      '{% if metaobjects.testimonials.homepage %}{{ metaobjects.testimonials.homepage.title.value }}{% endif %}',
+    ],
+    [
+      'unless',
+      '{% unless metaobjects.testimonials.homepage == nil %}{{ metaobjects.testimonials.homepage.title.value }}{% endunless %}',
+    ],
+    [
+      'descendant field',
+      '{% if metaobjects.testimonials.homepage.title.value %}{{ metaobjects.testimonials.homepage.title.value }}{% endif %}',
+    ],
+  ])('accepts a metaobject tested in an %s guard', async (_, source) => {
+    expect(await runLiquidCheck(UnguardedMetaobject, source)).toEqual([]);
+  });
+
+  it('accepts a default filter on the output', async () => {
+    const source =
+      "{{ metaobjects.testimonials.homepage.title.value | default: 'Untitled' }}";
+
+    expect(await runLiquidCheck(UnguardedMetaobject, source)).toEqual([]);
+  });
+
+  it('does not mistake a different metaobject guard for the output guard', async () => {
+    const source = `
+      {% if metaobjects.testimonials.featured %}
+        {{ metaobjects.testimonials.homepage.title.value }}
+      {% endif %}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetaobject, source)).toHaveLength(1);
+  });
+
+  it('ignores type collections, dynamic accesses, and the current template metaobject', async () => {
+    const source = `
+      {{ metaobjects }}
+      {{ metaobjects.testimonials }}
+      {{ metaobjects[type][handle].title.value }}
+      {{ metaobject.title.value }}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetaobject, source)).toEqual([]);
+  });
+
+  it('only considers variable output tags', async () => {
+    const source = `
+      {% assign testimonial = metaobjects.testimonials.homepage %}
+      {% echo metaobjects.testimonials.homepage.title.value %}
+    `;
+
+    expect(await runLiquidCheck(UnguardedMetaobject, source)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,42 @@
+import {
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import type {
+  LiquidVariableLookup,
+} from '@shopify/liquid-html-parser';
+
+import {
+  createNullableOutputCheck,
+} from '../utils/nullable-output-check';
+import type {
+  NullableObjectReference,
+} from '../utils/nullable-output-check';
+
+export const UnguardedMetaobject = createNullableOutputCheck({
+  code: 'UnguardedMetaobject',
+  name: 'Require guards for metaobjects',
+  description:
+    'Reports metaobject output without a presence guard or default filter.',
+  objectName: 'metaobject',
+  getReference: getMetaobjectReference,
+});
+
+function getMetaobjectReference(
+  node: LiquidVariableLookup,
+): NullableObjectReference | undefined {
+  if (node.name !== 'metaobjects') return undefined;
+
+  const [type, handle] = node.lookups;
+  if (
+    type?.type !== NodeTypes.String ||
+    handle?.type !== NodeTypes.String
+  ) {
+    return undefined;
+  }
+
+  const name = `metaobjects.${type.value}.${handle.value}`;
+  return {
+    key: JSON.stringify(['metaobject', type.value, handle.value]),
+    name,
+  };
+}