td-ai-tools 1.3.4 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/shopify-lint/SKILL.md

@@ -40,7 +40,7 @@ python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
 
 The script identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, then runs three linters over that set and merges their results into one report:
 
-- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags, and except text beginning with `--`, which is a CSS custom property name rather than copy. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
+- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags, except text beginning with `--`, which is a CSS custom property name rather than copy, and except string arguments passed to `{% render %}` and `{% include %}`, which are as often class names or size tokens as copy. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
 - **JavaScript** — ESLint's recommended rules plus the bundled `eslint-plugin-theory`, over modified `.js` and `.mjs` files *and* the JavaScript inside `{% javascript %}` blocks of modified `.liquid` files.
 - **CSS** — `stylelint-config-standard` through the bundled `stylelint-config-theory`, over modified `.css` files *and* the CSS inside `{% stylesheet %}` blocks of modified `.liquid` files.
 

package/skills/shopify-lint/theme-check-theory/.theme-check.example.yml

@@ -12,6 +12,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/README.md

@@ -13,6 +13,7 @@ integrated into Shopify CLI. It is not compatible with the archived Ruby
 | --- | --- | --- |
 | `DisallowedScriptOrStyleTag` | warning | An inline executable `<script>` or any `<style>` tag in a Liquid file. |
 | `HardcodedText` | warning | Rendered hard-coded storefront copy that should use a dynamic content source. |
+| `RequiredLiquidDoc` | warning | A `td-` snippet or theme block without a complete Liquid doc contract. |
 | `UnusedSectionSettings` | warning | A setting declared in `{% schema %}` that is never referenced in the file. |
 | `UnguardedNullableSetting` | warning | A potentially blank setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
 | `UnguardedMetafield` | warning | A metafield output with no presence guard or `\| default`. |
@@ -33,12 +34,18 @@ Rendered storefront copy should come from a section setting, translation key,
 metafield, or metaobject. The check reports text nodes, direct quoted output
 with `{{ }}` or `{% echo %}`, quoted `default` filter fallbacks, hard-coded
 `alt`, `title`, `placeholder`, and ARIA text attributes, and labels in the
-`value` attribute of button-like inputs. Text inside inline SVG elements and
-string literals passed as named `render` or `include` arguments are also
+`value` attribute of button-like inputs. Text inside inline SVG elements is also
 checked. It ignores technical attributes such as classes and IDs, Liquid logic
 strings, comments, punctuation-only fragments, and text made entirely of HTML
 character references.
 
+String literals passed as named `{% render %}` and `{% include %}` arguments are
+ignored. A snippet argument is as often a class name, icon key, size token, or
+heading level as it is storefront copy, and nothing at the call site separates
+the two, so checking them produced mostly false positives. Copy that a snippet
+renders is still reported inside the snippet itself, where it appears as a text
+node or a quoted output.
+
 Text beginning with `--` is ignored as a CSS custom property name: Liquid
 routinely assembles a custom property declaration before handing it to a
 `style` attribute or a `{% style %}` block, neither of which this check reads.
@@ -52,6 +59,36 @@ accepted. Short alphabetic tokens and copyright years remain reportable because
 the check cannot reliably distinguish user-facing copy from currency codes,
 units, or other intentional literals.
 
+### RequiredLiquidDoc
+
+Files whose name contains `td-` under `snippets/` or `blocks/` must contain a
+`{% doc %}` tag with a prose description and a non-empty `@example`. Every
+`@param` that is present must use LiquidDoc's `{type} name - description`
+shape; optional names such as `[heading]` are supported. LiquidDoc types are
+descriptive rather than a closed type system, so Shopify Liquid object names,
+primitive names, and project-specific type expressions are all accepted.
+
+```liquid
+{% doc %}
+  Renders a product card.
+
+  @param {product} product - The product to display.
+  @param {string} [heading] - An optional card heading.
+
+  @example
+  {% render 'td-product-card', product: product, heading: 'Featured' %}
+{% enddoc %}
+```
+
+The check does not infer missing parameters from variable lookups inside the
+file. Liquid exposes many global objects, and a snippet parameter is introduced
+at its call site, so a single-file lookup cannot reliably distinguish the two.
+To require complete parameter coverage, add a separate project-level analysis
+that indexes named arguments at static `{% render %}` call sites and compares
+their union with each target file's documented parameters. Dynamic snippet
+names and values passed with `with`/`for` require an explicit project policy or
+an allowlist.
+
 ### UnusedSectionSettings
 
 This single-file check collects every `id` under `settings` and
@@ -185,6 +222,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/configs/recommended.yml

@@ -6,6 +6,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
   enabled: false
   severity: warning

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

@@ -98,22 +98,18 @@ describe('HardcodedText', () => {
     ]);
   });
 
-  it('reports string literals passed as render and include arguments', async () => {
+  it('ignores string literals passed as render and include arguments', async () => {
+    // A snippet argument is as often a class name, icon key, size token, or
+    // heading level as it is storefront copy, and the call site carries nothing
+    // that separates the two. The snippet body is still checked on its own.
     const source = `
       {% render 'button', label: 'Add to cart' %}
       {% include 'icon', accessible_name: "Search icon" %}
-      {% render 'button', label: section.settings.button_label %}
+      {% render 'button', variant: 'primary', size: 'large' %}
       {% render 'icon' %}
     `;
 
-    const offenses = await runLiquidCheck(HardcodedText, source);
-
-    expect(offenses).toHaveLength(2);
-    expect(
-      offenses.map(({ start, end }) =>
-        source.slice(start.index, end.index),
-      ),
-    ).toEqual(["'Add to cart'", '"Search icon"']);
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
   it('reports hard-coded default filter fallbacks', async () => {

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

@@ -308,17 +308,6 @@ export const HardcodedText: LiquidCheckDefinition = {
 
         reportInlineSvgText(node);
       },
-
-      async RenderMarkup(node) {
-        for (const argument of node.args) {
-          if (
-            argument.type === NodeTypes.NamedArgument &&
-            argument.value.type === NodeTypes.String
-          ) {
-            reportString(argument.value);
-          }
-        }
-      },
     };
   },
 };

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { liquidDocProblems, requiresLiquidDoc } from './required-liquid-doc';
+
+describe('RequiredLiquidDoc', () => {
+  it('targets td- Liquid snippets and blocks only', () => {
+    expect(requiresLiquidDoc('file:///theme/snippets/td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/blocks/product-td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/sections/td-card.liquid')).toBe(false);
+    expect(requiresLiquidDoc('/theme/snippets/card.liquid')).toBe(false);
+  });
+
+  it('accepts a description, typed parameters, and an example', () => {
+    const body = `
+      Renders a card for a product.
+      @param {product} product - The product displayed by the card.
+      @param {string} [heading] - An optional heading.
+      @example
+      {% render 'td-card', product: product, heading: 'Featured' %}
+    `;
+    expect(liquidDocProblems(body)).toEqual([]);
+  });
+
+  it('requires both a description and non-empty example', () => {
+    expect(liquidDocProblems('@example\n').map(({ message }) => message)).toEqual([
+      'Liquid doc must include a description before its annotations',
+      'Liquid doc must include an @example with example markup',
+    ]);
+  });
+
+  it('requires types and descriptions on documented parameters', () => {
+    const body = `
+      Renders a card.
+      @param product - The product.
+      @param {string} heading
+      @example
+      {% render 'td-card', product: product %}
+    `;
+    expect(liquidDocProblems(body).map(({ message }) => message)).toEqual([
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+    ]);
+  });
+});

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.ts

@@ -0,0 +1,111 @@
+import type { LiquidRawTag } from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+type DocumentationProblem = { message: string; offset: number; length: number };
+
+const PARAM_LINE = /^[ \t]*@param[ \t]+(.*)$/gm;
+const COMPLETE_PARAM = /^\{([^}\n]+)\}\s+(\[[^\]\n]+\]|[^\s-]+)\s+-\s+(.+)$/;
+
+/** Returns true for td-named snippets and theme blocks. */
+export function requiresLiquidDoc(uri: string): boolean {
+  const path = decodeURIComponent(uri).replace(/\\/g, '/').split(/[?#]/, 1)[0];
+  const match = path.match(/(?:^|\/)(snippets|blocks)\/([^/]+)\.liquid$/i);
+  return Boolean(match?.[2].toLowerCase().includes('td-'));
+}
+
+/** Validates the documented contract without mistaking Shopify globals for parameters. */
+export function liquidDocProblems(body: string): DocumentationProblem[] {
+  const problems: DocumentationProblem[] = [];
+  const firstAnnotation = body.search(/^[ \t]*@\w+/m);
+  const description = body.slice(0, firstAnnotation < 0 ? body.length : firstAnnotation).trim();
+
+  if (!description) {
+    problems.push({
+      message: 'Liquid doc must include a description before its annotations',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  const example = body.match(
+    /^[ \t]*@example[^\n]*\n([\s\S]*?)(?=^[ \t]*@\w+|(?![\s\S]))/m,
+  );
+  if (!example || !example[1].trim()) {
+    problems.push({
+      message: 'Liquid doc must include an @example with example markup',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  for (const match of body.matchAll(PARAM_LINE)) {
+    const complete = match[1].trim().match(COMPLETE_PARAM);
+    const offset = match.index ?? 0;
+    if (!complete?.[1].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a type in braces',
+        offset,
+        length: match[0].length,
+      });
+    }
+    if (!complete?.[3].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a description after " - "',
+        offset,
+        length: match[0].length,
+      });
+    }
+  }
+
+  return problems;
+}
+
+export const RequiredLiquidDoc: LiquidCheckDefinition = {
+  meta: {
+    code: 'RequiredLiquidDoc',
+    name: 'Require documentation for td- snippets and theme blocks',
+    docs: {
+      description:
+        'Requires td- snippets and blocks to have a Liquid doc description and example, and validates documented parameters.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    const uri = (context as unknown as { file?: { uri?: string } }).file?.uri ?? '';
+    if (!requiresLiquidDoc(uri)) return {};
+
+    const docs: LiquidRawTag[] = [];
+    return {
+      async LiquidRawTag(node) {
+        if (node.name === 'doc') docs.push(node);
+      },
+      async onCodePathEnd() {
+        if (docs.length === 0) {
+          context.report({
+            message: 'td- snippets and blocks must include a {% doc %} tag',
+            startIndex: 0,
+            endIndex: 1,
+          });
+          return;
+        }
+
+        const doc = docs[0];
+        for (const problem of liquidDocProblems(doc.body.value)) {
+          const startIndex = doc.body.position.start + problem.offset;
+          context.report({
+            message: problem.message,
+            startIndex,
+            endIndex: startIndex + problem.length,
+          });
+        }
+      },
+    };
+  },
+};

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

@@ -8,6 +8,7 @@ describe('theme-check-theory module', () => {
     expect(checks.map(({ meta }) => meta.code)).toEqual([
       'DisallowedScriptOrStyleTag',
       'HardcodedText',
+      'RequiredLiquidDoc',
       'UnusedSectionSettings',
       'UnguardedNullableSetting',
       'UnguardedMetafield',
@@ -24,6 +25,7 @@ describe('theme-check-theory module', () => {
     ).toEqual({
       DisallowedScriptOrStyleTag: true,
       HardcodedText: true,
+      RequiredLiquidDoc: true,
       UnusedSectionSettings: false,
       UnguardedNullableSetting: true,
       UnguardedMetafield: true,

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

@@ -1,5 +1,6 @@
 import { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 import { HardcodedText } from './checks/hardcoded-text';
+import { RequiredLiquidDoc } from './checks/required-liquid-doc';
 import { UnusedSectionSettings } from './checks/unused-section-settings';
 import { UnguardedMetafield } from './checks/unguarded-metafield';
 import { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -7,6 +8,7 @@ import { UnguardedNullableSetting } from './checks/unguarded-nullable-setting';
 
 export { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 export { HardcodedText } from './checks/hardcoded-text';
+export { RequiredLiquidDoc } from './checks/required-liquid-doc';
 export { UnusedSectionSettings } from './checks/unused-section-settings';
 export { UnguardedMetafield } from './checks/unguarded-metafield';
 export { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -18,6 +20,7 @@ export {
 export const checks = [
   DisallowedScriptOrStyleTag,
   HardcodedText,
+  RequiredLiquidDoc,
   UnusedSectionSettings,
   UnguardedNullableSetting,
   UnguardedMetafield,

package/skills/shopify-lint/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.10","results":[[":eslint-plugin-theory/src/rules/guarded-custom-element-define.test.ts",{"duration":0,"failed":true}],[":stylelint-config-theory/src/liquid/mask.test.ts",{"duration":21.486761,"failed":false}],[":theme-check-theory/src/checks/hardcoded-text.test.ts",{"duration":79.642067,"failed":false}],[":stylelint-config-theory/src/integration.test.ts",{"duration":322.234405,"failed":false}],[":theme-check-theory/src/checks/unguarded-nullable-setting.test.ts",{"duration":126.54217099999994,"failed":false}],[":eslint-plugin-theory/src/rules/disconnected-callback-cleanup.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/integration.test.ts",{"duration":207.055841,"failed":false}],[":eslint-plugin-theory/src/liquid/mask.test.ts",{"duration":31.769655,"failed":false}],[":stylelint-config-theory/src/config.test.ts",{"duration":13.856021999999996,"failed":false}],[":theme-check-theory/src/checks/unused-section-settings.test.ts",{"duration":63.80623400000002,"failed":false}],[":theme-check-theory/src/checks/unguarded-metaobject.test.ts",{"duration":34.325909000000024,"failed":false}],[":eslint-plugin-theory/src/index.test.ts",{"duration":6.773288999999977,"failed":false}],[":theme-check-theory/src/checks/disallowed-script-or-style-tag.test.ts",{"duration":32.848730000000046,"failed":false}],[":theme-check-theory/src/checks/unguarded-metafield.test.ts",{"duration":37.897699999999986,"failed":false}],[":eslint-plugin-theory/src/rules/no-class-selectors.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/rules/no-unapproved-imports.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/rules/require-jsdoc.test.ts",{"duration":87.66796799999997,"failed":false}],[":eslint-plugin-theory/src/rules/centralize-selectors.test.ts",{"duration":0,"failed":true}],[":stylelint-config-theory/src/build.test.ts",{"duration":903.9329710000001,"failed":false}],[":theme-check-theory/src/index.test.ts",{"duration":2.380390000000034,"failed":false}],[":eslint-plugin-theory/src/processors/liquid.test.ts",{"duration":6.720345000000009,"failed":false}],[":eslint-plugin-theory/src/build.test.ts",{"duration":965.007413,"failed":false}]]}